deepseek-harness/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md

# Agent Note: 跨平台串行 CI 参考流程

Status: implemented

[English](2026-07-21-serial-cross-platform-ci-reference.md) | 中文

## 问题

拉取请求工作流通过把静态检查、lint、覆盖率、快照回放和产物验证拆分到显式的 GitHub 作业中来达到延迟目标。这些分区由代码穷举校验，但优化工作流仍不应成为自身唯一的完整性判定基准：如果分片选择逻辑及其清单测试存在同一缺陷，即使所有优化通道都保持绿灯，也可能漏掉部分工作。

将非 Windows 作业的 1 分钟目标和 Windows 作业的 3 分钟目标写成作业超时，会引入另一种失败模式。托管运行器的启动时间和性能会波动，因此即使门禁本身正确，也可能在到达目标时间边界时被取消，来不及输出有用的诊断信息。性能目标需要根据 GitHub 时间戳衡量，而正确性验证需要给门禁留足完成时间。

评审人还需要直接回答一个更简单的问题：在每个选定的托管操作系统上，如果仓库完整的主 Node CI 聚合流程不使用矩阵选择、分片变量或并发门禁，运行结果会怎样？

## 决策

[CI](../../../../.github/workflows/ci.yml) 除正常的 push 和拉取请求事件外，也接受 `workflow_dispatch`。手动触发时会跳过优化作业和兼容性作业，只提供三个名为 `serial / linux`、`serial / macos` 和 `serial / windows` 的显式作业。这些作业有意分别重复简短的代码检出、运行时设置和依赖锁定的安装步骤，不用矩阵或可复用工作流把操作系统差异隐藏起来。

每个参考作业均在不设置任何分片选择器的情况下运行 `pnpm run check:ci`。`DSH_GATE_CONCURRENCY=1` 使顶层聚合每次只执行一个已经就绪的门禁；覆盖率、快照回放、built-bin 冒烟测试和发布验证的并发数也设为 1。三种操作系统的作业可以彼此并行，但每台主机上的仓库门禁都串行运行且完整执行。Linux 在回放快照前安装 bubblewrap，Windows 则在安装采用符号链接的工作区前启用开发人员模式。

手动参考作业仅用于诊断，不参与必需的 `all checks passed` 结果。拉取请求和 push 事件仍只运行优化通道。系统根据已完成托管作业的时间戳评估非 Windows 作业的 1 分钟目标和 Windows 作业的 3 分钟目标，并将其报告为测量结果，而不是写成 `timeout-minutes` 值。

可移植的参考流程使用 GitHub 标准的 `ubuntu-latest`、`macos-latest` 和 `windows-2025` 标签。仍可将更高核心数的托管运行器作为未来的基准测试，但不将其设为默认选择：更大型运行器需要组织自有的标签和预配，而参考判定基准应无需仓库外部的运行器配置即可运行。日后完成这类预配，可以改变性能实验而无需改变该正确性基线。

## 曾考虑的替代方案

- **将每个超时值设为相应延迟目标**：不予采纳，因为调度波动会中止原本正确的执行，并使诊断回归所需的证据无法产生。
- **仅信任优化分片清单**：不予采纳，因为选择逻辑与校验逻辑共享实现假设；无分片的聚合流程是一项独立的完整性检查。
- **在每个拉取请求上运行串行参考作业**：不予采纳，因为这些作业有意以更长的总耗时和更多运行器用量换取简单性，快速反馈循环不需要它们。
- **使用一个操作系统矩阵**：不予采纳，因为三个具名作业无需另一套选择机制，就能让参考流程的构成清晰可见。
- **立即把快速工作流迁移到更大型运行器**：不作为可移植的默认方案，因为这会让常规 CI 与特定组织的运行器容量耦合。等到这类容量拥有明确归属的标签和预算后，仍可将其作为一项可选实验。

## 后果

工作流包含重复的设置步骤，手动参考运行也可能比优化后的拉取请求路径耗时长得多。这些重复是有意保留的：评审人无需解析矩阵或分片清单，就能直接检查每种操作系统执行的完整命令。

参考流程可能暴露某些平台上的故障，而优化后的阻塞门禁集合尚未声明支持这些平台，Windows 尤其如此。这类失败反映了当前的跨平台行为，不应成为削弱或静默跳过该聚合流程的理由。

移除严格的时长超时后，系统会观测到延迟回归，而不是在发生回归时自动取消运行。因此，性能改动必须附带托管环境测量结果，已完成的日志则保留优化最慢通道所需的信息。