jvibe 1.0.9 → 1.1.1

package/JVIBE.md

@@ -52,7 +52,7 @@ TODO 完成情况 → 功能状态
 ### 3. 开发流程
 
 ```
-需求分析 → 功能拆解 → 技术设计 → 编码实现 → 代码审查 → 文档同步
+需求分析 → 功能拆解 → 技术设计 → 编码实现 → 测试验证 → 代码审查 → 文档同步
 ```
 
 ## Agent 职责
@@ -61,6 +61,7 @@ TODO 完成情况 → 功能状态
 |-------|------|----------|
 | **planner** | 需求分析、功能拆解、创建 F-XXX 条目 | Feature-List.md |
 | **developer** | 代码实现、逐项完成 TODO、勾选完成项 | Feature-List.md + 源代码 |
+| **tester** | 测试执行、结果分析、回归验证 | 测试文件（仅在明确要求时） |
 | **reviewer** | 代码审查、规范检查、PR 描述生成 | 只读 |
 | **doc-sync** | 状态推导、统计更新、格式检查 | Project.md |
 

package/README.md

@@ -11,7 +11,7 @@
 
 JVibe 是一个**文档驱动的 AI 辅助开发系统**，专为 Claude Code 设计。它提供：
 
-- 🤖 **4 个专业 Agent**：需求规划、代码开发、代码审查、文档同步
+- 🤖 **5 个专业 Agent**：需求规划、代码开发、测试验证、代码审查、文档同步
 - 📝 **结构化文档体系**：CORE-DOCS（4个核心文档）+ PROJECT-DOCS（按需扩展）
 - 🔄 **自动化 Hooks**：自动加载上下文、同步功能状态、输出统计信息
 - 🎯 **单一事实来源**：功能状态只在功能清单中维护（SoT 原则）
@@ -91,7 +91,7 @@ jvibe init
 ```
 your-project/
 ├── .claude/                    # Claude Code 配置
-│   ├── agents/                 # 4 个 Sub-Agents
+│   ├── agents/                 # 5 个 Sub-Agents
 │   ├── commands/               # 3 个 JVibe Skills
 │   ├── hooks/                  # 4 个自动化 Hooks
 │   └── settings.json
@@ -146,6 +146,7 @@ TODO 完成情况 → 功能状态
 |-------|------|------|
 | **planner** | 需求分析、功能拆解 | Sonnet |
 | **developer** | 代码实现、TODO 完成 | Sonnet |
+| **tester** | 测试执行、结果分析 | Sonnet |
 | **reviewer** | 代码审查、规范检查 | Sonnet |
 | **doc-sync** | 状态推导、统计更新 | Haiku |
 
@@ -158,8 +159,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.1",
   "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/init.js

@@ -100,7 +100,7 @@ async function init(options = {}) {
     console.log(chalk.green('\n✅ JVibe 初始化完成！\n'));
 
     console.log(chalk.white('已创建：'));
-    console.log(chalk.gray('  - .claude/agents/      (4 个 Sub-Agents)'));
+    console.log(chalk.gray('  - .claude/agents/      (5 个 Sub-Agents)'));
     console.log(chalk.gray('  - .claude/commands/    (3 个 JVibe Skills)'));
     console.log(chalk.gray('  - .claude/hooks/       (3 个自动化 Hooks)'));
     console.log(chalk.gray('  - .claude/settings.json'));

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/scripts/validate.js

@@ -39,7 +39,7 @@ async function validate() {
       }
 
       // 检查 agents
-      const requiredAgents = ['planner.md', 'developer.md', 'reviewer.md', 'doc-sync.md'];
+      const requiredAgents = ['planner.md', 'developer.md', 'reviewer.md', 'doc-sync.md', 'tester.md'];
       const agentsDir = path.join(claudeDir, 'agents');
       if (await fs.pathExists(agentsDir)) {
         for (const agent of requiredAgents) {

package/template/.claude/agents/developer.md

@@ -41,6 +41,7 @@ model: sonnet
 ## 约束（硬规则）
 
 ```yaml
