会话插件面板 KuramiWan/dshp-plugin-panel

dshp-plugin-panel

npm
MIT
DSH

为 DeepSeek Harness 开发的会话级插件管理面板。随时添加、移除你的插件，热插拔生效，会话隔离，便捷的可视化面板。同时管理插件、skills、MCP。

🚀 会话级技能 | 可视化面板 | 插件 & MCP 管理 | 多数改动免重启 | 一条命令安装

Highlights | Who it is for | Quick start | Skill management | Plugins and MCP | How it works | Architecture | Troubleshooting | FAQ

🌐 English | 中文

版本说明。 本 README 描述当前发布版本。若你的安装里缺少文档中的某项能力，请对照 CHANGELOG.md 检查已安装版本。

插件面板：全局层、可用池、本会话已引入，三区一屏

Highlights

技能

- 会话级技能管理。 按会话引入、移除技能。每个会话有自己隔离的技能集，可热插拔，会话之间互不泄漏；宿主重启后，resume 的会话自动重放引入集。

插件 & MCP

- 插件管理。 启用/停用用户安装的插件、插件的冷挂载与热插拔状态随时切换。全在「插件」页签里，无需手改配置文件。
- 会话 MCP。 按会话添加、拆除会话级 MCP 连接，与全局配置互相独立。

Who it is for

1. 你想要一个可视化总览，在一个设置节里用鼠标控制你的技能与插件。
2. 你想要技能按会话隔离 —— 一个会话引入的，不进入任何其它会话。
3. 你想启用/停用或热插拔 DSH 插件，而不必重启宿主。
4. 你想要按会话的 MCP 连接，而不用手改配置。

Quick start

1. 安装

dsh plugin --profile web add @super_camel/dsh-plugin-panel

或从源码安装：

dsh plugin --profile web add github:kuramiwan/dshp-plugin-panel

2. 重启并打开面板

重启 dsh web，打开 设置 → 插件面板（Plugin Panel）。你会看到两个页签：

- 技能 —— 全局层、可用池、本会话已引入。
- 插件 —— DSH 已加载的插件，以及会话 MCP。

3. 试一试

在「技能」页签里搜索你的可用池并引入一个技能 —— 它只在本会话可用。在「插件」页签里切换一个插件，立即生效（patch 挂载）。

Skill management

「技能」页签是日常入口，展示三组：

- 全局层（~/.dsh/skills）—— 进程级、每个会话都可见的技能；可激活/停用、打 tag。（全局生效）
- 可用池（~/.dsh/.skill-pool/local/）—— 你自己管理的技能。放一个文件夹进去即纳入管理，删掉即移出。（此处的技能不会在任何地方生效）
- 本会话 —— 从可用池引入到当前会话的技能；在这里移除，立刻消失。（会话级别生效）

技能支持搜索、展开详情，自行分组。

引入技能只需一次点击，面板会提示引入集已持久化 —— 宿主重启后，resume 的会话会自动重放：

点一下「加入本会话」，技能即刻只对本会话生效

高级工具 —— 斜杠命令与模型工具

同样的操作也可脱离面板进行，方便自动化或交给模型：

/skill-browse 列出你的可用技能 /skill-search 搜索你的可用技能 /skill-introduce 把技能引入本会话 /skill-list 列出本会话已引入的技能 /skill-remove 从本会话移除技能

模型也可以自己调用 session_skill_browse、session_skill_search、session_skill_list、session_skill_introduce、session_skill_remove。

Plugins and MCP

「插件」页签列出 DSH 已加载的插件，按挂载方式分组：

- 系统内置 —— 随 DSH 提供，只读。
- 用户安装（patch） —— 从 cordis.patch.yml 挂载；启用/停用立即生效，无需重启。
- 用户安装（bundle） —— 从 dsh.profile.bundles 挂载；启用/停用需重启。
- MCP —— 会话级连接，单独管理。

插件页签：热插拔（patch）插件即时启停、冷挂载列表，以及 MCP 区

新增插件

「新增插件」 按钮可让你直接从面板登记插件 —— 填入包名（或 id）即可。插件默认以 已停用 状态登记（只写面板状态文件，不改 cordis.patch.yml、不触发热重载），出现在「热插拔」段；点 「启用」 才热挂载进宿主。勾选 「添加后立即启用」 可跳过这一步，登记即挂载。

让 bundle 插件热插拔

用 dsh plugin install 安装、且声明了 dsh.bundle.patch 的插件会以 bundle 方式挂载：DSH 只在启动时读取一次 dsh.profile.bundles，所以启用/停用要重启才生效。

「提升为热插拔」 按钮把 bundle 插件转成 patch 插件，之后即可免重启启停：

1. 点插件上的 「提升为热插拔」。面板把它从 dsh.profile.bundles 移除，并重写已安装包的 package.json、去掉它的 dsh.bundle 声明（就地 fork），让 DSH 不再把它当 bundle。
2. 重启 DSH。
3. 点 「启用」。插件改从 cordis.patch.yml 挂载，启用/停用立即生效。

