CI 在每次推送到 main 分支以及每个 Pull Request 时运行。它使用智能作用域检测，当只有不相关区域发生变更时跳过昂贵的作业。包含 Linux、Windows、macOS 和 Android 等多平台构建通道的验证指南。

CI 流水线

CI 在每次推送到 main 分支以及每个 Pull Request 时运行。它使用智能作用域检测，当只有不相关区域发生变更时跳过昂贵的作业。

作业总览

作业	用途	运行时机
preflight	检测文档变更、变更作用域、变更扩展，并构建 CI manifest	始终运行（非 draft 推送和 PR）
security-fast	私钥检测、zizmor 工作流审计、生产依赖审计	始终运行（非 draft 推送和 PR）
build-artifacts	构建一次 dist/ 和 Control UI，上传可复用产物供下游作业使用	Node 相关变更
checks-fast-core	Linux 快速正确性通道（bundled/plugin-contract/protocol 检查）	Node 相关变更
checks-fast-extensions	汇总 checks-fast-extensions-shard 完成后的扩展分片通道	Node 相关变更
extension-fast	仅针对变更的内置插件的专项测试	检测到扩展变更时
check	CI 的主本地门控：pnpm check + pnpm build:strict-smoke	Node 相关变更
check-additional	架构和边界守卫 + gateway watch 回归测试套件	Node 相关变更
build-smoke	已构建 CLI 的冒烟测试 + 启动内存冒烟测试	Node 相关变更
checks	较重的 Linux Node 通道：完整测试、频道测试，以及仅推送时的 Node 22 兼容性	Node 相关变更
check-docs	文档格式、lint 和死链检查	文档变更
skills-python	Python 技能的 Ruff + pytest	Python 技能相关变更
checks-windows	Windows 专项测试通道	Windows 相关变更
macos-node	使用共享构建产物的 macOS TypeScript 测试通道	macOS 相关变更
macos-swift	macOS 应用的 Swift lint、构建和测试	macOS 相关变更
android	Android 构建和测试矩阵	Android 相关变更

快速失败顺序

作业按"廉价检查先失败，昂贵作业后运行"的顺序排列：

1. preflight 决定哪些通道存在。docs-scope 和 changed-scope 逻辑是该作业内部的步骤，不是独立作业。
2. security-fast、check、check-additional、check-docs 和 skills-python 快速失败，不等待较重的产物和平台矩阵作业。
3. build-artifacts 与快速 Linux 通道并行，以便下游消费者在共享构建就绪后立即启动。
4. 较重的平台和运行时通道在此之后展开：checks-fast-core、checks-fast-extensions、extension-fast、checks、checks-windows、macos-node、macos-swift 和 android。

作用域逻辑位于 scripts/ci-changed-scope.mjs，并有 src/scripts/ci-changed-scope.test.ts 中的单元测试覆盖。

独立的 install-smoke 工作流通过其自己的 preflight 作业复用相同的作用域脚本，从更窄的 changed-smoke 信号计算 run_install_smoke，因此 Docker/安装冒烟测试只在安装、打包和容器相关变更时运行。

在推送时，checks 矩阵会添加仅推送的 compat-node22 通道。在 PR 上，该通道被跳过，矩阵专注于正常的测试/频道通道。

运行器

运行器	作业
blacksmith-16vcpu-ubuntu-2404	preflight、security-fast、build-artifacts、Linux 检查、文档检查、Python 技能、android
blacksmith-32vcpu-windows-2025	checks-windows
macos-latest	macos-node、macos-swift

本地等效命令

在本地开发环境中，可用以下命令模拟 CI 检查：

pnpm check          # 类型 + lint + 格式化
pnpm build:strict-smoke
pnpm test:gateway:watch-regression
pnpm test           # vitest 测试
pnpm test:channels
pnpm check:docs     # 文档格式 + lint + 死链
pnpm build          # 当 CI artifact/build-smoke 通道有影响时构建 dist

常见问题

Q: 提交代码后，为什么 GitHub Actions 里只跑了 preflight 就结束了？

A: 这说明你的修改命中了 CI 的智能作用域跳过逻辑。例如你只修改了文档文件，CI 判断无需编译和运行 Node/Swift 代码，就会自动跳过以节省时间和算力。

Q: 本地跑 pnpm test 全绿，为什么推上去 CI 还是挂在 check？

A: check 不光包含测试，还包含更为严格的 TypeScript 类型检查（pnpm check）以及代码风格和架构守护检查。推代码前最好完整跑一遍 pnpm check 修复类型警告。