docs(codex): 補齊 read_account_email docstring 與指令檔註解並重建 README

README.md

@@ -1,6 +1,8 @@
 # Codex CLI Composite Action
 
-此 repository 提供一個 Gitea/GitHub Actions composite action，用於安裝 Codex CLI、寫入 OAuth token、執行指定提示詞，並將 CLI 輸出寫入 action output。
+提供一個 Gitea/GitHub Actions composite action，用於安裝 Codex CLI、寫入 OAuth token、執行指定提示詞，並將 CLI 輸出寫入 action output；另提供透過 `codex app-server` 取得目前登入帳號 email 的工具函式。
+
+> 更新時間：2026/06/29 14:18:26
 
 ## 專案列表
 
@@ -8,50 +10,66 @@
 
 | 專案名稱 | 專案描述 |
 | --- | --- |
-| [codex](https://gitea.jsc.idv.tw/composite-actions/codex) | 提供 Codex CLI composite action，讓 workflow 可透過 `oauth` 與 `prompt` 輸入執行 CLI，並從 repository variable 讀取模型名稱後取得文字輸出。 |
+| [codex](https://gitea.jsc.idv.tw/composite-actions/codex/src/branch/develop/) | 提供 Codex CLI composite action（安裝 `@openai/codex`、寫入 OAuth token、執行提示詞並輸出文字），並提供透過 `codex app-server` JSON-RPC `account/read` 取得目前登入帳號 email 的工具函式。 |
 
 ### 參考專案
 
 | 專案名稱 | 參考專案列表 |
 | --- | --- |
-| [codex](https://gitea.jsc.idv.tw/composite-actions/codex) | 無 |
+| [codex](https://gitea.jsc.idv.tw/composite-actions/codex/src/branch/develop/) | 無 |
 
 ### NuGet 套件
 
 | 專案名稱 | NuGet 套件列表 |
 | --- | --- |
-| [codex](https://gitea.jsc.idv.tw/composite-actions/codex) | 無 |
+| [codex](https://gitea.jsc.idv.tw/composite-actions/codex/src/branch/develop/) | 無 |
 
 ## 功能列表
 
-此 repository 未包含可列入 README 的 public method、public constructor、public extension method 或 public operator。
+### codex
+
+| 功能名稱 | 功能描述 |
+| --- | --- |
+| [codex_account.read_account_email](https://gitea.jsc.idv.tw/composite-actions/codex/src/branch/develop/app/codex_account.py#L12) | [透過 codex app-server 的 JSON-RPC `account/read` 取得目前登入帳號的 email，取不到或逾時回傳空字串。](#codex_accountread_account_email) |
 
 ## 使用範例
 
-### 在 workflow 中呼叫 Codex CLI
+<a id="codex_accountread_account_email"></a>
+### codex_account.read_account_email
 
-以下範例示範在 workflow step 中呼叫此 composite action，傳入 OAuth token 與提示詞，並在後續步驟讀取 `text` output。模型名稱由 action 直接讀取 `vars.CODEX_MODEL`。
+透過 `codex app-server` 的 JSON-RPC `account/read` 取得目前登入帳號的 email。函式會啟動 `codex app-server` 子行程，依序送出 `initialize` / `initialized` / `account/read` 三筆 JSON-RPC 訊息，讀取回應中 `result.account.email` 作為回傳值；讀到 EOF、JSON 解析失敗或超過 `timeout_seconds` 逾時都會停止，取不到時回傳空字串 `""`，且不論成功或失敗都會在 `finally` 終止子行程。
 
-```yaml
-- name: 執行 Codex CLI
-  id: codex
-  uses: https://gitea.jsc.idv.tw/composite-actions/codex@v1
-  with:
-    oauth: ${{ secrets.CODEX_OAUTH }}
-    prompt: "請自我介紹"
+簽名：
 
-- name: 使用輸出文字
-  run: printf '%s\n' '${{ steps.codex.outputs.text }}'
+```python
+def read_account_email(timeout_seconds: float = 25.0) -> str
 ```
 
 前置條件：
 
-- `secrets.CODEX_OAUTH` 必須是 Codex OAuth token 檔案內容的 base64 字串。
-- `vars.CODEX_MODEL` 必須是 Codex CLI 可用的模型名稱。
-- runner 必須可透過 npm 安裝 `@openai/codex`。
+- `codex` CLI 已安裝（例如本 action 的安裝步驟已執行）。
+- `$HOME/.codex/auth.json` 已寫入有效的 OAuth token。
+
+典型呼叫方式：
+
+```python
+from app.codex_account import read_account_email
+
+# 取得目前登入帳號 email；可自訂等待 app-server 回應的逾時秒數
+email = read_account_email(timeout_seconds=25.0)
+if email:
+    print(f"目前登入帳號：{email}")
+else:
+    print("取不到登入帳號（未登入或逾時）")
+```
 
 預期結果：
 
-- action 會安裝 `codex` CLI。
-- action 會將 OAuth token 寫入 `$HOME/.codex/auth.json` 並設定檔案權限為 `600`。
-- action 會執行 `codex exec --model "$MODEL" "$PROMPT"`，並把 stdout 寫入 `steps.codex.outputs.text`。
+- 成功時回傳登入帳號的 email 字串。
+- 未登入、回應缺漏或逾時時回傳空字串 `""`。
+
+此模組亦可直接以指令執行，會將 email 印到 stdout（取不到時印空字串）：
+
+```bash
+python3 app/codex_account.py
+```