@tinkcarlos/skillora 0.2.0

package/.claude/skills/bug-fixing/references/knowledge-extraction-guide.md

@@ -0,0 +1,531 @@
+# Knowledge Extraction Guide (知识提取指南)
+
+> 将每次 Bug 修复的经验转化为可复用的知识，持续丰富 bug-guide.md。
+
+---
+
+## 为什么需要知识提取?
+
+### 问题：重复踩坑
+
+| 场景 | 后果 |
+|------|------|
+| 相同类型 Bug 反复出现 | 浪费时间重复调查 |
+| 修复经验只在个人记忆中 | 知识无法传承 |
+| 没有标准化的修复模式 | 每次都从零开始 |
+
+### 解决方案：知识沉淀循环
+
+```
+Bug 修复
+    ↓
+模式抽象
+    ↓
+更新 bug-guide.md
+    ↓
+下次修复前查询
+    ↓
+快速应用已知方案
+    ↓
+更快修复，更少踩坑
+```
+
+---
+
+## Phase -1: 知识查询 (修复前)
+
+### 强制查询流程
+
+**每次开始修复 Bug 前，必须执行：**
+
+```markdown
+## 📚 Phase -1: 知识库查询
+
+### Step 1: 提取搜索关键词
+从用户报告中提取:
+- 症状关键词: [如: 页面崩溃, 数据不同步, API 超时]
+- 错误类型: [如: TypeError, 500 错误, 渲染异常]
+- 技术栈: [如: React, FastAPI, PostgreSQL]
+
+### Step 2: 搜索 bug-guide.md
+在以下位置搜索:
+1. Common Bug Pattern Library (各 Category 表格)
+2. High-Frequency Root Causes
+3. Universal Verification Checklist
+
+### Step 3: 记录匹配结果
+| 匹配度 | 模式 | 相关性 |
+|--------|------|--------|
+| 🟢 高 | [Category X: Pattern Name] | [为什么匹配] |
+| 🟡 中 | [Category Y: Pattern Name] | [部分相关] |
+
+### Step 4: 决策
+- [ ] 🟢 高匹配: 直接应用已知方案
+- [ ] 🟡 中匹配: 参考策略，但需验证
+- [ ] 🔴 无匹配: 新模式，完整调查 + Phase 6 沉淀
+```
+
+### 匹配决策矩阵
+
+| 匹配度 | 定义 | 处理方式 |
+|--------|------|---------|
+| 🟢 **高匹配** | 症状、根因、技术栈都匹配 | 直接应用修复策略，可跳过 RCA |
+| 🟡 **中匹配** | 症状相似，但细节不同 | 参考策略，但需验证假设 |
+| 🔴 **无匹配** | 找不到相关模式 | 完整调查，修复后必须更新知识库 |
+
+---
+
+## Phase 6: 知识提取 (修复后)
+
+### 6.1 提取触发条件
+
+**以下情况必须执行知识提取：**
+
+| 条件 | 必须提取 |
+|------|---------|
+| Phase -1 无匹配 | ✅ 必须 (新模式) |
+| 修复策略与已知模式不同 | ✅ 必须 (补充/修正) |
+| 发现新的检测方法 | ✅ 必须 (增强) |
+| P0/P1 严重 Bug | ✅ 必须 (重要经验) |
+| 简单 Bug + 已有模式覆盖 | ⚪ 可选 |
+
+### 6.2 模式抽象流程
+
+```
+具体 Bug
+    ↓
+┌──────────────────────────────────────────────────────┐
+│ Step 1: 识别模式类别                                 │
+│ ─────────────────────────────────────────────────────│
+│ 这个 Bug 属于哪个已有类别?                          │
+│ - Category 1: Input Handling Bugs                   │
+│ - Category 2: Status/State Bugs                     │
+│ - Category 3: API Integration Bugs                  │
+│ - Category 4: Data Flow Bugs                        │
+│ - Category 5: Configuration Bugs                    │
+│ - Category 6: Platform-Specific Bugs                │
+│ - ...                                               │
+│                                                      │
+│ 如果不属于任何类别 → 创建新 Category                 │
+└──────────────────────────────────────────────────────┘
+    ↓
+┌──────────────────────────────────────────────────────┐
+│ Step 2: 通用化描述                                   │
+│ ─────────────────────────────────────────────────────│
+│ 将项目特定细节抽象为通用语言:                        │
+│                                                      │
+│ 项目特定:                                            │
+│ "UserService.login() 返回 null 但前端显示成功"      │
+│                                                      │
+│ 通用化:                                              │
+│ "Service 返回 null/空值但调用方未检查"              │
+└──────────────────────────────────────────────────────┘
+    ↓
+┌──────────────────────────────────────────────────────┐
+│ Step 3: 提取可复用元素                               │
+│ ─────────────────────────────────────────────────────│
+│ - 模式名称: [简短、可搜索]                          │
+│ - 典型症状: [用户会怎么描述]                        │
+│ - 检测方法: [如何发现这类 Bug]                      │
+│ - 修复策略: [通用的解决方法]                        │
+└──────────────────────────────────────────────────────┘
+    ↓
+┌──────────────────────────────────────────────────────┐
+│ Step 4: 格式化为表格行                               │
+│ ─────────────────────────────────────────────────────│
+│ | Pattern | Typical Symptom | Detection | Fix |     │
+│ |---------|-----------------|-----------|-----|     │
+│ | [名称]  | [症状]          | [检测]    | [修复] |  │
+└──────────────────────────────────────────────────────┘
+```
+
+### 6.3 通用化规则
+
+| 项目特定 | 通用化 |
+|---------|--------|
+| `UserService.login()` | Service 方法 |
+| `React useState` | 前端状态管理 |
+| `FastAPI endpoint` | 后端 API 接口 |
+| `/api/v1/users` | API 端点 |
+| `PostgreSQL query` | 数据库查询 |
+| 具体错误消息 | 错误类型 (TypeError, 500, etc.) |
+
+### 6.4 提取模板
+
+```markdown
+## 📝 Phase 6: 知识提取
+
+### Bug 信息
+- **Bug ID**: BUG-XXX
+- **日期**: YYYY-MM-DD
+- **严重程度**: P0/P1/P2
+- **技术栈**: [React, FastAPI, PostgreSQL]
+
+### 原始问题
+- **症状**: [用户报告的问题]
+- **根因**: [识别的根本原因]
+- **修复**: [采用的修复方法]
+
+### 模式抽象
+
+#### 类别归属
+- **类别**: [现有类别名 / NEW: 新类别名]
+- **理由**: [为什么属于这个类别]
+
+#### 通用化描述
+| 维度 | 项目特定 | 通用化 |
+|------|---------|--------|
+| 症状 | [具体描述] | [通用描述] |
+| 检测 | [具体方法] | [通用方法] |
+| 修复 | [具体方案] | [通用策略] |
+
+#### 生成的表格行
+```
+| [模式名] | [典型症状] | [检测方法] | [修复策略] |
+```
+
+### 关键词覆盖
+确保以下关键词可以找到这个模式:
+- [ ] [关键词1]
+- [ ] [关键词2]
+- [ ] [关键词3]
+
+### bug-guide.md 更新
+- **添加位置**: Category X 表格
+- **添加内容**: [上面生成的表格行]
+```
+
+---
+
+## bug-guide.md 更新规范
+
+### 添加到已有类别
+
+如果 Bug 属于已有类别，在对应表格末尾添加新行：
+
+```markdown
+### Category 2: Status/State Bugs
+
+| Pattern | Typical Symptom | Detection | Fix Strategy |
+|---------|-----------------|-----------|--------------|
+| **Status mismatch** | UI says success but operation failed | Check both HTTP and business status | Parse full response body |
+| **Stale state** | Shows outdated data after updates | Check state invalidation | Refresh state after mutations |
+| **NEW PATTERN** | [症状] | [检测] | [修复] |  ← 新增行
+```
+
+### 创建新类别
+
+如果 Bug 不属于任何已有类别：
+
+```markdown
+### Category N: [新类别名] (NEW)
+
+[简短描述这类 Bug 的共同特征]
+
+| Pattern | Typical Symptom | Detection | Fix Strategy |
+|---------|-----------------|-----------|--------------|
+| **[模式名]** | [症状] | [检测] | [修复] |
+```
+
+### 更新高频根因列表
+
+如果这个根因值得加入 Top 13：
+
+```markdown
+## High-Frequency Root Causes (Top 14)  ← 更新数字
+
+...
+14. **[新根因]**: [描述]  ← 新增
+```
+
+---
+
+## 知识质量标准
+
+### 4 个必须满足的标准
+
+| 标准 | 检查问题 | 不通过示例 | 通过示例 |
+|------|---------|-----------|---------|
+| **通用性** | 换个项目能理解吗? | "UserService 的 login 方法" | "Service 方法返回值" |
+| **可操作性** | 能直接按步骤执行吗? | "检查代码" | "grep 'return null' 搜索空返回" |
+| **可搜索性** | 用不同关键词能找到吗? | 只有一个关键词 | 包含多个同义词 |
+| **完整性** | 缺少关键信息吗? | 只有症状没有修复 | 症状+检测+修复都有 |
+
+### 质量检查清单
+
+```markdown
+## 知识质量检查
+
+### 通用性
+- [ ] 没有项目特定的类名/方法名
+- [ ] 技术栈无关或明确标注
+- [ ] 其他开发者能理解
+
+### 可操作性
+- [ ] 检测方法具体可执行
+- [ ] 修复策略有明确步骤
+- [ ] 不需要额外解释就能操作
+
+### 可搜索性
+- [ ] 症状描述包含常见表达
+- [ ] 覆盖可能的同义词
+- [ ] 关键词测试: 用 3 种不同表达搜索都能找到
+
+### 完整性
+- [ ] 有典型症状
+- [ ] 有检测方法
+- [ ] 有修复策略
+- [ ] 4 列都填写
+```
+
+---
+
+## 知识验证
+
+### 搜索测试
+
+更新 bug-guide.md 后，验证知识可被找到：
+
+```markdown
+## 搜索测试
+
+用以下关键词搜索，验证能找到新添加的模式:
+
+| 搜索词 | 能找到? |
+|--------|--------|
+| [用户可能用的描述1] | ✅/❌ |
+| [用户可能用的描述2] | ✅/❌ |
+| [错误类型关键词] | ✅/❌ |
+
+如果 ❌，需要调整模式描述或添加同义词。
+```
+
+### 复用测试
+
+假设遇到类似 Bug，验证知识有用：
+
+```markdown
+## 复用测试
+
+假设场景: [描述一个类似的假设 Bug]
+
+能通过 bug-guide.md 找到解决方案吗?
+- [ ] 能找到相关模式
+- [ ] 模式描述能帮助理解问题
+- [ ] 修复策略能指导解决
+
+如果任何一项 ❌，需要补充信息。
+```
+
+---
+
+## 常见问题
+
+### Q1: 所有 Bug 都要提取吗?
+
+**A**: 不是。只有以下情况需要：
+- Phase -1 无匹配的新模式
+- P0/P1 严重 Bug
+- 发现新的检测/修复方法
+
+简单、已有模式覆盖的 Bug 可以跳过。
+
+### Q2: 模式太具体怎么办?
+
+**A**: 逐步通用化：
+
+```
+太具体: "React useState 在 useEffect 中更新后组件不刷新"
+↓
+第一层: "状态更新后组件不刷新"
+↓
+第二层: "状态更新未触发预期的 UI 更新"
+↓
+最终: "Stale state" (已有模式)
+```
+
+### Q3: 不确定属于哪个类别?
+
+**A**: 问自己：
+1. 问题出在输入处理? → Category 1
+2. 问题出在状态管理? → Category 2
+3. 问题出在 API 调用? → Category 3
+4. 问题出在数据流转? → Category 4
+5. 问题出在配置? → Category 5
+6. 问题是平台特定? → Category 6
+7. 以上都不是? → 创建新 Category
+
+### Q4: 怎么确保知识被使用?
+
+**A**: Phase -1 强制查询机制确保每次修复前都会查询 bug-guide.md。
+
+---
+
+## 检查清单
+
+### Phase -1 (修复前)
+- [ ] 提取搜索关键词
+- [ ] 搜索 bug-guide.md
+- [ ] 记录匹配结果
+- [ ] 决定修复策略
+
+### Phase 6 (修复后)
+- [ ] 判断是否需要提取
+- [ ] 识别模式类别
+- [ ] 通用化描述
+- [ ] 生成表格行
+- [ ] 更新 bug-guide.md
+- [ ] 质量检查
+- [ ] 搜索测试
+
+### 持续改进
+- [ ] 定期审查 bug-guide.md
+- [ ] 合并重复模式
+- [ ] 更新过时内容
+- [ ] 补充缺失检测/修复方法
+
+---
+
+## 🔴 Debugging Journal (个人调试日志)
+
+**记录个人调试经验，加速未来问题解决。**
+
+### 为什么需要调试日志？
+
+| 好处 | 说明 |
+|------|------|
+| **加速定位** | 遇到类似问题时快速回忆解决方案 |
+| **发现模式** | 识别自己常犯的错误类型 |
+| **时间追踪** | 了解哪类 Bug 耗时最多 |
+| **技能提升** | 通过复盘持续改进调试能力 |
+
+### 调试日志模板
+
+```markdown
+## Debugging Journal Entry
+
+**Date**: YYYY-MM-DD
+**Bug**: [简短描述]
+**Time to Fix**: [耗时]
+**Difficulty**: Easy / Medium / Hard
+
+### Symptoms
+[用户报告的问题]
+
+### Root Cause
+[根本原因]
+
+### Solution
+[解决方案]
+
+### What Worked
+- [有效的调试方法]
+
+### What Didn't Work
+- [尝试过但无效的方法]
+
+### Lesson Learned
+[下次遇到类似问题的经验]
+
+### Tags
+#[category] #[technology] #[pattern]
+```
+
+### 调试日志示例
+
+```markdown
+## Debugging Journal Entry
+
+**Date**: 2025-01-19
+**Bug**: API 返回 500 但前端显示成功
+**Time to Fix**: 2 hours
+**Difficulty**: Medium
+
+### Symptoms
+用户点击保存后显示"保存成功"，但数据实际未保存
+
+### Root Cause
+前端只检查了 HTTP 状态码 200，没有检查响应体中的 business code
+
+### Solution
+添加 business code 检查: `if (response.code !== 0) throw new Error()`
+
+### What Worked
+- 查看 Network 面板发现响应体有 code: -1
+- 对比成功/失败请求的响应差异
+
+### What Didn't Work
+- 最初以为是后端问题，浪费了 30 分钟
+
+### Lesson Learned
+API 响应要同时检查 HTTP 状态码和业务状态码
+
+### Tags
+#api #status-check #frontend
+```
+
+### 定期复盘
+
+**每周/每月复盘调试日志：**
+
+1. **统计耗时最多的 Bug 类型** → 重点学习
+2. **识别重复出现的模式** → 添加到 bug-guide.md
+3. **分析无效尝试** → 避免下次重复
+
+---
+
+## 🔴 Proactive Bug Prevention (主动 Bug 预防)
+
+**不只是修 Bug，更要预防 Bug！**
+
+### 预防技术概览
+
+| 技术 | 工具 | 目的 |
+|------|------|------|
+| **Fuzz Testing** | AFL, libFuzzer | 发现边界条件 Bug |
+| **Chaos Engineering** | Chaos Monkey, Gremlin | 测试系统韧性 |
+| **Load Testing** | k6, Locust | 发现性能 Bug |
+| **Contract Testing** | Pact | 发现 API 集成 Bug |
+
+### Fuzz Testing (模糊测试)
+
+**用随机输入发现边界条件 Bug：**
+
+```bash
+# JavaScript (使用 fast-check)
+npm install fast-check
+```
+
+```javascript
+import fc from 'fast-check';
+
+// 测试函数对任意输入都不崩溃
+fc.assert(
+  fc.property(fc.string(), (input) => {
+    const result = myFunction(input);
+    return result !== undefined;
+  })
+);
+```
+
+### Chaos Engineering (混沌工程)
+
+**主动注入故障，测试系统韧性：**
+
+| 故障类型 | 测试目的 |
+|----------|----------|
+| 网络延迟 | 超时处理是否正确 |
+| 服务宕机 | 降级策略是否生效 |
+| 磁盘满 | 错误处理是否优雅 |
+| CPU 过载 | 性能降级是否平滑 |
+
+> 研究表明：68% 使用混沌工程的组织减少了 20% 以上的生产事故 (Gremlin 2023)
+
+### 何时使用预防技术
+
+| 场景 | 推荐技术 |
+|------|----------|
+| 发布前 | Fuzz Testing + Load Testing |
+| 重大变更后 | Contract Testing |
+| 生产环境 | Chaos Engineering (谨慎) |
+| 持续集成 | 所有自动化测试 |