zoahdev/dsh-plugin-doctor

dsh-plugin-doctor

CI
License: MIT

CI Release

English · 中文

English

针对 DeepSeek Harness 插件的健康检查——在官方命令出现之前，这是对 RFC #1629 中 dsh plugin check 想法的实用解答。

它有两种工作方式：

- CLI（dsh-plugin-doctor / node lib/bin.js）——在终端或 CI 中运行，然后再提交 PR。
- 插件 shell（dsh plugin add）——一旦安装到 DeepSeek Harness 中，agent 就可以直接调用 plugin_check 工具：“检查这个插件是否已准备好发布”，无需 shell。

检查内容

| 检查项 | 验证内容 | 默认 |
|---|---|---|
| manifest | package.json 存在；dsh.bundle + dsh.bundle.patch + prepare + main 均存在 | ✅ |
| patch | cordis.patch.yml 可解析为 YAML，并至少包含一行带 id 的 insert | ✅ |
| entry | main 目标存在（尚未构建时发出警告） | ✅ |
| files | 声明了 files 允许列表 | ✅ |
| build | pnpm run build 成功 | --build |
| pack + install + config | pnpm pack，安装到全新的 DSH_HOME profile，并在 --dump-config 中确认插件 id | --full |
| profile-shadow | dsh profile 中没有真实目录形式的 @deepseek-ai/ 副本遮蔽宿主实例（讨论 #1697） | --profile  |
| manifest-bom | dsh profile 的 package.json 没有 UTF-8 BOM（会导致 dsh web 启动时崩溃，讨论 #1842） | --profile  |
| large-files | 没有 profile 文件超过 100 MB（会话日志可能触及约 512 MB 的 stringify 上限，讨论 #1859） | --profile  |
| entry-points | 每个已安装插件的 main/exports 目标都存在（未构建的源码副本安装会导致 dsh web 启动时崩溃，讨论 #1965） | --profile  |
| profile-deps | 运行时 @deepseek-ai scope 存在（在 profile 目录中直接执行 npm install 会修剪共享树，讨论 #2081） | --profile  |
| native-modules | 运行时树中存在 koffi/node-pty（npm 11 的 allow-scripts=false 会跳过原生构建，讨论 #2081） | --profile  |
| pre-execute-side-effects | pre-execute 监听器在批准前不会运行宿主级副作用（启发式 lint，讨论 #1863） | 默认流水线 |
| shell-launcher | child_process 的使用不会调用 explorer/start/open/powershell/cmd 等可绕过审批/工作区限制的界面（启发式，讨论 #1923/#1863） | 默认流水线 |
| node / pnpm / dsh-path / port-3080 / win-bash | 环境诊断：PATH 上的工具链、Web UI 端口是否空闲，以及最小预设下 Windows bash 是否可解析（讨论 #1856） | --env |

当没有任何失败时退出码为 0，否则为 1。--json 会打印供 CI 使用的机器可读报告。

证据优先的插件审计

audit 是一种独立的、只读的检查模式。它从不导入目标插件、运行生命周期脚本、安装依赖或联系注册表。它会报告：

- 包标识、源仓库元数据、可用时的本地 Git 修订版本，以及被检查内容的 SHA-256 摘要；
- install/prepare/publish 生命周期脚本、声明的依赖来源，以及本地已安装直接依赖的生命周期脚本；
- 每一项 Cordis 补丁操作、受影响的条目 id 和配置键、运行时 !!js 表达式，以及禁用审批或沙箱条目的更改；
- 观察到的文件系统、网络、进程、环境、凭据、动态代码、原生代码、持久化、浏览器存储、会话数据、剪贴板以及动态模块加载能力；
- 带有稳定规则 id、严重性、置信度、已脱敏的文件与行号证据、覆盖缺口以及诚实局限性的发现项；
- 当提供 --compare  时的升级差异。

扫描器优先使用包声明的已发布 files 范围。当声明的主构建输出不存在时，它会回退到工作树并记录该选择。工作树回退会跳过测试、fixtures、示例、演示、普通 JSON 数据以及未声明的开发脚本；为发布而显式声明的路径仍会被扫描。网络组合会区分固定的外部目标与同源/回环调用以及动态目标。大型生成包和相距较远文件区段中的源代码匹配会降低置信度，因为共处一地并不能证明数据流。

CLI 用法

