jvibe 1.0.0

package/template/.claude/commands/JVibe:init.md

@@ -0,0 +1,125 @@
+---
+name: JVibe:init
+description: 初始化 JVibe 项目文档结构
+---
+
+# /JVibe:init - 初始化 JVibe 项目文档
+
+你需要为新项目初始化完整的 JVibe 文档体系。
+
+## 任务
+
+1. **创建 docs 目录**（如果不存在）
+
+2. **创建 4 个核心文档**：
+
+### 规范文档.md
+
+基于模版-规范文档.md 创建，包含：
+- 快速导航
+- Project 文档注册表
+- 开发流程说明
+- 文档体系说明
+
+### 项目文档.md
+
+基于模板-项目文档.md 创建，包含：
+- 项目概览
+- 技术栈
+- 项目结构
+- 模块清单（初始为空）
+- 模块功能统计表（初始为空）
+
+### 功能清单.md
+
+基于模板-功能清单.md 创建，包含：
+- 文档说明
+- 功能索引（初始为空）
+
+### 附加材料.md
+
+基于模板-附加材料.md 创建，包含：
+- 使用方式与约定
+- 8 个规范分类（编码规范、API规范、数据库规范等）
+- Links 字典
+
+## 询问用户
+
+在创建文档前，询问用户以下信息（使用 AskUserQuestion）：
+
+```yaml
+questions:
+  - question: "项目名称是什么？"
+    header: "项目名称"
+    multiSelect: false
+    options:
+      - label: "自定义项目名"
+        description: "手动输入项目名称"
+
+  - question: "主要技术栈是什么？"
+    header: "技术栈"
+    multiSelect: true
+    options:
+      - label: "前端：React + TypeScript"
+        description: "现代前端技术栈"
+      - label: "前端：Vue 3 + TypeScript"
+        description: "Vue 生态"
+      - label: "后端：Node.js + Express"
+        description: "轻量级后端"
+      - label: "后端：Node.js + NestJS"
+        description: "企业级后端框架"
+      - label: "数据库：PostgreSQL"
+        description: "关系型数据库"
+      - label: "数据库：MongoDB"
+        description: "文档数据库"
+      - label: "其他"
+        description: "手动指定其他技术栈"
+
+  - question: "是否需要创建初始模块？"
+    header: "初始模块"
+    multiSelect: true
+    options:
+      - label: "用户认证模块（AuthModule）"
+        description: "用户注册、登录、权限管理"
+      - label: "用户管理模块（UserModule）"
+        description: "用户信息、个人资料"
+      - label: "暂不创建"
+        description: "稍后手动添加模块"
+```
+
+## 执行步骤
+
+1. 创建 `docs/` 目录
+2. 从模板复制并填充项目信息：
+   - 项目名称
+   - 技术栈
+   - 初始模块（如果用户选择了）
+3. 创建 4 个核心文档
+4. 输出确认信息
+
+## 输出格式
+
+```
+✅ JVibe 项目文档初始化完成！
+
+已创建文档：
+  - docs/规范文档.md
+  - docs/项目文档.md
+  - docs/功能清单.md
+  - docs/附加材料.md
+
+项目信息：
+  - 项目名称：{项目名}
+  - 技术栈：{技术栈列表}
+  - 初始模块：{模块列表}
+
+下一步：
+  - 使用自然语言添加功能："添加 XXX 功能"
+  - 查看项目状态：/JVibe:status
+```
+
+## 注意事项
+
+1. **不覆盖已存在的文档**：如果 docs/ 目录已存在文档，先询问用户是否覆盖
+2. **使用模板**：从项目根目录的 `模版-*.md` 和 `模板-*.md` 文件复制内容
+3. **填充占位符**：将模板中的占位符替换为用户提供的实际信息

package/template/.claude/commands/JVibe:pr.md

