@tinkcarlos/skillora 0.2.0

package/.claude/skills/bug-fixing/references/dependency-and-integrity-protocol.md

@@ -0,0 +1,369 @@
+# Dependency Management & Code Integrity Protocol
+
+> **核心原则**: 新增依赖必须安装 → 依赖文件必须更新 → 完成后必须验证 → 验证包括兼容性和文件完整性
+
+---
+
+## 🔴 依赖管理门禁 (Dependency Management Gate)
+
+### 触发条件
+
+当代码中出现以下情况时，**必须执行依赖管理流程**：
+
+| 触发条件 | 示例 |
+|----------|------|
+| 新增 import/require 语句 | `import { Collapsible } from "@radix-ui/react-collapsible"` |
+| 安装新的组件库/UI 框架 | shadcn/ui, Ant Design, Material UI |
+| 引入新的工具函数库 | lodash, date-fns, zod |
+| 使用新的后端框架/库 | FastAPI, LangChain, Pydantic |
+| 调用新的第三方 API SDK | Stripe, OpenAI, AWS SDK |
+
+---
+
+## 依赖检测规则 (通用)
+
+### Step 1: 识别依赖类型
+
+| 项目类型 | 依赖文件 | 安装命令 |
+|----------|---------|----------|
+| Node.js/前端 | `package.json` | `npm install <pkg>` / `yarn add <pkg>` / `pnpm add <pkg>` |
+| Python | `requirements.txt` / `pyproject.toml` | `pip install <pkg>` / `uv add <pkg>` |
+| Go | `go.mod` | `go get <pkg>` |
+| Rust | `Cargo.toml` | `cargo add <pkg>` |
+| Java/Kotlin | `pom.xml` / `build.gradle` | Maven/Gradle 手动添加 |
+
+### Step 2: 检查依赖是否已存在
+
+```bash
+# Node.js - 检查 package.json
+grep "<package-name>" package.json
+
+# Python - 检查 requirements.txt
+grep "<package-name>" requirements.txt
+
+# 通用 - 检查 node_modules / venv
+ls node_modules/<package-name> 2>/dev/null || echo "Not installed"
+```
+
+### Step 3: 安装缺失依赖
+
+**🔴 必须在代码修改前或立即之后安装依赖！**
+
+```bash
+# Node.js
+npm install <package-name>
+# 或指定版本
+npm install <package-name>@<version>
+```
+
+#### 🔴 Python 虚拟环境强制要求 (NON-NEGOTIABLE)
+
+**Python 项目的所有依赖操作必须在虚拟环境中进行！**
+
+```bash
+# Step 1: 检查虚拟环境是否存在
+ls venv/ 2>/dev/null || ls .venv/ 2>/dev/null || echo "虚拟环境不存在"
+
+# Step 2: 如果不存在，创建虚拟环境
+python -m venv venv
+
+# Step 3: 激活虚拟环境 (必须!)
+# Windows CMD
+venv\Scripts\activate
+# Windows PowerShell
+.\venv\Scripts\Activate.ps1
+# Linux/Mac
+source venv/bin/activate
+
+# Step 4: 在虚拟环境中安装依赖
+pip install <package-name>
+# 或指定版本
+pip install <package-name>==<version>
+
+# Step 5: 更新 requirements.txt
+pip freeze > requirements.txt
+```
+
+**❌ 禁止事项**:
+- 禁止在全局 Python 环境中安装项目依赖
+- 禁止不激活虚拟环境就执行 `pip install`
+- 禁止使用系统 Python 运行项目脚本
+
+**✅ 验证虚拟环境激活**:
+```bash
+# 检查 which/where python 指向虚拟环境
+which python  # Linux/Mac: 应显示 .../venv/bin/python
+where python  # Windows: 应显示 ...\venv\Scripts\python.exe
+```
+
+### Step 4: 更新依赖文件
+
+**🔴 安装后必须验证依赖文件已更新！**
+
+| 项目类型 | 验证方式 |
+|----------|---------|
+| Node.js | 检查 `package.json` 和 `package-lock.json` 是否包含新依赖 |
+| Python | 执行 `pip freeze > requirements.txt` 或手动添加到 requirements.txt |
+
+---
+
+## 🔴 代码文件完整性检查 (File Integrity Check)
+
+### 触发条件
+
+当新增功能涉及以下情况时，**必须执行文件完整性检查**：
+
+| 场景 | 检查内容 |
+|------|----------|
+| 使用 UI 组件库 | 组件文件是否存在于 `components/ui/` |
+| 引用工具函数 | 工具函数文件是否存在于 `lib/` 或 `utils/` |
+| 导入类型定义 | 类型文件是否存在于 `types/` |
+| 调用 API 服务 | 服务文件是否存在于 `services/` 或 `api/` |
+
+### 检查流程
+
+```
+代码中有新 import
+       ↓
+┌──────────────────────────────────────────────────────┐
+│ Step 1: 解析 import 路径                              │
+│ ─────────────────────────────────────────────────────│
+│ 相对路径? → 检查文件是否存在                          │
+│ 别名路径 (@/)? → 解析别名后检查文件是否存在           │
+│ 包路径? → 检查 node_modules 或 site-packages         │
+└──────────────────────────────────────────────────────┘
+       ↓
+┌──────────────────────────────────────────────────────┐
+│ Step 2: 文件不存在时的处理                            │
+│ ─────────────────────────────────────────────────────│
+│ UI 组件? → 创建组件文件 (shadcn/ui 风格)              │
+│ 工具函数? → 创建工具函数文件                          │
+│ 第三方包? → 安装依赖                                  │
+└──────────────────────────────────────────────────────┘
+```
+
+### 常见缺失文件场景
+
+| 场景 | 缺失类型 | 解决方案 |
+|------|---------|----------|
+| shadcn/ui 组件 | `components/ui/xxx.tsx` | 使用 `npx shadcn@latest add xxx` 或手动创建 |
+| Radix UI 原语 | npm 包未安装 | `npm install @radix-ui/react-xxx` |
+| 自定义 Hook | `hooks/useXxx.ts` | 创建 Hook 文件 |
+| API 服务 | `services/xxxService.ts` | 创建服务文件 |
+
+---
+
+## 🔴 兼容性检查 (Compatibility Check)
+
+### 版本兼容性矩阵
+
+| 检查项 | 方法 | 风险等级 |
+|--------|------|----------|
+| **Peer Dependencies** | 检查 npm 警告信息 | 🔴 高 |
+| **Node.js 版本** | 对比 `engines` 字段 | 🔴 高 |
+| **TypeScript 版本** | 检查类型定义兼容性 | 🟡 中 |
+| **React 版本** | 检查 Hooks/API 可用性 | 🔴 高 |
+| **Python 版本** | 对比 `python_requires` | 🔴 高 |
+| 🔴 **原生模块 (Electron/RN)** | 检查是否需要编译 | 🔴 高 |
+
+---
+
+## 🔴 原生模块 Bug 诊断与修复 (Electron/React Native)
+
+> **原生模块是 Electron 应用启动失败的头号杀手！**
+
+### 常见原生模块错误信息
+
+| 错误信息 | 根因 | 解决方案 |
+|----------|------|----------|
+| `Cannot find module 'xxx'` | 原生模块未针对 Electron 编译 | **首选**: 换用纯 JS 替代 |
+| `NODE_MODULE_VERSION mismatch` | Node ABI 版本不匹配 | electron-rebuild |
+| `was compiled against a different Node.js version` | 编译版本不匹配 | 重新编译或换纯 JS |
+| `Error: The module was compiled against ABI xxx` | Electron Node 版本不同 | electron-rebuild |
+
+### 识别原生模块
+
+```bash
+# 方法 1: 检查 .node 文件
+ls node_modules/<pkg>/*.node
+
+# 方法 2: 检查 binding.gyp
+ls node_modules/<pkg>/binding.gyp
+
+# 方法 3: npm info
+npm info <pkg> | grep -i "native\|gyp\|c++"
+```
+
+### 原生模块 → 纯 JS 替代方案
+
+| 功能 | ❌ 原生模块 (问题源) | ✅ 纯 JS 替代 (推荐) |
+|------|---------------------|---------------------|
+| **SQLite** | `better-sqlite3`, `sqlite3` | `sql.js` |
+| **图片处理** | `sharp` | `jimp`, `pica` |
+| **密码哈希** | `bcrypt` | `bcryptjs` |
+| **SCSS** | `node-sass` | `sass` (dart-sass) |
+| **画布** | `canvas` | HTML Canvas API |
+| **文件监听** | `fsevents` | `chokidar` |
+
+### 修复流程
+
+```
+原生模块 Bug
+    │
+    ▼
+┌─────────────────────────────────────────────────────┐
+│ Step 1: 确认是原生模块问题                           │
+│ → 错误信息含 "module"/"compile"/"ABI"               │
+└─────────────────────────────────────────────────────┘
+    │
+    ▼
+┌─────────────────────────────────────────────────────┐
+│ Step 2: 搜索纯 JS 替代方案 (首选)                    │
+│ → "<功能> pure javascript" 或 "<功能> wasm"         │
+└─────────────────────────────────────────────────────┘
+    │
+    ├─ 有替代 → 替换依赖 + 更新代码 + npm run dev 验证
+    │
+    └─ 无替代 → 配置 electron-rebuild
+         │
+         ├─ package.json: "postinstall": "electron-rebuild"
+         ├─ electron-builder: asarUnpack
+         └─ vite.config: external + optimizeDeps.exclude
+```
+
+### 🔴 修复后强制验证
+
+```bash
+# 运行开发服务器验证
+npm run dev
+
+# 确保无以下错误：
+# - Cannot find module
+# - NODE_MODULE_VERSION mismatch
+# - was compiled against a different Node.js version
+```
+
+### 兼容性检查命令
+
+```bash
+# Node.js - 检查 peer dependency 警告
+npm ls 2>&1 | grep -i "peer dep"
+
+# Node.js - 审计安全问题
+npm audit
+
+# Python - 检查依赖冲突
+pip check
+
+# Python - 查看依赖树
+pip show <package-name>
+```
+
+### 常见兼容性问题处理
+
+| 问题 | 症状 | 解决方案 |
+|------|------|----------|
+| Peer dependency 不满足 | npm 警告 | 安装兼容版本或使用 `--legacy-peer-deps` |
+| TypeScript 类型错误 | 编译失败 | 安装 `@types/xxx` 或升级 TS 版本 |
+| React 版本不匹配 | 运行时错误 | 检查组件库的 React 版本要求 |
+| Python 版本不兼容 | ImportError | 检查库的 Python 版本要求 |
+
+---
+
+## 任务完成验证清单 (Post-Task Verification)
+
+**🔴 每个开发任务结束前，必须完成以下检查：**
+
+### 依赖验证
+
+- [ ] **依赖安装完成**: 所有新增依赖已安装到项目中
+- [ ] **依赖文件更新**: `package.json` / `requirements.txt` 已包含新依赖
+- [ ] **Lock 文件同步**: `package-lock.json` / `poetry.lock` 已更新
+- [ ] **无兼容性警告**: `npm ls` / `pip check` 无报错
+
+### 文件完整性验证
+
+- [ ] **所有 import 可解析**: 无 "Cannot find module" / "ModuleNotFoundError"
+- [ ] **组件文件存在**: UI 组件文件均存在于正确路径
+- [ ] **类型定义完整**: 无 TypeScript 类型错误
+
+### 运行时验证
+
+- [ ] **开发服务器启动**: `npm run dev` / `python run.py` 无报错
+- [ ] **无控制台错误**: 浏览器/终端无红色错误
+- [ ] **核心功能正常**: 主要功能可正常使用
+
+---
+
+## 验证命令速查
+
+```bash
+# ===== Node.js 项目 =====
+# 检查依赖安装
+npm ls --depth=0
+
+# 检查 peer dependency
+npm ls 2>&1 | grep -i "peer\|missing\|invalid"
+
+# 启动开发服务器验证
+npm run dev
+
+# ===== Python 项目 (🔴 必须在虚拟环境中!) =====
+# Step 0: 检查虚拟环境是否存在
+ls venv/ 2>/dev/null || ls .venv/ 2>/dev/null || echo "需要创建虚拟环境"
+
+# Step 1: 创建虚拟环境 (如果不存在)
+python -m venv venv
+
+# Step 2: 激活虚拟环境 (🔴 必须!)
+# Windows CMD
+venv\Scripts\activate
+# Windows PowerShell  
+.\venv\Scripts\Activate.ps1
+# Linux/Mac
+source venv/bin/activate
+
+# Step 3: 验证虚拟环境已激活
+which python  # 应指向 venv/bin/python 或 venv\Scripts\python.exe
+
+# Step 4: 安装依赖
+pip install -r requirements.txt
+
+# Step 5: 检查依赖安装
+pip list | grep <package-name>
+
+# Step 6: 检查依赖冲突
+pip check
+
+# Step 7: 导出依赖 (安装新包后)
+pip freeze > requirements.txt
+
+# Step 8: 运行项目 (使用虚拟环境 Python)
+python run.py  # 或 venv/bin/python run.py
+```
+
+---
+
+## 输出契约 (Dependency Gate Report)
+
+**任务完成时，在 Output Contract 中添加：**
+
+```markdown
+## 依赖管理报告
+
+### 新增依赖
+| 包名 | 版本 | 用途 | 安装状态 |
+|------|------|------|----------|
+| @radix-ui/react-collapsible | ^1.0.0 | Collapsible 组件 | ✅ 已安装 |
+
+### 文件完整性
+| 文件 | 类型 | 状态 |
+|------|------|------|
+| components/ui/collapsible.tsx | UI 组件 | ✅ 已创建 |
+
+### 验证结果
+- [x] 依赖安装完成
+- [x] 依赖文件更新
+- [x] 无兼容性警告
+- [x] 开发服务器启动正常
+```

