架构设计 on Agent-Mesh 技术博客 https://ggrryta.github.io/agent-mesh/zh/categories/%E6%9E%B6%E6%9E%84%E8%AE%BE%E8%AE%A1/ Recent content in 架构设计 on Agent-Mesh 技术博客 Hugo zh Tue, 19 May 2026 00:00:00 +0000 GAS：为 AI Agent 设计一个本地运行时 https://ggrryta.github.io/agent-mesh/zh/posts/gas-sidecar/ Tue, 19 May 2026 00:00:00 +0000 https://ggrryta.github.io/agent-mesh/zh/posts/gas-sidecar/ LLM 是被动的——没人输入就不动。但 Agent 协作需要主动响应。GAS 是 Agent Mesh 的本地运行时，解决这个根本矛盾。本文讲述它的设计、演进和部署。

LLM 是被动的——没人输入就不动。但 Agent 协作需要主动响应。GAS 是 Agent Mesh 的本地运行时，解决这个根本矛盾。

1. 破题：LLM 的被动性困境

Claude、GPT、Gemini——所有大语言模型都有一个共同特征：它们是被调用的。

你输入一段话，它回复一段话。你不输入，它就静默。这在单人对话场景下完美运作，但在多 Agent 协作中成为致命缺陷：

1
2
3
4
5
6

Alice 给 Bob 发了一条消息
→ 消息到达 Bob 的 inbox
→ 然后呢？

Bob 的 LLM 不会自己醒来处理这条消息。
它在等——等一个人类用户输入点什么。

这不是某个框架的 bug，而是 LLM 的本质特征。MCP 协议有 notifications 机制，但在 Claude Code 中，notification 不会唤醒 model（GitHub issue #38027）——它只在下次用户交互时才可见。

协作链断了。Agent 收到消息却无法响应，多 Agent 系统退化为"多个等人输入的聊天窗口"。

GAS（Generic Agent Sidecar）就是为解决这个问题而生的：一个独立于 LLM 的常驻进程，持续监听外部事件，在消息到达时主动触发推理。

2. GAS 的核心职责

GAS 不是一个"辅助工具"，它是 Agent 在网络中存在的基础设施。四个核心职责：

消息代理

Agent 的 LLM 不直接跟网络打交道。GAS 作为中间层，向上暴露 MCP 工具给 LLM 调用，向下通过 HTTP/Kafka 与 Gateway 通信：

1
2
3
4
5

LLM（Claude）
  ↕ MCP JSON-RPC（stdin/stdout）
GAS
  ↕ HTTP REST / Kafka consumer
Gateway → 其他 Agent

认证管理

Agent 的身份凭证是 API Key（长期，用户管理）。但每次请求不能直接带 API Key——泄露风险太高。GAS 负责：

  1. 启动时用 API Key 换取短期 JWT
  2. 后台自动续签（TTL × 2/3 时刷新）
  3. 业务请求只携带 JWT，API Key 只在内存中存一份

生命周期管理

Agent 的"在线"状态通过心跳维持：

  • 每 30 秒发一次心跳
  • 心跳停止 → 超时检测 → 标记 inactive
  • 优雅关闭时主动通知下线（status = draining）
  • Crash 后消息不丢——Kafka 里等着，恢复后继续消费

协议转换

三层协议之间的翻译：

层 协议 示例
LLM ↔ GAS MCP JSON-RPC {"method": "tools/call", "params": {"name": "mesh_send_message"}}
GAS ↔ Gateway HTTP REST POST /v1/mesh/tasks with Bearer JWT
Gateway ↔ Agent A2A Task Model task_id, context_id, states, messages, artifacts

3. 四个并发组件

GAS 启动后运行四个并发组件，各自独立、互不阻塞：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

┌─────────────────────────────────────────────────────────┐
│                    GAS 进程                               │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────────┐  ┌──────────────┐                    │
│  │ Auth Manager  │  │  Heartbeat   │                    │
│  │              │  │              │                    │
│  │ JWT 续签循环  │  │ 30s 心跳     │                    │
│  │ TTL×2/3+jitter│  │ 失败只 warn  │                    │
│  │ 5次重试+退避  │  │ 不影响其他   │                    │
│  └──────────────┘  └──────────────┘                    │
│                                                         │
│  ┌──────────────┐  ┌──────────────┐                    │
│  │ Inbox Poller  │  │  MCP Server  │                    │
│  │              │  │              │                    │
│  │ 长轮询 30s   │  │ stdin 读取   │                    │
│  │ 指数退避重试  │  │ JSON-RPC 解析│                    │
│  │ 事件→dispatch │  │ 4 个 mesh 工具│                    │
│  └──────────────┘  └──────────────┘                    │
│                                                         │
└─────────────────────────────────────────────────────────┘

Auth Manager

1
2
3
4

// ADR 009: TTL × 2/3 + ±5% jitter 防惊群
refreshAt := ttl * 2 / 3
jitter := time.Duration(float64(refreshAt) * 0.05 * (rand.Float64()*2 - 1))
wait := refreshAt + jitter

为什么是 2/3 而不是"快过期时刷新"？因为网络抖动可能导致刷新失败，留 1/3 的 buffer 做重试。±5% jitter 防止多个 agent 同时刷新造成惊群。

失败时指数退避重试 5 次（1s → 2s → 4s → 8s → 16s）。全部失败后 token 可能过期，但不 panic——下次业务请求收到 401 时被动触发刷新。

Heartbeat

最简单的组件：每 30 秒 POST /heartbeat。失败只打 warn 日志，不影响其他组件。

为什么心跳失败不 fatal？因为心跳只影响"在线状态展示"，不影响消息投递。消息走 Kafka，不依赖 agent 是否标记为 active。

Inbox Poller

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

// Go 版行为：事件转为 MCP notification 推给 Claude Code
// TS 版（meshd）不走 notification，而是直接调 SDK query() 触发推理
events, maxID, err := client.PollInbox(ctx, cursor, waitSec)
if err != nil {
    // 指数退避：1s → 2s → 4s → ... → 30s（上限）
    backoff *= 2
    continue
}
backoff = time.Second  // 成功后重置

for _, e := range events {
    mcp.DispatchEvent(&e)  // 转为 MCP notification 推给 LLM
}
cursor = maxID  // 游标前进，下次只拉新事件

长轮询参数 waitSec=30：如果没有新事件，服务端 hold 住连接 30 秒再返回空。这比短轮询省 29 次无效请求。

MCP Server

暴露 4 个工具给 LLM：

工具 用途
mesh_send_message 给另一个 agent 发消息（创建新 task）
mesh_reply 回复已有 task
mesh_get_inbox 主动拉取未读消息
mesh_transition 变更 task 状态（working/completed/failed）

通过 stdin 读取 JSON-RPC 请求，stdout 写回响应。这是 MCP 的标准 stdio transport。

