HubaKing/dsh-community-plugins

dsh-community-plugins

一个 DeepSeek Harness (dsh) 插件，教会 agent 如何发现、评估和安装社区插件——并给它们两个工具，用来对照本机上实际运行的 dsh 构建来检查这些插件：一个完全离线，另一个在安装之前获取包。

English · 中文

这个 bundle 为每个会话添加三样东西：

1. 一个 skill（dsh-community-plugins）——如何通过 GitHub 的 dsh-plugin topic、精选索引和 npm 找到插件；如何在安装前审查一个插件；如何通过官方的 dsh plugin 机制安装；如何验证结果。
2. 一个离线工具（dsh_plugin_audit）——将已安装的插件与本机的 dsh 构建进行对比，并逐个插件报告：哪些已损坏、哪些只是有风险、哪些无法确定。它不获取任何东西。
3. 一个联网工具（dsh_plugin_inspect）——下载某个包已发布的 tarball，对照 registry 发布的哈希进行校验，将其解压到临时目录，并在安装之前对其进行评判。它从不安装任何东西，也从不运行该包的生命周期脚本。

这两个工具被刻意分开。audit 的承诺是它不触碰网络；一个有时会让它去获取的 flag 会让这个承诺变成有条件的，而有条件的承诺就不是承诺。两个工具，两个保证，各自说明自己是哪一个。

为什么需要这个插件

DeepSeek Harness 通过两种互补机制提供插件能力：Tools 和 Skills。

| | Tool（例如 market_search） | Skill（由本插件注册） |
|---|---|---|
| 本质 | 能力通道：可调用的函数 | 上下文知识：何时、为何以及如何调用 |
| 单独的效果 | 工具存在，但 agent 不认识它 | 没有可调用的 marketplace 接口 |

仅有 marketplace 工具是不够的，因为 agent 的行为由上下文知识驱动。web_search 有直观的描述，是任何模型的默认做法；market_search 则是 DSH 特有的。没有这个 skill，agent 就不知道它存在，不会把它与安装插件联系起来，也不了解本地 profile 布局、bundle 机制、审查工作流或重启要求。

而仅有知识也不够：这个生态中一个硬性的实际问题——“升级 dsh 会不会破坏我已安装的东西？”——无法可靠地手工回答，因为下面的 rc 预发布规则让肉眼判断失效。

为什么用实时探测而不是兼容性数据集

上游有意声明 API 表面不稳定：

- README.md —— “THERE WILL BE COMPATIBILITY-BREAKING CHANGES.”
- AGENTS.md —— “Public APIs are pre-stable; update every consumer.”
因此，该 API 表面的缓存快照从写入的那一刻起就开始失效。这里实测：一个月内 16 个 0.x 预发布版本——大约每周一个破坏性变更。数据集需要持续维护，并且在两次更新之间就是错误的，而一个自信地给出错误结论的验证工具比没有工具更糟。

所以这个插件不存储任何东西。dsh_plugin_audit 在每次调用时读取 dsh 安装根目录和 profile，并针对这台机器、此时此刻给出答案；dsh_plugin_inspect 读取它刚刚下载的 tarball，并针对同一个构建给出答案。没有遥测，没有缓存，没有需要保持新鲜的数据——当某些东西确实无法检查时，两者都会说 unknown 并给出原因，而不是猜测。

这就是它与约 75 个市场插件、生态系统中已有的 3 个以上静态审计器，甚至官方运行时检查器之间的区别：那些工具列出、排名、扫描安全性，或描述当前正在运行的内容。没有一个会将插件的声明范围与实际 API 使用情况与你的 dsh 构建进行对比，也没有一个能对尚未安装的插件做到这一点。

与官方运行时检查器互补。 @deepseek-ai/dsh-tool-cordis 提供了 cordis_inspect_，它精确查询实时运行时（Service.listService、Event.listEvents、Tool.listTools，以及用于真实客户端 slot props 的 Slots.listSubTree）。对于“运行时现在长什么样”，那无疑是更好的工具。这个插件回答的是另一个问题——“磁盘上的声明是否仍然与这里安装的构建一致”——而且它仍然能在检查器无法工作的地方工作：加载失败的插件不在实时运行时中，因此检查器根本看不到它。 静态检查读取磁盘；检查器读取进程。两者都需要。

两者都无法预测未来的升级。两者都只能看到这台机器上安装的构建；对于“升级后什么会坏”的诚实答案是升级后再运行它们一次。

离线审计工具

dsh_plugin_audit({})                                  # profile 中的每个第三方插件
dsh_plugin_audit({ target: 'dsh-llm-local-token' })   # 一个包（名称或目录）

对每个插件，它报告：

