@ganziliang/zhizh-pi-qa-agent

pi 原生的端到端 QA 验收扩展。把一个「验收 / 回归 / 质量检查」请求拆成有门禁、可追溯的阶段：

初始化 → 环境体检 → 上下文收集 → 风险分析 → 用例设计
                    ↓
        ★ 人工门禁：用户确认用例（唯一需要人介入的一步）
                    ↓
        脚本生成 → 执行与报告 → G5 独立代码审查 → 最终报告

只支持 pi。不依赖 Claude Code / Codex，也不写它们的配置文件。

---

为什么是扩展而不是一堆 skill

上游 skill 做法	本扩展做法
用提示词说「确认前不写测试代码」	tool_call 真的拦截写 tests/**（可用 /qa:unlock 临时放行）
靠模型记住 7 个 skill 的阶段顺序	阶段由文件事实推导，qa_status 直接告诉你下一步
手抄 30+ 条 PowerShell 命令	引擎命令目录内建在工具描述里，参数走 schema
「等待用户确认」靠对话猜	qa_confirm_cases / /qa:confirm 弹出真的确认框，用例内容一变确认自动失效
6 个 stage skill 各自维护职责散文	6 个 .pi/agents/qa-*.md 子代理，按阶段按需加载

---

安装

pi install npm:@ganziliang/zhizh-pi-qa-agent

装好后新开一个 pi 会话，输入 /qa 看帮助。

前置要求：

依赖	必需性	说明
Python 3	必需	确定性引擎（校验 / 门禁 / 报告渲染 / 用例索引）。没有 Python 时扩展仍会加载，但会提示。可用环境变量 QA_AGENT_PYTHON 指定解释器（例如 py -3）。
git	建议	没有 git 时 diff 类上下文、ensure-branch、atomic-commit 不可用
node / npm / npx	按需	前端与 Playwright E2E 需要
Maven / JDK	按需	Java 项目需要

---

第一次使用：/qa:init

/qa:init 是一个 4 步向导，只会问你「只有人知道」的问题：

1. 确认探测结果 —— 语言/框架/模块、测试套件与命令、被测服务与端口、MySQL MCP。
2. 模块名 —— 用例固化文件名与报告归档前缀（默认从分支名推导）。
3. 运行模式 —— 验收 / 回归 / 增量。
4. MySQL MCP —— 有多个候选时才问你选哪个（见下）。

会生成 / 补齐什么

文件	是否入库	内容
.qa-agent/config/qa-agent.config.yaml	入库	gate 命令、模型与网关、覆盖率阈值、修复路径约束、MCP server 名
.qa-agent/config/pi-extension.json	入库	模块名、运行模式、门禁开关与受保护路径、MCP server 名、界面噪音开关（ui）
.qa-agent/config/env.shared	入库	团队共享的非敏感环境值（服务地址、账号名、MySQL 连接信息）
.qa-agent/config/accounts.json	入库	测试账号清单（只存环境变量名）
.qa-agent/config/services.json	入库	被测服务清单 + dir / startCmd / readySignal / healthUrl
.qa-agent/profiles/project-test-profile.json	入库	测试画像（套件、测试文件、每个 gate 的命令）
.qa-agent/fixtures/*.example.*	入库	脱敏模板
.qa-agent/references/*.md	入库	用例 schema、spec-task 规范、门禁语义、报告规范、Playwright 取证协议（每次 init 随包同步）
.qa-agent/risk-rules/README.md	入库	项目专用风险规则说明（自己往里写业务不变量）
.qa-agent/local/.env	不入库	本地密钥与覆盖值
.pi/agents/qa-*.md	入库	6 个阶段子代理
目标项目的规则载体（探测命中：.claude/rules/e2e-and-delegation.md、.cursor/rules/*.mdc、AGENTS.md …）	入库	「E2E 提速与子代理委派纪律」：证据档（关重试）、快失败、派子代理前的预检与任务模板；并在 agent 入口文件里挂一行引用
.qa-agent/.gitignore + 根 .gitignore 片段	入库	运行时产物忽略规则

幂等性：已存在的文件默认不覆盖；环境变量模板按 key 增量补齐，你填好的值不会被改掉。要强制同步用 /qa:init --force。

协作规则写到哪：探测目标项目的约定，不发明新约定

模型不跨会话记忆，所以纪律必须落到目标项目自己读得到的位置。初始化时按下面的优先级探测，命中哪个写哪个：

优先级	命中条件	写入位置
1	.claude/rules/ 目录存在	.claude/rules/e2e-and-delegation.md
2	.cursor/rules/ 目录存在	.cursor/rules/e2e-and-delegation.mdc
3	.github/instructions/ 目录存在	.github/instructions/e2e-and-delegation.instructions.md
4	.windsurf/rules/ 目录存在	.windsurf/rules/e2e-and-delegation.md
5	AGENTS.md / CLAUDE.md / claude.md 存在（无规则目录）	直接追加一个受标记管理的段落
6	都没有	建 .claude/rules/e2e-and-delegation.md

• 内容是按本项目探测结果生成的（文末带真实的 e2e 运行/列举命令与测试目录）；
• 规则是独立文件时，会在 AGENTS.md（或 CLAUDE.md）里挂一行引用；入口文件都没有才新建一个只含引用段的 AGENTS.md；
• 幂等：本包写入的段落用 <!-- zhizh-pi-qa-agent:rule begin (e2e-and-delegation) --> 包裹，重跑只替换标内内容；
• 同名文件已存在但不是本包写的 → 不覆盖，只在结果里提醒（要用 force=true 显式覆盖）；
• 不想写规则：qa_setup / /qa:init 传 installDelegationRule=false（对应 SetupOptions.installDelegationRule）。

必须填的东西（只有 1 项是必需的）

/qa:init 结束时会明确列出来。唯一必填项是：

# .qa-agent/local/.env
QA_AGENT_LLM_API_KEY=<公司 LLM 网关的 key>

它只影响 /qa:review（三模型交叉审查用例）。没填也不会阻断其它阶段，只是用例少了一道交叉验证。

按需填写的条目（缺失时对应能力退化，不报错）：

条目	作用
QA_USER_USERNAME / QA_USER_PASSWORD	被测系统的测试账号（密码只进 local/.env）
QA_ADMIN_USERNAME / QA_ADMIN_PASSWORD	后台测试账号（探测到 admin 类目录时才会生成）
QA_MYSQL_HOST / QA_MYSQL_PORT / QA_MYSQL_DATABASE / QA_MYSQL_USER	数据核对用的连接信息（QA_MYSQL_PASS 只进 local/.env）
QA_API_BASE_URL / QA_WEB_BASE_URL 等	探测出的服务地址，团队成员可在 local/.env 覆盖

模板永远不会遗漏条目：envCatalog() 是条目清单的唯一来源，向导、.env 模板、env.example、/qa:doctor 都从它生成。

---

MySQL MCP：复用，不新建

需求很明确：成员本机/本项目已经有在用的 MySQL MCP server 配置时，用回它的配置。

本扩展的行为：

• 只读 扫描 .mcp.json、.pi/mcp.json、~/.pi/agent/mcp.json，以及 pi 运行时已连接的 MCP（工具名前缀 mcp__*）。
• 把看起来是 MySQL 的 server 脱敏后列出来（password / token / key 之类的值一律替换成 ***）。
• 你选中的 server 只写进 .qa-agent/config/pi-extension.json 的 mysqlMcpServerName。
• 绝不写 .mcp.json、.pi/mcp.json、settings.json，也绝不新建 server。扩展源码里 init / init-config / init-project / install-mysql-mcp 这些上游命令被显式禁用（调用会直接报错）。

没有找到任何 MySQL server 时：向导会提示你「本扩展不会替你创建（避免覆盖团队配置）」，其余阶段照常可用，只是涉及数据库核对/测试数据准备的用例会缺少证据来源。配好之后重跑 /qa:init 会自动识别。

---

命令

命令	作用
/qa	帮助 + 当前状态
/qa:init	交互式初始化/修复（--module --run-type --mysql-mcp --force --yes）
/qa:doctor	环境体检（--services 额外探测服务可达性）
/qa:status	阶段、缺失项、下一步
/qa:context	阶段 0：收集上下文 + 索引存量用例
/qa:risk	阶段 1：风险骨架（--paths 限定扫描范围）
/qa:cases	阶段 2：生成用例 + 确认页（--incremental）
/qa:confirm	★ 确认用例（唯一人工门禁）
/qa:tasks	阶段 3：spec-task + 脚本（--dev-mode 用金字塔比例）
/qa:run	阶段 4：执行 + 分类失败 + 门禁（--regression）
/qa:review	阶段 5：G5 独立代码审查
/qa:report	阶段 6：三连门禁 + 最终报告 + 时间戳归档
/qa:unlock <原因> / /qa:lock	临时放行/恢复写测试代码的门禁
/qa:agents	安装/更新 .pi/agents/qa-*（--force）

工具（供模型调用）

工具	作用
qa_status	只读：阶段、就绪、缺失项、产物清单
qa_agent	调用确定性引擎（35 个命令，含参数说明；初始化和安装类命令被禁用）
qa_setup	非交互初始化/修复（幂等，dry_run 可预览）
qa_confirm_cases	弹确认框请用户确认用例；只有用户点了确认才会固化并解锁门禁

---

用例确认门禁（本扩展最实用的部分）

默认情况下，在用例被用户确认之前，以下写入会被直接拦截：

tests/**   test/**   e2e/**   src/test/**
**/*.spec.ts  **/*.spec.js  **/*.spec.mjs
**/*.test.ts  **/*.test.js  **/*.test.mjs  **/*.test.tsx

