alex
fcf7680e49
- 自 alterminal/fox 的 cli/ 目錄以 git subtree split 移出（保留 git 歷史）。 - package.json：改為獨立專案（移除 private、補 repository／homepage／files、 增加 packageManager pnpm@9.15.3）。 - README／docs/cli-install.md：路徑與指令改為本倉庫根目錄版型 （node dist/cli.js、pnpm build；獨立安裝不會建立 node_modules/.bin/fox， 掛 PATH 改用 symlink）。 - 新增 .gitignore 與 pnpm-lock.yaml。 - 驗證：pnpm install + pnpm build + node dist/cli.js --help（exit 0）、 未知命令 exit 2。
150 lines
4.7 KiB
Markdown
150 lines
4.7 KiB
Markdown
# Fox CLI 安裝指南
|
||
|
||
> 適用對象：想在命令列使用 `fox` 與 Fox 後端互動的人與 AI agent。
|
||
> 命令功能、設計原則與開發計畫見 [README.md](../README.md)。
|
||
> 本指南以 macOS／Linux 為主（Windows 差異處另行註記）。
|
||
|
||
## 一、前置需求
|
||
|
||
| 項目 | 需求 | 說明 |
|
||
|------|------|------|
|
||
| Node.js | ≥ 22 | CLI 使用內建 `fetch`，**零執行期相依**（無第三方套件） |
|
||
| pnpm | 任意近期版本 | 僅安裝與建置階段需要 |
|
||
| git | 任意近期版本 | 取得原始碼 |
|
||
| Fox 後端 | 可連線的 API 位址 | 見第四節；本機開發預設 `http://localhost:3000` |
|
||
|
||
檢查版本：
|
||
|
||
```bash
|
||
node --version # 應為 v22 以上
|
||
pnpm --version
|
||
```
|
||
|
||
沒有 pnpm 時可用 Corepack（Node 內建）或 npm 安裝：
|
||
|
||
```bash
|
||
corepack enable # 或
|
||
npm install -g pnpm
|
||
```
|
||
|
||
> CLI 是純客戶端工具：**不需要** Postgres／MinIO（`docker compose`）或前端，只要網路上連得到後端 API 即可。
|
||
|
||
## 二、取得與建置
|
||
|
||
```bash
|
||
git clone https://gitea.alterminal.com/alterminal/fox-cli.git
|
||
cd fox-cli
|
||
pnpm install # 安裝相依（typescript／@types/node，僅建置需要）
|
||
pnpm build # 以 tsc 編譯到 dist/
|
||
```
|
||
|
||
建置產物 `dist/` 是純 JavaScript，只使用 Node 內建模組，可整個目錄複製到其他有 Node ≥22 的機器直接執行。
|
||
|
||
## 三、執行方式（擇一）
|
||
|
||
**1. 倉庫內直接使用**
|
||
|
||
```bash
|
||
node dist/cli.js --help
|
||
# 或
|
||
pnpm start auth status
|
||
```
|
||
|
||
注意：`pnpm start -- <子命令>` 這種含 `--` 的寫法，在 pnpm 9 會把 `--` 當成參數傳給程式而報「未知命令」——**不要加 `--`**。
|
||
|
||
**2. 掛上 PATH（推薦）**
|
||
|
||
```bash
|
||
mkdir -p ~/.local/bin
|
||
ln -s "$(pwd)/dist/cli.js" ~/.local/bin/fox
|
||
# 確認 ~/.local/bin 在 PATH 內（echo $PATH）；沒有就加進 shell 設定檔後重開 shell
|
||
fox --help
|
||
```
|
||
|
||
> symlink 指向倉庫內的 `dist/cli.js`；`pnpm build` 之後即是新版（pnpm 不會為倉庫本體建立 bin 連結，掛 PATH 請用 symlink）。
|
||
|
||
**3. 不建連結，直接以 node 執行**
|
||
|
||
```bash
|
||
node dist/cli.js --help
|
||
```
|
||
|
||
## 四、設定：API 位址與 access token
|
||
|
||
讀取優先順序（高 → 低）：
|
||
|
||
1. `--api-url`／`--token` 參數
|
||
2. 環境變數 `FOX_API_URL`／`FOX_API_TOKEN`
|
||
3. 設定檔 `~/.config/fox/cli.json`
|
||
4. `apiUrl` 預設 `http://localhost:3000`（token 無預設）
|
||
|
||
**環境變數（推薦，適合 agent／CI）**
|
||
|
||
```bash
|
||
export FOX_API_URL="https://api.fox.example.com"
|
||
export FOX_API_TOKEN="fpat_…" # token 值請見下方安全說明
|
||
```
|
||
|
||
**設定檔**
|
||
|
||
```bash
|
||
mkdir -p ~/.config/fox
|
||
umask 077
|
||
cat > ~/.config/fox/cli.json <<'EOF'
|
||
{
|
||
"apiUrl": "https://api.fox.example.com",
|
||
"token": "fpat_…"
|
||
}
|
||
EOF
|
||
chmod 600 ~/.config/fox/cli.json
|
||
```
|
||
|
||
Windows 的對應路徑為 `%USERPROFILE%\.config\fox\cli.json`。
|
||
|
||
> `--token <value>` 會留在 shell 歷史與 process list，僅供本機快速測試，不建議日常使用。
|
||
|
||
**取得 access token**：在 Fox 網頁端以自己的帳號建立，或由管理員通過 `POST /access-tokens` 建立。token 以 `fpat_` 開頭，**原始值只在建立當下顯示一次**。之後隨時可用 `fox tokens verify` 確認有效性（過期或撤銷會回 401）。
|
||
|
||
**安全原則**：token 只存放在環境變數或本機設定檔（權限 600），**絕不寫進 commit、issue、PR 或任何儲存庫內容**。經公開渠道交付時須以收受方公開金鑰加密（組織慣例見 `alterminal/agents` 的 AGENTS.md 2.3）。
|
||
|
||
## 五、驗證安裝
|
||
|
||
```bash
|
||
fox --help # 印出命令清單（exit 0）
|
||
fox auth status # 公開端點：查後端登入／SSO 設定
|
||
fox tokens verify # 需要 token：有效回 exit 0；缺少或無效回 exit 1 並在 stderr 說明
|
||
```
|
||
|
||
| exit code | 意義 |
|
||
|-----------|------|
|
||
| 0 | 成功 |
|
||
| 1 | 執行失敗（後端 4xx/5xx、網路錯誤、缺 token） |
|
||
| 2 | 用法錯誤（缺參數、未知命令） |
|
||
|
||
stdout 只輸出**單一 JSON**（可直接管給 `jq`），人類可讀訊息一律走 stderr：
|
||
|
||
```bash
|
||
fox novels get my-novel | jq '.title'
|
||
```
|
||
|
||
## 六、更新與解除安裝
|
||
|
||
```bash
|
||
# 更新
|
||
cd fox-cli
|
||
git pull
|
||
pnpm install && pnpm build
|
||
|
||
# 解除安裝
|
||
rm ~/.local/bin/fox # 若有建連結
|
||
rm -rf /path/to/fox-cli # 倉庫本體
|
||
rm ~/.config/fox/cli.json # 內含 token，一併刪除
|
||
```
|
||
|
||
## 疑難排解
|
||
|
||
- **`fox: command not found`**：`~/.local/bin` 不在 PATH，或還沒建 symlink（見第三節）。
|
||
- **`未知命令：fox --…`**：用了 `pnpm start -- <子命令>` 的寫法；把 `--` 拿掉（見第三節）。
|
||
- **`無法連線到 http://localhost:3000`**：後端沒開或位址不對；設定 `FOX_API_URL` 指向正確的 API 位址。
|
||
- **`缺少 access token`**：需要授權的命令（如 `tokens verify`）沒有設定 token；見第四節。
|