第一章. Vibe Kanban 环境搭建

1.1. Vibe Kanban 的核心功能与定位

如果你已经在使用 Cursor、GitHub Copilot 或 Windsurf，你可能遇到过这些痛点：

痛点 1：多任务并行时的代码冲突
当你同时让 AI 处理 “用户登录” 和 “密码重置” 两个功能时，它们可能会修改同一个文件（比如 auth.py），导致代码互相覆盖。传统 AI 助手在单一会话中工作，无法隔离不同任务的代码变更。

痛点 2：缺少任务管理与审查机制
AI 生成的代码直接写入你的工作区，你需要手动 review 每一处改动。如果 AI 在凌晨 3 点生成了一段有问题的代码，你可能要到第二天才发现。

痛点 3：无法复用 AI 的工作成果
AI 生成的需求分析、架构设计文档散落在聊天记录里，下次遇到类似需求时，你得重新让 AI 分析一遍。

Vibe Kanban 通过三个核心机制解决了这些问题：

机制 1：Git Worktree 任务隔离
每个任务在独立的 Git 分支和工作目录中执行。“用户登录” 在 feature/login 分支，“密码重置” 在 feature/reset-password 分支，两者互不干扰。即使同时运行 3 个 AI Agent，它们也不会产生代码冲突。

机制 2：看板式任务管理
Vibe Kanban 提供了一个可视化的任务板，每个任务卡片包含：

• 任务状态（Todo / In Progress / Review / Done）
• 执行的 AI Agent（Gemini / Claude Code / Codex）
• 生成的工件（需求文档、架构设计、代码、测试用例）

你可以在任务完成后进行 Code Review，通过后再合并到主分支。

机制 3：工件持久化存储
AI 生成的所有文档（PRD、架构设计、接口契约）都以 Markdown 文件形式保存在项目的 .vibe 目录中。这些文档可以被后续任务引用，形成知识积累。

Vibe Kanban 的定位是 AI 编码助手的编排平台，而不是替代品。它不会取代你正在使用的 Cursor 或 Copilot，而是让你能够：

• 同时使用多个 AI Agent（Gemini 做规划，Claude Code 写代码，Codex 生成测试）
• 让 AI 按照 BMAD 方法论（Analysis → Planning → Solutioning → Implementation）有序工作
• 在安全的沙箱环境中验证 AI 的输出，而不是直接污染主分支

Vibe Kanban 需要你的项目已经初始化为 Git 仓库。如果你还没有代码仓库，我们会在第二章手把手创建一个。

1.2. 安装 Vibe Kanban

Vibe Kanban 是一个基于 Rust 开发的桌面应用，通过 npm 分发。安装过程非常简单，只需一条命令。

步骤 1：验证 Node.js 环境

打开 PowerShell（按 Win + X，选择 “Windows PowerShell”），执行以下命令验证 Node.js 版本：

1
2

node --version
npm --version

你应该看到类似这样的输出：

1
2

v20.11.0
10.2.4

步骤 2：安装 Vibe Kanban

执行以下命令安装 Vibe Kanban：

1

npm install -g vibe-kanban

安装过程大约需要 1-2 分钟。安装完成后，验证安装是否成功：

1

vibe-kanban --version

如果看到版本号（如 vibe-kanban 0.5.2），说明安装成功。

步骤 3：理解 Vibe Kanban 的工作原理

在配置 AI Agent 之前，我们需要理解 Vibe Kanban 的工作流程：

Vibe Kanban 的核心概念：

• 任务一个独立的开发单元，如 实现用户登录接口
• 执行器负责执行任务的 AI Agent，如 Gemini、Claude Code
• 工件任务执行过程中生成的文档或代码
• 工作树基于 Git Worktree 的独立工作目录

1.3. 配置 AI 编码助手：Gemini、Claude Code、Codex

Vibe Kanban 支持多种 AI Agent，但我们推荐使用以下三个组合：

• Gemini：用于需求分析（Analysis）和项目规划（Planning），以及前端开发
• Claude Code：用于架构设计（Solutioning）和代码实现（Implementation）
• OpenAI Codex：用于测试用例生成，在后端复杂的时候可以用于编写后端

