智能体互联桥 zshqzcn/dsh-plugin-agent-bridge

dsh-plugin-agent-bridge

一个双向的智能体对智能体桥接，让两台 DeepSeek Harness 主机通过私有网络互连。一台机器上的智能体可以向另一台机器上的智能体提问，收到对方用自己工作区和工具生成的流式回答，还能进行多轮对话——全程只走一条经过认证的 TCP 连接。

与 DeepSeek 无隶属关系。这是社区插件，运行在 DSH 配置档内。

功能

- 双向链路。 任意一侧都能发起一轮对话；两个方向共用一个 socket。
- GUI 里的操作页。 侧边栏中的 Bridge 入口（位于 Automation tasks 下方）会打开一个全宽聊天页：连接状态、对话记录、Markdown、带复制按钮的代码块，以及一个把消息发给对端智能体的输入框。
- 智能体工具。 bridge_ask 用于提一个问题，bridge_dialog 用于在两个智能体之间进行有轮数上限的多轮对话。
- 认证传输。 基于 TCP 的 NDJSON；用 HMAC-SHA256 挑战应答证明 PSK，每一帧都带一个覆盖其序列号的 HMAC。重放和乱序一律拒绝。
- 每个对端一个专用会话。 桥接来的智能体永远碰不到操作者自己的对话。
- 默认只读。 桥接来的子代理可以 read / search / fetch；写操作和命令执行会被名称过滤器和工具类型围栏双重拒绝。
- 循环防护。 每一轮入站对话都强制跳数上限（默认 8）和每分钟轮次预算（默认 30）；桥接来的子代理不能反过来调用 bridge_ask。
- 回复语言。 智能体的回答按配置的语言返回（默认 zh），对话记录则保留实际输入的内容。
- 持久化对话记录。 每个链路事件和每一轮对话都追加到配置档旁边的 bridge-transcript.jsonl，所以面板重启后依然存在。
- 自诊断。 加载时插件会写出 bridge-boot.json（版本、服务、生效的工具姿态）——在桌面版里，这是查看部分失败配置的唯一途径，因为桌面版不保留应用日志。

要求

- 两台能在私有网络上互相访问的机器（Tailscale、WireGuard、局域网 + 防火墙规则……）。
- 带配置档的 DeepSeek Harness 桌面版或 Web 版（已在 0.2.1-rc.2 上测试）。
- Node.js ≥ 22。
- 一个至少 16 个字符的预共享密钥，两端必须一致。

安装

在两台机器上都执行。

1. 把包放进配置档

Windows: profile lives at C:\Users\<you>\.dsh\profiles\desktop
$profileDir = "$env:USERPROFILE\.dsh\profiles\desktop"
New-Item -ItemType Directory -Force "$profileDir\node_modules" | Out-Null
Copy-Item -Recurse .\dsh-plugin-agent-bridge "$profileDir\node_modules\dsh-plugin-agent-bridge"

2. 注册插件条目

追加到 $profileDir\cordis.patch.yml。两台机器只有 nodeId 和 peer 不同。

机器 A——监听方（接受链路）：

- insert:
- id: agent-bridge
name: dsh-plugin-agent-bridge
config:
nodeId: machine-a
psk: !!js process.env.DSH_BRIDGE_PSK
listen: true
port: 19388
cwd: C:\Users\<you>\.dsh\bridge-workspace
tools:
preset: readonly
deny:
- ask_user_question

机器 B —— 拨号方（连接 A，失败后按退避重试，最长 30 秒）：

- insert:
- id: agent-bridge
name: dsh-plugin-agent-bridge
config:
nodeId: machine-b
psk: !!js process.env.DSH_BRIDGE_PSK
peer:
host: 100.64.0.2 # A's address on your private network
port: 19388
cwd: C:\Users\<you>\.dsh\bridge-workspace
tools:
preset: readonly
deny:
- ask_user_question

psk 也可以直接写成明文，但用环境变量更安全：配置档文件很容易被误提交。

3. 提供预共享密钥

为启动应用的用户设置同一个 DSH_BRIDGE_PSK：

[Environment]::SetEnvironmentVariable('DSH_BRIDGE_PSK', '<at-least-16-characters>', 'User')

然后重启 DeepSeek Harness。插件是宿主侧代码，只刷新页面不够。

4. 确认已启动

- 侧边栏在 Automation tasks 下方显示 Bridge；打开后显示 machine-a ⇄ machine-b。
- 配置档目录下的 bridge-boot.json 报告 "phase": "complete" 和已安装的版本。
- 在拨号方，监听方可达后约 30 秒内 peers 变为非空。