npx dsh-plugin-doctor .                 # 对当前目录进行快速检查
npx dsh-plugin-doctor --build ./my-plugin
npx dsh-plugin-doctor --full ./my-plugin
npx dsh-plugin-doctor preflight ./my-plugin       # 别名：build + full 流水线（讨论 #1774）
npx dsh-plugin-doctor check ./my-plugin           # 同一流水线；匹配提议的 dsh plugin check 界面（RFC #1846）
npx dsh-plugin-doctor --json ./my-plugin
npx dsh-plugin-doctor audit ./my-plugin
npx dsh-plugin-doctor audit ./new-version --compare ./old-version --json
npx dsh-plugin-doctor audit-batch ./plugins/plugin-a ./plugins/plugin-b --json
npx dsh-plugin-doctor audit-batch ./plugins/ --markdown > plugin-ecosystem-audit.md
npx dsh-plugin-doctor --profile ~/.dsh/profiles/web   # profile 绊线：host-shadowing + manifest BOM
npx dsh-plugin-doctor --env                            # 环境诊断（node/pnpm/dsh PATH、端口 3080）
npx dsh-plugin-doctor --env --port 8090                # 改为探测自定义 Web 端口
npx dsh-plugin-doctor env explain DEEPSEEK_API_KEY      # 密钥安全的环境变量溯源（RFC #1953）
npx dsh-plugin-doctor env explain MY_KEY --json         # 机器可读封装；值始终为 [redacted]
npx dsh-plugin-doctor --help

无需安装，直接从仓库运行（在 pnpm build 之后）：

node lib/bin.js --full ./my-plugin

插件用法（可由 agent 调用）

将插件安装到 DeepSeek Harness 配置文件中：

dsh plugin --profile web add dsh-plugin-doctor   # 从 npm 安装
或从本地构建安装：
dsh plugin --profile web add ./dsh-plugin-doctor-1.6.0.tgz

然后在 DSH 中向 agent 提问：

检查一下这个插件能不能发布 —— 先跑 build，再做完整验证。
检查这个插件是否已准备好发布 —— 先运行 build，再做完整验证。

agent 会调用 plugin_check 工具（参数为 dir，可选 build/full 标志）。该工具会针对每项检查返回 PASS/WARN/FAIL，以及一个总体 ok 标志。

“full” 究竟证明了什么

--full 不只是加载 bundle。它会：

1. 在真实项目上运行 pnpm pack；
2. 创建一个全新的 DSH_HOME 配置文件（不会污染你真实的配置文件）；
3. 运行 dsh plugin add ；
4. 运行 dsh --dump-config，并断言来自 cordis.patch.yml 的插件 id 确实出现在合成后的配置中。

CI 还会运行一次真实 registry 的 agent 可见性检查：一个真实的 Cordis 上下文 + 真实的 dsh-tools ToolRuntime + 一个限定范围的 agent 视图，断言 plugin_check 可通过 ctx.tools.schemas(scope) 可见——这正是 agent 实际使用的机制（覆盖了讨论 #1697/#1782 中的双实例遮蔽问题类别）。

这与 awesome-dsh-plugin 维护者在审查插件 PR 时使用的是同一条路径。

它为什么存在

- pnpm 可能会悄悄地把一个较旧的 RC 链接到插件的 peer 槽位中，而“能正常加载”并不意味着“能正常工作”（参见模板的运行时防护和故障排查）。
- 可重复的本地检查（manifest → build → install → config）能捕获那些只在别人机器上才会出现的故障。
- dsh web 启动步骤目前在 CI 中运行于 Windows，因为上游 npm CLI 缺少 linux-x64 的 pty.node 预构建（讨论 #1686）；doctor 的安装/配置验证与平台无关。
- 一个被提升到配置文件中的 @deepseek-ai/dsh-tools 真实目录副本可能会遮蔽宿主实例，并导致每次工具调用都崩溃（讨论 #1697）；--profile 会在任何东西启动之前就准确标记出这一前提条件。
- profile 的 package.json 中带有 UTF-8 BOM 会导致 dsh web 在启动时崩溃，报错 Unexpected token（讨论 #1842）；manifest-bom 检查会在启动前捕获该问题。
- 环境摩擦（缺少 pnpm、Node 版本、PATH、Web 端口被占用）是另一大类安装时故障；--env 将其转化为一条命令（即 讨论 #1719 中的 dsh doctor 构想）。

相关社区工具