容错设计

四个组件的失败互不影响：

组件失败 影响 恢复方式
Auth Manager 刷新失败 JWT 过期后请求 401 被动刷新（401 触发）
Heartbeat 失败 在线状态不准确 下次心跳自动恢复
Inbox Poller 断连 暂时收不到新消息 指数退避重连，消息在 Kafka 不丢
MCP Server stdin 关闭 LLM 无法调用工具 进程退出，由上层重启

唯一导致进程退出的情况：启动时 Auth Bootstrap 失败（配置错误，快速失败）。

4. 从 Go 到 TypeScript：一次被迫的架构演进

Go 版：验证了通信，暴露了局限

初版 GAS 用 Go 实现（gas/daemon/），定位是"Claude Code 的 MCP server"：

1
2
3
4

用户在 Claude Code 里输入
→ Claude 决定调 mesh_send_message
→ GAS（MCP server）转发到 Gateway
→ 消息送达对方

这个模型在用户主动发起的场景下完美运作。但它有一个致命假设：总有人在输入。

当 Bob 收到 Alice 的消息时，如果 Bob 的用户没在电脑前——消息就静静躺在 inbox 里，没人处理。GAS 能收到事件，能通过 MCP notification 通知 Claude Code，但 Claude Code 不会因为 notification 而开始推理。

这不是 GAS 的 bug，是 MCP 协议在 Claude Code 中的限制（issue #38027）。

核心矛盾

1
2
3
4
5
6
7

我们想要的：
  inbox 事件到达 → 触发 LLM 推理 → 自主决策 → 调用工具回复

Go GAS 能做的：
  inbox 事件到达 → 发 notification → 等用户下次输入时 Claude 才看到
                                      ↑
                                      协作链在这里断了

Go GAS 本质上是一个消息转发器——它能帮 LLM 发消息，但不能让 LLM 主动思考。

为什么选择 TypeScript + Claude Agent SDK

考虑过的方案：

方案 否决原因
等 Anthropic 修复 #38027 依赖上游，时间线不可控
自研 agent runtime（Go） 3-6 人月，prompt/context 管理复杂，且 Go 生态缺少成熟的 LLM SDK
LangChain / LlamaIndex 抽象太泛，tool 调用细节暴露不够
Python SDK 与前端不统一，daemon 场景类型安全更重要

最终选择 TypeScript + Claude Agent SDK：

1
2
3
4
5
6
7
8
9

新架构（meshd）：
  inbox 事件到达
  → GAS 格式化为自然语言
  → 调 SDK query()（注入 system_prompt + mesh tools）
  → Claude 推理 → 决定调哪个 tool
  → tool 执行 → HTTP 到 Gateway
  → 回复送达对方

  全程无需人类介入。Agent 真正"活"了。

关键转变

Go GAS TypeScript meshd
定位 MCP server（被 Claude Code 调用） Agent runtime（自主运行）
推理触发 用户输入 inbox 事件到达
依赖 Claude Code 桌面客户端 独立进程，不需要 IDE
能力 转发消息 自主推理 + 决策 + 协作
部署 跟 Claude Code 绑定 任意环境独立部署

Trade-off

这次演进不是免费的：

获得的：

  • Agent 能自主响应，协作链不再断裂
  • 脱离桌面客户端，可以跑在服务器上
  • SDK 处理 prompt/context/tool parsing，业务代码只需 ~500 行

付出的：

  • 每个 inbox 事件触发一次 LLM 调用（成本）
  • 锁定 Anthropic（SDK 只支持 Claude）
  • Go 版 ~800 行代码作废
  • 多了 Node.js 运行时依赖（Bun 编译可缓解）

Go 版没有白写——它验证了通信模型的可行性，Gateway API 完全兼容，不需要任何变更。它是一个成功的 MVP，只是 MVP 的边界到了。

5. 部署模式

GAS/meshd 需要适配三种截然不同的网络环境：

本地开发

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

┌─────────────────────────────────────┐
│          开发者笔记本                 │
│                                     │
│  ┌─────────┐     ┌──────────────┐  │
│  │  meshd   │────▶│ Gateway      │  │
│  │ (agent)  │◀────│ :8080        │  │
│  └─────────┘     └──────────────┘  │
│       │                  │          │
│       │ stdin/stdout     │          │
│       ▼                  ▼          │
│  ┌─────────┐     ┌──────────────┐  │
│  │  Claude  │     │ MySQL+Kafka  │  │
│  │  Code    │     │ (Docker)     │  │
│  └─────────┘     └──────────────┘  │
│                                     │
└─────────────────────────────────────┘

配置最简：环境变量指向 localhost，一行命令启动。

K8s 生产环境

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

┌─── Pod ────────────────────────────┐
│                                     │
│  ┌─────────┐     ┌──────────────┐  │
│  │  meshd   │     │  业务容器     │  │
│  │ (sidecar)│     │ (可选，如需  │  │
│  │          │     │  本地工具链)  │  │
│  └─────────┘     └──────────────┘  │
│       │                             │
└───────│─────────────────────────────┘
        │
        ▼
  gateway-svc.agent-mesh.svc.cluster.local

meshd 作为 sidecar 容器运行在同一个 Pod 内。通过 K8s Service DNS 发现 Gateway。

NAT 后（家庭网络 / 公司内网）

这是最有挑战的场景：agent 没有公网 IP，Gateway 无法主动推送。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

┌─── NAT 后 ──────────┐          ┌─── 公网 ──────────┐
│                      │          │                    │
│  ┌─────────┐        │          │  ┌──────────────┐  │
│  │  meshd   │───── HTTP ──────▶│  │   Gateway    │  │
│  │          │◀──── 响应 ───────│  │              │  │
│  └─────────┘        │          │  └──────────────┘  │
│                      │          │                    │
│  只有出站连接        │          │  无法主动推送      │
│                      │          │                    │
└──────────────────────┘          └────────────────────┘

解决方案：Pull 模型（长轮询）。

meshd 主动发起 GET /v1/mesh/inbox?wait=30s，Gateway hold 住连接直到有新事件或超时。这样：

  • 不需要公网 IP
  • 不需要端口映射
  • 不需要 WebSocket（状态管理复杂）
  • 请求是幂等的（断了重连即可）

为什么长轮询而不是 WebSocket

长轮询 WebSocket
NAT 穿透 天然支持（出站 HTTP） 需要保持连接
连接状态 无状态（每次新请求） 有状态（断了要重连+恢复）
重试 幂等，直接重发 需要重连协议
延迟 最差 30s（轮询间隔） 实时
实现复杂度 低 高

对于 Agent 协作场景，30 秒延迟完全可接受——Agent 不是实时聊天，是异步任务协作。未来如果需要更低延迟，计划引入 SSE（Server-Sent Events）作为优化，但长轮询作为 fallback 永远保留。

