Zaogaogwc/dsh-plugin-manager

DSH 插件管理器

CI
npm
License: MIT

DSH Plugin Manager：面向 DeepSeek Harness 的 Mod 风格插件管理

@zaogaogwc/dsh-plugin-manager 是面向 DeepSeek Harness（DSH）Web GUI 的 Mod 风格插件管理器。它把分散的来源包、Loader 实例和 Agent 预设整理为可理解、可预览、可撤销的管理界面。

入口：设置 → 插件 → 插件管理。

本项目管理“是否启用”，不会把“禁用”伪装成“卸载”。插件文件与 npm 依赖不会因禁用而删除。

为什么需要它

当 Web profile 安装多个插件包后，用户通常会遇到三个问题：不知道某个插件来自哪个包、不清楚它当前由 Loader 还是 Cordis 管理，以及为了某项任务临时切换一组插件时容易改错配置。

本管理器使用三级视图解决这些问题：

1. 方案或来源包：官方/用户 Agent 预设与已安装来源包在同一级展示。
2. 功能分类：按文件、终端、规划、Web、设置等用途分组。
3. 插件实例：展示实际 Loader 条目、配置状态、Cordis FiberState 和诊断信息。

例如，example-package/plugin-a 与 example-package/plugin-b 会明确显示为 example-package 的包内成员，而不是两个来源不明的独立插件。

主要能力

插件浏览与来源归属

- 从当前 profile 的 bundle 清单和 bundle patch 还原真实安装来源。
- 展开来源包后查看包信息、功能分类、插件实例和当前状态。
- 官方目录元数据随包发布，不收录用户安装的第三方包信息。
- 第三方说明保留作者原文；AI 分类结果只保存在本机浏览器中。

安全启停

- 单个插件、分类和整包都可以启用或禁用。
- 所有批量操作必须先进入变更预览，再由用户确认。
- 原子写入 ~/.dsh/cordis.patch.yml 的专属 managed 段。
- 保留最近 20 次变更历史，可撤销上一次管理器操作。
- “恢复全部默认状态”只清除本管理器托管的禁用项。
- managed 修复会清理重复或失效条目，同时保留其他工具和用户手写配置。

遵循 Harness 生命周期

管理器不会直接篡改运行中的 Cordis Fiber。确认启停后，它只更新补丁文件，由 DSH 官方 plugin-include watcher 和 Loader 执行热重载。

flowchart LR
UI[插件管理界面] --> Preview[变更预览]
Preview --> Confirm[用户确认]
Confirm --> Patch[原子更新 cordis.patch.yml]
Patch --> Watcher[官方 include watcher]
Watcher --> Loader[Loader 生命周期]
Loader --> Cordis[Cordis FiberState]
Cordis --> UI

- 普通启停通常由 watcher 热重载，不需要管理器自行操作 Fiber。
- 已经运行的 Agent 会话保持创建时的能力代际。
- 新建 Agent 预设只影响之后创建的会话。
- npm 包更新涉及 Host 与 Client 代码一致性，完成后明确要求重启 DSH。

状态与诊断

界面区分配置、Loader、Cordis 和管理器推导状态，不把不同层级混为一谈。

| 字段 | 含义 |
| --- | --- |
| availability | live、configured、disposed 或预设中的 declared |
| configState | Loader 配置层的 enabled 或 disabled |
| fiberState | Cordis 的 pending、loading、active、failed、disposed、unloading 或 absent |
| status | 界面主状态，包括运行中、已禁用、未运行和需要重启 |
| issue | 依赖缺失、加载失败等独立诊断信息 |

“需要重启”是管理器根据更新状态推导的提示，不会冒充 Cordis 原生状态。

Mod 启停方案

可以将当前 Web profile 的第三方插件启停状态保存为具名方案，例如“写作”“开发”“极简”。

- 方案只记录启停状态，不复制或删除插件文件。
- 应用方案前仍然显示变更预览。
- 多个方案彼此独立，可更新、应用和删除。
- 损坏的方案存储会停止写入，避免覆盖原数据。

