一、背景

在此次调试开始前，系统已预置了一套基于文件队列的异步 Agent 编排骨架，目录为：

~/.openclaw/workspace/memory/orchestration/
├── pending/      ← main 写入待分配任务
├── running/      ← specialist 认领标记
├── results/      ← specialist 写入执行结果
├── completed/    ← specialist 写完成标记
├── watching/     ← main 监听标记
└── archive/      ← 归档

脚本骨架位于 ~/.openclaw/scripts/，协议文档写在 workspace/AGENTS.md。

二、Phase 1 — 工作流框架定义 + 初步仿真

用户需求

“WEB main 聊天框输入：各位开始干活了。→ 各 agent 推 ‘我开始工作了’ 到手机端 → agent 把调用的工具/技能汇报给 main → main 汇总并把评语推到各自机器人客户端。”

实现步骤

1. 设计事件链（Python 仿真）：

   • web_input_received → task_assigned × N → push_to_user(开工) → task_received → tool_skill_called → task_result_reported → main_summary_ready → push_review_to_agent_client

2. 运行仿真，产物：

   • archive/2026-03-29/web-main-flow-20260329-170913/workflow-test-result.json
   • 涵盖 research、mail、heartbeat 三个 specialist 的完整事件链

仿真结果摘要

{
  "runId": "web-main-flow-20260329-170913",
  "webInput": { "message": "各位开始开活了。", "source": "web-main-chat" },
  "agents": ["research", "mail", "heartbeat"],
  "eventsCount": 18
}

三、Phase 2 — Mail 工具异常 + 阶段诊断能力

用户需求

“Mail 配置好了但不能用工具，main 应有评估工具在哪个阶段异常的能力，并在总结时反馈到各自机器人。”

实现步骤

1. 创建阶段诊断脚本

文件：~/.openclaw/scripts/evaluate-orchestration-stage.sh

核心逻辑（Python 内嵌）：

• 读取 results/{PREFIX}-*_result.json
• 关键字匹配 → 映射到阶段标签：

• 生成 results/{PREFIX}_main_evaluation.json，包含：
  • stageFailures[] — 哪个 agent 在哪个阶段失败
  • pushFeedback[] — 对每个 agent 的点评消息

2. 更新 test-scenario-3.sh

Mail 的失败模拟从 IMAP timeout 改为 tool_not_available: himalaya-cli cannot invoke tool backend + command_not_found，更真实反映工具绑定缺失场景。在 Step 2.5 插入 evaluator 调用：

bash "$HOME/.openclaw/scripts/evaluate-orchestration-stage.sh" TEST-3-FAILURE-HANDLING

坑：直接执行脚本报 Permission denied（未 chmod +x），改为 bash <path> 后解决。

3. 更新 AGENTS.md 协议

在 workspace/AGENTS.md 的 “Result Collection & Aggregation” 之后，新增 Stage Evaluation & Feedback Push 节，规定 4 步：

1. 将失败结果分类到阶段标签
2. 写入 {PREFIX}_main_evaluation.json
3. 为每个 agent 生成推送消息
4. 最终汇总时附带阶段诊断

测试结果

{
  "stageFailures": [{"agent":"mail","stage":"tool_invoke","diagnosis":"工具调用阶段异常"}],
  "pushFeedback": [
    {"agent":"heartbeat","status":"ok"},
    {"agent":"mail","status":"degraded","message":"...工具调用阶段异常...请检查工具安装/配置权限..."},
    {"agent":"research","status":"ok"}
  ],
  "summary": {"total":3,"success":2,"failed":1,"health":"degraded"}
}

四、Phase 3 — 全流程重测（含用户可感知状态推送）

用户需求

“开始对全流程编排任务重新测试。从分配工作，到接收，进行的工作，并结果反馈。通过推送让用户可感知各个 agent 的工作状态。”

产物

archive/2026-03-29/full-flow-20260329-091640/status-stream.jsonl：31 个事件，包含完整状态流：

