# 秀秀 3.0 消息通信链路通俗分析

## 1. 总览

秀秀 3.0 包含三大模块：**秀秀模块（消息/任务）**、**链接模块（跨服路由）**、**龙虾模块（语义理解）**。用户发送消息后，系统通过 12 步链路处理并返回回复。

- **秀秀模块 = 前台 + 工单系统**：负责接收用户消息、管理 Bot 队列、把任务交给合适的 Bot，最后把回复发出去。
- **链接模块 = 跨服务器快递员**：当 Bot 不在本机时，负责把消息打包、跨服务器投递、把回复带回。
- **龙虾模块 = 真正理解并写回复的大脑**：调用 AI 模型理解用户意图，生成高质量回复。

**替身类任务特殊说明**：替身类任务会先在步骤 4.5 经过「工作要求整理专家BOT」预处理，再进入 AI 生成环节。

| 模块 | 核心职责 | 一句话类比 |
|------|---------|-----------|
| 秀秀模块 | 消息收发、Bot 管理、任务队列、插件校验 | 前台 + 工单系统 |
| 链接模块 | 跨服务器消息路由、远端 Bot 投递 | 跨服务器快递员 |
| 龙虾模块 | 语义理解、AI 回复生成 | 真正理解和写回复的大脑 |

---

## 2. 一张图看完整通信链路

```
 1. 用户发消息 → 电脑端/手机端
         ↓
 2. 秀秀 API 接收 → send_im_message
         ↓
 3. 消息入库 → chat_messages
         ↓
 4. 选择 Bot → 私聊/群聊@/mention/确认工单/远端路由
         ↓
 4.5 工作要求整理 → run_requirement_organizer（替身类任务）
         ↓
 5. 创建任务事件 → create_task_event
         ↓
 6. 队列 Worker → BOT_TASK_QUEUE
         ↓
 7. 前置检查 → process_bot_task
         ↓
 8. 龙虾生成 → openclaw_agent_reply
         ↓
 9. 校验/插件 → 工单/批量/Loop/ACTION/FILE
         ↓
10. 写回消息 → bot_insert_message
         ↓
11. 行首@派发 → dispatch_mention_tokens
         ↓
12. 前端展示 → GET /api/im/messages
```

---

## 3. 12 步明细

| 步骤 | 关键函数 / 模块 | 通俗逻辑 | 例外情况 |
|------|----------------|---------|---------|
| 1 | 客户端 | 用户在电脑或手机上输入消息并发送。这是整个链路的起点。 | 网络断开时消息发不出去，前端会显示发送失败。 |
| 2 | `send_im_message` | 秀秀服务端 API 收到消息请求，校验用户身份和消息格式。 | 用户被禁言或频道限制时，API 会拒绝接收。 |
| 3 | `chat_messages` | 消息写入数据库 chat_messages 表，保证消息不丢失。此时消息状态为"待处理"。 | 数据库写入失败会导致消息丢失（极罕见，有重试机制）。 |
| 4 | `bot_select` | 根据场景选 Bot：私聊直接用当前 Bot；群聊识别行首 @；确认工单匹配任务 Bot；远端 Bot 走链接模块路由。 | 未 @ 任何 Bot 时不会触发回复；多 Bot @ 时只取第一个。 |
| 4.5 | `run_requirement_organizer` | 替身类任务专用。将用户原始消息交给「工作要求整理专家BOT」，生成标准化任务描述，再进入步骤 5。 | 非替身类任务跳过此步骤，直接进步骤 5。 |
| 5 | `create_task_event` | 为选中的 Bot 创建任务事件，写入任务队列。任务包含消息内容、Bot ID、优先级等信息。 | Bot 离线或禁用时，任务创建会被拒绝。 |
| 6 | `BOT_TASK_QUEUE` | 队列 Worker 按优先级从 BOT_TASK_QUEUE 中取出任务。高优先级任务优先处理。 | 队列积压时消息处理会延迟。 |
| 7 | `process_bot_task` | 前置检查：Bot 是否在线、权限是否足够、参数是否完整、是否超过速率限制。 | 速率限制触发时，任务会被延迟或拒绝。 |
| 8 | `openclaw_agent_reply` | 调用龙虾模块的 AI 模型，将消息内容和上下文发给 Agent，生成回复文本。 | AI 超时、token 不足、模型不可用时返回错误。 |
| 9 | `validate_plugins` | 校验 AI 回复并通过插件链处理：工单创建/更新、批量操作、Loop 循环、ACTION 动作执行、FILE 文件生成。 | 校验失败时回复被拦截；Loop 超过最大轮数时强制终止。 |
| 10 | `bot_insert_message` | 将校验后的 Bot 回复写入 chat_messages 表，标记消息来源为 Bot。 | 写入冲突时以最后写入为准。 |
| 11 | `dispatch_mention_tokens` | 如果回复中包含行首 @，系统解析 @ 目标，触发对应接收者的通知和消息分发。 | @ 的用户不存在或离线时，@ 静默失败。 |
| 12 | `GET /api/im/messages` | 前端定时轮询或 WebSocket 推送，拉取最新消息并展示在聊天界面上。 | 前端轮询间隔内新消息有短暂延迟。 |

