qa-evaluation - SKILL.md Agent Skill

name: qa-evaluation description: Evidence-driven QA evaluation for 1flowbase dev acceptance, PR merge gates, project health gates, regression, delivery, full-project audits, quality gate routing, i18n/multilingual key-value hygiene, frontend/backend contract, status, boundary and runtime checks, scope/error-handling acceptance, hotspot/churn prevention reviews, and maintainability/dead-abstraction warnings. Use when Codex must report verifiable findings and risks instead of directly implementing or fixing.

QA Evaluation

Overview

qa-evaluation 不是另一个开发 Skill，而是 1flowbase 的质量评估器。开发阶段默认不自动注入完整测试门禁；进入自检、验收、回归或交付阶段后，再由这个 Skill 负责选择脚本、收集证据并输出 QA 结论。它默认只产出问题报告与修正方向，不直接改代码。

质量门禁先分 lane 再选证据：开发后验收优先快，PR 门禁优先合并信心，项目体检优先完整健康快照和维护者感知。当前本地开发分支专注结果验证和尽早发现直接问题；仓库级、线上级、重型质量门禁默认交给 beta / CI / 专门质量工作区。不要把三种资源预算混成一套重门禁。

Project Health Gate 的顺序固定为：先确认 lane 和范围，再建立质量维度矩阵，再把脚本、artifact、日志、截图、代码证据归类到矩阵，最后输出 findings。当前失败脚本或错误报告只是证据来源，不得成为项目体检的完整范围或主线。

When to Use

功能完成后，需要对当前任务做质量回归
改了共享组件、共享状态或公共 API，需要检查变化传播
用户明确要求“全量评估项目现状代码”
需要输出结构化 QA 报告，而不是直接进入修复
需要判断 UI、流程、响应式、API、状态和架构边界是否仍然成立
需要评估后端接口、状态入口、插件消费边界、runtime 行为或工程质量门禁是否仍然符合最新规范
需要检查多语言 key / value、未引用 key、locale 文件名、翻译资源归属或 i18n-hygiene 报告
需要分析昨天/今天、近两天或近期代码热点、反复修改、churn 来源，并把问题转化为 AI 下次少犯错的 skills / AGENTS / 质量门禁 / 代码环境优化

不要用于

直接实现或修复功能
纯代码风格讨论
没有范围和验收场景的泛泛“看一眼”

The Iron Law

没有直接证据，不得下 QA 结论。默认只报告和 warning，不直接修；任何修复、删除或重构都必须得到用户明确同意。

用户可见文案是开发者已调好的产品内容，不是 QA 修复素材。除非用户在当前任务中明确要求改文案，否则 QA / i18n hygiene 不得修改任何展示给用户的字符串值；只能报告问题、复用既有 key、调整 key 引用、合并重复 key、删除确认失效 key，且必须保留原文案值。

Code Acceptance Checks

Dev Acceptance Gate 和 Project Health Gate 都必须把代码体检问题绑定到证据：文件 / 函数 / 调用点 / 运行路径 / 测试 / 日志 / 截图 / artifact。只凭“看起来复杂”不能下 finding；证据不足时写 未验证，不下确定结论。

Maintainability: 检查是否为了拆分而拆分、把完整业务流程拆成多个只调用一次的微型私有方法、引入无领域责任的 helper / utils / manager / adapter，或让主业务路径需要频繁跳转才读懂。单个方法超过约 80 行只是调查信号，不是自动 blocker；业务流程连贯且可读时不要强行要求拆分。
Error handling: 检查静默 fallback、默认值兜底、吞错、泛化错误、绕过逻辑和无业务语义防御代码。只有错误路径真实存在且符合当前边界时才建议错误处理；不应该发生的状态优先暴露问题、收敛状态来源或修正数据流。
Scope and boundary: 检查实现是否只覆盖已确认范围，是否顺手重构无关逻辑，是否为了局部方便破坏领域模型、状态模型、权限模型、contract 或前后端职责边界，是否把复杂度扩散到多个调用点或隐式约定里。

Quick Reference

