Tianyi Cui
3.4 KiB
Agent Note: 推送前本地运行主 CI
Status: implemented
English | 中文
问题
托管 CI 可能会因账户、计费、配额或运行器故障，在仓库代码开始执行之前就不可用。此时，仅运行类型检查的发布钩子会允许更新远端分支，却缺少覆盖率、快照、文档、构建、包（package）和构建后入口点的证据；恰恰这时，托管工作流无法提供这些信号。
实现期间，聚焦检查仍是正确的反馈循环，但检查选择取决于作者是否正确预判每项受影响的契约。发布需要一套由机制统一维护的完整本地基线，且不依赖托管控制平面能否启动作业。
决策
lefthook.yml 让 pre-commit 集中处理暂存文件 lint、空白错误和 vendor 源码元数据。Pre-push 调用 pnpm run check:pre-push，任何检查失败都会阻止发布。
check:pre-push 包脚本从 scripts/run-gates.ts 中选择 pre-push 模式。pre-push 和 ci-primary 都返回同一份 ciPrimaryGates() 清单，因此钩子与主 Node CI 作业不会因分别维护命令列表而产生漂移。构建产物消费方仍保留对调度器的显式依赖关系，DSH_GATE_CONCURRENCY 仍是资源受限主机的资源控制 seam。
作者在迭代时仍运行聚焦检查。正常推送前不立即运行全量聚合，因为钩子负责这一次全面的本地执行。钩子失败必须修复或报告为阻塞项；绕过钩子需要明确批准。
本契约等同于当前主机上的 keyless 主 Node CI 聚合。它不代表已经取得受支持版本矩阵或操作系统矩阵、Python SDK、真实模型提供方、原生构建或沙箱工作流的信号；这些信号需要各自的环境才能取得。
取代关系
本决策取代快速本地 Git 钩子中有关 pre-push 的部分。其中面向暂存文件的 pre-commit 设计继续有效。它还恢复了并行 pre-push 门禁中描述的本地发布职责，但没有重新引入第二份门禁清单。
考虑过的替代方案
- 依靠恢复托管 CI 可用性——可以修复当前的管理性故障，但下一次控制平面或运行器中断时，发布流程仍没有基线。
- 将 pre-push 接入
check:all——能够复用一条广泛的本地命令，但其清单有意不同于主 CI 契约，会使「等同于 CI」的表述不准确。 - 将 CI 命令复制到
lefthook.yml——能够直观展示钩子的全面性，但会创建第二份清单，并在每次 CI 变更时产生漂移。 - 保留仅运行类型检查的 pre-push，并要求中断期间手动运行命令——能够维持低延迟，但依赖每位作者发现中断，并在每次更新前记得执行特殊流程。
结果
每次正常推送都要承担主 CI 聚合的实际耗时，也可能被与待推送 diff 无关的全仓本地失败阻塞。相应地，即使托管作业从未启动，每个已发布版本仍有一套由共享清单实际运行得出的覆盖率、快照、文档、构建、包和构建后入口点证据。
该结果只是本地证据，不能代替不可用的远端环境。PR（Pull Request）和交接会分别报告托管服务计费、提供方、平台与待处理状态，而不会把一次成功的 macOS pre-push 运行表述成 GitHub 矩阵已通过。