Squad .squad目录深度揭秘让AI团队记忆随Git版本化、可审计、可共享的终极方案【免费下载链接】squadSquad: AI agent teams for any project项目地址: https://gitcode.com/gh_mirrors/squad4/squadSquad 是一个面向任意项目的 AI agent 团队框架而它的.squad/目录正是整套系统的核心团队的决策记录、每个 AI 成员的个人记忆、路由配置和角色花名册全部存放在这里并且天然支持随 Git 仓库一起版本化、可审计、可共享。 本文带你用 5 分钟看懂这个目录的每一层结构以及让团队记忆干净沉淀到 Git 的 3 种最佳实践。什么是 .squad 目录当你运行squad init初始化一个项目后仓库根目录会出现一个.squad/目录。可以把它理解为 AI 团队的集体大脑每个 AI 成员agent拥有自己的身份、角色和历史记忆团队共享决策记录在同一个文件里所有成员开工前必读所有记忆都是纯 Markdown 文件人类可以直接阅读、编辑、纳入版本控制这意味着 AI 团队不再是用完即忘的临时工具——它的每一次学习都会被记录下来跟着代码一起演进。.squad 目录结构一图速览文件/路径角色.squad/decisions.md团队共享决策共享大脑所有 agent 开工前必读.squad/decisions/inbox/决策收件箱agent 并行写入的暂存区.squad/decisions-archive.md过期决策归档不再占用上下文.squad/agents/{name}/history.md每个 AI 成员的个人记忆仅本人可读.squad/team.md团队花名册成员名字、角色、charter 路径.squad/routing.md任务路由规则决定任务派给谁.squad/identity/wisdom.md团队沉淀的智慧可被上游继承.squad/config.json状态后端选择、模型偏好等配置.squad/casting/角色选角casting状态完整目录架构见官方概念文档memory-and-knowledge.md。三层记忆系统如何记住你的一切Squad 的记忆按三层复利式增长越用越聪明共享决策层decisions.md团队级规则集中存放在decisions.md。当你随口说一句永远用单引号或周五禁止部署协调者会检测到 always / never / from now on 等信号词自动写入decisions/inbox/随后由 Scribe agent 定期合并去重沉淀为正式决策。✨个人记忆层history.md每个 agent 只读自己的history.md。Kane 可以成为认证系统专家Dallas 则专精组件库——分工越久专长越深。当文件超过约 12KB 时旧条目会被渐进式摘要压缩既保住积累的知识又不撑爆上下文。技能层可迁移的招式与本项目用 PostgreSQL这类决策不同技能是可跨项目迁移的技术如如何配置 GitHub Actions CI由 agent 在实际工作中赚取并带有 Low/Medium/High 置信度等级。如何把 .squad 目录纳入 Git 版本控制.squad/目录默认以普通文件形式存在于工作树中local 后端这带来三个直接好处版本化git add .squad/ git commit后团队记忆的每一次变化都有提交记录可审计git log .squad/decisions.md或git blame可以追溯这条决策是谁在哪个版本加入的可共享同事克隆仓库后直接获得一支训练好的 AI 团队官方建议导入新团队后立即提交.squad/让所有 clone 仓库的人都获得完整团队见 portability.md。需要提醒的是当使用高级状态后端时Squad 会自动向.gitignore写入带标记的状态块防止decisions.md、history.md被误提交到工作分支——这套防护逻辑实现在 gitignore-state.ts。4 种状态后端让 AI 记忆不污染 PR团队开发时最大的痛点是agent 每写一条决策PR 里就多一堆无关文件评审者看到 40 条决策日志埋在 57 行代码里。 Squad 提供状态后端解决这一问题一行配置即可迁移squad init --state-backend two-layer # 新项目直接选两层架构 squad upgrade --state-backend two-layer # 老项目一键迁移后端记忆存放位置PR 干净适合场景local默认工作树.squad/文件❌个人项目、希望状态随代码提交orphan独立squad-state分支✅想要 Git 版本化但不想污染主分支two-layergit notes 孤儿分支✅团队多人协作推荐two-layer 架构的精髓在于分工第 1 层git notes提交级的为什么批注PR diff 中不可见仅附着在特定 commit 上第 2 层孤儿分支持久状态仓库存放决策、历史、日志按文件粒度存储天然支持多人并发合并Ralph 负责桥接PR 合并后标记promote_to_permanent的批注会被提升到孤儿分支被拒 PR 上的决策则自动作废配置只需在.squad/config.json中加一行stateBackend: two-layer后续所有命令自动读取。查看状态也非常简单git log --oneline squad-state、git show squad-state:decisions.md。详细说明见 state-backends.md 和设计动机博客031-state-backends.md。3 种方式共享 AI 团队记忆方式一直接提交克隆即得最简单把.squad/提交到仓库团队成员克隆后开箱即用git clone https://gitcode.com/gh_mirrors/squad4/squad这是版本化 可共享的最直接形态——记忆和代码在同一分支历史中演进。方式二Export / Import 快照跨项目搬运squad export # 生成 squad-export.json squad import squad-export.json # 导入到新仓库导出包含 agent charter、历史、技能、决策和 casting 状态导入时历史会自动拆分为可移植知识与项目专属知识--force时会把旧团队归档而非删除。方式三Upstream 继承组织级知识下发squad upstream add ../org-practices/.squad --name org squad upstream sync声明外部 Squad 来源本地目录、Git 仓库或导出快照后技能、决策、identity/wisdom.md、casting策略和routing.md会在会话开始时自动继承实现组织 → 团队 → 仓库的知识流且本地.squad/始终优先。详见 portability.md。可审计性随时复盘 AI 团队的决策因为记忆是纯文本 Git 原生结构审计几乎是零成本cat .squad/decisions.md # 当前生效的全部团队决策 git log --oneline .squad/decisions.md # 决策文件的演进历史 git show squad-state:decisions.md # 查看孤儿分支上的持久状态冲突处理也是透明的当新指令与旧决策矛盾时Scribe 会检测重叠并询问你替换、合并还是跳过——人始终拥有最终决定权。去哪里深入学习想动手实践可以直接对协调者说Show me the team directives 或 export the current team。更多资料官方概念文档docs/src/content/docs/concepts/memory-and-knowledge.md会话初始化流程参考templates/session-init-reference.md状态后端选型参考docs/src/content/docs/reference/state-backend-selection.md官方 SDK 类型化 API 参考resolveStateBackend等总结.squad/目录让 AI 团队记忆从易失的上下文变成可版本化、可审计、可共享的团队资产。默认 local 后端适合个人项目团队场景强烈建议two-layer后端——你的 PR 只留代码记忆由 Git 守护。【免费下载链接】squadSquad: AI agent teams for any project项目地址: https://gitcode.com/gh_mirrors/squad4/squad创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考