标签化版本管理与版本分析 — 开发计划

文档类型：Phase3 开发计划 ｜ 关联 Phase1 / Phase2 创建时间：2026-07-06 状态：MVP 已实现，浏览器验证待确认

导读

建议分 5 个 wave 落地：先打数据底座，再接 API，再改 Trace 页面，最后做版本管理和版本分析 UI。这样每一步都有可验证的服务端能力，不会先堆前端假数据。

§1 开发范围

本次计划包含：

• 新增 Tag / ExecutionTag 数据模型与迁移。
• 新增标签 CRUD API。
• 新增 Trace 标签绑定 API。
• 扩展 Trace 查询与筛选，支持业务标签过滤和标签返回。
• 新增版本管理页面。
• 改造链路追踪标签列、系统标签列、列显隐、用户标签多选筛选。
• 新增版本分析页面，包括版本对比和版本详情。
• 补充测试与用户/开发者指南。

本次不包含：

• 自动给历史 Trace 打版本标签。
• LLM 生成版本分析结论。
• CI 质量门禁。
• SkillVersion 体系改造。
• 版本分析内按业务标签二次过滤；该能力仅作为未来潜在优化点记录。

§2 任务拆分

Wave 0 — 设计确认

任务	内容	通过标准
T0-1	固化已对齐决策：允许多标签、硬删除、按 query 做单问题、只统计 root、版本分析暂不支持业务标签过滤	Phase1/Phase2 已记录结论
T0-2	确认页面路由命名：版本管理、版本分析	路由名称与侧边栏位置确定

Wave 1 — 数据底座

任务	内容	通过标准
T1-1	修改 prisma/schema.prisma，新增 Tag 与 ExecutionTag	Prisma schema 可生成，关系与索引完整
T1-2	增加迁移或 SQLite 初始化兼容逻辑	本地数据库可启动并自动具备新表
T1-3	扩展存储层或 service helper：标签 CRUD、绑定增删查、按 tag 查询 Execution	单测覆盖 CRUD 和绑定唯一性
T1-4	保留 Execution.label 旧字段，不迁移旧数据	老 Trace 查询不受影响

Wave 2 — API

任务	内容	通过标准
T2-1	实现 /api/tags 与 /api/tags/[id]	GET/POST/PUT/DELETE 均按 user 隔离
T2-2	实现 /api/observe/executions/[executionId]/tags	可获取、替换、增量添加、删除 Trace 标签
T2-3	扩展 /api/observe/data 返回标签并支持用户标签多选筛选	tagIds 可混选版本/业务标签并按 AND 命中；旧 bizTag 保持兼容
T2-4	实现 /api/observe/version-analysis/compare	返回版本标签聚合指标，版本按名称排序
T2-5	实现 /api/observe/version-analysis/tags/[tagId]/traces	返回指定版本下 Trace 明细和详情页所需指标

Wave 3 — 链路追踪改造

任务	内容	通过标准
T3-1	扩展 Trace 行类型，接入用户标签和系统标签	列表能渲染两类标签
T3-2	增加用户标签多选筛选入口	版本/业务标签按类型和前缀聚类；列表只显示同时命中全部所选标签的 Trace
T3-3	增加标签添加/移除交互	操作后刷新仍存在，失败时有提示
T3-4	增加系统标签列和列显隐配置	系统标签默认隐藏，用户标签默认展示
T3-5	保持现有搜索、筛选、排序、详情抽屉行为不退化	现有 Trace golden path 仍可用

Wave 4 — 版本管理页面

任务	内容	通过标准
T4-1	新增版本管理路由与侧边栏入口	可从配置组进入
T4-2	实现版本标签和业务标签分区列表	标签按类型展示，空态清晰
T4-3	实现新建/编辑弹窗	类型、名称、描述、颜色可编辑
T4-4	实现删除确认	删除后绑定清理，列表与 Trace 页面同步刷新
T4-5	接入使用次数和版本标签摘要指标	卡片摘要与 API 数据一致

Wave 5 — 版本分析页面

任务	内容	通过标准
T5-1	新增版本分析路由与侧边栏入口	可从观测组进入
T5-2	实现顶部上下文筛选和 KPI	Agent/时间窗口切换触发刷新
T5-3	实现版本对比 Tab	横轴为版本标签，按名称排序；指标切换可用
T5-4	实现单问题下钻	点击问题后图表和表格切换到该问题
T5-5	实现版本详情 Tab	选择版本后展示趋势、覆盖问题、Trace 明细
T5-6	Trace 明细跳转链路追踪详情	能打开对应 Trace
T5-7	实现导出当前聚合数据	导出内容与当前筛选一致

Wave FINAL — 文档与验证

任务	内容	通过标准
TF-1	更新用户指南	用户能按文档创建标签、给 Trace 打标、查看版本分析
TF-2	更新开发者指南	API、数据模型、数据流、前端路由与列配置不与实现脱节
TF-3	跑 npm run test	测试通过
TF-4	跑 npx tsc --noEmit	类型检查通过
TF-5	询问是否启动 dev server 做浏览器验证	用户确认后再按仓库约定执行 UI golden path

§3 测试计划

测试	覆盖
Tag CRUD 单测	创建、重名校验、编辑、删除、user 隔离
ExecutionTag 单测	绑定唯一性、删除标签级联、删除 Execution 级联
Trace 查询测试	tagIds 跨类型多选只返回同时命中全部标签的 Trace；bizTag 保持旧兼容语义
版本聚合测试	answerScore 均值、覆盖率、Token 均值、p95 latency、成本；运行成功率如实现则按 Trace 状态派生
空值测试	answerScore / tokens / latency / cost 缺失时不污染聚合
系统标签派生测试	Multi-Agent、Skills、SUB、framework 标签派生正确
前端组件测试	标签 chip、筛选状态、空态、删除失败提示

§4 UI 验证路径

用户确认启动 dev server 后，建议至少验证：

1. 创建一个版本标签和一个业务标签。
2. 在 Trace 列表给一条 Trace 打两个标签。
3. 刷新页面，确认标签仍显示。
4. 混合选择一个版本标签和一个业务标签，确认列表只剩同时命中二者的 Trace。
5. 打开版本分析，确认版本标签出现在横轴。
6. 进入版本详情，点击 Trace 明细能打开对应 Trace 详情。
7. 关闭系统标签列后刷新，确认列配置符合预期策略。

§5 提交建议

建议拆成 3 到 4 个 commit：

1. feat: 增加 Trace 标签数据模型和 API
2. feat: 支持链路追踪标签打标与业务筛选
3. feat: 增加版本管理与版本分析页面
4. docs: 更新标签化版本管理指南

§6 开发红线

• 不复用 Execution.label 作为新标签主存储。
• 不在版本分析中调用 LLM。
• 不把业务标签混入版本横轴。
• 不默认统计 sub-agent Execution，除非用户明确选择。
• 不新增局部色板；前端样式使用共享设计 token。
• 不默认启动 dev server；浏览器验证前先问用户。

变更记录

v0.1（2026-07-06）

• 根据 Phase1/Phase2 初稿拆分开发 wave、测试计划与验证路径。

v0.2（2026-07-06）

• 同步已对齐决策：多标签、硬删除、按 query 下钻、root-only、版本分析暂不支持业务标签过滤。
• 调整成功率为可选派生运行指标，不作为现有存储字段。