WorkBuddy 智能诊断助手

WorkBuddy 报错、卡住、连不上、任务不跑？不用再瞎猜了。

一键运行诊断脚本，自动扫描代理、连接器、日志、网络和客户端检测结果，匹配常见错误模式，直接告诉你问题在哪、怎么修。复杂问题还能自动生成官方反馈文案，复制就能提交。

快速使用

# 标准诊断（自动扫描代理/连接器/日志/网络）
python scripts/smart_diagnose.py

# 直接描述症状，让中文模式也能命中（推荐复制报错原文或口语）
python scripts/smart_diagnose.py --symptom "白屏了"
python scripts/smart_diagnose.py --symptom "连接器连不上"

# 输出结构化 JSON 结果（供自动化/测评机器校验）
# 默认落盘到系统临时目录，不污染技能包；用 --out 指定位置
python scripts/smart_diagnose.py --json
python scripts/smart_diagnose.py --json --out /tmp/diag.json

# 查看版本
python scripts/smart_diagnose.py --version

使用示例

场景1：刚遇到问题，不知道怎么回事

1. 在 WorkBuddy 里说「诊断一下」或「帮我排查」
2. 脚本自动检查代理、连接器、日志、网络
3. 看输出第一行 [*] 问题：xxx — 这就是根因
4. 跟着 [>] 修复：xxx 的建议做
5. 术语看不懂？打开 references/glossary.md 查大白话

场景2：修完还不行

1. 再看输出底部「官方反馈报告」部分
2. 复制文案 → 打开 WorkBuddy → 帮助(H) → 意见反馈 → 粘贴提交
3. 同时加载 workbuddy-guide 技能做深度排查

场景3：脚本说"所有检查通过"

1. 说明当前环境未触发已知故障模式，可放心使用
2. 若仍有体感异常，用 --symptom 直接描述症状，或按 5 步自助清单依次试
3. 还不行就复制反馈报告提交给官方

诊断流程

用户说"诊断一下"
    │
    ▼
运行 smart_diagnose.py
    ├── 检测代理状态（是否运行/端口/响应时间）
    ├── 扫描连接器配置（哪些连接/哪些断开/错误码）
    ├── 读取最近日志（搜索 error/fail/timeout/401/403；中文错误描述也会自动命中）
    ├── 检查客户端网络检测报告（帮助→网络检查）
    ├── 匹配错误模式（英文错误码 + 中文模式双路扫描：长任务卡住/文件读取/格式错乱/休眠/安全软件等）
    └── 输出一句话诊断 + 一个修复动作
    │
    ▼
匹配错误模式（pattern-db.md）
    │
    ▼
输出一句话诊断 + 一个修复动作
    │
    ▼
若无法匹配 → 自动生成300字以内官方反馈文案

适用边界与前置依赖

口语触发词（说这些也能触发）：诊断一下 / 检查环境 / 出问题了 / 帮我排查 / 连不上 / 白屏了 / 闪退 / 崩了 / 登不上 / 打不开 / 卡死。

前置依赖：
- Python 3.8+（仅用标准库，无第三方依赖）
- 本机已安装并运行 WorkBuddy（代理健康检查依赖 127.0.0.1:51103）
- 可选 curl：用于代理端口探测；缺失时自动跳过该项，不影响其余检查

适用版本：模式库基于 WorkBuddy v4.21 – v5.2.6 公开变更整理。极旧版本（< v4.21）的部分路径/错误码可能不吻合。

不适用场景（何时不要用本技能）：
- 咨询 WorkBuddy 怎么用、功能介绍 → 用 workbuddy-guide（使用指南技能）
- 纯业务逻辑 / 代码编写需求 → 直接用对应生成类技能
- 需要原理级根因分析而非"先修起来" → 加载 workbuddy-guide 手册深度排查

覆盖的高频问题

本技能内置 80+ 种错误模式（按场景分为 9 类，每条含动作类型，速查表附人工检查点），完整清单见 references/pattern-db.md。典型问题：

> 术语看不懂？打开 references/glossary.md 查大白话解释。

诊断示例输出

