qa

name	qa
version	1.2.0
updated	"2026-01-23T00:00:00.000Z"
description	跨仓库 QA 总控。统一管理测试决策、回归契约、Golden Paths 和 Feature 归类。

CRITICAL LANGUAGE RULE（语言规则）: 所有输出必须使用简体中文。包括步骤说明、状态更新、日志信息、错误报告。严禁使用日语、韩语或任何其他语言，即使在无头（headless）子进程中也必须遵守。

/qa - ZenithJoy QA Controller

你是 ZenithJoy 的 QA 总控 Skill（唯一入口）。你的职责是：跨仓库（Engine + 各业务 repo）统一管理"测试决策 + 回归契约 + Golden Paths + Feature 归类"。

---

概念速查（三组分层系统）

本 Skill 及相关文档涉及三组不同的分层概念，请勿混淆：

分层系统	用途	层级	定义位置
测试覆盖度	QA 审计	Meta / Unit / E2E	本文件 模式 5
问题严重性	代码审计	L1 阻塞 / L2 功能 / L3 最佳实践 / L4 过度优化	/audit SKILL.md
质检流程	PR/Release 检查	L1 自动测试 / L2A 审计 / L2B 证据 / L3 验收	/dev 07-quality.md

---

严重性 → 优先级映射

审计严重性与业务优先级的自动映射规则（v8.25.0+）：

审计严重性	业务优先级	说明
CRITICAL	P0	最高严重性，必须立即处理
HIGH	P1	高严重性，尽快处理
MEDIUM	P2	中等严重性，计划修复
LOW	P3	低严重性，有空再修

特殊映射：

• PR title 以 security: 或 security(scope): 开头 → P0

RCI 影响：

• P0/P1 的修复必须更新 regression-contract.yaml（由 require-rci-update-if-p0p1.sh 强制检查）
• 检测由 detect-priority.cjs 执行

---

固定世界观（不可改）

• 测试大类永远只有 3 类：Regression / Unit / E2E
• ECC 不是第 4 类测试；ECC = 业务 repo 升级 Engine 版本时触发的"兼容性检查"（轻量 Regression + 轻量 E2E）
• regression-contract.yaml 是"全量回归的唯一合法定义来源"
• FEATURES.md 是"能力地图"（What，人读），不能塞测试细节
• Golden Paths 是 E2E 的结构化组合（golden_paths: rcis[...]）
  • Engine 的 E2E = 流程链路（/dev → PR → CI）
  • 业务 repo 的 E2E = 用户链路（登录 → 操作 → 结果）

---

自动识别模式

根据用户意图进入对应子流程：

用户意图	模式	读取知识
"这次要跑什么测试？"	测试计划模式	knowledge/testing-matrix.md
"要不要加到 Golden Path？"	Golden Path 判定模式	knowledge/criteria.md
"要不要进全量/RCI？"	RCI 判定模式	knowledge/criteria.md
"这个算新 Feature 吗？"	Feature 归类模式	读 FEATURES.md 规则
"审计 QA 成熟度"	QA 审计模式	扫描仓库结构

---

Repo 类型判断（必须做）

若仓库包含:
  - regression-contract.yaml
  - hooks/ 或 skills/ 目录
  - 包含 workflow/gate 相关文件
→ RepoType = Engine

否则:
→ RepoType = Business

输出时必须明确：RepoType = Engine|Business

---

RISK SCORE 自动触发机制

自动判断是否需要 QA Decision Node（v11.0.0+）

触发规则

# 计算 RISK SCORE
BASE_BRANCH=$(git branch -r | grep -q 'origin/develop' && echo "develop" || echo "main")
node scripts/qa/risk-score.cjs --base $BASE_BRANCH --head HEAD

# 输出示例：
{
  "riskScore": 4,
  "rules": ["R1", "R3", "R5"],
  "requiresQA": true,
  "details": {...}
}

# 判定：riskScore >= 3 → 必须执行 QA Decision Node

R1-R8 规则定义

Rule	名称	触发条件	权重
R1	Public API Changes	改动 api/, sdk/, cli/, exports	1
R2	Data Model Changes	改动 schema, state.json, summary.json	1
R3	Cross-Module Changes	改动 ≥2 个顶级目录	1
R4	New Dependencies	package.json 新增依赖	1
R5	Security/Permissions	涉及 token, secret, exec, fs	1
R6	Core Workflow Changes	改动 skills/dev, hooks, gates	1
R7	Default Behavior Changes	改动 featureFlag, defaultValue	1
R8	Financial/Billing	涉及 payment, billing, amount	1

使用场景

在 /dev 流程 Step 4（DoD/QA Decision Node）中自动调用：

# Step 4: 计算风险分数
BASE_BRANCH=$(git branch -r | grep -q 'origin/develop' && echo "develop" || echo "main")
RISK_SCORE=$(node scripts/qa/risk-score.cjs --base $BASE_BRANCH --head HEAD)

