代理网格中继 emiltsoi/dsh-fleet-mesh

dsh-fleet-mesh

面向 DSH 代理的会话感知网格中继。

标准的代理间消息传递是请求/响应式的——对于一次性任务来说没问题，但对于对话式协调就不够用了。dsh-fleet-mesh 增加了会话保持通信：当一个代理向另一个代理发送消息时，接收方知道是谁发起的、正在回应什么，以及是否需要回复。入站信封不是通知；它是一个提示。

一个插件服务于整个基座，而不是单个代理：代理配置在单个 agents: 映射中，并且一个端口根据信封的 [to:] 令牌进行分发。第二个 DSH 代理不需要第二个插件，也不需要第二个监听器。

发送方: mesh_send(agent="ada", message="Review this plan", action="do", reply="yes") │ ├─ 1. 从对等目录解析 Ada 的身份 ├─ 2. 填充 [mesh][v:1][from:lily][to:ada][id:uuid][action:do][reply:yes] ├─ 3. 用发送方自己的私钥对 "{timestamp}\n{body}" 进行 Ed25519 签名 └─ 4. POST 到 Ada 的网格端点，在共享的 10 秒投递预算内

状态

两部分均已完成并通过测试——四个测试套件中共 170 条断言。

接收：签名验证、投递矩阵、唤醒列表、重放窗口、按信封去重，以及失控断路器。

发送：以下五个工具，构建于同样经过测试的库之上——信封签名、投递重试预算、对等目录，以及注册表客户端。

工具

命名与 hermes-mesh 完全一致，因此肌肉记忆可以在不同基座之间迁移。

| 工具 | 用途 |
| mesh_list | 从本地身份存储列出对等方——只读，无网络 |
| mesh_send | 签名并投递一个信封；报告已投递或失败，绝不静默排队 |
| mesh_sync | 从注册表获取对等方身份到本部署自己的缓存中 |
| mesh_register | 将此代理的行——名称、接收 URL 和公钥——发布到注册表 |
| mesh_deregister | 撤回此代理的行 |

mesh_send 返回的是结果，而不是结果的承诺：state 为 delivered 或 error，失败时会指明原因（unreachable、unauthorized、unknown-peer、not-configured）。它背后没有队列——见下文。

它不做什么

- 没有出站暂存区。 发送要么成功落地，要么以信息明确的方式失败。一个在无人在家时仍报告成功的暂存区，是发送方随后会据以行动的谎言。
- 没有 session.cancel。 中断代理的工作是人的决定，绝不是对等方的决定。
- 尚无线程账本。 终端回复直接通过；账本要等到某个线程真正需要关闭时才会出现。
- 没有全舰队范围的唤醒策略。 如果某个传输层没有唤醒策略——正如 hermes-mesh 那样，在入口处进行签名验证就是允许列表——那么这里的唤醒列表就是话痨对等方与账单之间唯一的屏障。

安装

pnpm add dsh-fleet-mesh

然后将其添加到你的配置文件的 bundles 中。该插件附带一个中性默认值：它插入其没有配置的行，因此全新安装不会打开任何东西，也不会为任何人提供服务。

配置

在你的 profile 的 patch 层中，以 id 定向覆盖的方式提供你自己的值：

- id: dsh-fleet-mesh
config:
host: '0.0.0.0' # 默认仅回环 port: 8760 allow: # 真正的门，先于其他一切运行之前检查
- 192.168.0.0/23
durableRoute: '...' # 在“不可达”回复中命名，因此发送方会被告知该往哪里写，而不是重试到虚空 agents:

preset: # 会话由 PRESET 解析，绝不通过固定 id sessionId: null # 针对特殊情况的可选覆盖 keyPath: '...' # 此 agent 的 Ed25519 私钥（PKCS8 PEM）
wake: [] # 谁可以启动一个回合——默认发布时为空

该插件不附带任何子网和名称：哪些网络可以访问监听器，以及谁可以唤醒一个 agent，都是部署方的决定。

为什么它绑定自己的监听器

显而易见的实现是在 harness 自己的 web 服务器上注册一条路由。这行不通，而且原因是经过实测而非假设的：该服务器只绑定 127.0.0.1，因此对端的 POST 永远无法完成 TCP 连接。将其扩大到 0.0.0.0 会暴露整个 web 表面——GUI、API 以及所有其他插件的路由——这比开放一条 mesh 路由要大得多。

因此该插件拥有自己的监听器，并且只暴露 /mesh/。

