项目概述

Vibe Kanban 是一款专为软件工程师设计的协作工具，旨在优化编码代理（coding agents）的规划与代码审查流程。在现代软件开发中，工程师们花费大量时间在规划任务和审查代码上，Vibe Kanban 通过提供高效的看板式任务管理和流畅的编码代理执行环境，帮助团队显著提升交付效率。

资料来源：README.md

核心功能

Vibe Kanban 提供了完整的软件开发工作流支持，主要包括以下功能模块：

资料来源：README.md

支持的编码代理

Vibe Kanban 原生支持多种主流编码代理工具，满足不同开发团队的偏好：

资料来源：README.md

技术架构

Vibe Kanban 采用多包 monorepo 架构，主要由前端组件库、后端服务和 CLI 工具组成。

项目结构概览

graph TD
    A[vibe-kanban] --> B[packages/web-core]
    A --> C[packages/ui]
    A --> D[packages/remote-web]
    A --> E[crates/server]
    A --> F[npx-cli]
    
    B -->|React 组件| C
    C -->|UI 组件| D
    D -->|远程 Web| E
    F -->|CLI 入口| E

核心包说明

资料来源：package.json

状态管理

应用使用 Zustand 进行状态管理，主要 store 包括：

• useUiPreferencesStore - UI 偏好设置和布局模式管理
• useWorkspaceDiffStore - 工作区差异和 GitHub 评论数据
• useOrganizationStore - 组织相关状态

资料来源：packages/web-core/src/shared/stores/useUiPreferencesStore.ts

安装指南

前置要求

在安装 Vibe Kanban 之前，请确保已完成以下准备工作：

1. Node.js 环境：建议使用 Node.js 18.x 或更高版本
2. 编码代理认证：完成您选择的编码代理的身份验证配置
3. 包管理器：npm、pnpm 或 yarn 任选其一

安装方式

Vibe Kanban 提供多种安装和运行方式，最简捷的方式是通过 npx 直接运行：

npx vibe-kanban

此命令会自动下载并执行最新版本的 Vibe Kanban CLI。

资料来源：README.md

从源码构建

如需从源码构建和运行，请按以下步骤操作：

# 克隆仓库
git clone https://github.com/BloopAI/vibe-kanban.git
cd vibe-kanban

# 安装依赖
npm install

# 启动开发服务器
npm run dev

资料来源：npx-cli/package.json

快速开始

基本工作流

graph LR
    A[创建看板任务] --> B[分配给工作区]
    B --> C[启动编码代理]
    C --> D[代理执行任务]
    D --> E[审查代码差异]
    E --> F[发送反馈评论]
    F -->|需要修改| D
    F -->|审核通过| G[创建 Pull Request]
    G --> H[合并代码]

创建新工作区

1. 打开 Vibe Kanban 应用
2. 选择项目或创建新项目
3. 点击"创建新工作区"按钮
4. 选择编码代理和配置文件
5. 描述工作任务，代理开始执行

资料来源：packages/web-core/src/shared/dialogs/command-bar/WorkspaceSelectionDialog.tsx

键盘快捷键

资料来源：packages/web-core/src/shared/keyboard/useWorkspaceShortcuts.ts

自托管部署

如需在自有基础设施上部署 Vibe Kanban Cloud 实例，可使用 Docker 进行部署。

详细部署指南请参阅官方文档：https://vibekanban.com/docs/self-hosting/deploy-docker

资料来源：README.md

认证与集成

GitHub OAuth 集成

Vibe Kanban 支持通过 GitHub CLI 进行 OAuth 认证。认证成功后，应用会返回包含 Base64 编码应用图标的 HTML 响应：

Response::builder()
    .status(StatusCode::OK)
    .header("content-type", "text/html; charset=utf-8")
    .body(body)
    .unwrap()

资料来源：crates/server/src/routes/oauth.rs

GitHub CLI 设置

GitHub CLI 集成需要执行以下设置步骤：

1. 检查 gh CLI 是否已安装
2. 安装 Homebrew（如果需要）
3. 完成 GitHub 身份验证

资料来源：packages/web-core/src/shared/dialogs/auth/GhCliSetupDialog.tsx

相关资源

支持与反馈

• 功能请求：请通过 GitHub Discussions 提出
• Bug 报告：请在 GitHub Issues 中提交
• 社区交流：加入 Discord 服务器参与讨论

建议在提出新想法或变更之前，先与核心团队通过 GitHub Discussions 或 Discord 沟通，以确保实现方案与现有路线图保持一致。

资料来源：README.md

1. 项目简介

Vibe Kanban 是一个面向软件工程师的代码规划与审核平台，旨在通过看板式任务管理和 AI 编程代理工作区集成，显著提升软件交付效率。该项目采用 monorepo 结构，核心代码使用 TypeScript/React 构建前端界面，Rust 构建后端服务。

项目官方公告：Vibe Kanban 正在进行 sunsetting（停止运营），详情见 官方公告。资料来源：README.md

2. 整体架构

2.1 架构分层

graph TD
    subgraph 前端层["前端层 (packages/)"]
        UI["UI 组件库<br/>packages/ui"]
        WebCore["Web 核心模块<br/>packages/web-core"]
        LocalWeb["本地 Web 应用<br/>packages/local-web"]
        RemoteWeb["远程 Web 应用<br/>packages/remote-web"]
    end
    
    subgraph 核心服务层["核心服务层 (crates/)"]
        Server["后端服务<br/>crates/server"]
        Remote["远程通信<br/>crates/remote"]
        Executors["执行器引擎<br/>crates/executors"]
    end
    
    subgraph 共享层["共享基础设施"]
        DB[("数据库")]
        Auth["认证系统"]
    end
    
    UI --> WebCore
    LocalWeb --> WebCore
    RemoteWeb --> WebCore
    WebCore --> Server
    WebCore --> Remote
    Server --> Executors
    Server --> DB
    Server --> Auth

2.2 Monorepo 包结构

资料来源：packages/ui/src/components/WorkspacesSidebar.tsx 资料来源：packages/web-core/src/shared/dialogs/command-bar/ForcePushDialog.tsx 资料来源：crates/server/src/routes/oauth.rs

3. 前端架构

3.1 状态管理

前端采用 Zustand 进行状态管理，定义了多个独立的 store 模块：

// useUiPreferencesStore 核心功能
toggleLeftSidebar: () => set((s) => ({ isLeftSidebarVisible: !s.isLeftSidebarVisible })),
toggleLeftMainPanel: (workspaceId) => { /* 切换主面板 */ },
toggleRightSidebar: () => set((s) => ({ isRightSidebarVisible: !s.isRightSidebarVisible })),
toggleTerminal: () => set((s) => ({ isTerminalVisible: !s.isTerminalVisible })),

资料来源：packages/web-core/src/shared/stores/useUiPreferencesStore.ts

3.2 对话框系统

项目实现了统一的模态对话框框架 defineModal，支持在应用中复用对话框组件：

graph LR
    A[用户操作] --> B[打开对话框]
    B --> C[DialogContent]
    C --> D[DialogFooter<br/>取消/确认按钮]
    C --> E[状态管理<br/>isSubmitting]

核心对话框组件：

export const ForcePushDialog = defineModal<ForcePushDialogProps, string>(
  ForcePushDialogImpl
);

资料来源：packages/web-core/src/shared/dialogs/command-bar/ForcePushDialog.tsx 资料来源：packages/web-core/src/shared/dialogs/global/ReleaseNotesDialog.tsx

3.3 命令面板系统

CommandBar 组件实现了一个功能强大的命令面板，支持多种项目类型：

function getItemSearchLabel(item: CommandBarGroupItem<TAction, TPageId>) {
  if (item.type === 'page') return `${item.pageId} ${item.label}`;
  if (item.type === 'repo') return `${item.repo.id} ${item.repo.display_name}`;
  if (item.type === 'branch') return item.branch.name;
  if (item.type === 'status') return `${item.status.id} ${item.status.name}`;
  if (item.type === 'priority') return `${item.priority.id ?? 'none'} ${item.priority.name}`;
  if (item.type === 'issue') return `${item.issue.id} ${item.issue.simple_id} ${item.issue.title}`;
  // ...
}

