JVibe

文档驱动的 AI 辅助开发系统

Doc-driven AI-assisted Development System for Claude Code & OpenCode

快速开始 · 使用方法 · 文档 · 贡献

目录

• 什么是 JVibe？
• 为什么选择 JVibe？
• 快速开始
• 使用方法一览
• 典型使用场景
• 项目结构
• 文档体系
• Agent 架构
• CLI 命令
• Core Tools 维护
• 核心原则
• ���见问题
• 文档
• 贡献
• 许可证

📌 什么是 JVibe？

JVibe 是一个文档驱动的 AI 辅助开发系统，面向 Claude Code 与 OpenCode。核心能力包括：

• 🎯 单一事实来源：功能状态只在功能清单中维护（SoT 原则）
• 🤖 多 Agent 协作：规划、开发、测试、修复、审查、文档同步
• 📝 结构化文档体系：CORE-DOCS（4 个核心文档）+ PROJECT-DOCS（按需扩展）
• 🔄 自动化 Hooks：加载上下文、同步状态、输出统计信息

💡 为什么选择 JVibe？

| 痛点 | JVibe 解决方案 | |------|---------------| | AI 缺乏项目上下文，每次都要重复解释 | 自动加载项目文档，AI 开箱即知项目全貌 | | 功能状态散落各处，难以追踪 | 单一事实来源（SoT），状态只在一处维护 | | AI 生成代码质量参差不齐 | 多 Agent 分工协作，专业的事交给专业的 Agent | | 文档与代码脱节，维护困难 | 文档驱动开发，代码变更自动触发文档同步 | | 团队协作时上下文丢失 | 结构化任务交接文件，无缝衔接工作进度 |

核心优势：

┌─────────────────────────────────────────────────────────────┐
│                      JVibe 工作流                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   需求 ──→ planner ──→ developer ──→ tester ──→ reviewer   │
│     │                      │            │           │       │
│     └──────────────────────┴────────────┴───────────┘       │
│                            ↓                                │
│                       doc-sync                              │
│                    (自动同步状态)                            │
│                                                             │
└─────────────────────────────────────────────────────────────┘

🚀 快速开始

初始化方式（选一种）

JVibe 提供两种初始化方式，根据你的需求选择：

方式 1：CLI 初始化（推荐）

适用场景：新项目、需要完整的文件结构

默认进入 TUI 配置向导，如需跳过请使用 --no-ui。

# 全局安装
npm install -g jvibe

# 初始化项目
cd your-project

# 进入 TUI 配置（推荐）
jvibe

# 或者
jvibe setup

# 跳过 TUI，直接初始化
jvibe init --no-ui

# Claude Code 适配
jvibe init --adapter=claude --no-ui

# OpenCode 适配
jvibe init --adapter=opencode --no-ui

# 同时适配 Claude Code + OpenCode
jvibe init --adapter=both --no-ui

初始化过程中，如果检测到项目 docs/ 目录下仍存在旧的中文核心文档（规范文档.md/项目文档.md/功能清单.md/附加材料.md），jvibe init 会给出提示，建议迁移/删除以避免出现“旧中文文档 + 新英文文档”双轨并存导致的规范不一致。

特点：

• ✅ 自动复制所有配置文件（agents、hooks、commands）
• ✅ 创建完整的文档结构（Core + Project）
• ✅ 一次性完成所有设置

方式 2：Claude Code / OpenCode 命令初始化

适用场景：现有项目、需要 AI 引导式创建文档

# 在 Claude Code 中运行
/JVibe:init

# 在 OpenCode 中运行
/jvibe-init

特点：

• 🤖 AI 引导式询问（项目名称、类型、技术栈）
• 🤖 AI 自动分析并规划模块架构
• 🤖 识别既有项目时先扫描代码/文档并填充 Project 与 Feature-List
• 🤖 根据需求生成定制化文档
• ⚠️ 注意：如果已运行 jvibe init，无需再执行此命令

选择哪种方式？

