dsh-skills-mcp-manager

dsh-skills-mcp-manager

在 DSH 的设置面板里管理「技能」与「MCP 服务器」——全局 / 项目级分层，改完即生效

[!IMPORTANT]

这是自有版本（0.6.0 起），不是任何第三方的发布版。 代码基于 MIT 许可的既有实现演进，

自 0.6.0 起包名统一为 dsh-skills-mcp-manager（无 scope）。

仓库：；

npm：（由 GitHub Actions 的 OIDC

Trusted Publishing 自动发布，带 provenance）。安装命令见下；「设置 → Skills & MCP → 获取技能

→ 插件更新」的更新检查读本仓库的 Release。

能力已扩展到与 @michengai/dsh-skills-manager 对齐：外部 Agent 来源、逐技能/逐来源启停

（不改源文件）、分类、回收站、GitHub 仓库、在线市场（skills.sh / ClawHub）、导入、工作区

视图、侧栏入口。

功能对照、模块地图、必须守住的安全边界、以及安装/迭代流程见 FORK.md；

逐版本改动见 CHANGELOG.md。

DSH 插件：把 Skills 与 MCP 的管理搬进 设置 → Skills & MCP。页面是「两个 tab × 两个层级」——MCP 与技能各自分「全局」和「项目级」；卡片、按钮、间距都对齐宿主内置的「内置插件」页，不 import 任何 Harness Client 包。

• 🗂️ 技能：列表 / 搜索 / 预览全文 / 新建 / 重命名 / 删除，落盘就是 //SKILL.md；删除先备份再删，可手动恢复
• 🔌 MCP：全局条目就是 profile cordis.patch.yml 里的真实 Loader 行，增删改停写回配置文件；项目级条目只挂到该项目里运行的 agent
• 🎛️ 按服务器筛选工具：展开卡片就能看到这一行实际注册了哪些工具（名字 + 描述，来自 harness 自己的工具注册表），并按服务器选择「全部保留 / 只保留勾选 / 只挡勾选」。被挡下的工具不进工具注册表，所以也不占用每次组装工具面的 token——实测一个 chrome-devtools 就有 30 个工具、约 25 KB schema
• 🚦 连接状态圆点 + 一键重连：每张卡片用一个小圆点加一行小字说明状态 —— 🟢可用 · N 个工具 / 🟡连接中 · 约 Ns / 🔴已放弃重试 / 🔴异常 / 🟡需要授权 / ⚪未挂载，需要时在 … 菜单里点「重连」即可恢复——不用重启 DSH。它解决的是一个很坑的场景：DSH 启动时连不上的 MCP，等重试预算用完就永久失效（默认只等 151.5 秒），而以前界面上完全看不出来。「需要授权」是其中单列的一种：需要 OAuth 的服务器被拒绝连接不是故障（dsh-mcp-client 没有 OAuth 支持，401 会被当成网络故障一路重试到放弃），所以它用黄色而不是红色，并说明补授权的办法
• 🎛 每行一个开关 + `…` 菜单：启用/停用是小号开关（同时表达当前档位），重连/编辑/删除收在竖向菜单里。停用的行不显示操作，重连只在启用且确实异常时出现
• 📥 MCP 导入：一键扫描 Claude Code / Cursor / VS Code / Gemini / Codex 等 26 个来源的用户级或项目级配置，预览后导入
• 🗂 一份列表，跨工作区：全局在前、然后按工作区顺序；卡片上的标签说明它属于谁（「全局」或工作区名）
• 🧯 不动坏你的配置：插件里绝不把异常抛出去（DSH 会因此隔离整个 profile 配置），写 cordis.patch.yml 前自动备份（只留一个滚动 .bak）、写前重新校验
• 📦 零运行时依赖：react / yaml 都用宿主已有的那份，插件本体不带第三方运行时依赖

目录：界面预览 · 安装 · 使用 · 工作原理 · 已知边界 · 更多文档 · License

界面预览

MCP 页：全局 / 项目级行、连接状态、逐行开关与 … 菜单。

工具过滤：展开卡片看到该服务器实际注册的工具，按「全部保留 / 只保留勾选 / 只挡勾选」收窄。

