jvibe 1.0.1 → 1.0.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jvibe",
-  "version": "1.0.1",
-  "description": "文档驱动的 AI 辅助开发系统 - Doc-driven AI-assisted development system for Claude Code",
+  "version": "1.0.2",
+  "description": "\u6587\u6863\u9a71\u52a8\u7684 AI \u8f85\u52a9\u5f00\u53d1\u7cfb\u7edf - Doc-driven AI-assisted development system for Claude Code",
   "main": "bin/jvibe.js",
   "bin": {
     "jvibe": "bin/jvibe.js"

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

@@ -43,9 +43,11 @@ description: 初始化 JVibe 项目文档结构
 - 8 个规范分类（编码规范、API规范、数据库规范等）
 - Links 字典
 
-## 询问用户
+## 询问流程（分阶段引导）
 
-在创建文档前，询问用户以下信息（使用 AskUserQuestion）：
+采用**引导式询问**，帮助用户梳理需求，而不是直接让用户做技术决策。
+
+### 第一阶段：基本信息
 
 ```yaml
 questions:
@@ -56,25 +58,62 @@ questions:
       - label: "自定义项目名"
         description: "手动输入项目名称"
 
-  - question: "主要技术栈是什么？"
-    header: "技术栈"
-    multiSelect: true
+  - question: "你想做什么项目？请简单描述一下项目目标"
+    header: "项目描述"
+    multiSelect: false
     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: "手动指定其他技术栈"
+      - label: "Web 应用"
+        description: "网站、管理后台、在线平台等"
+      - label: "移动端应用"
+        description: "iOS/Android App、小程序等"
+      - label: "API 服务"
+        description: "后端接口、微服务等"
+      - label: "CLI 工具"
+        description: "命令行工具、自动化脚本等"
+```
+
+### 第二阶段：AI 分析并推荐技术栈
+
+根据用户在第一阶段的描述，**AI 主动分析并推荐合适的技术栈**：
+
+1. **分析用户需求**：
+   - 项目类型（Web/移动端/API/工具）
+   - 复杂度（简单/中等/复杂）
+   - 特殊需求（实时通信、大数据、AI 等）
+
+2. **生成推荐方案**：
+   ```
+   基于你的项目描述，我推荐以下技术栈：
+
+   📦 推荐方案：
+   - 前端：React + TypeScript + Tailwind CSS
+   - 后端：Node.js + Express
+   - 数据库：PostgreSQL
+
+   💡 推荐理由：
+   - React 生态成熟，适合 xxx 场景
+   - PostgreSQL 支持 xxx 特性，适合你的需求
+   ```
+
+3. **让用户确认或调整**：
+   ```yaml
+   questions:
+     - question: "是否采用推荐的技术栈？"
+       header: "技术栈确认"
+       multiSelect: false
+       options:
+         - label: "采用推荐方案（推荐）"
+           description: "使用 AI 推荐的技术栈组合"
+         - label: "我要自己指定"
+           description: "手动选择或输入技术栈"
+         - label: "帮我调整一下"
+           description: "在推荐基础上做一些修改"
+   ```
+
+### 第三阶段：初始模块（可选）
 
+```yaml
+questions:
   - question: "是否需要创建初始模块？"
     header: "初始模块"
     multiSelect: true
@@ -87,15 +126,40 @@ questions:
         description: "稍后手动添加模块"
 ```
 
+## 技术栈推荐规则
+
+根据项目类型，AI 应参考以下推荐规则：
+
+| 项目类型 | 前端推荐 | 后端推荐 | 数据库推荐 |
+|---------|---------|---------|-----------|
+| 简单 Web 应用 | Vue 3 + TypeScript | Node.js + Express | SQLite / MongoDB |
+| 复杂 Web 应用 | React + TypeScript | Node.js + NestJS | PostgreSQL |
+| 管理后台 | React + Ant Design | Node.js + NestJS | PostgreSQL |
+| 移动端 App | React Native | Node.js + Express | PostgreSQL |
+| 小程序 | Taro / uni-app | Node.js + Express | MongoDB |
+| API 服务 | - | Node.js + NestJS / Go | PostgreSQL |
+| CLI 工具 | - | Node.js / Python | SQLite |
+| 实时应用 | React + Socket.io | Node.js + Socket.io | Redis + PostgreSQL |
+
 ## 执行步骤
 
-1. 创建 `docs/` 目录
-2. 从模板复制并填充项目信息：
-   - 项目名称
-   - 技术栈
-   - 初始模块（如果用户选择了）
-3. 创建 4 个核心文档
-4. 输出确认信息
+1. **第一阶段询问**：获取项目名称和项目描述
+2. **AI 分析**：根据描述推荐技术栈并说明理由
+3. **第二阶段询问**：让用户确认或调整技术栈
+4. **第三阶段询问**：初始模块选择
+5. 创建 `docs/` 目录
+6. 从模板复制并填充项目信息
+7. 创建 4 个核心文档
+8. **创建状态标记文件** `.jvibe-state.json`：
+   ```json
+   {
+     "initialized": true,
+     "firstSessionAfterInit": true,
+     "version": "1.0.0",
+     "createdAt": "2026-01-11T10:00:00Z"
+   }
+   ```
+9. 输出确认信息
 
 ## 输出格式
 
@@ -110,6 +174,7 @@ questions:
 
 项目信息：
   - 项目名称：{项目名}
+  - 项目类型：{Web 应用 / API 服务 / ...}
   - 技术栈：{技术栈列表}
   - 初始模块：{模块列表}
 
@@ -123,3 +188,5 @@ questions:
 1. **不覆盖已存在的文档**：如果 docs/ 目录已存在文档，先询问用户是否覆盖
 2. **使用模板**：从项目根目录的 `模版-*.md` 和 `模板-*.md` 文件复制内容
 3. **填充占位符**：将模板中的占位符替换为用户提供的实际信息
+4. **引导而非询问**：对于技术选择，AI 应主动分析并给出建议，而不是让用户自己做决定
+5. **允许直接指定**：如果用户在初始化时已经明确说了技术栈，跳过推荐环节，直接使用用户指定的

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

@@ -3,14 +3,20 @@
 # load-context.sh - 会话开始时加载项目上下文
 # ============================================================================
 # 触发事件: SessionStart
-# 用途: 在会话开始时输出项目关键信息，帮助 AI 快速了解项目状态
+# 用途: 在会话开始时输出项目关键信息,帮助 AI 快速了解项目状态
+# 版本: 2.0 - 支持状态标记机制
 # ============================================================================
 
 set -euo pipefail
 
 # 项目根目录（相对于 .claude/hooks/）
 PROJECT_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
-DOCS_DIR="$PROJECT_ROOT/docs"
+if [[ -d "$PROJECT_ROOT/docs/core" ]]; then
+    DOCS_DIR="$PROJECT_ROOT/docs/core"
+else
+    DOCS_DIR="$PROJECT_ROOT/docs"
+fi
+STATE_FILE="$PROJECT_ROOT/.jvibe-state.json"
 
 # 颜色定义
 GREEN='\033[0;32m'
@@ -18,17 +24,54 @@ YELLOW='\033[1;33m'
 BLUE='\033[0;34m'
 NC='\033[0m' # No Color
 
+# 读取状态文件
+read_state() {
+    if [[ -f "$STATE_FILE" ]]; then
+        cat "$STATE_FILE"
+    else
+        echo '{"initialized":false,"firstSessionAfterInit":false}'
+    fi
+}
+
+# 更新状态文件
+update_state() {
+    local key=$1
+    local value=$2
+    local state=$(read_state)
+    echo "$state" | jq --arg key "$key" --arg value "$value" '.[$key] = ($value | fromjson)' > "$STATE_FILE"
+}
+
+# 检查是否已初始化
+STATE=$(read_state)
+INITIALIZED=$(echo "$STATE" | jq -r '.initialized // false')
+FIRST_SESSION=$(echo "$STATE" | jq -r '.firstSessionAfterInit // false')
+
 echo -e "${BLUE}========================================${NC}"
 echo -e "${BLUE}  JVibe 项目上下文加载${NC}"
 echo -e "${BLUE}========================================${NC}"
 
-# 检查文档目录是否存在
-if [[ ! -d "$DOCS_DIR" ]]; then
-    echo -e "${YELLOW}[提示] docs/ 目录不存在，跳过上下文加载${NC}"
+# 未初始化：简洁提示
+if [[ "$INITIALIZED" == "false" ]]; then
+    echo -e "${YELLOW}[提示] 功能清单.md 不存在${NC}"
+    echo -e "\n${BLUE}========================================${NC}"
+    echo -e "${BLUE}  上下文加载完成${NC}"
+    echo -e "${BLUE}========================================${NC}"
     exit 0
 fi
 
-# 检查功能清单是否存在
+# 首次会话：显示欢迎信息
+if [[ "$FIRST_SESSION" == "true" ]]; then
+    echo -e "\n${GREEN}✅ JVibe 项目已初始化！${NC}"
+    echo "----------------------------------------"
+    echo "  使用自然语言添加功能"
+    echo "  使用 /JVibe:status 查看项目状态"
+    echo "  使用 /JVibe:pr 生成 PR 描述"
+
+    # 更新状态：标记为非首次会话
+    update_state "firstSessionAfterInit" "false"
+fi
+
+# 常规会话：显示功能统计（如果功能清单存在）
 FEATURE_LIST="$DOCS_DIR/功能清单.md"
 if [[ -f "$FEATURE_LIST" ]]; then
     echo -e "\n${GREEN}📋 功能状态统计${NC}"
@@ -56,8 +99,6 @@ if [[ -f "$FEATURE_LIST" ]]; then
         echo "----------------------------------------"
         grep "^## F-[0-9]* 🚧" "$FEATURE_LIST" | sed 's/^## /  /' || true
     fi
-else
-    echo -e "${YELLOW}[提示] 功能清单.md 不存在${NC}"
 fi
 
 echo -e "\n${BLUE}========================================${NC}"

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

@@ -20,7 +20,7 @@ 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
+if [[ "$FILE_PATH" != *"docs/core/功能清单.md" && "$FILE_PATH" != *"docs/功能清单.md" ]]; then
     exit 0
 fi
 

package/template/.claude/hooks/sync-stats.sh

@@ -10,7 +10,11 @@ set -euo pipefail
 
 # 项目根目录（相对于 .claude/hooks/）
 PROJECT_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
-DOCS_DIR="$PROJECT_ROOT/docs"
+if [[ -d "$PROJECT_ROOT/docs/core" ]]; then
+    DOCS_DIR="$PROJECT_ROOT/docs/core"
+else
+    DOCS_DIR="$PROJECT_ROOT/docs"
+fi
 FEATURE_LIST="$DOCS_DIR/功能清单.md"
 
 # 颜色定义

package/template/docs/core//345/212/237/350/203/275/346/270/205/345/215/225.md

@@ -1,28 +1,17 @@
 # [项目名称] 功能清单
 
-## 📌 文档说明
+> 功能状态的唯一来源（SoT），记录每个功能的描述和实现TODO
 
-本文档是**功能状态的唯一来源（SoT）**，详细描述每个功能的：
-1. **功能描述** - 该功能是什么，解决什么问题
-2. **实现TODO** - 具体的开发任务清单
+**编号规则**: `F-XXX`（F = Feature，XXX = 三位数字）
 
-**功能状态总览**: 见 [项目文档](./项目文档.md) §5 统计表（按 sprint/里程碑从本文档推导）
-
-**编号规则**: F-XXX (F = Feature，XXX = 三位数字)
-
----
-
-## 状态说明
-
-- ✅ **已完成**: 功能开发完成、测试通过、已合并到主分支
-- 🚧 **开发中**: 正在开发中，TODO未全部完成
-- ❌ **未开始**: 已规划但尚未开始开发
-
-> ⚠️ **重要**: 功能状态只在本文档维护，项目文档的统计数据由本文档推导。
+**状态说明**:
+- ✅ 已完成 - 开发完成、测试通过、已合并
+- 🚧 开发中 - 正在开发，TODO未全部完成
+- ❌ 未开始 - 已规划但未开始
 
 ---
 
-# AuthModule (认证模块)
+# 示例模块（AuthModule）
 
 ## F-001 ✅ 用户注册
 
@@ -36,232 +25,10 @@
 - [x] 单元测试（邮箱格式、密码强度、加密函数）
 - [x] 集成测试（注册流程、异常情况）
 - [x] API文档更新
-- [x] 数据库Schema文档更新
-
----
-
-## F-002 ✅ 用户登录
-
-**描述**：已注册用户通过邮箱和密码登录系统，登录成功后获得访问令牌（Access Token）和刷新令牌（Refresh Token）。支持登录失败锁定机制。
-
-**TODO**
-- [x] 实现 POST /api/auth/login 端点
-- [x] 实现登录失败计数器（Redis存储，5次失败锁定15分钟）
-- [x] 实现auth_tokens表存储refreshToken
-- [x] 单元测试（密码验证、Token生成、失败计数）
-- [x] 集成测试（登录流程、失败场景、锁定机制）
-- [x] API文档更新
-
----
-
-## F-003 ✅ Token刷新
-
-**描述**：当accessToken过期后，客户端可使用refreshToken获取新的accessToken，无需用户重新登录。
-
-**TODO**
-- [x] 实现 POST /api/auth/refresh 端点
-- [x] 验证refreshToken有效性
-- [x] 生成新的accessToken
-- [x] 单元测试和集成测试
-- [x] API文档更新
-
----
-
-## F-004 ✅ 密码重置
-
-**描述**：用户忘记密码时，可通过邮箱接收重置密码链接，点击链接后设置新密码。重置成功后旧token全部失效。
-
-**TODO**
-- [x] 实现 POST /api/auth/forgot-password 端点
-- [x] 实现 POST /api/auth/reset-password 端点
-- [x] 生成重置token（JWT，有效期1小时）
-- [x] 发送重置密码邮件
-- [x] 更新密码并使旧token失效
-- [x] 单元测试和集成测试
-- [x] API文档更新
-
----
-
-## F-005 ✅ 邮箱验证
-
-**描述**：用户注册后需要验证邮箱，验证成功后才能登录系统。支持重新发送验证邮件（1分钟内限制1次）。
-
-**TODO**
-- [x] 实现 GET /api/auth/verify/:token 端点
-- [x] 实现 POST /api/auth/resend-verification 端点
-- [x] 验证token有效性（24小时有效期）
-- [x] 更新email_verified字段
-- [x] 单元测试和集成测试
-- [x] API文档更新
-
----
-
-# UserModule (用户管理模块)
-
-## F-006 ✅ 用户信息查询
-
-**描述**：查询用户的基本信息和资料。支持查询自己的完整信息和其他用户的公开信息。
-
-**TODO**
-- [x] 实现 GET /api/users/:id 端点
-- [x] 实现 GET /api/users/me 端点
-- [x] 权限验证（需登录）
-- [x] 区分公开信息和私密信息
-- [x] 单元测试和集成测试
-- [x] API文档更新
-
----
-
-## F-007 ✅ 用户资料编辑
-
-**描述**：用户可以编辑自己的资料，包括昵称（2-20字符）、简介（0-200字符）等信息。只能编辑自己的资料。
-
-**TODO**
-- [x] 实现 PUT /api/users/:id 端点
-- [x] 请求体验证和字段长度验证
-- [x] 权限验证（只能编辑自己）
-- [x] 单元测试和集成测试
-- [x] API文档更新
-
----
-
-## F-008 ✅ 头像上传
-
-**描述**：用户可以上传自己的头像图片，支持JPG、PNG格式（最大5MB），自动裁剪为正方形并生成200x200缩略图。
-
-**TODO**
-- [x] 实现 POST /api/users/:id/avatar 端点
-- [x] 文件上传处理（multer）
-- [x] 图片格式验证
-- [x] 图片压缩和裁剪（sharp）
-- [x] 上传到云存储（S3/OSS）
-- [x] 更新user_profiles.avatar_url
-- [x] 单元测试和集成测试
-- [x] API文档更新
-
----
-
-## F-009 ✅ 用户搜索
-
-**描述**：通过关键词搜索用户，支持按昵称模糊搜索和按邮箱精确搜索，返回匹配的用户列表。支持分页（默认20条/页）。
-
-**TODO**
-- [x] 实现 GET /api/users/search 端点
-- [x] 查询参数验证（q, page, limit）
-- [x] 数据库模糊查询和分页逻辑
-- [x] 权限验证（需登录）
-- [x] 单元测试和集成测试
-- [x] API文档更新
-
----
-
-## F-010 ✅ 用户权限管理
-
-**描述**：管理员可以设置用户的角色（user/admin），支持角色变更日志记录。防止自我提权。
-
-**TODO**
-- [x] 实现 PUT /api/users/:id/role 端点
-- [x] 权限验证（需admin角色）
-- [x] 防止自我提权
-- [x] 记录角色变更日志
-- [x] 单元测试和集成测试
-- [x] API文档更新
-
----
-
-# ChatModule (实时聊天模块)
-
-## F-011 ✅ 创建聊天室
-
-**描述**：用户可以创建聊天室，邀请其他用户加入。支持一对一聊天（direct，2人）和群聊（group，3-100人）。
-
-**TODO**
-- [x] 实现 POST /api/chat/rooms 端点
-- [x] 聊天室类型验证（direct/group）
-- [x] 成员列表验证（名称长度1-50字符）
-- [x] 创建chat_rooms和room_members记录
-- [x] 单元测试和集成测试
-- [x] API文档更新
-
----
-
-## F-012 ✅ 发送文本消息
-
-**描述**：用户在聊天室内发送文本消息，消息实时推送给其他在线成员。
-
-**TODO**
-- [x] 实现 POST /api/chat/messages 端点
-- [x] WebSocket消息广播逻辑
-- [x] 消息内容验证和存储
-- [x] 单元测试和集成测试
-- [x] API文档更新
 
 ---
 
-## F-013 ✅ 接收实时消息
-
-**描述**：用户通过WebSocket连接实时接收聊天室消息，支持断线重连和消息补发。
-
-**TODO**
-- [x] 实现WebSocket连接管理
-- [x] 实现消息推送逻辑
-- [x] 实现断线重连机制
-- [x] 实现消息补发逻辑
-- [x] 单元测试和集成测试
-
----
-
-## F-014 ✅ 历史消息查询
-
-**描述**：查询聊天室的历史消息，支持分页加载（默认50条/页）和时间范围筛选。
-
-**TODO**
-- [x] 实现 GET /api/chat/messages/:roomId 端点
-- [x] 分页查询逻辑
-- [x] 时间范围筛选
-- [x] 权限验证（只能查询已加入的聊天室）
-- [x] 单元测试和集成测试
-- [x] API文档更新
-
----
-
-## F-015 ✅ 在线状态显示
-
-**描述**：显示聊天室成员的在线状态（在线/离线/离开），通过WebSocket实时更新。
-
-**TODO**
-- [x] 实现在线状态管理（Redis存储）
-- [x] WebSocket在线状态广播
-- [x] 心跳检测机制
-- [x] 单元测试和集成测试
-
----
-
-## F-016 ✅ 输入状态指示
-
-**描述**：显示其他用户正在输入的状态提示（"XXX正在输入..."），3秒无输入后自动清除。
-
-**TODO**
-- [x] WebSocket输入状态事件监听
-- [x] 输入状态广播逻辑
-- [x] 自动清除机制（3秒超时）
-- [x] 单元测试和集成测试
-
----
-
-## F-017 ✅ 消息通知
-
-**描述**：用户离线或未打开聊天室时，收到新消息的系统通知（桌面通知/推送通知）。
-
-**TODO**
-- [x] 实现桌面通知（Web Notification API）
-- [x] 实现推送通知服务集成
-- [x] 通知开关和权限管理
-- [x] 单元测试和集成测试
-
----
-
-## F-018 🚧 文件分享
+## F-002 🚧 文件分享
 
 **描述**：用户可以在聊天室中分享文件（图片、文档、视频等），支持文件预览和下载。最大文件大小100MB。
 
@@ -277,7 +44,7 @@
 
 ---
 
-## F-019 ❌ 消息搜索
+## F-003 ❌ 消息搜索
 
 **描述**：在聊天室或全局范围内搜索历史消息，支持关键词搜索和高级筛选（发送人、时间范围、文件类型）。
 
@@ -289,18 +56,3 @@
 - [ ] 权限验证（只搜索有权限的聊天室）
 - [ ] 单元测试和集成测试
 - [ ] API文档更新
-
----
-
-## F-020 ❌ 消息已读状态
-
-**描述**：显示消息的已读状态，支持单聊的"已读/未读"标记和群聊的"X人已读"统计。
-
-**TODO**
-- [ ] 实现消息已读记录表（message_read_status）
-- [ ] 实现 PUT /api/chat/messages/:id/read 端点
-- [ ] WebSocket已读状态广播
-- [ ] 群聊已读人数统计
-- [ ] 未读消息计数功能
-- [ ] 单元测试和集成测试
-- [ ] API文档更新