注意： 重写发生在 node_modules 里，pnpm update 或 dsh plugin update 会覆盖它、恢复 dsh.bundle 声明 —— 更新后需重新提升。原始 package.json 备份为 package.json.bak，需要回退时可用。

侵入式插件

有些插件不局限于 DSH 的插件接口，而是直接 monkey-patch DSH 的内部服务（如 subprocess、sandbox、terminals）或修改 process.env，并可能在安装时单向复制文件（如 agent preset）。

面板只能挂载/卸载插件，无法撤销插件在进程内已经施加的改动：

- 运行时 monkey-patch 不可逆 若插件修改了服务原型却没有返回 disposer，停用后这些改动仍留在内存里，只有重启 DSH 才能清除。
- 单向文件同步会残留 若插件在安装时复制了文件（如 agent preset），卸载时不会删除它们，需要你手动清理。
- 绕过沙箱 某些 Windows 兼容插件会为 shell 工具关闭文件沙箱；停用插件后沙箱要重启才恢复。

安装会深入 DSH 内部的插件前，先确认它 patch 了什么、能否干净地回退。

Session MCP

会话 MCP 连接只作用于当前会话。白名单一个服务器、为本会话连上、用完断开 —— 面板把它隔离在全局配置之外。

面向模型的 MCP 工具

模型可以自己用 session_mcp_list、session_mcp_connect、session_mcp_disconnect 管理会话 MCP。

How it works

DSH 自身的模型就是 everything is a plugin（一切都是插件）：宿主是一个组合，组合里每个可挂载行（cordis composition line）都是插件 —— skill 是插件提供的文档能力，MCP 是 mcp-client 组合行，宿主插件是 patch/bundle 组合行。面板并不引入第二套模型：它只是给这个组合层一个管理视图，仅在你管理时把 技能 vs 插件 作为展示区分。

Interactive version: how-it-works.zh.architecture.html · Source: how-it-works.zh.architecture.json

文字版（Mermaid）

flowchart TB
subgraph PANEL["dshp-plugin-panel"]
PANELNOTE["它自己也是 patch 插件，挂在 cordis.patch.yml给你的 DSH 组合层加一个管理视图"]
end

PANEL -->|"暴露"| VIEW["管理视图：DSH 组合层的可管理界面everything-is-plugin（一切能力都是组合行）"]

VIEW --> SKILL["技能能力（会话级）引入 = 注册：指回池目录，不复制文件落盘 <poolRoot>/.session-skills/<sessionId>.json，resume 后重放"]
VIEW --> MCP["MCP 能力（会话级）mcp-client 组合行 · 会话级连接/断开"]
VIEW --> HOST["宿主插件（进程级）patch：热挂载（改 cordis.patch.yml 即热重载）bundle：冷挂载（改 dsh.profile.bundles，重启生效）"]

HOST -->|"可提升"| PROMOTE["bundle → patch「提升为热插拔」"]

subgraph FRONT["前端管理视图（仅展示区分）"]
TABSKILLS["技能页签全局层 / 可用池 / 本会话"]
TABPLUGINS["插件页签内置 / patch / bundle / MCP"]
end

VIEW -.->|"同一语义层，仅展示区分"| FRONT

1. 一切都是插件。 skill、MCP、宿主插件都是同一个 DSH 组合里的可挂载行；它们的不同只在 挂在哪，不在种类。
2. 两种挂载维度。 会话级能力（引入的技能、连上的 MCP）活在 agent 上下文里、按会话隔离；进程级宿主插件加载进宿主、全局生效。
3. 引入技能是纯注册。 不复制文件 —— 注册指回池目录（~/.dsh/.skill-pool/local/）。引入集落盘到 /.session-skills/.json，宿主重启后 resume 的会话自动重放。
4. 前端只做展示区分。 同一批底层能力被展示为「技能」页签与「插件」页签；斜杠命令与模型工具是无 GUI 的同一管理面。

精确路径、resume 触发点、影子覆盖与 patch/bundle 挂载的完整图见 docs/diagrams/capability-mount.md。

Architecture

管理视图背后的运行路径：面板 UI 经同进程 HTTP 调 PluginPanelService；会话级的技能 / MCP 操作走会话能力管理，进程级插件操作走宿主插件管理 —— 后者写组合层文件，再由 watcher 热重载进 cordis 组合。

可交互版：runtime-architecture.zh.architecture.html · 图源：runtime-architecture.zh.architecture.json · 源码证据 12 处，钉在同一个 commit。

Troubleshooting