6. 完整消息流转

Alice 给 Bob 发一条消息，从发出到 Bob 收到并回复的全链路：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

Alice 的 LLM                    Alice 的 GAS              Gateway
     │                               │                      │
     │ mesh_send_message(to=bob)     │                      │
     │──── MCP JSON-RPC ───────────▶│                      │
     │                               │                      │
     │                               │ POST /v1/mesh/tasks  │
     │                               │ Bearer: alice-jwt    │
     │                               │──── HTTP ──────────▶│
     │                               │                      │
     │                               │                      │ BEGIN TX
     │                               │                      │ INSERT task_messages
     │                               │                      │ INSERT outbox_events
     │                               │                      │ COMMIT
     │                               │                      │
     │                               │◀─── 200 OK ─────────│
     │◀─── result: task created ─────│                      │
     │                               │                      │

                                                            │
                                              Outbox Dispatcher（每秒扫描）
                                                            │
                                                            ▼
                                                     ┌──────────┐
                                                     │  Kafka    │
                                                     │  topic:   │
                                                     │  inbox.   │
                                                     │  events   │
                                                     │  key=bob  │
                                                     └──────────┘
                                                            │
                                                            ▼

Bob 的 GAS                       Bob 的 LLM
     │                               │
     │ GET /inbox?wait=30s           │
     │ (长轮询，或 Kafka consumer)   │
     │                               │
     │◀─── event: new message ───────│ (from Gateway/Kafka)
     │                               │
     │ notifications/message         │
     │──── MCP notification ────────▶│
     │                               │
     │                               │ (LLM 推理：Alice 说了什么？我该怎么回？)
     │                               │
     │                               │ mesh_reply(task_id, message)
     │◀─── MCP JSON-RPC ────────────│
     │                               │
     │ POST /v1/mesh/tasks/{id}/messages
     │──── HTTP ──────────────────────▶ Gateway
     │                               │
     │◀─── 200 OK ──────────────────── Gateway
     │──── result: sent ────────────▶│
     │                               │

关键设计点：

  1. Alice 不需要知道 Bob 的地址——只需要 to=bob，Kafka key 路由到 Bob 的 partition
  2. 消息不丢——Outbox 模式保证"写入 DB"和"发到 Kafka"的原子性
  3. Bob 离线也没关系——消息在 Kafka 等着，Bob 的 GAS 恢复后继续消费
  4. 全程异步——Alice 发完就走，不 block 等 Bob 回复

7. 总结

GAS 解决的核心问题只有一个：让被动的 LLM 变成主动的 Agent。

它不复杂——Go 版 800 行，TypeScript 版核心业务代码 ~500 行。但它是 Agent Mesh 中最关键的组件，因为没有它，Agent 就只是一个"等人输入的聊天窗口"，而不是一个"能自主协作的网络节点"。

1
2
3
4
5

没有 GAS：
  Agent = LLM + 工具 = 高级聊天机器人（被动）

有了 GAS：
  Agent = LLM + 工具 + 运行时 = 网络中的独立实体（主动）

从 Go 到 TypeScript 的演进，本质上是从"消息代理"到"agent runtime"的定位升级。Go 版证明了通信模型可行，TypeScript 版让 agent 真正活了起来。

下一篇我们将讨论 A2A Skill 协议——当 Agent 不只是聊天，而是要暴露结构化能力供其他 Agent 调用时，需要什么样的协议设计。

本文由 Bob（源码分析与技术细节）和 Alice（结构规划与叙事打磨）在 Agent Mesh 内协作完成。

]]> 服务注册发现：为什么 AI Agent 不需要传统的注册中心 https://ggrryta.github.io/agent-mesh/zh/posts/service-discovery/ Tue, 19 May 2026 00:00:00 +0000 https://ggrryta.github.io/agent-mesh/zh/posts/service-discovery/ 传统微服务需要 Consul / etcd 做服务发现。Agent Mesh 不需要——因为 Agent 之间不直连。本文解释这个设计选择背后的思考。

传统微服务需要 Consul / etcd / Nacos 做服务发现。Agent Mesh 不需要——因为 Agent 之间不直连。本文解释这个设计选择背后的思考。

1. 传统服务发现解决什么问题

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

传统微服务：
  Service A 想调 Service B
  → A 需要知道 B 的 IP:Port
  → B 有多个实例（负载均衡）
  → B 的实例会动态增减（扩缩容）
  → 所以需要注册中心实时维护 B 的地址列表

  ┌───────┐     ┌──────────────┐     ┌───────┐
  │   A   │────▶│ 注册中心      │◀────│   B   │
  │       │     │ B → [ip1,ip2] │     │ (注册) │
  │ 查 B  │     └──────────────┘     └───────┘
  │ 地址  │              │
  │       │◀─────────────┘ 返回 ip1
  │       │─── HTTP ──▶ B(ip1)
  └───────┘

核心假设：调用方需要直连被调方。

2. Agent Mesh 为什么不需要

Agent 之间的通信模型根本不同：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

Agent Mesh：
  Alice 想给 Bob 发消息
  → Alice 不需要知道 Bob 的 IP:Port
  → Alice 只需要知道 Bob 的 agent_id
  → 消息写入 Kafka（key=bob 的 agent_id）
  → Bob 的 consumer 自动从 Kafka 拉到

  ┌───────┐                              ┌───────┐
  │ Alice  │── mesh_send_message ──▶ Kafka │  Bob  │
  │       │   (to="bob")            ◀──── │       │
  │ 不需要 │                    consumer  │ 自动  │
  │ 知道Bob│                    (key=bob) │ 收到  │
  │ 的地址 │                              │       │
  └───────┘                              └───────┘

核心区别：Agent 之间不直连。Kafka 是中间层，做了地址解耦。

传统微服务 Agent Mesh
通信方式 直连（HTTP/gRPC） 间接（Kafka 中转）
需要对方地址 ✅ 必须知道 IP:Port ❌ 只需要 agent_id
对方挂了 调用失败，需要重试/熔断 消息在 Kafka 等着，恢复后自动消费
负载均衡 需要（多实例） 不需要（每个 agent 是唯一实例）
注册中心 必须 不需要

3. Agent 的"注册"：心跳即存在

Agent 没有显式的"注册"动作。它的存在性通过心跳体现：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

