| name | message-flow-troubleshooter |
| description | 中间层消息流问题排查 - 使用两端消息排查法定位 Cursor ↔ 中间路由层 ↔ LLM 服务端通信异常，快速判定故障点并执行重启或代码修复。触发条件：客户端收不到消息、消息异常、中间层代理故障。 |
中间层消息流问题排查 Skill
适用场景
当使用中间层（如 LamaPuppeteer）代理大模型时，客户端（如 Cursor）收不到消息或消息异常。
🚀 【智能经验沉淀&极速执行规则】
1. 故障排查统一强制使用【两端消息排查法】
链路：Cursor客户端 ↔ 中间路由层 ↔ LLM-Puppeteer服务端
排查顺序固定不变：
① 校验Cursor发出原始请求报文是否正常 → 异常判定为客户端问题
② 校验LLM服务返回原生响应内容是否正常 → 异常判定为底层模型/浏览器执行层问题
③ 两端数据均正常，输出结果异常/丢包/无响应 → 直接判定为中间路由层故障
④ 判定中间层宕机/数据篡改故障后 → 立即终止深度推理，禁止长时间空想分析，优先执行重启服务动作
⑤ 重启后依旧异常 → 直接锁定中间层代码逻辑问题，定向定位修改，不再全链路盲目排查
2. 经验自动沉淀机制
所有需要长时间推理、多轮反复调试才能解决的代码问题、链路故障、对接报错，解决完成后：
- 自动精简提炼【最简固定解决步骤】
- 整理为标准化执行流程存入本地技能库
- 后续遇到同类型同源问题，直接调取沉淀好的流程执行
- 跳过试错、跳过冗余思考，优先复用成熟最优方案
3. 调试行为精简规则
- 区分调试中必要操作与无效重复操作
- 剔除无意义反复测试、随机尝试行为
- 同类问题只保留一套最高效解决路径
- 固化为行为范式，统一执行标准
4. 执行优先级
已沉淀Skill流程 > 临场自主思考
既定排错流程 > 发散分析猜测
故障既定处理动作 > 长时间逻辑推演
⚠️ 核心原则：先重启，再分析
不要浪费时间在思考上！发现问题后立即重启！
快速排查流程
第一步：立即重启中间层
# 1. 停止所有服务
cd f:\myclaw\lama-puppeteer
.\stop_all.bat
# 2. 等待 3 秒
timeout /t 3 /nobreak
# 3. 重新启动
cd f:\myclaw\lama-puppeteer
.\start_dispatcher.bat
# 4. 等待 Workers 初始化完成（30-60秒）
第二步：立即测试
- 在 Cursor 中发送一条测试消息
- 观察是否收到回复
- 观察 DeepSeek 网站是否正确返回
第三步：根据测试结果判断
- ✅ 如果恢复正常 → 问题就是中间层挂掉了，已解决
- ❌ 如果还有问题 → 排除中间层挂掉的可能，确认是代码逻辑问题，进入详细排查
🔍 详细排查步骤（仅在重启无效时使用）
第一步：对比中间层左右两侧的数据
检查点：
- 左侧数据（客户端 → 中间层）：查看中间层接收到的原始消息
- 右侧数据（中间层 → 大模型）：查看中间层发送出去的原始消息
判断标准：
- 如果左右两侧数据不一致 → 中间层修改了数据，问题出在中间层的转换逻辑
- 如果左右两侧数据一致 → 进入第二步
第二步：检查中间层是否挂掉
检查点：
- 左侧有消息，右侧没有消息 → 中间层挂了，没有转发到右侧
- 右侧有消息，左侧没有消息 → 中间层挂了，没有回传到左侧
判断标准：
实际操作步骤
1. 查看中间层接收的消息
日志位置：中间层的 debug 日志或消息调试文件
# 查看发送给大模型的消息
cd f:\myclaw\lama-puppeteer
Get-ChildItem test\message_debug -Filter "worker_sent_*.json" | Sort-Object LastWriteTime -Descending | Select-Object -First 1 | ForEach-Object { Get-Content $_.FullName -Raw | ConvertFrom-Json }
2. 查看大模型的实际回复
日志位置：中间层的 debug 日志中的 "Raw response from provider"
# 查看大模型的原始回复
cd f:\myclaw\lama-puppeteer
Get-Content logs\debug_requests.log -Tail 50 | Select-String -Pattern "Raw response from provider" -Context 2
3. 对比数据
对比内容：
- 消息角色（role）：user, assistant, tool
- 消息内容（content）：是否被修改
- 工具调用（tool_calls）：是否正确解析
示例对比：
左侧（Cursor 发送）：
role: user, content: "给我新建一个文件"
右侧（发送给 DeepSeek）：
role: user, content: "给我新建一个文件\n\n<visible_files>..."
结论：中间层添加了 <visible_files> 标签，需要过滤
4. 检查中间层状态
检查命令：
# 检查 Python 进程
Get-Process python
# 检查端口占用
netstat -ano | findstr "9091 9100"
# 查看错误日志
Get-Content logs\debug_requests.log | Select-String -Pattern "Error|Exception"
常见案例
案例 1：中间层过滤了消息
现象：客户端收到空消息
原因：中间层检测到工具调用后，清空了 content
解决：修改中间层的过滤逻辑，保留必要的消息
案例 2：中间层修改了消息格式
现象：大模型循环调用工具
原因：中间层将 tool 消息的 JSON 原样发送给大模型，大模型看不懂
解决：中间层将 tool 消息转换为自然语言（如"工具执行成功"）
案例 3：中间层进程挂掉
现象：客户端没有收到任何消息
原因：中间层进程异常退出或阻塞
解决：重启中间层服务
💡 经验总结
核心教训（从实际案例中发现）
错误做法：
- ❌ 遇到问题后花费大量时间分析和思考
- ❌ 反复查看日志、猜测原因、推导逻辑
- ❌ 陷入死循环，无法快速定位问题
正确做法：
- ✅ 发现问题 → 立即重启（只需 30 秒）
- ✅ 测试验证 → 如果好了，问题解决
- ✅ 如果还有问题 → 这时才开始分析代码逻辑
关键认知：
- 重启是最快的验证方式！
- 不要在第一步就陷入分析！先重启！
- 90% 的问题通过重启就能解决
调试要点
- 不要猜，看实际数据：直接查看中间层左右两侧的实际消息内容
- 对比是关键：通过对比快速定位是中间层改数据还是中间层挂了
- 日志是最好的朋友：
debug_requests.log 和 message_debug 文件夹包含所有关键信息
- 重启解决 90% 的问题：修改代码后一定要重启服务
- 遵循既定流程：严格执行【两端消息排查法】，不要偏离
常见问题速查
| 现象 | 原因 | 解决方案 |
|---|
| 客户端收到空消息 | 中间层过滤了消息 | 修改中间层的过滤逻辑 |
| 大模型循环调用工具 | 中间层修改了消息格式 | 将 tool 消息转换为自然语言 |
| 客户端没有任何消息 | 中间层进程挂掉 | 重启中间层服务 |
| 消息被截断 | 中间层解析出错 | 检查 XML/JSON 解析逻辑 |
📅 创建时间
2026-05-18
🔗 相关项目
LamaPuppeteer（DeepSeek 网页端代理）
