平台支持状态（当前）

仅凭此技能是否足够：

• Claude/Gemini：是
• Codex：是（需要基于脚本的设置）
• OpenCode：是（通过编排）

Vibe Kanban — AI 代理看板

从一个统一的看板管理多个 AI 代理（Claude/Codex/Gemini）。
将卡片（任务）移动到“进行中”会自动创建一个 git 工作树并启动代理。

何时使用此技能

• 将大型任务分解为独立子任务，以便并行分配给多个代理时
• 当您想直观地跟踪正在进行的 AI 工作的状态时
• 当您想在界面中查看代理结果的差异/日志并重试它们时
• 当您将基于 GitHub PR 的团队协作与 AI 代理工作相结合时

前提条件

# 需要 Node.js 18+
node --version

# 事先完成代理的身份验证
claude --version    # 设置 ANTHROPIC_API_KEY
codex --version     # 设置 OPENAI_API_KEY（可选）
gemini --version    # 设置 GOOGLE_API_KEY（可选）
opencode --version  # 无需单独设置（基于 GUI）

已验证版本（截至 2026-02-22）

• vibe-kanban：v0.1.17
• claude (Claude Code)：2.1.50
• codex：0.104.0
• gemini：0.29.5
• opencode：1.2.10

安装与运行

npx（最快）

# 立即运行（无需安装）
npx vibe-kanban

# 指定端口（默认端口 3000）
npx vibe-kanban --port 3001

# 同时指定端口和环境变量
PORT=3001 npx vibe-kanban --port 3001

# 使用包装脚本
bash scripts/vibe-kanban-start.sh

浏览器会自动打开 http://localhost:3000。

⚠️ 端口冲突警告：如果另一个开发服务器（如 Next.js）正在使用端口 3000，
请运行 PORT=3001 npx vibe-kanban --port 3001。
确认启动日志中出现 Main server on :3001，然后访问 http://localhost:3001。

正常启动日志：

正在启动 vibe-kanban v0.1.17...
未找到用户配置文件 profiles.json，仅使用默认配置
以 60 秒的间隔启动 PR 监控服务
远程客户端已初始化，URL：https://api.vibekanban.com
主服务器在 :3001，预览代理在 :XXXXX
正在打开浏览器...

克隆 + 开发模式

git clone https://github.com/BloopAI/vibe-kanban.git
cd vibe-kanban
pnpm i
pnpm run dev

环境变量

在启动服务器前，将这些变量设置在 .env 文件中。

每个代理的 API 密钥位置（设置 → 代理 → 环境变量）

• Claude Code：ANTHROPIC_API_KEY
• Codex：OPENAI_API_KEY
• Gemini：GOOGLE_API_KEY
• Opencode：无需单独设置（内置认证）

MCP 配置

Vibe Kanban 作为一个 MCP（模型上下文协议）服务器运行，允许代理直接控制看板。

Claude Code MCP 设置

~/.claude/settings.json 或项目中的 .mcp.json：

{
  "mcpServers": {
    "vibe-kanban": {
      "command": "npx",
      "args": ["vibe-kanban", "--mcp"],
      "env": {
        "MCP_HOST": "127.0.0.1",
        "MCP_PORT": "3001"
      }
    }
  }
}

OpenCode MCP 设置

添加到 ~/.config/opencode/opencode.json：

{
  "mcp": {
    "vibe-kanban": {
      "command": "npx",
      "args": ["vibe-kanban", "--mcp"],
      "env": {
        "MCP_HOST": "127.0.0.1",
        "MCP_PORT": "3001"
      }
    }
  }
}

重启后，vk_* 工具将直接在您的 OpenCode 会话中可用。

MCP 工具列表

⚠️ 旧版本中的工具名称变更：vk_list_tasks → vk_list_cards，vk_create_task → vk_create_card
这些是根据 v0.1.17 实际 MCP API 确认的工具名称。

