harness-relay-mcp

dsh plugin --profile web add harness-relay-mcp

Harness Relay MCP

[English](README.md) | 简体中文

让外部 Agent 委派并持续监控 DeepSeek Harness 任务。

让任何支持 MCP 的 Agent 向 DeepSeek Harness 委派长时间任务，并持续监控直至完成。

Harness Relay MCP 将 MCP 客户端直接连接到 DeepSeek Harness 原生会话与事件模型。推荐形态是安装为 Harness 树外内部 bundle；它不包装 CLI、不修改 Harness 源码，也不接管 Harness 进程。

MCP Agent
   │
   ├─ start_run ── Provider / 模型 / 推理强度 / preset / 权限
   │
   ├─ status_run / wait_run / steer_run / cancel_run
   │
   └─ 持久结果 + 原生 Harness Web 会话链接

定位：Harness 控制平面，而不是模型包装器

Harness Relay MCP 是独立的第三方项目，并非由 DeepSeek AI 开发、背书或提供支持。

这不是 DeepSeek 模型包装器，而是 DeepSeek Harness 的 MCP 控制平面。

请区分三种完全不同的接入方向：

• DeepSeek Harness 官方仓库当前记录的是 mcp-client，用途是让 Harness 消费外部 MCP Server；这与把 Harness 暴露为可由 MCP 控制的工作 Agent 方向相反。
• 简单 DeepSeek MCP Server 直接调用模型 API 并返回模型输出，不会进入 Harness 原生会话、插件、工作区、权限和事件生命周期。
• Harness Relay MCP 连接现有的官方 Harness Host，把该 Host 的原生能力提供给外部 MCP Agent。

截至 2026-08-20，官方 dsh 启动器源码只提供 profile 启动和插件管理，没有记录可对外控制 Harness 的 dsh mcp Server 命令。DeepSeek Harness 仍处于开发者预览阶段，依赖本对比前应重新核对官方仓库。

对比核验日期：2026-08-20。

能力 · 当前官方 Harness · 简单 DeepSeek MCP · Harness Relay MCP

主要方向 · Harness 消费 MCP 工具 · MCP 客户端调用 DeepSeek 模型 · MCP 客户端控制运行中的 Harness Host

原生 Harness 会话和事件 · 内部原生存在，但没有通过文档化 MCP Server 对外提供 · 不支持 · 支持

Harness 插件、工具和沙箱 · Harness 内部原生能力 · 不支持 · 由 Harness 原生执行

Provider/模型/推理强度/preset · Harness UI 和 API 内可用 · 通常只有少量固定模型参数 · 从 Host 发现并选择

原生权限 preset · Harness 内部行为 · 没有工作区权限体系 · read-only、workspace-write、danger-full-access

长任务生命周期 · 在 Harness 内操作 · 通常一次请求返回一次结果 · 启动、查询、等待、纠偏、回复、取消、重新打开

持久监控和恢复 · Harness 保存会话历史 · 通常没有 · Relay 运行标识、幂等、对账和重启恢复

Harness Web 会话链接 · 原生 UI · 没有 · 返回并可验证

安装与维护 · 只使用 Harness 时最低 · MCP 方案中最简单 · 组件更多，需要持续适配 Harness

如何选择

• 只需要分类、提取、总结或快速第二意见，而且模型文本输出已经足够时，使用简单 DeepSeek MCP Server。
• 任务必须在 DeepSeek Harness 内运行，并需要已登记工作区、工具、插件、Provider 目录、原生权限、持久会话、长任务监控、故障恢复或 Web 查看时，使用 Harness Relay MCP。
• 不要仅为替代一次普通 Chat Completions 请求而安装 Relay；额外的 Host、状态、认证和 proxy 层不会在这种场景中产生足够的控制面价值。

主要能力

• 使用 Harness 原生会话和持久事件，不解析 CLI 输出。
• 完整异步生命周期：启动、查询、等待、纠偏、回复、取消和重新打开。
• 在首条任务提示词前选择 Provider、模型、推理强度、Agent preset 和原生权限。
• 直接支持 Harness 的 read-only、workspace-write、danger-full-access 三档权限。
• 支持有序文本和内联图片提示词，并对 base64 和大小进行有界校验。
• 持久保存运行标识，MCP Server 重启后可恢复监控。
• 返回稳定的 Harness Web 会话链接；随附 Skill 会在分享前验证页面确实可见。
• 兼容 Codex、Claude Code、OpenCode、Cursor 及其他符合标准的 MCP 客户端。
• 内部 bundle 使用 Harness 0.1.2 的直接 Typert Gateway 和原生权限服务；外部 Agent 通过认证 HTTP 或无状态 stdio proxy 调用。
• 保留独立 dsh-relay 模式用于旧版 Harness 和显式回滚。

运行要求