支持的命令项类型：

资料来源：packages/ui/src/components/CommandBar.tsx

3.4 快捷键系统

项目实现了基于 useHotkeys 的全局快捷键绑定：

// useWorkspaceShortcuts.ts 关键映射
'v>p': TogglePreviewMode    // 预览模式
'v>s': ToggleLeftSidebar     // 切换左侧边栏
'v>h': ToggleLeftMainPanel   // 切换左侧主面板
'x>p': GitCreatePR           // 创建 Pull Request
'x>m': GitMerge              // 合并分支
'x>u': GitPush               // 推送代码
't>d': ToggleDevServer       // 切换开发服务器

资料来源：packages/web-core/src/shared/keyboard/useWorkspaceShortcuts.ts

4. 工作区系统

4.1 工作区组件架构

WorkspacesSidebar 是核心工作区管理组件，支持多种布局模式：

graph TD
    A[WorkspacesSidebar] --> B[accordion 模式]
    A --> C[列表模式]
    B --> B1[可折叠区域<br/>needsAttention]
    B --> B2[运行中工作区]
    B --> B3[归档工作区]
    C --> C1[工作区摘要卡片]

工作区状态属性：

资料来源：packages/ui/src/components/WorkspacesSidebar.tsx

4.2 附件上传与 Azure 集成

useAzureAttachments Hook 实现了文件上传的状态管理：

// 上传流程状态转换
上传中 → confirmAttachmentUpload() → 完成
// 状态映射
{ status: 'uploading', progress: pct }
{ status: 'confirming', progress: 100 }
{ id: result.id, blob_id: result.blob_id } // 完成状态

资料来源：packages/web-core/src/shared/hooks/useAzureAttachments.ts

5. 后端服务

5.1 Rust 后端架构

后端采用 Rust 构建，主要路由位于 crates/server/src/routes/ 目录：

graph LR
    A[HTTP 请求] --> B[oauth.rs]
    A --> C[API 路由]
    B --> D[GitHub OAuth]
    C --> E[业务逻辑]
    E --> F[executors]
    E --> G[数据库]

OAuth 认证端点示例：

Response::builder()
    .status(StatusCode::OK)
    .header("content-type", "text/html; charset=utf-8")
    .body(body)
    .unwrap()

资料来源：crates/server/src/routes/oauth.rs

5.2 冲突解决对话框

当检测到 Git 冲突时，ResolveConflictsDialog 展示冲突文件列表：

{conflictedFiles.slice(0, 5).map((file) => (
  <li key={file} className="truncate">{file}</li>
))}
{conflictedFiles.length > 5 && (
  <li>还有 {conflictedFiles.length - 5} 个文件</li>
)}

资料来源：packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx

6. 会话与聊天系统

6.1 SessionChatBox 组件

会话聊天框组件 SessionChatBox 是用户与 AI 代理交互的核心界面：

// 聊天框头部状态展示
headerRight={
  <>
    <TurnNavigationPopup />      // 消息导航
    <TodoProgressPopup todos={todos ?? []} />  // 待办进度
    <ContextUsageG />            // 上下文使用情况
  </>
}

会话模式：

资料来源：packages/ui/src/components/SessionChatBox.tsx

7. 项目页面结构

7.1 HomePage 组织架构

HomePage 组件采用三级组织结构：

graph TD
    A[HomePage] --> B[OrganizationSection]
    A --> C[NoOrganizations]
    B --> D[ProjectCard × n]
    D --> E[hostId 检查]
    E -->|无 hostId| F[openRelaySettings]
    E -->|有 hostId| G[导航到项目]

资料来源：packages/remote-web/src/pages/HomePage.tsx

8. 核心数据流

8.1 Git 操作流程

sequenceDiagram
    participant U as 用户
    participant CB as CommandBar
    participant D as ForcePushDialog
    participant S as Server
    
    U->>CB: 输入命令
    CB->>D: 打开确认对话框
    D->>U: 显示警告信息
    U->>D: 点击确认
    D->>S: 发送 force push 请求
    S-->>D: 返回结果
    D-->>U: 显示成功/错误

资料来源：packages/web-core/src/shared/dialogs/command-bar/ForcePushDialog.tsx

9. 依赖关系总结

概述

Vibe Kanban 是一个采用 pnpm monorepo 结构管理的前后端分离项目。前端使用 React 技术栈（TypeScript），后端使用 Rust 语言（基于 Axum 框架）。项目通过 pnpm workspaces 统一管理多个子包，实现统一的依赖管理和构建流程。

技术栈概览：

前置条件

系统要求

开发环境需要满足以下最低要求：

• 操作系统：macOS、Linux 或 Windows (WSL2)
• 内存：建议 8GB 以上
• 磁盘空间：至少 10GB 可用空间

必需工具

#### Rust 环境

项目使用 Rust 作为后端语言，需要安装 Rust 工具链：

# 安装 Rust (如果尚未安装)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 验证安装
rustc --version
cargo --version

Rust 工具链版本由 rust-toolchain.toml 文件定义，确保使用兼容版本：

[toolchain]
channel = "stable"
components = ["rustfmt", "clippy"]

#### Node.js 与 pnpm

前端开发需要 Node.js 环境：

# 安装 Node.js 18+
# 建议使用 nvm 管理 Node 版本
nvm install 18
nvm use 18

# 安装 pnpm (如果尚未安装)
npm install -g pnpm

# 验证 pnpm 版本
pnpm --version

项目根目录下的 pnpm-workspace.yaml 定义了工作区配置：

packages:
  - 'packages/*'
  - 'crates/*'

#### 数据库

Vibe Kanban 后端依赖 PostgreSQL 数据库：

• 最低版本：PostgreSQL 14+
• 建议版本：PostgreSQL 15 或 16

可选工具

安装步骤

1. 克隆代码仓库

git clone https://github.com/BloopAI/vibe-kanban.git
cd vibe-kanban

2. 安装前端依赖

在项目根目录执行依赖安装：

pnpm install

pnpm 会根据 pnpm-workspace.yaml 的配置，自动安装所有 workspace 内的依赖：

• packages/web-core - 核心 Web 模块
• packages/ui - UI 组件库
• packages/remote-web - 远程 Web 模块
• crates/server - Rust 服务（通过 cargo 管理）

3. 配置环境变量

创建环境变量配置文件：

cp .env.example .env

根据实际环境修改 .env 文件中的配置项：

4. 初始化数据库

# 创建数据库
psql -U postgres -c "CREATE DATABASE vibe_kanban;"

# 运行数据库迁移
cd crates/server
cargo run --bin migrate

本地构建

完整构建

使用项目提供的构建脚本进行完整构建：

./local-build.sh

该脚本会自动执行以下步骤：

1. 安装 Rust 依赖
2. 构建后端服务
3. 构建前端应用
4. 生成可部署产物

分步构建

#### 后端构建

cd crates/server
cargo build --release

产物位置：crates/server/target/release/server

#### 前端构建

cd packages/web-core
pnpm build

产物位置：packages/web-core/dist

开发模式

#### 启动后端服务

cd crates/server
cargo run

服务默认监听 http://localhost:8080

#### 启动前端开发服务器

cd packages/web-core
pnpm dev

访问 http://localhost:3000 查看前端应用

项目结构

vibe-kanban/
├── packages/                    # 前端包目录
│   ├── web-core/               # 核心 Web 模块
│   │   └── src/
│   │       ├── shared/         # 共享组件和工具
│   │       ├── dialogs/        # 对话框组件
│   │       ├── stores/         # Zustand 状态管理
│   │       └── hooks/          # React 自定义 Hooks
│   ├── ui/                     # UI 组件库
│   └── remote-web/             # 远程 Web 模块
├── crates/                      # Rust crates 目录
│   └── server/                 # 后端服务
│       ├── src/
│       │   ├── routes/         # API 路由定义
│       │   └── models/         # 数据模型
│       └── migrations/          # 数据库迁移
├── docs/                       # 项目文档
│   └── self-hosting/           # 自托管文档
├── pnpm-workspace.yaml         # pnpm 工作区配置
├── rust-toolchain.toml         # Rust 工具链定义
└── local-build.sh              # 本地构建脚本

