Squad 开源架构深析：SDK+CLI 双包 Monorepo 设计原理与贡献者入门指南-平芜编程栈

Squad 开源架构深析：SDK+CLI 双包 Monorepo 设计原理与贡献者入门指南

【免费下载链接】squadSquad: AI agent teams for any project项目地址: https://gitcode.com/gh_mirrors/squad4/squad

Squad 是一个「人类主导的 AI agent 团队」运行时，通过 npm workspaces 将项目组织为SDK + CLI 双包 Monorepo：@bradygaster/squad-sdk提供多智能体编排核心，@bradygaster/squad-cli提供命令行界面。本文带你读懂这套架构的设计原理，并给出一份可上手的贡献者入门指南，帮你在一个下午内跑通构建、测试与 PR 流程。

上图为 Squad 用 TypeDoc 从 squad-sdk/src/ 源码自动生成的 API 参考文档首页，可见 SDK 对外暴露的类型体系。

什么是 Squad？

Squad 让你在 GitHub Copilot 中获得一支「AI 开发团队」：描述你要构建的东西，它会提议一支由前端、后端、测试、技术负责人等角色组成的团队。

成员即文件—— 每个 agent 以charter.md、history.md等形式存活于仓库中，跨会话持久化；
上下文隔离—— 每个成员只读自己的知识、写回自己学到的内容，全程可审查；
人类掌舵—— 优先级、审批、最终变更始终由人负责。

架构上，Squad 由两大 npm 包组成，外加文档站、测试集与 GitHub 工作流模板，全部放在同一个 Monorepo 里协同演进。

Monorepo 全景：一个仓库，两个独立发布的包

Squad 使用 npm workspaces 管理仓库，根 package.json 中声明：

"workspaces": ["packages/*"]

这意味着一次npm install就会自动把两个本地包链接起来 ——squad-cli可以直接 importsquad-sdk，无需先发布到 npm。整体结构如下：

squad/ ├── packages/squad-sdk/ # 运行时 SDK：@bradygaster/squad-sdk ├── packages/squad-cli/ # 命令行工具：@bradygaster/squad-cli ├── src/ # .NET 预览包 Squad.Agents.AI ├── docs/ # Astro 文档站与功能文档 ├── templates/ # 角色/技能/工作流模板（随包分发） ├── test/ # 200+ 测试文件（Vitest） ├── samples/ # 面向 SDK 消费者的示例项目 └── scripts/ # 构建、CI 校验、健康检查脚本

为什么拆成两个包？

这是典型的「内核 + 外壳」分层设计：

包	职责	依赖方向
squad-sdk	核心运行时、agent 编排、工具注册、配置、遥测	零 CLI 依赖，只依赖`@github/copilot-sdk`
squad-cli	命令解析、交互 shell、终端渲染、安装升级	单向依赖 squad-sdk

这种单向依赖带来三个直接好处：

SDK 可独立消费—— 第三方可以在自己的应用（如 .NET 项目、Azure Function）中直接引用 SDK，而不必拉进 CLI；仓库中 samples/ 目录提供了十几个真实消费示例；
独立版本演进—— 两个包使用 changesets 独立发版：改 SDK 只 bump SDK，改 CLI 只 bump CLI；
边界清晰—— 终端渲染逻辑不会污染运行时，运行时升级也不会破坏命令接口。

上图为 Squad 官方文档站的全文搜索界面（pagefind），贡献者本地可通过npm run docs:dev体验同一套文档站效果。

读懂 SDK：一个包的 30+ 个模块

SDK 的源码组织在 packages/squad-sdk/src/ 下，按能力切分为 20+ 个子目录，核心包括：

agent 编排层：coordinator/（协调者路由）、agents/、roles/
运行时层：runtime/ —— 事件总线、流式输出、OpenTelemetry 遥测、跨 squad 通信、调度器
能力扩展层：tools/（工具注册）、skills/（技能加载）、marketplace/（插件市场）、hooks/
持久化层：state/、storage/、memory/

对外 API 通过 package.json 的exports字段精细暴露 —— 从./coordinator、./tools到./runtime/otel共 50 余个子路径，每个能力都可单独按需 import。这种细粒度 exports map 既控制了包体积，也让 CLI 与外部消费者都能只取所需。

而 CLI 侧的 packages/squad-cli/src/cli/ 则按commands/（命令）、shell/（交互式 REPL）、core/（环境探测、squad 目录解析）组织，最终由cli-entry.ts打包为全局squad命令。

贡献者入门：从克隆到 PR 的五步流程

Squad 对新人非常友好 —— 完整的贡献规范写在 CONTRIBUTING.md 中。以下是精简后的核心路径。

第一步：环境准备与克隆

Node.js ≥ 20（推荐 ≥ 22.5，与engines字段一致）
npm ≥ 10（workspaces 支持）

git clone https://gitcode.com/gh_mirrors/squad4/squad cd squad npm install

npm install完成后，workspaces 已自动链接两个本地包，这是 Monorepo 开发体验的第一层红利。

第二步：构建与本地调试

npm run build # 先编译 SDK，再编译 CLI（顺序有依赖） npm test # Vitest 全量测试 npm run lint # tsc 严格模式类型检查

想让squad命令直接指向本地构建，只需一条 link 命令，改代码后重建即可自动生效，无需重装：

npm run dev:link

验证是否生效：squad version应显示-preview版本标签。

第三步：分支与提交规范

分支命名：用户名/issue号-短描述（如bradygaster/217-readme-help-update）；
提交前必须三关全过：编译 → 测试 → 类型检查；
代码风格严格：strict: true、禁止@ts-ignore、ESM-only、结构化错误处理。

第四步：Changeset 与 PR 流程

这是 Monorepo 独立版本管理的落地机制：只要改动触及packages/squad-(sdk|cli)/src/或受管模板路径，PR 就必须附带一个 changeset：

npx changeset add

PR 建议先以 Draft 创建，CI 全绿后再转「Ready for review」。仓库有一个自动 PR 就绪检查（见 scripts/pr-readiness.mjs），会自动核对：单提交、非草稿、已 rebase 到dev、changeset 存在、无冲突、CI 通过。

第五步：理解测试体系

测试分布在三层，也是新功能该在哪里写测试的参考：

test/ —— 根级集成/单元/旅程测试（test/journey-*.test.ts模拟真实用户旅程）；
test/cli/ —— CLI 命令行为测试（init、cast、watch、upgrade 等 40+ 文件）；
test/acceptance/ —— 基于 Gherkin feature 文件的验收测试。

改动 CLI 命令对应去test/cli/，改动运行时行为对应去根级test/，这是最稳的贡献路径。

架构速记：记住这三句话

SDK 是内核，CLI 是外壳—— 依赖永远单向流动，SDK 保持纯净可嵌入；
changesets 驱动独立发版—— 两个包版本解耦，PR 附 changeset 是硬性流程；
agent 即文件—— 团队状态、角色宪章、历史学习全部落盘为 Markdown，架构的「持久化」靠文件而非黑盒数据库。

想深入了解某个子系统，建议从对应源码目录与 docs/proposals/ 下的设计文档入手 —— 重要变更在写代码前都必须先有提案，这也是读懂 Squad 架构演进的最好材料。

【免费下载链接】squadSquad: AI agent teams for any project项目地址: https://gitcode.com/gh_mirrors/squad4/squad

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Squad 开源架构深析：SDK+CLI 双包 Monorepo 设计原理与贡献者入门指南