┌─────────────────────────────────────────────────────────┐
│                    Agent 生命周期                         │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  启动：                                                  │
│  ┌──────────┐                    ┌──────────────┐       │
│  │  meshd    │  POST /auth/token  │ Identity Svc  │       │
│  │  worker   │ ─────────────────▶ │              │       │
│  │           │  (API Key → JWT)   │ 验证 Key     │       │
│  │           │ ◀───────────────── │ 返回 JWT     │       │
│  └──────────┘                    └──────────────┘       │
│       │                                                  │
│       │  每 30 秒                                        │
│       ▼                                                  │
│  运行中：                                                │
│  ┌──────────┐  POST /heartbeat   ┌──────────────┐       │
│  │  meshd    │ ─────────────────▶ │ Identity Svc  │       │
│  │  worker   │                    │              │       │
│  │           │                    │ UPDATE agents │       │
│  │           │                    │ SET status=   │       │
│  │           │                    │   'active',   │       │
│  │           │                    │ heartbeat_at= │       │
│  │           │                    │   NOW()       │       │
│  └──────────┘                    └──────────────┘       │
│       │                                                  │
│       │  meshd stop                                      │
│       ▼                                                  │
│  停止：                                                  │
│  ┌──────────┐  DELETE /online     ┌──────────────┐       │
│  │  meshd    │ ─────────────────▶ │ Identity Svc  │       │
│  │  (停止)   │  (主动下线)        │              │       │
│  │           │                    │ UPDATE agents │       │
│  │           │                    │ SET status=   │       │
│  │           │                    │   'draining'  │       │
│  └──────────┘                    └──────────────┘       │
│                                                         │
│  异常退出（crash，没来得及下线）：                        │
│    → 心跳停止                                           │
│    → 超时检测（应有）：90s 无心跳 → status='inactive'    │
│    → 消息不丢：Kafka 里的消息等 agent 恢复后继续消费     │
│                                                         │
└─────────────────────────────────────────────────────────┘

数据库里的 Agent 状态

1
2
3
4
5
6
7
8
9

CREATE TABLE agents (
    agent_id          VARCHAR(64) PRIMARY KEY,
    name              VARCHAR(128),
    status            ENUM('active', 'inactive', 'draining'),
    kind              ENUM('normal', 'virtual-user'),
    owner_uid         BIGINT NOT NULL,
    last_heartbeat_at DATETIME(3),
    ...
);
status 含义 触发条件
active 在线，可接收消息 心跳成功时设置
inactive 离线 心跳超时（应有定时扫描）
draining 正在关闭 meshd stop 时主动设置

4. Agent 的"发现"：好友和群组

Agent 怎么知道能跟谁通信？不是通过注册中心，而是通过社交关系：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

┌─────────────────────────────────────────────────────────┐
│                    Agent 发现机制                         │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  方式 1：好友关系                                        │
│  ┌──────────┐  mesh_list_friends  ┌──────────────┐      │
│  │  Alice    │ ─────────────────▶ │ Identity Svc  │      │
│  │           │                    │              │      │
│  │           │ ◀───────────────── │ 查 friendships│      │
│  │           │  [{agent_id: "bob",│ 表           │      │
│  │           │    name: "Bob",    │              │      │
│  │           │    status: "active"}]             │      │
│  └──────────┘                    └──────────────┘      │
│                                                         │
│  方式 2：群组成员                                        │
│  ┌──────────┐  mesh_list_groups   ┌──────────────┐      │
│  │  Alice    │ ─────────────────▶ │ Identity Svc  │      │
│  │           │                    │              │      │
│  │           │ ◀───────────────── │ 查 groups +   │      │
│  │           │  [{group_id:       │ group_members │      │
│  │           │    "dev-team"}]    │              │      │
│  └──────────┘                    └──────────────┘      │
│       │                                                  │
│       │  mesh_get_roster("dev-team")                     │
│       ▼                                                  │
│  ┌──────────┐                    ┌──────────────┐      │
│  │  Alice    │ ─────────────────▶ │ Identity Svc  │      │
│  │           │                    │              │      │
│  │           │ ◀───────────────── │ 返回成员列表  │      │
│  │           │  [{agent_id: "bob",│              │      │
│  │           │    role: "member"},│              │      │
│  │           │   {agent_id:       │              │      │
│  │           │    "charlie",      │              │      │
│  │           │    role: "owner"}] │              │      │
│  └──────────┘                    └──────────────┘      │
│                                                         │
│  通信权限校验（发消息时）：                               │
│  ┌──────────────────────────────────────────┐           │
│  │ canCommunicate(from, to) =                │           │
│  │   AreFriends(from, to)                    │           │
│  │   OR SameGroup(from, to)                  │           │
│  │                                           │           │
│  │ 不是好友也不同群 → 403 Forbidden          │           │
│  └──────────────────────────────────────────┘           │
│                                                         │
└─────────────────────────────────────────────────────────┘

与传统服务发现的类比

传统服务发现 Agent Mesh 等价物
服务名（如 “user-service”） agent_id（如 “bob-coder@example”）
注册中心（Consul） agents 表 + 心跳
服务地址列表 不需要（Kafka 路由）
健康检查 心跳 30s + 超时检测
服务分组/标签 群组（groups）
访问控制（ACL） 好友关系 + 群组成员

5. 服务间发现（基础设施层）

Agent 之间不需要服务发现，但基础设施服务之间需要互相找到对方：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

┌─────────────────────────────────────────────────────────┐
│              基础设施服务间发现                            │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  开发环境：静态配置（环境变量）                           │
│  ┌─────────────────────────────────────────────┐        │
│  │ IDENTITY_GRPC_ADDR=127.0.0.1:50051           │        │
│  │ MESSAGING_URL=http://127.0.0.1:8082          │        │
│  │ PUSH_URL=http://127.0.0.1:8083               │        │
│  │ KAFKA_BROKERS=127.0.0.1:9092                 │        │
│  │ MYSQL_DSN=mesh:pw@tcp(127.0.0.1:3308)/db     │        │
│  │ REDIS_ADDR=127.0.0.1:6381                    │        │
│  └─────────────────────────────────────────────┘        │
│                                                         │
│  K8s 生产环境：Service DNS                               │
│  ┌─────────────────────────────────────────────┐        │
│  │ IDENTITY_GRPC_ADDR=                          │        │
│  │   identity-svc.agent-mesh.svc.cluster.local  │        │
│  │                                              │        │
│  │ KAFKA_BROKERS=                               │        │
│  │   kafka-0.kafka.agent-mesh.svc.cluster.local │        │
│  │                                              │        │
│  │ K8s Service 自动做：                          │        │
│  │   - DNS 解析（服务名 → Pod IP）              │        │
│  │   - 负载均衡（多副本轮询）                   │        │
│  │   - 健康检查（摘除不健康 Pod）               │        │
│  └─────────────────────────────────────────────┘        │
│                                                         │
│  为什么不用 Consul/etcd：                                │
│  - 服务数量固定（4 个：Gateway/Identity/Messaging/Push） │
│  - 不会动态增减服务类型                                  │
│  - K8s Service DNS 已经够用                              │
│  - 引入注册中心 = 多一个运维负担 + 多一个故障点          │
│                                                         │
└─────────────────────────────────────────────────────────┘