web_input_received
  └─ task_assigned × 3
      └─ push_to_user(开始执行) × 3
          └─ task_received × 3
              └─ tool_skill_called × 3
                  └─ push_to_user(执行进度) × 3
                      └─ task_result_reported × 3
                          └─ main_summary_ready
                              └─ push_to_user(汇总)
                                  └─ push_review_to_agent_client × 3

archive/2026-03-29/full-flow-20260329-091640/final-summary.json：

{
  "totals": {"assigned":3,"received":3,"success":2,"failed":1},
  "mainSummary": "本轮全流程编排已完成：research、heartbeat 成功；mail 在 tool_invoke 阶段异常。",
  "stageFailures": [{"agent":"mail","stage":"tool_invoke"}]
}

五、Phase 4 — 真实渠道三阶段推送打通

用户需求

“开始吧，我在WEB端输入：各位开始干活了。手机不同的IM客户端就应能推送工作状态，直到工作结束。”

推送渠道配置

推送命令模板

openclaw agent --agent main \
  --message "<内容>" \
  --deliver \
  --reply-channel <channel> \
  --reply-to <target> \
  --thinking off --timeout 45 --json

三阶段推送结果

六、调试过程关键问题与解决

问题 1：脚本 Permission Denied

现象：~/.openclaw/scripts/evaluate-orchestration-stage.sh 直接调用时报 Permission denied
原因：脚本未执行 chmod +x
解决：调用方式改为 bash "$HOME/.../evaluate-orchestration-stage.sh" — 无需执行位

问题 2：Python snippet 批量调用被 Cancelled

现象：单个 Python 代码片段中串行发起 3 个以上 subprocess.run() 时，第 3 个及之后的调用被 request cancelled
原因：Python runner 的执行上下文对长时间阻塞的批量调用存在取消限制
解决：每次只做一个渠道的 delivery 调用，拆成独立 snippet 执行

问题 3：QQBot / 微信"已结束"阶段超时（exit=124）

现象：subprocess.run(..., timeout=25) 超时退出
根因分析：

• 网关日志（/tmp/openclaw/openclaw-2026-03-29.log）确认 sessions_send 已被调用
• [qqbot-api] >>> Body: {...} 已记录，说明推送到了渠道层
• 超时是因为 QQBot/WeChat 的 delivery ACK 返回时间 > 25s，不是路由失败

解决：subprocess timeout 从 25s 提高到 55s，全部成功

问题 4：消息格式选择

背景：用户要求 QQBot、微信推送内容"简单点，原样输出 JSON，只是一个提醒"
最终格式：原始 JSON 字符串，不加 emoji 或自然语言包装：

{"status":"已结束","runId":"live-finish-20260329-xxxxxx","summary":{"research":"ok","heartbeat":"ok","mail":"tool_invoke_error"}}

七、最终文件清单

核心脚本（~/.openclaw/scripts/）

协议文档

运行存档（workspace/memory/orchestration/archive/2026-03-29/）

八、任务状态生命周期（最终确认）

pending/{specialist}_{taskId}.json
    ↓ [specialist reads & claims]
running/{taskId}          ← 认领标记
    ↓ [specialist executes]
results/{taskId}_result.json
    ↓ [specialist reports completion]
completed/{taskId}        ← 完成标记
    ↓ [main evaluates stages]
results/{PREFIX}_main_evaluation.json
    ↓ [main pushes feedback to each channel]
archive/{YYYY-MM-DD}/{runId}/

九、关键结论

1. 文件队列协议可靠：基于文件系统的 pending→running→results→completed 状态机在所有测试场景均正确运行。

2. 阶段诊断有效：evaluate-orchestration-stage.sh 能准确区分 tool_invoke vs provider_connect vs execution 三类失败，并生成可直接推送的 per-agent 反馈。

3. 三渠道全部打通：飞书、QQBot、微信在开工/执行中/已结束三阶段均成功接收 JSON 推送（exit=0），用户手机可全程感知 agent 工作状态。

4. 推送超时根因明确：QQBot/微信 delivery ACK 慢（>25s），非路由故障，subprocess timeout ≥ 55s 可稳定解决。

5. 消息格式保持原始 JSON：推送内容定位为"提醒"，具体执行结果取决于 agent 本地工具/技能定义，不在推送消息中展开。