dsh-plugins/dsh-loader

Banner

dshloader

一个版本感知的运行时兼容垫片，让第三方插件在 dsh（DeepSeek Harness）升级过程中无需修改即可继续工作。

DSH Plugin

English

一个面向 dsh（DeepSeek Harness）cordis bundle 插件的运行时兼容垫片。
dshloader 通过一个版本感知的适配器注册表，将第三方插件与 dsh 的内部服务名、
模块路径、包名以及 RPC 细节解耦，因此当 dsh 升级并破坏内部 API 时，你只需升级
dshloader —— 插件无需修改即可继续工作。

为什么

dsh 迭代很快，其内部接口在不同版本之间会发生变化：

- httpServer 被重命名为 webServer —— 注入 httpServer 的旧插件会永远挂起。
- 像
@deepseek-ai/dsh-client-runtime/src/client/sessions/context-provenance.ts
这样的深层源码导入，会在 dsh 不再提供 src/ 时失效。
- 像 @deepseek-ai/dsh-client-ui-primitives 这样的客户端 UI 包，可能会在未来的
dsh 版本中被重命名，从而破坏每一个直接导入它们的插件。
- 官方的 dsh-host-apiproxy 硬编码了设置命名空间白名单，
因此第三方设置卡片永远不会出现在 Web UI 中。

dshloader 将这些（以及未来的）破坏性变更吸收在一个稳定 API 之后：
宿主端的 ctx.dshLoader、浏览器端的 window.__dshLoader__，以及用于包导入的
@dsh-plugin/dsh-loader/ 稳定子路径。

快速开始

1. 将 dshloader 安装到某个 profile

dsh plugin --profile  add /path/to/dshloader
or
DSH_HOME=~/.dsh npx dshloader setup

2. 插件 package.json —— 只依赖 dshloader

{
"dependencies": {
"@dsh-plugin/dsh-loader": "link:..."
}
}

插件绝不能声明任何 @deepseek-ai/ 依赖。 所有 dsh
包都应通过 dshloader 的稳定子路径访问。

3. 宿主端 —— 使用 ctx.dshLoader

export const inject = ['dshLoader'];

export async function apply(ctx) {
// Settings: register a namespace
const scope = ctx.dshLoader.settings.register('my-plugin', schema);

// Web: register routes and WebSocket upgrades
ctx.dshLoader.web.get('/api/my-plugin/status', (req, res) => res.json({ ok: true }));
ctx.dshLoader.web.registerUpgrade({ path: '/ws/my-plugin', handler: fn });
// 服务：读取 cordis 服务
const sessions = ctx.dshLoader.services.get('sessions');
}

4. 通过稳定子路径导入 dsh 包

// 宿主包
const { defineTool } = require('@dsh-plugin/dsh-loader/tools');

// 客户端 UI 包（在客户端 bundle 源码中）
import { IconCloseFill14 } from '@dsh-plugin/dsh-loader/ui-primitives';

稳定子路径 → 真实 dsh 包映射（dsh 1.x）：

| 稳定子路径 | 真实 dsh 包 |
|---|---|
| @dsh-plugin/dsh-loader/tools | @deepseek-ai/dsh-tools |
| @dsh-plugin/dsh-loader/llm | @deepseek-ai/dsh-llm |
| @dsh-plugin/dsh-loader/agent | @deepseek-ai/dsh-agent |
| @dsh-plugin/dsh-loader/settings | @deepseek-ai/dsh-settings |
| @dsh-plugin/dsh-loader/ui-primitives | @deepseek-ai/dsh-client-ui-primitives |
| @dsh-plugin/dsh-loader/ui-slots | @deepseek-ai/dsh-client-ui-slots |
| @dsh-plugin/dsh-loader/ui-settings | @deepseek-ai/dsh-client-ui-settings/client |
| @dsh-plugin/dsh-loader/web-react | @deepseek-ai/dsh-client-web-react |
| @dsh-plugin/dsh-loader/schema-form | @deepseek-ai/dsh-client-schema-form |
| @dsh-plugin/dsh-loader/runtime | @deepseek-ai/dsh-client-runtime/client |

当 dsh 重命名某个包时，只需修改 dshloader 适配器——插件
源码和 bundle 保持不变。

5. 客户端侧——使用 window.__dshLoader__

// 读取 cordis 客户端服务
const conv = window.__dshLoader__.services.get('conversation');

// 在运行时注册包别名（回退方案）
window.__dshLoader__.registerPackageAlias('@old/pkg', '@new/pkg');

