前言¶

DeepSeek Harness（DSH）把能力拆成可组合的插件行（patch bundle）。自己写插件时，常见问题不是业务逻辑写不出来，而是 bundle 三行分工、宿主与浏览器半部构建、以及和某一版 DSH 核心的兼容性契约容易搭错；改一处漏一处，冒烟时才发现组合里根本没有挂上 client 锚点。

下面介绍维护者 cherrchen 在 SkillHub 工作流分类下的 dsh-plugin-scaffold（GitHub：cherrchen/dsh-plugin-scaffold）。它是一个不修改上游 deepseek-harness 任何包的最小 out-of-tree 脚手架：把兼容性门禁、宿主服务行、浏览器 client 图锚点行先摆对，并带上完整的 build / test / smoke 链；业务侧只需替换 src/service.ts 与 src/client/index.ts 里的占位实现。仓库当前星标为 0，许可证为 MIT。

这是什么¶

一句话：可运行的 DSH 插件骨架 + 派生时的改名清单 + 验证链，不是自带功能的成品插件。

package.json 中的包名为 @dsh-electron/dsh-plugin-scaffold，描述为：兼容性门禁、宿主服务行、浏览器 client 锚点，以及完整的 build / test / smoke 链。src/service.ts 暴露占位服务 dshPluginScaffold，src/client/index.ts 的 apply 为空——这是刻意的起点。

核心能力（与资料一致）¶

bundle 三行分工¶

脚手架通过 cordis.patch.yml 等约定，固定三类 patch 行 id（派生时需一并改名）：

构建与类型¶

• host / client 分半构建：tsdown 产出宿主 ESM 与浏览器闭包工厂；tsc 分别产出两套声明（build:types + bundle）。
• exports 面：根入口、./compat、./service、./client 均指向 lib/ 下对应产物（见仓库 package.json）。

兼容性契约¶

• 源码集中在 src/compat/dsh-version.ts：SUPPORTED_DSH_RELEASES、REQUIRED_CORE_PACKAGES、OPTIONAL_CORE_PACKAGES 与 peerDependencies 需保持一致。
• pnpm compat:check 校验 allowlist、peers、开发 pin 与已安装树四者一致；漂移会报错。
• 支持矩阵为精确版本 allowlist，不在清单或核心包混装时，门禁服务行不启动，组合表现为「未安装该插件」（见仓库 ADR-0001）。

当前资料记载的 DSH 支持：

作为插件使用者：表中版本需精确匹配；用 dsh plugin 安装即可，无需本地 Node 工具链。从源码开发：Node.js ^22.19.0 || >=24，pnpm 11.25.0（建议经 corepack），开发 pin 的 DSH 为 0.2.1-rc.2。

验证链¶

pnpm verify:all 依次执行 lint、typecheck、build、test、组合冒烟、打包门禁与打包冒烟（不含 compat:check；PR 前资料要求另跑 compat:check 与 docs:check）。

常用脚本含义（摘自 README）：

pnpm compat:check       # allowlist / peers / 开发 pin / 已安装树四者一致
pnpm lint               # oxlint
pnpm typecheck          # host + client 两面，noEmit
pnpm build              # 声明 + tsdown bundle
pnpm test               # vitest；断言 BUILT lib/，需先 build
pnpm smoke              # 真实 dsh plugin add + --dump-config
pnpm pack:check         # tarball 成员、exports、patch 引用
pnpm smoke:packed       # 对打包产物复跑组合冒烟
pnpm docs:check         # 文档结构检查
pnpm verify:all         # 除 compat:check 外的完整链

工程约定还包括 AGENTS.md、.agent/、docs/ 九分区、双语 README/CHANGELOG，以及 CI / release / upgrade / diag 相关脚本。

安装与启用¶

将本地仓库路径安装进 DSH 运行时并检查组合（命令来自 README）：

dsh plugin --profile web add /path/to/repo
dsh --profile web --dump-config | grep -A4 'dsh-plugin-scaffold'

预期可见 compat、service、client 三行注册信息，例如：

# == @dsh-electron/dsh-plugin-scaffold
- id: dsh-plugin-scaffold-compat
  name: '@dsh-electron/dsh-plugin-scaffold/compat'
- id: dsh-plugin-scaffold-service
  name: '@dsh-electron/dsh-plugin-scaffold/service'
- id: dsh-plugin-scaffold-client
  name: '@dsh-electron/dsh-plugin-scaffold'

若 dsh 不在 PATH（例如用源码仓库跑 DSH），将命令中的 dsh 换成 pnpm dsh。

安装前请自行审阅仓库源码与 MIT 许可证；插件以当前 dsh 进程权限运行，路径安装意味着你信任该目录下的代码。

典型用法¶

本地开发首次验证¶

在脚手架工程目录内（资料中的开发流程）：

export CI=true
pnpm install
pnpm verify:all

首次运行需能访问 npm registry。pnpm test 依赖已构建的 lib/，因此完整链里 build 在 test 之前。

派生为你的插件¶

脚手架标识集中在一组 name 上。按 README 表格替换 package.json 的 name 与 repository.url、LICENSE 版权行、源码/脚本/测试中的包名引用、环境变量 DSH_PLUGIN_SCAFFOLD_COMPAT、服务键 dshPluginScaffoldCompat / dshPluginScaffold、Connection 通道 /dsh-plugin-scaffold、patch 行 id 以及含 dsh-plugin-scaffold 的文档文件名。

一次定位待改项：

grep -rn "dsh-plugin-scaffold\|dshPluginScaffold\|DSH_PLUGIN_SCAFFOLD" \
  --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=lib .

随后按实际耦合调整 src/compat/dsh-version.ts 中的核心包清单与 peerDependencies，再执行 pnpm compat:check 与 pnpm verify:all。

目录结构速览¶

src/
├── compat.ts                 # 启动门禁
├── compat/dsh-version.ts     # 兼容性契约本体
├── service.ts                # 宿主占位服务（替换为业务）
├── client/                   # 浏览器半部（替换 apply）
├── contract.ts               # Connection 通道名
└── index.ts                  # 公共 barrel；裸包名 client 锚点

更细的 bundle 约定、开发工作流与故障排查见仓库 docs/（如 docs/reference/dsh-plugin-bundle.md、docs/development/plugin-development-workflow.md）。

适用场景与注意¶

适合谁：要在 DSH 生态里做 out-of-tree 插件、希望从第一天就具备三行 bundle、双端构建与冒烟门禁的团队或个人；需要派生新项目时有一份可执行的改名清单。

不适合当作：直接安装即可用的功能插件——当前行为尚未实现，只有占位服务与空 apply。

限制（README 已知限制）：

• 上游接缝无 semver 承诺；升级车道只提供候选版本证据，扩大支持矩阵需人工决策。
• 精确 allowlist：宿主版本不匹配或混装时，相关服务行不启动。

SkillHub 上的 插件目录页 与 GitHub 仓库由社区维护，与 DeepSeek / 幻方无官方从属关系；DSH 生态理念是「一切皆插件」，本脚手架解决的是搭插件工程这一工作流，而非替代 DSH 本体。

结尾¶

dsh-plugin-scaffold 把 DSH 插件最容易搭错的基础设施（compat / service / client 三行、双端构建、兼容性四向校验、verify 链）做成可复制的起点；你只需替换服务与 client 行为并完成改名清单。详情与贡献规则以仓库 README 与 AGENTS.md 为准：

• 目录页：https://www.skillhub.cn/plugins/cherrchen/dsh-plugin-scaffold
• 源码：https://github.com/cherrchen/dsh-plugin-scaffold