# 知识管理系统重构完成报告

## 重构日期
2026-03-05

## 核心改动

### 1. 数据结构调整

按照 `agent/docs/knowledge.md` 定义，完成以下字段调整：

**旧结构 → 新结构：**
- `scenario` → `task`（任务描述）
- `tags_type` → `types`（支持多选数组）
- 新增 `tags`（JSON 对象，业务标签）
- 新增 `scopes`（数组，可见范围）
- 新增 `owner`（所有者）
- `source_*` 字段 → `source`（嵌套对象）
- `eval_*` 和 `metrics_*` 字段 → `eval`（嵌套对象）
- 保留顶层 `message_id`

**新数据结构示例：**
```json
{
  "id": "knowledge-xxx",
  "message_id": "msg-xxx",
  "types": ["strategy", "tool"],
  "task": "任务描述",
  "tags": {"category": "preference"},
  "scopes": ["org:cybertogether"],
  "owner": "agent:research_agent",
  "content": "知识内容",
  "source": {
    "name": "资源名称",
    "category": "exp",
    "urls": ["https://example.com"],
    "agent_id": "research_agent",
    "submitted_by": "user@example.com",
    "timestamp": "2026-03-05T12:00:00Z"
  },
  "eval": {
    "score": 4,
    "helpful": 5,
    "harmful": 0,
    "confidence": 0.9,
    "helpful_history": [],
    "harmful_history": []
  },
  "created_at": "2026-03-05T12:00:00Z",
  "updated_at": "2026-03-05T12:00:00Z"
}
```

### 2. 数据库迁移

**文件：** `knowhub/server.py`

- 重建 knowledge 表结构
- 使用 JSON 字段存储 `types`, `tags`, `scopes`, `source`, `eval`
- 删除旧的扁平化字段（`tags_type`, `scenario`, `source_*`, `eval_*`, `metrics_*`）
- 备份旧数据库到 `knowhub.db.backup-20260305`

### 3. API 更新

**文件：** `knowhub/server.py`

所有 knowledge API 已更新：

- `POST /api/knowledge` - 保存知识（使用新结构）
- `GET /api/knowledge/search` - 搜索知识（参数 `tags_type` → `types`）
- `GET /api/knowledge` - 列出知识（参数 `tags_type` → `types`，新增 `scopes`）
- `GET /api/knowledge/{id}` - 获取知识（返回新结构）
- `PUT /api/knowledge/{id}` - 更新知识（使用嵌套 eval 结构）
- `POST /api/knowledge/batch_update` - 批量更新（使用嵌套 eval 结构）
- `POST /api/knowledge/slim` - 知识瘦身（使用新结构）

### 4. CLI 工具更新

**文件：** `knowhub/skill/cli.py`

完全重写 CLI 工具以匹配新的数据结构：

```bash
# 搜索知识
python -m knowhub.skill.cli search "查询内容" --types strategy

# 保存知识
python -m knowhub.skill.cli save \
  --task "任务描述" \
  --content "知识内容" \
  --types strategy,tool \
  --tags '{"category":"preference"}' \
  --scopes org:cybertogether

# 列出知识
python -m knowhub.skill.cli list --limit 10 --types strategy

# 更新知识
python -m knowhub.skill.cli update knowledge-xxx \
  --score 5 \
  --helpful-case "有效案例"

# 批量更新
python -m knowhub.skill.cli batch-update --file feedback.json

# 知识瘦身
python -m knowhub.skill.cli slim --model google/gemini-2.0-flash-001
```

### 5. Agent 工具更新

**文件：** `agent/tools/builtin/knowledge.py`

更新所有工具函数：

**knowledge_search:**
- 参数 `tags_type` → `types`
- 输出显示 `task` 而不是 `scenario`

**knowledge_save:**
- 参数 `scenario` → `task`
- 参数 `tags_type` → `types`
- 新增参数：`tags`, `scopes`, `owner`, `source_name`, `source_category`, `submitted_by`
- **重要：** 默认值在 agent 代码中设置（不是服务器端）：
  - `scopes` 默认 `["org:cybertogether"]`
  - `owner` 默认 `f"agent:{agent_id}"`

**knowledge_list:**
- 参数 `tags_type` → `types`
- 新增参数：`scopes`

**knowledge_slim:**
- 默认模型改为 `google/gemini-2.0-flash-001`

### 6. 清理旧代码

**已删除/备份：**
- `agent/tools/builtin/experience.py` → `experience.py.old`（旧的经验系统）
- `agent/tools/builtin/__init__.py` - 删除 `get_experience` 导入和导出
- `agent/core/runner.py` - 删除 `experiences_path` 参数和 `_load_experiences()` 方法
- `agent/core/runner.py` - 从 BUILTIN_TOOLS 列表中删除 `get_experience`

### 7. 备份文件

所有修改前的文件都已备份：
- `knowhub/server.py.old`
- `knowhub/skill/cli.py.old`
- `agent/tools/builtin/knowledge.py.old`
- `agent/tools/builtin/experience.py.old`
- `knowhub.db.backup-20260305`

## 测试建议

### 1. 启动 KnowHub Server

```bash
cd knowhub
python server.py
```

### 2. 测试 CLI 工具

```bash
# 保存知识
python -m knowhub.skill.cli save \
  --task "测试任务" \
  --content "测试内容" \
  --types strategy

# 搜索知识
python -m knowhub.skill.cli search "测试"

# 列出知识
python -m knowhub.skill.cli list
```

### 3. 测试 Agent 工具

在 agent 代码中调用：

```python
from agent.tools.builtin.knowledge import knowledge_save, knowledge_search

# 保存知识
await knowledge_save(
    task="测试任务",
    content="测试内容",
    types=["strategy"],
    agent_id="test_agent"
)

# 搜索知识
await knowledge_search(
    query="测试",
    types=["strategy"]
)
```

## 注意事项

1. **默认值设置位置：** 按照用户要求，默认 org (`scopes`) 和 owner 在 agent 代码中设置，不在服务器端设置。

2. **数据库重建：** 旧数据库已备份，新数据库为空。如需迁移旧数据，需要编写迁移脚本。

3. **完全移除旧系统：** 已删除所有旧的经验系统代码（experience.py, get_experience 等），不保留兼容接口。

4. **环境变量：** 确保设置 `OPEN_ROUTER_API_KEY` 和 `KNOWHUB_API`。

## 下一步

1. 测试所有 API 端点
2. 如需要，编写数据迁移脚本
3. 更新相关文档

## 文件清单

**已修改：**
- `knowhub/server.py` - KnowHub Server（数据库 + API）
- `knowhub/skill/cli.py` - CLI 工具
- `agent/tools/builtin/knowledge.py` - Agent 工具集成
- `agent/tools/builtin/__init__.py` - 删除旧的 experience 导入
- `agent/core/runner.py` - 删除 experiences_path 和相关代码

**已删除/备份：**
- `agent/tools/builtin/experience.py` → `experience.py.old`

**已备份：**
- `knowhub/server.py.old`
- `knowhub/skill/cli.py.old`
- `agent/tools/builtin/knowledge.py.old`
- `knowhub.db.backup-20260305`

**新增：**
- `.refactor-knowledge-complete.md` - 本文档