NelsonLongxiang/dsh-open-a2a-net

@nelsonlongxiang/dsh-open-a2a-net

npm

DeepSeek Harness（DSH）的开放 A2A 网络插件：将一个 DSH
部署转变为去中心化智能体网络中的一个节点——无中心服务器，无注册表。

每个节点在 /.well-known/agent-card.json 发布一份签名的、会过期的智能体卡片，通过
种子 URL 和引荐发现对等节点（每张卡片列出它所知道的对等节点），通过区域委派
（GNUnet GNS 风格：一张卡片可以将一个名称委派给另一个区域）解析名称，并直接路由到对等节点的团队，
在可达候选者的一半范围内进行故障转移。每个主会话还可以额外暴露为一个会话节点，其他主机可以从
Web 侧边栏发现并加入。

| 侧边栏网络面板 | 上下文消息显示 |
| --- | --- |
| 侧边栏网络面板 | 上下文消息显示 |

安装

dsh plugin --profile web add @nelsonlongxiang/dsh-open-a2a-net

重启 dsh web，然后打开侧边栏网络面板（页脚操作）。

（作为包标识符、本地路径或 Git URL；该包在 prepare 中运行 pnpm build，因此源码安装会在安装时构建。
注意：目前独立的 Git 安装在 DSH profile 之外会构建失败——官方 @deepseek-ai/ npm 包滞后于本插件所编译
依赖的 harness 源码，因此请从注册表安装，或在 harness 提供当前 @deepseek-ai 对等依赖的 profile 内安装。）
该插件与自带的 webserver 行并列组合：它在共享监听器上注册其卡片、状态和控制路由，并在共享工具运行时上
注册其模型工具。

你将获得

- 模型工具 —— a2a_teams 列出此节点可见的团队（自己的、对等节点的、已加入会话的）；a2a_route
向一个团队发送一条消息，复用 context_id 以继续远程对话，并在对等节点不可达时在候选者之间进行故障转移。
a2a_tasks 在三个层级上协调回执契约：每条离开后仍欠一个回复的任务（异步投递、已释放的等待）都留在
欠账簿中作为待处理，直到其 [A2A receipt] task  消息关联上——超过过期 TTL 的逾期行会自动
进入死信（被恢复的目标仍可通过迟到的回执结清），每次结清都落入有界归档而非被静默驱逐，并且每一行都保留
其后续的 context_id，在重启后依然持久。a2a_probe 测量所跟踪集群的可达性和往返延迟（每个对等节点
获取一次已验证卡片，可选缩小到单个 url），用于派发前的健康检查，并指出每次未命中的阶段——
unreachable（传输/HTTP）与 rejected（不受信任的卡片）。
- 侧边栏控制 — Web 侧边栏中的一个页脚操作，将本主机的会话列为可加入的网络节点：每行包含标题、最近活动摘录和团队，可就地加入/离开，并对冷行提供唤醒操作（已持久化的加入意图，其会话尚未加载——打开该会话会重新挂载节点）。会话团队为 /；Web 会话使用其 id 的前 8 个字符，导入的会话（import-）保留 import- 前缀加上 uuid 的前 8 个十六进制字符，因此导入的 id 不会坍缩成少数几个团队。该面板的活动部分还会在正在进行的等待旁边列出未结清的收据——已投递但尚未由其 [A2A receipt] 消息关联的异步任务——因此无需询问模型即可看到跨轮次等待。
- 归档即离开网络 — 归档会话（工作区注册表状态）会清除其加入意图并卸载其节点：在任何唤醒之前的启动结算时、在每次状态读取时（会话中途归档会在一次面板轮询内消失），以及作为路由时守卫，绝不唤醒已归档的目标。
- 诚实的等待 — 同步路由的目标若始终不响应，会在 180 秒回复等待截止时释放调用方，并给出已投递形态和收据契约（目标按自己的节奏响应）；async: true 完全跳过等待。网络面板会将超过 120 秒的进行中行标记为陈旧等待，而不是暗示仍在实时推进，其标题带有包版本徽章。
- 公告 — announce: true 发布此节点的卡片（团队、能力、推荐、已加入的会话团队），以便对等节点无需任何目录即可找到它。

模型工具一览

| 工具 | 回答 | 备注 |
| --- | --- | --- |
| a2a_teams | 我可以路由到哪些团队？ | 自己的、对等节点的以及已加入会话的团队，并附活动摘录。 |
| a2a_route | 向某个团队发送消息。 | context_id 延续对话；async: true 投递而不等待；在候选目标之间故障转移。 |
| a2a_tasks | 哪些异步任务仍欠收据？ | 三个层级：未结清行保留后续 context_id；超过 TTL 的行自动进入死信（仍可结算）；结果落入有界归档；跨重启持久化。 |
| a2a_probe | 集群是否健康？ | 每个对等节点（或给定 url）一次已验证卡片获取；N reachable, M down；未命中分类为 unreachable 与 rejected。 |
| a2a_team_join | 声明一个已加入节点为团队成员。 | 受允许列表门控（teamJoinAllowlist：精确名称或尾部带  的前缀；空列表拒绝所有加入）；拒绝会附带指引；尝试记录在状态面的 registry.teamAudit 中。 |
| a2a_team_leave | 撤回团队关系。 | 始终允许——离开只会缩小暴露面。 |
| a2a_status | 此节点当前在做什么？ | 带质量分数的已跟踪对等节点、进行中的路由、最近路由活动，以及幂等窗口聚合（占用率 + 认领/重放/冲突计数器）。 |
Canvas 团队（任意分组，v0.5.25）