---

## 4. 各模块分工

| 模块 | 负责什么 | 不负责什么 | 典型函数 / 位置 |
|------|---------|-----------|---------------|
| 秀秀前端 | 消息输入、发送、列表展示、@ 选择、文件上传 | 消息路由、Bot 逻辑、AI 生成 | `GET /api/im/messages`, `POST /api/im/send` |
| 秀秀核心服务 | 消息收发、Bot 管理、任务队列、数据库读写、插件调度 | 跨服消息投递、AI 语义理解 | `send_im_message`, `create_task_event`, `process_bot_task`, `bot_insert_message` |
| 秀秀相关插件/协议 | 工单流转、批量操作、Loop 循环控制、ACTION 协议解析、FILE 文件处理、@ 派发 | 核心消息路由、AI 回复生成 | `validate_plugins`, `dispatch_mention_tokens` |
| 工作要求整理专家BOT | 替身类任务的预处理：将用户需求整理为标准化工单描述 | 非替身类任务、最终回复生成 | `run_requirement_organizer` |
| 链接模块 | 跨服务器消息路由、远端 Bot 发现与投递、回复回传 | 本机消息处理、AI 语义理解 | 链接模块独立服务 |
| 龙虾模块 | 语义理解、AI 回复生成、Agent 上下文管理 | 消息收发、队列管理、插件执行 | `openclaw_agent_reply`, OpenClaw Agent Runtime |

---

## 5. 常见路径怎么走

| 场景 | 怎么处理 | 是否经过龙虾 | 例外 |
|------|---------|------------|------|
| 私聊本地 Bot | 用户直接对 Bot 发消息，Bot 选择阶段自动选中当前 Bot，走标准 12 步链路 | ✅ 是 | Bot 离线/禁用时不处理 |
| 群聊行首 @Bot | 用户在群聊中 @ 某个 Bot，系统识别 @ 目标后为该 Bot 创建任务 | ✅ 是 | @ 多个 Bot 只取第一个；未 @ 不触发 |
| 替身讨论任务 | 先经步骤 4.5 工作要求整理，再走标准链路。替身类任务会在生成回复前先做需求分析 | ✅ 是（两次：整理 + 回复） | 非讨论类消息不触发整理 |
| 确认执行 | 用户回复"确认"后，系统匹配之前的待确认工单，执行对应 ACTION 协议 | ⚠️ 部分经过 | 确认操作本身不走龙虾，但确认触发的后续任务可能走 |
| 批量创建 Bot | 插件层识别批量指令，自动循环创建多个 Bot 并分配任务 | ⚠️ 部分经过 | 批量指令解析在插件层，每个子 Bot 独立走链路 |
| 多 Bot Loop | 插件层控制多个 Bot 轮流传球，每个 Bot 生成输出后传给下一个 | ✅ 是（每轮） | 超过最大轮数强制终止 |
| 文件/网页报告 | 龙虾生成内容后，插件层将内容输出为文件或报告格式，再写回消息 | ✅ 是 | 文件过大时可能截断或拒绝 |
| 远端 Bot | 链接模块将消息打包投递到远端服务器，远端龙虾处理后将回复回传 | ✅ 是（远端） | 远端服务器不可达时超时失败 |

---

## 6. 例外情况汇总

