REST 介面
除特別說明外，所有介面都需要在請求頭帶上租戶 API Key：
Authorization: Bearer <租戶API Key>預設地址 http://localhost:8787，演示租戶 demo（apiKey 首次啟動隨機生成並列印在日誌中）。本頁供整合開發參考， 普通使用者無需關心。
啟動服務端
bash
# 無模型 Key 也能啟動（認證/會話/介面都能測，只是對話會報錯）
pnpm run server
# 帶真實模型（推薦）
OPENAI_API_KEY=sk-... OPENAI_MODEL=gpt-4o-mini pnpm run server主要環境變數：PORT（預設 8787）、DATA_DIR（預設 ./.zqagent_data）、 APPROVAL_TIMEOUT_SECONDS（審核/提問掛起超時，預設 900）、 TENANT_ID / TENANT_API_KEY / MODEL（演示租戶）。
認證
bash
export BASE=http://localhost:8787
export TOKEN=zk_xxxx # 取啟動日誌「已建立演示租戶」那一行的 apiKey
# 健康檢查（公開）
curl -s $BASE/healthz # => {"status":"ok"}
# 無 Key → 401
curl -s -o /dev/null -w "%{http_code}\n" $BASE/api/v1/sessions # => 401
# 正確 Key → 200
curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer $TOKEN" $BASE/api/v1/sessions核心端點速查
會話
| 方法 | 路徑 | 說明 |
|---|---|---|
| GET | /healthz | 健康檢查（公開） |
| POST | /api/v1/sessions | 建立會話 |
| GET | /api/v1/sessions | 列出會話 |
| GET | /api/v1/sessions/{id} | 獲取會話 |
| PATCH | /api/v1/sessions/{id} | 重新命名會話 |
| DELETE | /api/v1/sessions/{id} | 刪除會話 |
| GET | /api/v1/sessions/{id}/state | 會話狀態（含掛起中的審核/提問） |
| PATCH | /api/v1/sessions/{id}/model | 切換會話模型 |
| PATCH | /api/v1/sessions/{id}/mode | 切換許可權模式（plan / interactive / auto / discuss） |
| PATCH | /api/v1/sessions/{id}/draft | 儲存輸入框草稿（傳空串即清空） |
| POST | /api/v1/sessions/{id}/turns | 提交任務 |
| POST | /api/v1/sessions/{id}/steer | 執行中補充資訊 |
| POST | /api/v1/sessions/{id}/interrupt | 中斷當前任務 |
| POST | /api/v1/sessions/{id}/resume | 恢復會話 |
| GET | /api/v1/sessions/{id}/events | 事件流（輪詢或 SSE，支援 ?since= 增量） |
| GET | /api/v1/sessions/{id}/approvals | 待審核列表 |
| POST | /api/v1/sessions/{id}/approvals/{aid} | 回答審核 |
| GET | /api/v1/sessions/{id}/questions | 待回答列表 |
| POST | /api/v1/sessions/{id}/questions/{qid} | 回答問題 |
專案與節點
| 方法 | 路徑 | 說明 |
|---|---|---|
| GET / POST | /api/v1/projects | 列出 / 建立專案（建立時指定工作目錄） |
| DELETE | /api/v1/projects/{id} | 刪除專案 |
| GET | /api/v1/models | 可用模型列表 |
| GET / PUT | /api/v1/config | 檢視 / 更新節點設定 |
| GET / PUT | /api/v1/node/llm | 檢視 / 設定節點級預設模型 |
| GET | /api/v1/node/host | 節點主機資訊 |
| GET | /api/v1/tools | 工具列表 |
| GET | /api/v1/mcp | MCP 伺服器列表 |
| PUT | /api/v1/mcp | 整體替換 MCP 設定（寫入專案 .agent/mcp.json；平臺下發時 409） |
| POST | /api/v1/mcp/test | 連線測試單個 MCP 伺服器（不落盤） |
用量與成本
| 方法 | 路徑 | 說明 |
|---|---|---|
| GET | /api/v1/usage/summary | 用量彙總（按時間範圍 / 模型） |
| GET | /api/v1/usage/records | 明細記錄 |
| GET | /api/v1/usage/export | 匯出 CSV |
| GET / PUT | /api/v1/usage/pricing | 檢視 / 修改價格表 |
| POST | /api/v1/usage/rebuild | 重建彙總 |
| POST | /api/v1/usage/verify | 校驗賬本 |
遠端接入與配對
| 方法 | 路徑 | 說明 |
|---|---|---|
| GET | /api/v1/fleet/status | 節點接入狀態 |
| POST | /api/v1/fleet/enroll | 憑接入碼接入（zqagent link 呼叫） |
| POST | /api/v1/fleet/unlink | 解除接入 |
| GET | /api/v1/fleet/pairing | 獲取雲端接入配對資訊（閘道器地址 + 名稱空間/金鑰 + nodeId） |
| GET / POST | /api/v1/notifications | 檢視 / 新增通知渠道 |
| DELETE | /api/v1/notifications/{id} | 刪除通知渠道 |
快速上手
bash
# 建立會話
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"model":"gpt-4o-mini"}' $BASE/api/v1/sessions
# => {"data":{"sessionId":"e4df66d6...","status":"idle",...}}
export SID=e4df66d6... # 替換為返回的 sessionId
# 提交任務（立即返回，後臺非同步執行）
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"input":"你好，請介紹一下自己"}' $BASE/api/v1/sessions/$SID/turns
# => {"data":{"accepted":true,"status":"running"}}
# 輪詢事件（since 游標增量拉取）
curl -s "$BASE/api/v1/sessions/$SID/events?since=0"
# 即時訂閱（SSE）
curl -N -H "Authorization: Bearer $TOKEN" -H "Accept: text/event-stream" \
$BASE/api/v1/sessions/$SID/events若會話正在執行任務，
POST /turns會自動轉為補充資訊注入當前任務 （返回{"data":{"accepted":true,"status":"steering"}}），而不是報錯。
審核與提問
模型請求有副作用的操作（寫檔案、執行命令等）時會掛起等待審核；呼叫 ask_user 等工具時 會掛起等待回答。
bash
# 檢視待審核列表（id 就是工具呼叫 ID）
curl -s -H "Authorization: Bearer $TOKEN" $BASE/api/v1/sessions/$SID/approvals
# 回答審核：once | always_tool | always_command | deny
# always_command 僅對 run_shell 有效
export AID=call_xxx
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"decision":"once"}' $BASE/api/v1/sessions/$SID/approvals/$AID
# 回答問題
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"answer":"繼續"}' $BASE/api/v1/sessions/$SID/questions/qid_xxx多租戶隔離
每個租戶用自己的 API Key 訪問自己的會話；用租戶 A 的 Key 訪問租戶 B 的會話會返回 404。
錯誤碼速查
| HTTP | code | 場景 |
|---|---|---|
| 401 | unauthorized | 無 Key / Key 無效 |
| 404 | not_found | 會話不存在 / 未知路由 / 跨租戶訪問 |
| 409 | not_running | 顯式 steer 時會話未在執行中 |
| 409 | has_pending_interaction | 存在未決審核/提問，不能提交新任務 |
| 400 | bad_request | body 非法 JSON / input 為空 |
| 400 | invalid_decision | decision 非法，或對非 run_shell 提交 always_command |