一、总览结论
秀秀 3.0 的任务回复不是一个单点函数完成，而是"消息入库 → 任务事件 → 队列消费 → 龙虾语义生成 → 程序层校验/执行动作 → 消息回写 → 行首 @ 继续派发 → 前端轮询展示"的链路。
当前源码里，普通 Bot 回复、替身确认后的复杂执行、002 方案、001 配置、自测、Loop 协同发言，原则上都会进入 openclaw_agent_reply，也就是进入龙虾模块。程序层只做可确定的控制：入库、权限、@选择、数量冲突、确认工单、任务去重、派发防串台、001 动作落库、超时重试、最终消息写回。
不进入龙虾的主要场景是：模糊 @ 拦截、数量冲突拦截、未确认前的标准工单兜底、远端 Bot 转发给其它服务器、历史重复/空回复抑制、部分 001 配置动作兜底。
二、三模块职责图
秀秀模块
入口存储展示
负责电脑端/手机端发消息、上传附件、展示消息、消息已读；后端负责 API、数据库、Bot 注册、群组、任务事件和可见回复写入。
依据：web/web.js:2757-2815、app/mobile.js:1897-1955、standalone.py:23878-23895、standalone.py:24225-24230。
链接模块
跨服OpenAPIRelay
负责远端 Bot 的路由、公司服务器之间的消息中继、OpenAPI Bot 发消息/拉取被 @ 消息。它决定"本机处理"还是"发到目标服务器处理"。
依据：standalone.py:4475、standalone.py:22865-22940、standalone.py:23015-23019。
龙虾模块
语义理解Agent 工作区动态回复
负责每个 OpenClaw Bot 的语义理解、方案生成、协同回复、隐藏动作协议输出、长期工作区资料承接。
依据：standalone.py:18456-18892、standalone.py:18997-19000。
三、立大志服务器原始位置
以下路径是从立大志服务器 ubuntu@101.42.116.193 当前运行环境读取到的真实位置。本报告后续每一步的"服务器原始位置"均以这些路径为基准。
| 对象 | 立大志服务器原始位置 | 用途 | 确认依据 |
|---|---|---|---|
| 秀秀 3.0 部署根目录 | /opt/xiuxiu3-open-source | 三模块源码、前端资源、下载目录、运行入口所在目录。 | systemctl cat xiuxiu3-web 与 xiuxiu3-bridge 的 WorkingDirectory 均指向此处。 |
| 核心后端源码 | /opt/xiuxiu3-open-source/xiuxiu3_core/standalone.py | 消息入口、任务队列、替身工单、批量创建、Loop、OpenClaw 调用、回复回写、跨服路由主要逻辑。 | 远端 hash：0d5759d243fa99f4e0067eea03c3337022047768d09617c97d208bbe219b79d2 |
| 电脑端前端源码 | /opt/xiuxiu3-open-source/web/web.js | 电脑网页端消息发送、消息拉取、引用、附件和 mention metadata。 | 远端文件存在，服务静态路径 /web 映射到 ROOT_DIR/"web"。 |
| 手机端前端源码 | /opt/xiuxiu3-open-source/app/mobile.js | 手机端消息发送、消息拉取、附件和行首 mention metadata。 | 远端文件存在，服务静态路径 /app 映射到 ROOT_DIR/"app"。 |
| 配置文件源码 | /opt/xiuxiu3-open-source/xiuxiu3_core/config.py | 读取 XIUXIU3_SERVER_ID、XIUXIU3_DB_PATH、XIUXIU3_PUBLIC_BASE_URL。 | 源码 config.py:6-12。 |
| 数据库连接源码 | /opt/xiuxiu3-open-source/xiuxiu3_core/db.py | SQLite 连接、WAL 模式、基础表结构。 | 源码 db.py:12-19、db.py:22+。 |
| 运行环境配置 | /etc/xiuxiu3.env | 立大志当前 XIUXIU3_SERVER_ID=company-d-lidazhi，XIUXIU3_DB_PATH=/var/lib/xiuxiu3/xiuxiu3.db，OPENCLAW_CLI=/usr/bin/openclaw。 | 远端读取环境文件，只摘录非密钥字段。 |
| 秀秀 Web/API 服务 | /etc/systemd/system/xiuxiu3-web.service | 启动网页/API：/usr/bin/python3 -m xiuxiu3_core.runtime.web_api --host 0.0.0.0 --port 18303。 | 远端 systemctl cat xiuxiu3-web。 |
| 链接/任务桥接服务 | /etc/systemd/system/xiuxiu3-bridge.service | 启动任务 worker/桥接：/usr/bin/python3 -m xiuxiu3_core.runtime.bridge_worker，并连接 OpenClaw gateway 端口 18790。 | 远端 systemctl cat xiuxiu3-bridge。 |
| 龙虾 OpenClaw Gateway 服务 | /etc/systemd/system/openclaw-xiuxiu3-root-gateway.service | 启动龙虾网关：/usr/bin/openclaw gateway run --bind loopback --port 18790 --auth none --allow-unconfigured。 | 远端 systemctl cat openclaw-xiuxiu3-root-gateway。 |
| SQLite 业务数据库 | /var/lib/xiuxiu3/xiuxiu3.db | 保存用户、Bot、群组、聊天记录、任务事件、审计、文件元数据等。 | 远端 /etc/xiuxiu3.env 的 XIUXIU3_DB_PATH。 |
| 附件上传目录 | /var/lib/xiuxiu3/uploads | 聊天附件实际存储目录；网页通过 /uploads/... 访问。 | 源码 standalone.py:454-480，实际目录远端存在。 |
| Bot 独立龙虾工作区根目录 | /var/lib/xiuxiu3/openclaw-agents/company-d-lidazhi/<bot_id> | 每个 Bot 的 workspace、agent、SOUL.md、MEMORY.md 等长期资料。 | 源码 standalone.py:1381-1385，远端目录存在。 |
| 002 创建方案归档目录 | /var/lib/xiuxiu3/openclaw-agents/company-d-lidazhi/_002_bot_creation_files | 002 输出的 Bot 创建方案、配置材料、批次归档。 | 源码 standalone.py:1405-1413，远端目录存在。 |
| 报告页下载目录 | /opt/xiuxiu3-open-source/downloads/bot-reports | 长内容报告页、最终汇总在线查看页面。 | 源码 standalone.py:5266、standalone.py:5500，远端目录存在。 |
| 秀秀服务日志 | /var/log/xiuxiu3/web.log、/var/log/xiuxiu3/bridge.log | Web/API 与 bridge/worker 运行日志。 | systemd 服务的 StandardOutput/StandardError。 |
| 龙虾网关日志 | /var/log/openclaw-xiuxiu3/root-gateway.log | OpenClaw gateway 运行日志。 | systemd 服务的 StandardOutput/StandardError。 |
四、完整前后逻辑关系图
1. 用户发消息电脑端或手机端发送正文、引用、附件、mention metadata。
2. 秀秀 API 接收
POST /api/im/messages 校验用户身份并调用统一入口。3. 消息入库
send_im_message 先保存 chat_messages，引用内容也保留。4. 选择执行 Bot按私聊 Bot、群聊行首 @、前端 mention、确认工单、远端 Bot 分支。
5. 创建任务事件
create_task_event 写 task_events，补充批量创建、数量冲突、原子链路元数据。6. 队列执行
BOT_TASK_QUEUE 由 worker 拉取，进入 process_bot_task。7. 程序层前置检查锁、任务状态、替身确认、数量冲突、用户插队暂停 Loop。
8. 龙虾语义生成
bot_reply 对 openclaw Bot 调 openclaw_agent_reply。9. 回复校验修复结构化计划、工单、批量创建、Loop、短回复、空回复、文件协议、001 动作。
10. 可见消息写回
bot_insert_message 写入 Bot 回复，并沉淀长期交互记忆。11. 行首 @ 派发解析 Bot 回复中的行首 @，生成下一段 Bot 任务，继续队列。
12. 前端展示前端轮询
GET /api/im/messages，渲染最新回复。五、逐步链路详解
| 步骤 | 所在模块 | 源码依据与立大志原始位置 | 通过时怎么走 | 不通过/异常时怎么走 | 是否进入龙虾 |
|---|---|---|---|---|---|
| 1. 用户发消息 | 秀秀前端 | /opt/xiuxiu3-open-source/web/web.js:2757-2815/opt/xiuxiu3-open-source/app/mobile.js:1897-1955 |
电脑端和手机端都会先读取输入框正文；如果有附件，先调 /api/files/upload 上传，再把附件列表写进消息 metadata。最终提交给 /api/im/messages 的核心字段包括：conversation_type、conversation_id、target_id、sender_type=user、sender_id、content、quote、mention_targets。通俗说，前端不是只发一段文字，而是把"谁发的、发到哪个窗口、是否引用、是否带附件、真正 @ 了谁"一起交给后端。 |
如果附件上传或消息接口失败，前端会撤掉临时显示的乐观消息，并把原输入恢复或显示"发送失败"。这一步失败时，后端没有消息入库，也不会产生 Bot 任务。 | 否，只负责提交。 |
| 2. 秀秀 API 接收 | 秀秀核心服务 | /opt/xiuxiu3-open-source/xiuxiu3_core/standalone.py:23952-23987/opt/xiuxiu3-open-source/xiuxiu3_core/standalone.py:24225-24230/opt/xiuxiu3-open-source/xiuxiu3_core/standalone.py:425-438/opt/xiuxiu3-open-source/xiuxiu3_core/standalone.py:22015-22020服务入口： /etc/systemd/system/xiuxiu3-web.service |
后端 do_POST 先解析 JSON。登录、注册、OpenAPI Bot 接口是独立入口；普通消息接口会先通过 require_key 得到当前调用者 actor。如果请求头里有有效 X-Xiuxiu-Session，actor 是 user:<当前登录用户ID>；如果是管理员 key，则是 admin；如果是服务器 API key，则是对应 server_id。当 sender_type=user 时，系统用 require_actor_user_match 比对 actor 和 payload 里的 sender_id：登录的是 U3，就只能以 U3 发消息。这一步的理由是防止前端或接口伪造别人账号发消息。 |
如果没有有效 session/key，会返回 invalid key；如果 actor=user:u3 但 payload 写 sender_id=u1，会抛出"只能使用当前登录账号发送消息"。这类失败发生在调用 send_im_message 之前，所以不会入库、不会建任务、不会进龙虾。 |
否。 |
| 3. 消息入库 | 秀秀核心服务 | /opt/xiuxiu3-open-source/xiuxiu3_core/standalone.py:23001-23006/opt/xiuxiu3-open-source/xiuxiu3_core/standalone.py:22952/opt/xiuxiu3-open-source/xiuxiu3_core/standalone.py:22764-22793数据库： /var/lib/xiuxiu3/xiuxiu3.db |
send_im_message 的第一步是 augment_quote_mention_targets(payload)，然后才 insert_chat_message(payload)。通俗说，如果你引用了一条旧工单后只回复"确认执行"，新消息正文很短，但引用里的 quote.content 可能包含完整的 @替身BOT 创建... 需求。系统会先把引用里能确定的 mention 目标补到当前消息 metadata，再把正文、引用、附件、metadata 一起写进 chat_messages。这样排查时能看到：content=确认执行，同时 quote.content=原始完整工单，不会只剩一个孤立短句。 |
如果 payload 带 metadata.replicated_from，表示这是跨服复制过来的消息。系统只保存展示，不再继续派发，避免 A 服务器同步到 B、B 又触发 Bot 再同步回 A 的循环。入库失败则整条消息链停止。 |
否。 |
| 4. 选择执行 Bot | 秀秀核心 + 链接模块 | /opt/xiuxiu3-open-source/xiuxiu3_core/standalone.py:23008-23153远端入口： route_remote_bot_from_source；pending 工单表：/var/lib/xiuxiu3/xiuxiu3.db 的 task_events |
这一阶段的核心问题是"这条消息应该交给谁"。私聊 Bot 时，系统从 target_id 或 conversation_id=bot_xxx 拆出 bot_id，查 bots 表确认 Bot 存在、未删除、已启用；如果 Bot 属于当前服务器，就准备创建本地任务；如果 bot.server_id 不是当前服务器，就走链接模块 route_remote_bot_from_source，由对端服务器处理。群聊时，系统先看前端 metadata 里的真实 mention_targets，再看正文行首 @，这样可以避免显示文本、复制引用、输入法导致的 @ 识别偏差。没有明确 @ 但用户回复"确认执行"时，系统会查当前群是否存在唯一待确认工单；唯一时自动路由到对应替身，并把 pending 工单原文带回后续任务。 |
如果 Bot 不存在、被删除或禁用，不会创建任务；如果群聊 @ 命中多个相似名称，会由替身输出模糊 @ 拦截，避免串台；如果"确认执行"对应的待确认工单不是唯一，会返回确认歧义提示；如果远端路由失败，会写入"跨服调用失败"。这些失败分支的共同点是：在目标不清楚或目标不可用时，不把任务交给龙虾自由猜。 | 本地可执行 Bot 后续会进入；远端 Bot 由对端服务器决定。 |
| 5. 创建任务事件 | 秀秀核心服务 | /opt/xiuxiu3-open-source/xiuxiu3_core/standalone.py:5844-5888写入： /var/lib/xiuxiu3/xiuxiu3.db |
第 4 步是"选人"，第 5 步是"登记成正式后台任务"。只有第 4 步确认目标是本地可执行 Bot 后，才调用 create_task_event 写 task_events。任务记录包含 task_id、来源类型 source_type、来源 ID、目标 Bot、会话类型、会话 ID、任务正文、状态和 metadata。这里还会做程序层可确定的抽取：批量创建时写入 batch_bot_creation、Bot 清单、当前项、原始需求；数量不一致时写 batch_bot_count_conflict；所有任务都会通过原子链路 metadata 记录当前任务身份，方便后续防重复、防串台、回到原替身。 |
如果检测到同会话有新的批量创建任务，会作废冲突旧批次，避免旧链路继续往下跑；如果任务重复或已经存在等价 queued/running 项，会防止重复入队。数量冲突类任务虽然会登记，但后续前置检查会直接拦截，不派 002/001。 | 否，任务事件只是执行凭据。 |
| 6. 队列执行 | 秀秀核心服务/桥接运行进程 | /opt/xiuxiu3-open-source/xiuxiu3_core/standalone.py:7540-7554、:14217-14251运行服务： /etc/systemd/system/xiuxiu3-bridge.service |
enqueue_bot_task 只把 task_id 放进内存队列 BOT_TASK_QUEUE，完整任务内容仍在数据库 task_events。这样 API 可以快速返回，不需要等龙虾、创建 Bot、自测、Loop 全部做完。xiuxiu3-bridge.service 常驻运行 worker 线程，循环从队列取 task_id，然后调用 process_bot_task(item) 真正执行。通俗说，前面是登记工单，这里是后台工人开始领工单。 |
如果队列 2 秒内没有任务，worker 不空转，会做维护：轮询 pending 任务、恢复卡在 running 的 OpenClaw 任务、恢复失败 batch loop、执行 batch watchdog、发送超时通知。这些维护逻辑是为了避免服务重启、龙虾超时、某一步漏派发后任务永久停住。 | worker 内部决定。 |
| 7. 程序层前置检查 | 秀秀核心服务 | /opt/xiuxiu3-open-source/xiuxiu3_core/standalone.py:13364-13439/opt/xiuxiu3-open-source/xiuxiu3_core/standalone.py:10350-10361worker 日志： /var/log/xiuxiu3/bridge.log |
worker 拿到 task_id 后先 claim_task_event 认领任务，防止多个 worker 重复执行；再校验目标 Bot 是否存在、是否启用；接着获取同 Bot 同会话锁，保证一个 Bot 在一个窗口内同一时间只处理一个任务，避免龙虾 session 混乱、旧任务续写和 session file locked。随后补齐 current_task_id、source_type 等 metadata，对批量创建当前项做文本/metadata 对齐；如果用户中途插入新任务，会暂停活动 Loop，优先处理新消息。最后检查批量创建数量冲突，例如声明创建 4 个但列出 5 个，程序层会直接生成冲突提示，记录 declared_bot_count 和 parsed_bot_count。 |
任务不存在或已被领取则结束；Bot 不存在/禁用则标记 failed；会话锁占用则以 same_bot_session_busy 延迟重排队；数量冲突则写可见提示并结束，不派 002/001、不创建 Bot。理由是这些都是程序能确定的安全问题，不能交给语义层猜。 |
否，属于可确定程序层拦截。 |
| 8. 龙虾语义生成 | 龙虾模块 | /opt/xiuxiu3-open-source/xiuxiu3_core/standalone.py:18997-19000/opt/xiuxiu3-open-source/xiuxiu3_core/standalone.py:18456-18608/opt/xiuxiu3-open-source/xiuxiu3_core/standalone.py:18631-18646CLI： /usr/bin/openclaw；Bot 工作区：/var/lib/xiuxiu3/openclaw-agents/company-d-lidazhi/<bot_id>/workspace |
前置检查通过后，bot_reply 判断 Bot 类型。只有 kind=openclaw 才进入 openclaw_agent_reply；系统不会用本地固定话术替代未绑定龙虾的 Bot。进入龙虾前会准备每个 Bot 自己的绑定目录、workspace、agent，同步 OpenClaw 注册，并组装完整 prompt：长期人设、SOUL.md/USER.md/ASSISTANT.md/AGENTS.md/MEMORY.md、公司资料、账号资料、群成员、当前任务、引用/附件、批量创建上下文、Loop 上下文、任务隔离规则、001/002/替身规则等。然后写临时 message 文件，执行 openclaw agent --agent ... --session-id ... --message-file ... --json --timeout ...。 |
如果 Bot 不是 openclaw 类型，直接返回"未绑定龙虾秀秀Agent"；如果是创建/配置/附件/文件/交接任务，会强制独立 session 并清空历史，降低串台；如果 OpenClaw 进程超时、session locked、上下文溢出，进入后续异常恢复和重试流程。 | 是。 |
| 9. 回复校验修复 | 秀秀核心服务 | /opt/xiuxiu3-open-source/xiuxiu3_core/standalone.py:18779-18892/opt/xiuxiu3-open-source/xiuxiu3_core/standalone.py:13892-14059/opt/xiuxiu3-open-source/xiuxiu3_core/standalone.py:13057文件/报告输出： /opt/xiuxiu3-open-source/downloads/bot-reports；附件上传：/var/lib/xiuxiu3/uploads |
龙虾返回后不是马上显示，而是先验收。系统会提取 OpenClaw 输出，必要时从 trajectory 恢复更完整回复；遇到上下文溢出会自动构造压缩 prompt 换 session 重试；遇到 memory/LLM timeout 会抛重试。拿到回复后，程序层继续应用替身结构化计划、确认工单、批量创建入口、Loop 入口、不能提前最终交付、短句"收到"修复、只有 @ 重试、空回复重试、文件任务校验、报告页归档、XIUXIU3_FILE 附件协议、XIUXIU3_ACTION 配置动作执行。001 如果只说"等待配置"但没有动作协议，程序层会尝试生成配置动作兜底。 |
如果龙虾回复为空、只有 @、明显旧任务续写、上下文溢出、模型超时，会静默重试或返回可追踪失败原因；如果替身应该先出确认工单却越过确认直接执行，程序层会替换为标准工单；如果批量创建还没全部完成就最终汇总，会被拦截修正。理由是：内容由龙虾生成，但流程边界、确认门槛和落库动作必须由程序层保证。 | 龙虾已返回，程序层验收。 |
| 10. 可见消息写回 | 秀秀核心服务 | /opt/xiuxiu3-open-source/xiuxiu3_core/standalone.py:14148-14155/opt/xiuxiu3-open-source/xiuxiu3_core/standalone.py:7505-7533/opt/xiuxiu3-open-source/xiuxiu3_core/standalone.py:2115写入： /var/lib/xiuxiu3/xiuxiu3.db 的 chat_messages |
回复通过校验后，系统调用 bot_insert_message 把 Bot 可见回复写回 chat_messages。写入时会带上 source_task_id、workflow、附件 metadata、报告页链接、原子链路信息等，方便之后从聊天消息追溯到后台任务。随后调用长期交互沉淀逻辑，把本次任务和回复写入 Bot 长期记忆/工作区相关资料。通俗说，这一步才是你在聊天窗口里最终能看到 Bot 回复的入库点。 |
不是所有龙虾返回都会写可见消息。后台三轮自测聚合任务可能只用于批次验收，不单独刷屏；Bot 来源的待命/空结果会被抑制；重复最终交付会被跳过；异常失败会写入带 error metadata 的失败消息。这样做是为了减少重复回复、短句干扰和旧任务补发。 | 否，回到秀秀展示层。 |
| 11. 行首 @ 继续派发 | 秀秀核心服务 | /opt/xiuxiu3-open-source/xiuxiu3_core/standalone.py:11350-11835新任务继续写入 /var/lib/xiuxiu3/xiuxiu3.db 的 task_events |
Bot 消息写回后，如果是群聊并且回复中存在行首 @，系统会解析目标 Bot，再为下一位 Bot 创建新的 task_events 并入队。派发会继承批量创建、Loop、source_task_id、source_message_id、当前轮次、当前参与人、派发深度等 metadata；还会生成幂等 key，防止同一条回复重复派发。批量创建时，替身派 002、002 回替身、替身派 001、001 回替身、替身推进下一个，都是靠这一步把可见 @ 转成后台任务。 |
如果消息 metadata 设置 suppress_mention_dispatch，不会派发；如果达到深度 30，会停止，避免无限循环；如果检测到重复 dispatch key，会跳过；在 substitute_collaboration_loop 下，业务 Bot 不允许横向 @ 其它业务 Bot，只能回主持/替身，防止 Loop 跑乱；如果 001/002 忘记行首 @ 回替身，部分 rescue 逻辑会尝试补派回源替身。 |
下一位 Bot 任务执行时再进入。 |
| 12. 前端展示 | 秀秀前端 | /opt/xiuxiu3-open-source/web/web.js:1913-1986、/opt/xiuxiu3-open-source/app/mobile.js:1264-1324、/opt/xiuxiu3-open-source/xiuxiu3_core/standalone.py:23878-23895 |
前端不会直接从 worker 收回复，而是持续按当前会话调用 GET /api/im/messages。后端 list_messages 从 chat_messages 读取消息，解析 quote 和 metadata，补齐 Bot 名称、用户名称、头像、已读数等；前端拿到后合并本地缓存、渲染消息气泡、滚动到底部并提交已读。通俗说，Bot 回复只有先在第 10 步写进数据库，这一步才能被用户看到。 |
如果用户快速切换会话，前端使用 conversationSwitchSeq 和当前会话 ID 检查，防止旧会话的请求结果覆盖新窗口；如果当前没有会话，会显示空状态；如果消息被后端抑制或还在后台队列中，前端只能看到用户原消息，直到 Bot 回复写回。 |
否。 |
六、业务功能链路
1. 普通 @Bot 问答
用户在群里行首 @ 某个 Bot，秀秀通过 metadata 或正文选择目标 Bot，创建任务事件。worker 执行时调用 OpenClaw，龙虾根据 Bot 长期人设、公司资料、当前消息、相关历史生成回复。回复经空回复、短回复、旧任务续写、文件协议等校验后写回群里。
进入龙虾正常进入。只有 Bot 未绑定、禁用、@模糊、被防重复拦截时不进入。
2. 替身确认工单
替身收到需要确认的任务时，程序层会保证"先工单、后执行"。未确认时生成 awaiting_confirmation 任务；用户回复"确认执行"后，秀秀把 pending 工单原文合并到新任务 metadata 中，避免只把"确认执行"发给龙虾。
进入龙虾确认后进入。未确认工单兜底不进入。
3. 批量创建 Bot
创建任务先由程序层抽取 Bot 清单、职责、后续 Loop 和数量一致性。未确认时替身输出标准执行工单；确认后替身串行派 002。002 只输出当前一个 Bot 的完整方案，回报替身；替身审核通过后派 001；001 必须输出 XIUXIU3_ACTION configure_bot，由秀秀服务器落库创建、拉群、绑定 OpenClaw Agent，并触发轻量自测。
进入龙虾002/001/替身审核和业务 Bot 自测均按 OpenClaw Bot 执行；001 的落库动作由程序层执行。
4. 数量不一致
如果用户说"创建 4 个 Bot"，但后文具体列了 5 个，当前逻辑属于 batch_bot_count_conflict：程序层拦截，记录声明数量和解析数量，要求用户确认最终清单，不派发 002/001，不创建 Bot。
不进入龙虾这是明确可判断的安全拦截，避免语义层按错误数量继续执行。
5. 创建完成后的 Loop 协同
批量创建全部完成后，系统从原始需求中抽取后续协同主题，生成 substitute_collaboration_loop 元数据。替身按参与 Bot 顺序和轮次逐个行首 @ 派发。业务 Bot 只回报替身，替身验收后推进下一位，全部轮次完成后由替身汇总。
进入龙虾每一位业务 Bot 发言和替身汇总都进入龙虾，程序层负责轮次、下一位和防横向串台。
6. 用户中途插入新任务
worker 前置阶段会调用用户插队暂停逻辑。新用户消息优先，活动协同 Loop 被暂停，避免替身继续旧链路无视用户新指令。后续是否恢复，依赖 pending/metadata 和用户再次确认或派发。
进入龙虾新任务按正常入口进入；旧 Loop 暂停是程序层控制。
7. 附件、文件和报告页
前端先上传附件，消息 metadata 带附件列表。龙虾 prompt 中会追加附件隐式内容。若 Bot 输出 XIUXIU3_FILE，秀秀程序层保存为聊天附件；长报告会被整理为在线报告页链接，最终回复只展示概要和真实下载/查看地址。
进入龙虾附件理解进入；文件落盘和报告页生成由秀秀程序层执行。
8. 长期记忆和工作区
每个 OpenClaw Bot 进入龙虾前都会准备独立工作区和 Agent 目录，并要求读取 SOUL.md、USER.md、ASSISTANT.md、AGENTS.md、MEMORY.md。回复完成后调用长期交互沉淀逻辑，保证 Bot 有自己的长期资料。
进入龙虾工作区和记忆作为 Prompt 上下文进入，沉淀由程序层写入。
9. 跨服务器 Bot
私聊 Bot 如果归属服务器不是当前服务器，send_im_message 不会在本机执行 OpenClaw，而是进入 route_remote_bot_from_source。远端服务器接收后按自己的秀秀/龙虾链路处理，再通过链接模块回流。
本机不进入龙虾目标服务器是否进入龙虾由目标服务器自己的 Bot 绑定和运行状态决定。
七、程序层与龙虾层边界
| 类型 | 程序层负责 | 龙虾层负责 |
|---|---|---|
| 确定性规则 | 消息入库、权限、Bot 选择、任务事件、队列、去重、数量冲突、确认状态、行首 @ 派发、Loop 轮次、001 动作执行。 | 不负责这些数据库和调度动作。 |
| 语义理解 | 只做基础抽取和兜底，不应替代复杂语义。 | 完整理解用户原始消息，输出方案、拆解、业务回复、医学/招聘/售后等内容。 |
| 回复稳定性 | 校验龙虾返回是否空、只有 @、短句、旧任务续写、提前终稿、漏派发；必要时重试或兜底。 | 生成主体内容，并遵守 prompt 中的任务边界和回报格式。 |
| Bot 创建 | 解析锁定清单、执行 XIUXIU3_ACTION、落库、入群、绑定、自测、推进下一个。 |
002 生成方案，001 输出隐藏动作协议，替身审核和汇总。 |
八、关键异常与处理
| 异常 | 根因位置 | 当前处理方式 |
|---|---|---|
| Bot 没回复 | 可能卡在任务队列、Bot 禁用、同会话锁、OpenClaw 超时、上下文溢出、消息被抑制。 | worker 维护任务会恢复 stuck running、失败 batch loop、超时任务；OpenClaw 异常会重试或生成失败原因。 |
| 回复很短或只有"收到" | 龙虾返回 thin ack，或业务 Bot 非动作回执。 | repair_substitute_thin_summary_ack、enforce_received_only_visible_reply、空回复/只有 @ 重试、trajectory 恢复。 |
| Loop 跑乱或横向派发 | Bot 回复中行首 @ 指向了非主持/替身业务 Bot。 | dispatch_line_start_mentions_from_bot_reply 在 substitute_collaboration_loop 下禁止业务 Bot 横向派发，只允许回替身/主持。 |
| 主题抽取别扭 | 后续 Loop 主题如果直接继承原始创建指令，会把"创建 Bot 的长文本"当成协同主题。 | 当前派发链路使用 effective_post_batch_loop_topic、extract_post_batch_loop_topic 和结构化计划里的 task_subject/task_action/post_task 做主题收敛。 |
| openclaw_context_overflow | OpenClaw 上下文过长或历史/附件/批量信息合并后超过模型窗口。 | 自动构造压缩 prompt 并使用独立 compact session 重试；001 配置类可降级生成动作协议。 |
| 数量不一致 | 声明数量和枚举清单数量冲突。 | 程序层直接拦截，要求用户确认最终清单，不让 002/001 创建。 |
九、是否通过龙虾模块的判定表
| 任务场景 | 是否进入龙虾 | 原因 |
|---|---|---|
| 私聊本地 openclaw Bot | 是 | 任务入队后 bot_reply 调 openclaw_agent_reply。 |
| 群聊行首 @ 本地 Bot | 是 | 选中 Bot 后创建 task，worker 调 OpenClaw。 |
| 替身首次收到复杂任务但需确认 | 通常否 | 程序层先出标准工单，等待确认，防止直接执行。 |
| 用户确认执行后的替身任务 | 是 | 合并 pending 原始需求，确认后交龙虾理解并继续派发。 |
| 002 创建方案 | 是 | 002 是独立 openclaw Bot，方案应由龙虾动态生成。 |
| 001 配置顾问 | 是 | 001 先由龙虾输出 XIUXIU3_ACTION；程序层再执行动作。OpenClaw 失败时才兜底。 |
| 新建普通业务 Bot 简单自测 | 是 | 新 Bot 需通过自己的 OpenClaw Agent 完成轻量职能回复。 |
| Loop 协同每一位发言 | 是 | 每个参与 Bot 都独立进入自己的 Agent 工作区生成内容。 |
| 模糊 @ | 否 | 程序层直接拦截，避免串台。 |
| 数量冲突 | 否 | 程序层直接拦截，避免按错误清单执行。 |
| 远端 Bot | 本机否，对端可能是 | 本机通过链接模块路由，对端服务器按自己的链路进入龙虾。 |
十、源码证据清单
- 电脑端发消息/拉消息：
/home/halo/xiuxiu3-open-source/web/web.js:1913-1986、:2757-2815 - 手机端发消息/拉消息：
/home/halo/xiuxiu3-open-source/app/mobile.js:1264-1324、:1897-1955 - HTTP 消息接口：
/home/halo/xiuxiu3-open-source/xiuxiu3_core/standalone.py:23878-23895、:24225-24230 - OpenAPI Bot 发消息/拉取被 @ 消息：
standalone.py:22865-22940 - 统一消息入口：
standalone.py:23001-23154 - 任务事件创建：
standalone.py:5844-5888 - 任务队列和 worker：
standalone.py:7540-7554、:14217-14251 - 任务执行主链：
standalone.py:13364-14185 - 替身批量创建/确认工单：
standalone.py:10183-10376 - 行首 @ 派发和 Loop 继承：
standalone.py:11350-11835 - 龙虾 OpenClaw 调用：
standalone.py:18456-18892 - Bot 回复入口：
standalone.py:18997-19000
十一、当前链路仍需关注的边界
从源码看，当前设计已经把"确定性控制"和"语义生成"分开：程序层不应该替代龙虾理解复杂任务，但必须拦住确定性风险。真正需要持续关注的是 OpenClaw 运行态稳定性，包括 session locked、上下文溢出、模型超时、trajectory 恢复失败，以及跨服时对端服务是否同步了相同版本和 Agent 绑定。
如果现场出现"没有回复"，排查顺序应是：查 chat_messages 是否入库 → 查 task_events 当前状态和 metadata → 查 worker 是否消费 → 查 OpenClaw 返回/错误原因 → 查是否被 suppress/duplicate/final delivery 拦截 → 查前端是否拉到最新消息。