Codex MCP 集成

要将 Vibe Kanban 与 Codex 连接，请从您的项目根目录运行：

bash scripts/mcp-setup.sh --codex

此命令将 vibe-kanban MCP 服务器配置添加到 ~/.codex/config.toml。
基于钩子的自动循环不是 Codex 的默认行为，因此重试/循环管理通过看板卡片进度状态或更高级的编排器来处理。

工作区 → 并行代理 → PR 工作流

v0.1.17 实际 UI 结构：Vibe Kanban 是一个看板，但
实际的工作单元是一个工作区。
每个工作区独立处理一个任务。

1. 启动服务器

# 默认运行
npx vibe-kanban
# → http://localhost:3000

# 端口冲突（例如，Next.js）
PORT=3001 npx vibe-kanban --port 3001
# → http://localhost:3001

2.（可选）使用 planno 审查史诗计划

使用 planno 审查此功能的实施计划

planno（plannotator）是一个独立的技能——无需 Vibe Kanban 即可使用。

3. 创建工作区

1. 打开 UI → 点击 “+ 创建工作区” 或左侧边栏的 + 按钮
2. 选择仓库？ 屏幕：
   • 浏览 → 从文件系统中选择 git 仓库（支持手动输入路径）
   • 最近 → 之前使用过的仓库
   • 选择一个仓库，然后选择分支（默认：main）
   • 点击 继续
3. 你想做什么工作？ 屏幕：
   • 选择一个代理（Opencode, Claude Code, Codex, Gemini, Amp, Qwen Code, Copilot, Droid, Cursor Agent）
   • 输入任务描述（支持 Markdown）
   • 选择模式（默认、构建等）
   • 点击 创建

4. 自动代理执行

创建工作区时：

• 自动创建 vk/<哈希>-<别名> 分支（例如 vk/3816-add-a-comment-to）
• 自动创建 git 工作树（每个代理完全隔离）
• 选定的代理 CLI 运行，日志实时流式传输

工作区状态：

• 运行中：代理正在执行（左侧边栏）
• 空闲：等待
• 需要注意：代理已完成或需要输入

5. 审查结果

• 更改面板：查看文件差异
• 日志面板：代理执行日志
• 预览面板：Web 应用预览
• 终端：直接运行命令
• 笔记：写笔记

6. 创建 PR 并完成

• 工作区详情 → “打开拉取请求” 按钮
• PR 合并 → 工作区移至存档
• 工作树自动清理

Git 工作树隔离结构

工作区目录（可在设置 → 常规 → 工作区目录中配置）：

~/.vibe-kanban-workspaces/          ← 默认位置（位于用户主目录下）
├── <工作区-uuid-1>/             ← 工作区 1 的隔离环境
├── <工作区-uuid-2>/             ← 工作区 2 的隔离环境
└── <工作区-uuid-3>/             ← 工作区 3 的隔离环境

分支命名（可在设置 → 常规 → Git → 分支前缀中配置）：

vk/<4 字符 ID>-<任务别名>
例如：vk/3816-add-a-comment-to-readme

内部行为：

git worktree add <工作区目录> -b vk/<哈希>-<任务别名> main
<代理-cli> -p "<任务描述>" --cwd <工作区目录>

建议添加到 .gitignore 的条目：

.vibe-kanban-workspaces/
.vibe-kanban/

远程部署

Docker

# 官方镜像
docker run -p 3000:3000 vibekanban/vibe-kanban

# 传递环境变量
docker run -p 3000:3000 \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -e VK_ALLOWED_ORIGINS=https://vk.example.com \
  vibekanban/vibe-kanban

反向代理（Nginx/Caddy）

# 必须允许 CORS
VK_ALLOWED_ORIGINS=https://vk.example.com

# 或多个来源
VK_ALLOWED_ORIGINS=https://a.example.com,https://b.example.com

SSH 远程访问

