# Routing（消息路由）

**模块：** `gateway/core/routing/`

## 文档维护规范

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

---

## 模块职责

消息路由，包括：

- **飞书消息接收和转发**：接收飞书消息并转发到对应的 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 通过工具主动回复消息

---

## 相关文档

- [需求规划](../requirements.md)：消息路由需求
- [架构设计](../architecture.md)：模块在整体架构中的位置
- [两种 Agent 类型](../requirements.md#两种-agent-类型)：详细说明