dsh-test-framework

dsh plugin --profile web add dsh-test-framework

dsh-test-framework

面向测试工程师的 DSH 插件：把一个空文件夹变成你自己的「测试工作框架」，并在 AI 会话里

自动带上框架约束、把「需求文档 → 子模块拆分 → 版本 / 跨文档关联 / 测试环境账密」这条链

做成绕不过去的闸门。

- 宿主是 cordis 插件，零第三方依赖（只用 Node 内置模块），无前端构建步骤

- 插件版本：0.2.9 ｜ 适配：DSH（dsh.engines.dsh = "*"）｜ Node ≥ 20

---

〇、前置条件（装之前先确认）

外部 MCP · 必需？ · 没有会怎样

playwright MCP（mcp__playwright__browser_*） · ✅ 必需，且没有替代路径 · 「看着页面操作流程」这类验证做不了。框架铁律 10 要求「必须真实浏览器 + 真实点击/输入」，明确不许用只读 DOM / 只抓报文 / 离线脚本 / 旧截图冒充 —— 所以缺它不是"降级运行"，而是"这条要求根本执行不了"。<br>插件会在会话开头的「测试框架状态」段落和 test_framework_status 输出里报「未检测到 playwright MCP（必需）」；看到就先配好再开工

keyword_mcp（接口报文落盘 / toast 历史） · 建议 · 少一条取证通道（与 playwright 互补不替代）

cr69_mcp（Chromium 69） · 可选 · 老内核 / 小视口兼容性验证做不了

配在哪：DSH profile 的 cordis.patch.yml —— 加一个 mcp-playwright 服务（serverName: playwright，

命令用 @playwright/mcp），并且必须有头（窗口可见），否则"看着"是假的。

⚠️ 改完必须重启 DSH（profile 层不热加载）。

自查：

# npm 安装的用户
npx dsh-test-framework doctor

# 在测试框架里（插件源码在 _plugin\ 下）
node _plugin\dsh-test-framework\lib\cli.js doctor

doctor 会把这三项逐个列出来（"已检测到" / "未检测到" / "无法判定"）。

⚠️ 口径说明：插件是靠读 profile 的 cordis.patch.yml 来判断的，"未检测到"≠"一定不存在"

（你也可能用别的方式起这个 MCP）—— 真查不到时它会说"无法判定"，不会硬下结论。

---

一、它解决什么问题

用 DSH 做需求测试时，反复出问题的是这几件事 —— 它们不是能力问题，是纪律问题：

痛点 · 本插件的处置

新建一个文件夹就要手工搭一遍框架骨架（AGENTS.md / skills / _templates / 产品级规范 / 目录联接） · test_framework_init 一条命令生成，已存在即跳过、不覆盖

在 <产品>\<模块>\ 这种子目录里开会话，框架根 AGENTS.md 静默不加载（DSH 只认 .git 当项目根） · 初始化时建 .git 标记；并且插件另注入一段实时状态，没加载成也会明说

120 页的需求文档含 3 个子模块，AI 自己就拆了或干脆不拆 · 探针给页数/章节/菜单命中 → 命中判据就必须用 ask_user_question 让用户确认，不许自作主张

某个业务逻辑其实写在另一份需求文档里，没人问过 · 闸门 crossDocChecked：必须问过（答"没有"要落 relatedDocs: []，缺 key = 没问过）

需求文档路径不区分版本，测错版本全白干 · 闸门 versionsConfirmed，并在流程里写死"不许用文件时间判版本"

每次都要重新问一遍环境地址、账号密码、数据库地址 · test_framework_record 落产品级规范（人读的 md + 机器读的 json），下次直接命中

密码散落到脚本和报告里 · 明文只落 _框架配置\环境与账密.md，框架登记.json 里只记指针（有测试守着）

报告越堆越多，模块 report\ 里几个月前的报告还混在最新一批里 · test_framework_report_gc：满 24h 的报告移进 _archive\报告归档\<模块>\<日期>\（归档不是删除，台账记着原名与日期）；agent 入口默认只预演

报告写成"密密麻麻一大长篇"，看不出有几条、最严重的是哪条、差在需求哪一句 · AGENTS.md 铁律 4 + 测试报告模板硬性要求：结论先行 + 缺陷速览表在最前 + 一条缺陷一小节（≤20 行）+ 复现步骤可照做 + 每条写「需求原文依据」与「与需求不符点」

一个模块测了好几版，几版的口径/造数逻辑/坑全揉在一份 SKILL.md 里，用的时候不知道哪句对哪版 · 模块 SKILL.md 降为索引，每版一份 skill\<版本>\SKILL.md，一版一份、多版并存、互不覆盖；test_framework_module_add 传 version 就自动建好并回填索引 §8 版本索引

别的项目 / 别的工具的规矩渗进本框架 —— 它的"落盘必须在自己的工作区内"变成了本框架的规矩，于是模块里被建出一批永远装不进东西的 temps\ 空壳、模块 SKILL.md 里留下"照着做必然失败"的经验 · lib\isolation.js：① 会话开头先说清当前会话的项目根是谁、会加载哪份 AGENTS.md（嵌套仓库截断 / 找不到 .git 退回 cwd / 项目根跑到框架外，三种都认）；② 模块里出现外部工具的工作目录就报，并写明正确做法（落它自己的工作区 → 证据拷回模块 data\）；③ doctor 一并列出周边所有外部权威来源（别处的 AGENTS.md、.trae 规范库）

