开发实践 · 复盘
给 AI 编程代理设闸门:一个个人站点的 9 个 CI 任务
azsou.com v2 的大部分代码是在 AI 编程代理的参与下写出来的:重构内容结构、写迁移、补测试、修 Lighthouse 的分数。AI 代理写代码很快,但它不会因为「上次改坏了」而心有余悸,也不会记得某个页面在 iPhone 宽度下按钮会被底栏挡住。真正让这种协作可持续的,不是提示词写得多好,而是一套不讲情面的闸门:每次推送都跑完整的检查,任何一项不过就不合并。这篇记录本站 CI 的九个任务分别守住什么,以及和 AI 代理配合时的几条经验。
九个任务,各守一类问题
本站的 CI 定义在 .github/workflows/ci.yml,每次推送到开发分支、每个 Pull Request 都会触发,同一分支有新推送时自动取消旧的运行。一共九个任务:
- build:依次运行 ESLint 与 Prettier、Astro 类型检查、单元测试、构建、死链与锚点检查、HTML 校验、结构化数据检查、首屏 JS 体积预算、CSP 与安全头检查,最后把构建产物上传给后面的任务复用。
- db:在 PostgreSQL 17 服务容器上执行全部迁移,跑行级安全(RLS)的角色矩阵测试,用 PostgREST 14 重放旧版前端的真实请求,最后做一次备份恢复演练:导出、整库恢复、换库恢复、核对、再跑一遍权限测试。
- e2e:Playwright 端到端测试,Chromium、Firefox、WebKit 三个引擎,每个引擎再分两片并行,共六个任务;每个引擎覆盖桌面 1440、iPad 834、iPhone 390、安卓 360 四个视口,并用 axe 做无障碍检查。社区、后台和角色相关的用例连接真实的 Postgres 与 PostgREST,而不是模拟数据。
- lighthouse:移动端模拟(慢速 4G、四倍 CPU 节流),覆盖首页、各列表和详情模板、论坛、登录、英文版、404 等近三十个页面,性能、无障碍、最佳实践、SEO 四项都必须不低于 95 分。
1 + 1 + 6 + 1,正好九个。构建只做一次,后面的任务下载同一份产物,保证测的就是将要上线的那份文件。
为什么要连真实数据库
AI 代理很擅长写「看起来对」的数据库代码:表结构合理、函数命名清晰、注释齐全。但权限问题往往藏在组合里——某个角色能不能读另一张表的某一列,某个函数以定义者权限执行时有没有先检查调用者身份。这类错误用模拟数据测不出来,因为模拟层根本不实现行级安全。
所以本站的数据库测试一律打真实的 PostgreSQL,并让 PostgREST 充当和线上同一大版本的接口层。角色矩阵测试把匿名访客、普通用户、被封禁用户、版主、管理员逐一代入,检查每张表、每个函数的读写结果。代理新加一张表时,如果忘了开启行级安全或者授予了多余的权限,这里会直接失败,失败信息会写明是哪个角色、哪张表、期望什么、实际是什么。
备份恢复演练也是同样的思路:备份脚本写完不演练,等于没有备份。演练放进 CI,每次推送都证明一次「这份备份真的能恢复出一个权限正确的库」。
跨浏览器与视口:代理看不到的地方
代理在终端里工作,看不到页面。它修好一个桌面端的布局问题,很可能在 390 像素宽的手机上把按钮挤到底部标签栏下面。本站的端到端测试为此写了专门的检查:关键按钮的触控目标不小于 44 像素、移动端底栏不遮挡内容、页面没有横向滚动、控制台没有错误。这些检查在十二个「引擎 × 视口」组合里都会跑一遍。
无障碍同理。axe 会检查对比度、可访问名称、标题层级、表单标签,深浅两种配色都要测。一个真实的例子:页脚的语言切换链接在移动端触控目标不足 44 像素,代理在修别的问题时没有注意到,是端到端测试在手机视口下指出的,修复只是一行 CSS,但没有测试的话它会一直留在线上。
性能预算与偶发失败
Lighthouse 的分数会波动,这是和代理协作时最容易产生争执的地方:代理改了一处无关的代码,性能分从 97 掉到 94,到底是真的变慢了,还是测量噪声?本站的经验是两条规则。第一,预算定在明确的数字上(首屏 JS 压缩后不超过 50 KB,由 build 任务里的体积检查负责),而不是只盯 Lighthouse 总分,这样退步会在更早、更确定的地方暴露。第二,对已知的偶发错误制定固定的处理方式:比如 Lighthouse 偶尔报出 NO_NAVSTART(页面导航时间没被记录到),规则是只重跑这一个任务一次,再失败就当真问题处理,避免无限重试掩盖真实退步。
端到端测试在 CI 里允许重试一次,也是出于同样的考虑:网络和调度带来的偶发失败不应该阻塞合并,但连续两次失败一定要看。
和 AI 代理配合的几条经验
- 完成的定义写进任务说明:本站给代理的任务都以「推送后九个任务全部通过」为验收标准,最多三轮修复;做不到就提交当前进度并写明还差什么,而不是宣布完成。
- 失败信息要能直接动手:检查脚本的报错写清楚「哪个文件、缺什么、怎么修」,比如 CSP 检查会提示运行哪条命令更新哈希。代理读到这样的信息,修复成功率明显更高。
- 不可逆的操作永远人工确认:合并到主分支、修改生产数据库、向外部平台提交申请,这些不交给代理。代理可以把迁移脚本、核对步骤和回滚方法准备好,执行由人来做。
- 工具选择看工作方式:能在终端里自己跑测试、读 CI 结果的代理(例如 Claude Code、Codex CLI)更适合这种「改到全绿为止」的循环;需要操作浏览器做探索性检查时,Playwright MCP 能让代理直接看到页面。
闸门不是不信任代理,而是让人可以放心地把更多事交给它。测试越完整,每次合并时需要人亲自检查的东西就越少。关于其中 CSP 检查的细节,可以接着读静态站点的严格 CSP。
讨论
1 条评论公开可见,支持 Markdown。后端不可达时本区自动进入只读模式。
- Randy Hopkins 作者
欢迎讨论。登录后即可发言,评论公开可见,你可以随时删除自己的评论。这里期待的是围绕文章内容的经验与勘误——我会定期回来逐条处理。
正在加载讨论…