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 |