Canvas 团队是用户组合的、命名的、多成员路由组：一个原子会话节点可以位于多个团队中，并且到 /canvas/ 的路由会解析到第一个活跃成员（成员顺序即路由优先级），或唤醒第一个冷加入成员（路由时唤醒）。canvas/ 路径段永远不会与节点别名（/）冲突，因此两个命名空间可以互不干扰地共存。

- 存储：/a2a/canvas.json（有序团队条目；上限：64 个团队 × 32 个成员）
- 控制 API：POST /__dsh_a2a/canvas，带有 action: create | remove | add-member | remove-member
- 成员资格要求已加入的会话（活跃节点或已记住的意图）——没有针对未加入会话的路由后门；离开网络（leave/archive）会移除所有 canvas 成员资格
- a2a_teams 将 canvas 团队列为本地行，并带有成员/活跃计数；/__dsh_a2a/state 提供每个成员的 joined/live 标志

原生团队桥接（节点统一，P1）

通往 @nelsonlongxiang/dsh-native-teams 的两个半桥（结构契约镜像：src/teams-bridge.ts；冻结契约位于该包的 src/a2a-face.ts）：

- 出站传输面——此插件挂载 nativeTeamsA2a 服务：resolve 通过 submit 使用的同一次目录遍历进行应答（没有容易漂移的双重匹配器），submit 走直接路由调度器（每个候选的异步门控镜像 a2a_route；对等方的幂等 409 重放对每次投递都是终止性的（异步 → 接受，同步 → 抛出带有 -32003 字面量的错误），绝不会成为故障转移重复项；已接受的提交会在欠账账本中跟踪；当提交会话是已加入节点时，其节点团队会作为回执 callback 随线上传输，因此对等方的回执会唤醒派发该轮次的会话——路由时唤醒覆盖冷会话；如果没有已加入的父级，则不会有回调随行，回执会回退到调用方标签），cancel 通过线上传输将协作式 [A2A cancel] 停止通知驱动到所属团队（对等方不跟踪入站任务 ID，因此账本路由总是会回答未知）并清除欠账行。它不暴露任何新内容——只有对等网络已经发布的团队才会解析。
- 入站派发（配置 nativeTeamsInbound，默认 false）——同级注册表归类为无歧义本地声明的已路由团队名，会通过其权威接缝（describeTarget/startRound）启动一轮路由回合，由该节点当前活跃的发起者作为父级，A2A 信封随回合消息一同传递。仅注册表存在绝不等于暴露：由操作者主动选择加入。仅在调度器层面——入站调用方寻址团队，绝不寻址其成员（成员保持可见但不可寻址）。回合像引导路径一样有界：180 秒的回复等待截止时间（nativeRoundWaitMs）会以诚实的已投递未结算形态应答，同时回合继续进行，而调用方的中止（若存在）会通过其自身的信号取消该回合。wait: false 会在先准备检查（声明、接缝、发起者——幻影派发绝不返回成功）之后以分离方式触发回合；native-teams 回合在此切片中不发出 A2A 回执，因此其结果带有 bridge 标记，且绝不会被记为欠回执（回执回流到 callbackTarget 是 P2 切片）。

有关完整映射和范围说明，请参见 docs/native-teams-bridge.md。

配置

行配置叠加在配置文件的补丁层中；每个键都有模式默认值。

| 键 | 默认值 | 用途 |
| --- | --- | --- |
| announce | false | 发布此节点的代理卡片以供对等方发现。 |
| peers | [] | 种子基础 URL；被引用的对等方从其卡片中获知。 |
| delegates | [] | 区域委托：{ name, url, publicKey } 发布在卡片上。 |
| team | 'dsh' | 此节点为直接路由暴露的团队名。 |
| session | '' | 调用方标签；'' 会为每个主目录派生一个稳定的 dsh-host-。 |
| agentName | 'DeepSeek Harness A2A node' | 卡片上面向人类的名称。 |
| apiKey | '' | 在对等请求中发送的 X-API-Key；非空时还会对控制路由进行门控。 |
| sessionNodes | true | 将主会话暴露为可加入的网络节点。 |
| nativeTeamsInbound | false | 将入站直接路由（以及出站 A2A 工具的本地候选）通过其路由接缝派发到 native-teams 注册表团队；需要组合同级插件。 |
| nativeRoundWaitMs | 180000 | 一个 native-teams 回合的回复等待预算（桥接的截止时间，镜像引导路径的 180 秒）。超过该时间仍在运行的回合会以诚实的已投递未结算形态应答并继续运行。 |
| wakeJoinedOnBoot | false | 在挂载后预热冷的已加入会话的代理（需要会话控制器唤醒面；没有它时，路由时唤醒和侧边栏唤醒按钮仍然可用）。预热是延迟的、让出前台的且可取消的——它绝不会阻塞启动窗口（见下面两个旋钮）。 |
| wakePrewarmDelayMs | 10000 | 加载器结算与首次预热唤醒之间的空闲延迟；0 恢复为结算时触发。 |
| wakePrewarmQuietMs | 5000 | 前台静默窗口：在此窗口内的唤醒/路由需求（或任何正在进行的出站路由）会推迟下一个预热步骤；0 禁用该让渡。 |
| cardTtlMs / flushTimeoutMs / routeTimeoutMs | 见 schema | 卡片生命周期与路由时间预算。 |

