工具表（Resource）与知识库对接文档

文档维护规范

先改文档，再动代码 - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现；除非改动较小、不被文档涵盖
文档分层，链接代码 - 重要或复杂设计可以另有详细文档；关键实现需标注代码文件路径；格式：module/file.py:function_name
简洁快照，日志分离 - 只记录最重要的、与代码准确对应的或者明确的已完成的设计的信息，避免推测、建议、决策历史、修改日志、大量代码；决策依据或修改日志若有必要，可在 knowhub/docs/decisions.md 另行记录

一、核心概念

知识库（KnowHub）中的工具表存储在 Resource 模块里，与 Knowledge（知识条目）通过双向索引关联。

模块	存储后端	主键格式
Resource（工具表）	SQLite	`tools/{category}/{slug}`
Knowledge（知识）	Milvus（向量库）	`knowledge-{日期}-{随机}`

二、Resource 数据结构

工具表字段

{
  "id": "tools/plugin/ip_adapter",
  "title": "IP-Adapter",
  "body": "",
  "content_type": "text",
  "metadata": {
    "category": "plugin",
    "tool_slug": "ip_adapter",
    "status": "未接入",
    "version": "v1.0",
    "description": "22M参数的轻量适配器，通过CLIP ViT-H图像编码器实现图像提示",
    "usage": "scale=1.0用于纯图像提示，scale=0.5用于多模态（图像+文本）",
    "scenarios": ["人物一致性控制", "风格迁移", "图像引导生成"],
    "input": "参考图像 + 文本提示（可选）",
    "output": "生成图像",
    "source": "https://github.com/tencent-ailab/IP-Adapter",
    "knowledge_ids": ["knowledge-20260309-215835-a699"],
    "migrated_from": "knowhub_old"
  },
  "submitted_by": "migrate_script"
}

metadata 字段说明

字段	类型	必填	说明
`category`	string	✅	分类：`image_gen` / `image_process` / `model` / `plugin` / `workflow` / `other`
`tool_slug`	string	✅	小写英文短名，空格换下划线，如 `controlnet`、`ip_adapter`
`status`	string	✅	接入状态：`未接入` / `已接入` / `测试中`
`version`	string\|null	—	版本号
`description`	string\|null	—	一句话功能介绍
`usage`	string\|null	—	核心用法说明
`scenarios`	array	—	应用场景列表
`input`	string\|null	—	输入类型描述
`output`	string\|null	—	输出类型描述
`source`	string\|null	—	来源/文档链接
`knowledge_ids`	array	—	关联的知识 ID 列表（双向索引）

ID 命名规则

tools/{category}/{slug}

示例：
tools/plugin/ip_adapter
tools/plugin/controlnet
tools/image_gen/midjourney
tools/model/sdxl

三、双向索引机制

Resource（工具）                     Knowledge（知识）
┌─────────────────────────┐         ┌──────────────────────────────┐
│ id: tools/plugin/ip_adapter │◄────►│ id: knowledge-20260309-xxx   │
│ metadata.knowledge_ids:  │         │ resource_ids:                │
│   ["knowledge-xxx"]      │         │   ["tools/plugin/ip_adapter"] │
└─────────────────────────┘         │ tags: {"tool": true}         │
                                     └──────────────────────────────┘

Resource → Knowledge：metadata.knowledge_ids 存储关联知识的 ID 列表
Knowledge → Resource：resource_ids 存储关联工具的 ID 列表，同时打 tags.tool = true 标记

重要：双向索引是手动维护的

目前没有任何自动同步机制，两侧的索引相互独立存储，需要调用方自己负责保持一致。

两侧的写入时机：

方向	存在哪	写入时机
Resource → Knowledge	SQLite `resources.metadata.knowledge_ids`	创建/更新 Resource 时手动 PATCH
Knowledge → Resource	Milvus `resource_ids` 字段	Knowledge 创建时传入，创建后无法通过 API 修改

Knowledge 的 resource_ids 字段目前不在 PATCH 接口的支持范围内，一旦 Knowledge 创建，只能通过删除重建来更改其关联的工具。

四、API 接口

服务地址由环境变量 KNOWHUB_API 指定（如 http://localhost:9999）。

4.1 工具表（Resource）

创建工具

POST /api/resource
Content-Type: application/json

