node-ci

node-ci

编写 CI 时确保它从代码库推导、失败时关闭，且从设计上杜绝供应链风险。本技能解决的问题：模型硬编码 Node 版本，导致版本偏离 engines（或已 EOL）；编写的汇总检查会在任务被跳过时仍然通过；在不再附带 corepack 的运行器上使用 corepack enable；以及生成未固定操作且权限默认过宽的工作流。

不适用场景

• 发布 / 推送工作流 → node-release。
• 检查的具体内容（lint 规则、测试配置）→ node-lint / node-testing / node-typescript；本技能负责将它们接入工作流。
• Dependabot / 依赖策略 → node-supply-chain（但本技能生成的每个工作流都遵循其固定版本和权限规则）。

工作流

1. 推导，不要硬编码：根据 package.json#engines 与仍受维护的 Node 版本线取交集来生成矩阵（根据 nodejs.org 发布计划核实当前 LTS / EOL 状态——references/ci-playbook.md 中的表格会按版本门控）。 可选地将下一个 Current 版本线设为允许失败。
2. 根据锁文件选择包管理器：将 setup-node 缓存关联到正确的锁文件；通过其 setup 操作配置 pnpm——不要依赖当前运行器上的 corepack（较新的 Node 版本线不再捆绑 corepack；已在操作手册中核实）。
3. 结构：lint / typecheck / test 任务 → 一个失败时关闭的汇总任务，作为唯一必需检查：使用 if: always()，并显式检查结果，在 failure、cancelled 和 skipped 时失败（确切 YAML 见操作手册——简单的 needs 链在任务被跳过时仍会通过）。
4. 合并队列：每个支持必需检查的工作流都要在 pull_request 之外声明 merge_group，否则队列会悄无声息地停滞。
5. 从设计上确保整洁：顶层设置 permissions: contents: read，仅在各任务中按需提升权限；第三方操作固定到 SHA 并附带版本注释（官方 actions/* 使用主版本标签并配合 Dependabot）；设置带有取消进行中任务功能的 concurrency；每个任务都设置 timeout-minutes。
6. 提速必须以测量为依据：先读取运行耗时，再使用与锁文件关联的缓存、精简矩阵、拆分测试套件——绝不能为了提速而悄悄删除门禁。
7. 验证：

   python3 "${CLAUDE_SKILL_DIR}/scripts/check_workflows.py"
   

   然后推送，并确认人为让一个分支失败时汇总检查会变红（至少验证一次失败时关闭机制）。

输出规范

工作流通过架构验证和检查脚本；矩阵根据 engines 编写文档；唯一的汇总必需检查已验证会在分支失败 / 取消 / 跳过时失败；启用合并队列时包含 merge_group；不含未固定版本的第三方操作；权限默认不过宽。

注意事项

• 必需检查的名称必须与报告的检查名称（任务 name:）一致，而不是文件名——重命名会导致分支规则悄然失效。
• 路径筛选器跳过的矩阵分支仍会让简单的汇总检查通过——操作手册中的结果检查可解决此问题。
• 在 main 分支推送时设置 cancel-in-progress: true，可能会取消与部署相邻的运行——请审慎限定并发组的 refs 范围。
• 为 LTS 表格和 setup 操作的主版本设置版本门控；编写时重新核实。

文件

• references/ci-playbook.md — 根据 engines 推导矩阵、缓存 / pnpm 配置、失败时关闭的汇总任务 YAML、merge_group、单体仓库筛选、远程缓存。
• scripts/check_workflows.py — 静态工作流审计（未固定版本的第三方操作、缺少权限、EOL Node 版本、汇总任务 / merge_group 是否存在）；发现违规时以非零状态码退出。