bugfix-protocol

<img src="banner.png" width="100%" alt="bugfix-protocol banner"> > **中文** — `bugfix-protocol` 官方中文版本。 # Bugfix Protocol: 系统的 6 阶段 Debugging 协议 结构化的 Bug 处理方法 — 从症状分析到验证。 防止盲目的试错，确保修复方案可持续。 --- ## 概述与目的 | 阶段 | 名称 | 目标 | 最长时��� | |------|------|------|----------| | 1 | 快速检查 | 排除明显原因 | 2 分钟 | | 2 | 诊断 | 定位根本原因 | 10 分钟 | | 3 | 隔离测试 | 使 Bug 可复现 | 5 分钟 | | 4 | 修复 | 最小化修正 | 10 分钟 | | 5 | 验证 | 验证修复 + 检查副作用 | 5 分钟 | | 6 | 文档编写 | 保存知识经验 | 2 分钟 | **20分钟规则：** 如果 20 分钟后仍无进展，请改变方法或寻求帮助。 --- ## 阶段 1: 快速检查 (2 分钟) 在深入分析之前 — 检查最常见的原因： ### 检查清单 - [ ] **语法错误？** 仔细阅读错误信息，检查对应行 - [ ] **导入错误？** 模块已安装？名称正确？循环导入？ - [ ] **拼写错误？** 变量/函数名称是否正确？ - [ ] **数据类型错误？** 字符串误作为整型？本应为对象的地方为 None？ - [ ] **缓存过期？** 删除 `__pycache__`，重新启动 - [ ] **环境错误？** 是否激活了正确的 venv？Python 版本是否正确？ - [ ] **编码问题？** UTF-8 vs. cp1252 (Windows 经典) ### 快速操作 ```bash # 清除缓存 find . -name "__pycache__" -type d -exec rm -rf {} + 2>&1 find . -name "*.pyc" -delete 2>&1 # 检查导入 python -c "import modulename" # 检查语法 python -m py_compile file.py ``` --- ## 阶段 2: 诊断 (10 分钟) ### 策略：由外入内 (Outside-In) 1. **分析错误信息** — 从下往上阅读堆栈追踪 (traceback) 2. **检查最近的修改** — `git diff`, `git log --oneline -10` 3. **使用诊断工具** — 使用项目专属的诊断工具 ### 诊断工具 (示例) 根据项目的不同，专用的诊断脚本可能会大有帮助： | 工具 | 用途 | |------|------| | `import_diagnose.py` | 分析导入问题 | | `method_analyzer.py` | 检查方法签名 | | `env_checker.py` | 验证环境变量/路径 | > **注意：** 创建项目专属的诊断工具或使用现有的工具。 > 重要的是系统性的方法，而不是具体的工具。 ### 调试技巧 ```python # 1. Print 调试 (简单但高效) print(f"DEBUG: variable={variable!r}, type={type(vari...