package/.claude/skills/bug-fixing/references/fix-completeness-checklist.md

@@ -0,0 +1,239 @@
+# Fix Completeness Checklist (修复完整性检查)
+
+**核心问题**：修复 Bug 时是否引入了新的问题？修复是否完整覆盖了所有路径？
+
+## 🔴 修复时必须检查的问题模式
+
+### 1. 控制流完整性
+
+**问题**：修复 Bug 时添加了 `break/return`，但没有处理退出后的逻辑。
+
+| 修复模式 | 潜在问题 | 正确做法 |
+|---------|---------|---------|
+| 添加 `if condition: return` | 函数可能静默返回空值 | 返回有意义的值或抛异常 |
+| 添加 `if condition: break` | 循环外没有处理 break 情况 | break 前设置状态/输出 |
+| 添加 `try-except: pass` | 异常被静默吞掉 | 记录日志 + 返回/抛出 |
+
+**检查清单**：
+- [ ] 新增的 `return` 语句返回有意义的值吗？
+- [ ] 新增的 `break` 语句，循环外有处理逻辑吗？
+- [ ] 新增的 `except` 块不是简单的 `pass` 吗？
+
+### 2. 边界条件覆盖
+
+**问题**：修复只考虑了正常场景，没有测试边界条件。
+
+| 场景 | 必须测试 |
+|------|---------|
+| 资源限制 | 小内存、小上下文、大数据量 |
+| 空/异常输入 | null、空字符串、超长文本 |
+| 并发场景 | 多用户同时操作 |
+| 超时场景 | 外部服务慢或不可用 |
+
+**检查清单**：
+- [ ] 修复后在"最小资源"环境测试了吗？
+- [ ] 修复后用空/异常输入测试了吗？
+- [ ] 修复涉及外部调用时，测试了超时场景吗？
+
+### 3. 降级策略
+
+**问题**：修复添加了限制检查，但超限时直接失败。
+
+```python
+# ❌ 错误修复
+if current_tokens > max_tokens:
+    logger.warning("Token limit exceeded")
+    return  # 直接返回，用户收不到任何回复
+
+# ✅ 正确修复
+if current_tokens > max_tokens:
+    logger.warning("Token limit exceeded, applying degradation")
+    # 降级策略 1: 压缩上下文
+    context = truncate_context(context)
+    # 降级策略 2: 禁用非必要功能
+    disable_optional_features()
+    # 确保仍然生成输出
+    return generate_with_constraints()
+```
+
+**检查清单**：
+- [ ] 新增的限制检查有降级策略吗？
+- [ ] 降级后用户仍能收到响应吗？
+- [ ] 降级有日志记录吗？
+
+### 4. 用户可见性保证
+
+**问题**：修复后某些路径导致用户看不到任何输出。
+
+| 场景 | 必须保证 |
+|------|---------|
+| 流式输出 | 至少有一个输出块 |
+| API 响应 | 非空响应体 |
+| UI 反馈 | 有视觉/文字提示 |
+
+**检查清单**：
+- [ ] 所有代码路径都能产生用户可见的输出吗？
+- [ ] 异常路径有友好的错误信息吗？
+- [ ] 流式函数确保至少有一个输出吗？
+
+## 修复完整性验证流程
+
+```
+修复代码完成
+       ↓
+┌──────────────────────────────────────────────────────┐
+│ Step 1: 控制流检查                                    │
+│ ─────────────────────────────────────────────────────│
+│ grep "return|break|continue|pass" 修改的文件         │
+│ 每个新增的退出点都有合理的后续处理吗？                 │
+└──────────────────────────────────────────────────────┘
+       ↓
+┌──────────────────────────────────────────────────────┐
+│ Step 2: 边界条件测试                                  │
+│ ─────────────────────────────────────────────────────│
+│ 用最小/最大资源配置测试修复                           │
+│ 用空/异常输入测试修复                                 │
+└──────────────────────────────────────────────────────┘
+       ↓
+┌──────────────────────────────────────────────────────┐
+│ Step 3: 降级策略验证                                  │
+│ ─────────────────────────────────────────────────────│
+│ 触发限制条件，验证降级逻辑是否工作                     │
+│ 用户仍能收到响应吗？                                  │
+└──────────────────────────────────────────────────────┘
+       ↓
+┌──────────────────────────────────────────────────────┐
+│ Step 4: 用户可见性验证                                │
+│ ─────────────────────────────────────────────────────│
+│ 模拟所有代码路径，确保都有用户可见的输出               │
+└──────────────────────────────────────────────────────┘
+```
+
+## 典型修复错误模式
+
+| 错误模式 | 问题 | 正确修复 |
+|---------|------|---------|
+| **Silent Return** | `return` 没有返回值 | 返回有意义的结果或抛异常 |
+| **Orphan Break** | `break` 后循环外没处理 | break 前设置状态/输出 |
+| **Hard Limit Fail** | 超限直接返回 | 添加降级策略 |
+| **Empty Stream** | 流提前中断 | 确保至少一个输出 |
+| **Swallowed Exception** | `except: pass` | 记录日志 + 返回/抛出 |
+| **Single Path Fix** | 只修了正常路径 | 考虑异常/边界路径 |
+
+## 修复后自问清单
+
+1. **"如果这个条件触发，用户会看到什么？"** → 确保有输出
+2. **"循环所有迭代都失败时会怎样？"** → 需要兜底处理
+3. **"最小资源配置下能工作吗？"** → 需要边界测试
+4. **"外部服务不可用时会怎样？"** → 需要超时和降级
+5. **"这个修复引入了新的退出点吗？"** → 检查后续处理
+
+---
+
+## 🔴 Incremental Fix Protocol (增量修复协议)
+
+**核心原则**: 一次只改一处，每次改动都验证。
+
+### 为什么要增量修复？
+
+| 批量修复 | 增量修复 |
+|----------|----------|
+| ❌ 多处改动，难以定位哪个有效 | ✅ 每次改动可追溯 |
+| ❌ 引入新 Bug 难以发现 | ✅ 新问题立即暴露 |
+| ❌ 回滚困难 | ✅ 可精确回滚单个改动 |
+| ❌ 代码审查困难 | ✅ 小改动易于审查 |
+
+### 增量修复流程
+
+```
+发现 Bug 有多个修复点
+       ↓
+Step 1: 列出所有需要修改的位置
+       ↓
+Step 2: 按依赖顺序排序 (被依赖的先改)
+       ↓
+Step 3: 修复第一处
+       ↓
+Step 4: 运行测试/验证
+       ├─ 通过 → Commit → 修复下一处
+       └─ 失败 → 回滚 → 分析原因
+       ↓
+Step 5: 重复直到全部完成
+```
+
+### 增量修复检查清单
+
+- [ ] **一次只改一处** - 不要批量修改多个文件
+- [ ] **每次改动后验证** - 运行测试或手动验证
+- [ ] **频繁提交** - 每个有效修复单独 commit
+- [ ] **记录每步** - 记录修改了什么、为什么
+
+### 反模式警告
+
+```python
+# ❌ 错误: 一次性修复 5 个问题
+git commit -m "Fix all issues"
+
+# ✅ 正确: 增量修复
+git commit -m "Fix null check in UserService"
+git commit -m "Fix timeout in ApiClient"
+git commit -m "Fix validation in FormHandler"
+```
+
+---
+
+## 🔴 Static Analysis Gate (静态分析门禁)
+
+**在提交修复前，必须通过静态分析检查！**
+
+### 为什么需要静态分析？
+
+> 研究表明：静态分析可减少 22% 的生产缺陷 (Synopsys 2024)
+
+静态分析能在运行前发现：
+- 空指针引用
+- 类型错误
+- 安全漏洞
+- 代码风格问题
+
+### 静态分析工具速查
+
+| 语言 | 工具 | 命令 |
+|------|------|------|
+| JavaScript/TypeScript | ESLint | `npx eslint --fix src/` |
+| Python | Ruff | `ruff check --fix .` |
+| Python | Pylint | `pylint src/` |
+| Python | mypy | `mypy src/` |
+| Go | golangci-lint | `golangci-lint run` |
+| Rust | Clippy | `cargo clippy` |
+| Java | SonarQube | `sonar-scanner` |
+
+### 修复前静态分析流程
+
+```
+修复代码完成
+       ↓
+Step 1: 运行 Linter
+       npx eslint src/ --fix
+       ruff check --fix .
+       ↓
+Step 2: 运行类型检查
+       npx tsc --noEmit
+       mypy src/
+       ↓
+Step 3: 检查安全问题
+       npm audit
+       pip-audit
+       ↓
+Step 4: 修复所有警告/错误
+       ↓
+Step 5: 提交代码
+```
+
+### 静态分析检查清单
+
+- [ ] **Linter 通过** - 无 error，warning 已审查
+- [ ] **类型检查通过** - 无类型错误
+- [ ] **安全扫描通过** - 无高危漏洞
+- [ ] **格式化完成** - 代码风格一致
+