一句话定位

在 DSH Web 设置页嵌入「插件管理」面板 + 4 个 agent 工具，0 patch 统一管理 profile 插件安装态：bundle 层栈、insert 行、启停与版本检查都走官方机制，不直接改源码。

核心能力

• 在 DSH 设置页新增「插件管理」tab，列出全部已加载插件与版本状态，按「运行中 / 预设挂载 / 已停用」三态展示，并区分用户安装 / 官方内置 / 管理工具自身。
• 一行安装入口：输入 npm 包名或 GitHub URL（含 https://github.com/o/r、github.com/o/r、github:o/r 三种写法自动规范化），按包是否声明 dsh.bundle 自动分流：bundle 进层栈（重启生效），非 bundle 写 insert 行（配置 HMR 实时挂载，无需重启）。
• 已加载插件的运行时启停：停用/启用即时生效并持久化到 profile patch；bundle 形态支持更新（pnpm update）与卸载（pnpm remove + reconcile）。
• 注册 4 个 agent 工具（plugin_search / plugin_install / plugin_uninstall / plugin_status），agent 与面板写同一份安装态，支持命令行化批量运维。
• npm registry 版本检查：原生 fetch 查最新版（不走子进程，受限宿主也能用），6h 缓存 + 30 秒防抖，git/link 源自动识别为「本地」无 latest。

技术实现

• 语言: TypeScript（Node half）+ TypeScript + React 18（Browser half）
• 关键依赖: cordis ^4.0.0-rc.7（host 半插件运行时）/ react ^18.2.0（browser 半面板）/ @deepseek-ai/dsh-tools ^0.1.0-rc.5（agent 工具注册 defineTool）/ yaml ^2.4.0（profile patch 解析写入）
• 架构模式: 官方 bundle 双半插件——Node half 通过 dsh.bundle.patch 注册 plugin-console cordis 插件，挂载到 web profile 的 webServer（/api/plugin-console 路由）+ loader（读 loader 树条目）+ tools（注册 4 个 agent 工具）+ agentPresets（preset 挂载标注）四个 inject 服务；Browser half 通过 dsh.client.inject 把 React 面板挂到 settings.section 插槽
• 入口文件: packages/plugin/console/src/index.ts（Node half）/ packages/plugin/console/src/client/index.ts（Browser half）/ packages/plugin/console/cordis.patch.yml（bundle 注入声明）

适用场景

DSH 用户装了多个第三方 bundle 或非 bundle 插件，需要在 Web UI 集中查看/启停/更新，不想逐个手动改 profile 配置或重启服务。 agent 开发者需要在受控的 DSH 流程里自动安装/卸载插件（例如做 setup 流程、CI 内验证插件），希望走官方机制而非绕过 pnpm。 想做一个干净的环境试装不同插件组合，又不想每次都进 cordis.patch.yml 手写 YAML——面板+工具直接接管安装态读写。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:vlln/plugin-registry

配置项

常见问题

Q: 装好之后在 DSH Web 的哪里能看到管理面板？

A: 装好后刷新 Web 页面，进入设置页会多出一个名为「插件管理」的 tab（位于官方「插件」tab 旁），点击即加载面板。

Q: 非 bundle 插件安装完为什么不需要重启 DSH？

A: 面板走的是 profile cordis.patch.yml 的 insert 行写入；DSH 0811 起 profile-boot 挂载 watch-only HMR 实例，写行/删行实时生效。

Q: bundle 插件为什么装完还要重启 web？

A: bundle 插件装在 profile package.json 的 dependencies + dsh.profile.bundles 层栈里，层栈在启动时合成，运行时不能热插拔。

Q: agent 怎么用这套安装机制？需要切到面板吗？

A: 不必。Node half 同时注册 4 个 defineTool 工具（plugin_search / plugin_install / plugin_uninstall / plugin_status），与面板写同一份安装态。

Q: 面板显示的「运行中 / 预设挂载 / 已停用」三态怎么区分？

A: 运行中 = host 启用；预设挂载 = host 停用但 agent preset 仍挂载（0811 模型面工具走 preset 通道，停用 host 不等于工具消失）；已停用 = 完全停用。

Q: 能不能在面板里把这个管理工具自身停用或卸载？

A: 不能。Node half 在 toggle/remove 路由里硬性禁止对 @dsh-external/plugin-console 操作，返回 409——避免管理入口自毁。

Q: 安装失败时提示「pnpm add succeeded but X is not in the profile dependencies」是什么意思？

A: 通常是 git 源或路径源未真正落盘（pnpm 退出 0 但依赖未写入 package.json），不会继续写安装态以免假成功；改用明确包名或确认 git/路径可达后重试。

Q: 插件有新版本时怎么更新？

A: 面板点「检查更新」按钮触发 Node half 用原生 fetch 查 npm registry 6h 缓存（30 秒最小间隔防抖），bundle 露出「更新」按钮，点后走 pnpm update（重启生效）；git/link 包标记为「本地」无 latest。

上手难度

入门 — 装完即用，无配置项；高级用户通过 agent 工具接入自动化流程，无需读源码。

已知问题与限制

