前言¶
在 DeepSeek Harness（dsh）里做插件，单元测试往往覆盖不到一类失败：profile 组合错误（某一行解析不了、patch 整段替换 config、provider id 冲突），或客户端 bundle 根本没挂上。这些问题要到真机启动、打开界面时才会暴露，反馈又常常是「应用坏了」，排查会拖很久。
@citisen/dsh-plugin-dev 是一套面向 DSH 插件开发的工作流工具：用一小套可重复的 CLI 把「组合 → 对比 → 启动 → 目视检查」固定下来，并附带 agent skill，在需要判断「该用哪条命令、为什么」时给出指引。仓库由 caparisen 维护，在 SkillHub 插件目录 中归类为工作流。npm 包名为 @citisen/dsh-plugin-dev，当前资料中的版本为 0.1.0，许可证 MIT。
这是什么¶
一句话：Development kit for DeepSeek Harness plugins——组合 profile、启动可丢弃的 shadow 实例、验证 host 侧、抓取 client 侧表现，并在 profile 弄坏时回滚。
实现上不重复造轮子：compose 调用真实的 dsh --profile <p> --dump-config 并做 diff；shadow 调用 dsh --profile <copy> --no-open --port 0 读取启动器打印的 URL；shot 通过 DevTools 协议驱动浏览器。Host 侧只注册一个 skill provider（读取 skills/dsh-plugin-dev/SKILL.md），设计上不应拖垮 profile 启动。
核心功能¶
下面按 README 中的命令表归纳，均为资料中已写明的能力。
| 命令 | 作用 |
|---|---|
doctor |
检测启动器及版本、列出 profiles、检查所选 profile 能否 compose、查找 Chromium |
compose |
经真实启动器组合 profile；--save 记 baseline，--check 在漂移时 exit 1，--json 列出条目与重复 id |
shadow |
复制 profile（文件复制、node_modules 链接），在系统分配端口上启动，等待 URL、探测后输出 url/token/log |
shot |
用 headless Chromium（CDP）渲染 URL：PNG、DOM 统计、控制台错误与未捕获异常；--fail-on-console-error 可将控制台错误视为失败 |
snapshot |
保存、列出、恢复决定 profile 组合的三份文件；restore 前会先快照当前状态 |
通用参数包括 --dsh <path>、--json、--help。
工具包把若干手工坑写进命令里，例如：desktop profile 被 CLI 拒绝（仅 Electron 管理）时需在副本上检查；GUI 无 token 会 401、就绪态是 303 token 交换而非 200；对 SPA 直接用 chrome --headless --screenshot 可能挂死；link: 依赖被包管理器替换时可能删掉含 .git 的工作树。
安装与启用¶
推荐以 bundle 安装，以便 agent 目录中出现对应 skill：
dsh plugin --profile desktop add @citisen/dsh-plugin-dev
包会注册 skill provider，dsh-plugin-dev 出现在 agent 目录；不改动其他 profile 行，禁用 bundle 即可移除。
仅需 CLI、不要 skill 时：
npx @citisen/dsh-plugin-dev doctor
或：
npm i -g @citisen/dsh-plugin-dev
环境要求（来自 README）：
dsh：桌面应用（内置 CLI 会自动找到）、已发布且位于PATH的 CLI，或--dsh <path>/$DSH_CLI- Node 20+
shot需要 Chromium、Chrome 或 Edge（自动查找，否则--browser <path>或CHROME_PATH）- 支持 Windows、macOS、Linux；桌面应用可选，任意可用的
dsh即可
版本说明：资料记载在 Windows 11 上曾与 dsh 0.2.1-rc.2（Electron 44 / Node 24.21）联测。若启动器变更 --dump-config、dsh web: 启动行或 desktop profile 策略，doctor 倾向于报错而非静默给出错误结果；可附 doctor --json 输出到仓库 issue。
典型用法¶
README 给出的最短闭环如下。先做环境自检，再查看启动器会挂载的组合树，启动临时 shadow，截图并抓控制台，必要时为 desktop profile 留快照。
dsh-plugin-dev doctor # what this machine can test
dsh-plugin-dev compose --profile desktop --json # the tree the launcher would mount
dsh-plugin-dev shadow --from desktop --hold # boot a throwaway copy, print url + token
dsh-plugin-dev shot --url "$URL" --out shot.png # render it, capture console errors
dsh-plugin-dev snapshot save --profile desktop # something to go back to
shadow --hold 会保持进程，便于把打印出的 URL 与 token 传给 shot。组合与漂移检查可配合 compose --save 与 compose --check 使用；profile 组合文件损坏时用 snapshot restore（恢复前会自动快照当前状态）。
适用场景与注意¶
适合：正在编写或维护 dsh 插件 / bundle，需要在本机反复验证 profile 组合、host 注册与 Web 客户端是否正常挂载的开发者。
注意：
- 插件与
dsh以你当前用户权限运行；安装前请自行查看 GitHub 源码 与 MIT 许可证。 - SkillHub 等社区目录与 DeepSeek / 幻方无官方从属关系，安装来源以你信任的 registry 与仓库为准。
- 目录页线索为
caparisen/dsh-plugin-dev，npm 安装名以 README 为准：@citisen/dsh-plugin-dev。
结尾¶
多数插件故障出在组合与客户端挂载，而不是某段业务代码。@citisen/dsh-plugin-dev 把 compose、shadow、shot、snapshot 收成固定步骤，并 bundled skill 说明何时用哪一步。进一步了解可看 SkillHub 目录页 与 GitHub 仓库。