常见问题

依赖安装失败

问题：pnpm 安装依赖时报错

解决方案：

# 清理缓存后重试
pnpm store prune
rm -rf node_modules
pnpm install

Rust 编译错误

问题：cargo 编译时出现版本不兼容错误

解决方案：

# 更新 Rust 工具链
rustup update
rustup upgrade

# 清理编译缓存
cargo clean
cargo build

数据库连接失败

问题：后端服务启动时无法连接数据库

解决方案：

1. 检查 PostgreSQL 服务是否运行
2. 验证 DATABASE_URL 环境变量配置
3. 确认数据库用户权限

# 检查 PostgreSQL 状态
pg_isready -h localhost -p 5432

# 测试数据库连接
psql $DATABASE_URL -c "SELECT 1;"

验证安装

完成以上步骤后，可以通过以下方式验证环境搭建是否成功：

1. 后端服务验证：访问 http://localhost:8080/health
2. 前端应用验证：访问 http://localhost:3000
3. API 文档：访问 http://localhost:8080/docs（如果启用 Swagger）

所有验证通过后，即可开始 Vibe Kanban 的开发工作。

概述

看板任务管理是 Vibe Kanban 系统的核心功能模块，旨在帮助软件工程师高效地规划、分配和跟踪编码任务。该系统通过直观的看板界面将传统项目管理方法与现代 AI 编码代理能力相结合，支持从任务创建到工作区执行的全流程管理。

看板任务管理的核心概念包括：

• Issue（问题/任务）：系统中的基本工作单元
• Project（项目）：包含多个相关 Issue 的容器
• Status（状态）：Issue 在看板中的流转阶段
• Workspace（工作区）：用于执行任务的隔离环境

数据模型

Issue 类型定义

Issue 是看板任务管理的基础单元。在 crates/api-types/src/issue.rs 中定义了完整的数据结构：

pub struct Issue {
    pub id: String,
    pub project_id: String,
    pub simple_id: String,          // 人类可读的短 ID
    pub title: String,              // 任务标题
    pub description: Option<String>, // 详细描述
    pub status_id: String,          // 当前状态 ID
    pub priority: Option<i32>,      // 优先级数值
    pub assignee_id: Option<String>, // 负责人 ID
    pub created_at: DateTime,
    pub updated_at: DateTime,
    pub completed_at: Option<DateTime>,
    pub labels: Vec<String>,        // 标签列表
    pub parent_id: Option<String>, // 父 Issue ID（用于子任务）
    pub is_archived: bool,
}

Issue Tag 标签系统

crates/api-types/src/issue_tag.rs 定义了标签相关的数据结构，用于对 Issue 进行分类和标记：

pub struct IssueTag {
    pub id: String,
    pub project_id: String,
    pub name: String,
    pub color: String,
}

pub struct IssueTagWithCount {
    pub tag: IssueTag,
    pub count: i32,  // 使用该标签的 Issue 数量
}

Task 数据库模型

crates/db/src/models/task.rs 中的 Task 模型与 Issue 概念相关联：

pub struct Task {
    pub id: String,
    pub issue_id: String,
    pub title: String,
    pub description: Option<String>,
    pub status: TaskStatus,
    pub created_at: DateTime,
    pub updated_at: DateTime,
    pub completed_at: Option<DateTime>,
}

Project 层级结构

crates/api-types/src/project.rs 定义了项目模型，作为 Issue 的容器：

pub struct Project {
    pub id: String,
    pub name: String,
    pub description: Option<String>,
    pub created_at: DateTime,
    pub updated_at: DateTime,
    pub issue_count: i32,
    pub workspace_count: i32,
}

系统架构

整体架构图

graph TD
    A[用户界面] --> B[KanbanBoard 组件]
    B --> C[LocalProjectKanban 页面]
    C --> D[状态管理层]
    D --> E[API 层]
    E --> F[数据库]
    
    G[Issue 数据流] --> H[创建 Issue]
    G --> I[更新 Issue]
    G --> J[删除 Issue]
    G --> K[移动 Issue 状态]
    
    H --> L[Task 模型]
    I --> L
    J --> L
    K --> L

看板组件结构

看板界面采用分层组件架构，主要组件包括：

状态管理模式

系统采用 Zustand 进行状态管理，主要涉及以下 Store：

// useUiPreferencesStore - UI 布局偏好
interface UiPreferencesState {
  layoutMode: 'kanban' | 'workspaces';
  isLeftSidebarVisible: boolean;
  isRightSidebarVisible: boolean;
  isTerminalVisible: boolean;
  paneSizes: Record<string, number>;
}

// useWorkspaceDiffStore - 工作区差异管理
interface WorkspaceDiffState {
  getGitHubCommentsForFile: (fileId: string) => GitHubComment[];
  getGitHubCommentCountForFile: (fileId: string) => number;
  getFilesWithGitHubComments: () => string[];
}

功能模块详解

看板视图

看板视图是任务管理的核心界面，采用列式布局展示不同状态的 Issue：

1. 列定义：每列代表一个工作流程状态（如 To Do、In Progress、Done）
2. 卡片展示：每个 Issue 显示为一张卡片，包含标题、优先级、负责人等信息
3. 拖拽操作：支持跨列拖拽以改变 Issue 状态
4. 快速操作：右键菜单提供快速编辑选项

Issue 详情面板

点击看板卡片后，右侧滑出的面板展示 Issue 完整信息，包含以下标签页：

interface IssuePanelTabs {
  workspacesSection: boolean;    // 关联的工作区
  relationshipsSection: boolean; // Issue 关系（阻塞、被阻塞等）
  subIssuesSection: boolean;     // 子任务列表
  commentsSection: boolean;      // 评论和讨论
}

评论系统

IssueCommentsSection 组件提供了完整的评论功能：

interface IssueCommentsSectionProps {
  comments: IssueCommentData[];
  commentInput: string;
  onCommentInputChange: (value: string) => void;
  onSubmitComment: () => void;
  editingCommentId: string | null;
  editingValue: string;
  onStartEdit: (commentId: string) => void;
  onSaveEdit: () => void;
  onCancelEdit: () => void;
  onDeleteComment: (id: string) => void;
  reactionsByCommentId: Map<string, ReactionGroup[]>;
  onToggleReaction: (commentId: string, emoji: string) => void;
}

支持的功能包括：

• 发表新评论：富文本编辑器支持
• 编辑评论：对已发布内容进行修改
• 删除评论：移除不需要的评论
• 表情反应：快速反馈
• 附件上传：支持文件附件

工作区关联

每个 Issue 可以关联多个 Workspace，实现任务与执行的连接：

interface WorkspaceSummary {
  name: string;
  workspaceId: string;
  filesChanged: number;
  linesAdded: number;
  linesRemoved: number;
  isActive: boolean;
  isRunning: boolean;
  isPinned: boolean;
  hasPendingApproval: boolean;
  hasRunningDevServer: boolean;
  hasUnseenActivity: boolean;
  latestProcessCompletedAt: Date | null;
  latestProcessStatus: ProcessStatus;
  prStatus: PRStatus | null;
}

标签管理

Issue 支持多标签分类，通过颜色区分不同类型的工作：

• 标签创建和编辑
• 标签与 Issue 的关联
• 按标签筛选看板视图
• 标签使用统计

工作流程

任务创建流程

graph LR
    A[用户点击新建] --> B[输入任务标题]
    B --> C[选择状态列]
    C --> D[设置优先级和负责人]
    D --> E[添加标签和描述]
    E --> F[保存到数据库]
    F --> G[更新看板视图]

任务状态流转

graph TD
    A[新建] --> B[待办]
    B --> C[进行中]
    C --> D[代码审查]
    D -->|通过| E[完成]
    D -->|需要修改| C
    E --> F[归档]
    
    G[阻塞] --> B
    H[取消] --> G

评论与协作流程

