第二章. Vibe KanBan 项目管理

2.1. Vibe Kanban 的数据存储与 Git Worktree 原理

在创建项目之前，我们需要理解 Vibe Kanban 如何存储数据，以及它如何通过 Git Worktree 实现任务隔离。

2.1.1. Vibe Kanban 的应用数据目录

Vibe Kanban 将所有数据存储在操作系统的应用数据目录中，而不是你的项目目录。这个设计有两个好处：

好处 1：不污染项目代码
你的 Git 仓库中不会出现 Vibe Kanban 的配置文件，保持代码仓库的干净。

好处 2：跨项目共享配置
Agent 配置、Task Tags 等全局设置可以在所有项目中复用。

应用数据目录的位置：

在 Windows 上，完整路径通常是：

1

C:\Users\YourName\AppData\Roaming\bloop\vibe-kanban\

步骤 1：查看应用数据目录

我们需要直接访问文件资源管理器来查看 Vibe Kanban 的底层数据存储结构。在地址栏输入以下路径即可进入应用数据目录：

1

%APPDATA%\bloop\vibe-kanban\

该目录下的实际文件结构如下所示：

1
2
3
4
5

vibe-kanban/
├── config.json 应用全局配置
├── credentials.json 保存用户认证与授权相关的加密数据
├── db.sqlite 用于存储项目、任务详情、工件以及执行历史记录。重置应用时删除数据目录即会清空此数据库。
└── profiles.json 高级用户可直接修改此文件进行自定义配置，系统会保留用户的覆盖设置。

2.1.2. Git Worktree 的核心机制

Vibe Kanban 利用 Git Worktree 为每个任务尝试（Attempt）创建一个完全隔离的执行环境。这是实现安全 AI 执行和并行处理的基石。

Git Worktree 的定义

Git Worktree 允许我们在同一个仓库中，将不同的分支检出到独立的文件夹中。这与传统的 git checkout 切换分支不同，后者会修改当前工作目录的文件状态。

Vibe Kanban 中的执行流程

当我们开始一个任务时，系统会自动协调以下步骤：

1. 环境创建：基于指定的 Base Branch 创建一个临时的 Git Worktree。
2. 文件准备：如果配置了 Copy Files，系统会将 .env 等被 gitignore 的文件从主目录复制到 Worktree 中。
3. 环境初始化：运行配置好的 Setup Scripts（如 npm install），因为 Worktree 默认不包含依赖包。
4. Agent 执行：Agent 在这个隔离的环境中读取代码、思考并执行修改。
5. 自动清理：任务结束后（无论成功与否），该临时 Worktree 会被自动删除。

Worktree 带来的优势

关键注意事项：环境隔离

由于 Worktree 是一个全新的检出（Checkout），它 不包含 我们主工作区中被 .gitignore 忽略的文件（例如 node_modules、.env、build/ 目录）。

因此，在项目设置中配置以下两项至关重要：

• Setup Scripts：用于重新安装依赖（如 npm install、cargo build）。
• Copy Files：用于将必要的环境配置文件从主项目复制到任务的 Worktree 中。

2.1.3. 理解项目、仓库、任务的关系

在 Vibe Kanban 中，有三个核心概念：

概念 1：项目（Project）

• 一个项目可以包含一个或多个 Git 仓库
• 项目是任务的容器
• 项目配置包括：Setup Scripts、Dev Server Scripts、Cleanup Scripts

概念 2：仓库（Repository）

• 一个 Git 仓库对应一个代码库
• 每个仓库有自己的 Base Branch（如 main 或 develop）
• 任务执行时可以选择在哪个仓库中工作

概念 3：任务（Task）

• 任务是最小的工作单元
• 每个任务对应一个 Git 分支和一个 Worktree
• 任务可以有多个尝试（Task Attempts）

关系图：

实际场景举例：

假设你正在开发一个前后端分离的电商系统：

项目配置：

• 项目名称：电商系统
• 仓库 1：frontend（React 项目，Base Branch: main）
• 仓库 2：backend（Node.js 项目，Base Branch: develop）

任务 1：实现商品列表页

• 目标仓库：frontend
• 任务分支：feature/product-list
• Worktree 路径：frontend-worktrees/task-1-product-list/
• 执行 Agent：Gemini（擅长前端）

任务 2：实现商品查询 API

