Squad 开源架构深析SDKCLI 双包 Monorepo 设计原理与贡献者入门指南【免费下载链接】squadSquad: AI agent teams for any project项目地址: https://gitcode.com/gh_mirrors/squad4/squadSquad 是一个「人类主导的 AI agent 团队」运行时通过 npm workspaces 将项目组织为SDK CLI 双包 Monorepobradygaster/squad-sdk提供多智能体编排核心bradygaster/squad-cli提供命令行界面。本文带你读懂这套架构的设计原理并给出一份可上手的贡献者入门指南帮你在一个下午内跑通构建、测试与 PR 流程。上图为 Squad 用 TypeDoc 从 squad-sdk/src/ 源码自动生成的 API 参考文档首页可见 SDK 对外暴露的类型体系。什么是 SquadSquad 让你在 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/ # 运行时 SDKbradygaster/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-sdksquad-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 ≥ 10workspaces 支持git clone https://gitcode.com/gh_mirrors/squad4/squad cd squad npm installnpm 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 就必须附带一个 changesetnpx changeset addPR 建议先以 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），仅供参考