Systematic debugging and problem-solving methodology. Activate when encountering unexpected errors, service failures, regression bugs, deployment issues, or when a fix attempt has failed twice. Also activate when proposing ANY fix to verify it addresses root cause (not a workaround). Prevents patch-chaining, wrong-environment restarts, workaround addiction, and "drunk man" random fixes.
系统化的调试与问题解决方法。提炼自真实生产事故与行业最佳实践。
每个修复方案必须针对根本原因。除非明确批准，否则禁止使用临时解决方案。
在提出任何解决方案之前，必须通过根本原因检查门：
┌─────────────────────────────────────────────┐
│ 根本原因检查门 │
│ │
│ 1. 实际的问题是什么？ │
│ 2. 为什么会发生？（不仅仅是发生了什么） │
│ 3. 我的修复方案能消除为什么吗？ │
│ 是 → 继续 │
│ 否 → 这是临时方案 → 停止 │
│ │
│ 临时方案测试： │
│ 如果我移除修复方案，bug会重现吗？ │
│ 是 → 临时方案（请修复根本原因） │
│ 否 → 真正的修复 ✅ │
└─────────────────────────────────────────────┘
问题：API返回524超时
为什么？→ Cloudflare切断超过100秒的连接
为什么？→ API调用耗时超过100秒
为什么？→ 使用非流式请求，服务器保持连接静默
为什么？→ 代码使用常规fetch，而非流式
修复：→ 使用流式（服务器持续发送数据，Cloudflare不会切断）
❌ 错误：切换到更快的模型（临时方案——避免超时而非修复问题）
✅ 正确：使用流式API（根本原因——Cloudflare需要持续的数据流）
| 问题 | 临时方案（❌） | 根本原因修复（✅） |
|---|---|---|
| API超时 | 切换到更快的模型 | 使用流式/修复慢查询 |
| 数据精度丢失 |
自检问题：我是在解决问题，还是在回避问题？
在任何修复尝试之前：
□ 确切症状是什么？（错误信息、行为、截图）
□ 上次正常工作是什么时候？之后发生了什么变化？
□ 服务是如何运行的？（进程、环境、启动命令）
对于正在运行的服务：
bash
ps -p
ls .venv/ venv/ env/ # 虚拟环境？
which python3 && python3 --version
which node && node --version
切勿在未记录原始启动命令的情况下重启服务。
优先级顺序：
更改X → 测试 → 工作？→ 完成
→ 失败？→ 回滚X → 新假设
不要堆叠更改。
2次修复尝试失败 → 停止。回滚所有更改。回到阶段1。
你可能正在：
任何修复之后，验证：
□ 是否解决了原始问题？（不仅仅是消除错误）
□ 是否引入了新问题？（回归检查）
□ 移除修复方案是否会让bug重现？（确认因果关系）
□ 修复是否在正确的层级？（不是在上游修补症状）
□ 运行时：系统还是venv/nvm？
□ 依赖：匹配预期版本？
□ 配置：.env、config.json——最近有更改？
□ 进程管理器：PM2/systemd——重启方法？
□ 日志：重现前执行tail -f
□ 备份：任何更改前创建快照
铁律：切勿直接在服务器上编辑文件。切勿在无备份的情况下覆盖服务器文件。
标准部署（每次执行，无一例外）：
更改1个文件 → 拉取该文件 + 其导入/导入者
更改路由 → 同时拉取server.js（检查挂载点）
更改前端 → 同时拉取index.html（检查脚本标签）
更改配置 → 同时拉取读取配置的代码
不确定要拉取什么 → 拉取整个项目目录
❌ 在服务器上对多行代码使用sed -i
❌ 编辑.js后跳过node -c
❌ 在语法验证前执行pm2 restart
❌ 在健康检查通过前告诉用户刷新
❌ 无备份推送
服务器上的每次代码更改必须在重启/重新加载前进行语法验证。
编辑.js文件后：
□ node -c
□ node -e require(./
□ 失败 → 不要重启。不要告诉用户刷新。先修复。
编辑.html文件后：
□ 检查关键标签闭合（div/script/style）
□ grep -c
复杂多行更改：
□ 本地编写完整文件 → scp上传
□ 切勿使用sed进行多行代码插入（换行符会被吞掉）
□ 如果必须使用sed → 立即用node -c验证
重启顺序：
□ node -c *.js通过 → pm2 restart
□ 检查pm2 logs --lines 5查看启动错误
□ curl健康端点确认服务已启动
原因：sed -i多行插入会静默破坏JS（换行符变成单行），导致语法错误，使整个页面崩溃且用户看不到任何可见错误。
问题出现
├─ 我刚编辑了什么？→ DIFF → 如果可疑则回滚
├─ 服务无法启动？→ 检查启动命令 + 环境
├─ 修复后出现新错误？→ 停止（补丁链！）→ 回滚 → 阶段1
├─ 用户报告回归？→ DIFF前后对比
├─ 想用临时方案？→ 根本原因检查门 → 修复真正问题
└─ 间歇性问题？→ 检查日志 + 外部依赖 + 时间
该技能支持在以下平台通过对话安装：
帮我安装 SkillHub 和 debug-methodology-1776275370 技能
设置 SkillHub 为我的优先技能安装源，然后帮我安装 debug-methodology-1776275370 技能
skillhub install debug-methodology-1776275370
文件大小: 6.6 KB | 发布时间: 2026-4-16 17:41
