sumulige-claude 1.1.2 → 1.2.1

package/.claude/templates/TASK_PLAN.md

@@ -0,0 +1,121 @@
+# 任务执行计划 (Task Execution Plan)
+
+> 本文件由 AI 在项目启动时生成，执行时持续更新
+> 关联文件: PROJECT_KICKOFF.md, ARCHITECTURE.md
+
+---
+
+## 任务概览
+
+```
+总任务数: {TOTAL_TASKS} | 已完成: {COMPLETED} | 进行中: {IN_PROGRESS} | 待开始: {PENDING}
+进度: {PERCENTAGE}%
+```
+
+---
+
+## 任务分解 (WBS)
+
+### Phase 1: {PHASE_1_NAME}
+| ID | 任务 | 依赖 | 预估 | 优先级 | 状态 | 负责Agent |
+|----|------|------|------|--------|------|-----------|
+| T1.1 | {TASK_NAME} | - | {EST} | P0 | ⏳ | {AGENT} |
+| T1.2 | {TASK_NAME} | T1.1 | {EST} | P0 | ⏳ | {AGENT} |
+
+### Phase 2: {PHASE_2_NAME}
+| ID | 任务 | 依赖 | 预估 | 优先级 | 状态 | 负责Agent |
+|----|------|------|------|--------|------|-----------|
+| T2.1 | {TASK_NAME} | T1.2 | {EST} | P1 | ⏳ | {AGENT} |
+
+### Phase 3: {PHASE_3_NAME}
+| ID | 任务 | 依赖 | 预估 | 优先级 | 状态 | 负责Agent |
+|----|------|------|------|--------|------|-----------|
+| T3.1 | {TASK_NAME} | T2.1 | {EST} | P2 | ⏳ | {AGENT} |
+
+---
+
+## 依赖关系图
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        任务依赖图                            │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│   [T1.1] ──► [T1.2] ──► [T1.3]                            │
+│                │                                            │
+│                └───► [T2.1] ──► [T2.2]                     │
+│                         │                                  │
+│                         └───► [T3.1]                       │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 里程碑
+
+| 里程碑 | 包含任务 | 预计完成 | 实际完成 | 状态 |
+|--------|----------|----------|----------|------|
+| M1: {MILESTONE} | T1.1-T1.3 | {DATE} | - | ⏳ |
+| M2: {MILESTONE} | T2.1-T2.2 | {DATE} | - | ⏳ |
+| M3: {MILESTONE} | T3.1 | {DATE} | - | ⏳ |
+
+---
+
+## 风险登记
+
+| 风险 | 可能性 | 影响 | 缓解措施 | 状态 |
+|------|--------|------|----------|------|
+| {RISK} | 高/中/低 | 高/中/低 | {MITIGATION} | 🟡 |
+
+---
+
+## 执行日志
+
+### {DATE}
+- **T1.1 完成**: {NOTES}
+- **T1.2 启动**: {NOTES}
+
+---
+
+## Agent 分配规则
+
+| Agent | 擅长任务 | 默认分配 |
+|-------|----------|----------|
+| **Conductor** | 任务分解、依赖分析、风险评估 | Phase 启动 |
+| **Architect** | 架构设计、技术选型、接口定义 | 架构相关任务 |
+| **Builder** | 功能实现、单元测试、Bug 修复 | 开发任务 |
+| **Reviewer** | 代码审查、质量检查、性能优化 | 审查任务 |
+| **Librarian** | 文档编写、知识整理、注释更新 | 文档任务 |
+
+---
+
+## 检查点策略
+
+| 检查点 | 触发条件 | Human 确认 |
+|--------|----------|------------|
+| CP1 | Phase 1 完成 | ✅ 必需 |
+| CP2 | 架构变更 | ✅ 必需 |
+| CP3 | 数据模型变更 | ✅ 必需 |
+| CP4 | 里程碑完成 | ✅ 确认 |
+
+---
+
+## 状态图例
+
+| 图例 | 含义 |
+|------|------|
+| ⏳ | 待开始 (Pending) |
+| 🔄 | 进行中 (In Progress) |
+| ✅ | 已完成 (Completed) |
+| ⏸️ | 阻塞 (Blocked) |
+| ❌ | 取消 (Cancelled) |
+| 🛑 | 等待确认 (Waiting for Human) |
+
+---
+
+## 下一步行动
+
+1. **当前任务**: {CURRENT_TASK}
+2. **阻塞问题**: {BLOCKERS}
+3. **需要决策**: {DECISIONS_NEEDED}

