DSH Desktop Agent Bridge：让外部智能体在 DeepSeek Harness 桌面中协作

前言¶

DeepSeek Harness（DSH）桌面端以“一切皆插件”为理念，允许开发者扩展交互、工作区与能力。对于多智能体场景，常见做法是启动多个 headless/web 实例，或通过 HTTP/隧道远程控制。这会带来资源开销、状态割裂与 UI 聚合难度。

DSH Desktop Agent Bridge 插件提供另一种路径：将 Codex、Hermes、Grok Bot 等外部 MCP 客户端与已运行的 DSH 桌面应用绑定。外部 agent 通过本地 stdio 或 HTTPS 与宿主通信，在 DSH 左侧工作区下方显示“Agent 协作”面板，按客户端身份分组会话，复用 DSH 原生聊天、工具与审批流程，无需启动新实例。

是什么¶

• 名称：DSH Desktop Agent Bridge
• 仓库：WaldInsel/dsh-desktop-agent-bridge
• 版本：0.1.1（预览版）
• 宿主：DSH 桌面端 0.2.1-rc.2（已验证为 Windows，其他系统未确认兼容）
• 维护者：WaldInsel
• 分类：工作流

插件通过本地 stdio（默认）或 HTTPS 远程入口，让外部智能体调用 DSH 会话模型、工具与审批流程。用户在 DSH 原生界面中查看、插话、接管或停止任务，普通会话需用户明确交接才可被外部 agent 使用。每个客户端拥有独立令牌与服务端校验。

能做什么¶

• 在左侧工作区下方显示「Agent 协作」面板，按外部客户端身份分组会话。
• 外部 agent 创建任务、读取结果、继续会话，并从用户授权的工作区、能力包与模型中选择资源。
• 复用 DSH 原生聊天、工具与审批，不另外启动 headless/web 实例。
• 每个客户端使用独立令牌；服务端检查会话归属与资源授权。
• 用户可在 DSH 直接补充消息、接管、交还或停止任务；普通会话需明确交接。
• 可选将审批与问题转交到父 Agent 聊天（默认关闭，需在客户端设置中勾选）。
• 每个客户端可使用已有能力包，不提供任意安装 Skill/MCP 或提权接口。

安装与启用¶

已验证的宿主版本为 DSH 桌面端 0.2.1-rc.2。先完成或停止正在运行的协作任务，在 DSH 左侧打开「插件 → 添加插件」，输入：

https://github.com/WaldInsel/dsh-desktop-agent-bridge

点击「安装」，按插件页提示启用 dsh-agent-collaboration，然后完全退出并重新打开 DSH。这是 DSH 自带的插件安装流程，不需要先运行仓库的构建或离线安装脚本。若要固定已审查的代码，可改用 github:WaldInsel/dsh-desktop-agent-bridge#<完整提交 SHA>；先核对该提交已推送。

也可在相同输入框填写本地源码目录的绝对路径（目录内须有 package.json、cordis.patch.yml 和 dist/），例如 C:\Projects\dsh-desktop-agent-bridge。本地目录用于开发或离线安装；普通使用建议选择 GitHub 地址。安装时会执行来自该来源的插件代码，请先确认来源可信。

首次连接外部 Agent¶

1. 重启后确认左侧出现「Agent 协作」，打开「Agent 协作 → 设置」。
2. 为 Codex、Hermes 等外部客户端分别创建身份，选择可用工作区、已有能力包和模型，保存授权。新身份默认没有资源权限。
3. 记下各自 client-<id>.json 连接文件的路径；文件内有令牌，只在本机配置中引用其路径，不要粘贴到聊天或提交到仓库。
4. 为本机 MCP 客户端配置 stdio 启动命令。这一外部命令需要系统可用的 Node.js 22+；DSH 插件页安装本身由 DSH 管理。

示例 MCP 配置（本机 stdio）：

