dsh-web-plugin-manager

61Star4Fork0Issue0Watching

DeepSeek Harness 的 Web 端插件管理器：可视化启停/安装/更新/卸载插件，含质量门、健康检查和第三方插件市场。

LX2000WASDLX2000WASD
·LX2000WASD/dsh-web-plugin-manager.git
语言
TypeScript
License
MIT
分支
master
dshdsh-plugin

安装

$ dsh plugin --profile web add github:LX2000WASD/dsh-web-plugin-manager

在终端中运行以上命令，通过 dsh CLI 安装此插件。可在右上角切换 Profile。 第一次用 dsh？看这篇新手教程

一句话定位

给 DeepSeek Harness 写的"插件控制中心"。在 Web 设置面板里集中查看、启停、安装、卸载、更新 DSH 插件，并附带安装前的质量门、运行后的健康检查和一个第三方插件市场，避免手动改 cordis.patch.yml 和裸跑 pnpm add 带来的翻车。

核心能力

  • 在 Web UI 中查看 profile 下所有已装插件（bundle 与非 bundle 两类），按需启用或禁用，不需重启 profile
  • 一键安装/卸载插件，支持 npm 包名、GitHub 仓库、本地路径、tarball 等多种来源
  • 检查并执行插件更新（包含管理器自身），更新带质量门校验与失败自动回滚
  • 运行依赖图、缺失项、循环依赖、重复行 id、同名注册冲突、peer 兼容性等健康检查并一键修复
  • 浏览第三方插件市场，浏览/搜索/按主题筛选，结合服务端已装判定避免重复安装
  • 管理 profile 环境：启停、复制/转移插件、新建/重命名/删除 profile（官方只读 profile 不可动）、备份导出与恢复

