From 1686322eff916cffd45bb4af627bcdb61619c620 Mon Sep 17 00:00:00 2001 From: alex Date: Fri, 4 Sep 2026 19:01:51 +0800 Subject: [PATCH] =?UTF-8?q?feat(cli):=20=E6=96=B0=E5=A2=9E=20cli=20?= =?UTF-8?q?=E5=AD=90=E9=A0=85=E7=9B=AE=E7=9B=AE=E9=8C=84=E8=88=87=20README?= =?UTF-8?q?=EF=BC=88issue=20#10=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 定位：供人與 AI agent 直接與後端 API 互動的命令列工具 - 命令規劃對應現有後端端點（access-tokens、auth、novels） - 記錄 novels 授權缺口（session-only），待後端支援 Bearer 後補齊 - 根 README 目錄結構加入 cli/ --- README.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..3d1b18d --- /dev/null +++ b/README.md @@ -0,0 +1,65 @@ +# Fox CLI — 與 Fox 後端互動的命令列工具 + +> 專案狀態：規劃中（本目錄與說明先行，見 issue #10）｜日期：2026-09-04 + +`fox` 是一個命令列工具，讓人與 **AI agent** 不經過前端，直接與 Fox 後端 API 互動：查詢／建立／編輯作品、管理 access token 等。目標是「一句命令拿到機器可解析的結果」，方便腳本、CI 與 agent 排程使用。 + +## 一、設計原則 + +1. **非互動優先**：所有命令不跳 prompt，參數與環境變數給齊即可執行。缺少必要參數直接報錯（非零 exit code），適合 AI agent 與 cron。 +2. **機器可讀輸出**：資料命令預設輸出 JSON（stdout 僅印 JSON，其餘訊息一律走 stderr）；人用格式之後再以 `--pretty` 提供。 +3. **穩定的 exit code**：`0` 成功；`1` 執行失敗（後端 4xx/5xx、網路錯誤）；用法錯誤（缺參數、未知子命令）同樣回非零，訊息在 stderr。 +4. **冪等意識**：文件會標明各命令是否幂等（如 `tokens revoke` 冪等、`novels create` 會因 slug 重複而失敗），供 agent 重試決策。 +5. **Secret 不落檔**：token 只從環境變數或本機設定檔讀取（見下），絕不寫進 commit／issue／PR。 + +## 二、授權（access token） + +後端的 access token（`fpat_` 前綴）是 CLI 的主要憑證： + +- **建立**：先在 Fox 網頁端以帳號建立，或由管理員以 `POST /access-tokens` 建立；原始值只在建立時顯示一次。 +- **讀取優先順序**： + 1. 環境變數 `FOX_API_TOKEN`（推薦，適合 agent／CI） + 2. `--token ` 參數（注意：會留在 shell 歷史，僅供本機快速測試） + 3. 本機設定檔 `~/.config/fox/cli.json`（`{"apiUrl": "...", "token": "..."}`，權限應設 600） +- **使用方式**：每個請求帶 `Authorization: Bearer `；先用 `fox tokens verify` 確認有效（過期／撤銷會回 401）。 + +後端 API 位址由 `FOX_API_URL`（或設定檔 `apiUrl`）指定，本機開發預設 `http://localhost:3000`。 + +## 三、命令規劃（對應後端端點） + +| 命令 | 後端端點 | 說明 | +|------|----------|------| +| `fox auth status` | `GET /auth/status` | 查詢登入／SSO 設定（公開） | +| `fox tokens verify` | `GET /access-tokens/verify` | 驗證手中 token 是否有效 | +| `fox tokens create --name <名稱> [--expires-at ]` | `POST /access-tokens` | 建立新 token（回傳只出現一次的原始值） | +| `fox tokens list` | `GET /access-tokens` | 列出 token（不含 hash／原始值） | +| `fox tokens revoke ` | `DELETE /access-tokens/:id` | 撤銷 token（冪等） | +| `fox novels get ` | `GET /novels/:slug` | 查單一作品（公開） | +| `fox novels list` | `GET /novels` | 列出自己的作品（需授權，見下） | +| `fox novels create --title <書名> [--slug ] [--synopsis <簡介>]` | `POST /novels` | 建立作品（需授權，見下） | +| `fox novels update [--title ...] [--slug ...] [--synopsis ...]` | `PATCH /novels/:slug` | 更新作品（需授權，見下） | + +> **授權缺口（待後端跟進）**：目前 `novels` 的授權端點只吃瀏覽器 session（Bear SSO cookie），尚未接受 Bearer access token；access token 也暫無 `accountId` 歸屬（見 `backend/src/access-token` 註解）。CLI 第一步先支援公開端點與 `access-tokens` 系列；待後端讓 `AccessTokenGuard` 套用到 `novels`（並為 token 加帳號歸屬）後，再補齊 `novels` 的授權命令。 + +## 四、AI agent 使用指引 + +- 每個命令都有 `--help`；未知命令回非零 exit code。 +- 輸出為單一 JSON 物件，可直接 `jq` 解析；錯誤時 stderr 有人類可讀訊息，stdout 不印半成品。 +- agent 拿到 token 的建議流程：由人透過加密渠道交付（組織公開金鑰加密，見 `alterminal/agents` 的 AGENTS.md 2.3），存入環境變數或設定檔，不寫入任何儲存庫內容。 + +## 五、技術棧與開發計畫 + +- **實作語言**：Node.js（≥22）＋ TypeScript，與 `frontend`／`backend` 同語言。 +- **加入 workspace**：實作開始時把 `cli` 加進根 `pnpm-workspace.yaml` 並建立 `package.json`（目前僅目錄與說明，先不動 workspace 設定）。 + +里程碑： + +- **M0**：子項目目錄＋README（本步）。 +- **M1**：HTTP client、設定讀取、`tokens verify`／`auth status`。 +- **M2**：`tokens create/list/revoke`、公開的 `novels get`。 +- **M3**：`novels list/create/update`（視後端授權進度）、`--pretty`、錯誤處理打磨。 + +## 維護說明 + +1. 後端端點異動時，同步更新第三節對應表。 +2. 命令列介面（參數、輸出欄位）保持向下相容；破壞性變更須在 README 註明版本。