vibe — VIBE 工作流 CLI

通过 Planner + Reviewer 双 session 协作，让能力较弱的模型（如豆包等）也能可靠地完成复杂需求开发和 bug 修复。

适用场景： 模型推理能力有限，但代码逻辑复杂、需要严格审查和多轮迭代的项目。

vibe "实现用户登录功能，支持邮箱注册和 JWT 认证"

安装

1. 安装前置依赖

• Node.js >= 18 — 下载地址
• Claude Code CLI — npm install -g @anthropic-ai/claude-code
• OpenSpec CLI — npm install -g openspec

2. 安装 vibe

npm install -g @wangjiang988/vibe-coding

验证安装：

vibe --version

3. 升级

npm update -g @wangjiang988/vibe-coding

快速开始

在项目目录下初始化 OpenSpec（首次使用）：

cd ~/projects/myapp
openspec init --tools claude

然后运行 vibe：

vibe "实现用户登录功能，支持邮箱注册和 JWT 认证"

更多用法见下方详细说明。

使用方法

场景一：开发新功能（Full 模式）

适用：复杂功能，需要 proposal、审查、分步实现。

cd ~/projects/myapp
vibe "实现用户登录功能，支持邮箱注册和 JWT 认证"

执行过程：

Tool:     claude
Project:  /home/user/projects/myapp
Request:  实现用户登录功能，支持邮箱注册和 JWT 认证

Mode: full

Generating feature name...
Feature:  user-auth

══════════════════════════════════════════════════════
  Phase 1/6: Planner — /opsx:explore
══════════════════════════════════════════════════════
# Claude 探索代码库，生成 explore.md

══════════════════════════════════════════════════════
  Phase 2/6: Reviewer — 设计反馈 (→ explore.md)
══════════════════════════════════════════════════════
# Reviewer 阅读 explore.md，追加设计反馈

══════════════════════════════════════════════════════
  Phase 3/6: Planner — /opsx:propose
══════════════════════════════════════════════════════
# Planner 生成 proposal.md、design.md、tasks.md、specs/

── Quality Gate: Validating generated artifacts...
# Linter + OpenSpec 验证生成的产物
# 如果验证失败，自动进入修复循环（最多 2 次）
# 修复失败则写入 manual-intervention.md 并停止

══════════════════════════════════════════════════════
  Phase 4/6 Round 1: Reviewer — 审问 Proposal
══════════════════════════════════════════════════════
# Reviewer 对 proposal 进行 MACHINE_CHECKS + 5 维度审问

──────────────────────────────────────────────────
  🔴 Reviewer 发现 2 个需要你确认的问题：
──────────────────────────────────────────────────

  -- Question 1/2 --
  Task: 用户系统
  Q: 是否需要支持第三方登录（Google/GitHub）？
  建议: 如果 MVP 阶段可暂不支持，后续通过 OAuth 扩展

  你的回答: 暂不支持，但预留扩展接口

  -- Question 2/2 --
  Task: token 刷新
  Q: refresh token 的存储策略？
  建议: A) Redis B) 数据库 C) 内存

  你的回答: A

══════════════════════════════════════════════════════
  Phase 5/6 Round 1: Planner — 回应审查
══════════════════════════════════════════════════════
# Planner 回应审查意见，更新 proposal/design/tasks
# 更新后自动重新验证产物有效性

══════════════════════════════════════════════════════
  Phase 6/6: 结论
══════════════════════════════════════════════════════

Artifact Status:
  Linter:     PASS (0 errors, 0 warnings)
  Apply-ready: Yes

🎉 VIBE SDD 工作流执行完毕！

Proceed to code implementation? (y/n, default n):

完成后可续接 session 继续修改：

claude -r "vibe-planner-user-auth"
claude -r "vibe-reviewer-user-auth"

Phase 2：代码实现

SDD 文档审核通过后，可独立运行 Phase 2 实现代码：

# 指定已有 proposal，仅执行代码实现
vibe --phase 2 --proposal user-auth

Phase 2 流程：

• Phase 7/10 — code-applyer 执行 /opsx:apply 按 task 实现代码
• Phase 8-9/10 — code-reviewer 审查工作区未提交代码变更（支持 Codex 或 Claude Code）→ code-applyer 修复（可多轮）
• Phase 10/10 — code-applyer 执行 /opsx:archive 归档

Phase 8-9/10 的 code-reviewer 工具可通过 .vibe.json 配置：

{
  "codeReviewer": {
    "tool": "codex",
    "model": "gpt-5.3-codex",
    "effort": "high"
  }
}