与 VSCode Remote-SSH 集成：

vscode://vscode-remote/ssh-remote+user@host/path/to/.vk/trees/<任务别名>

故障排除

工作树冲突 / 孤立的工作树

# 清理孤立的工作树
git worktree prune

# 列出当前工作树
git worktree list

# 强制移除特定工作树
git worktree remove .vk/trees/<别名> --force

403 Forbidden（CORS 错误）

# 远程访问需要 CORS 配置
VK_ALLOWED_ORIGINS=https://your-domain.com npx vibe-kanban

代理无法启动

# 直接测试 CLI
claude --version
codex --version

# 检查 API 密钥
echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY

端口冲突

# 使用不同的端口
npx vibe-kanban --port 3001

# 或使用环境变量
PORT=3001 npx vibe-kanban

SQLite 锁定错误

# 禁用工作树清理并重启
DISABLE_WORKTREE_CLEANUP=1 npx vibe-kanban

界面 vs CLI 决策指南

支持的代理（已验证 v0.1.17）

在设置 → 代理中配置每个代理：

每个代理的可配置项：

• 追加提示词：在代理运行时追加的额外指令
• 模型：要使用的模型名称（例如 claude-opus-4-6）
• 变体：模型变体
• 自动批准：自动批准代理操作（默认：开启）
• 自动压缩：自动压缩上下文（默认：开启）
• 环境变量：API 密钥和其他环境变量

代表性用例

1. 并行分解大型任务

"支付流程 v2" 大型任务
  ├── 工作区 1：前端界面  → Claude Code
  ├── 工作区 2：后端 API  → Codex
  └── 工作区 3：集成测试 → Opencode
→ 3 个工作区同时运行 → 并行实现

2. 基于角色的专家代理分配

Claude Code  → 设计/领域密集型功能
Codex        → 类型/测试/重构
Gemini       → 文档/故事撰写
Opencode     → 通用任务（默认）

3. 基于 GitHub PR 的团队协作

设置 VIBE_KANBAN_REMOTE=true
→ 团队成员在看板上查看状态
→ 仅通过 GitHub PR 进行审查/批准
→ 并行代理 + 传统 PR 流程相结合

4. 实现方案对比

同一个任务，两个工作区：
  工作区 A → Claude Code（关注 UI 结构）
  工作区 B → Codex（关注性能优化）
→ 比较 PR，取两者之长

5. OpenCode + ulw 并行委托

与 OpenCode 的 ulw（ultrawork）模式结合，在任务级别并行运行代理：

# ulw 关键字 → 激活 ultrawork 并行执行层
# Vibe Kanban 看板：npx vibe-kanban（在单独的终端中运行）

task(category="视觉工程", run_in_background=True,
     load_skills=["前端界面-用户体验", "vibe-kanban"],
     description="[看板 WS1] 前端界面",
     prompt="实现支付流程界面 — 在 src/components/payment/ 中创建卡片输入、订单确认和完成屏幕")

task(category="未指定-高", run_in_background=True,
     load_skills=["vibe-kanban"],
     description="[看板 WS2] 后端 API",
     prompt="实现支付流程 API — POST /charge, POST /refund, GET /status/:id")

task(category="未指定-低", run_in_background=True,
     load_skills=["vibe-kanban"],
     description="[看板 WS3] 集成测试",
     prompt="编写支付流程端到端测试 — 成功/失败/退款场景")

# → 3 个工作区同时出现在看板的"运行中"状态
# → 每个完成时：需要注意 → 创建 PR → 存档

提示与技巧

• 保持卡片范围狭窄（1 张卡片 = 1 次提交单位）
• 对于涉及 2 个以上文件的更改，先用 planno 审查计划
• 仅在受信任的网络上使用 VIBE_KANBAN_REMOTE=true
• 如果代理停滞不前，重新分配或拆分卡片

架构概览

