文档驱动的 AI 辅助开发系统 - Doc-driven AI-assisted development system for Claude Code and OpenCode
npm install jvibe文档驱动的 AI 辅助开发系统
Doc-driven AI-assisted Development System for Claude Code & OpenCode





---
- 什么是 JVibe?
- 为什么选择 JVibe?
- 快速开始
- 使用方法一览
- 典型使用场景
- 项目结构
- 文档体系
- Agent 架构
- CLI 命令
- Core Tools 维护
- 核心原则
- ���见问题
- 文档
- 贡献
- 许可证
---
JVibe 是一个文档驱动的 AI 辅助开发系统,面向 Claude Code 与 OpenCode。核心能力包括:
- 🎯 单一事实来源:功能状态只在功能清单中维护(SoT 原则)
- 🤖 多 Agent 协作:规划、开发、测试、修复、审查、文档同步
- 📝 结构化文档体系:CORE-DOCS(4 个核心文档)+ PROJECT-DOCS(按需扩展)
- 🔄 自动化 Hooks:加载上下文、同步状态、输出统计信息
---
| 痛点 | JVibe 解决方案 |
|------|---------------|
| AI 缺乏项目上下文,每次都要重复解释 | 自动加载项目文档,AI 开箱即知项目全貌 |
| 功能状态散落各处,难以追踪 | 单一事实来源(SoT),状态只在一处维护 |
| AI 生成代码质量参差不齐 | 多 Agent 分工协作,专业的事交给专业的 Agent |
| 文档与代码脱节,维护困难 | 文档驱动开发,代码变更自动触发文档同步 |
| 团队协作时上下文丢失 | 结构化任务交接文件,无缝衔接工作进度 |
核心优势:
```
┌─────────────────────────────────────────────────────────────┐
│ JVibe 工作流 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 需求 ──→ planner ──→ developer ──→ tester ──→ reviewer │
│ │ │ │ │ │
│ └──────────────────────┴────────────┴───────────┘ │
│ ↓ │
│ doc-sync │
│ (自动同步状态) │
│ │
└─────────────────────────────────────────────────────────────┘
---
JVibe 提供两种初始化方式,根据你的需求选择:
#### 方式 1:CLI 初始化(推荐)
适用场景:新项目、需要完整的文件结构
默认进入 TUI 配置向导,如需跳过请使用 --no-ui。
`bash全局安装
npm install -g jvibe
初始化过程中,如果检测到项目
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.md3. 更新 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 文档、数据库文档),必须在规范文档中注册
如何升级到新版本?
`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`---
---
- Claude Code 官方文档
- OpenCode 官方文档
- OpenSpec - 灵感来源
- GitHub Issues - 问题反馈
- NPM Package - NPM 主页
---
如果 JVibe 对你有帮助,请给个 ⭐ Star 支持一下!
Made with ❤️ by 9963KK