- moonquake2004/dsh-doctor —— 离线 profile/session/env 诊断，包含 19 项检查，对应社区故障报告。互补关系：dsh-plugin-doctor 覆盖发布前的插件路径，dsh-doctor 覆盖离线 profile/session 路径。它的 P5 检查与我们的 profile-shadow 检查从两个方向标记同一宿主遮蔽前置条件。
- iiwish/dsh-testkit —— 真实宿主插件生命周期测试（打包 → 安装 → 启动 → 注册 → 确定性演练 → 卸载 → 重启 → 残留检查），在一次性 Docker 环境中进行。互补关系：dsh-plugin-doctor 是快速的本地预检，dsh-testkit 是完整的发布分支生命周期门禁。

CI

对于插件作者，同样的检查以一行 GitHub Action 的形式提供：

- uses: zoahdev/dsh-plugin-doctor-action@v1
with: { path: . }

参见 zoahdev/dsh-plugin-doctor-action。

仓库 CI 运行：

pnpm install --frozen-lockfile → typecheck → build → 单元测试 → 打包插件外壳冒烟测试（打包 → 全新宿主安装 → 加载 lib/plugin.js → 注册 plugin_check → 调用真实处理器 → 断言结果）→ CLI 冒烟测试 → 完整 doctor 自检（打包 → 全新 DSH_HOME profile → dsh plugin add → --dump-config）。

开发

pnpm install
pnpm typecheck
pnpm build
pnpm test
pnpm test:integration

许可证

MIT © 2026 zoahdev

中文

dsh-plugin-doctor —— DeepSeek Harness 插件的健康检查工具，是 RFC #1629 中 dsh plugin check 提案在官方命令落地前的实际实现。

它有两种使用方式：

- CLI（dsh-plugin-doctor / node lib/bin.js）——在终端或 CI 里跑，适合提 PR 前自检。
- 插件外壳（dsh plugin add）——装进 DeepSeek Harness 后，agent 可以直接调用 plugin_check 工具：说一句“检查一下我这个插件能不能发”，不用切到终端。

检查项

| 检查 | 验证内容 | 默认 |
|---|---|---|
| manifest | package.json 存在；dsh.bundle、dsh.bundle.patch、prepare、main 齐全 | ✅ |
| patch | cordis.patch.yml 是合法 YAML，且至少有一条带 id 的 insert | ✅ |
| entry | main 指向的文件存在（未构建时给 WARN） | ✅ |
| files | 声明了 files 白名单 | ✅ |
| build | pnpm run build 成功 | --build |
| pack+install+config | pnpm pack，装进全新 DSH_HOME profile，并在 --dump-config 里确认插件 id | --full |
| profile-shadow | dsh profile 顶层没有真实目录形式的 @deepseek-ai/ 副本遮蔽宿主实例（讨论 #1697） | --profile  |
| entry-points | 已安装插件的 main/exports 指向的文件存在（未构建的源码拷贝会导致 dsh web 启动崩溃，讨论 #1965） | --profile  |
| node / pnpm / dsh-path / port-3080 / win-bash | 环境诊断：工具链在 PATH 上、Web UI 端口空闲、Windows bash 可解析（minimal 预设，讨论 #1856） | --env |

退出码：全部通过为 0，否则为 1。--json 输出机器可读报告，方便接入 CI。

证据优先的插件审计

audit 是独立的只读检测模式。它不会导入被检查插件，不会运行安装脚本，不会安装依赖，也不会访问软件仓库。报告包含：

- 包名、版本、源码仓库、本地 Git 版本（如果可用），以及本次实际检查内容的 SHA-256 摘要；
- install/prepare/publish 等安装生命周期脚本、依赖来源，以及本地已安装直接依赖的生命周期脚本；
- Cordis 配置修改、受影响的 entry id 和配置键、运行时 !!js 表达式，以及关闭审批或沙箱的改动；
- 文件、网络、进程、环境变量、凭据、动态代码、原生代码、持久化、浏览器存储、会话数据、剪贴板和动态模块加载等能力；
- 稳定规则编号、严重程度、判断把握、经过脱敏的文件与行号证据、未覆盖范围和明确限制；
- 使用 --compare  时生成升级前后差异。

扫描器优先检查 package.json files 声明的实际发布内容。声明的主构建文件不存在时，才回退到工作目录，并在报告中写明。回退扫描会跳过测试、示例、普通 JSON 规则数据和未声明的开发脚本；明确声明为发布内容的路径仍会检查。联网组合会区分外部网站、地址不确定、同源接口和本机地址。大型打包文件或相距很远的代码片段会降低判断把握，因为代码放在一起不代表存在真实数据传递。

CLI 用法

