@dsh-electron/dsh-plugin-scaffold
一个最小化的外置 DeepSeek Harness 插件脚手架：兼容性门控、主机服务条目、浏览器客户端锚点，以及完整的构建/测试/冒烟测试链路
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:cherrchen/dsh-plugin-scaffold#971e114f91be7c36f40fd3f222f2e77c66316d4bPlugin Scaffold 以 @dsh-electron/dsh-plugin-scaffold 发布，当前版本为 0.0.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
中文 | English
这是一个最小的 out-of-tree DSH（DeepSeek Harness）插件脚手架。它不修改上游任何包，把搭一个 DSH 插件真正需要、却很容易搭错的部分先准备好：
unsupported / mixed / incomplete 判定、升级车道；.agent/、docs/ 九分区、双语 README/CHANGELOG、CI/release/upgrade/diag 工作流。脚手架当前只提供可运行的骨架：src/service.ts 暴露一个占位服务，src/client/index.ts 的 apply 为空。把这里替换成你的插件行为即可，其余基础设施不需要重搭。
作为插件使用者：一个下表中的 DSH 版本（精确匹配，不是范围）。dsh plugin 负责安装，无需本地 Node 工具链。
| DSH 系列 | 受支持的版本 |
|---|---|
0.2.1 | 0.2.1-rc.2 |
从源码开发：Node.js ^22.19.0 || >=24，pnpm 11.25.0（建议经 corepack 启用）；开发 pin 的 DSH 为 0.2.1-rc.2。
git clone https://github.com/cherrchen/dsh-plugin-scaffold.git my-dsh-plugin
cd my-dsh-plugin
export CI=true
pnpm install
pnpm verify:all
pnpm verify:all 会依次跑 lint、typecheck、build、test、组合冒烟、打包门禁与打包冒烟。首次运行需要能访问 npm registry。
脚手架里的所有标识都集中在一组明确的 name 上。派生新项目时，按下表替换后再跑 pnpm verify:all：
| 位置 | 脚手架当前值 | 替换为 |
|---|---|---|
package.json name | @dsh-electron/dsh-plugin-scaffold | 你的包名 |
package.json repository.url | git+https://github.com/cherrchen/dsh-plugin-scaffold.git | 你的仓库地址 |
LICENSE 版权行 | Copyright (c) 2026 Cherry Chen | 你的名字或组织 |
| 包名引用（源码/脚本/测试） | @dsh-electron/dsh-plugin-scaffold | 你的包名 |
| 环境变量 | DSH_PLUGIN_SCAFFOLD_COMPAT | DSH_<YOUR_PLUGIN>_COMPAT |
| 兼容性服务键 | dshPluginScaffoldCompat | 你的服务键 |
| 宿主服务键 | dshPluginScaffold | 你的服务键 |
| Connection 通道 | /dsh-plugin-scaffold | 你的通道 |
| patch 行 id | dsh-plugin-scaffold-compat / -service / -client | 你的行 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 里的 REQUIRED_CORE_PACKAGES、OPTIONAL_CORE_PACKAGES 与 peerDependencies；pnpm compat:check 会在两处漂移时报错。
安装进 DSH 运行时并检查组合：
dsh plugin --profile web add /path/to/repo
dsh --profile web --dump-config | grep -A4 'dsh-plugin-scaffold'
预期输出：
# == @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-plugin-scaffold-compat 是启动门禁，dsh-plugin-scaffold-service 是宿主服务半部（它 inject dshPluginScaffoldCompat，门禁不过即不启动），dsh-plugin-scaffold-client 挂在裸包名上，是 web 客户端图读取 dsh.client 声明的唯一锚点。
[!TIP]
dsh不在 PATH 里时（例如用源码仓库跑 DSH），把命令里的dsh换成pnpm dsh。
pnpm compat:check # allowlist / peers / 开发 pin / 已安装树四者一致
pnpm lint # oxlint
pnpm typecheck # host + client 两面，noEmit
pnpm build # 声明 + tsdown bundle（host ESM + browser client）
pnpm test # vitest；断言 BUILT lib/ 产物，所以要先 build
pnpm smoke # smoke:compose，真实 dsh plugin add + --dump-config
pnpm pack:check # tarball 成员、exports 目标、patch 引用模块
pnpm smoke:packed # 对打包产物复跑组合冒烟
pnpm docs:check # 文档结构检查
pnpm verify:all # 上面除 compat:check 外的完整链
.
├── src/
│ ├── compat.ts 启动门禁（版本 allowlist 与混装判定）
│ ├── compat/dsh-version.ts 兼容性契约本体：SUPPORTED_DSH_RELEASES、包清单、分类
│ ├── service.ts 宿主服务半部（占位服务，替换为你的插件行为）
│ ├── client/ 浏览器半部（空 apply，替换为你的槽位贡献）
│ ├── contract.ts host/client 共用的 Connection 通道名
│ └── index.ts 公共面 barrel；空 apply 同时承载裸包名 client 锚点行
├── tests/ 兼容性判定、patch 不变量、client 制品形态
├── scripts/ 冒烟、兼容性检查、打包门禁、升级流程、lefthook 安装器
└── docs/ 需求、架构、ADR、计划、开发流程、参考与故障排查
AGENTS.md（仓库级规则）与开发工作流。main 拉分支；提交信息遵循 conventional commits。pnpm verify:all、pnpm compat:check、pnpm docs:check。docs/ 下对应文档；README 保持中英双语同步；有取舍的工程决策请新增 ADR。service.ts 只提供 dshPluginScaffold 服务键与兼容性裁决，客户端 apply 为空。这是刻意的起点，不是缺陷。Coding Agent 的仓库级规则定义于 AGENTS.md。