• bundle 插件的安装/更新/卸载需要重启 web（层栈启动时合成），运行时仅支持启停；非 bundle 插件（insert 行）才实时挂载（packages/plugin/console/README.md:73-75）。
• Node half 改动需要重启 web（ESM 缓存），Browser half 改动只需重装 + 刷新页面（packages/plugin/console/README.md:75）。
• profile cordis.patch.yml 被删除为空时，HMR 会因 YAML 解析为 null 而 reload 失败——Node half 写入逻辑保留注释+[]模板的兜底结构（src/index.ts:206-211）。
• 安装源字符串若是 npm scoped 包（如 @scope/name），profile patch name 字段必须加引号——YAML 中 @ 是保留指示符，裸写会导致 HMR 不生效（src/index.ts:140-145）。
• Windows 下 pnpm / npm 命令通过 .cmd 批处理垫片调用会触发 libuv EINVAL，Node half 改为直接 spawn <node>\node_modules\npm\bin\npm-cli.js 或 %APPDATA%\npm\node_modules\pnpm\bin\pnpm.mjs JS 入口，入口找不到时回退 .cmd（src/index.ts:382-403）。
• 浏览器面板自定义 tab 图标走 MutationObserver 监听 DOM 替换，仅匹配文本为「插件管理」的 tab（不会误改官方「插件」tab 的齿轮图标），曾因重名误换过图标（src/client/index.ts:18-42）。
• 已加载插件的「预设挂载」标注依赖宿主 agentPresets 服务可读，服务不可用时退化为普通已停用（src/index.ts:484-498）。

plugin-registry

DSH 插件生态基建：薄控制台 + 官方插件开发引导
浏览器面板管理 profile 插件安装态（bundle 层栈 + insert 行 + 启停），零补丁； `make-dsh-plugin` skill 引导开发者按官方格式写插件。

---

转向（2026-08）：官方 0809 推出仓库插件机制（.dsh-plugin）覆盖旧独立机制 ~95%，本仓库收敛为 薄控制台 + 插件开发规范和引导（旧 patch/CLI/面板已移除）。0811 起官方删除 repository-plugins 机制（vendor/loader/src/repository.ts），外部插件统一经 web profile 安装： bundle 插件（dsh.bundle 包）进 dsh.profile.bundles 层栈；非 bundle 插件（纯 cordis 包）经 profile cordis.patch.yml insert 行挂载（配置 HMR 实时生效）。完整评估见 官方 0809 覆盖度。

定位

DeepSeek Harness 官方机制管「插件是什么、怎么跑」；本仓库补两件事（面板结构见 console README，开发引导见下文）：

1. 薄控制台（packages/plugin/console）——管理 profile 插件安装态的浏览器面板 + 4 个 agent 工具
2. 开发规范和引导——make-dsh-plugin skill + cookbook，指导创建官方 bundle / cordis 插件

生态关系（谁能干什么）

官方 DSH（DeepSeek Harness）     插件运行时 + profile bundle 机制（0811 起无 repository 机制）
   │
   ├── 官方插件（bundle）        loop / task-status / navbar 等——`dsh plugin --profile web add` 装进 profile 层栈
   ├── 第三方插件（bundle/纯插件）独立 GitHub 仓库或 npm 包——bundle 进层栈；纯插件走 insert 行（实时）
   │
   └── 本仓库（plugin-registry） ① 薄控制台：管理安装态的浏览器面板 + agent 工具
                                ② make-dsh-plugin skill + cookbook：引导开发第三方插件

插件形态与安装路径说明见 插件类型对比；现有插件的安装示例见 examples。

薄控制台

设置页「插件管理」面板管理 profile 插件安装态：安装插件区（统一入口——输入 npm 包名或 GitHub 项目：https://github.com/o/r / github.com/o/r / github:o/r，URL 自动规范化——自动 pnpm add，bundle 插件进层栈、非 bundle 写 insert 行）+ 已加载插件区（版本检查/更新、disabled 启停持久化、bundle 卸载）。

安装

方式一：git 源直接安装（推荐，真一行）

dsh plugin --profile web add "github:vlln/plugin-registry#main&path:/packages/plugin/console"

构建产物已入库（git 源安装不触发构建），一行命令直接装（实测约 15 秒）。

方式二：本地目录（有源码时）

git clone https://github.com/vlln/plugin-registry
cd plugin-registry/packages/plugin/console
dsh plugin --profile web add .   # 产物已入库，无需构建；当前目录即 bundle 包子目录（dsh 锚定 . 为绝对路径）

挂载后刷新 Web 页面，设置页出现「插件管理」面板。

Agent Skills

开发前须知（踩过的坑）

关键坑（官方包未发布、Node half 改动需重启、宿主 CSS 覆盖等）与完整清单见 skill references/gotchas——开发前先读。

文档

• 插件类型对比 — bundle 插件 vs 纯 cordis 插件：开发/分发/安装/管理四维 + 选型
• 官方 0809 覆盖度评估 — 官方机制覆盖度、转向决策（含 0811 repository 移除说明见 CHANGELOG）
• 薄控制台设计 — 统一管理安装态的设计
• 历史机制文档（已转向，仅存档）：架构（旧）、创建插件（旧）、清单格式（旧）、创建 repository-plugin（旧） 等
• 变更记录 / 路线图

版权

MIT License。见 LICENSE。