Agent 预设生成

Agent 预设与 Mod 启停方案是两种不同对象：

| 对象 | 控制范围 | 生效时间 | 存储 |
| --- | --- | --- | --- |
| Mod 启停方案 | 当前 Web profile 的第三方宿主插件 | watcher/Loader 应用补丁后 | 管理器本地状态目录 |
| Agent 预设 | 新 Agent 会话可使用的能力组合 | 此后创建的新会话 | DSH Agent 预设目录 |

创建新预设时，可以选择任意官方预设或用户预设作为基础。差量合并会保留来源预设的专有工具、配置、注释和管理器暂不认识的条目。

AI 辅助筛选

输入自然语言需求后，AI 可以为第三方插件生成分类或启停建议：
- AI 只返回候选方案，不直接执行。
- 用户必须进入变更预览并再次确认。
- 官方工具分类由随包目录提供，不交给 AI 改写。
- 不会把本机第三方插件信息写入发布包源码。
- AI 服务不可用时，基础浏览、手动启停和方案管理仍可使用。

官方工具双语简介

随包提供的官方工具简介包含中文和英文，并订阅 DSH 官方 locale 服务。切换 DSH 语言后，官方简介同步切换；第三方简介保持作者原文，不自动翻译。

npm 来源包更新

对于从 npm registry 安装的第三方来源包，管理器可以：

1. 使用当前 profile 的 registry 查询最新版本。
2. 显示已安装版本与目标版本。
3. 再次确认后调用 DSH 官方插件更新命令。
4. 更新前备份 profile 依赖清单、锁文件和 managed 状态。
5. 验证安装版本；失败时自动回滚。
6. 若整包原本全部禁用，更新新增的子插件也继续保持禁用。
7. 更新成功后标记“需要重启”，直到新 DSH 进程接管。

本地链接、Git、URL、压缩包、npm 别名和官方包不会误走 registry 一键更新。

安全边界

- 官方宿主组件和管理器自身不可在本界面禁用。
- 禁用不会卸载、删除或改写第三方包文件。
- 所有会写文件、调用 AI 或执行更新的 API 都要求 loopback 请求。
- 从 LAN 地址访问 Web UI 时，这些敏感 API 会返回 403。
- 更新可能执行目标 npm 包允许的安装脚本，确认框会明确提示风险。
- 管理器只拥有补丁和自身状态文件，不接管 Cordis/Loader 生命周期所有权。

环境要求

- Node.js ^22.19.0 或 >=24.0.0
- DeepSeek Harness Web profile
- 与 package.json 中 peer dependencies 兼容的 DSH/Cordis 版本
- 构建源码时需要 pnpm 和 tsdown

安装

从 npm 安装

发布到 npm 后执行：

dsh plugin --profile web add @zaogaogwc/dsh-plugin-manager
dsh web

打开 http://127.0.0.1:3080，进入 设置 → 插件 → 插件管理。

从源码安装

git clone https://github.com/Zaogaogwc/dsh-plugin-manager.git
cd dsh-plugin-manager
pnpm install --frozen-lockfile
pnpm test
pnpm build
dsh plugin --profile web add link:
dsh web

Windows 路径包含空格时，可以创建无空格 junction：

New-Item -ItemType Junction -Path D:\dsh-plugin-manager -Target (Resolve-Path .)
dsh plugin --profile web add link:D:/dsh-plugin-manager

构建必须生成 lib/index.js 和 lib/client.cjs。Client 产物必须通过 DSH __ModuleLoader__.load 注册，不能发布为未注册的裸浏览器 ESM 文件。

使用流程

禁用单个插件、分类或整包

1. 展开来源包，查看包简介和实际插件数量。
2. 点击“禁用”，页面会自动滚动到确认区。
3. 检查直接变更和依赖影响。
4. 确认应用，等待 Loader 返回稳定状态。

保存和应用 Mod 方案

1. 调整当前第三方插件启停状态。
2. 在“Mod 启停方案”输入名称并保存当前状态。
3. 需要切换时选择该方案并检查预览。
4. 确认后由 watcher/Loader 应用。

