DeepSeek Harness 插件

wingsky-1/dsh-plugin-hub#packages/dsh-mcp-manager

Star 数 ★ 32 下载量(近 30 天) 2,566 分类 工具与能力 收录于 2026-08-18 npm @wingsky-1/dsh-mcp-manager

MCP 服务器管理器(stdio / streamable-http):按工作目录分项目级/全局两级配置;项目级 MCP 默认经中间层收敛为 4 个原子工具(`middleware: all` 连同全局服务器一并收敛,设置页热切换);工作空间隔离防串台;配置只存 `${ENV}` 引用、不落盘明文密钥;提供运行时注册接口供其他插件注入 MCP。

安装

# npm 包(预构建)

dsh plugin --profile web add @wingsky-1/dsh-mcp-manager

# GitHub 源码(首次需按提示配置 allowBuilds 构建授权后重试)

dsh plugin --profile web add github:wingsky-1/dsh-plugin-hub#path:/packages/dsh-mcp-manager

装任何插件都等于在你的机器上跑第三方代码,权限和你本人一样大——能读你的文件、用你的凭据、访问网络,工具审批管不到它。GitHub 来源的插件还会在安装时执行构建脚本——pnpm 默认拦截,所以安装可能停在 ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED 或 ERR_PNPM_IGNORED_BUILDS;dsh 会打印出需要添加的确切键名,把它加进该 profile 的 pnpm-workspace.yaml 的 allowBuilds 下,重跑一次即可装上。放行构建本身就是一次信任判断:请只安装可信来源,并尽量锁定 commit(github:owner/repo#sha)。

README

DSH(DeepSeek Harness)的 MCP 服务器管理插件:会话界面右上角浮窗 + 分级面板 + 快速接入(手工表单 + 粘贴 mcpServers JSON 导入,不预设任何服务器)。 连接与协议交官方 @deepseek-ai/dsh-mcp-client(宿主 cordis loader 按包名装载到 dsh 安装内的副本),本插件只留配置面与模型可见面;官方客户端不随包分发,也无需额外安装。

模型可见面只有四个原子工具(ws_mcp_list / ws_mcp_detail / ws_mcp_search / ws_mcp_call):项目级、全局级与运行时注入的封装定义条目一律经中间层访问,两级发现 (ws_mcp_list 完整盘点 → ws_mcp_detail 按需拉完整 schema);cwd 无项目时回落全局虚拟 root @global。宿主仍按 mcp__<id>__<tool> 注册工具(id 是本次装配按 (工作空间, 服务器名) 分配的不透明短串,不能由服务器名推导),但这些名字会被从模型的 工具列表中摘除,禁止直呼。 两级配置文件中的服务器列表(增删/启停/改配置)支持热加载、即时生效,无需重启。 (middleware / middlewarePolicy 两个配置键已在 #767 笔 2 废除——旧配置里写了不生效、 也不会被本插件改写。)

项目根怎么定(#1137):项目级 MCP 跟随调用 agent 在调用开始时的有效活动 workingDirectory——每次工具调用开始时取一次目录快照,并在本次调用内固定该 root; 切目录后的新调用才采用新 root,已在飞的调用仍在旧 root 完成(或按既有取消协议取消)。 会话创建目录 header.cwd 只是初始项目身份,不再作为活动目录猜测值。没有有效活动 目录时项目级操作 fail-closed(报「无法确定工作空间」),不回退 header.cwd / process.cwd / UI 最近 session / 另一个已连接工作区;显式 @global 仍可达(全局 来源存在服务器时),且不把未知项目名偷换成同名全局服务器。

升级后历史会话打不开? 当前版本只生成 producer-owned V4 source;旧 source 仅通过一次性维护脚本处理,详见升级与历史会话边界。

一键安装

dsh plugin --profile web add @wingsky-1/dsh-mcp-manager

安装 / 卸载 / 更新后都需重启一次 dsh web(bundle 层只在启动时组合)生效。

核心优势

  • 上下文成本可控:全部 MCP 经中间层收敛,模型面只占 ws_mcp_list / ws_mcp_detail / ws_mcp_search / ws_mcp_call 四个原子工具位——接多少台 服务器、多少个工具都不膨胀系统提示词(两级发现:ws_mcp_list 完整盘点 → ws_mcp_detail 按需拉完整 schema)
  • 分工作目录维护:项目级配置 <项目根>/.dsh/@wingsky-1/dsh-mcp-manager/mcp.json 随仓库走、可提交 git 团队共享; 全局配置 <DSH_HOME>/@wingsky-1/dsh-mcp-manager/mcp.json 常连;切换会话自动加载当前目录的 MCP 集
  • 工作空间隔离:中间层按调用方会话活动目录快照路由到对应连接池(每次调用开始取 一次快照并在本次调用内固定),server 全名一致性校验防跨空间串台;不同目录注入同名 server 也互不冲突
  • 安全的默认值:配置只存 ${ENV} 引用、不落盘密钥本身(0600 权限 + 原子写入); stdio 子进程环境净化,宿主凭据形状变量不透传;目录摘要与错误路径经 redactor 脱敏
  • 运维省心:运行中/连接中/失败等分级状态一目了然;断线有界指数退避自动重连; 调用超时可按 server 覆盖(toolCallTimeoutMs),中间层调用按在用服务器的最大值 + 25s 内部尾结算(默认 15s + 25s = 40s)

安装

前提:已安装 DeepSeek Harness 且 dsh web 可正常启动(未全局安装 dsh 见下方「未全局安装 dsh」)。

安装插件(add)

dsh plugin --profile web add @wingsky-1/dsh-mcp-manager

卸载插件(remove)

dsh plugin --profile web remove @wingsky-1/dsh-mcp-manager

更新插件(update)

dsh plugin --profile web update @wingsky-1/dsh-mcp-manager

安装 / 卸载 / 更新后都需重启一次 dsh web(bundle 层只在启动时组合)生效。

指定版本号(@version)

省略 @版本号 即安装默认 latest(推荐)。仅当 registry 尚未同步到最新、或最新版在你的环境有问题时,在包名后追加 @版本号:

dsh plugin --profile web add @wingsky-1/dsh-mcp-manager@<版本号>

未全局安装 dsh

若本机没有全局 dsh 命令,用 npx 临时拉起(底层调用 pnpm,仍需本机装好 pnpm 与 Node.js):

npx @deepseek-ai/dsh plugin --profile web add @wingsky-1/dsh-mcp-manager
npx @deepseek-ai/dsh plugin --profile web remove @wingsky-1/dsh-mcp-manager
npx @deepseek-ai/dsh plugin --profile web update @wingsky-1/dsh-mcp-manager

能力

能力 说明
右上角浮窗 状态点 + 计数摘要(MCP 2/3),点击展开下拉面板;随会话切换自动刷新
项目级 MCP 服务器分「项目级 / 全局」两级:项目级存 <项目根>/.dsh/@wingsky-1/dsh-mcp-manager/mcp.json(随项目走、可提交 git),全局存 <DSH_HOME>/@wingsky-1/dsh-mcp-manager/mcp.json 常连
分级展示 运行中 / 连接中 / 重连中 / 未连接 / 已停用 / 失败;每台显示传输、端点、工具数;客户端未知状态按「未连接」投影、不丢卡(C13 统一口径)
服务器管理 增删改查(可选项目级/全局)、连接 / 断开 / 重连;配置版本化 JSON,原子写入
连接请求 界面连接、重连和停止请求异步受理:连接期间显示「连接中」,失败后显示「失败」及错误;刷新页面或切换会话时重新读取宿主内存中的状态。宿主直接调用 connect 仍等待连接完成。停止是逻辑停止,不保证底层连接或进程已完全释放;这些运行状态不跨宿主进程重启保留。HTTP 202 Accepted 表示请求已受理而非操作已完成;兼容调用方应接受所有 2xx 成功响应,并通过状态确认结果。
两种传输 stdio(本地子进程,env 支持 ${ENV} 引用)与 streamable-http(远程,header 支持 ${ENV} 引用,自动回传 Mcp-Session-Id)
JSON 导入 粘贴 mcpServers JSON 文本导入(仅 JSON 格式;不扫描任何应用配置文件)
模型工具 全部服务器(项目级 / 全局 / runtime 注入)一律经中间层四个原子工具访问:ws_mcp_list / ws_mcp_detail / ws_mcp_search / ws_mcp_call,不同工作空间互不冲突;宿主注册名 mcp__<id>__<tool>(id 按 (工作空间, 服务器名) 随机分配、同一次装配内稳定、不透明;工具名仍受 64 字符 / [A-Za-z0-9_-] / 冲突哈希后缀约束)会被从模型工具列表摘除——模型不可见、不得直呼
工作空间隔离 中间层按调用方会话调用开始时的活动目录快照路由到对应工作空间的连接池(在飞调用固定旧 root,新调用取新 root);server 全名 @<root>/<server> 一致性校验防跨空间串台
断线重连 有界指数退避(500ms 起、30s 上限、10 次后停止后台重试;用户手动连接或 ws_mcp_call 触发可再试)
结果体积 本包不做结果截断,工具结果原样返回。目录装箱限额(每工具 4KB / 总 256KB)约束的是目录、不是执行结果;需要限长请在 MCP 服务器侧或宿主 compaction 策略里做
超时下探 工具调用超时默认 60s → 15s(可按服务器 toolCallTimeoutMs 覆盖);中间层 ws_mcp_call 按在用服务器最大值 + 25s 内部尾结算,不是固定值
状态推送自愈 SSE 通道共享 sse-hub(#515):服务端每 30s data ping 心跳 + stalled 超窗回收 + maxAge 轮换(120min 无业务帧主动断开);客户端 60s 无帧即关旧建新(watchdog)、页面回前台重建 SSE 并 POST resume 做非强制可用性恢复(携带本次会话 cwd,服务端固定本次 root;旧无 body 请求回落既有绑定);SSE 连续失败降级 10s 轮询,期间每 5 个轮询周期自动探测恢复推送(C2,页面失联自愈)——移动端切后台被静默掐断的半开连接由客户端自愈 + 服务端确定性回收,不堆积僵尸连接。自动恢复复用官方管理机制的已存在状态投影与在途去重,不强制重建健康/connecting/reconnecting 连接;不声称检测真实健康(有工具注册的健康连接与半开连接无法实时区分),半开仍由用户显式重连恢复

配置(浮窗位置)

配置页入口:Plugin Manager → dsh-mcp-manager → Configure。浮窗按钮(MCP 胶囊)的位置与偏移(position / offset)在此保存,canonical row id 为 dsh-mcp-manager,settings namespace 为 dsh-mcp-manager,保存后即时生效。

非回环地址的持久化设置展示仍服从 DSH 官方页面与 settings 安全策略;Configure 按钮是否出现不改变 API 的官方身份校验。不要在可信性不明时自行绕过该策略;旧 dsh-lan-proxy 的远程兼容入口已退役。

键 值域 默认
position top-right(右上,默认)/ top-left(左上)/ bottom-right(右下)/ bottom-left(左下) top-right
offset.x 非负整数(水平偏移,单位 px) 8
offset.y 非负整数(垂直偏移,单位 px) 8
offset.blankY 非负整数(空白会话垂直偏移,单位 px) 40
zIndexBase 整数,clamp 到 1–9000(浮窗层级基准;胶囊与点击后弹出的主面板同取该配置值,模态管理面板不受影响) 10
Settings namespace

DSH 官方 importer 会按同名 section 直接导入 dsh-mcp-manager;本插件不再运行第二套 namespace migration。settings.yaml.imported 仅为已消费文档的审计副本,不应整体复制。

当 position = bottom-right 或 bottom-left 时,下拉面板会在胶囊上方展开(底部 锚点向上弹出),不溢出视口、内容完整可见可点击;顶部锚点向下展开(历史行为,默认不变)。

移动端 / 平板端适配(issue #128):断点判定基准是会话容器(conversationHost) 的视口宽度而非窗口媒体查询——窄屏(≤480px,手机竖屏 / 极窄分栏)下面板近全屏宽、 服务器卡片重排、操作按钮触控目标加大到 ≈44px;平板档(≤834px)过渡;桌面维持现状。 浮窗最终坐标经 JS 视口 clamp(safe-area 语义:宿主无 viewport-fit=cover, env(safe-area-inset-*) 恒 0 时自然退化为普通 clamp);软键盘弹出经 visualViewport resize 跟随,横竖屏切换后下一帧重算。

跨包避让契约(源自 issue #116,不可回退):本插件浮窗默认 top-right 且距顶 8px、高约 26px;dsh-provider-usage 用量胶囊依赖这一默认位置以 offsetY: 48 在其正下方让位(两胶囊默认互不重叠)。修改本插件默认锚点 / 垂直偏移会使该避让 失效,属跨包行为契约,回退前须同步调整 provider-usage 默认值。

在设置页保存后即时生效,无需重启 dsh web、也无需手动刷新页面:宿主端经既有 SSE events 通道推送一变,客户端自动重新拉取 /api/dsh-mcp/config 并就地更新浮窗位置。

配置(中间层)

全部 MCP 经中间层访问(单池,没有模式开关):任何服务器都不产生模型可见的 mcp__ 直呼工具,统一经四个原子工具访问(两级发现,业界标准形态)—— ws_mcp_list(完整盘点当前工作空间全部服务器 + 每台完整工具清单,不受 ws_mcp_search 的 limit 截断;支持 server 全名/裸名过滤,perServerLimit 每服务器工具条数上限默认 50 / 上限 500,超限置 toolsTruncated;空返回附明确 message,带 server 过滤 0 命中时 message 归因到过滤条件并列出可见项目级 服务器)/ ws_mcp_detail(按 @<root>/<server> + tool 裸名精确查询单工具 完整 inputSchema,错误三分:发现失败附原因 / 服务器未连接或未发现 / 工具 不存在)/ ws_mcp_search(关键词检索,先搜后调,输出 truncated 标志提示结果是否因 limit 截断)/ ws_mcp_call(按 @<root>/<server> 全名调用,参数 schema 用 ws_mcp_detail 核对),执行时按调用方会话当前 cwd 路由到对应工作空间 连接池,不同工作空间注入不同 MCP、无命名冲突;cwd 无项目时回落全局虚拟 root @global,list/search/detail 恒合并查询「项目 root 单元 + @global 单元」, call 放行 @global root(全局配置跨工作空间共享,语义成立)。宿主注册名形如 mcp__<id>__<tool>,id 不透明、以工具清单为准;它只作内部标识(模型工具列表里看不到), 封装定义条目(toolDefinitions)只经 ws_mcp_call 按 @<root>/<server> 触达。 注:全局服务器增删改后需重启或触发会话触达才刷新目录(既有行为)。

活动目录快照与 root 解析(#1137):

  • 快照点:ws_mcp_list / ws_mcp_detail / ws_mcp_search / ws_mcp_call 四个入口 与 mcp__ 直呼守卫都在各自调用的首行取一次 root 快照;同一次调用内的目录变更不改投, 切目录后的新调用采用新 root。
  • 发现规则:从活动目录向上找最近的 .git(目录或 worktree 的 .git 文件)/ .dsh / .mcp.json 标记,最近命中层为根;找不到标记则活动目录自身为根。搜索上限沿用既有 16 层,DSH 全局家目录的 .dsh 不算项目标记。
  • 路径归一:同一项目经符号链接进入时按真实路径归并为同一根,连接池不因路径拼写分裂。
  • fail-closed:活动目录缺失 / 空白 / 相对 / 不可访问 / 已删除 / 读取抛错 / 归属未知时, 四个工具一律报「无法确定工作空间」的项目级错误(不含任何项目配置读取、建连或远端执行), 不回退 header.cwd、process.cwd、UI 最近 session 或另一个已连接工作区。
  • @global 规则:无有效活动目录时,仅当全局配置或 runtime 注入里确实存在已启用的 全局来源服务器,才回落虚拟 root @global;没有全局来源时维持拒绝。显式 @@global/<name> 与 @global/<name> 等价可达,不把未知项目名偷换成同名全局服务器。
  • 并发与连接所有权:连接、目录缓存、禁用状态、schema 与运行时注入都按 root + server 身份隔离;两个会话共享同根同服务器时不强行新建物理连接;一个会话切走 或卸载不会关闭另一个仍持有该 root 的调用;迟到的旧 root 结果不覆盖新 root 状态、不写进 新 root 的目录缓存。

顶层配置键(Config schema)

顶层键(packages/dsh-mcp-manager/src/server/config/config-schema.ts 的 Config)默认值与语义:

键 默认值 语义
enabled true 是否启用本插件(插件级总开关)。
announceToAgent true 是否向 Agent 宣告插件(能力清单由 <available_mcp_servers> 承担)。
storePath 留空(默认 <DSH_HOME>/@wingsky-1/dsh-mcp-manager/mcp.json) 全局服务器配置路径,留空用默认路径。
announceCatalog true 是否注入 MCP 能力目录(<available_mcp_servers>)。
catalogMaxEntries 6 目录注入条目上限。
debug.callStats false 是否开启调用统计调试与落盘(默认关闭,仅可通过配置文件开启;详见下节“调用统计与 Debug 模式”)。
debug.statsFile 留空(默认 <DSH_HOME>/@wingsky-1/dsh-mcp-manager/stats.json) 统计落盘路径,留空使用默认路径。
ui 见“配置(浮窗位置)”节(position 默认 top-right;offset.x / offset.y 默认 8,blankY 默认 40;zIndexBase 默认 10,clamp 到 1–9000) 浮窗位置与层级配置,详见“配置(浮窗位置)”节。

已废除的配置键(#767 笔 2):middleware(off / project / all 三档模式)与 middlewarePolicy(allowTools / denyTools 策略)。设置页的模式下拉已删除;旧配置里写了 这两个键不报错也不生效(键被原样带过、没有任何消费者),本插件也不会改写用户的配置文件。 工具级禁用是唯一的准入裁决。

已退役的实现:S1-5c 自研连接栈退役(runtime/supervisor.ts、runtime/reconnect.ts 等四文件整体退役,连接改走官方引擎);W11b2a src/types 与 src/integration 删除(无迁移动作)。

工具级禁用(浮窗)

  • 服务器卡片的「工具(N)」折叠区展开后为 checkbox 列表,逐个启停,点击即 经 PATCH /api/dsh-mcp/tool-disable 持久化(落盘 <DSH_HOME>/@wingsky-1/dsh-mcp-manager/user-state.json 的 disabledTools,合并写盘、重启保留);
  • 语义:项目级与全局级服务器的工具都可禁用(单池后两类都经中间层;全局记录以 @global 为 key 跨工作空间共享);默认全部启用;
  • 工具级禁用独立于服务器级 enabled 开关(服务器级复活不清工具级状态);
  • 作用于 mcp-manager 管辖的全部 MCP 工具(mcp__ 前缀直呼与中间层 ws_mcp_* 一致生效,runtime 封装工具同样受控);插件侧自行声明的纪律裸名工具 不受影响;
  • 超长工具名(>64 字符哈希后缀)不可逆 → 按未知 server 处理,不禁用/不误禁;
  • 浮窗与管理面板的「项目级」「全局级」分组都渲染工具开关(单池后两类都经中间层, 全局组的开关同样生效);
  • 浮窗与管理面板均按「项目级 / 全局级」两大分组展示(各自内部再按连接状态);
  • 全名形态 @@global/<name> 或 @<绝对路径>/<name>(与宿主 parseFullServerName 归一化一致);宿主重启后 projectRoot 暂缺时客户端防御性跳过提交(不发送非法 @/name,C6);浮窗与管理面板的连接 / 断开 / 重连 / 启停操作携带当前会话 cwd, 宿主重启场景可自愈恢复会话(C7)。

路由(loopback 快路径 + 官方身份准入)

路由 说明
/api/dsh-mcp/health 健康检查(注意与目录名不同)
/api/dsh-mcp/tool-disable 工具级禁用开关(PATCH;loopback 直接访问或官方身份准入通过)
/api/dsh-mcp/* 服务器管理 / 连接控制 / 工具清单 / SSE 事件等

运行时注入(registerServer.toolDefinitions)

其他插件可经 ctx.mcpManager.registerServer 运行时注册 MCP 服务器(内存态不落盘, 同名幂等)。注册入参支持可选 toolDefinitions(调用方封装工具定义,ToolDefinition[], 工具名用裸名):

  • 有 toolDefinitions:该服务器工具全部用封装定义注册——execute 来自调用方 (调用方可先做预处理再内部转发底层命令),跳过远端 schema 投影与 通用 callTool,底层真实实现不外泄;
  • 没有:维持现状(远端 schema + 通用 callTool),其他服务器零影响;
  • 模型不可见 mcp__ 直呼工具:只经 ws_mcp_call 用裸名调用(@<root>/<server>
    • 裸名;封装的 execute 是调用方 JS,没有远端实现可直呼)。调用名派生仍走 publicToolName(64 字符 / 哈希后缀规则不变),但它只作为中间层 callTool 的转发名;
  • 工具级禁用 / 可见性 / 能力目录对封装工具照常生效(按服务器 + 工具名判定,与 mcp__ 前缀工具同口径);
  • 仅运行时注入面(runtimeRegistry)消费,不随 store 落盘、不随 mcpServers 导入透传。
await ctx.mcpManager.registerServer({
  name: "my-mcp",
  transport: "stdio",
  command: "my-mcp-server",
  args: ["serve", "--mcp"],
  toolDefinitions: [
    {
      name: "my_tool",                    // 裸名
      description: "调用方自定义的封装工具",
      parameters: { type: "object", properties: { query: { type: "string" } }, required: ["query"] },
      output: { schema: { ... }, render(args, value) { ... } },
      execute: async (args) => { await prepare(); return forwarded; }, // 内部转发,不外泄
    },
  ],
});

数据与安全

  • 服务器配置:<DSH_HOME>/@wingsky-1/dsh-mcp-manager/mcp.json(仅存 ${ENV} 引用,不落盘密钥本身); 落盘 0600 权限 + 同目录临时文件原子替换;Windows 上替换遇到 EPERM / EBUSY 时会有界异步重试,重试期间检测到外部修改则中止以保留外部内容
  • 所有 /api/dsh-mcp/* 路由保留 loopback 快路径;非回环短请求必须通过官方 requestRejection 的 Host/Origin、跨站、cookie/API peer 校验,异常、401/403 或未知结果 fail-closed,通过后才判方法错 405。非回环 SSE 还须经 connection.admit 保留 admitted PeerScope;Peer 释放时停止广播、从连接表移除并关闭响应
  • stdio 子进程环境净化(官方 dsh-mcp-client 口径):净化只作用于继承的父环境—— 凭据词根(KEY / PASSWORD / SECRET / TOKEN)与全部 DSH_* 变量从父环境摘掉, 避免把宿主机密隐式透传给 MCP 子进程;用户在配置里显式声明的 env 原样传给子进程 (显式层在净化之后合并)——env 不是脱敏面,要隔离就别往里写凭据
  • stdio 子进程继承宿主权限:MCP 服务器命令在宿主进程权限下执行, 仅配置可信的服务器。信任边界:同进程插件注入(ctx.mcpManager.registerServer) 与宿主同权限、不构成提权;随仓库提交的项目级 mcp.json 才是需要你审慎对待的那一面
  • 统计只落元数据:debug 统计(debug.callStats)记录调用次数/时长/成败与渐进式披露 漏斗;搜索词只以 SHA-256 哈希桶落盘(h:<12 位 hex>,空查询为 <empty>),旧版本 落的明文键在读回时丢弃(丢弃发生在读回那一刻,下次落盘即不再写回;若统计此后无活动, 旧明文键会留到下一次有活动为止)。哈希是假名化不是匿名:搜索词熵低,仍有字典攻击面。 漏斗的另两维仍落明文:ws_mcp_list 的 server 过滤项、ws_mcp_detail 的 server/tool—— 它们是服务器与工具名,本就在配置面与目录面里,不是自由文本
  • MCP 工具在真实服务器上执行,先确认再操作;工具结果原样返回, 可能含敏感信息;工具描述/结果按不可信输入对待
  • 注入信任分级:远端工具描述/结果为不可信输入,仅展示与传参,不作指令执行;本地配置与用户显式操作为可信
  • 工作空间隔离(中间层):路由以调用方会话调用开始时的活动目录快照为唯一输入; server 全名一致性校验(参数声明的 root ≠ 路由 root 且 ≠ @global → 拒绝)防跨空间串台; 工具级禁用表按 @<root>/<server> 全名或裸名裁决(全名优先;@global 记录跨工作空间共享)
  • 活动目录归属与 fail-closed(#1137):目录读数只经宿主 sessionProjections 的 stateOf(session, "workingDirectory") 原始可空投影按 session 归属取——刻意不读官方 get()(其 ?? defaultDirectory 兜底 process.cwd(),会把「投影未记录」静默变成进程 cwd)。服务缺席 / 投影未记录 / 空白 / 相对 / 非字符串 / 读取抛错一律判「无有效活动目录」, 项目级操作拒绝,不回退任何目录猜测值;header.cwd 只是创建目录,不作为活动目录。
  • 并发调用所有权(#1137):每次调用在开始时固定 root 快照,已在飞的调用不在 await 之后改投另一个 root;连接 / 目录缓存 / 禁用状态 / schema / 运行时注入 / 销毁都按 root + server 归属隔离。跨会话执行路由的隔离不依赖模型遵守提示词,由路由结构本身保证。
  • 中间层工具只读边界:ws_mcp_list / ws_mcp_detail / ws_mcp_search 不执行远端 工具,但首次触达某工作空间时会创建连接单元并触发后台建连(不等同于纯本地读);ws_mcp_call 是唯一执行远端工具的入口,并受工具级禁用表约束;ws_mcp_call 错误消息按 「显式 + 下一步」规范给出(确认 server 连接 / 用 ws_mcp_detail 核对参数 / 检查工具级禁用状态)
  • MCP 图片附件硬上限:每个官方 MCP client 在独立 attachments scope 中挂载一个自持 saveImages facade。SDK 完成图片解码后、写入根附件库前,facade 统一执行每批最多 10 张、 每张最多 8 MiB 的硬校验;越界批次不会落库,模型面只收到 unavailable 诊断,raw MCP result 仍交给程序调用方。facade 每次动态读取未隔离父 Context 的当前 store,缺失、晚到或 替换均 fail-closed,不缓存旧引用;正常图片只复用官方 projection 的一次持久化,不做第二次 saveImages。client wrapper 释放时只撤销自己的 facade 与官方 child,根 store 和其他 client 不受影响。该校验发生在 SDK 解码之后,不宣称限制解码前内存。
  • 禁直呼是机器强制的(#1014):mcp__<id>__<tool> 是内部注册名,pre-execute guard 默认拒绝一切非我方转发的 mcp__ 直呼——不再依赖模型遵守提示词,也不依赖声明面遮蔽 (连接翻转期遮蔽必有泄漏窗口)。唯一放行位是宿主赋予的飞行中 token:本包 ws_mcp_call 内经宿主 loader 取得公开 ToolExecutionPipeline,以精确注册名、 agent / toolSet / rootCallId / signal 与外层 parent token 执行受控子调用; source 仅在目标 root/server/tool 策略、外层准入与 parent 活性同时成立时解析该依赖。 结算即摘除,同一 token 重放或依赖定义被移除/替换后都会拒绝。拒绝文案指路 ws_mcp_call 并写明不要重试本次调用。
  • 工具级禁用(三入口一致):ws_mcp_call(callTool 查禁用表)、 pre-execute guard(mcp__ 前缀直呼工具)、插件侧声明的纪律裸名工具 统一走 isToolDenied 裁决;禁用只作用于 mcp__ 前缀工具,拒绝原因附语义声明; 禁用记录 <DSH_HOME>/@wingsky-1/dsh-mcp-manager/user-state.json 的 disabledTools(@global key 跨工作空间共享,合并写盘不整表覆盖)
  • 凭据脱敏:目录摘要与错误路径经 redactor 把 env/headers/URL 用户信息 (username/password/searchParams)等凭据形状替换为 [REDACTED];URL 主机与 路径无凭据部分保留可读(可诊断性,B8 口径);percent-encoding 的 raw 形态与 decoded 形态双注册,防编码绕过;supervisor/manager 错误日志与 HTTP body 同口径 脱敏
  • 调用统计与 Debug 模式(Metadata-Only):默认关闭;启用后把 MCP 调用指标与渐进式披露漏斗防抖原子持久化至 <DSH_HOME>/@wingsky-1/dsh-mcp-manager/stats.json,且控制台输出单行跟踪;严格不持久化用户 arguments 与返回 content
  • 能力目录注入含来源标注与“不代表当前连接状态”说明
  • 能力目录 source:dsh-mcp-manager 是 canonical row/settings 条目 id;目录消息的当前业务格式是 producer-owned V4:{ kind: "plugin:@wingsky-1/dsh-mcp-manager", form: "snapshot", sections: [{ name: "mcp-catalog", text }] }

升级与历史会话边界

当前写入与业务读取只认 producer-owned V4;本包不提供旧 V0/V2/V3 parser,也不把旧格式写成业务兼容。

旧 mcp-catalog source 属于一次性维护责任。scripts/maintenance/repair-mcp-catalog-sessions.mjs 只把旧 source 元数据修为 V3 wrapper,保留消息正文与事件序列;它不写 V4,也不实现或伪造 v3→v4 迁移。修复后由目标 dsh(版本见 catalog)的官方迁移链依次恢复旧产物并转为 V4,当前 V4 产物不动。

# 先停止 dsh web;默认预演,只列出受影响会话
node scripts/maintenance/repair-mcp-catalog-sessions.mjs

# 核对后落盘;自动备份,随后重启 dsh web
node scripts/maintenance/repair-mcp-catalog-sessions.mjs --apply

默认处理 v0/v1/v2 与 v3 中残留的旧 source;--legacy-only 只处理 v0/v1/v2。脚本幂等,可用 --home 或 DSH_HOME 指定目录、用 --session <id> 限定单个会话。

验证

测试单份维护、变异自动覆盖:单元测试只维护 test/*.test.ts(import "../lib/index.js" 测产物);stryker 经 lib→src hook 复用同一份断言,无需手工同步副本。

# 健康检查(回环)
curl -s http://127.0.0.1:3080/api/dsh-mcp/health

# 源码在 src/,改后必须 build
pnpm --filter @wingsky-1/dsh-mcp-manager build
pnpm --filter @wingsky-1/dsh-mcp-manager test

已知限制

  • mcp__ 注册名只作内部标识:服务器由官方 dsh-mcp-client 装载,宿主注册名为 mcp__<id>__<tool>,id 是按 (工作空间, 服务器名) 分配的 随机短串(同一次插件装配内 稳定;插件重载或宿主重启后变化;不透明,不能由服务器名推导)。这些名字会被从模型工具列表 摘除,模型经 ws_mcp_call 转发触达——不要在任何脚本或提示词里写死工具名, 一律用 ws_mcp_list / ws_mcp_detail 取名字
  • 不订阅 MCP 的 tools/list_changed 通知(无 SSE 长连接);工具列表变化在 重连 / 手动刷新时重新同步
  • 中间层目录是「采集边界内的 last-good 快照」(单服务器 ≤512 工具 / ≤256KB 总量), 发现失败时 list 透出 unavailable 原因
  • 仅桥接工具能力;MCP 的 resources 与 prompts 尚无 harness 消费接口
  • 多标签页各自绑定不同会话时,项目级 MCP 只能跟随一个会话(issue #1028 未解决项): 宿主 projectRoot 是单例,多个页签会互相覆盖,且每次切回前台的 rebindSession 会 放大覆盖。本包不自行仲裁「哪个页签优先」。
  • 读不到当前会话时保持既有绑定、不做清空(#1028):官方会话快照就绪前、或该页签 暂未被官方 mainView 持有时,本包判定为「未知」并不向宿主发送 cwd:""——未知 不等于无项目,误清会造成面板只剩全局条目、项目级导入报 no active project session。告警口径:首帧未知是官方快照尚未就绪的竞态 (每次冷启动必现),不告警;只有「已解析过又读不到」或「连续多帧仍读不到」才打 一次告警,以免正常态与异常态显示同一条黄警而丢掉判别价值。
  • 切回前台的自动恢复是非强制的(#1120),不是用户显式强制重连:复用官方管理机制的 已存在状态投影与 per-root/server 在途去重,不以每次 visibilitychange 为由 dispose/restart;connected/connecting/reconnecting 保留现有代际与官方退避, entry 缺失与真正失败走正常路径恢复,userDisabled 绝不复活。官方挂载层只提供 ready/disposed/工具注册面,有工具注册的健康连接与半开连接无法实时区分——自动恢复 不声称已检测真实健康、不发自研 ping;半开仍可由用户显式重连恢复。resume 携带本次会话 cwd,服务端在本次调用中解析并固定 root(旧无 body 请求回落既有绑定,新请求明确无工作区 即 cwd:"" 固定 @global,不回落到别人的 projectRoot);客户端恢复节流按 cwd 分键覆盖 resume,不同 cwd 的恢复不互吞。
  • 依赖 Node ≥ 20

类型依赖

宿主端与客户端类型均来自官方 @deepseek-ai/* 包(cordis / dsh-host-webserver / dsh-agent / dsh-tools / dsh-system-prompt / dsh-llm / dsh-client-ui-slots / dsh-api-session-controller / dsh-client-ui-session,版本统一锁在仓库 pnpm-workspace.yaml catalog,随 DSH 发布节奏升级):仅 import type 编译期使用, 编译产物零官方运行时导入。包以 optional peerDependencies 声明这一宿主耦合;对插件做 类型检查的消费者需可解析这些官方包(跳过类型检查则无影响)。

客户端的「当前会话」读数经 src/client/core/current-session.ts 单一接缝,判据用官方 口径 retainedBy.mainView > 0 并以官方 SessionListState / SessionSummary 类型锚定 (不自建镜像类型):DSH 0.1.7-rc.2 起会话列表快照已删除 current 字段,官方 ISessions 也不提供「当前会话」访问器,因此不再自造 {current, byId} 形状。

License

MIT

内容来自项目 README(GitHub)↗

链接

同类插件

查看整个分类 →

社区评论

评论公开保存在 GitHub Discussions。加载评论会连接 GitHub 和 Giscus;发表内容需要 GitHub 账号。