api.md 6.0 KB
REST API 参考
文档维护规范
- 先改文档，再动代码
- 文档分层，链接代码 — 格式：
module/file.py:function_name - 简洁快照，日志分离 — 决策依据记录在
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/knowledge/ask — 智能知识查询
同步阻塞。向量检索 + 结果整合，返回 response + source_ids + sources。
运行 Librarian Agent 检索 + 整合。详见 librarian-agent.md。
请求体：query（必填）, trace_id, top_k（默认5）
POST /api/knowledge/upload — 异步知识上传
校验格式后写入 buffer 目录，立即返回 202。Librarian Agent 异步处理图谱编排和去重。
请求体：data（{knowledge, resources, tools}）, trace_id, finalize