| 你的情况 | 推荐方式 | 原因 | |---------|---------|------| | 全新项目 | CLI 初始化 | 一次性获得完整配置 | | 已有项目，想试用 JVibe | Claude/OpenCode 命令 | 自动扫描现有代码/文档 | | 需要快速开始 | CLI 初始化 | 无需手动配置 | | 需要定制化文档 | Claude/OpenCode 命令 | AI 根据需求生成 |

开始使用

初始化完成后，在 Claude Code 或 OpenCode 中使用：

# Claude Code
/JVibe:status   # 查看项目状态
/JVibe:plan     # 规划新功能（planner）
/JVibe:dev      # 开发实现（developer）
/JVibe:test     # 测试验证（tester）
/JVibe:sop      # 按 SOP 选择并执行阶段
/JVibe:keepgo   # 自动推进（强力但不稳定）
/JVibe:pr       # 生成 PR 描述

# OpenCode
/jvibe-status   # 查看项目状态
/jvibe-plan     # 规划新功能（planner）
/jvibe-dev      # 开发实现（developer）
/jvibe-test     # 测试验证（tester）
/jvibe-sop      # 按 SOP 选择并执行阶段
/jvibe-keepgo   # 自动推进（强力但不稳定）
/jvibe-pr       # 生成 PR 描述

🧭 使用方法一览

JVibe 支持多种使用方式，可按场景组合：

1) 命令行与 TUI

# 交互式 TUI
jvibe

# 直接初始化
jvibe init --no-ui

# 仅检查升级
jvibe upgrade --check

2) AI 命令驱动（Claude/OpenCode）

/JVibe:init     # 初始化项目文档（已有项目会先扫描）
/JVibe:plan     # 规划新功能（planner）
/JVibe:dev      # 开发实现（developer）
/JVibe:test     # 测试验证（tester）
/JVibe:bugfix   # 复杂修复（bugfix）
/JVibe:doc-sync # 文档同步（doc-sync）
/JVibe:review   # 代码审查（reviewer）
/JVibe:sop      # 按 SOP 选择并执行阶段（命令式封装）
/JVibe:keepgo   # 自动推进下一步
/JVibe:status   # 查看项目状态
/JVibe:pr       # 生成 PR 描述
/JVibe:migrate  # 迁移旧文档

OpenCode 对应命令： /jvibe-init、/jvibe-plan、/jvibe-dev、/jvibe-test、/jvibe-bugfix、/jvibe-doc-sync、/jvibe-review、/jvibe-sop、/jvibe-keepgo、/jvibe-status、/jvibe-pr、/jvibe-migrate

/JVibe:sop / /jvibe-sop 使用说明（命令式）

/JVibe:sop 是一个统一入口：你先显式选择阶段（plan/dev/test/bugfix/doc/review；其中 doc=doc-sync），它会按该阶段的 SOP 把自然语言整理成规范 task_input（YAML），然后调用对应 subagent；不会自动推进到下一阶段。

# Claude Code
/JVibe:sop plan      # 规划：整理需求 → 调用 planner（plan_feature）
/JVibe:sop dev       # 开发：整理 feature_id/todos/code_roots → 调用 developer（develop_feature）
/JVibe:sop test      # 测试：targeted/discover → 调用 tester（run_tests）
/JVibe:sop bugfix    # 修复：整理 failures/modules_hit/files → 调用 bugfix（fix_bug）
/JVibe:sop doc       # 同步（doc-sync）：同步状态/统计/执行 doc_updates → 调用 doc-sync
/JVibe:sop review    # 审查：files/diff_range → 调用 reviewer（只读）

# OpenCode
/jvibe-sop plan|dev|test|bugfix|doc|review

3) 开发流程

• 需求描述 → planner 生成 TODO
• 功能实现 → developer 完成 TODO
• 测试验证 → tester 执行测试
• 测试失败且涉及多模块/核心模块 → bugfix 修复 → tester 复测
• 代码审查 → reviewer 给出审查结论
• 文档同步 → doc-sync 更新状态与统计

4) 运维与校验

