秀秀 3.0 包含三大模块：秀秀模块（消息/任务）、链接模块（跨服路由）、龙虾模块（语义理解）。用户发消息，系统通过12步链路处理并返回回复。
秀秀 3.0 是一个由三大模块协同工作的智能消息系统。理解它的最好方式是打一个比方：
用户发送一条消息后，系统会经过一条 12 步 的完整链路来处理。其中，替身类任务 会先在步骤 4.5 经过「工作要求整理专家BOT」预处理，再进入 AI 生成环节。
| 模块 | 核心职责 | 一句话类比 |
|---|---|---|
| 秀秀模块 | 消息收发、Bot 管理、任务队列、插件校验 | 前台 + 工单系统 |
| 链接模块 | 跨服务器消息路由、远端 Bot 投递 | 跨服务器快递员 |
| 龙虾模块 | 语义理解、AI 回复生成 | 真正理解和写回复的大脑 |
本文档将从「一张图看完整链路」开始，逐步拆解每一步的细节、各模块分工、常见路径走法、例外情况排查，以及程序层与龙虾层的职责边界。
以下是秀秀 3.0 消息通信的完整 12 步链路（横屏查看效果更佳）：
run_requirement_organizer）进行预处理，将用户需求整理为标准化的任务描述，再提交给龙虾模块生成回复。
每一步的核心函数、通俗逻辑和可能的例外情况：
| 步骤 | 关键函数 / 模块 | 通俗逻辑 | 例外情况 |
|---|---|---|---|
| 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 推送，拉取最新消息并展示在聊天界面上。 | 前端轮询间隔内新消息有短暂延迟。 |
六大模块各司其职，明确"负责什么"和"不负责什么"：
| 模块 | 负责什么 | 不负责什么 | 典型函数 / 位置 |
|---|---|---|---|
| 秀秀前端 | 消息输入、发送、列表展示、@ 选择、文件上传 | 消息路由、Bot 逻辑、AI 生成 | GET /api/im/messagesPOST /api/im/send |
| 秀秀核心服务 | 消息收发、Bot 管理、任务队列、数据库读写、插件调度 | 跨服消息投递、AI 语义理解 | send_im_messagecreate_task_eventprocess_bot_taskbot_insert_message |
| 秀秀相关插件 / 协议 | 工单流转、批量操作、Loop 循环控制、ACTION 协议解析、FILE 文件处理、@ 派发 | 核心消息路由、AI 回复生成 | validate_pluginsdispatch_mention_tokens |
| 工作要求整理专家BOT | 替身类任务的预处理：将用户需求整理为标准化工单描述 | 非替身类任务、最终回复生成 | run_requirement_organizer |
| 链接模块 | 跨服务器消息路由、远端 Bot 发现与投递、回复回传 | 本机消息处理、AI 语义理解 | 链接模块独立服务 |
| 龙虾模块 | 语义理解、AI 回复生成、Agent 上下文管理 | 消息收发、队列管理、插件执行 | openclaw_agent_replyOpenClaw Agent Runtime |
8 种常见场景下，消息的处理路径和是否经过龙虾模块：
| 场景 | 怎么处理 | 是否经过龙虾 | 例外 |
|---|---|---|---|
| 私聊本地 Bot | 用户直接对 Bot 发消息，Bot 选择阶段自动选中当前 Bot，走标准 12 步链路 | ✅ 是 | Bot 离线/禁用时不处理 |
| 群聊行首 @Bot | 用户在群聊中 @ 某个 Bot，系统识别 @ 目标后为该 Bot 创建任务 | ✅ 是 | @ 多个 Bot 只取第一个；未 @ 不触发 |
| 替身讨论任务 | 先经步骤 4.5 工作要求整理，再走标准链路。替身类任务会在生成回复前先做需求分析 | ✅ 是（两次：整理 + 回复） | 非讨论类消息不触发整理 |
| 确认执行 | 用户回复"确认"后，系统匹配之前的待确认工单，执行对应 ACTION 协议 | ⚠️ 部分经过 | 确认操作本身不走龙虾，但确认触发的后续任务可能走 |
| 批量创建 Bot | 插件层识别批量指令，自动循环创建多个 Bot 并分配任务 | ⚠️ 部分经过 | 批量指令解析在插件层，每个子 Bot 独立走链路 |
| 多 Bot Loop | 插件层控制多个 Bot 轮流传球，每个 Bot 生成输出后传给下一个 | ✅ 是（每轮） | 超过最大轮数强制终止 |
| 文件 / 网页报告 | 龙虾生成内容后，插件层将内容输出为文件或报告格式，再写回消息 | ✅ 是 | 文件过大时可能截断或拒绝 |
| 远端 Bot | 链接模块将消息打包投递到远端服务器，远端龙虾处理后将回复回传 | ✅ 是（远端） | 远端服务器不可达时超时失败 |
排查问题时对照此表，快速定位问题出在哪一步：
| 问题表现 | 卡在哪一步 | 真实含义 | 排查方向 |
|---|---|---|---|
| 消息发不出去 | 步骤 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 多次触发 | 检查 @ 派发去重逻辑；查看事件触发次数 |
理解什么应该由程序层（确定性规则）处理，什么应该由龙虾层（语义理解/AI）处理，是设计秀秀 3.0 的核心原则：
| 类型 | 程序层该做 | 龙虾层该做 |
|---|---|---|
| 确定性规则 | 消息格式校验、权限检查、速率限制、Bot 选择路由 | ——（不参与，这是程序逻辑） |
| 语义理解 | ——（不做语义判断） | 理解用户意图、分析需求、判断任务类型 |
| 创建 Bot | 校验参数合法性、写入数据库、分配 ID | 理解用户对 Bot 的描述、生成 Bot 配置 |
| Loop 协同 | 控制轮数上限、传递消息、记录状态 | 每轮生成有意义的输出、保持话题连贯 |
| 文件报告 | 文件格式转换、存储、写回消息附件 | 生成报告内容、分析数据、撰写结论 |
| 异常恢复 | 重试机制、超时处理、降级策略 | 根据错误上下文调整回复策略 |
以下为本分析文档所依据的核心源码位置：
| 能力 | 函数 / 文件 |
|---|---|
| 消息发送 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 运行时 |
// === 秀秀 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