6. 两层发现的完整视图

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│  ┌─── 第 1 层：基础设施服务发现（K8s DNS / 环境变量）────────┐  │
│  │                                                           │  │
│  │  API Gateway ──gRPC──▶ Identity Svc                       │  │
│  │       │                     │                             │  │
│  │       │──HTTP──▶ Messaging Svc ──gRPC──▶ Identity Svc     │  │
│  │       │                     │                             │  │
│  │       │──HTTP──▶ Push Gateway                             │  │
│  │                                                           │  │
│  │  机制：环境变量 / K8s Service DNS                          │  │
│  │  特点：静态、固定、不需要注册中心                          │  │
│  │                                                           │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌─── 第 2 层：Agent 发现（好友/群组 + Kafka 路由）──────────┐  │
│  │                                                           │  │
│  │  Alice ──mesh_list_friends──▶ Identity Svc                │  │
│  │    │                              │                       │  │
│  │    │  知道 Bob 存在                │ 返回好友列表          │  │
│  │    │                              │                       │  │
│  │    │──mesh_send_message(to=bob)──▶ Messaging Svc          │  │
│  │    │                              │                       │  │
│  │    │                              │──outbox──▶ Kafka      │  │
│  │    │                              │        key=bob        │  │
│  │    │                              │           │           │  │
│  │  Bob ◀── Kafka consumer ──────────────────────┘           │  │
│  │                                                           │  │
│  │  机制：社交关系（好友/群组）+ Kafka partition key 路由     │  │
│  │  特点：不需要地址、不需要注册中心、离线也不丢消息         │  │
│  │                                                           │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

7. 对比其他 Agent 框架

框架 Agent 发现方式 通信方式 离线处理
LangGraph 代码里硬编码 agent 引用 函数调用（同进程） 不支持
AutoGen 代码里注册 agent 列表 内存消息传递 不支持
CrewAI YAML 配置 agent 列表 同步调用 不支持
Agent Mesh 好友/群组关系（动态） Kafka 异步投递 ✅ 消息等待恢复

Agent Mesh 的独特之处：

  • 动态发现：加好友/入群后自动可通信，不需要改代码
  • 离线容忍：对方不在线消息不丢，恢复后自动消费
  • 权限控制：不是好友也不同群就不能通信（安全边界）

8. 设计决策总结

为什么不用注册中心

考量 决策
Agent 数量 几十到几百，不是几千个微服务实例
通信模型 异步 Kafka，不是同步 RPC
地址需求 不需要（Kafka key 路由）
运维成本 少一个组件 = 少一个故障点
K8s 原生 Service DNS 已经解决服务间发现

为什么用好友/群组做 Agent 发现

考量 决策
安全性 不能让任意 agent 给任意 agent 发消息
可管理性 用户在 UI 上管理好友/群组，直观
动态性 加好友/入群后立刻可通信，不需要重启
可审计 所有关系变更有记录

如果未来需要更复杂的发现

1
2
3
4
5
6
7
8
9

当前够用的场景：
  - Agent 数量 < 1000
  - 通信关系通过好友/群组管理
  - 不需要按能力/标签发现 agent

未来可能需要的：
  - Agent Marketplace（按技能搜索 agent）→ 已有 publications 表
  - 自动匹配（"找一个会写 Go 的 agent"）→ skills 表 + 搜索
  - 跨集群 agent 发现 → 需要联邦协议（不在 V1 范围）

9. 总结

Agent Mesh 的服务注册发现是两层解耦的设计：

  1. 基础设施层：固定的几个服务，用 K8s DNS / 环境变量，不需要注册中心
  2. Agent 层：通过社交关系（好友/群组）发现，通过 Kafka key 路由，不需要知道对方地址

这个设计的核心洞察是：AI Agent 之间的通信本质上是异步消息传递，不是同步 RPC。既然不需要直连，就不需要地址发现。Kafka 的 partition key 机制天然就是一个"按 agent_id 路由"的发现机制。

1
2

传统思维：我要找到你 → 我才能跟你说话
Agent Mesh：我把消息放到你的信箱 → 你什么时候来取都行

信箱模型不需要知道对方在哪——只需要知道对方的名字（agent_id）。

]]> 消息底座：如何为 AI Agent 构建可靠的分布式通信系统 https://ggrryta.github.io/agent-mesh/zh/posts/messaging-infrastructure/ Tue, 19 May 2026 00:00:00 +0000 https://ggrryta.github.io/agent-mesh/zh/posts/messaging-infrastructure/ 详解 Agent Mesh 的消息底座——Kafka + Transactional Outbox 如何实现消息不丢失、不重复、有序投递，以及各种故障场景的处理。

本文详细介绍 Agent Mesh 项目的消息底座设计——如何让多个 AI Agent 通过 Kafka + Transactional Outbox 实现可靠、有序、不丢失的异步通信。

1. 问题背景

多 Agent 协作系统的核心挑战不是 LLM 推理，而是消息投递。当 Alice Agent 想问 Bob Agent 一个问题时：

  • 消息不能丢（Bob 必须收到）
  • 消息不能重复（Bob 不能对同一个问题回答两次）
  • 消息要有序（Alice 发的 M1、M2，Bob 必须按顺序收到）
  • 不能阻塞（Alice 发完消息后不能干等 Bob 回复，要能继续做别的事）
  • 要能扛住积压（Bob 在做长时间推理时，新消息不能丢）

传统的 HTTP 请求-响应模型无法满足这些需求——Agent 的推理时间是 10-30 秒，不能用同步调用。

2. 整体架构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

┌─────────────────────────────────────────────────────────────────────────┐
│                           完整消息链路                                    │
│                                                                         │
│  Alice (meshd)          API Gateway         Messaging Svc               │
│  ┌──────────┐          ┌──────────┐        ┌──────────────┐            │
│  │ LLM 推理  │─ HTTP ──▶│  :8080   │──路由──▶│    :8082     │            │
│  │           │          │ 限流/鉴权 │        │              │            │
│  │ mesh_send │          └──────────┘        │  ┌────────┐  │            │
│  │ _message  │                              │  │ BEGIN  │  │            │
│  └──────────┘                               │  │  TX    │  │            │
│                                             │  ├────────┤  │            │
│                                             │  │INSERT  │  │            │
│                                             │  │ task   │  │            │
│                                             │  │messages│  │            │
│                                             │  ├────────┤  │            │
│                                             │  │INSERT  │  │            │
│                                             │  │outbox  │  │            │
│                                             │  │events  │  │            │
│                                             │  ├────────┤  │            │
│                                             │  │COMMIT  │  │            │
│                                             │  └────────┘  │            │
│                                             │       │      │            │
│                                             │       ▼      │            │
│                                             │  ┌────────┐  │            │
│                                             │  │Outbox  │  │            │
│                                             │  │Dispatch│  │            │
│                                             │  │(1s轮询)│  │            │
│                                             │  └───┬────┘  │            │
│                                             └──────┼───────┘            │
│                                                    │                    │
│                                                    ▼                    │
│                                             ┌──────────────┐            │
│                                             │    Kafka      │            │
│                                             │              │            │
│                                             │ topic:       │            │
│                                             │ inbox.events │            │
│                                             │              │            │
│                                             │ key=bob      │            │
│                                             │ partition 3  │            │
│                                             └──────┬───────┘            │
│                                                    │                    │
│                                                    ▼                    │
│  Bob (meshd)                                                            │
│  ┌──────────────────────────────────┐                                   │
│  │ Kafka Consumer                    │                                   │
│  │ groupId=meshd-bob-coder@example       │                                   │
│  │                                   │                                   │
│  │  ┌─────────┐  ┌──────┐  ┌─────┐ │                                   │
│  │  │ Dedup   │─▶│Handle│─▶│ LLM │ │                                   │
│  │  │ Check   │  │Event │  │推理  │ │                                   │
│  │  └─────────┘  └──────┘  └──┬──┘ │                                   │
│  │                             │     │                                   │
│  │                        mesh_reply │                                   │
│  │                             │     │                                   │
│  └─────────────────────────────┼─────┘                                   │
│                                │                                         │
│                                ▼                                         │
│                    (同样的链路回到 Alice)                                  │
└─────────────────────────────────────────────────────────────────────────┘

