# REST API 参考

## 文档维护规范

0. **先改文档，再动代码**
1. **文档分层，链接代码** — 格式：`module/file.py:function_name`
2. **简洁快照，日志分离** — 决策依据记录在 `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, resource_ids, source, eval, support_capability, tools

自动生成 task_embedding + content_embedding。初始 status=pending，异步触发去重处理（详见 [processing-pipeline.md](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, support_capability, tools（均可选）

修改 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, capabilities, tool_knowledge, case_knowledge, process_knowledge, implemented_tool_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, requirements, implements, tools, source_knowledge

自动生成 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, atomics, 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}` — 删除

---

## 计划中的 API（设计中，未实现）

### `POST /api/knowledge/ask` — 智能知识查询

同步阻塞。KnowHub 内部启动/续跑 Librarian Agent 处理查询，返回整合回答 + source_ids。详见 [librarian-agent.md](librarian-agent.md)。

### `POST /api/knowledge/upload` — 异步知识上传

校验格式后立即返回 202，Librarian Agent 后台队列处理。详见 [librarian-agent.md](librarian-agent.md)。