package/.claude/templates/hooks/README.md

@@ -0,0 +1,302 @@
+# Claude Code Hooks 模板库
+
+> 标准化 hook 开发，防止常见错误
+
+---
+
+## 📋 目录
+
+- [快速开始](#快速开始)
+- [Hook 类型](#hook-类型)
+- [最佳实践](#最佳实践)
+- [常见错误](#常见错误)
+- [检查清单](#检查清单)
+
+---
+
+## 🚀 快速开始
+
+### 1. 选择模板
+
+```bash
+# UserPromptSubmit hook (用户提交提示时触发)
+cp user-prompt-submit.cjs.template my-hook.cjs
+
+# UserResponseSubmit hook (AI 返回响应后触发)
+cp user-response-submit.cjs.template my-hook.cjs
+
+# Shell hook
+cp hook.sh.template my-hook.sh
+```
+
+### 2. 修改配置
+
+```javascript
+// 修改配置区域
+const CONFIG = {
+  enabled: true,
+  verbose: false,  // 开发时设为 true
+};
+```
+
+### 3. 实现逻辑
+
+在标记区域添加你的代码：
+
+```javascript
+// ===== 在这里实现你的 hook 逻辑 =====
+
+// 你的代码
+
+// ===== Hook 逻辑结束 =====
+```
+
+### 4. 测试
+
+```bash
+# 添加执行权限
+chmod +x my-hook.cjs
+
+# 测试（模拟环境变量）
+CLAUDE_PROJECT_DIR=/path/to/project node my-hook.cjs
+
+# 开启调试模式
+VERBOSE=true CLAUDE_PROJECT_DIR=/path/to/project node my-hook.cjs
+```
+
+---
+
+## 📦 Hook 类型
+
+### UserPromptSubmit
+
+用户每次提交提示时触发。
+
+**可用环境变量:**
+- `CLAUDE_PROJECT_DIR` - 项目根目录
+- `CLAUDE_TOOL_NAME` - 当前调用的工具名
+- `CLAUDE_TOOL_INPUT` - 工具输入内容
+
+**使用场景:**
+- 追踪用户操作
+- 记录工具调用
+- 触发自动化流程
+
+### UserResponseSubmit
+
+AI 返回响应后触发。
+
+**可用环境变量:**
+- `CLAUDE_PROJECT_DIR` - 项目根目录
+- `CLAUDE_RESPONSE_CONTENT` - 响应内容
+
+**使用场景:**
+- 分析响应内容
+- 统计 token 使用
+- 自动保存代码
+
+---
+
+## ✅ 最佳实践
+
+### 1. 环境变量处理
+
+```javascript
+// ✅ 正确 - 提供 fallback
+const PROJECT_DIR = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+// ❌ 错误 - 直接使用可能 undefined
+const PROJECT_DIR = process.env.CLAUDE_PROJECT_DIR;
+```
+
+### 2. 静默退出
+
+```javascript
+// ✅ 正确 - 非项目环境时静默退出
+if (!process.env.CLAUDE_PROJECT_DIR) {
+  process.exit(0);
+}
+
+// ❌ 错误 - 会抛出异常
+if (!process.env.CLAUDE_PROJECT_DIR) {
+  throw new Error('No project dir');
+}
+```
+
+### 3. 错误处理
+
+```javascript
+// ✅ 正确 - 捕获所有错误
+try {
+  // 你的逻辑
+} catch (error) {
+  log('Error:', error.message);
+}
+
+// ❌ 错误 - 未捕获错误会显示给用户
+// 直接执行可能失败的操作
+```
+
+### 4. 文件操作
+
+```javascript
+// ✅ 正确 - 安全的文件操作
+function safeWriteFile(filePath, content) {
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content, 'utf-8');
+    return true;
+  } catch (e) {
+    return false;  // 静默失败
+  }
+}
+
+// ❌ 错误 - 可能因为目录不存在而失败
+fs.writeFileSync(filePath, content);
+```
+
+### 5. 输出控制
+
+```javascript
+// ✅ 正确 - 使用 stderr 记录日志
+function log(...args) {
+  console.error('[Hook]', ...args);
+}
+
+// ❌ 错误 - stdout 会干扰响应
+console.log(...args);
+```
+
+---
+
+## 🐛 常见错误
+
+### 错误 1: 未检查环境变量
+
+```javascript
+// ❌ 问题代码
+const dir = path.join(process.env.CLAUDE_PROJECT_DIR, 'subdir');
+
+// ✅ 修复
+const PROJECT_DIR = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+if (!process.env.CLAUDE_PROJECT_DIR) {
+  process.exit(0);
+}
+const dir = path.join(PROJECT_DIR, 'subdir');
+```
+
+### 错误 2: 未捕获异常
+
+```javascript
+// ❌ 问题代码
+function main() {
+  const data = JSON.parse(fs.readFileSync('data.json'));  // 文件不存在会崩溃
+}
+
+// ✅ 修复
+function main() {
+  try {
+    const data = JSON.parse(fs.readFileSync('data.json') || '{}');
+  } catch (e) {
+    // 静默处理
+  }
+}
+```
+
+### 错误 3: 输出到 stdout
+
+```javascript
+// ❌ 问题代码
+console.log('Processing...');  // 会出现在用户对话中
+
+// ✅ 修复
+function log(...args) {
+  if (CONFIG.verbose) {
+    console.error('[Hook]', ...args);  // stderr 不影响对话
+  }
+}
+```
+
+### 错误 4: 忘记退出码
+
+```javascript
+// ❌ 问题代码
+main();  // 可能返回非零退出码
+
+// ✅ 修复
+try {
+  main();
+} catch (e) {
+  // ...
+}
+process.exit(0);  // 始终返回成功
+```
+
+---
+
+## 📝 Hook 开发检查清单
+
+在提交新 hook 前，确保：
+
+- [ ] **环境变量**: 使用 `|| process.cwd()` 提供 fallback
+- [ ] **静默退出**: 非项目环境时 `process.exit(0)`
+- [ ] **错误处理**: 所有可能失败的操作都在 try-catch 中
+- [ ] **文件操作**: 使用安全函数，目录不存在时自动创建
+- [ ] **输出控制**: 调试信息使用 stderr，生产环境静默
+- [ ] **退出码**: 始终返回 0，不影响 Claude Code
+- [ ] **执行权限**: Shell hooks 有 `chmod +x`
+- [ ] **测试**: 在有/无 CLAUDE_PROJECT_DIR 环境下都测试过
+
+---
+
+## 🔧 调试技巧
+
+### 开启调试模式
+
+```bash
+# 临时开启
+VERBOSE=true CLAUDE_PROJECT_DIR=/path/to/project node my-hook.cjs
+
+# 或修改配置
+const CONFIG = {
+  verbose: true,  // 开启调试
+};
+```
+
+### 查看日志
+
+```bash
+# 追踪执行
+node my-hook.cjs 2>&1 | tee hook-debug.log
+
+# 检查退出码
+node my-hook.cjs; echo "Exit code: $?"
+```
+
+### 常用测试命令
+
+```bash
+# 模拟完整环境
+CLAUDE_PROJECT_DIR=$(pwd) \
+CLAUDE_TOOL_NAME=Edit \
+CLAUDE_TOOL_INPUT="test input" \
+node my-hook.cjs
+
+# 测试错误处理
+CLAUDE_PROJECT_DIR="" node my-hook.cjs
+```
+
+---
+
+## 📚 现有 Hooks 参考
+
+| Hook | 功能 | 关键技术 |
+|------|------|----------|
+| `todo-manager.cjs` | 任务管理 | 目录扫描、状态流转 |
+| `thinking-silent.cjs` | 对话追踪 | 静默执行、定期同步 |
+| `code-formatter.cjs` | 代码格式化 | 文件监听、外部调用 |
+| `multi-session.cjs` | 多会话管理 | 会话追踪、状态恢复 |
+
+---
+
+> **维护**: 添加新 hook 时，请基于模板创建并更新本文档

package/.claude/templates/hooks/hook.sh.template

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+#
+# [Hook Name] - Shell Hook Template
+#
+# 触发时机: [说明触发时机]
+# 环境变量:
+#   - CLAUDE_PROJECT_DIR: 项目根目录
+#
+# @version 1.0.0
+#
+
+set -euo pipefail  # 严格模式
+
+# ============================================================
+# 标准头部 - 所有 hooks 必须包含
+# ============================================================
+
+# 获取项目目录，提供 fallback
+CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+
+# 如果不在项目环境中，静默退出
+[[ -z "${CLAUDE_PROJECT_DIR:-}" ]] && exit 0
+
+# ============================================================
+# 配置区域
+# ============================================================
+
+VERBOSE="${VERBOSE:-false}"
+HOOKS_DIR="$CLAUDE_PROJECT_DIR/.claude/hooks"
+DATA_DIR="$HOOKS_DIR/.data"
+
+# ============================================================
+# 工具函数
+// ============================================================
+
+# 安全日志
+log() {
+    if [[ "$VERBOSE" == "true" ]]; then
+        echo "[Hook] $*" >&2
+    fi
+}
+
+# 确保目录存在
+ensure_dir() {
+    local dir="$1"
+    mkdir -p "$dir" 2>/dev/null || true
+}
+
+# 安全读取文件
+safe_read() {
+    local file="$1"
+    local default="${2:-}"
+    if [[ -f "$file" ]]; then
+        cat "$file" 2>/dev/null || echo "$default"
+    else
+        echo "$default"
+    fi
+}
+
+# 安全写入文件
+safe_write() {
+    local file="$1"
+    local content="$2"
+    ensure_dir "$(dirname "$file")"
+    echo "$content" > "$file" 2>/dev/null || true
+}
+
+# ============================================================
+# Hook 核心逻辑
+# ============================================================
+
+main() {
+    # 错误处理：任何错误都静默处理，不影响 Claude Code
+    {
+
+        log "Project: $CLAUDE_PROJECT_DIR"
+
+        # ===== 在这里实现你的 hook 逻辑 =====
+
+        # 示例: 记录执行时间
+        local timestamp_file="$DATA_DIR/last-run.txt"
+        safe_write "$timestamp_file" "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+
+        # ===== Hook 逻辑结束 =====
+
+    } || true
+}
+
+# ============================================================
+# 执行
+# ============================================================
+
+main
+exit 0

package/.claude/templates/hooks/user-prompt-submit.cjs.template

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * [Hook Name] - UserPromptSubmit Hook Template
+ *
+ * 触发时机: 用户每次提交提示时
+ * 环境变量:
+ *   - CLAUDE_PROJECT_DIR: 项目根目录
+ *   - CLAUDE_TOOL_NAME: 当前调用的工具名
+ *   - CLAUDE_TOOL_INPUT: 工具输入内容
+ *
+ * @version 1.0.0
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ============================================================
+// 标准头部 - 所有 hooks 必须包含
+// ============================================================
+
+const PROJECT_DIR = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+// 如果不在 Claude Code 环境中运行，静默退出
+if (!process.env.CLAUDE_PROJECT_DIR) {
+  process.exit(0);
+}
+
+// ============================================================
+// 配置区域
+// ============================================================
+
+const CONFIG = {
+  // 你的 hook 配置
+  enabled: true,
+  verbose: false,  // 设为 true 开启调试输出
+};
+
+// ============================================================
+// 工具函数
+// ============================================================
+
+/**
+ * 安全日志 - 只有 verbose=true 时才输出
+ */
+function log(...args) {
+  if (CONFIG.verbose) {
+    console.error('[Hook]', ...args);
+  }
+}
+
+/**
+ * 安全读取文件
+ */
+function safeReadFile(filePath, defaultValue = '') {
+  try {
+    return fs.readFileSync(filePath, 'utf-8');
+  } catch (e) {
+    return defaultValue;
+  }
+}
+
+/**
+ * 安全写入文件
+ */
+function safeWriteFile(filePath, content) {
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content, 'utf-8');
+    return true;
+  } catch (e) {
+    log('Write error:', e.message);
+    return false;
+  }
+}
+
+// ============================================================
+// Hook 核心逻辑
+// ============================================================
+
+/**
+ * 主处理函数
+ */
+function main() {
+  try {
+    // 获取环境变量
+    const toolName = process.env.CLAUDE_TOOL_NAME || '';
+    const toolInput = process.env.CLAUDE_TOOL_INPUT || '';
+
+    log('Tool:', toolName);
+    log('Project:', PROJECT_DIR);
+
+    // ===== 在这里实现你的 hook 逻辑 =====
+
+    // 示例: 追踪操作
+    const trackerFile = path.join(PROJECT_DIR, '.claude/hooks/.tracker.json');
+    const data = JSON.parse(safeReadFile(trackerFile, '{}'));
+    data.lastRun = new Date().toISOString();
+    data.runs = (data.runs || 0) + 1;
+    safeWriteFile(trackerFile, JSON.stringify(data, null, 2));
+
+    // ===== Hook 逻辑结束 =====
+
+  } catch (error) {
+    // 静默处理错误，不干扰用户对话
+    log('Error:', error.message);
+  }
+
+  // 永远输出成功，不影响 Claude Code 正常运行
+  process.exit(0);
+}
+
+// ============================================================
+// 执行
+// ============================================================
+
+main();