KnowHub API 参考

KnowHub 是一个 FastAPI 服务，提供知识图谱的存储、检索和管理能力。基础地址由环境变量 KNOWHUB_API 控制，默认 http://localhost:8000。

FastAPI 自动生成的交互式文档：{KNOWHUB_API}/docs

数据模型

Knowledge（知识）

字段	类型	说明
`id`	string	格式 `knowledge-{date}-{hash}`，自动生成
`task`	string	任务描述（在什么情景下要完成什么目标）
`content`	string	核心内容
`types`	string[]	类型标签：`tool` / `strategy` / `case` / `experience`
`tags`	object	业务标签，如 `{"project": "foo", "domain": "ai"}`
`scopes`	string[]	可见范围，默认 `["org:cybertogether"]`
`owner`	string	所有者，默认 `agent:{agent_id}`
`source`	object	`{name, category, urls, agent_id, submitted_by, timestamp}`
`eval`	object	`{score(1-5), helpful, harmful, confidence}`
`capability_ids`	string[]	关联的能力 ID
`tool_ids`	string[]	关联的工具 ID
`resource_ids`	string[]	关联的资源 ID
`status`	string	`pending` / `processing` / `dedup_passed` / `analyzing` / `approved` / `checked` / `rejected`

Tool（工具）

字段	类型	说明
`id`	string	格式 `tools/{category}/{name}`，调用方指定
`name`	string	工具名称
`version`	string	版本号（可选）
`introduction`	string	简介
`tutorial`	string	使用教程
`input`	object/string	输入格式描述
`output`	object/string	输出格式描述
`status`	string	默认 `未接入`
`capability_ids`	string[]	关联的能力 ID
`knowledge_ids`	string[]	关联的知识 ID
`provider_ids`	string[]	关联的提供方 ID

Capability（原子能力）

字段	类型	说明
`id`	string	格式 `CAP-XXX`，调用方指定
`name`	string	能力名称
`criterion`	string	判断标准（何时认为该能力被满足）
`description`	string	详细描述
`requirement_ids`	string[]	关联的需求 ID
`tool_ids`	string[]	实现该能力的工具 ID
`implements`	object	`{tool_id: description}` 工具实现描述
`knowledge_ids`	string[]	关联的知识 ID

Requirement（需求）

字段	类型	说明
`id`	string	格式 `REQ_XXX`，调用方指定
`description`	string	需求描述
`capability_ids`	string[]	满足该需求的能力 ID
`knowledge_ids`	string[]	关联的知识 ID
`source_nodes`	object[]	分类树节点 `[{id, score}]`
`status`	string	默认 `未满足`
`match_result`	string	匹配结果说明

Resource（资源）

字段	类型	说明
`id`	string	路径格式，如 `docs/foo/bar`
`title`	string	标题
`body`	string	正文内容
`secure_body`	string	加密内容（AES256-GCM）
`content_type`	string	默认 `text`
`metadata`	object	自定义元数据

Knowledge API

智能查询（Librarian Agent）

`POST /api/knowledge/ask`

同步阻塞。触发 Librarian Agent 跨表检索 + LLM 整合，返回带引用的回答。同一 trace_id 的多次调用复用同一个 Librarian trace，积累上下文。

// 请求
{
  "query": "有没有工具能做角色一致性生成？",
  "trace_id": "trace-abc123"
}

// 响应
{
  "response": "根据知识库，ControlNet 可以...",
  "source_ids": ["knowledge-20260101-abcd"],
  "sources": []
}

`POST /api/knowledge/upload` → 202

异步。校验后立即返回，后台 Librarian Agent 处理去重、关联、写草稿池。

// 请求
{
  "data": {
    "knowledge": [...],
    "tools": [...],
    "resources": [...]
  },
  "trace_id": "trace-abc123",
  "finalize": false
}

// 响应 202
{
  "message": "已接收 知识: 2 个，Librarian Agent 后台处理中",
  "buffer_file": ".cache/.knowledge/buffer/upload_20260101_120000.json"
}

