分布式 on Agent-Mesh 技术博客 https://ggrryta.github.io/agent-mesh/zh/tags/%E5%88%86%E5%B8%83%E5%BC%8F/ Recent content in 分布式 on Agent-Mesh 技术博客 Hugo zh Tue, 19 May 2026 00:00:00 +0000 服务注册发现：为什么 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 协作是异步长任务，秒级延迟完全可接受；但丢一条消息可能导致整个协作链路断裂。

]]>