简体中文 | English

qa-skills

让 AI 像资深测试工程师一样工作。

知识 × 工具 × 决策 —— 面向 Claude Code 等 Agent 的测试工程 Skill 框架。
每一个数字，都来自实测。

--- ## 快速开始 ```bash git clone https://github.com/fishzjp/qa-skills.git cd qa-skills ./install.sh # 交互式选择宿主目录（自动检测 ~/.agents/skills 等） ./install.sh --auto # 或全自动安装 ``` 或通过 [skills.sh](https://skills.sh) 跨 Agent 安装（Claude Code / Cursor / Codex / OpenCode 等 50+ 宿主）： ```bash npx skills add fishzjp/qa-skills # 交互式勾选，全装用 --skill '*' ``` **DeepSeek Harness（dsh）用户**：本仓库已打包为 dsh 插件（npm 包 [`dsh-qa-skills`](https://www.npmjs.com/package/dsh-qa-skills)），一条命令安装—— ```bash dsh plugin --profile web add dsh-qa-skills ``` 也可以走文件路径：dsh 原生兼容本仓库格式，装到 `~/.agents/skills/`（`./install.sh --target ~/.agents/skills`）或 `~/.dsh/skills/`，重启 dsh 生效。已在 dsh 0.1.0-rc.8 + deepseek-v4-flash 上完成双路径端到端验证。 > `core` 是共享知识库依赖单元（不可执行任务），安装任一 skill 时必须一并安装，否则引用路径断裂。 装好后对 Agent 说一句： > **帮我测试这个需求：{需求描述 + 仓库地址}** 从需求理解、风险与类型决策，到测试报告——完整流水线就此跑通。只需要其中某个阶段（写用例 / 审查 / 转自动化 / 回归范围）时，直接描述需求即可，无需走完整流水线。卸载：`./uninstall.sh`；手动安装：`cp -r skills/* /`（**core/ 必须一起复制**，各 skill 以相对路径引用它）。验证安装：`ls ` 应见 10 个 skill 目录 + `core/` + `qa-skills.VERSION`。 → [设计文档](https://github.com/fishzjp/qa-skills/blob/main/docs/DESIGN.md) · [决策层设计](https://github.com/fishzjp/qa-skills/blob/main/docs/decision-layer-design.md) · [Skill On / Off 产出对照](https://github.com/fishzjp/qa-skills/blob/main/examples/)

宿主兼容性与降级路径

