majiayu000 Debugging - 自主诊断和修复
Purpose: 让 Agent 自己决定诊断方法，而非遵循固定步骤
AMP Principle: "告诉它「你想理解什么」，而非「怎么测试」"
核心思维
🔧 本地測試優先原則 (2026-01-08 教訓)
遇到 Bug 時：
❌ 不要等部署後測試
❌ 不要只測一次就以為對了
❌ 不要用 workaround 繞過問題
✅ 先寫本地測試腳本
✅ 來回測試 3-5 次觀察變異
✅ 確認 root cause 再修
✅ 修完再測 3+ 次確認
教訓來源: Quick Feedback 截斷 bug
- 用 staging 測試太慢
- 用戶說「你不要等部署，你在 local 測試！！跟 debug，來回多次！！」
- 本地測 10 次才找到 max_tokens 問題
❌ 旧方式（固定步骤）
第1步: 运行测试
第2步: 检查日志
第3步: 添加 print
第4步: 重现错误
第5步: 修复
✅ 新方式（自主诊断）
问自己:
- 我想理解什么？
- 需要什么信息来诊断？
- 最快的方法是什么？
然后:
- 自己写诊断脚本
- 执行并分析结果
- 迭代直到找到根因
- 用完删除临时工具
诊断模式示例
Pattern 1: 写临时诊断脚本
场景: API 返回 500 错误
不要: 遵循固定步骤
应该:
# 自己写临时诊断脚本
cat > /tmp/debug_api.sh << 'EOF'
#!/bin/bash
# Create logs directory
mkdir -p logs
rm -f logs/*.log
# Run API with verbose logging
export DEBUG=true
export LOG_LEVEL=DEBUG
cd /Users/young/project/career_ios_backend
poetry run uvicorn app.main:app \
--reload \
--log-level debug \
> logs/api.log 2>&1 &
API_PID=$!
# Wait for startup
sleep 2
# Test the failing endpoint
curl -X POST http://localhost:8000/api/sessions \
-H "Content-Type: application/json" \
-d '{"name": "test"}' \
-v > logs/curl.log 2>&1
# Analyze logs
echo "=== Errors ==="
grep -i "error\|exception" logs/api.log
echo "=== Response ==="
cat logs/curl.log
# Cleanup
kill $API_PID
EOF
chmod +x /tmp/debug_api.sh
/tmp/debug_api.sh
# 用完就删
rm /tmp/debug_api.sh
Pattern 2: 动态添加日志
场景: 不确定哪里出错
不要: 预设添加日志的位置
应该:
# TEMP: Add detailed logging
import logging
logging.basicConfig(level=logging.DEBUG)
# 在怀疑的函数添加
def problematic_function(input_data):
logger.debug(f"Input: {input_data}")
logger.debug(f"Processing...")
result = some_operation()
logger.debug(f"Result: {result}")
return result
# 运行、分析、然后移除日志
Pattern 3: 数据库诊断
场景: 数据不一致
不要: 手动查询
应该:
# 写临时分析脚本
cat > /tmp/analyze_db.py << 'EOF'
from sqlalchemy import create_engine, text
import os
import sys
# Add project root to path
sys.path.insert(0, '/Users/young/project/career_ios_backend')
from app.core.config import settings
engine = create_engine(settings.DATABASE_URL)
queries = {
"orphaned_sessions": """
SELECT s.id, s.name, s.client_id
FROM sessions s
LEFT JOIN clients c ON s.client_id = c.id
WHERE c.id IS NULL
""",
"duplicate_codes": """
SELECT client_code, COUNT(*)
FROM clients
GROUP BY client_code
HAVING COUNT(*) > 1
""",
"invalid_timestamps": """
SELECT * FROM sessions
WHERE created_at > updated_at
"""
}
for name, query in queries.items():
print(f"\n=== {name} ===")
result = engine.execute(text(query))
for row in result:
print(row)
EOF
cd /Users/young/project/career_ios_backend
poetry run python /tmp/analyze_db.py
rm /tmp/analyze_db.py
诊断思维流程
遇到 Bug
↓
问: "我需要理解什么？"
- 错误发生在哪一层？(API/Service/DB)
- 输入数据是什么？
- 预期 vs 实际输出？
↓
问: "最快的验证方法是什么？"
- 写临时脚本？
- 添加日志？
- 直接测试 SQL？
↓
执行诊断
- 不要担心代码质量
- 不要过度工程化
- 快速迭代
↓
找到根因
↓
修复
↓
清理临时工具
- 删除临时脚本
- 移除调试日志
- 恢复正常代码
快速诊断工具箱
1. HTTP 请求诊断
# 详细查看 HTTP 交互
curl -v http://localhost:8000/api/endpoint
# 添加 timing 信息
curl -w "Time: %{time_total}s\n" http://localhost:8000/api/endpoint
# 保存响应详情
curl -v http://localhost:8000/api/endpoint > /tmp/response.log 2>&1
2. Python 交互式调试
# 在怀疑的地方添加断点
import pdb; pdb.set_trace()
# 或使用 breakpoint() (Python 3.7+)
breakpoint()
3. 数据库实时查询
# PostgreSQL
cd /Users/young/project/career_ios_backend
poetry run python -c "
from app.core.config import settings
import psycopg2
conn = psycopg2.connect(settings.DATABASE_URL)
cur = conn.cursor()
cur.execute('SELECT * FROM sessions LIMIT 5')
print(cur.fetchall())
"
4. 日志实时监控
# 实时查看日志
tail -f /Users/young/project/career_ios_backend/logs/app.log | grep -i error
# 过滤特定关键词
tail -f /Users/young/project/career_ios_backend/logs/app.log | grep "session\|client"
AMP 原则应用
Graham 的例子:
"Agent 自己写了一整个 bash 脚本: 建立 logs 目录、每次执行前清空、设环境变数、把输出写入 log 档、用 grep 找出失败的地方。这个 script 不是人要求的，是 Agent 自己判断需要而产生的。"
我们应该:
- 让 Agent 自己决定需要什么工具
- 鼓励临时脚本和一次性工具
- 用完就删，不要保留
- 不要预设固定流程
IMPORTANT
- No Fixed Checklist - 每个 bug 都不同
- Think, Don't Follow - 理解问题，自主决策
- Temporary is OK - 诊断脚本可以很丑
- Clean Up After - 修复后删除临时工具
Version: 2.0 (Self-Diagnostic refactor) Size: ~230 lines Philosophy: Think > Follow