quality-guardian

name	quality-guardian
description	运行并解读 lint、类型检查、测试等质量门时使用。它不只是执行命令，还要根据变更范围选择最小充分检查、分析失败原因，并给出是否允许继续提交或发布的判断。用户提到 lint、typecheck、tests、quality gate、验证改动时都应触发。
metadata	{"internal":true}

Quality Guardian

铁律：不要把“命令跑过了”当成质量结论。必须解释跑了什么、为什么跑、失败在哪里、是否允许继续。

工作流

• Step 1: 评估所需检查 ⚠️ REQUIRED
  • 1.1 根据改动类型判断要跑 lint、test、typecheck 还是组合检查。
  • 1.2 区分快速验证和全量验证。
• Step 2: 执行质量门 ⚠️ REQUIRED
  • 2.1 优先使用 package.json 中真实存在的脚本。
  • 2.2 如果没有精细脚本，再说明为什么只能跑更重的检查。
  • 2.3 ⚠️ 绕过 pnpm run 执行质量门：pnpm run lint 会触发依赖状态检查 → 自动 pnpm install → 可能因 ERR_PNPM_IGNORED_BUILDS 退出码 1 而失败，掩盖真实的 lint 结果。正确做法是直接调用二进制：

    & "node_modules\.bin\eslint.cmd" .
    & "node_modules\.bin\vitest.cmd" run
    

    或者用 npx <binary>（如果二进制支持 npx 模式）。避免在执行质量门时引入不必要的依赖检查副作用。
• Step 3: 分析结果
  • 3.1 提炼失败文件、错误类别和根因，而不是整段贴日志。
  • 3.2 明确这是阻塞问题、建议问题，还是外部已知问题。
• Step 4: 给出放行结论
  • 4.1 明确是否允许进入提交、发布或下一阶段。
  • 4.2 如果未跑某些检查，说明原因和残余风险。

常见检查

• pnpm lint
• pnpm lint:md
• pnpm test

项目特化提示

• 如果仓库提供 typecheck 或等价的类型检查脚本，应纳入质量门；如果没有，必须明确说明当前缺少该层验证。
• 如果全量测试成本过高，优先运行与改动范围直接相关的测试文件或测试集。
• 输出结论时要把“脚本不存在”和“脚本通过”严格区分。

反模式

• 不看 package.json，臆造并不存在的脚本。

• 把失败日志原样倾倒给用户，不提炼根因。

• 没跑全量检查却假装“全部通过”。

• 使用 pnpm run 执行 lint/test，触发不必要的依赖状态检查，导致 ERR_PNPM_IGNORED_BUILDS 伪装成质量门失败。

交付前检查

• 已基于变更范围选择质量门。
• 使用的命令都真实存在。
• 已明确失败根因或残余风险。
• 输出包含能否继续下一阶段的判断。