jvibe 1.0.9 → 1.1.0

package/README.md

@@ -158,8 +158,10 @@ TODO 完成情况 → 功能状态
 | `jvibe init` | 初始化 JVibe 项目 |
 | `jvibe init --mode=minimal` | 最小化初始化（仅 Core 文档） |
 | `jvibe init --force` | 强制覆盖已存在的配置 |
-| `jvibe upgrade` | 升级到最新版本 |
+| `jvibe upgrade` | 升级到最新版本（默认卸载重装） |
 | `jvibe upgrade --check` | 仅检查更新 |
+| `jvibe upgrade --migrate` | 仅执行旧版迁移 |
+| `jvibe uninstall` | 卸载项目内 JVibe 配置 |
 | `jvibe status` | 查看项目配置状态 |
 | `jvibe validate` | 验证项目配置 |
 

package/bin/jvibe.js

@@ -34,7 +34,7 @@ program
 // upgrade 命令
 program
   .command('upgrade')
-  .description('升级到最新版本（支持旧版本自动迁移）')
+  .description('升级到最新版本（默认卸载重装）')
   .option('--check', '仅检查更新，不执行升级', false)
   .option('--force', '强制升级，跳过确认', false)
   .option('--migrate', '仅执行迁移，不更新到最新版本', false)
@@ -53,6 +53,20 @@ program
     await upgrade({ ...options, migrate: true });
   });
 
+// uninstall 命令
+program
+  .command('uninstall')
+  .description('卸载项目内的 JVibe 配置与核心文档')
+  .option('--purge-project-docs', '同时移除 docs/project', false)
+  .option('--no-backup', '不创建备份', false)
+  .action(async (options) => {
+    const uninstall = require('../scripts/uninstall');
+    await uninstall({
+      purgeProjectDocs: options.purgeProjectDocs,
+      backup: options.backup
+    });
+  });
+
 // status 命令
 program
   .command('status')

package/lib/migrate.js

@@ -494,10 +494,9 @@ async function checkContentMigration(projectDir, currentVersion) {
         description: '核心文档需要强制重构（以 template/docs/core 为准）'
       });
     }
-    return result;
   }
 