这三个 Agent 的特点对比：

1.3.1. Gemini CLI 安装与认证

Gemini 是 Google 推出的多模态大模型，提供了慷慨的免费额度（每分钟 15 次请求）。详见 Gemini CIL 安装与认证。我们将使用 Gemini 3.0 Flash 模型作为主力 Agent，利用其 100 万 Token 的超大上下文窗口 来理解整个项目的需求文档。

优势：处理大规模文档和前端代码生成的性价比极高。
劣势：在处理非常复杂的后端架构逻辑时，偶尔会出现幻觉。

有关 Gemini CLI 的详细安装步骤、API Key 获取以及认证故障排查，请移步阅读我的专题笔记：Gemini CIL 从零开始：安装与认证。

1.3.2. Claude Code 配置

Claude Code 是 Anthropic 推出的代码生成工具，它在代码重构和复杂逻辑实现方面表现优异。详细教程请看 Claude Code 基础篇。

优势：Agentic 自动化能力极强，能主动拆解任务并执行多文件修改。
劣势：固定月费制对低频用户不太友好，且模型输出较慢。

Claude Code 的详细能力边界、安装教程及一人公司实战场景，请阅读我的专题笔记：Claude Code 是什么？3 分钟搞懂 AI 编程助手与传统 Copilot 的本质区别。

1.3.3. OpenAI Codex 配置

OpenAI Codex 是 OpenAI 推出的代码生成模型，擅长生成测试用例和代码补全。了解更多请查看 Codex CLI 入门教程。

优势：严谨性极高，适合用于定位难以发现的 Bug 和编写高质量单元测试。
劣势：单次模型调用成本高，国内访问需要稳定的网络环境。

Codex CLI 的安装、账号鉴权以及三种沙箱模式的配置，请阅读我的专题笔记：Codex 是什么？为什么要用它？。

1.3.4. 其他支持的 Agent 速览

除了上述三个主力 Agent，Vibe Kanban 还支持以下 AI 编码助手：

这些 Agent 的配置方式与上述三个类似，都是通过 CLI 工具安装并配置 API Key。如果你对某个 Agent 感兴趣，可以参考官方文档进行配置。

在本教程中，我们将专注于 Gemini、Claude Code、Codex 三个 Agent 的使用。

1.4. 启动 Vibe Kanban 首次运行

现在我们已经配置好了所有 AI Agent，可以启动 Vibe Kanban 了。

步骤 1：启动 Vibe Kanban

在 PowerShell 中执行：

1

npx vibe-kanban

首次启动时，Vibe Kanban 会执行以下初始化操作：

1. 创建应用数据目录（%APPDATA%\bloop\vibe-kanban\）
2. 初始化 SQLite 数据库（存储任务、工件等数据）
3. 扫描已安装的 AI Agent
4. 启动本地 Web 服务器
5. 若选择的项目没有.git 目录，自动创建.git 目录

启动成功后，你会看到类似这样的页面

1.5. 理解 Vibe Kanban 的界面与任务板

Vibe Kanban 的界面采用经典的看板布局，但在正式使用之前，我们需要先完成一个关键配置：禁用 Claude Code 的 API Key 验证。

重要配置：如果你使用路由代理（如 OpenRouter、API2D）来中转 Claude API，必须禁用 disable_api_key 选项，否则 Claude Code 将无法正常工作

1.5.1. 配置 Claude Code 代理模式

步骤 1：打开代理设置页面

在 Vibe Kanban 界面中：

1. 点击右上角的 “设置” 图标（⚙️ 齿轮图标）
2. 在左侧菜单中点击 “代理”（编码代理配置）

你会看到如下界面：

步骤 2：理解配置选项

在代理设置页面，你会看到以下配置项：

步骤 3：配置代理模式（关键）

按照以下步骤配置：

配置 1：禁用 API Key 验证

找到 disable_api_key 选项，勾选 这个复选框。

1

☑ disable_api_key