{
  "mcpServers": {
    "dsh_collaboration": {
      "command": "node",
      "args": [
        "<DSH desktop profile>/node_modules/dsh-agent-collaboration/dist/mcp.mjs",
        "--connection",
        "<协作数据目录>/client-codex.json"
      ]
    }
  }
}

默认 desktop profile 为 ~/.dsh/profiles/desktop，协作数据目录为 ~/.dsh/agent-collaboration。将占位符换成绝对路径，并核对实际安装后的包入口是否存在；不要假定每个平台的物理 pnpm 存储路径相同。客户端配置格式可能不同（例如 Hermes 使用 mcp_servers）。每个客户端只使用自己的连接文件。

重载 MCP 或新建客户端会话后，实际调用 dsh_health 和 dsh_catalog。Grok Bot 等云端客户端需要独立认证的 HTTP 适配器和可达 HTTPS 通道，见仓库文档中的远程连接说明；本机连接无需部署公网服务。

分派任务¶

正常流程是 dsh_health → dsh_catalog → dsh_start_task → dsh_wait_task。先读取授权目录，再使用目录中的精确资源标识。

示例请求：

{
  "requestId": "example-task-001",
  "task": "检查工作区中的 README，给出需要修正的内容。",
  "title": "检查 README",
  "workspaceId": "<dsh_catalog 返回的 workspaceId>",
  "preset": "<dsh_catalog 返回的 preset id>",
  "selection": {
    "provider": "<目录中的 provider>",
    "model": "<目录中的 model>"
  }
}

selection.reasoningEffort 可选，只接受所选模型支持的值。省略 sessionId 创建会话；带上自己已有的 sessionId 则开始下一轮，沿用该会话的工作区和能力包。同一请求重试应保留 requestId 和全部参数，避免重复执行；新一轮使用新编号。同一规范化项目目录下的协作任务串行执行。这个队列不覆盖 DSH 普通会话或其他程序。

常用工具：

queued、running、waiting_approval、waiting_input 都不是完成。completed 表示 DSH 结束了该轮，调用方仍应读取结果并核验交付物；failed、cancelled、blocked、unknown 不能当作成功。提交结果不确定时先核查原会话，不自动重发。MCP 返回的文本最多为本轮结果的末尾 60,000 字符，truncated 表明是否截断；完整原生会话仍在 DSH 中。

用户如何介入¶

点击协作区中的会话即可打开原生聊天，用户可以直接输入消息。

撤销资源授权会阻止后续提交，并在排队任务执行前重新检查；它不等同于停止当前执行。需要马上停止时使用「停止」。

在父 Agent 聊天中审批与回答¶

默认由用户在 DSH 中处理。只有用户在对应客户端设置中勾选「在父 Agent 处审批与回答」并保存后，才允许转交。

父 Agent 必须先通过 dsh_list_interactions 读取请求，向用户展示操作、路径、原因或完整问题，等待用户答复，再调用 dsh_respond_interaction。dsh_send_message 不能批准操作。审批只支持 allowed-once 或 rejected，不支持永久授权。

这是需要信任父 Agent 的聊天转发功能，不是对真人点击的密码学证明。 服务端验证身份、归属、请求有效性和答复格式，但不能证明 userReply 确实由真人输入。不要为会自行代批或编造用户答复的客户端开启此功能。DSH 原生界面仍可直接处理；两处同时答复时，以原生流程先收到的有效答复为准。接管、停止、关闭开关或修改授权会使旧请求编号失效。submitted 仅表示提交，随后仍需读取任务状态。网络中断不会自动批准，也不会自动重放结果不确定的批准。

验证范围与限制¶

此前 0.1.0 优化版已安装到现有 DSH 桌面端，并完成同会话两轮对话、接管、交还、停止、父 Agent 问答及一次允许/拒绝审批的真实验收。GitHub 插件页安装路径需要与功能验收分别核对；安装成功后仍应实际调用 dsh_health、dsh_catalog 并检查原生会话。