sequenceDiagram
    participant User as 用户
    participant UI as 界面组件
    participant Store as 状态管理
    participant API as API 层
    participant DB as 数据库
    
    User->>UI: 输入评论内容
    UI->>Store: onCommentInputChange()
    User->>UI: 点击发送
    UI->>API: submitComment()
    API->>DB: 保存评论
    DB-->>API: 评论记录
    API-->>Store: 更新评论列表
    Store-->>UI: 刷新评论显示

UI 布局配置

侧边栏管理

系统支持灵活的侧边栏配置：

// 切换侧边栏可见性
toggleLeftSidebar: () => void;
toggleRightSidebar: () => void;

// 切换主面板
toggleLeftMainPanel: (workspaceId: string) => void;

// 切换终端
toggleTerminal: () => void;

// 布局模式切换
toggleLayoutMode: () => void; // 'workspaces' <-> 'kanban'

面板大小持久化

interface PaneSizeConfig {
  setPaneSize: (key: string, size: number) => void;
  setCollapsedPaths: (key: string, paths: string[]) => void;
  setFileSearchRepo: (repoId: string) => void;
}

文件结构总览

packages/
├── ui/
│   └── src/components/
│       ├── KanbanBoard.tsx          # 核心看板组件
│       ├── IssueCommentsSection.tsx # 评论组件
│       └── WorkspacesSidebar.tsx    # 工作区侧边栏
└── web-core/
    └── src/
        ├── pages/kanban/
        │   ├── KanbanIssuePanelContainer.tsx  # Issue 面板容器
        │   └── LocalProjectKanban.tsx         # 本地看板页面
        ├── shared/
        │   ├── dialogs/                       # 对话框组件
        │   └── stores/                        # 状态管理
        │       ├── useWorkspaceDiffStore.ts
        │       └── useUiPreferencesStore.ts
        └── pages/HomePage.tsx                 # 主页入口

crates/
├── api-types/src/
│   ├── issue.rs       # Issue 类型定义
│   ├── issue_tag.rs   # 标签类型定义
│   └── project.rs     # 项目类型定义
└── db/src/models/
    └── task.rs        # 数据库任务模型

相关资源

• 官方文档：https://vibekanban.com/docs
• 自托管指南：https://vibekanban.com/docs/self-hosting/deploy-docker
• GitHub 仓库：https://github.com/BloopAI/vibe-kanban

概述

工作区（Workspace）是 Vibe Kanban 系统中用于运行编码代理的核心执行单元。每个工作区为 AI 代理提供独立的 Git 分支、终端环境和开发服务器，使团队能够通过看板任务规划和执行编码工作。

工作区管理涵盖工作区的创建、状态追踪、进程执行以及与编码会话的关联。系统支持多工作区并行运行，并提供统一的用户界面用于工作区切换、状态监控和结果查看。

资料来源：README.md

核心数据模型

Workspace 数据结构

工作区包含以下关键属性，用于追踪和管理执行状态：

资料来源：packages/ui/src/components/WorkspacesSidebar.tsx:35-48

Session 会话模型

每个工作区可关联一个编码会话，会话记录代理执行的上下文和结果：

资料来源：packages/ui/src/components/SessionChatBox.tsx:89-92

工作区选择与创建

工作区选择对话框

WorkspaceSelectionDialog 提供命令面板式的工作区选择界面，支持搜索、分页和新建工作区功能。

组件层级结构：

WorkspaceSelectionDialog
├── CommandDialog (cmdk 库)
│   └── Command
│       ├── CommandInput (搜索输入)
│       ├── CommandList
│       │   ├── CommandEmpty (无结果提示)
│       │   ├── CommandGroup (新建工作区选项)
│       │   │   └── CommandItem (__create_new__)
│       │   └── CommandGroup (可用工作区列表)
│       │       └── CommandItem (各工作区)
│       └── CommandList (分页计数显示)
└── WorkspaceSelectionWithContext (Context 包装器)
    ├── UserProvider
    └── ProjectProvider

工作区显示逻辑：

// 搜索值格式包含 ID、名称、分支和归档状态
value={`${workspace.id} ${workspace.name} ${workspace.branch}${workspace.isArchived ? ' archived' : ''}`}

资料来源：packages/web-core/src/shared/dialogs/command-bar/WorkspaceSelectionDialog.tsx:20-60

工作区过滤与搜索

系统支持按名称和分支搜索工作区，采用分页加载机制：

搜索时显示所有匹配结果，非搜索模式下超过 PAGE_SIZE 时显示分页提示。

资料来源：packages/web-core/src/shared/dialogs/command-bar/WorkspaceSelectionDialog.tsx:65-72

工作区侧边栏

布局模式

工作区侧边栏支持两种布局模式，可在 useUiPreferencesStore 中管理：

资料来源：packages/web-core/src/shared/stores/useUiPreferencesStore.ts:42-48

工作区状态指示

侧边栏通过 WorkspaceSummary 组件展示每个工作区的综合状态：

• 活跃状态: isActive 标识当前选中的工作区
• 运行状态: isRunning 显示代理是否正在执行
• 审批状态: hasPendingApproval 标记待审批内容
• 活动通知: hasUnseenActivity 提示未读更新

资料来源：packages/ui/src/components/WorkspacesSidebar.tsx:20-50

归档工作区展示

归档的工作区显示在独立区域，通过 isArchived 属性区分：

{workspace.isArchived && (
  <span className="text-xs text-low">
    ({t('workspaces.archived').toLowerCase()})
  </span>
)}

归档工作区列表为空时显示友好提示文本。

资料来源：packages/ui/src/components/WorkspacesSidebar.tsx:14-30

进程管理与执行

进程标签页

ProcessesTab 组件展示工作区内的执行进程历史：

显示信息包括：

• 进程启动时间 (started_at)
• 进程完成时间 (completed_at)
• 进程日志输出

操作功能：

• 复制日志: handleCopyLogs 处理日志复制到剪贴板
• 查看详情: setSelectedProcessId 选择特定进程查看

<div className="flex items-center gap-2">
  <button onClick={handleCopyLogs} disabled={logs.length === 0}>
    {copied ? t('processes.logsCopied') : t('processes.copyLogs')}
  </button>
  <button onClick={() => setSelectedProcessId(null)}>
    {t('processes.backToList')}
  </button>
</div>

资料来源：packages/web-core/src/shared/components/tasks/TaskDetails/ProcessesTab.tsx:50-80

执行状态时间线

每个进程的完整生命周期显示在界面中：

<div className="flex justify-between">
  <span>{t('processes.started', { date: formatDate(process.started_at) })}</span>
  {process.completed_at && (
    <span>{t('processes.completed', { date: formatDate(process.completed_at) })}</span>
  )}
</div>

资料来源：packages/web-core/src/shared/components/tasks/TaskDetails/ProcessesTab.tsx:75-85

会话与工作区关联

会话状态显示

SessionChatBox 组件在会话界面展示当前工作区的执行摘要：

<span className="text-sm text-low space-x-half whitespace-nowrap truncate min-w-0">
  <span>{t('diff.filesChanged', { count: filesChanged })}</span>
  {(linesAdded !== undefined || linesRemoved !== undefined) && (
    <span className="space-x-half">
      {linesAdded !== undefined && (
        <span className="text-success">+{linesAdded}</span>
      )}
      {linesRemoved !== undefined && (
        <span className="text-error">-{linesRemoved}</span>
      )}
    </span>
  )}
</span>

资料来源：packages/ui/src/components/SessionChatBox.tsx:82-98

代理图标与导航

会话界面支持代理图标显示和消息导航：

• 代理图标: renderAgentIcon?.(agent, 'size-icon-xl')
• 消息导航: TurnNavigationPopup 组件用于跳转历史消息
• Todo 进度: TodoProgressPopup 展示当前 Todo 状态

资料来源：packages/ui/src/components/SessionChatBox.tsx:103-125

工作区偏好设置

UI 状态持久化

useUiPreferencesStore 管理工作区相关的 UI 状态：

toggleLayoutMode: () =>
  set((s) => ({
    layoutMode: s.layoutMode === 'workspaces' ? 'kanban' : 'workspaces',
  })),

