Interface

API 与 CLI

ZhiWu 对外只有一套接口：统一挂 /api 前缀的 REST + SSE。Web 前端、官方 CLI 与外部渠道共用同一份路由与同一套鉴权，没有专用服务端 SDK，也没有第二套私有协议。

Overview

接口总览

以下结论逐条核对自 docs/06-api.md 与 backend/server/src/server/routers/ 的路由装饰器。

⌁REST + SSE

同步请求走 REST JSON，Run 的流式输出走 Server-Sent Events（Redis Stream 转发），无 GraphQL。

/统一前缀

26 个 router 聚合后统一挂 /api（routers/__init__.py、main.py）。URL 无版本号。

⤴兼容性策略

无 /v1 前缀、仓内无 CHANGELOG 与弃用策略，兼容性靠响应字段增量演进（docs/06-api.md §1）。

⌨客户端

官方 CLI zhiwu（zhiwu-cli/）走同一套 HTTP/SSE 接口；仓库内没有专用服务端 SDK。

错误格式：统一为 FastAPI HTTPException 的 JSON，错误信息在 detail 字段；请求体不合法时为 422 校验错误。见 docs/06-api.md §1。

版本号来源：/api/system/discovery 与 /api/system/health 返回的 version 取自包元数据 importlib.metadata.version("zhiwu")，部署时可用 ZHIWU_CODE_REVISION 另记代码修订号（docs/06-api.md）。

Authentication

鉴权：双通道 Bearer，无全局中间件

Authorization: Bearer <JWT | zhiwukey_...> 单头双通道：以 zhiwukey_ 开头按 API Key 校验，否则按 JWT 解析（server/src/server/utils/auth_middleware.py、utils/auth_utils.py）。

没有全局鉴权中间件或跳过列表。auth_middleware.py 只提供四个依赖：get_current_user / get_required_user / get_admin_user / get_superadmin_user，逐路由声明。未声明依赖的路由即匿名可访——按此规则扫描全部 196 个路由，公开端点仅下表所列（docs/06-api.md §1 统计为 12 个，OIDC 三个 GET 路径在原文档并为一行，故此处按方法×路径拆为 13 行）。

公开端点（无鉴权依赖）

方法	路径	说明
POST	/api/auth/token	密码换 JWT（限流 60s / 10 次 / IP）
POST	/api/auth/initialize	首次运行创建 superadmin
GET	/api/auth/check-first-run	是否需要初始化
POST	/api/auth/cli/sessions	CLI 设备码会话创建
POST	/api/auth/cli/sessions/token	CLI 设备码轮询换 token
GET	/api/auth/oidc/config	OIDC 配置
GET	/api/auth/oidc/login-url	OIDC 授权跳转地址
GET	/api/auth/oidc/callback	OIDC 回调（302）
POST	/api/auth/oidc/exchange-code	一次性 code 换登录数据
GET	/api/system/health	探活
GET	/api/system/ready	就绪检查
GET	/api/system/discovery	版本与能力发现（CLI 兼容性校验入口）
GET	/api/system/info	品牌信息

其余端点（含 /api/auth/cli/sessions/{user_code}、/api/auth/me）一律带 get_required_user 或更高依赖；/auth/cli/authorize 是前端路由而非 API。来源：docs/06-api.md。

生产暴露面提示：/docs 与 /openapi.json 在所有环境下都是开的——main.py#L82 以 FastAPI(lifespan=lifespan) 默认参数构造，未按 ZHIWU_ENV 关闭 docs_url/redoc_url/openapi_url。是否需要收敛属部署决策，见 docs/06-api.md §3 注记。

Endpoints

端点清单（按模块）

路径与方法逐一取自 backend/server/src/server/routers/ 内的路由装饰器，聚合前缀见 routers/__init__.py#L29-L61。输入关键字可跨全部表格过滤行。

命中行数

/api/agent — Agent 运行

