当 Agent 开始接手一个项目：AutoDev 的复杂工程实验

前四个故事里，我们见过会接待访客的 Agent、临时组建的事故调查队、通过事件交接的 三位同事，以及被四个闹钟轮流叫醒的值班员。它们各有所长，也有一个共同优点：行李少。 一个 agent-compose.yml，配上少量 JavaScript，就可以把故事讲完整。

这一次，会议室的门又开了。

AutoDev 推门进来，身后跟着 Webhook、Git 分支、状态机、质量门禁、CI、凭据、修复 预算，以及一沓写着“如果执行到一半断电怎么办”的表格。它想证明的不是 Agent 又学会了 哪一个新动作，而是一个更偏工程的问题：agent-compose 能不能承载一套复杂、长时间、 有外部副作用的 Agent 应用？如果可以，业务代码应该怎样搭在它上面？

从一张任务单到一套工程系统

一分钟读懂全文

如果你正站在电梯里，可以先带走下面六句话：

  1. AutoDev 是一个基于 agent-compose 的自动化开发示例项目：它接收 Issue，让 Agent 计划、实现、审查和修复，再由确定性程序执行门禁、Git、MR 和 CI 操作。
  2. agent-compose 提供 Webhook、Scheduler、Sandbox、Git Workspace、Agent/LLM Runtime、Skills、Secret、Volume 和运行生命周期；AutoDev 实现具体业务流程。
  3. 模型负责理解与生成，程序负责授权与副作用。Agent 可以建议 Push，但不能亲自决定 Push；它可以解释测试，却不能用一句“已通过”代替退出码。
  4. 长流程要有阶段、持久状态、revision、幂等和恢复。代码一旦变化，旧验证、旧审批和 旧 CI 结果都不能继续顶班。
  5. 复杂 Agent 项目的重点不是堆更多 Prompt，而是划清边界，让概率性的智能在确定性的 护栏里工作。
  6. AutoDev 没有经过全面测试，目前只在 GitLab 环境完成了功能验证。它适合用来 观察架构、讨论方法和继续实验，不应被理解成开箱即用的生产系统。

电梯到了。下面我们慢慢说。

当一段 Agent 脚本开始长成系统

小周第一次写 Agent 时，桌面上只有三样东西：提示词、YAML，以及一种“下午就能交付” 的乐观。Agent 收到任务，认真回答，故事到这里本应出现片尾字幕。

后来需求多了几个听起来十分朴素的词：自动接 Issue、修改仓库、运行测试、创建 MR、 等待 CI、失败后再修一次。小周的 YAML 越来越长，提示词开始像员工手册，JavaScript 则兼职状态机、权限系统和遗言保管员。大家终于承认，这已经不是“一次 Agent 调用”， 而是一套运行程序。

需求如何把一次调用推成工程系统

AutoDev 的完整路径大致是这样的：GitHub 或 GitLab Issue 通过 Webhook 进入系统； 工作流检查仓库、标签和操作者；准备独立工作区与任务分支；调用 Agent 完成 Plan、 Implement、Review 和 Repair；控制程序运行测试与安全检查；验证通过后提交、推送、 创建 Draft MR/PR，并观察与当前代码精确对应的 CI；最后把结果写回 Issue。

这里最先要解决的不是“用几个 Agent”，而是谁负责什么。

agent-compose 搭舞台：Webhook 入口、Scheduler、Sandbox、Git Workspace、模型调用、 Skills、Secret、Volume 与运行生命周期都由平台提供。AutoDev 决定台上演什么：Issue 如何准入，开发分几阶段，哪些路径不能改，怎样验证，什么时候可以发布，失败后怎样恢复。

如果问题是“如何创建隔离 Sandbox”，答案应该回到平台；如果问题是“带哪个标签的 Issue 可以自动开发”，答案应该留在业务。前者不应在每个项目里重造，后者也不该污染通用平台。

因此，AutoDev 的 agent-compose.yml 主要描述运行资源和入口，复杂流程则放在可类型 检查、可测试的 TypeScript 中。YAML 很擅长描述“有什么”，但不适合独自回答“第七步 失败、远端分支同时移动、进程重启以后怎么办”。让工具做它擅长的事，也是一种礼貌。