• 目标仓库：backend
• 任务分支：feature/product-api
• Worktree 路径：backend-worktrees/task-2-product-api/
• 执行 Agent：Claude Code（擅长后端）

当我们给定了统一的规范文档后，两个任务可以同时执行，互不干扰。

2.2. 创建你的第一个项目

在掌握了 Vibe Kanban 的数据存储与隔离机制后，我们将进入实际操作阶段。本节将演示如何基于标准的 React 技术栈创建一个新项目，并完成关键的自动化脚本配置。

2.2.1. 从现有 Git 仓库创建项目

Vibe Kanban 支持 “From existing git repository”（从现有仓库）和 “Create blank project”（创建空白项目）两种模式。为了演示完整的开发流程，我们将使用 Vite 脚手架初始化一个 React 项目，并将其导入 Vibe Kanban。

步骤 1：初始化标准 Git 仓库

我们将使用 pnpm 和 vite 创建一个名为 vibe-kanban-demo 的项目，模拟真实的开发环境。

1
2
3
4
5
6
7
8
9
10
11
12
13

# 使用 pnpm 创建 vite 项目 (React + TypeScript)
pnpm create vite vibe-kanban-demo --template react-ts

# 进入项目目录
cd vibe-kanban-demo

# 安装依赖
pnpm install

# 初始化 Git 仓库并提交初始代码
git init
git add .
git commit -m "feat: init project with vite and react"

步骤 2：导入项目至 Vibe Kanban

启动 Vibe Kanban 后，在主界面点击右上角的 “Create Project” 按钮，选择 “From existing git repository”。

步骤 3：选择目标仓库

系统会自动扫描包含 .git 的目录。在列表中找到并选中 vibe-kanban-demo。

步骤 4：配置项目元数据

选中仓库后，需确认项目的基本信息：

点击 “Create” 完成创建，系统将自动跳转至项目看板。

2.2.2. 配置项目脚本：Setup、Dev Server、Cleanup

项目创建仅是第一步，为了让 AI Agent 能在隔离的 Worktree 中正常工作，我们需要配置自动化脚本。点击看板右上角的 设置图标 (⚙️) 进入配置页。

Vibe Kanban 的自动化流程主要依赖以下三类脚本：

2.2.3. Setup Scripts：依赖安装与环境准备

由于 Vibe Kanban 使用 Git Worktree 隔离任务，新创建的 Worktree 目录是纯净的，不包含 node_modules 等被 .gitignore 忽略的文件。因此，必须通过 Setup Scripts 重新构建运行环境。

配置原则：脚本应包含项目运行所需的所有前置命令。对于我们的 React 项目，主要是安装依赖。

脚本配置示例：

在 “Setup Scripts” 区域输入以下命令：

1
2
3

# 使用 pnpm 安装项目依赖
# 提示：pnpm 的存储机制比 npm 更适合多 Worktree 环境，能显著节省磁盘空间
pnpm install

性能提示：
Setup Scripts 会在每次创建任务尝试（Attempt）时运行。请确保脚本尽可能高效，避免执行耗时过长的非必要构建任务，以免拖慢 Agent 的启动速度。

2.2.4. Dev Server Scripts：本地开发服务器配置

Dev Server Scripts 允许我们在 Vibe Kanban 界面中直接启动应用，以便实时预览 Agent 的修改成果。

配置原则：脚本应启动一个可访问的本地服务器。Vibe Kanban 会捕获该进程的输出并在界面中提供访问链接。

脚本配置示例：

在 “Dev Server Scripts” 区域配置 Vite 的启动命令：

1
2

# 启动开发服务器
pnpm run dev

使用方式：配置生效后，在任务详情页点击 “Start Dev Server”。系统将执行该脚本，你可以在内置的日志面板中查看输出，并通过链接在浏览器中打开应用。

2.2.5. Cleanup Scripts：代码格式化与质量检查

Cleanup Scripts 充当了类似 Git Pre-commit Hook 的角色。当 Agent 完成编码工作后，系统会自动运行这些脚本来确保代码质量符合规范。

配置原则：通常用于执行代码格式化（Formatter）和静态分析（Linter）。如果脚本执行失败（例如测试未通过），并不会阻止任务提交，但会在日志中通过报错提醒开发者。

脚本配置示例：