@@ -0,0 +1,159 @@
+---
+name: JVibe:pr
+description: 生成标准化的 Pull Request 描述
+---
+
+# /JVibe:pr - 生成 Pull Request 描述
+
+你需要生成符合 JVibe 规范的 PR 描述，包含变更总结、关联功能、命中规范清单和测试计划。
+
+## 任务
+
+调用 **reviewer Sub-Agent** 完成以下工作：
+
+1. **分析代码变更**
+   - 执行 `git diff` 获取变更内容
+   - 识别变更的文件和模块
+   - 分析变更类型（新功能/Bug修复/重构/文档等）
+
+2. **关联功能**
+   - 从功能清单中找到本次 PR 关联的功能编号（F-XXX）
+   - 列出相关的 TODO 项
+
+3. **规范检查**
+   - 读取附加材料中的规范条目
+   - 匹配本次变更命中的规范（CS-/API-/DB-/SEC-/TEST-等）
+   - 说明如何满足这些规范
+
+4. **生成 PR 描述**
+
+## PR 描述格式
+
+```markdown
+## Summary
+- [变更点1：简要描述]
+- [变更点2：简要描述]
+- [变更点3：简要描述]
+
+## Related Features
+- F-XXX: [功能名称]
+  - [相关 TODO 1]
+  - [相关 TODO 2]
+
+## Hit Specs
+本次变更涉及以下规范，已确认满足：
+
+- [ ] **CS-001**: SOLID原则检查
+  - ✅ 每个类遵循单一职责原则
+  - ✅ 新增模块符合开闭原则
+
+- [ ] **SEC-001**: SQL注入防范
+  - ✅ 使用参数化查询
+  - ✅ ORM 方式操作数据库
+
+- [ ] **API-002**: 统一响应格式
+  - ✅ 所有 API 返回包含 code/message/data 字段
+
+- [ ] **TEST-001**: 测试覆盖率要求
+  - ✅ 单元测试覆盖率 85%
+  - ✅ 核心模块测试覆盖率 92%
+
+## Test Plan
+- [ ] 单元测试通过 (`npm test`)
+- [ ] 集成测试通过
+- [ ] 手动测试验证
+  - [ ] [测试场景1]
+  - [ ] [测试场景2]
+- [ ] 代码审查通过
+
+## Breaking Changes
+[如有破坏性变更，详细说明；否则写 "None"]
+
+## Screenshots (if applicable)
+[如涉及 UI 变更，添加截图或 GIF]
+
+## Additional Notes
+[其他需要说明的内容]
+```
+
+## 调用方式
+
+```yaml
+# 主 Agent 调用 reviewer Sub-Agent
+task: 生成 PR 描述
+agent: reviewer
+input:
+  - git diff 输出
+  - 功能清单
+  - 附加材料
+output:
+  - 标准化的 PR 描述（Markdown 格式）
+```
+
+## 输出格式
+
+生成的 PR 描述应该可以**直接复制粘贴到 GitHub/GitLab**，无需手动修改。
+
+输出示例：
+
+```
+✅ PR 描述已生成！
+
+---
+[以下内容可直接复制到 PR 描述框]
+
+## Summary
+- 实现文件上传功能，支持图片和文档
+- 添加图片缩略图自动生成
+- 集成 S3 云存储
+
+## Related Features
+- F-018: 文件上传
+  - ✅ 实现 POST /api/files 端点
+  - ✅ 文件类型和大小验证
+  - ✅ 图片缩略图生成
+  - ✅ S3 云存储集成
+  - ✅ 单元测试和集成测试
+
+## Hit Specs
+本次变更涉及以下规范，已确认满足：
+
+- [ ] **CS-003**: 函数复杂度限制
+  - ✅ 所有函数圈复杂度 ≤ 8
+
+- [ ] **SEC-001**: SQL注入防范
+  - ✅ 使用 Prisma ORM 参数化查询
+
+- [ ] **SEC-003**: 敏感信息保护
+  - ✅ S3 密钥使用环境变量
+
+- [ ] **TEST-001**: 测试覆盖率要求
+  - ✅ 单元测试覆盖率 88%
+
+## Test Plan
+- [x] 单元测试通过
+- [x] 集成测试通过
+- [ ] 手动测试验证
+  - [ ] 上传图片文件（JPG, PNG）
+  - [ ] 上传文档文件（PDF, DOCX）
+  - [ ] 验证文件大小限制（50 MB）
+  - [ ] 验证缩略图生成
+  - [ ] 验证 S3 存储
+- [ ] 代码审查通过
+
+## Breaking Changes
+None
+
+## Screenshots
+[待添加上传界面截图]
+
+---
+```
+
+## 注意事项
+
+1. **自动识别功能**：从 commit 信息和文件变更中识别关联的 F-XXX
+2. **规范匹配准确**：只列出真正命中的规范，不要无关的
+3. **测试计划具体**：测试项应该具体可执行，不是泛泛而谈
+4. **格式标准化**：严格遵循格式，便于团队统一
+5. **一键复制**：输出的内容应该可以直接使用，不需要手动调整

package/template/.claude/commands/JVibe:status.md

