Vibe Squad 部署教程：多模型 AI 编排系统

Vibe Squad 是一个多模型 AI 编排系统，它通过一个协调器 (Chrono) 将任务路由给 71 个基于 Markdown 定义的角色专家，这些专家分属 Codex、Claude、Gemini、Grok 和 Kimi 五个模型家族。每个任务在隔离的 git worktree 中执行，并由不同模型进行审查，最终在一个 tmux 会话中完成所有操作，无需额外服务器。本教程将指导你在 macOS 上完成部署和基本使用。

核心概念与架构

理解 Vibe Squad 的设计哲学是有效使用它的关键：

  • 行为即 Markdown：专家的角色定义、能力、技能和模式都以 Markdown 文件 形式存在。你可以直接阅读和编辑这些文件来改变系统行为，无需修改核心代码。
  • 协调器 (Chrono)：你只与 Chrono 交互。它负责将你的目标转化为计划，匹配合适的专家和模型，启动工作，并协调审查。
  • 隔离执行：每个任务都在一个独立的 git worktree 中运行，拥有明确限定的读写范围 (write_scope/read_scope)。变更在通过测试和独立审查后才会被集成。注意：这是一种自主性工具，而非安全沙箱，因为 Worker 在你的主机上以你的权限执行。
  • 独立审查：一个任务完成后，会由来自不同模型家族的另一个专家进行审查，防止单个模型自审自批。
  • 持久化记忆：每次运行学到的经验教训会被记录在私有 Markdown 仓库中，并在后续会话中被 Recall，避免重复犯错。

第一步：环境准备与前提条件

Vibe Squad 目前仅支持 macOS。你需要确保以下依赖已安装：

  • 核心工具：tmux, fswatch, jq, curl
  • Python 环境：Python 3.13 和 uv (一个快速的 Python 包管理器)
  • 模型 CLI：为你想使用的模型家族安装并认证对应的原生 CLI 工具：
    • Claude (claude)
    • Codex (codex)
    • Gemini (agy)
    • Kimi (需安装其 CLI)
    • Grok (需要 xAI API 密钥)

安装依赖 (示例)：

1
2
3
4
5
6
7
8
# 使用 Homebrew 安装工具
brew install tmux fswatch jq curl

# 安装 Python 3.13 (如果未安装)
brew install python@3.13

# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

第二步：创建私有记忆仓库

Vibe Squad 的持久化记忆需要存储在你的私有仓库中，而不是公共仓库。

1
2
3
4
5
6
7
8
9
# 1. 创建记忆仓库目录 (例如 ~/Obsidian-Chrono)
mkdir -p "$HOME/Obsidian-Chrono"

# 2. 创建必要的配置文件
printf '%s\n' '{"vault_id":"my-private-vault","schema_version":1}' \
  > "$HOME/Obsidian-Chrono/.chrono-vault"

# 3. 设置环境变量，指向该仓库
export CHRONO_VAULT_ROOT="$HOME/Obsidian-Chrono"

建议将此环境变量添加到你的 shell 配置文件 (如 .zshrc 或 .bashrc) 中。

第三步：克隆与安装 Vibe Squad

1
2
3
4
5
6
7
8
9
10
11
12
# 1. 克隆项目仓库
git clone https://github.com/mtarcure/claude-vibe-squad.git
cd claude-vibe-squad

# 2. 同步 Python 环境 (创建虚拟环境并安装依赖)
uv sync

# 3. 安装 Git 预提交钩子 (用于防止私有数据泄露)
bash docs/install/install-pre-commit-hook.sh

# 4. 运行环境诊断，检查所有依赖是否正确
bin/squad doctor

确保 bin/squad doctor 命令没有报错。

第四步：启动 Vibe Squad 控制室

启动过程会打开一个 tmux 会话，其中包含 Chrono 协调器窗口和一个状态窗口。

1
2
# 启动控制室
bin/squad up
  • 你可以使用 Ctrl-b d 来分离 (detach) tmux 会话，让其在后台运行。
  • 使用 bin/squad attach 可以重新连接到运行中的控制室。
  • 在 tmux 会话中，Chrono 所在的窗格就是你与系统交互的地方。

第五步：基本使用与工作流

  1. 与 Chrono 对话：在 tmux 的 Chrono 窗格中，直接用自然语言提出你的需求。

    1
    2
    "Build a polished landing page, test it in the browser, and show me the result."
    "Research this product idea, compare the competitors, and turn it into a cited brief."

  2. 任务处理：Chrono 会分析你的请求，并决定使用 Project 或 Bounty 模式。

    • Project：用于软件、研究、内容创作等。生命周期为：范围 → 计划 → 构建 → 验证 → (必要时) 审查 → 交付 → 记忆。
    • Bounty：用于授权的安全测试工作，有更严格的验证和证据要求。

  3. 观察与介入：你可以在 Chrono 窗格中观察其规划和任务分发过程。如果需要，你可以随时中断或引导 Chrono。

第六步：(可选) 高级配置与守护进程

Vibe Squad 提供了一个可选的 launchd 守护进程，用于启用 tmux 状态栏中的 ● daemon 指示器和 MCP HTTP 桥接。

1
2
3
4
5
# 仅安装守护进程
bash bin/install-routines.sh --daemon-only

# 安装所有例行代理 (包括守护进程)
bash bin/install-routines.sh

安全警告：这些代理会以你的用户权限执行代码。在检出或切换到一个未经审查的分支（尤其是来自 Fork 的 PR）之前，建议先卸载代理，完成审查后再重新加载。具体的 launchctl 命令请参考项目文档。

故障排查与注意事项

  • bin/squad doctor 报错：根据输出信息安装缺失的依赖或认证 CLI。这是解决大多数启动问题的关键步骤。
  • 权限与安全问题：重申：Worker 在你的主机上以你的权限执行命令。write_scope 是在集成时强制执行的，而非 Worker 执行时的访问控制屏障。因此，请仅在可信项目上使用，并谨慎授予任务写入权限。
  • 模型 API 密钥：确保所有需要 API 密钥的模型（如 Grok）都已正确配置其环境变量。
  • tmux 使用：如果对 tmux 不熟悉，建议先了解基本的 tmux 命令（如窗格切换、分离、重新连接）。

总而言之，Vibe Squad 是一个面向高级用户的、强大而复杂的 AI 编排系统。它通过将行为与代码分离，提供了极高的灵活性和可定制性。但这份灵活性伴随着责任，尤其是在安全模型方面。建议你从 bin/squad doctor 开始，确保环境就绪，然后通过一个简单的 Project 任务（如“生成一个简单的 HTML 页面”）来体验其核心工作流，再逐步探索更高级的功能。