技能页：按来源分组、逐技能/逐来源启停；只在磁盘上存在的目录才出现，只读来源不显示写操作。

截图由本仓库构建出的客户端 bundle 离线渲染生成（同一套 stub 加载器 + 示例数据），

不是真机截图——真机截图会把作者自己的服务器地址与项目路径带进 README。重新生成：

```bash

node scripts/screenshots.mjs

`

需要 headless Chrome、SMP_PREVIEW_DIR（含 React 18 UMD）与 SMP_THEME_CSS（--dsw-* token 列表）

三样夹具，缺任何一样都会打印缺什么并跳过（不会假装成功）。

安装

本插件装进 DSH 的某个 profile（$DSH_HOME/profiles/），Host 半在 harness 进程里跑。

从 npm（一条命令）

dsh plugin --profile web add dsh-skills-mcp-manager

桌面端：设置 → 插件 → 安装插件，搜 dsh-skills-mcp-manager 即可（插件市场收录前也可以直接从 npm 或 Releases 下载/安装）。

桌面端：设置 → 插件 → 安装本地包

从 Releases 下载 dsh-skills-mcp-manager-0.6.1.tgz，在 设置 → 插件 → 安装本地包 里选中它，然后重启 DSH。

desktop profile 由桌面应用独占，宿主 CLI 的 dsh plugin --profile desktop 会被直接拒绝。

命令行（GitHub Release / 本地 tarball）

# 装 GitHub Release 里预构建的包：
dsh plugin --profile web add \
  https://github.com/zx2021210538/dsh-skills-mcp-manager/releases/download/v0.6.1/dsh-skills-mcp-manager-0.6.1.tgz

# 或者用本机打出来的 tarball：
npm pack
dsh plugin --profile web add ./dsh-skills-mcp-manager-0.6.1.tgz

重启 DSH，再刷新页面：设置 → Skills & MCP。

升级：dsh plugin --profile add dsh-skills-mcp-manager（或换新 Release 的 tgz 重装一次）； 插件自己的「获取技能 → 插件更新」会读本仓库的 releases/latest 并提示有没有新版（只提示，不自动替换文件）。

卸载：

dsh plugin --profile web remove dsh-skills-mcp-manager

从源码（开发）

git clone https://github.com/zx2021210538/dsh-skills-mcp-manager.git
cd dsh-skills-mcp-manager
npm install
npm run build      # dist/（Host，tsc）+ lib/client.js（Client，esbuild 单文件）
npm run deploy     # 拷贝进 profile；部署前先跑加载冒烟，失败则 profile 一字不动

npm run deploy 的目标是 $DSH_HOME/profiles/desktop/node_modules/dsh-skills-mcp-manager， 旧版本备份成同级的 .backup-（回滚只需改名回来）。仓库不提交构建产物，所以克隆后必须先 build。

之后把包名挂进 profile 的 bundles 并重启：

// $DSH_HOME/profiles/desktop/package.json
{ "dsh": { "profile": { "bundles": [ /* … */ "dsh-skills-mcp-manager" ] } } }

使用

入口：设置 → Skills & MCP（与内置插件页同一套设置槽位）。

• 搜索只匹配名称，不匹配地址 / 参数 / 环境变量
• 一份列表，没有分区标题：全局的排前面，然后按工作区顺序；卡片上的标签说明它属于谁
• 「添加」按钮与搜索框同一行，表单紧贴列表上方（点完就能看到它要追加到的位置）
• 没有项目筛选器：列表跨工作区展示（全局在前，然后按工作区顺序），卡片上的标签说明归属。

新条目要写到哪个工作区，在添加对话框里选

• 卡片标签统一：全局显示「全局」，项目级显示工作区名 —— MCP 与 Skills 同一套词表
• 卡片操作收进 `…` 菜单（预览 / 编辑 / 删除）；技能没有启用开关——磁盘上有文件就是启用

MCP