| 问题 | 怎么办 |
| 空白新会话里命令结果不显示 | DSH 客户端有意不把命令节点当会话内容。发一条消息或刷新，或在有会话历史的会话里使用命令。 |
| 放进可用池的技能没出现 | 确认它是 ~/.dsh/.skill-pool/local/ 下含 SKILL.md 的子目录。 |
| 全局层（~/.dsh/skills）里的技能没出现 | 确认它是 ~/.dsh/skills 下含 SKILL.md 的子目录；全局层会显示在技能页签的全局分组里。 |
| 出问题但说不清原因 | 跑一次插件调试器，一次导出状态 + 最近错误日志（见下文）。 |

调试插件

面板附带一个独立、只读的诊断脚本，一条命令检查插件状态和最近错误日志 —— 它不需要宿主在运行，也从不修改文件。

pnpm debug # 文本导出：池扫描 + 会话引入集 + 配置 + 一致性检查
pnpm debug --json # 同一份数据，结构化 JSON
pnpm debug --root # 覆盖池根目录
pnpm debug --profile # 覆盖 DSH profile 根目录
pnpm debug --logs 20 # 最多包含 20 条最近的 error/warn 日志

注意： pnpm debug 脚本是开发/源码工具，不会随发布的 npm bundle 一起发布（bundle 只含 lib/index.js、lib/client.js、cordis.patch.yml），且需要 Node ≥ 22.6 —— 请克隆仓库后在源码树里运行。

结构化日志会通过 ctx.logger 追加到 /.dshp-plugin-panel.log（JSON Lines），因此调试器的错误线索与宿主实时日志来自同一数据源。

Agent 指南：面向 AI agent 的可观测性/调试工作流（埋点规范、调试器协议、兼容性、五步诊断）已沉淀在 docs/observability-sop.md。

开发环境

一个 dsh 内核，多个 $DSH_HOME 根隔离环境。生产用默认根（~/.dsh）；开发用项目内根（.dsh-dev/），与生产完全隔离——开发活动不碰 ~/.dsh。
两个根都跑官方 web profile（dsh-base + dsh-web-app + 面板，与生产同组合）； dev/test 差异只在 patch 内容。模型配置与凭证经 config.path 指向生产文件跨根共享（零复制、零软链）。

| 根 | profile | 用途 |
| ~/.dsh | web（npm 发布版） | 生产 |
| /.dsh-dev | web（仓库构建） | 开发（无 fixtures） |
| /.dsh-dev | web + fixtures patch | 测试（dshp-test-plugin + test-mcp-stdio） |

一次性构建（每台机器一次）

1. 构建面板 checkout（clone 后必做；lib/ 不进 git）
cd dshp-plugin-panel && pnpm install && pnpm build

2. 建开发根 + 挂载面板（官方入口：initProfile + pnpm add + reconcile bundles； web 是官方模板，base + web-app 自动带上）
mkdir -p .dsh-dev
DSH_HOME="$PWD/.dsh-dev" dsh plugin --profile web add "$PWD"

就这些。wrapper 脚本（./dsh-dev、./dsh-test）首次运行自动补全：凭证/设置共享 patch（config.path → 生产 ~/.dsh 文件）；web-app bundle 兜底（若 profile 模板组合缺 @deepseek-ai/dsh-web-app 则幂等补入，防止面板 initialized 后无 web 层静默挂起的回归）；./dsh-test 额外补全 fixtures patch（dshp-test-plugin 行 + test-mcp-stdio MCP 桥接行， fixture 包以真副本装入，不软链）。

日常使用 —— 单命令

./dsh-dev --port 3181 # 开发（DSH_HOME=.dsh-dev，web profile） ./dsh-test --port 3182 # 测试（同根，web profile + fixtures）
dsh --profile web --port 3081 # 生产（默认 ~/.dsh，npm 发布版）

面板通过 ctx.baseUrl（dsh 启动时设为 profile 目录）自动探测所在 profile，无需注入 profileDir。

凭证/模型配置共享

开发根经 config.path 把 settings / credentials 指向生产文件（wrapper 自动完成）：

.dsh-dev/profiles//cordis.patch.yml（./dsh- 自动追加）
- id: settings
config:
path: $HOME/.dsh/settings.yaml
- id: credentials
config:
path: $HOME/.dsh/.credentials.yaml

- 模型定义与 API key 直接读生产文件（零复制）
- 开发根保留自己的会话/技能/profile——开发绝不写生产

FAQ

引入技能会复制文件吗？

不会。引入是纯会话注册，资源目录指回原文件夹。

技能会在会话间共享吗？

不会。引入按会话隔离；影子覆盖也只作用于当前会话。

这个包会预置技能吗？

不会。它只管理你自己的文件夹 —— 不预置技能、不做订阅、不做目录。

为什么我装好的技能不显示？

如果技能不可见，请确认它在受管层（local/ 或 ~/.dsh/skills）下、是含 SKILL.md 的子目录，然后刷新面板。

贡献

开发环境搭建、构建与测试见 CONTRIBUTING.md。

License

MIT © 2026 super_camel