技术实现

  • 语言: TypeScript（服务端 + 浏览器端均 TS，客户端含 .tsx）
  • 关键依赖: @deepseek-ai/cordis（宿主框架）、@deepseek-ai/dsh-tools（agent tools 与 guard）、@deepseek-ai/schemastery（Config 校验）、undici（marketplace 网络请求）
  • 架构模式: Cordis 双面插件 — 服务端（src/index.ts）注册 PluginManagerService 与 /api2/plugin-manager/* REST 路由；浏览器端（src/client/index.ts）注册 catalog/manager/environments 三个 settings Tab 与 kinds/marketplace 两个 settings.section；通过同源 fetch 通信；安装链路 installWithSource→installProtected 整体串行互斥；通过 live.ts 直接调 loader entry.update 让 patch 变更不重启生效
  • 入口文件: src/index.ts:4669（host apply）+ src/client/index.ts:75（client apply）

适用场景

日常使用 DSH 时遇到这些情况会用到它：profile 里塞了一堆插件但忘了谁在干啥、想装一个第三方仓库又担心装坏 profile、需要把配置好的 profile 复制到另一台机器、或者只想搞清楚某个插件被谁依赖、为什么没生效。

前置依赖与兼容性

依赖最低版本说明
DSH 宿主@deepseek-ai/cordis ^4.0.1、@deepseek-ai/dsh-tools ^0.1.0-rc.6由 peerDependencies 声明
校验库@deepseek-ai/schemastery ^3.18.1、js-yaml ^4.3.1由 peerDependencies 声明
Node 类型@types/node ^22.0.0devDependencies，未在 engines 中硬约束
运行平台Node 主机（跨平台） + Web profile 浏览器端client.platform=web；host 用 undici 与 node:fs，无原生模块
原生模块无仅 Node 内置模块与 undici

安装方式

dsh plugin --profile web add github:LX2000WASD/dsh-web-plugin-manager

配置项

配置类型说明默认值
profile字符串决定 agent 工具（plugin_status/install/uninstall/toggle）作用的目标 profile 名web

其他参数（如 marketplace 缓存 TTL、会话 TTL）写死在源码中，不通过 Config 暴露：SESSION_TTL_MS（15 分钟，src/installSession.ts:23）、REGISTRY_MAX_AGE_MS（6 小时，src/registry.ts:80）。

常见问题

Q: 这个插件和官方自带的插件列表是什么关系？

A: 它通过 cordis.patch.yml:13-14 显式禁用官方只读清单 ui-settings-plugin-inventory，自己注册 catalog 与 manager 两个 Tab 取而代之；移除本插件后官方清单自动恢复。

Q: 强烈建议先装管理器再装别的插件？

A: 是的。管理器的质量门会在每次安装时跑依赖图、未声明 import、官方包重复、bundle patch 行校验；健康检查在运行期和静态都能用，能显著减少"装上就炸、重启起不来"的情况。

Q: 跟 AI 提了装插件但它跑的是裸 dsh plugin add 会怎样？

A: src/guard.ts 注册的工具守卫会拦截 dsh plugin add/remove/update 以及指向 profile 的 pnpm/npm/yarn/bun add/remove，拒绝原因里直接指路 plugin_install / plugin_uninstall / plugin_toggle 工具或 dshpm CLI，模型会改走受保护链路。系统提示里也有一条常驻规则提示同样的事。

Q: 安装过程中需要 API Key 这类环境变量怎么办？

A: src/scan.ts 在安装前扫描仓库的 README/.env/package.json/yaml/install 脚本，匹配 TOKEN/KEY/SECRET/PASSWORD/PASS/CREDENTIAL 形态变量；命中后会暂停安装并在 UI 里弹出表单填写，提交的值只按白名单注入 pnpm 子进程，其他宿主敏感键不会外传给第三方 prepare 脚本。

Q: 怎么用命令行版本？

A: 插件自带 dshpm bin（在 profile 的 node_modules 里），命令包括 install / remove / update / mount / list / analyze / uninstall-kind，所有变更走与 Web UI 完全一致的受保护链路，非交互式场景里也能用 --env KEY=value 续装。

Q: 市场里看到的插件怎么判定我装没装？

A: 服务端 src/registry.ts 通过包名、repository URL 双向匹配、git 源（gitHead）以及本地目录探测综合判定；同名包冲突会自动消解；列表会标"已装"且禁用重复安装。

Q: 健康检查能修问题吗？

A: 能。A 级问题（影响启动的重复行 id、循环依赖等）可一键修复；B 级问题（peer 版本警告、官方包重复等）需确认后修复；语义冲突（同逻辑不同名）检测不到，因为没有同名可比。

上手难度

入门 — 安装后即在「设置」出现新 Tab，绝大多数操作点 UI 即可；只有 CLI/质量门白名单等进阶场景才需要看文档。

已知问题与限制

  • 禁用被依赖的条目可能导致 profile 启动失败（官方 fail-loud 设计）；需手动删除 cordis.patch.yml 里的 managed 块恢复
  • 安装来自 git 的 bundle 需在终端放行 pnpm allowBuilds（命令输出会回显缺失项）
  • 随机行（无显式 id 的挂载行）不可经本管理器启停，因为 id 每次挂载都会变
  • 多包仓库的 git 子包安装需用 #path:<dir> 约定指定子目录，子目录必须位于克隆缓存内
  • 质量门可能误伤未声明运行时依赖的插件（保守策略），可通过白名单豁免
  • 官方包默认只能作为 peerDependencies，普通依赖会装出第二份副本并劫持官方 loader 行；豁免白名单为 @deepseek-ai/schemastery 与 @deepseek-ai/cosmokit（详见 src/analyze.ts:55）
  • 安装守卫只拦 agent 工具调用，拦不住用户在终端手工执行裸 dsh plugin
  • 本地目录安装（非 git）的更新检测报告"不可检测"；git URL 源需 manifest 记录安装 commit（gitHead）
  • 健康检查为静态+尽力而为：同名注册冲突依赖源码正则扫描（动态拼接的名字检测不到）；语义冲突无同名可查，不在检测范围
  • 手动通过官方 CLI 安装的依赖不会自动挂载，本管理器会显示"未挂载"并提供"挂载"/dshpm mount，不擅自改变 profile 行为
  • 环境变量过滤只覆盖 TOKEN/KEY/SECRET/PASSWORD/PASS/CREDENTIAL 形态，未匹配形态的宿主变量仍可能进入 git 源安装的 pnpm 解析进程（安装为 link 语义，不执行第三方脚本）
  • 市场代理只读 HTTP_PROXY/HTTPS_PROXY；系统代理/规则模式加速器对 Node 进程无效（undici 不读系统代理）
  • 市场索引项目（DSH-Plugins-Marketplace）为第三方维护；GitHub API 未认证限流 60/h 仅影响 catalog 独有条目的星数富化，列表本身不受影响
返回插件目录