资料来源：packages/web-core/src/shared/stores/useUiPreferencesStore.ts:50-80

文件树折叠状态持久化

系统支持按工作区独立保存文件树折叠状态：

export function usePersistedCollapsedPaths(
  workspaceId: string | undefined
): [Set<string>, (paths: Set<string>) => void] {
  const key = workspaceId ? `file-tree:${workspaceId}` : '';
  // 状态存储在 collapsedPaths[key] 中
}

资料来源：packages/web-core/src/shared/stores/useUiPreferencesStore.ts:120-145

架构流程

工作区执行流程

graph TD
    A[用户创建工作区] --> B[分配 Git 分支]
    B --> C[启动编码会话]
    C --> D[代理执行任务]
    D --> E[更新文件变更]
    E --> F[记录进程日志]
    F --> G[完成执行]
    G --> H{创建 Pull Request?}
    H -->|是| I[生成 PR 描述]
    H -->|否| J[归档工作区]
    I --> K[等待审批]
    K --> L[合并 PR]
    L --> J

工作区管理状态机

stateDiagram-v2
    [*] --> 空闲: 创建工作区
    空闲 --> 运行中: 启动会话
    运行中 --> 空闲: 会话结束
    运行中 --> 待审批: 提交 PR
    待审批 --> 运行中: 需要修改
    待审批 --> 已归档: PR 已合并
    已归档 --> 空闲: 恢复工作区
    空闲 --> 已归档: 手动归档

关键交互

工作区选择交互

面板切换

资料来源：packages/web-core/src/shared/stores/useUiPreferencesStore.ts:60-75

总结

Vibe Kanban 的工作区管理模块为编码代理提供了完整的执行环境支持。通过工作区选择对话框、侧边栏概览、进程标签页和会话状态显示等组件，系统实现了从工作区创建到执行完成的完整生命周期管理。前端采用 React Context 模式管理用户和项目上下文，通过 Zustand store 持久化 UI 偏好设置，确保跨会话的用户体验一致性。

概述

Vibe Kanban 的编码代理集成（Coding Agent Integration）模块是该平台的核心功能之一，旨在为软件工程师提供与多种 AI 编码代理无缝协作的工作环境。该系统允许用户通过统一的界面管理、配置和切换不同的编码代理，在专用工作空间中执行代码任务，同时保持与项目看板（Kanban）的紧密集成。

根据项目 README 说明，Vibe Kanban 已支持超过 10 种编码代理，包括：

• Claude Code
• Codex
• Gemini CLI
• GitHub Copilot
• Amp
• Cursor
• OpenCode
• Droid
• CCR
• Qwen Code

资料来源：README.md:32

架构设计

整体架构

Vibe Kanban 的编码代理集成采用模块化架构设计，核心组件位于 crates/executors 目录下的 Rust crate 中。该架构支持动态代理发现、多代理配置管理以及统一的执行接口。

graph TD
    A[用户界面层<br/>packages/ui] --> B[Web Core 层<br/>packages/web-core]
    B --> C[执行器抽象层<br/>crates/executors]
    C --> D[Claude 执行器]
    C --> E[Codex 执行器]
    C --> F[其他执行器]
    G[配置文件<br/>Profile] --> C
    H[工作空间状态<br/>Workspace State] --> B

执行器模块结构

根据仓库结构分析，执行器模块的主要组织方式如下：

资料来源：README.md:32

配置管理

执行器配置（Profile）

每个编码代理都通过 Profile 配置进行管理。配置系统支持以下关键参数：

配置存储通过 Zustand store useUiPreferencesStore 进行前端状态管理：

// packages/web-core/src/shared/stores/useUiPreferencesStore.ts
toggleLayoutMode: () =>
  set((s) => ({
    layoutMode: s.layoutMode === 'workspaces' ? 'kanban' : 'workspaces',
  })),

资料来源：packages/web-core/src/shared/stores/useUiPreferencesStore.ts:45

UI 配置选择器

在用户界面中，代理和配置的选择通过 AgentSelector 和 ConfigSelector 组件实现。这些组件出现在工作空间创建和冲突解决对话框中：

// packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx
{profiles && createNewSession && (
  <div className="flex gap-3 flex-col sm:flex-row">
    <AgentSelector
      profiles={profiles}
      selectedExecutorProfile={effectiveProfile}
      onChange={setUserSelectedProfile}
      showLabel={false}
    />
    <ConfigSelector
      profiles={profiles}
      selectedExecutorProfile={effectiveProfile}
      onChange={setUserSelectedProfile}
      showLabel={false}
    />
  </div>
)}

资料来源：packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx:85-96

工作空间集成

工作空间选择

编码代理在特定的工作空间（Workspace）中执行。用户可以通过命令面板（Command Bar）或专用对话框选择代理的工作空间：

// packages/web-core/src/shared/dialogs/command-bar/WorkspaceSelectionDialog.tsx
{displayedWorkspaces.map((workspace) => (
  <CommandItem
    key={workspace.id}
    value={`${workspace.id} ${workspace.name} ${workspace.branch}${workspace.isArchived ? ' archived' : ''}`}
    onSelect={() => handleLinkWorkspace(workspace.id)}
    disabled={isLinking}
  >
    <GitBranchIcon
      className={`h-4 w-4 shrink-0 ${workspace.isArchived ? 'text-low' : ''}`}
      weight="regular"
    />
    <span className={`truncate ${workspace.isArchived ? 'text-low' : ''}`}>
      {workspace.name}
    </span>
    {workspace.isArchived && (
      <span className="text-xs text-low">
        ({t('workspaces.archived').toLowerCase()})
      </span>
    )}
  </CommandItem>
))}

资料来源：packages/web-core/src/shared/dialogs/command-bar/WorkspaceSelectionDialog.tsx:54-71

工作空间状态管理

工作空间侧边栏组件 WorkspacesSidebar 显示所有工作空间及其运行状态，包括：

// packages/ui/src/components/WorkspacesSidebar.tsx
<WorkspaceSummary
  summary
  key={workspace.id}
  name={workspace.name}
  workspaceId={workspace.id}
  filesChanged={workspace.filesChanged}
  linesAdded={workspace.linesAdded}
  linesRemoved={workspace.linesRemoved}
  isActive={selectedWorkspaceId === workspace.id}
  isRunning={workspace.isRunning}
  isPinned={workspace.isPinned}
  hasPendingApproval={workspace.hasPendingApproval}
  hasRunningDevServer={workspace.hasRunningDevServer}
  hasUnseenActivity={workspace.hasUnseenActivity}
  latestProcessCompletedAt={workspace.latestProcessCompletedAt}
  latestProcessStatus={workspace.latestProcessStatus}
  prStatus={workspace.prStatus}
  onOpenWorkspaceActions={handleOpenWorkspaceActions}
  onClick={() => onSelectWorkspace(workspace.id)}
/>

资料来源：packages/ui/src/components/WorkspacesSidebar.tsx:42-59

快捷键绑定

工作空间快捷键

Vibe Kanban 为编码代理操作提供了丰富的快捷键支持，定义在 useWorkspaceShortcuts hook 中：

// packages/web-core/src/shared/keyboard/useWorkspaceShortcuts.ts
useHotkeys('x>p', () => execute(Actions.GitCreatePR), OPTIONS);
useHotkeys('x>m', () => execute(Actions.GitMerge), OPTIONS);
useHotkeys('x>r', () => execute(Actions.GitRebase), OPTIONS);
useHotkeys('x>u', () => execute(Actions.GitPush), OPTIONS);
useHotkeys('t>d', () => execute(Actions.ToggleDevServer), OPTIONS);
useHotkeys('t>w', () => execute(Actions.ToggleWrapLines), OPTIONS);
useHotkeys('r>s', () => execute(Actions.RunSetupScript), OPTIONS);
useHotkeys('r>c', () => execute(Actions.RunCleanupScript), OPTIONS);

资料来源：packages/web-core/src/shared/keyboard/useWorkspaceShortcuts.ts:1-30

命令面板集成

命令项类型

命令面板（CommandBar）组件支持多种与编码代理相关的命令项类型：