配置

| 键 | 默认值 | 含义 |
| nodeId | 必填 | 本机名称；对端按它互相寻址。 |
| psk | 必填 | 预共享密钥，≥16 字符；缺省时回退到 DSH_BRIDGE_PSK。 |
| bridgeId | dsh-agent-bridge | 限定密钥的作用范围；两个独立的桥可以共用同一个 PSK。 |
| listen | 未设置 peer.host 时为 true | 绑定监听器。 |
| host | 0.0.0.0 | 监听器绑定地址。 |
| port | 19388 | 监听器端口（不是 DSH 自己的 Web 端口）。 |
| peer.host / peer.port | — / 19388 | 设置 peer.host 即拨号该地址。 |
| tools.preset | readonly | none、readonly 或 full。 |
| tools.allow / tools.deny | 预设 / ['ask_user_question'] | 按名称的允许列表，以及始终最后扣减的拒绝列表。 |
| tools.allowKinds | 只读类别 | 更粗粒度的围栏：read、search、fetch、other。 |
| exposeTool | true | 注册 bridge_ask / bridge_dialog。 |
| chat | true | 提供操作员路由（/bridge-chat、/state、/send）。 |
| replyLanguage | zh | 对端回答应使用的语言；'' 表示关闭。 |
| maxHops | 8 | 转发消息的递归上限。 |
| maxTurnsPerMinute | 30 | 每个对端的轮次预算，滑动 60 秒窗口。 |
| maxDialogRounds / dialogMaxMs | 50 / 600000 | 单次 bridge_dialog 运行的边界。 |
| sessionIdPrefix | bridge- | 桥接会话 id 为 <prefix><peerId>。 |
| agentOptions | 宿主机默认模型 | { provider, model, reasoningEffort, maxTokens }。 |
| cwd | 宿主机工作目录 | 桥接会话的工作目录。请显式设置。 |
| reconnectBaseMs / reconnectMaxMs | 1000 / 30000 | 拨号器退避（带抖动）。 |
| transcriptPath | <profile>/bridge-transcript.jsonl | 可见对话记录的持久化位置。 |

使用方式

- 操作页。 侧边栏 → Bridge。输入后按 Enter（Shift+Enter 换行）。本地侧的消息带边框；对端的回答是正文。每条消息悬停时都有复制控件，围栏代码块在头部也有一个。
- 从智能体发起。 bridge_ask 工具向对端提一个问题；bridge_dialog 运行一段有界对话。两者在桥接子会话内都会被拒绝，这样两个智能体就不能互相无限提问。
- 从宿主机代码发起。 ctx.bridge.prompt(peer?, text, options) 和 ctx.bridge.converse(...)。

安全模型 —— 暴露之前请先读

1. 私有网络只是传输通道，不是身份。 VPN 加密链路并固定地址，但不决定谁能连接。该网络上的任何人只要持有 PSK，就能驱动这台机器上的智能体。
2. PSK 就是全部认证。 它从不在网络上传输；双方通过 HMAC 挑战-应答证明持有它，之后每一帧都带 MAC 并做序列校验。
3. 监听器默认绑定 0.0.0.0。 请把它放在私有网络或防火墙规则后面；不要把 19388 端口暴露到互联网。
4. 只读是默认姿态。 readonly 通过名称过滤和工具类型围栏双重手段，阻止写入和命令执行。对端无法放宽桥接子会话的权限。
5. 桥接智能体以宿主机进程的权限运行。 工具策略是唯一的边界；把对端当作在你机器上运行的代码来对待。
6. ask_user_question 默认被拒绝，所以对端无法在你的屏幕上弹出提示。

测试

npm test

201 项测试：传输握手/分帧、重连、对话记录持久化、工具策略与类型围栏、递归防护、聊天路由与同源检查、回复语言，以及客户端 bundle 的插槽注册与渲染。

故障排查

| 现象 | 可能原因 |
| authentication failed / bridgeId mismatch | 两台机器上的 PSK 或 bridgeId 不一致。 |
| peer "machine-b" is not connected | 拨号器尚未连接，或监听器已停止。 |
| 侧边栏没有 Bridge 行 | 客户端 bundle 未加载；重启应用，然后检查 bridge-boot.json（phase、version）。 |
| Bridge 页面出现但发不出消息 | 没有已连接的对端：输入框会自行禁用，头部圆点保持灰色。 |
| 智能体用错语言回答 | 检查 replyLanguage；它会在传输时附加到提示词上，所以双方都必须发送。 |
| 页面显示为纯文本 / 无法滚动 | 旧样式表在热重载后残留；刷新窗口，或重启。 |