Skill 是纯 Markdown 指令文件（frontmatter + 相对路径引用），不依赖特定宿主特性： | 宿主 | 安装目录 | 状态 | |------|---------|------| | Claude Code | `~/.claude/skills/` 或 `<项目>/.claude/skills/` | ✅ 主要适配对象，评测基于此 | | 跨宿主共享目录 | `~/.agents/skills/` | ✅ 多 Agent 共读一份，`install.sh` 默认推荐 | | DeepSeek Harness (dsh) | `~/.agents/skills/`、`~/.dsh/skills/` 或 `<项目>/.agents/skills/` | ✅ 实测通过（dsh 原生实现 Anthropic Skills 规范；deepseek-v4-flash 全链路验证：识别 / 触发 / 产出） | | Codex CLI | `~/.codex/skills/` | 🔶 按约定应可用，未系统评测 | | 其他支持 Skills 的 Agent | 各自的 skills 目录 | 🔶 同上 | `qa` 流水线的"阶段间上下文隔离"依赖宿主的子会话 / 子代理能力；宿主不支持时自动退化为顺序会话 + 文件衔接，正确性不受影响（见 [DESIGN.md](https://github.com/fishzjp/qa-skills/blob/main/docs/DESIGN.md) 编排会话模型一节）。`--link` 软链安装随 `git pull` 升级。

## 能力总览 | 你说 | 框架做 | 产出 | |------|--------|------| | "帮我测试这个需求" | `qa` 编排 9 阶段流水线，检查点等你裁决 | 全套测试资产 + 测试报告 | | "根据这份 PRD 写用例" | 代码优先：索取仓库、读实现、审出潜在 Bug 再写 | 双轨用例：markmap（人）+ schema.yaml（机器） | | "这个功能应该怎么测" | Risk Map（评级挂证据）→ 功能域 + 类型域两域决策（十轴全轴必答） | `测试策略.md`（含 type_scope 与专项移交包） | | "审一下这份存量用例" | 独立审查：可测点基准分母 + 覆盖 + 可执行性双线 | 直接修订用例文件 + 审查记录 | | "把用例转成自动化" | Page Object 规范、监听先于操作、自建数据自清理 | 可运行的 Playwright / pytest 代码 | | "这个 Bug 帮我定位一下" | 复现 → 读代码到行 → 影响三面分析 → 回归建议 | Bug 条目（根因 / 证据 / 回归） | `exploratory-testing`（charter 驱动探索）、`api-testing`（接口级）、`bug-analysis`、`regression-testing`（diff → 回归范围）各自独立可用。

测试用例脑图怎么渲染

`测试用例_markmap.md` 是标准 Markdown（markmap 语法）：VS Code 装 [Markmap 扩展](https://marketplace.visualstudio.com/items?itemName=gera2ld.markmap-vscode)、`npx markmap-cli 测试用例_markmap.md` 生成交互式 HTML、或粘贴到 [markmap.js.org/repl](https://markmap.js.org/repl)。

## 能写，更要能执行。 AI 写出的用例常常看似专业、实则无法执行——判定模糊、占位符、无判定时限、虚构入口。 同一个需求，本框架的产出长这样： ```markdown > 前置:运营账号已登录,进入「营销中台 → 券工场 → 活动列表」 - **TC-02-05 到期自动结束** [P1] - 操作步骤: 1. 选一张结束时间为 2 分钟后的已发布券「满100减20-测试」 2. 等待到期 - 预期结果: 到期后 1 小时内状态自动变为「已结束」,超过 1 小时未变判失败 ``` **核心产出标准只有一条：没读过需求、没人讲解的人，拿着文件能直接开工。** 这背后是 `skills/core/executability.md` 的 8 条硬标准；评测中它是一票否决项——不可执行的用例，覆盖再全也计零分。 ## 指令更少，遵循更强。 把方法论、模板、规则全部塞进一个 SKILL.md，Agent 有效遵循的规则反而更少（[Red Hat ACE 实践总结](https://next.redhat.com/2026/07/28/building-skills-for-ai-agents-pitfalls-and-best-practices/)：指令超过 500 行后性能退化）。解法是三层架构： ```text L1 SKILL.md 头部 触发边界：什么时候用、什么时候不用、交给谁 L2 SKILL.md 正文 工作流：每次触发都要走的主干（≤500 行红线） L3 references/ + core/ 方法 / 规则 / 模板：按需加载，工作流步骤里显式引用 ``` SKILL.md 只装流程编排，方法细则全部下沉、按需加载——Agent 每一步只面对当前需要的指令。 ## 会测，更会决定不测什么。 未装 skill 的模型制定测试策略时，在跨两个模型段位的 30 次评测采样中**零显式类型决策**——输出里"提到"性能与安全，却从不决定哪些纳入、测多深、哪些明确不测。提到不等于决策；不可审计的策略等于没有策略。 解法是**类型决策矩阵（决策层）**：性能 / 业务安全 / 可靠 / 并发等十个测试类型**全轴必答**——纳入必须挂信号（G 级信号由脚本扫描并生成预填表）、排除必须留痕（G+S 双清单）、full 档有预算上限，每条决策落盘为机器可校验的 type_scope（V1–V5）。实测：最弱模型类型查全率 0 → **0.88**，需求未提、只存在于代码的可靠性/契约轴 0 → 8/9（详见[实测效果](#实测效果)一节的决策层注）。 ## 工作原理 **文件即流水线状态**——每个阶段产出落盘为文件，下一阶段只消费文件而非会话记忆；长流水线不依赖上下文，中断后新会话读文件续跑： ```text PRD / 代码 │ requirement-analysis ▼ 需求模型.md ·················· ⏸ 澄清检查点 │ test-strategy（风险 → 两域决策） ▼ 测试策略.md（Risk Map + 类型域十轴决策 type_scope）· ⏸ 预算裁决 │ test-case-writing ▼ 测试用例 markmap（给人）+ schema.yaml（给机器） │ test-case-review ▼ ⏸ 执行策略裁决（手动 / Playwright / API） │ automated-e2e-testing / api-testing ▼ 执行产物 + Bug 证据 → bug-analysis → regression-testing ▼ 回归清单.md → 测试报告.md ``` - **证据与风险模型**：每条结论标注证据等级（E0–E4）与状态；风险评级强制挂证据，无证据的评级无效。推导链全程可追溯：证据 → 风险 → 策略 → 用例。 - **类型决策矩阵**：十轴全轴必答，纳入与排除都留痕，full 档有预算上限；G 级信号由脚本扫描成预填表，弱模型从预填表修订、而非从空白生成。 - **人在环路的检查点**：澄清、执行策略、Bug 定性、预算上限四类事项由你裁决，Agent 只提案、不代答；裁决落盘后，后续阶段不得推翻。 > 设计动机与关键决策（为什么是 10 个窄 skill、为什么 markmap 是唯一维护源、为什么评测先于扩容）见 [DESIGN.md](https://github.com/fishzjp/qa-skills/blob/main/docs/DESIGN.md)。 ## 实测效果 在 12 个任务的黄金集上评测：同一模型、同一评测链路，唯一差异是是否注入本框架；数字以异构裁判复评轮为准，如实披露（含反向结果）。完整方法学、原始数据与研究报告在本地评测链路中维护、不随仓库分发；每版 Release 附跨模型增益矩阵快照（[Releases](https://github.com/fishzjp/qa-skills/releases)），On / Off 产出对照见 [examples/](https://github.com/fishzjp/qa-skills/blob/main/examples/)： | 指标 | 无 Skill | 有 Skill | |------|:---:|:---:| | 用例规格符合度 | 0.26 | **0.98** | | E2E 代码真实执行（单任务 × 3 采样） | 0/3 可运行 | 1 全过 + 2×(2/3) | | 植入 Bug 检出率 | — | **75%** | | 产出质量（LLM judge） | 0.70 | **0.76** | | API 代码真实执行通过率 † | **74%** | 52% | | Token 成本 | 1× | 3.3× | > **决策层首轮（2026-08-23，类别性判读，未进正式增益表）**：类型域决策任务（5 任务黄金集，参考答案经双人独立标注复核）在最弱模型（deepseek-v4-flash，n=3，注入式上界口径）上：**无 skill 组零显式类型决策**（宽容口径亦为 0——输出里"提到"了正确类型，但没有逐轴的纳入/排除决策，盲区在决策纪律而非类型知识）；**有 skill 组类型查全率 0 → 0.88**（格式锤复验轮），其中需求未提、只存在于代码的可靠性/契约轴 0 → 8/9。数字待任务扩容与跨模型梯度轮后进正式表。

逐项口径

- **用例规格符合度**（旧称"可执行性"）：编号 / 导读格式 × 内容红线复合，无 judge。差距主要由格式采纳驱动，内容红线层两组基线均近满分；无格式的采样按 0 计（同口径；早期 0.77 为修复前口径，勘误记录见 [CHANGELOG](https://github.com/fishzjp/qa-skills/blob/main/CHANGELOG.md)）；跨两个生成模型复现（0.20→0.99）。 - **E2E 真实执行**：真实浏览器 + 被测应用，无 judge；有 skill 一侧 2 个采样的同一失败测试稳定复现，无 skill 一侧含未产出代码与执行失败两种情况。 - **植入 Bug 检出率**：代码审查类任务；异构裁判口径，同源裁判下为 100%。 - **产出质量**：异构裁判；Δ+6.1pp（95%CI 含零，同源口径下显著）。 - **API 真实执行通过率 †**：如实披露的历史反向结果（74% vs 52%，3 采样口径；早期 87% 为 2 采样均值）。根因已定案并修复（2026-08-24 逐失败归类）：主因是评测任务契约的状态机断裂（创建恒返回待发布、领取要求已发布、契约却无发布路径——题目缺陷而非 skill 缺陷），叠加输出截断与采样退化、登录响应契约缺失；"严断言更易暴露失败"的早期解释经逐点证伪（46 个失败中仅 4 个与断言强度相关，且属超出书面契约的过严断言）。修复后干净复验（契约与截断续写修复、主模型 glm-5.2）：无/有 skill 组 **100% / 99.2%**，差距 0.8pp，反转消除（弱模型段位同向：有 skill 组 0.67 > 0.30）。 - **Token 成本**：如实披露——更好但更贵；口径为总 token 比（任务级均值、含 skill 全量注入）：主模型 glm-5.2 轮 3.3×，弱模型（mimo）轮最高 9.5×（推理开销计入产出侧）；单文件消融实验证明增益不可由"只拿走核心标准文档"替代。

预注册门判定与覆盖增益

预注册门判定：同源裁判 4/7、异构裁判 5/8（两者构成不同，含 G1b 方向翻转）。覆盖类增益（异构裁判）：用例编写任务口径 **+8.7pp**（CI[0.5, 15.4]，显著）、全任务 **+13.2pp**（CI[2.8, 26.3]，显著）、缺陷检出 **+9.7pp**（CI[3.3, 16.4]，显著）——同源裁判口径为 +3.8pp（宽容偏差已量化并勘误，见 [CHANGELOG](https://github.com/fishzjp/qa-skills/blob/main/CHANGELOG.md)）。早期单采样的 +29pp 表观增益经多样本复验证实为噪声。 **口径边界**：评测的注入通道将 skill 全部指令文件预注入（真实宿主为按需加载），"有 skill"一侧的数字是"指令全部在场"的上界——in-situ 探针（n=1）未观测到衰减；成对评审在三种裁判下平局率均超限，胜率指标作废（机制问题）。

## 更多文档 - [DESIGN.md](https://github.com/fishzjp/qa-skills/blob/main/docs/DESIGN.md) —— 设计动机与关键决策 - [决策层设计稿](https://github.com/fishzjp/qa-skills/blob/main/docs/decision-layer-design.md) —— 类型决策矩阵完整设计（十轴 / R1–R6 / V1–V5 / 弱模型机制） - [v2 规划](https://github.com/fishzjp/qa-skills/blob/main/docs/qa-skills-v2.md) —— 演进蓝图与历史决策记录 - [examples/](https://github.com/fishzjp/qa-skills/blob/main/examples/) —— 同一 PRD 的 Skill On / Off 产出对照 - [CHANGELOG.md](https://github.com/fishzjp/qa-skills/blob/main/CHANGELOG.md) —— 版本历史（各版本附增益矩阵快照）

仓库结构

```text skills/ 产品本体（10 个 skill + core 共享知识库） qa/ 编排入口（薄，无领域知识） core/ 共享知识库（SKILL.md 仅作安装依赖单元，不参与任务触发）：evidence / risk-model / executability / testing-principles / report-template / case-format / coverage / schema-extraction / clarify-pattern / test-type-matrix （类型决策矩阵）+ methods/（4 篇设计方法细则）+ scripts/ （Schema 校验器 + 类型信号扫描器）——被多 skill 消费的内容统一在此 requirement-analysis/ test-strategy/ test-case-writing/ test-case-review/ automated-e2e-testing/ api-testing/ exploratory-testing/ bug-analysis/ regression-testing/ docs/ 设计文档（DESIGN / 决策层设计 / v2 规划） examples/ Skill On / Off 产出对照 ``` 评测链路（黄金集 / harness / 单测 / 研究报告）本地维护、不随仓库分发；每版 Release 附跨模型增益矩阵快照（[Releases](https://github.com/fishzjp/qa-skills/releases)）。

## 贡献与社区 - **贡献指南与架构红线**：[CONTRIBUTING.md](https://github.com/fishzjp/qa-skills/blob/main/CONTRIBUTING.md)；本地一条命令自检 `python3 scripts/validate_skills.py`（与 CI 同一校验） - 🐛 缺陷 / 💡 功能建议：先到 [Discussions](https://github.com/fishzjp/qa-skills/discussions)（使用问答与经验分享），确认是缺陷或明确诉求后再提 [Issue](https://github.com/fishzjp/qa-skills/issues) - 🛡️ 安全漏洞：请勿公开讨论，按[安全策略](https://github.com/fishzjp/qa-skills/blob/main/.github/SECURITY.md)私密报告 - 📜 行为准则：[CODE_OF_CONDUCT.md](https://github.com/fishzjp/qa-skills/blob/main/.github/CODE_OF_CONDUCT.md) · 📋 版本历史：[CHANGELOG.md](https://github.com/fishzjp/qa-skills/blob/main/CHANGELOG.md) ## 许可证 [MIT](https://github.com/fishzjp/qa-skills/blob/main/LICENSE)