jvibe upgrade   # 升级到最新版本
jvibe migrate   # 保留旧结构的迁移模式
jvibe validate  # 检查配置完整性
jvibe uninstall # 卸载 JVibe 配置

🎯 典型使用场景

• 新项目快速启动：jvibe 进入 TUI 初始化 → /JVibe:status 查看状态 → /JVibe:keepgo 推进任务
• 已有项目接入：/JVibe:init 自动扫描代码/文档 → 生成 Project 与 Feature-List → 再用 /JVibe:keepgo 继续
• 需求到落地：描述需求 → planner 拆解 TODO → developer 实现 → tester 验证 → reviewer 反馈
• 测试自动派发：TODO 含“测试/test” → keepgo 进入测试阶段自动调用 tester
• 版本升级：jvibe upgrade --check 先确认 → jvibe upgrade 执行升级（需要确认或 --force）
• 协作交接：以 docs/core/Feature-List.md 为 SoT，同步进度到 docs/.jvibe/tasks.yaml

📂 项目结构

运行 jvibe init 后，你的项目将包含：

your-project/
├── .claude/                    # Claude Code 配置（可选）
│   ├── agents/                 # 6 个 Sub-Agents
│   ├── commands/               # 5 个 JVibe Skills
│   ├── hooks/                  # 4 个自动化 Hooks
│   └── settings.json
│
├── .opencode/                  # OpenCode 配置（可选）
│   ├── agent/                  # 6 个 Sub-Agents
│   ├── command/                # 5 个 JVibe Commands
│   ├── permissions.yaml        # 权限矩阵
│   ├── error-handling.md       # 错误处理策略
│   ├── instructions.md         # OpenCode 启动指令
│   └── opencode.jsonc
│
├── docs/
│   ├── core/                   # CORE-DOCS（4个固定核心文档）
│   │   ├── Standards.md        # 入口和索引
│   │   ├── Project.md          # 架构与模块边界
│   │   ├── Feature-List.md     # 功能状态唯一来源（SoT）
│   │   └── Appendix.md        # 规范索引
│   ├── .jvibe/                 # 任务交接文件
│   │   └── tasks.yaml          # 单文件协作入口
│   │
│   └── project/                # PROJECT-DOCS（按需创建）
│       └── README.md
│
└── .gitignore

📚 文档体系

CORE-DOCS vs PROJECT-DOCS

| 维度 | CORE-DOCS | PROJECT-DOCS | |------|-----------|--------------| | 结构 | 所有项目相同 | 按需创建 | | 数量 | 固定 4 个 | 可变（0~N） | | 注册 | 自动存在 | 必须在规范文档中注册 |

单一事实来源（SoT）

功能状态只在 Feature-List.md 中维护：

TODO 完成情况 → 功能状态
┌─────────────────────────────────────┐
│  完成数 / 总数  │  状态符号   │
├─────────────────┼─────────────┤
│     0 / N       │     ❌      │
│   1~(N-1) / N   │     🚧      │
│     N / N       │     ✅      │
└─────────────────────────────────────┘

🤖 Agent 架构

| Agent | 职责 | 模型 | |-------|------|------| | planner | 需求分析、功能拆解 | Opus | | developer | 代码实现、TODO 完成 | Sonnet | | tester | 测试执行、结果分析 | Sonnet | | bugfix | 缺陷修复、补充测试 | Opus | | reviewer | 代码审查、规范检查 | Sonnet | | doc-sync | 状态推导、统计更新 | Haiku |

🔧 CLI 命令

| 命令 | 说明 | |------|------| | jvibe init | 初始化 JVibe 项目 | | jvibe setup | 启动 TUI 配置向导 | | jvibe init --mode=minimal | 最小化初始化（仅 Core 文档） | | jvibe init --force | 强制覆盖已存在的配置 | | jvibe init --adapter=opencode | 初始化 OpenCode 适配 | | jvibe init --adapter=both | 同时适配 Claude Code + OpenCode | | jvibe upgrade | 升级到最新版本（默认卸载重装） | | jvibe upgrade --check | 仅检查更新 | | jvibe upgrade --migrate | 仅执行旧版迁移 | | jvibe uninstall | 卸载项目内 JVibe 配置 | | jvibe status | 查看项目配置状态 | | jvibe validate | 验证项目配置 |

