用 OpenAPI 卡住后台 Agent 的破坏性改动
后台 Cursor Agent 连续修改代码时,字段重命名、必填规则或状态码变更可能逐步破坏现有客户端依赖的约定。文章建议在 CI 中自动验证 OpenAPI 契约,断言失败就阻止合并。
AI 深度解读
后台 Cursor Agent 一次可以改完一批代码。等它交回任务摘要,字段改名、可选参数变必填、状态码变更这些小改动可能已经叠在一起,前端仍按原来的约定发请求,接口却变了。
作者建议把检查提前到合并前。让 Agent 在独立分支工作,由 CI 启动服务,按 OpenAPI 契约发送真实请求,再用断言决定这次改动能否合并。对已经依赖这些接口的前端和全栈团队,这比事后从任务摘要里找兼容性问题更直接。
后台 Agent 为什么容易改偏接口
交互式会话里,你看到 Agent 把可选参数改成必填,可以当场追问有哪些调用方。后台模式把计划、编辑和交付放进同一批工作,等你看到结果时,多处改动可能已经互相配合起来。新版代码能跑通 Agent 手里的任务,旧客户端却可能还在发原来的请求。
这种偏移也可能发生在响应上。字段改名会影响前端取值,状态码变更会影响错误分支,删掉一项输入校验则可能改变服务对同一份请求的处理。每一处单独看都可能有理由。任务摘要通常围绕「需求做完了吗」来写,调用方依赖的行为要逐项验证。
OpenAPI 怎么变成合并门禁
作者建议把版本化的 OpenAPI 作为唯一的契约来源,在派给 Agent 的任务里直接指向这份规范。CI 启动待合并分支上的服务,按业务顺序发送真实请求,逐步检查状态码、必填字段和关键响应结构。任一断言失败就阻止合并,再把失败详情反馈给 Agent,让它沿着具体请求定位问题。
按顺序执行很重要。比如一个流程要先创建资源、再读取资源,两个请求各自返回成功状态码,还得检查后一步拿到的是刚创建的那条记录,以及前端渲染所需的字段是否齐全。OpenAPI 给出了构造和校验调用的依据,具体跑哪些流程、每一步要检查什么,仍要写进场景。导入规范后,还需要一个实际运行的后端供请求访问。
原文以 Powerduck 为例。它可以导入 OpenAPI,经由桌面应用的本地主进程向真实服务发送有先后顺序的请求,并报告断言失败。它的 AI 审查给出的是待核查的线索。作者没交代这些场景怎样接入 CI,也没给出可复用的命令或参数。
谁能改契约,决定门禁能守住什么
如果 Agent 同时能改实现和规范,遇到失败时,它可以改回接口,也可以修改规范里的预期。第二种做法同样有机会让 CI 变绿,旧调用方遇到的问题却还在。作者建议限制契约文件的修改权限,单独审查规范差异,并让后台 Agent 通过独立分支和受控的合并流程交付。
通过门禁能证明的是,本次运行满足了已写入场景的断言。没覆盖的调用路径仍可能出问题,缺少检查脚本的路径只能记作未验证。静态检查和 AI 审查也会漏报或误报。改动意图、性能、并发和安全仍需要人工判断。
我的判断
这套做法最实在的地方,是把「旧调用方还能不能用」落到了可重复执行的请求上。单看 OpenAPI 的文件差异,适合发现规范里显式声明的变化。对运行中的服务执行场景,则能发现规范没动、实际响应却已经变了的情况。如果仓库已有覆盖相同调用路径的集成测试,把关键断言补进去并设为合并条件,也能实现作者描述的门禁。
代价主要在场景维护和测试环境。服务要能在 CI 里稳定启动,测试数据要能支撑有状态的请求,团队也要知道哪些行为是调用方真正依赖的。原文没有提供实测数据或对照结果,关于这种流程能拦下多少回归、节省多少审查时间,属于经验之谈。
能拿来做什么
- 从现有前端调用里挑一条依赖多个请求的流程,在 Node 服务启动后按顺序跑一遍,把页面实际依赖的状态码和响应字段写成断言。
- 给后台 Cursor Agent 派任务时写明 OpenAPI 文件路径和允许修改的范围。让它在独立分支工作,并用 CI 断言的失败详情指导下一轮修改。
- 有意调整接口时,单独审查 OpenAPI 的差异,并在合并前核对调用方是否已适配。把人工审查时间留给断言难以覆盖的意图、性能、并发和安全问题。