开发阶段默认不加载完整质量门禁；功能完成后再主动进入 qa-evaluation
先按 references/gate-lanes.md 选择门禁 lane：Dev Acceptance Gate、PR Merge Gate、Project Health Gate
默认 Dev Acceptance Gate / task mode；用户明确要求 PR 校验、全量门禁、项目体检或完整 QA 审计时，才升级到对应 lane
Dev Acceptance Gate 追求快速反馈：复用 TDD 红绿结果，按风险向量选择最小证据链，证据足够或预算耗尽就停，不用仓库级门禁惩罚局部开发
本地开发分支只证明当前任务结果、直接相关 contract 和主路径风险；workspace 级 cargo / pnpm build / clippy / full test、coverage、verify-repo、repo hygiene、i18n hygiene 等重门禁默认延后到 beta / CI / 专门质量工作区
PR Merge Gate 追求合并信心：优先 GitHub Actions / artifact / beta 质量门禁结果，报告 blocker、warning、advisory、资源耗时和合并风险
Project Health Gate 追求维护者感知：先按 references/project-evaluation-checklist.md 建质量维度矩阵，再读取远端完整门禁、artifact、warningFiles、beta 质量工作区产物和必要本地证据，输出全局快照、风险热力图、趋势、轮转深挖和维护建议
Project Health Gate 不得只围绕当前失败脚本或错误报告展开；脚本失败必须先归入对应质量维度、硬性门禁失败、warning 或未覆盖项，再进入 findings
评估前先读 .memory/AGENTS.md、.memory/user-memory.md、项目记忆、反馈记忆和相关 spec
仓库质量门禁“怎么选、怎么组合、各自覆盖什么”看 references/repo-quality-gates.md
多语言 key / value hygiene、warning 解释和修复边界看 references/i18n-hygiene-gate.md
需要处理周期性质量门禁值守、GitHub Issue / Actions 报告闭环或无权限贡献者本地门禁取证时，看 references/quality-gate-watch.md
评估范围命中容器镜像、Trivy、GHCR、Dockerfile、基础镜像或镜像漏洞报告时，再加载 references/container-image-security.md
如果评估范围命中后端，必须先读 api/AGENTS.md，再对齐 .memory/project-memory 中最近的后端规范、计划和插件边界记忆，不能沿用旧口径
task mode / Dev Acceptance Gate 必查：验收场景、交互流、变化传播、状态 / API / 数据映射、关键回归；后端 API 任务必须把已确认验收预期与 TDD / 定向接口 evidence 对照，不能只凭编译、cargo 或代码阅读下结论
project evaluation mode / Project Health Gate 必查：UI 一致性、流程逻辑、响应式降级、API 契约、状态数据一致性、架构边界、测试缺口、风险热力图和维护建议；后端接口体检使用 mock / fixture / 受控数据跑质量门禁，检查状态是否正常、返回结构是否稳定、值是否正确、过期 / 禁用 / 缺失状态是否符合预期
前后端字段契约必查：接口字段名必须沿用后端 DTO / 领域语义；展示文案可本地化，但不得为展示另起业务字段别名
用户可见文案硬边界：不得改 locale value、按钮/菜单/标题/导航/placeholder/empty/error/help text、schema label、节点展示名或默认 alias 等任何用户能看到的字符串；发现错字、不一致或表达问题时只写 finding / warning，并要求产品或开发者确认新文案
i18n hygiene 修复边界：不得为了消除重复 value、未引用 key 或 common 抽取 warning 改文案值；只能复用既有 key、调整 key 引用、合并重复 key、删除确认失效 key，或保留相同文案值并说明原因
临时兼容旧字段必须标记 @field-contract-compat source=... alias=... remove_by=yyyy-mm-dd，带废弃计划和测试；QA 报告和 repo-hygiene 必须把它作为 warning 暴露
命中过度抽象、无用代码、空转封装、死代码或无意义 helper / manager / utils 时，加载 references/maintainability-dead-abstraction.md；只能基于调用方、边界、运行路径或历史证据输出 finding / warning
命中碎片化拆分、微型私有方法、业务流程连贯性下降、静默 fallback、默认值兜底、吞错、绕过逻辑或无语义防御代码时，必须使用本文件 Code Acceptance Checks 和 references/anti-patterns.md 归类；未经用户确认不得直接修复
热点修改复盘必查：高频文件、提交意图、反复修改原因、缺失的前置判断规则，以及应更新的 skills / AGENTS / scripts/node 门禁；报告重点是预防下一次 AI 返工，不是只列业务代码修复建议
评估范围命中前端页面、导航、样式、共享壳层或第三方组件覆写时，必须加载 references/frontend-quality-gates.md
评估范围命中前端页面运行态、受保护页面、路由跳转、浏览器截图或控制台证据时，优先运行 node scripts/node/page-debug.js
评估范围命中前端样式边界时，优先读取 node scripts/node/check-style-boundary.js ... 的运行结果；它只说明边界/扩散是否通过，不直接说明泛 UI 质量
评估范围命中共享 console API DTO、style-boundary mock、settings / agent-flow 的 model provider consumer 时，必须检查 node scripts/node/cli/test-contracts.js 或等价四条定向 contract consumer vitest，并确认 verify-repo 已包含该 gate
评估范围命中前端 i18n/、插件 i18n/、语言切换或 UI 文案抽取时，必须运行或读取 node scripts/node/tooling.js i18n-hygiene
没有运行时证据时，前端样式结论默认降级为受限结论
只要评估范围涉及后端 API、状态入口、插件边界、runtime、Resource Action Kernel、HostExtension registry 或 route / service / repository / domain / mapper 分层，就必须加载后端专项检查
后端任务必查：已确认验收预期、三平面、接口包装、认证 / CSRF / ACL、状态写入口、接口返回结构和值正确性、过期 / 禁用 / 缺失状态、HostExtension / RuntimeExtension / CapabilityPlugin 边界、HostExtension manifest contribution、pre-state infra provider、route/worker/migration registry、storage-durable/postgres 内 storage-postgres 的 repository/mapper 拆分、storage-durable / storage-object 边界、workspace/system 命名面、SYSTEM_SCOPE_ID、runtime scope_id、无 legacy alias、验证命令、API evidence 与 blast radius
Provider / 上游 runtime 错误属于透传 contract：QA 不得把 provider stdout / stderr / upstream error 原样进入 RuntimeContract / API response 误判为泄漏或要求脱敏；应检查宿主是否改写、截断、翻译、吞掉或泛化上游信息，导致 provider / 协议排障信息损失
后端范围命中 Rust 代码时，必须额外检查类型不变量、错误边界、状态方法、事务、幂等、async 阻塞、锁跨 await、数据库约束和 Rust 质量门禁
Rust 后端验收必须核对 completion self-check；缺少证据时对应项只能写 未验证，不能下通过结论
同一工作区内执行后端 cargo 验证命令时默认串行，不要为了加速 QA 并发启动多条 cargo test / check / clippy 导致锁等待和结论失真
验证预算由 gate lane 决定：开发后验收用最小证据链和早停；PR 门禁用 CI / gate DAG / artifact；项目体检用全量维度覆盖、风险热力图和轮转深挖
前端层级、入口、L0 / L1 / L2 / L3 问题：联动 frontend-logic-design
后端契约、状态入口、边界污染问题：联动 backend-development
项目体检发现非硬性维护问题时，联动 problem-framing 输出现状、方向、风险收益和建议；硬性门禁失败才进入质量回归修复
无法验证时必须明确写：未验证，不下确定结论

