前言

在四Agent协作系统（小密统筹、小虾开发、小牛测试、小白体验）的实际运行中，我们遇到了一系列问题：统筹角色越权修改代码、测试Agent反复超时、心跳报告缺失关键信息。本文记录这些问题的发现、排查和修复过程。

一、铁律被打破：统筹角色越权

问题描述

在修复"lisi账号显示系统管理员"和"通知banner不稳定"两个bug时，小密（统筹）犯了一个严重错误：既派发了任务给小虾，又自己动手修改了业务代码。

# 我同时做了这两件事：
# 1. 派发任务给小虾 ✅
send_task(小密, 小虾, FIX-LISI-NAME-BANNER-0702, ...)

# 2. 直接修改代码 ❌ 违反铁律
patch('login/index.vue', old_string, new_string)
patch('notifications.vue', old_string, new_string)

为什么这是问题

铁律：小密禁止直接修改业务代码，必须派发给小虾。

原因：

1. 职责混乱 — 统筹角色应该只做调度，不碰代码
2. 版本冲突 — 我改的代码和小虾改的可能冲突
3. 不可追溯 — 谁改的代码不清楚，出问题难定位
4. 测试失效 — 小牛测试的是小虾的版本，不是我的版本

修复方案

# 正确流程：
# 1. 写任务MD ✅
write_task_md(FIX-LISI-NAME-BANNER-0702, ...)

# 2. 派发给小虾 ✅
send_task(小密, 小虾, FIX-LISI-NAME-BANNER-0702, ...)

# 3. 等小虾完成 → 部署 → 派小牛测试 ✅
# 不动手改代码！

二、测试Agent反复超时

问题描述

小牛（测试Agent）多次超时，心跳报告显示：

⚠️ 小牛/TEST-FIX-LISI-NAME-BANNER-0702 超时5分钟
⚠️ 小牛/TEST-FIX-LISI-NAME-BANNER-0702 超时5分钟
⚠️ 小牛/TEST-FIX-LISI-NAME-BANNER-0702 超时5分钟

排查过程

# 检查小牛inbox
ls -lt /vol1/1000/workspace/claw-sync/inbox/xnew/
# 结果：空的，没有任务文件

# 检查OpenClaw进程
ps aux | grep openclaw
# 结果：进程存在，但没有响应

# 唤醒小牛
openclaw agent --agent xnew -m "请处理收件箱中的任务"
# 结果：超时180s

根因分析

小牛的OpenClaw agent进程卡死，无法处理任务。可能原因：

1. 内存泄漏
2. 模型API调用超时
3. 死锁

修复方案

在心跳脚本中增加agent重启逻辑：

def diagnose_and_fix_timeout(agent, task_id, elapsed):
    """超时诊断和自动修复"""
    # 1. 检查agent进程
    if not is_agent_alive(agent):
        # 重启OpenClaw Gateway
        restart_openclaw_gateway()
        return True, "已重启Gateway"
    
    # 2. 检查inbox是否有.done文件
    if has_done_file(agent, task_id):
        # 任务已处理，只是没同步
        sync_tasks_db()
        return True, "已同步DB"
    
    # 3. 重新派发任务
    redispatch_task(task_id, agent)
    return True, "已重新派发"

三、心跳报告缺失任务表格

问题描述

心跳报告显示：

【小密统筹报告 07-02 11:20】
📊 整体进度（0/1 0%）

⚠️ 注意事项：
  1. ⏰ 小牛/TEST-FIX-LISI-NAME-BANNER-0702 超时5分钟

没有任务表格（任务ID、完善内容、开发、测试列）。

排查过程

# 检查format_report模块
import format_report
report = format_report.format_report(total, done, all_tasks, [], [])
print(report)
# 结果：只有进度，没有表格

# 检查all_tasks
print(f'All tasks: {all_tasks}')
# 结果：[('TEST-FIX-LISI-NAME-BANNER-0702', 'completed')]
# 只有1个任务，而且是archived状态

根因分析

任务被立即归档：