| 检查项 | 事实来源 |
|---|---|
| 它的 bundle 层能否被挂载？ | 磁盘上是否存在 dsh.bundle.patch，以及该包是否在 dsh.profile.bundles 中被命名 |
| peerDependencies 范围是否满足？ | 这台机器上每个包的实际版本，包括 vendor/ |
| 导入的 @deepseek-ai/ 包是否仍然存在？ | dsh 安装根目录（packages/、vendor/、node_modules/@deepseek-ai） |
| 这些导入所需的具名导出是否仍然被导出？ | 该包的声明入口，遍历 export  重导出，并与其运行时入口取并集 |
| 注册的客户端 slot 是否仍然被定义？ | 从官方 packages/client + packages/core 源码中提取的 slot 契约 |
| inject 服务名可解析？ | 实时的 Cordis 上下文 |
| 安装时风险信号？ | npm 生命周期脚本、child_process、eval、远程导入、网络 |

判定结果是分级的，而非二元的：

| 判定 | 含义 |
|---|---|
| compatible | 此工具能执行的每一项检查都通过了 |
| at-risk | 某个声明的范围不再匹配，或其层未被组合进来，尽管代码可能仍能运行——这是该生态系统的常态 |
| incompatible | 硬证据：它所需的某个包、导出或槽位在此构建中已不存在，或其 bundle 层无法挂载 |
| unknown | 某项所需检查无法离线完成；原因始终会说明 |

符号级检查，以及为什么“包仍然存在”还不够

一个执行 import { PiAiAdapter } from '@deepseek-ai/dsh-llm' 的插件，只有在该包仍然导出* PiAiAdapter 时才能继续工作。一次重命名或拆分会让包仍然存在，而绑定却消失了——而对模块未提供的绑定进行 ESM 具名导入，是链接时抛出，而不是功能降级。

确认这一点比 grep 一个文件更难，因为一个包的导出面是一张图。官方声明是 barrel 文件，而 TypeScript 会生成源扩展名：

export * from './attribution.ts';          // 随附的文件是 attribution.d.ts
export { BlockAssembler } from './assembler.ts';

单文件扫描会把每一个再导出的符号都报告为缺失。因此，该检查会遍历这张图——相对说明符、.ts/.js → .d.ts 映射、指向其他包的裸说明符——并将两件事严格区分开：

- 它已确认的符号集合，以及
- 该集合是否完整。

只有完整的图才允许使用已移除一词。不完整的图会给出 unknown，因为“我无法解析它”并不等于“它已消失”。声明类型表面会与运行时入口自身的导出列表取并集，因此过时的声明无法制造出失败。

已在本机验证（2026-09，dsh 0.1.5-rc.1）：检查了 279 个官方包，276 个声明图完全解析，检查了 1,874 个运行时导出名，0 个未确认。 那三个不完整的图被报告为 unknown，而绝不会被报告为移除。该测试套件会在运行它的任何机器上重新执行这次扫描。

一个糟糕的插件可能让 dsh 无法启动

这就是为什么层检查排在第一位。以下三种情况会抛出异常而不是降级，因此整个 profile 无法启动：

| 情况 | 上游行为 |
|---|---|
| 声明了 dsh.bundle.patch，但包中不包含该文件 | failed to read overlay——抛出（packages/boot/app-boot/src/index.ts:315-323） |
| 声明了 dsh.bundle 但没有 patch 路径 | declares no dsh.bundle——抛出（packages/boot/app-boot/src/profile.ts:792-797） |
| dsh.profile.bundles 指定了一个无法解析的包 | 层解析失败——抛出（同一文件） |
还有一个会静默失败的情况：一个可读的补丁，其包不在 dsh.profile.bundles 中——该层永远不会被应用，因此插件完全不起作用。通常的原因是使用 pnpm add 在 profile 内安装，而不是使用 dsh plugin add，后者才是负责协调该列表的命令（apps/cli/src/plugin.ts:59-91）。

该工具会为每个插件打印一行 layer …，并将其余的作为阻塞项抛出，因此你可以在重启 dsh 之前就看到这一切。这些特定的判断是精确的——它们读取 package.json 和文件系统，而不是源代码启发式规则。

它存在的目的：捕获 rc 预发布陷阱

^0.1.0-rc.5 展开为 >=0.1.0-rc.5  ⚠️ npm 形式务必使用 @hubaking/ 作用域。 npm 上未加作用域的名称 dsh-community-plugins 属于另一个项目（funcodingdev/dsh-community-plugins，TypeScript，带构建脚本），因此 dsh plugin add dsh-community-plugins 会静默安装那个包。

⚠️ 带作用域的包尚未发布到 npm。 截至 2026-09，dsh plugin add @hubaking/dsh-community-plugins 返回 404；一旦配置好 NPM_TOKEN，发布工作流会在 v 标签上发布它。在此之前，请使用上述任一形式。