示例1：命中已知模式（长任务卡住）

  [*] 问题：上下文压缩触发或内存OOM
  [>] 修复：调大压缩阈值或关闭自动压缩；旧对话不超过50轮；>100MB大文件拆成子任务
  [>] 动作：手动配置/操作，执行前请确认无副作用
  [?] 深度排查：加载 workbuddy-guide 技能，或查 references/glossary.md 术语解释
  [!!] 这是高优先级问题（PS1），建议立即处理。

示例2：所有检查通过（环境健康，给自助清单 + 反馈报告）

  [!] 所有检查通过，未检测到已知问题模式（环境健康）

  --------- 5 步自助排查（按顺序试）---------
  1. 完全退出后重开 WorkBuddy（任务管理器结束残留进程） — 能解决 60% 的问题
  2. 切换模型再试 — 排除模型侧异常
  3. 断开并重连对应平台 — Bot 连接问题
  4. 看日志找错误码 — 帮助(H) → 打开日志目录
  5. 运行网络检测 — 帮助(H) → 网络检查
  ----------------------------------------------
  [?] 还不行？复制上方反馈报告提交给官方，或加载 workbuddy-guide 技能深度排查

  ════════════════════════════════════════════════
  官方反馈报告（一键复制）
  【WorkBuddy问题反馈】
  问题：所有检查通过
  ...

不会跑脚本？手动自检清单

不懂命令行也没关系，纯界面点击即可完成核心排查：

1. 看代理：WorkBuddy 能正常对话说明代理正常；若完全连不上，先看右下角是否显示「离线」
2. 重连连接器：设置 → 连接器 → 找到对应平台 → 点「重新登录/重连」
3. 跑网络检测：菜单栏 帮助(H) → 网络检查 → 看哪项标红（代理/hosts/服务/TCP/丢包）
4. 看日志：帮助(H) → 打开日志目录 → 搜索 error / fail / timeout 找线索

仍无解，把第 3 步网络检测的结果截图，直接去 帮助(H) → 意见反馈 提交即可。

输出格式

[*] 诊断结论：问题类型 — 简要描述
[>] 推荐修复：具体操作（1条，不列多个选项）
[>] 动作类型：重试 / 重启 / 手动 / 转人工（对应可自助程度）
[?] 深度排查：加载 workbuddy-guide 技能，或查 references/glossary.md 术语解释

与 workbuddy-guide 的协作

• 本技能输出"诊断 + 修复"，workbuddy-guide 提供"原理 + 完整流程"
• 诊断结论中附带 guide 引用链接，用户需要深入学习时跳转
• 诊断失败（无匹配模式）时，建议用户加载 workbuddy-guide 详细排查

使用规范

1. 不要只列可能原因，输出 1 个最可能的根因和 1 个修复动作
2. 诊断失败时，输出 scripts/smart_diagnose.py 的完整输出，引导用户去 workbuddy-guide
3. 涉及外部操作（如重启服务、修改配置），先提示用户确认
4. 模式库持续更新：发现新错误模式后，追加到 scripts/smart_diagnose.py 的 PATTERN_DB 字典中

已知局限（重要）

• 中文日志已支持自动扫描：从 v1.0.12 起，日志中出现中文错误描述（如"页面白屏或渲染崩溃""无法连接代理"）也会自动命中，无需 --symptom。但为获得最准结论，仍推荐用 --symptom "你的描述" 直接喂症状（口语别名表已覆盖白屏/闪退/崩了/登不上/卡死/掉线等常见说法）。
• 不做根因深挖：本技能目标是"先让环境跑起来"，不替代 workbuddy-guide 的原理级排查。
• 反馈报告需人工复核：自动生成的文案仅汇总已识别症状，提交官方前请确认描述准确，避免误报信息干扰排查。
• 代理探测依赖本地端口：若 WorkBuddy 代理未启动，127.0.0.1:51103 无响应会被判定为"无法连接代理"（属预期），并非误报；重启 WorkBuddy 后重试即可。

排查决策树（先看这张，再决定怎么用）