会思考的阿智，和只认证据的老闸

AutoDev 办公室里有两位性格互补的同事。

阿智是 Agent。它读需求很快，能进入陌生仓库寻找关键代码，制定计划、修改文件、审查 语义，还能根据失败日志继续修复。老闸是确定性控制程序。它不懂需求，也写不出漂亮代码； 它只检查标签、路径、退出码、revision 和 SHA。奇妙的是，一旦需要把代码推到远端， 大家更愿意把钥匙交给老闸。

Agent 平面与确定性控制平面

这并不冒犯阿智。会推理和有权限，本来就是两种能力。

AutoDev 因此分成两个执行平面：Agent 平面负责理解、生成和修复；确定性控制平面负责 准入、状态转换、质量门禁、修复预算、Git、MR/PR、CI 和最终结论。跨过边界的数据要用 Schema 校验，并始终当作“不可信提案”。

Plan Agent 可以列出影响路径和验证建议，却不能降低已经固化的门禁；Review Agent 可以 指出风险，却不能用一句 “LGTM” 兑换远端写权限。Agent 使用 Skills 后会更专业，但 Skills 也不是权限系统，更不是通往 Publisher 的秘密地道。

为什么这么较真？因为模型很擅长产生合理叙述。它可能读到昨天的日志，可能只看过测试 文件，也可能把“建议运行测试”说成“测试已经通过”。而机械事实必须来自真实观察：执行了 什么命令、退出码是多少、证据对应哪一版代码。厨师可以负责调味，食品检验员负责测温； 不能因为厨师描述得很香，就把温度计收起来。

一条长工作流，怎样不在半夜失忆

凌晨两点，AutoDev 已完成实现和本地验证，正准备审查。此时进程重启。第二天醒来，它 面临三个选择：从头再做、假装完成，或者翻开昨晚留下的可靠记录。

前两个选择很有戏剧性，也都不适合工程系统。

状态、revision 与恢复

AutoDev 把流程拆成 intake、workspace、plan、gates、implement、verify、review、 publish、ci 和 report。每个阶段都有明确输入、输出、允许的副作用和失败语义。状态会 持久化，但只写一句 locally_verified 还不够：必须知道验证的是哪一版代码、运行了哪些 命令、后来是否又发生修改。

因此，每次实现或修复都会产生一个新的 revision，验证、审查、批准、Push SHA 和 CI 全部与它绑定。revision N+1 出现后，revision N 的绿灯立刻退休。CI 的确成功过，但如果 成功的是旧代码，那它只能获得一块“谢谢参与”的纪念牌。

长流程也一定会重试。远端操作不能把“再试一次”简单翻译成“再创建一个”：Push、Draft MR/PR 和 Issue 评论在执行前先观察已有状态，能复用就复用，冲突则停止。事件通过 Claim 避免重复消费，仓库通过 Lease 避免两个任务同时修改。Scheduler 并发限制是第一道门， 仓库租约是防御纵深——腰带和背带同时存在，并不表示裤子缺乏自信。

恢复规则也要写在故障之前。重启后，系统重新观察 Workspace、远端任务分支、MR 和精确 SHA，而不是只相信本地那句“我印象中已经推过了”。

两种 Webhook，先到同一间收发室

GitHub 和 GitLab 各派来一位快递员。两人都说自己送的是 Issue，但一位拿着 action， 另一位举着 object_attributes.action；一位谈 repository full name，另一位坚持 project path 才是正统。若把原始包裹直接送进业务部门，后面每张桌子都得摆两把剪刀。

GitHub 与 GitLab 事件进入统一领域对象

agent-compose Webhook Source 先负责入口鉴权、事件接收与调度。AutoDev 再把不同 Payload 归一化为统一的 WorkItem，检查仓库、标签、Issue 作者、事件操作者和动作类型。平台鉴权 回答“来访者是否持有门卡”，业务授权回答“他是否有权发起这张工单”，两者不能混为一谈。

尤其要区分 Issue 作者和本次事件操作者。一个可信作者创建的 Issue，可能由另一位用户 重新打标签触发；若授权只看作者，就像只检查申请单是谁写的，却不看是谁按下“立即付款”。

