Agent/gateway/docs/core/routing.md

Routing（消息路由）

模块： gateway/core/routing/

文档维护规范

1. 先改文档，再动代码 - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现
2. 文档分层，链接代码 - 关键实现需标注代码文件路径；格式：module/file.py:function_name
3. 简洁快照，日志分离 - 只记录已确认的设计

---

模块职责

消息路由，包括：

• 飞书消息接收和转发：接收飞书消息并转发到对应的 Agent
• 消息路由规则管理：管理消息路由规则
• Agent 联系人列表维护：维护 Agent 的可见联系人列表

---

核心概念

消息路由

• 根据配置将飞书消息路由到对应的 Trace
• 支持两种 Agent 类型的路由规则

飞书集成

• 接收飞书消息
• 发送消息到飞书
• 处理飞书事件

联系人管理

• 维护每个 Agent 的可见联系人列表
• 联系人包括：Agent ID、介绍、运行设备信息
• 支持 Agent 之间发送消息

---

模块结构

gateway/core/routing/
├── router.py              # 消息路由核心
├── feishu_connector.py    # 飞书集成
└── contact_manager.py     # 联系人管理

---

关键功能

消息路由核心

实现位置： gateway/core/routing/router.py

职责：

• 接收消息
• 根据路由规则转发消息
• 管理路由规则

飞书集成

实现位置： gateway/core/routing/feishu_connector.py

职责：

• 接收飞书消息
• 发送消息到飞书
• 处理飞书事件（消息、@提及等）

联系人管理

实现位置： gateway/core/routing/contact_manager.py

职责：

• 注册 Agent 联系人
• 查询联系人列表
• 更新联系人信息

---

两种 Agent 类型的路由规则

个人助理型 Agent

路由规则：

飞书用户 ID → Agent Trace ID

示例：
- 用户 Alice 发消息给助理账号 → 路由到 trace-alice-001
- 用户 Bob 发消息给助理账号 → 路由到 trace-bob-001

实现方式：

• 维护 飞书用户 ID → Trace ID 的映射
• 消息到达时查找对应的 Trace

数字员工型 Agent

路由规则：

所有发给数字员工账号的消息 → 同一个 Trace

示例：
- 用户 Alice 发消息 → trace-receptionist
- 用户 Bob 发消息 → trace-receptionist（同一个）

工作模式：

• Agent 定时检查或收到新消息通知
• Agent 通过工具主动查看消息
• Agent 通过工具主动回复消息

---

相关文档

• 需求规划：消息路由需求
• 架构设计：模块在整体架构中的位置
• 两种 Agent 类型：详细说明