// packages/ui/src/components/CommandBar.tsx
function getItemSearchLabel<
  TAction extends CommandBarAction,
  TPageId extends string,
>(
  item: CommandBarGroupItem<TAction, TPageId>,
  getLabel: (action: TAction) => string
) {
  if (item.type === 'page') {
    return `${item.pageId} ${item.label}`;
  }
  if (item.type === 'repo') {
    return `${item.repo.id} ${item.repo.display_name}`;
  }
  if (item.type === 'branch') {
    return item.branch.name;
  }
  // ... 其他类型处理
}

资料来源：packages/ui/src/components/CommandBar.tsx:40-65

Git 操作与冲突处理

强制推送处理

当编码代理执行 Git 操作时遇到冲突，系统提供强制推送（Force Push）确认对话框：

// packages/web-core/src/shared/dialogs/command-bar/ForcePushDialog.tsx
<DialogFooter className="gap-2">
  <Button
    variant="outline"
    onClick={handleCancel}
    disabled={isProcessing}
  >
    {t('common:buttons.cancel')}
  </Button>
  <Button
    variant="destructive"
    onClick={handleConfirm}
    disabled={isProcessing}
  >
    {isProcessing && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
    {isProcessing
      ? t('tasks:git.states.forcePushing')
      : t('tasks:git.states.forcePush')}
  </Button>
</DialogFooter>

资料来源：packages/web-core/src/shared/dialogs/command-bar/ForcePushDialog.tsx:40-57

冲突文件显示

冲突解决对话框展示所有冲突文件，并支持选择新的执行器配置：

// packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx
{conflictedFiles.slice(0, 5).map((file) => (
  <li key={file} className="truncate">
    {file}
  </li>
)))}
{conflictedFiles.length > 5 && (
  <li className="text-warning-foreground/60 dark:text-warning/60">
    {t('resolveConflicts.dialog.andMore', {
      count: conflictedFiles.length - 5,
    })}
  </li>
)}

资料来源：packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx:73-83

进程与日志管理

进程状态追踪

编码代理执行的进程通过 ProcessesTab 组件进行监控：

// packages/web-core/src/shared/components/tasks/TaskDetails/ProcessesTab.tsx
<div className="flex justify-between">
  <span>
    {t('processes.started', {
      date: formatDate(process.started_at),
    })}
  </span>
  {process.completed_at && (
    <span>
      {t('processes.completed', {
        date: formatDate(process.completed_at),
      })}
    </span>
  )}
</div>

支持的操作包括：

资料来源：packages/web-core/src/shared/components/tasks/TaskDetails/ProcessesTab.tsx:1-50

工单与评论集成

评论系统

编码代理的工作成果通过工单评论系统进行交流：

// packages/ui/src/components/IssueCommentsSection.tsx
interface IssueCommentsSectionProps {
  comments: IssueCommentData[];
  commentInput: string;
  onCommentInputChange: (value: string) => void;
  onSubmitComment: () => void;
  editingCommentId: string | null;
  editingValue: string;
  onEditingValueChange: (value: string) => void;
  onStartEdit: (commentId: string) => void;
  onSaveEdit: () => void;
  onCancelEdit: () => void;
  onDeleteComment: (id: string) => void;
  reactionsByCommentId: Map<string, ReactionGroup[]>;
  onToggleReaction: (commentId: string, emoji: string) => void;
  onReply: (authorName: string, message: string) => void;
  // ... 其他属性
}

资料来源：packages/ui/src/components/IssueCommentsSection.tsx:20-42

数据模型

工单数据更新

工单的更新操作支持多种字段的原子性修改：

// crates/remote/src/db/issues.rs
pub async fn update<'e, E>(
    executor: E,
    id: Uuid,
    status_id: Option<Uuid>,
    title: Option<String>,
    description: Option<Option<String>>,
    priority: Option<Option<IssuePriority>>,
    start_date: Option<Option<DateTime<Utc>>>,
    target_date: Option<Option<DateTime<Utc>>>,
    completed_at: Option<Option<DateTime<Utc>>>,
    sort_order: Option<f64>,
    parent_issue_id: Option<Option<Uuid>>,
    parent_issue_sort_order: Option<Option<f64>>,
    extension_metadata: Option<Value>,
) -> Result<Issue, IssueError>

该设计使用 Rust 的 Option<Option<T>> 类型来区分"不更新字段"（None）和"显式设置为 NULL"（Some(None)）两种情况：

资料来源：crates/remote/src/db/issues.rs:1-40

工作流程示意

graph LR
    A[创建工单<br/>Create Issue] --> B[规划任务<br/>Plan Tasks]
    B --> C[创建工作空间<br/>Create Workspace]
    C --> D[选择编码代理<br/>Select Agent]
    D --> E[执行编码任务<br/>Execute Tasks]
    E --> F{检查结果}
    F -->|有冲突| G[解决冲突<br/>Resolve Conflicts]
    G --> D
    F -->|成功| H[审查 Diff<br/>Review Diff]
    H --> I[创建 PR<br/>Create PR]
    I --> J[合并代码<br/>Merge]

平台状态说明

根据项目 README 公告，Vibe Kanban 项目已于近期宣布停止运营（sunsetting）。相关公告可在 vibekanban.com/blog/shutdown 查看。

资料来源：README.md:1-10

总结

Vibe Kanban 的编码代理集成系统通过以下核心机制实现与多种 AI 编码代理的无缝协作：

1. 模块化执行器架构：基于 Rust crate 的插件式设计，支持动态发现和加载不同的编码代理
2. 统一配置管理：Profile 系统提供灵活的代理参数配置能力
3. 深度工作空间集成：编码代理在隔离的工作空间中执行，与 Git 仓库和工单系统紧密关联
4. 丰富的交互接口：支持快捷键、命令面板、冲突解决对话框等多种交互方式
5. 完整的进程监控：提供进程状态追踪、日志管理和实时反馈机制

概述

Vibe Kanban 项目采用 Rust 后端 + SQLite 本地数据库 的架构模式。数据库层位于 crates/db 目录，包含数据模型定义和数据库迁移脚本。项目的数据库设计遵循 Rust 生态系统的最佳实践，使用 Diesel ORM 框架进行数据库操作。

项目的数据模型涵盖了核心业务实体：Project（项目）、Workspace（工作空间）、Session（会话） 以及相关的关联数据。前端通过 API 与后端进行数据交互，后端负责数据库的读写操作。

概述

Vibe Kanban 的本地 API 服务器是基于 Rust 构建的后端服务，负责处理前端应用与远程服务之间的通信、OAuth 认证流程、Workspace 生命周期管理以及会话状态维护。该服务器作为本地代理层，为 Web 前端提供统一的 API 接口，同时管理 GitHub 集成和项目数据同步。

本地 API 服务器的核心职责包括：

• 作为前端与远程后端之间的中间层，转发请求和响应
• 处理 OAuth 2.0 认证流程，包括 GitHub CLI 认证
• 管理 Workspace 的创建、更新和删除操作
• 处理会话（Session）的创建、查询和状态同步
• 提供文件系统操作和终端命令执行的桥接能力

技术架构

技术栈

资料来源：crates/server/src/lib.rs:1-50

模块结构

graph TD
    A[crates/server/src] --> B[main.rs - 入口点]
    A --> C[lib.rs - 库定义]
    A --> D[routes/ - 路由模块]
    A --> E[middleware/ - 中间件]
    
    D --> D1[mod.rs - 路由聚合]
    D --> D2[workspaces/ - Workspace 路由]
    D --> D3[sessions/ - 会话路由]
    D --> D4[oauth.rs - OAuth 路由]
    
    E --> E1[mod.rs - 中间件聚合]

核心模块

主入口 (main.rs)

main.rs 是服务器进程的启动入口，负责初始化日志系统、配置加载和 HTTP 服务器的绑定。服务器默认监听本地端口，支持配置化端口设置。

主要启动流程：

1. 解析命令行参数和配置文件
2. 初始化日志记录器（支持结构和日志级别配置）
3. 建立数据库连接池（如适用）
4. 挂载所有路由模块
5. 启动 HTTP 服务器监听