Implementation

Mode selection and session bias: references/modes.md
Gate lane model and resource budgets: references/gate-lanes.md
Repository quality gate routing: references/repo-quality-gates.md
I18n hygiene gate: references/i18n-hygiene-gate.md
Quality gate watch scenarios: references/quality-gate-watch.md
Hotspot prevention review: references/hotspot-prevention.md
Maintainability / dead abstraction checks: references/maintainability-dead-abstraction.md
Task-scoped checks: references/task-mode-checklist.md
Full-project checks: references/project-evaluation-checklist.md
Frontend quality gates: references/frontend-quality-gates.md
Route-scoped runtime evidence: node scripts/node/page-debug.js snapshot|open ...
Backend regression and API evidence steps: references/backend-regression-steps.md
Authenticated backend API evidence: node scripts/node/tooling.js api-debug [METHOD] <api-path-or-url> ...
Rust backend quality checks: references/rust-backend-quality-gates.md
Report output: references/report-template.md
Severity rules: references/severity-rules.md
Anti-patterns: references/anti-patterns.md

Common Mistakes

把 QA 当成修复流程
把开发后验收、PR 门禁和项目体检混成同一套重门禁
项目体检被当前错误脚本、最新日志或单个 artifact 锚定，跳过质量维度矩阵
没有证据就下结论
把代码审查写成 QA 报告
小任务也直接上全量审计
把 beta / CI / 专门质量工作区应承接的全局门禁拉回当前本地开发分支
只挑视觉问题，不看契约和状态
只看当前改动点，不看被影响的其他消费者
后端接口验收只报告 cargo / clippy 通过，没有对照预期 response、认证态、状态副作用或错误 shape 的证据
为了通过 QA、i18n hygiene 或视觉一致性检查而改用户可见文案值
把 maintainability warning 当成已授权清理，未经用户同意就删除或重构
把静默 fallback、默认值兜底、吞错或无语义防御代码当成稳定性改进
把完整业务流程拆成多个只调用一次的小函数，导致 QA 只能靠跳转拼回主路径
只检查功能是否跑通，不检查变更是否越过已确认范围或破坏整体边界
后端评估仍沿用旧术语，忽略 workspace/system、SYSTEM_SCOPE_ID、runtime scope_id、HostExtension / RuntimeExtension / CapabilityPlugin、Resource Action Kernel 和新质量门禁