包括用 bash 重定向绕道的写法（echo x > tests/a.spec.ts）。

• 写 .qa-agent/** 永远放行。
• 跑测试（npx playwright test ...）永远放行——门禁管的是「写」，不是「跑」。
• 用例内容一变，已确认状态自动失效（按内容指纹判断），门禁重新生效。
• 你在调试时可以用 /qa:unlock 临时调试登录流程 放行（原因会记录），完事 /qa:lock 恢复。

受保护路径可以在 .qa-agent/config/pi-extension.json 里改：

{
  "caseGate": {
    "enabled": true,
    "protectedPaths": ["tests/**", "**/*.spec.ts"]
  }
}

界面噪音同样在这个文件里控制（默认都开，只有显式关闭才生效）：

{
  "ui": {
    "widget": false,
    "status": false
  }
}

• ui.widget：true（默认）输入框上方三行进度；"compact" 压成一行；false 完全不显示。
• ui.status：false 时不再占用底部状态栏的 QA <阶段>。
• 关掉之后仍然可以随时用 /qa:status（或 qa_status 工具）看阶段与缺失项。

---

三种运行模式

模式	触发	行为
验收	默认	全流程：上下文 → 风险 → 用例（需确认）→ 脚本 → 执行 → 审查 → 报告
回归	/qa:run --regression	不重新收集上下文、不重新设计用例、不重新生成脚本；每个 task 都必须重新执行并产生新证据
增量	/qa:cases --incremental	已有用例不动，只针对新场景走完整流程