路由模块 (routes/)

#### 路由聚合 (routes/mod.rs)

路由模块作为中央聚合点，将所有子路由统一注册到主路由器。该模块定义了基础路径前缀和共享的路由配置。

#### Workspace 核心路由 (routes/workspaces/core.rs)

Workspace 路由是服务器最核心的功能模块之一，负责处理与编码代理工作区相关的所有 API 请求。

资料来源：crates/server/src/routes/workspaces/core.rs:1-100

#### 会话路由 (routes/sessions/mod.rs)

会话路由管理 Workspace 内的编码代理会话，包括会话创建、状态查询和日志获取。

资料来源：crates/server/src/routes/sessions/mod.rs:1-80

#### OAuth 路由 (routes/oauth.rs)

OAuth 路由处理 GitHub 认证流程的回掉逻辑。当用户完成 GitHub 授权后，GitHub 会重定向到本地服务器的回掉端点。

Response::builder()
    .status(StatusCode::OK)
    .header("content-type", "text/html; charset=utf-8")
    .body(body)
    .unwrap()

OAuth 流程包含以下步骤：

1. 用户发起认证请求
2. 服务器生成临时状态令牌
3. 重定向到 GitHub 授权页面
4. 用户授权后回调到本地服务器
5. 服务器验证状态令牌并交换访问令牌
6. 返回认证结果页面

资料来源：crates/server/src/routes/oauth.rs:1-50

中间件模块 (middleware/)

中间件模块提供了请求处理的横切关注点，包括：

资料来源：crates/server/src/middleware/mod.rs:1-60

请求处理流程

sequenceDiagram
    participant Client as 前端客户端
    participant Server as 本地 API 服务器
    participant Remote as 远程后端服务
    
    Client->>Server: HTTP 请求
    Server->>Server: 中间件处理链
    Server->>Remote: 转发请求（添加认证头）
    Remote-->>Server: 远程响应
    Server->>Server: 响应转换/处理
    Server-->>Client: 处理后的响应

配置管理

本地 API 服务器支持通过环境变量和配置文件进行配置：

错误处理

服务器采用统一的错误响应格式：

{
  "error": {
    "code": "WORKSPACE_NOT_FOUND",
    "message": "指定的工作区不存在",
    "details": {}
  }
}

常见的错误码包括：

与前端的集成

前端通过以下方式与本地 API 服务器交互：

1. 固定端口通信：前端使用固定端口（如 8080）与本地服务器通信
2. 相对路径代理：前端请求通过相对路径自动转发到本地服务器
3. 认证令牌传递：Bearer Token 在请求头中传递
4. OAuth 弹窗：GitHub 认证通过弹窗完成，结果回写到父窗口

启动与部署

开发环境启动

cd crates/server
cargo run

生产环境构建

cargo build --release
./target/release/vibe-kanban-server

Docker 部署

服务器支持 Docker 容器化部署，提供轻量级的隔离运行环境。

安全考量

• 所有与远程服务的通信使用 HTTPS
• OAuth 令牌安全存储，不暴露在前端日志中
• 速率限制防止 API 滥用
• CORS 策略限制跨域请求来源

概述

Vibe Kanban 的远程云服务架构为团队协作提供了基础设施支持，允许用户通过远程 Web 界面访问和管理项目。该架构涵盖了身份验证、文件附件、GitHub 集成以及组织管理等功能模块。

根据仓库结构，远程服务主要由 crates/server（后端 Rust 服务）、packages/remote-web（远程 Web 前端）和 packages/web-core（共享核心组件）组成。这种模块化设计使得远程访问与企业内部部署可以共享核心业务逻辑。资料来源：packages/web-core/src/shared/dialogs/auth/GhCliSetupDialog.tsx:1-50

核心架构组件

后端服务层

后端服务采用 Rust 语言实现，提供高性能的 HTTP API 接口。主要包括以下模块：

资料来源：crates/server/src/routes/oauth.rs:1-50

前端访问层

远程 Web 界面由 React 组件构建，提供用户交互界面。主要页面组件包括：

graph TD
    A[HomePage] --> B[OrganizationSection]
    A --> C[ProjectCard]
    B --> D[Projects List]
    C --> E[Remote Connection]
    
    F[GhCliSetupDialog] --> G[GitHub CLI Setup]
    H[ResolveConflictsDialog] --> I[Git Merge Resolution]

资料来源：packages/remote-web/src/pages/HomePage.tsx:1-100, packages/web-core/src/shared/dialogs/auth/GhCliSetupDialog.tsx:1-50

身份验证系统

OAuth 认证流程

OAuth 认证是远程服务访问的核心机制。当用户通过浏览器访问远程服务时，系统会显示一个确认页面让用户授权。资料来源：crates/server/src/routes/oauth.rs:30-45

sequenceDiagram
    participant User
    participant Browser
    participant RemoteServer
    participant GitHub
    
    User->>Browser: 访问远程服务
    Browser->>RemoteServer: 请求授权
    RemoteServer->>GitHub: 重定向到 GitHub OAuth
    GitHub->>User: 显示授权页面
    User->>GitHub: 确认授权
    GitHub->>RemoteServer: 返回授权码
    RemoteServer->>Browser: 显示成功页面

认证成功后会返回以下 HTML 响应格式：

<body>
  <div class="container">
    <img class="logo" src="data:image/png;base64,{APP_ICON_BASE64}">
    <div class="content">
      <p class="title">{message}</p>
      <p class="subtitle">You can close this tab and return to the app.</p>
    </div>
  </div>
</body>

资料来源：crates/server/src/routes/oauth.rs:30-50

GitHub CLI 设置

对于需要本地 GitHub CLI 集成的用户，系统提供了交互式设置流程。设置步骤包括：

1. 检查 GitHub CLI 是否已安装
2. 通过 Homebrew 安装（如需要）
3. 完成身份验证

资料来源：packages/web-core/src/shared/dialogs/auth/GhCliSetupDialog.tsx:15-35

文件附件系统

远程服务支持 Azure Blob Storage 集成的文件上传功能。附件处理流程涉及多个状态转换：

资料来源：packages/web-core/src/shared/hooks/useAzureAttachments.ts:1-60

附件上传完成后，系统会返回唯一标识符供后续引用，格式为 attachment://{id}。资料来源：packages/web-core/src/shared/hooks/useAzureAttachments.ts:45-55

组织与项目管理

组织管理

远程 Web 界面允许用户创建或加入组织，以便团队协作。组织管理界面显示了每个组织的名称和项目数量。资料来源：packages/remote-web/src/pages/HomePage.tsx:60-90

graph LR
    A[Organizations] -->|包含| B[Projects]
    B -->|包含| C[Workspaces]
    C -->|执行| D[AI Agents]

项目卡片组件

每个项目通过 ProjectCard 组件展示，支持以下功能：

• 显示项目基本信息（名称、颜色）
• 远程主机连接管理
• 快速访问项目工作区

当缺少主机配置时，用户可以触发 onRequireHost 回调打开中继设置。资料来源：packages/remote-web/src/pages/HomePage.tsx:120-160

Git 冲突解决

远程服务提供了冲突解决对话框组件，支持以下功能：

• 显示冲突文件列表（最多显示 5 个）
• 提示更多冲突文件数量
• 提供 Agent/Profile 选择器
• 新会话创建选项

资料来源：packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx:80-110

服务启动与配置

后端服务入口点定义在 crates/remote/src/main.rs，负责初始化配置并启动 HTTP 服务器。服务支持环境变量配置，包括：

• 数据库连接参数
• Azure Storage 凭证
• GitHub App 配置
• OAuth 回调 URL

资料来源：crates/remote/src/main.rs:1-30

安全考虑

远程服务架构实现了多层安全机制：

1. OAuth 2.0 授权码流程：防止令牌泄露
2. HTML 响应 Content-Type 头：正确设置 text/html; charset=utf-8 资料来源：crates/server/src/routes/oauth.rs:47-50
3. 会话隔离：每个远程连接独立管理
4. 主机验证：中继设置确保连接安全

总结