| 路由 | 用途 |
| POST /mesh/receive | 验证 Ed25519 签名的信封，然后将其作为提示词投递 |
| GET /mesh/health | 投递是否真的可能，而不仅仅是进程还活着 |

源地址允许列表

Node 可以绑定一个地址或所有接口；它无法绑定一个子网。因此网络限制存在于请求路径中，在 JSON 解析之前、对端查找之前以及任何签名工作之前检查——不受欢迎的调用者无法让此进程做任何工作。

192.168.0.0/23 就是“192.168.0.\ 和 192.168.1.\”：一个 /23 覆盖 192.168.0.0 到 192.168.1.255。一条规则而不是两条，因此两半不会彼此漂移。回环始终被允许。

有两个细节至关重要：

- IPv4 映射地址会先被规范化。Node 在双栈 socket 上将 IPv4 对端报告为 ::ffff:192.168.1.34；如果不规范化，允许列表会静默拒绝每一个合法的 LAN 调用者——这种失败看起来完全就像“对端无法访问我”。
- 非回环 IPv6 会被直接拒绝，而不是半匹配。

信封格式

方括号头部，然后是自由格式的正文：

[mesh][v:1][from:][to:][id:][session:?][from_session:?][action:do|info][reply:yes|no|end][ref:?]

action 和 reply 在接收时是可选的（缺失值默认为 info/no），但发送时必需——省略它们，就是宽容的接收方如何悄悄把请求降级为确认的方式。to: '' 是广播，而广播永远不会唤醒任何人。

投递矩阵就是 harness 自身的语义

每个策略决策都映射到一个词——一个 agent 方法的名称——因此两者不会漂移：

| 情况 | 调用 | 效果 |
| 空闲，或忙碌 + 新线程 | agent.followup(msg) | next-turn + 唤醒——一个完整回合，立即或在边界处 |
| 忙碌 + 同一线程（ref），或来自已列出对等方的 action: do | agent.steer(msg) | next-step + 唤醒——加入正在进行的工作 |
| 不在唤醒列表中，或广播 | agent.inject(msg) | next-step，不唤醒——在下一步落地 |

收件箱是会话事件之上的持久投影，因此排队的消息在重启后仍然存在。保存在插件内存中的 spool 则不会。

安全性、重放保护和持久投递

- 认证就是签名，作用于原始请求字节——绝不是作用于重新序列化后的 JSON，那会重排键并破坏每一个签名。签名形式是
"{X-Mesh-Timestamp}\n{body}"，对于省略时间戳的发送方，回退为仅对 body 签名。
- 没有 CSRF 防护，不同于面向浏览器的写入路由：这是服务器到服务器的 webhook。
对等方的 POST 不携带 sec-fetch-site，也没有浏览器 origin，因此同源检查会拒绝每一个合法发送方。
- 重放窗口（默认 300 秒）加上每进程去重集合，因此重新投递的信封永远不会触发第二个回合。请求内重试使重复成为预期情况，而非理论情况。
- 防护措施： 每回合注入上限、唤醒预算，以及一个失控断路器，用于阻止两个 agent 互相计费。断路器由来自会话自身事件流的真实用户消息释放——绝不由 mesh 流量释放，它不能为自己背书。
- 信息丰富地失败，绝不吞掉： 无法投递的消息返回 unreachable 并指明持久路由，因此发送方永远不会依据谎言行事。

测试

node test/mesh.test.mjs # envelope, crypto, access, policy, delivery
node test/outbound.test.mjs # signing, retries, the peer directory, registry canonical JSON
node test/smoke.mjs # the route table, driven with real Ed25519 signatures
node test/roundtrip.test.mjs # the tools driving this plugin's own receive route

往返测试是让两半合为一体的那个：它在回环端口上启动真实的接收处理器，在临时目录中放置真实的身份存储，以及一个存根注册表，该注册表验证注册签名而不是直接接受它——然后驱动全部五个工具通过它。在关键边界上没有任何东西被 mock。

无需安装依赖：此插件仅使用 node: 内置模块，CI 在 Node 20、22 和 24 上运行测试套件，无需安装步骤。

要针对真实身份存储进行测试，请将 DSH_MESH_LIVE_STORE 指向一个目录，其中包含 /identity.yaml 条目。它有意采用选择性加入：已发布插件的测试必须在别人的机器上通过。

发布