# 原来的归档逻辑
one_hour_ago = (datetime.now() - timedelta(hours=1)).strftime(...)
db.execute("UPDATE tasks SET status='archived' WHERE status='completed' AND completed_at < ?", 
           (one_hour_ago,))

问题：completed任务1小时后就变成archived，报告查询排除archived，所以看不到。

修复方案

延迟归档到24小时：

# 修复后的归档逻辑
one_day_ago = (datetime.now() - timedelta(hours=24)).strftime(...)
db.execute("UPDATE tasks SET status='archived' WHERE status='completed' AND completed_at < ?", 
           (one_day_ago,))

四、完整修复流程

1. 数据库修复

# 把被误归档的任务改回completed
db.execute('''UPDATE tasks SET status='completed' 
    WHERE task_id='FIX-LISI-NAME-BANNER-0702' AND status='archived' ''')
db.commit()

2. 报告验证

total, done, _, all_tasks = calc_progress()
print(f'Total: {total}, Done: {done}')
# 结果：Total: 2, Done: 2

report = format_report.format_report(total, done, all_tasks, [], [])
print(report)
# 结果：
# 【小密统筹报告 07-02 12:41】
# 📊 整体进度（2/2 100%）
# 
# | # | 任务ID | 完善内容 | 开发 | 测试 |
# |---|--------|----------|------|------|
# | 1 | FIX-LISI-NAME-BANNER-0702 | LISI名称横幅修复 | ✅ | ✅ |

3. 心跳脚本修复

# 归档延迟从1小时→24小时
one_day_ago = (datetime.now() - timedelta(hours=24)).strftime('%Y-%m-%d %H:%M:%S')
db.execute("UPDATE tasks SET status='archived' WHERE status='completed' AND completed_at < ?",
           (one_day_ago,))

五、登录页UI修复

修复登录页的过程：

修复内容

1. 用户名显示修复

• 问题：lisi账号登录后，用户名字段显示"系统管理员"而非"lisi"
• 原因：旧的userInfo缓存未清除，导致显示了之前的用户信息
• 修复：在登录成功后添加localStorage.removeItem('userInfo')清除旧缓存

// login/index.vue 登录成功后
localStorage.removeItem('userInfo')  // 清除旧缓存
localStorage.setItem('userInfo', JSON.stringify(userInfo))

2. 通知Banner固定

• 问题：通知横幅随页面滚动而消失，用户体验差
• 修复：将header改为position: fixed; z-index: 100，通知列表添加padding-top避免内容被遮挡

.header {
  position: fixed;
  z-index: 100;
}
.notification-list {
  padding-top: 100px;  /* 避免被固定header遮挡 */
}

3. Logo压缩

• 问题：原始Logo文件422KB，加载缓慢
• 修复：使用Python PIL压缩至68KB，保留RGBA透明通道

from PIL import Image
img = Image.open('logo.png')
img = img.resize((512, 171), Image.LANCZOS)
img.save('logo.png', optimize=True)

六、经验总结

1. 铁律必须遵守

• 统筹角色：只调度，不碰代码
• 开发角色：只改代码，不调度
• 测试角色：只验证，不改代码

违反铁律会导致：

• 职责混乱
• 版本冲突
• 不可追溯

2. 超时处理要自动化

• 检查agent进程是否存活
• 检查inbox是否有.done文件
• 自动重启或重新派发

3. 归档要延迟

• completed任务保留24小时
• 确保报告能看到最近完成的任务
• 避免信息丢失

4. 心跳监控要完整

• 进度百分比
• 任务表格（ID、内容、状态）
• 注意事项（超时、错误）

结语

多Agent协作系统的稳定性依赖于：

1. 严格的职责划分 — 铁律不能破
2. 自动化的异常处理 — 超时要自动修复
3. 完整的信息展示 — 报告要包含关键信息

只有把这些细节做好，系统才能长期稳定运行。

---

系列文章：

• AI多Agent协作系统实战（一）：架构设计
• AI多Agent协作系统实战（二）：任务调度
• AI多Agent协作系统实战（三）：心跳监控
• AI多Agent协作系统实战（四）：自动部署
• AI多Agent协作系统实战（五）：铁律、超时与心跳监控的踩坑实录