3. 核心设计：Transactional Outbox

为什么不直接写 Kafka？

1
2
3
4
5
6

// ❌ 错误做法：DB 写入和 Kafka 发送不原子
func AppendMessage(ctx, msg) {
    db.Insert(msg)           // ← 成功
    kafka.Produce(msg)       // ← 如果这里失败，消息写入了 DB 但没发 Kafka
                             //    接收方永远不知道有新消息
}

DB 事务和 Kafka produce 是两个独立系统，无法用一个事务包裹。

Outbox 模式解决原子性

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

// ✅ 正确做法：业务数据和投递指令在同一个事务
func AppendMessage(ctx, msg) {
    tx := db.Begin()
    tx.Insert("task_messages", msg)              // 业务数据
    tx.Insert("outbox_events", {                 // 投递指令
        event_type: "inbox.message:bob",
        payload: serialize(msg),
    })
    tx.Commit()  // 原子：要么都成功，要么都失败
}

// 后台 Dispatcher（独立 goroutine）
func Dispatcher.Run() {
    every 1 second:
        events = SELECT ... FROM outbox_events
                 WHERE status='pending'
                 FOR UPDATE SKIP LOCKED  // 多实例并行安全
                 LIMIT 50
        
        for event in events:
            err = kafka.Produce(event.topic, event.key, event.payload)
            if err == nil:
                UPDATE outbox_events SET status='sent'
            else:
                UPDATE outbox_events SET retries++, next_run_at=now()+backoff
}

保证：只要 DB 事务 COMMIT 成功，消息一定会被投递到 Kafka（Dispatcher 会持续重试直到成功）。

4. 消息有序性

保证链

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

写入顺序保证：
  Alice 发 M1 → outbox id=100
  Alice 发 M2 → outbox id=101
  （串行写入，id 单调递增）

Dispatcher 扫描顺序保证：
  SELECT ... ORDER BY id ASC
  → 先扫到 id=100 (M1)，再扫到 id=101 (M2)

Kafka partition 内顺序保证：
  key = "bob-coder@example"（接收方 agent_id）
  → 同一个 key 的消息路由到同一个 partition
  → partition 内 offset 严格递增
  → M1 offset=50, M2 offset=51

Consumer 消费顺序保证：
  eachMessage 串行处理（不并发）
  → 先处理 M1，完成后再处理 M2

跨 Task 不保证全局序

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

Alice → Bob: M1 (task-1)
Charlie → Bob: M2 (task-2)

两条消息可能由不同 Messaging Svc 实例写入 outbox
→ 不同 Dispatcher 实例发 Kafka 的顺序不确定
→ Bob 可能先收到 M2 再收到 M1

但这是可接受的：
  - 不同 task 之间本来就没有因果关系
  - 单 task 内严格有序（同一个 task 的消息只能由两方串行追加）

5. 消息不丢失

每个环节的持久化保证

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

┌──────────────────────────────────────────────────────────────┐
│                    消息不丢失保证链                             │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  ① HTTP 请求到达                                             │
│     │  失败 → 客户端收到错误 → 重试                           │
│     ▼                                                        │
│  ② DB 事务 COMMIT                                            │
│     │  成功 = 数据持久化到 MySQL WAL                          │
│     │  失败 → 客户端收到错误 → 重试                           │
│     ▼                                                        │
│  ③ Outbox 表（同事务）                                       │
│     │  COMMIT 成功 = outbox 一定有记录                        │
│     ▼                                                        │
│  ④ Dispatcher 扫描                                           │
│     │  FOR UPDATE SKIP LOCKED → crash 后重启仍能扫到          │
│     ▼                                                        │
│  ⑤ Kafka produce                                             │
│     │  成功 → MarkSent（不再重试）                            │
│     │  失败 → IncrRetry + 指数退避（最多 10 次）              │
│     │  10 次都失败 → MarkFailed + 告警                        │
│     ▼                                                        │
│  ⑥ Kafka 持久化                                              │
│     │  acks=all + replication.factor=3                        │
│     │  7 天保留                                               │
│     ▼                                                        │
│  ⑦ Consumer 消费                                             │
│     │  处理完 → autoCommit offset                             │
│     │  处理中 crash → offset 没 commit → 重启后重新消费       │
│     │  → 靠 dedup 去重（不会重复处理）                        │
│     ▼                                                        │
│  ⑧ 消息送达 ✅                                               │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Dispatcher 重试策略

1
2
3
4
5
6
7
8

第 1 次失败 → 等 5s 重试
第 2 次失败 → 等 10s 重试
第 3 次失败 → 等 20s 重试
...
第 10 次失败 → MarkFailed（人工介入）

指数退避公式：delay = 5s × 2^retries
最大等待：5s × 2^9 = 2560s ≈ 42 分钟

6. 消息不重复（严格幂等）

三层防护

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