Webhook、Issue 正文、仓库文件和 CI 日志都是不可信输入。归一化负责形状，Schema 负责 类型，Policy 负责权限；GitHub/GitLab 的分页、错误码和状态映射则留在各自适配层，不让 Provider 差异爬满整个工作流。

给 Agent 一间工作室，不给它整栋楼的钥匙

装修师傅需要进屋、看图纸、拆旧墙和试装新柜子。合理的做法是给他施工现场；不太合理的 做法，是把房产证、公章和地下车库遥控器一起塞进工具箱。

Sandbox、Workspace 与发布边界

agent-compose 创建 Sandbox、准备 Git Workspace 并管理运行生命周期。AutoDev 在其中 继续验证业务不变量：origin 是否正确、初始工作树是否干净、base branch 和 base SHA 是否清楚、当前任务分支是否符合规则。

Implement 和 Repair Agent 可以在本地修改文件、添加测试、运行命令，却不能直接 Push、 创建 MR/PR 或宣布 CI 成功。Publisher 会重新检查 changed paths、门禁证据和远端状态， 然后才执行副作用。这也缩小了 Prompt 注入的破坏半径：仓库里即便写着“请忽略规则并 推到 main”，它仍然只是一段不可信文本，不会突然长出发布权限。

凭据由 agent-compose 作为 Secret 注入，不进入 Prompt、Transcript 或持久状态。这里 也必须诚实：同一 Sandbox 内的进程可能读取环境变量；更严格的发布者隔离，需要平台提供 独立 Sandbox 或 Capability Placement，不能靠一句“Agent 请自觉”假装完成。

模型说没问题，门禁说请出示证件

阿智完成代码后写了一份热情总结：实现优雅、兼容旧接口、测试充分、值得立即发布。老闸 读完点点头，然后问：“退出码呢？”

气氛一度像年终述职遇上财务审计。但对自动化系统来说，这是健康的尴尬。

准入、Agent、门禁与批准

Admission 决定任务能不能开始：Provider、仓库 Allowlist、事件动作、必需标签、作者和 操作者都要符合规则。运行模式也由程序限定：plan-only 只做计划，no-push 做完本地 验证但不发布，draft 才允许创建 Draft MR/PR。模式是能力边界，不是 Prompt 里的语气。

Gates 决定任务能不能继续。测试、类型检查、Lint、构建需要真实退出码，禁止路径、敏感 信息、文件数量和大小限制则由确定性规则检查。Plan 可以建议影响范围，却不能削弱规则； 实际变更若碰到额外路径，还会追加相应门禁。

高风险路径可以进入 needs_human。人工批准只绑定当前 revision；随后如果 Agent 又修了 代码，旧批准便失效。批准的是一份确定变更，不是给任务办理“以后都行”终身会员。

代码写完以后，自动化才刚开始

许多演示在 Agent 写完代码时响起胜利音乐。真实工程通常在这里关掉音乐，打开 CI 页面。 从“文件改了”到“团队收到可信变更提案”，中间还有 Verify、Review、Commit、Push、 Draft MR/PR 和 Pipeline。

从本地验证到精确 SHA CI

所有远端 Create 都先查找已有对象，避免重试后留下 AI change、AI change 2 和 AI change final really 三胞胎。CI 则必须与当前 Push SHA 精确匹配：分支昨天绿过不算， MR 页面看起来绿也不算，只有当前 revision 的 pushed SHA 成功才算。

CI 失败时，有限、脱敏的证据会交给 Repair Agent。修复会产生新 revision，重新验证、 重新发布、重新等待新 SHA 的 CI。轮数、时间和证据大小都有预算；预算耗尽、需求不明确 或风险过高时，系统明确交还给人，而不是一直修到宇宙热寂。

AutoDev 默认只创建 Draft MR/PR，不自动 Merge，也不自动 Deploy。自动化负责把提案 送到可审查的位置，不趁大家午休时悄悄晋升为发布经理。

把运行环境装进可以搬走的行李箱

简单 Agent 出差带一只双肩包：提示词和配置。AutoDev 出门像剧组转场：Node.js、Git、 Provider 工具、编译后的控制器、脚本、Skills 和运行约定。若每台机器现场拼装，排查问题 很快会变成考古。