· 全局 MCP · 项目级 MCP 存在哪 · profile cordis.patch.yml 的 Loader 行 · profile cordis.patch.yml 里带 scope 的 Loader 行 谁去连接 · 官方 @deepseek-ai/dsh-mcp-client 直接加载这些行 · 插件在 agent/created 时按项目路径挂载 生效范围 · 所有会话（含 subagent） · 只有该项目里运行的会话 agent 增删改 · 写回配置文件（加锁 + 原子写 + 写前校验 + 自动备份） · 同一个行命令路由，写回带 scope 的行

• 卡片上的「配置文件」标签表示这一行来自 cordis.patch.yml；这种行可以编辑 / 停用 / 删除，改动通过带鉴权的 POST /dsh-skills-mcp-manager/rows 立即写回（新增/删除在点击瞬间就生效，不等轮询）
• 展开卡片能看传输方式、地址或命令、参数、环境变量（值打码）、范围与启停状态
• 展开卡片的「工具」一栏可以只保留你需要的工具。每个服务器的工具清单下面有三档：

档位 · 含义 全部保留（默认） · 不做任何干预，该服务器列出的工具全部注册 只保留勾选 · 勾选的才注册，没勾的不会进入工具注册表（也不占 token） 只挡勾选 · 勾选的被挡住，其余照常注册

被挡下的工具不只是「不显示」——它们从未注册，所以也不占用每次组装工具面的 JSON schema 体积。 实测本机 chrome-devtools 一个服务器就占 30 个工具、约 25 KB（≈5.8k tokens）， 只留常用的几个收益很明显。

两点如实说明：

• 改动要等该服务器重新注册工具时才完全生效。规则本身是即时读取的（改完保存即可，

不用重启），但已经注册进注册表的工具无法被插件注销，所以已存在的工具不会当场消失。 想立刻看到效果：把这张卡片「停用」再「启用」（几秒即可）——停用会销毁该服务器的桥接、 连带注销它的工具，启用时重新连接并重新注册，于是全部工具重新过一遍过滤；或者重启 DSH。

• 过滤靠劫持工具服务的 register 实现——因为 dsh-mcp-client 自身没有白名单字段，

而 ctx.tools.restrict() 要求 scoped 上下文（全局调用会抛错）、且只遮罩不注销。 这是唯一能真正把工具挡在注册表外的接缝。装不上时面板会显示原因，而不是假装在工作。

• 停用只是把该行的 `enabled` 置 false，不删你的配置
• 连接与重连（添加/编辑 MCP 时的最后一组输入，全局与项目级都支持）：直接对应 @deepseek-ai/dsh-mcp-client 自己的配置字段

表单里填的 · 落到 config 的 · 默认值 · 作用 连不上时拒绝激活 · failOnStartupError · false · 勾上后：首次连接或工具同步失败会让插件激活失败（不勾则照常启动，只是没有该服务器的工具） 工具调用超时（ms） · toolCallTimeoutMs · 60000 · 单次 tools/call 的超时。导入/分析这类分钟级操作会被默认 60 秒打断（本机实测一次 Ghidra 导入+全量分析约 158 秒），按需调大 重连首次延迟（ms） · reconnect.initialDelayMs · 500 · 第一次重连等待多久，之后逐次翻倍 重连最大延迟（ms） · reconnect.maxDelayMs · 30000 · 退避延迟的上限 重连最大次数 · reconnect.maxAttempts · 10 · 单次断线最多连续尝试几次，超出则放弃 输入框预填真实默认值，落库也写成显式值（500 / 30000 / 10）：表单显示的就是实际生效的， 不用去翻 dsh-mcp-client 的源码才知道这一行怎么重连。清空输入框会回到默认值，而不是删掉键。 failOnStartupError 例外——false 与「键不存在」完全等价，写它只是噪音，所以只在勾选时写入。 填了非法值（非整数、超范围）会被拒绝并提示——因为写进去会让整行加载失败

• 导入 MCP：选来源 → 扫描 → 预览「哪些文件存在、识别出几个、几个形态不支持」→ 确认。全局与项目级都写成配置文件行（项目行带 scope）

技能