npx dsh-plugin-doctor .                 # 对当前目录做快速检查
npx dsh-plugin-doctor --build ./my-plugin
npx dsh-plugin-doctor --full ./my-plugin
npx dsh-plugin-doctor preflight ./my-plugin       # 别名：build + 全链路（讨论 #1774）
npx dsh-plugin-doctor check ./my-plugin           # 同 pipeline；对应 RFC #1846 的 dsh plugin check 命名
npx dsh-plugin-doctor --json ./my-plugin
npx dsh-plugin-doctor audit ./my-plugin
npx dsh-plugin-doctor audit ./new-version --compare ./old-version --json
npx dsh-plugin-doctor audit-batch ./plugins/plugin-a ./plugins/plugin-b --json
npx dsh-plugin-doctor audit-batch ./plugins/ --markdown > plugin-ecosystem-audit.md
npx dsh-plugin-doctor --profile ~/.dsh/profiles/web   # profile 级宿主遮蔽 tripwire
npx dsh-plugin-doctor --env                            # 环境诊断（node/pnpm/dsh PATH、3080 端口）
npx dsh-plugin-doctor --env --port 8090                # 探测自定义端口
npx dsh-plugin-doctor env explain DEEPSEEK_API_KEY      # 密钥安全的环境变量源大排查（RFC #1953）
npx dsh-plugin-doctor --help

不全局安装也可以（先 pnpm build）：

node lib/bin.js --full ./my-plugin

插件用法（agent 可直接调用）

装进 DeepSeek Harness profile：

dsh plugin --profile web add dsh-plugin-doctor   # 从 npm 安装
或本地构建产物：
dsh plugin --profile web add ./dsh-plugin-doctor-1.5.0.tgz

然后在 DSH 里直接对 agent 说：

检查一下这个插件能不能发布 —— 先跑 build，再做完整验证。

agent 会调用 plugin_check 工具（参数 dir，可选 build/full），逐项返回 PASS/WARN/FAIL 和整体 ok 标志。

--full 真正验证了什么

不是“能加载”就算过，而是：

1. 对真实项目执行 pnpm pack；
2. 创建全新 DSH_HOME profile（不污染真实配置）；
3. 执行 dsh plugin add ；
4. 执行 dsh --dump-config，断言 cordis.patch.yml 里的插件 id 真的出现在合成配置里。

这条路径与 awesome-dsh-plugin 维护者人工审插件 PR 的流程一致。

为什么需要它

- pnpm 可能把旧 RC 静默链进插件的 peer 槽；“能加载”不等于“能用”（参见模板的运行时守卫与故障排查）。
- 本地可重复检查（manifest → build → 安装 → 配置）能提前抓出只在别人机器上才会爆的错。
- 由于上游 npm CLI 目前缺少 linux-x64 的 pty.node 预编译（#1686），dsh web 启动冒烟测试在 CI 的 Windows runner 上执行；doctor 的安装/配置验证与平台无关。
- 如果 profile 顶层出现真实目录形式的 @deepseek-ai/dsh-tools 副本，会遮蔽宿主实例，并导致每次工具调用崩溃（#1697）；--profile 能在启动前就抓出这个前置条件。
- 环境类故障（缺少 pnpm、Node 版本、PATH、Web 端口被占用）是另一大 setup 期痛点；--env 一条命令全部检查（#1719 的 dsh doctor 设想）。

相关社区工具

- moonquake2004/dsh-doctor —— 离线 profile/session/env 诊断（19 项检查，映射到社区故障报告）。与 dsh-plugin-doctor 互补：我们负责发布前的插件路径，它负责离线 profile/session 路径；它的 P5 检查与我们的 profile-shadow 检查从两个方向标记同一个宿主遮蔽前置条件。
- iiwish/dsh-testkit —— 真实宿主插件生命周期测试（pack → install → boot → register → 确定性调用 → uninstall → reboot → 残留检查），在一次性 Docker 环境中运行。互补：dsh-plugin-doctor 是快速的本地 preflight，dsh-testkit 是发布分支的完整生命周期门禁。

CI

仓库 CI 完整流程：

pnpm install --frozen-lockfile → typecheck → build → 单元测试 → 打包插件外壳冒烟（pack → 全新宿主安装 → 加载 lib/plugin.js → 注册 plugin_check → 真实调用 handler → 断言结果）→ CLI 冒烟 → doctor 自检（pack → 全新 DSH_HOME profile → dsh plugin add → --dump-config）。

开发

pnpm install
pnpm typecheck
pnpm build
pnpm test
pnpm test:integration

许可证

MIT © 2026 zoahdev