alex
1686322eff
- 定位：供人與 AI agent 直接與後端 API 互動的命令列工具 - 命令規劃對應現有後端端點（access-tokens、auth、novels） - 記錄 novels 授權缺口（session-only），待後端支援 Bearer 後補齊 - 根 README 目錄結構加入 cli/
66 lines
4.7 KiB
Markdown
66 lines
4.7 KiB
Markdown
# 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 <value>` 參數（注意：會留在 shell 歷史，僅供本機快速測試）
|
||
3. 本機設定檔 `~/.config/fox/cli.json`（`{"apiUrl": "...", "token": "..."}`，權限應設 600）
|
||
- **使用方式**：每個請求帶 `Authorization: Bearer <token>`；先用 `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 <ISO8601>]` | `POST /access-tokens` | 建立新 token（回傳只出現一次的原始值） |
|
||
| `fox tokens list` | `GET /access-tokens` | 列出 token（不含 hash／原始值） |
|
||
| `fox tokens revoke <id>` | `DELETE /access-tokens/:id` | 撤銷 token（冪等） |
|
||
| `fox novels get <slug>` | `GET /novels/:slug` | 查單一作品（公開） |
|
||
| `fox novels list` | `GET /novels` | 列出自己的作品（需授權，見下） |
|
||
| `fox novels create --title <書名> [--slug <slug>] [--synopsis <簡介>]` | `POST /novels` | 建立作品（需授權，見下） |
|
||
| `fox novels update <slug> [--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 註明版本。
|