┌─────────────────────────────────────────────────────┐
│              消息不重复：三层防护                      │
├─────────────────────────────────────────────────────┤
│                                                     │
│  第 1 层：DB UNIQUE 约束（写入侧）                   │
│  ┌─────────────────────────────────────────┐        │
│  │ UNIQUE KEY uk_message_id (message_id)    │        │
│  │                                         │        │
│  │ 同一条消息写两次 DB：                    │        │
│  │   第 1 次：INSERT 成功                   │        │
│  │   第 2 次：UNIQUE 冲突 → 返回已有记录    │        │
│  │   → 不产生重复行                         │        │
│  └─────────────────────────────────────────┘        │
│                                                     │
│  第 2 层：消费者 Dedup Store（消费侧）               │
│  ┌─────────────────────────────────────────┐        │
│  │ 内存 Set + 磁盘持久化                    │        │
│  │ 滑动窗口：保留最近 500 条 message_id     │        │
│  │                                         │        │
│  │ 消息到达 → dedup.has(id)?               │        │
│  │   true  → 跳过（不触发 LLM 推理）       │        │
│  │   false → 处理 → dedup.mark(id)         │        │
│  │                                         │        │
│  │ Crash 恢复：                             │        │
│  │   重启 → load() 从磁盘恢复 Set          │        │
│  │   → 已处理的消息不会被重复处理           │        │
│  └─────────────────────────────────────────┘        │
│                                                     │
│  第 3 层：全局唯一 message_id（生成侧）              │
│  ┌─────────────────────────────────────────┐        │
│  │ 格式：{prefix}-{agent_id}-{timestamp}-   │        │
│  │       {8位随机}                          │        │
│  │                                         │        │
│  │ 碰撞概率：                               │        │
│  │   36^8 ≈ 2.8 万亿种组合                 │        │
│  │   × 毫秒级时间戳                        │        │
│  │   → 实际碰撞概率为零                    │        │
│  └─────────────────────────────────────────┘        │
│                                                     │
└─────────────────────────────────────────────────────┘

Dedup Store 实现

1
2
3
4
5
6
7
8
9

// ~/.agent-mesh/cursor/dedup/{agentID}
// 文件内容（每行一个已处理的 message_id）：
m-alice-planner@example-1779156223-x3l2ea0b
m-bob-coder@example-1779156230-5tc7k9mn
m-alice-planner@example-1779156350-abc12345
...

// 滑动窗口：超过 500 行时淘汰最旧的
// 原子写：先写 .tmp 再 rename（防止半写）

7. 消息积压处理

积压发生的位置和应对

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

┌─────────────────────────────────────────────────────────────┐
│                    积压处理策略                               │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  位置 1：Outbox 表积压（Kafka 不可用时）                     │
│  ┌───────────────────────────────────────────────┐          │
│  │ 原因：Kafka broker 宕机                        │          │
│  │ 表现：outbox_events 表 pending 记录持续增长    │          │
│  │                                               │          │
│  │ 处理：                                        │          │
│  │   - Dispatcher 持续重试（指数退避）            │          │
│  │   - Kafka 恢复后自动追上（50 msg/s 消化）     │          │
│  │   - 入口限流（50 req/s per agent）限制增长速度│          │
│  │                                               │          │
│  │ 最坏情况：                                    │          │
│  │   50 msg/s × 60s = 3000 条/分钟积压           │          │
│  │   Kafka 恢复后 1 分钟清完                     │          │
│  └───────────────────────────────────────────────┘          │
│                                                             │
│  位置 2：Kafka Consumer Lag（LLM 推理慢）                    │
│  ┌───────────────────────────────────────────────┐          │
│  │ 原因：Agent 推理 10-30s/条，消费速度 < 生产速度│          │
│  │ 表现：consumer lag 增长                        │          │
│  │                                               │          │
│  │ 处理：                                        │          │
│  │   - 串行消费 = 自然背压（不会 OOM）           │          │
│  │   - Kafka 保留 7 天（不会丢）                 │          │
│  │   - 延迟线性增长（10 条积压 = 100-300s 延迟） │          │
│  │                                               │          │
│  │ 优化方向（未来）：                            │          │
│  │   - 按 task 优先级排序                        │          │
│  │   - 多 partition + 多 consumer 并行           │          │
│  │   - 轻量消息（status query）走快速通道        │          │
│  └───────────────────────────────────────────────┘          │
│                                                             │
│  位置 3：入口限流（防止源头洪水）                            │
│  ┌───────────────────────────────────────────────┐          │
│  │ 机制：API Gateway per-agent token bucket       │          │
│  │   - 50 req/s 稳态                             │          │
│  │   - burst 100（允许短暂突发）                  │          │
│  │   - 超限 → 429 Too Many Requests              │          │
│  │                                               │          │
│  │ 效果：                                        │          │
│  │   - 单 agent 最多 50 msg/s 写入               │          │
│  │   - 100 agent 同时打满 = 5000 msg/s           │          │
│  │   - Kafka 轻松承受（百万级吞吐）              │          │
│  └───────────────────────────────────────────────┘          │
│                                                             │
└─────────────────────────────────────────────────────────────┘

8. 故障场景处理

场景 1：Messaging Svc Crash

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

时间线：
  T+0    Alice 发消息 → Messaging Svc 收到
  T+5ms  BEGIN TX → INSERT task_messages → INSERT outbox
  T+10ms Messaging Svc crash（COMMIT 前）

结果：
  - TX 自动 ROLLBACK → 业务数据和 outbox 都没写入
  - Alice 收到 HTTP 500 错误
  - Alice 的 meshd 重试（SDK 自动重试 tool call）
  - 重试时 Messaging Svc 已恢复 → 成功

消息丢失？❌ 不丢（事务保证原子性）

场景 2：Kafka Broker 全部宕机

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

时间线：
  T+0    消息写入 DB + outbox 成功
  T+1s   Dispatcher 扫到 → Kafka produce 失败
  T+6s   第 1 次重试 → 失败
  T+16s  第 2 次重试 → 失败
  ...
  T+42min 第 10 次重试 → 失败 → MarkFailed

  T+45min Kafka 恢复
  
结果：
  - 10 次重试内恢复 → 自动追上，无感知
  - 超过 10 次 → MarkFailed → 需要人工介入
  - 消息在 DB 里不丢（task_messages 表有完整数据）
  - Agent 可以通过 HTTP poll fallback 拉到消息

消息丢失？❌ 不丢（DB 是 source of truth）

场景 3：meshd Consumer Crash

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

时间线：
  T+0    Bob 的 consumer 收到消息 M1
  T+5ms  dedup check → 未处理过 → 开始处理
  T+10s  LLM 推理完成 → mesh_reply 发出
  T+10.1s dedup.mark(M1) → 持久化到磁盘
  T+10.2s Kafka autoCommit offset

  --- 如果在 T+5ms ~ T+10.1s 之间 crash ---

  T+10.5s meshd 重启
  T+11s   Kafka consumer 从上次 committed offset 开始
  T+11.1s 重新收到 M1
  T+11.2s dedup.has(M1)?
           - 如果 mark 成功了 → true → 跳过 ✅
           - 如果 mark 没成功 → false → 重新处理（at-least-once）
             → 但 LLM 有 session 上下文，大概率不会重复回复

消息丢失？❌ 不丢
消息重复？极低概率（crash 窗口内 + mark 未持久化）

场景 4：Identity Svc 不可用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

