Agent/knowhub/docs/migration-guide.md

知识管理工具迁移指南

架构变更

旧架构（Deprecated）

Agent → knowledge_search/knowledge_save → HTTP API → KnowHub Server → Database

新架构（推荐）

Agent → ask_knowledge/upload_knowledge → IM → Knowledge Manager → Internal Tools → Database

工具对照表

旧工具	新工具	说明
knowledge_search	ask_knowledge	查询知识库（同步等待回复）
knowledge_save	upload_knowledge	上传知识（异步，支持增量+批量）
resource_save	upload_knowledge	统一通过 upload_knowledge 上传

迁移步骤

1. 启用 IM 和 Knowledge Manager

# config.py
IM_ENABLED = True
KNOWLEDGE_MANAGER_ENABLED = True

2. 更新 Prompt

旧写法：

knowledge_search("查询 ControlNet")
knowledge_save(task="...", content="...", types=["tool"])

新写法：

ask_knowledge("查询 ControlNet 相关信息")
upload_knowledge({
  "tools": [...],
  "resources": [...],
  "knowledge": [...]
})

3. 增量上传模式

新架构支持边搜边传：

# 第一批数据
upload_knowledge({"tools": [...]})

# 第二批数据
upload_knowledge({"resources": [...]})

# 最终提交（触发入库）
upload_knowledge({"knowledge": [...]}, finalize=True)

新架构优势

1. 自动去重：Knowledge Manager 在缓冲区中自动去重
2. 批量提交：减少数据库操作，提高性能
3. 并发控制：通过 IM 消息队列避免并发冲突
4. 状态管理：Knowledge Manager 维护 IDLE/WORKING 状态
5. 后台处理：异步深度去重和整合

向后兼容

旧工具仍然可用，但会输出 deprecation 警告：

WARNING: knowledge_search is deprecated. Use ask_knowledge instead.

建议尽快迁移到新架构。

内部工具封装

直接数据库访问的工具已移至 knowhub/internal_tools/，仅 Knowledge Manager 内部使用：

• knowledge_search (内部)
• knowledge_save (内部)
• resource_save (内部)

普通 Agent 不应直接调用这些工具。