dsh-cordis-universal-adapter
面向 DeepSeek Harness 的双向桥接插件：消费外部 MCP 服务器与 Agent Plugins 1.0 包，并把 DSH 原生工具反向暴露为标准 MCP 服务器。
一句话描述
在 DSH（DeepSeek Harness）的 Host 组合层 上，把 MCP 生态（服务器、Agent Plugins 1.0 包）接入 ctx.tools，
同时把 ctx.tools 导出为 MCP 服务器，让同一批工具同时以 DSH 原生与 MCP 两种形态暴露。
外部 MCP 服务器 ──▶ McpClientBridge ──▶ ctx.tools（DSH 工具）
Agent Plugins 1.0 ─▶ PluginLoader ─────┘ │
▼
外部 MCP 客户端 ◀── McpServerBridge ◀── ctx.tools.schemas()
安装
三条安装命令（按场景选择）：
# 从 GitHub 仓库安装
dsh plugin --profile web add github:helibeiqi/dsh-cordis-universal-adapter
# 从 npm 安装
dsh plugin --profile web add dsh-cordis-universal-adapter
# 从本地目录安装（开发调试）
dsh plugin --profile web add "file:./dsh-cordis-universal-adapter"
平面说明：Host 组合层
本插件不是 Agent（不参与对话主循环），也不是工具本身——它是一个 Host 组合层的连接器：
- Inbound（正向）：连接外部 MCP 服务器（stdio / Streamable HTTP），
listTools() 后把每个 MCP 工具
注册为 ctx.tools 中的 DSH 工具（命名 mcp:<serverId>:<toolName>）；加载 Agent Plugins 1.0 包时，
解析 plugin.json + skills/*/SKILL.md + mcp.json，把 Skill 描述注入系统提示词扩展点。
- Outbound（反向）：通过
ctx.tools.schemas() 枚举已注册工具，注册到 McpServer，
经 serveStdio（或 HTTP）暴露给任意 MCP 客户端（命名 dsh:<toolName>）。
- 路由（可选）：语义路由通过
ctx.llm 的带 tools 参数的 chat 接口（function calling）为任务排序工具，
失败退化为 prompt-based 选择；默认关闭，开启后每次路由产生一次 LLM 调用。
- 生命周期：所有连接由状态机（start / stop / update）管理，
update 时"断开旧 → listTools → 注销旧 → 注册新"，
与 DSH HMR 协同；卸载时经 ctx.effect 全部回收。
支持的 DSH 版本区间
| 依赖 | 版本区间 |
|---|
@deepseek-ai/cordis | >=0.1.0（peerDependency） |
@deepseek-ai/dsh-tools | >=0.1.0（peerDependency） |
| Node.js | >=22.19 |
⚠️ Developer Preview 破坏性变更警告：@deepseek-ai/dsh-tools 与 MCP 均处于 Developer Preview 阶段，
接口可能破坏性变更。本插件在 0.1.x 内锁定已验证的 API 形态（见 docs/DESIGN.md §14 真实 API 对齐修正与
§15 真实运行时验证发现）；依赖升级导致签名变化时，请关注 CHANGELOG 中的迁移说明。
ℹ️ 已在 dsh 0.1.0-rc.6 实测通过：插件挂载进配置树、真实连接 filesystem MCP 服务器（注册 14 个工具）、
Agent 调用其工具返回真实结果、单服务器故障隔离。注意 dsh bundle 要求 package.json 中
dsh.bundle 为对象形式（{ "patch": "./cordis.patch.yml" }），且 patch 文件为顶层 YAML 数组语法。
配置字段表
cordis.patch.yml 插件段（完整示例见仓库内 cordis.patch.yml）：
| 字段 | 类型 | 默认值 | 必填 | 说明 |
|---|
servers[] | array | [] | 否 | 外部 MCP 服务器列表 |
servers[].id | string | — | 是 | 唯一标识（[A-Za-z0-9_-]），用于工具命名空间与状态跟踪 |
servers[].transport | 'stdio' | 'http' | — | 是 | 传输类型 |
servers[].command | string | — | stdio 时必填 | 子进程命令（如 npx） |
servers[].args | string[] | [] | 否 | 子进程参数 |
servers[].env | record | — | 否 | 附加环境变量（凭据不落日志） |
servers[].url | string | — | http 时必填 | Streamable HTTP 端点 |
servers[].headers | record | — | 否 | 静态请求头（支持 ${ENV_VAR} 插值） |
servers[].requestTimeoutMs | number | 30000 | 否 | callTool/listTools 超时 |
servers[].connectTimeoutMs | number | 10000 | 否 | 连接握手超时 |
pluginDirs[] | array | [] | 否 | Agent Plugins 1.0 包目录 |
export.enabled | boolean | false | 否 | 是否反向导出 DSH 工具 |
export.transport | 'stdio' | 'http' | 'stdio' | 否 | 导出传输 |
export.name | string | 'dsh-export' | 否 | 导出服务器名 |
export.namespace | string | 'dsh' | 否 | Outbound 工具前缀 |
|
端到端示例：加载社区 filesystem MCP 服务器
# cordis.patch.yml
plugins:
dsh-cordis-universal-adapter:
servers:
- id: filesystem
transport: stdio
command: npx
args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
启动后，DSH 中将出现 mcp:filesystem:read_directory、mcp:filesystem:write_file 等工具，
Agent 可以直接调用：
用户：读取 /tmp 目录下有哪些文件
Agent → 调用 mcp:filesystem:read_directory({ path: "/tmp" }) → 返回目录列表
dsh --profile web --dump-config # 确认插件正确挂载进配置树
反向导出示例：把 DSH 原生工具导出为 MCP 服务器
plugins:
dsh-cordis-universal-adapter:
export:
enabled: true
transport: stdio
namespace: dsh
DSH 中所有已注册工具（ctx.tools.schemas()）将以 dsh:<toolName> 暴露。任意 MCP 客户端
（Claude Desktop、其他 Harness、@modelcontextprotocol/inspector）连接该 stdio 端点后即可调用：
# 在 DSH 进程内加载本插件（export.enabled=true），然后在外部：
npx @modelcontextprotocol/inspector # 选择 stdio 模式连接 DSH 进程
独立调试可用仓库自带脚本（不依赖 DSH 运行时，演示转换链路）：
npx tsx scripts/export-mcp.ts # 启动 stdio 演示服务器（dsh:echo / dsh:add / dsh:fail）
开发调试
npm install
npm run typecheck # tsc --noEmit（含 tests/scripts）
npm run lint # ESLint（零警告）
npm run test # Vitest（核心模块覆盖率 ≥ 80%）
npm run build # 产出 lib/
npm pack --dry-run # 检查 tarball 只含 lib/ + README + LICENSE
调试要点：
- 日志脱敏：
env / headers / URL 凭据永不写入日志；Authorization 用 ${ENV_VAR} 插值。
- 状态查看：监听
universal-adapter/status 事件（ctx.on）可跟踪每个 server 的连接状态机。
- 单服务器故障隔离：一个外部 MCP 服务器连接失败只影响自身（状态
error），不阻断其他服务器与导出。
- HMR：插件
apply 重跑时旧 ctx.effect cleanup 自动执行；配置热更优先走 update()。
已知限制
- JSON Schema → DSH DSL 仅支持常用子集：
$ref / 循环引用 / 复杂 oneOf 降级为宽松校验
（schema.strict: false 时工具仍注册，入参不校验）。
- Streamable HTTP 认证：仅支持静态头（Bearer token），OAuth 动态流程不在 0.1 范围。
- 反向导出返回值：DSH 工具返回值必须是 JSON 可序列化值；二进制 / 流式输出不支持。
- 路由开销：
router.enabled: false 时零 LLM 开销；开启后每次路由一次 LLM 调用，且不缓存。
- 跨 server 工具名唯一性：依赖
serverId 前缀保证；serverId 冲突会导致注册报错
（按 naming.conflictStrategy 处理）。
- 不实现沙箱：外部 MCP 服务器的隔离依赖其宿主进程边界（stdio 子进程 / 远程 HTTP 服务）。
GitHub 仓库发布步骤
- 推送公开 GitHub 仓库（helibeiqi/dsh-cordis-universal-adapter）
- 添加 topic：
dsh-plugin、deepseek-harness、agent-plugin、mcp、cordis
npm login && npm publish- 在 DSH 社区 Discussions 宣布发布
License
MIT © dsh-cordis-universal-adapter contributors
