Harness Relay MCP

English | 简体中文

让外部 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。

如何选择

• 只需要分类、提取、总结或快速第二意见，而且模型文本输出已经足够时，使用简单 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 使用官方 InProcess ApiProxy 和原生权限服务；外部 Agent 通过认证 HTTP 或无状态 stdio proxy 调用。
• 保留独立 dsh-relay 模式用于旧版 Harness 和显式回滚。

运行要求

• Node.js ^22.19 或 >=24。
• 内部模式要求 DeepSeek Harness 0.1.0-rc.7 兼容系列的 web profile，并只允许 127.0.0.1 绑定。
• 独立兼容模式要求已在本机回环 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，并新建一个 Codex 任务，让新任务加载 MCP Server 和 Skill。可在新任务中要求：

调用 Harness Relay 的 doctor 和 list_workspaces，只做只读检查，确认 Harness Host、Relay 端点和工作区是否可用。

升级仓库 Marketplace 与 Codex 插件时：

codex plugin marketplace upgrade harness-relay
codex plugin add deepseek-harness-relay@harness-relay

然后再次重启 Codex 并新建任务。不要把 Relay 配置为同一个 Harness 的 MCP client；Codex 插件应连接 Relay proxy，而 Harness 仍通过 dsh plugin --profile web add harness-relay-mcp 管理内部 bundle。Codex Marketplace 的官方格式与命令参见 OpenAI 插件打包文档。

#### 让 AI 分析并协助安装

尚未安装插件的用户可以把下面提示词直接交给具备终端权限的 Codex。AI 应先只读检查环境、说明将发生的改动并获得用户确认，再执行安装；不得修改 DeepSeek Harness 产品源码或把 Relay 配回 Harness MCP client：

请阅读 https://github.com/tonytanglab/deepseek-harness-relay-mcp/blob/main/README.zh-CN.md 的“安装”章节，协助我安装 Harness Relay MCP。
先只读检查操作系统、Node.js 版本、dsh、Codex CLI、Harness web profile 和 127.0.0.1:3080，不要修改任何文件。
列出检测结果、缺失依赖、拟执行命令和影响范围，获得我确认后再操作。
Harness 侧只能使用 dsh plugin --profile web add harness-relay-mcp 安装内部 bundle，不修改 DeepSeek Harness 源码，不把 Relay 添加为 Harness MCP client。
Codex 侧使用仓库 Marketplace tonytanglab/deepseek-harness-relay-mcp，安装 deepseek-harness-relay@harness-relay。
安装后验证 dsh --profile web --dump-config、codex plugin list，并提醒我重启 Codex、新建任务后运行 doctor 与 list_workspaces。遇到错误时停止并报告原始错误，不扩大权限、不删除现有配置。

本地开发

pnpm install
pnpm run build

内部 bundle 启动后，让 MCP 客户端启动通用 stdio proxy：

{
  "mcpServers": {
    "harness-relay-mcp": {
      "command": "node",
      "args": ["C:/Users/you/plugins/deepseek-harness-relay-mcp/dist/dsh-relay-proxy.mjs"],
      "env": {
        "DSH_RELAY_CLIENT_PRINCIPAL_ID": "cursor:project"
      }
    }
  }
}

proxy 默认读取 $DSH_HOME/plugins/dsh-relay/web/relay-endpoint.json；未设置 DSH_HOME 时统一回退到用户目录下的 .dsh，空白 DSH_PROFILE 回退到 web。自定义状态目录时显式设置 DSH_RELAY_ENDPOINT_DESCRIPTOR。客户端配置不保存 token。harness-relay-mcp 包根入口是 Harness bundle，同时提供 harness-relay-mcp、harness-relay-mcp-proxy 命令；旧 dsh-relay 命令作为兼容别名保留。

0.2.3 起，内部 bundle 会在 endpoint 同目录原子发布不含凭证的 relay-status.json。stdio proxy 先启动本地 MCP；当 endpoint 缺失、状态失败、owner epoch 不匹配、token 不可读或 POST 返回 401/404/405/503 时，tools/list 至少保留本地 doctor，其他工具统一返回 RELAY_ROUTE_UNAVAILABLE。Host 恢复后，同一个 proxy 会重新连接并发送 tools/list_changed；不处理该通知的客户端需要主动重新调用 tools/list。

快速开始

先读取 Harness 原生工作区注册表，不要把 Host 进程目录当成授权清单：

{
  "tool": "list_workspaces",
  "arguments": {}
}

然后读取 Host 实际能力，不要猜测路由名称：

{
  "tool": "list_capabilities",
  "arguments": {}
}

然后使用 Kimi K3/MAX 发起只读审查：

{
  "tool": "start_review",
  "arguments": {
    "workspace": "D:/work/project",
    "task": "审查此工作区，只返回可复现的发现。",
    "provider": "kimi-coding",
    "model": "k3",
    "reasoningEffort": "max",
    "agentPreset": "standard",
    "idempotencyKey": "review-2026-08-19-001"
  }
}

保存返回的 runId、sessionId 和 webUrl，通过有界等待监控运行：

{
  "tool": "wait_run",
  "arguments": {
    "runId": "<run-id>",
    "timeoutMs": 30000
  }
}

活动运行需要补充或纠正时调用 steer_run。运行进入终态后，通过 reply_run 在同一个原生 Harness 会话中继续对话。

同时省略 sessionId 和 sessionMode 时，会在所选 Harness 工作区内创建新会话。需要延续现有项目对话时，先调用 list_workspace_sessions 并传入其中空闲的 sessionId，或者传入 sessionMode: "latest-idle"，复用最新的非空、空闲、未归档会话。显式 sessionId 不能与 sessionMode 同时使用。