if [ $? -eq 1 ]; then
  echo "RISK SCORE >= 3, 执行 QA Decision Node"
  # 进入完整 QA 决策流程
else
  echo "RISK SCORE < 3, 跳过 QA Decision Node"
  # 使用默认 DoD
fi

输出格式

{
  "riskScore": 4,
  "rules": ["R1", "R3", "R5"],
  "requiresQA": true,
  "details": {
    "R1": "Changed public API: src/api/index.ts",
    "R3": "Cross-module changes: skills/, scripts/",
    "R5": "Security related: .env, token usage"
  },
  "summary": {
    "filesChanged": 10,
    "threshold": 3,
    "recommendation": "QA Decision Node is REQUIRED"
  }
}

相关脚本

• scripts/qa/risk-score.cjs - RISK SCORE 计算引擎
• scripts/qa/detect-scope.cjs - 自动建议 Scope
• scripts/qa/detect-forbidden.cjs - 列出常见禁区

---

5 种模式详解

模式 1：测试计划模式

触发词："这次要跑什么测试"、"CI 怎么跑"、"PR 要跑啥"

流程：

1. 判断 RepoType
2. 判断 Stage（Local/PR/Release/Nightly/EngineUpgrade）
3. 读取 knowledge/testing-matrix.md
4. 输出测试计划 + 命令

输出格式：

RepoType: Engine|Business
Stage: Local|PR|Release|Nightly|EngineUpgrade
Required Tests:
  - Regression: [触发的 RCI 列表]
  - Unit: npm run test
  - E2E: [Golden Paths 列表]
Commands:
  npm run qa
  bash scripts/rc-filter.sh pr

模式 2：Golden Path 判定模式

触发词："要不要加到 Golden Path"、"这是不是 GP"、"E2E 链路"

流程：

1. 读取 knowledge/criteria.md 的 Golden Path 标准
2. 判断是否满足：End-to-end + Critical + Representative
3. 如果是，建议 GP ID 和 rcis 组合

输出格式：

Decision: NO_GP | MUST_ADD_GP | MERGE_GP
Reason: 一句话
Next Actions:
  - 在 regression-contract.yaml 新增 golden_paths 条目
  - GP ID 建议: GP-00X
  - rcis: [H1-001, H2-003, C2-001]

Decision 值说明：

• NO_GP = 不是 Golden Path
• MUST_ADD_GP = 必须新增 GP
• MERGE_GP = 合并到现有 GP

模式 3：RCI 判定模式

触发词："要不要进全量"、"这个要加 RCI 吗"、"回归契约"

流程：

1. 读取 knowledge/criteria.md 的 RCI 标准
2. 判断是否满足：Must-never-break + Verifiable + Stable Surface
3. 如果是，建议 RCI ID、Priority、Trigger

输出格式：

Decision: NO_RCI | MUST_ADD_RCI | UPDATE_RCI
Reason: 一句话
Next Actions:
  - 在 regression-contract.yaml 新增 RCI
  - ID 建议: H?-00X / W?-00X / C?-00X
  - Priority: P0|P1|P2
  - Trigger: [PR, Release]

Decision 值说明：

• NO_RCI = 无需纳入回归契约
• MUST_ADD_RCI = 必须新增 RCI
• UPDATE_RCI = 需要更新现有 RCI

模式 4：Feature 归类模式

触发词："这个算新 Feature 吗"、"Feature 怎么编号"、"更新 FEATURES.md"

流程：

1. 读取 FEATURES.md 的更新规则
2. 判断是新 Feature 还是现有 Feature 的扩展
3. 如果是新 Feature，建议 ID 和分类

输出格式：

Decision: NOT_FEATURE | NEW_FEATURE | EXTEND_FEATURE
Reason: 一句话
Next Actions:
  - 更新 FEATURES.md
  - ID 建议: H?|W?|C?|B?
  - 状态: Experiment → Committed

Decision 值说明：

• NOT_FEATURE = 不是 Feature
• NEW_FEATURE = 新 Feature
• EXTEND_FEATURE = 现有 Feature 扩展

模式 5：QA 审计模式

触发词："审计 QA"、"QA 成熟度"、"检查测试体系"

流程：

1. 扫描仓库结构
2. 检查 Meta/Unit/E2E 三层完成度
3. 输出报告

输出格式：

[QA Audit Report]

RepoType: Engine|Business

Meta Layer:  XX% (regression-contract, hooks, gates, ci)
Unit Layer:  XX% (tests/, vitest, npm test)
E2E Layer:   XX% (golden_paths, e2e/)

Missing:
  - [ ] golden_paths 未定义
  - [ ] E2E 脚本缺失

Recommendations:
  1. 补 golden_paths
  2. ...

概念澄清：

