# 知识管理系统重构追踪

## 目标

将知识管理系统重构为统一的 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
- [x] 添加 knowledge 表结构
- [x] 实现 POST /api/knowledge (保存知识)
- [x] 实现 GET /api/knowledge (列出知识)
- [x] 实现 GET /api/knowledge/{id} (获取单条知识)

### Step 2: KnowHub Server - 实现检索逻辑
- [x] 实现两阶段检索逻辑
  - [x] 语义路由（LLM 筛选）
  - [x] 质量精排（评分过滤）
- [x] 实现 GET /api/knowledge/search

### Step 3: KnowHub Server - 实现更新和进化
- [x] 实现 PUT /api/knowledge/{id} (更新知识)
- [x] 实现知识进化逻辑（LLM 重写）
- [x] 实现 POST /api/knowledge/batch_update

### Step 4: KnowHub Server - 实现瘦身
- [x] 实现 POST /api/knowledge/slim

### Step 5: Agent 工具重构
- [x] 重命名工具（xxx_knowledge → knowledge_xxx）
- [x] 改为 HTTP API 调用
- [x] 更新数据结构（trace_id → message_id）
- [x] 备份旧文件到 knowledge.py.backup

### Step 6: 知识注入重构
- [x] 在 goal_tool.py 实现自动注入（focus 时自动调用 knowledge_search）
- [x] 从 runner.py 移除知识注入逻辑
  - [x] 更新导入：knowledge_save, knowledge_batch_update
  - [x] 更新 BUILTIN_TOOLS 中的工具名称
  - [x] 更新所有工具调用为新名称
  - [x] 修复 agent/tools/builtin/__init__.py 的导入
  - [x] 验证导入成功
  - [ ] 移除 _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 配置项（保留，用于研究流程）
  - [x] 移除经验检索注入逻辑（已注释，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 行）