sumulige-claude 1.2.1 → 1.3.1

package/.claude/commands/plan.md

@@ -0,0 +1,88 @@
+---
+description: Plan implementation with architecture design
+---
+
+# /plan
+
+为功能或任务创建实现计划，支持快速规划和深度设计。
+
+## 使用方式
+
+```bash
+/plan              # 快速规划（默认）
+/plan --deep       # 深度设计（架构决策）
+/plan --arch       # 仅架构设计
+```
+
+## 关联 Skill
+
+此命令加载 `design-brain` skill（复杂任务使用 opus）。
+
+---
+
+## 工作流程
+
+### 快速规划（默认）
+
+```markdown
+# Plan: [功能名称]
+
+## Goal
+[一句话描述]
+
+## Steps
+1. [ ] [步骤 1]
+2. [ ] [步骤 2]
+3. [ ] [步骤 3]
+
+## Files
+- `path/to/file.ts` - [修改内容]
+
+## Risk
+- [主要风险] → [缓解策略]
+```
+
+### 深度设计（--deep）
+
+```markdown
+# Design: [系统名称]
+
+## Overview
+[背景和目标]
+
+## Architecture
+[组件图 + 数据流]
+
+## Technical Decisions
+| Decision | Choice | Reason | Trade-offs |
+|----------|--------|--------|------------|
+
+## Implementation Plan
+### Phase 1: [阶段名]
+1. [ ] Step 1
+2. [ ] Step 2
+
+## Risks
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+
+## Success Criteria
+- [ ] 标准 1
+- [ ] 标准 2
+```
+
+---
+
+## 设计原则
+
+1. **简单优于复杂** - 能用简单方案就不要复杂化
+2. **最小变更** - 优先复用现有代码
+3. **可测试性** - 每个步骤都可验证
+
+## 使用场景
+
+| 场景 | 推荐模式 |
+|------|---------|
+| 小功能/bug 修复 | 快速规划 |
+| 新模块/系统 | 深度设计 |
+| 技术选型 | --arch |

package/.claude/commands/refactor.md

@@ -0,0 +1,102 @@
+---
+description: Safe code refactoring and cleanup
+---
+
+# /refactor
+
+安全的代码重构和清理。
+
+## 使用方式
+
+```bash
+/refactor              # 分析并建议清理（默认）
+/refactor --dead       # 查找死代码
+/refactor --deps       # 查找未使用依赖
+/refactor --duplicate  # 查找重复代码
+/refactor --execute    # 执行清理（需确认）
+```
+
+## 关联 Skill
+
+此命令加载 `quality-guard` skill（清理模式）。
+
+---
+
+## 工作流程
+
+### Step 1: 运行分析工具
+
+```bash
+# 未使用的文件、导出、依赖
+npx knip
+
+# 未使用的 npm 依赖
+npx depcheck
+
+# 未使用的 TypeScript 导出
+npx ts-prune
+
+# 未使用的 eslint-disable
+npx eslint . --report-unused-disable-directives
+```
+
+### Step 2: 风险分类
+
+| 风险 | 类型 | 处理 |
+|------|------|------|
+| 🟢 SAFE | 未使用导出、测试文件 | 可直接删除 |
+| 🟡 CAREFUL | 动态导入可能使用 | 需验证 |
+| 🔴 RISKY | 公共 API、配置文件 | 谨慎处理 |
+
+### Step 3: 生成报告
+
+```markdown
+# Refactor Report
+
+## Dead Code
+| File | Type | Risk | Reason |
+|------|------|------|--------|
+
+## Unused Dependencies
+| Package | Size | Last Used |
+|---------|------|-----------|
+
+## Duplicate Code
+| Location 1 | Location 2 | Lines |
+|------------|------------|-------|
+
+## Recommended Actions
+1. [ ] Remove unused-package (SAFE)
+2. [ ] Delete src/old.ts (SAFE)
+3. [ ] Review src/utils.ts (CAREFUL)
+
+## Impact
+- Files to delete: X
+- Dependencies to remove: Y
+- Lines of code: -Z
+```
+
+### Step 4: 执行清理（--execute）
+
+```
+⚠️ 执行前：
+1. 创建备份分支
+2. 确保测试通过
+3. 逐个删除，每删一个运行测试
+4. 记录到 DELETION_LOG.md
+```
+
+---
+
+## 安全检查清单
+
+删除前：
+- [ ] grep 所有引用
+- [ ] 检查动态导入
+- [ ] 查看 git 历史
+- [ ] 运行所有测试
+
+删除后：
+- [ ] 构建成功
+- [ ] 测试通过
+- [ ] 提交变更

