前言¶

DeepSeek Harness（DSH）采用「一切皆插件」的扩展方式：装得多了之后，启停、找版本、批量升级往往要反复打开插件市场或敲 plugin_manager 命令，分组与排序也没有统一入口。Plugin Shelf（dsh-plugin-shelf，侧栏名「插件书架」）是一个客户端 bundle，面向已经装进当前 profile 的插件，在侧栏面板里做排序、分组、筛选、一键启停，以及基于 npm registry 的检查和批量更新。维护者为 QYF-888；社区目录见 SkillHub 插件页，源码在 GitHub。SkillHub 为社区独立站点，与 DeepSeek / 幻方无官方从属关系。

这是什么¶

Plugin Shelf 是 DSH 第三方 bundle：host 半在 webServer 上注册精确路由 /plugin-shelf/api，汇总 pluginManager.listBundles() 并读写本地状态；client 半注册侧栏「插件书架」与主页面板，数据全部经该 API 获取。它不替代插件市场的「发现与首次安装」，而是把已安装列表当成可编排的书架来管。

兼容范围（README / package.json）：dsh >= 0.2.0-rc.1 < 0.3.0；profile 支持 desktop / web / headless。当前包版本 1.1.2，许可证 MIT。

核心功能¶

下面按 README 功能表归纳，均可在面板中操作。

浏览与整理¶

• 排序：按名称、安装时间、大小排序，可切换升序 / 降序。
• 分组：新建任意分组；分组支持行内重命名（✎）、上下移序、折叠、删除；插件可移入某组或回到「未分组」。
• 未分组：「未分组」区也可重命名、折叠，状态会持久化。
• 移出分组：分组内每行行首红色「−」，点击后回到未分组；未分组行无此按钮。
• 加插件浮窗：分组头「+ 加插件」或新建分组后弹出；只列出当前不在任何分组的插件，支持搜索、全选、清空、勾选后加入。
• 筛选：状态下拉（全部 / 已启用 / 已停用）、分组下拉、「只看可更新」，与搜索框叠加；计数行显示命中 / 总数，可「清空筛选」。
• 显示范围：默认只列 installed === true 且 availability === 'profile' 的插件；可选「显示内置」查看 DSH 自带包（不可管理）。

启停¶

• 每个插件单独开关。
• 每个分组可「启用本组 / 停用本组」。
• 顶部可「全部启用 / 全部停用」。

更新¶

• 版本探测：不依赖 pluginManager.inspect（对已装包会 refused('already-installed')），改为读 npm registry 的 dist-tags.latest；默认源 https://registry.npmjs.org，面板可改并写入 state.autoUpdate.registry。
• 自动更新：定时对比 registry 与本地版本；可只检查或自动安装，可限定只处理某些分组；host 侧每 60 秒检查是否到点（面板关闭仍会继续）。
• 一键更新：自动更新卡片右侧「一键更新（N）」；第一次点击变为「确认一键更新？」，4 秒内未确认则复原；确认后对 profile 内插件逐个执行 removeBundle → installBundle，汇总成功 / 总数 / 排队 / 失败。
• 更新失败：展示原因、pendingBuilds 时可「批准并重试」；restart-required 会明确提示。
• 中断修复：更新过程写 journal（pending-updates.json），面板顶部可一键续装；横幅可关闭或清理记录。

单次更新采用「移除再安装」：当前 DSH 的 installBundle 对已安装包会抛 already-installed，无法原地升级。失败会回滚；若 removeBundle 因 bundle-in-use 失败，会停用并排队，重启后由 repairUpdates 完成安装。

卸载¶

每行行尾红色「✕」：第一次点击变为「确认卸载」，5 秒内再点一次才执行；host 调用 pluginManager.removeBundle，并清理分组记录与 journal。内置插件（removable === false）按钮禁用。插件仍被挂载时，管理器会先停用并写 step: 'uninstall' 的 journal，重启后由 repairUpdates 完成卸载。

安装与启用¶

装完后重启 DSH，侧栏应出现「插件书架」。官方 README 给出四种方式，任选其一：

1. 从 npm 装（推荐：npm 来源才能被本插件的自动更新接管）：

plugin_manager install_bundle target=dsh-plugin-shelf

2. 插件市场：在 DSH 插件市场搜索 dsh-plugin-shelf 或「插件书架」，一键安装。

3. 从 GitHub 装：

plugin_manager install_bundle target=github:QYF-888/dsh-plugin-shelf

4. 本地目录（开发时）：

plugin_manager install_bundle target=D:\path\to\dsh-plugin-shelf

说明：若 profile 内来源为 file: / link: / git+ / github: 等，自动更新会跳过并在结果中标记 non-npm-source，其余管理功能仍可用。README 还提到：本机依赖须为 1.1.2 或 link: 指向源码目录；若被「一键更新」换成 git+https://github.com/QYF-888/dsh-plugin-shelf.git 且该地址停在旧提交，面板可能回退到旧客户端行为。

典型用法¶

日常整理¶

1. 打开侧栏「插件书架」。
2. 用排序与搜索缩小列表，按项目新建分组并重命名。
3. 通过「+ 加插件」把未分组插件批量加入某组；需要时用行首「−」移回未分组。
4. 用状态下拉或分组下拉配合「只看可更新」做例行检查。

批量启停¶

实验或排障时，可先对单个分组「停用本组」，确认无问题后再「启用本组」；全局切换用顶部「全部启用 / 全部停用」。

检查与更新 npm 来源插件¶

1. 在自动更新卡片配置 registry（如需非默认源）、是否自动安装、限定分组等。
2. 使用「只检查」或等待定时任务；对可更新项使用「一键更新（N）」并按二次确认流程执行。
3. 若出现 build-blocked，在面板「批准并重试」；若提示 bundle-in-use 或 restart-required，按面板说明停用、重启或续装。
4. 面板可展开运行日志，查看每次检查与安装结果。

自测（维护者脚本）¶

仓库提供 host Harness 自测，不依赖完整 DSH 桌面环境：

node test/host-harness.mjs

脚本在假 profile 上挂载真实 index.js，覆盖更新、回滚、跨源拒绝等分支，见 README「自测」一节。

数据、权限与注意¶

• 状态与日志：$DSH_HOME/plugin-shelf/state.json（未设置 DSH_HOME 时为 ~/.dsh/plugin-shelf/state.json）；更新中断记录为同目录下 pending-updates.json。UI 筛选等偏好双写服务端 state 与浏览器 localStorage['dsh-plugin-shelf:ui-prefs']。
• API 安全：路由带 Origin 时需与 Host 同源，否则 403。
• 更新范围：仅处理 availability === 'profile' 且来源为 npm-like 的包；file: / link: / workspace: / portal: / git+ / github: / http(s): 等会跳过。
• 运行权限：插件以当前 DSH 进程权限读写本机 DSH_HOME、调用 pluginManager 与 registry；安装前请自行查看源码与 MIT 许可证，确认符合你的环境策略。
• Node：package.json 要求 node ^22.19.0 || >=24.0.0。

结尾¶

Plugin Shelf 把「已装插件列表」收成一块可排序、可分组、可筛可搜的书架，并把启停与 npm 侧的版本检查、批量「移除再安装」更新接到同一面板；适合插件数量较多、需要按场景分组或定期统一升级的 DSH 用户。

• 社区目录：https://www.skillhub.cn/plugins/QYF-888/dsh-plugin-shelf
• GitHub：https://github.com/QYF-888/dsh-plugin-shelf