@@ -0,0 +1,160 @@
+---
+name: JVibe:status
+description: 快速查看项目功能状态和进度总览
+---
+
+# /JVibe:status - 查看项目状态
+
+你需要快速展示项目的功能状态、进度统计和最近活跃情况。
+
+## 任务
+
+调用 **doc-sync Sub-Agent** 完成以下工作：
+
+1. **读取功能清单**
+   - 统计各状态功能数量（✅/🚧/❌）
+   - 计算总体完成率
+
+2. **按模块统计**
+   - 从项目文档读取模块列表
+   - 统计每个模块的功能数量和完成情况
+
+3. **识别关键信息**
+   - 最近开发中的功能
+   - 最近完成的功能
+   - 长期未开始的功能（如有）
+
+## 输出格式
+
+```
+========================================
+  📊 JVibe 项目状态
+========================================
+
+项目：{项目名称}
+更新时间：{当前日期}
+
+----------------------------------------
+功能总览
+----------------------------------------
+  总功能数: {总数}
+  ✅ 已完成: {已完成数} ({完成率}%)
+  🚧 开发中: {开发中数}
+  ❌ 未开始: {未开始数}
+
+----------------------------------------
+模块统计
+----------------------------------------
+  AuthModule
+    总数: 5  |  ✅ 5  |  🚧 0  |  ❌ 0  |  完成率: 100%
+
+  UserModule
+    总数: 5  |  ✅ 5  |  🚧 0  |  ❌ 0  |  完成率: 100%
+
+  ChatModule
+    总数: 10  |  ✅ 7  |  🚧  2  |  ❌ 1  |  完成率: 70%
+
+----------------------------------------
+🔨 开发中的功能
+----------------------------------------
+  🚧 F-018: 文件上传
+  🚧 F-019: 消息撤回
+
+----------------------------------------
+✅ 最近完成
+----------------------------------------
+  ✅ F-015: 用户头像上传
+  ✅ F-016: 在线状态显示
+  ✅ F-017: 消息已读回执
+
+========================================
+```
+
+## 可选：按优先级分组
+
+如果功能清单中标注了优先级（P0/P1/P2），可以额外展示：
+
+```
+----------------------------------------
+⚡ 高优先级功能 (P0)
+----------------------------------------
+  ✅ F-001: 用户注册
+  ✅ F-002: 用户登录
+  🚧 F-018: 文件上传
+  ❌ F-020: 消息加密
+```
+
+## 可选：显示阻塞信息
+
+如果某些功能有依赖关系或被阻塞，可以提示：
+
+```
+----------------------------------------
+⚠️  需要注意
+----------------------------------------
+  - F-020 (消息加密) 依赖 F-018 (文件上传) 完成
+  - F-021 (消息撤回) 已开发中超过 2 周
+```
+
+## 调用方式
+
+```yaml
+# 主 Agent 调用 doc-sync Sub-Agent
+task: 生成项目状态报告
+agent: doc-sync
+input:
+  - 功能清单
+  - 项目文档
+output:
+  - 格式化的状态报告
+```
+
+## 简洁模式
+
+如果用户只需要简单统计，可以输出简洁版本：
+
+```
+📊 项目状态
+  总数: 20  |  ✅ 18 (90%)  |  🚧 1  |  ❌ 1
+
+🚧 开发中: F-018, F-019
+✅ 最近完成: F-015, F-016, F-017
+```
+
+## 详细模式
+
+如果用户需要详细信息，可以列出每个功能的 TODO 完成情况：
+
+```
+========================================
+  📋 详细功能状态
+========================================
+
+ChatModule
+
+  ✅ F-015: 用户头像上传
+    ✅ 8/8 TODO 已完成
+
+  🚧 F-018: 文件上传
+    ✅ 6/9 TODO 已完成 (67%)
+    - ✅ 实现 POST /api/files 端点
+    - ✅ 文件类型验证
+    - ✅ 文件大小验证
+    - ✅ 图片缩略图生成
+    - ✅ S3 云存储集成
+    - ✅ 上传进度反馈
+    - ⏳ 单元测试
+    - ⏳ 集成测试
+    - ⏳ API文档更新
+
+  ❌ F-020: 消息加密
+    ⏳ 0/7 TODO 未开始
+```
+
+## 注意事项
+
+1. **数据准确**：统计数据必须与功能清单完全一致
+2. **格式美观**：使用表格或对齐的文本，易于阅读
+3. **重点突出**：用 emoji 和颜色（如果支持）突出关键信息
+4. **快速响应**：使用 haiku 模型，确保快速返回
+5. **可配置**：根据项目规模选择简洁或详细模式