---

二、装插件

路线 A：从 npm 装（别人用这条）

# DSH 插件就是 npm 包 —— `dsh plugin ...` 本身就是转发给 pnpm
dsh plugin --profile desktop add dsh-test-framework

# 重启 DSH（profile 的 bundles 层与 cordis.patch.yml **不支持热加载**，不重启不生效）

装完看会话里有没有 test_framework_status 工具，或跑：

npx dsh-test-framework doctor --profile desktop

路线 B：从源码装（改代码时用这条）

cd <插件目录>
# ① 看计划（不写盘）
node lib\cli.js install --profile desktop

# ② 真装（链接安装：`link:` + 目录联接，不跑 pnpm）
node lib\cli.js install --profile desktop --apply

# ③ 重启 DSH

自检：

node lib\cli.js doctor --profile desktop

doctor 会逐项报：插件清单 / 入口 / cordis.patch.yml / Node 版本 / 找不找得到 dsh 与 pnpm /

这个 profile 里依赖与 bundles 两处是不是都有（只有一处 = 半装 = 不会加载）。

可选配置

# profile 的 cordis.patch.yml —— 把需求文档总根目录固定下来
- id: test-framework
  config:
    reqDocRoot: '<你的需求文档总根目录>'

不配也可以：省略时按「插件配置 → 环境变量 DSH_REQ_DOC_ROOT → <用户主目录>\需求业务文档」解析。

插件里没有写死任何绝对路径（有测试守着这一条）。

默认为什么不跑 dsh plugin add

默认走的是「链接安装」：备份 package.json → 给 dependencies 和 dsh.profile.bundles

各加一条 → 在 node_modules 里建一个目录联接。link: 依赖的本质就是这个联接，

所以这条路和 pnpm 的产出等价，但不碰整棵 node_modules。

dsh plugin add 会在 profile 目录里真跑一次 pnpm install。实测本机 desktop profile 的

node_modules\@deepseek-ai 处于两个 dsh 版本混链的状态（profiles\node_modules 下

0.1.1-rc.2 与 0.1.5-rc.3 混着指），一次 pnpm install 很可能把这棵树"规范化"掉、

连带影响正在运行的 DSH。装一个小插件不值得冒这个险。

要用官方命令（或补跑 pnpm）：

# 官方命令：会真跑 pnpm install
node ...\cli.js install --profile desktop --apply --official
# 链接安装 + 之后再补跑一次 pnpm install
node ...\cli.js install --profile desktop --apply --pnpm

关于本机有多个 dsh

本机 npx 缓存里有 4 个 dsh（0.2.0-rc.2 / 0.1.7-rc.1 / 0.1.5-rc.3 / 0.1.1-rc.2），

而 profile 的 node_modules 是混链的。所以 doctor / install 挑 dsh 的顺序是

PATH → 这个 profile 自己链的那个 → npm 全局 → npx 缓存（版本降序），并把候选全列出来；

要指定就 --dsh <dsh.cmd 路径>。

（找 profile 自己链的那个时要查两层：<profile>\node_modules 与

<dshHome>\profiles\node_modules —— 本机 @deepseek-ai\dsh 挂在上一层，只查自己那层会挑错版本。）

怎么确认真装上了：重启后新开一个会话，看 skill 列表里有没有 test-framework-onboard、

工具列表里有没有 test_framework_status；或直接说一句"看下测试框架状态"。

（本次装到 desktop profile 后无需重启就已生效：会话的 skill 目录里已出现 4 个

test-framework* skill，dsh --profile desktop --dump-config 里能看到 - id: test-framework。）

卸载

node lib\cli.js uninstall --profile desktop

只摘掉 profile 的依赖与 dsh.profile.bundles 条目（改前一定先备份成 package.json.bak-testfw-<日期>），

并摘掉手动建的那个目录联接（不然会留下一个指向已卸载插件的死链接）。

不动框架工作区里的任何文件 —— 卸载插件 ≠ 删框架。

---

三、装完能得到什么

3.1 七个工具

工具 · 干什么

test_framework_status · 开工前先调它。返回框架根、产品与模块、登记到哪一步、还缺哪些项。ready: false 时不许直接开测

test_framework_init · 把（空的）文件夹初始化成框架骨架。dryRun: true 只看计划

test_framework_module_add · 新增一个模块（= 系统里的一个叶子菜单；父菜单不建目录、只作菜单路径）：建 requirement/final/report/data/skill + 渲染模块索引 SKILL.md + 传 version 时再建 skill\<版本>\SKILL.md（一版一份，互不覆盖）并回填索引 §8 版本索引，最后同时回填框架根 AGENTS.md §三 与产品级 模块路由.md

test_framework_link · 跨端关联的只读体检（不改任何文件）：查 关联边两端模块是否存在 / 单向边（只有 A→B 没有 B→A）/ **

…(truncated)