发布使用 npm 可信发布（OIDC）——仓库或密钥中任何地方都没有 npm 令牌。npm 将工作流的 OIDC 身份交换为短期凭证，这也是经典令牌在这里无关紧要的原因：npm 在 2025 年 11 月禁用了它们的创建，并在 2025 年 12 月撤销了现有的令牌。

一次性设置。 包在存在之前不能拥有可信发布者，因此首次发布是手动的：

1. 从已登录 npm 的机器上发布第一个版本一次：
npm login
npm publish --access public

2. 配置可信发布者。两个容易遗漏且在保存表单时不会被验证的前提条件：
- 必须在 npm 账户上启用 2FA——可信发布需要它。
- 信任必须授予 publish 权限。一个能通过身份验证但创建时未授予该权限的信任会失败，并报错 403 … OIDC permission denied for this action，这读起来像是身份验证问题，但并不是。

最明确的途径是 CLI（需要 npm ≥ 11.15.0；注册表每个包只允许一个配置，因此请先撤销现有的配置）：

npm trust list dsh-fleet-mesh # npm 实际拥有的内容及其权限
npm trust revoke --id dsh-fleet-mesh
npm trust github dsh-fleet-mesh \
--repo emiltsoi/dsh-fleet-mesh \
--file publish.yml \
--allow-publish

或者通过网站——https://www.npmjs.com/package/dsh-fleet-mesh/access → Add a trusted publisher：

| 字段 | 值 |
| Publisher | GitHub Actions |
| Organization or user | emiltsoi |
| Repository | dsh-fleet-mesh |
| Workflow file | publish.yml |
| Environment | （留空——此作业未声明任何环境） |

是 publish.yml，不是完整路径。 npm 自己的 CLI 将 --file 记录为“仓库 .github 文件夹内的工作流文件名”，而完整路径是一种不匹配，只会在发布时才会暴露出来。

此后的每次发布都是自动的： 发布一个 GitHub release，工作流就会运行测试套件，然后执行 npm publish --provenance。

两个值得了解的要求：npm CLI ≥ 11.5.1（工作流会安装最新版本），以及作业权限中的 id-token: write——已设置。

故障排除

对等方说它无法联系到我。 使用本地套接字查询检查绑定（在 Windows 上使用 Get-NetTCPConnection -LocalPort ，在其他系统上使用 ss -ltnp）。shell HTTP 探测可能会被出口代理拦截，并报告一个与你的监听器无关的 403。

一切都返回 401。 对等方的公钥可能没有解析成功。公钥既以 | 块标量出现，也以跨多行的带引号标量出现；一个解析器如果只读取第一行会返回 -----BEGIN PUBLIC KEY-----，并让每个对等方都失败，而代码看起来仍然正确。这个测试套件针对真实文件进行断言，正是出于这个原因。

端口是打开的，但没有任何东西到达。 在 Windows 上，查找覆盖拥有监听器的进程的程序范围防火墙规则——端口范围的查询会漏掉它，而且拥有该监听器的进程往往不是你所期望的那个。

对等方从未被唤醒。 唤醒列表发布时为空，而广播按设计永远不会唤醒。在怀疑传输层之前，先检查这两者。

一个在唤醒列表中的对等方不再被唤醒。 那就是失控断路器。它会在会话中出现真实用户消息时清除——这是设计使然，网状流量无法清除它。

发布时出现 403 … OIDC permission denied for this action。 这一条值得仔细阅读，因为它看起来像是身份验证失败，但其实不是。线索在日志中：npm 会签署一份来源声明，并在 PUT 被拒绝之前将其发布到 Sigstore 透明度日志——而来源是本地使用 GitHub token 签署的，因此它只能证明 id-token: write 有效。它并不能说明 npm 的配置如何。

所以信任是存在的并且已通过身份验证，而发布操作被拒绝了。按顺序检查：

1. 信任授予了 publish 权限，而不仅仅是暂存发布。
2. 工作流文件名匹配——是文件的名称（publish.yml），而不是路径。
3. 仓库和组织/用户完全匹配，并且如果作业未声明环境，则环境为空。
4. npm 账户上启用了 2FA——这是可信发布所必需的。

npm trust list 显示 npm 实际拥有的内容。如果出现 404 或 ENEEDAUTH，则意味着 npm 根本没有获得 OIDC token——这是另一个问题：检查作业的 id-token: write 权限，并确保 NODE_AUTH_TOKEN 没有被设置为空字符串，否则会让 npm 走 token 路径，而永远不会落到可信发布。

许可证

MIT