`GET /api/knowledge/upload/pending`

列出所有未处理或失败的 upload 任务。

`POST /api/knowledge/upload/retry`

重跑所有 status=failed 的 upload 任务。

向量检索

`GET /api/knowledge/search`

向量召回 + LLM 精排。

参数	类型	默认	说明
`q`	string	必填	查询文本
`top_k`	int	5	返回条数（1-20）
`min_score`	int	3	最低评分过滤（1-5）
`types`	string	-	逗号分隔，如 `tool,case`
`owner`	string	-	逗号分隔，过滤 owner

// 响应
{
  "results": [{"id": "...", "task": "...", "content": "...", "score": 0.92, ...}],
  "count": 3
}

CRUD

`POST /api/knowledge` → 201

创建知识，进入 pending 状态，自动触发去重流水线。

{
  "task": "使用 ControlNet 进行姿态控制",
  "content": "...",
  "types": ["tool"],
  "tags": {"project": "image_gen"},
  "source": {"agent_id": "research_agent", "category": "research"},
  "eval": {"score": 4}
}
// 响应: {"status": "pending", "knowledge_id": "knowledge-20260101-abcd"}

`GET /api/knowledge`

列出知识，支持分页和过滤。

参数	说明
`page` / `page_size`	分页，默认 1/20
`types`	逗号分隔类型过滤
`scopes`	逗号分隔范围过滤
`owner`	owner 过滤
`tags`	JSON 字符串，如 `{"project":"foo"}`
`status`	状态过滤

`GET /api/knowledge/{knowledge_id}`

获取单条知识详情。

`GET /api/knowledge/status/{knowledge_id}`

查询知识处理状态（pending / approved 等）。

`PUT /api/knowledge/{knowledge_id}`

更新知识评估，支持知识进化（LLM 重写 content）。

{
  "update_score": 5,
  "add_helpful_case": {"context": "...", "result": "success"},
  "add_harmful_case": null,
  "evolve_feedback": "内容需要补充 batch 处理的情况"
}

`PATCH /api/knowledge/{knowledge_id}`

直接编辑字段（task、content、types、tags、scopes、owner、capability_ids、tool_ids）。

`DELETE /api/knowledge/{knowledge_id}`

删除单条知识（级联清理关联表）。

`POST /api/knowledge/batch_delete`

批量删除。请求体为 ["knowledge-xxx", "knowledge-yyy"]。

审核与验证

`POST /api/knowledge/{knowledge_id}/verify`

// approve：approved ↔ checked 切换；reject：→ rejected
{"action": "approve", "verified_by": "howard"}

`POST /api/knowledge/batch_verify`

{"knowledge_ids": ["knowledge-xxx"], "action": "approve", "verified_by": "howard"}

运维工具

`GET /api/knowledge/pending`

查询处理队列（pending / processing / dedup_passed / analyzing）。

`POST /api/knowledge/process`

手动触发去重处理。force=true 时先回滚所有超时锁。

`GET /api/knowledge/meta/tags`

获取所有已使用的 tag keys。

`POST /api/knowledge/slim`

知识库瘦身：LLM 分析全库，合并语义相似条目。可选参数 model，默认 google/gemini-2.5-flash-lite。

`POST /api/knowledge/batch_update`

批量反馈知识有效性。

`POST /api/extract`

从消息历史中 LLM 提取知识并入库。

