---

目录

- 什么是 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 │
│ (自动同步状态) │
│ │
└─────────────────────────────────────────────────────────────┘
`

---

🚀 快速开始

$3

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

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

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

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

`bash


全局安装

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 引导式创建文档

`bash


在 Claude Code 中运行

/JVibe:init

在 OpenCode 中运行

/jvibe-init
`

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

---

$3

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

---

$3

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

`bash


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 支持多种使用方式，可按场景组合：

$3

`bash


交互式 TUI

jvibe

直接初始化

jvibe init --no-ui

仅检查升级

jvibe upgrade --check
`

$3

`bash
/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；不会自动推进到下一阶段。

`bash


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 更新状态与统计

$3

`bash
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
`

---

📚 文档体系

$3

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

$3

功能状态只在 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 维护

$3

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

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

`bash


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 指向新版本：
`json
"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：只实现当前需要的功能

---

❓ 常见问题

JVibe 支持哪些 AI 编码工具？

目前支持：
- Claude Code - Anthropic 官方 CLI 工具
- OpenCode - 开源 AI 编码助手

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


已有项目如何接入 JVibe？

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


CORE-DOCS 和 PROJECT-DOCS 有什么区别？

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

详见 CORE vs PROJECT 文档。

如何升级到新版本？

`bash


检查是否有新版本

jvibe upgrade --check

执行升级（会提示确认）

jvibe upgrade

强制升级（跳过确认）

jvibe upgrade --force
`


Agent 之间如何协作？

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

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


如何卸载 JVibe？

`bash


卸载项目内的 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 主页

---