# Message Flow Troubleshooter

> 中间层消息流问题排查 - 使用两端消息排查法定位 Cursor ↔ 中间路由层 ↔ LLM 服务端通信异常，快速判定故障点并执行重启或代码修复。触发条件：客户端收不到消息、消息异常、中间层代理故障。

- Skill: `drgon1/message-flow-troubleshooter` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add drgon1/message-flow-troubleshooter`
- Raw SKILL.md: https://api.skillmd.com/api/skills/drgon1/message-flow-troubleshooter/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: drgon1 (https://skillmd.com/u/drgon1)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/drgon1/message-flow-troubleshooter

---


# 中间层消息流问题排查 Skill

## 适用场景
当使用中间层（如 LamaPuppeteer）代理大模型时，客户端（如 Cursor）收不到消息或消息异常。

---

## 🚀 【智能经验沉淀&极速执行规则】

### 1. 故障排查统一强制使用【两端消息排查法】

**链路**：Cursor客户端 ↔ 中间路由层 ↔ LLM-Puppeteer服务端

**排查顺序固定不变**：

① **校验Cursor发出原始请求报文是否正常** → 异常判定为客户端问题  
② **校验LLM服务返回原生响应内容是否正常** → 异常判定为底层模型/浏览器执行层问题  
③ **两端数据均正常，输出结果异常/丢包/无响应** → 直接判定为中间路由层故障  
④ **判定中间层宕机/数据篡改故障后** → 立即终止深度推理，禁止长时间空想分析，优先执行重启服务动作  
⑤ **重启后依旧异常** → 直接锁定中间层代码逻辑问题，定向定位修改，不再全链路盲目排查

### 2. 经验自动沉淀机制

所有需要长时间推理、多轮反复调试才能解决的代码问题、链路故障、对接报错，解决完成后：
- 自动精简提炼【最简固定解决步骤】
- 整理为标准化执行流程存入本地技能库
- 后续遇到同类型同源问题，直接调取沉淀好的流程执行
- 跳过试错、跳过冗余思考，优先复用成熟最优方案

### 3. 调试行为精简规则

- 区分调试中必要操作与无效重复操作
- 剔除无意义反复测试、随机尝试行为
- 同类问题只保留一套最高效解决路径
- 固化为行为范式，统一执行标准

### 4. 执行优先级

```
已沉淀Skill流程 > 临场自主思考
既定排错流程 > 发散分析猜测
故障既定处理动作 > 长时间逻辑推演
```

---

## ⚠️ 核心原则：先重启，再分析

**不要浪费时间在思考上！发现问题后立即重启！**

### 快速排查流程

**第一步：立即重启中间层**
```powershell
# 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 日志或消息调试文件

```powershell
# 查看发送给大模型的消息
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"

```powershell
# 查看大模型的原始回复
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. 检查中间层状态

**检查命令**：
```powershell
# 检查 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 网页端代理）