方法	路径	用途
GET	/api/agent/backends	后端图实现列表
GET	/api/agent/backends/{backend_id}	后端图实现详情
GET	/api/agent	Agent 列表
POST	/api/agent	创建 Agent
GET	/api/agent/default	默认 Agent
GET	/api/agent/{agent_id}	Agent 详情
PUT	/api/agent/{agent_id}	更新 Agent
DELETE	/api/agent/{agent_id}	删除 Agent
POST	/api/agent/{agent_id}/set_default	设为默认 Agent
POST	/api/agent/runs	提交 Run（thread_id、消息、request_id 幂等、queue_policy）
GET	/api/agent/requests/{request_id}	请求状态
GET	/api/agent/thread/{thread_id}/requests	线程请求队列
POST	/api/agent/thread/{thread_id}/requests/continue	队列继续派发
POST	/api/agent/requests/{request_id}/cancel	取消排队请求
POST	/api/agent/requests/{request_id}/steer	Steer 排队请求
GET	/api/agent/requests/{request_id}/events	排队事件流 SSE
GET	/api/agent/runs/{run_id}	Run 状态
GET	/api/agent/runs/{run_id}/result	Run 结果
GET	/api/agent/runs/{run_id}/langfuse	Langfuse 追踪链接
POST	/api/agent/runs/{run_id}/cancel	取消运行
GET	/api/agent/runs/{run_id}/events	运行事件流，Last-Event-ID / after_seq 续传 SSE
GET	/api/agent/thread/{thread_id}/active_run	线程当前活跃 Run

