proxycast/docs/develop/execution-tracker-p1-p2-roadmap.md

Execution Tracker 后续路线（P1 / P2）

1. 目标说明

P0 已完成统一追踪能力落地；本路线定义下一阶段（P1/P2）可执行改进项，用于持续提升一致性、可观测性与运维效率。

2. P1（应做，近期）

P1-1 生命周期统一收敛

• 目标：Skill / Heartbeat 入口统一切换为 with_run 风格
• 收益：减少重复生命周期模板代码，降低维护成本
• 交付：
  • 入口改造 PR
  • code review checklist（执行追踪接入规范）

P1-2 一致性与悬挂监控

• 目标：建立 running 悬挂探测与告警机制
• 收益：提前发现 finish 漏写、异常中断等问题
• 交付：
  • 定时巡检任务（阈值可配置）
  • 统计指标：悬挂数、悬挂时长分布、来源维度占比

P1-3 旧路径读侧收敛

• 目标：禁止新增模块依赖 heartbeat_executions 写路径
• 收益：为单写切换清障，避免双写长期化
• 交付：
  • 文档与注释标记（deprecated 说明）
  • 读写链路梳理清单

3. P2（可做，中期）

P2-1 执行追踪聚合 API

• 目标：提供按来源/状态/时间窗口的聚合统计接口
• 收益：支撑运营看板、质量趋势分析
• 交付：
  • 聚合命令/API（例如成功率、P95 时延、错误 TopN）

P2-2 追踪与日志链路关联

• 目标：在 run 维度关联请求日志、会话消息与错误栈索引
• 收益：故障排查从“多处跳转”收敛到“单 run 入口”
• 交付：
  • run → 日志/会话的关联字段规范
  • 前端详情页一跳联查能力

P2-3 数据归档与保留策略

• 目标：定义 agent_runs 分层保留与归档策略
• 收益：控制数据量增长，保障查询性能
• 交付：
  • 保留周期配置（热数据/冷数据）
  • 清理任务与容量水位监控

4. 建议里程碑

• M1（1-2 周）：完成 P1-1、P1-2
• M2（2-4 周）：完成 P1-3，启动单写切换评估
• M3（4-8 周）：推进 P2 聚合与链路关联能力