+source_of_truth: .claude/permissions.yaml
 constraints:
   read_allowlist:
     - docs/**
@@ -57,7 +58,11 @@ constraints:
     - .claude/**
     - .jvibe-state.json
     - package.json
-    - lockfiles
+    - package-lock.json
+    - pnpm-lock.yaml
+    - yarn.lock
+    - Pipfile.lock
+    - poetry.lock
     - .gitignore
   ops:
     network: forbidden
@@ -103,8 +108,22 @@ constraints:
 ### TODO 执行规则
 
 1. **按顺序执行**：通常按 TODO 列表顺序
-2. **完成即勾选**：完成一个就勾选一个，不要积攒
-3. **遇阻即报告**：无法完成时说明原因
+2. **尽量一次完成**：单次调用应尝试完成该功能的所有 TODO
+3. **完成即勾选**：完成一个就勾选一个，不要积攒
+4. **遇阻即报告**：无法完成时说明原因并停止
+
+### 交接协议
+
+```yaml
+handoff_rules:
+  - when: todo_includes_test
+    target: tester
+    action: run_tests
+    payload:
+      feature: F-XXX
+      files: []
+      scope: unit|integration|e2e
+```
 
 ### 勾选格式
 
@@ -136,6 +155,16 @@ update_requests:  # 需要主 Agent 处理的更新
     action: check_status
     feature: F-XXX
     reason: "TODO 全部完成，需要更新功能状态"
+
+handoff:
+  target: tester
+  action: run_tests
+  payload:
+    feature: F-XXX
+    files:
+      - src/modules/auth/register.ts
+      - src/modules/auth/register.test.ts
+    scope: unit
 ```
 
 ## 示例
@@ -194,6 +223,16 @@ update_requests:
     action: check_status
     feature: F-018
     reason: "所有 TODO 已完成，需要更新功能状态为 ✅"
+
+handoff:
+  target: tester
+  action: run_tests
+  payload:
+    feature: F-018
+    files:
+      - src/modules/chat/thumbnail.service.ts
+      - src/modules/chat/file.test.ts
+    scope: integration
 ```
 
 ## 注意事项

package/template/.claude/agents/doc-sync.md

@@ -14,7 +14,7 @@ model: haiku
 1. **状态推导**：根据 TODO 完成情况推导功能状态
 2. **统计更新**：更新项目文档中的统计表
 3. **格式检查**：检查文档格式一致性
-4. **Git 提交**：仅在用户明确要求时执行
+4. **Git 提交**：仅在用户明确要求或 keepgo `auto_commit=true` 时执行
 
 ## 权限范围
 
@@ -38,6 +38,7 @@ model: haiku
 ## 约束（硬规则）
 
 ```yaml
+source_of_truth: .claude/permissions.yaml
 constraints:
   read_allowlist:
     - docs/core/Feature-List.md
@@ -52,13 +53,17 @@ constraints:
     - .claude/**
     - .jvibe-state.json
     - package.json
-    - lockfiles
+    - package-lock.json
+    - pnpm-lock.yaml
+    - yarn.lock
+    - Pipfile.lock
+    - poetry.lock
     - .gitignore
   ops:
     network: forbidden
     install: forbidden
     tests: forbidden
-    git: only_if_user_requested
+    git: only_if_user_requested  # keepgo auto_commit=true counts as explicit request
 ```
 
 ## 状态推导规则

package/template/.claude/agents/planner.md

@@ -35,6 +35,7 @@ model: sonnet
 ## 约束（硬规则）
 
 ```yaml
+source_of_truth: .claude/permissions.yaml
 constraints:
   read_allowlist:
     - docs/**
@@ -46,7 +47,11 @@ constraints:
     - .claude/**
     - .jvibe-state.json
     - package.json
-    - lockfiles
+    - package-lock.json
+    - pnpm-lock.yaml
+    - yarn.lock
+    - Pipfile.lock
+    - poetry.lock
     - .gitignore
   ops:
     network: forbidden
@@ -55,6 +60,13 @@ constraints:
     git: forbidden
 ```
 
+## 拒绝规划规则
+
+当需求明显超出项目范围或违反约束时：
+- 不写入 `Feature-List.md`
+- 说明拒绝原因与可行替代方案
+- 如可拆解，建议用户缩小范围后再规划
+
 ## 工作流程
 
 ```

package/template/.claude/agents/reviewer.md

@@ -38,6 +38,7 @@ model: sonnet
 ## 约束（硬规则）
 
 ```yaml
+source_of_truth: .claude/permissions.yaml
 constraints:
   read_allowlist:
     - docs/**
@@ -52,7 +53,7 @@ constraints:
     network: forbidden
     install: forbidden
     tests: forbidden
-    git: read_only  # allow git diff/status only
+    git: read_only  # allowed: git diff, git status, git log --oneline, git show
 ```
 
 ## 工作流程
@@ -125,20 +126,18 @@ result:
   summary: "审查通过/需要修改"
   files_reviewed: 5
 
-  issues:  # 发现的问题
+  issues:  # 发现的问题（spec 可选，优先在 hit_specs 汇总）
     - severity: error      # error/warning/info
       file: src/auth/login.ts
       line: 42
       message: "SQL 拼接存在注入风险"
       suggestion: "使用参数化查询"
-      spec: SEC-001
 
     - severity: warning
       file: src/user/profile.ts
       line: 78
       message: "函数复杂度过高"
       suggestion: "拆分为多个小函数"
-      spec: CS-003
 
   hit_specs:  # 命中的规范条目
     - id: CS-001