-  // 模板不可用时，退回版本配置
+  // 模板检测后继续合并版本迁移配置
   if (migrationsConfig && currentVersion) {
     const configResult = migrationsConfig.checkAIMigrationRequired(currentVersion);
     if (configResult.required) {

package/lib/migrations/index.js

@@ -226,7 +226,13 @@ function generateMigrationPrompt(fromVersion) {
   if (result.changes.renamed.length > 0) {
     prompt += `## 重命名的字段\n\n`;
     for (const change of result.changes.renamed) {
-      prompt += `- ${change.file}: ${change.oldName} → ${change.newName}\n`;
+      const renameLabel = change.oldName && change.newName
+        ? `${change.oldName} → ${change.newName}`
+        : (change.field || change.description || '重命名');
+      prompt += `- ${change.file}: ${renameLabel}\n`;
+      if (change.description && renameLabel !== change.description) {
+        prompt += `  - ${change.description}\n`;
+      }
     }
     prompt += `\n`;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jvibe",
-  "version": "1.0.9",
+  "version": "1.1.0",
   "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": {

package/scripts/uninstall.js

@@ -0,0 +1,83 @@
+/**
+ * JVibe Uninstall Script
+ * 卸载项目内的 JVibe 配置与核心文档
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+/**
+ * 卸载 JVibe 配置
+ * @param {Object} options - 卸载选项
+ * @param {boolean} options.purgeProjectDocs - 是否移除 docs/project
+ * @param {boolean} options.backup - 是否创建备份
+ * @param {boolean} options.showNextSteps - 是否输出下一步提示
+ */
+async function uninstall(options = {}) {
+  const purgeProjectDocs = options.purgeProjectDocs || false;
+  const backupEnabled = options.backup !== false;
+  const showNextSteps = options.showNextSteps !== false;
+  const cwd = process.cwd();
+
+  console.log(chalk.blue('\n🧹 正在卸载 JVibe...\n'));
+
+  const targets = [
+    { relPath: '.claude', label: '.claude/' },
+    { relPath: 'docs/core', label: 'docs/core/' },
+    { relPath: 'docs/.jvibe', label: 'docs/.jvibe/' },
+    { relPath: '.jvibe-state.json', label: '.jvibe-state.json' },
+    { relPath: 'docs/.jvibe-state.json', label: 'docs/.jvibe-state.json' },
+    { relPath: 'docs/project', label: 'docs/project/', optional: true }
+  ];
+
+  const existingTargets = [];
+  for (const target of targets) {
+    if (target.optional && !purgeProjectDocs) {
+      continue;
+    }
+    const fullPath = path.join(cwd, target.relPath);
+    if (await fs.pathExists(fullPath)) {
+      existingTargets.push({ ...target, fullPath });
+    }
+  }
+
+  if (existingTargets.length === 0) {
+    console.log(chalk.yellow('⚠️  未发现可卸载的 JVibe 配置'));
+    return;
+  }
+
+  let backupDir = null;
+  if (backupEnabled) {
+    backupDir = path.join(cwd, `.jvibe-uninstall-backup-${Date.now()}`);
+    await fs.ensureDir(backupDir);
+
+    for (const target of existingTargets) {
+      const destPath = path.join(backupDir, target.relPath);
+      await fs.ensureDir(path.dirname(destPath));
+      await fs.copy(target.fullPath, destPath);
+    }
+  }
+
+  for (const target of existingTargets) {
+    await fs.remove(target.fullPath);
+  }
+
+  console.log(chalk.green('\n✅ JVibe 卸载完成！'));
+  console.log(chalk.white('\n已移除：'));
+  for (const target of existingTargets) {
+    console.log(chalk.gray(`  - ${target.label}`));
+  }
+
+  if (backupDir) {
+    console.log(chalk.gray(`\n备份位置：${path.basename(backupDir)}/`));
+  }
+
+  if (showNextSteps) {
+    console.log(chalk.yellow('\n📝 下一步：'));
+    console.log(chalk.white('  1. 重新运行 jvibe init 或 /JVibe:init 初始化'));
+    console.log(chalk.white('  2. 如需恢复，可从备份目录手动还原\n'));
+  }
+}
+
+module.exports = uninstall;

package/scripts/upgrade.js

@@ -1,7 +1,7 @@
 /**
  * JVibe Upgrade Script
  * 升级项目的 JVibe 配置到最新版本
- * 支持旧版本自动检测和迁移
+ * 默认执行卸载重装，可选保留旧迁移策略
  */
 
 const fs = require('fs-extra');
@@ -13,6 +13,8 @@ const {
   executeMigration,
   printMigrationSummary
 } = require('../lib/migrate');
+const init = require('./init');
+const uninstall = require('./uninstall');
 
 const TEMPLATE_DIR = path.join(__dirname, '../template');
 
@@ -63,23 +65,47 @@ async function upgrade(options = {}) {
     if (checkOnly) {
       if (migrationPlan.needsMigration) {
         console.log(chalk.yellow('\n📦 检测到旧版本，需要迁移'));
-        console.log(chalk.white('   运行 jvibe upgrade 进行升级和迁移\n'));
+        console.log(chalk.white('   运行 jvibe upgrade 执行卸载重装\n'));
       } else if (currentVersion === latestVersion) {
         console.log(chalk.green('\n✅ 已是最新版本！\n'));
       } else {
         console.log(chalk.yellow(`\n📦 有新版本可用: ${latestVersion}`));
-        console.log(chalk.white('   运行 jvibe upgrade 进行升级\n'));
+        console.log(chalk.white('   运行 jvibe upgrade 执行卸载重装\n'));
       }
       return;
     }
 
-    // 4. 检查是否需要任何操作
+    if (!migrateOnly) {
+      if (!force) {
+        console.log(chalk.yellow('\n⚠️  将执行卸载重装（重置 .claude/ 与 docs/core/）'));
+        console.log(chalk.white('   使用 --force 选项跳过此确认'));
+      }
+
+      let mode = 'full';
+      if (await fs.pathExists(settingsPath)) {
+        try {
+          const settings = await fs.readJson(settingsPath);
+          mode = settings.jvibe?.mode || mode;
+        } catch (e) {
+          // 读取失败则使用默认模式
+        }
+      }
+
+      await uninstall({ purgeProjectDocs: false, backup: true, showNextSteps: false });
+      await init({ mode, force: false });
+
+      console.log(chalk.green(`\n✅ 升级完成！`));
+      console.log(chalk.green(`   版本: ${currentVersion} → ${latestVersion}`));
+      console.log(chalk.gray('\n   已执行卸载重装（保留 docs/project/）\n'));
+      return;
+    }
+
+    // migrate-only 模式保留旧迁移逻辑
     if (!migrationPlan.needsMigration && currentVersion === latestVersion) {
-      console.log(chalk.green('\n✅ 已是最新版本，无需升级！\n'));
+      console.log(chalk.green('\n✅ 已是最新版本，无需迁移！\n'));
       return;
     }
 
-    // 5. 确认升级（如果没有 --force）
     if (!force && (migrationPlan.needsMigration || currentVersion !== latestVersion)) {
       console.log(chalk.yellow('\n⚠️  即将执行以下操作：'));
 
@@ -92,12 +118,8 @@ async function upgrade(options = {}) {
 
       console.log(chalk.white('\n   使用 --force 选项跳过此确认'));
       console.log(chalk.white('   或重新运行命令继续...\n'));
-
-      // 在非交互模式下直接继续
-      // 实际项目中可能需要 readline 来获取用户确认
     }
 
-    // 6. 创建备份
     console.log(chalk.gray('\n   创建备份...'));
     const backupDir = path.join(cwd, '.jvibe-backup-' + Date.now());
     if (hasClaudeDir) {
@@ -108,78 +130,11 @@ async function upgrade(options = {}) {
     }
     console.log(chalk.gray(`   备份已保存到: ${path.basename(backupDir)}/`));
 
-    // 7. 执行迁移（如果需要）
     if (migrationPlan.needsMigration) {
       await executeMigration(cwd, TEMPLATE_DIR, migrationPlan, latestVersion);
     }
 
-    // 8. 执行常规升级（如果不是仅迁移模式）
-    if (!migrateOnly && currentVersion !== latestVersion) {
-      console.log(chalk.yellow(`\n📦 正在升级到 ${latestVersion}...\n`));
-
-      // 更新 agents（如果迁移时没有更新）
-      if (migrationPlan.details.agentsToUpdate.length === 0) {
-        console.log(chalk.gray('   更新 agents...'));
-        await fs.copy(
-          path.join(TEMPLATE_DIR, '.claude/agents'),
-          path.join(cwd, '.claude/agents'),
-          { overwrite: true }
-        );
-      }
-
-      // 更新 commands（如果迁移时没有更新）
-      if (migrationPlan.details.commandsToRename.length === 0) {
-        console.log(chalk.gray('   更新 commands...'));
-        await fs.copy(
-          path.join(TEMPLATE_DIR, '.claude/commands'),
-          path.join(cwd, '.claude/commands'),
-          { overwrite: true }
-        );
-      }
-
-      // 更新 hooks（如果迁移时没有更新）
-      if (migrationPlan.details.hooksToUpdate.length === 0) {
-        console.log(chalk.gray('   更新 hooks...'));
-        await fs.copy(
-          path.join(TEMPLATE_DIR, '.claude/hooks'),
-          path.join(cwd, '.claude/hooks'),
-          { overwrite: true }
-        );
-      }
-
-      // 补充任务交接文件（如不存在）
-      const handoffSrc = path.join(TEMPLATE_DIR, 'docs/.jvibe/tasks.yaml');
-      const handoffDir = path.join(cwd, 'docs/.jvibe');
-      const handoffDest = path.join(handoffDir, 'tasks.yaml');
-      if (await fs.pathExists(handoffSrc) && !await fs.pathExists(handoffDest)) {
-        await fs.ensureDir(handoffDir);
-        await fs.copy(handoffSrc, handoffDest, { overwrite: false });
-      }
-
-      // 更新版本信息
-      let settings = {};
-      if (await fs.pathExists(settingsPath)) {
-        try {
-          settings = await fs.readJson(settingsPath);
-        } catch (e) {
-          // 读取失败则创建新配置
-        }
-      }
-
-      settings.jvibe = {
-        ...settings.jvibe,
-        version: latestVersion,
-        upgradedAt: new Date().toISOString()
-      };
-      await fs.writeJson(settingsPath, settings, { spaces: 2 });
-    }
-
-    // 9. 清理旧备份（保留最新的）
-    // 可选：保留备份供用户手动清理
-
-    // 10. 输出成功信息
-    console.log(chalk.green(`\n✅ 升级完成！`));
-
+    console.log(chalk.green(`\n✅ 迁移完成！`));
     if (migrationPlan.needsMigration) {
       console.log(chalk.green('   已完成旧版本迁移'));
     }
@@ -190,7 +145,6 @@ async function upgrade(options = {}) {
     console.log(chalk.gray(`\n   备份位置: ${path.basename(backupDir)}/`));
     console.log(chalk.gray('   如需回滚，请手动恢复备份文件'));
 
-    // 11. 检查是否需要 AI 内容迁移
     if (migrationPlan.needsAIMigration) {
       console.log(chalk.yellow('\n⚠️  检测到文档内容需要智能迁移'));
       console.log(chalk.yellow('   以下内容需要 AI 介入处理：'));
@@ -207,7 +161,7 @@ async function upgrade(options = {}) {
     console.error(chalk.red('\n❌ 升级失败：'), error.message);
 
     // 提示备份位置
-    const backups = await findBackups(cwd);
+    const backups = await findBackups(cwd, ['.jvibe-backup-', '.jvibe-uninstall-backup-']);
     if (backups.length > 0) {
       console.log(chalk.yellow(`   最新备份: ${backups[0]}`));
     }
@@ -221,11 +175,11 @@ async function upgrade(options = {}) {
  * @param {string} dir - 项目目录
  * @returns {Promise<string[]>}
  */
-async function findBackups(dir) {
+async function findBackups(dir, prefixes = ['.jvibe-backup-']) {
   try {
     const files = await fs.readdir(dir);
     return files
-      .filter(f => f.startsWith('.jvibe-backup-'))
+      .filter(f => prefixes.some(prefix => f.startsWith(prefix)))
       .sort()
       .reverse();
   } catch (e) {

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

@@ -29,6 +29,7 @@ description: 初始化 JVibe 项目文档结构
 - 模块清单（根据 AI 分析生成）
 - 模块依赖关系
 - 模块功能统计表（初始为空）
+- 环境配置（项目根路径、代码根路径）
 
 ### Feature-List.md
 
@@ -207,13 +208,19 @@ questions:
 3. **AI 分析规划**：生成模块架构、依赖关系、技术栈推荐
 4. **用户确认/调整**：让用户确认或修改架构
 5. 创建 `docs/` 目录
-6. 从模板复制并填充项目信息
-7. 创建 4 个核心文档：
+6. 自动识别项目路径并写入 Project.md：
+   ```yaml
+   detect_paths:
+     project_root: $PWD (包含 .git 或 .claude)
+     code_root: src/ | app/ | lib/ | .
+   ```
+7. 从模板复制并填充项目信息
+8. 创建 4 个核心文档：
    - **Project.md**：填充模块清单、架构图、技术栈
    - **Feature-List.md**：空模板（后续逐个添加功能）
    - **Standards.md**：基础模板
    - **Appendix.md**：基础模板
-8. **创建状态标记文件** `.jvibe-state.json`：
+9. **创建状态标记文件** `.jvibe-state.json`：
    ```json
    {
      "initialized": true,
@@ -222,7 +229,7 @@ questions:
      "createdAt": "2026-01-11T10:00:00Z"
    }
    ```
-9. 输出确认信息
+10. 输出确认信息
 
 ## 输出要求
 

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

@@ -79,6 +79,9 @@ project:
   architecture: []
   tech_stack: []
   modules: []
+  paths:
+    project_root: $PWD (包含 .git 或 .claude)
+    code_root: src/ | app/ | lib/ | .
 features: []
 appendix:
   entries: []
@@ -121,7 +124,7 @@ appendix:
 #### 3.4 重构 Project
 
 1. **按模板章节顺序重建**
-2. **填充项目事实**（架构、模块、接口、数据模型、代码落点）
+2. **填充项目事实**（架构、模块、接口、数据模型、代码落点、项目路径）
 3. **更新模块功能统计**（从功能清单重新计算）
 
 #### 3.5 重构 Standards / Appendix

package/template/docs/core/Project.md

@@ -228,3 +228,12 @@ src/modules/chat/
 | chat_rooms | ChatModule | id, name, type, created_at | name |
 | messages | ChatModule | id, room_id, sender_id, content, sent_at | room_id, sender_id, sent_at |
 | room_members | ChatModule | id, room_id, user_id, joined_at | room_id, user_id |
+
+---
+
+## 7. 环境配置
+
+| 项目项 | 值 | 说明 |
+|------|----|------|
+| 项目根路径 | `[自动填充]` | 运行 `pwd` 或识别 `.git/.claude` 所在目录 |
+| 代码根路径 | `[自动填充]` | 常见为 `src/`，若无则为项目根 |

package/template/docs/core/Standards.md

@@ -50,6 +50,21 @@ docs/
 | P-001  | API文档      | `docs/project/api.md`      | REST API端点     | active |
 | P-002  | 数据库Schema | `docs/project/database.md` | 表结构和ER图     | active |
 
+**自动创建规则**：
+```yaml
+project_docs:
+  create_if:
+    has_api_layer: docs/project/api.md
+    has_database: docs/project/database.md
+    has_frontend: docs/project/frontend.md
+    has_backend: docs/project/backend.md
+```
+
+**使用方式**：
+- 新增文档必须先登记到注册表（§2.2）
+- 文档开头写明用途、更新时机、信息来源
+- 内容更新以模块变更为触发，不做长期遗漏
+
 ### 2.3 任务交接文件（Task Handoff）
 
 **位置**：`docs/.jvibe/tasks.yaml`
@@ -146,6 +161,23 @@ planner 分析需求（必要时反问澄清）
 ...
 ```
 
+### 3.5 环境隔离与依赖安装
+
+```yaml
+env_isolation:
+  required: true
+  forbid: [base, global]
+  allowed:
+    - .venv
+    - .conda
+  install:
+    python: "<env>/bin/python -m pip install ..."
+    node: "npm ci (project root)"
+```
+
+- 任何测试或脚本必须使用项目隔离环境，不允许默认 base 环境
+- 环境选择与激活方式写入项目文档（如无相关章节则新增“环境配置”）
+
 ---
 
 ## 4. 文档编写规范
@@ -197,6 +229,14 @@ planner 分析需求（必要时反问澄清）
 1. 在注册表（§2.2）添加记录
 2. 在文档开头说明用途和更新时机
 
+必须包含项目路径信息：
+```yaml
+project_paths:
+  project_root: required
+  code_root: required
+  source: auto_detected
+```
+
 ---
 
 ## 5. 文档同步规则