Agent/knowhub/docs/api.md

REST API 参考

文档维护规范

1. 先改文档，再动代码
2. 文档分层，链接代码 — 格式：module/file.py:function_name
3. 简洁快照，日志分离 — 决策依据记录在 knowhub/docs/decisions.md

---

实现：knowhub/server.py

Knowledge API

GET /api/knowledge/search — 向量搜索知识

参数：q（必填）, top_k（默认5, 1-20）, min_score（默认3, 1-5）, types（逗号分隔, AND）, owner（逗号分隔, OR）

只返回 status=approved/checked 的知识。向量召回 3×top_k 候选，按余弦距离排序取 top_k。当前跳过 LLM 精排。

响应：{"results": [...], "count": int, "reranked": false}

POST /api/knowledge — 创建知识

请求体：task（必填）, content（必填）, types, tags, scopes, owner, message_id, source, eval, capability_ids, tool_ids

自动生成 task_embedding + content_embedding。初始 status=pending，异步触发去重处理（详见 processing-pipeline.md）。

GET /api/knowledge — 列表（分页+过滤）

参数：page, page_size（默认20）, types, scopes, owner, tags, status（默认 approved,checked）

GET /api/knowledge/{knowledge_id} — 获取单条

PUT /api/knowledge/{knowledge_id} — 更新（含知识进化）

请求体：add_helpful_case, add_harmful_case, update_score, evolve_feedback

evolve_feedback 非空时触发 LLM 重写知识内容并更新 task_embedding。

PATCH /api/knowledge/{knowledge_id} — 直接编辑字段

请求体：task, content, types, tags, scopes, owner, capability_ids, tool_ids（均可选）

修改 task/content 时自动更新对应 embedding。

DELETE /api/knowledge/{knowledge_id} — 删除

POST /api/knowledge/batch_delete — 批量删除

请求体：List[str]（knowledge_ids）

POST /api/knowledge/{knowledge_id}/verify — 验证

请求体：action（"approve"/"reject"）, verified_by

approve 在 approved ↔ checked 之间切换。reject 设为 rejected。

POST /api/knowledge/batch_verify — 批量验证

请求体：knowledge_ids, action（必须 "approve"）, verified_by

POST /api/knowledge/batch_update — 批量反馈

请求体：feedback_list [{knowledge_id, is_effective, feedback?}]

is_effective=true + feedback 时触发并发 LLM 知识进化。

POST /api/knowledge/slim — 知识库瘦身

参数：model（默认 gemini-2.5-flash-lite）

LLM 识别可合并项 → 合并 → 重建 embedding。

POST /api/extract — 从对话提取知识

请求体：messages（[{role, content}]）, agent_id, submitted_by（必填）, session_key

LLM 提取结构化知识 → 批量生成 embedding → 入库（pending） → 触发去重。

GET /api/knowledge/pending — 处理队列

返回 status 为 pending/processing/dedup_passed/analyzing 的知识。

POST /api/knowledge/process — 手动触发处理

参数：force（重置卡住的 processing/analyzing 状态）

GET /api/knowledge/status/{knowledge_id} — 查看处理状态

GET /api/knowledge/meta/tags — 获取所有标签

---

Resource API

POST /api/resource — 创建/更新资源

请求体：id（必填, 路径格式）, title, body, secure_body, content_type, metadata, sort_order, submitted_by

secure_body 在有组织密钥时自动加密（AES-256-GCM）。

GET /api/resource/{resource_id} — 获取资源（含导航）

响应包含：toc（根节点）, children（子节点）, prev/next（同级前后节点）。

PATCH /api/resource/{resource_id} — 更新字段

GET /api/resource — 列表

参数：content_type, limit（默认100）

DELETE /api/resource/{resource_id} — 删除

---

Tool API

POST /api/tool — 创建/更新工具

请求体：id（必填）, name, version, introduction, tutorial, input, output, status, capability_ids, knowledge_ids

自动生成 embedding（name + introduction）。

GET /api/tool — 列表

参数：status, limit（默认100）, offset

GET /api/tool/search — 向量搜索工具

参数：q（必填）, top_k（默认5）, status

GET /api/tool/{tool_id} — 获取单个

PATCH /api/tool/{tool_id} — 更新字段

DELETE /api/tool/{tool_id} — 删除

---

Capability API

POST /api/capability — 创建/更新原子能力

请求体：id（必填）, name, criterion, description, requirement_ids, implements, tool_ids, knowledge_ids

自动生成 embedding（name + description）。

GET /api/capability — 列表

参数：limit（默认100）, offset

GET /api/capability/search — 向量搜索能力

参数：q（必填）, top_k（默认5）

GET /api/capability/{cap_id} — 获取单个

PATCH /api/capability/{cap_id} — 更新字段

DELETE /api/capability/{cap_id} — 删除

---

Requirement API

POST /api/requirement — 创建/更新需求

请求体：id（必填）, description, capability_ids, source_nodes, status（默认 "未满足"）, match_result

自动生成 embedding（description）。

GET /api/requirement — 列表

参数：status, limit（默认100）, offset

GET /api/requirement/search — 向量搜索需求

参数：q（必填）, top_k（默认5）

GET /api/requirement/{req_id} — 获取单个

PATCH /api/requirement/{req_id} — 更新字段

DELETE /api/requirement/{req_id} — 删除

---

POST /api/agent — 统一远端 Agent 入口

同步阻塞。运行由 agent_type 指定的远端 Agent（如 remote_librarian、remote_research），返回标准的 Agent 结果。

请求体： | 字段 | 类型 | 说明 | |------|------|------| | agent_type | str | 必填。必须是 remote_ 前缀，如 remote_librarian、remote_research | | task | str | 必填。单任务描述（远端模式不支持 List[str] 多任务） | | messages | List | 可选。预置 OpenAI 格式消息，作为 Agent 初始上下文 | | continue_from | str | 可选。已有 sub_trace_id，传入则续跑该 trace | | skills | List[str] | 可选。调用方指定的 skill 列表；服务器按每个 agent_type 的 ALLOWED_SKILLS 过滤 |

约束：客户端传的 tool_groups / model / prompt 由服务器 preset 完全决定，客户端无法干预。skills 是例外——可被指定但受白名单约束。

响应：

{
  "sub_trace_id": "...",
  "status": "completed",
  "summary": "...",
  "stats": {"total_messages": N, "total_tokens": N, "total_cost": 0.xxx}
}

summary 是 Agent 最终产出的 message 文本——Agent 之间通过 message 通信，不定义 per-agent 的结构化字段。如果 Agent 需要返回结构化数据（引用来源、ID 列表等），由其 prompt 约定写进 message 文本（例如 JSON 代码块），调用方自行 parse。

续跑语义：服务器不维护 caller_trace_id → sub_trace_id 映射。首次调用不传 continue_from 创建新 trace；caller 自行记住返回的 sub_trace_id，下次作为 continue_from 传回。

详见 remote-agents.md。

GET /api/knowledge/upload/pending / POST /api/knowledge/upload/retry — 运维

查询与重跑历史 upload buffer 中的 pending / failed 记录。仅用于人工排查，不在主 agent 调用流中。

知识上传本身已并入 POST /api/agent，使用 agent_type="remote_librarian_ingest"；task 为 JSON 字符串（{knowledge, tools, resources}）。详见 remote-agents.md。