• 列表 = 磁盘扫描结果：$DSH_HOME/skills、~/.agents/skills、以及各项目的 .agents/skills / .dsh/skills。磁盘文件是唯一真源，config.skills[] / 对账镜像已删除（旧条目会在升级时一次性写成文件）
• 「添加技能」写入 //SKILL.md：区域选全局或项目，名字同时是目录名
• 预览/编辑按需通过 GET //skill?path= 读取正文（只允许读扫描到的文件；正文不进 profile patch）
• 重命名会同时移动目录并改写 frontmatter 里的 `name`（否则面板和文件夹会对不上）
• 删除是两步确认：先把目录备份到同级的 .smp-backup--，再删除；备份会保留，需要时手动改回原名即可

状态与失败

在途操作在卡片上显示进度（保存中… / 删除中… / 切换中…），期间该卡片的其它按钮不可点；操作失败会就地显示原因（例如「该技能不在当前扫描结果里」）。删除若 15 秒没有回执，会停止转圈并提示重试。

工作原理

插件分两半，装在同一个包里：

src/**        Host 半（tsc → dist/index.js）       跑在 harness 进程
lib/src/**    Client 半（esbuild → lib/client.js） 跑在浏览器，单文件、CSS 内联
cordis.patch.yml                                   声明插件行（本包自己的 bundle patch）

写通道：所有修改都是 HTTP 请求/响应，没有 settings 队列，也没有持久化的命令字段。

路由 · 作用 POST /dsh-skills-mcp-manager/rows · MCP 行增删改；Host 加锁、校验、原子写 cordis.patch.yml，并在响应里带回写后的行列表 POST /dsh-skills-mcp-manager/skills · 技能增删改；直接写/删 //SKILL.md GET /dsh-skills-mcp-manager/skill?path= · 读取一个已被扫描到的 SKILL.md 正文（路径必须来自扫描结果） POST /dsh-skills-mcp-manager/reconnect · 重连一台服务器；请求返回时命令已经跑完 POST /dsh-skills-mcp-manager/import · 扫描其它工具的 MCP 配置，直接返回预览

写路由先过 connection.requestRejection() 鉴权，只接受 POST + application/json，请求串行执行。为什么不用 settings：写一个文件只要 1ms，而队列通道要连等四个轮询（600ms 取请求 + 面板回读 + 2s 对账 + 5s 投影），实测最坏约 9 秒。旧 Host / 旧面板不再兼容，请一起升级。

数据通道：GET /dsh-skills-mcp-manager/runtime 一次返回整个读模型：MCP 行列表（Host 直接读 patch 文件，Loader 只补 phase）、工具清单（现读工具注册表）、连接/授权状态（探测缓存 + 重连预算）、磁盘技能扫描、工作区与过滤状态。响应禁用缓存；面板在页签打开/展开卡片/页面恢复可见时读取，可见期间每 5 秒刷新，写入成功后立刻重拉一次。读取失败会显示原因并保留上一次的行列表，只把观测状态标成「状态未知」。

命名与升级：插件行 id、settings 命名空间和运行时接口前缀统一为 dsh-skills-mcp-manager。升级前请读 `docs/MIGRATION-0.5.6.md` —— 0.5.6 删掉了 settings 里的技能、命令与读模型字段：config.skills[] 迁移成 SKILL.md，config.servers[] 迁移成带 scope 的 Loader 行，其余键删除。迁移全部自动完成，但需要重启一次 DSH。

配置持久化：插件的 settings 里只剩 `toolFilters`（用户偏好，改过滤规则时才写）。技能、MCP 行、工具清单、连接/授权状态、命令都不再进 settings；启动时用配置文件锁、备份和原子写一次性清掉旧字段，之后扫描时间变化也不会再改写 cordis.patch.yml。

技能：面板写的、导入的、手工放进根目录的，全部只以磁盘文件为准；Host 每 5 秒扫描一次四个根供 /runtime 使用，不做任何镜像或回收。升级时 config.skills[] 的旧条目会写成 SKILL.md（已存在的文件优先，不覆盖）。

项目级 MCP：不猜项目根——用「配置里的 scope 是否为会话 cwd 的目录前缀」判定，命中的 agent 才挂载，agent/disposed 时卸载。注意 subagent 是独立 agent，只继承 root 作用域，所以项目级工具对 subagent 不可见（全局工具两处都可见）。