{
  "messages": [{"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}],
  "agent_id": "research_agent",
  "submitted_by": "howard@example.com",
  "session_key": ""
}

Tool API

`POST /api/tool` → 201

创建或更新工具（id 相同则覆盖，同时全量替换关联表）。

{
  "id": "tools/image/controlnet",
  "name": "ControlNet",
  "introduction": "基于条件控制的图像生成工具",
  "tutorial": "...",
  "status": "已接入",
  "capability_ids": ["CAP-001"],
  "knowledge_ids": ["knowledge-20260101-abcd"]
}

`GET /api/tool`

列出工具。参数：status、limit（默认100）、offset。

`GET /api/tool/search?q=...&top_k=5`

向量检索工具。

`GET /api/tool/{tool_id}`

获取单个工具详情（含关联的 capability_ids、knowledge_ids）。

`PATCH /api/tool/{tool_id}`

部分更新工具字段。

`DELETE /api/tool/{tool_id}`

删除工具（级联清理关联表）。

Capability API

`POST /api/capability` → 201

创建或更新原子能力。

{
  "id": "CAP-001",
  "name": "人物姿态控制生成",
  "criterion": "能根据骨骼图生成指定姿态的人物图像",
  "description": "...",
  "tool_ids": ["tools/image/controlnet"],
  "implements": {"tools/image/controlnet": "使用 openpose 模型控制姿态"}
}

`GET /api/capability`

列出所有能力。参数：limit、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` → 201

创建或更新需求。

{
  "id": "REQ_001",
  "description": "需要能生成角色一致的多视角图像",
  "capability_ids": ["CAP-001"],
  "source_nodes": [{"id": "image_generation", "score": 0.9}],
  "status": "已满足"
}

`GET /api/requirement`

列出需求。参数：status、limit、offset。

`GET /api/requirement/search?q=...&top_k=5`

向量检索需求。

`GET /api/requirement/{req_id}`

获取单个需求详情。

`PATCH /api/requirement/{req_id}`

部分更新需求字段。

`DELETE /api/requirement/{req_id}`

删除需求（级联清理关联表）。

Resource API

Resource 存储原始资料文档，通过 knowledge_resource 关联表与 Knowledge 关联。

`POST /api/resource` → 201

创建或更新资源。

`GET /api/resource`

列出资源（树形结构）。

`GET /api/resource/{resource_id}`

获取单个资源（含 toc、children、prev/next 导航）。

`PATCH /api/resource/{resource_id}`

部分更新资源字段。

`DELETE /api/resource/{resource_id}`

删除资源。

关联表说明

所有实体间的关系通过 junction table 维护，写入时全量替换（DELETE + INSERT）：

关联表	连接
`capability_tool`	Capability ↔ Tool
`capability_knowledge`	Capability ↔ Knowledge
`requirement_capability`	Requirement ↔ Capability
`requirement_knowledge`	Requirement ↔ Knowledge
`tool_knowledge`	Tool ↔ Knowledge
`tool_provider`	Tool ↔ Provider
`knowledge_resource`	Knowledge ↔ Resource
`knowledge_relation`	Knowledge → Knowledge（supplement/duplicate）

查询任意实体时，关联 ID 通过子查询自动聚合返回（capability_ids、tool_ids 等字段）。

knowledge-management.md 11 KB История Исходник

KnowHub API 参考

数据模型

Knowledge（知识）

Tool（工具）

Capability（原子能力）

Requirement（需求）

Resource（资源）

Knowledge API

智能查询（Librarian Agent）

POST /api/knowledge/ask

POST /api/knowledge/upload → 202

GET /api/knowledge/upload/pending

POST /api/knowledge/upload/retry

向量检索

GET /api/knowledge/search

CRUD

POST /api/knowledge → 201

GET /api/knowledge

GET /api/knowledge/{knowledge_id}

GET /api/knowledge/status/{knowledge_id}

PUT /api/knowledge/{knowledge_id}

PATCH /api/knowledge/{knowledge_id}

DELETE /api/knowledge/{knowledge_id}

POST /api/knowledge/batch_delete

审核与验证

POST /api/knowledge/{knowledge_id}/verify

POST /api/knowledge/batch_verify

运维工具

GET /api/knowledge/pending

POST /api/knowledge/process

GET /api/knowledge/meta/tags

POST /api/knowledge/slim

POST /api/knowledge/batch_update

POST /api/extract

Tool API

POST /api/tool → 201

GET /api/tool

GET /api/tool/search?q=...&top_k=5

GET /api/tool/{tool_id}

PATCH /api/tool/{tool_id}

DELETE /api/tool/{tool_id}