> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/BloopAI/vibe-kanban) · [上游 README](https://github.com/BloopAI/vibe-kanban/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
充分发挥 Claude Code、Gemini CLI、Codex、Amp 及其他编程智能体（coding agents）的 10 倍效能……
Vibe Kanban 即将停止服务。
阅读公告。
## 概览
在软件工程师将大部分时间用于规划和审查编程智能体的世界里，提升交付效率最有影响力的方式，就是加快规划与审查的速度。
Vibe Kanban 正是为此而构建。使用看板（kanban）议题来规划工作，可私下进行，也可与团队协作。准备开始时，创建工作区（workspaces），让编程智能体在其中执行。
- **用看板议题进行规划** — 在看板上创建、排序并分配议题
- **在工作区中运行编程智能体** — 每个工作区为智能体提供分支、终端和开发服务器
- **审查 diff 并留下行内评论** — 无需离开界面即可直接向智能体发送反馈
- **预览你的应用** — 内置浏览器，支持开发者工具、检查模式与设备模拟
- **在 10 余种编程智能体之间切换** — Claude Code、Codex、Gemini CLI、GitHub Copilot、Amp、Cursor、OpenCode、Droid、CCR 和 Qwen Code
- **创建拉取请求并合并** — 使用 AI 生成的描述打开 PR，在 GitHub 上审查并合并
一条命令。描述工作、审查 diff、交付上线。
```bash
npx vibe-kanban
```
## 安装
请确保你已使用自己偏好的编程智能体完成身份验证。完整支持的编程智能体列表见[文档](https://vibekanban.com/docs/supported-coding-agents). Then in your terminal run:
```bash
npx vibe-kanban
```
## 文档
前往[网站](https://vibekanban.com/docs) 获取最新文档与用户指南。
## 自托管
想自行托管 Vibe Kanban Cloud 实例？请参阅我们的[自托管指南](https://vibekanban.com/docs/self-hosting/deploy-docker).
## 支持
我们使用 [GitHub Discussions](https://github.com/BloopAI/vibe-kanban/discussions) 提交功能请求。请开启讨论以创建功能请求。如遇 bug，请在本仓库中提交 issue。
## 贡献
我们更希望先通过 [GitHub Discussions](https://github.com/BloopAI/vibe-kanban/discussions) 或 [Discord](https://discord.gg/AC4nwVtJM3), 与核心团队沟通想法与变更，以便讨论实现细节以及与现有路线图的契合度。请勿在未与团队讨论你的提案前提交 PR。
## 开发
### 前置要求
- [Rust](https://rustup.rs/)（最新稳定版）
- [Node.js](https://nodejs.org/)（>=20）
- [pnpm](https://pnpm.io/)（>=8）
其他开发工具：
```bash
cargo install cargo-watch
cargo install sqlx-cli
```
安装依赖：
```bash
pnpm i
```
### 运行开发服务器
```bash
pnpm run dev
```
这将启动后端与 Web 应用。空白数据库将从 `dev_assets_seed` 文件夹复制。
### 构建 Web 应用
仅构建 Web 应用：
```bash
cd packages/local-web
pnpm run build
```
### 从源码构建（macOS）
1. 运行 `./local-build.sh`
2. 使用 `cd npx-cli && node bin/cli.js` 进行测试
### 环境变量
以下环境变量可在构建时或运行时配置：
| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `POSTHOG_API_KEY` | Build-time | Empty | PostHog 分析 API 密钥（为空时禁用分析） |
| `POSTHOG_API_ENDPOINT` | Build-time | Empty | PostHog 分析端点（为空时禁用分析） |
| `PORT` | Runtime | Auto-assign | **生产环境**：服务器端口。**开发环境**：前端端口（后端使用 PORT+1） |
| `BACKEND_PORT` | Runtime | `0` (auto-assign) | 后端服务器端口（仅开发模式，覆盖 PORT+1） |
| `FRONTEND_PORT` | Runtime | `3000` | 前端开发服务器端口（仅开发模式，覆盖 PORT） |
| `HOST` | Runtime | `127.0.0.1` | 后端服务器主机 |
| `MCP_HOST` | Runtime | Value of `HOST` | MCP 服务器连接主机（在 Windows 上当 `HOST=0.0.0.0` 时使用 `127.0.0.1`） |
| `MCP_PORT` | Runtime | Value of `BACKEND_PORT` | MCP 服务器连接端口 |
| `DISABLE_WORKTREE_CLEANUP` | Runtime | Not set | 禁用所有 git worktree 清理，包括孤立与过期工作区清理（用于调试） |
| `VK_ALLOWED_ORIGINS` | Runtime | Not set | 允许向后端 API 发起请求的源（origin）列表，以逗号分隔（例如 `https://my-vibekanban-frontend.com`） |
| `VK_SHARED_API_BASE` | Runtime | Not set | 本地桌面应用所使用的远程/云端 API 基础 URL |
| `VK_SHARED_RELAY_API_BASE` | Runtime | Not set | 隧道模式连接所使用的中继 API 基础 URL |
| `VK_TUNNEL` | Runtime | Not set | 设置后启用中继隧道模式（需要中继 API 基础 URL） |
**构建时变量**必须在运行 `pnpm run build` 时设置。**运行时变量**在应用启动时读取。
#### 使用反向代理或自定义域名进行自托管
在反向代理（例如 nginx、Caddy、Traefik）之后运行 Vibe Kanban，或使用自定义域名时，必须设置 `VK_ALLOWED_ORIGINS` 环境变量。否则，浏览器的 Origin 请求头将与后端预期主机不匹配，API 请求将被拒绝并返回 403 Forbidden 错误。
将其设置为前端可访问的完整源 URL：
```bash
# Single origin
VK_ALLOWED_ORIGINS=https://vk.example.com
# Multiple origins (comma-separated)
VK_ALLOWED_ORIGINS=https://vk.example.com,https://vk-staging.example.com
```
### 远程部署
在远程服务器上运行 Vibe Kanban（例如通过 systemctl、Docker 或云托管）时，可配置编辑器通过 SSH 打开项目：
1. **通过隧道访问**：使用 Cloudflare Tunnel、ngrok 或类似工具暴露 Web UI
2. 在 Settings → Editor Integration 中**配置远程 SSH**：
- 将 **Remote SSH Host** 设置为服务器主机名或 IP
- 将 **Remote SSH User** 设置为 SSH 用户名（可选）
3. **前置要求**：
- 本地机器到远程服务器的 SSH 访问
- 已配置 SSH 密钥（免密认证）
- VSCode Remote-SSH 扩展
配置完成后，“Open in VSCode”按钮将生成类似 `vscode://vscode-remote/ssh-remote+user@host/path` 的 URL，用于打开本地编辑器并连接远程服务器。
详见[文档](https://vibekanban.com/docs/settings/general) 中的详细设置说明。