dsh-qa-skills

dsh plugin --profile web add dsh-qa-skills

[简体中文](./README.md) | [English](./README.en.md)

<p align="center">

<picture>

<source media="(prefers-color-scheme: dark)" srcset="./assets/hero-dark.png">

<img src="./assets/hero.png" alt="QA Skills —— 知识 × 工具 × 决策的测试工程 Skill 框架：十轴类型决策矩阵与完整测试流水线" width="800">

</picture>

</p>

<h1 align="center">qa-skills</h1>

<p align="center"><strong>让 AI 像资深测试工程师一样工作。</strong></p>

<p align="center">知识 × 工具 × 决策 —— 面向 Claude Code 等 Agent 的测试工程 Skill 框架。<br>每一个数字，都来自实测。</p>

<p align="center">

<a href="https://github.com/fishzjp/qa-skills/actions/workflows/ci.yml"><img src="https://github.com/fishzjp/qa-skills/actions/workflows/ci.yml/badge.svg" alt="CI"></a>

<a href="./skills/"><img src="https://img.shields.io/badge/skills-10-blue" alt="Skills"></a>

<a href="https://github.com/fishzjp/qa-skills/releases"><img src="https://img.shields.io/badge/release-%E5%A2%9E%E7%9B%8A%E7%9F%A9%E9%98%B5%E5%BF%AB%E7%85%A7-orange" alt="Release gain matrix"></a>

<a href="https://github.com/fishzjp/qa-skills/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>

</p>

---

快速开始

安装

方式一：通用安装脚本（自动检测宿主 skills 目录）

git clone https://github.com/fishzjp/qa-skills.git
cd qa-skills

./install.sh            # 交互式选择宿主目录（自动检测 ~/.agents/skills 等）
./install.sh --auto     # 或全自动安装

方式二：skills.sh 跨 Agent 安装（Claude Code / Cursor / Codex / OpenCode 等 50+ 宿主）

npx skills add fishzjp/qa-skills            # 交互式勾选，全装用 --skill '*'

方式三：DeepSeek Harness（dsh）插件（npm 包 dsh-qa-skills）

dsh plugin --profile web add dsh-qa-skills

dsh 原生兼容本仓库格式，走文件路径安装亦可（见下方安装细节）；已在 dsh 0.1.0-rc.8 + deepseek-v4-flash 上完成两条安装路径的端到端验证。

core/ 是共享知识库依赖单元（不可执行任务）：安装任一 skill 时必须一并安装，否则引用路径断裂。

<details>

<summary><strong>手动安装、验证与卸载</strong></summary>

• 手动安装：cp -r skills/* <skills 目录>/——core/ 必须一起复制，各 skill 以相对路径引用它。
• 验证安装：ls <skills 目录> 应见 10 个 skill 目录 + core/ + qa-skills.VERSION。
• dsh 文件路径安装：装到 ~/.agents/skills/（./install.sh --target ~/.agents/skills）或 ~/.dsh/skills/，重启 dsh 生效。
• 升级：./install.sh --target <目录> --link 用软链代替拷贝，git pull 后即更新。
• 卸载：./uninstall.sh。

</details>

<details>

<summary><strong>宿主兼容性与降级路径</strong></summary>

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](./docs/DESIGN.md) 编排会话模型一节）。

</details>

开始使用

装好后对 Agent 说一句：

帮我测试这个需求：{需求描述 + 仓库地址}

从需求理解、风险与类型决策，到测试报告——完整流水线就此跑通。只需要其中某个阶段（写用例 / 审查 / 转自动化 / 回归范围）时，直接描述需求即可，无需走完整流水线。

能力总览

你说 · 框架做 · 产出

"帮我测试这个需求" · 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 → 回归范围）各自独立可用。

<details>

<summary><strong>测试用例脑图怎么渲染</strong></summary>

测试用例_markmap.md 是标准 Markdown（markmap 语法）：VS Code 装 Markmap 扩展、npx markmap-cli 测试用例_markmap.md 生成交互式 HTML、或粘贴到 markmap.js.org/repl。

</details>

能写，更要能执行。

AI 写出的用例常常看似专业、实则无法执行——判定模糊、占位符、无判定时限、虚构入口。

同一个需求，本框架的产出长这样：

> 前置:运营账号已登录,进入「营销中台 → 券工场 → 活动列表」

- **TC-02-05 到期自动结束** [P1]
  - 操作步骤: 1. 选一张结束时间为 2 分钟后的已发布券「满100减20-测试」 2. 等待到期
  - 预期结果: 到期后 1 小时内状态自动变为「已结束」,超过 1 小时未变判失败

核心产出标准只有一条：没读过需求、没人讲解的人，拿着文件能直接开工。 这背后是 skills/core/executability.md 的 8 条硬标准；评测中它是一票否决项——不可执行的用例，覆盖再全也计零分。

指令更少，遵循更强。

把方法论、模板、规则全部塞进一个 SKILL.md，Agent 有效遵循的规则反而更少（Red Hat ACE 实践总结：指令超过 500 行后性能退化）。解法是三层架构：

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（详见[实测效果](#实测效果)一节的决策层注）。

工作原理

文件即流水线状态——每个阶段产出落盘为文件，下一阶段只消费文件而非会话记忆；长流水线不依赖上下文，中断后新会话读文件续跑：

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](./docs/DESIGN.md)。

实测效果

在 12 个评测任务上对比：同一模型、同一评测链路，唯一差异是是否注入本框架；数字以异构裁

…(truncated)