---

报告

• .qa-agent/reports/latest-report.html —— 始终指向最后一次运行
• .qa-agent/reports/<module>-<runType>-<YYYYMMDD-HHMMSS>.html —— 时间戳归档副本

最终判定严格引用 readiness-check.json：就绪 / 有条件就绪 / 未就绪 / 未完成。 completion-check 通过但 G5 审查有 blocking 发现时，报告必须是未就绪——不允许「用例都过了就说 Ready」。

---

目录结构（本包）

src/                    扩展本体（TypeScript，jiti 直接加载）
  index.ts              注册工具/命令/事件
  engine.ts             引擎封装 + 命令目录（CLI 参考的唯一真相）
  detect.ts             通用项目探测（Maven/npm/Playwright/pytest/Go）
  scaffold.ts           初始化落地（幂等）
  mcp-mysql.ts          MCP 只读发现与复用选择
  gates.ts              用例确认门禁
  status.ts             阶段/就绪/缺失项推导
  doctor.ts             环境体检
  templates.ts          所有模板（条目清单的唯一来源）
  wizard.ts             /qa:init 向导
  ui.ts                 面向用户的中文排版
agents/                 6 个阶段子代理（安装到项目 .pi/agents/）
engine/scripts/         vendored 确定性引擎（见 PATCHES.md）
engine/assets/          报告模板、E2E fixture 模板
engine/references/      schema/门禁/报告规范（安装到 .qa-agent/references/）
scripts/self-test.mjs   自检

---

开发与自检

npm install --no-save typescript @types/node   # 仅类型检查需要
npm run verify        # = typecheck + self-test
npm run typecheck     # 用 pi 安装目录里的 peer 类型做一次完整类型检查
npm run self-test     # 假仓库里跑通「加载 → 初始化 → 状态 → 门禁 → 引擎调用」
python engine/scripts/qa_agent.py self-test    # 引擎自身自检

.qa-agent/references/*.md 由包内文件在每次 /qa:init 时同步（会覆盖本地修改）—— 需要改规范请改 engine/references/ 并重新发版，避免各项目规范漂移。

常见问题：

现象	原因 / 处理
提示「未找到 Python 3」	装 Python 3，或 set QA_AGENT_PYTHON=py -3
/qa:review 失败	QA_AGENT_LLM_API_KEY 没填；只影响用例交叉审查
门禁一直拦你	用例没确认（/qa:confirm），或用例改过导致确认失效；调试用 /qa:unlock <原因>
测试画像为空	探测不到测试目录时，手工补 .qa-agent/profiles/project-test-profile.json
服务不可达	按 .qa-agent/config/services.json 的 dir/startCmd 启动，再 /qa:doctor --services
MCP 没识别到	扩展不读你 pi 配置以外的来源；确认 server 名里含 mysql/db，或 /qa:init --mysql-mcp <名字> 显式指定

升级引擎（上游 skill 更新后）：

cp ~/.claude/skills/quality-assurance-agent/scripts/qa_agent.py engine/scripts/qa_agent.py
# 重新应用 PATCHES.md 里标记的改动，然后跑 self-test

---

安全说明

• 扩展不会启动任何后台进程；只在命令/工具被调用时执行 Python 与外部命令。
• 不打印密钥、token、数据库口令；MCP 配置展示前一律脱敏。
• 不改动 MCP 配置、不动 Claude/Codex 配置、不自动 git commit（atomic-commit 需要显式调用且受 repair.allowedPaths 约束）。