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

重构日期

2026-03-05

核心改动

1. 数据结构调整

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

旧结构 → 新结构：

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

新数据结构示例：

{
  "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 工具以匹配新的数据结构：

# 搜索知识
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

cd knowhub
python server.py

2. 测试 CLI 工具

# 保存知识
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 代码中调用：

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"]
)

注意事项

默认值设置位置： 按照用户要求，默认 org (scopes) 和 owner 在 agent 代码中设置，不在服务器端设置。
数据库重建： 旧数据库已备份，新数据库为空。如需迁移旧数据，需要编写迁移脚本。
完全移除旧系统： 已删除所有旧的经验系统代码（experience.py, get_experience 等），不保留兼容接口。
环境变量： 确保设置 OPEN_ROUTER_API_KEY 和 KNOWHUB_API。

下一步

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

文件清单

已修改：

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 和相关代码