/api/agent-invocation/* — Agent 外部调用通道

方法	路径	用途
POST	/api/agent-invocation/agent-call/runs	外部调用：异步提交 Run
POST	/api/agent-invocation/agent-call/runs/result	外部调用：拉取结果
POST	/api/agent-invocation/channel/messages	外部渠道消息提交
POST	/api/agent-invocation/eval/runs	评测 Run（HTTP 内阻塞至终结，不走 SSE）

三个 invocation 路由均只挂 get_required_user（API Key 与 JWT 同权），没有独立限流/配额；并发上限来自队列语义与 ARQ_MAX_JOBS（默认 10）。来源：docs/06-api.md 已确认结论。

/api/chat — 对话

方法	路径	用途
POST	/api/chat/call	同步对话入口（非 Run 体系）
GET	/api/chat/thread/{thread_id}/history	历史消息
GET	/api/chat/thread/{thread_id}/state	LangGraph state
GET	/api/chat/thread/{thread_id}/audits	审计消息
POST	/api/chat/thread/{thread_id}/compress	手动压缩上下文
POST	/api/chat/thread	创建线程
GET	/api/chat/threads	线程列表
GET	/api/chat/threads/search	线程搜索
GET	/api/chat/thread/{thread_id}	线程详情
PUT	/api/chat/thread/{thread_id}	更新线程
DELETE	/api/chat/thread/{thread_id}	删除线程
POST	/api/chat/thread/{thread_id}/viewed	标记已读
POST	/api/chat/attachments/tmp	附件临时上传（三段式 · 1）
POST	/api/chat/attachments/tmp/parse	附件临时解析（三段式 · 2）
POST	/api/chat/thread/{thread_id}/attachments/confirm	附件确认入线程（三段式 · 3）
GET	/api/chat/thread/{thread_id}/attachments	附件列表
DELETE	/api/chat/thread/{thread_id}/attachments/{file_id}	删除附件
GET	/api/chat/thread/{thread_id}/artifacts/{path}	产物读取
POST	/api/chat/thread/{thread_id}/artifacts/save	产物保存到工作区
POST	/api/chat/message/{message_id}/feedback	消息点赞/点踩
GET	/api/chat/message/{message_id}/feedback	查询消息反馈
POST	/api/chat/image/upload	图片上传

/api/knowledge — 知识库

方法	路径	用途
GET	/api/knowledge/databases	知识库列表
POST	/api/knowledge/databases	创建知识库
GET	/api/knowledge/databases/accessible	可访问的知识库
GET	/api/knowledge/databases/{kb_id}	知识库详情
PUT	/api/knowledge/databases/{kb_id}	更新知识库
DELETE	/api/knowledge/databases/{kb_id}	删除知识库
POST	/api/knowledge/databases/{kb_id}/stats/repair	修复知识库统计
GET	/api/knowledge/types	知识库类型
GET	/api/knowledge/chunk-presets	分块 preset 列表
GET	/api/knowledge/stats	知识库整体统计
POST	/api/knowledge/generate-description	生成知识库描述
GET	/api/knowledge/databases/{kb_id}/documents	文档列表
POST	/api/knowledge/databases/{kb_id}/documents	登记文档
POST	/api/knowledge/databases/{kb_id}/documents/add	确认添加文档
GET	/api/knowledge/databases/{kb_id}/documents/search	文档搜索
GET	/api/knowledge/databases/{kb_id}/documents/exists	同名/同内容存在性检查
GET	/api/knowledge/databases/{kb_id}/documents/{doc_id}	文档详情
GET	/api/knowledge/databases/{kb_id}/documents/{doc_id}/basic	文档基础信息
GET	/api/knowledge/databases/{kb_id}/documents/{doc_id}/content	文档解析内容
GET	/api/knowledge/databases/{kb_id}/documents/{doc_id}/download	下载原始文档
DELETE	/api/knowledge/databases/{kb_id}/documents/{doc_id}	删除文档
DELETE	/api/knowledge/databases/{kb_id}/documents/batch	批量删除文档
POST	/api/knowledge/databases/{kb_id}/documents/parse	解析文档
POST	/api/knowledge/databases/{kb_id}/documents/parse-pending	批量解析待处理文档
POST	/api/knowledge/databases/{kb_id}/documents/index	构建索引
POST	/api/knowledge/databases/{kb_id}/documents/index-pending	批量索引待处理文档
POST	/api/knowledge/databases/{kb_id}/query	知识库检索
POST	/api/knowledge/databases/{kb_id}/query-test	检索参数试跑
GET	/api/knowledge/databases/{kb_id}/query-params	读取检索参数
PUT	/api/knowledge/databases/{kb_id}/query-params	保存检索参数
GET	/api/knowledge/databases/{kb_id}/sample-questions	示例问题列表
POST	/api/knowledge/databases/{kb_id}/sample-questions	生成示例问题
GET	/api/knowledge/databases/{kb_id}/graph-build/status	图谱构建状态
POST	/api/knowledge/databases/{kb_id}/graph-build/config	图谱构建配置
POST	/api/knowledge/databases/{kb_id}/graph-build/index	触发图谱构建
GET	/api/knowledge/databases/{kb_id}/graph-build/failed-chunks	构建失败的 chunk
POST	/api/knowledge/databases/{kb_id}/graph-build/reset	重置图谱构建
POST	/api/knowledge/databases/{kb_id}/graph-build/reconcile	图谱对账修复
GET	/api/knowledge/mindmap/databases	思维导图知识库列表
GET	/api/knowledge/databases/{kb_id}/mindmap	读取思维导图
GET	/api/knowledge/databases/{kb_id}/mindmap/files	思维导图文件列表
GET	/api/knowledge/databases/{kb_id}/mindmap/diff	思维导图版本对比
POST	/api/knowledge/databases/{kb_id}/mindmap/generate	生成思维导图
POST	/api/knowledge/databases/{kb_id}/folders	创建文件夹
PUT	/api/knowledge/databases/{kb_id}/folders/{folder_id}/rename	重命名文件夹
PUT	/api/knowledge/databases/{kb_id}/documents/{doc_id}/move	移动文档到文件夹
GET	/api/knowledge/databases/{kb_id}/virtual-folders/detect	虚拟文件夹探测
POST	/api/knowledge/databases/{kb_id}/virtual-folders/migrate	虚拟文件夹迁移
GET	/api/knowledge/databases/{kb_id}/virtual-folders/migrations/{task_id}/events	迁移进度事件流 SSE
POST	/api/knowledge/files/upload	上传文件
POST	/api/knowledge/files/fetch-url	从 URL 抓取文件
POST	/api/knowledge/files/import-workspace	从工作区导入文件
GET	/api/knowledge/files/supported-types	支持的文件类型
POST	/api/knowledge/files/markdown	文件转 Markdown
GET	/api/knowledge/databases/{kb_id}/images/{object_path}	读取文档内嵌图片
GET	/api/knowledge/databases/{kb_id}/export	导出知识库

/api/knowledge/databases/external — 外部知识通道（CLI / Agent，API Key）

方法	路径	用途
GET	/api/knowledge/databases/external	可访问知识库列表（kb list）
GET	/api/knowledge/databases/external/{kb_id}/files	文件列表（kb files）
POST	/api/knowledge/databases/external/{kb_id}/retrieve	知识检索（kb query）
GET	/api/knowledge/databases/external/{kb_id}/files/{file_id}/open	分块打开文件（kb open）
POST	/api/knowledge/databases/external/{kb_id}/files/{file_id}/find	文件内关键词/正则查找（kb find）

/api/evaluation 与 /api/graph — 评估与图谱查询

方法	路径	用途
POST	/api/evaluation/databases/{kb_id}/datasets/upload	上传评测数据集
GET	/api/evaluation/databases/{kb_id}/datasets	数据集列表
GET	/api/evaluation/databases/{kb_id}/datasets/{dataset_id}	数据集详情
GET	/api/evaluation/datasets/{dataset_id}/download	下载数据集
DELETE	/api/evaluation/datasets/{dataset_id}	删除数据集
POST	/api/evaluation/databases/{kb_id}/datasets/generate	生成数据集
POST	/api/evaluation/databases/{kb_id}/datasets/{dataset_id}/resume	续跑数据集生成
POST	/api/evaluation/databases/{kb_id}/runs	创建评测 Run
GET	/api/evaluation/databases/{kb_id}/runs	评测 Run 列表
GET	/api/evaluation/databases/{kb_id}/runs/{run_id}	评测 Run 详情
DELETE	/api/evaluation/databases/{kb_id}/runs/{run_id}	删除评测 Run
GET	/api/graph/list	图谱列表
GET	/api/graph/subgraph	子图查询
GET	/api/graph/labels	节点标签
GET	/api/graph/stats	图谱统计

/api/skills 与 /api/system/skills — Skills

方法	路径	用途
GET	/api/skills	用户可见 Skills 列表
GET	/api/skills/accessible	可访问 Skills
POST	/api/skills/import/prepare	上传导入准备
POST	/api/skills/remote/list	远程仓库列表
POST	/api/skills/remote/search	远程仓库搜索
POST	/api/skills/remote/prepare	远程安装准备（两段式 · 1）
POST	/api/skills/install-drafts/{draft_id}/confirm	确认安装草稿（两段式 · 2）
DELETE	/api/skills/install-drafts/{draft_id}	丢弃安装草稿
POST	/api/skills/personal/install-drafts/{draft_id}/confirm	确认安装为个人 Skill
GET	/api/skills/personal/{slug}/file	读取个人 Skill 文件
DELETE	/api/skills/personal/{slug}	删除个人 Skill
GET	/api/system/skills	管理侧 Skills 列表
GET	/api/system/skills/dependency-options	依赖可选项
GET	/api/system/skills/builtin	内置 Skills
POST	/api/system/skills/builtin/sync	同步内置 Skills
PUT	/api/system/skills/{slug}/share-config	设置分享范围
PUT	/api/system/skills/{slug}/enabled	启用/停用 Skill
GET	/api/system/skills/{slug}/tree	Skill 文件树
GET	/api/system/skills/{slug}/file	读取 Skill 文件
POST	/api/system/skills/{slug}/file	新建 Skill 文件
PUT	/api/system/skills/{slug}/file	更新 Skill 文件
DELETE	/api/system/skills/{slug}/file	删除 Skill 文件
PUT	/api/system/skills/{slug}/dependencies	设置依赖工具/MCP
GET	/api/system/skills/{slug}/export	导出 Skill
DELETE	/api/system/skills/{slug}	删除 Skill
POST	/api/system/skills/delete-batch	批量删除 Skill

/api/system/mcp-servers — MCP 服务（权限：admin）

方法	路径	用途
GET	/api/system/mcp-servers	MCP 服务列表
POST	/api/system/mcp-servers	注册 MCP 服务
GET	/api/system/mcp-servers/{slug}	服务详情
PUT	/api/system/mcp-servers/{slug}	更新服务配置
DELETE	/api/system/mcp-servers/{slug}	删除服务
POST	/api/system/mcp-servers/{slug}/test	连通性测试
PUT	/api/system/mcp-servers/{slug}/status	启用/停用服务
GET	/api/system/mcp-servers/{slug}/tools	工具列表
POST	/api/system/mcp-servers/{slug}/tools/refresh	刷新工具缓存
PUT	/api/system/mcp-servers/{slug}/tools/{tool_name}/toggle	单个工具开关

/api/system/model-providers — 模型供应商

方法	路径	用途
GET	/api/system/model-providers	供应商列表
POST	/api/system/model-providers	创建供应商
GET	/api/system/model-providers/{provider_id}	供应商详情
PUT	/api/system/model-providers/{provider_id}	更新供应商
DELETE	/api/system/model-providers/{provider_id}	删除供应商
GET	/api/system/model-providers/{provider_id}/remote-models	拉取远端模型列表
POST	/api/system/model-providers/models/cache/refresh	刷新模型缓存
GET	/api/system/model-providers/models/v2	可用模型列表
GET	/api/system/model-providers/models/status	模型可用状态

/api/auth · /api/departments · /api/user — 认证与用户

方法	路径	用途
POST	/api/auth/token	密码登录换 JWT（限流 60s/10 次/IP）
GET	/api/auth/check-first-run	是否首次运行
POST	/api/auth/initialize	首跑创建 superadmin
GET	/api/auth/oidc/config	OIDC 配置
GET	/api/auth/oidc/login-url	OIDC 授权地址
GET	/api/auth/oidc/callback	OIDC 回调
POST	/api/auth/oidc/exchange-code	OIDC code 换登录数据
POST	/api/auth/cli/sessions	CLI 授权会话创建
GET	/api/auth/cli/sessions/{user_code}	CLI 会话查询（授权页用，需登录）
POST	/api/auth/cli/sessions/{user_code}/approve	CLI 会话批准
POST	/api/auth/cli/sessions/token	CLI 轮询换 API Key token
GET	/api/auth/me	当前用户信息
PUT	/api/auth/profile	更新个人资料
GET	/api/auth/users	用户列表（admin）
GET	/api/auth/users/page	用户分页（admin）
GET	/api/auth/users/access-options	授权选项（admin）
POST	/api/auth/users	创建用户（admin）
GET	/api/auth/users/{user_id}	用户详情（admin）
PUT	/api/auth/users/{user_id}	更新用户（admin）
DELETE	/api/auth/users/{user_id}	删除用户（admin）
POST	/api/auth/validate-username	校验用户名并预生成 UID
GET	/api/auth/check-uid/{uid}	UID 存在性检查
POST	/api/auth/upload-avatar	上传头像
POST	/api/auth/impersonate/{user_id}	管理员扮演用户（admin）
GET	/api/departments	部门列表
POST	/api/departments	创建部门
GET	/api/departments/{department_id}	部门详情
PUT	/api/departments/{department_id}	更新部门
DELETE	/api/departments/{department_id}	删除部门
GET	/api/user/config	读取用户配置
PUT	/api/user/config	更新用户配置
POST	/api/user/upload-image	上传图片
GET	/api/user/apikey/	API Key 列表
POST	/api/user/apikey/	创建 API Key（zhiwukey_...）
GET	/api/user/apikey/{api_key_id}	API Key 详情
PUT	/api/user/apikey/{api_key_id}	更新 API Key
DELETE	/api/user/apikey/{api_key_id}	删除 API Key（CLI logout 远程失效走这条）
GET	/api/user/agent-env	Agent 环境变量读取
PUT	/api/user/agent-env	Agent 环境变量更新

/api/system 与 /api/system/tools — 系统

方法	路径	用途
GET	/api/system/health	探活（公开，含版本号）
GET	/api/system/ready	就绪检查（公开）
GET	/api/system/discovery	能力发现（公开，CLI 兼容性校验）
GET	/api/system/info	品牌信息（公开）
POST	/api/system/info/reload	重载品牌信息
GET	/api/system/logs	日志查看（admin）
GET	/api/system/config	系统配置读取
POST	/api/system/config	系统配置写入
POST	/api/system/config/update	系统配置更新
GET	/api/system/config/options	system_options 列表
PUT	/api/system/config/options/{key}	更新单个 system_option
GET	/api/system/ocr/options	OCR 引擎选项
GET	/api/system/ocr/health	OCR 引擎健康检查
GET	/api/system/tools	内置工具列表
GET	/api/system/tools/options	工具配置选项

其他模块

方法	路径	用途
GET	/api/projects	项目列表
POST	/api/projects	创建项目
GET	/api/projects/history-candidates	历史候选目录
PUT	/api/projects/{project_id}	更新项目
DELETE	/api/projects/{project_id}	删除项目
GET	/api/scheduled-tasks	定时任务列表
POST	/api/scheduled-tasks	创建定时任务
PATCH	/api/scheduled-tasks/{job_id}	更新定时任务
POST	/api/scheduled-tasks/{job_id}/run-now	立即执行一次
DELETE	/api/scheduled-tasks/{job_id}	删除定时任务
GET	/api/tasks	后台任务列表
GET	/api/tasks/{task_id}	后台任务详情
POST	/api/tasks/{task_id}/cancel	取消后台任务
DELETE	/api/tasks/{task_id}	删除后台任务记录
GET	/api/viewer/filesystem/tree	工作台目录树
GET	/api/viewer/filesystem/file	读取文件
DELETE	/api/viewer/filesystem/file	删除文件
POST	/api/viewer/filesystem/directory	创建目录
POST	/api/viewer/filesystem/upload	上传文件
GET	/api/viewer/filesystem/search	文件名搜索
GET	/api/viewer/filesystem/download	下载文件
GET	/api/workspace/tree	个人工作区目录树
GET	/api/workspace/search	工作区搜索
GET	/api/workspace/file	读取工作区文件
PUT	/api/workspace/file	写入工作区文件
DELETE	/api/workspace/file	删除工作区文件
GET	/api/workspace/download	下载工作区文件
POST	/api/workspace/directory	创建工作区目录
POST	/api/workspace/upload	上传到工作区
GET	/api/workspace/knowledge/tree	知识文件只读目录树
GET	/api/workspace/knowledge/file	知识文件只读查看
GET	/api/workspace/knowledge/download	知识文件下载
GET	/api/mention/search	@ 提及文件搜索
GET	/api/dashboard/stats	仪表盘总览统计
GET	/api/dashboard/stats/users	用户维度统计
GET	/api/dashboard/stats/tools	工具维度统计
GET	/api/dashboard/stats/agents	Agent 维度统计
GET	/api/dashboard/stats/calls/timeseries	调用时序统计
GET	/api/dashboard/stats/threads	线程统计
GET	/api/dashboard/stats/knowledge	知识域统计
GET	/api/dashboard/feedbacks	反馈列表
GET	/api/dashboard/conversations/options	会话筛选选项
GET	/api/dashboard/conversations	会话列表
GET	/api/dashboard/conversations/{thread_id}	会话详情

Examples

调用示例

请求头与字段名以 docs/06-api.md §3 为准；请求体 schema 以各 router 内定义的 Pydantic 模型为准，下面只展示常用字段。

提交 Run · POST /api/agent/runs（request_id 幂等）

curl -X POST "$ZHIWU/api/agent/runs" \
  -H "Authorization: Bearer <jwt 或 zhiwukey_...>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_slug": "default",
    "thread_id": "uuid",
    "request_id": "幂等uuid",
    "content": "帮我分析 uploads/report.xlsx",
    "queue_policy": "enqueue"
  }'
# → 201 { "request_id": "...", "run_id": "...", "status": "pending", ... }
# queue_policy: enqueue（排队）/ reject（同线程有活跃 Run 即拒）/ steer
# 重复提交同一 request_id：返回既有请求，不产生新 Run

SSE 事件流 · GET /api/agent/runs/{run_id}/events（断线续传）

curl -N "$ZHIWU/api/agent/runs/$RUN_ID/events" \
  -H "Authorization: Bearer <jwt>" \
  -H "Accept: text/event-stream" \
  -H "Last-Event-ID: 1727000000000-0"      # 断线后带上次收到的 ID 续传
# 亦支持查询参数 after_seq；事件类型：
#   token · tool_call · tool_result · state · interrupt · done …
# 排队阶段的事件流在 /api/agent/requests/{request_id}/events

API Key 走外部通道检索知识库（CLI 同款路径）

KEY="zhiwukey_..."
# 1. 列出可访问的知识库
curl -s "$ZHIWU/api/knowledge/databases/external" \
  -H "Authorization: Bearer $KEY"
# 2. 对某个库发起检索（external 通道，CLI kb query 走同一条）
curl -s -X POST "$ZHIWU/api/knowledge/databases/external/1/retrieve" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "季度营收多少", "top_k": 5, "search_mode": "hybrid" }'
# 通道前缀 /api/knowledge/databases/external*，挂载见 routers/__init__.py#L55
# （external_kb_router.py#L76）

鉴权说明：API Key 与 JWT 在业务端点同权（都过 get_required_user），来源 docs/06-api.md 已确认结论。

Status Codes

状态码约定

错误体统一为 { "detail": ... }。以下语义核对自 docs/06-api.md §4。

状态码	含义	备注
401	JWT 过期/无效、API Key 无效	双通道 Bearer 均失败时返回
403	角色不足或资源拒绝	superadmin/admin 依赖不满足，或资源 `share_config` 拒绝
404	资源不存在	—
409	冲突	幂等冲突类场景（如队列 reject 语义、generation 不匹配）
422	校验错误	FastAPI Pydantic 请求体校验失败
423	账号登录锁定	响应头 `X-Lock-Remaining` 给出剩余秒数（`auth_middleware.py#L97-L102`，已在 CORS `expose_headers` 放行）
429	登录限流	60s 内 10 次 / IP（`main.py#L33-L44`、`services/login_rate_limit_service.py`）；全仓唯一的节流即登录链路

幂等语义：重复 request_id 提交 Run 返回既有请求，不产生新 Run（唯一约束，models_business.py#L1203，见 docs/06-api.md §4）。此外 agent-invocation 各通道没有独立限流/配额，大规模并发只会排队（ARQ_MAX_JOBS 默认 10）。

CLI

命令行客户端 zhiwu

官方 CLI zhiwu-cli（命令名 zhiwu）是仓库内独立 Python 包：Typer + httpx + questionary + langfuse，只做"远程编排 + 结果呈现"，执行全在后端。它复用本页同一套 /api 接口，走 API Key（zhiwukey_ 前缀）Bearer 鉴权（docs/14-cli.md §1）。

安装与首次连接

cd zhiwu-cli
uv tool install --editable .        # 全局命令 zhiwu（默认 ~/.local/bin）
zhiwu remote add prod https://your-host
zhiwu login --remote prod           # 浏览器授权
zhiwu login --remote prod --api-key zhiwukey_...   # 或直接导入 Key
zhiwu status

配置文件 ~/.zhiwu/config.toml，权限收敛为 0600（内含明文凭据）；缺失时回退单个 local remote 指向 http://localhost:5173（config.py）。
URL 规范化：自动补 http://、剥离结尾 /api；remote 的 url 被修改时其本地 api_key 一并清空。
多数命令支持 --remote <name>，省略时作用于 current 指向的 remote。
兼容性校验：命令执行前读 /api/system/discovery，比较顶层 version 与 CLI 自带 MIN_SERVER_VERSION = "0.1.0"，并要求对应 capabilities.cli.* 布尔标志为 true；不满足即 ServerCompatibilityError 退出（zhiwu-cli/src/zhiwu_cli/discovery.py#L8-L49）。discovery 的 11 个 cli 键全部是服务端硬编码字面量（system_router.py#L42-L73）。

命令 → 端点映射

命令	能力标志	服务端点（前缀 /api）
zhiwu remote ping	无（仅健康检查）	GET /system/health
zhiwu login --api-key	cli.api_key_auth	GET /auth/me（校验 Key）
zhiwu login（浏览器）	cli.browser_login	POST /auth/cli/sessions · GET /auth/cli/sessions/{user_code} · POST /auth/cli/sessions/token
zhiwu whoami / status	—	GET /auth/me · GET /system/health
zhiwu logout	—	DELETE /user/apikey/{api_key_id}（有 Key ID 时远程失效）
zhiwu agent list	cli.agent_list	GET /agent
zhiwu agent show <slug>	cli.agent_show	GET /agent/{slug}
zhiwu agent eval	无（不做能力校验）	POST /agent-invocation/eval/runs（单接口阻塞等待，不走 SSE）
zhiwu kb upload <path>	cli.kb_upload	GET /knowledge/files/supported-types · GET /knowledge/databases · POST /knowledge/files/upload · POST /knowledge/databases/{kb_id}/documents/exists · POST /knowledge/databases/{kb_id}/documents/add
zhiwu kb list	cli.kb_list	GET /knowledge/databases/external
zhiwu kb files	cli.kb_files	GET /knowledge/databases/external/{kb_id}/files
zhiwu kb query	cli.kb_query	POST /knowledge/databases/external/{kb_id}/retrieve
zhiwu kb open	cli.kb_open	GET /knowledge/databases/external/{kb_id}/files/{file_id}/open
zhiwu kb find	cli.kb_find	POST /knowledge/databases/external/{kb_id}/files/{file_id}/find
zhiwu chat	仅依赖登录（无标志校验）	POST /agent-invocation/channel/messages · GET /agent/runs/{run_id}/events（本机随机端口临时 Web Chat，读 SSE）

映射表核对自 docs/14-cli.md §3，命令与参数另见 zhiwu-cli/README.md（remote add/use/list、login --no-open、kb upload --include-ext 等）。

两条已核对的坑。其一：discovery 里的 min_cli_version 与 remote_config 两个标志声明了但 CLI 不消费——版本比较只用顶层 version 与自带 MIN_SERVER_VERSION（discovery.py#L8、L34-L36），remote_config 全仓无读取点。其二：agent eval 的客户端超时（--timeout-seconds 默认 900s，httpx 侧）与服务端等待上限（继承 SSE_MAX_CONNECTION_MINUTES 默认 30 分钟，超时返 504）是两个独立时钟——长任务会先看到 CLI 本地超时，而 Run 仍在后台继续，评测超时不等于 Run 失败（docs/14-cli.md §4）。

Internal

沙箱 Provisioner 内部 API

docker/sandbox_provisioner/app.py 提供的独立 FastAPI 服务，默认端口 8002。这是后端与 Provisioner 之间的内部接口，不面向终端用户，不要暴露到公网。

鉴权：除 GET /health 外全部端点挂 require_provisioner_auth 依赖；token 来自环境变量 SANDBOX_PROVISIONER_TOKEN，启动时硬校验至少 32 字符（app.py#L400-L403）。

方法	路径	用途
GET	/health	探活：backend 类型、空闲回收参数、tracked_sandboxes（唯一免鉴权端点，`app.py#L2179`）
POST	/api/sandboxes	创建沙箱（含容器复用发现；quiesce 期间返 503，`app.py#L2196`）
GET	/api/sandboxes	列举全部沙箱记录（`app.py#L2288`）
GET	/api/sandboxes/{sandbox_id}	发现并返回单个沙箱状态，顺带 touch（`app.py#L2238`）
DELETE	/api/sandboxes/{sandbox_id}	删除沙箱；`expected_generation` 不匹配返 409（`app.py#L2406`）
POST	/api/sandboxes/{sandbox_id}/touch	保活：刷新空闲回收计时（`app.py#L2264`）
POST	/api/sandboxes/quiesce	静默：禁止新建、并行删除全部沙箱并等待 inventory 归零；timeout 1–900s，超时返 504（`app.py#L2304`）
ALL	/api/sandboxes/{sandbox_id}/proxy/{path}	反代到沙箱容器 :8080，GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS 七种方法（`app.py#L2427`）
ALL	/api/sandboxes/{sandbox_id}/proxy	同上，无 path 变体（`app.py#L2432`）

端点清单逐一 grep 自 docker/sandbox_provisioner/app.py 的路由装饰器；三个 backend（docker / kubernetes / memory）共用这组接口，创建/删除冲突时另可见 400 / 502 / 503。