longnb47/dsh-agent-gateway

dsh-agent-gateway

一个 MCP stdio 网关，将本地 AI CLI 代理作为 MCP 工具暴露给 DeepSeek Harness (DSH)。

该网关发现已配置的代理配置文件，调用匹配的 CLI 驱动程序，在该驱动程序支持的范围内应用配置文件策略，并返回规范化结果。DSH 仍然是编排器：它选择代理、路由工作并验证结果。网关不代为 DSH 进行规划、路由、合并或接受工作。

subagent_codex 有意置于此网关之外，因为它保留了 DSH 的后台作业生命周期。该网关提供单次 MCP 调用。

快速开始

DSH 目前是开发者预览版。将捆绑包安装到目标 DSH 配置文件中：

dsh plugin add @longnb47/dsh-agent-gateway@next

在针对特定配置文件时使用 --profile ：

dsh plugin --profile  add @longnb47/dsh-agent-gateway@next

对于以本地包 tarball 形式分发的 RC 版本，请传入 tarball 路径而非包名：

dsh plugin --profile  add

该包声明了一个 DSH 捆绑包补丁。安装会将包添加到配置文件的捆绑包中，并插入一行名为 dsh-agent-gateway 的 @deepseek-ai/dsh-mcp-client 记录。该记录使用 Node 启动已安装的网关；它不引用开发者检出副本。

在启动 DSH 之前，请在以下位置创建网关配置：

~/.dsh/agent-gateway/agents.jsonc

如需进行零成本冒烟测试，请将 examples/agents.example.jsonc 复制到该位置。它使用随附的 fake CLI，不需要真实的 AI CLI，不进行网络调用，也不使用付费服务。fake 脚本路径相对于已安装的包根目录解析。

如果你使用自定义的 DSH_HOME，网关不会从中推导其默认值。请在 MCP 记录的 env 配置中设置 DSH_AGENT_GATEWAY_CONFIG；仅在 shell 中设置它不起作用，因为 DSH MCP 客户端会清除环境中的 DSH_* 变量。请参阅 DSH 集成。

创建配置后，重启或启动所选的 DSH 配置文件。

Fake 冒烟测试

在 DSH 中，按顺序调用以下工具：

1. 不带输入调用 mcp__agent-gateway__list_agents。确认 fake-agent 已列出。
2. 使用 { "agent": "fake-agent" } 调用 mcp__agent-gateway__get_agent_status。确认返回 fake 可执行文件/版本/认证就绪结果，且不读取凭据。
3. 使用真实绝对工作区目录调用 mcp__agent-gateway__call_agent：

{
"agent": "fake-agent",
"task": "Return a smoke-test response.",
"cwd": "",
"timeoutSeconds": 60
}

fake 调用返回与真实驱动程序相同的规范化 AgentResult 结构，且不联系 AI 服务。

工具接口

DSH 将 MCP 工具暴露为 mcp____。公共捆绑包使用 serverName: agent-gateway，因此工具为：
- mcp__agent-gateway__list_agents 返回已启用的配置文件，包括 name、label、description、purposes、policy、driver、kind、costTier、constraints 和 enforcementSummary。
- mcp__agent-gateway__call_agent 接受 { agent, task, cwd, model?, effort?, timeoutSeconds? }。它返回一个规范化的 AgentResult，包含 status（success、error、timeout 或 cancelled）、response 或结构化的 error { phase, code, message }，以及元数据。
- mcp__agent-gateway__get_agent_status 接受 { agent }，并报告可执行文件、版本和认证就绪状态，而不会读取或返回凭据。

驱动与强制执行

| 类型 | 用途 | 只读强制执行 |
|---|---|---|
| fake | 离线冒烟测试和测试夹具 | 无真实 AI CLI；无网络或付费服务 |
| agy | AGY 无头专家调用 | 尽力而为、基于权限；不是操作系统沙箱 |
| codex | Codex 一次性专家调用 | 对只读配置文件实施硬性只读沙箱 |
| opencode | OpenCode 专家调用 | 尽力而为 |

策略意图与实际强制执行是不同的。网关如实报告所请求的策略和驱动强制执行情况；DSH 仍必须将代理输出视为不可信证据并进行验证。

配置缺失或无效

公共捆绑包有意使用 failOnStartupError: false。如果配置文件缺失或无效，网关会向其 stderr 写入一条可操作的错误信息，DSH MCP 客户端会将其转发到 DSH 输出/日志。DSH 会继续启动，但网关工具不会被注册。

该捆绑包还设置了 reconnect.maxAttempts: 3，将失败噪音限制在总共约四次启动尝试（约 3.5 秒）内，而不是 MCP 客户端默认的十次重试。请主动检查配置路径，而不是仅依赖子进程的 stderr。设置完成后，你可以将配置文件行改为 failOnStartupError: true 以实现快速失败启动，或者在需要更长恢复时间时提高 reconnect.maxAttempts。参见故障排除。

兼容性

| 组件 | 状态 |
|---|---|
| DSH 0.1.1-rc.2、DSH 随附的 Node 24、Windows | 已一起验证 |
| Node >=22.3.0 | 捆绑包的 process.getBuiltinModule 表达式所要求；兼容性下限尚未验证 |
| Linux 和 macOS | 未验证；尚无测试 |

新的 DSH 次要版本或 RC 版本可能会更改捆绑包加载器或 MCP 客户端，因为 DSH 是开发者预览版。

安全性

- 捆绑包补丁可能包含 !!js，它会在配置加载期间执行。该包及其补丁是受信任的代码；安装前请检查包。
- 网关以当前用户的权限启动本地 CLI。配置无法提供任意 shell 参数：驱动负责 argv 构造，且进程使用 shell: false。
- 机密仅通过驱动特定的环境变量允许列表传递。它们绝不会被记录、包含在结果元数据中，或打包在包 tarball 中。不要将 API 密钥或令牌存储在 agents.jsonc 中。
- 只读强制执行因驱动而异，如上所示。DSH 必须验证所有 agent 输出。

有关威胁边界和报告流程，请参阅 SECURITY.md。

文档

- 配置参考
- DSH bundle 集成
- 故障排除
- 安全策略
- 更新日志

仓库：