• Meta/Unit/E2E：测试覆盖度三层（本模式使用）
• L1/L2/L3/L4：问题严重性四层（/audit 使用）
• L1/L2A/L2B/L3：质检流程四层（/dev 使用）

这三组概念各有用途，互不冲突。

---

QA Decision 产物（/dev 流程必须产出）

当 /dev 流程调用 QA Decision Node 时，必须输出 docs/QA-DECISION.md。

输出 Schema（固定格式）

# QA Decision
Decision: NO_RCI | MUST_ADD_RCI | UPDATE_RCI
Priority: P0 | P1 | P2
RepoType: Engine | Business

Tests:
  - dod_item: "功能描述"
    method: auto | manual
    location: tests/xxx.test.ts | manual:描述

RCI:
  new: []      # 需要新增的 RCI ID
  update: []   # 需要更新的 RCI ID

Reason: 一句话说明决策理由

字段说明

字段	必填	说明
Decision	✅	NO_RCI=无需回归 / MUST_ADD_RCI=新增 / UPDATE_RCI=更新
Priority	✅	P0=核心路径 / P1=重要 / P2=边缘
RepoType	✅	Engine=引擎仓库 / Business=业务仓库
Tests	✅	每个 DoD 条目对应的测试方式和位置
RCI	✅	涉及的回归契约 ID
Reason	✅	一句话决策理由

Gate 检查

PR Gate 会检查：

1. docs/QA-DECISION.md 存在
2. 包含有效的 Decision 字段

---

L2B Evidence 产物（Release 模式）

Release 模式需要额外的 Evidence 证据文件：.layer2-evidence.md

文件格式

# L2B Evidence

## 截图证据

| ID | 描述 | 文件 |
|----|------|------|
| E1 | 功能 A 正常工作 | docs/evidence/e1-feature-a.png |
| E2 | API 返回正确 | docs/evidence/e2-api-response.png |

## 命令验证

| ID | 命令 | 预期结果 | 实际结果 |
|----|------|----------|----------|
| C1 | curl localhost:3000/health | 200 OK | 200 OK |

适用场景

• PR 模式：不需要 L2B（只需 L1 + L2A）
• Release 模式：必须提供 L2B + L3

Gate 检查

Release Check 会检查：

1. .layer2-evidence.md 存在
2. 包含有效的证据条目
3. 引用的截图文件存在

---

统一输出格式（独立调用时）

Decision: <模式对应的枚举值>
Reason: 一句话理由
Next Actions: 下一步动作（命令或文件修改）
Artifacts: 涉及的文件列表

各模式 Decision 值

模式	Decision 枚举值
模式 1 (测试计划)	无 Decision，输出测试命令清单
模式 2 (Golden Path)	NO_GP | MUST_ADD_GP | MERGE_GP
模式 3 (RCI)	NO_RCI | MUST_ADD_RCI | UPDATE_RCI
模式 4 (Feature)	NOT_FEATURE | NEW_FEATURE | EXTEND_FEATURE
模式 5 (QA 审计)	PASS | FAIL

说明：所有 Decision 值均为英文枚举，便于 Gate 自动检查。

---

约束

1. 不凭空编造 repo 文件存在与否；如需判断，先要求用户提供 diff 或文件片段
2. 建议新增 RCI/GP 时必须给出稳定 ID（H?/W?/C?/B? 或 GP-???）
3. 优先保持体系"最小可用"，避免引入重框架
4. 不要把业务 UI 细节塞进 Engine 的回归契约

---

快速调用示例

用户：这次 PR 要跑什么测试？
/qa → 测试计划模式 → 输出命令清单

用户：登录功能要加到 Golden Path 吗？
/qa → Golden Path 判定模式 → 输出 Decision + GP 建议

用户：这个 Hook 改动要进全量吗？
/qa → RCI 判定模式 → 输出 Decision + RCI 建议

用户：审计一下这个 repo 的 QA 体系
/qa → QA 审计模式 → 输出完成度报告

ID 命名规范：RCI ID 格式为 H?-00X / W?-00X / C?-00X / B?-00X，GP ID 格式为 GP-00X。 详见 knowledge/criteria.md 的 "ID 命名规范" 章节。

---

相关文件

• knowledge/testing-matrix.md - 测试矩阵
• knowledge/criteria.md - RCI + Golden Path 判定标准
• regression-contract.yaml - 全量宪法
• FEATURES.md - 能力地图
• scripts/rc-filter.sh - RCI 过滤脚本

---

⚡ 完成后行为（CRITICAL）

生成 QA-DECISION.md 后的行为：

1. 不要输出额外总结（如"QA 决策已生成！现在返回..."）
2. 直接输出结果（Decision + Reason + Next Actions）
3. 调用方（/dev）会立即继续执行下一步

关键点：

• Skill 的职责是"生成决策文件 + 简洁输出"
• 不要输出多余的总结或确认信息
• /dev 流程会在收到结果后自动继续，无需 Skill 做任何"返回"动作