◆ 中级难度 ⏱ 预计 25 分钟 📋 前置: 终端基础, Node.js 活跃维护

Vibe Kanban
AI 编码代理任务编排平台

掌握多 AI 编码代理（Claude Code, Gemini CLI, Codex）的并行协作，实现 10 倍开发效率提升

学习目标 #

✓
理解 Vibe Kanban 核心价值
掌握为什么需要 AI 代理编排工具，以及它如何改变开发工作流
✓
配置多代理环境
学会设置 Claude Code、Gemini CLI、Codex 等代理并进行身份验证
✓
执行并行与顺序任务
掌握任务分配策略，让多个 AI 代理协同工作
✓
配置 MCP 和远程部署
理解 Model Context Protocol 集中配置与 SSH 远程访问机制

TL;DR 核心摘要 #

30 秒了解 Vibe Kanban

Vibe Kanban 是一个任务编排平台，让你能够同时管理多个 AI 编码代理（如 Claude Code、Gemini CLI、Codex）。通过看板界面，你可以将编码任务分配给不同代理并行执行，实时监控进度，并统一管理 MCP 配置。一条命令 npx vibe-kanban 即可启动，支持本地和远程（SSH）部署。

概念图 #

基础知识 #

先决条件

📦

Node.js v18+

运行 npx 命令和前端构建所需的 JavaScript 运行时环境

🔐

代理身份验证

需要预先完成 Claude Code / Gemini CLI / Codex 的登录认证

💻

终端基础

熟悉命令行操作，能够执行 npm/npx 命令

关键术语

AI Coding Agent

能够理解自然语言指令并生成、修改代码的 AI 工具，如 Claude Code

MCP (Model Context Protocol)

模型上下文协议，用于 AI 代理与外部工具、数据源交互的标准化协议

Task Orchestration

任务编排，协调多个代理执行复杂工作流的过程

Worktree

Git 工作树，允许同一仓库同时检出多个分支的功能

常见误区

❌ 误区

"Vibe Kanban 是另一个 AI 代理"

错误。Vibe Kanban 本身不是 AI，而是管理和编排现有 AI 代理的工具层。

✓ 正确理解

"Vibe Kanban 是代理的调度器"

它类似于 Kubernetes 调度容器，Vibe Kanban 调度 AI 代理执行任务。

详细讲解 #

显示模式: 基础完整

核心架构

WHY 为什么需要

当你同时使用多个 AI 代理时，手动切换窗口、复制粘贴上下文、跟踪各自进度会产生巨大的认知负担。Vibe Kanban 通过统一界面消除这些摩擦，让你专注于任务本身。

HOW 如何工作

Vibe Kanban 使用 Rust 后端处理代理进程管理和任务调度，TypeScript/React 前端提供看板界面。通过 WebSocket 实现实时状态同步。

WHEN 适用场景

• 需要并行处理多个独立功能模块
• 希望让不同代理处理各自擅长的任务
• 远程服务器上运行代理并本地监控

深入了解: Rust 后端选型原因

Rust 提供了：

内存安全保证，适合长时间运行的服务
优秀的并发原语（async/await）
低资源占用，适合 CLI 工具
与 Node.js 进程的高效 IPC

architecture.txt

┌─────────────────────────────────────────┐
│           Vibe Kanban UI               │
│         (React + TypeScript)            │
└────────────────┬────────────────────────┘
                 │ WebSocket
                 ▼
┌─────────────────────────────────────────┐
│           Rust Backend                 │
│  ┌──────────┬──────────┬──────────┐    │
│  │ Task     │ Agent    │ MCP      │    │
│  │ Scheduler│ Manager  │ Router   │    │
│  └────┬─────┴────┬─────┴────┬─────┘    │
└───────┼──────────┼──────────┼──────────┘
        │          │          │
   ┌────▼───┐ ┌────▼───┐ ┌────▼───┐
   │Claude  │ │Gemini │ │Codex  │
   │ Code   │ │ CLI    │ │ CLI    │
   └────────┘ └────────┘ └────────┘

? 检查点: Vibe Kanban 后端使用什么语言构建？

