# 知识管理工具迁移指南

## 架构变更

### 旧架构（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

```python
# 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. 增量上传模式

新架构支持边搜边传：
```python
# 第一批数据
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 不应直接调用这些工具。