# dsh-web-ui

> The Plugin Management tab in DSH web version supports npm/git installation, enable/disable toggles, conflict rollback, and failed repair session handling.

## Metadata

- Author: [@zhu1090093659](https://github.com/zhu1090093659)
- Repo: <https://github.com/zhu1090093659/dsh-web-ui.git>
- GitHub: [zhu1090093659/dsh-web-ui](https://github.com/zhu1090093659/dsh-web-ui)
- Stars: 5,125
- Language: TypeScript
- License: [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)
- Homepage: <https://gallery.dsh-market.com>
- Topics: `deepseek-harness`, `dsh`, `dsh-plugin`, `web-ui`
- Forks: 310
- Open Issues: 49
- Last push: 2026-08-20T14:37:38.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:zhu1090093659/dsh-web-ui/packages/dsh-plugin-manager
```

## Wiki

## 一句话定位
给 DSH 网页版设置页的"插件"分区补上一个"插件管理"标签页，可以从 npm 或 git 装新插件、对已装插件做下次启动生效的启停切换、查看更新并卸载，安装时遇到的冲突能一键撤销或交给 Agent 修复。它的存在让你不用回命令行就能管插件。

## 核心能力
- 在官方"插件"设置分区追加"插件管理"标签页（与官方安装器 Tab 并列），并把同一个交互入口作为 `pluginManager` cordis 服务暴露给兄弟插件调用。
- 从 npm 包名或 git 仓库 URL 安装插件，安装期间持续返回进度（fetch/download/extract/write 等阶段），git 源安装会以后台任务方式跑、可能耗时数分钟。
- 列出已装的用户插件，提供"下次启动生效"的启用开关，支持更新检查（npm 源走 registry）、一键更新与卸载。
- 在每次安装/卸载时显示实际的改动（产品行或 profile 行的差异），可一键撤销；每条冲突都给"让 Agent 修复"按钮，自动拉起一个工作区落在插件根目录的修复会话。
- 官方运行时附带启动失败环：每个挂掉的插件都给出"让 Agent 修复"（失败详情作为 seed）+ "复制错误"两枚按钮；npm 运行时没有失败环，只有安装错误本身会带修复转交。
- 显示宿主的安全模式横幅与"恢复正常模式"操作；官方运行时立即生效，npm 运行时则在下次手动重启后生效。

## 技术实现
- **语言**: TypeScript（React 浏览器半边 + Node 宿主半边 + 两侧共享的纯逻辑层）
- **关键依赖**: `@deepseek-ai/cordis`（插件框架 + 服务注入）、`@deepseek-ai/dsh-host-webserver`（注册网关路由）、`@deepseek-ai/dsh-client-runtime`（浏览器端工作区/会话注入）、`yaml`（profile patch 与 package.json 的读写解析）
- **架构模式**: 宿主/浏览器双半结构 + 双通道写入。宿主半边经 `cordis.patch.yml` 以 profile bundle 层插入 web profile，承担 `src/host/gateway.ts` 描述的 CLI 网关与 `src/host/routes.ts` 描述的 HTTP 路由；浏览器半边在 `package.json` 的 `dsh.client` 声明加载，向 `settings.plugins.tab` 槽位注册一个 Tab。写入通道分为两类：带官方安装器服务的运行时（DSHCode、1.0.4 checkout 版 web）走官方 `/plugin-installer` 与 `/plugin-control` 的 loopback RPC；npm 发布的官方 web 没有这两个通道，本包宿主半边挂载一个回环门禁 HTTP 网关，安装/卸载 spawn 官方 `dsh plugin` CLI 作为单一写入器，启停写 profile 的 `disabled` 覆盖行。两通道对调用方完全透明（统一的 `pluginManager` face）。
- **入口文件**: `src/index.ts`（宿主半边）、`src/client/index.ts`（浏览器半边）

## 适用场景
适合把 DSH 网页版当作日常工作台、不想频繁切回命令行的用户：装新插件、停用某个出问题的插件、检查 npm 上的更新、撤销一次失败的安装——都能在设置页内点完。也适合"全家桶"型用户：别的开发者想给自己的插件加一个"安装/卸载按钮"或订阅"插件刚刚装好了"事件时，可以直接 `ctx.inject(['pluginManager'])` 复用本插件的能力，不必自己再对接一遍官方 RPC。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH（@deepseek-ai/dsh-client-*） | ^0.1.0-rc.8 | 本包通过 peer/devDependencies 锁定的官方 SDK 版本；package.json 未声明 `engines` 字段 |
| Node | ^22.19 或 >=24 | 仓库共享约束；本包自身未在 package.json 显式声明 |
| 平台 | macOS / Windows / Linux | Windows 下把 npm 生成的 `dsh.cmd` 解析为 `node.exe` + 包内 `bin.js`，避免 `cmd.exe` 二次解析参数 |
| 原生模块 | 无 | 全部走 Node 内置模块（`node:child_process` / `node:fs` / `node:http` / `node:path`）与 `yaml` 纯 JS 包 |

## 安装方式
```bash
dsh plugin --profile web add github:zhu1090093659/dsh-web-ui/packages/dsh-plugin-manager
```

## 配置项
本插件无需额外配置。Tab 不携带配置命名空间，启停开关与安装动作的生效时机由 DSH 自身的重启机制决定（web 端在下次手动重启后生效）。

## 常见问题

**Q: 安装完为什么设置页里看不到"插件管理"标签？**

A: 需要先重启 dsh web。启停开关与安装动作都在下一次手动重启后才生效，web 端没有壳内重启能力。

**Q: 局域网或远程访问网页时这个标签能用吗？**

A: 不能。网关所有路由都只接受本机回环请求（socket 地址 + Host 头 + 同源标记四重门禁），非本机访问直接返回 403，与官方安装器 Tab 同一边界。

**Q: 从 npm 和从 git 仓库安装有什么区别？**

A: 两者都走官方 `dsh plugin` CLI 完成，但 git 源需要克隆仓库，可能耗时数分钟并以后台任务运行，列表里有进度条可看；host 进程的 PATH 里必须能找到 `dsh` 命令，否则会被网关拒绝。

**Q: 安装后下次启动挂了怎么办？**

A: 官方运行时会有"启动失败环"挂在该插件下，可点"让 Agent 修复"一键拉起修复会话（工作区就是插件安装根），或点"复制错误"取走报错。npm 运行时没有失败环，只有安装错误本身会带修复转交。

**Q: 安装时显示的"冲突"是什么？能不能撤销？**

A: 冲突就是这次安装实际改动的产品行或 profile 行，可一键撤销回到操作前的状态；如果撤销不了或不想手动处理，每条冲突都能"让 Agent 修复"由 AI 自动处理。

**Q: 别的插件想调用本插件的能力要怎么做？**

A: 通过 cordis 服务名 `pluginManager` 注入：`ctx.inject(['pluginManager'], cb)` 后读 `ctx.pluginManager`，可拿到 `list` / `install` / `uninstall` / `status` / `onChange` 这五个方法，`onChange` 在每次成功的安装/更新/卸载/启用变更后回调。

**Q: 启停开关会不会让某些插件再也起不来？**

A: 在 npm 运行时上，启停是通过在 profile 的 `cordis.patch.yml` 写入 `disabled` 覆盖行实现的，但这条路径没有官方桌面写入器经过充分锻炼，建议谨慎用于那些"全家桶聚合包以 patch 行挂载"的插件；官方运行时不受此限制。

**Q: 怎么彻底卸载？**

A: 用 `dsh plugin --profile web remove` 对应的包名后重启 dsh web 即可。本插件没有自己的配置命名空间，不需要再清理配置文件。

## 上手难度
入门 — 安装即用，零配置；用户只需要会"在设置页点几下"就能完成插件的安装、启停、更新与卸载，无需任何命令行操作。

## 已知问题与限制
- 仅限本机回环：LAN 或远程浏览器只显示"仅限本机操作"提示，网关对非 loopback 请求返回 403，与官方安装器 Tab 同一边界。
- npm 发布版官方 web 上没有启动失败环与安全模式：这两处界面降级为空，只有安装错误提供修复转交。
- npm 运行时上启停依赖 `cordis.patch.yml` 的 `disabled` 覆盖行；该路径不如官方桌面写入器经过充分锻炼，且对共享入口 id 不能用 `disabled` 绕开 loader 的重复检查（loader 的去重不认 disabled，写了反而会误伤现有插件）。
- web 端无壳内重启：所有变更都在下次手动重启 `dsh web` 后才生效。
- 安装时冲突检测报告"实际改了什么"（官方模式为产品行；网关模式为 profile 行与 bundle 条目）；npm 运行时上重复 insert-id 会在安装后自动回滚新插件，不会触碰现有插件。
- 重复挂载保护：官方 CLI 的 bundle 对账会把任何声明 `dsh.bundle` 的依赖加回 `dsh.profile.bundles`，包括已被 patch 行挂载的包（如 `dsh-better-sidebar`），会引发 `duplicate prefix route` 启动失败；网关在每次 CLI 变更成功后只剥除"本次新增且已被 patch 行挂载"的条目，正常条目与用户原有条目一律不动。
- 启动预检（`--dump-config`）只组合 patch 层、不 import 条目：能抓组合失败，抓不到 import 期失败——后者仍在首次真实启动时暴露。
- 上游 CLI 残留：官方 CLI 在 Windows 上转发到 pnpm 时仍走 `cmd.exe` shell，本包无法改变，已通过 spec 元字符校验（`& | < >`、引号、反引号、控制字符）作为本仓库内的缓解手段。

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-web-ui](https://deepseek-plugin.org/plugins/zhu1090093659/dsh-web-ui/packages/dsh-plugin-manager)
Wiki generated by AI (model: `MiniMax-M3`)