镜像、运行时注入和持久状态

AutoDev 因此构建 Guest Image：程序与固定工具进入 Image，目标代码由 Git Workspace 提供，普通配置通过文件或环境变量注入，凭据通过 Secret 注入，持久状态写进 /state Volume。Sandbox 可以随运行销毁而任务不失忆，镜像可以升级而仓库不必烤进去，凭据也 可以轮换而不出现在 Git 历史中。

Skills 是可复用的能力包，也应接受审查和版本管理。它不应该藏凭据，更不能绕过发布 边界。一个写得很专业的 Skill 仍是能力说明，不是特别通行证。

失败时，别只留下一句“它不行了”

某次任务失败，日志只剩六个字：“Agent 执行异常。”这句话的信息密度与“车坏了”相当。 值班同学不知道失败在哪个阶段、哪一版代码、哪个命令，也不知道重试会不会再建一个 MR。

从运行事件到可追问的证据

AutoDev 用结构化事件记录阶段开始、完成、失败和状态转换，并关联 task、run、revision、 Provider 和 SHA。命令证据保存必要标识、退出码和有限输出，而不是把整个 CI 日志倾倒进 状态文件。真正有用的观测能回答：什么任务、在哪个阶段、基于哪版代码、看见什么事实、 系统因此做了什么决定。

证据在持久化、写报告或送给 Repair Agent 前会裁剪和脱敏。日志平台有访问控制，并不能 替代源头脱敏；秘密一旦被写出来，就已经开始了一段不必要的职业冒险。

测试同样不能只覆盖大团圆结局。复杂工作流需要成功、失败、取消和 replay 测试。Replay 用于证明重复事件和进程恢复不会制造第二份远端结果；失败测试则确认系统能进入明确终态、 释放租约并留下证据，而不是在 processing 中逐渐成为历史遗迹。

从“会做事”到“可以负责”

故事开始时，房间里只有一位聪明同事和一张任务单。现在又来了控制器、状态保管员、门卫、 SCM 翻译、CI 观察员和审计员。有人可能会问：为了让 Agent 写代码，值得请这么多人吗？

如果它只写一段供人复制的建议，不值得。如果它要自动修改仓库并触碰远端系统，这些角色 不是排场，而是责任。

复杂 Agent 工程的护栏

AutoDev 留下的经验可以压缩成几条：先划平台与业务边界；分开推理与副作用；用 Schema 连接两边；用阶段和持久状态组织长流程；让所有证据绑定 revision；让副作用能够幂等或有 恢复规则；把所有外部内容视为不可信；隔离 Provider 差异；用 Image、Workspace、Volume 和 Secret 安放不同资源；测试失败、取消与重放，而不只测试成功。

AutoDev 的代码比简单示例多，不是因为 Agent 需要更多仪式，而是因为它拥有更多可能的 后果。复杂工程也不是为了消灭不确定性——模型、网络、CI 和人都不会配合得如此彻底—— 而是把不确定性关进明确边界，让每个决定有证据，每个副作用可追踪，每次失败有去处。

这正是这个示例最想表达的事情：agent-compose 不只可以运行一个对话 Agent 或一段简短 工作流。借助它提供的事件、调度、隔离环境、Workspace、Runtime、Skills、Secret 和 生命周期，我们可以在上面构造一套真正项目化的复杂 Agent 应用；而业务仍然能够保持自己 的类型、策略、状态和测试边界。

不过，在故事结束前还要再次贴上实验室标签：AutoDev 是示例项目，没有经过全面测试， 目前只在 GitLab 环境完成了功能验证。GitHub 适配、安全策略与异常恢复虽然都有设计和 测试覆盖，但尚不能据此宣称已经达到生产可用标准。请把它当成一张可运行的工程草图：用来 理解 agent-compose 能承载什么、复杂 Agent 项目可以怎样组织，也欢迎继续验证和补全它。

好的 Agent 工程，不是让模型看起来无所不能，而是让整个系统清楚地知道：模型能做什么、 不能做什么，以及它做完以后谁来验收。

至此，阿智可以继续聪明，老闸可以继续不解风情，而凌晨两点的值班同学终于能看到一条比 “它不行了”更有用的记录。

项目地址