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

┌────────────────────────────────────────────────────┐
│                 前端控制台 (Web)                      │
│   登录 / agent 管理 / 好友关系 / 消息历史             │
└────────────────────────┬───────────────────────────┘
                         │ REST + WebSocket
                         ▼
┌────────────────────────────────────────────────────┐
│              Gateway (Go, 单进程, 无状态)             │
│                                                      │
│  Admin API (/admin/*)        Mesh API (/mesh/*)      │
│  · agents CRUD               · register + heartbeat  │
│  · friends 管理               · tasks (发消息)        │
│  · tasks (下令)               · inbox SSE (推送)      │
│  · WebSocket feed            · agent-card.json       │
│                                                      │
│  核心域：agent · skill · friendship · inbox · task   │
│  基础能力：auth · ratelimit · breaker · concur · obs │
│                                                      │
│  Outbox Dispatcher → 消息队列 → ReliableTaskWorker   │
└────────────────────────┬───────────────────────────┘
                         │ SSE 长连接 (inbox push)
                         ▼
┌────────────────────────────────────────────────────┐
│              GAS (Python daemon, 本机)                │
│  · ControlAPI (localhost)                            │
│  · GatewayClient (SSE 长连接，订阅 inbox)            │
│  · AgentManager (拉起 Agent Core 进程)               │
│  · a2a-bus (MCP Server，Agent Core 的通信出口)       │
│  · FeedStorage (SQLite，本地消息缓存)                │
└────────────────────────┬───────────────────────────┘
                         │ MCP 协议
                         ▼
┌────────────────────────────────────────────────────┐
│              Agent Core (claude -p / 自定义)          │
│  · 通过 a2a-bus MCP tool 发送消息                    │
│  · 通过 a2a-bus MCP tool 接收消息                    │
│  · 专注业务逻辑，不感知网络细节                       │
└────────────────────────────────────────────────────┘

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

A 的 Agent Core → a2a-bus (MCP tool)
  → GAS → Gateway: POST /mesh/tasks {from: A, to: B, payload}
    → Gateway: 校验 friendship(A, B)
    → 同事务写入 reliable_async_tasks (pending) + outbox_events
    → 返回 task_id

OutboxDispatcher: 扫 outbox → publish TaskEvent
ReliableTaskWorker: 消费 TaskEvent
  → Claim task (CAS pending→running)
  → 推到 B 的 inbox → SSE 推送给 B 的 GAS

B 的 GAS → a2a-bus → B 的 Agent Core
B 处理完 → 回复消息（同上反向流程）

 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

┌─────────────────────────────────────────────────────────────┐
│                        接入层                                 │
│  API Gateway (:8080) — 路由/限流/CORS/WebSocket 代理         │
└────────────────────────────┬────────────────────────────────┘
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
┌──────────────────┐ ┌────────────────┐ ┌──────────────┐
│  Identity Svc    │ │ Messaging Svc  │ │ Push Gateway │
│  :8081 + gRPC    │ │ :8082          │ │ :8083        │
│                  │ │                │ │              │
│  user/agent/     │ │ task/inbox/    │ │ WebSocket    │
│  apikey/friend/  │ │ outbox         │ │ Kafka/Redis  │
│  group/skill/    │ │                │ │ consumer     │
│  publication     │ │ gRPC→Identity  │ │              │
│                  │ │ Kafka produce  │ │              │
└──────────────────┘ └────────────────┘ └──────────────┘
                             │
                    ┌────────┴────────┐
                    ▼                 ▼
              ┌──────────┐     ┌──────────┐
              │  Kafka   │     │  MySQL   │
              │  inbox   │     │  Redis   │
              └──────────┘     └──────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────────┐
│                    meshd（本机守护进程）                       │
│  Kafka consumer → Agent Runtime → Claude SDK → MCP Tools    │
│  内嵌 Web UI (:7878)                                        │
└─────────────────────────────────────────────────────────────┘

1
2
3
4
5
6
7
8

workspace/{agentID}/
  ├── CLAUDE.md          ← 项目上下文（Claude Code 原生读取）
  ├── notes/
  │   ├── learnings.md   ← 规律、方法
  │   ├── decisions.md   ← 决策、理由
  │   └── issues.md      ← 踩坑、已知问题
  ├── *.plan.md          ← 任务计划（checkbox 进度）
  └── .claude/           ← session 历史（跨重启保留）

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

k3d cluster: agent-mesh-dev
  1 server + 1 agent node
  local registry: localhost:5111

Pods (8 个服务 Pod + 3 个基础设施 Pod):
  api-gateway × 2
  identity × 2
  messaging × 2
  push × 2
  mysql × 1
  redis × 1
  kafka × 1

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

deploy/helm/agent-mesh/
  ├── Chart.yaml (v2.0.0)
  ├── values.yaml (4 服务配置)
  └── templates/
      ├── api-gateway.yaml
      ├── identity.yaml
      ├── messaging.yaml
      ├── push.yaml
      ├── secret.yaml
      ├── namespace.yaml
      └── ingress.yaml

1
2
3
4

docker build --build-arg SERVICE=identity-svc -t agent-mesh-identity .
docker build --build-arg SERVICE=messaging-svc -t agent-mesh-messaging .
docker build --build-arg SERVICE=push-gateway -t agent-mesh-push .
docker build --build-arg SERVICE=gateway -t agent-mesh-api-gateway .

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

agent-mesh/
├── gateway/       ← Go 后端（4 个 binary）
│   ├── cmd/       ← identity-svc, messaging-svc, push-gateway, gateway, server, migrate
│   ├── internal/  ← domain（11 个模块）+ api + grpc + infra
│   ├── proto/     ← gRPC proto 定义
│   └── Dockerfile
├── meshd/         ← TypeScript 守护进程
│   ├── src/       ← agent runtime + tools + kafka + http + gateway client
│   └── web/       ← React SPA（10 个页面）
├── blog/          ← Hugo 博客（6 篇技术文章）
├── docs/          ← ADR（14 篇架构决策记录）
├── deploy/        ← Helm Chart + K8s manifests + Grafana + AlertManager
├── docker-compose.dev.yml
└── Makefile

1
2
3
4
5

发送方显式指定：mesh_send_message(..., complexity="high")
未指定时自动推断：
  - 包含"重构/架构/设计/迁移" → high
  - 文本 > 200 字或包含"步骤/然后" → medium
  - 其他 → low

1
2
3
4

System Prompt 自动包含：
  你的队友：
  - bob-coder@example：高级后端工程师，擅长 Go/TypeScript 编码、性能优化
  需要了解详细能力时，调用 mesh_get_agent_card(agent_id)。

1
2
3
4
5
6
7
8

workspace/{agentID}/
  ├── CLAUDE.md          ← 项目上下文（Claude Code 原生读取）
  ├── notes/
  │   ├── learnings.md   ← 发现的规律、成功的方法
  │   ├── decisions.md   ← 做过的决策和理由
  │   └── issues.md      ← 踩过的坑、已知问题
  ├── *.plan.md          ← 任务计划（带 checkbox 进度）
  └── .claude/           ← session 历史（跨重启保留）

1
2
3
4
5
6

收到复杂任务
  → 语义握手（确认理解）
  → 对方确认后
  → 创建 {任务}.plan.md（checkbox 格式）
  → 按计划逐步执行，完成每步打勾
  → 中断后重启：runtime 检测未完成计划，注入恢复提示

1
2
3
4
5
6
7

# 计划：重构 task 模块

- [x] 创建 fsm.go 文件
- [x] 移动状态常量
- [ ] 移动 Transition 函数
- [ ] 更新 service.go 引用
- [ ] 跑测试确认

1
2

maxTurns: 30       ← 单次事件最多 30 轮对话
maxBudgetUsd: 5.0  ← 单次事件最多 $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

用户发任务
    │
    ▼
复杂度评估（显式指定 / 启发式推断）
    │
    ├── low ──→ effort=low, thinking=disabled
    │           直接执行 → 行为标注 → 回复
    │
    ├── medium ──→ effort=medium, thinking=adaptive
    │              语义握手 → 执行 → 行为标注 → 回复
    │
    └── high ──→ effort=high, thinking=adaptive
                 语义握手 → 创建 plan.md → 逐步执行
                 → 行为标注 → 独立验证 → 回复

全程防护：
  Circuit Breaker（工具熔断）
  Preemptive Compaction（渐进式警告）
  maxTurns + maxBudgetUsd（硬限制）
  环路检测 + 闲聊检测 + 静默失败检测

知识积累：
  Stop hook → 提醒写 notes/
  PreCompact → 提醒保存
  PostCompact → 提醒恢复
  启动时 → 读 notes/ 注入 prompt + 检测未完成 plan

1
2
3
4
5
6
7
8

用户："帮我写一个 HTTP server"
Alice 委派给 Bob
Bob 回复："写好了，编译通过，在 /tmp/server/main.go"

问题：
  - Bob 真的跑了 go build 吗？还是只是"觉得"能编译？
  - Alice 怎么判断这个回复可信？
  - 用户怎么知道这个结果经过了验证？

1
2
3
4
5

mesh_send_message(
  to_agent_id: "bob-coder@example",
  text: "重构 task 模块的状态机逻辑，抽到独立文件",
  complexity: "high"
)

1
2
3
4
5
6

function inferComplexity(text: string): 'low' | 'medium' | 'high' {
  const highSignals = ['重构', '架构', '设计', '迁移', '从零', '全面', '系统性', '多模块']
  if (highSignals.some(s => text.includes(s))) return 'high'
  if (text.length > 200 || text.includes('步骤') || text.includes('然后')) return 'medium'
  return 'low'
}

1
2
3
4

parts: [
  { kind: 'text', text: '重构 task 模块...' },
  { kind: 'metadata', key: 'complexity', value: 'high' }
]

1
2
3
4
5
6

语义握手（收到任务时的自主判断）：
  收到一个新任务时，先评估是否需要确认理解再执行：
  - 任务有歧义（"优化这个服务"——优化什么？延迟？内存？吞吐？）→ 先确认
  - 任务涉及多步骤或多文件 → 先确认方案
  - 任务有隐含假设（"部署到生产"——要不要先跑测试？）→ 先列出假设让对方确认
  - 任务很简单明确（"查一下版本号"）→ 直接执行，不需要确认

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

if (complexity === 'high' || complexity === 'medium') {
  lines.push(`⚠️ 这是一个${complexity === 'high' ? '高' : '中等'}复杂度任务，请先确认你的理解再执行：`)
  lines.push(`1. 用 mesh_reply 回复你理解的范围、方法和假设`)
  lines.push(`2. 等对方确认后再动手执行`)
  lines.push(`3. 如果有疑问，在回复中列出`)
  lines.push(``)
  lines.push(`回复格式参考：`)
  lines.push(`  范围：...`)
  lines.push(`  方法：...`)
  lines.push(`  假设：...`)
  lines.push(`  疑问：...`)
}

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

Alice → Bob（complexity=high）：
  "重构 task 模块，把状态机逻辑从 service.go 抽到独立的 fsm.go"

Bob 收到的 prompt：
  ⚠️ 这是一个高复杂度任务，请先确认你的理解再执行...

Bob 回复：
  范围：把 Transition()、IsAllowedTransition()、allowedTransitions map 抽到 fsm.go
  方法：新建 fsm.go，移动函数，service.go 改为调用 fsm 包
  假设：不改 Service 的公开 API，只是内部重组
  疑问：状态常量（StateSubmitted 等）也移过去吗？

Alice 确认：
  确认。状态常量也移过去，fsm.go 包含完整的状态机定义。

Bob 开始执行。

1
2
3
4
5

验证清单（完成编码任务后必须执行）：
  □ 文件已创建/修改 → 用 Read 确认文件内容正确
  □ 编译通过 → 用 Bash 跑 go build 或 bun build
  □ 基本功能正确 → 用 Bash 跑 go test 或 go run
  注意：系统会自动检测你是否执行了验证，并在回复末尾追加标注。

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

hooks: {
  PostToolUse: [{
    hooks: [async (event) => {
      const toolName = event?.tool_name || ''
      const exitCode = event?.tool_result?.exit_code
      const cmd = event?.tool_input?.command || ''
      if (toolName === 'Bash' && exitCode === 0) {
        if (cmd.includes('go build')) turnCtx.verifications.push('编译通过(exit 0)')
        else if (cmd.includes('go test')) turnCtx.verifications.push('测试通过(exit 0)')
      } else if (toolName === 'Bash' && exitCode !== undefined && exitCode !== 0) {
        turnCtx.verifications.push(`命令失败(exit ${exitCode}): ${cmd.slice(0, 50)}`)
      }
      return { continue: true }
    }],
  }],
}

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

async function runIndependentVerification(replyText: string, cwd: string): Promise<string[]> {
  const results: string[] = []

  // 检测"创建了 xxx.go" → stat 确认文件存在
  const filePathPattern = /(?:创建|写入|生成).*?([/\w.\-@]+\.\w{1,5})/g
  // ... 对每个匹配的路径执行 stat

  // 检测"编译通过" → 跑 go build 确认
  if (replyText.includes('编译通过')) {
    await execAsync('go build ./...', { cwd, timeout: 15000 })
    results.push('编译通过')
  }

  // 检测"测试通过" → 跑 go test 确认
  if (replyText.includes('测试通过')) {
    await execAsync('go test ./...', { cwd, timeout: 30000 })
    results.push('测试通过')
  }

  return results
}

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

const independentResults = await runIndependentVerification(args.text, turnCtx.cwd)
const agentVerified = turnCtx.verifications.length > 0

if (independentResults.length > 0) {
  annotations.push(`[独立验证 ✓] ${independentResults.join('、')}`)
}
if (agentVerified) {
  annotations.push(`[agent 已验证] ${remaining.join('、')}`)
}
if (annotations.length === 0) {
  annotations.push('[未验证] 以上结论基于推理，未执行验证命令')
}

1
2
3
4

hello.go 已创建，编译通过，可以直接 go run。

[独立验证 ✓] 文件存在: hello.go、编译通过
[agent 已验证] 编译通过(exit 0)、运行成功(exit 0)

1
2
3

代码写好了，但编译有个小问题，我来修一下。

[agent 已验证] 命令失败(exit 1): go build ./...

1
2
3

建议把查询改成批量接口，预计能降低 60% 的延迟。

[未验证] 以上结论基于推理，未执行验证命令

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

用户发任务给 Alice
    │
    ▼
Alice 评估复杂度（显式指定或启发式推断）
    │
    ├── low → effort=low, thinking=disabled
    │         直接委派 Bob，Bob 执行后回复带行为标注
    │
    ├── medium → effort=medium, thinking=adaptive
    │            语义握手（Bob 先确认理解）→ 执行 → 行为标注
    │
    └── high → effort=high, thinking=adaptive
               语义握手 → 执行 → 行为标注 → Alice 自己也验证
                                                → 双重标注

全程硬性防护：maxTurns=30, maxBudgetUsd=$5
PostToolUse hook 实时记录每个工具调用的成功/失败

1
2
3
4
5
6
7
8

// low complexity → 快速响应，省 token
effort: 'low', thinking: { type: 'disabled' }

// medium complexity → 适度推理
effort: 'medium', thinking: { type: 'adaptive' }

// high complexity → 深度推理，质量优先
effort: 'high', thinking: { type: 'adaptive' }

1
2

maxTurns: 30,      // 单次事件最多 30 轮对话
maxBudgetUsd: 5.0, // 单次事件最多花 $5

1
2
3
4
5
6

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

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

1
2
3
4
5

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

 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 工具│                    │
│  └──────────────┘  └──────────────┘                    │
│                                                         │
└─────────────────────────────────────────────────────────┘

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

 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  // 游标前进，下次只拉新事件

1
2
3
4

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

1
2
3
4
5
6
7

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

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

1
2
3
4
5
6
7
8
9

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

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

 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)     │  │
│  └─────────┘     └──────────────┘  │
│                                     │
└─────────────────────────────────────┘

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

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

 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
2
3
4
5

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

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

 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)
  └───────┘

 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) │ 收到  │
  │ 的地址 │                              │       │
  └───────┘                              └───────┘

 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 恢复后继续消费     │
│                                                         │
└─────────────────────────────────────────────────────────┘

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),
    ...
);

 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          │           │
│  └──────────────────────────────────────────┘           │
│                                                         │
└─────────────────────────────────────────────────────────┘

 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 已经够用                              │
│  - 引入注册中心 = 多一个运维负担 + 多一个故障点          │
│                                                         │
└─────────────────────────────────────────────────────────┘

 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 路由     │  │
│  │  特点：不需要地址、不需要注册中心、离线也不丢消息         │  │
│  │                                                           │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

1
2
3
4
5
6
7
8
9

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

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

1
2

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

 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)                                  │
└─────────────────────────────────────────────────────────────────────────┘

1
2
3
4
5
6

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

 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
}

 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

 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 的消息只能由两方串行追加）

 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 去重（不会重复处理）                        │
│     ▼                                                        │
│  ⑧ 消息送达 ✅                                               │
│                                                              │
└──────────────────────────────────────────────────────────────┘

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 分钟

 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 万亿种组合                 │        │
│  │   × 毫秒级时间戳                        │        │
│  │   → 实际碰撞概率为零                    │        │
│  └─────────────────────────────────────────┘        │
│                                                     │
└─────────────────────────────────────────────────────┘

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（防止半写）

 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 轻松承受（百万级吞吐）              │          │
│  └───────────────────────────────────────────────┘          │
│                                                             │
└─────────────────────────────────────────────────────────────┘

 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 已恢复 → 成功

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

 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）

 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 未持久化）

 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 缓存降级）

 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

 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 持续刷新                              │
│  → 永远不会被超时                                   │
│                                                     │
└─────────────────────────────────────────────────────┘

 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

 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
}

 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}
}

 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
    }
    // ...
}