Vibe Kanban 的远程云服务架构通过 Rust 后端和 React 前端的组合，实现了高效的远程协作能力。核心特性包括安全的 OAuth 认证、Azure 文件存储集成、GitHub App 集成以及组织级项目管理。该架构设计遵循了前端与后端分离的原则，同时通过共享的 web-core 包确保了本地和远程体验的一致性。

概述

MCP（Model Context Protocol）服务器是 Vibe Kanban 项目中用于扩展 AI 代理能力的核心组件。该模块允许外部编码代理通过标准化的 MCP 协议与 Vibe Kanban 系统进行交互，实现任务管理、工作区操作等功能。

架构设计

模块结构

MCP 实现位于 crates/mcp 目录下，采用模块化设计：

核心组件

MCP 服务器的核心组件包括：

1. 服务器入口 - vibe_kanban_mcp.rs 作为独立的二进制程序运行
2. 任务服务器 - 负责处理来自 AI 代理的请求
3. 工具集 - 定义可用的工具和操作
4. 请求处理器 - 路由和执行具体的工具调用

任务服务器模块

任务服务器（Task Server）是 MCP 服务器的核心实现，负责：

• 接收并解析 MCP 协议请求
• 管理会话状态
• 执行工具调用
• 返回标准化的响应

请求处理流程

graph TD
    A[MCP 请求] --> B[请求解析器]
    B --> C{请求类型}
    C -->|工具调用| D[工具调度器]
    C -->|资源请求| E[资源处理器]
    C -->|其他| F[错误处理]
    D --> G[执行工具]
    G --> H[结果序列化]
    H --> I[MCP 响应]
    E --> I
    F --> I

工具集

工具集定义了 AI 代理可以执行的操作类型。具体工具实现位于 task_server/tools/mod.rs。

工具分类

MCP 协议实现

请求格式

MCP 服务器遵循 Model Context Protocol 规范，请求包含：

• jsonrpc - JSON-RPC 版本标识
• method - 方法名称
• params - 参数字典
• id - 请求标识符

响应格式

标准响应格式：

{
  "jsonrpc": "2.0",
  "result": { ... },
  "id": "请求标识符"
}

错误响应格式：

{
  "jsonrpc": "2.0",
  "error": {
    "code": "错误代码",
    "message": "错误描述"
  },
  "id": "请求标识符"
}

配置与部署

二进制入口

crates/mcp/src/bin/vibe_kanban_mcp.rs 文件定义了可执行程序的入口点：

• 初始化日志系统
• 加载配置
• 启动 MCP 服务器
• 处理生命周期事件

配置项

与前端交互

MCP 服务器作为后端服务，与前端通过 WebSocket 或 HTTP 协议通信。前端组件（如 CommandBar.tsx 和 SessionChatBox.tsx）提供用户界面，通过这些协议与 MCP 服务器交换数据。

数据流

graph LR
    A[AI 代理] -->|MCP 协议| B[MCP 服务器]
    B -->|内部 API| C[Vibe Kanban 后端]
    C -->|数据| B
    B -->|MCP 响应| A
    D[前端 UI] -->|WebSocket| B

安全性

MCP 服务器实现包含以下安全措施：

1. 请求验证 - 验证所有传入请求的格式和来源
2. 权限控制 - 基于会话的权限检查
3. 输入清理 - 防止注入攻击
4. 超时保护 - 防止资源耗尽攻击

扩展指南

添加新工具

在 task_server/tools/mod.rs 中添加新的工具定义：

1. 定义工具的结构体
2. 实现工具的 execute 方法
3. 在工具注册表中添加新工具
4. 添加相应的测试用例

注册新处理器

在 task_server/handler.rs 中扩展请求处理逻辑：

1. 添加新的处理器函数
2. 更新路由逻辑
3. 注册处理程序到服务器

Pitfall Log / 踩坑日志

项目：BloopAI/vibe-kanban

摘要：发现 19 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：Deployment(Other(Migration failed: error returned from database: (code: 1) no such column: ep.session_id))。

1. 安装坑 · 来源证据：Deployment(Other(Migration failed: error returned from database: (code: 1) no such column: ep.session_id))

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Deployment(Other(Migration failed: error returned from database: (code: 1) no such column: ep.session_id))
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_b34b2ea1b35a4dc2a4a0eb0681bdb883 | https://github.com/BloopAI/vibe-kanban/issues/2972 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

2. 配置坑 · 来源证据：Support for self-hosted projects and better export

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Support for self-hosted projects and better export
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_19d27caa9e34416a9f282869f76624b0 | https://github.com/BloopAI/vibe-kanban/issues/3396 | 来源类型 github_issue 暴露的待验证使用条件。

3. 安全/权限坑 · 来源证据：[Proposal] JIRA Integration for Vibe Kanban

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Proposal] JIRA Integration for Vibe Kanban
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_ab38fe97c4574e2da01ddedd71a4fbac | https://github.com/BloopAI/vibe-kanban/issues/2424 | 来源类型 github_issue 暴露的待验证使用条件。

4. 安装坑 · 来源证据：Pre-release v0.1.40-20260401153532

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Pre-release v0.1.40-20260401153532
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_f4b99d437a4f4fd4989d2b3ef036553b | https://github.com/BloopAI/vibe-kanban/releases/tag/v0.1.40-20260401153532 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

5. 安装坑 · 来源证据：Release v0.1.36

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.1.36
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_527645be4e3f438e81757ef265a70d79 | https://github.com/BloopAI/vibe-kanban/releases/tag/v0.1.36-20260323174633 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

6. 安装坑 · 来源证据：Release v0.1.43

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.1.43
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_53704dc7171446fe86b2017f72212ddc | https://github.com/BloopAI/vibe-kanban/releases/tag/v0.1.43-20260417125614 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

7. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
• 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
• 证据：capability.host_targets | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | host_targets=claude, claude_code

8. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | README/documentation is current enough for a first validation pass.

9. 运行坑 · 来源证据：Pre-release v0.1.39-20260331145823

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Pre-release v0.1.39-20260331145823
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_c005a56959634369929ce33eddbdc103 | https://github.com/BloopAI/vibe-kanban/releases/tag/v0.1.39-20260331145823 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

10. 维护坑 · 来源证据：[Request] Support RDS for self hosting in AWS

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[Request] Support RDS for self hosting in AWS
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_f613b792c20942519560c0a286a82005 | https://github.com/BloopAI/vibe-kanban/issues/3405 | 来源类型 github_issue 暴露的待验证使用条件。

11. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | last_activity_observed missing

12. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | no_demo; severity=medium

13. 安全/权限坑 · 存在安全注意事项

• 严重度：medium
• 证据强度：source_linked
• 发现：No sandbox install has been executed yet; downstream must verify before user use.
• 对用户的影响：用户安装前需要知道权限边界和敏感操作。
• 建议检查：转成明确权限清单和安全审查提示。
• 防护动作：安全注意事项必须面向用户前置展示。
• 证据：risks.safety_notes | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | No sandbox install has been executed yet; downstream must verify before user use.

14. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | no_demo; severity=medium

15. 安全/权限坑 · 来源证据：Issue: Unclear Git + Bitbucket Setup for Vibe-Kanban (OpenCode) in Docker

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Issue: Unclear Git + Bitbucket Setup for Vibe-Kanban (OpenCode) in Docker
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_7d289a7b68ee4299ae4a5e54b0e64e35 | https://github.com/BloopAI/vibe-kanban/issues/3410 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

16. 安全/权限坑 · 来源证据：Pre-release v0.1.37-20260327101540

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Pre-release v0.1.37-20260327101540
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_d648fba4c94b4791ac2e7683f6cb1361 | https://github.com/BloopAI/vibe-kanban/releases/tag/v0.1.37-20260327101540 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

17. 安全/权限坑 · 来源证据：remote-v0.1.26

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：remote-v0.1.26
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_3f212752e8c142d68ffe2993ac23dd37 | https://github.com/BloopAI/vibe-kanban/releases/tag/remote-v0.1.26 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

18. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | issue_or_pr_quality=unknown

19. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | release_recency=unknown