# 重构计划：统一 Trace 模型

> 基于更新后的 context-management.md 设计，移除 branch 概念，采用独立 Trace 架构

## 目标

将当前基于 branch 的实现重构为统一的 Trace 模型，每个 Sub-Agent 都是独立的 Trace。

## Phase 1: 核心数据结构调整

### 1.1 Trace ID 生成器
- [ ] 实现 `agent/execution/trace_id.py`
  - [ ] `generate_sub_trace_id(parent_id, mode)` 函数
  - [ ] `parse_parent_trace_id(trace_id)` 函数
  - [ ] 线程安全的序号计数器
  - [ ] 单元测试

### 1.2 Trace 模型更新
- [ ] 更新 `agent/execution/models.py:Trace`
  - [ ] 添加 `parent_trace_id: Optional[str]` 字段
  - [ ] 添加 `parent_goal_id: Optional[str]` 字段
  - [ ] 确保 `context: Dict[str, Any]` 字段存在
  - [ ] 更新 `to_dict()` 和 `from_dict()` 方法
  - [ ] 移除任何 branch 相关字段（如果有）

### 1.3 Message 模型更新
- [ ] 更新 `agent/execution/models.py:Message`
  - [ ] **移除** `branch_id` 字段
  - [ ] 确保 `duration_ms` 字段存在
  - [ ] 更新 `to_dict()` 方法
  - [ ] 更新 `create()` 方法

### 1.4 Goal 模型更新
- [ ] 更新 `agent/goal/models.py:Goal`
  - [ ] **移除** `branch_id` 字段
  - [ ] **移除** `branch_ids` 字段
  - [ ] 确保 `sub_trace_ids` 字段存在
  - [ ] 更新 `to_dict()` 和 `from_dict()` 方法

### 1.5 移除 BranchContext
- [ ] 删除 `agent/goal/models.py:BranchContext` 类
  - [ ] 检查所有引用
  - [ ] 移除相关导入

## Phase 2: 存储层重构

### 2.1 FileSystem Store 更新
- [ ] 重构 `agent/execution/fs_store.py`
  - [ ] **移除** `_get_branches_dir()` 方法
  - [ ] **移除** `_get_branch_dir()` 方法
  - [ ] **移除** `_get_branch_meta_file()` 方法
  - [ ] **移除** `_get_branch_goal_file()` 方法
  - [ ] **移除** `_get_branch_messages_dir()` 方法
  - [ ] **移除** `create_branch()` 方法
  - [ ] **移除** `get_branch()` 方法
  - [ ] **移除** `get_branch_goal_tree()` 方法
  - [ ] **移除** `update_branch_goal_tree()` 方法
  - [ ] **移除** `update_branch()` 方法
  - [ ] **移除** `list_branches()` 方法
  - [ ] 更新 `create_trace()` - 不再创建 branches/ 目录
  - [ ] 更新 `add_message()` - 移除 branch_id 逻辑
  - [ ] 更新 `get_trace_messages()` - 移除 branch_id 参数
  - [ ] 更新 `get_messages_by_goal()` - 移除 branch_id 参数
  - [ ] 更新 `_update_goal_stats()` - 移除 branch_id 逻辑
  - [ ] 更新 `_get_affected_goals()` - 移除 branch_id 逻辑

### 2.2 TraceStore 协议更新
- [ ] 更新 `agent/execution/protocols.py:TraceStore`
  - [ ] **移除** branch 相关方法签名
  - [ ] 更新方法签名（移除 branch_id 参数）
  - [ ] 添加查询 Sub-Trace 的方法（如果需要）

### 2.3 数据迁移脚本
- [ ] 创建 `scripts/migrate_traces.py`
  - [ ] 读取旧的 `.trace/*/branches/` 结构
  - [ ] 为每个 branch 生成新的 trace_id
  - [ ] 创建独立的 Trace 目录
  - [ ] 更新 Goal 的 sub_trace_ids
  - [ ] 移除 branch_id 字段
  - [ ] 备份原始数据

## Phase 3: 工具实现

### 3.1 explore 工具
- [ ] 实现 `agent/goal/explore.py`
  - [ ] `explore_tool(branches, background)` 函数
  - [ ] 使用 `generate_sub_trace_id()` 生成 Sub-Trace ID
  - [ ] 创建独立的 Trace 实例
  - [ ] 并行执行 Sub-Traces
  - [ ] 汇总结果
  - [ ] 单元测试

### 3.2 delegate 工具
- [ ] 实现 `agent/goal/delegate.py`
  - [ ] `delegate_tool(task)` 函数
  - [ ] 使用 `generate_sub_trace_id()` 生成 Sub-Trace ID
  - [ ] 创建独立的 Trace 实例
  - [ ] 执行并返回结果
  - [ ] 单元测试

### 3.3 goal 工具更新
- [ ] 更新 `agent/goal/tool.py`
  - [ ] 移除任何 branch 相关逻辑
  - [ ] 确保与新的 Goal 模型兼容

## Phase 4: API 层更新

### 4.1 REST API
- [ ] 更新 `agent/execution/api.py`
  - [ ] `GET /api/traces/{trace_id}` - 支持新的 trace_id 格式
  - [ ] 添加查询 Sub-Traces 的端点
  - [ ] 移除 branch 相关端点
  - [ ] 更新响应格式（包含 sub_traces）

### 4.2 WebSocket
- [ ] 更新 `agent/execution/websocket.py`
  - [ ] 移除 branch 相关事件
  - [ ] 添加 `sub_trace_started` 事件
  - [ ] 添加 `sub_trace_completed` 事件
  - [ ] 更新事件格式

## Phase 5: 清理和测试

### 5.1 清理
- [ ] 搜索代码库中所有 "branch" 引用
  - [ ] 移除或更新相关代码
- [ ] 删除 `.trace/*/branches/` 目录（旧数据）
- [ ] 更新所有文档引用

### 5.2 测试
- [ ] 单元测试
  - [ ] Trace ID 生成器
  - [ ] explore 工具
  - [ ] delegate 工具
  - [ ] FileSystem Store
- [ ] 集成测试
  - [ ] 创建主 Trace
  - [ ] 启动 Sub-Trace
  - [ ] 查询跨 Trace 数据
- [ ] 端到端测试
  - [ ] 完整的 explore 流程
  - [ ] 完整的 delegate 流程

## Phase 6: 文档更新

- [ ] 更新 README
- [ ] 更新 API 文档
- [ ] 添加迁移指南
- [ ] 更新示例代码

## 实施顺序建议

1. **Phase 1** (数据结构) - 最重要，先打好基础
2. **Phase 2.1-2.2** (存储层) - 核心存储逻辑
3. **Phase 3** (工具实现) - 业务功能
4. **Phase 4** (API 层) - 对外接口
5. **Phase 2.3** (数据迁移) - 处理历史数据
6. **Phase 5** (清理测试) - 确保质量
7. **Phase 6** (文档) - 最后完善

## 风险和注意事项

1. **兼容性**：旧的 traces 数据需要迁移
2. **并发安全**：`generate_sub_trace_id` 的序号生成器需要线程安全
3. **性能**：独立 Trace 可能增加文件系统操作，需要监控
4. **调试**：新的 trace_id 格式较长，需要确保日志和 UI 能正确显示

## 完成标准

- [ ] 所有测试通过
- [ ] 文档更新完成
- [ ] 示例代码可运行
- [ ] 没有 branch 相关代码残留
- [ ] 旧数据可以迁移