squad 是一个轻量级的多 AI 智能体终端协作工具。它让 Claude Code、Gemini CLI、Codex CLI、OpenCode 等 AI 工具在不同终端里通过简单的 CLI 命令 + 本地 SQLite 实时协作，没有守护进程、没有后台服务，每条命令都是一次性操作。

核心角色示例：

  • manager：拆解目标、分配任务、协调
  • worker：执行具体任务
  • inspector：代码审查，给出 PASS/FAIL

一、安装

1. macOS（推荐 Homebrew）

1
brew install mco-org/tap/squad

2. Windows

  1. 去 Releases 页面 下载 squad-x86_64-pc-windows-msvc.zip
  2. 解压出 squad.exe，放到一个目录（例如 C:\Tools\squad）
  3. 把该目录加入系统 PATH

3. 从源码编译（所有平台）

需要 Rust 1.77+：

1
cargo install --git https://github.com/mco-org/squad.git

安装完成后验证：

1
squad --help

二、初始化工作区（每个项目只需做一次）

进入你的项目目录：

1
2
cd /path/to/your/project
squad init

这一步会做以下事情：

  • 创建 .squad/ 目录
  • 把 .squad/ 加入 .gitignore
  • 在项目的 CLAUDE.md、AGENTS.md、GEMINI.md（如果存在）中追加协作说明
  • 生成默认角色模板（manager / worker / inspector）

如果想刷新内置角色文件（不影响自定义角色）：

1
squad init --refresh-roles

三、安装斜杠命令到 AI 工具

1
2
3
4
5
6
7
8
9
10
11
# 自动检测并安装到所有支持的工具
squad setup

# 或指定平台
squad setup claude
squad setup gemini
squad setup codex
squad setup opencode

# 查看已安装状态
squad setup --list

安装位置示例：

  • Claude Code → ~/.claude/commands/squad.md
  • Gemini CLI → ~/.gemini/commands/squad.toml
  • Codex CLI → ~/.codex/skills/squad/SKILL.md
  • OpenCode → ~/.config/opencode/commands/squad.md

安装后，在对应工具里直接用 /squad（Codex 用 $squad）即可。

四、启动多 Agent 协作（核心流程）

打开多个终端窗口，分别进入同一个项目目录。

终端 1（Manager）：

1
/squad manager

Manager 会加入，询问你的目标（Goal），然后拆解成任务并分配给 Worker。

终端 2（Worker）：

1
/squad worker

自动加入为 worker，进入循环：等待任务 → 执行 → 回报。

终端 3（再开一个 Worker 或 Inspector）：

1
2
3
/squad worker          # 会自动变成 worker-2
# 或
/squad inspector

多个相同角色会自动加后缀（worker、worker-2、worker-3），无需手动处理冲突。

推荐工作流

  1. 你告诉 Manager 目标
  2. Manager 用 squad task create 分配任务
  3. Worker 用 squad receive –wait 等待并领取任务（task ack）
  4. Worker 执行完成后用 squad task complete … –summary “完成内容” 回报
  5. Inspector 可对代码进行审查并反馈

五、常用命令速查

命令 作用
squad init 初始化项目工作区
squad setup 安装斜杠命令到 AI 工具
squad join –role 手动加入（通常用斜杠命令自动完成）
squad leave 退出并归档
squad agents 查看当前在线 Agent
squad send <消息> 发送自由消息（@all 可广播）
squad receive [–wait] 检查收件箱（–wait 会阻塞等待）
squad task create –title “标题” [–body “详情”] 创建结构化任务
squad task ack 领取任务
squad task complete –summary “总结” 完成任务并汇报
squad task list 查看任务列表
squad task requeue [–to ] 重新排队
squad history 查看消息历史
squad roles 列出可用角色
squad teams 列出团队模板
squad clean 清空所有状态

六、自定义角色与团队

自定义角色

在 .squad/roles/ 下新建 Markdown 文件即可：

1
echo "你是一个专业的数据库专家，负责设计 schema、优化查询、审查 SQL……" > .squad/roles/dba.md

然后启动：

1
2
3
/squad dba
# 或手动
squad join db-expert --role dba

团队模板（YAML）

在 .squad/teams/ 下创建，例如 dev.yaml：

1
2
3
4
5
6
7
8
name: dev
roles:
  manager:
    prompt_file: manager
  worker:
    prompt_file: worker
  inspector:
    prompt_file: inspector

查看团队说明：

1
squad team dev

七、可选：tmux 一键启动（Unix）

仓库自带脚本 scripts/squad-tmux-launch.sh，可自动开多窗格并注入命令。需要 tmux + ruby + claude。

1
scripts/squad-tmux-launch.sh /path/to/project --dry-run   # 先预览

支持读取 .squad/launcher.yaml 和任务简报。

八、工作原理简述

所有 Agent 通过项目下的 .squad/messages.db（SQLite） 通信：

  • 发送消息 / 创建任务 → 写入数据库
  • 接收消息 → 读取数据库
  • 无网络、无守护进程、无 socket

Agent 推荐循环：

1
加入 → receive --wait → 收到任务 → task ack → 执行 → task complete → 再次 receive --wait

九、注意事项与最佳实践

  1. 每个项目独立：squad init 后状态都在项目本地的 .squad/ 目录。
  2. Token 消耗：多个 Agent 同时运行会明显增加 API 调用，建议有订阅或本地模型。
  3. 角色提示词：内置角色提示词在 .squad/roles/，可按需修改（用 –refresh-roles 可恢复默认）。
  4. 清理状态：出问题时运行 squad clean。
  5. Windows 用户：部分 setup 检测可能有兼容问题，可手动把命令文件放到对应目录。
  6. 协议版本：新版本支持更完善的任务命令和 JSON 输出（protocol ≥ 2）。

十、完整最小示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 1. 安装
brew install mco-org/tap/squad

# 2. 全局安装斜杠命令
squad setup

# 3. 进入项目并初始化
cd my-project
squad init

# 4. 开三个终端
# 终端1：
/squad manager

# 终端2：
/squad worker

# 终端3：
/squad inspector

告诉 Manager 你的目标，然后观察它们如何分工协作即可。