package/template/.claude/hooks/load-context.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+# ============================================================================
+# load-context.sh - 会话开始时加载项目上下文
+# ============================================================================
+# 触发事件: SessionStart
+# 用途: 在会话开始时输出项目关键信息，帮助 AI 快速了解项目状态
+# ============================================================================
+
+set -euo pipefail
+
+# 项目根目录（相对于 .claude/hooks/）
+PROJECT_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+DOCS_DIR="$PROJECT_ROOT/docs"
+
+# 颜色定义
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}========================================${NC}"
+echo -e "${BLUE}  JVibe 项目上下文加载${NC}"
+echo -e "${BLUE}========================================${NC}"
+
+# 检查文档目录是否存在
+if [[ ! -d "$DOCS_DIR" ]]; then
+    echo -e "${YELLOW}[提示] docs/ 目录不存在，跳过上下文加载${NC}"
+    exit 0
+fi
+
+# 检查功能清单是否存在
+FEATURE_LIST="$DOCS_DIR/功能清单.md"
+if [[ -f "$FEATURE_LIST" ]]; then
+    echo -e "\n${GREEN}📋 功能状态统计${NC}"
+    echo "----------------------------------------"
+
+    # 统计各状态数量
+    COMPLETED=$(grep -c "^## F-[0-9]* ✅" "$FEATURE_LIST" 2>/dev/null || echo "0")
+    IN_PROGRESS=$(grep -c "^## F-[0-9]* 🚧" "$FEATURE_LIST" 2>/dev/null || echo "0")
+    NOT_STARTED=$(grep -c "^## F-[0-9]* ❌" "$FEATURE_LIST" 2>/dev/null || echo "0")
+    TOTAL=$((COMPLETED + IN_PROGRESS + NOT_STARTED))
+
+    if [[ $TOTAL -gt 0 ]]; then
+        RATE=$((COMPLETED * 100 / TOTAL))
+        echo "  ✅ 已完成: $COMPLETED"
+        echo "  🚧 开发中: $IN_PROGRESS"
+        echo "  ❌ 未开始: $NOT_STARTED"
+        echo "  📊 完成率: $RATE%"
+    else
+        echo "  暂无功能条目"
+    fi
+
+    # 显示开发中的功能
+    if [[ $IN_PROGRESS -gt 0 ]]; then
+        echo -e "\n${YELLOW}🔨 当前开发中${NC}"
+        echo "----------------------------------------"
+        grep "^## F-[0-9]* 🚧" "$FEATURE_LIST" | sed 's/^## /  /' || true
+    fi
+else
+    echo -e "${YELLOW}[提示] 功能清单.md 不存在${NC}"
+fi
+
+echo -e "\n${BLUE}========================================${NC}"
+echo -e "${BLUE}  上下文加载完成${NC}"
+echo -e "${BLUE}========================================${NC}"
+
+exit 0

package/template/.claude/hooks/sync-feature-status.sh