如需继续使用 Claude Code 做代码审查：

{
  "codeReviewer": {
    "tool": "claude",
    "model": "claude-sonnet-4-6",
    "effort": "high"
  }
}

或者一步到位执行完整流程（SDD + 代码实现）：

vibe --phase all "实现用户登录功能，支持邮箱注册和 JWT 认证"

场景二：修 bug（Plan 模式）

适用：简单修复，不需要提案和审查流程。

vibe --mode plan "修复用户登录超时 500 错误，检查 token 过期判断逻辑"

流程：理解需求 → 直接实现 → git commit，一步完成。

场景三：指定项目目录

vibe --dir ~/projects/backend "添加 CSV 导出接口"

场景四：分阶段执行

# 交互选择执行阶段
vibe "重构数据库访问层，改用连接池"

# 指定执行阶段
vibe --phase 1 "添加 CSV 导出接口"     # 仅 SDD 文档
vibe --phase 2 --proposal add-csv-export # 仅代码实现
vibe --phase all "添加 CSV 导出接口"     # SDD + 代码实现

参数

| 参数 | 说明 | 默认值 | |------|------|--------| | --phase <1\|2\|all> | 执行阶段 | 交互选择 | | --proposal <name> | 指定 proposal 名称（Phase 2 使用） | - | | --mode plan\|full | 工作模式（legacy） | - | | --tool <name> | AI 工具 | claude | | --dir <path> | 项目目录 | 当前目录 | | --planner-model <m> | Planner 模型 | deepseek-v4-pro | | --reviewer-model <m> | Reviewer 模型 | deepseek-v4-flash | | --quick-model <m> | 快速生成模型 | deepseek-v4-flash | | --planner-effort <e> | Planner effort | max | | --reviewer-effort <e> | Reviewer effort | high | | --quick-effort <e> | 快速生成 effort | high | | --timeout <ms> | 子进程超时 | 300000 | | --max-rounds <n> | 最大审问轮数 | 5 | | --verbose | 调试日志 | - | | --quiet | 仅显示错误 | - | | --resume | 从中断阶段恢复 | - | | --no-cleanup | 完成后保留 session | - | | -v, --version | 版本号 | - | | -h, --help | 帮助 | - |

质量门控（Quality Gate）

Phase 3 产物生成后、Phase 4 审问之前，自动执行质量检查：

检查流程

Phase 3 完成后
  ├── lintChangeArtifacts() — 确定性检查（无 LLM）
  ├── validateOpenSpecChange() — 运行 openspec validate --strict
  ├── 通过 → 进入 Phase 4
  └── 失败 → 修复循环（最多 2 次）
      ├── 构建修复提示，发送给 Planner session
      ├── 重新检查
      └── 仍失败 → 写入 manual-intervention.md，停止工作流

Linter 检查项

错误（阻止继续）：

• proposal.md、design.md、tasks.md 或 specs/ 缺失
• spec.md 未使用 OpenSpec delta header（## ADDED/MODIFIED/REMOVED/RENAMED Requirements）
• requirement 缺少 #### Scenario: 块

警告（允许继续）：

• spec 使用普通 ## Requirements 而非 delta header
• 同一文件同时出现 MemorySaver 和 --resume/跨进程声明
• 硬编码 git checkout/merge main 或 diff main..
• tasks.md 缺少验收标准（验收/acceptance/验证/VERIFY/MUST）
• specs/ 下超过 2 个 capability 文件夹

Reviewer MACHINE_CHECKS

Phase 4 Reviewer 审问时，必须先填写 MACHINE_CHECKS 表格：

| Check | Status | Evidence | |---|---|---| | OpenSpec delta format | PASS/WARN/FAIL | ... | | Scenario coverage | PASS/WARN/FAIL | ... | | Proposal/design/tasks consistency | PASS/WARN/FAIL | ... | | Scope size | PASS/WARN/FAIL | ... | | Resume/checkpoint consistency | PASS/WARN/FAIL | ... | | Branch/merge safety | PASS/WARN/FAIL | ... | | Task acceptance criteria | PASS/WARN/FAIL | ... |

任一检查为 FAIL 时，即使出现 CONSENSUS_REACHED，工作流也不接受共识。

人工介入

修复循环耗尽后，自动生成 review/manual-intervention.md，包含：

• 失败原因和验证输出
• 需要检查的文件列表
• 手动修复清单（checkbox）
• 可直接复制的修复提示
• 恢复工作流的命令

模型配置

支持通过 CLI flag、环境变量、或编辑 src/constants.js 配置模型和 effort。

优先级：CLI flag > 环境变量 > 默认值

