# KnowHub Internal Tools

这些工具只能在 Knowledge Manager 内部使用，不暴露给普通 Agent。

## 缓存管理工具

Knowledge Manager 使用本地缓存机制来处理调研数据，流程如下：

### 1. 接收数据 → 缓存到本地

调研 Agent 通过 IM 发送调研结果时，KM 使用 `cache_research_data` 缓存到本地：

```python
await cache_research_data(
    data={
        "tools": [...],
        "resources": [...],
        "knowledge": [...]
    },
    source="agent_research"
)
```

**存储位置**：`.cache/.knowledge/buffer/{source}_{timestamp}.json`

### 2. 整理数据 → 去重合并

当需要整理缓存数据时，使用 `organize_cached_data`：

```python
await organize_cached_data(merge=True)
```

**功能**：
- 读取所有 buffer 中的文件
- 按名称/标题去重
- 合并到一个文件
- 保存到 `.cache/.knowledge/organized/organized_{timestamp}.json`
- 清空 buffer（如果 `merge=True`）

### 3. 提交到数据库（可选）

只有在明确要求时，才使用 `commit_to_database` 提交到数据库：

```python
await commit_to_database()
```

**功能**：
- 读取最新的 organized 文件
- 调用 `resource_save` 和 `knowledge_save` 入库
- 返回提交统计

### 4. 查看缓存状态

使用 `list_cache_status` 查看当前缓存情况：

```python
await list_cache_status()
```

## 工作流示例

### 场景 1：只缓存和整理，不入库

```
调研 Agent: 发送调研结果
KM: cache_research_data() → 缓存到 buffer
KM: 回复"已缓存"

用户: 整理一下
KM: organize_cached_data() → 整理到 organized
KM: 回复"已整理，去重 X 个"
```

### 场景 2：缓存、整理、入库

```
调研 Agent: 发送调研结果
KM: cache_research_data() → 缓存到 buffer
KM: 回复"已缓存"

用户: 提交到数据库
KM: organize_cached_data() → 整理
KM: commit_to_database() → 入库
KM: 回复"已提交到数据库"
```

## 目录结构

```
.cache/.knowledge/
├── buffer/              # 原始缓存（调研 Agent 提交的数据）
│   ├── agent_research_20260402_120000.json
│   └── agent_research_20260402_130000.json
└── organized/           # 整理后的数据（去重合并）
    └── organized_20260402_140000.json
```

## 设计原则

1. **默认缓存**：收到数据时先缓存，不直接入库
2. **按需入库**：只有明确要求时才提交到数据库
3. **去重优先**：整理时必须去重
4. **快速响应**：缓存操作很快，不阻塞调研 Agent