在 “Cleanup Scripts” 区域输入以下命令，由于我们生成的项目没有配置格式化和 lint 检测，这里只做命令的展示：

1
2
3
4
5
6
7
8

# 1. 自动格式化代码，确保 Agent 生成的代码风格统一
pnpm run format

# 2. 运行 Lint 检查并尝试自动修复简单问题
pnpm run lint:fix

# 3. (可选) 运行单元测试，确保修改没有破坏现有功能
# pnpm test

2.2.6. Copy Files：环境变量与配置文件的跨 Worktree 复制

Copy Files 是解决 Worktree 隔离性问题的关键功能。它允许将主项目目录下的特定文件（通常是被 Git 忽略的敏感配置）自动复制到每个新创建的任务 Worktree 中。

执行流程：

配置原则：仅列出项目运行必须、但未提交到 Git 的文件。支持具体文件名或通配符。

常见配置场景：

配置示例：

在 “Copy Files” 输入框中填写（多文件用逗号分隔）：

1

.env, .env.local, config/local.json

安全警告：请务必确保 Copy Files 中指定的文件（如 .env）已被包含在项目的 .gitignore 中。否则，Agent 可能会意外地将这些包含敏感信息的文件提交到代码仓库。

2.2.7. 保存项目配置

完成上述配置后，点击底部的 “Save” 按钮保存。此时，你的项目已经具备了自动化执行环境，Agent 可以从一个配置完善的 Worktree 开始工作，无需担心环境缺失问题。

2.3. 多仓库项目管理：前后端分离与 Monorepo

在现代全栈开发中，代码组织形式通常分为两种主流模式：

• 多仓库模式（Multi-repo）：前端 frontend 和后端 backend 分别存储在独立的 Git 仓库中，物理隔离。
• 单仓库模式（Monorepo）：一个 Git 仓库包含所有子项目（packages/frontend, packages/backend），代码共享更紧密。

Vibe Kanban 能够完美支持这两种模式，但配置策略略有不同。

2.3.1. 策略一：管理多仓库项目（前后端分离）

在多仓库架构下，由于 Vibe Kanban 的每个 Project 实体绑定一个 Git Repository，我们需要分别为前端和后端创建独立的 Vibe 项目。这种方式能确保两个环境的依赖（node_modules vs venv）和开发服务器彻底隔离。

步骤 1：准备后端仓库

假设我们完成了 2.2 节的前端项目创建，现在需要模拟一个独立的后端服务仓库。我们将创建一个基于 Express 的简单服务。

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 创建 backend 目录
mkdir backend-service
cd backend-service

# 初始化 Git 仓库
git init
echo "# Backend Service API" > README.md

# 初始化 package.json (模拟真实环境)
pnpm init

git add .
git commit -m "feat: init backend service"

步骤 2：创建后端专属项目

在 Vibe Kanban 界面，再次点击 “Create Project”，重复创建流程：

1. 选择 “From existing git repository”。
2. 选中刚才创建的 backend-service 目录。
3. 配置项目信息：

点击 “Create” 后，你将拥有两个并行的 Vibe 项目。

步骤 3：项目列表管理

此时，你的 Vibe Kanban 工作空间中并存了两个项目。你可以通过点击左上角的项目名称或侧边栏的主页图标，在项目列表中查看它们：

2.3.2. 策略二：Monorepo 项目配置

如果你的团队采用 Monorepo 架构（如使用 pnpm workspace 或 Nx），Vibe Kanban 的配置会更加简单且高效，因为你只需要创建一个 Vibe 项目。

步骤 1：导入 Monorepo 根目录

直接将包含 pnpm-workspace.yaml 或 lerna.json 的根目录作为 Vibe 项目导入。

步骤 2：配置统一的 Setup Scripts

在 Monorepo 中，通常需要在根目录安装所有子包的依赖。

1
2

# 在根目录安装所有 workspace 的依赖
pnpm install

步骤 3：通过任务描述控制修改范围

由于 Agent 可以访问整个 Monorepo 的代码，你需要在创建任务时，明确指定 Agent 应该工作的子目录（Package）。

任务提示词技巧：

Monorepo 的优势：在 Monorepo 模式下，Agent 可以同时修改前端和后端代码（例如一次性修改共享的 TypeScript 类型定义），并在同一个 Git Commit 中提交。这对于全栈开发者来说是非常强大的功能。