[Verification] 自动验证策略：测试选择、失败归因、flaky 检测和风险评分

[v833]

标签建议：area/verification, area/reliability, priority/P1, type/feature, depends-on/verification

背景

当前能力：

• q-code 仓库已有丰富测试脚本：pnpm typecheck、pnpm test:unit、pnpm test、legacy 测试和 eval smoke/cli/nightly。
• AGENTS 中维护了按改动类型建议运行的测试策略。
• Agent 当前更多依赖人工指令或固定命令选择，缺少自动推断“这次改动应该跑哪些测试”的策略层。

痛点：

• 小改动跑全量测试成本高，大改动只跑单测又容易漏风险。
• 测试失败后，需要人工读日志区分代码 bug、环境问题、flaky、依赖缺失或超时。
• PR review 很难快速判断“测试覆盖是否足够”。

需要补齐：

• 基于变更文件、模块边界、历史规则和索引信息的测试选择。
• 失败归因和建议下一步。
• flaky 检测、风险评分和验证报告。

目标

实现自动验证策略模块：根据代码变更和任务类型推荐并执行合适的测试命令，归因失败原因，识别 flaky 风险，输出可审计的验证报告和风险评分。

用户故事

• 作为开发者，我希望 q-code 修改代码后自动建议最小但足够的测试集，以便节省时间又不漏关键风险。
• 作为 reviewer，我希望看到验证报告说明为什么跑这些测试、哪些没跑和剩余风险。
• 作为维护者，我希望失败日志能被归因到测试失败、类型错误、环境缺失或 flaky，以便快速处理。
• 作为 CI 用户，我希望验证策略在非交互环境中可预测、可配置预算和超时。

详细需求

1. 测试选择策略

• 根据 git diff、文件路径、模块目录和 AGENTS 测试策略推荐命令。
• 与 [Indexing] 项目索引：symbol index、依赖图、语义搜索和增量缓存 #25 项目索引结合时，可根据相关测试候选补充更精确命令。
• 支持策略等级：minimal、standard、full。
• 默认小型纯逻辑改动至少推荐 pnpm test:unit；类型/公共接口改动推荐 pnpm typecheck。

2. 命令执行与预算

• 执行测试时复用 shell/background job 能力，支持 timeout 和输出 spill。
• 支持最大耗时、最大失败数、是否允许 legacy/eval 的配置。
• 非交互模式下必须可通过参数控制是否自动运行。

3. 失败归因

• 解析常见输出：TypeScript 错误、Vitest 失败、依赖缺失、超时、网络失败、权限失败。
• 输出摘要包含失败文件、关键断言、可能根因和建议下一步。
• 不把超大日志塞进上下文；保存 artifact 路径并引用摘要。

4. Flaky 检测

• 支持对指定失败测试重跑 N 次，记录稳定失败或疑似 flaky。
• Flaky 结论必须谨慎，标记为“疑似”并保留证据。
• 不在默认路径中过度重跑，避免浪费时间。

5. 风险评分与报告

• 输出验证报告，包含变更范围、已运行命令、结果、未覆盖风险和建议。
• 风险评分可基于改动模块、测试覆盖、失败状态、未跑测试和历史 flaky 信号。
• 报告可供 PR 描述或 session 总结引用。

输出样例

验证建议: standard

将运行:
- pnpm typecheck
- pnpm test:unit

原因:
- 修改 src/runtime/config.ts，影响公共配置解析
- 修改 tests/unit/runtime-config.test.ts，已有对应单测

风险: medium

验收标准

• 根据变更路径推荐 minimal/standard/full 测试命令。
• 能解释每条测试命令的选择原因。
• 测试执行支持 timeout、输出摘要和 spill artifact。
• 能归因 TypeScript、Vitest、依赖缺失、超时和权限类失败。
• 支持可选重跑并标记疑似 flaky。
• 输出验证报告包含已跑、未跑和剩余风险。
• README/AGENTS 如新增测试策略或命令，按需同步更新。
• 单元测试覆盖策略选择、归因解析和风险评分。

测试方案

• tests/unit/verification-strategy.test.ts：覆盖路径到命令映射、策略等级和预算。
• tests/unit/verification-parser.test.ts：覆盖 tsc、vitest、timeout、依赖缺失日志解析。
• tests/integration/verification-flow.test.ts：在 fixture 中模拟 diff、运行命令和生成报告。
• 手动验证：小型 src 改动、TUI 改动、eval 改动、失败测试、超时命令。

不在本期范围

• 替代 CI 或直接管理 GitHub Actions。
• 基于机器学习的复杂测试影响预测。
• 自动修复所有失败测试。
• 长期 flaky 数据库服务。

依赖 / 风险

• 与 [Indexing] 项目索引：symbol index、依赖图、语义搜索和增量缓存 #25 索引结合能提升精度，但基础策略不应强依赖索引完成。
• 自动运行命令可能耗时或触发外部副作用，需要和 approval policy/预算配置协同。
• 失败归因不能过度自信，需明确“可能原因”。
• Windows/PowerShell 输出编码和路径解析需要覆盖。

工作量评估

• 测试选择策略与配置：1.5 人日
• 执行封装与报告：1.5 人日
• 失败归因与 flaky 重跑：2 人日
• 测试与文档：1.5 人日
• 合计：~6.5 人日