# 消息路由编号原理

## 一、四层编号体系

| 层级 | 编号类型 | 格式 | 用途 |
|------|----------|------|------|
| 外部平台 | `external_id` | QQ号 / TG user_id | 外部账号标识 |
| 内部用户 | `internal_user` | 用户目录名 | 映射到 `users/<name>/` |
| 推送队列 | `push_id` | `push_{uuid12}` | 异步推送任务追踪 |
| API 对账 | `echo` | `{action}_{uuid}` | OneBot 请求-响应配对 |

## 二、身份映射

### 查找优先级

```
resolve_onebot(user_id="12345"):
  ① identity_map.json → "qq:12345"
  ② identity_map.json → "onebot:12345"
  ③ identity_map.json → "12345"
  ④ config.json → bound_users["qq:12345"]
  ⑤ config.json → bound_users["onebot:12345"]
  ⑥ config.json → bound_users["12345"]
  ⑦ 全部未命中 → 返回 None → 消息被丢弃
```

## 三、消息路由流程

### OneBot (QQ/NapCat)
```
NapCat WS → _handle_raw() → _handle_message_event()
  → resolve_onebot(user_id) → _check_access()
  → 构建 source dict → 下载附件 → agent.chat() → _reply()
```

### Telegram
```
getUpdates → _handle_update() → _handle_message()
  → resolve_telegram(user_id) → _check_access()
  → 构建 source dict → 下载附件 → agent.chat() → _reply()
```

## 四、推送队列

- ID: `push_{uuid12}`
- 状态机: pending → completed / failed (retry_times 次)
- 存储: `message/push_queue/push_xxx.json`

## 五、Source 闭环

```
外部消息 → 构建 source → AgentService.chat() 注入前缀
  → 定时任务创建时携带 source → 任务完成 → 推送回原平台
```