@@ -0,0 +1,172 @@
+#!/bin/bash
+# ============================================================================
+# sync-feature-status.sh - 自动推导功能状态
+# ============================================================================
+# 触发事件: PostToolUse (matcher: Edit|Write)
+# 用途: 当功能清单被修改时，根据 TODO 完成情况自动推导功能状态
+# ============================================================================
+# 状态推导规则:
+#   - 0/N 完成 → ❌ 未开始
+#   - 1~(N-1)/N 完成 → 🚧 开发中
+#   - N/N 完成 → ✅ 已完成
+# ============================================================================
+
+set -euo pipefail
+
+# 从 stdin 读取 hook 输入（JSON 格式）
+INPUT=$(cat)
+
+# 解析文件路径
+FILE_PATH=$(echo "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*"file_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' || echo "")
+
+# 只处理功能清单文件
+if [[ "$FILE_PATH" != *"功能清单.md" ]]; then
+    exit 0
+fi
+
+# 检查文件是否存在
+if [[ ! -f "$FILE_PATH" ]]; then
+    exit 0
+fi
+
+echo "[sync-feature-status] 检测到功能清单变更，开始同步状态..."
+
+# 创建临时文件
+TEMP_FILE=$(mktemp)
+trap "rm -f $TEMP_FILE" EXIT
+
+# 标记是否有状态变更
+CHANGES_MADE=false
+
+# 逐行处理文件
+current_feature=""
+current_status=""
+todo_total=0
+todo_completed=0
+
+while IFS= read -r line || [[ -n "$line" ]]; do
+    # 检测功能标题行: ## F-XXX [状态] 功能名称
+    if [[ "$line" =~ ^##[[:space:]]+(F-[0-9]+)[[:space:]]+(✅|🚧|❌)[[:space:]]+(.+)$ ]]; then
+        # 处理上一个功能的状态（如果有）
+        if [[ -n "$current_feature" ]]; then
+            # 推导状态
+            if [[ $todo_total -eq 0 ]]; then
+                new_status="❌"
+            elif [[ $todo_completed -eq 0 ]]; then
+                new_status="❌"
+            elif [[ $todo_completed -eq $todo_total ]]; then
+                new_status="✅"
+            else
+                new_status="🚧"
+            fi
+
+            # 如果状态需要更新，记录变更
+            if [[ "$new_status" != "$current_status" ]]; then
+                echo "[sync-feature-status] $current_feature: $current_status → $new_status ($todo_completed/$todo_total)"
+                CHANGES_MADE=true
+            fi
+        fi
+
+        # 记录当前功能信息
+        current_feature="${BASH_REMATCH[1]}"
+        current_status="${BASH_REMATCH[2]}"
+        feature_name="${BASH_REMATCH[3]}"
+        todo_total=0
+        todo_completed=0
+
+        echo "$line" >> "$TEMP_FILE"
+
+    # 检测 TODO 项: - [ ] 或 - [x]
+    elif [[ "$line" =~ ^[[:space:]]*-[[:space:]]\[([ xX])\] ]]; then
+        ((todo_total++)) || true
+        if [[ "${BASH_REMATCH[1]}" =~ [xX] ]]; then
+            ((todo_completed++)) || true
+        fi
+        echo "$line" >> "$TEMP_FILE"
+
+    # 其他行直接输出
+    else
+        echo "$line" >> "$TEMP_FILE"
+    fi
+done < "$FILE_PATH"
+
+# 处理最后一个功能
+if [[ -n "$current_feature" ]]; then
+    if [[ $todo_total -eq 0 ]]; then
+        new_status="❌"
+    elif [[ $todo_completed -eq 0 ]]; then
+        new_status="❌"
+    elif [[ $todo_completed -eq $todo_total ]]; then
+        new_status="✅"
+    else
+        new_status="🚧"
+    fi
+
+    if [[ "$new_status" != "$current_status" ]]; then
+        echo "[sync-feature-status] $current_feature: $current_status → $new_status ($todo_completed/$todo_total)"
+        CHANGES_MADE=true
+    fi
+fi
+
+# 如果有状态变更，更新文件
+if [[ "$CHANGES_MADE" == "true" ]]; then
+    # 重新处理文件，这次真正更新状态
+    > "$TEMP_FILE"
+    current_feature=""
+    todo_total=0
+    todo_completed=0
+    in_todo_section=false
+
+    while IFS= read -r line || [[ -n "$line" ]]; do
+        # 检测功能标题行
+        if [[ "$line" =~ ^##[[:space:]]+(F-[0-9]+)[[:space:]]+(✅|🚧|❌)[[:space:]]+(.+)$ ]]; then
+            current_feature="${BASH_REMATCH[1]}"
+            current_status="${BASH_REMATCH[2]}"
+            feature_name="${BASH_REMATCH[3]}"
+            todo_total=0
+            todo_completed=0
+            in_todo_section=false
+
+            # 先扫描该功能的所有 TODO
+            temp_total=0
+            temp_completed=0
+            found_next=false
+            while IFS= read -r next_line; do
+                if [[ "$next_line" =~ ^##[[:space:]] ]]; then
+                    break
+                fi
+                if [[ "$next_line" =~ ^[[:space:]]*-[[:space:]]\[([ xX])\] ]]; then
+                    ((temp_total++)) || true
+                    if [[ "${next_line}" =~ \[x\]|\[X\] ]]; then
+                        ((temp_completed++)) || true
+                    fi
+                fi
+            done
+
+            # 推导新状态
+            if [[ $temp_total -eq 0 ]]; then
+                new_status="❌"
+            elif [[ $temp_completed -eq 0 ]]; then
+                new_status="❌"
+            elif [[ $temp_completed -eq $temp_total ]]; then
+                new_status="✅"
+            else
+                new_status="🚧"
+            fi
+
+            # 输出更新后的标题行
+            echo "## $current_feature $new_status $feature_name" >> "$TEMP_FILE"
+        else
+            echo "$line" >> "$TEMP_FILE"
+        fi
+    done < "$FILE_PATH"
+
+    # 备份原文件并更新
+    cp "$FILE_PATH" "${FILE_PATH}.bak"
+    mv "$TEMP_FILE" "$FILE_PATH"
+    echo "[sync-feature-status] 状态同步完成"
+else
+    echo "[sync-feature-status] 无状态变更"
+fi
+
+exit 0