DSH插件描述扩展

English | 中文

看到DSH插件页茫茫多的不知内容的插件感到无从下手?本插件为你补上每一个插件的自我描述，助你轻松挑选自己需要的插件。

给 DeepSeek Harness用的持久化组合插件:在组合里挂一行,Web 设置中的 插件列表页每张插件卡片就都带上中英文功能说明,并发布 pluginDescriptions 服务供其他插件注册自己的说明。

功能特性

• 持久化:一个组合行同时进入宿主组合(Node part)与浏览器插件名册(Client part), DSH 每次启动自动挂载,跨会话生效,不需要任何会话内操作。
• 逐卡说明:插件列表页每张卡片展示中英文功能说明,展开卡片可看完整说明、Loader 条目 id、配置状态与 Cordis 挂载状态。
• 搜索升级:搜索框同时匹配插件名、条目 id 与说明文字;双语随界面语言(zh/en)自动切换。
• 可扩展:内置 134 个模块名的字典只是默认值;任何插件都能通过 pluginDescriptions 服务注册/覆盖说明,优先级高于内置字典。

安装(命令行,持久化)

要求:可正常运行的 DeepSeek Harness Web profile(需要 pnpm,dsh plugin 依赖它)。

本插件是双面 npm 包并声明 dsh.bundle:dsh plugin add 安装后,插件管理器会把 它追加进 dsh.profile.bundles,启动时应用包自带的 cordis.patch.yml 自动插入组合行 (宿主行 + 浏览器名册),不需要手改任何组合文件。

从 GitHub Release 安装(推荐,默认最新版)

npx @deepseek-ai/dsh plugin --profile web add https://github.com/MysaDC/dsh-plugin-description/releases/latest/download/dsh-plugin-description.tgz

上面的命令不带版本号:releases/latest/download 永远指向最新 Release 的固定名安装件, 以后升级重跑同一命令即可。需要固定版本时再写具体版本号(每个 Release 都附带带版本号的 tgz):

npx @deepseek-ai/dsh plugin --profile web add https://github.com/MysaDC/dsh-plugin-description/releases/download/v1.2.1/dsh-plugin-description-1.2.1.tgz

也可以从 Git 安装:不带 #tag 取默认分支的最新代码,带上 #tag 则固定版本 (无需构建:仓库提交了 lib/ 构建产物,安装时不跑任何脚本):

# 最新代码(默认分支)
npx @deepseek-ai/dsh plugin --profile web add github:MysaDC/dsh-plugin-description

# 固定版本
npx @deepseek-ai/dsh plugin --profile web add github:MysaDC/dsh-plugin-description#v1.2.1

安装后重启:

npx @deepseek-ai/dsh web

若 pnpm 提示 ERR_PNPM_ADDING_TO_ROOT,在 profile 目录的 .npmrc 加一行 ignore-workspace-root-check=true 再重试。

验证

npx @deepseek-ai/dsh web --dump-config | grep -n "plugin-description"

输出中出现 plugin-description,并且在「设置 → 插件 → 插件列表」中每张卡片都带说明, 即表示已加载。

升级与卸载

# 升级到最新版:重跑一次安装命令即可(pnpm 会重新解析 latest 安装件)
npx @deepseek-ai/dsh plugin --profile web add https://github.com/MysaDC/dsh-plugin-description/releases/latest/download/dsh-plugin-description.tgz

# 固定到指定版本(可选)
npx @deepseek-ai/dsh plugin --profile web add https://github.com/MysaDC/dsh-plugin-description/releases/download/v1.2.1/dsh-plugin-description-1.2.1.tgz

# 卸载(依赖与 bundle 层一并移除,组合文件不被改写)
npx @deepseek-ai/dsh plugin --profile web remove dsh-plugin-description

随后重启 dsh web 生效。

本地开发(改仓库源码)

# POSIX:链接本仓库,重建后重启即生效
dsh plugin --profile web add link:$(pwd)

# Windows(pnpm 8 对盘符 link:/file: 规格有解析问题):打 tgz 再装
npm run build && npm pack --pack-destination dist
npx @deepseek-ai/dsh plugin --profile web add .\dist\dsh-plugin-description-<版本>.tgz

手动安装(不想用命令行时)