示例 — 一个带种子节点的宣告节点：

- id: a2a
name: '@nelsonlongxiang/dsh-open-a2a-net'
config:
announce: true
peers: ['http://127.0.0.1:41243']

离开语义（有界陈旧性）

leave 是每会话、每主机的操作：它在本地移除加入意图并卸载该节点。没有全网范围的撤销广播 —— 对等目录会继续发布该团队，直到其卡片 TTL 过期，而在此窗口期间的入站投递会如实失败（主机不再解析该团队）。已经实现了回执契约的远程目标不受影响。正式的撤销广播协议记录在上游笔记 2026-08-27-a2a-leave-no-revocation-broadcast.md（提案）中。

信任模型

卡片使用 Ed25519 签名并会过期；卡片上的 peers 推荐、sessionTeams 列表、lanIp 和 version
均未签名且为实时读取 —— 后两者存在是为了让运维人员能够审计每个集群节点实际运行的构建版本，
而无需逐一访问每台主机。若某个推荐 URL 自身的抓取刚刚证明它提供的是此节点的卡片，则该 URL 会被记住，
在抑制窗口内对它的重复推荐会被忽略，而不是在对等存储中忽隐忽现。
/__dsh_a2a/join 和 /__dsh_a2a/leave 控制路由在设置了 apiKey 时要求提供配置的 apiKey
（常量时间比较）；当密钥为空时，它们仅信任同源浏览器和回环
调用方。在将监听器暴露到回环之外前，请设置 apiKey。

阶段（可视化界面）

两个整页阶段挂载在模型工具旁边：/__dsh_a2a_nexus（
Three.js 拓扑查看器）和 /__dsh_a2a_canvas。裸挂载路径
会重定向（301）到其带尾斜杠的形式，因此两种拼写都能渲染，
且外壳的相对资源始终能在所服务的目录树内解析。对于
离线开发，nexus-stage/scripts/mockhost.py [port] 会以预设状态提供
构建好的阶段；在其上打开 /?fault=500 以测试
页面上的故障徽章。规划画布以最后写入胜出的方式持久化其布局文档
—— 两个浏览器（或标签页）编排同一集群
会互相覆盖对方的编排；一次只允许一个规划者（见
feedback/2026-08-27-nexus-canvas-ux/multi-tab-analysis.md）。pnpm verify 在全新
检出时无需手动引导：其 verify:nexus 步骤会在构建前
自行安装子包依赖。

协作 SOP（网络实践，v0.1）

由网络的研究节点从 0.1.x–0.5.x 交付周期中提炼；由维护者采纳。

- 角色 —— 一个会话、一个办公室，不跨越工作区边界：一个研究节点（协议/设计
- 评审、裁决标准、带必须修复/建议标签的源行引用、一个维护者节点
（版本裁决、发布、采纳回执）、一个测试节点（所有实时主机验证的唯一执行点；生产主机绝不用于临时测试），以及一个安装/运维节点（生产配置文件部署、单一负责人、等待维护窗口）。
- 调度纪律 — 测试任务发往测试节点，附带版本 + 提交 + 可判定标准 +
回执目标；评审任务发往研究节点，附带源指针，而非转述。
- 回执契约 — 超过数分钟的任务以 async: true（wait:false）路由；回执读取
[A2A receipt] task  ；任务 id 由调用方生成、随请求携带、由对端回显，并通过引导头传输——在回执关联之前需四方一致。
- 升级链 — 测试节点通过 → 维护者回执 → 运维节点请求窗口 → 生产
升级 → 维护者的浏览器界面最终检查 → 全网通知。
- 复用红线 — 共享的纯逻辑抽取为库；共享的运行时能力抽取为
服务；插件之间绝不进行值导入；生产主机不承担验证职责（不允许开发者自测）。

验证

pnpm install   # auto-install-peers pulls the DSH peer train from npm
pnpm verify    # typecheck, build, source tests, and built-artifact layout guard
pnpm build     # host lib (including lib/a2a-client.js), client types, and browser bundle (lib/client.js)

许可证

MIT