@tinkcarlos/skillora 0.2.0

package/.claude/skills/code-review/references/platform-specific-review.md

@@ -0,0 +1,195 @@
+# Platform-Specific Review Guide
+
+This guide contains detailed checklists for reviewing native/desktop/hybrid applications.
+Use this as a reference when the main SKILL.md indicates platform-specific review is needed.
+
+## General Native/Desktop App Checklist
+
+| Area | Key Questions |
+|------|---------------|
+| **RPC/IPC Registration** | Every frontend call has matching backend handler? |
+| **Plugin Configuration** | Plugins installed AND initialized? |
+| **Security Permissions** | Required permissions configured? |
+| **API Verification** | APIs exist in framework version? Work in target platform? |
+| **Path Handling** | Using platform-appropriate paths? |
+| **Binary File Handling** | Binary files use proper encoding/protocol? |
+| **Asset Loading** | Local assets loaded correctly with proper protocol? |
+| 🔴 **Native Module Compatibility** | Native modules compatible with runtime? Need rebuild? |
+
+---
+
+## 🔴 Native Module Compatibility Check (MANDATORY for Electron/React Native)
+
+**原生模块是导致 Desktop App 启动失败的头号杀手！**
+
+### 什么是原生模块？
+
+原生模块是指使用 C/C++/Rust 编写并编译为 `.node` 文件的 Node.js 模块。它们：
+- 需要针对特定 Node.js ABI 版本编译
+- Electron 使用不同的 V8 版本，需要重新编译
+- 在不同操作系统上需要不同的二进制文件
+
+### 常见原生模块列表 (P0 风险)
+
+| 模块名 | 功能 | 纯 JS 替代方案 |
+|--------|------|----------------|
+| `better-sqlite3` | SQLite 数据库 | `sql.js` (推荐) |
+| `sqlite3` | SQLite 数据库 | `sql.js` |
+| `sharp` | 图片处理 | `jimp`, `canvas` (浏览器) |
+| `bcrypt` | 密码哈希 | `bcryptjs` |
+| `node-sass` | SCSS 编译 | `sass` (dart-sass) |
+| `canvas` | 画布渲染 | HTML Canvas API |
+| `serialport` | 串口通信 | Web Serial API (浏览器) |
+| `usb` | USB 设备 | WebUSB API (浏览器) |
+| `fsevents` | macOS 文件监听 | `chokidar` (跨平台) |
+| `leveldown` | LevelDB | `level-js` |
+
+### 原生模块检查流程
+
+```
+新增依赖
+    │
+    ▼
+┌──────────────────────────────────────────────────────┐
+│ Step 1: 识别是否为原生模块                            │
+│ ─────────────────────────────────────────────────────│
+│ 方法 1: 检查是否有 binding.gyp 文件                   │
+│ 方法 2: npm info <package> | grep "C++"              │
+│ 方法 3: 检查 node_modules/<pkg> 是否有 .node 文件     │
+└──────────────────────────────────────────────────────┘
+    │
+    ▼ 是原生模块
+┌──────────────────────────────────────────────────────┐
+│ Step 2: 评估兼容性风险                                │
+│ ─────────────────────────────────────────────────────│
+│ Electron 项目? → 🔴 高风险 → 优先考虑纯 JS 替代       │
+│ React Native? → 🔴 高风险 → 需要链接原生代码          │
+│ 纯 Node.js? → 🟡 中风险 → 检查 Node 版本兼容         │
+└──────────────────────────────────────────────────────┘
+    │
+    ▼ 必须使用原生模块
+┌──────────────────────────────────────────────────────┐
+│ Step 3: 配置编译环境                                  │
+│ ─────────────────────────────────────────────────────│
+│ Electron: electron-rebuild / @electron/rebuild       │
+│ 配置 package.json postinstall 脚本                    │
+│ 配置 electron-builder asarUnpack                      │
+└──────────────────────────────────────────────────────┘
+    │
+    ▼
+┌──────────────────────────────────────────────────────┐
+│ Step 4: 运行时验证 (MANDATORY)                        │
+│ ─────────────────────────────────────────────────────│
+│ npm run dev → 确保应用正常启动                        │
+│ 测试原生模块功能 → 确保功能正常                       │
+└──────────────────────────────────────────────────────┘
+```
+
+### Electron 原生模块配置清单
+
+| 配置项 | 文件 | 示例 |
+|--------|------|------|
+| **electron-rebuild** | `package.json` | `"postinstall": "electron-rebuild"` |
+| **asarUnpack** | `electron-builder.json5` | `"asarUnpack": ["**/node_modules/better-sqlite3/**"]` |
+| **external** | `vite.config.ts` | `external: ['better-sqlite3']` |
+| **optimizeDeps.exclude** | `vite.config.ts` | `exclude: ['better-sqlite3']` |
+
+### 原生模块审查报告模板
+
+```markdown
+## 原生模块兼容性报告
+
+### 新增依赖类型分析
+| 依赖名 | 类型 | 风险等级 | 处理方式 |
+|--------|------|----------|----------|
+| xxx | 原生模块 | 🔴 高 | 替换为 yyy |
+| zzz | 纯 JS | 🟢 低 | 直接使用 |
+
+### Electron 配置检查
+- [ ] electron-rebuild 已配置
+- [ ] asarUnpack 已配置
+- [ ] vite external 已配置
+- [ ] 🔴 运行时启动测试通过
+```
+
+## API Availability Verification
+
+**For EVERY external API call in the code under review:**
+
+| Question | How to Answer | Action if "No" |
+|----------|---------------|----------------|
+| Does this API exist in the framework version used? | Check official docs for the exact version | P1: Find alternative or upgrade |
+| Does this API work in the target environment? | Web vs Desktop vs Mobile constraints | P1: Use platform-appropriate API |
+| Is required configuration in place? | Check config files | P1: Add missing config |
+| Are security permissions configured? | Check capabilities, CSP, permissions | P0: Security misconfiguration |
+| Is there a working example in the codebase? | Search for similar usage | P2: Add test to verify |
+
+## Common Issues by Category
+
+### RPC/IPC Issues
+
+| Issue | Symptoms | Prevention |
+|-------|----------|------------|
+| Handler not registered | "command not found" or "no handler" errors | Verify backend registration |
+| Wrong import path | "module not found" errors | Check plugin/extension import paths |
+| Type mismatch | Serialization errors | Verify frontend/backend types match |
+
+### Security Issues
+
+| Issue | Symptoms | Prevention |
+|-------|----------|------------|
+| Missing permissions | "permission denied" errors | Check security configuration |
+| Overly permissive config | Security vulnerabilities | Follow principle of least privilege |
+| Improper context isolation | Data leakage between contexts | Verify isolation settings |
+
+### Asset/Resource Issues
+
+| Issue | Symptoms | Prevention |
+|-------|----------|------------|
+| Wrong protocol | 404 errors, broken images | Use platform-appropriate protocol |
+| Binary handling | Corrupted data, empty content | Use proper encoding (base64, etc.) |
+| Path separators | Works on dev, fails cross-platform | Use platform-aware path handling |
+
+## Platform Review Output Template
+
+```markdown
+## Platform-Specific Findings
+
+### RPC/IPC Commands
+| Command | Frontend Usage | Backend Registration | Status |
+|---------|----------------|----------------------|--------|
+| ... | ... | ... | ✅/P0/P1 |
+
+### Plugin/Extension Configuration
+| Plugin | Installed | Initialized | Config | Status |
+|--------|-----------|-------------|--------|--------|
+| ... | ✅/❌ | ✅/❌ | ... | ✅/P1 |
+
+### Security / Permissions
+| Permission | Required By | Configured | Status |
+|------------|-------------|------------|--------|
+| ... | ... | ✅/❌ | ✅/P0/P1 |
+
+### API Verification
+| API | Docs Verified | Platform Works | Config Ready | Status |
+|-----|---------------|----------------|--------------|--------|
+| ... | ✅/❌ | ✅/❌ | ✅/❌ | ✅/P1 |
+```
+
+## Framework-Specific Guides
+
+For detailed framework-specific checklists, consult official documentation:
+
+- **Tauri**: https://tauri.app/
+- **Electron**: https://www.electronjs.org/
+- **React Native**: https://reactnative.dev/
+- **Flutter**: https://flutter.dev/
+- **Qt**: https://doc.qt.io/
+
+Each framework has unique patterns for:
+- IPC/RPC mechanisms
+- Plugin/extension systems
+- Security models
+- Asset handling
+- Build configuration
+