运行生命周期

start_run
   │
   ├─ 预留会话
   ├─ 选择模型和原生权限 preset
   ├─ 持久化 runId + prompt rpcId
   ├─ 提交 session.prompt
   └─ 与持久历史对账

running ── status/wait/steer/cancel ──> succeeded | incomplete | failed | cancelled | needs_attention
   │
   └─ 终态 ── reply_run ──> 同一会话中的新运行

promptAdmission 表示提示词接纳状态：

start_run 参数

图片提示词

使用不带 data: URL 前缀的规范 base64：

{
  "workspace": "D:/work/project",
  "content": [
    { "type": "text", "text": "审查这张截图。" },
    {
      "type": "image",
      "mediaType": "image/png",
      "data": "<canonical-base64>",
      "name": "screen.png"
    }
  ]
}

支持 PNG、JPEG、WebP 和 GIF。图片字节会发送给 Harness，但不会保留在 Relay 运行快照或状态文件中。

原生权限 preset

DSH Relay 通过 commands/execute 调用 Harness 原生 /permission 命令，并在提交首条任务提示词前核验会话投影。提示词中的文字声明不会被当作权限边界。

MCP 工具

客户端配置与监控投影

setup_plan 支持 Codex、Claude Code、Cursor，以及显式标记版本的 OpenCode V2 配置结构。它接收已经解析的 Node 与 Relay 入口绝对路径，只返回结构化最小补丁，绝不直接编辑客户端配置。启动器平台必须与配置平台一致；pnpm.exe、pnpm.cmd 等包管理器 shim 不能充当 Node 运行时。

setup_doctor 同样无副作用。文件系统、Broker、Host、工作区、模型和权限事实必须由获得授权的调用方提供；未提供的探针会标记为 skipped，不会猜测结果。

get_run_summary 消费 Relay 权威运行快照并输出版本化监控投影。read_notifications 重放当前 MCP Server 进程保留的通知，并在游标缺口时返回明确的重同步元数据。原生运行通知 transport 尚未启用，因此通知缓冲为空属于正常情况，客户端必须自动降级到 get_run_summary、wait_run 或 get_run 轮询。

持久化与故障恢复

默认状态文件：

%LOCALAPPDATA%/dsh-relay/state.json

状态会经过 schema 校验、带所有者校验的跨进程锁和原子替换，并在支持的平台上使用限制性文件权限；旧写入者不能回退已停止服务、终态运行、待处理状态、操作或权限租约。损坏文件会被隔离而不是覆盖。默认不持久化提示词文本和图片字节。Relay 重启后会恢复运行与操作标识，并与 Harness 原生历史重新对账。对账得到的 Assistant 文本会按当前 turn 的事件顺序保留，不再只返回最后一条 Assistant 消息。活动运行在配置时间内没有持久进展时会进入 needs_attention 并给出 attentionReason: run_stalled；后续一旦出现新进展会自动恢复为 running。

多个本地 MCP Server 进程可以共享一个状态文件；写入会按稳定标识串行化并合并。遗留锁会安全失败，而不会仅因时间过长就被删除。需要运行隔离时，再为不同客户端配置独立的 DSH_RELAY_STATE_FILE。

会话链接

每个运行都会返回如下原生 URL：

http://127.0.0.1:3080/?sessionId=<session-id>

HTTP 200 只能证明 Host 已响应，不能证明超长实时对话已经完成浏览器渲染。随附 Skill 会先调用 open_run，再验证页面中可见的工作区和会话，然后才把链接作为可打开链接交给用户。Harness 成功选择会话后可能把地址栏规范化回 Host 根地址，但选中的会话仍然保持不变。

配置

只接受本机回环 HTTP Host。工作区路径会先经过文件系统解析，再执行包含关系检查。

安全模型

• Harness Relay MCP 不读取或存储 Harness 凭据。
• 现有 Harness Host 仍然是模型、权限、会话、附件和任务执行的权威来源。
• 默认权限 preset 为 read-only。
• 未配置显式 roots 时，以 Harness 工作区注册表作为路由授权真源；配置 roots 后仍执行更严格的本地边界。
• stop_service 不会停止 Harness，也不会删除会话。
• Harness 输出属于证据；最终复核和高风险决策仍由调用方 Agent 负责。
• Relay 无法保证 Codex 或其他 MCP 客户端是否请求批准或触发 auto-review；这仍由客户端、客户端策略和具体操作共同决定。

与 Harness 插件标准的边界

Harness Relay MCP 采用双层兼容结构：harness-relay-mcp 包根入口是遵循 Harness/Cordis 标准的树外内部 bundle，导出 Config/apply(ctx) 并通过 dsh.bundle 与 cordis.patch.yml 安装；外部 Agent 则通过认证 HTTP 或无业务状态的 proxy 使用同一内部 authority。standalone 入口只作为兼容和回滚路径。整个方案不复制或修改 Harness 产品源码。

参见 DeepSeek Harness 官方文档：创建 Harness 插件和发布 bundle。

开发与验证

version.json 是唯一可编辑版本源。构建会先同步 npm 与 Codex 清单，再生成自包含 MCP bundle。

pnpm run test
pnpm run build
pnpm run test:mcp
pnpm run check:package
pnpm pack --dry-run

prepack 会执行严格 TypeScript 检查、构建 bundle，并验证显式发布白名单。敏感目录、运行时产物、敏感文件和符号链接会被拒绝；展开后的默认总字节上限为 8 MiB。发布自动化可通过 DSH_RELAY_PACKAGE_MAX_BYTES 调整门限，但提高上限应经过审查，不能用于掩盖异常包体增长。test:mcp 每次都会先重新构建，再启动 stdio 冒烟测试。

标识

许可证

MIT