message-flow-troubleshooter

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% 的问题通过重启就能解决

调试要点

1. 不要猜，看实际数据：直接查看中间层左右两侧的实际消息内容
2. 对比是关键：通过对比快速定位是中间层改数据还是中间层挂了
3. 日志是最好的朋友：debug_requests.log 和 message_debug 文件夹包含所有关键信息
4. 重启解决 90% 的问题：修改代码后一定要重启服务
5. 遵循既定流程：严格执行【两端消息排查法】，不要偏离

常见问题速查

现象	原因	解决方案
客户端收到空消息	中间层过滤了消息	修改中间层的过滤逻辑
大模型循环调用工具	中间层修改了消息格式	将 tool 消息转换为自然语言
客户端没有任何消息	中间层进程挂掉	重启中间层服务
消息被截断	中间层解析出错	检查 XML/JSON 解析逻辑

---

📅 创建时间

2026-05-18

🔗 相关项目

LamaPuppeteer（DeepSeek 网页端代理）