package/.claude/hooks/pre-push.cjs

@@ -41,7 +41,8 @@ async function main() {
       stdio: 'pipe'
     }).trim() || 'origin/main';
 
-    const output = execSync(`git diff --name-only ${upstream}...HEAD`, {
+    // Use --diff-filter=ACMR to exclude deleted files (D)
+    const output = execSync(`git diff --name-only --diff-filter=ACMR ${upstream}...HEAD`, {
       encoding: 'utf-8',
       stdio: 'pipe'
     });
@@ -85,7 +86,7 @@ async function main() {
 
   const result = await gate.check({
     files: checkable.map(f => path.join(projectDir, f)),
-    severity: 'warn' // Block on warnings too for push
+    severity: 'error' // Only block on errors, not warnings
   });
 
   if (!result.passed) {

package/.claude/rules/coding-style.md

@@ -0,0 +1,119 @@
+# Coding Style Rules
+
+> 代码风格规则 - 所有代码必须遵守
+
+## 不可变性 (CRITICAL)
+
+**始终创建新对象，永不变异：**
+
+```javascript
+// ❌ 错误：变异
+function updateUser(user, name) {
+  user.name = name  // 变异！
+  return user
+}
+
+// ✅ 正确：不可变
+function updateUser(user, name) {
+  return {
+    ...user,
+    name
+  }
+}
+```
+
+## 文件组织
+
+**多个小文件 > 少数大文件：**
+
+| 规则 | 阈值 |
+|------|------|
+| 典型文件 | 200-400 行 |
+| 最大文件 | 800 行 |
+| 组织方式 | 按功能/领域，而非按类型 |
+
+原则：高内聚，低耦合
+
+## 错误处理
+
+**始终全面处理错误：**
+
+```typescript
+try {
+  const result = await riskyOperation()
+  return result
+} catch (error) {
+  console.error('Operation failed:', error)
+  throw new Error('用户友好的详细错误信息')
+}
+```
+
+## 输入验证
+
+**始终验证用户输入：**
+
+```typescript
+import { z } from 'zod'
+
+const schema = z.object({
+  email: z.string().email(),
+  age: z.number().int().min(0).max(150)
+})
+
+const validated = schema.parse(input)
+```
+
+## 代码质量检查清单
+
+完成工作前确认：
+
+- [ ] 代码可读、命名良好
+- [ ] 函数小（< 50 行）
+- [ ] 文件聚焦（< 800 行）
+- [ ] 无深嵌套（> 4 层）
+- [ ] 适当的错误处理
+- [ ] 无 console.log 语句
+- [ ] 无硬编码值
+- [ ] 无变异（使用不可变模式）
+
+## 命名规范
+
+| 类型 | 规范 | 示例 |
+|------|------|------|
+| 变量 | camelCase | `userName`, `isActive` |
+| 常量 | SCREAMING_SNAKE | `MAX_RETRY`, `API_URL` |
+| 函数 | camelCase, 动词开头 | `getUserById`, `validateInput` |
+| 类/组件 | PascalCase | `UserProfile`, `DataService` |
+| 文件 | kebab-case 或 PascalCase | `user-service.ts`, `UserProfile.tsx` |
+
+## 禁止的模式
+
+```typescript
+// ❌ 魔法数字
+if (status === 200) { ... }
+
+// ✅ 使用常量
+const HTTP_OK = 200
+if (status === HTTP_OK) { ... }
+
+// ❌ 变量名不清晰
+const x = getUser()
+const tmp = process(data)
+
+// ✅ 描述性命名
+const currentUser = getUser()
+const processedData = process(data)
+
+// ❌ 直接变异数组
+arr.push(item)
+arr.sort()
+
+// ✅ 创建新数组
+const newArr = [...arr, item]
+const sortedArr = [...arr].sort()
+```
+
+## 相关命令
+
+- `/code-review` - 代码审查
+- `/refactor-clean` - 重构清理

package/.claude/rules/hooks.md

@@ -0,0 +1,288 @@
+# Hooks 最佳实践
+
+> 自动化钩子使用指南 - 融合自 everything-claude-code
+
+## Hook 类型
+
+| 类型 | 触发时机 | 用途 |
+|------|---------|------|
+| PreToolUse | 工具执行前 | 验证、准备、确认 |
+| PostToolUse | 工具执行后 | 格式化、检查、通知 |
+| Stop | 会话结束时 | 总结、清理、保存 |
+
+## 推荐的 Hook 配置
+
+### PreToolUse Hooks
+
+**1. Git Push 审查**
+
+在 `git push` 前确认分支和状态：
+
+```javascript
+// hooks/git-push-review.cjs
+module.exports = {
+  event: 'PreToolUse',
+  condition: (input) => {
+    return input.tool === 'Bash' &&
+           input.input?.command?.includes('git push')
+  },
+  action: async (input, context) => {
+    // 获取当前分支
+    const branch = execSync('git branch --show-current').toString().trim()
+
+    // 检查是否推送到 main/master
+    if (branch === 'main' || branch === 'master') {
+      return {
+        decision: 'ask',
+        message: `即将推送到 ${branch} 分支，确认继续？`
+      }
+    }
+
+    return { decision: 'allow' }
+  }
+}
+```
+
+**2. 敏感文件保护**
+
+防止修改关键配置文件：
+
+```javascript
+// hooks/protect-sensitive.cjs
+const PROTECTED_PATTERNS = [
+  '.env',
+  'credentials',
+  'secrets',
+  '*.pem',
+  '*.key'
+]
+
+module.exports = {
+  event: 'PreToolUse',
+  condition: (input) => {
+    return ['Write', 'Edit'].includes(input.tool)
+  },
+  action: async (input, context) => {
+    const filePath = input.input?.file_path || ''
+
+    for (const pattern of PROTECTED_PATTERNS) {
+      if (filePath.includes(pattern) ||
+          filePath.endsWith(pattern.replace('*', ''))) {
+        return {
+          decision: 'ask',
+          message: `即将修改敏感文件 ${filePath}，确认继续？`
+        }
+      }
+    }
+
+    return { decision: 'allow' }
+  }
+}
+```
+
+### PostToolUse Hooks
+
+**1. 自动格式化**
+
+写入文件后自动运行 Prettier：
+
+```javascript
+// hooks/auto-format.cjs
+const { execSync } = require('child_process')
+
+const FORMATTABLE_EXTENSIONS = [
+  '.js', '.jsx', '.ts', '.tsx',
+  '.json', '.md', '.css', '.scss'
+]
+
+module.exports = {
+  event: 'PostToolUse',
+  condition: (input, output) => {
+    if (!['Write', 'Edit'].includes(input.tool)) return false
+
+    const filePath = input.input?.file_path || ''
+    return FORMATTABLE_EXTENSIONS.some(ext => filePath.endsWith(ext))
+  },
+  action: async (input, output, context) => {
+    const filePath = input.input?.file_path
+
+    try {
+      execSync(`npx prettier --write "${filePath}"`, {
+        stdio: 'pipe'
+      })
+      return { message: `已格式化: ${filePath}` }
+    } catch (error) {
+      // Prettier 未安装或格式化失败，静默处理
+      return null
+    }
+  }
+}
+```
+
+**2. TypeScript 类型检查**
+
+编辑 TS 文件后检查类型：
+
+```javascript
+// hooks/type-check.cjs
+const { execSync } = require('child_process')
+
+module.exports = {
+  event: 'PostToolUse',
+  condition: (input, output) => {
+    if (!['Write', 'Edit'].includes(input.tool)) return false
+
+    const filePath = input.input?.file_path || ''
+    return filePath.endsWith('.ts') || filePath.endsWith('.tsx')
+  },
+  action: async (input, output, context) => {
+    try {
+      execSync('npx tsc --noEmit', {
+        stdio: 'pipe',
+        timeout: 30000
+      })
+      return { message: '类型检查通过' }
+    } catch (error) {
+      const stderr = error.stderr?.toString() || ''
+      if (stderr.includes('error')) {
+        return {
+          message: `类型错误:\n${stderr.slice(0, 500)}`
+        }
+      }
+      return null
+    }
+  }
+}
+```
+
+**3. Console.log 警告**
+
+检测遗留的调试语句：
+
+```javascript
+// hooks/console-warning.cjs
+const fs = require('fs')
+
+module.exports = {
+  event: 'PostToolUse',
+  condition: (input, output) => {
+    if (!['Write', 'Edit'].includes(input.tool)) return false
+
+    const filePath = input.input?.file_path || ''
+    return filePath.endsWith('.ts') ||
+           filePath.endsWith('.tsx') ||
+           filePath.endsWith('.js') ||
+           filePath.endsWith('.jsx')
+  },
+  action: async (input, output, context) => {
+    const filePath = input.input?.file_path
+
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8')
+      const consoleMatches = content.match(/console\.(log|debug|info)\(/g)
+
+      if (consoleMatches && consoleMatches.length > 0) {
+        return {
+          message: `警告: 文件中有 ${consoleMatches.length} 个 console 语句，提交前请移除`
+        }
+      }
+    } catch (error) {
+      // 文件读取失败，静默处理
+    }
+
+    return null
+  }
+}
+```
+
+### Stop Hooks
+
+**会话总结**
+
+会话结束时生成进度总结：
+
+```javascript
+// hooks/session-summary.cjs
+module.exports = {
+  event: 'Stop',
+  action: async (context) => {
+    const summary = {
+      timestamp: new Date().toISOString(),
+      filesModified: context.modifiedFiles || [],
+      tasksCompleted: context.completedTasks || [],
+      pendingTasks: context.pendingTasks || []
+    }
+
+    // 保存到会话日志
+    const logPath = '.claude/session-logs/latest.json'
+    fs.writeFileSync(logPath, JSON.stringify(summary, null, 2))
+
+    return {
+      message: `会话已保存，修改了 ${summary.filesModified.length} 个文件`
+    }
+  }
+}
+```
+
+## Hook 编写原则
+
+### 1. 快速执行
+
+```
+Hook 不应阻塞主流程超过 2 秒
+使用超时保护
+异步操作不要等待
+```
+
+### 2. 静默失败
+
+```
+Hook 失败不应中断主流程
+记录错误但继续执行
+提供有意义的错误信息
+```
+
+### 3. 最小权限
+
+```
+只请求必要的权限
+不修改不相关的文件
+不执行危险命令
+```
+
+### 4. 可配置
+
+```
+支持通过环境变量配置
+允许禁用特定 hook
+提供合理的默认值
+```
+
+## 现有 Hooks 清单
+
+当前项目 `.claude/hooks/` 已有：
+
+| Hook | 功能 |
+|------|------|
+| code-formatter.cjs | 代码格式化 |
+| multi-session.cjs | 多会话管理 |
+| project-kickoff.cjs | 项目初始化 |
+| rag-skill-loader.cjs | RAG 技能加载 |
+| session-restore.cjs | 会话恢复 |
+| session-save.cjs | 会话保存 |
+| todo-manager.cjs | TODO 管理 |
+| verify-work.cjs | 工作验证 |
+
+## 调试 Hooks
+
+```bash
+# 启用 hook 调试日志
+export CLAUDE_HOOK_DEBUG=true
+
+# 查看 hook 执行日志
+tail -f .claude/logs/hooks.log
+```
+
+---
+
+**记住**：Hooks 是强大的自动化工具，但要谨慎使用。过多的 hooks 会影响性能，过于激进的 hooks 会干扰正常工作流程。

package/.claude/rules/performance.md

@@ -0,0 +1,78 @@
+# Performance Rules
+
+> 性能和资源管理规则
+
+## 模型选择策略
+
+根据任务复杂度选择合适的模型：
+
+| 模型 | 适用场景 | 成本 |
+|------|---------|------|
+| **Haiku** | 简单任务、高频调用、轻量 agent | 最低 |
+| **Sonnet** | 主要开发、代码生成、工作流编排 | 中等 |
+| **Opus** | 复杂架构决策、深度推理、研究分析 | 最高 |
+
+### 推荐配置
+
+```
+Conductor   → Sonnet (需要全局理解)
+Architect   → Opus (需要深度思考)
+Builder     → Sonnet (主要编码工作)
+Reviewer    → Opus (需要严谨分析)
+Librarian   → Haiku (文档整理)
+```
+
+## Context Window 管理
+
+**关键原则**：避免在 context 的最后 20% 进行复杂操作
+
+### 高 Context 敏感任务（避免在 context 末尾）
+- 大规模重构
+- 跨多文件的功能实现
+- 复杂交互调试
+
+### 低 Context 敏感任务（可在任何时候）
+- 单文件编辑
+- 独立工具创建
+- 文档更新
+- 简单 bug 修复
+
+## MCP 管理
+
+**关键**：不要同时启用所有 MCP
+
+- 200k context 可能被压缩到 70k
+- 建议配置 20-30 个 MCP
+- 每个项目启用不超过 10 个
+- 活跃工具保持在 80 个以下
+
+### 禁用不需要的 MCP
+
+在项目 `settings.json` 中：
+
+```json
+{
+  "disabledMcpServers": [
+    "unused-mcp-1",
+    "unused-mcp-2"
+  ]
+}
+```
+
+## 构建故障排除
+
+构建失败时：
+
+1. 使用 **build-error-resolver** skill
+2. 分析错误信息
+3. 增量修复
+4. 每次修复后验证
+
+## 复杂任务策略
+
+对于需要深度推理的任务：
+
+1. 使用 `ultrathink` 模式增强思考
+2. 启用 **Plan Mode** 进行结构化方案
+3. 多轮自我批判优化
+4. 使用分角色 sub-agents 进行多角度分析