┌─────────────────────────────────────────────────────────┐
│                    Vibe Kanban 用户界面                  │
│   ┌──────────┬──────────┬──────────┬──────────┐        │
│   │  待办    │  进行中  │  审查中  │  已完成  │        │
│   └──────────┴──────────┴──────────┴──────────┘        │
└───────────────────────────┬─────────────────────────────┘
                            │ REST API
┌───────────────────────────▼─────────────────────────────┐
│                    Rust 后端                            │
│  ┌─────────┐  ┌──────────┐  ┌─────────┐  ┌──────────┐  │
│  │ server  │  │executors │  │   git   │  │ services │  │
│  └─────────┘  └──────────┘  └─────────┘  └──────────┘  │
│                   │                                     │
│             ┌─────▼─────┐                               │
│             │  SQLite   │                               │
│             └───────────┘                               │
└─────────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
   ┌────▼────┐        ┌─────▼─────┐       ┌────▼────┐
   │ Claude  │        │   Codex   │       │ Gemini  │
   │工作树1  │        │ 工作树2   │       │工作树3  │
   └─────────┘        └───────────┘       └─────────┘

参考链接

• GitHub 仓库：BloopAI/vibe-kanban
• 官方落地页：vibekanban.com
• 架构分析：vibe-kanban – 面向 AI 代理的看板
• 采用故事
• 演示：无 Git 冲突地运行多个 Claude Code 代理
• 演示：Claude Code 变得更好了 | 自动 Claude 看板

技能文件结构

.agent-skills/vibe-kanban/
├── SKILL.md              # 主技能文档
├── SKILL.toon            # TOON 格式（压缩版）
├── scripts/
│   ├── start.sh          # 服务器启动包装器
│   ├── cleanup.sh        # 工作树清理
│   ├── mcp-setup.sh      # MCP 设置自动化
│   └── health-check.sh   # 服务器健康检查
├── references/
│   ├── environment-variables.md  # 环境变量参考
│   └── mcp-api.md                # MCP API 参考
└── templates/
    ├── claude-mcp-config.json    # Claude Code MCP 配置
    ├── docker-compose.yml        # Docker 部署模板
    └── .env.example              # 环境变量示例

脚本用法

# 启动服务器
bash scripts/start.sh --port 3001

# 工作树清理
bash scripts/cleanup.sh --dry-run  # 预览
bash scripts/cleanup.sh --all       # 移除所有 VK 工作树

# MCP 设置
bash scripts/mcp-setup.sh --claude  # Claude Code 设置
bash scripts/mcp-setup.sh --all     # 为所有代理设置

# 健康检查
bash scripts/health-check.sh
bash scripts/health-check.sh --json  # JSON 输出

快速参考

=== 启动服务器 ===
npx vibe-kanban                       立即运行（端口 3000）
PORT=3001 npx vibe-kanban --port 3001 端口冲突（例如 Next.js）
http://localhost:3000                  看板界面

=== 环境变量 ===
PORT=3001                        更改端口
VK_ALLOWED_ORIGINS=https://...   允许 CORS
ANTHROPIC_API_KEY=...            Claude Code 认证
OPENAI_API_KEY=...               Codex 认证
GOOGLE_API_KEY=...               Gemini 认证

=== MCP 集成 ===
npx vibe-kanban --mcp            MCP 模式
vk_list_cards                    列出卡片（工作区）
vk_create_card                   创建卡片
vk_move_card                     更改状态

=== 工作区流程 ===
创建 → 运行中 → 需要注意 → 存档
运行中：工作树已创建 + 代理已启动
需要注意：已完成或需要输入
存档：PR 合并完成

=== MCP 配置文件位置 ===
Opencode：~/.config/opencode/opencode.json
Claude Code：~/.claude/settings.json 或 .mcp.json

=== 工作树清理 ===
git worktree prune               清理孤立工作树
git worktree list                列出所有
git worktree remove <路径>       强制移除