package/.claude/skills/code-review/references/precision-analysis-protocol.md

@@ -0,0 +1,260 @@
+# 精准代码分析协议 (Precision Analysis Protocol)
+
+## 核心原则
+
+```
+分析计划先行 → 逻辑优先 → 证据驱动 → 逐文件验证
+```
+
+**Iron Law**: 没有分析计划不开始审查，没有证据不报告问题
+
+---
+
+## 🔴 Phase A: 分析计划制定 (MANDATORY FIRST)
+
+### Step 1: 代码范围扫描
+
+```markdown
+## 代码范围扫描
+
+**变更文件清单:**
+| # | 文件路径 | 变更类型 | 行数 | 复杂度预估 |
+|---|----------|----------|------|-----------|
+| 1 | src/auth/login.py | Modified | +50/-10 | 高 |
+| 2 | src/api/users.py | New | +120 | 中 |
+| 3 | tests/test_auth.py | Modified | +30 | 低 |
+
+**总计**: X 个文件, +Y/-Z 行
+```
+
+### Step 2: 依赖关系分析
+
+```markdown
+## 依赖关系图
+
+```
+login.py
+    ├── imports: users.py (直接依赖)
+    ├── imports: db/session.py (间接依赖)
+    └── called by: routes/auth.py (调用方)
+
+users.py
+    ├── imports: models/user.py
+    └── called by: login.py, admin.py
+```
+
+**关键路径**: login.py → users.py → models/user.py
+```
+
+### Step 3: 制定分析计划
+
+```markdown
+## 详细分析计划
+
+### 分析顺序 (按依赖关系)
+1. **models/user.py** - 基础模型，其他文件依赖
+2. **users.py** - 核心业务逻辑
+3. **login.py** - 入口逻辑
+4. **test_auth.py** - 测试覆盖
+
+### 每个文件的分析重点
+
+| 文件 | 逻辑分析重点 | 预期耗时 |
+|------|-------------|---------|
+| models/user.py | 数据模型完整性、字段约束 | 5min |
+| users.py | 🔴 核心业务逻辑、边界条件、错误处理 | 15min |
+| login.py | 🔴 认证流程、状态转换、异常路径 | 10min |
+| test_auth.py | 测试覆盖率、边界用例 | 5min |
+
+### 逻辑分析检查清单 (每个文件必须回答)
+
+- [ ] 所有条件分支是否都有处理？
+- [ ] 循环是否有正确的终止条件？
+- [ ] 异常情况是否都被捕获和处理？
+- [ ] 边界值是否正确处理？
+- [ ] 状态转换是否完整？
+- [ ] 返回值是否在所有路径上都有定义？
+```
+
+---
+
+## 🔴 Phase B: 逻辑优先分析 (LOGIC FIRST)
+
+### 逻辑问题优先级
+
+| 优先级 | 问题类型 | 示例 |
+|--------|---------|------|
+| **L0** | 逻辑错误 | 条件判断错误、循环逻辑错误 |
+| **L1** | 边界问题 | 空值未处理、数组越界、off-by-one |
+| **L2** | 状态问题 | 状态不一致、竞态条件 |
+| **L3** | 流程问题 | 异常路径未处理、资源未释放 |
+
+### 逻辑分析模板 (每个函数/方法)
+
+```markdown
+### 函数: `authenticate_user(username, password)`
+
+**1. 输入分析**
+- username: string | None? → 需要检查空值
+- password: string | None? → 需要检查空值
+
+**2. 条件分支追踪**
+```
+Line 10: if not username:     → 处理: return None ✅
+Line 12: if not password:     → 处理: return None ✅
+Line 15: if user is None:     → 处理: return None ✅
+Line 18: if not verify_pwd(): → 处理: ❌ 未处理! 直接 fall through
+Line 22: return user          → 正常路径 ✅
+```
+
+**3. 发现的逻辑问题**
+| 行号 | 问题 | 严重度 |
+|------|------|--------|
+| 18 | 密码验证失败时没有 return，会继续执行到 line 22 | **L0** |
+
+**4. 证据截图/代码片段**
+```python
+# Line 15-22 原始代码
+if user is None:
+    return None
+if not verify_password(password, user.hashed_password):
+    logger.warning("Invalid password")  # ❌ 没有 return!
+return user  # ❌ 密码错误也会返回 user
+```
+```
+
+---
+
+## 🔴 Phase C: 证据驱动报告 (EVIDENCE REQUIRED)
+
+### 证据要求
+
+**每个发现必须包含:**
+
+1. **文件路径 + 行号**: `src/auth/login.py:18`
+2. **原始代码片段**: 至少 3-5 行上下文
+3. **问题描述**: 具体说明什么逻辑有问题
+4. **影响分析**: 这个问题会导致什么后果
+5. **修复建议**: 具体的修复方案
+
+### 证据模板
+
+```markdown
+## 发现 #1: 密码验证逻辑缺陷
+
+**位置**: `src/auth/login.py:18-22`
+
+**证据 (原始代码)**:
+```python
+15 |     if user is None:
+16 |         return None
+17 |     if not verify_password(password, user.hashed_password):
+18 |         logger.warning("Invalid password")
+19 |         # ❌ 缺少 return 语句
+20 |     return user  # ❌ 即使密码错误也会执行到这里
+```
+
+**问题分析**:
+- Line 17-18: 密码验证失败后只记录日志，没有 return
+- Line 20: 无论密码是否正确都会返回 user 对象
+- 这是一个 **认证绕过漏洞**
+
+**影响**:
+- 任何用户只要知道用户名就能登录
+- 严重度: **P0 (安全漏洞)**
+
+**修复建议**:
+```python
+if not verify_password(password, user.hashed_password):
+    logger.warning("Invalid password")
+    return None  # 添加 return
+return user
+```
+
+**验证方法**:
+- 单元测试: 使用错误密码登录应返回 None
+- 集成测试: 错误密码应返回 401
+```
+
+---
+
+## 🔴 Phase D: 分析完成确认 (COMPLETION VERIFICATION)
+
+### 文件分析完成检查清单
+
+```markdown
+## 文件分析完成确认: `src/auth/login.py`
+
+### 分析覆盖证明
+
+| 检查项 | 状态 | 证据 |
+|--------|------|------|
+| 所有函数已分析 | ✅ | 分析了 3/3 个函数 |
+| 所有条件分支已追踪 | ✅ | 追踪了 8 个 if/else |
+| 所有循环已检查 | ✅ | 检查了 2 个 for 循环 |
+| 所有异常处理已审查 | ✅ | 审查了 3 个 try/except |
+| 所有返回路径已验证 | ✅ | 验证了 5 个 return |
+
+### 分析的函数清单
+
+| 函数名 | 行号 | 逻辑问题 | 其他问题 |
+|--------|------|---------|---------|
+| `authenticate_user` | 10-25 | 1 个 L0 | 0 |
+| `create_session` | 27-45 | 0 | 1 个 P2 |
+| `logout` | 47-55 | 0 | 0 |
+
+### 本文件发现汇总
+
+| 严重度 | 数量 | 行号 |
+|--------|------|------|
+| L0 (逻辑错误) | 1 | 18 |
+| L1 (边界问题) | 0 | - |
+| P2 (其他) | 1 | 35 |
+
+**文件分析状态**: ✅ 完成
+```
+
+---
+
+## 输出契约
+
+### 分析报告结构
+
+```markdown
+# Code Review Report
+
+## 1. 分析计划
+[Phase A 的输出]
+
+## 2. 逐文件分析
+
+### 文件 1: src/auth/login.py
+[Phase B + C 的输出]
+[Phase D 的完成确认]
+
+### 文件 2: src/api/users.py
+[Phase B + C 的输出]
+[Phase D 的完成确认]
+
+## 3. 发现汇总
+
+### 逻辑问题 (优先处理)
+| # | 文件:行号 | 问题 | 严重度 |
+|---|-----------|------|--------|
+| 1 | login.py:18 | 密码验证逻辑缺陷 | L0 |
+
+### 其他问题
+| # | 文件:行号 | 问题 | 严重度 |
+|---|-----------|------|--------|
+| 1 | users.py:35 | 缺少输入验证 | P2 |
+
+## 4. 分析完成确认
+
+| 文件 | 分析状态 | 逻辑问题 | 其他问题 |
+|------|---------|---------|---------|
+| login.py | ✅ 完成 | 1 | 0 |
+| users.py | ✅ 完成 | 0 | 1 |
+| test_auth.py | ✅ 完成 | 0 | 0 |
+
+**总计**: 3/3 文件已分析, 1 个逻辑问题, 1 个其他问题
+```