6. 构建配置——将稳定子路径标记为 external

const CLIENT_EXTERNALS = [
'react', 'react/jsx-runtime', 'react-dom', 'react-dom/client', 'cordis',
'@dsh-plugin/dsh-loader/ui-primitives',
'@dsh-plugin/dsh-loader/ui-slots',
'@dsh-plugin/dsh-loader/ui-settings',
'@dsh-plugin/dsh-loader/web-react',
'@dsh-plugin/dsh-loader/schema-form',
'@dsh-plugin/dsh-loader/runtime',
]

工作原理

plugin ──▶ ctx.dshLoader.{settings,web,services} ──▶ dshloader adapter
│
▼
real dsh (current version)

plugin bundle ──▶ require('@dsh-plugin/dsh-loader/ui-primitives')
│
▼ (__ModuleLoader__ wrapper maps stable name)
require('@deepseek-ai/dsh-client-ui-primitives')
│
▼
dsh module table

1. 版本检测读取 node_modules/@deepseek-ai/dsh/package.json
（或使用 DSHLOADER_DSH_VERSION 用于测试/覆盖）。
2. AdapterRegistry 为检测到的版本选择最佳适配器
（精确匹配 → 范围匹配 → 就近向下回退 → 明确报错）。
3. 选定的适配器注册服务别名，安装包名
映射钩子（宿主：Module._resolveFilename；客户端：
__ModuleLoader__.load 包装器），以及（仅在明确选择启用时）设置
白名单绕过桥接。所有注册都使用 ctx.reflect.provide /
ctx.effect，因此 cordis 会在 fiber 卸载时自动回收它们。

加载顺序无关紧要。 cordis 是响应式依赖注入：
声明了 inject: [...] 的插件会保持 PENDING 状态，直到别名
被提供，无论 dshloader 在 cordis.patch.yml 中处于什么位置。

设置白名单绕过（exposeAllNamespaces）

默认情况下，dshloader 不会绕过官方设置命名空间
白名单。需明确选择启用：

- 环境变量：DSHLOADER_EXPOSE_ALL_SETTINGS=1
- profile 的 package.json：dsh.dshloader.exposeAllNamespaces: true

安全权衡：启用此项会移除官方对浏览器设置访问的默认拒绝
边界。仅在你信任所有已安装插件的 profile 中启用它。

CLI

dshloader setup         将 dshloader 注入到 profile 中（依赖 + 补丁）。
dshloader dump-config   运行 dsh --profile  --dump-config。
dshloader info [profile]         打印 loader 版本、检测到的 dsh 版本、
所选适配器。

回滚 / 禁用

- 每次启动时禁用：DSHLOADER_DISABLE=1 dsh web
- 移除：dsh plugin --profile  rm @dsh-plugin/dsh-loader

项目结构

src/
index.ts            host bundle 入口（name / inject / apply）
client.ts           client bundle 入口（immediately tier）
api.ts              DshLoaderHostAPI 构建
registry.ts         AdapterRegistry + 版本检测
types.ts            共享的 host/client TypeScript 类型
version.ts          loader 版本 + 日志前缀
stable/             稳定子路径再导出（ui-primitives、tools、...）
services/
settings.ts       settings 稳定 API
web.ts            web 稳定 API
services.ts       services 稳定 API（get / alias）
adapters/
dsh-1-x.ts        dsh 1.x 适配器
index.ts          适配器注册
setup.ts            profile 注入 + dump-config + info
bin/dshloader.mjs     CLI 入口
dist/                 编译后的 host 构建产物（tsc 输出，git 忽略）
lib/                  编译后的 client bundle（tsdown 输出，git 忽略）
tsconfig.json         类型检查配置
tsconfig.build.json   host 构建配置（输出到 dist/）
tsdown.client.config.mjs  client bundle 构建配置
docs/
api.md              完整 API 参考（中文）
design.md           设计文档（中文）
tests/                L1（单元）/ 模块（L2）/ 集成（L3）
examples/
sample-plugin/      最小示例插件
dsh-aux-state/      仅使用 ctx.dshLoader 的示例

开发

pnpm install
npm run typecheck   # 对 src/*/.ts 进行类型检查
npm run build       # 编译 host（dist/）+ client bundle（lib/）
npm test            # 所有测试
npm run test:l1     # 单元
npm run test:l2     # 模块
npm run test:l3     # 集成
Node.js >= 18，node --test，无需额外的测试框架。

许可证

LGPL-3.0-only（仅限 GNU 宽通用公共许可证 v3）。参见 LICENSE。