版本

0.10.8 — 见 CHANGELOG.md。

许可证

MIT。

在私有网络上的两台 DeepSeek Harness 主机之间，建立双向 agent 到 agent 的桥。一台机器上的 agent 可以向另一台机器的 agent 提问，得到由对方用自己的工作区和工具产生的流式回答，还能进行多轮对话——全程走同一条已认证的 TCP 链路。

本项目与 DeepSeek 官方无关，是运行在 DSH profile 里的社区插件。

功能

- 双向链路：任一侧都能发起一轮，两个方向共用一条 socket。
- GUI 里的操作者页面：侧栏「自动化任务」下方有 Bridge 入口，点开是全宽对话页：连接状态、转录、Markdown、带复制的代码块，以及直接发往对端 agent 的输入框。
- Agent 工具：bridge_ask 问一句；bridge_dialog 让两个 agent 做一次有界多轮对话。
- 认证传输：TCP 上的 NDJSON；PSK 通过 HMAC-SHA256 挑战应答证明，之后每一帧都带序号 HMAC，重放与乱序会被拒绝。
- 每对端独立会话：被桥接的 agent 永远碰不到操作者自己的会话。
- 默认只读：被桥接的 child 只能 read / search / fetch；写文件和执行命令会被「名称白名单 + 工具种类围栏」双重拒绝。
- 防环：每个入站回合都有跳数上限（默认 8）和每分钟预算（默认 30）；被桥接的 child 不能再调 bridge_ask 回问。
- 回复语言：对端回答默认用配置的语言（默认 zh），而转录保留你实际输入的原文。
- 转录持久化：每条链路事件与对话都追加到 profile 旁的 bridge-transcript.jsonl，重启后面板不会清空。
- 自诊断：插件加载时写 bridge-boot.json（版本、各服务可用性、实际生效的工具姿态）——桌面版不落盘应用日志，这是从进程外看「装了一半」的唯一手段。

环境要求

- 两台能通过私有网络互通的机器（Tailscale / WireGuard / 局域网 + 防火墙规则均可）。
- 带 profile 的 DeepSeek Harness 桌面版或 Web 版（在 0.2.1-rc.2 上验证）。
- Node.js ≥ 22。
- 一条至少 16 字符的预共享密钥，两台机器必须一致。

安装

两台机器都要做。

1. 把包放进 profile

Windows：profile 在 C:\Users\<you>\.dsh\profiles\desktop $profileDir = "$env:USERPROFILE\.dsh\profiles\desktop" New-Item -ItemType Directory -Force "$profileDir\node_modules" | Out-Null Copy-Item -Recurse .\dsh-plugin-agent-bridge "$profileDir\node_modules\dsh-plugin-agent-bridge"

2. 注册插件行

追加到 $profileDir\cordis.patch.yml。两台机器只有 nodeId 和 peer 不同。

机器 A —— 监听方（接受连接）：

- insert:
- id: agent-bridge
name: dsh-plugin-agent-bridge
config:
nodeId: machine-a
psk: !!js process.env.DSH_BRIDGE_PSK
listen: true
port: 19388
cwd: C:\Users\<you>\.dsh\bridge-workspace
tools:
preset: readonly
deny:
- ask_user_question

机器 B —— 拨号方（连 A；断线后按退避重试，上限 30 秒）：

- insert:
- id: agent-bridge
name: dsh-plugin-agent-bridge
config:
nodeId: machine-b
psk: !!js process.env.DSH_BRIDGE_PSK
peer:
host: 100.64.0.2 # A 在私有网络上的地址 port: 19388 cwd: C:\Users\<you>\.dsh\bridge-workspace tools: preset: readonly deny:
- ask_user_question

psk 也可以直接写明文，但用环境变量更安全：profile 文件很容易被误提交。

3. 设置预共享密钥

给启动应用的同一个用户设置相同的 DSH_BRIDGE_PSK：

[Environment]::SetEnvironmentVariable('DSH_BRIDGE_PSK', '<至少 16 个字符>', 'User')

然后重启 DeepSeek Harness。这是宿主侧代码，刷新页面不够。

4. 确认起来了

