Squad

Squad 是构建在 @github/copilot-sdk 之上的多 Agent 协作运行时，允许开发者在代码仓库中组建由 Frontend、Backend、Tester、Lead、Scribe 等专业角色组成的 AI 团队。核心采用 Markdown-First 设计，所有 Agent 状态以 Markdown 文件存储在 .squad/ 目录中，随 Git 提交共享，实现跨会话记忆与跨开发者协作。

多 Agent 编排#

• 团队组建：在一个仓库中创建多个专业角色 Agent，每个 Agent 拥有独立的 charter 与上下文
• Coordinator 调度：中央协调器负责消息路由、任务分发，支持多 Agent 并行执行
• 路由规则：通过 routing.md 定义任务到 Agent 的分发逻辑

状态持久化与协作#

• Markdown-First 存储：所有 Agent 状态（charter、history、decisions）以 Markdown 文件存于 .squad/ 目录
• Git 原生共享：.squad/ 随 Git 提交共享，任何克隆仓库的人获得相同团队及知识
• 跨会话记忆：Agent 的 history.md 在会话间累积项目约定和偏好
• 导出/导入：squad export / squad import 支持团队状态的可移植 JSON 快照

自动化与持续运行#

• Ralph Watch Mode：持续监控 GitHub Issues，自动分派给合适 Agent 执行
• 4 级错误恢复策略：执行失败时逐级重试
• 优雅停机：支持 --overnight-start/end 夜间暂停/恢复时段配置
• 多状态后端：--state-backend 支持 git-notes、orphan-branch、in-memory 三种持久化策略

上下文管理#

• squad nap：上下文压缩、裁剪、归档，防止上下文窗口溢出
• 分支切换安全：squad externalize 将 .squad/ 状态移到工作树外部，切换分支不丢失

可观测性与治理#

• 决策日志：所有 Agent 决策记录在 decisions.md，编排日志记录在 orchestration-log/
• OpenTelemetry 集成：squad aspire 打开 Aspire 仪表盘
• 主题化角色命名（Casting）：通过 casting/registry.json 统一角色池命名

扩展性#

• 插件市场：squad plugin marketplace 管理第三方插件源
• SDK-First 模式（实验性）：通过 squad.config.ts 以 TypeScript 代码定义团队，squad build 生成 Markdown

架构要点#

采用 Monorepo 结构：packages/squad-sdk（核心运行时库）+ packages/squad-cli（命令行界面），使用 npm workspaces 管理。构建与测试使用 TypeScript 5.7+、ESLint、Vitest（单元测试 + 覆盖率）、Playwright（E2E 测试），samples/ 目录含 8 个从入门到高级的示例。

.squad/ 目录结构#

.squad/
├── team.md              # 团队名册
├── routing.md           # 路由规则
├── decisions.md         # 共享决策记录
├── ceremonies.md        # Sprint 仪式配置
├── casting/             # 角色命名配置
├── agents/{name}/       # 各 Agent（charter.md + history.md）
├── skills/              # 压缩的工作学习成果
├── identity/            # 当前焦点和可复用模式
└── log/                 # 会话历史存档

安装与快速开始#

前置要求：Node.js ≥ 22.5.0、Git、GitHub CLI（gh）

mkdir my-project && cd my-project
git init
npm install -g @bradygaster/squad-cli
squad init
gh auth login
copilot --agent squad --yolo

VS Code 方式：打开 Copilot Chat，选择 Squad Agent，然后描述项目需求。

待确认信息#

• 独立文档站 URL 未公开，仓库内 docs/ 目录可通过 npm run docs:dev 本地预览
• @github/copilot-sdk 的具体最低版本未在根 package.json 中显式声明
• SDK-First 模式标注为 Experimental，已知存在 bug
• 作者 Brady Gaster 的具体职位/所属组织未在仓库中说明
• 插件市场命令存在但未发现实际可用的第三方插件源