83 lines
5.5 KiB
Markdown
83 lines
5.5 KiB
Markdown
# Fox CLI — 與 Fox 後端互動的命令列工具
|
||
|
||
> 專案狀態：M0–M2 已實作（M1：HTTP client、設定讀取、`tokens verify`／`auth status`；M2：`tokens create/list/revoke`、公開的 `novels get`）｜日期：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` | 更新作品（需授權，見下） |
|
||
|
||
> **授權（issue #16 已補齊）**：受保護端點（`novels list/create/update`、`auth me`）的 `AuthGuard` 現在同時接受 `Authorization: Bearer <access token>` 與瀏覽器 session（cookie）；Bearer 優先。access token 需綁定帳號（`POST /access-tokens` 帶 `accountId`，或由管理員建立時指定），未綁帳號的系統 token 只能用於 `tokens verify`。CLI 待 M3 補齊 `novels list/create/update` 命令。
|
||
|
||
## 四、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`（完成，見 `src/http.ts`、`src/config.ts`）。
|
||
- **M2**：`tokens create/list/revoke`、公開的 `novels get`（完成）。
|
||
- **M3**：`novels list/create/update`（視後端授權進度）、`--pretty`、錯誤處理打磨。
|
||
|
||
## 開發
|
||
|
||
> 使用者安裝與設定說明見 [docs/cli-install.md](../docs/cli-install.md)。
|
||
|
||
```bash
|
||
pnpm install # 倉庫根目錄
|
||
pnpm --filter fox-cli build
|
||
pnpm --filter fox-cli start <子命令> # 例如 auth status；不要加 "--"（pnpm 9 會把它當參數）
|
||
```
|
||
|
||
結構：`src/cli.ts`（進入點與分發）、`src/command.ts`（參數解析與註冊表）、
|
||
`src/config.ts`（設定讀取）、`src/http.ts`（fetch 封裝）、`src/commands.ts`（各命令實作）、
|
||
`src/errors.ts`（錯誤與 exit code）。
|
||
|
||
exit code：`0` 成功；`1` 執行失敗（後端 4xx/5xx、網路錯誤）；`2` 用法錯誤。
|
||
`tokens revoke` 成功時輸出 `{"ok": true, "id": <id>}`（後端回 204 無內容）。
|
||
|
||
## 維護說明
|
||
|
||
1. 後端端點異動時，同步更新第三節對應表。
|
||
2. 命令列介面（參數、輸出欄位）保持向下相容；破壞性變更須在 README 註明版本。
|