| 变量 | 对应 flag | 默认值 | |------|-----------|--------| | VIBE_PLANNER_MODEL | --planner-model | deepseek-v4-pro | | VIBE_REVIEWER_MODEL | --reviewer-model | deepseek-v4-flash | | VIBE_CODE_APPLYER_MODEL | --code-applyer-model | deepseek-v4-pro | | VIBE_CODE_REVIEWER_MODEL | --code-reviewer-model | deepseek-v4-flash | | VIBE_QUICK_MODEL | --quick-model | deepseek-v4-flash | | VIBE_PLANNER_EFFORT | --planner-effort | max | | VIBE_REVIEWER_EFFORT | --reviewer-effort | high | | VIBE_CODE_APPLYER_EFFORT | --code-applyer-effort | max | | VIBE_CODE_REVIEWER_EFFORT | --code-reviewer-effort | high | | VIBE_QUICK_EFFORT | --quick-effort | high | | VIBE_TIMEOUT | --timeout | 300000 | | VIBE_MAX_ROUNDS | --max-rounds | 5 |

| 角色 | 定位 | 推荐模型 | 推荐 effort | |------|------|---------|-------------| | Planner（Phase 1） | 深度推理、架构设计 | deepseek-v4-pro / claude-opus-4-6 | max | | Reviewer（Phase 1） | 快速审查、发现模糊点 | deepseek-v4-flash / claude-sonnet-4-6 | high | | code-applyer（Phase 2） | 代码实现与修复 | deepseek-v4-pro / claude-opus-4-6 | max | | code-reviewer（Phase 2） | 代码审查 | deepseek-v4-flash / claude-sonnet-4-6 | high | | Quick | 轻量命名、简单分类 | deepseek-v4-flash | high |

项目结构

vibe-cli/
├── README.md
├── package.json
├── cli.js                ← 入口：参数解析、适配器注册
└── src/
    ├── adapters/
    │   └── claude.js     ← Claude Code 适配器（session 管理、超时、进度指示）
    ├── executor.js       ← 工作流引擎（plan + full + resume + 质量门控）
    ├── artifact-linter.js  ← 产物确定性检查（delta header、scenario、一致性）
    ├── openspec-validator.js ← OpenSpec CLI 验证封装（openspec validate --strict）
    ├── artifact-repair.js ← 修复提示构建 + 人工介入模板生成
    ├── logger.js         ← 结构化日志（severity 级别控制）
    ├── prompts.js        ← 交互询问（内置 readline，零依赖）
    ├── namegen.js        ← AI 生成 kebab-case 功能名称
    ├── resume-manager.js ← 状态持久化 / --resume 恢复 / phase 失败标记
    └── constants.js      ← 默认模型、effort、PATHS 配置

扩展

添加新工具（Codex / Cursor / Kimi）

1. 在 src/adapters/ 下新增文件，实现接口：

export class CodexAdapter {
  async createSession(name, prompt, opts) { /* codex exec */ }
  async resumeSession(name, prompt, opts) { /* codex exec */ }
  async quickExec(prompt, opts) { /* 返回 string */ }
}

2. 在 cli.js 的 ADAPTERS 中注册：

const ADAPTERS = {
  claude: ClaudeAdapter,
  codex:  CodexAdapter,   // ← 添加
};

添加新模式

在 executor.js 新增方法，cli.js 加上选项即可。

容器运行

新增 adapters/docker-claude.js，将 spawn('claude', ...) 替换为 spawn('docker', ['exec', containerId, 'claude', ...])。

前置条件

1. claude CLI 已安装
2. 项目已运行 openspec init --tools claude（Full 模式需要）
3. 项目目录下有 .git（用于渐进式 commit）

Linux 注意事项

必须使用非 root 账号运行。 Claude Code 的 --dangerously-skip-permissions (bypass) 参数不允许在 root 用户下执行。

# 1. 创建非 root 用户（如果还没有）
sudo useradd -m -s /bin/bash vibe-user

# 2. 切换到该用户
su - vibe-user

# 3. 确认以下工具在该用户下可执行
node --version    # >= 18
npm --version
claude --version  # Claude Code CLI
openspec --version

# 如果不可用，在该用户下重新安装

要求： npm、node、openspec、claude 均需在非 root 账号下安装并可执行。

与 shell 脚本的关系

vibe-cli 是 scripts/run-openspec-workflow.sh 的 Node.js 替代品，提供了更好的交互体验（用户介入环节）和扩展性（多工具支持）。Shell 脚本保留作为参考和 CI/CD 集成用途。