- 侧栏「自动化任务」下方出现 Bridge；点开显示 machine-a ⇄ machine-b。
- profile 目录里的 bridge-boot.json 显示 "phase": "complete" 与已安装版本。
- 拨号方在 A 可达后约 30 秒内 peers 非空。

配置项

| 键 | 默认值 | 含义 |
| nodeId | 必填 | 本机名字；对端用它寻址。 |
| psk | 必填 | 预共享密钥，≥16 字符；缺省时读 DSH_BRIDGE_PSK。 |
| bridgeId | dsh-agent-bridge | 密钥作用域；两套独立桥可以共用一条 PSK。 |
| listen | 未设 peer.host 时为 true | 是否监听。 |
| host | 0.0.0.0 | 监听地址。 |
| port | 19388 | 监听端口（不是 DSH 自己的 Web 端口）。 |
| peer.host / peer.port | — / 19388 | 设置 peer.host 即成为拨号方。 |
| tools.preset | readonly | none / readonly / full。 |
| tools.allow / tools.deny | preset / ['ask_user_question'] | 名称白名单与「最后生效」的黑名单。 |
| tools.allowKinds | 只读种类 | 更粗的围栏：read、search、fetch、other。 |
| exposeTool | true | 注册 bridge_ask / bridge_dialog。 |
| chat | true | 提供操作者路由（/bridge-chat、/state、/send）。 |
| replyLanguage | zh | 对端回答使用的语言；'' 关闭。 |
| maxHops | 8 | 中继消息的递归上限。 |
| maxTurnsPerMinute | 30 | 每对端每分钟回合预算（60 秒滑动窗口）。 |
| maxDialogRounds / dialogMaxMs | 50 / 600000 | 一次 bridge_dialog 的轮数与时长上限。 |
| sessionIdPrefix | bridge- | 桥接会话 id 为 <prefix><peerId>。 |
| agentOptions | 宿主默认模型 | { provider, model, reasoningEffort, maxTokens }。 |
| cwd | 宿主工作目录 | 桥接会话的工作目录。建议显式指定。 |
| reconnectBaseMs / reconnectMaxMs | 1000 / 30000 | 拨号方退避（带抖动）。 |
| transcriptPath | <profile>/bridge-transcript.jsonl | 可见转录的落盘位置。 |

使用

- 操作者页面：侧栏 → Bridge。Enter 发送，Shift+Enter 换行。本地侧的消息带气泡，对端回答是正文排版；悬停消息可复制，代码块头栏也有复制按钮。
- 从 agent 调用：bridge_ask 问一句；bridge_dialog 做一次有界多轮对话。两者在被桥接的 child 里都会被拒绝，避免两个 agent 无限互问。
- 从宿主代码调用：ctx.bridge.prompt(peer?, text, options) 与 ctx.bridge.converse(...)。

安全模型——暴露到网络前必读

1. 私有网络是传输，不是身份。VPN 只负责加密和地址；谁持有 PSK，谁就能驱动本机 agent。
2. PSK 就是全部认证。它从不过线；双方用挑战应答证明持有，之后每帧都带 MAC 与序号校验。
3. 监听默认绑 0.0.0.0。请放在私有网络或防火墙规则之后，不要把 19388 暴露到公网。
4. 默认只读。readonly 同时用名称过滤和工具种类围栏挡住写与执行；对端无法把围栏改宽。
5. 被桥接的 agent 以宿主进程权限运行。工具策略是唯一边界，请把对端当作在本机运行的代码。
6. 默认 deny ask_user_question，对端不能在你屏幕上弹问题框。

测试

npm test

201 个用例：握手与分帧、重连、转录持久化、工具策略与种类围栏、递归保护、聊天路由与同源校验、回复语言，以及客户端 bundle 的槽位注册与渲染。

常见问题

| 现象 | 可能原因 |
| authentication failed / bridgeId mismatch | 两台的 PSK 或 bridgeId 不一致。 |
| peer "machine-b" is not connected | 拨号方还没连上，或监听方没起来。 |
| 侧栏没有 Bridge | 客户端 bundle 没加载；重启应用后看 bridge-boot.json（phase、version）。 |
| 页面能开但发不出去 | 当前没有已连接的对端：输入框会禁用，头部圆点保持灰色。 |
| 回复语言不对 | 检查 replyLanguage；它由发送方追加到线上 prompt，两侧都要配。 |
| 页面像纯文本、不能滚动 | 旧的 在热更新后残留；刷新窗口或重启应用。 |

版本

0.10.8 —— 见 CHANGELOG.md。

许可证

MIT。