1. 下载 Release 的 dsh-plugin-description-v<版本>.zip,把解压出的整个包目录放到 <DSH_HOME>/profiles/node_modules/dsh-plugin-description/;
2. 在 profile 的 cordis.patch.yml 加一行(内容同本仓库根目录的 cordis.patch.yml);
3. 重启 DSH。

自定义与新增说明(普通用户)

不用改代码、不用重新打包,直接在页面上编辑:

1. 在「设置 → 插件 → 插件列表」展开任意插件卡片,点 编辑说明;
2. 填写中文/英文说明,点 保存。默认同名的所有卡片一起改(按插件记);勾选 「只改这一张卡片」则只改当前这张,同名的其他卡片保持原样——适合同一插件被加载 多次且各次用途不同的情况;
3. 被自定义过的卡片会带 「已自定义」 徽标,编辑态里点 恢复默认 即可退回内置说明。

改动会持久化到用户字典文件 <DSH_HOME>/plugin-descriptions.json(与 settings.yaml 同级),升级、重装插件都不会丢;也可以直接用文本编辑器修改它,重新打开页面即生效:

{
  "modules": { "@your-scope/your-plugin": { "zh": "中文说明", "en": "English description" } },
  "entries": { "your-row-id": { "zh": "只改这一张卡片的说明" } }
}

说明的最终优先级:用户字典 > 插件运行时注册 > 内置特殊条目 > 内置字典。出于安全, 界面写操作只接受本机(回环地址)请求,与 DSH 设置 API 同级约束。

接入说明:让其他插件注册自己的说明

本插件的 Host 半在宿主组合发布服务 pluginDescriptions,同一 DSH 进程内的任何 Host 侧插件(组合行)都可以这样接入:

return {
  apply(ctx) {
    const descriptions = ctx.get('pluginDescriptions')   // 可选读取,必须判空
    if (descriptions === undefined) return
    ctx.effect(() => descriptions.register([
      // 按模块名注册(同模块的多个 Loader 条目共享这条说明)
      { moduleName: '@your-scope/your-plugin', zh: '你的插件的中文说明。', en: 'English description.' },
      // 按 Loader 条目 id 注册(精确到某一条组合行,优先于模块名)
      { entryId: 'your-row-id', zh: '针对特定条目 id 的说明。' },
    ]))
  },
}

契约细节:

• register(entries) 接收 { moduleName?, entryId?, zh, en? } 数组,返回一个 disposer,精确撤销本次注册的条目;放进 ctx.effect 随插件 fiber 生命周期清理。
• resolve(moduleName, entryId) 按 entryId → moduleName 顺序查询注册表。
• 最终显示优先级:用户字典 > 运行时注册表 > 内置特殊条目(codex/claude-code) > 内置字典。
• 作为硬依赖时也可以声明 inject: ['pluginDescriptions'],Cordis 会在服务出现前挂起插件。
• 本插件自己也吃自己的狗粮:它在 apply 里通过同一服务注册了自身 (dsh-plugin-description)的说明,插件列表页里那张卡片就是这么来的(内置字典里也有该条目,双保险)。

把说明合入仓库(对所有人生效,仅对各插件作者开放)

1. 直接编辑 descriptions/plugin-descriptions.json,新增 "<moduleName>": { "zh": "...", "en": "..." }。
2. 或运行再生器:准备一个 DSH checkout,执行 node scripts/regenerate-descriptions.mjs <checkout路径>,它会从各包 README 提取 首段,叠加 scripts/regenerate-descriptions.mjs 里的 OVERRIDES 人工校对表后重新生成字典。
3. npm run build 后提交 PR。

构建与发布

npm run build           # src + 字典 → lib/{index,client}.js、dist/package/
npm run verify          # 构建 + 完整校验(字典完整性、模块 id、exports 契约;CI 用)

常见问题

浏览器页白屏或启动失败? 本插件只做可选服务读取(ctx.get 判空),没有硬注入依赖,不会阻塞引导。若确实出现,把组合行disabled: true 即可排除。

想改某条说明文字? 三种方式:页面里点「编辑说明」直接改(立即生效,普通用户首选); 插件作者用 pluginDescriptions.register 运行时覆盖;或改descriptions/plugin-descriptions.json 后 npm run build 并更新 profile 里的包(提交合并后对所有人生效)。

官方插件的说明是哪里来的? 内置字典提取自 DeepSeek Harness 各官方包的 README 首段, 并经人工校对;个别条目(id 级,如 codex/claude-code 后端)有专属说明。

License

MIT