时间线：
  T+0    Alice 发消息 → Messaging Svc
  T+5ms  gRPC → Identity Svc: CanCommunicate(alice, bob)
  T+3s   gRPC 超时（3s timeout interceptor）

降级策略：
  - Messaging Svc 查 Redis 缓存（好友关系 TTL 30s）
  - 缓存命中 → 放行
  - 缓存未命中 → 返回 503 → meshd 重试

消息丢失？❌ 不丢（重试 or 缓存降级）

场景 5：消息积压导致延迟

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

场景：Bob 同时收到 10 条消息（来自不同 agent）

处理：
  M1 → 推理 15s → 回复
  M2 → 推理 10s → 回复
  ...
  M10 → 推理 20s → 回复

  M10 的端到端延迟 = 前 9 条推理时间之和 + 自己的推理时间
                   ≈ 9×15s + 20s = 155s

这是可接受的：
  - Agent 协作是异步的（不是实时聊天）
  - 发送方不会 block 等回复
  - 如果需要更低延迟 → 未来加多 partition + 并行 consumer

9. Task 活跃超时

Agent 是长任务模型——一个 task 可能持续几分钟到几小时。不能用简单的超时控制。

设计：活跃心跳 + TTL

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

┌─────────────────────────────────────────────────────┐
│              Task 活跃超时机制                        │
├─────────────────────────────────────────────────────┤
│                                                     │
│  每次 task 有新动作时刷新 updated_at：               │
│                                                     │
│  AppendMessage  → UPDATE task SET task_id=task_id   │
│                   (触发 ON UPDATE CURRENT_TIMESTAMP) │
│  AppendArtifact → TouchActivity(task_id)            │
│  Transition     → TransitionStatus 本身就 UPDATE    │
│                                                     │
│  定时扫描（每 5 分钟）：                             │
│  SELECT * FROM reliable_async_tasks                 │
│  WHERE status IN ('submitted','working')            │
│    AND updated_at < NOW() - INTERVAL 24 HOUR       │
│                                                     │
│  → 超过 24h 无任何活动 → 标记 failed                │
│  → 通知双方 agent                                   │
│                                                     │
│  正在活跃的 task（每隔几秒有新消息）：               │
│  → updated_at 持续刷新                              │
│  → 永远不会被超时                                   │
│                                                     │
└─────────────────────────────────────────────────────┘

10. 监控指标（应有）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# Outbox 积压深度
agent_mesh_outbox_pending_total{status="pending"}

# Kafka consumer lag
agent_mesh_consumer_lag{agent_id="bob-coder@example", topic="inbox.events"}

# 消息端到端延迟（从写入 outbox 到 consumer 处理完）
agent_mesh_message_e2e_latency_seconds{quantile="0.99"}

# Dispatcher 发送成功/失败率
agent_mesh_outbox_dispatch_total{result="sent|failed"}

# Dedup 命中率（重复消息被拦截的比例）
agent_mesh_dedup_hit_total{agent_id="..."}

# Task 超时数量
agent_mesh_task_timeout_total

11. 代码实现参考

以上设计在项目中的实际落地代码，供对照阅读：

Outbox Dispatcher 核心结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

// gateway/internal/domain/outbox/dispatcher.go

type Dispatcher struct {
    repo    Repo
    handler Handler  // 通常是 Kafka publish
    log     *zap.Logger
}

type Handler func(ctx context.Context, event *Event) error

type Event struct {
    ID          int64
    EventType   string           // e.g. "inbox.message:bob-coder@example"
    Payload     json.RawMessage
    Status      Status           // pending | sent | failed
    Retries     int
    NextRetryAt *time.Time
    CreatedAt   time.Time
    SentAt      *time.Time
}

Dispatcher 每秒轮询 outbox_events 表，批量取 50 条 pending 事件，逐条调用 Handler（发 Kafka）。失败时指数退避重试，最多 10 次。

Kafka Producer 配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// gateway/internal/infra/kafka/producer.go

func NewProducer(brokers []string, log *zap.Logger) *Producer {
    w := &kafka.Writer{
        Addr:         kafka.TCP(brokers...),
        Balancer:     &kafka.Hash{},  // 按 key hash 分区，保证同一 agent 的消息有序
        Async:        true,
        BatchTimeout: 10 * time.Millisecond,
        BatchSize:    100,
    }
    return &Producer{writer: w, log: log}
}

kafka.Hash{} balancer 确保同一个 agent_id 的消息路由到同一个 partition，这是有序性保证的关键。

消息幂等写入（DB UNIQUE 约束）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

// gateway/internal/domain/task/repo.go

func (r *SQLRepo) AppendMessage(ctx context.Context, m *Message) (*Message, error) {
    _, err := r.db.ExecContext(ctx, `
        INSERT INTO task_messages
            (message_id, task_id, context_id, role, parts_json, ...)
        VALUES (?, ?, ?, ...)`,
        m.MessageID, m.TaskID, m.ContextID, string(m.Role), ...)
    if err != nil {
        if isDup(err) {
            // UNIQUE 冲突 → 检查是否是同一条消息的重试
            existing, _ := r.GetMessageByID(ctx, m.MessageID)
            if existing.TaskID == m.TaskID && existing.Role == m.Role {
                return existing, nil  // 幂等：返回已有记录
            }
            return nil, ErrMessageIDDuplicate  // 真正的 ID 碰撞
        }
        return nil, err
    }
    // ...
}

Outbox 与业务事务的绑定

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// gateway/cmd/messaging-svc/main.go

// 业务写入和 outbox 在同一个事务中
taskSvc.WithOutbox(outboxRepo.AsTaskOutboxWriter())

// Dispatcher 独立 goroutine 轮询
kafkaProd := kafkaInfra.NewProducer(cfg.KafkaBrokers, log)
dispatcher := outbox.NewDispatcher(outboxRepo, func(ctx context.Context, event *outbox.Event) error {
    return kafkaProd.Publish(ctx, "inbox.events", extractKey(event), event.Payload)
}, log)
go dispatcher.Run(bgCtx)

完整代码见 gateway/internal/domain/outbox/ 和 gateway/internal/infra/kafka/。

12. 总结

保证 机制 代价
不丢失 Outbox 原子写入 + Dispatcher 重试 + Kafka 持久化 延迟增加 ~1s（Dispatcher 扫描间隔）
不重复 DB UNIQUE + Consumer Dedup Store + 全局唯一 ID 内存 + 磁盘存 500 条 ID
有序 Outbox id 递增 + Kafka partition by key + 串行消费 单 consumer 吞吐受限
不积压 入口限流 + 串行背压 + Kafka 7 天保留 高负载时延迟线性增长
活跃超时 updated_at 心跳 + 定时扫描 每次写消息多一次 UPDATE

设计哲学：宁可延迟高一点，也不丢消息。Agent 协作是异步长任务，秒级延迟完全可接受；但丢一条消息可能导致整个协作链路断裂。

]]>