如何开发并测试一个 DSH 插件:dsh-unrestricted fixture 断言与 verify-live 验收完整教程

原创2026-10-31 18:22:201,451 阅读
文章标签:人工智能大模型提示工程AI 插件dsh-plugin

如何开发并测试一个 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:

  1. 在临时目录启动 DSH 的 Web 组合(不占端口、不联网,对源码仓库只读);
  2. 逐个挂载 standard、ptc、cordis、minimal 预设,渲染模型实际收到的提示词;
  3. 对每个预设额外开一次 plan 模式,并派生一个 subagent 子代理;
  4. 落盘三类文件到 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 插件的标准开发循环是:

  1. 改规则 → 修改 src/rules.js 中的锚点或注入块;
  2. 跑断言 → pnpm test,fixtures 立刻告诉你是否丢失原文、是否越界改写;
  3. 抓真机 → 上游 DSH 发新版后,用 dump-prompts 刷新 tests/fixtures/,锚点失配的测试会精准命名失败段落(见 ISSUE_LABELS);
  4. 做验收 → verify-live 在真实运行时核对"关时无痕、开时全量、切回复原";
  5. 锁声明 → 依赖清单、patch 文件变更时,manifest 断言兜底。

这套"真实快照 + 纯函数断言 + 真实启动验收"的组合,让提示词类这种难以单元测试的改动,也拥有了回归测试的确定性和安全感。

登录后查看全文
dsh-unrestricted