dsh-mcp-glue
适用于 DeepSeek Harness 的会话隔离工作区 MCP 声明，支持可扩展预设和 Composer 管理界面
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:AkotaP/dsh-mcp-glue#d3516930785df2c3619818158b9a5b59584484f1Mcp Glue 以 dsh-mcp-glue 发布，当前版本为 0.3.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
English | 中文
为 DeepSeek Harness 0.2.1-rc.2（离线测试基线 0.2.0-rc.2）加载项目级 MCP 声明。一个工作区的会话只读取自己的配置，并在各自 Agent 作用域内连接服务器；不会把配置写入 DSH 全局 profile，也不会修改原声明文件。
| ID | 工作区相对位置 | 服务器表 | 格式 |
|---|---|---|---|
root | .mcp.json | mcpServers 或 servers，不能同时存在 | JSONC |
vscode | .vscode/mcp.json | servers | JSONC |
codex | .codex/config.toml | mcp_servers | TOML |
cursor | .cursor/mcp.json | mcpServers | JSONC |
gemini | .gemini/settings.json | mcpServers | JSONC |
新的 VS Code portable 配置也通过 root 预设加载。预设只是 Host 配置中的数据，不执行项目脚本或转换函数。
两个界面：
● MCP 已连接/声明），点开可逐台 连接/断开、重新读取 声明、连接全部/全部断开。手动连接等于对该会话 + 该声明指纹的显式授权；断开 是粘性的，声明变化后也不会自动重连。plugins.bundle.config，按包名 keyed），不是另开的设置节。两个座位的文案都以包名为命名空间注册进 ctx.locale 的中英词典，随 GUI 语言切换；没有 locale 服务时使用中文列。
详细契约、安全边界与生效方式见 管理界面文档。客户端半是仓库里的构建产物 lib/client.js，由 src/client.js 经 pnpm run build 生成；缺这个文件时宿主会报缺 bundle 并拒绝激活，所以改完客户端源码必须先构建。是否自动热替换取决于宿主的开发构建监听是否运行，页面打开不能说明新 bundle 已生效。宿主半改完要重启 Harness 才会重新 import 模块。
selected）、且策略仍允许自动连接（autoAllowed）的服务器。原生桥接按能力准入：0.2.0-rc.2 / 0.2.1-rc.2 这两个读过生命周期措辞的版本按版本信任，其余版本只要仍接受 reconnect 配置并导出 createMcpToolDefinition 就启用（日志写明“版本未核实、能力已确认”），凑不齐才回退原生行为。手动选择（custom）不妨碍符合策略的服务器重连；未被策略允许的手动连接只有单次尝试。手动断开 / 停止连接保持粘性。required 服务器不可用期间拒绝模型请求，恢复后放行，但保留健康同伴。后台重试发现目标声明变化时以 DECLARATION_CHANGED 停止，等待下一次安全的模型组装 / 编辑协调应用新声明。reconnecting、本地倒计时和尝试次数显示退避，提供「停止连接 / 立即重试」。非法声明、鉴权错误或永久性启动错误暂停；无法确认旧进程已关闭（CLOSE_UNCONFIRMED）时，连手动重试也禁止，须换会话或重启宿主。原生版本 / 接口无法验证时明确显示监控不支持，回退原生连接而不启用增强重连。HEAD，1.5 秒超时，不带凭据，任何 HTTP 响应都算存活）。第一次失败立即撤下绿点、显示「待确认」，1.2 秒后复核；连续两次失败才交给重连监督器，而任何真实调用成功都会刷新确认。节奏随活跃度：有 MCP 活动时 10 秒，2 分钟后 30 秒，5 分钟无活动即停。面板打开时与工具调用前（距上次确认超过 5 秒）会即时探测，不可达时该次调用立刻得到明确原因，而不是干等工具超时；原调用不会重放。stdio 依赖子进程退出事件，不做探测。更多边界见管理界面的自动重连说明。本轮验证仅覆盖后端检查与客户端构建，尚未完成运行中宿主的部署验证；宿主源码改动必须实际重启 Harness，不能靠切换插件条目或假定 HMR 生效。
三种方式，任选其一。三条路都只把包装进 profile 的 node_modules，随后由 dsh.bundle.patch 插入 workspace-mcp-glue 条目，在插件页确认 dsh-mcp-glue 已启用即可。
pnpm dsh plugin --profile <profile> add 'github:<owner>/dsh-mcp-glue'
# 建议锁到具体 commit：'github:<owner>/dsh-mcp-glue#<sha>'
lib/client.js 已随仓库提交，prepack 只在本地打包时跑（DSH 侧执行的是 pnpm add <spec>，不跑 pack 生命周期）。仓库里也没有 install 期脚本，因此不会出现「有待批准的依赖构建脚本」。# 在 profile 目录执行；spec 用 link: 指向本工程
pnpm add link:<本工程绝对路径>
pnpm pack 后在插件界面安装生成的 tgz（prepack 会先重建 lib/client.js）。本包的运行时代码刻意不 import 任何 @deepseek-ai/dsh-* 模块：作用域身份来自模块私有 Symbol，第二份模块拷贝会让 scoped 注册退化成全局注册。原生 MCP 桥接通过宿主 Cordis loader 按运行时自己的实例加载（详见调查笔记）。
peerDependencies 只声明 @deepseek-ai/dsh: >=0.2.0-rc.2 并标为 optional。DSH 用它做安装与启动时的版本兼容判定（只认 @deepseek-ai/dsh 与 @deepseek-ai/dsh-* 前缀），不满足就拒绝安装或告警；标 optional 后 pnpm 不会自动安装它，它也不代表运行时 import。engines.dsh 只是文档，运行时不读。
开发/打包（node/pnpm 应为 Node 22.16+）：
pnpm install --ignore-scripts
pnpm run build # 生成客户端半 lib/client.js（缺失会导致激活失败）
pnpm test
pnpm run check
pnpm pack
若通过 CLI 安装，先用 dsh plugin --help 核对当前版本的命令参数；不要直接把项目里的 MCP 列表导入 profile。
六个可热改字段（enabledBuiltins、presets、trustMode、trustedWorkspaces、workspaceAllowances、conflictPolicy）在 Config 里声明为 .volatile()：DSH 的 ctx.settings 只把「有 volatile 字段」的 Loader 条目视为可配置（describe() 直接丢掉其余条目），写入经 configEditor 落进 profile patch 并由 Loader 就地应用，保存后立即生效、不需要重启。上限、密钥（inputValues，secret 角色）与 webControl 刻意不可热改，也不在浏览器与宿主之间往返。
同样的值也可以直接写在自己的 profile patch 里，覆盖安装产生的条目（这样改不会经过设置表单，但两者是同一份文件与同一条 config）：
- id: workspace-mcp-glue
config:
enabledBuiltins: [root, vscode, codex, cursor, gemini]
trustMode: manual # manual | all（all 等于信任一切仓库，谨慎）
trustedWorkspaces: # 这个目录里的声明全部允许自动加载；精确匹配目录本身
- 'D:\Data\Project\trusted-project'
workspaceAllowances: # 只信这个目录里的这几样
- workspace: 'D:\Data\Project\other-repo'
allowMcp: [team-tools]
allowTools: ['mcp__team-tools__identity']
conflictPolicy: error
webControl: true # 注册管理界面的同源控制路由；false 则界面只读不到状态
一个声明的服务器是否自动连接，按三层判定，从强到弱，任一层命中就加载：
trustMode: all —— 信任一切：任何仓库的声明都会启动本地程序（高风险 opt-in，别对不可信仓库用）。trustedWorkspaces —— 这个目录里的声明全部允许自动加载。目录按规范化身份精确匹配，不包含其子目录。workspaceAllowances[].allowMcp —— 这个工作区里只允许列出的那几个服务器自动加载。三层都不命中时：保持未加载，插件不会主动弹批准框（这点与早期版本不同）。要让它跑起来，点面板里那一行的「连接」，或者打开面板底部的「始终信任此工作区」开关——授权只能由用户在界面上做出，插件不代用户询问。
selectionMode: custom，之后声明再变也不会把它悄悄移除，点「恢复自动」才回到策略判定）；对策略已允许的服务器点「连接」或「立即重试」只是重试一次，不改变意图、不出现「恢复自动」。「断开」则是真正的意图改变，仍然粘性。includeTools/excludeTools（Codex enabled_tools/disabled_tools、Gemini）是项目自己的工具过滤，与信任无关：被项目排除的工具永远不可用。允许一个服务器启动和允许它的某个工具被调用是两件事。当一个工具来自「服务器已被允许、但这个工具不在 allowTools 里」的工作区时，插件在 tools/pre-execute 闸门里先问用户，给三个答案：
| 答案 | 效果 |
|---|---|
| 仅此次允许 | 放行这一次；下次调用仍会询问 |
| 总是允许这个工具 | 把 mcp__<server>__<tool> 写进该工作区的 allowTools，以后不再询问（面板里的工具开关读写的就是同一份名单） |
| 拒绝 | 本次调用返回一条错误结果，模型看得到原因，回合继续 |
ctx.userQuestions），在对话里显示成一张带选项的卡片，不是 DSH 的批准弹窗：只有这条路能给出三个选项，而不是「允许一次 / 拒绝」两个。trustMode: all、工作区在 trustedWorkspaces 里、工具在 allowTools 里、部署或当前会话本身是 danger-full-access（用户已全局表态过）、这个 composition 没装问答服务，或调用来自被委派的子 Agent（DSH 不允许子 Agent 打开人类交互）。最后两种都直接放行，绝不把工具调用挂死。exec 字段、决策四态、与 tools.guard 的关系，以及判断完全权限的正确姿势，见闸门契约。includeTools / excludeTools（Codex enabled_tools / disabled_tools、Gemini）由 tools.guard 在本闸门之后执行，而 guard 只能拒绝、没有任何东西能把它翻回允许。所以一个被项目禁用的工具既不会被询问、也不会被面板放行：闸门直接跳过它，交给 guard 用准确的理由拒绝；面板把那一行标成「项目已禁用」并且不给开关——避免出现永远不生效的开关。MCP 小面板标题栏提供 ＋新建 / 管理；服务器名称与 ⋯ 可直达编辑。新建和编辑在独立大弹窗完成，左侧服务器列表始终保留；配置位置直接在表单里选择，默认优先本工作区上次使用的可写位置，其次项目配置。小面板保留「始终信任此工作区」快捷开关，逐台自动连接与权限策略放在管理弹窗。
url / headers；stdio 只显示 command / args / env / cwd。命令、URL、工作目录用单行；参数用多行（每行一个参数）；环境变量与请求头默认逐行填写键和值，值默认遮掩，可切换高级 JSON 模式。已有条目也能补填原先不存在的字段；重复键或漏填键会阻止提交。type（stdio / http）。Gemini、Codex 也提供连接方式选择器，但仅用于筛选表单，不会写入不存在的 type；文件按命令或地址推断连接方式。自定义字段映射同样参与推断。sse 不提供：加载器会以 UNSUPPORTED_SSE 直接拒绝整台服务器，所以插件在写入前就拦下这种值，而不是写进去再回滚。dialect——不写就是 standard，于是有调用方式；写到哪个键由 fields.transport 决定（不写就是 type）。如果某个格式没有「调用方式」这个概念，把 fields: { transport: '' } 映射成空串即表示不支持，否则我们会往文件里写一个没人读的 type。null = 删掉对应键。jsonc-parser 的 modify，YAML 走 Document API。@iarna/toml 会重写整个文件，整个文件的注释和排版可能丢失，其他配置值保留。表单会提示，保存 / 删除 / 迁移前还要单独确认；后端也要求严格的 allowLossy: true，不确认就不落盘。新建尚不存在的 TOML 文件无需这次确认，版本守卫和失败回滚仍然有效。read-only 时会话里入口只读并说明原因；workspace-write 及以上才允许保存。.mcp.json 同时被 VS Code / Cursor 读，.codex/config.toml 是 Codex 的。「改了哪个文件、哪个键」都会记进宿主日志。transport 不会写入。含工具过滤、凭证转发或超时等尚未支持转换的高级字段时拒绝复制，防止静默丢失语义；同一物理文件不允许通过预设别名复制到自身。迁移失败时对源和目标均做版本守卫回滚。agent.session.header.cwd 为唯一工作区根；不使用 DSH Host 的当前目录，不向父目录寻找项目根，不读取用户全局 MCP 配置。required: true 的服务器声明本身非法、启动失败或运行中断线会拒绝模型请求而不是静默降级；运行时故障由符合资格的监督重试恢复，模型请求不绕过退避，健康同伴保留。至于「没被授权且未选中」——那只是没加载，不是错误：插件不会为一个用户的沉默而打断会话。system-prompt/assemble 的组装阶段，因此新增/删除的服务器能在当前这次请求就生效，而不是等到下一轮。完整例子见 自定义预设示例。可以定义任意工作区相对文件位置、解析格式、服务器表路径、字段映射，也可以继承或覆盖内置预设：
- id: workspace-mcp-glue
config:
presets:
- id: team-tools
files: ['.team/mcp.yaml']
format: yaml
serversPaths: ['/integrations/mcp']
fields:
command: executable
args: arguments
env: environment
transport: connection.type
url: connection.url
headers: connection.headers
- id: extra-vscode
extends: vscode
files: ['.tools/mcp.json']
# 同 ID 覆盖内置预设，不修改插件源码
- id: cursor
enabled: false
该团队声明可写成：
integrations:
mcp:
local:
executable: node
arguments: ['${workspaceFolder}/tools/server.js']
environment:
API_TOKEN: '${env:MY_TOKEN}'
serversPaths / fields 接受点路径或 RFC6901 JSON Pointer；空字符串代表对象根。服务器表必须是「名字 → 对象」的映射，不支持数组、glob、任意 JS/eval。文件和 envFile 经规范化后必须位于工作区内，拒绝目录联接/符号链接逃逸。
可映射字段：transport, command, args, env, cwd, url, headers, enabled, disabled, envFile, envVars, envHeaders, bearerTokenEnv, timeoutMs, timeoutSeconds。
格式：json, jsonc, toml, yaml。方言：standard, codex, gemini。extends 可以继承内置或前面定义的自定义预设；自定义预设按定义顺序追加，内置预设顺序由 enabledBuiltins 决定。
standard 支持 ${VAR}, ${VAR:-default}, ${env:VAR}, ${workspaceFolder}, ${workspaceFolderBasename}, ${userHome}, ${pathSeparator}, ${/}, ${configDir}, ${input:id}。shell（Gemini 默认）另支持 $VAR 与 %VAR%；none（Codex 默认）保留字面字符串。${input:id} 只读取 Host 插件配置 inputValues，值在设置 schema 中标记为 secret；不会运行 VS Code 的 inputs.command。envFile 是工作区内 UTF-8 dotenv 文件，按字面值解析；显式 env 覆盖其值。它不会自动成为其他字段插值的环境来源。env_vars 转发指定的宿主变量，env_http_headers 读取 header 对应的变量值，bearer_token_env_var 读取 token 并添加 Bearer。不支持 remote 来源。$/${...} 不会递归解释。插件自身诊断只记录预设名、文件名、服务器名与错误码；原生桥接的启动错误被降级为不含正文的摘要，避免密钥经 spawn 错误进入日志。command 按声明中的 cwd（未声明时是工作区）解析，与各客户端在子进程 cwd 下解析的语义一致；args/cwd 中出现 NUL 字符会被拒绝。conflictPolicy: error 禁用不同来源中存在不同配置的同名服务器；完全相同的声明去重。可显式选择 first-wins/last-wins，整条替换、不混合凭证。type: http 映射到 Streamable HTTP。未指定 type 时根据 command/url 推断，是兼容加载器策略而非 Claude 的严格校验行为。httpUrl 是 HTTP，url 是旧 SSE，不会误当 HTTP。enabled_tools/disabled_tools 与 Gemini includeTools/excludeTools 的调用限制（排除优先）；被禁工具可能仍在 schema 列表中，但直接调用/PTC 调用均会被 guard 阻止。Gemini trust 不会自动批准工具。env 中 null 删除继承变量；非字符串/数字环境值拒绝。不会导入其他客户端的单工具批准/输出截断策略。__ 或以 _ 结尾的名字也会 hash，避免原生未转义分隔符造成工具身份/过滤前缀重叠。startup_timeout_sec 可覆盖单台启动超时。多台服务器并发启动（最多 6 台同时进行，MOUNT_CONCURRENCY）：一代的总耗时取决于最慢的那台，而不是各台之和——本机实测一台 stdio 服务器约 470 ms，串行 5 台要 2.4 s，而读取并解析全部声明文件只要约 3 ms。DSH 加载链路调查 记录原生加载方式、扩展点及为什么不能把项目配置放进全局 Loader；管理界面文档 记录控件契约、控制路由与令牌边界。测试目录 使用真实 Cordis/DSH MCP 桥接与本地 JSON-RPC fixture，覆盖工作区并发隔离、更新、资源/指令、首次请求与卸载；HTTP 测试 用真实 dsh-host-webserver 跑通令牌注入 → 状态 → 手动连接的完整链路。
外部格式依据：
本包是声明格式兼容加载器，不是这些客户端的完整运行时或鉴权实现。
conflictPolicy