Python
Rust
Go

正确！Vibe Kanban 使用 Rust（占代码库 57.9%）构建后端，利用其内存安全和并发优势。

反模式 vs 最佳实践 #

❌ 反模式: 串行阻塞

# 低效：一个接一个等待
task1 = claude.run("写登录页")
await task1  # 等待完成
task2 = gemini.run("写样式")
await task2  # 再等待
# 总时间 = task1 + task2
                            

问题: 独立任务不应该相互等待，浪费时间。

✓ 最佳实践: 并行执行

# 高效：并行启动
task1 = claude.run("写登录逻辑")
task2 = gemini.run("写登录样式")
await Promise.all([task1, task2])
# 总时间 = max(task1, task2)
                            

优势: 独立任务并行执行，总时间取决于最长任务。

❌ 反模式: 无验证直接执行

直接让代理修改生产代码，不审查不测试。

风险: AI 可能引入 bug、安全漏洞或破坏现有功能。

✓ 最佳实践: 分支隔离 + 审查

使用 Git Worktree 在独立分支工作，完成后 Code Review。

优势: 变更可追溯、可回滚、可审计。

完整示例 #

场景首次启动 Vibe Kanban，快速体验基础功能

前提已安装 Node.js v18+，已认证至少一个 AI 代理

预期结果 打开浏览器看板界面，可创建和分配任务

逐步操作

验证 Node.js 版本 WHY: Vibe Kanban 需要 Node.js 18+ 的 ES 模块支持
确认代理认证状态 WHY: 没有认证的代理将无法执行任务
启动 Vibe Kanban WHY: npx 自动下载最新版本，无需全局安装
访问 Web 界面 WHY: 默认在 localhost:3000 启动前端服务

Terminal — zsh

$ node --version

v20.10.0

$ claude --version

claude-code v1.0.42

$ npx vibe-kanban

🚀 Starting Vibe Kanban...

📦 Checking for updates...

✓ Server running at http://localhost:3000

✓ Detected agents: claude-code, gemini

变体: 指定端口

bash

# 自定义端口启动
PORT=8080 npx vibe-kanban

# 分别指定前后端端口
FRONTEND_PORT=3001 BACKEND_PORT=4000 npx vibe-kanban

场景处理代理超时、网络断开、无效输入等异常

前提 Vibe Kanban 已启动，任务执行中遇到问题

预期结果 优雅处理异常，提供清晰错误信息

场景 1: 代理认证过期

Terminal — Error State

$ npx vibe-kanban

⚠ Warning: claude-code authentication expired

→ Run 'claude login' to re-authenticate

✓ Continuing with available agents: gemini, codex

处理方式: Vibe Kanban 会自动降级，仅使用可用代理继续运行。你可以在另一个终端重新认证，无需重启服务。

场景 2: 任务执行超时

处理策略

// Vibe Kanban 内置超时处理
{
  "task": "实现复杂算法",
  "agent": "claude-code",
  "timeout": 300000, // 5分钟
  "on_timeout": "retry_once" // 可选: fail, retry_once, notify
}
                            

场景 3: Git 工作树冲突

当多个代理同时修改相同文件时:

Terminal — Conflict Resolution

⚠ Conflict detected in src/auth.ts

Agent 1 (claude): Modified lines 42-58

Agent 2 (gemini): Modified lines 50-65

→ Actions: [M]erge manual | [K]eep first | [R]erun second

场景远程服务器部署 + SSH 访问 + MCP 配置

前提有可 SSH 访问的远程服务器，已配置 VSCode Remote-SSH

预期结果 本地浏览器访问远程 Vibe Kanban，可在远程编辑器打开文件

远程部署步骤

在远程服务器启动 Vibe Kanban WHY: 利用远程服务器的计算资源和 GPU
使用 Tunnel 暴露 Web UI WHY: 安全地将内网服务暴露给本地浏览器
配置 SSH 远程编辑器集成 WHY: 让 "Open in Editor" 功能直接打开远程 VSCode

remote-setup.sh

# 1. 在远程服务器 (SSH 进入后执行)
HOST="0.0.0.0" npx vibe-kanban

