@zaogaogwc/dsh-plugin-manager

Readme

# DSH Plugin Manager

[![CI](https://github.com/Zaogaogwc/dsh-plugin-manager/actions/workflows/ci.yml/badge.svg)](https://github.com/Zaogaogwc/dsh-plugin-manager/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/%40zaogaogwc%2Fdsh-plugin-manager)](https://www.npmjs.com/package/@zaogaogwc/dsh-plugin-manager)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

[English](./README.en.md) | **简体中文**

![DSH Plugin Manager：面向 DeepSeek Harness 的 Mod 风格插件管理](https://raw.githubusercontent.com/Zaogaogwc/dsh-plugin-manager/main/assets/social-preview-final-v4.png)

`@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 执行热重载。

```mermaid
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 后执行：

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

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

### 从源码安装

```powershell
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：

```powershell
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 启停方案 |
| `<profile>/.dsh-plugin-manager-backups/` | 包更新备份及待重启状态 |

## API 概览

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

## 源码结构

```text
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/                 纯逻辑、持久化、更新和客户端状态测试
```

## 开发与验证

```powershell
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 加载后没有注册

典型错误：

```text
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](./LICENSE)