安装后重启 dsh（bundle 层在启动时组合）。当 dsh-community-plugins 出现在  中，且 dsh_plugin_audit 和 dsh_plugin_inspect 都出现在工具列表中时，安装即成功。

当 dsh 不在 PATH 中时，使用 node /apps/cli/lib/bin.js plugin --profile web add 。

工作原理

| 文件 | 职责 |
|---|---|
| index.js | 插件入口：注册 skill 提供者，然后通过 ctx.get('tools') 挂载两个工具 |
| lib/skills.js | 解析 skills//SKILL.md bundle 并将它们注册到 ctx.skills |
| lib/tool.js | 离线工具定义和人类可读的报告渲染器 |
| lib/inspect-tool.js | 联网工具定义及其渲染器 |
| lib/audit.js | 定位 dsh 根目录和 profile，扫描插件，生成判定 |
| lib/symbols.js | 通过 export  桶文件遍历声明图，以确认命名导出 |
| lib/semver.js | 无依赖的 semver 匹配，与 node-semver 对齐，包括预发布规则 |
| lib/registry.js | 注册表/仓库解析、完整性校验、有上限的下载 |
| lib/inspect.js | 获取、解包并判定尚未安装的包，然后删除临时目录树 |
| lib/tar.js | 手写的加固 tar 读取器：拒绝路径穿越、链接条目和炸弹 |
| cordis.patch.yml | Bundle 补丁层：- insert: 行在 profile 启动时挂载插件 |

开发

npm install      # 仅 yaml
npm test         # semver + symbols + 实时审计 + fixtures + tar + 预安装 + 契约 + 集成

这些测试套件旨在在任何机器上都能发挥作用：

- test/semver.test.mjs — 在可获取到 npm 的 semver 时，将 lib/semver.js 与其交叉验证（930 个范围/版本对和 900 个排序对，目前零不匹配，外加显式断言）。
- test/symbols.test.mjs — 针对合成包的导出图解析器：带 .ts 后缀的 export *、别名再导出、barrel 中的私有类、无法解析的图，以及过去被错误归属的导入形式。
- test/audit.test.mjs — 针对本机的真实安装运行审计并打印报告；机器特定的值会被打印，但绝不会被断言。它还会重新运行上文描述的整个导出面扫描，作为自洽性预言机。
- test/fixtures.test.mjs + test/fixtures.mjs — 在临时目录中构建合成的 dsh 主目录（profile、已安装插件、fallback、可选源码树），并断言精确的判定结果，包括每条启动失败路径和每种符号检查结果。
- test/tar.test.mjs — 针对它不应接受的归档文件测试提取器。
- test/inspect.test.mjs — 针对本地 HTTP 服务器（而非 npm）端到端测试预安装工具：版本选择、完整性验证、拒绝路径穿越和链接条目、临时目录清理，以及“未安装任何内容”的保证。
- test/plugin.test.mjs — 演练 apply 契约、所有优雅降级路径，并使用 dsh 自带的 schema 验证器验证两个手写的工具定义。
- test/integration.test.mjs — 通过真实的 Cordis Context 和真实的 ToolRuntime 加载插件，然后检查两个工具确实对模型可见，并在卸载时被释放。

布局

dsh-community-plugins/
├── index.js                  # 插件入口
├── lib/
│   ├── audit.js              # 环境探测 + 判定
│   ├── semver.js             # 感知 rc 的范围匹配（无依赖）
│   ├── skills.js             # SKILL.md 提供者
│   ├── symbols.js            # 导出图解析
│   ├── tool.js               # 离线工具 + 渲染器
│   ├── registry.js           # 注册表访问 + 完整性
│   ├── inspect.js            # 预安装审计
│   ├── inspect-tool.js       # 联网工具 + 渲染器
│   └── tar.js                # 加固的 tar 读取器
├── test/                     # Node 原生测试，无框架
├── cordis.patch.yml          # Bundle 补丁层
├── package.json              # dsh.bundle 清单
├── README.md                 # 英文
├── docs/lang/README_zh.md    # 中文
└── skills/dsh-community-plugins/SKILL.md

修改技能内容
编辑 skills/dsh-community-plugins/SKILL.md；保存后更改即生效（提供方在每次发现时都会从磁盘重新读取），然后执行 git push 即可分享。对 index.js 或 lib/ 的更改需要重启 dsh —— patchReload: live 只会重新读取 cordis.patch.yml，并不会替换源模块。

相关文档

- DeepSeek Harness 官方仓库
- 官方文档（英文）
- 官方文档（简体中文）
- 打包与安装插件
- 插件与生命周期
- GitHub dsh-plugin 主题

许可证

MIT