Agent/docs/refactor-plan.md

重构计划：统一 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 相关代码残留
• 旧数据可以迁移