background-agents多仓库自动化设计决策深潜统一invocation模型的取舍【免费下载链接】background-agentsAn open-source background agents coding system项目地址: https://gitcode.com/GitHub_Trending/ba/background-agentsbackground-agents开源后台编程代理系统的自动化功能支持一次触发并行维护最多 10 个仓库。本文深潜其多仓库自动化背后的设计决策拆解统一 invocation调用模型的关键取舍为什么每次触发都走同一条管道、为什么状态不入库而是实时推导、以及为什么仓库快照让运行中随时改配置成为可能。适合想了解开源项目架构权衡的开发者与新手阅读。多仓库自动化解决什么问题场景很直观你管理着 10 个仓库每周都要检查一遍AGENTS.md是否合规。手动做太累写十个独立的定时任务又不优雅。background-agents 的方案是一个自动化Automation绑定一个仓库集合0 到 10 个每次触发定时、手动、事件对集合做扇出fan-out——每个仓库启动一个独立的会话各自克隆自己的代码、执行同一份指令、需要时各自开自己的 PR。核心设计文档见 docs/MULTI_REPO_AUTOMATIONS.md它记录了这个特性从模型到落地的全部决策。统一 invocation 模型所有触发同一条管道这是整个设计的地基。模型长这样automation ── repositories (0..10仓库选择) │ └── invocation 一次触发 一行记录定时 / 手动 / 事件 / 被跳过 │ └── runs (0..10) 每个仓库一个各绑定一个会话 └── session 普通沙箱会话拥有分支、产物和 PR关键取舍在于没有单仓库管道和多仓库管道之分。单仓库触发只是一个恰好有一个 run 的 invocation无仓库自动化是一个零子记录或一个空仓库子记录的 invocation被跳过的触发是一条没有子记录、只带跳过原因的空 invocation。 统一管道的红利原本单仓库和多仓库是两条独立代码路径各自有独立的状态机、独立的并发规则、独立的失败计数。合并后这些逻辑只写一遍也只需维护一遍。文档明确指出过去多仓库至少选 2 个的限制就是为了把两条管道隔开——统一管道后这个限制自然消失了。状态不入库用推导消灭一类竞态传统做法会把父级状态invocation 整体是成功还是失败存进数据库但这要求所有子任务结束后回写父状态——这一步一旦在最后一个子任务完成和父状态更新之间崩溃或竞态父状态就永远卡死了。background-agents 的选择是invocation 行不存任何 status 字段状态永远从子 run 实时推导。推导规则只有一张表子任务情况推导出的状态没有子任务skipped有 starting / runningstarting/running全部终态全跳过skipped全部终态无失败completed全部终态无成功failed全部终态有成功有失败partial_failed这套逻辑同时存在两个孪生实现一段 SQL 的CASE表达式和一个 TypeScript 函数集成测试断言两者永远一致。实现位于 automation-store.ts迁移契约见 0030_automation_repositories_and_invocations.sql。取舍很明确得到状态永远自洽父状态与子任务不一致这个 bug 类别在数据模型层面就不可表达。付出每次读历史都要聚合一次子任务多一次 JOIN以及维护 SQL/TS 双实现的同步纪律。partial_failed这个状态也体现了产品思维它保留了10 个仓库全挂了和9 个成功 1 个失败的区别——前者是系统性故障后者只是某个仓库权限过期了。仓库快照让运行中随时改配置成为可能一个容易被忽视的问题如果自动化正在跑用户这时改了仓库选择历史记录会不会错乱答案是每次触发时把仓库信息owner / name / id / 基础分支快照进 run 行。历史记录渲染和会话创建都只读快照从不回查自动化当前选了哪些仓库。这带来一个漂亮的连锁反应文档里记载早期草稿中有两道防护——运行中禁止编辑仓库和一旦有历史就冻结仓库数量——它们存在的唯一理由是保护那些会回查实时配置的读者。快照一旦就位这两道防护连同它们保护的代码依赖一起被删除了。运行中的子任务保留旧快照下一次触发用新集合历史永远自洽。配套细节也很讲究重复仓库不静默去重服务端直接报校验错误。因为客户端提交 5 个实际存了 4 个会让 API 变得不可预测——UI 负责防呆服务端负责不变量。单仓库不可访问不连坐某个仓库权限失效只让对应的子任务失败并继续启动其余仓库只有当所有仓库都失败时invocation 才生而终局。并发扇出有预算单次触发内所有仓库并发启动但调度器每次 tick 额外设了约 50 个的启动预算防止塞满 10 仓库自动化的 tick 耗尽 Workers 的子请求上限。失败计数为长期半坏而设计统一模型下失败策略有几条值得抄作业的规则部分失败也算失败只要有任何一个子任务失败就朝连续 3 次失败自动暂停的阈值计 1 次——一个每周都挂同一个仓库的巡检依然是坏的不该无人值守地永远跑下去。跳过不算失败因为并发而被跳过的触发永远不触碰失败计数器否则一次超长扫描会被重复计数把可恢复的自动化误暂停。只有全绿才重置partial_failed永远不重置计数器只有全部仓库完成的触发才算恢复了。失败用 CAS 只计一次首个子任务失败时就通过比较-交换标记failure_counted_at把计数戳下并发回调、启动失败、恢复清扫三条路径都保证精确计数一次。这些规则的完整问答式记录就在 docs/MULTI_REPO_AUTOMATIONS.md 的 Decisions 一节值得当作如何写设计决策文档的范例。取舍清单统一模型买了什么、付出了什么维度统一 invocation 模型的选择付出的代价代码路径单/多/无仓库共用一条管道早期迁移要把存量 run 回填成 invocation 子记录状态一致性状态实时推导不存储每次读取需聚合子任务SQL/TS 双实现需同步历史正确性触发时快照仓库上下文每条 run 多存几个快照列事件触发v1 事件类触发仍限 0 或 1 仓库产品语义事件如何扇出到无关节点仓库未定义前先不收回滚契约迁移删除了旧列无法纯代码回滚需先快照数据库最后一条常被忽略但很重要迁移0031删除了旧版 worker 依赖的automations.repo_*列意味着部署后回退代码会读不到列——文档明确提示想要回滚路径就先快照数据库。这是统一模型落地时一次真实的取舍用不可回滚换取模型干净。在界面上长什么样API 层的词汇是automation / repository / invocation / run / session而 UI 刻意保留了原有的 Run History 叫法单仓库触发渲染为一行扁平记录和以前一模一样多仓库触发渲染为一行可展开的记录展开后是各仓库子行例如 10 个仓库 — 8 完成1 失败1 运行中。后端模型升级了用户心智负担没有升级。用户侧的操作细节创建自动化、仓库选择、Trigger Now、运行历史状态表完整记载于 docs/AUTOMATIONS.md。延伸阅读设计决策全文问答式 ADR 风格docs/MULTI_REPO_AUTOMATIONS.md自动化功能用户文档docs/AUTOMATIONS.md会话契约与关联边界 ADRdocs/adr/0002-shared-session-contracts-and-correlation-boundary.md数据访问层invocation 状态推导实现packages/control-plane/src/db/automation-store.ts触发时仓库解析单仓库失败不连坐packages/control-plane/src/automation/repository.ts迁移契约run 必须隶属 invocationterraform/d1/migrations/0059_require_automation_run_invocation.sql【免费下载链接】background-agentsAn open-source background agents coding system项目地址: https://gitcode.com/GitHub_Trending/ba/background-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考