{
  "id": "tools/plugin/controlnet",
  "title": "ControlNet",
  "body": "",
  "content_type": "text",
  "metadata": {
    "category": "plugin",
    "tool_slug": "controlnet",
    "status": "已接入",
    "description": "...",
    "usage": "...",
    "scenarios": [...],
    "knowledge_ids": []
  },
  "submitted_by": "your_name"
}

更新工具（局部更新，推荐）

PATCH /api/resource/tools/plugin/controlnet
Content-Type: application/json

{
  "metadata": {
    "status": "已接入",
    "knowledge_ids": ["knowledge-xxx", "knowledge-yyy"]
  }
}

⚠️ PATCH metadata 会整体替换 metadata 字段，需带上所有已有字段。

获取工具详情

GET /api/resource/tools/plugin/controlnet

返回额外的导航字段：toc（根节点）、children（子节点）、prev/next（同级导航）。

列出所有工具

GET /api/resource?limit=1000

过滤出工具（客户端过滤）：

const tools = results.filter(r => r.id.startsWith("tools/"));

删除工具

DELETE /api/resource/tools/plugin/controlnet

4.2 知识（Knowledge）

搜索工具相关知识（语义搜索）

GET /api/knowledge/search?q=IP-Adapter人物一致性&top_k=5&min_score=3

列出所有工具相关知识

GET /api/knowledge?tags=tool&status=approved,checked&page_size=200

获取单条知识

GET /api/knowledge/knowledge-20260309-215835-a699

批量删除知识

POST /api/knowledge/batch_delete
Content-Type: application/json

["knowledge-xxx", "knowledge-yyy"]

五、典型操作示例（Python）

新增一个工具并关联知识

import httpx

KNOWHUB_API = "http://your-server:9999"

# 1. 创建工具
tool = {
    "id": "tools/plugin/controlnet",
    "title": "ControlNet",
    "body": "",
    "content_type": "text",
    "metadata": {
        "category": "plugin",
        "tool_slug": "controlnet",
        "status": "已接入",
        "version": "v1.1",
        "description": "基于条件图像控制SD生成的插件",
        "usage": "提供边缘图/骨骼图/深度图等条件，精确控制生成结果",
        "scenarios": ["姿势控制", "边缘控制", "深度控制"],
        "input": "条件图像（canny/pose/depth等）+ 文本提示",
        "output": "生成图像",
        "source": "https://github.com/lllyasviel/ControlNet",
        "knowledge_ids": []
    },
    "submitted_by": "your_name"
}

resp = httpx.post(f"{KNOWHUB_API}/api/resource", json=tool)
print(resp.json())  # {"status": "ok", "id": "tools/plugin/controlnet"}

# 2. 回填知识关联（PATCH 更新 knowledge_ids）
patch = {
    "metadata": {
        **tool["metadata"],  # 保留所有已有字段
        "knowledge_ids": ["knowledge-20260309-215835-a699"]
    }
}

resp = httpx.patch(f"{KNOWHUB_API}/api/resource/tools/plugin/controlnet", json=patch)
print(resp.json())  # {"status": "ok"}

更新工具接入状态

# 先获取当前 metadata，再更新
resp = httpx.get(f"{KNOWHUB_API}/api/resource/tools/plugin/controlnet")
tool = resp.json()
meta = tool["metadata"]

meta["status"] = "已接入"

httpx.patch(
    f"{KNOWHUB_API}/api/resource/tools/plugin/controlnet",
    json={"metadata": meta}
)

六、前端查看

访问 KnowHub 管理界面，点击右上角 🔧 工具表 按钮：

按 category Tab 切换分类
左侧列表点击工具查看详情
详情页显示：基础概览 / 使用指南 / 技术规格 / 消息信源 / 关联知识（可跳转）
知识卡片底部有工具 Tag，点击可跳回工具表对应条目

七、注意事项

PATCH metadata 是整体替换：更新前先 GET 拿到当前值，合并后再 PATCH，避免覆盖已有字段（尤其是 knowledge_ids）。
Resource ID 含斜杠：URL 调用时需注意路径编码（框架已支持 {resource_id:path}，直接拼接即可，无需手动 encode）。
双向索引需手动维护：创建/删除工具时，需同步更新关联 Knowledge 的 resource_ids 字段（PATCH /api/knowledge/{id}）。
工具筛选靠客户端：GET /api/resource 返回所有 resource，需在客户端过滤 id.startsWith("tools/") 得到工具列表。

tool-table-integration.md 9.0 KB تاريخچه خام