• Node.js ^22.19 或 >=24。
• Relay 0.2.19 内部模式要求 DeepSeek Harness >=0.2.1-alpha.5 <0.3.0、web profile，并只允许 127.0.0.1 绑定。使用新版 Typert 网关要求的公开 connection Peer API；须同时更新内嵌 bundle 与客户端代理并重启 Host，旧版 Relay 未传递必需的 Peer。
• 独立兼容模式要求已在本机回环 HTTP 地址运行的 DeepSeek Harness Web Host。
• 目标工作区必须已在 Harness 中登记，或属于明确配置的允许根目录。

默认 Host 地址：

http://127.0.0.1:3080/

安装

安装为 Harness 内部 bundle（推荐）

使用 Harness 官方 profile 命令从 npm 安装已发布包，检查组合后的配置，再启动该 profile：

dsh plugin --profile web add harness-relay-mcp
dsh --profile web --dump-config
dsh --profile web

离线安装或需要锁定本地文件时，可下载 Release tarball，并将第一条命令中的 harness-relay-mcp 替换为本地 .tgz 路径。

配置输出应包含 id: harness-relay-mcp 和 name: 'harness-relay-mcp'。因此 Harness 插件列表显示为无斜杆的 harness-relay-mcp。如果 dsh web 已在运行，安装或升级后需要重启该 Host 才会加载新 bundle。启动后，bundle 会继续在兼容路径 $DSH_HOME/plugins/dsh-relay/web/relay-endpoint.json 发布不含密钥的端点描述；Bearer token 单独保存在 Host 专属状态目录。

卸载不会取消已提交的 Harness 任务：

dsh plugin --profile web remove harness-relay-mcp

不要把 Relay 再配置进同一 Harness 的 MCP client，否则会形成 Harness → Relay → Harness 递归。

安装 Codex 插件

Codex 插件是外部调用层，不能替代前面的 Harness 内部 bundle。先确认 dsh --profile web 已加载 harness-relay-mcp，再从本仓库 Marketplace 安装 Codex 插件：

codex plugin marketplace add tonytanglab/deepseek-harness-relay-mcp
codex plugin add deepseek-harness-relay@harness-relay
codex plugin list

第一条命令登记本项目的 GitHub Marketplace；第二条命令从 npm 获取同版本插件包，并为 Codex 加载 .mcp.json 与 delegate-to-deepseek-harness Skill。Codex 侧只启动无业务状态的 dist/dsh-relay-proxy.mjs，它通过端点描述连接已经运行的 Harness 内部 bundle；这个流程不会修改 DeepSeek Harness 源码、web profile 的内部 bundle 配置或 cordis.patch.yml。

若更新后原生工具消失，且 Codex 报 connection closed: initialize response，先检查任务引用的缓存目录是否仍包含 dist/dsh-relay-proxy.mjs。新缓存目录存在不代表运行中的宿主已切换。使用桌面应用对应的 Codex CLI 从已确认的 Marketplace 重装；如果新任务仍引用已移除的缓存，保存进行中的工作后重启应用。必须验证原生 doctor 和工具目录后再宣称恢复，不得改用临时 Relay 客户端。

如果 personal Marketplace 指向本地源码目录，Codex 安装器只复制现有文件，不会运行 TypeScript/esbuild 构建。每次拉取源码后必须先在该目录执行 pnpm run prepare:codex-local；命令会构建并校验三套 dist 产物的内嵌版本及 proxy 的完整工具目录，然后才能生成 cachebuster 并执行 codex plugin add。否则可能出现 manifest 和安装记录显示新版、实际 MCP 进程仍运行旧 bundle 的假升级。正式使用优先采用上面的仓库 Marketplace/npm 安装路径。

Codex 内置 MCP 的生成规范（不要写错入口）

Windows 偶发控制台弹窗还需检查 Harness 本体：启用原生 Job 子进程管理时，Node runner 必须设置 windowsHide: true，原生 CreateProcessW/CreateProcessAsUserW 目标必须使用 CREATE_NO_WINDOW。仅更新 Relay 或修复 Harness 的普通 spawn 回退入口不足以覆盖这条路径；更新 Harness 后须重启实际 Host，并验证控制台可见性及输出、退出和清理行为。

Codex 插件 manifest 必须同时引用 Skill 和包内 MCP 声明：

{
  "skills": "./skills/",
  "mcpServers": "./.mcp.json"
}

随插件发布的 .mcp.json 必须使用下面的相对入口：

{
  "mcpServers": {
    "harness-relay-mcp": {
      "command": "node",
      "args": ["./dist/dsh-relay-proxy.mjs"],
      "cwd": "."
    }
  }
}

cwd: "." 由 Codex 解析到当前已安装插件的版本根目录。不要写开发机绝对路径或 %USERPROFILE%\.codex\plugins\cache\... 版本缓存路径；不要在 Codex 用户 config.toml 再注册第二份同名 MCP。最重要的是，Codex 只能启动 dsh-relay-proxy.mjs：不能指向 dsh-relay-harness.mjs（Harness 内部 bundle），不能指向会另建独立控制面的 dsh-relay.mjs，也不能由 Agent 手工启动第二个 Harness Web。proxy 通过 $DSH_HOME/plugins/dsh-relay/web/relay-endpoint.json 发现

…(truncated)