智能体实时组网 dpskh/dsh-a2a

@dpskh/a2a — 面向 DeepSeek Harness 的 Agent2Agent 实时网格

dshfind

一个包，一个入口插件。挂载 @dpskh/a2a 0.3 即可获得实时 A2A 网格：hub 宿主（ctx.a2aHub：项目注册表 + 存储域上的不可变消息历史，外加可选的监听 hub 服务器，同时提供实时 WebSocket），网格客户端（ctx.a2aMesh：每个已加入的智能体一个 WebSocket 在线状态，串行注入），a2a_peers / a2a_message / a2a_history 工具，以及 /a2a 命令界面。在线状态是一条活着的 socket；消息是持久记录 —— 在可信私有网络上的实时聊天。

配置

- id: a2a
name: '@dpskh/a2a'
config:
hub: # optional: run the mesh hub server
host: 127.0.0.1
port: 43123 # base bind port
maxPort: 43223 # optional: walk up on EADDRINUSE
mesh: # optional: mesh client
project: main # project to connect to (defaults to main)
agentId: main # local agent this presence belongs to
name: main # roster name; defaults to the agent id
autoConnect: true # connect when the configured agent registers
persistConnections: false # remember each session's last connection and rejoin it
reconnectMs: 500 # initial reconnect delay (doubles to 10 s)

hub 需要可路由的存储后端：挂载 @deepseek-ai/dsh-storage、一个后端（storage-json 或 storage-sqlite），以及 @deepseek-ai/dsh-storage-domain，并把后端路由到 a2a 域。入口插件组合了 hub 宿主服务（ctx.a2aHub）、网格客户端（ctx.a2aMesh），以及 —— 配置了网格时 —— 工具和命令插件（cordis 按它们的 inject 依赖激活）。0.2 中已移除的网格字段（persistBindings、autoRejoin、pollIntervalMs、heartbeatMs、caps）会被忽略，以兼容复制过来的 0.2 配置。

网格

- Hub（ctx.a2aHub）：权威项目注册表和只追加的消息历史（每个项目单调递增的序列号，项目范围内的 messageRef，形如 demo:42）。可选的 hub 服务器通过 HTTP 提供项目/历史路由，并在 /v1/connect 提供实时 WebSocket（协议版本 3）。
- 在线状态：当且仅当一条 WebSocket 存活时，在线状态才存在。已占用的名册名称在每个项目内唯一；同名的后续连接是新的在线状态，不继承任何东西。hub 重启会清空所有在线状态，而消息历史保留。
- 消息：不可变，按 messageId 幂等（重试同一请求体会返回原消息；用同一个 id 发送不同内容会报 MessageIdConflictError）。直接发送在受理时解析收件人当前在线状态，对方不在线就立即失败；项目广播冻结当前在线快照（不含发送者），之后加入的人不会补收。replyTo 在同一项目历史内建立因果关联。文本和附件共享 4 MiB 解码后内容预算；每条消息最多八个附件，以 base64 传输（压缩后更小时用 gzip）。
- 投递：内存中的结果回报给发送者——delivered 表示接收方客户端已注入消息，failed 表示物化或注入出错，disconnected 表示 socket 在确认前已关闭。
- Mesh 客户端（ctx.a2aMesh）：每个已加入的智能体拥有一个连接（项目 + 名册名）。入站消息按 hub 分配的序号串行推送，注入到所属智能体的会话（空闲时作为后续轮次，忙碌时作为普通上下文），附件物化到系统临时目录下。连接仍被需要时，意外断开会自动重连并退避；认领被拒（名称占用、项目未知、协议不匹配）则不再需要该连接。a2a/presence-changed 事件通告本地连接与断开；a2a/delivery 事件通告投递结果。智能体被销毁时自动移除其在线状态。启用 persistConnections 后，每次成功连接都会在 a2a-connections 设置命名空间里记录 agentId → (project, name)，智能体注册时若存在已存记录就重新加入——这是 GUI 路径，会话 id 是动态的，没有配置静态 agentId；显式断开则忘记该记录。每个成员关系还跟踪一份本地会话活动视图（idle / conversing / working，由发送、投递和入站消息推断——活动状态不经过 hub 传输），并在 status() 中暴露，供连接图动画使用；活动状态变化会发出 a2a/change，浏览器据此实时刷新。

工具与命令

- a2a_peers — 列出当前在此项目中的确切名册名。
- a2a_message — 发送给某个当前对等方（target: {type: 'agent', name}），或广播给所有当前对等方（target: {type: 'project'}），可选 replyTo、附件文件路径和幂等 messageId。回复被动到达——发送后绝不要等待或轮询。
- a2a_history — 用 before、after、limit 或 from 查看更早的项目消息（仅过去上下文）。
- /a2a hub、/a2a project create|list|delete、/a2a connect <project> [--as <name>]、/a2a disconnect、/a2a status、/a2a peers、/a2a history [--before <ref>] [--after <ref>] [--limit <n>] [--from <name>]、/a2a help。

Web 协作控件

@dpskh/ui-a2a 每个会话消费一份 Host a2a.snapshot：连接身份、实时名册和项目。本地与远程名册变化会发出 host/a2a-changed；浏览器重新拉取快照，让 Overview 页面、Projects 页面、徽标和快捷面板始终共用同一个状态源。名册是主体；辅助拓扑在不超过六个对端时用轨道布局，超过该阈值改用网格布局，窄屏下隐藏。浏览器从不连接 Hub WebSocket。

信任模型

这套 mesh 假定运行在完全可信的私有网络中：hub 端点不认证调用方，调用方提供的项目与成员身份都按可信声明处理。不要把 hub 暴露到公网或不可信网络。

模型体验

间接进入，途径是 a2a_* 工具、/a2a 命令，以及注入的入站信封：项目成员 id、消息引用、加入结果和已投递消息都可能进入对话。

KV Cache 影响

插件配置和工具定义不变时，前缀保持稳定；项目、名册或历史变化不会改动 schema。

已知限制与后续工作

- 仅支持在线接收方 —— 接收方当前不在线时，直接发送立即失败；没有离线投递，也没有持久化名册。
- 每个客户端只连一个 hub —— mesh 客户端同一时间只连接一个 hub；多 hub 扇出留待后续。
- 投递结果存于内存 —— delivered/failed/disconnected 不持久化；更丰富的投递元数据留待后续。
- 附件落地到临时目录 —— 入站附件落在系统临时目录下；可配置的会话级位置留待后续。