基于现有预设创建新 Agent 预设

1. 展开一个官方或用户 Agent 预设。
2. 点击“以此为新预设基础”。
3. 调整所需能力，填写新标识符和显示名。
4. 生成并验证预设；它将供之后创建的 Agent 会话使用。

数据与文件

| 路径 | 用途 |
| --- | --- |
| ~/.dsh/cordis.patch.yml | 本管理器写入专属 managed 禁用段 |
| ~/.dsh/plugin-manager/history.json | 最近的启停历史 |
| ~/.dsh/plugin-manager/mod-schemes.json | 具名 Mod 启停方案 |
| /.dsh-plugin-manager-backups/ | 包更新备份及待重启状态 |

API 概览

Host 端注册 /api/plugin-manager/* 路由族，包括目录与来源读取、AI 分类和推荐、批量变更预览与应用、历史和撤销、恢复与修复、Mod 方案、npm 更新及 Agent 预设创建。

源码结构

src/
index.js            Host 入口与路由注册
routes.js           清单、AI、批量事务、历史、更新与预设 API
inventory.js        bundle 来源、Loader/Cordis 快照、预设投影
catalog.js          官方双语元数据、组合生成与差量合并
persist-toggle.js   原子 managed patch、历史、撤销、恢复与修复
mod-schemes.js      独立的 Mod 启停方案存储
package-update.js   registry 检查、profile 备份、更新与回滚
client/
index.js          React 管理界面和状态交互
api.js            同源 API 客户端
test/                 纯逻辑、持久化、更新和客户端状态测试

开发与验证

pnpm install --frozen-lockfile
pnpm test
pnpm build
pnpm pack:check

发布前建议至少验证：

1. “插件管理”标签出现且不会阻断其他客户端模块。
2. 单项、分类和整包操作都会先进入确认区。
3. cordis.patch.yml 只改变本管理器 managed 段，重启后状态仍存在。
4. 恢复默认和 managed 修复不影响其他配置段。
5. Mod 方案和 Agent 预设互不混淆。
6. npm 更新成功后提示重启，失败时能恢复 profile 和锁文件。
7. 切换 DSH 语言时，官方工具简介在中英文之间切换。

常见问题

Client bundle 加载后没有注册

典型错误：

loaded without registering "@zaogaogwc/dsh-plugin-manager" via __ModuleLoader__.load

通常是 lib/client.cjs 未重新构建、浏览器缓存旧包，或 package.json、cordis.patch.yml 与 Loader banner 的包名不一致。运行 pnpm build，确认三处都使用新包名，再重启 DSH 并刷新页面。

点击禁用后没有变化

- 检查页面是否已自动滚动到“变更预览”。
- 官方宿主组件和管理器自身受保护，不能从本界面禁用。
- LAN 访问会触发 loopback 围栏；请使用 127.0.0.1 或 localhost。
- 检查 managed 状态，并留意依赖缺失、加载失败或需要重启提示。

为什么包更新后必须重启

插件启停只改变 Loader 配置，可以由 watcher 热重载；包更新会同时替换 Host 和 Client 代码。重启用于保证两端加载同一版本，不应以局部热替换冒充完整更新。

禁用是否等于卸载

不等于。禁用仅写入 Loader 补丁；包仍保留在 profile 依赖和磁盘中。卸载必须显式执行 DSH 插件移除命令。

已知限制

- 管理界面本身目前以中文为主；官方工具简介支持跟随 DSH locale 切换中英文。
- AI 分类与推荐依赖当前 DSH 模型服务，结果只作为候选方案。
- 一键更新仅支持可识别的 npm registry 第三方来源。
- loopback 围栏会阻止从 LAN 页面执行敏感写操作。
- 管理器展示当前 profile 的可观测状态，不能替代 DSH/Cordis 底层日志诊断。

隐私说明

发布包只包含官方目录元数据和通用逻辑，不包含作者或用户机器上安装的第三方插件清单。README 和封面中的第三方名称均使用 example-package 等示例词。

许可证

MIT