前言¶

在 DeepSeek Harness（DSH）里做带设置页的客户端插件，通常要同时处理宿主侧注册、浏览器侧 UI、文案与构建产物如何被 dsh plugin add 识别。从零搭目录、package.json 的 exports 与 dsh 清单、cordis.patch.yml 挂接方式，容易在细节上反复试错。下面介绍维护者 longyi-0x0 发布的 dsh-plugin-template：一个不含业务接口与示例业务逻辑的最小插件，保留 TypeScript 宿主入口、React TSX 空设置页、中英双语、esbuild 构建与 vitest 测试，便于用 GitHub「Use this template」复制后改名、加业务再安装验证。

这是什么¶

dsh-plugin-template 是 DSH 插件模板，分类为客户端。仓库：GitHub — longyi-0x0/dsh-plugin-template；社区目录页：skillhub.cn/plugins/longyi-0x0/dsh-plugin-template。当前 package 版本为 0.1.0，许可证 MIT（见仓库 LICENSE）。

它解决的是「先有一个能装、能编、能测的标准骨架」：宿主在 src/host/index.ts 提供 name / inject / apply；浏览器侧是空的设置页骨架；locale/{zh,en}.json 提供插件页 meta 与界面字典；target/index.js 与 target/client.js 为已提交的构建产物，因此通过 link: 或 GitHub 安装时不必在目标机器上现场构建。

目录与入口¶

README 中的目录结构如下（入口由 package.json 的 exports['.'] / exports['./client'] 指向 target/）：

package.json               exports、dsh 清单、脚本与开发依赖
cordis.patch.yml           把插件挂进 DSH 配置树的一行
src/host/index.ts          宿主入口：name / inject / apply
src/host/context.ts        宿主侧最小结构化类型
src/client/index.tsx       React TSX：空设置页 + inject/apply
src/client/i18n.ts         从 locale JSON 导入的类型化字典
src/client/styles.ts       主题变量样式
src/client/context.ts      Slots / Locale / SlotProps 类型
scripts/build.mjs          esbuild：host → target/index.js，client → target/client.js
target/index.js            宿主产物（提交，不要手改）
target/client.js           浏览器产物（提交，不要手改）
locale/{zh,en}.json        meta（插件页标题/简介）+ ui（界面字典）
icon.svg                   插件图标
test/                      vitest：i18n + client 冒烟

核心能力¶

宿主与 Cordis 挂接¶

宿主侧在 apply 中扩展服务、路由或监听器；需要宿主服务时在 inject 中声明名称，并补全 src/host/context.ts。插件通过 cordis.patch.yml 挂入 DSH 配置树；package.json 中 dsh.bundle.patch 指向该文件。

浏览器设置页与插槽¶

客户端平台为 web。默认 dsh.client.inject 激活：

• @deepseek-ai/dsh-client-locale
• @deepseek-ai/dsh-client-ui-settings

client.inject 只控制平台包激活顺序，不是运行期 import。需要其他插槽时，把对应平台包加入该数组；插槽清单可安装 dsh-slot-explorer 查看。浏览器半区最终打包为单个 target/client.js；不 import DSH Client 运行期包，UI 结构、主题与可访问性需按 DSH 规范自行实现。

双语与类型化文案¶

locale/{zh,en}.json 是唯一文案来源：

• meta.title / meta.description：插件列表展示，宿主直接读取；
• ui：界面字典，经 src/client/i18n.ts 在 esbuild 构建时内联进 target/client.js。

en.ui 的键自动成为 MessageKey，zh.ui 须补齐相同键，t('key') 在编译期检查。

构建与校验¶

开发依赖 Node >= 20。常用脚本：

npm install        # 开发与 CI
npm run build      # 生成 target/index.js、target/client.js
npm run dev        # 监听 src/ 自动重建
npm run build:check# 校验提交的 target/ 与源码一致
npm run typecheck  # host + client 两套 tsc
npm run check      # build:check + typecheck + test

宿主：esbuild 打包 src/host/index.ts → target/index.js（ESM，Node 内置模块 external）。浏览器：esbuild 打包 src/client/index.tsx → CJS，react / react/jsx-runtime external，再套 window.__ModuleLoader__.load({ id: <package name>, factory })。target/client.js 文件头标注为生成文件，勿手改。

测试¶

npm test           # vitest run
npm run check      # build:check + typecheck + test

覆盖中英字典键一致性、浏览器 bundle 的模块 id / factory / 插槽注册；组件不做渲染测试。CI 在 .github/workflows/test.yml 中执行 npm ci 与 npm run check。

从模板到新插件¶

1. 在 GitHub 上对仓库点 Use this template 创建新仓库。
2. 按 README 表格改名：package.json 的 name（建议 dsh-plugin-<名字>）、cordis.patch.yml 的 name（须与包名一致）、src/client/i18n.ts 的 NS、locale/*.json 的 meta/ui、icon.svg。
3. 在 src/host/index.ts 的 apply 与 src/client/index.tsx 中加入业务；需要时在 dsh.client.inject 中增加平台包。
4. 本地执行 npm install、npm run build、npm test，并提交 target/index.js / target/client.js；CI 用 build:check 防止产物过期。

安装与启用¶

产物已提交，link: 或 GitHub 安装均不需要在安装端构建。安装后需重启 DSH；若修改并重新构建 target/client.js，也需重启应用（浏览器 bundle 在启动时装配）。

macOS（示例 profile 名为 desktop）：

"/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh" \
  plugin --profile desktop add "link:/path/to/your-plugin"

或从 GitHub 安装（将 your-name/your-plugin 换成你的仓库）：

dsh plugin --profile desktop add "github:your-name/your-plugin"

Windows：

& "$env:LOCALAPPDATA\Programs\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd" `
  plugin --profile desktop add "link:C:\path\to\your-plugin"

清单字段（摘录）¶

"dsh": {
  "manifestVersion": 1,
  "bundle": { "patch": "./cordis.patch.yml" },
  "client": {
    "platform": "web",
    "inject": [
      "@deepseek-ai/dsh-client-locale",
      "@deepseek-ai/dsh-client-ui-settings"
    ]
  }
}

适用场景与注意¶

适合需要客户端设置页 + 宿主扩展、并希望沿用 TypeScript、React、esbuild 与 vitest 工作流的 DSH 插件作者。默认无 CSS Modules，样式使用主题变量与 React style 对象；locale/*.json 的 ui 会内联进浏览器 bundle。组件渲染与安装后的外观仍须在运行中的 DSH 里验证。

DSH 生态理念是「一切皆插件」；社区目录 skillhub.cn 为独立站点，与 DeepSeek / 幻方无官方从属关系。插件在当前 dsh 进程权限下运行，安装前应阅读源码并确认 MIT 等许可证是否满足你的使用条件。本文未使用 git clone 作为安装步骤；请以 README 中的 dsh plugin add 与本地 link: 为准。

结尾¶

dsh-plugin-template 提供的是无业务的最小可安装骨架：Cordis 挂接、React 空设置页、双语、构建产物与冒烟测试一并就绪，便于复制后专注业务逻辑。

• 目录页：https://www.skillhub.cn/plugins/longyi-0x0/dsh-plugin-template
• GitHub：https://github.com/longyi-0x0/dsh-plugin-template