你遇到了什么？
├─ 完全没思路 / 不知道啥问题
│   └─ 直接跑：python scripts/smart_diagnose.py   （全自动扫描代理/连接器/日志/网络）
│
├─ 有明确的体感症状（白屏/闪退/卡住/连不上/登不上/掉线/打不开…）
│   └─ 跑：python scripts/smart_diagnose.py --symptom "你的描述"
│       （口语别名表会自动映射到对应模式，结论最准）
│
├─ 脚本说"所有检查通过"但你还觉得不对
│   └─ 用 --symptom 描述真实体感，或按 5 步自助清单依次试
│
├─ 命中已知模式 → 跟 [>] 修复 做，看 [✓] 验证 确认是否解决
│   └─ PS0（代理层）：优先重启 WorkBuddy（任务管理器结束残留进程）
│   └─ PS1（配置/网络层）：重连连接器 / 重新登录 / 跑网络检测
│   └─ PS2（工具层）：核对工具名 / 检查 plugin.json 拼写
│
└─ 仍无解 → 复制底部"官方反馈报告"去 帮助(H)→意见反馈 提交，
            或加载 workbuddy-guide 做原理级深度排查

常见误用与 FAQ

Q：脚本报"无法连接代理"，是不是脚本坏了？
A：不是。这说明 127.0.0.1:51103 确实没响应——通常是 WorkBuddy 没启动或代理进程挂了。先完全退出 WorkBuddy 再重开，然后重跑脚本。

Q：我明明白屏了，跑脚本却说"所有检查通过"？
A：日志扫描以英文/错误码为主，中文口语症状不会自动命中。改用 python scripts/smart_diagnose.py --symptom "白屏了" 直接喂症状即可。

Q：能不能直接让它帮我改配置 / 重启服务？
A：不能，本技能是只读诊断——只读 ~/.workbuddy 下的配置和日志，不写、不删、不重启任何东西。所有修复动作都由你确认后手动执行，这是刻意设计的安全边界。

Q：为什么只给 1 个根因，不把所有可能都列出来？
A：列 5 个可能等于没结论。本技能按优先级只输出最可能的 1 条 + 1 个动作；修完不行再看反馈报告或转 workbuddy-guide 深挖。

Q：诊断结果能被自动化/脚本消费吗？
A：可以。加 --json 会把结构化结果（含 timestamp、版本、症状列表、优先级、动作类型 action、反馈报告字数）写到系统临时目录下的 diagnosis_result.json；用 --out <path> 可自定义落盘位置。供 CI / 自动化流程读取，且不污染技能包目录。

Q：诊断显示"未识别异常"是什么意思？和健康有什么区别？
A：两回事。"所有检查通过"= 没发现任何已知症状（真健康）；"未识别异常"= 检测到了异常症状，但没匹配到模式库里的根因。后者请直接复制反馈报告提交官方，或加载 workbuddy-guide 深挖，别当成"没问题"放过。

Q：好几个问题同时报出来，先处理哪个？
A：看结论区 [=] 研判 那行的计数——PS0(代理层) > PS1(配置/网络层) > PS2(工具层)。PS0 最优先（代理挂了啥都干不了），先解决它，再往下看 PS1/PS2。

Q：诊断结论和我自己的体感对不上？
A：脚本会同时做"环境扫描"和"你用 --symptom 描述的症状"。当你主动描述症状时，结论以你的描述为准；但若环境里还藏着更高优先级（如 PS0）的问题，脚本会显式追加提醒"先处理它"，不会悄悄吞掉。

Q：能不能批量诊断多台设备 / 多个会话？
A：不能，本技能只诊断当前本机的 WorkBuddy 环境（只读 ~/.workbuddy）。多设备问题请逐台运行，或汇总各机反馈报告后统一提交官方。

反模式提醒：
- ❌ 把本技能当"WorkBuddy 说明书"问功能怎么用 → 该用 workbuddy-guide
- ❌ 环境健康时反复重跑脚本期待不同结果 → 换 --symptom 描述你的真实体感
- ❌ 把"未识别异常"误当成"所有检查通过" → 前者是没匹配到模式，仍需提交反馈
- ❌ 直接把反馈报告原文提交而不核对 → 报告是汇总草稿，提交前请人工确认描述准确
- ❌ 跳过 [✓] 验证 步骤直接判定修好 → 验证步骤是用来确认根因是否真的命中的

参考文件索引