Agent/.refactor-knowledge.md

知识管理系统重构追踪

目标

将知识管理系统重构为统一的 KnowHub Server 架构。

主要变更

1. 工具命名规范

• search_knowledge → knowledge_search
• save_knowledge → knowledge_save
• update_knowledge → knowledge_update
• batch_update_knowledge → knowledge_batch_update
• list_knowledge → knowledge_list
• slim_knowledge → knowledge_slim
• get_experience → 保持不变（兼容接口）

2. 数据结构调整

• trace_id → message_id
• trace 对象 → source 对象
• 更新所有相关的数据结构

3. 架构调整

• 将核心逻辑从 agent/tools/builtin/knowledge.py 迁移到 knowhub/server.py
• Agent 工具改为 API 调用封装
• 实现 KnowHub Server 的 API 端点

4. 知识注入位置调整

• 从 runner.py 移除知识注入逻辑
• 在 goal_tool.py 的 focus_goal 中实现自动注入
• 移除 runner 中的研究流程相关代码

实施步骤

Phase 1: 准备工作

• 查看当前实现状态
• 备份关键文件
• 确定迁移策略

Phase 2: KnowHub Server 实现

• 实现知识管理 API 端点
• 实现两阶段检索逻辑
• 实现知识进化逻辑
• 实现知识瘦身逻辑

Phase 3: Agent 工具重构

• 重命名工具
• 改为 API 调用封装
• 更新数据结构

Phase 4: 知识注入重构

• 在 goal_tool.py 中实现自动注入
• 从 runner.py 移除相关逻辑
• 更新 system prompt

Phase 5: 测试和验证

• 测试工具调用
• 测试知识注入
• 测试 API 端点

当前状态

现有实现

• agent/tools/builtin/knowledge.py: 1183 行，完整的本地实现

  • 包含两阶段检索逻辑
  • 包含知识进化逻辑
  • 包含知识瘦身逻辑
  • 直接操作 .cache/knowledge_atoms/ 目录

• knowhub/server.py: 359 行，只有 experiences API

  • 缺少 knowledge 相关的 API 端点
  • 缺少 knowledge 表结构

实施策略

采用渐进式迁移：

1. 先在 KnowHub Server 添加 knowledge API 端点
2. 将核心逻辑从 knowledge.py 迁移到 server.py
3. 重构 Agent 工具为 API 调用
4. 调整知识注入位置
5. 清理 runner 中的旧逻辑

详细步骤

Step 1: KnowHub Server - 添加 knowledge 表和基础 API

• 添加 knowledge 表结构
• 实现 POST /api/knowledge (保存知识)
• 实现 GET /api/knowledge (列出知识)
• 实现 GET /api/knowledge/{id} (获取单条知识)

Step 2: KnowHub Server - 实现检索逻辑

• 实现两阶段检索逻辑
  • 语义路由（LLM 筛选）
  • 质量精排（评分过滤）
• 实现 GET /api/knowledge/search

Step 3: KnowHub Server - 实现更新和进化

• 实现 PUT /api/knowledge/{id} (更新知识)
• 实现知识进化逻辑（LLM 重写）
• 实现 POST /api/knowledge/batch_update

Step 4: KnowHub Server - 实现瘦身

• 实现 POST /api/knowledge/slim

Step 5: Agent 工具重构

• 重命名工具（xxx_knowledge → knowledge_xxx）
• 改为 HTTP API 调用
• 更新数据结构（trace_id → message_id）
• 备份旧文件到 knowledge.py.backup

Step 6: 知识注入重构

• 在 goal_tool.py 实现自动注入（focus 时自动调用 knowledge_search）
• 从 runner.py 移除知识注入逻辑
  • 更新导入：knowledge_save, knowledge_batch_update
  • 更新 BUILTIN_TOOLS 中的工具名称
  • 更新所有工具调用为新名称
  • 修复 agent/tools/builtin/init.py 的导入
  • 验证导入成功
  • 移除 _research_states 相关代码（保留，用于研究流程）
  • 移除 _init_research_flow 函数（保留，用于研究流程）
  • 移除 _get_research_state 函数（保留，用于研究流程）
  • 移除 _update_research_stage 函数（保留，用于研究流程）
  • 移除 _build_research_guide 函数（保留，用于研究流程）
  • 移除 _build_research_decision_guide 函数（保留，用于研究流程）
  • 移除 _handle_research_flow_transition 函数（保留，用于研究流程）
  • 移除 enable_research_flow 配置项（保留，用于研究流程）
  • 移除经验检索注入逻辑（已注释，1064-1105行）

Step 7: 测试和清理

• 启动 KnowHub Server
• 测试 knowledge_save 工具
• 测试 knowledge_search 工具
• 测试 goal focus 自动注入
• 测试完整流程（保存→检索→注入）
• 添加 KNOWHUB_API 到 .env
• 清理注释代码（可选）
• 更新 .gitignore（排除 .cache/knowledge_atoms/）

完成状态

已完成

• ✅ KnowHub Server 完整实现（知识表、API 端点）
• ✅ 两阶段检索逻辑（语义路由 + 质量精排）
• ✅ 知识进化和瘦身功能
• ✅ Agent 工具重构为 API 封装（1183 → 398 行）
• ✅ 工具重命名（knowledge_xxx 前缀）
• ✅ 数据结构调整（trace_id → message_id）
• ✅ goal_tool.py 自动知识注入
• ✅ runner.py 导入和工具名称更新
• ✅ 模块导入验证通过

待测试

• 端到端知识管理流程
• KnowHub Server API 调用
• 自动知识注入效果

备注

• 研究流程相关代码保留（_research_states, _init_research_flow 等），因为它们用于显式的调研决策流程
• 知识注入已从研究流程中分离，现在是 goal focus 时的自动行为
• 旧的经验检索逻辑已注释（1064-1105 行）