这个配置的作用是：告诉 Vibe Kanban 不要验证 Claude API Key，而是直接使用你配置的代理地址。

为什么必须禁用 API Key？

Claude 官方 API 需要使用 sk-ant- 开头的 API Key。但如果你使用第三方代理（如 OpenRouter），代理服务会使用自己的 Key 格式（如 sk-or-）。如果不禁用 API Key 验证，Vibe Kanban 会拒绝这些 “非官方格式” 的 Key。

配置 2：保持 model 字段为空

在 model 输入框中，不要填写任何内容，保持为空。

1

model: [                    ]  ← 留空

这个配置的作用是：让 Vibe Kanban 使用 default 模型配置。如果你手动填写了模型名称（如 claude-3-5-sonnet），可能会导致代理服务无法识别。

为什么 model 必须留空？

Vibe Kanban 的 profiles.json 配置文件中，DEFAULT 变体对应的就是 “model 字段为空” 的情况。如果你填写了具体的模型名称，Vibe Kanban 会尝试使用自定义变体，而不是 DEFAULT 变体，这可能导致配置冲突。

配置 3：保持 dangerously_skip_permissions 勾选

确保 dangerously_skip_permissions 选项是 勾选 状态。

1

☑ dangerously_skip_permissions

这个配置的作用是：启用 YOLO 模式，让 Claude Code 自动执行文件读写、命令执行等操作，无需每次都请求你的确认。

步骤 4：保存配置

完成上述配置后，点击页面底部的 “保存” 按钮。Vibe Kanban 会自动重启 Claude Code 服务，使配置生效。

1.5.2. 设置页面的其他选项

除了代理配置，设置页面还包含以下选项卡：

选项卡 1：常规

• 主题设置：切换亮色/暗色主题
• 语言设置：切换中文/英文界面
• 通知设置：配置任务完成时的通知方式（桌面通知、邮件通知）

选项卡 2：项目

• 默认分支：配置新项目的默认主分支名称（main 或 master）
• 分支命名规范：配置任务分支的命名格式（如 feature/{task-name}）
• 自动删除分支：任务完成后自动删除工作分支
• 自动化脚本：在看板的生命周期中插入脚本

选项卡 3：组织设置

• 团队成员管理：邀请团队成员协作
• 权限配置：通过读取 git 可以配置不同成员的操作权限

选项卡 4：代理

这就是我们刚才配置的页面，用于管理 AI Agent 的配置。

选项卡 5：MCP 服务器

• MCP Server 配置：配置自定义的 MCP Server（我们会在博文 2 中详细讲解）
• 服务器状态：查看 MCP Server 的连接状态

1.5.4. 任务状态流转规则

任务在看板中的流转遵循以下规则：

状态 1：Todo → In Progress

当你点击任务卡片上的 “开始执行” 按钮时，Vibe Kanban 会：

1. 创建一个新的 Git 分支（如 feature/login）
2. 使用 Git Worktree 创建独立的工作目录
3. 启动选定的 AI Agent（如 Claude Code）
4. 将任务描述传递给 Agent

状态 2：In Progress → Review

当 Agent 完成工作后，Vibe Kanban 会：

1. 保存 Agent 生成的工件（代码、文档、测试）
2. 提交代码到工作分支
3. 将任务状态变更为 “Review”
4. 发送通知（如果启用了通知功能）

状态 3：Review → Done

当你审查代码并点击 “通过审查” 按钮后，Vibe Kanban 会：

1. 将工作分支合并到主分支
2. 删除工作目录（Git Worktree）
3. 将任务状态变更为 “Done”
4. 将工件存档到 .vibe/artifacts/ 目录

状态 4：Review → Todo（审查不通过）

如果你发现 Agent 生成的代码有问题，可以点击 “创建修复任务” 按钮。Vibe Kanban 会：

1. 创建一个新的任务（类型为 “Fix”）
2. 将原任务的工作分支和工件复制到新任务
3. 原任务状态保持为 “Review”（不会合并到主分支）
4. 新任务状态为 “Todo”，等待重新执行