# 2. 设置 Cloudflare Tunnel (另一个终端)
cloudflared tunnel --url http://localhost:3000

# 输出类似: https://random-name.trycloudflare.com

# 3. 在 Vibe Kanban Settings 中配置:
#    - Remote SSH Host: your-server.com
#    - SSH User: ubuntu (可选)
#    - Editor: vscode-remote

MCP 集中配置

mcp-config.json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-filesystem", "/workspace"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

注意: MCP 配置一次设置后，所有代理共享。无需在每个代理中重复配置。

场景任务失败后的诊断与恢复策略

前提任务执行失败，需要排查原因

预期结果 识别失败原因，成功重试或降级处理

常见错误与恢复

ECONNREFUSED 代理连接失败

原因: 代理进程未运行或端口被占用

恢复:

$ lsof -i :3001 # 检查端口占用

$ pkill -f "claude" # 强制终止残留进程

$ npx vibe-kanban # 重新启动

RATE_LIMIT_EXCEEDED API 限流

原因: AI 代理 API 调用超出配额

恢复策略:

自动退避: Vibe Kanban 会指数退避重试
任务分流: 将任务分配给未限流的代理
等待重置: 查看 API 配额重置时间

WORKTREE_LOCKED Git 工作树锁定

原因: 之前的操作未正常结束，留下锁文件

恢复:

$ rm -f .git/worktrees/*/locked

$ git worktree prune

或设置环境变量跳过清理: DISABLE_WORKTREE_ORPHAN_CLEANUP=1

失败注入测试

test-resilience.sh

# 模拟网络故障
SIMULATE_NETWORK_FAILURE=1 npx vibe-kanban

# 模拟代理崩溃
SIMULATE_AGENT_CRASH="claude" npx vibe-kanban

# 验证恢复行为
# 预期: 自动重试 → 降级到其他代理 → 通知用户

术语词汇表 #

Orchestration

编排。协调多个组件或服务协同工作的过程，类似于交响乐指挥。

Kanban

看板。源自日语，一种可视化工作流管理方法，通过卡片追踪任务状态。

MCP

Model Context Protocol。Anthropic 提出的标准协议，让 AI 模型与外部工具交互。

Worktree

Git 工作树。允许同一仓库同时检出多个分支到不同目录，便于并行开发。

Agent

代理。这里特指能够自主执行编码任务的 AI 助手，如 Claude Code。

WebSocket

双向通信协议。允许服务器主动推送数据，实现实时状态更新。

故障排除 #

症状 / 错误	原因	解决方案
`No agents detected`	未安装或未认证任何 AI 代理	运行 `claude login` 或 `gemini auth login`
`Port already in use`	3000 端口被其他进程占用	使用 `PORT=8080 npx vibe-kanban` 指定其他端口
`SQLITE_BUSY`	数据库被其他 Vibe Kanban 实例锁定	关闭其他实例，或删除 `~/.vibe-kanban/db.sqlite-lock`
UI 加载空白	前端资源未正确构建	清除缓存: `npx vibe-kanban --clear-cache`
远程编辑器不打开	SSH 配置不正确或 VSCode Remote-SSH 未安装	检查 Settings → Editor Integration 配置，确保 SSH 密钥免密登录

速查表 #

🚀 启动命令

npx vibe-kanban 快速启动

PORT=8080 npx vibe-kanban 指定端口

HOST=0.0.0.0 npx vibe-kanban 远程访问

🔧 环境变量

FRONTEND_PORT 前端端口 (默认 3000)

BACKEND_PORT 后端端口 (默认 auto)

POSTHOG_API_KEY 分析 API 密钥

🔐 代理认证

claude login Claude Code

gemini auth login Gemini CLI

codex auth Codex CLI

🛠️ 开发命令

pnpm run dev 开发模式

pnpm build 构建前端

cargo watch -x run 后端热重载

行动步骤 #

🚀 快速开始

安装 Node.js v18 或更高版本
运行 claude login 完成认证
执行 npx vibe-kanban
打开 http://localhost:3000
创建第一个任务并分配给代理