🔌 Core Tools 维护

Agent Browser Skill 更新

Agent Browser Skill 当前固定在 v0.6.0 版本，以确保稳定性。如需更新到最新版本：

方法 1：手动更新（推荐）

# 1. 访问 GitHub Releases 页面查看最新版本
# https://github.com/vercel-labs/agent-browser/releases

# 2. 下载最新版本的 SKILL.md
curl -o .claude/skills/agent-browser/SKILL.md \
  https://raw.githubusercontent.com/vercel-labs/agent-browser/v0.7.0/skills/agent-browser/SKILL.md

# 3. 更新 CLI 到对应版本
npm install -g agent-browser@latest
agent-browser install

方法 2：修改 registry.json（高级用户）

如果你想让 jvibe plugins core 自动使用新版本：

1. 编辑 lib/plugins/registry.json
2. 找到 agent-browser 配置（约第 80 行）
3. 修改 skillSource 指向新版本：

   "skillSource": "https://raw.githubusercontent.com/vercel-labs/agent-browser/v0.7.0/skills/agent-browser/SKILL.md"

4. 删除现有 Skill 文件：rm -rf .claude/skills/agent-browser
5. 重新运行：jvibe plugins core

注意：更新前请查看 Agent Browser Changelog 确认兼容性。

🎯 核心原则

JVibe 基于以下原则设计：

• SOLID：单一职责、开闭原则、里氏替换、接口隔离、依赖倒置
• DRY：避免重复，功能状态只在一处维护
• KISS：保持简单，状态推导规则清晰明确
• YAGNI：只实现当前需要的功能

❓ 常见问题

目前支持：

• Claude Code - Anthropic 官方 CLI 工具
• OpenCode - 开源 AI 编码助手

通过 --adapter 参数选择适配器，或使用 --adapter=both 同时支持两者。

推荐使用 /JVibe:init 命令（在 Claude Code 中）或 /jvibe-init（在 OpenCode 中）。AI 会自动扫描现有代码和文档，生成符合项目现状的 Feature-List 和 Project 文档。

• CORE-DOCS：固定 4 个核心文档，所有项目结构相同，自动存在
• PROJECT-DOCS：按需创建的扩展文档（如 API 文档、数据库文档），必须在规范文档中注册

详见 CORE vs PROJECT 文档。

# 检查是否有新版本
jvibe upgrade --check

# 执行升级（会提示确认）
jvibe upgrade

# 强制升级（跳过确认）
jvibe upgrade --force

JVibe 采用流水线式协作：

1. planner 分析需求，拆解为 TODO 列表
2. developer 逐项完成 TODO，编写代码
3. tester 执行测试，验证功能
4. bugfix 处理复杂 bug（多模块/核心模块问题）
5. reviewer 代码审查，确保质量
6. doc-sync 自动同步文档状态

使用 /JVibe:keepgo 可自动推进到下一阶段。

# 卸载项目内的 JVibe 配置
jvibe uninstall

# 全局卸载
npm uninstall -g jvibe

📖 文档

• 快速开始指南
• CLI 命令参考
• 架构说明
• CORE vs PROJECT 文档
• Tools & Plugins（工具与插件）
• 贡献指南

🤝 贡献

欢迎贡献！请查看 贡献指南。

1. Fork 本仓库
2. 创建分支 git checkout -b feature/improvement
3. 提交变更 git commit -m 'feat: 添加新功能'
4. 推送分支 git push origin feature/improvement
5. 创建 Pull Request

📄 许可证

MIT

🔗 相关链接

• Claude Code 官方文档
• OpenCode 官方文档
• OpenSpec - 灵感来源
• GitHub Issues - 问题反馈
• NPM Package - NPM 主页

如果 JVibe 对你有帮助，请给个 ⭐ Star 支持一下！

Made with ❤️ by 9963KK