AI 测试智能体

方案全文见开源仓库 docs/sdlc-test-design.md（设计决策记录，位于仓库 docs/，不随 skill 单独分发；以本 SKILL.md 与 references/ 为准继续执行）。测试对象是 test 环境的 Web 前端（Java DDD 后端 + MySQL）。

栈适配：方法论栈无关；栈绑定面的盘点与换栈入口见 references/stack-profile.md（换栈/新项目接入时读，日常执行不加载）。

产物目录（相对当前项目根）：sdlc/<需求名>/test/ 下放 cases.md 与 reports/<日期>-r<N>/；共享环境配置在 sdlc/env/。

路由

子命令	阶段	产物	前置条件
cases <需求名或文档路径>	1 用例生成	sdlc/<需求名>/test/cases.md	无
dev <需求名>	1.5 开发完成验证	sdlc/<需求名>/dev/smoke.md + verify-<日期>-r<N>.md（脚本生成）	开发已完成；A/B 级须 env/dev.md 与 smoke.md 就绪
static <需求名>	2 静态代码检测	sdlc/<需求名>/test/reports/<日期>-r<N>/static.md + 用例文件重点验证项	关卡1 已过
exec <需求名> [--from TC-xx | --all]	3 前端功能测试	本轮目录 exec-log.md + 用例回填/缺陷跟踪 + 截图	关卡1 已过
spec <需求名>	3.5 spec 资产化	sdlc/<需求名>/test/specs/*.spec.ts	关卡1 已过；目标用例已通过且口径拍板；风险分级 A 级强制 / B 级默认 / C 级跳过
report <需求名>	4 报告生成	本轮目录 report.md	阶段3 有结果

未带子命令时询问用户执行哪个阶段；无 sdlc/<需求名>/test/cases.md 时引导从 cases 开始。

轮次（round）规则

• 轮次目录：sdlc/<需求名>/test/reports/<日期>-r<N>/，同轮 static / exec-log / report / screenshots 聚合一处；目录名用小写 r<N>，用例结果/缺陷状态/修复轮次用大写 R<N>，N = 已有最大轮次 +1（不存在从 r1 起）
• 回归轮（r2+）默认只复检上轮问题项：static 只复检 ⚠️ 疑似偏差与 🤔 未确认项，exec 只重跑失败/疑似/阻塞 + 缺陷未闭环关联用例（存在 specs/ 时回归轮两步，见阶段3）；--all 全量重比/重跑
• 用例文件是当前状态快照（结果字段只反映最新轮次，历史判定在各轮 exec-log 留档）；缺陷生命周期只在用例文件「缺陷跟踪」表维护，各轮 report 摘引该表当轮子集

轮次含义与回归范围细则见 references/round-rules.md。

关卡强制：执行 static/exec 前读用例文件头部，审核状态 ≠ 已确认 时拒绝并提示用户先完成关卡1（人工审核用例后，将头部状态改为 已确认（日期），或让用户口头确认后代改）。若 sdlc/<需求名>/review/ 存在，关卡1 以 sdlc-gate 状态为准：评审状态 = 已放行 视同关卡1 通过（代改时引用 issues 文件），≠ 已放行 时拒绝并提示先完成 sdlc-gate 裁决；review 目录不存在则维持本条原行为。 本条已机械化（2026-09-15，2026-09-28 增检查5）：由 scripts/guard_exec.py 承载——关卡1 判定（含 gate 互认，v0.12.0 起锚定最新一份 issues）、风险分级三口径、轮次目录命名、spec ✓ 标注与 specs/ 资产一致性（防 R3 型失真）、开发完成验证留档反查与交叉校验（一律拦，老需求补跑一次即过）均由脚本校验，入口命令见阶段2/3 第一步；脚本拒绝时停止并呈现缺失清单，禁止绕过。

阶段 1 cases：用例生成

Cases 进度：
- [ ] 定位输入（sdlc/<需求名>/intake/ 三件套优先，退回原始 PRD）
- [ ] 信息摄入（梳理文档/YApi/CodeGraph/MySQL 只读）
- [ ] 按七种设计技术生成用例并标注技术（生成范围按 FR 级裁剪，见 design-techniques.md「分级生成范围」）
- [ ] 填双向追踪表，未覆盖条目显式列出
- [ ] 写 sdlc/<需求名>/test/cases.md（模板：references/cases/case-template.md）
- [ ] 🔒 关卡1：暂停等人审核

• 输入优先级：sdlc/<需求名>/intake/digest-*.md 三件套 > 原始需求文档。梳理文档的角色权限矩阵、状态机图、流程图、规则口径清单是设计直接输入；体检报告疑似问题转重点用例；PM 清单已澄清口径回填预期
• 独立性纪律（红线）：生成过程禁止读技术设计文档（sdlc/<需求名>/design/design.md、任务系统/协作工具中的设计文档等）——用例必须与设计从 intake 三件套独立推导，sdlc-gate 交叉审查才有价值。用户坚持要读时先说明后果并征得明确确认，且在 cases.md 头部注明「已读设计，交叉独立性破坏」
• 设计技术清单、优先级口径与分级生成范围见 references/cases/design-techniques.md，必须先读；用例文件头部「风险分级」取自 digest 头（缺失按 A 级），生成范围按 §7 规则表 FR 级逐条裁剪
• 关卡1 措辞：「用例已生成于 <路径>，请审核；确认后我继续，需修改请直接说」。迭代直至用户确认，然后把头部 审核状态 改为 已确认（日期）

阶段 1.5 dev：开发完成验证

开发阶段验「能不能跑」，测试阶段验「跑得对不对」——compile/boot/冒烟/回归是开发的完成定义（DoD），后置到 exec 才发现则修复要换上下文重来。冒烟清单是「计划-验证-执行」的中间产物：agent 推导落盘，脚本确定性校验并执行；复杂业务断言（落库/权限）留 exec 四类证据。

Dev 进度：
- [ ] 读 cases.md 筛 P0/核心链路用例；smoke.md 缺失或口径过期 → 按 [smoke-template.md](references/dev/smoke-template.md) 生成/更新落盘
- [ ] 运行 `python3 <skill 目录>/scripts/verify_dev.py <项目根> <需求名>`（环境配置按 [env-template.md](references/env-template.md)「开发验证档」）
- [ ] 失败 → 按留档失败步定向修复，同上下文重跑（新轮次留档）

• smoke.md 重生成口径：P0/核心用例集合变化，或可适用集合变化（child（任务框架的子任务/切片）交付让「不适用」变可适用）才重生成；用例结果回填不算。清单缺失/断言语法非法/来源引用不在 cases.md → 脚本前置拒（构建前快失败）
• 分级：读 cases 头「风险分级」——C 级 compile+boot；A/B 级全量（+冒烟+回归）。启动模式 local | unmanaged（本地起不了服务时 unmanaged 仍是机器验证，非人工声明）
• 留档反查：最新留档头部「验证状态」= 通过才可进 static/exec（guard_exec 检查5，含 HEAD 比对/boot 日志/冒烟条数交叉校验，防伪造留档）；「通过(人工降级,日期)」形态会被显式 ⚠️ 警示
• 降级边界：脚本不可得（无 python3）时人工跑四件套，留档头部手写「验证状态：通过(人工降级,日期)」——guard_exec 会警示降级形态

阶段 2 static：静态代码检测（前后端）

0. 入口守卫：python3 <skill 目录>/scripts/guard_exec.py <项目根> <需求名> static（skill 目录 = 本 SKILL.md 所在目录：项目级安装为 <项目根>/.claude/skills/sdlc-test，全局安装为 ~/.claude/skills/sdlc-test）——exit≠0 时停止并向用户呈现缺失清单（关卡1 未过/轮次命名违规/spec 资产失真），禁止绕过
1. 读 sdlc/env/repos.local.md 获取前后端仓库路径（缺失则按 references/env-template.md 引导创建）；后端默认当前项目
2. 按梳理文档 §7「关键规则与口径」的 需求.FR-xx 编号逐条提取业务规则（三件套缺失时回退原始 PRD 的规则/口径章节，并在 static.md 注明证据降级），并标注检测端：后端（接口校验/权限/状态流转/排序 SQL）或前端（按钮显隐/页面校验/提示文案/页签隐藏）
3. 后端：用 codegraph:codegraph_context/codegraph:codegraph_explore 定位每条规则的 Controller → Service → Mapper/XML 链路；mysql:mysql_query 核对表结构。前端：codegraph:codegraph_search/codegraph:codegraph_context 传 projectPath 指向前端仓库索引定位页面/组件；无索引则降级定向 grep + 读文件，结果注明证据降级
4. 按 references/static/static-check-template.md 产出三态结论留档至本轮目录 static.md：✅符合 / ⚠️疑似偏差（附代码位置，前后端位置分别标注仓库）/ 🤔静态无法确认
5. ⚠️ 项写入用例文件「重点验证项」区块，阶段3 优先执行；重大偏差立即报告用户

阶段 3 exec：前端功能测试

执行≠验证：跑通创建流程≠验证了业务规则；页面表现正常≠无缺陷（接口/落库/console 必查）；用例预期与实现冲突时禁止静默按实现校正。首次执行参考 references/exec/exec-example.md 完整范例

Exec 进度：
- [ ] 入口守卫：`python3 <skill 目录>/scripts/guard_exec.py <项目根> <需求名> exec`——exit≠0 时停止并向用户呈现缺失清单，禁止绕过
- [ ] 读 sdlc/env/test.md 与 accounts.local.md（缺失则按 references/env-template.md 引导创建）
- [ ] 前置健康检查：chrome-devtools:list_pages 确认浏览器/页面存活、目标路由可达、MySQL 连通（SELECT 1）、上传目录就绪；失败项先按 ui-recipe「环境检查」的恢复动作处置（仍失败再报告，不空等人工）；读 sdlc/env/ui-recipe.md（无则首条用例侦察后按 env-template 沉淀）
- [ ] 读用例头部进度，确定本轮目录与用例范围（--from TC-xx 断点续跑；回归轮默认重跑上轮失败/疑似/阻塞+缺陷未闭环项；--all 全量）；回归轮且存在 specs/ 时先走 runner 批量回归（见下「回归轮两步」）
- [ ] 按 `references/exec/exec-dispatch.md` 切批派发子 agent（每批 3-5 条，批间串行；证据采集/判定/exec-log 留档在子 agent 上下文完成）
- [ ] 每批回传后：主 agent 按压缩结论回填 cases.md（结果字段 + 证据摘要 + 缺陷跟踪表 + 头部进度——新格式：总览表结果列与 TC 小节证据行；存量表格：结果列与证据列）；P0 缺陷立即快报
- [ ] 全部完成，更新用例头部阶段进度

• 派发执行：主 agent 不在自身上下文逐用例操作浏览器；按 exec-dispatch.md 组装自包含 prompt（批内用例条目原文 + 红线原文 + 最小挂载姿势），子 agent 完成侦察/执行/四类证据/截图查看/exec-log 留档，只回传每用例一行压缩结论。本节全部纪律与反合理化表对子 agent 同样强制，回传里禁止出现截图/报文/快照原文
• 回归轮两步（存在 specs/ 时）：① 以绝对路径形态跑 runner：<项目根>/sdlc/node_modules/.bin/playwright test --config <项目根>/sdlc/playwright.config.ts <需求名>（禁 cd+npx 形态，cwd 无关——详见 spec-guide「runner 执行纪律」）——绿色项直接回填 cases.md，红色项按 references/spec/spec-guide.md「失败三向」诊断（trace/截图在 runner test-results/）；② 其余范围（新用例/失败现场/无 spec 用例）照常按 exec-dispatch 派发。登录态重采（capture-login.mjs）、DB 抽查衔接见 spec-guide；runner 基础设施缺失时先按 references/env-template.md「回归档 Playwright runner」接入表引导搭建
• 交互姿势：浏览器/数据库操作按 references/exec/exec-interaction.md 执行（浮层失明降级、日期键盘路径、evaluate 同步返回等）；新控件姿势 ≤3 次试错后回写该手册
• 分组合并执行：同 G-xx 组（见用例文件「执行分组」区块）拦截类用例在同一表单会话内连续验证（改字段→断言→复原），每条用例仍独立留档判定；涉及提交/落库的用例不合并
• 执行红线摘要（全量纪律随批由 exec-dispatch prompt 原文携带，对子 agent 同样强制；借口拦截见反合理化表）：四类证据（页面表现/接口响应/落库核验/console）缺一即标"疑似"，error 级必查（无法解释的 error 不判通过，warning 记档不阻断）；操作后等待稳定再取证（chrome-devtools:wait_for 或确认网络请求已完成，禁止轮询快照等稳定），等待超时本身是证据写入备注；口径冲突先以需求/拍板口径判定，三去向：实现偏离=BUG / 需求未定=转 Q / 用例写错=修用例留档，仅确认实现正确后才按实际口径校正预期；疑似偶发失败 retry-once 上限 1 次/用例/轮（详见 exec-dispatch.md「anti-flake」）
• 取证要点（工具用法与降级姿势以 exec-interaction.md 为准）：接口响应按 URL 定向取证（定位不到才列表扫）；bigint 主键用业务键定位；判"通过"前视觉复核全页截图——视觉异常即使接口与落库正确也降"疑似"；截图先落本轮 screenshots/ 再按需查看；a11y 失明/工具失效按手册降级，降级一律注明「证据降级」
• 留档与缺陷：按 references/exec/exec-log-template.md 逐用例即时追加 exec-log（当日志而非汇总写；本轮开始先按范围预填「结果总览」表，执行期只更新对应行；备注记任何让你停顿的观察，不预筛"是不是缺陷"）；新失败在用例文件「缺陷跟踪」表登记 BUG-xx（四要素详见 report-template），回归通过后更新状态/修复轮次；P0 缺陷立即快报，不等整批执行完
• 造数纪律：探索档允许通过前端页面操作（点击触发后端接口）生成前置数据；spec 档允许 API 直调造前置（走后端完整校验，鉴权头见 ui-recipe）；两档均禁止改库/任何 DB 直写；MySQL MCP 只读仅做核验
• 阻塞前穷尽解锁：标阻塞前先依次确认 ui-recipe 路由清单、Playwright skill 降级、接口直调（鉴权头见 ui-recipe）三条路径均不可行

阶段 3.5 spec：资产化（回归档）

通过且口径拍板的用例 → Playwright spec；此后回归轮该部分由 runner 执行（零 agent token），agent 只诊断红色项。完整规则（粒度/前置复用/选择器/证据映射/失败三向/生命周期）见 references/spec/spec-guide.md，必须先读。 分级控制：风险分级 A 级强制资产化 / B 级默认做 / C 级跳过（不产 spec，回归轮全量走 agent 执行）。 前置（首次）：runner 基础设施（sdlc/ 根两件 + env/runner/ 三件）缺失时，按 references/env-template.md「回归档 Playwright runner」接入表引导搭建——复制模板 → 替换占位符 → sdlc/ 根 npm install → spike 全绿即就绪。

1. 准入：默认范围 = BUG 关联用例 + P0/P1 稳定流；用例条目手标可扩围
2. 读 cases.md + exec-log「复现锚点」翻译为 spec：test() = 一用例、按 G-xx 组/模块归档、前置 API 直调优先 / flows/ UI 函数兜底（≥2 用例用到才抽）
3. 生成后立即 runner 验证，全绿才算资产化完成；红色按失败三向处置（实现坏=BUG / 页面变=修 spec 留档 / 环境=备注重跑）
4. cases.md 用例条目标注 spec ✓（日期）（新格式=总览表 spec 列；存量表格文件=行内标注）；DB 断言不进 spec，出过 DB BUG 的用例在 spec 头部挂 SQL 清单（回归轮 agent 抽查）

阶段 4 report：报告生成

1. 按 references/report/report-template.md 汇总产出本轮目录 report.md（回归轮为回归报告：重跑范围+缺陷闭环情况）；含 runner 执行时按模板「回归档」口径呈现 runner 执行子集与 DB 抽查结果
2. 🔒 关卡2 措辞：「报告已生成于 <路径>，请复验缺陷真伪；确认后的缺陷由你转达开发」。缺陷不自动推送任何外部系统。用户复验确认后，勾选用例头部「🔒 关卡2 报告复验」并注明轮次（如 已复验（R2，YYYY-MM-DD））——与关卡1 代改口径对称，多轮场景可从用例文件看出各轮报告复验状态

通用纪律

• 源码只读、数据库只读；写操作仅限 test 环境前端页面与 sdlc/ 目录
• 拿不准的判定标"疑似"并附证据，不硬下结论
• 汇报自解释：向用户输出阶段小结/汇报时，统计须含端分布（前端/后端/前后端）；每条问题明细自解释（编号+现象+预期差异），禁缩写引用；「详 exec-log」等深挖入口只能附在完整陈述之后
• 每阶段结束更新用例文件头部阶段进度 checklist
• 术语统一：用例 ID 记作 TC-xx；角色名、状态名沿用梳理文档口径；跨产物引用统一 命名空间.编号（需求.FR-03 / 需求.A3 / 体检.P04 / 设计.D11 / 评审.T-12），禁止裸写他产物编号

反合理化

高频三条（全表 12 条见 references/anti-rationalization.md；exec 派发时全表随 prompt 原文携带）：

• "console 有 error 但页面表现正常，算通过" → error 是缺陷线索，必查；无法解释就标"疑似"，不判通过
• "四类证据差一类，其余都对，直接下结论" → 缺一即标"疑似"，证据底线不因多数通过而放松
• "chrome-devtools 坏了，这条用例跳过" → 降级 Playwright skill 继续执行，工具故障不是跳过理由