dsh-plugin-mgr

Readme

# dsh-plugin-mgr

[![npm version](https://img.shields.io/npm/v/dsh-plugin-mgr.svg)](https://www.npmjs.com/package/dsh-plugin-mgr)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](#license)

> DeepSeek Harness (DSH) 插件：在 设置 → 插件 页面新增「插件管理」子页面——卡片式管理已安装插件，支持启停切换、详情查看与卸载。
>
> 中文 ｜ [EN](README_EN.md)

![插件管理面板](snapshot1.png)

![插件详情](snapshot2.png)

## 功能 / Features

| # | 形式 | 说明 |
|---|------|------|
| 1 | 已安装插件列表 | 卡片式布局，支持 单列 / 双列 切换（记忆偏好）；显示名称、版本、运行状态、启停开关 |
| 2 | 启动 / 停止 | 通过 profile 用户补丁层（`cordis.patch.yml`）写入 `disabled: true/false`，HMR 约 1s 热生效，跨重启保留 |
| 3 | 详情展开 | 点卡片展开：版本 / 安装来源（npm·GitHub·本地分类 + 版本范围 + 可点击的仓库地址）/ 插件介绍 |
| 4 | 卸载 | 展开详情中的卸载按钮（二次确认），先清理启停行再执行 `dsh plugin --profile <name> remove <pkg>` |
| 5 | 更新检查 + 一键更新 | npm 来源插件自动比对 registry 最新版（结果缓存 5min），有新版时卡片显示「可更新」徽标，详情里一键更新到 latest；更新不冲掉已有启停状态；有更新的包会惰性补查并显示新版本的 npm 发布时间 |
| 6 | 搜索 | 工具栏搜索框（匹配 名称/描述/spec，大小写不敏感）；过滤时计数显示「x / y」，滤空可一键清除 |
| 7 | 运行错误展示 | 监听宿主 fiber 状态事件：插件加载失败时卡片显示红色「加载失败」、详情里看错误信息；恢复运行（HMR 修复/回滚重启）自动清除 |

**特性一览：**

- 现代化卡片 UI，设计语言对齐 DSH 官方设置卡片（bg-layer-3 卡面、12px 圆角、hover 提亮）
- 明暗主题适配（全部取主题 CSS 变量），中英双语（语言跟随 harness 设置即时切换）
- 刷新带明确反馈：按钮态变化 + 「列表已刷新 · 时间」横幅
- 安全防护：宿主基础设施模块拒绝启停/卸载；插件管理器自身开关与卸载置灰（悬停提示"本插件"），host 侧 API 双重校验
- 补丁层写入做了串行化（防并发交错）、空 `[]` 占位恢复（防 profile 无法启动）、非法 YAML 拒绝写入
- 更新检查走 npm registry，registry 取用顺序：`DSH_PLUGIN_MGR_REGISTRY` 环境变量 > `npm_config_registry` > profile/.npmrc > ~/.npmrc > npmjs.org（识别 npmmirror 等镜像）；仅查 npm 源插件，宿主模块与自身保护同卸载口径
- 运行错误捕获走 cordis `internal/status` 事件（`global: true` 绕过上下文过滤）：FAILED 按 `fiber.entry.options.name` 归因到包、`fiber.await()` 重抛的错误取消息，回 ACTIVE 清除——不依赖轮询，失败与恢复都是即时感知
- POST 接口校验 `Content-Type: application/json`（CSRF 门卫）+ 64KB 请求体上限

## 实现方式 / How it works

插件分为 host 侧与 client 侧两部分（`package.json` 的 `dsh.client` 字段声明 client 入口）：

```
┌─ host 侧  src/index.ts → dist/index.js ─────────────────────────┐
│  ctx.webServer.register：                                          │
│    GET  /api/plugin-manager/list     读取 profile 依赖+补丁层状态    │
│    GET  /api/plugin-manager/updates  比对 npm registry 最新版本      │
│    POST /api/plugin-manager/toggle   启停（写 cordis.patch.yml）    │
│    POST /api/plugin-manager/uninstall spawn dsh plugin remove      │
│    POST /api/plugin-manager/update   spawn dsh plugin add pkg@latest│
│  profile 定位：loader 的 cordis:include entry 实际路径              │
└──────────────────────────────────────────────────────────────────┘
                          │ fetch (JSON)
┌─ client 侧 src/client.js（浏览器端模块）───────────────────────────┐
│  settings.plugins.tab slot 注入「插件管理」tab                      │
│  React 卡片列表 + switch + 手风琴详情；locale 服务注册 zh/en 词典    │
└──────────────────────────────────────────────────────────────────┘
```

启停机制（与 dshmarket / dsh-plugin-hub 的 plugin console 同源）：profile 用户补丁层逐行覆盖语义，`- id: X` + `disabled: true` 停用、`disabled: false` 强制启用，DSH 配置热重载（HMR）约 1s 内重新组合插件树。

## 安装 / Install

### npm 安装（推荐）

```sh
dsh plugin --profile web add dsh-plugin-mgr
```

### 源码 / GitHub 安装

```sh
git clone https://github.com/oxlyn/dsh-plugin-mgr.git
cd dsh-plugin-mgr && pnpm install && pnpm run build

# 在插件父目录执行（dsh plugin add 相对路径锚定调用目录）：
cd ..
dsh plugin --profile web add ./dsh-plugin-mgr
dsh web
# 启动日志应出现：[dsh-plugin-mgr] ready — routes GET /api/plugin-manager/list ...
```

GitHub 直装（自动跑 prepare 构建出 dist）：

```sh
dsh plugin --profile web add github:oxlyn/dsh-plugin-mgr
```

### 验证 / Verify

打开 `dsh web` → 设置 → 插件 → 「插件管理」tab，应能看到已安装插件卡片。

## 环境要求 / Requirements

- Node `^22.19.0 || >=24.0.0`（DSH 宿主要求）
- pnpm（源码构建用）

## 开发 / Development

```sh
pnpm install
pnpm run typecheck   # 类型检查
pnpm run build       # 构建 dist/
```

项目结构：

```
dsh-plugin-mgr/
├── src/index.ts              # host 入口：插件元数据 + 路由注册 + 单测导出聚合
├── src/server/               # host 侧按职责拆分的模块
│   ├── types.ts              #   共享类型 + cordis Context 声明
│   ├── paths.ts              #   profile / 用户补丁层定位
│   ├── patch-layer.ts        #   补丁层逐行读写（启停落盘）
│   ├── rows.ts               #   每个包拥有的补丁行 id
│   ├── lifecycle.ts          #   dsh CLI 子进程（卸载/更新）
│   ├── fiber-watch.ts        #   运行失败捕获（fiber FAILED 归因）
│   ├── registry.ts           #   npm 更新检查（semver/.npmrc/packument）
│   ├── inspect.ts            #   已安装列表组装
│   └── http.ts               #   JSON 收发 + 参数校验
├── src/shared/api-paths.ts   # API 路径常量（host 与 client 同源引用）
├── src/client/               # client 侧（esbuild 打包为 dist/client.js）
│   ├── main.js               #   boot() 工厂入口 + apply()
│   ├── context.js            #   平台 require 桥（React/hooks/UI 原语）
│   ├── i18n.js               #   zh/en 词典 + fmt
│   ├── styles.js             #   CSS 注入
│   ├── api.js                #   HTTP 封装
│   ├── toast.js              #   Toast 队列 hook + 渲染
│   ├── PluginManagerTab.js   #   tab 主组件（状态编排）
│   └── components/           #   Toolbar / PluginCard / ConfirmModal
├── scripts/build-client.mjs  # esbuild 打包脚本
├── cordis.patch.yml          # bundle 层声明（id/name 走包名解析）
└── dist/                     # 构建产物（npm 发布包含在 files 字段中）
```

client 产物约束：`dist/client.js` 必须是单文件 IIFE，尾部追加
`__ModuleLoader__.load(...)` 调用；平台依赖（react、UI 原语）在运行期经
`context.js` 桥接解析，因此打包无需 external 配置。业务模块禁止在模块顶层
取用平台模块（bundle 求值早于工厂执行）。

## 友情链接 / Links

- [LinuxDo](https://linux.do)

## License

[MIT](LICENSE)