如何开发并测试一个 DSH 插件:dsh-unrestricted fixture 断言与 verify-live 验收完整教程
如何开发并测试一个 DSH 插件:dsh-unrestricted fixture 断言与 verify-live 验收完整教程
dsh-unrestricted 是一个 DeepSeek Harness(DSH)提示词破限插件:它在系统提示词组装时向 standard、ptc、cordis、minimal 等预设注入执行规则,同时保留 DSH 原生的工具调用、计划模式与子代理逻辑。本文以它为例,完整讲解如何开发并测试一个 DSH 插件:用 fixture 断言锁定提示词融合规则,再用 verify-live 做真实环境验收,帮助新手快速掌握插件测试的最佳实践。
一、先认识 dsh-unrestricted 的目录结构 🧭
开发 DSH 插件前,先看懂它的"双半体"架构:node 半负责注入提示词,client 半负责 Web 设置卡片。
| 路径 | 作用 |
|---|---|
| src/rules.js | 融合规则核心:特征锚点 ANCHORS、注入块、fuseSections() 纯函数 |
| src/node.js | 宿主半:监听 system-prompt/assemble 流水线完成注入 |
| src/client/controller.ts | 浏览器半:设置开关、预览、状态卡片逻辑 |
| tests/rules.spec.mjs | fixture 断言:回放真实提示词快照验证融合 |
| tests/controller.spec.mjs | 控制器并发时序测试(fixture 驱动) |
| tests/manifest.spec.mjs | 锁定 package.json 中的客户端依赖声明 |
| tests/fixtures/ | 从真实 DSH 捕获的原版提示词快照 |
| tools/dump-prompts.mjs | 从 DSH 源码仓库抓取提示词,刷新 fixtures |
| tools/verify-live.mjs | 真实启动 DSH 运行时的验收脚本 |
核心思想一句话:测试不依赖 mock 提示词,而是回放从真机捕获的原版提示词快照(fixture),断言"注入是纯追加、锚点校验失败即安全降级"。
二、环境搭建:一键跑通开发环境 ⚡
克隆仓库并安装依赖(仓库地址为开发源,测试脚本还需要一个本地的 DeepSeek Harness 源码目录):
git clone https://gitcode.com/gh_mirrors/ds/dsh-unrestricted
cd dsh-unrestricted
pnpm install
# 类型检查 + 构建 + 规则测试
pnpm typecheck
pnpm build
pnpm test
pnpm test 实际执行的是 node --test tests/*.spec.mjs(见 package.json),无需额外测试框架,Node.js 自带测试器即可。
💡 插件的宿主兼容范围也写在 package.json 的
engines.dsh字段中:>=0.2.0-rc.2 <0.2.2-0,这是 DSH 插件声明版本约束的标准位置。
三、抓取 fixture:用真实提示词做测试数据 📦
插件最大的风险是"上游提示词改版后注入错位"。解法是 tools/dump-prompts.mjs:
- 在临时目录启动 DSH 的 Web 组合(不占端口、不联网,对源码仓库只读);
- 逐个挂载
standard、ptc、cordis、minimal预设,渲染模型实际收到的提示词; - 对每个预设额外开一次 plan 模式,并派生一个 subagent 子代理;
- 落盘三类文件到 tests/fixtures/:
original-*.md:渲染后的完整提示词;sections-*.json:按段落拆分的结构化快照;tools-*.json:工具目录快照;- meta.json:记录捕获时的 DSH commit、时间与各预设段落/工具清单。
刷新命令(需要本地 DSH 源码目录,且需已构建 lib/):
node tools/dump-prompts.mjs --repo <path/to/deepseek-harness> --out tests/fixtures
fixtures 里包含全部 7 组快照:standard、standard-plan、ptc、ptc-plan、cordis、cordis-plan、subagent-standard,覆盖矩阵一目了然。
四、理解 fixture 断言:rules.spec.mjs 的四层防线 🛡️
tests/rules.spec.mjs 是整个测试体系的精华,它把"什么算融合正确"拆成了可断言的不变量。
4.1 逐预设回放:锚点通过 + 零丢失
CASES 表 把 7 组 fixture 逐一喂给 fuseSections(),断言四件事:
- 锚点校验:
result.issues必须为undefined,即官方原文特征(如deployment:persona-prefix的角色句)逐字匹配; - 结构不变:融合后的段落顺序与原文一致,且恰好只新增一个
unrestricted:execution-mode段落; - 位置正确:注入块紧跟在 persona 段落之后(断言代码);
- 纯追加:任何被改写的段落,其原文必须是新文本的严格前缀,且只允许出现在 4 个文档化段落内(persona、plan、ptc-only、structured_output)。
4.2 字节级等价断言
最有说服力的断言在 第 110-120 行:融合输出减去注入块和 persona 指针后,必须与原版渲染结果逐字节相等,并与落盘的 original-standard.md 完全一致。这意味着插件"只加不改"的承诺被锁死在测试里。
4.3 篡改检测:锚点失配要能"拒绝并命名"
安全降级要求:上游文案被改动后,插件必须放弃注入而不是产出畸形提示词。测试故意篡改锚点来验证(第 122-142 行):
- 把 identity 开场白改成别的内容 →
issues必须包含identity; - 把 persona 改成陌生文案 → 主代理拒融,但
isSubagent: true时容忍自定义角色,仍追加指针; - plan 模式只在
plan:policy非空时才检测篡改,保留锚点前缀的扩展文案仍允许融合(第 144-156 行)。
4.4 规则内容的"内容级"断言
EXECUTION_MODE_BLOCK 是注入的完整契约文本。测试用大量 assert.ok 钉住它的关键条款(第 181-410 行),例如:
- 契约必须声明"只约束内容、不改工具目录/调用协议/沙箱限制"(范围断言);
- 契约指纹
contractFingerprint()必须是注入块 SHA-256 的前 16 位十六进制(第 305-310 行),用于设置卡片区分"本契约已生效"与"别的契约在跑"; - 每个预设都有 fixture 覆盖,防止漏抓(coverage 断言)。
五、manifest 与控制器:两个容易被忽略的测试 🧪
5.1 manifest 断言:锁定客户端依赖声明
tests/manifest.spec.mjs 只有十几行,却防止一类隐蔽回归:package.json 的 dsh.client.inject 列表(connection、locale、remotes、renderer、settings、plugin-manager)与 dsh.bundle.patch 指向的 cordis.patch.yml 必须逐字锁定——少注入一个依赖,Web 卡片就会在运行时静默失败。
5.2 控制器 fixture:把"并发时序"变成可重放剧本
设置卡片的 UI 状态机最容易出竞态 bug。tests/controller.spec.mjs 用一个自制的 fixture 工厂 解决:保留真实的 createUnrestrictedController,只把设置提交和 RPC 调用改造成手动应答的 Promise 队列(take() 取请求、answer() 决定何时响应)。
这样就能精确编排时序,测试例如:
- 迟到旧预览不得覆盖新正文:先发起预览,再触发刷新/重检,旧请求最后才返回错误——新预览必须不受影响(第 52-92 行);
- 开关提交立即失效旧预览,且忙碌状态要等写入完成才解除(第 112-134 行)。
这是"fixture 断言"思想在 UI 层的复用:fixture 不是静态文件,而是一套可控的请求应答剧本。
六、verify-live:真实环境验收清单 ✅
单元测试证明"规则正确",但插件必须证明"装进真 DSH 也正确"。tools/verify-live.mjs 就是验收脚本:
node tools/verify-live.mjs --repo <path/to/deepseek-harness> [--boot-enabled]
它完全模拟 dsh plugin add file: 的真实安装方式(复制进 profile 的 node_modules + 叠加 bundle patch),然后跑一份验收契约:
| 阶段 | 验收断言 |
|---|---|
| baseline(开关关) | 四个预设的提示词与工具目录和未装插件时逐字节一致 |
| toggle on | standard/ptc/cordis/minimal 全部融合;工具、上下文不变;契约块只出现一次 |
| 存量会话 | 开关打开前创建的会话,下一次组装即生效 |
| plan 模式 | 开/关 plan 只翻转 plan:policy 一个段落,注入块始终在场 |
| PTC 模式 | 保留 run_code 唯一工具规则,仅追加传输层说明 |
| 子代理 | 委派子代理同样融合,工具目录不变 |
| minimal | 开关前后创建的会话都收敛到同一份融合结果;预设切换(minimal↔standard)时影子段落正确安装/拆除 |
| 部署预览 | 卡片预览与真实提示词在契约位置之前逐字一致,未绑定变量保留 {{model}} 字面量 |
| toggle off | 所有模式恢复基线原文,工具目录仍不变 |
--boot-enabled 分支单独验证"启动即开启"场景:四个预设必须在预设注册完成后才允许融合,避免首组装落空(第 224-244 行)。
失败计数与退出码设计也很规范:任一 check 失败即 process.exit(1)(第 427-431 行),可直接接入 CI。
七、开发工作流总结 🎯
把整套测试串起来,一个 DSH 插件的标准开发循环是:
- 改规则 → 修改 src/rules.js 中的锚点或注入块;
- 跑断言 →
pnpm test,fixtures 立刻告诉你是否丢失原文、是否越界改写; - 抓真机 → 上游 DSH 发新版后,用
dump-prompts刷新 tests/fixtures/,锚点失配的测试会精准命名失败段落(见 ISSUE_LABELS); - 做验收 →
verify-live在真实运行时核对"关时无痕、开时全量、切回复原"; - 锁声明 → 依赖清单、patch 文件变更时,manifest 断言兜底。
这套"真实快照 + 纯函数断言 + 真实启动验收"的组合,让提示词类这种难以单元测试的改动,也拥有了回归测试的确定性和安全感。