needsAttention]\n B --> B2[运行中工作区]\n B --> B3[归档工作区]\n C --> C1[工作区摘要卡片]\n```\n\n**工作区状态属性**：\n\n| 属性 | 类型 | 描述 |\n|------|------|------|\n| `isRunning` | boolean | 是否正在运行 |\n| `isPinned` | boolean | 是否固定显示 |\n| `hasPendingApproval` | boolean | 是否有待审批项 |\n| `hasRunningDevServer` | boolean | 开发服务器状态 |\n| `hasUnseenActivity` | boolean | 是否有未读活动 |\n| `prStatus` | string | PR 状态 |\n| `filesChanged` | number | 变更文件数 |\n| `linesAdded` | number | 新增行数 |\n| `linesRemoved` | number | 删除行数 |\n\n资料来源：[packages/ui/src/components/WorkspacesSidebar.tsx]()\n\n### 4.2 附件上传与 Azure 集成\n\n`useAzureAttachments` Hook 实现了文件上传的状态管理：\n\n```typescript\n// 上传流程状态转换\n上传中 → confirmAttachmentUpload() → 完成\n// 状态映射\n{ status: 'uploading', progress: pct }\n{ status: 'confirming', progress: 100 }\n{ id: result.id, blob_id: result.blob_id } // 完成状态\n```\n\n资料来源：[packages/web-core/src/shared/hooks/useAzureAttachments.ts]()\n\n## 5. 后端服务\n\n### 5.1 Rust 后端架构\n\n后端采用 Rust 构建，主要路由位于 `crates/server/src/routes/` 目录：\n\n```mermaid\ngraph LR\n A[HTTP 请求] --> B[oauth.rs]\n A --> C[API 路由]\n B --> D[GitHub OAuth]\n C --> E[业务逻辑]\n E --> F[executors]\n E --> G[数据库]\n```\n\n**OAuth 认证端点示例**：\n\n```rust\nResponse::builder()\n .status(StatusCode::OK)\n .header(\"content-type\", \"text/html; charset=utf-8\")\n .body(body)\n .unwrap()\n```\n\n资料来源：[crates/server/src/routes/oauth.rs]()\n\n### 5.2 冲突解决对话框\n\n当检测到 Git 冲突时，`ResolveConflictsDialog` 展示冲突文件列表：\n\n```typescript\n{conflictedFiles.slice(0, 5).map((file) => (\n
\n
\n\n# 开发环境搭建\n\n本文档详细介绍 Vibe Kanban 项目的开发环境搭建流程，包括前置条件、安装步骤、配置说明以及本地运行方法。\n\n## 概述\n\nVibe Kanban 是一个采用 **pnpm monorepo** 结构管理的前后端分离项目。前端使用 React 技术栈（TypeScript），后端使用 Rust 语言（基于 Axum 框架）。项目通过 pnpm workspaces 统一管理多个子包，实现统一的依赖管理和构建流程。\n\n**技术栈概览：**\n\n| 层级 | 技术选型 | 主要包 |\n|------|----------|--------|\n| 前端框架 | React 18 + TypeScript | packages/web-core, packages/ui |\n| 后端服务 | Rust + Axum | crates/server |\n| 包管理器 | pnpm | pnpm-workspace.yaml |\n| UI 组件库 | Radix UI + Tailwind CSS | packages/ui |\n| 状态管理 | Zustand | packages/web-core |\n\n## 前置条件\n\n### 系统要求\n\n开发环境需要满足以下最低要求：\n\n- **操作系统**：macOS、Linux 或 Windows (WSL2)\n- **内存**：建议 8GB 以上\n- **磁盘空间**：至少 10GB 可用空间\n\n### 必需工具\n\n#### Rust 环境\n\n项目使用 Rust 作为后端语言，需要安装 Rust 工具链：\n\n```bash\n# 安装 Rust (如果尚未安装)\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n\n# 验证安装\nrustc --version\ncargo --version\n```\n\nRust 工具链版本由 `rust-toolchain.toml` 文件定义，确保使用兼容版本：\n\n```toml\n[toolchain]\nchannel = \"stable\"\ncomponents = [\"rustfmt\", \"clippy\"]\n```\n\n#### Node.js 与 pnpm\n\n前端开发需要 Node.js 环境：\n\n```bash\n# 安装 Node.js 18+\n# 建议使用 nvm 管理 Node 版本\nnvm install 18\nnvm use 18\n\n# 安装 pnpm (如果尚未安装)\nnpm install -g pnpm\n\n# 验证 pnpm 版本\npnpm --version\n```\n\n项目根目录下的 `pnpm-workspace.yaml` 定义了工作区配置：\n\n```yaml\npackages:\n - 'packages/*'\n - 'crates/*'\n```\n\n#### 数据库\n\nVibe Kanban 后端依赖 PostgreSQL 数据库：\n\n- **最低版本**：PostgreSQL 14+\n- **建议版本**：PostgreSQL 15 或 16\n\n### 可选工具\n\n| 工具 | 用途 | 必需性 |\n|------|------|--------|\n| Docker | 容器化运行环境 | 可选 |\n| DBeaver / pgAdmin | 数据库管理 | 推荐 |\n| VS Code + Rust Analyzer | Rust 开发 | 推荐 |\n| pnpm 插件 | 加速依赖安装 | 可选 |\n\n## 安装步骤\n\n### 1. 克隆代码仓库\n\n```bash\ngit clone https://github.com/BloopAI/vibe-kanban.git\ncd vibe-kanban\n```\n\n### 2. 安装前端依赖\n\n在项目根目录执行依赖安装：\n\n```bash\npnpm install\n```\n\npnpm 会根据 `pnpm-workspace.yaml` 的配置，自动安装所有 workspace 内的依赖：\n\n- `packages/web-core` - 核心 Web 模块\n- `packages/ui` - UI 组件库\n- `packages/remote-web` - 远程 Web 模块\n- `crates/server` - Rust 服务（通过 cargo 管理）\n\n### 3. 配置环境变量\n\n创建环境变量配置文件：\n\n```bash\ncp .env.example .env\n```\n\n根据实际环境修改 `.env` 文件中的配置项：\n\n| 变量名 | 说明 | 示例值 |\n|--------|------|--------|\n| `DATABASE_URL` | PostgreSQL 连接字符串 | `postgres://user:pass@localhost:5432/vibkanban` |\n| `RUST_LOG` | 日志级别 | `info` 或 `debug` |\n| `APP_PORT` | 应用监听端口 | `8080` |\n| `APP_HOST` | 应用监听地址 | `0.0.0.0` |\n| `GITHUB_CLIENT_ID` | GitHub OAuth 客户端 ID | `your_client_id` |\n| `GITHUB_CLIENT_SECRET` | GitHub OAuth 客户端密钥 | `your_client_secret` |\n\n### 4. 初始化数据库\n\n```bash\n# 创建数据库\npsql -U postgres -c \"CREATE DATABASE vibe_kanban;\"\n\n# 运行数据库迁移\ncd crates/server\ncargo run --bin migrate\n```\n\n## 本地构建\n\n### 完整构建\n\n使用项目提供的构建脚本进行完整构建：\n\n```bash\n./local-build.sh\n```\n\n该脚本会自动执行以下步骤：\n\n1. 安装 Rust 依赖\n2. 构建后端服务\n3. 构建前端应用\n4. 生成可部署产物\n\n### 分步构建\n\n#### 后端构建\n\n```bash\ncd crates/server\ncargo build --release\n```\n\n产物位置：`crates/server/target/release/server`\n\n#### 前端构建\n\n```bash\ncd packages/web-core\npnpm build\n```\n\n产物位置：`packages/web-core/dist`\n\n### 开发模式\n\n#### 启动后端服务\n\n```bash\ncd crates/server\ncargo run\n```\n\n服务默认监听 `http://localhost:8080`\n\n#### 启动前端开发服务器\n\n```bash\ncd packages/web-core\npnpm dev\n```\n\n访问 `http://localhost:3000` 查看前端应用\n\n## 项目结构\n\n```\nvibe-kanban/\n├── packages/ # 前端包目录\n│ ├── web-core/ # 核心 Web 模块\n│ │ └── src/\n│ │ ├── shared/ # 共享组件和工具\n│ │ ├── dialogs/ # 对话框组件\n│ │ ├── stores/ # Zustand 状态管理\n│ │ └── hooks/ # React 自定义 Hooks\n│ ├── ui/ # UI 组件库\n│ └── remote-web/ # 远程 Web 模块\n├── crates/ # Rust crates 目录\n│ └── server/ # 后端服务\n│ ├── src/\n│ │ ├── routes/ # API 路由定义\n│ │ └── models/ # 数据模型\n│ └── migrations/ # 数据库迁移\n├── docs/ # 项目文档\n│ └── self-hosting/ # 自托管文档\n├── pnpm-workspace.yaml # pnpm 工作区配置\n├── rust-toolchain.toml # Rust 工具链定义\n└── local-build.sh # 本地构建脚本\n```\n\n## 常见问题\n\n### 依赖安装失败\n\n**问题**：pnpm 安装依赖时报错\n\n**解决方案**：\n\n```bash\n# 清理缓存后重试\npnpm store prune\nrm -rf node_modules\npnpm install\n```\n\n### Rust 编译错误\n\n**问题**：cargo 编译时出现版本不兼容错误\n\n**解决方案**：\n\n```bash\n# 更新 Rust 工具链\nrustup update\nrustup upgrade\n\n# 清理编译缓存\ncargo clean\ncargo build\n```\n\n### 数据库连接失败\n\n**问题**：后端服务启动时无法连接数据库\n\n**解决方案**：\n\n1. 检查 PostgreSQL 服务是否运行\n2. 验证 `DATABASE_URL` 环境变量配置\n3. 确认数据库用户权限\n\n```bash\n# 检查 PostgreSQL 状态\npg_isready -h localhost -p 5432\n\n# 测试数据库连接\npsql $DATABASE_URL -c \"SELECT 1;\"\n```\n\n## 验证安装\n\n完成以上步骤后，可以通过以下方式验证环境搭建是否成功：\n\n1. **后端服务验证**：访问 `http://localhost:8080/health`\n2. **前端应用验证**：访问 `http://localhost:3000`\n3. **API 文档**：访问 `http://localhost:8080/docs`（如果启用 Swagger）\n\n所有验证通过后，即可开始 Vibe Kanban 的开发工作。\n\n---\n\n\n\n## 看板任务管理\n\n### 相关页面\n\n相关主题：[工作区管理与执行](#workspace-management), [编码代理集成](#coding-agents)\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [rust-toolchain.toml](https://github.com/BloopAI/vibe-kanban/blob/main/rust-toolchain.toml)\n- [pnpm-workspace.yaml](https://github.com/BloopAI/vibe-kanban/blob/main/pnpm-workspace.yaml)\n- [docs/self-hosting/local-development.mdx](https://github.com/BloopAI/vibe-kanban/blob/main/docs/self-hosting/local-development.mdx)\n- [local-build.sh](https://github.com/BloopAI/vibe-kanban/blob/main/local-build.sh)\n\n
\n\n# 看板任务管理\n\n## 概述\n\n看板任务管理是 Vibe Kanban 系统的核心功能模块，旨在帮助软件工程师高效地规划、分配和跟踪编码任务。该系统通过直观的看板界面将传统项目管理方法与现代 AI 编码代理能力相结合，支持从任务创建到工作区执行的全流程管理。\n\n看板任务管理的核心概念包括：\n\n- **Issue（问题/任务）**：系统中的基本工作单元\n- **Project（项目）**：包含多个相关 Issue 的容器\n- **Status（状态）**：Issue 在看板中的流转阶段\n- **Workspace（工作区）**：用于执行任务的隔离环境\n\n## 数据模型\n\n### Issue 类型定义\n\nIssue 是看板任务管理的基础单元。在 `crates/api-types/src/issue.rs` 中定义了完整的数据结构：\n\n```rust\npub struct Issue {\n pub id: String,\n pub project_id: String,\n pub simple_id: String, // 人类可读的短 ID\n pub title: String, // 任务标题\n pub description: Option相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/api-types/src/issue.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/api-types/src/issue.rs)\n- [crates/api-types/src/issue_tag.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/api-types/src/issue_tag.rs)\n- [crates/api-types/src/project.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/api-types/src/project.rs)\n- [crates/db/src/models/task.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/db/src/models/task.rs)\n- [packages/ui/src/components/KanbanBoard.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/ui/src/components/KanbanBoard.tsx)\n- [packages/web-core/src/pages/kanban/LocalProjectKanban.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/pages/kanban/LocalProjectKanban.tsx)\n\n
\n\n# 工作区管理与执行\n\n## 概述\n\n工作区（Workspace）是 Vibe Kanban 系统中用于运行编码代理的核心执行单元。每个工作区为 AI 代理提供独立的 Git 分支、终端环境和开发服务器，使团队能够通过看板任务规划和执行编码工作。\n\n工作区管理涵盖工作区的创建、状态追踪、进程执行以及与编码会话的关联。系统支持多工作区并行运行，并提供统一的用户界面用于工作区切换、状态监控和结果查看。\n\n资料来源：[README.md]()\n\n## 核心数据模型\n\n### Workspace 数据结构\n\n工作区包含以下关键属性，用于追踪和管理执行状态：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| id | string | 工作区唯一标识符 |\n| name | string | 工作区显示名称 |\n| branch | string | 关联的 Git 分支名称 |\n| isArchived | boolean | 是否已归档 |\n| isRunning | boolean | 当前是否正在运行 |\n| isPinned | boolean | 是否被固定显示 |\n| filesChanged | number | 修改的文件数量 |\n| linesAdded | number | 新增代码行数 |\n| linesRemoved | number | 删除代码行数 |\n| hasPendingApproval | boolean | 是否有待审批内容 |\n| hasRunningDevServer | boolean | 开发服务器是否运行中 |\n| hasUnseenActivity | boolean | 是否有未读活动 |\n| latestProcessCompletedAt | Date | 最近进程完成时间 |\n| latestProcessStatus | string | 最近进程状态 |\n| prStatus | object | Pull Request 状态信息 |\n\n资料来源：[packages/ui/src/components/WorkspacesSidebar.tsx:35-48]()\n\n### Session 会话模型\n\n每个工作区可关联一个编码会话，会话记录代理执行的上下文和结果：\n\n| 属性 | 说明 |\n|------|------|\n| filesChanged | 会话期间修改的文件数 |\n| linesAdded | 新增代码行数 |\n| linesRemoved | 删除代码行数 |\n\n资料来源：[packages/ui/src/components/SessionChatBox.tsx:89-92]()\n\n## 工作区选择与创建\n\n### 工作区选择对话框\n\n`WorkspaceSelectionDialog` 提供命令面板式的工作区选择界面，支持搜索、分页和新建工作区功能。\n\n**组件层级结构：**\n\n```\nWorkspaceSelectionDialog\n├── CommandDialog (cmdk 库)\n│ └── Command\n│ ├── CommandInput (搜索输入)\n│ ├── CommandList\n│ │ ├── CommandEmpty (无结果提示)\n│ │ ├── CommandGroup (新建工作区选项)\n│ │ │ └── CommandItem (__create_new__)\n│ │ └── CommandGroup (可用工作区列表)\n│ │ └── CommandItem (各工作区)\n│ └── CommandList (分页计数显示)\n└── WorkspaceSelectionWithContext (Context 包装器)\n ├── UserProvider\n └── ProjectProvider\n```\n\n**工作区显示逻辑：**\n\n```typescript\n// 搜索值格式包含 ID、名称、分支和归档状态\nvalue={`${workspace.id} ${workspace.name} ${workspace.branch}${workspace.isArchived ? ' archived' : ''}`}\n```\n\n资料来源：[packages/web-core/src/shared/dialogs/command-bar/WorkspaceSelectionDialog.tsx:20-60]()\n\n### 工作区过滤与搜索\n\n系统支持按名称和分支搜索工作区，采用分页加载机制：\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| PAGE_SIZE | 50 | 每页显示数量 |\n| isSearching | boolean | 是否处于搜索模式 |\n\n搜索时显示所有匹配结果，非搜索模式下超过 PAGE_SIZE 时显示分页提示。\n\n资料来源：[packages/web-core/src/shared/dialogs/command-bar/WorkspaceSelectionDialog.tsx:65-72]()\n\n## 工作区侧边栏\n\n### 布局模式\n\n工作区侧边栏支持两种布局模式，可在 `useUiPreferencesStore` 中管理：\n\n| 模式 | 说明 |\n|------|------|\n| workspaces | 工作区列表视图 |\n| kanban | 看板视图 |\n| accordion | 可折叠分组视图 |\n\n资料来源：[packages/web-core/src/shared/stores/useUiPreferencesStore.ts:42-48]()\n\n### 工作区状态指示\n\n侧边栏通过 `WorkspaceSummary` 组件展示每个工作区的综合状态：\n\n- **活跃状态**: `isActive` 标识当前选中的工作区\n- **运行状态**: `isRunning` 显示代理是否正在执行\n- **审批状态**: `hasPendingApproval` 标记待审批内容\n- **活动通知**: `hasUnseenActivity` 提示未读更新\n\n资料来源：[packages/ui/src/components/WorkspacesSidebar.tsx:20-50]()\n\n### 归档工作区展示\n\n归档的工作区显示在独立区域，通过 `isArchived` 属性区分：\n\n```typescript\n{workspace.isArchived && (\n \n ({t('workspaces.archived').toLowerCase()})\n \n)}\n```\n\n归档工作区列表为空时显示友好提示文本。\n\n资料来源：[packages/ui/src/components/WorkspacesSidebar.tsx:14-30]()\n\n## 进程管理与执行\n\n### 进程标签页\n\n`ProcessesTab` 组件展示工作区内的执行进程历史：\n\n**显示信息包括：**\n\n- 进程启动时间 (`started_at`)\n- 进程完成时间 (`completed_at`)\n- 进程日志输出\n\n**操作功能：**\n\n- 复制日志: `handleCopyLogs` 处理日志复制到剪贴板\n- 查看详情: `setSelectedProcessId` 选择特定进程查看\n\n```typescript\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/web-core/src/shared/dialogs/command-bar/WorkspaceSelectionDialog.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/dialogs/command-bar/WorkspaceSelectionDialog.tsx)\n- [packages/ui/src/components/WorkspacesSidebar.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/ui/src/components/WorkspacesSidebar.tsx)\n- [packages/web-core/src/shared/components/tasks/TaskDetails/ProcessesTab.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/components/tasks/TaskDetails/ProcessesTab.tsx)\n- [packages/web-core/src/shared/stores/useUiPreferencesStore.ts](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/stores/useUiPreferencesStore.ts)\n- [packages/ui/src/components/SessionChatBox.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/ui/src/components/SessionChatBox.tsx)\n\n \n \n
\n```\n\n资料来源：[packages/web-core/src/shared/components/tasks/TaskDetails/ProcessesTab.tsx:50-80]()\n\n### 执行状态时间线\n\n每个进程的完整生命周期显示在界面中：\n\n```typescript\n\n {t('processes.started', { date: formatDate(process.started_at) })}\n {process.completed_at && (\n {t('processes.completed', { date: formatDate(process.completed_at) })}\n )}\n
\n```\n\n资料来源：[packages/web-core/src/shared/components/tasks/TaskDetails/ProcessesTab.tsx:75-85]()\n\n## 会话与工作区关联\n\n### 会话状态显示\n\n`SessionChatBox` 组件在会话界面展示当前工作区的执行摘要：\n\n| 指标 | 显示格式 | 颜色编码 |\n|------|----------|----------|\n| 文件变更数 | `+N files` | 默认文本色 |\n| 新增行数 | `+{linesAdded}` | 绿色 (text-success) |\n| 删除行数 | `-{linesRemoved}` | 红色 (text-error) |\n\n```typescript\n\n {t('diff.filesChanged', { count: filesChanged })}\n {(linesAdded !== undefined || linesRemoved !== undefined) && (\n \n {linesAdded !== undefined && (\n +{linesAdded}\n )}\n {linesRemoved !== undefined && (\n -{linesRemoved}\n )}\n \n )}\n\n```\n\n资料来源：[packages/ui/src/components/SessionChatBox.tsx:82-98]()\n\n### 代理图标与导航\n\n会话界面支持代理图标显示和消息导航：\n\n- 代理图标: `renderAgentIcon?.(agent, 'size-icon-xl')`\n- 消息导航: `TurnNavigationPopup` 组件用于跳转历史消息\n- Todo 进度: `TodoProgressPopup` 展示当前 Todo 状态\n\n资料来源：[packages/ui/src/components/SessionChatBox.tsx:103-125]()\n\n## 工作区偏好设置\n\n### UI 状态持久化\n\n`useUiPreferencesStore` 管理工作区相关的 UI 状态：\n\n| 状态键 | 类型 | 用途 |\n|--------|------|------|\n| paneSizes | object | 面板尺寸配置 |\n| collapsedPaths | object | 文件树折叠状态 |\n| fileSearchRepoId | string | 文件搜索仓库 ID |\n| layoutMode | string | 当前布局模式 |\n| workspacePanelStates | object | 各工作区面板状态 |\n| mobileActiveTab | string | 移动端激活标签 |\n\n```typescript\ntoggleLayoutMode: () =>\n set((s) => ({\n layoutMode: s.layoutMode === 'workspaces' ? 'kanban' : 'workspaces',\n })),\n```\n\n资料来源：[packages/web-core/src/shared/stores/useUiPreferencesStore.ts:50-80]()\n\n### 文件树折叠状态持久化\n\n系统支持按工作区独立保存文件树折叠状态：\n\n```typescript\nexport function usePersistedCollapsedPaths(\n workspaceId: string | undefined\n): [Set\n
\n\n# 编码代理集成\n\n## 概述\n\nVibe Kanban 的编码代理集成（Coding Agent Integration）模块是该平台的核心功能之一，旨在为软件工程师提供与多种 AI 编码代理无缝协作的工作环境。该系统允许用户通过统一的界面管理、配置和切换不同的编码代理，在专用工作空间中执行代码任务，同时保持与项目看板（Kanban）的紧密集成。\n\n根据项目 README 说明，Vibe Kanban 已支持超过 **10 种编码代理**，包括：\n\n- Claude Code\n- Codex\n- Gemini CLI\n- GitHub Copilot\n- Amp\n- Cursor\n- OpenCode\n- Droid\n- CCR\n- Qwen Code\n\n资料来源：[README.md:32]()\n\n## 架构设计\n\n### 整体架构\n\nVibe Kanban 的编码代理集成采用模块化架构设计，核心组件位于 `crates/executors` 目录下的 Rust crate 中。该架构支持动态代理发现、多代理配置管理以及统一的执行接口。\n\n```mermaid\ngraph TD\n A[用户界面层相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/BloopAI/vibe-kanban/blob/main/README.md)\n- [packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx)\n- [packages/web-core/src/shared/keyboard/useWorkspaceShortcuts.ts](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/keyboard/useWorkspaceShortcuts.ts)\n- [packages/web-core/src/shared/dialogs/command-bar/WorkspaceSelectionDialog.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/dialogs/command-bar/WorkspaceSelectionDialog.tsx)\n- [packages/ui/src/components/CommandBar.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/ui/src/components/CommandBar.tsx)\n- [packages/ui/src/components/IssueCommentsSection.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/ui/src/components/IssueCommentsSection.tsx)\n- [crates/remote/src/db/issues.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/remote/src/db/issues.rs)\n\n> **注意**：本页面部分内容基于仓库结构的推断分析。由于仓库已宣布停止运营（sunsetting），部分执行器核心源码文件（如 `crates/executors/src/` 目录下的文件）未在当前检索上下文中完整获取。以下文档综合了 README 说明、UI 组件代码、以及已知的产品功能描述进行编写。\n\npackages/ui] --> B[Web Core 层
packages/web-core]\n B --> C[执行器抽象层
crates/executors]\n C --> D[Claude 执行器]\n C --> E[Codex 执行器]\n C --> F[其他执行器]\n G[配置文件
Profile] --> C\n H[工作空间状态
Workspace State] --> B\n```\n\n### 执行器模块结构\n\n根据仓库结构分析，执行器模块的主要组织方式如下：\n\n| 模块路径 | 说明 |\n|---------|------|\n| `crates/executors/src/lib.rs` | 执行器库入口，定义公共 API |\n| `crates/executors/src/executor_discovery.rs` | 动态发现机制，支持运行时检测可用代理 |\n| `crates/executors/src/profile.rs` | 执行器配置管理，存储用户偏好和代理参数 |\n| `crates/executors/src/executors/mod.rs` | 执行器通用抽象接口 |\n| `crates/executors/src/executors/claude/mod.rs` | Claude Code 专用执行器实现 |\n| `crates/executors/src/executors/codex/mod.rs` | Codex 专用执行器实现 |\n| `shared/schemas/claude_code.json` | Claude Code 通信协议 Schema |\n\n资料来源：[README.md:32]()\n\n## 配置管理\n\n### 执行器配置（Profile）\n\n每个编码代理都通过 Profile 配置进行管理。配置系统支持以下关键参数：\n\n| 配置项 | 类型 | 说明 |\n|-------|------|------|\n| `agent_type` | String | 代理类型标识符（如 `claude`, `codex`） |\n| `api_key` | String | API 认证密钥 |\n| `model` | String | 指定使用的模型版本 |\n| `temperature` | Float | 生成随机性控制参数 |\n| `max_tokens` | Integer | 单次响应最大 token 数 |\n| `custom_flags` | Object | 代理特定的额外参数 |\n\n配置存储通过 Zustand store `useUiPreferencesStore` 进行前端状态管理：\n\n```typescript\n// packages/web-core/src/shared/stores/useUiPreferencesStore.ts\ntoggleLayoutMode: () =>\n set((s) => ({\n layoutMode: s.layoutMode === 'workspaces' ? 'kanban' : 'workspaces',\n })),\n```\n\n资料来源：[packages/web-core/src/shared/stores/useUiPreferencesStore.ts:45]()\n\n### UI 配置选择器\n\n在用户界面中，代理和配置的选择通过 `AgentSelector` 和 `ConfigSelector` 组件实现。这些组件出现在工作空间创建和冲突解决对话框中：\n\n```typescript\n// packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx\n{profiles && createNewSession && (\n
\n
\n)}\n```\n\n资料来源：[packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx:85-96]()\n\n## 工作空间集成\n\n### 工作空间选择\n\n编码代理在特定的工作空间（Workspace）中执行。用户可以通过命令面板（Command Bar）或专用对话框选择代理的工作空间：\n\n```typescript\n// packages/web-core/src/shared/dialogs/command-bar/WorkspaceSelectionDialog.tsx\n{displayedWorkspaces.map((workspace) => (\n \n \n {t('processes.started', {\n date: formatDate(process.started_at),\n })}\n \n {process.completed_at && (\n \n {t('processes.completed', {\n date: formatDate(process.completed_at),\n })}\n \n )}\n
\n```\n\n支持的操作包括：\n\n| 功能 | 触发方式 | 说明 |\n|-----|---------|------|\n| 复制日志 | 按钮点击 | 将执行日志复制到剪贴板 |\n| 查看详情 | 列表项点击 | 显示特定进程的详细信息 |\n\n资料来源：[packages/web-core/src/shared/components/tasks/TaskDetails/ProcessesTab.tsx:1-50]()\n\n## 工单与评论集成\n\n### 评论系统\n\n编码代理的工作成果通过工单评论系统进行交流：\n\n```typescript\n// packages/ui/src/components/IssueCommentsSection.tsx\ninterface IssueCommentsSectionProps {\n comments: IssueCommentData[];\n commentInput: string;\n onCommentInputChange: (value: string) => void;\n onSubmitComment: () => void;\n editingCommentId: string | null;\n editingValue: string;\n onEditingValueChange: (value: string) => void;\n onStartEdit: (commentId: string) => void;\n onSaveEdit: () => void;\n onCancelEdit: () => void;\n onDeleteComment: (id: string) => void;\n reactionsByCommentId: MapCreate Issue] --> B[规划任务
Plan Tasks]\n B --> C[创建工作空间
Create Workspace]\n C --> D[选择编码代理
Select Agent]\n D --> E[执行编码任务
Execute Tasks]\n E --> F{检查结果}\n F -->|有冲突| G[解决冲突
Resolve Conflicts]\n G --> D\n F -->|成功| H[审查 Diff
Review Diff]\n H --> I[创建 PR
Create PR]\n I --> J[合并代码
Merge]\n```\n\n## 平台状态说明\n\n根据项目 README 公告，**Vibe Kanban 项目已于近期宣布停止运营（sunsetting）**。相关公告可在 [vibekanban.com/blog/shutdown](https://www.vibekanban.com/blog/shutdown) 查看。\n\n资料来源：[README.md:1-10]()\n\n## 总结\n\nVibe Kanban 的编码代理集成系统通过以下核心机制实现与多种 AI 编码代理的无缝协作：\n\n1. **模块化执行器架构**：基于 Rust crate 的插件式设计，支持动态发现和加载不同的编码代理\n2. **统一配置管理**：Profile 系统提供灵活的代理参数配置能力\n3. **深度工作空间集成**：编码代理在隔离的工作空间中执行，与 Git 仓库和工单系统紧密关联\n4. **丰富的交互接口**：支持快捷键、命令面板、冲突解决对话框等多种交互方式\n5. **完整的进程监控**：提供进程状态追踪、日志管理和实时反馈机制\n\n---\n\n\n\n## 数据库模型与迁移\n\n### 相关页面\n\n相关主题：[系统架构总览](#architecture-overview), [本地 API 服务器](#api-server), [工作区管理与执行](#workspace-management)\n\n
\n
\n\n# 数据库模型与迁移\n\n## 概述\n\nVibe Kanban 项目采用 **Rust 后端 + SQLite 本地数据库** 的架构模式。数据库层位于 `crates/db` 目录，包含数据模型定义和数据库迁移脚本。项目的数据库设计遵循 Rust 生态系统的最佳实践，使用 Diesel ORM 框架进行数据库操作。\n\n项目的数据模型涵盖了核心业务实体：**Project（项目）**、**Workspace（工作空间）**、**Session（会话）** 以及相关的关联数据。前端通过 API 与后端进行数据交互，后端负责数据库的读写操作。\n\n---\n\n## 架构分层\n\n### 系统架构概览\n\n```graph TD\n subgraph 前端层[\"前端层 (React/TypeScript)\"]\n A[Web UI]\n B[状态管理 Store]\n C[API 客户端]\n end\n\n subgraph 后端层[\"后端层 (Rust/Axum)\"]\n D[API 路由]\n E[业务逻辑]\n F[数据库访问层]\n end\n\n subgraph 数据层[\"数据层 (SQLite)\"]\n G[数据库文件]\n H[迁移脚本]\n end\n\n A --> B\n B --> C\n C --> D\n D --> E\n E --> F\n F --> G\n F --> H\n```\n\n项目采用分层架构，数据层位于最底层。前端通过 REST API 与后端通信，后端使用 Diesel ORM 与 SQLite 数据库交互。\n\n---\n\n## 核心数据模型\n\n### 模型组织结构\n\n数据库模型文件位于 `crates/db/src/models/` 目录下，采用模块化设计：\n\n| 模块文件 | 主要职责 | 关键类型 |\n|----------|----------|----------|\n| `mod.rs` | 模块导出和聚合 | 模型 trait 定义 |\n| `project.rs` | 项目实体模型 | Project |\n| `workspace.rs` | 工作空间模型 | Workspace |\n| `session.rs` | 会话模型 | Session |\n\n资料来源：[crates/db/src/models/mod.rs]()\n\n### Project（项目）\n\n项目是 Vibe Kanban 中的顶级组织单元。一个项目包含多个工作空间，并关联特定的用户和配置信息。\n\n```\nProject {\n id: String, // 唯一标识符\n name: String, // 项目名称\n color: String, // 展示颜色（十六进制）\n created_at: DateTime, // 创建时间\n updated_at: DateTime, // 更新时间\n user_id: String, // 所属用户ID\n}\n```\n\n### Workspace（工作空间）\n\n工作空间代表一个编码代理的执行环境，与 Git 分支关联。每个工作空间有独立的状态跟踪。\n\n```\nWorkspace {\n id: String,\n name: String,\n project_id: String, // 关联项目ID\n branch: String, // Git 分支名\n is_archived: Boolean, // 是否归档\n is_running: Boolean, // 是否正在运行\n is_pinned: Boolean, // 是否固定\n files_changed: Integer, // 变更文件数\n lines_added: Integer, // 新增行数\n lines_removed: Integer, // 删除行数\n latest_process_status: Option相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/server/src/routes/oauth.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/server/src/routes/oauth.rs)\n- [packages/web-core/src/shared/stores/useWorkspaceDiffStore.ts](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/stores/useWorkspaceDiffStore.ts)\n- [packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx)\n- [packages/web-core/src/shared/hooks/useAzureAttachments.ts](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/hooks/useAzureAttachments.ts)\n- [packages/remote-web/src/pages/HomePage.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/remote-web/src/pages/HomePage.tsx)\n- [packages/ui/src/components/CommandBar.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/ui/src/components/CommandBar.tsx)\n\n
\n\n# 本地 API 服务器\n\n## 概述\n\nVibe Kanban 的本地 API 服务器是基于 Rust 构建的后端服务，负责处理前端应用与远程服务之间的通信、OAuth 认证流程、Workspace 生命周期管理以及会话状态维护。该服务器作为本地代理层，为 Web 前端提供统一的 API 接口，同时管理 GitHub 集成和项目数据同步。\n\n本地 API 服务器的核心职责包括：\n\n- 作为前端与远程后端之间的中间层，转发请求和响应\n- 处理 OAuth 2.0 认证流程，包括 GitHub CLI 认证\n- 管理 Workspace 的创建、更新和删除操作\n- 处理会话（Session）的创建、查询和状态同步\n- 提供文件系统操作和终端命令执行的桥接能力\n\n## 技术架构\n\n### 技术栈\n\n| 组件 | 技术选型 | 说明 |\n|------|----------|------|\n| 运行时 | Rust | 高性能、低内存占用的系统编程语言 |\n| Web 框架 | Axum | 基于 Tokio 异步运行时的高性能 Web 框架 |\n| 路由系统 | Tower Router | 模块化的路由中间件系统 |\n| 序列化 | Serde | 通用的序列化/反序列化框架 |\n| 异步运行时 | Tokio | Rust 异步运行时 |\n\n资料来源：[crates/server/src/lib.rs:1-50]()\n\n### 模块结构\n\n```mermaid\ngraph TD\n A[crates/server/src] --> B[main.rs - 入口点]\n A --> C[lib.rs - 库定义]\n A --> D[routes/ - 路由模块]\n A --> E[middleware/ - 中间件]\n \n D --> D1[mod.rs - 路由聚合]\n D --> D2[workspaces/ - Workspace 路由]\n D --> D3[sessions/ - 会话路由]\n D --> D4[oauth.rs - OAuth 路由]\n \n E --> E1[mod.rs - 中间件聚合]\n```\n\n## 核心模块\n\n### 主入口 (main.rs)\n\n`main.rs` 是服务器进程的启动入口，负责初始化日志系统、配置加载和 HTTP 服务器的绑定。服务器默认监听本地端口，支持配置化端口设置。\n\n主要启动流程：\n\n1. 解析命令行参数和配置文件\n2. 初始化日志记录器（支持结构和日志级别配置）\n3. 建立数据库连接池（如适用）\n4. 挂载所有路由模块\n5. 启动 HTTP 服务器监听\n\n### 路由模块 (routes/)\n\n#### 路由聚合 (routes/mod.rs)\n\n路由模块作为中央聚合点，将所有子路由统一注册到主路由器。该模块定义了基础路径前缀和共享的路由配置。\n\n#### Workspace 核心路由 (routes/workspaces/core.rs)\n\nWorkspace 路由是服务器最核心的功能模块之一，负责处理与编码代理工作区相关的所有 API 请求。\n\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/workspaces` | GET | 列出当前项目的所有 Workspace |\n| `/api/workspaces` | POST | 创建新的 Workspace |\n| `/api/workspaces/:id` | GET | 获取特定 Workspace 的详细信息 |\n| `/api/workspaces/:id` | PATCH | 更新 Workspace 配置 |\n| `/api/workspaces/:id` | DELETE | 删除 Workspace |\n| `/api/workspaces/:id/processes` | GET | 获取 Workspace 内运行中的进程 |\n\n资料来源：[crates/server/src/routes/workspaces/core.rs:1-100]()\n\n#### 会话路由 (routes/sessions/mod.rs)\n\n会话路由管理 Workspace 内的编码代理会话，包括会话创建、状态查询和日志获取。\n\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/workspaces/:id/sessions` | GET | 获取会话列表 |\n| `/api/workspaces/:id/sessions` | POST | 创建新会话 |\n| `/api/sessions/:sessionId` | GET | 获取会话详情 |\n| `/api/sessions/:sessionId/logs` | GET | 获取会话执行日志 |\n\n资料来源：[crates/server/src/routes/sessions/mod.rs:1-80]()\n\n#### OAuth 路由 (routes/oauth.rs)\n\nOAuth 路由处理 GitHub 认证流程的回掉逻辑。当用户完成 GitHub 授权后，GitHub 会重定向到本地服务器的回掉端点。\n\n```rust\nResponse::builder()\n .status(StatusCode::OK)\n .header(\"content-type\", \"text/html; charset=utf-8\")\n .body(body)\n .unwrap()\n```\n\nOAuth 流程包含以下步骤：\n\n1. 用户发起认证请求\n2. 服务器生成临时状态令牌\n3. 重定向到 GitHub 授权页面\n4. 用户授权后回调到本地服务器\n5. 服务器验证状态令牌并交换访问令牌\n6. 返回认证结果页面\n\n资料来源：[crates/server/src/routes/oauth.rs:1-50]()\n\n### 中间件模块 (middleware/)\n\n中间件模块提供了请求处理的横切关注点，包括：\n\n| 中间件 | 功能 |\n|--------|------|\n| 认证中间件 | 验证请求头中的 Bearer Token |\n| 日志中间件 | 记录请求路径、方法和响应时间 |\n| CORS 中间件 | 处理跨域资源共享策略 |\n| 错误处理中间件 | 统一格式化错误响应 |\n\n资料来源：[crates/server/src/middleware/mod.rs:1-60]()\n\n## 请求处理流程\n\n```mermaid\nsequenceDiagram\n participant Client as 前端客户端\n participant Server as 本地 API 服务器\n participant Remote as 远程后端服务\n \n Client->>Server: HTTP 请求\n Server->>Server: 中间件处理链\n Server->>Remote: 转发请求（添加认证头）\n Remote-->>Server: 远程响应\n Server->>Server: 响应转换/处理\n Server-->>Client: 处理后的响应\n```\n\n## 配置管理\n\n本地 API 服务器支持通过环境变量和配置文件进行配置：\n\n| 配置项 | 环境变量 | 默认值 | 说明 |\n|--------|----------|--------|------|\n| 服务器端口 | `PORT` | 8080 | HTTP 监听端口 |\n| 日志级别 | `RUST_LOG` | info | 日志详细程度 |\n| 远程 API 地址 | `REMOTE_API_URL` | - | 远程后端服务地址 |\n| 数据库连接 | `DATABASE_URL` | - | PostgreSQL 连接字符串 |\n\n## 错误处理\n\n服务器采用统一的错误响应格式：\n\n```json\n{\n \"error\": {\n \"code\": \"WORKSPACE_NOT_FOUND\",\n \"message\": \"指定的工作区不存在\",\n \"details\": {}\n }\n}\n```\n\n常见的错误码包括：\n\n| 错误码 | HTTP 状态码 | 描述 |\n|--------|-------------|------|\n| UNAUTHORIZED | 401 | 认证令牌无效或已过期 |\n| FORBIDDEN | 403 | 无权访问该资源 |\n| NOT_FOUND | 404 | 请求的资源不存在 |\n| VALIDATION_ERROR | 422 | 请求参数验证失败 |\n| INTERNAL_ERROR | 500 | 服务器内部错误 |\n\n## 与前端的集成\n\n前端通过以下方式与本地 API 服务器交互：\n\n1. **固定端口通信**：前端使用固定端口（如 8080）与本地服务器通信\n2. **相对路径代理**：前端请求通过相对路径自动转发到本地服务器\n3. **认证令牌传递**：Bearer Token 在请求头中传递\n4. **OAuth 弹窗**：GitHub 认证通过弹窗完成，结果回写到父窗口\n\n## 启动与部署\n\n### 开发环境启动\n\n```bash\ncd crates/server\ncargo run\n```\n\n### 生产环境构建\n\n```bash\ncargo build --release\n./target/release/vibe-kanban-server\n```\n\n### Docker 部署\n\n服务器支持 Docker 容器化部署，提供轻量级的隔离运行环境。\n\n## 安全考量\n\n- 所有与远程服务的通信使用 HTTPS\n- OAuth 令牌安全存储，不暴露在前端日志中\n- 速率限制防止 API 滥用\n- CORS 策略限制跨域请求来源\n\n---\n\n\n\n## 远程云服务架构\n\n### 相关页面\n\n相关主题：[本地 API 服务器](#api-server), [数据库模型与迁移](#database-models)\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/server/src/lib.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/server/src/lib.rs)\n- [crates/server/src/main.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/server/src/main.rs)\n- [crates/server/src/routes/mod.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/server/src/routes/mod.rs)\n- [crates/server/src/routes/workspaces/core.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/server/src/routes/workspaces/core.rs)\n- [crates/server/src/middleware/mod.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/server/src/middleware/mod.rs)\n- [crates/server/src/routes/sessions/mod.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/server/src/routes/sessions/mod.rs)\n\n
\n\n# 远程云服务架构\n\n## 概述\n\nVibe Kanban 的远程云服务架构为团队协作提供了基础设施支持，允许用户通过远程 Web 界面访问和管理项目。该架构涵盖了身份验证、文件附件、GitHub 集成以及组织管理等功能模块。\n\n根据仓库结构，远程服务主要由 `crates/server`（后端 Rust 服务）、`packages/remote-web`（远程 Web 前端）和 `packages/web-core`（共享核心组件）组成。这种模块化设计使得远程访问与企业内部部署可以共享核心业务逻辑。资料来源：[packages/web-core/src/shared/dialogs/auth/GhCliSetupDialog.tsx:1-50]()\n\n## 核心架构组件\n\n### 后端服务层\n\n后端服务采用 Rust 语言实现，提供高性能的 HTTP API 接口。主要包括以下模块：\n\n| 模块 | 职责 | 关键文件 |\n|------|------|----------|\n| oauth | OAuth 2.0 认证流程处理 | crates/server/src/routes/oauth.rs |\n| routes | HTTP 路由定义与请求处理 | crates/server/src/routes/mod.rs |\n| auth | 身份验证与授权逻辑 | crates/remote/src/auth/mod.rs |\n| github_app | GitHub App 集成 | crates/remote/src/github_app/mod.rs |\n| digest | 数据摘要与校验 | crates/remote/src/digest/mod.rs |\n\n资料来源：[crates/server/src/routes/oauth.rs:1-50]()\n\n### 前端访问层\n\n远程 Web 界面由 React 组件构建，提供用户交互界面。主要页面组件包括：\n\n```mermaid\ngraph TD\n A[HomePage] --> B[OrganizationSection]\n A --> C[ProjectCard]\n B --> D[Projects List]\n C --> E[Remote Connection]\n \n F[GhCliSetupDialog] --> G[GitHub CLI Setup]\n H[ResolveConflictsDialog] --> I[Git Merge Resolution]\n```\n\n资料来源：[packages/remote-web/src/pages/HomePage.tsx:1-100](), [packages/web-core/src/shared/dialogs/auth/GhCliSetupDialog.tsx:1-50]()\n\n## 身份验证系统\n\n### OAuth 认证流程\n\nOAuth 认证是远程服务访问的核心机制。当用户通过浏览器访问远程服务时，系统会显示一个确认页面让用户授权。资料来源：[crates/server/src/routes/oauth.rs:30-45]()\n\n```mermaid\nsequenceDiagram\n participant User\n participant Browser\n participant RemoteServer\n participant GitHub\n \n User->>Browser: 访问远程服务\n Browser->>RemoteServer: 请求授权\n RemoteServer->>GitHub: 重定向到 GitHub OAuth\n GitHub->>User: 显示授权页面\n User->>GitHub: 确认授权\n GitHub->>RemoteServer: 返回授权码\n RemoteServer->>Browser: 显示成功页面\n```\n\n认证成功后会返回以下 HTML 响应格式：\n\n```html\n\n 相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/server/src/routes/oauth.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/server/src/routes/oauth.rs)\n- [packages/web-core/src/shared/dialogs/auth/GhCliSetupDialog.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/dialogs/auth/GhCliSetupDialog.tsx)\n- [packages/remote-web/src/pages/HomePage.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/remote-web/src/pages/HomePage.tsx)\n- [packages/web-core/src/shared/hooks/useAzureAttachments.ts](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/hooks/useAzureAttachments.ts)\n- [packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx)\n\n ![](\"data:image/png;base64,{APP_ICON_BASE64}\")
\n
\n\n```\n\n资料来源：[crates/server/src/routes/oauth.rs:30-50]()\n\n### GitHub CLI 设置\n\n对于需要本地 GitHub CLI 集成的用户，系统提供了交互式设置流程。设置步骤包括：\n\n1. 检查 GitHub CLI 是否已安装\n2. 通过 Homebrew 安装（如需要）\n3. 完成身份验证\n\n资料来源：[packages/web-core/src/shared/dialogs/auth/GhCliSetupDialog.tsx:15-35]()\n\n## 文件附件系统\n\n远程服务支持 Azure Blob Storage 集成的文件上传功能。附件处理流程涉及多个状态转换：\n\n| 状态 | 描述 | 进度 |\n|------|------|------|\n| pending | 等待上传 | 0% |\n| uploading | 上传中 | 0-99% |\n| confirming | 确认中 | 100% |\n| completed | 上传完成 | - |\n| failed | 上传失败 | - |\n\n资料来源：[packages/web-core/src/shared/hooks/useAzureAttachments.ts:1-60]()\n\n附件上传完成后，系统会返回唯一标识符供后续引用，格式为 `attachment://{id}`。资料来源：[packages/web-core/src/shared/hooks/useAzureAttachments.ts:45-55]()\n\n## 组织与项目管理\n\n### 组织管理\n\n远程 Web 界面允许用户创建或加入组织，以便团队协作。组织管理界面显示了每个组织的名称和项目数量。资料来源：[packages/remote-web/src/pages/HomePage.tsx:60-90]()\n\n```mermaid\ngraph LR\n A[Organizations] -->|包含| B[Projects]\n B -->|包含| C[Workspaces]\n C -->|执行| D[AI Agents]\n```\n\n### 项目卡片组件\n\n每个项目通过 `ProjectCard` 组件展示，支持以下功能：\n\n- 显示项目基本信息（名称、颜色）\n- 远程主机连接管理\n- 快速访问项目工作区\n\n当缺少主机配置时，用户可以触发 `onRequireHost` 回调打开中继设置。资料来源：[packages/remote-web/src/pages/HomePage.tsx:120-160]()\n\n## Git 冲突解决\n\n远程服务提供了冲突解决对话框组件，支持以下功能：\n\n- 显示冲突文件列表（最多显示 5 个）\n- 提示更多冲突文件数量\n- 提供 Agent/Profile 选择器\n- 新会话创建选项\n\n资料来源：[packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx:80-110]()\n\n## 服务启动与配置\n\n后端服务入口点定义在 `crates/remote/src/main.rs`，负责初始化配置并启动 HTTP 服务器。服务支持环境变量配置，包括：\n\n- 数据库连接参数\n- Azure Storage 凭证\n- GitHub App 配置\n- OAuth 回调 URL\n\n资料来源：[crates/remote/src/main.rs:1-30]()\n\n## 安全考虑\n\n远程服务架构实现了多层安全机制：\n\n1. **OAuth 2.0 授权码流程**：防止令牌泄露\n2. **HTML 响应 Content-Type 头**：正确设置 `text/html; charset=utf-8` 资料来源：[crates/server/src/routes/oauth.rs:47-50]()\n3. **会话隔离**：每个远程连接独立管理\n4. **主机验证**：中继设置确保连接安全\n\n## 总结\n\nVibe Kanban 的远程云服务架构通过 Rust 后端和 React 前端的组合，实现了高效的远程协作能力。核心特性包括安全的 OAuth 认证、Azure 文件存储集成、GitHub App 集成以及组织级项目管理。该架构设计遵循了前端与后端分离的原则，同时通过共享的 `web-core` 包确保了本地和远程体验的一致性。\n\n---\n\n\n\n## MCP 服务器实现\n\n### 相关页面\n\n相关主题：[编码代理集成](#coding-agents), [看板任务管理](#kanban-management)\n\n\n
\n {message}
\nYou can close this tab and return to the app.
\n\n
\n\n# MCP 服务器实现\n\n## 概述\n\nMCP（Model Context Protocol）服务器是 Vibe Kanban 项目中用于扩展 AI 代理能力的核心组件。该模块允许外部编码代理通过标准化的 MCP 协议与 Vibe Kanban 系统进行交互，实现任务管理、工作区操作等功能。\n\n## 架构设计\n\n### 模块结构\n\nMCP 实现位于 `crates/mcp` 目录下，采用模块化设计：\n\n| 模块路径 | 功能说明 |\n|---------|---------|\n| `lib.rs` | MCP 服务器核心库定义和导出 |\n| `task_server/mod.rs` | 任务服务器主模块 |\n| `task_server/handler.rs` | 请求处理器实现 |\n| `task_server/tools/mod.rs` | 工具集定义和实现 |\n| `bin/vibe_kanban_mcp.rs` | 可执行入口文件 |\n\n### 核心组件\n\nMCP 服务器的核心组件包括：\n\n1. **服务器入口** - `vibe_kanban_mcp.rs` 作为独立的二进制程序运行\n2. **任务服务器** - 负责处理来自 AI 代理的请求\n3. **工具集** - 定义可用的工具和操作\n4. **请求处理器** - 路由和执行具体的工具调用\n\n## 任务服务器模块\n\n任务服务器（Task Server）是 MCP 服务器的核心实现，负责：\n\n- 接收并解析 MCP 协议请求\n- 管理会话状态\n- 执行工具调用\n- 返回标准化的响应\n\n### 请求处理流程\n\n```mermaid\ngraph TD\n A[MCP 请求] --> B[请求解析器]\n B --> C{请求类型}\n C -->|工具调用| D[工具调度器]\n C -->|资源请求| E[资源处理器]\n C -->|其他| F[错误处理]\n D --> G[执行工具]\n G --> H[结果序列化]\n H --> I[MCP 响应]\n E --> I\n F --> I\n```\n\n## 工具集\n\n工具集定义了 AI 代理可以执行的操作类型。具体工具实现位于 `task_server/tools/mod.rs`。\n\n### 工具分类\n\n| 类别 | 描述 | 典型操作 |\n|-----|------|---------|\n| 任务工具 | 看板任务管理 | 创建、更新、查询任务 |\n| 工作区工具 | 工作区操作 | 打开、关闭、状态查询 |\n| 文件工具 | 文件系统操作 | 读取、写入文件 |\n| Git 工具 | 版本控制操作 | 分支管理、提交操作 |\n\n## MCP 协议实现\n\n### 请求格式\n\nMCP 服务器遵循 Model Context Protocol 规范，请求包含：\n\n- `jsonrpc` - JSON-RPC 版本标识\n- `method` - 方法名称\n- `params` - 参数字典\n- `id` - 请求标识符\n\n### 响应格式\n\n标准响应格式：\n\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"result\": { ... },\n \"id\": \"请求标识符\"\n}\n```\n\n错误响应格式：\n\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"error\": {\n \"code\": \"错误代码\",\n \"message\": \"错误描述\"\n },\n \"id\": \"请求标识符\"\n}\n```\n\n## 配置与部署\n\n### 二进制入口\n\n`crates/mcp/src/bin/vibe_kanban_mcp.rs` 文件定义了可执行程序的入口点：\n\n- 初始化日志系统\n- 加载配置\n- 启动 MCP 服务器\n- 处理生命周期事件\n\n### 配置项\n\n| 配置项 | 说明 | 默认值 |\n|-------|------|-------|\n| 服务器端口 | MCP 服务监听端口 | 随机可用端口 |\n| 日志级别 | 日志详细程度 | info |\n| 超时设置 | 请求处理超时时间 | 30秒 |\n\n## 与前端交互\n\nMCP 服务器作为后端服务，与前端通过 WebSocket 或 HTTP 协议通信。前端组件（如 `CommandBar.tsx` 和 `SessionChatBox.tsx`）提供用户界面，通过这些协议与 MCP 服务器交换数据。\n\n### 数据流\n\n```mermaid\ngraph LR\n A[AI 代理] -->|MCP 协议| B[MCP 服务器]\n B -->|内部 API| C[Vibe Kanban 后端]\n C -->|数据| B\n B -->|MCP 响应| A\n D[前端 UI] -->|WebSocket| B\n```\n\n## 安全性\n\nMCP 服务器实现包含以下安全措施：\n\n1. **请求验证** - 验证所有传入请求的格式和来源\n2. **权限控制** - 基于会话的权限检查\n3. **输入清理** - 防止注入攻击\n4. **超时保护** - 防止资源耗尽攻击\n\n## 扩展指南\n\n### 添加新工具\n\n在 `task_server/tools/mod.rs` 中添加新的工具定义：\n\n1. 定义工具的结构体\n2. 实现工具的 `execute` 方法\n3. 在工具注册表中添加新工具\n4. 添加相应的测试用例\n\n### 注册新处理器\n\n在 `task_server/handler.rs` 中扩展请求处理逻辑：\n\n1. 添加新的处理器函数\n2. 更新路由逻辑\n3. 注册处理程序到服务器\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：BloopAI/vibe-kanban\n\n摘要：发现 19 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：Deployment(Other(Migration failed: error returned from database: (code: 1) no such column: ep.session_id))。\n\n## 1. 安装坑 · 来源证据：Deployment(Other(Migration failed: error returned from database: (code: 1) no such column: ep.session_id))\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Deployment(Other(Migration failed: error returned from database: (code: 1) no such column: ep.session_id))\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b34b2ea1b35a4dc2a4a0eb0681bdb883 | https://github.com/BloopAI/vibe-kanban/issues/2972 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 2. 配置坑 · 来源证据：Support for self-hosted projects and better export\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Support for self-hosted projects and better export\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_19d27caa9e34416a9f282869f76624b0 | https://github.com/BloopAI/vibe-kanban/issues/3396 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安全/权限坑 · 来源证据：[Proposal] JIRA Integration for Vibe Kanban\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Proposal] JIRA Integration for Vibe Kanban\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ab38fe97c4574e2da01ddedd71a4fbac | https://github.com/BloopAI/vibe-kanban/issues/2424 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：Pre-release v0.1.40-20260401153532\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Pre-release v0.1.40-20260401153532\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f4b99d437a4f4fd4989d2b3ef036553b | https://github.com/BloopAI/vibe-kanban/releases/tag/v0.1.40-20260401153532 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：Release v0.1.36\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.1.36\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_527645be4e3f438e81757ef265a70d79 | https://github.com/BloopAI/vibe-kanban/releases/tag/v0.1.36-20260323174633 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：Release v0.1.43\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.1.43\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_53704dc7171446fe86b2017f72212ddc | https://github.com/BloopAI/vibe-kanban/releases/tag/v0.1.43-20260417125614 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 7. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | host_targets=claude, claude_code\n\n## 8. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | README/documentation is current enough for a first validation pass.\n\n## 9. 运行坑 · 来源证据：Pre-release v0.1.39-20260331145823\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Pre-release v0.1.39-20260331145823\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c005a56959634369929ce33eddbdc103 | https://github.com/BloopAI/vibe-kanban/releases/tag/v0.1.39-20260331145823 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 10. 维护坑 · 来源证据：[Request] Support RDS for self hosting in AWS\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[Request] Support RDS for self hosting in AWS\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f613b792c20942519560c0a286a82005 | https://github.com/BloopAI/vibe-kanban/issues/3405 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | last_activity_observed missing\n\n## 12. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：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.\n\n## 14. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 来源证据：Issue: Unclear Git + Bitbucket Setup for Vibe-Kanban (OpenCode) in Docker\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Issue: Unclear Git + Bitbucket Setup for Vibe-Kanban (OpenCode) in Docker\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7d289a7b68ee4299ae4a5e54b0e64e35 | https://github.com/BloopAI/vibe-kanban/issues/3410 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：Pre-release v0.1.37-20260327101540\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Pre-release v0.1.37-20260327101540\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d648fba4c94b4791ac2e7683f6cb1361 | https://github.com/BloopAI/vibe-kanban/releases/tag/v0.1.37-20260327101540 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：remote-v0.1.26\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：remote-v0.1.26\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3f212752e8c142d68ffe2993ac23dd37 | https://github.com/BloopAI/vibe-kanban/releases/tag/remote-v0.1.26 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 18. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | issue_or_pr_quality=unknown\n\n## 19. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | release_recency=unknown\n\n\n",
"markdown_key": "vibe-kanban",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1002125012",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/BloopAI/vibe-kanban"
},
{
"evidence_id": "art_f7a8f562234649b7b40da7395ba0ea47",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/BloopAI/vibe-kanban#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "vibe-kanban 说明书",
"toc": [
"https://github.com/BloopAI/vibe-kanban 项目说明书",
"目录",
"项目介绍与安装",
"项目概述",
"核心功能",
"支持的编码代理",
"技术架构",
"安装指南",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "4deb7eca8f381f7cbc1f9d15515a9ab8f8009053",
"repo_inspection_error": null,
"repo_inspection_files": [
"pnpm-lock.yaml",
"Dockerfile",
"package.json",
"README.md",
"docs/AGENTS.md",
"docs/troubleshooting.mdx",
"docs/browser-testing.mdx",
"docs/reviewing-code.mdx",
"docs/issue-management.mdx",
"docs/getting-started.mdx",
"docs/CLAUDE.md",
"docs/supported-coding-agents.mdx",
"docs/index.mdx",
"docs/README.md",
"docs/docs.json",
"docs/frontend-ui-library-refactor-audit.md",
"docs/remote-access.mdx",
"docs/responsible-disclosure.mdx",
"docs/settings/general.mdx",
"docs/settings/remote-projects.mdx",
"docs/settings/agent-configurations.mdx",
"docs/settings/organization-settings.mdx",
"docs/settings/index.mdx",
"docs/settings/creating-task-tags.mdx",
"docs/settings/mcp-servers.mdx",
"docs/settings/projects-repositories.mdx",
"docs/workspaces/changes.mdx",
"docs/workspaces/slash-commands.mdx",
"docs/workspaces/managing-workspaces.mdx",
"docs/workspaces/multi-repo-sessions.mdx",
"docs/workspaces/repositories.mdx",
"docs/workspaces/git-operations.mdx",
"docs/workspaces/index.mdx",
"docs/workspaces/command-bar.mdx",
"docs/workspaces/interface.mdx",
"docs/workspaces/chat-interface.mdx",
"docs/workspaces/creating-workspaces.mdx",
"docs/workspaces/sessions.mdx",
"docs/core-features/reviewing-code-changes.mdx",
"docs/core-features/new-task-attempts.mdx"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# vibe-kanban - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 vibe-kanban 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `npx vibe-kanban` 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`AGENTS.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`AGENTS.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0004` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0005` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：1897\n- 重要文件覆盖：40/1897\n- 证据索引条目：80\n- 角色 / Skill 条目：14\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 vibe-kanban 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 vibe-kanban 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 vibe-kanban 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 14 个角色 / Skill / 项目文档条目。\n\n- **Mintlify technical writing rule**（project_doc）：You are an AI writing assistant specialised in creating exceptional technical documentation using Mintlify components and following industry-leading technical writing practices. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/AGENTS.md`\n- **Mintlify Starter Kit**（project_doc）：Mintlify Quickstart Guide https://starter.mintlify.com/quickstart 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/README.md`\n- **Repository Guidelines**（project_doc）：Project Structure & Module Organization - crates/ : Rust workspace crates — server API + bins , db SQLx models/migrations , executors , services , utils , git Git operations , api-types shared API types for local + remote , review PR review tool , deployment , local-deployment , remote . - packages/local-web/ : Local React + TypeScript app entrypoint Vite, Tailwind . Shell source in packages/local-web/src . - packag… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`AGENTS.md`\n- **Overview**（project_doc）：Get 10X more out of Claude Code, Gemini CLI, Codex, Amp and other coding agents... 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Vibe Kanban**（project_doc）：A visual project management tool for developers that integrates with git repositories and coding agents like Claude Code and Amp. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`npx-cli/README.md`\n- **Remote Crate — Agent Guidelines**（project_doc）：The remote crate is the hosted Vibe Kanban Cloud server: an Axum HTTP API, a React SPA frontend, and real-time sync via ElectricSQL. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`crates/remote/AGENTS.md`\n- **New Design System Styling Guidelines**（project_doc）：New Design System Styling Guidelines 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/local-web/AGENTS.md`\n- **@vibe/ui**（project_doc）：Shared UI package for reusable web app primitives. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/ui/README.md`\n- **Relay Test Client**（project_doc）：Standalone browser client for testing relay path routing without modifying the Remote frontend UX. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`scripts/relay-test-client/README.md`\n- **Frontend UI Package Refactor Audit**（project_doc）：- Source audited: packages/local-web/src/components/ / .tsx - Total components: 280 - Objective: identify what should move first into a new pnpm UI library package. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/frontend-ui-library-refactor-audit.md`\n- **Contributor Covenant Code of Conduct**（project_doc）：Contributor Covenant Code of Conduct 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CODE-OF-CONDUCT.md`\n- **Contributing & Change Control**（project_doc）：All changes to production code are governed by formal change control procedures. These procedures ensure that modifications are reviewed, approved, and deployed in a controlled manner. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTORS.md`\n- **Testing on Mobile Devices**（project_doc）：This guide explains how to access the remote-web frontend from a phone iPhone/Android for UI testing. It uses Tailscale https://tailscale.com for stable networking and HTTPS certificates, and Caddy https://caddyserver.com as a reverse proxy — no custom IPs, no random URLs, works on any network. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`mobile-testing.md`\n- **Init Prompt**（project_doc）：Generate a file named AGENTS.md that serves as a contributor guide for this repository. Your goal is to produce a clear, concise, and well-structured document with descriptive headings and actionable explanations for each section. Follow the outline below, but adapt as needed — add sections if relevant, and omit those that do not apply to this project. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`crates/executors/src/executors/codex/init_prompt.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **Mintlify technical writing rule**（documentation）：You are an AI writing assistant specialised in creating exceptional technical documentation using Mintlify components and following industry-leading technical writing practices. 证据：`docs/AGENTS.md`\n- **Mintlify Starter Kit**（documentation）：Mintlify Quickstart Guide https://starter.mintlify.com/quickstart 证据：`docs/README.md`\n- **Repository Guidelines**（documentation）：Project Structure & Module Organization - crates/ : Rust workspace crates — server API + bins , db SQLx models/migrations , executors , services , utils , git Git operations , api-types shared API types for local + remote , review PR review tool , deployment , local-deployment , remote . - packages/local-web/ : Local React + TypeScript app entrypoint Vite, Tailwind . Shell source in packages/local-web/src . - packages/remote-web/ : Remote deployment frontend entrypoint. - packages/web-core/ : Shared React + TypeScript frontend library used by local + remote web packages/web-core/src . - shared/ : Generated TypeScript types shared/types.ts , shared/remote-types.ts and agent tool schemas shar… 证据：`AGENTS.md`\n- **Overview**（documentation）：Get 10X more out of Claude Code, Gemini CLI, Codex, Amp and other coding agents... 证据：`README.md`\n- **Vibe Kanban**（documentation）：A visual project management tool for developers that integrates with git repositories and coding agents like Claude Code and Amp. 证据：`npx-cli/README.md`\n- **Remote Crate — Agent Guidelines**（documentation）：The remote crate is the hosted Vibe Kanban Cloud server: an Axum HTTP API, a React SPA frontend, and real-time sync via ElectricSQL. 证据：`crates/remote/AGENTS.md`\n- **New Design System Styling Guidelines**（documentation）：New Design System Styling Guidelines 证据：`packages/local-web/AGENTS.md`\n- **@vibe/ui**（documentation）：Shared UI package for reusable web app primitives. 证据：`packages/ui/README.md`\n- **Relay Test Client**（documentation）：Standalone browser client for testing relay path routing without modifying the Remote frontend UX. 证据：`scripts/relay-test-client/README.md`\n- **Package**（package_manifest）：{ \"name\": \"vibe-kanban\", \"private\": false, \"version\": \"0.1.44\", \"main\": \"index.js\", \"bin\": { \"vibe-kanban\": \"bin/cli.js\" }, \"scripts\": { \"build\": \"esbuild src/cli.ts --bundle --platform=node --target=node20 --format=cjs --outfile=bin/cli.js --external:adm-zip --banner:js=\\\" !/usr/bin/env node\\\"\", \"check\": \"tsc --noEmit -p tsconfig.json\" }, \"keywords\": , \"author\": \"bloop\", \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/BloopAI/vibe-kanban\" }, \"engines\": { \"node\": \" =20.19.0\" }, \"license\": \"\", \"description\": \"NPX wrapper around vibe-kanban and vibe-kanban-mcp\", \"devDependencies\": { \"esbuild\": \"^0.27.2\" }, \"dependencies\": { \"adm-zip\": \"^0.5.16\", \"cac\": \"^7.0.0\" }, \"files\": \"bin\", \"d… 证据：`npx-cli/package.json`\n- **Package**（package_manifest）：{ \"name\": \"vibe-kanban\", \"version\": \"0.1.44\", \"private\": true, \"bin\": { \"vibe-kanban\": \"npx-cli/bin/cli.js\" }, \"files\": \"npx-cli/bin/cli.js\", \"npx-cli/dist/ \" , \"scripts\": { \"lint\": \"pnpm run local-web:lint && pnpm run ui:lint && pnpm run backend:lint && node scripts/check-unused-i18n-keys.mjs\", \"format\": \"pnpm run backend:format && pnpm run web-core:format && pnpm run local-web:format && pnpm run remote-web:format\", \"check\": \"pnpm run local-web:legacy-path-guard && pnpm run local-web:check && pnpm run remote-web:check && pnpm run web-core:check && pnpm run ui:check && pnpm run backend:check\", \"dev\": \"export FRONTEND PORT=$ node scripts/setup-dev-environment.js frontend && export BACKEND PO… 证据：`package.json`\n- **Package**（package_manifest）：{ \"name\": \"@vibe/local-web\", \"private\": true, \"version\": \"0.1.44\", \"type\": \"module\", \"scripts\": { \"dev\": \"VITE OPEN=${VITE OPEN:-false} vite\", \"build\": \"tsc && vite build\", \"check\": \"tsc --noEmit\", \"preview\": \"vite preview\", \"lint\": \"eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0\", \"lint:fix\": \"eslint . --ext ts,tsx --fix\", \"lint:i18n\": \"LINT I18N=true eslint . --ext ts,tsx --max-warnings 0\", \"format\": \"prettier --write \\\"src/ / .{ts,tsx,js,jsx,json,css,md}\\\"\", \"format:check\": \"prettier --check \\\"src/ / .{ts,tsx,js,jsx,json,css,md}\\\"\" }, \"dependencies\": { \"@codemirror/lang-json\": \"^6.0.2\", \"@codemirror/language\": \"^6.11.2\", \"@codemirror/lint\": \"^6.8.5\", \"@codemirr… 证据：`packages/local-web/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@vibe/remote-web\", \"private\": true, \"version\": \"0.1.0\", \"type\": \"module\", \"scripts\": { \"dev\": \"vite\", \"build\": \"tsc && vite build\", \"check\": \"tsc --noEmit\", \"preview\": \"vite preview\", \"format\": \"prettier --write \\\"src/ / .{ts,tsx,js,jsx,json,css,md}\\\"\", \"format:check\": \"prettier --check \\\"src/ / .{ts,tsx,js,jsx,json,css,md}\\\"\", \"migrate:structure\": \"node ../../scripts/migrate-remote-web-structure.mjs --apply\", \"migrate:structure:dry-run\": \"node ../../scripts/migrate-remote-web-structure.mjs\" }, \"dependencies\": { \"@ebay/nice-modal-react\": \"^1.2.13\", \"@phosphor-icons/react\": \"^2.1.10\", \"@tanstack/react-query\": \"^5.85.5\", \"@tanstack/react-router\": \"^1.161.1\", \"@tanstack/zod-adapter\"… 证据：`packages/remote-web/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@vibe/ui\", \"private\": true, \"version\": \"0.1.0\", \"type\": \"module\", \"scripts\": { \"check\": \"tsc --noEmit -p tsconfig.json\", \"lint\": \"eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0\", \"format\": \"prettier --config ../../packages/local-web/.prettierrc.json --write \\\"src/ / .{ts,tsx,js,jsx,json,md}\\\"\", \"format:check\": \"prettier --config ../../packages/local-web/.prettierrc.json --check \\\"src/ / .{ts,tsx,js,jsx,json,md}\\\"\" }, \"sideEffects\": false, \"exports\": { \"./components/ \": \"./src/components/ .tsx\", \"./lib/ \": \"./src/lib/ .ts\" }, \"dependencies\": { \"@ebay/nice-modal-react\": \"^1.2.13\", \"@tanstack/react-virtual\": \"^3.13.23\", \"@hello-pangea/dnd\": \"^18.0.1\", \"@le… 证据：`packages/ui/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@vibe/web-core\", \"private\": true, \"version\": \"0.1.18\", \"type\": \"module\", \"exports\": { \"./project-fallback-page\": \"./src/project-routes/ProjectFallbackPage.tsx\", \"./project-search\": \"./src/project-routes/project-search.ts\", \"./ \": \"./src/ \" }, \"dependencies\": { \"@codemirror/lang-json\": \"^6.0.2\", \"@codemirror/language\": \"^6.11.2\", \"@codemirror/lint\": \"^6.8.5\", \"@codemirror/view\": \"^6.38.1\", \"@dnd-kit/core\": \"^6.3.1\", \"@dnd-kit/sortable\": \"^10.0.0\", \"@dnd-kit/utilities\": \"^3.2.2\", \"@ebay/nice-modal-react\": \"^1.2.13\", \"@git-diff-view/file\": \"^0.0.30\", \"@git-diff-view/react\": \"^0.0.30\", \"@hello-pangea/dnd\": \"^18.0.1\", \"@lexical/code\": \"^0.36.2\", \"@lexical/link\": \"^0.36.2\", \"@lexical/l… 证据：`packages/web-core/package.json`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **Frontend UI Package Refactor Audit**（documentation）：- Source audited: packages/local-web/src/components/ / .tsx - Total components: 280 - Objective: identify what should move first into a new pnpm UI library package. 证据：`docs/frontend-ui-library-refactor-audit.md`\n- **Contributor Covenant Code of Conduct**（documentation）：Contributor Covenant Code of Conduct 证据：`CODE-OF-CONDUCT.md`\n- **Contributing & Change Control**（documentation）：All changes to production code are governed by formal change control procedures. These procedures ensure that modifications are reviewed, approved, and deployed in a controlled manner. 证据：`CONTRIBUTORS.md`\n- **Testing on Mobile Devices**（documentation）：This guide explains how to access the remote-web frontend from a phone iPhone/Android for UI testing. It uses Tailscale https://tailscale.com for stable networking and HTTPS certificates, and Caddy https://caddyserver.com as a reverse proxy — no custom IPs, no random URLs, works on any network. 证据：`mobile-testing.md`\n- **Init Prompt**（documentation）：Generate a file named AGENTS.md that serves as a contributor guide for this repository. Your goal is to produce a clear, concise, and well-structured document with descriptive headings and actionable explanations for each section. Follow the outline below, but adapt as needed — add sections if relevant, and omit those that do not apply to this project. 证据：`crates/executors/src/executors/codex/init_prompt.md`\n- **Config**（structured_config）：{ \"theme\": \"light\", \"executor\": { \"type\": \"claude\" }, \"disclaimer acknowledged\": true, \"onboarding acknowledged\": true, \"sound alerts\": true, \"sound file\": \"abstract-sound4\", \"push notifications\": true, \"editor\": { \"editor type\": \"VS CODE\", \"custom command\": null }, \"github\": { \"token\": \"\", \"default pr base\": \"main\" } } 证据：`dev_assets_seed/config.json`\n- **Docs**（structured_config）：{ \"$schema\": \"https://mintlify.com/docs.json\", \"theme\": \"mint\", \"name\": \"Vibe Kanban\", \"description\": \"A kanban board for developers to track coding tasks with AI coding agents\", \"appearance\": { \"default\": \"light\" }, \"colors\": { \"primary\": \" 000000\", \"light\": \" fefefe\", \"dark\": \" 121212\" }, \"background\": { \"color\": { \"light\": \" FAF9F5\", \"dark\": \" 2F2F2D\" } }, \"favicon\": \"/logo/v-192.png\", \"navigation\": { \"groups\": { \"group\": \"Getting started\", \"pages\": \"index\", \"getting-started\", \"browser-testing\", \"issue-management\", \"reviewing-code\", \"remote-access\", { \"group\": \"Supported Coding Agents\", \"expanded\": true, \"pages\": \"supported-coding-agents\", \"agents/claude-code\", \"agents/openai-codex\", \"ag… 证据：`docs/docs.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2020\", \"module\": \"ESNext\", \"moduleResolution\": \"bundler\", \"strict\": true, \"noUnusedLocals\": true, \"noUnusedParameters\": true, \"resolveJsonModule\": true, \"skipLibCheck\": true, \"noEmit\": true, \"types\": \"node\" }, \"include\": \"src\" } 证据：`npx-cli/tsconfig.json`\n- **Query 039C2290B6Cf7Cdc905C8Ddc44293F067Fe7E8F246Da737E4Baad3F494Ac8B8F**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"INSERT INTO execution processes \\n id, session id, run reason, executor action,\\n status, exit code, started at, completed at, created at, updated at\\n VALUES ?, ?, ?, ?, ?, ?, ?, ?, ?, ? \", \"describe\": { \"columns\": , \"parameters\": { \"Right\": 10 }, \"nullable\": }, \"hash\": \"039c2290b6cf7cdc905c8ddc44293f067fe7e8f246da737e4baad3f494ac8b8f\" } 证据：`crates/db/.sqlx/query-039c2290b6cf7cdc905c8ddc44293f067fe7e8f246da737e4baad3f494ac8b8f.json`\n- **Query 04C207Be2C3C2C07Ff42C695542504C358D67C1F40Ca2B1E75A396A90C173A53**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"SELECT eprs.after head commit\\n FROM execution process repo states eprs\\n JOIN execution processes ep ON ep.id = eprs.execution process id\\n WHERE ep.session id = $1\\n AND eprs.repo id = $2\\n AND ep.created at < SELECT created at FROM execution processes WHERE id = $3 \\n ORDER BY ep.created at DESC\\n LIMIT 1\", \"describe\": { \"columns\": { \"name\": \"after head commit\", \"ordinal\": 0, \"type info\": \"Text\" } , \"parameters\": { \"Right\": 3 }, \"nullable\": true }, \"hash\": \"04c207be2c3c2c07ff42c695542504c358d67c1f40ca2b1e75a396a90c173a53\" } 证据：`crates/db/.sqlx/query-04c207be2c3c2c07ff42c695542504c358d67c1f40ca2b1e75a396a90c173a53.json`\n- **Query 04F17449E3E12785Affab91E4Eab308103491E34C022199B7B060E04Fa8Aed0F**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"SELECT id as \\\"id!: Uuid\\\",\\n file path as \\\"file path!\\\",\\n original name as \\\"original name!\\\",\\n mime type,\\n size bytes as \\\"size bytes!\\\",\\n hash as \\\"hash!\\\",\\n created at as \\\"created at!: DateTime \\\",\\n updated at as \\\"updated at!: DateTime \\\"\\n FROM attachments\\n WHERE hash = $1\", \"describe\": { \"columns\": { \"name\": \"id!: Uuid\", \"ordinal\": 0, \"type info\": \"Blob\" }, { \"name\": \"file path!\", \"ordinal\": 1, \"type info\": \"Text\" }, { \"name\": \"original name!\", \"ordinal\": 2, \"type info\": \"Text\" }, { \"name\": \"mime type\", \"ordinal\": 3, \"type info\": \"Text\" }, { \"name\": \"size bytes!\", \"ordinal\": 4, \"type info\": \"Integer\" }, { \"name\": \"hash!\", \"ordinal\": 5, \"type… 证据：`crates/db/.sqlx/query-04f17449e3e12785affab91e4eab308103491e34c022199b7b060e04fa8aed0f.json`\n- **Query 0Ab07Fb562E61148F3F07F33F766Ea12C73D467Df4522240008370F681C8409A**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"UPDATE workspace repos\\n SET target branch = $1, updated at = datetime 'now' \\n WHERE target branch = $2\\n AND workspace id IN \\n SELECT w.id FROM workspaces w\\n JOIN tasks t ON w.task id = t.id\\n WHERE t.parent workspace id = $3\\n \", \"describe\": { \"columns\": , \"parameters\": { \"Right\": 3 }, \"nullable\": }, \"hash\": \"0ab07fb562e61148f3f07f33f766ea12c73d467df4522240008370f681c8409a\" } 证据：`crates/db/.sqlx/query-0ab07fb562e61148f3f07f33f766ea12c73d467df4522240008370f681c8409a.json`\n- **Query 0C7B20643F119Afd3E233105B0Fa2920E8E940Bdad86Cdc95D01E485A20D6Ed4**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"SELECT\\n ep.id as \\\"id!: Uuid\\\",\\n ep.session id as \\\"session id!: Uuid\\\",\\n ep.run reason as \\\"run reason!: ExecutionProcessRunReason\\\",\\n ep.executor action as \\\"executor action!: sqlx::types::Json \\\",\\n ep.status as \\\"status!: ExecutionProcessStatus\\\",\\n ep.exit code,\\n ep.dropped as \\\"dropped!: bool\\\",\\n ep.started at as \\\"started at!: DateTime \\\",\\n ep.completed at as \\\"completed at?: DateTime \\\",\\n ep.created at as \\\"created at!: DateTime \\\",\\n ep.updated at as \\\"updated at!: DateTime \\\"\\n FROM execution processes ep\\n JOIN sessions s ON ep.session id = s.id\\n WHERE s.workspace id = ? AND ep.run reason = ? AND ep.dropped = FALSE\\n ORDER BY ep.created a… 证据：`crates/db/.sqlx/query-0c7b20643f119afd3e233105b0fa2920e8e940bdad86cdc95d01e485a20d6ed4.json`\n- **Query 0Ee24D51E7557D9D6C9418A06156C03D7Dd49Dfe938194Cd6951942Dfd8F179D**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"DELETE FROM pull requests WHERE id = ?\", \"describe\": { \"columns\": , \"parameters\": { \"Right\": 1 }, \"nullable\": }, \"hash\": \"0ee24d51e7557d9d6c9418a06156c03d7dd49dfe938194cd6951942dfd8f179d\" } 证据：`crates/db/.sqlx/query-0ee24d51e7557d9d6c9418a06156c03d7dd49dfe938194cd6951942dfd8f179d.json`\n- **Query 11793C98A4Bee67Fce9972Ed6B10A18226E0455A0E8D113D04C4D5148B72Aec7**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"SELECT id as \\\"id!: Uuid\\\", tag name, content as \\\"content!\\\", created at as \\\"created at!: DateTime \\\", updated at as \\\"updated at!: DateTime \\\"\\n FROM tags\\n WHERE id = $1\", \"describe\": { \"columns\": { \"name\": \"id!: Uuid\", \"ordinal\": 0, \"type info\": \"Blob\" }, { \"name\": \"tag name\", \"ordinal\": 1, \"type info\": \"Text\" }, { \"name\": \"content!\", \"ordinal\": 2, \"type info\": \"Text\" }, { \"name\": \"created at!: DateTime \", \"ordinal\": 3, \"type info\": \"Text\" }, { \"name\": \"updated at!: DateTime \", \"ordinal\": 4, \"type info\": \"Text\" } , \"parameters\": { \"Right\": 1 }, \"nullable\": true, false, false, false, false }, \"hash\": \"11793c98a4bee67fce9972ed6b10a18226e0455a0e8d113d04c4d… 证据：`crates/db/.sqlx/query-11793c98a4bee67fce9972ed6b10a18226e0455a0e8d113d04c4d5148b72aec7.json`\n- **Query 12A5C0A8B95D8Cb87F1C869Ff35692A2Cee52Bc418B06D00A31A4C139E12D18A**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"\\n SELECT \\n ep.id as \\\"execution id!: Uuid\\\", \\n ep.session id as \\\"session id!: Uuid\\\"\\n FROM execution processes ep\\n WHERE EXISTS \\n SELECT 1 FROM execution process logs epl WHERE epl.execution id = ep.id\\n \\n \", \"describe\": { \"columns\": { \"name\": \"execution id!: Uuid\", \"ordinal\": 0, \"type info\": \"Blob\" }, { \"name\": \"session id!: Uuid\", \"ordinal\": 1, \"type info\": \"Blob\" } , \"parameters\": { \"Right\": 0 }, \"nullable\": true, false }, \"hash\": \"12a5c0a8b95d8cb87f1c869ff35692a2cee52bc418b06d00a31a4c139e12d18a\" } 证据：`crates/db/.sqlx/query-12a5c0a8b95d8cb87f1c869ff35692a2cee52bc418b06d00a31a4c139e12d18a.json`\n- **Query 13826Fc6Fdd367255Cb921640E5972F30905Ac7A81Ad477Cf8Bbcfc24F06F39B**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"\\n SELECT\\n ep.id as \\\"id!: Uuid\\\",\\n ep.session id as \\\"session id!: Uuid\\\",\\n ep.run reason as \\\"run reason!: ExecutionProcessRunReason\\\",\\n ep.executor action as \\\"executor action!: sqlx::types::Json \\\",\\n ep.status as \\\"status!: ExecutionProcessStatus\\\",\\n ep.exit code,\\n ep.dropped as \\\"dropped!: bool\\\",\\n ep.started at as \\\"started at!: DateTime \\\",\\n ep.completed at as \\\"completed at?: DateTime \\\",\\n ep.created at as \\\"created at!: DateTime \\\",\\n ep.updated at as \\\"updated at!: DateTime \\\"\\n FROM execution processes ep\\n JOIN sessions s ON ep.session id = s.id\\n WHERE s.workspace id = ?\\n AND ep.status = 'running'\\n AND ep.run reason = 'devserver'\\n O… 证据：`crates/db/.sqlx/query-13826fc6fdd367255cb921640e5972f30905ac7a81ad477cf8bbcfc24f06f39b.json`\n- **Query 1Af7A606A64D9662D6Edc4Fbeaae0D53A4D657A6E29B2561E820085A2D9E3348**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"SELECT\\n id,\\n workspace id AS \\\"workspace id: Uuid\\\",\\n repo id AS \\\"repo id: Uuid\\\",\\n pr url,\\n pr number,\\n pr status AS \\\"pr status: MergeStatus\\\",\\n target branch name,\\n merged at AS \\\"merged at: DateTime \\\",\\n merge commit sha,\\n created at AS \\\"created at!: DateTime \\\",\\n updated at AS \\\"updated at!: DateTime \\\",\\n synced at AS \\\"synced at: DateTime \\\"\\n FROM pull requests\\n WHERE synced at IS NULL OR synced at \", \"ordinal\": 7, \"type info\": \"Text\" }, { \"name\": \"merge commit sha\", \"ordinal\": 8, \"type info\": \"Text\" }, { \"name\": \"created at!: DateTime \", \"ordinal\": 9, \"type info\": \"Datetime\" }, { \"name\": \"updated at!: DateTime \", \"ordinal\": 10, \"type i… 证据：`crates/db/.sqlx/query-1af7a606a64d9662d6edc4fbeaae0d53a4d657a6e29b2561e820085a2d9e3348.json`\n- **Query 1B186Dc075846Fc1F7270A942Afbf82A88806Ee6Ababdb437Ab5E97Ddd2122Da**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"SELECT COUNT as \\\"count!: i64\\\"\\n FROM execution processes ep\\n WHERE ep.session id = $1\\n AND ep.status = 'running'\\n AND ep.run reason = 'codingagent'\", \"describe\": { \"columns\": { \"name\": \"count!: i64\", \"ordinal\": 0, \"type info\": \"Integer\" } , \"parameters\": { \"Right\": 1 }, \"nullable\": false }, \"hash\": \"1b186dc075846fc1f7270a942afbf82a88806ee6ababdb437ab5e97ddd2122da\" } 证据：`crates/db/.sqlx/query-1b186dc075846fc1f7270a942afbf82a88806ee6ababdb437ab5e97ddd2122da.json`\n- **Query 1C2201B0Ca9305283634Fe5C72Df6Eac3Ad954C1238088A84A4B9085B1Dbdb74**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"DELETE FROM workspaces WHERE id = $1\", \"describe\": { \"columns\": , \"parameters\": { \"Right\": 1 }, \"nullable\": }, \"hash\": \"1c2201b0ca9305283634fe5c72df6eac3ad954c1238088a84a4b9085b1dbdb74\" } 证据：`crates/db/.sqlx/query-1c2201b0ca9305283634fe5c72df6eac3ad954c1238088a84a4b9085b1dbdb74.json`\n- **Query 218F1D14C72148Ea88D75E816E1Ba111C8F4678A7E428B15462E6Dfc74C25B03**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"UPDATE tags\\n SET tag name = $2, content = $3, updated at = datetime 'now', 'subsec' \\n WHERE id = $1\\n RETURNING id as \\\"id!: Uuid\\\", tag name, content as \\\"content!\\\", created at as \\\"created at!: DateTime \\\", updated at as \\\"updated at!: DateTime \\\"\", \"describe\": { \"columns\": { \"name\": \"id!: Uuid\", \"ordinal\": 0, \"type info\": \"Blob\" }, { \"name\": \"tag name\", \"ordinal\": 1, \"type info\": \"Text\" }, { \"name\": \"content!\", \"ordinal\": 2, \"type info\": \"Text\" }, { \"name\": \"created at!: DateTime \", \"ordinal\": 3, \"type info\": \"Text\" }, { \"name\": \"updated at!: DateTime \", \"ordinal\": 4, \"type info\": \"Text\" } , \"parameters\": { \"Right\": 3 }, \"nullable\": true, false, false,… 证据：`crates/db/.sqlx/query-218f1d14c72148ea88d75e816e1ba111c8f4678a7e428b15462e6dfc74c25b03.json`\n- **Query 21C7A9F62322212A5F6B923Bb410C25Ac06E6A0C857D910D93Fb80Ab77Fc9B35**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"SELECT COUNT 1 AS \\\"count!: i64\\\" FROM pull requests WHERE workspace id = ? AND pr status = 'open'\", \"describe\": { \"columns\": { \"name\": \"count!: i64\", \"ordinal\": 0, \"type info\": \"Integer\" } , \"parameters\": { \"Right\": 1 }, \"nullable\": false }, \"hash\": \"21c7a9f62322212a5f6b923bb410c25ac06e6a0c857d910d93fb80ab77fc9b35\" } 证据：`crates/db/.sqlx/query-21c7a9f62322212a5f6b923bb410c25ac06e6a0c857d910d93fb80ab77fc9b35.json`\n- **Query 2547A5D06Fd3B17360Bff34A04B7D3D929C13Ef0D86395A9201834D8Fc955295**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"SELECT\\n cat.agent session id as \\\"session id!\\\",\\n cat.agent message id as \\\"message id\\\"\\n FROM execution processes ep\\n JOIN coding agent turns cat ON ep.id = cat.execution process id\\n WHERE ep.session id = $1\\n AND ep.run reason = 'codingagent'\\n AND ep.dropped = FALSE\\n AND cat.agent session id IS NOT NULL\\n ORDER BY ep.created at DESC\\n LIMIT 1\", \"describe\": { \"columns\": { \"name\": \"session id!\", \"ordinal\": 0, \"type info\": \"Text\" }, { \"name\": \"message id\", \"ordinal\": 1, \"type info\": \"Text\" } , \"parameters\": { \"Right\": 1 }, \"nullable\": true, true }, \"hash\": \"2547a5d06fd3b17360bff34a04b7d3d929c13ef0d86395a9201834d8fc955295\" } 证据：`crates/db/.sqlx/query-2547a5d06fd3b17360bff34a04b7d3d929c13ef0d86395a9201834d8fc955295.json`\n- **Query 256F9E937384933464E6D4D00Ee977Bbb2915Ef80930C8B5C0B0525367A5264D**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"UPDATE repos SET name = $1, display name = $2, updated at = datetime 'now', 'subsec' WHERE id = $3\", \"describe\": { \"columns\": , \"parameters\": { \"Right\": 3 }, \"nullable\": }, \"hash\": \"256f9e937384933464e6d4d00ee977bbb2915ef80930c8b5c0b0525367a5264d\" } 证据：`crates/db/.sqlx/query-256f9e937384933464e6d4d00ee977bbb2915ef80930c8b5c0b0525367a5264d.json`\n- **Query 2948Ec0606A39Ee67Bdbaf4F2Cf82592448A1D91A66D7D89Cf7204F71F706274**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"UPDATE pull requests SET pr status = ?, merged at = ?, merge commit sha = ?, updated at = ?, synced at = NULL WHERE pr url = ?\", \"describe\": { \"columns\": , \"parameters\": { \"Right\": 5 }, \"nullable\": }, \"hash\": \"2948ec0606a39ee67bdbaf4f2cf82592448a1d91a66d7d89cf7204f71f706274\" } 证据：`crates/db/.sqlx/query-2948ec0606a39ee67bdbaf4f2cf82592448a1d91a66d7d89cf7204f71f706274.json`\n- **Query 2A57B702E52B3Cc9Bdbc361267985958B11D4493B01A9Ab8Daedf5D951422897**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"UPDATE workspaces SET updated at = datetime 'now', 'subsec' WHERE id = ?\", \"describe\": { \"columns\": , \"parameters\": { \"Right\": 1 }, \"nullable\": }, \"hash\": \"2a57b702e52b3cc9bdbc361267985958b11d4493b01a9ab8daedf5d951422897\" } 证据：`crates/db/.sqlx/query-2a57b702e52b3cc9bdbc361267985958b11d4493b01a9ab8daedf5d951422897.json`\n- **Query 2B253F92Ac5Daa4864E7335Fde1B82625F504Fd73D19B21992497219A9C3170A**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"INSERT INTO repos id, path, name, display name \\n VALUES $1, $2, $3, $4 \\n ON CONFLICT path DO UPDATE SET updated at = updated at\\n RETURNING id as \\\"id!: Uuid\\\",\\n path,\\n name,\\n display name,\\n setup script,\\n cleanup script,\\n archive script,\\n copy files,\\n parallel setup script as \\\"parallel setup script!: bool\\\",\\n dev server script,\\n default target branch,\\n default working dir,\\n created at as \\\"created at!: DateTime \\\",\\n updated at as \\\"updated at!: DateTime \\\"\", \"describe\": { \"columns\": { \"name\": \"id!: Uuid\", \"ordinal\": 0, \"type info\": \"Blob\" }, { \"name\": \"path\", \"ordinal\": 1, \"type info\": \"Text\" }, { \"name\": \"name\", \"ordinal\": 2, \"type info\": \"… 证据：`crates/db/.sqlx/query-2b253f92ac5daa4864e7335fde1b82625f504fd73d19b21992497219a9c3170a.json`\n- **Query 2C0172D5B2C5Bff0914727A57983D5C336F5B2Dfa73Ca6C2Efa4Ea23Bb526E05**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"SELECT id as \\\"id!: Uuid\\\",\\n name,\\n default agent working dir,\\n remote project id as \\\"remote project id: Uuid\\\",\\n created at as \\\"created at!: DateTime \\\",\\n updated at as \\\"updated at!: DateTime \\\"\\n FROM projects\\n ORDER BY created at DESC\", \"describe\": { \"columns\": { \"name\": \"id!: Uuid\", \"ordinal\": 0, \"type info\": \"Blob\" }, { \"name\": \"name\", \"ordinal\": 1, \"type info\": \"Text\" }, { \"name\": \"default agent working dir\", \"ordinal\": 2, \"type info\": \"Text\" }, { \"name\": \"remote project id: Uuid\", \"ordinal\": 3, \"type info\": \"Blob\" }, { \"name\": \"created at!: DateTime \", \"ordinal\": 4, \"type info\": \"Text\" }, { \"name\": \"updated at!: DateTime \", \"ordinal\": 5, \"typ… 证据：`crates/db/.sqlx/query-2c0172d5b2c5bff0914727a57983d5c336f5b2dfa73ca6c2efa4ea23bb526e05.json`\n- **Query 2C71Bf4Dd5683E0Dedf2341E52880Ff2C0765659D3Cf53D62Faa54Adc91071Dd**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"SELECT w.name AS \\\"name: String\\\"\\n FROM workspaces w\\n JOIN workspace repos wr ON wr.workspace id = w.id\\n WHERE wr.repo id = $1\\n AND w.archived = FALSE\", \"describe\": { \"columns\": { \"name\": \"name: String\", \"ordinal\": 0, \"type info\": \"Text\" } , \"parameters\": { \"Right\": 1 }, \"nullable\": true }, \"hash\": \"2c71bf4dd5683e0dedf2341e52880ff2c0765659d3cf53d62faa54adc91071dd\" } 证据：`crates/db/.sqlx/query-2c71bf4dd5683e0dedf2341e52880ff2c0765659d3cf53d62faa54adc91071dd.json`\n- **Query 2Cb5A269045F23Da9F4Ee0Ee679Ccb7Fffc39D4B37B1B58357B11A7Abfdba125**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"UPDATE sessions SET executor = $1, updated at = CURRENT TIMESTAMP WHERE id = $2\", \"describe\": { \"columns\": , \"parameters\": { \"Right\": 2 }, \"nullable\": }, \"hash\": \"2cb5a269045f23da9f4ee0ee679ccb7fffc39d4b37b1b58357b11a7abfdba125\" } 证据：`crates/db/.sqlx/query-2cb5a269045f23da9f4ee0ee679ccb7fffc39d4b37b1b58357b11a7abfdba125.json`\n- **Query 31F4E685Fc0B1103Ff662B3866B3Bb422Cc7Fc8E0661Ebfed30Ffd16Ea7Ed8C0**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"SELECT id as \\\"id!: Uuid\\\",\\n workspace id as \\\"workspace id!: Uuid\\\",\\n repo id as \\\"repo id!: Uuid\\\",\\n target branch,\\n created at as \\\"created at!: DateTime \\\",\\n updated at as \\\"updated at!: DateTime \\\"\\n FROM workspace repos\\n WHERE workspace id = $1\", \"describe\": { \"columns\": { \"name\": \"id!: Uuid\", \"ordinal\": 0, \"type info\": \"Blob\" }, { \"name\": \"workspace id!: Uuid\", \"ordinal\": 1, \"type info\": \"Blob\" }, { \"name\": \"repo id!: Uuid\", \"ordinal\": 2, \"type info\": \"Blob\" }, { \"name\": \"target branch\", \"ordinal\": 3, \"type info\": \"Text\" }, { \"name\": \"created at!: DateTime \", \"ordinal\": 4, \"type info\": \"Text\" }, { \"name\": \"updated at!: DateTime \", \"ordinal\": 5,… 证据：`crates/db/.sqlx/query-31f4e685fc0b1103ff662b3866b3bb422cc7fc8e0661ebfed30ffd16ea7ed8c0.json`\n- **Query 3266B6A544952177F84E2E7C31Be9Dba212C92D91B997De7F6Aa811E08Ed6C72**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"SELECT\\n ep.id as \\\"id!: Uuid\\\",\\n ep.session id as \\\"session id!: Uuid\\\",\\n ep.run reason as \\\"run reason!: ExecutionProcessRunReason\\\",\\n ep.executor action as \\\"executor action!: sqlx::types::Json \\\",\\n ep.status as \\\"status!: ExecutionProcessStatus\\\",\\n ep.exit code,\\n ep.dropped as \\\"dropped!: bool\\\",\\n ep.started at as \\\"started at!: DateTime \\\",\\n ep.completed at as \\\"completed at?: DateTime \\\",\\n ep.created at as \\\"created at!: DateTime \\\",\\n ep.updated at as \\\"updated at!: DateTime \\\"\\n FROM execution processes ep\\n WHERE ep.session id = ? AND ep.run reason = ? AND ep.dropped = FALSE\\n ORDER BY ep.created at DESC LIMIT 1\", \"describe\": { \"columns\": {… 证据：`crates/db/.sqlx/query-3266b6a544952177f84e2e7c31be9dba212c92d91b997de7f6aa811e08ed6c72.json`\n- **Query 32C74A54Fdd72A6B167583228F2C30944837B7Cc29C9Cc4Acfbb4F047Cea7118**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"SELECT\\n id,\\n workspace id AS \\\"workspace id: Uuid\\\",\\n repo id AS \\\"repo id: Uuid\\\",\\n pr url,\\n pr number,\\n pr status AS \\\"pr status: MergeStatus\\\",\\n target branch name,\\n merged at AS \\\"merged at: DateTime \\\",\\n merge commit sha,\\n created at AS \\\"created at!: DateTime \\\",\\n updated at AS \\\"updated at!: DateTime \\\",\\n synced at AS \\\"synced at: DateTime \\\"\\n FROM pull requests\\n WHERE workspace id = $1 AND repo id = $2\\n ORDER BY created at DESC\", \"describe\": { \"columns\": { \"name\": \"id\", \"ordinal\": 0, \"type info\": \"Text\" }, { \"name\": \"workspace id: Uuid\", \"ordinal\": 1, \"type info\": \"Blob\" }, { \"name\": \"repo id: Uuid\", \"ordinal\": 2, \"type info\": \"Blob\" }… 证据：`crates/db/.sqlx/query-32c74a54fdd72a6b167583228f2c30944837b7cc29c9cc4acfbb4f047cea7118.json`\n- **Query 3634E2Bab8Fef106721Bb64A791Edd81D3D49Eb34Fbabd34E4Feadfb5F229A6E**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"SELECT id as \\\"id!: Uuid\\\",\\n container ref as \\\"container ref!\\\"\\n FROM workspaces\\n WHERE container ref IS NOT NULL\", \"describe\": { \"columns\": { \"name\": \"id!: Uuid\", \"ordinal\": 0, \"type info\": \"Blob\" }, { \"name\": \"container ref!\", \"ordinal\": 1, \"type info\": \"Text\" } , \"parameters\": { \"Right\": 0 }, \"nullable\": true, true }, \"hash\": \"3634e2bab8fef106721bb64a791edd81d3d49eb34fbabd34e4feadfb5f229a6e\" } 证据：`crates/db/.sqlx/query-3634e2bab8fef106721bb64a791edd81d3d49eb34fbabd34e4feadfb5f229a6e.json`\n- **Query 3A9148E9E914D644D4D82A1C2Dc8Bd0E093D4F4C638Afa7Fd8F5211892Fb6D84**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"DELETE FROM repos WHERE id = $1\", \"describe\": { \"columns\": , \"parameters\": { \"Right\": 1 }, \"nullable\": }, \"hash\": \"3a9148e9e914d644d4d82a1c2dc8bd0e093d4f4c638afa7fd8f5211892fb6d84\" } 证据：`crates/db/.sqlx/query-3a9148e9e914d644d4d82a1c2dc8bd0e093d4f4c638afa7fd8f5211892fb6d84.json`\n- **Query 3D34580933Bc02A168F4A7C483460A6Ad13Ef72B508532F5A6Cd5E53Aff04A69**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"\\n SELECT\\n workspace id as \\\"workspace id!: Uuid\\\",\\n execution process id as \\\"execution process id!: Uuid\\\",\\n session id as \\\"session id!: Uuid\\\",\\n status as \\\"status!: ExecutionProcessStatus\\\",\\n completed at as \\\"completed at?: DateTime \\\"\\n FROM \\n SELECT\\n s.workspace id,\\n ep.id as execution process id,\\n ep.session id,\\n ep.status,\\n ep.completed at,\\n ROW NUMBER OVER \\n PARTITION BY s.workspace id\\n ORDER BY ep.created at DESC\\n as rn\\n FROM execution processes ep\\n JOIN sessions s ON ep.session id = s.id\\n JOIN workspaces w ON s.workspace id = w.id\\n WHERE w.archived = $1\\n AND ep.run reason IN 'codingagent', 'setupscript', 'cleanupscript' \\n AN… 证据：`crates/db/.sqlx/query-3d34580933bc02a168f4a7c483460a6ad13ef72b508532f5a6cd5e53aff04a69.json`\n- **Query 3F4B2179Dcd8857Fc18F1E5F6E6Cf10F152Eebbb141B2D3604Dd4191E0C2F367**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"SELECT\\n ep.id as \\\"id!: Uuid\\\",\\n ep.session id as \\\"session id!: Uuid\\\",\\n ep.run reason as \\\"run reason!: ExecutionProcessRunReason\\\",\\n ep.executor action as \\\"executor action!: sqlx::types::Json \\\",\\n ep.status as \\\"status!: ExecutionProcessStatus\\\",\\n ep.exit code,\\n ep.dropped as \\\"dropped!: bool\\\",\\n ep.started at as \\\"started at!: DateTime \\\",\\n ep.completed at as \\\"completed at?: DateTime \\\",\\n ep.created at as \\\"created at!: DateTime \\\",\\n ep.updated at as \\\"updated at!: DateTime \\\"\\n FROM execution processes ep WHERE ep.id = ?\", \"describe\": { \"columns\": { \"name\": \"id!: Uuid\", \"ordinal\": 0, \"type info\": \"Blob\" }, { \"name\": \"session id!: Uuid\", \"or… 证据：`crates/db/.sqlx/query-3f4b2179dcd8857fc18f1e5f6e6cf10f152eebbb141b2d3604dd4191e0c2f367.json`\n- **Query 420A0C490F1E4D549Fb194265E971D8C03B86Fe75B595091F6425De11D120A6B**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"UPDATE execution processes\\n SET dropped = TRUE\\n WHERE session id = $1\\n AND created at = SELECT created at FROM execution processes WHERE id = $2 \\n AND dropped = FALSE\", \"describe\": { \"columns\": , \"parameters\": { \"Right\": 2 }, \"nullable\": }, \"hash\": \"420a0c490f1e4d549fb194265e971d8c03b86fe75b595091f6425de11d120a6b\" } 证据：`crates/db/.sqlx/query-420a0c490f1e4d549fb194265e971d8c03b86fe75b595091f6425de11d120a6b.json`\n- **Query 4506Eeeb85B49F00143A9D23636C976159E1C72C9Cfce005599C5Eb52Dc15095**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"SELECT s.id AS \\\"id!: Uuid\\\",\\n s.workspace id AS \\\"workspace id!: Uuid\\\",\\n s.name,\\n s.executor,\\n s.agent working dir,\\n s.created at AS \\\"created at!: DateTime \\\",\\n s.updated at AS \\\"updated at!: DateTime \\\"\\n FROM sessions s\\n LEFT JOIN \\n SELECT ep.session id, MAX ep.created at as last used\\n FROM execution processes ep\\n WHERE ep.run reason != 'devserver' AND ep.dropped = FALSE\\n GROUP BY ep.session id\\n latest ep ON s.id = latest ep.session id\\n WHERE s.workspace id = $1\\n ORDER BY COALESCE latest ep.last used, s.created at DESC\", \"describe\": { \"columns\": { \"name\": \"id!: Uuid\", \"ordinal\": 0, \"type info\": \"Blob\" }, { \"name\": \"workspace id!: Uuid\", \"o… 证据：`crates/db/.sqlx/query-4506eeeb85b49f00143a9d23636c976159e1c72c9cfce005599c5eb52dc15095.json`\n- **Query 48C556A5317E6Ea77595A8Fdc410D30Df50C8405Adf38B371Fdf0A1Bde8C0083**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"UPDATE execution process repo states\\n SET before head commit = $1, updated at = $2\\n WHERE execution process id = $3\\n AND repo id = $4\", \"describe\": { \"columns\": , \"parameters\": { \"Right\": 4 }, \"nullable\": }, \"hash\": \"48c556a5317e6ea77595a8fdc410d30df50c8405adf38b371fdf0a1bde8c0083\" } 证据：`crates/db/.sqlx/query-48c556a5317e6ea77595a8fdc410d30df50c8405adf38b371fdf0a1bde8c0083.json`\n- **Query 4Ac35216Ead7E5Be9Cc2De504A06B6E375E23Ca2Ed14493Ec991F53E458A6A34**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"DELETE FROM attachments WHERE id = $1\", \"describe\": { \"columns\": , \"parameters\": { \"Right\": 1 }, \"nullable\": }, \"hash\": \"4ac35216ead7e5be9cc2de504a06b6e375e23ca2ed14493ec991f53e458a6a34\" } 证据：`crates/db/.sqlx/query-4ac35216ead7e5be9cc2de504a06b6e375e23ca2ed14493ec991f53e458a6a34.json`\n- **Query 4B952Fb779Fbcf70Bd402B6Bcc0Eec07B75879333614B8Ef98E5B8073Ad66Ca6**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"INSERT INTO attachments id, file path, original name, mime type, size bytes, hash \\n VALUES $1, $2, $3, $4, $5, $6 \\n RETURNING id as \\\"id!: Uuid\\\", \\n file path as \\\"file path!\\\", \\n original name as \\\"original name!\\\", \\n mime type,\\n size bytes as \\\"size bytes!\\\",\\n hash as \\\"hash!\\\",\\n created at as \\\"created at!: DateTime \\\", \\n updated at as \\\"updated at!: DateTime \\\"\", \"describe\": { \"columns\": { \"name\": \"id!: Uuid\", \"ordinal\": 0, \"type info\": \"Blob\" }, { \"name\": \"file path!\", \"ordinal\": 1, \"type info\": \"Text\" }, { \"name\": \"original name!\", \"ordinal\": 2, \"type info\": \"Text\" }, { \"name\": \"mime type\", \"ordinal\": 3, \"type info\": \"Text\" }, { \"name\": \"size… 证据：`crates/db/.sqlx/query-4b952fb779fbcf70bd402b6bcc0eec07b75879333614b8ef98e5b8073ad66ca6.json`\n- **Query 4C9B1B539Ec383Ace94Ef29C58967Bbf08112Ebdc61276E9710663A083318211**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"SELECT id as \\\"id!: Uuid\\\", project id as \\\"project id!: Uuid\\\", title, description, status as \\\"status!: TaskStatus\\\", parent workspace id as \\\"parent workspace id: Uuid\\\", created at as \\\"created at!: DateTime \\\", updated at as \\\"updated at!: DateTime \\\"\\n FROM tasks\\n ORDER BY created at ASC\", \"describe\": { \"columns\": { \"name\": \"id!: Uuid\", \"ordinal\": 0, \"type info\": \"Blob\" }, { \"name\": \"project id!: Uuid\", \"ordinal\": 1, \"type info\": \"Blob\" }, { \"name\": \"title\", \"ordinal\": 2, \"type info\": \"Text\" }, { \"name\": \"description\", \"ordinal\": 3, \"type info\": \"Text\" }, { \"name\": \"status!: TaskStatus\", \"ordinal\": 4, \"type info\": \"Text\" }, { \"name\": \"parent workspace… 证据：`crates/db/.sqlx/query-4c9b1b539ec383ace94ef29c58967bbf08112ebdc61276e9710663a083318211.json`\n- **Query 4D86Dcbf754F971Ff3Acffe9E85B5C2F455E77C40C624E09736Be9480238110B**（structured_config）：{ \"db name\": \"SQLite\", \"query\": \"UPDATE workspaces SET archived = $1, updated at = datetime 'now', 'subsec' WHERE id = $2\", \"describe\": { \"columns\": , \"parameters\": { \"Right\": 2 }, \"nullable\": }, \"hash\": \"4d86dcbf754f971ff3acffe9e85b5c2f455e77c40c624e09736be9480238110b\" } 证据：`crates/db/.sqlx/query-4d86dcbf754f971ff3acffe9e85b5c2f455e77c40c624e09736be9480238110b.json`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/AGENTS.md`, `docs/README.md`, `AGENTS.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/AGENTS.md`, `docs/README.md`, `AGENTS.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目介绍与安装**：importance `high`\n - source_paths: README.md, Cargo.toml, package.json, npx-cli/package.json\n- **系统架构总览**：importance `high`\n - source_paths: crates/server/src/lib.rs, crates/remote/src/lib.rs, crates/executors/src/lib.rs, packages/local-web/src/routes/__root.tsx, packages/remote-web/src/routes/__root.tsx\n- **开发环境搭建**：importance `high`\n - source_paths: rust-toolchain.toml, pnpm-workspace.yaml, docs/self-hosting/local-development.mdx, local-build.sh\n- **看板任务管理**：importance `high`\n - source_paths: crates/api-types/src/issue.rs, crates/api-types/src/issue_tag.rs, crates/api-types/src/project.rs, crates/db/src/models/task.rs, packages/ui/src/components/KanbanBoard.tsx\n- **工作区管理与执行**：importance `high`\n - source_paths: crates/workspace-manager/src/workspace_manager.rs, crates/worktree-manager/src/worktree_manager.rs, crates/db/src/models/workspace.rs, crates/db/src/models/session.rs, crates/services/src/services/execution_process.rs\n- **编码代理集成**：importance `high`\n - source_paths: crates/executors/src/lib.rs, crates/executors/src/executor_discovery.rs, crates/executors/src/executors/mod.rs, crates/executors/src/executors/claude/mod.rs, crates/executors/src/executors/codex/mod.rs\n- **数据库模型与迁移**：importance `medium`\n - source_paths: crates/db/src/lib.rs, crates/db/src/models/mod.rs, crates/db/src/models/project.rs, crates/db/src/models/workspace.rs, crates/db/src/models/session.rs\n- **本地 API 服务器**：importance `high`\n - source_paths: crates/server/src/lib.rs, crates/server/src/main.rs, crates/server/src/routes/mod.rs, crates/server/src/routes/workspaces/core.rs, crates/server/src/middleware/mod.rs\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `4deb7eca8f381f7cbc1f9d15515a9ab8f8009053`\n- inspected_files: `pnpm-lock.yaml`, `Dockerfile`, `package.json`, `README.md`, `docs/AGENTS.md`, `docs/troubleshooting.mdx`, `docs/browser-testing.mdx`, `docs/reviewing-code.mdx`, `docs/issue-management.mdx`, `docs/getting-started.mdx`, `docs/CLAUDE.md`, `docs/supported-coding-agents.mdx`, `docs/index.mdx`, `docs/README.md`, `docs/docs.json`, `docs/frontend-ui-library-refactor-audit.md`, `docs/remote-access.mdx`, `docs/responsible-disclosure.mdx`, `docs/settings/general.mdx`, `docs/settings/remote-projects.mdx`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：Deployment(Other(Migration failed: error returned from database: (code: 1) no such column: ep.session_id))\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Deployment(Other(Migration failed: error returned from database: (code: 1) no such column: ep.session_id))\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_b34b2ea1b35a4dc2a4a0eb0681bdb883 | https://github.com/BloopAI/vibe-kanban/issues/2972 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：Support for self-hosted projects and better export\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Support for self-hosted projects and better export\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_19d27caa9e34416a9f282869f76624b0 | https://github.com/BloopAI/vibe-kanban/issues/3396 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：[Proposal] JIRA Integration for Vibe Kanban\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Proposal] JIRA Integration for Vibe Kanban\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_ab38fe97c4574e2da01ddedd71a4fbac | https://github.com/BloopAI/vibe-kanban/issues/2424 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：Pre-release v0.1.40-20260401153532\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Pre-release v0.1.40-20260401153532\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_f4b99d437a4f4fd4989d2b3ef036553b | https://github.com/BloopAI/vibe-kanban/releases/tag/v0.1.40-20260401153532 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：Release v0.1.36\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.1.36\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_527645be4e3f438e81757ef265a70d79 | https://github.com/BloopAI/vibe-kanban/releases/tag/v0.1.36-20260323174633 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：Release v0.1.43\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.1.43\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_53704dc7171446fe86b2017f72212ddc | https://github.com/BloopAI/vibe-kanban/releases/tag/v0.1.43-20260417125614 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 可能修改宿主 AI 配置\n\n- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Evidence: capability.host_targets | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | host_targets=claude, claude_code\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：Pre-release v0.1.39-20260331145823\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Pre-release v0.1.39-20260331145823\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_c005a56959634369929ce33eddbdc103 | https://github.com/BloopAI/vibe-kanban/releases/tag/v0.1.39-20260331145823 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：[Request] Support RDS for self hosting in AWS\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[Request] Support RDS for self hosting in AWS\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_f613b792c20942519560c0a286a82005 | https://github.com/BloopAI/vibe-kanban/issues/3405 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：BloopAI/vibe-kanban\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：claude, claude_code\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：Deployment(Other(Migration failed: error returned from database: (code: 1) no such column: ep.session_id))（high）：可能影响升级、迁移或版本选择。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Support for self-hosted projects and better export（high）：可能阻塞安装或首次运行。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[Proposal] JIRA Integration for Vibe Kanban（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Pre-release v0.1.40-20260401153532（medium）：可能阻塞安装或首次运行。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：Release v0.1.36（medium）：可能阻塞安装或首次运行。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/BloopAI/vibe-kanban 项目说明书\n\n生成时间：2026-05-13 11:19:08 UTC\n\n## 目录\n\n- [项目介绍与安装](#project-introduction)\n- [系统架构总览](#architecture-overview)\n- [开发环境搭建](#development-setup)\n- [看板任务管理](#kanban-management)\n- [工作区管理与执行](#workspace-management)\n- [编码代理集成](#coding-agents)\n- [数据库模型与迁移](#database-models)\n- [本地 API 服务器](#api-server)\n- [远程云服务架构](#remote-server)\n- [MCP 服务器实现](#mcp-server)\n\n\n\n## 项目介绍与安装\n\n### 相关页面\n\n相关主题：[系统架构总览](#architecture-overview), [开发环境搭建](#development-setup)\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/mcp/src/lib.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/mcp/src/lib.rs)\n- [crates/mcp/src/task_server/mod.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/mcp/src/task_server/mod.rs)\n- [crates/mcp/src/task_server/handler.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/mcp/src/task_server/handler.rs)\n- [crates/mcp/src/task_server/tools/mod.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/mcp/src/task_server/tools/mod.rs)\n- [crates/mcp/src/bin/vibe_kanban_mcp.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/mcp/src/bin/vibe_kanban_mcp.rs)\n\n
\n\n# 项目介绍与安装\n\n## 项目概述\n\nVibe Kanban 是一款专为软件工程师设计的协作工具，旨在优化编码代理（coding agents）的规划与代码审查流程。在现代软件开发中，工程师们花费大量时间在规划任务和审查代码上，Vibe Kanban 通过提供高效的看板式任务管理和流畅的编码代理执行环境，帮助团队显著提升交付效率。\n\n资料来源：[README.md](https://github.com/BloopAI/vibe-kanban/blob/main/README.md)\n\n## 核心功能\n\nVibe Kanban 提供了完整的软件开发工作流支持，主要包括以下功能模块：\n\n| 功能模块 | 描述 |\n|---------|------|\n| **看板式任务管理** | 创建、优先级排序和分配看板问题，支持隐私或团队协作模式 |\n| **编码代理工作区** | 每个工作区为代理提供独立的分支、终端和开发服务器 |\n| **差异审查与评论** | 直接在 UI 中发送反馈给代理，支持内联评论 |\n| **应用预览** | 内置浏览器 DevTools、检查模式和设备模拟功能 |\n| **编码代理切换** | 支持在 10+ 种主流编码代理之间自由切换 |\n| **Pull Request 管理** | 创建带 AI 生成描述的 PR，支持 GitHub 审查和合并 |\n\n资料来源：[README.md](https://github.com/BloopAI/vibe-kanban/blob/main/README.md)\n\n## 支持的编码代理\n\nVibe Kanban 原生支持多种主流编码代理工具，满足不同开发团队的偏好：\n\n| 编码代理 | 状态 |\n|---------|------|\n| Claude Code | ✅ 支持 |\n| Codex | ✅ 支持 |\n| Gemini CLI | ✅ 支持 |\n| GitHub Copilot | ✅ 支持 |\n| Amp | ✅ 支持 |\n| Cursor | ✅ 支持 |\n| OpenCode | ✅ 支持 |\n| Droid | ✅ 支持 |\n| CCR | ✅ 支持 |\n| Qwen Code | ✅ 支持 |\n\n资料来源：[README.md](https://github.com/BloopAI/vibe-kanban/blob/main/README.md)\n\n## 技术架构\n\nVibe Kanban 采用多包 monorepo 架构，主要由前端组件库、后端服务和 CLI 工具组成。\n\n### 项目结构概览\n\n```mermaid\ngraph TD\n A[vibe-kanban] --> B[packages/web-core]\n A --> C[packages/ui]\n A --> D[packages/remote-web]\n A --> E[crates/server]\n A --> F[npx-cli]\n \n B -->|React 组件| C\n C -->|UI 组件| D\n D -->|远程 Web| E\n F -->|CLI 入口| E\n```\n\n### 核心包说明\n\n| 包名称 | 类型 | 描述 |\n|-------|------|------|\n| `packages/web-core` | React Core | 核心业务逻辑、状态管理、对话框组件 |\n| `packages/ui` | UI 组件库 | 可复用 UI 组件，包括 CommandBar、WorkspacesSidebar |\n| `packages/remote-web` | Web 应用 | 远程 Web 页面，包括首页和组织管理 |\n| `crates/server` | Rust 后端 | OAuth 认证、API 路由和服务器逻辑 |\n| `npx-cli` | CLI 工具 | `npx vibe-kanban` 命令行入口 |\n\n资料来源：[package.json](https://github.com/BloopAI/vibe-kanban/blob/main/package.json)\n\n### 状态管理\n\n应用使用 Zustand 进行状态管理，主要 store 包括：\n\n- `useUiPreferencesStore` - UI 偏好设置和布局模式管理\n- `useWorkspaceDiffStore` - 工作区差异和 GitHub 评论数据\n- `useOrganizationStore` - 组织相关状态\n\n资料来源：[packages/web-core/src/shared/stores/useUiPreferencesStore.ts](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/stores/useUiPreferencesStore.ts)\n\n## 安装指南\n\n### 前置要求\n\n在安装 Vibe Kanban 之前，请确保已完成以下准备工作：\n\n1. **Node.js 环境**：建议使用 Node.js 18.x 或更高版本\n2. **编码代理认证**：完成您选择的编码代理的身份验证配置\n3. **包管理器**：npm、pnpm 或 yarn 任选其一\n\n### 安装方式\n\nVibe Kanban 提供多种安装和运行方式，最简捷的方式是通过 npx 直接运行：\n\n```bash\nnpx vibe-kanban\n```\n\n此命令会自动下载并执行最新版本的 Vibe Kanban CLI。\n\n资料来源：[README.md](https://github.com/BloopAI/vibe-kanban/blob/main/README.md)\n\n### 从源码构建\n\n如需从源码构建和运行，请按以下步骤操作：\n\n```bash\n# 克隆仓库\ngit clone https://github.com/BloopAI/vibe-kanban.git\ncd vibe-kanban\n\n# 安装依赖\nnpm install\n\n# 启动开发服务器\nnpm run dev\n```\n\n资料来源：[npx-cli/package.json](https://github.com/BloopAI/vibe-kanban/blob/main/npx-cli/package.json)\n\n## 快速开始\n\n### 基本工作流\n\n```mermaid\ngraph LR\n A[创建看板任务] --> B[分配给工作区]\n B --> C[启动编码代理]\n C --> D[代理执行任务]\n D --> E[审查代码差异]\n E --> F[发送反馈评论]\n F -->|需要修改| D\n F -->|审核通过| G[创建 Pull Request]\n G --> H[合并代码]\n```\n\n### 创建新工作区\n\n1. 打开 Vibe Kanban 应用\n2. 选择项目或创建新项目\n3. 点击\"创建新工作区\"按钮\n4. 选择编码代理和配置文件\n5. 描述工作任务，代理开始执行\n\n资料来源：[packages/web-core/src/shared/dialogs/command-bar/WorkspaceSelectionDialog.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/dialogs/command-bar/WorkspaceSelectionDialog.tsx)\n\n### 键盘快捷键\n\n| 快捷键 | 功能 |\n|-------|------|\n| `v > s` | 切换预览模式 |\n| `v > h` | 切换左侧主面板 |\n| `x > p` | 创建 Pull Request |\n| `x > m` | 合并代码 |\n| `x > u` | 推送代码 |\n| `t > d` | 切换开发服务器 |\n| `r > s` | 运行设置脚本 |\n| `r > c` | 运行清理脚本 |\n\n资料来源：[packages/web-core/src/shared/keyboard/useWorkspaceShortcuts.ts](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/keyboard/useWorkspaceShortcuts.ts)\n\n## 自托管部署\n\n如需在自有基础设施上部署 Vibe Kanban Cloud 实例，可使用 Docker 进行部署。\n\n详细部署指南请参阅官方文档：https://vibekanban.com/docs/self-hosting/deploy-docker\n\n资料来源：[README.md](https://github.com/BloopAI/vibe-kanban/blob/main/README.md)\n\n## 认证与集成\n\n### GitHub OAuth 集成\n\nVibe Kanban 支持通过 GitHub CLI 进行 OAuth 认证。认证成功后，应用会返回包含 Base64 编码应用图标的 HTML 响应：\n\n```rust\nResponse::builder()\n .status(StatusCode::OK)\n .header(\"content-type\", \"text/html; charset=utf-8\")\n .body(body)\n .unwrap()\n```\n\n资料来源：[crates/server/src/routes/oauth.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/server/src/routes/oauth.rs)\n\n### GitHub CLI 设置\n\nGitHub CLI 集成需要执行以下设置步骤：\n\n1. 检查 gh CLI 是否已安装\n2. 安装 Homebrew（如果需要）\n3. 完成 GitHub 身份验证\n\n资料来源：[packages/web-core/src/shared/dialogs/auth/GhCliSetupDialog.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/dialogs/auth/GhCliSetupDialog.tsx)\n\n## 相关资源\n\n| 资源类型 | 链接 |\n|---------|------|\n| 官方文档 | https://vibekanban.com/docs |\n| npm 包 | https://www.npmjs.com/package/vibe-kanban |\n| GitHub Discussions | https://github.com/BloopAI/vibe-kanban/discussions |\n| Discord 社区 | https://discord.gg/AC4nwVtJM3 |\n| DeepWiki 文档 | https://deepwiki.com/BloopAI/vibe-kanban |\n\n## 支持与反馈\n\n- **功能请求**：请通过 GitHub Discussions 提出\n- **Bug 报告**：请在 GitHub Issues 中提交\n- **社区交流**：加入 Discord 服务器参与讨论\n\n建议在提出新想法或变更之前，先与核心团队通过 GitHub Discussions 或 Discord 沟通，以确保实现方案与现有路线图保持一致。\n\n资料来源：[README.md](https://github.com/BloopAI/vibe-kanban/blob/main/README.md)\n\n---\n\n\n\n## 系统架构总览\n\n### 相关页面\n\n相关主题：[项目介绍与安装](#project-introduction), [数据库模型与迁移](#database-models), [本地 API 服务器](#api-server)\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/BloopAI/vibe-kanban/blob/main/README.md)\n- [Cargo.toml](https://github.com/BloopAI/vibe-kanban/blob/main/Cargo.toml)\n- [package.json](https://github.com/BloopAI/vibe-kanban/blob/main/package.json)\n- [npx-cli/package.json](https://github.com/BloopAI/vibe-kanban/blob/main/npx-cli/package.json)\n- [crates/server/src/routes/oauth.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/server/src/routes/oauth.rs)\n\n
\n\n# 系统架构总览\n\n## 1. 项目简介\n\nVibe Kanban 是一个面向软件工程师的代码规划与审核平台，旨在通过看板式任务管理和 AI 编程代理工作区集成，显著提升软件交付效率。该项目采用 **monorepo 结构**，核心代码使用 TypeScript/React 构建前端界面，Rust 构建后端服务。\n\n> 项目官方公告：Vibe Kanban 正在进行 sunsetting（停止运营），详情见 [官方公告](https://www.vibekanban.com/blog/shutdown)。资料来源：[README.md]()\n\n## 2. 整体架构\n\n### 2.1 架构分层\n\n```mermaid\ngraph TD\n subgraph 前端层[\"前端层 (packages/)\"]\n UI[\"UI 组件库相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx)\n- [packages/web-core/src/shared/hooks/useAzureAttachments.ts](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/hooks/useAzureAttachments.ts)\n- [packages/web-core/src/shared/dialogs/command-bar/ForcePushDialog.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/dialogs/command-bar/ForcePushDialog.tsx)\n- [packages/ui/src/components/WorkspacesSidebar.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/ui/src/components/WorkspacesSidebar.tsx)\n- [packages/ui/src/components/CommandBar.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/ui/src/components/CommandBar.tsx)\n- [packages/web-core/src/shared/stores/useWorkspaceDiffStore.ts](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/stores/useWorkspaceDiffStore.ts)\n- [packages/web-core/src/shared/stores/useUiPreferencesStore.ts](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/stores/useUiPreferencesStore.ts)\n- [packages/web-core/src/shared/keyboard/useWorkspaceShortcuts.ts](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/keyboard/useWorkspaceShortcuts.ts)\n- [crates/server/src/routes/oauth.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/server/src/routes/oauth.rs)\n- [packages/remote-web/src/pages/HomePage.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/remote-web/src/pages/HomePage.tsx)\npackages/ui\"]\n WebCore[\"Web 核心模块
packages/web-core\"]\n LocalWeb[\"本地 Web 应用
packages/local-web\"]\n RemoteWeb[\"远程 Web 应用
packages/remote-web\"]\n end\n \n subgraph 核心服务层[\"核心服务层 (crates/)\"]\n Server[\"后端服务
crates/server\"]\n Remote[\"远程通信
crates/remote\"]\n Executors[\"执行器引擎
crates/executors\"]\n end\n \n subgraph 共享层[\"共享基础设施\"]\n DB[(\"数据库\")]\n Auth[\"认证系统\"]\n end\n \n UI --> WebCore\n LocalWeb --> WebCore\n RemoteWeb --> WebCore\n WebCore --> Server\n WebCore --> Remote\n Server --> Executors\n Server --> DB\n Server --> Auth\n```\n\n### 2.2 Monorepo 包结构\n\n| 包名 | 技术栈 | 职责 |\n|------|--------|------|\n| `packages/ui` | React, TypeScript | 可复用的 UI 组件库，包括 `WorkspacesSidebar`、`CommandBar`、`SessionChatBox` |\n| `packages/web-core` | React, TypeScript | 业务逻辑核心，包含状态管理、对话框、快捷键、Git 操作 |\n| `packages/local-web` | React, TypeScript | 本地部署的前端应用入口 |\n| `packages/remote-web` | React, TypeScript | 远程协作的前端应用入口 |\n| `crates/server` | Rust | 后端 API 服务、OAuth 认证路由 |\n| `crates/remote` | Rust | 远程通信协议实现 |\n| `crates/executors` | Rust | AI 编程代理执行引擎 |\n\n资料来源：[packages/ui/src/components/WorkspacesSidebar.tsx]()\n资料来源：[packages/web-core/src/shared/dialogs/command-bar/ForcePushDialog.tsx]()\n资料来源：[crates/server/src/routes/oauth.rs]()\n\n## 3. 前端架构\n\n### 3.1 状态管理\n\n前端采用 **Zustand** 进行状态管理，定义了多个独立的 store 模块：\n\n| Store 模块 | 文件位置 | 主要职责 |\n|-----------|----------|----------|\n| `useWorkspaceDiffStore` | `web-core/src/shared/stores/useWorkspaceDiffStore.ts` | GitHub PR 评论、文件差异状态 |\n| `useUiPreferencesStore` | `web-core/src/shared/stores/useUiPreferencesStore.ts` | UI 偏好设置、面板布局、侧边栏可见性 |\n\n```typescript\n// useUiPreferencesStore 核心功能\ntoggleLeftSidebar: () => set((s) => ({ isLeftSidebarVisible: !s.isLeftSidebarVisible })),\ntoggleLeftMainPanel: (workspaceId) => { /* 切换主面板 */ },\ntoggleRightSidebar: () => set((s) => ({ isRightSidebarVisible: !s.isRightSidebarVisible })),\ntoggleTerminal: () => set((s) => ({ isTerminalVisible: !s.isTerminalVisible })),\n```\n\n资料来源：[packages/web-core/src/shared/stores/useUiPreferencesStore.ts]()\n\n### 3.2 对话框系统\n\n项目实现了统一的模态对话框框架 `defineModal`，支持在应用中复用对话框组件：\n\n```mermaid\ngraph LR\n A[用户操作] --> B[打开对话框]\n B --> C[DialogContent]\n C --> D[DialogFooter
取消/确认按钮]\n C --> E[状态管理
isSubmitting]\n```\n\n**核心对话框组件**：\n\n| 组件名称 | 文件路径 | 功能描述 |\n|---------|----------|----------|\n| `ResolveConflictsDialog` | `web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx` | 处理 Git 冲突文件列表展示 |\n| `ForcePushDialog` | `web-core/src/shared/dialogs/command-bar/ForcePushDialog.tsx` | Git 强制推送确认 |\n| `ReleaseNotesDialog` | `web-core/src/shared/dialogs/global/ReleaseNotesDialog.tsx` | 版本更新日志展示 |\n| `WorkspaceSelectionDialog` | `web-core/src/shared/dialogs/command-bar/WorkspaceSelectionDialog.tsx` | 工作区选择/链接 |\n| `GhCliSetupDialog` | `web-core/src/shared/dialogs/auth/GhCliSetupDialog.tsx` | GitHub CLI 配置引导 |\n\n```typescript\nexport const ForcePushDialog = defineModal
needsAttention]\n B --> B2[运行中工作区]\n B --> B3[归档工作区]\n C --> C1[工作区摘要卡片]\n```\n\n**工作区状态属性**：\n\n| 属性 | 类型 | 描述 |\n|------|------|------|\n| `isRunning` | boolean | 是否正在运行 |\n| `isPinned` | boolean | 是否固定显示 |\n| `hasPendingApproval` | boolean | 是否有待审批项 |\n| `hasRunningDevServer` | boolean | 开发服务器状态 |\n| `hasUnseenActivity` | boolean | 是否有未读活动 |\n| `prStatus` | string | PR 状态 |\n| `filesChanged` | number | 变更文件数 |\n| `linesAdded` | number | 新增行数 |\n| `linesRemoved` | number | 删除行数 |\n\n资料来源：[packages/ui/src/components/WorkspacesSidebar.tsx]()\n\n### 4.2 附件上传与 Azure 集成\n\n`useAzureAttachments` Hook 实现了文件上传的状态管理：\n\n```typescript\n// 上传流程状态转换\n上传中 → confirmAttachmentUpload() → 完成\n// 状态映射\n{ status: 'uploading', progress: pct }\n{ status: 'confirming', progress: 100 }\n{ id: result.id, blob_id: result.blob_id } // 完成状态\n```\n\n资料来源：[packages/web-core/src/shared/hooks/useAzureAttachments.ts]()\n\n## 5. 后端服务\n\n### 5.1 Rust 后端架构\n\n后端采用 Rust 构建，主要路由位于 `crates/server/src/routes/` 目录：\n\n```mermaid\ngraph LR\n A[HTTP 请求] --> B[oauth.rs]\n A --> C[API 路由]\n B --> D[GitHub OAuth]\n C --> E[业务逻辑]\n E --> F[executors]\n E --> G[数据库]\n```\n\n**OAuth 认证端点示例**：\n\n```rust\nResponse::builder()\n .status(StatusCode::OK)\n .header(\"content-type\", \"text/html; charset=utf-8\")\n .body(body)\n .unwrap()\n```\n\n资料来源：[crates/server/src/routes/oauth.rs]()\n\n### 5.2 冲突解决对话框\n\n当检测到 Git 冲突时，`ResolveConflictsDialog` 展示冲突文件列表：\n\n```typescript\n{conflictedFiles.slice(0, 5).map((file) => (\n
\n
\n\n# 开发环境搭建\n\n本文档详细介绍 Vibe Kanban 项目的开发环境搭建流程，包括前置条件、安装步骤、配置说明以及本地运行方法。\n\n## 概述\n\nVibe Kanban 是一个采用 **pnpm monorepo** 结构管理的前后端分离项目。前端使用 React 技术栈（TypeScript），后端使用 Rust 语言（基于 Axum 框架）。项目通过 pnpm workspaces 统一管理多个子包，实现统一的依赖管理和构建流程。\n\n**技术栈概览：**\n\n| 层级 | 技术选型 | 主要包 |\n|------|----------|--------|\n| 前端框架 | React 18 + TypeScript | packages/web-core, packages/ui |\n| 后端服务 | Rust + Axum | crates/server |\n| 包管理器 | pnpm | pnpm-workspace.yaml |\n| UI 组件库 | Radix UI + Tailwind CSS | packages/ui |\n| 状态管理 | Zustand | packages/web-core |\n\n## 前置条件\n\n### 系统要求\n\n开发环境需要满足以下最低要求：\n\n- **操作系统**：macOS、Linux 或 Windows (WSL2)\n- **内存**：建议 8GB 以上\n- **磁盘空间**：至少 10GB 可用空间\n\n### 必需工具\n\n#### Rust 环境\n\n项目使用 Rust 作为后端语言，需要安装 Rust 工具链：\n\n```bash\n# 安装 Rust (如果尚未安装)\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n\n# 验证安装\nrustc --version\ncargo --version\n```\n\nRust 工具链版本由 `rust-toolchain.toml` 文件定义，确保使用兼容版本：\n\n```toml\n[toolchain]\nchannel = \"stable\"\ncomponents = [\"rustfmt\", \"clippy\"]\n```\n\n#### Node.js 与 pnpm\n\n前端开发需要 Node.js 环境：\n\n```bash\n# 安装 Node.js 18+\n# 建议使用 nvm 管理 Node 版本\nnvm install 18\nnvm use 18\n\n# 安装 pnpm (如果尚未安装)\nnpm install -g pnpm\n\n# 验证 pnpm 版本\npnpm --version\n```\n\n项目根目录下的 `pnpm-workspace.yaml` 定义了工作区配置：\n\n```yaml\npackages:\n - 'packages/*'\n - 'crates/*'\n```\n\n#### 数据库\n\nVibe Kanban 后端依赖 PostgreSQL 数据库：\n\n- **最低版本**：PostgreSQL 14+\n- **建议版本**：PostgreSQL 15 或 16\n\n### 可选工具\n\n| 工具 | 用途 | 必需性 |\n|------|------|--------|\n| Docker | 容器化运行环境 | 可选 |\n| DBeaver / pgAdmin | 数据库管理 | 推荐 |\n| VS Code + Rust Analyzer | Rust 开发 | 推荐 |\n| pnpm 插件 | 加速依赖安装 | 可选 |\n\n## 安装步骤\n\n### 1. 克隆代码仓库\n\n```bash\ngit clone https://github.com/BloopAI/vibe-kanban.git\ncd vibe-kanban\n```\n\n### 2. 安装前端依赖\n\n在项目根目录执行依赖安装：\n\n```bash\npnpm install\n```\n\npnpm 会根据 `pnpm-workspace.yaml` 的配置，自动安装所有 workspace 内的依赖：\n\n- `packages/web-core` - 核心 Web 模块\n- `packages/ui` - UI 组件库\n- `packages/remote-web` - 远程 Web 模块\n- `crates/server` - Rust 服务（通过 cargo 管理）\n\n### 3. 配置环境变量\n\n创建环境变量配置文件：\n\n```bash\ncp .env.example .env\n```\n\n根据实际环境修改 `.env` 文件中的配置项：\n\n| 变量名 | 说明 | 示例值 |\n|--------|------|--------|\n| `DATABASE_URL` | PostgreSQL 连接字符串 | `postgres://user:pass@localhost:5432/vibkanban` |\n| `RUST_LOG` | 日志级别 | `info` 或 `debug` |\n| `APP_PORT` | 应用监听端口 | `8080` |\n| `APP_HOST` | 应用监听地址 | `0.0.0.0` |\n| `GITHUB_CLIENT_ID` | GitHub OAuth 客户端 ID | `your_client_id` |\n| `GITHUB_CLIENT_SECRET` | GitHub OAuth 客户端密钥 | `your_client_secret` |\n\n### 4. 初始化数据库\n\n```bash\n# 创建数据库\npsql -U postgres -c \"CREATE DATABASE vibe_kanban;\"\n\n# 运行数据库迁移\ncd crates/server\ncargo run --bin migrate\n```\n\n## 本地构建\n\n### 完整构建\n\n使用项目提供的构建脚本进行完整构建：\n\n```bash\n./local-build.sh\n```\n\n该脚本会自动执行以下步骤：\n\n1. 安装 Rust 依赖\n2. 构建后端服务\n3. 构建前端应用\n4. 生成可部署产物\n\n### 分步构建\n\n#### 后端构建\n\n```bash\ncd crates/server\ncargo build --release\n```\n\n产物位置：`crates/server/target/release/server`\n\n#### 前端构建\n\n```bash\ncd packages/web-core\npnpm build\n```\n\n产物位置：`packages/web-core/dist`\n\n### 开发模式\n\n#### 启动后端服务\n\n```bash\ncd crates/server\ncargo run\n```\n\n服务默认监听 `http://localhost:8080`\n\n#### 启动前端开发服务器\n\n```bash\ncd packages/web-core\npnpm dev\n```\n\n访问 `http://localhost:3000` 查看前端应用\n\n## 项目结构\n\n```\nvibe-kanban/\n├── packages/ # 前端包目录\n│ ├── web-core/ # 核心 Web 模块\n│ │ └── src/\n│ │ ├── shared/ # 共享组件和工具\n│ │ ├── dialogs/ # 对话框组件\n│ │ ├── stores/ # Zustand 状态管理\n│ │ └── hooks/ # React 自定义 Hooks\n│ ├── ui/ # UI 组件库\n│ └── remote-web/ # 远程 Web 模块\n├── crates/ # Rust crates 目录\n│ └── server/ # 后端服务\n│ ├── src/\n│ │ ├── routes/ # API 路由定义\n│ │ └── models/ # 数据模型\n│ └── migrations/ # 数据库迁移\n├── docs/ # 项目文档\n│ └── self-hosting/ # 自托管文档\n├── pnpm-workspace.yaml # pnpm 工作区配置\n├── rust-toolchain.toml # Rust 工具链定义\n└── local-build.sh # 本地构建脚本\n```\n\n## 常见问题\n\n### 依赖安装失败\n\n**问题**：pnpm 安装依赖时报错\n\n**解决方案**：\n\n```bash\n# 清理缓存后重试\npnpm store prune\nrm -rf node_modules\npnpm install\n```\n\n### Rust 编译错误\n\n**问题**：cargo 编译时出现版本不兼容错误\n\n**解决方案**：\n\n```bash\n# 更新 Rust 工具链\nrustup update\nrustup upgrade\n\n# 清理编译缓存\ncargo clean\ncargo build\n```\n\n### 数据库连接失败\n\n**问题**：后端服务启动时无法连接数据库\n\n**解决方案**：\n\n1. 检查 PostgreSQL 服务是否运行\n2. 验证 `DATABASE_URL` 环境变量配置\n3. 确认数据库用户权限\n\n```bash\n# 检查 PostgreSQL 状态\npg_isready -h localhost -p 5432\n\n# 测试数据库连接\npsql $DATABASE_URL -c \"SELECT 1;\"\n```\n\n## 验证安装\n\n完成以上步骤后，可以通过以下方式验证环境搭建是否成功：\n\n1. **后端服务验证**：访问 `http://localhost:8080/health`\n2. **前端应用验证**：访问 `http://localhost:3000`\n3. **API 文档**：访问 `http://localhost:8080/docs`（如果启用 Swagger）\n\n所有验证通过后，即可开始 Vibe Kanban 的开发工作。\n\n---\n\n\n\n## 看板任务管理\n\n### 相关页面\n\n相关主题：[工作区管理与执行](#workspace-management), [编码代理集成](#coding-agents)\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [rust-toolchain.toml](https://github.com/BloopAI/vibe-kanban/blob/main/rust-toolchain.toml)\n- [pnpm-workspace.yaml](https://github.com/BloopAI/vibe-kanban/blob/main/pnpm-workspace.yaml)\n- [docs/self-hosting/local-development.mdx](https://github.com/BloopAI/vibe-kanban/blob/main/docs/self-hosting/local-development.mdx)\n- [local-build.sh](https://github.com/BloopAI/vibe-kanban/blob/main/local-build.sh)\n\n
\n\n# 看板任务管理\n\n## 概述\n\n看板任务管理是 Vibe Kanban 系统的核心功能模块，旨在帮助软件工程师高效地规划、分配和跟踪编码任务。该系统通过直观的看板界面将传统项目管理方法与现代 AI 编码代理能力相结合，支持从任务创建到工作区执行的全流程管理。\n\n看板任务管理的核心概念包括：\n\n- **Issue（问题/任务）**：系统中的基本工作单元\n- **Project（项目）**：包含多个相关 Issue 的容器\n- **Status（状态）**：Issue 在看板中的流转阶段\n- **Workspace（工作区）**：用于执行任务的隔离环境\n\n## 数据模型\n\n### Issue 类型定义\n\nIssue 是看板任务管理的基础单元。在 `crates/api-types/src/issue.rs` 中定义了完整的数据结构：\n\n```rust\npub struct Issue {\n pub id: String,\n pub project_id: String,\n pub simple_id: String, // 人类可读的短 ID\n pub title: String, // 任务标题\n pub description: Option相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/api-types/src/issue.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/api-types/src/issue.rs)\n- [crates/api-types/src/issue_tag.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/api-types/src/issue_tag.rs)\n- [crates/api-types/src/project.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/api-types/src/project.rs)\n- [crates/db/src/models/task.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/db/src/models/task.rs)\n- [packages/ui/src/components/KanbanBoard.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/ui/src/components/KanbanBoard.tsx)\n- [packages/web-core/src/pages/kanban/LocalProjectKanban.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/pages/kanban/LocalProjectKanban.tsx)\n\n
\n\n# 工作区管理与执行\n\n## 概述\n\n工作区（Workspace）是 Vibe Kanban 系统中用于运行编码代理的核心执行单元。每个工作区为 AI 代理提供独立的 Git 分支、终端环境和开发服务器，使团队能够通过看板任务规划和执行编码工作。\n\n工作区管理涵盖工作区的创建、状态追踪、进程执行以及与编码会话的关联。系统支持多工作区并行运行，并提供统一的用户界面用于工作区切换、状态监控和结果查看。\n\n资料来源：[README.md]()\n\n## 核心数据模型\n\n### Workspace 数据结构\n\n工作区包含以下关键属性，用于追踪和管理执行状态：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| id | string | 工作区唯一标识符 |\n| name | string | 工作区显示名称 |\n| branch | string | 关联的 Git 分支名称 |\n| isArchived | boolean | 是否已归档 |\n| isRunning | boolean | 当前是否正在运行 |\n| isPinned | boolean | 是否被固定显示 |\n| filesChanged | number | 修改的文件数量 |\n| linesAdded | number | 新增代码行数 |\n| linesRemoved | number | 删除代码行数 |\n| hasPendingApproval | boolean | 是否有待审批内容 |\n| hasRunningDevServer | boolean | 开发服务器是否运行中 |\n| hasUnseenActivity | boolean | 是否有未读活动 |\n| latestProcessCompletedAt | Date | 最近进程完成时间 |\n| latestProcessStatus | string | 最近进程状态 |\n| prStatus | object | Pull Request 状态信息 |\n\n资料来源：[packages/ui/src/components/WorkspacesSidebar.tsx:35-48]()\n\n### Session 会话模型\n\n每个工作区可关联一个编码会话，会话记录代理执行的上下文和结果：\n\n| 属性 | 说明 |\n|------|------|\n| filesChanged | 会话期间修改的文件数 |\n| linesAdded | 新增代码行数 |\n| linesRemoved | 删除代码行数 |\n\n资料来源：[packages/ui/src/components/SessionChatBox.tsx:89-92]()\n\n## 工作区选择与创建\n\n### 工作区选择对话框\n\n`WorkspaceSelectionDialog` 提供命令面板式的工作区选择界面，支持搜索、分页和新建工作区功能。\n\n**组件层级结构：**\n\n```\nWorkspaceSelectionDialog\n├── CommandDialog (cmdk 库)\n│ └── Command\n│ ├── CommandInput (搜索输入)\n│ ├── CommandList\n│ │ ├── CommandEmpty (无结果提示)\n│ │ ├── CommandGroup (新建工作区选项)\n│ │ │ └── CommandItem (__create_new__)\n│ │ └── CommandGroup (可用工作区列表)\n│ │ └── CommandItem (各工作区)\n│ └── CommandList (分页计数显示)\n└── WorkspaceSelectionWithContext (Context 包装器)\n ├── UserProvider\n └── ProjectProvider\n```\n\n**工作区显示逻辑：**\n\n```typescript\n// 搜索值格式包含 ID、名称、分支和归档状态\nvalue={`${workspace.id} ${workspace.name} ${workspace.branch}${workspace.isArchived ? ' archived' : ''}`}\n```\n\n资料来源：[packages/web-core/src/shared/dialogs/command-bar/WorkspaceSelectionDialog.tsx:20-60]()\n\n### 工作区过滤与搜索\n\n系统支持按名称和分支搜索工作区，采用分页加载机制：\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| PAGE_SIZE | 50 | 每页显示数量 |\n| isSearching | boolean | 是否处于搜索模式 |\n\n搜索时显示所有匹配结果，非搜索模式下超过 PAGE_SIZE 时显示分页提示。\n\n资料来源：[packages/web-core/src/shared/dialogs/command-bar/WorkspaceSelectionDialog.tsx:65-72]()\n\n## 工作区侧边栏\n\n### 布局模式\n\n工作区侧边栏支持两种布局模式，可在 `useUiPreferencesStore` 中管理：\n\n| 模式 | 说明 |\n|------|------|\n| workspaces | 工作区列表视图 |\n| kanban | 看板视图 |\n| accordion | 可折叠分组视图 |\n\n资料来源：[packages/web-core/src/shared/stores/useUiPreferencesStore.ts:42-48]()\n\n### 工作区状态指示\n\n侧边栏通过 `WorkspaceSummary` 组件展示每个工作区的综合状态：\n\n- **活跃状态**: `isActive` 标识当前选中的工作区\n- **运行状态**: `isRunning` 显示代理是否正在执行\n- **审批状态**: `hasPendingApproval` 标记待审批内容\n- **活动通知**: `hasUnseenActivity` 提示未读更新\n\n资料来源：[packages/ui/src/components/WorkspacesSidebar.tsx:20-50]()\n\n### 归档工作区展示\n\n归档的工作区显示在独立区域，通过 `isArchived` 属性区分：\n\n```typescript\n{workspace.isArchived && (\n \n ({t('workspaces.archived').toLowerCase()})\n \n)}\n```\n\n归档工作区列表为空时显示友好提示文本。\n\n资料来源：[packages/ui/src/components/WorkspacesSidebar.tsx:14-30]()\n\n## 进程管理与执行\n\n### 进程标签页\n\n`ProcessesTab` 组件展示工作区内的执行进程历史：\n\n**显示信息包括：**\n\n- 进程启动时间 (`started_at`)\n- 进程完成时间 (`completed_at`)\n- 进程日志输出\n\n**操作功能：**\n\n- 复制日志: `handleCopyLogs` 处理日志复制到剪贴板\n- 查看详情: `setSelectedProcessId` 选择特定进程查看\n\n```typescript\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/web-core/src/shared/dialogs/command-bar/WorkspaceSelectionDialog.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/dialogs/command-bar/WorkspaceSelectionDialog.tsx)\n- [packages/ui/src/components/WorkspacesSidebar.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/ui/src/components/WorkspacesSidebar.tsx)\n- [packages/web-core/src/shared/components/tasks/TaskDetails/ProcessesTab.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/components/tasks/TaskDetails/ProcessesTab.tsx)\n- [packages/web-core/src/shared/stores/useUiPreferencesStore.ts](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/stores/useUiPreferencesStore.ts)\n- [packages/ui/src/components/SessionChatBox.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/ui/src/components/SessionChatBox.tsx)\n\n \n \n
\n```\n\n资料来源：[packages/web-core/src/shared/components/tasks/TaskDetails/ProcessesTab.tsx:50-80]()\n\n### 执行状态时间线\n\n每个进程的完整生命周期显示在界面中：\n\n```typescript\n\n {t('processes.started', { date: formatDate(process.started_at) })}\n {process.completed_at && (\n {t('processes.completed', { date: formatDate(process.completed_at) })}\n )}\n
\n```\n\n资料来源：[packages/web-core/src/shared/components/tasks/TaskDetails/ProcessesTab.tsx:75-85]()\n\n## 会话与工作区关联\n\n### 会话状态显示\n\n`SessionChatBox` 组件在会话界面展示当前工作区的执行摘要：\n\n| 指标 | 显示格式 | 颜色编码 |\n|------|----------|----------|\n| 文件变更数 | `+N files` | 默认文本色 |\n| 新增行数 | `+{linesAdded}` | 绿色 (text-success) |\n| 删除行数 | `-{linesRemoved}` | 红色 (text-error) |\n\n```typescript\n\n {t('diff.filesChanged', { count: filesChanged })}\n {(linesAdded !== undefined || linesRemoved !== undefined) && (\n \n {linesAdded !== undefined && (\n +{linesAdded}\n )}\n {linesRemoved !== undefined && (\n -{linesRemoved}\n )}\n \n )}\n\n```\n\n资料来源：[packages/ui/src/components/SessionChatBox.tsx:82-98]()\n\n### 代理图标与导航\n\n会话界面支持代理图标显示和消息导航：\n\n- 代理图标: `renderAgentIcon?.(agent, 'size-icon-xl')`\n- 消息导航: `TurnNavigationPopup` 组件用于跳转历史消息\n- Todo 进度: `TodoProgressPopup` 展示当前 Todo 状态\n\n资料来源：[packages/ui/src/components/SessionChatBox.tsx:103-125]()\n\n## 工作区偏好设置\n\n### UI 状态持久化\n\n`useUiPreferencesStore` 管理工作区相关的 UI 状态：\n\n| 状态键 | 类型 | 用途 |\n|--------|------|------|\n| paneSizes | object | 面板尺寸配置 |\n| collapsedPaths | object | 文件树折叠状态 |\n| fileSearchRepoId | string | 文件搜索仓库 ID |\n| layoutMode | string | 当前布局模式 |\n| workspacePanelStates | object | 各工作区面板状态 |\n| mobileActiveTab | string | 移动端激活标签 |\n\n```typescript\ntoggleLayoutMode: () =>\n set((s) => ({\n layoutMode: s.layoutMode === 'workspaces' ? 'kanban' : 'workspaces',\n })),\n```\n\n资料来源：[packages/web-core/src/shared/stores/useUiPreferencesStore.ts:50-80]()\n\n### 文件树折叠状态持久化\n\n系统支持按工作区独立保存文件树折叠状态：\n\n```typescript\nexport function usePersistedCollapsedPaths(\n workspaceId: string | undefined\n): [Set\n
\n\n# 编码代理集成\n\n## 概述\n\nVibe Kanban 的编码代理集成（Coding Agent Integration）模块是该平台的核心功能之一，旨在为软件工程师提供与多种 AI 编码代理无缝协作的工作环境。该系统允许用户通过统一的界面管理、配置和切换不同的编码代理，在专用工作空间中执行代码任务，同时保持与项目看板（Kanban）的紧密集成。\n\n根据项目 README 说明，Vibe Kanban 已支持超过 **10 种编码代理**，包括：\n\n- Claude Code\n- Codex\n- Gemini CLI\n- GitHub Copilot\n- Amp\n- Cursor\n- OpenCode\n- Droid\n- CCR\n- Qwen Code\n\n资料来源：[README.md:32]()\n\n## 架构设计\n\n### 整体架构\n\nVibe Kanban 的编码代理集成采用模块化架构设计，核心组件位于 `crates/executors` 目录下的 Rust crate 中。该架构支持动态代理发现、多代理配置管理以及统一的执行接口。\n\n```mermaid\ngraph TD\n A[用户界面层相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/BloopAI/vibe-kanban/blob/main/README.md)\n- [packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx)\n- [packages/web-core/src/shared/keyboard/useWorkspaceShortcuts.ts](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/keyboard/useWorkspaceShortcuts.ts)\n- [packages/web-core/src/shared/dialogs/command-bar/WorkspaceSelectionDialog.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/dialogs/command-bar/WorkspaceSelectionDialog.tsx)\n- [packages/ui/src/components/CommandBar.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/ui/src/components/CommandBar.tsx)\n- [packages/ui/src/components/IssueCommentsSection.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/ui/src/components/IssueCommentsSection.tsx)\n- [crates/remote/src/db/issues.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/remote/src/db/issues.rs)\n\n> **注意**：本页面部分内容基于仓库结构的推断分析。由于仓库已宣布停止运营（sunsetting），部分执行器核心源码文件（如 `crates/executors/src/` 目录下的文件）未在当前检索上下文中完整获取。以下文档综合了 README 说明、UI 组件代码、以及已知的产品功能描述进行编写。\n\npackages/ui] --> B[Web Core 层
packages/web-core]\n B --> C[执行器抽象层
crates/executors]\n C --> D[Claude 执行器]\n C --> E[Codex 执行器]\n C --> F[其他执行器]\n G[配置文件
Profile] --> C\n H[工作空间状态
Workspace State] --> B\n```\n\n### 执行器模块结构\n\n根据仓库结构分析，执行器模块的主要组织方式如下：\n\n| 模块路径 | 说明 |\n|---------|------|\n| `crates/executors/src/lib.rs` | 执行器库入口，定义公共 API |\n| `crates/executors/src/executor_discovery.rs` | 动态发现机制，支持运行时检测可用代理 |\n| `crates/executors/src/profile.rs` | 执行器配置管理，存储用户偏好和代理参数 |\n| `crates/executors/src/executors/mod.rs` | 执行器通用抽象接口 |\n| `crates/executors/src/executors/claude/mod.rs` | Claude Code 专用执行器实现 |\n| `crates/executors/src/executors/codex/mod.rs` | Codex 专用执行器实现 |\n| `shared/schemas/claude_code.json` | Claude Code 通信协议 Schema |\n\n资料来源：[README.md:32]()\n\n## 配置管理\n\n### 执行器配置（Profile）\n\n每个编码代理都通过 Profile 配置进行管理。配置系统支持以下关键参数：\n\n| 配置项 | 类型 | 说明 |\n|-------|------|------|\n| `agent_type` | String | 代理类型标识符（如 `claude`, `codex`） |\n| `api_key` | String | API 认证密钥 |\n| `model` | String | 指定使用的模型版本 |\n| `temperature` | Float | 生成随机性控制参数 |\n| `max_tokens` | Integer | 单次响应最大 token 数 |\n| `custom_flags` | Object | 代理特定的额外参数 |\n\n配置存储通过 Zustand store `useUiPreferencesStore` 进行前端状态管理：\n\n```typescript\n// packages/web-core/src/shared/stores/useUiPreferencesStore.ts\ntoggleLayoutMode: () =>\n set((s) => ({\n layoutMode: s.layoutMode === 'workspaces' ? 'kanban' : 'workspaces',\n })),\n```\n\n资料来源：[packages/web-core/src/shared/stores/useUiPreferencesStore.ts:45]()\n\n### UI 配置选择器\n\n在用户界面中，代理和配置的选择通过 `AgentSelector` 和 `ConfigSelector` 组件实现。这些组件出现在工作空间创建和冲突解决对话框中：\n\n```typescript\n// packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx\n{profiles && createNewSession && (\n
\n
\n)}\n```\n\n资料来源：[packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx:85-96]()\n\n## 工作空间集成\n\n### 工作空间选择\n\n编码代理在特定的工作空间（Workspace）中执行。用户可以通过命令面板（Command Bar）或专用对话框选择代理的工作空间：\n\n```typescript\n// packages/web-core/src/shared/dialogs/command-bar/WorkspaceSelectionDialog.tsx\n{displayedWorkspaces.map((workspace) => (\n \n \n {t('processes.started', {\n date: formatDate(process.started_at),\n })}\n \n {process.completed_at && (\n \n {t('processes.completed', {\n date: formatDate(process.completed_at),\n })}\n \n )}\n
\n```\n\n支持的操作包括：\n\n| 功能 | 触发方式 | 说明 |\n|-----|---------|------|\n| 复制日志 | 按钮点击 | 将执行日志复制到剪贴板 |\n| 查看详情 | 列表项点击 | 显示特定进程的详细信息 |\n\n资料来源：[packages/web-core/src/shared/components/tasks/TaskDetails/ProcessesTab.tsx:1-50]()\n\n## 工单与评论集成\n\n### 评论系统\n\n编码代理的工作成果通过工单评论系统进行交流：\n\n```typescript\n// packages/ui/src/components/IssueCommentsSection.tsx\ninterface IssueCommentsSectionProps {\n comments: IssueCommentData[];\n commentInput: string;\n onCommentInputChange: (value: string) => void;\n onSubmitComment: () => void;\n editingCommentId: string | null;\n editingValue: string;\n onEditingValueChange: (value: string) => void;\n onStartEdit: (commentId: string) => void;\n onSaveEdit: () => void;\n onCancelEdit: () => void;\n onDeleteComment: (id: string) => void;\n reactionsByCommentId: MapCreate Issue] --> B[规划任务
Plan Tasks]\n B --> C[创建工作空间
Create Workspace]\n C --> D[选择编码代理
Select Agent]\n D --> E[执行编码任务
Execute Tasks]\n E --> F{检查结果}\n F -->|有冲突| G[解决冲突
Resolve Conflicts]\n G --> D\n F -->|成功| H[审查 Diff
Review Diff]\n H --> I[创建 PR
Create PR]\n I --> J[合并代码
Merge]\n```\n\n## 平台状态说明\n\n根据项目 README 公告，**Vibe Kanban 项目已于近期宣布停止运营（sunsetting）**。相关公告可在 [vibekanban.com/blog/shutdown](https://www.vibekanban.com/blog/shutdown) 查看。\n\n资料来源：[README.md:1-10]()\n\n## 总结\n\nVibe Kanban 的编码代理集成系统通过以下核心机制实现与多种 AI 编码代理的无缝协作：\n\n1. **模块化执行器架构**：基于 Rust crate 的插件式设计，支持动态发现和加载不同的编码代理\n2. **统一配置管理**：Profile 系统提供灵活的代理参数配置能力\n3. **深度工作空间集成**：编码代理在隔离的工作空间中执行，与 Git 仓库和工单系统紧密关联\n4. **丰富的交互接口**：支持快捷键、命令面板、冲突解决对话框等多种交互方式\n5. **完整的进程监控**：提供进程状态追踪、日志管理和实时反馈机制\n\n---\n\n\n\n## 数据库模型与迁移\n\n### 相关页面\n\n相关主题：[系统架构总览](#architecture-overview), [本地 API 服务器](#api-server), [工作区管理与执行](#workspace-management)\n\n
\n
\n\n# 数据库模型与迁移\n\n## 概述\n\nVibe Kanban 项目采用 **Rust 后端 + SQLite 本地数据库** 的架构模式。数据库层位于 `crates/db` 目录，包含数据模型定义和数据库迁移脚本。项目的数据库设计遵循 Rust 生态系统的最佳实践，使用 Diesel ORM 框架进行数据库操作。\n\n项目的数据模型涵盖了核心业务实体：**Project（项目）**、**Workspace（工作空间）**、**Session（会话）** 以及相关的关联数据。前端通过 API 与后端进行数据交互，后端负责数据库的读写操作。\n\n---\n\n## 架构分层\n\n### 系统架构概览\n\n```graph TD\n subgraph 前端层[\"前端层 (React/TypeScript)\"]\n A[Web UI]\n B[状态管理 Store]\n C[API 客户端]\n end\n\n subgraph 后端层[\"后端层 (Rust/Axum)\"]\n D[API 路由]\n E[业务逻辑]\n F[数据库访问层]\n end\n\n subgraph 数据层[\"数据层 (SQLite)\"]\n G[数据库文件]\n H[迁移脚本]\n end\n\n A --> B\n B --> C\n C --> D\n D --> E\n E --> F\n F --> G\n F --> H\n```\n\n项目采用分层架构，数据层位于最底层。前端通过 REST API 与后端通信，后端使用 Diesel ORM 与 SQLite 数据库交互。\n\n---\n\n## 核心数据模型\n\n### 模型组织结构\n\n数据库模型文件位于 `crates/db/src/models/` 目录下，采用模块化设计：\n\n| 模块文件 | 主要职责 | 关键类型 |\n|----------|----------|----------|\n| `mod.rs` | 模块导出和聚合 | 模型 trait 定义 |\n| `project.rs` | 项目实体模型 | Project |\n| `workspace.rs` | 工作空间模型 | Workspace |\n| `session.rs` | 会话模型 | Session |\n\n资料来源：[crates/db/src/models/mod.rs]()\n\n### Project（项目）\n\n项目是 Vibe Kanban 中的顶级组织单元。一个项目包含多个工作空间，并关联特定的用户和配置信息。\n\n```\nProject {\n id: String, // 唯一标识符\n name: String, // 项目名称\n color: String, // 展示颜色（十六进制）\n created_at: DateTime, // 创建时间\n updated_at: DateTime, // 更新时间\n user_id: String, // 所属用户ID\n}\n```\n\n### Workspace（工作空间）\n\n工作空间代表一个编码代理的执行环境，与 Git 分支关联。每个工作空间有独立的状态跟踪。\n\n```\nWorkspace {\n id: String,\n name: String,\n project_id: String, // 关联项目ID\n branch: String, // Git 分支名\n is_archived: Boolean, // 是否归档\n is_running: Boolean, // 是否正在运行\n is_pinned: Boolean, // 是否固定\n files_changed: Integer, // 变更文件数\n lines_added: Integer, // 新增行数\n lines_removed: Integer, // 删除行数\n latest_process_status: Option相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/server/src/routes/oauth.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/server/src/routes/oauth.rs)\n- [packages/web-core/src/shared/stores/useWorkspaceDiffStore.ts](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/stores/useWorkspaceDiffStore.ts)\n- [packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx)\n- [packages/web-core/src/shared/hooks/useAzureAttachments.ts](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/hooks/useAzureAttachments.ts)\n- [packages/remote-web/src/pages/HomePage.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/remote-web/src/pages/HomePage.tsx)\n- [packages/ui/src/components/CommandBar.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/ui/src/components/CommandBar.tsx)\n\n
\n\n# 本地 API 服务器\n\n## 概述\n\nVibe Kanban 的本地 API 服务器是基于 Rust 构建的后端服务，负责处理前端应用与远程服务之间的通信、OAuth 认证流程、Workspace 生命周期管理以及会话状态维护。该服务器作为本地代理层，为 Web 前端提供统一的 API 接口，同时管理 GitHub 集成和项目数据同步。\n\n本地 API 服务器的核心职责包括：\n\n- 作为前端与远程后端之间的中间层，转发请求和响应\n- 处理 OAuth 2.0 认证流程，包括 GitHub CLI 认证\n- 管理 Workspace 的创建、更新和删除操作\n- 处理会话（Session）的创建、查询和状态同步\n- 提供文件系统操作和终端命令执行的桥接能力\n\n## 技术架构\n\n### 技术栈\n\n| 组件 | 技术选型 | 说明 |\n|------|----------|------|\n| 运行时 | Rust | 高性能、低内存占用的系统编程语言 |\n| Web 框架 | Axum | 基于 Tokio 异步运行时的高性能 Web 框架 |\n| 路由系统 | Tower Router | 模块化的路由中间件系统 |\n| 序列化 | Serde | 通用的序列化/反序列化框架 |\n| 异步运行时 | Tokio | Rust 异步运行时 |\n\n资料来源：[crates/server/src/lib.rs:1-50]()\n\n### 模块结构\n\n```mermaid\ngraph TD\n A[crates/server/src] --> B[main.rs - 入口点]\n A --> C[lib.rs - 库定义]\n A --> D[routes/ - 路由模块]\n A --> E[middleware/ - 中间件]\n \n D --> D1[mod.rs - 路由聚合]\n D --> D2[workspaces/ - Workspace 路由]\n D --> D3[sessions/ - 会话路由]\n D --> D4[oauth.rs - OAuth 路由]\n \n E --> E1[mod.rs - 中间件聚合]\n```\n\n## 核心模块\n\n### 主入口 (main.rs)\n\n`main.rs` 是服务器进程的启动入口，负责初始化日志系统、配置加载和 HTTP 服务器的绑定。服务器默认监听本地端口，支持配置化端口设置。\n\n主要启动流程：\n\n1. 解析命令行参数和配置文件\n2. 初始化日志记录器（支持结构和日志级别配置）\n3. 建立数据库连接池（如适用）\n4. 挂载所有路由模块\n5. 启动 HTTP 服务器监听\n\n### 路由模块 (routes/)\n\n#### 路由聚合 (routes/mod.rs)\n\n路由模块作为中央聚合点，将所有子路由统一注册到主路由器。该模块定义了基础路径前缀和共享的路由配置。\n\n#### Workspace 核心路由 (routes/workspaces/core.rs)\n\nWorkspace 路由是服务器最核心的功能模块之一，负责处理与编码代理工作区相关的所有 API 请求。\n\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/workspaces` | GET | 列出当前项目的所有 Workspace |\n| `/api/workspaces` | POST | 创建新的 Workspace |\n| `/api/workspaces/:id` | GET | 获取特定 Workspace 的详细信息 |\n| `/api/workspaces/:id` | PATCH | 更新 Workspace 配置 |\n| `/api/workspaces/:id` | DELETE | 删除 Workspace |\n| `/api/workspaces/:id/processes` | GET | 获取 Workspace 内运行中的进程 |\n\n资料来源：[crates/server/src/routes/workspaces/core.rs:1-100]()\n\n#### 会话路由 (routes/sessions/mod.rs)\n\n会话路由管理 Workspace 内的编码代理会话，包括会话创建、状态查询和日志获取。\n\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/workspaces/:id/sessions` | GET | 获取会话列表 |\n| `/api/workspaces/:id/sessions` | POST | 创建新会话 |\n| `/api/sessions/:sessionId` | GET | 获取会话详情 |\n| `/api/sessions/:sessionId/logs` | GET | 获取会话执行日志 |\n\n资料来源：[crates/server/src/routes/sessions/mod.rs:1-80]()\n\n#### OAuth 路由 (routes/oauth.rs)\n\nOAuth 路由处理 GitHub 认证流程的回掉逻辑。当用户完成 GitHub 授权后，GitHub 会重定向到本地服务器的回掉端点。\n\n```rust\nResponse::builder()\n .status(StatusCode::OK)\n .header(\"content-type\", \"text/html; charset=utf-8\")\n .body(body)\n .unwrap()\n```\n\nOAuth 流程包含以下步骤：\n\n1. 用户发起认证请求\n2. 服务器生成临时状态令牌\n3. 重定向到 GitHub 授权页面\n4. 用户授权后回调到本地服务器\n5. 服务器验证状态令牌并交换访问令牌\n6. 返回认证结果页面\n\n资料来源：[crates/server/src/routes/oauth.rs:1-50]()\n\n### 中间件模块 (middleware/)\n\n中间件模块提供了请求处理的横切关注点，包括：\n\n| 中间件 | 功能 |\n|--------|------|\n| 认证中间件 | 验证请求头中的 Bearer Token |\n| 日志中间件 | 记录请求路径、方法和响应时间 |\n| CORS 中间件 | 处理跨域资源共享策略 |\n| 错误处理中间件 | 统一格式化错误响应 |\n\n资料来源：[crates/server/src/middleware/mod.rs:1-60]()\n\n## 请求处理流程\n\n```mermaid\nsequenceDiagram\n participant Client as 前端客户端\n participant Server as 本地 API 服务器\n participant Remote as 远程后端服务\n \n Client->>Server: HTTP 请求\n Server->>Server: 中间件处理链\n Server->>Remote: 转发请求（添加认证头）\n Remote-->>Server: 远程响应\n Server->>Server: 响应转换/处理\n Server-->>Client: 处理后的响应\n```\n\n## 配置管理\n\n本地 API 服务器支持通过环境变量和配置文件进行配置：\n\n| 配置项 | 环境变量 | 默认值 | 说明 |\n|--------|----------|--------|------|\n| 服务器端口 | `PORT` | 8080 | HTTP 监听端口 |\n| 日志级别 | `RUST_LOG` | info | 日志详细程度 |\n| 远程 API 地址 | `REMOTE_API_URL` | - | 远程后端服务地址 |\n| 数据库连接 | `DATABASE_URL` | - | PostgreSQL 连接字符串 |\n\n## 错误处理\n\n服务器采用统一的错误响应格式：\n\n```json\n{\n \"error\": {\n \"code\": \"WORKSPACE_NOT_FOUND\",\n \"message\": \"指定的工作区不存在\",\n \"details\": {}\n }\n}\n```\n\n常见的错误码包括：\n\n| 错误码 | HTTP 状态码 | 描述 |\n|--------|-------------|------|\n| UNAUTHORIZED | 401 | 认证令牌无效或已过期 |\n| FORBIDDEN | 403 | 无权访问该资源 |\n| NOT_FOUND | 404 | 请求的资源不存在 |\n| VALIDATION_ERROR | 422 | 请求参数验证失败 |\n| INTERNAL_ERROR | 500 | 服务器内部错误 |\n\n## 与前端的集成\n\n前端通过以下方式与本地 API 服务器交互：\n\n1. **固定端口通信**：前端使用固定端口（如 8080）与本地服务器通信\n2. **相对路径代理**：前端请求通过相对路径自动转发到本地服务器\n3. **认证令牌传递**：Bearer Token 在请求头中传递\n4. **OAuth 弹窗**：GitHub 认证通过弹窗完成，结果回写到父窗口\n\n## 启动与部署\n\n### 开发环境启动\n\n```bash\ncd crates/server\ncargo run\n```\n\n### 生产环境构建\n\n```bash\ncargo build --release\n./target/release/vibe-kanban-server\n```\n\n### Docker 部署\n\n服务器支持 Docker 容器化部署，提供轻量级的隔离运行环境。\n\n## 安全考量\n\n- 所有与远程服务的通信使用 HTTPS\n- OAuth 令牌安全存储，不暴露在前端日志中\n- 速率限制防止 API 滥用\n- CORS 策略限制跨域请求来源\n\n---\n\n\n\n## 远程云服务架构\n\n### 相关页面\n\n相关主题：[本地 API 服务器](#api-server), [数据库模型与迁移](#database-models)\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/server/src/lib.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/server/src/lib.rs)\n- [crates/server/src/main.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/server/src/main.rs)\n- [crates/server/src/routes/mod.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/server/src/routes/mod.rs)\n- [crates/server/src/routes/workspaces/core.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/server/src/routes/workspaces/core.rs)\n- [crates/server/src/middleware/mod.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/server/src/middleware/mod.rs)\n- [crates/server/src/routes/sessions/mod.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/server/src/routes/sessions/mod.rs)\n\n
\n\n# 远程云服务架构\n\n## 概述\n\nVibe Kanban 的远程云服务架构为团队协作提供了基础设施支持，允许用户通过远程 Web 界面访问和管理项目。该架构涵盖了身份验证、文件附件、GitHub 集成以及组织管理等功能模块。\n\n根据仓库结构，远程服务主要由 `crates/server`（后端 Rust 服务）、`packages/remote-web`（远程 Web 前端）和 `packages/web-core`（共享核心组件）组成。这种模块化设计使得远程访问与企业内部部署可以共享核心业务逻辑。资料来源：[packages/web-core/src/shared/dialogs/auth/GhCliSetupDialog.tsx:1-50]()\n\n## 核心架构组件\n\n### 后端服务层\n\n后端服务采用 Rust 语言实现，提供高性能的 HTTP API 接口。主要包括以下模块：\n\n| 模块 | 职责 | 关键文件 |\n|------|------|----------|\n| oauth | OAuth 2.0 认证流程处理 | crates/server/src/routes/oauth.rs |\n| routes | HTTP 路由定义与请求处理 | crates/server/src/routes/mod.rs |\n| auth | 身份验证与授权逻辑 | crates/remote/src/auth/mod.rs |\n| github_app | GitHub App 集成 | crates/remote/src/github_app/mod.rs |\n| digest | 数据摘要与校验 | crates/remote/src/digest/mod.rs |\n\n资料来源：[crates/server/src/routes/oauth.rs:1-50]()\n\n### 前端访问层\n\n远程 Web 界面由 React 组件构建，提供用户交互界面。主要页面组件包括：\n\n```mermaid\ngraph TD\n A[HomePage] --> B[OrganizationSection]\n A --> C[ProjectCard]\n B --> D[Projects List]\n C --> E[Remote Connection]\n \n F[GhCliSetupDialog] --> G[GitHub CLI Setup]\n H[ResolveConflictsDialog] --> I[Git Merge Resolution]\n```\n\n资料来源：[packages/remote-web/src/pages/HomePage.tsx:1-100](), [packages/web-core/src/shared/dialogs/auth/GhCliSetupDialog.tsx:1-50]()\n\n## 身份验证系统\n\n### OAuth 认证流程\n\nOAuth 认证是远程服务访问的核心机制。当用户通过浏览器访问远程服务时，系统会显示一个确认页面让用户授权。资料来源：[crates/server/src/routes/oauth.rs:30-45]()\n\n```mermaid\nsequenceDiagram\n participant User\n participant Browser\n participant RemoteServer\n participant GitHub\n \n User->>Browser: 访问远程服务\n Browser->>RemoteServer: 请求授权\n RemoteServer->>GitHub: 重定向到 GitHub OAuth\n GitHub->>User: 显示授权页面\n User->>GitHub: 确认授权\n GitHub->>RemoteServer: 返回授权码\n RemoteServer->>Browser: 显示成功页面\n```\n\n认证成功后会返回以下 HTML 响应格式：\n\n```html\n\n 相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/server/src/routes/oauth.rs](https://github.com/BloopAI/vibe-kanban/blob/main/crates/server/src/routes/oauth.rs)\n- [packages/web-core/src/shared/dialogs/auth/GhCliSetupDialog.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/dialogs/auth/GhCliSetupDialog.tsx)\n- [packages/remote-web/src/pages/HomePage.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/remote-web/src/pages/HomePage.tsx)\n- [packages/web-core/src/shared/hooks/useAzureAttachments.ts](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/hooks/useAzureAttachments.ts)\n- [packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx](https://github.com/BloopAI/vibe-kanban/blob/main/packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx)\n\n \n
\n\n```\n\n资料来源：[crates/server/src/routes/oauth.rs:30-50]()\n\n### GitHub CLI 设置\n\n对于需要本地 GitHub CLI 集成的用户，系统提供了交互式设置流程。设置步骤包括：\n\n1. 检查 GitHub CLI 是否已安装\n2. 通过 Homebrew 安装（如需要）\n3. 完成身份验证\n\n资料来源：[packages/web-core/src/shared/dialogs/auth/GhCliSetupDialog.tsx:15-35]()\n\n## 文件附件系统\n\n远程服务支持 Azure Blob Storage 集成的文件上传功能。附件处理流程涉及多个状态转换：\n\n| 状态 | 描述 | 进度 |\n|------|------|------|\n| pending | 等待上传 | 0% |\n| uploading | 上传中 | 0-99% |\n| confirming | 确认中 | 100% |\n| completed | 上传完成 | - |\n| failed | 上传失败 | - |\n\n资料来源：[packages/web-core/src/shared/hooks/useAzureAttachments.ts:1-60]()\n\n附件上传完成后，系统会返回唯一标识符供后续引用，格式为 `attachment://{id}`。资料来源：[packages/web-core/src/shared/hooks/useAzureAttachments.ts:45-55]()\n\n## 组织与项目管理\n\n### 组织管理\n\n远程 Web 界面允许用户创建或加入组织，以便团队协作。组织管理界面显示了每个组织的名称和项目数量。资料来源：[packages/remote-web/src/pages/HomePage.tsx:60-90]()\n\n```mermaid\ngraph LR\n A[Organizations] -->|包含| B[Projects]\n B -->|包含| C[Workspaces]\n C -->|执行| D[AI Agents]\n```\n\n### 项目卡片组件\n\n每个项目通过 `ProjectCard` 组件展示，支持以下功能：\n\n- 显示项目基本信息（名称、颜色）\n- 远程主机连接管理\n- 快速访问项目工作区\n\n当缺少主机配置时，用户可以触发 `onRequireHost` 回调打开中继设置。资料来源：[packages/remote-web/src/pages/HomePage.tsx:120-160]()\n\n## Git 冲突解决\n\n远程服务提供了冲突解决对话框组件，支持以下功能：\n\n- 显示冲突文件列表（最多显示 5 个）\n- 提示更多冲突文件数量\n- 提供 Agent/Profile 选择器\n- 新会话创建选项\n\n资料来源：[packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx:80-110]()\n\n## 服务启动与配置\n\n后端服务入口点定义在 `crates/remote/src/main.rs`，负责初始化配置并启动 HTTP 服务器。服务支持环境变量配置，包括：\n\n- 数据库连接参数\n- Azure Storage 凭证\n- GitHub App 配置\n- OAuth 回调 URL\n\n资料来源：[crates/remote/src/main.rs:1-30]()\n\n## 安全考虑\n\n远程服务架构实现了多层安全机制：\n\n1. **OAuth 2.0 授权码流程**：防止令牌泄露\n2. **HTML 响应 Content-Type 头**：正确设置 `text/html; charset=utf-8` 资料来源：[crates/server/src/routes/oauth.rs:47-50]()\n3. **会话隔离**：每个远程连接独立管理\n4. **主机验证**：中继设置确保连接安全\n\n## 总结\n\nVibe Kanban 的远程云服务架构通过 Rust 后端和 React 前端的组合，实现了高效的远程协作能力。核心特性包括安全的 OAuth 认证、Azure 文件存储集成、GitHub App 集成以及组织级项目管理。该架构设计遵循了前端与后端分离的原则，同时通过共享的 `web-core` 包确保了本地和远程体验的一致性。\n\n---\n\n\n\n## MCP 服务器实现\n\n### 相关页面\n\n相关主题：[编码代理集成](#coding-agents), [看板任务管理](#kanban-management)\n\n\n
\n {message}
\nYou can close this tab and return to the app.
\n\n
\n\n# MCP 服务器实现\n\n## 概述\n\nMCP（Model Context Protocol）服务器是 Vibe Kanban 项目中用于扩展 AI 代理能力的核心组件。该模块允许外部编码代理通过标准化的 MCP 协议与 Vibe Kanban 系统进行交互，实现任务管理、工作区操作等功能。\n\n## 架构设计\n\n### 模块结构\n\nMCP 实现位于 `crates/mcp` 目录下，采用模块化设计：\n\n| 模块路径 | 功能说明 |\n|---------|---------|\n| `lib.rs` | MCP 服务器核心库定义和导出 |\n| `task_server/mod.rs` | 任务服务器主模块 |\n| `task_server/handler.rs` | 请求处理器实现 |\n| `task_server/tools/mod.rs` | 工具集定义和实现 |\n| `bin/vibe_kanban_mcp.rs` | 可执行入口文件 |\n\n### 核心组件\n\nMCP 服务器的核心组件包括：\n\n1. **服务器入口** - `vibe_kanban_mcp.rs` 作为独立的二进制程序运行\n2. **任务服务器** - 负责处理来自 AI 代理的请求\n3. **工具集** - 定义可用的工具和操作\n4. **请求处理器** - 路由和执行具体的工具调用\n\n## 任务服务器模块\n\n任务服务器（Task Server）是 MCP 服务器的核心实现，负责：\n\n- 接收并解析 MCP 协议请求\n- 管理会话状态\n- 执行工具调用\n- 返回标准化的响应\n\n### 请求处理流程\n\n```mermaid\ngraph TD\n A[MCP 请求] --> B[请求解析器]\n B --> C{请求类型}\n C -->|工具调用| D[工具调度器]\n C -->|资源请求| E[资源处理器]\n C -->|其他| F[错误处理]\n D --> G[执行工具]\n G --> H[结果序列化]\n H --> I[MCP 响应]\n E --> I\n F --> I\n```\n\n## 工具集\n\n工具集定义了 AI 代理可以执行的操作类型。具体工具实现位于 `task_server/tools/mod.rs`。\n\n### 工具分类\n\n| 类别 | 描述 | 典型操作 |\n|-----|------|---------|\n| 任务工具 | 看板任务管理 | 创建、更新、查询任务 |\n| 工作区工具 | 工作区操作 | 打开、关闭、状态查询 |\n| 文件工具 | 文件系统操作 | 读取、写入文件 |\n| Git 工具 | 版本控制操作 | 分支管理、提交操作 |\n\n## MCP 协议实现\n\n### 请求格式\n\nMCP 服务器遵循 Model Context Protocol 规范，请求包含：\n\n- `jsonrpc` - JSON-RPC 版本标识\n- `method` - 方法名称\n- `params` - 参数字典\n- `id` - 请求标识符\n\n### 响应格式\n\n标准响应格式：\n\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"result\": { ... },\n \"id\": \"请求标识符\"\n}\n```\n\n错误响应格式：\n\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"error\": {\n \"code\": \"错误代码\",\n \"message\": \"错误描述\"\n },\n \"id\": \"请求标识符\"\n}\n```\n\n## 配置与部署\n\n### 二进制入口\n\n`crates/mcp/src/bin/vibe_kanban_mcp.rs` 文件定义了可执行程序的入口点：\n\n- 初始化日志系统\n- 加载配置\n- 启动 MCP 服务器\n- 处理生命周期事件\n\n### 配置项\n\n| 配置项 | 说明 | 默认值 |\n|-------|------|-------|\n| 服务器端口 | MCP 服务监听端口 | 随机可用端口 |\n| 日志级别 | 日志详细程度 | info |\n| 超时设置 | 请求处理超时时间 | 30秒 |\n\n## 与前端交互\n\nMCP 服务器作为后端服务，与前端通过 WebSocket 或 HTTP 协议通信。前端组件（如 `CommandBar.tsx` 和 `SessionChatBox.tsx`）提供用户界面，通过这些协议与 MCP 服务器交换数据。\n\n### 数据流\n\n```mermaid\ngraph LR\n A[AI 代理] -->|MCP 协议| B[MCP 服务器]\n B -->|内部 API| C[Vibe Kanban 后端]\n C -->|数据| B\n B -->|MCP 响应| A\n D[前端 UI] -->|WebSocket| B\n```\n\n## 安全性\n\nMCP 服务器实现包含以下安全措施：\n\n1. **请求验证** - 验证所有传入请求的格式和来源\n2. **权限控制** - 基于会话的权限检查\n3. **输入清理** - 防止注入攻击\n4. **超时保护** - 防止资源耗尽攻击\n\n## 扩展指南\n\n### 添加新工具\n\n在 `task_server/tools/mod.rs` 中添加新的工具定义：\n\n1. 定义工具的结构体\n2. 实现工具的 `execute` 方法\n3. 在工具注册表中添加新工具\n4. 添加相应的测试用例\n\n### 注册新处理器\n\n在 `task_server/handler.rs` 中扩展请求处理逻辑：\n\n1. 添加新的处理器函数\n2. 更新路由逻辑\n3. 注册处理程序到服务器\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：BloopAI/vibe-kanban\n\n摘要：发现 19 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：Deployment(Other(Migration failed: error returned from database: (code: 1) no such column: ep.session_id))。\n\n## 1. 安装坑 · 来源证据：Deployment(Other(Migration failed: error returned from database: (code: 1) no such column: ep.session_id))\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Deployment(Other(Migration failed: error returned from database: (code: 1) no such column: ep.session_id))\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b34b2ea1b35a4dc2a4a0eb0681bdb883 | https://github.com/BloopAI/vibe-kanban/issues/2972 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 2. 配置坑 · 来源证据：Support for self-hosted projects and better export\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Support for self-hosted projects and better export\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_19d27caa9e34416a9f282869f76624b0 | https://github.com/BloopAI/vibe-kanban/issues/3396 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安全/权限坑 · 来源证据：[Proposal] JIRA Integration for Vibe Kanban\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Proposal] JIRA Integration for Vibe Kanban\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ab38fe97c4574e2da01ddedd71a4fbac | https://github.com/BloopAI/vibe-kanban/issues/2424 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：Pre-release v0.1.40-20260401153532\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Pre-release v0.1.40-20260401153532\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f4b99d437a4f4fd4989d2b3ef036553b | https://github.com/BloopAI/vibe-kanban/releases/tag/v0.1.40-20260401153532 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：Release v0.1.36\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.1.36\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_527645be4e3f438e81757ef265a70d79 | https://github.com/BloopAI/vibe-kanban/releases/tag/v0.1.36-20260323174633 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：Release v0.1.43\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.1.43\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_53704dc7171446fe86b2017f72212ddc | https://github.com/BloopAI/vibe-kanban/releases/tag/v0.1.43-20260417125614 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 7. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | host_targets=claude, claude_code\n\n## 8. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | README/documentation is current enough for a first validation pass.\n\n## 9. 运行坑 · 来源证据：Pre-release v0.1.39-20260331145823\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Pre-release v0.1.39-20260331145823\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c005a56959634369929ce33eddbdc103 | https://github.com/BloopAI/vibe-kanban/releases/tag/v0.1.39-20260331145823 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 10. 维护坑 · 来源证据：[Request] Support RDS for self hosting in AWS\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[Request] Support RDS for self hosting in AWS\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f613b792c20942519560c0a286a82005 | https://github.com/BloopAI/vibe-kanban/issues/3405 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | last_activity_observed missing\n\n## 12. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：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.\n\n## 14. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 来源证据：Issue: Unclear Git + Bitbucket Setup for Vibe-Kanban (OpenCode) in Docker\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Issue: Unclear Git + Bitbucket Setup for Vibe-Kanban (OpenCode) in Docker\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7d289a7b68ee4299ae4a5e54b0e64e35 | https://github.com/BloopAI/vibe-kanban/issues/3410 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：Pre-release v0.1.37-20260327101540\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Pre-release v0.1.37-20260327101540\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d648fba4c94b4791ac2e7683f6cb1361 | https://github.com/BloopAI/vibe-kanban/releases/tag/v0.1.37-20260327101540 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：remote-v0.1.26\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：remote-v0.1.26\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3f212752e8c142d68ffe2993ac23dd37 | https://github.com/BloopAI/vibe-kanban/releases/tag/remote-v0.1.26 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 18. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | issue_or_pr_quality=unknown\n\n## 19. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：BloopAI/vibe-kanban\n\n摘要：发现 19 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：Deployment(Other(Migration failed: error returned from database: (code: 1) no such column: ep.session_id))。\n\n## 1. 安装坑 · 来源证据：Deployment(Other(Migration failed: error returned from database: (code: 1) no such column: ep.session_id))\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Deployment(Other(Migration failed: error returned from database: (code: 1) no such column: ep.session_id))\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b34b2ea1b35a4dc2a4a0eb0681bdb883 | https://github.com/BloopAI/vibe-kanban/issues/2972 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 2. 配置坑 · 来源证据：Support for self-hosted projects and better export\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Support for self-hosted projects and better export\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_19d27caa9e34416a9f282869f76624b0 | https://github.com/BloopAI/vibe-kanban/issues/3396 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安全/权限坑 · 来源证据：[Proposal] JIRA Integration for Vibe Kanban\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Proposal] JIRA Integration for Vibe Kanban\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ab38fe97c4574e2da01ddedd71a4fbac | https://github.com/BloopAI/vibe-kanban/issues/2424 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：Pre-release v0.1.40-20260401153532\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Pre-release v0.1.40-20260401153532\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f4b99d437a4f4fd4989d2b3ef036553b | https://github.com/BloopAI/vibe-kanban/releases/tag/v0.1.40-20260401153532 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：Release v0.1.36\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.1.36\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_527645be4e3f438e81757ef265a70d79 | https://github.com/BloopAI/vibe-kanban/releases/tag/v0.1.36-20260323174633 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：Release v0.1.43\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.1.43\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_53704dc7171446fe86b2017f72212ddc | https://github.com/BloopAI/vibe-kanban/releases/tag/v0.1.43-20260417125614 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 7. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | host_targets=claude, claude_code\n\n## 8. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | README/documentation is current enough for a first validation pass.\n\n## 9. 运行坑 · 来源证据：Pre-release v0.1.39-20260331145823\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Pre-release v0.1.39-20260331145823\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c005a56959634369929ce33eddbdc103 | https://github.com/BloopAI/vibe-kanban/releases/tag/v0.1.39-20260331145823 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 10. 维护坑 · 来源证据：[Request] Support RDS for self hosting in AWS\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[Request] Support RDS for self hosting in AWS\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f613b792c20942519560c0a286a82005 | https://github.com/BloopAI/vibe-kanban/issues/3405 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | last_activity_observed missing\n\n## 12. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：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.\n\n## 14. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 来源证据：Issue: Unclear Git + Bitbucket Setup for Vibe-Kanban (OpenCode) in Docker\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Issue: Unclear Git + Bitbucket Setup for Vibe-Kanban (OpenCode) in Docker\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7d289a7b68ee4299ae4a5e54b0e64e35 | https://github.com/BloopAI/vibe-kanban/issues/3410 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：Pre-release v0.1.37-20260327101540\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Pre-release v0.1.37-20260327101540\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d648fba4c94b4791ac2e7683f6cb1361 | https://github.com/BloopAI/vibe-kanban/releases/tag/v0.1.37-20260327101540 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：remote-v0.1.26\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：remote-v0.1.26\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3f212752e8c142d68ffe2993ac23dd37 | https://github.com/BloopAI/vibe-kanban/releases/tag/remote-v0.1.26 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 18. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | issue_or_pr_quality=unknown\n\n## 19. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# vibe-kanban - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 vibe-kanban 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：claude / Claude Code\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Get 10X more out of Claude Code, Codex or any coding agent 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. project-introduction：项目介绍与安装。围绕“项目介绍与安装”模拟一次用户任务，不展示安装或运行结果。\n2. architecture-overview：系统架构总览。围绕“系统架构总览”模拟一次用户任务，不展示安装或运行结果。\n3. development-setup：开发环境搭建。围绕“开发环境搭建”模拟一次用户任务，不展示安装或运行结果。\n4. kanban-management：看板任务管理。围绕“看板任务管理”模拟一次用户任务，不展示安装或运行结果。\n5. workspace-management：工作区管理与执行。围绕“工作区管理与执行”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. project-introduction\n输入：用户提供的“项目介绍与安装”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. architecture-overview\n输入：用户提供的“系统架构总览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. development-setup\n输入：用户提供的“开发环境搭建”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. kanban-management\n输入：用户提供的“看板任务管理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. workspace-management\n输入：用户提供的“工作区管理与执行”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / project-introduction：Step 1 必须围绕“项目介绍与安装”形成一个小中间产物，并等待用户确认。\n- Step 2 / architecture-overview：Step 2 必须围绕“系统架构总览”形成一个小中间产物，并等待用户确认。\n- Step 3 / development-setup：Step 3 必须围绕“开发环境搭建”形成一个小中间产物，并等待用户确认。\n- Step 4 / kanban-management：Step 4 必须围绕“看板任务管理”形成一个小中间产物，并等待用户确认。\n- Step 5 / workspace-management：Step 5 必须围绕“工作区管理与执行”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/BloopAI/vibe-kanban\n- https://github.com/BloopAI/vibe-kanban#readme\n- README.md\n- Cargo.toml\n- package.json\n- npx-cli/package.json\n- crates/server/src/lib.rs\n- crates/remote/src/lib.rs\n- crates/executors/src/lib.rs\n- packages/local-web/src/routes/__root.tsx\n- packages/remote-web/src/routes/__root.tsx\n- rust-toolchain.toml\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 vibe-kanban 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：BloopAI/vibe-kanban\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx vibe-kanban\n```\n\n来源：https://github.com/BloopAI/vibe-kanban#readme\n\n## 来源\n\n- repo: https://github.com/BloopAI/vibe-kanban\n- docs: https://github.com/BloopAI/vibe-kanban#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_e55369cc1fa641a2b59247e944d86e7c"
}