| 问题表现 | 卡在哪一步 | 真实含义 | 排查方向 |
|---------|-----------|---------|---------|
| 消息发不出去 | 步骤 1-2 | 网络断开或用户无发送权限 | 检查网络连接；确认用户未被禁言；检查频道发送权限 |
| @ 了 Bot 但不回复 | 步骤 4 | Bot 未被正确选中 | 确认 @ 格式正确；检查 Bot 是否在线；查看 Bot 选择日志 |
| Bot 回复超时 | 步骤 6-8 | 队列积压或 AI 生成超时 | 检查 BOT_TASK_QUEUE 积压情况；查看 AI 调用耗时日志 |
| 回复被截断 | 步骤 9-10 | 消息过长被限制或校验截断 | 检查消息长度限制配置；查看 validate_plugins 截断日志 |
| 确认绕过现象 | 步骤 4 | Bot 选择逻辑绕过了确认环节 | 检查 bot_select 确认逻辑；查看工单状态流转 |
| 讨论消息误转为工单 | 步骤 4.5 | 替身整理将非任务消息判为任务 | 检查 run_requirement_organizer 分类逻辑；调整需求识别阈值 |
| Loop 话题跑偏 | 步骤 9 | 多 Bot 协同时上下文漂移 | 检查 Loop 上下文传递；查看每轮输入输出日志 |
| 私聊 @ 替身无效 | 步骤 4 | 私聊中 @ 不是有效的 Bot 选择方式 | 私聊应直接发消息给目标 Bot，不需 @ |
| 配置了不执行 | 步骤 7 | 前置检查未通过（权限/参数不足） | 检查 process_bot_task 前置条件；确认 Bot 配置完整 |
| 重复派发 | 步骤 11 | dispatch_mention_tokens 多次触发 | 检查 @ 派发去重逻辑；查看事件触发次数 |

---

## 7. 程序层和龙虾层的边界

| 类型 | 程序层该做 | 龙虾层该做 |
|------|-----------|-----------|
| 确定性规则 | 消息格式校验、权限检查、速率限制、Bot 选择路由 | ——（不参与，这是程序逻辑） |
| 语义理解 | ——（不做语义判断） | 理解用户意图、分析需求、判断任务类型 |
| 创建 Bot | 校验参数合法性、写入数据库、分配 ID | 理解用户对 Bot 的描述、生成 Bot 配置 |
| Loop 协同 | 控制轮数上限、传递消息、记录状态 | 每轮生成有意义的输出、保持话题连贯 |
| 文件报告 | 文件格式转换、存储、写回消息附件 | 生成报告内容、分析数据、撰写结论 |
| 异常恢复 | 重试机制、超时处理、降级策略 | 根据错误上下文调整回复策略 |

**🎯 核心原则**：程序层负责「怎么做」（确定性逻辑、规则、流程控制），龙虾层负责「说什么」（语义理解、内容生成、意图判断）。两者各司其职，不越界。

---

## 8. 主要源码依据

| 能力 | 函数 / 文件 |
|------|-----------|
| 消息发送 API | `send_im_message` |
| 消息表 | `chat_messages` |
| Bot 选择 | `bot_select` |
| 工作要求整理 | `run_requirement_organizer` |
| 任务事件创建 | `create_task_event` |
| 任务队列 Worker | `BOT_TASK_QUEUE` |
| Bot 任务预处理 | `process_bot_task` |
| 龙虾 AI 回复 | `openclaw_agent_reply` |
| 插件校验链路 | `validate_plugins` |
| Bot 消息写回 | `bot_insert_message` |
| 行首 @ 派发 | `dispatch_mention_tokens` |
| 消息拉取接口 | `GET /api/im/messages` |
| OpenClaw Agent Runtime | 龙虾模块底层 Agent 运行时 |

### 源码参考

```javascript
// === 秀秀 3.0 消息通信链路核心函数签名（示意） ===

// 步骤 2: API 接收消息
function send_im_message(channel_id, user_id, content, msg_type)

// 步骤 3: 消息入库
// 表: chat_messages (id, channel_id, user_id, content, status, created_at)

// 步骤 4: Bot 选择
function bot_select(channel_id, message) -> Bot | null

// 步骤 4.5: 工作要求整理（替身类任务）
function run_requirement_organizer(message, bot_config) -> TaskDescription

// 步骤 5: 创建任务事件
function create_task_event(bot_id, message, priority) -> TaskEvent

// 步骤 6: 队列消费
// 队列: BOT_TASK_QUEUE (FIFO, priority-aware)

// 步骤 7: 前置检查
function process_bot_task(task_event) -> PreCheckResult

// 步骤 8: 龙虾 AI 生成
function openclaw_agent_reply(agent_id, message, context) -> Reply

// 步骤 9: 校验与插件
function validate_plugins(reply, plugins_config) -> ValidatedReply

// 步骤 10: 写回消息
function bot_insert_message(channel_id, bot_id, reply) -> MessageID

// 步骤 11: @ 派发
function dispatch_mention_tokens(message) -> DispatchResult

// 步骤 12: 前端拉取
// GET /api/im/messages?channel_id=xxx&since=xxx
```

---

> 部署于 http://xiuxiu3-message-chain.qootc2.xyz/  
> 品牌色 #FFB300 体系 | PingFang SC / Microsoft YaHei | 响应式 7 断点 | WCAG AA  
> 部署日期：2026-08-04 | 部署者：050龙虾官网设计师