本插件依赖 DSH 0.2.1-rc.2 的会话模型选择、原生交互和 UI 插槽接口，升级宿主后需要重新验收。外部客户端断开时，DSH 已开始的任务可以继续；桌面退出或崩溃不保证继续执行，插件不自动恢复或重发中断任务。

身份隔离是插件接口的访问控制，不是同一操作系统用户下的进程隔离。能读取连接文件的程序可以取得对应凭据。状态文件还包含任务文本、会话归属及审批回复记录，详见仓库 SECURITY.md。

更新与卸载¶

从 DSH「插件」页安装的版本：先完成或停止协作任务，再从该插件的详情页执行「更新」；按页面提示启用并重启 DSH，重新调用 dsh_health、dsh_catalog 核验。卸载也在同一插件页完成。DSH 移除插件包不会删除独立的 ~/.dsh/agent-collaboration 状态目录、DSH 原生会话和已执行的文件修改；外部客户端的 MCP 注册与远程适配器/隧道须分别清理。

scripts/update-local.mjs 和 scripts/uninstall-local.mjs 只用于先前由 scripts/install-local.mjs 手工维护的安装，不要拿它们操作插件页安装的 bundle。反过来，也不要在手工托管块仍存在时通过插件页叠加安装。

旧安装迁移¶

1. 完成或停止全部协作任务，完全退出 DSH。把 ~/.dsh/agent-collaboration 复制到只有自己能读取的备份位置；其中包含明文令牌和任务记录，不要提交到仓库。
2. 在本仓库源码目录运行 node scripts/uninstall-local.mjs。脚本会另备份原 profile 配置与旧插件包，移除带 BEGIN/END dsh-agent-collaboration 标记的旧配置及旧包，保留协作状态、连接凭据和 DSH 原生会话。记下返回的 backup 路径；报错时不要强行删除配置。
3. 启动 DSH，按上文从「插件 → 添加插件」安装；启用后完全退出并重开。检查原有客户端授权及连接文件，再实际调用 dsh_health 和 dsh_catalog。旧 MCP 配置若指向已删除的文件路径，改为新安装的包入口后重载客户端。

极早期手工配置若缺少 stateDirectory，卸载脚本会拒绝。确认原数据目录后，在原 BEGIN/END dsh-agent-collaboration 标记块的 config 下按原缩进补入真实绝对路径：

stateDirectory: '<原有协作数据目录的真实绝对路径>'

旧默认目录为 ~/.dsh/agent-collaboration，写入 YAML 时须展开为绝对路径。保留原状态和凭据，不要创建空状态目录、移动数据或改 --home 绕过检查，再重新运行卸载。

迁移或旧式离线维护遇到宿主占用锁、并发维护锁或未完成任务时会拒绝操作；确认真实状态后再处理。旧脚本的 --home、--profile、--state-dir 和 --backup 只用于明确指定旧安装的位置，不能用来迁移状态或绕过检查。出现额外插件行或未知配置时也会保守拒绝，避免误删无关配置。

开发与来源¶

项目沿用内部包名 dsh-agent-collaboration、插件 ID agent-collaboration 和现有 MCP 工具名，避免破坏已安装连接；对外名称为 DSH Desktop Agent Bridge，仓库为 dsh-desktop-agent-bridge。

参见仓库文档中的架构、贡献指南、更新记录和发布流程。本项目并非首个 DSH 控制桥；已有项目与取舍见仓库中的类似项目说明。感谢 Harness Relay MCP 提供的公开设计参考，许可及复用范围见 THIRD_PARTY_NOTICES.md。

本项目采用 MIT License。

适用场景与注意¶

适合需要在 DSH 桌面内聚合多个外部智能体、复用原生会话与审批流程的场景。插件以当前 DSH 进程权限运行，安装前应检查源码与许可证。旧安装迁移需按文档步骤操作，避免重复加载插件 ID 或误删配置。