aif-ci

CI — 流水线配置生成器

分析项目，并为 GitHub Actions 或 GitLab CI 生成可用于生产环境的 CI/CD 流水线配置。根据项目的语言、框架和现有工具，生成分别用于代码检查、静态分析、测试和安全扫描的任务。

根据现有情况选择三种模式：

现有情况	模式	操作
没有 CI 配置	generate	通过交互式设置从头创建流水线
已有 CI 配置，但不完整	enhance	审查并改进，添加缺失的任务
CI 配置完整	audit	根据最佳实践进行审查并修复问题

---

步骤 0：加载项目上下文

如果有项目描述，请阅读：

Read .ai-factory/DESCRIPTION.md

保存项目上下文，供后续步骤使用。如果不存在，步骤 2 会检测所有内容。

阅读 .ai-factory/skill-context/aif-ci/SKILL.md —— 如果该文件存在，则必须阅读。

此文件包含 /aif-evolve 根据补丁、代码库约定和技术栈分析积累的项目专属规则。这些规则针对当前项目进行了定制。

如何应用 skill-context 规则：

• 将其视为本技能通用指令的项目级覆盖规则
• 当 skill-context 规则与本 SKILL.md 中的通用规则冲突时，以 skill-context 规则为准（更具体的上下文优先级更高——与嵌套 CLAUDE.md 文件的原则相同）
• 如果没有冲突，则同时应用两者：SKILL.md 中的通用规则和 skill-context 中的项目规则
• 即使 skill-context 规则看起来与本技能的默认设置相矛盾，也不要忽略它们——这些规则的存在是因为项目实践证明默认设置不够充分
• 重要： skill-context 规则适用于本技能的所有输出，包括生成的 CI 工作流文件和审查报告。本技能中的模板只是基础结构。如果 skill-context 规则要求“CI 必须包含步骤 X”或“工作流必须包含任务 Y”，则必须相应扩展模板。生成违反 skill-context 规则的 CI 配置属于缺陷。

**强制执行：**生成任何输出文件后，都要根据所有 skill-context 规则进行验证。如果违反任何规则，必须先修正输出，再呈现给用户。

---

步骤 1：检测现有 CI 并确定模式

1.1 扫描现有 CI 配置

Glob: .github/workflows/*.yml, .github/workflows/*.yaml, .gitlab-ci.yml, .circleci/config.yml, Jenkinsfile, .travis.yml, bitbucket-pipelines.yml

对找到的文件进行分类：

• HAS_GITHUB_ACTIONS：.github/workflows/ 中包含 YAML 文件
• HAS_GITLAB_CI：存在 .gitlab-ci.yml
• HAS_OTHER_CI：检测到 CircleCI、Jenkins、Travis 或 Bitbucket

1.2 确定模式

如果 $ARGUMENTS 包含 --enhance -> 无论如何都设置 MODE = "enhance"。

路径 A：不存在 CI 配置（!HAS_GITHUB_ACTIONS && !HAS_GITLAB_CI && !HAS_OTHER_CI）：

• 设置 MODE = "generate"
• 继续执行步骤 1.3：交互式设置

路径 B：存在 CI 配置但不完整（例如，只有测试，没有代码检查）：

• 设置 MODE = "enhance"
• 读取所有现有 CI 文件 -> 保存为 EXISTING_CONTENT
• 记录：“发现现有 CI 配置。将进行分析并添加缺失的任务。”

路径 C：CI 配置完整（包含代码检查 + 测试 + 静态分析）：

• 设置 MODE = "audit"
• 读取所有现有 CI 文件 -> 保存为 EXISTING_CONTENT
• 记录：“发现完整的 CI 设置。将根据最佳实践进行审查并修复问题。”

1.3 交互式设置（仅限生成模式）

根据 $ARGUMENTS 确定 CI 平台，或进行询问：

如果 $ARGUMENTS 包含 github -> 设置 PLATFORM = "github" 如果 $ARGUMENTS 包含 gitlab -> 设置 PLATFORM = "gitlab"

否则：

AskUserQuestion: Which CI/CD platform do you use?

Options:
1. GitHub Actions (Recommended) — .github/workflows/*.yml
2. GitLab CI — .gitlab-ci.yml

询问可选功能：

AskUserQuestion: Which additional CI features do you need?

Options (multiSelect):
1. Security scanning — Dependency audit, SAST
2. Coverage reporting — Upload test coverage
3. Matrix builds — Test across multiple language versions
4. None — Just linting, static analysis, and tests

保存选择：

• PLATFORM：github | gitlab
• WANT_SECURITY：布尔值
• WANT_COVERAGE：布尔值
• WANT_MATRIX：布尔值

1.4 读取现有文件（增强 / 审查模式）

读取所有现有 CI 文件，并保存为 EXISTING_CONTENT：

• 所有 .github/workflows/*.yml 文件
• .gitlab-ci.yml
• 任何被包含的 GitLab CI 文件（检查 include: 指令）

根据现有文件确定 PLATFORM。

---

步骤 2：深入分析项目

全面扫描项目——生成的流水线中的每项决策都取决于此配置。

2.1 语言与运行时

文件	语言
composer.json	PHP
package.json	Node.js / TypeScript
pyproject.toml / setup.py / setup.cfg	Python
go.mod	Go
Cargo.toml	Rust
pom.xml	Java（Maven）
build.gradle / build.gradle.kts	Java/Kotlin（Gradle）

2.2 语言版本

检测项目的语言版本，以便在 CI 中使用：

语言	版本来源	示例
PHP	composer.json -> require.php	>=8.2 -> ['8.2', '8.3', '8.4']
Node.js	package.json -> engines.node、.nvmrc、.node-version	>=18 -> [18, 20, 22]
Python	pyproject.toml -> requires-python、.python-version	>=3.11 -> ['3.11', '3.12', '3.13']
Go	go.mod -> go 指令	go 1.23 -> '1.23'
Rust	Cargo.toml -> rust-version、rust-toolchain.toml	1.82 -> '1.82'
Java	pom.xml -> maven.compiler.source、build.gradle -> sourceCompatibility	17 -> [17, 21]

对于矩阵构建：将项目配置中的最低版本作为下限，并包含最新稳定版本。对于非矩阵构建：使用满足约束的最新版本。

2.3 包管理器与锁文件

文件	包管理器	安装命令
composer.lock	Composer	composer install --no-interaction --prefer-dist
bun.lockb	Bun	bun install --frozen-lockfile
pnpm-lock.yaml	pnpm	pnpm install --frozen-lockfile
yarn.lock	Yarn	yarn install --frozen-lockfile
package-lock.json	npm	npm ci
uv.lock	uv	uv sync --all-extras --dev
poetry.lock	Poetry	poetry install
Pipfile.lock	Pipenv	pipenv install --dev
requirements.txt	pip	pip install -r requirements.txt
go.sum	Go modules	go mod download
Cargo.lock	Cargo	（内置）

保存：PACKAGE_MANAGER、LOCK_FILE、INSTALL_CMD。

2.4–2.7 工具检测

通过扫描配置文件和依赖项来检测项目工具。完整的工具到命令映射 → 阅读 references/TOOL-COMMANDS.md

类别：Linter 与格式化工具（PHP-CS-Fixer、ESLint、Prettier、Biome、Ruff、golangci-lint、clippy、Checkstyle）、静态分析（PHPStan、Psalm、Rector、mypy、tsc）、测试框架（PHPUnit、Pest、Jest、Vitest、pytest、go test、cargo test），以及覆盖率标志；安全审计（composer audit、npm audit、pip-audit、govulncheck、cargo audit）。

2.8 服务检测

检查测试是否需要外部服务（数据库、Redis 等）：

Grep in tests/: postgres|mysql|redis|mongo|rabbitmq|elasticsearch
Glob: docker-compose.test.yml, docker-compose.ci.yml

如果需要服务，它们将在 CI 流水线中配置为服务容器。

2.9 构建输出

项目是否有构建步骤？

语言	是否需要构建	构建命令
Node.js（含 build 脚本）	是	npm run build / pnpm build
Go	是	go build ./...
Rust	是	cargo build --release
Java	是	mvn package -DskipTests -B / ./gradlew assemble
PHP	通常不需要	—
Python	通常不需要	—

摘要

构建 PROJECT_PROFILE：

• language、language_version、language_versions（用于矩阵构建）
• package_manager、lock_file、install_cmd
• linters：{name, command, config_file} 列表
• static_analyzers：{name, command} 列表
• test_framework、test_cmd、coverage_cmd
• security_tools：{name, command} 列表
• has_build_step、build_cmd
• has_typescript：布尔值（用于类型检查任务）
• services_needed：CI 所需服务列表
• source_dir：主要源代码目录（src/、app/、lib/）

---

第 3 步：阅读最佳实践和模板

Read skills/ci/references/BEST-PRACTICES.md

选择与平台和语言匹配的模板：

GitHub Actions：

语言	模板
PHP	templates/github/php.yml
Node.js	templates/github/node.yml
Python	templates/github/python.yml
Go	templates/github/go.yml
Rust	templates/github/rust.yml
Java	templates/github/java.yml

GitLab CI：

语言	模板
PHP	templates/gitlab/php.yml
Node.js	templates/gitlab/node.yml
Python	templates/gitlab/python.yml
Go	templates/gitlab/go.yml
Rust	templates/gitlab/rust.yml
Java	templates/gitlab/java.yml

阅读所选模板：

Read skills/ci/templates/<platform>/<language>.yml

---

第 4 步：生成流水线（生成模式）

以 PROJECT_PROFILE、最佳实践和模板为基础，生成自定义 CI 流水线。

4.1 生成 GitHub Actions

每项关注点使用一个工作流——每个文件都有自己的触发器、权限和并发设置：

文件	名称	作业	创建时机
lint.yml	Lint	code-style、static-analysis、rector	检测到代码检查工具或静态分析工具
tests.yml	Tests	tests（+ 服务容器）	始终创建
build.yml	Build	build	has_build_step
security.yml	Security	dependency-audit、dependency-review	WANT_SECURITY

每项关注点单独使用一个文件的原因：

• 每项检查都是 PR 中的独立状态检查——可立即查看失败项
• 触发器相互独立——安全检查按计划运行，测试在 push/PR 时运行，构建仅在测试后运行
• 权限相互独立——安全检查可能需要 security-events: write
• 无需改动其他工作流，即可禁用或重新运行某个工作流
• 分支保护规则可以要求特定工作流（例如，要求 tests，但不要求 security）

**何时保留单个文件：**仅适用于只有 lint 和 tests（2 个作业）的非常小型项目。一旦有 3 项或更多关注点，就应拆分。

每个工作流都使用相同的头部模式：

name: <Name>

on:
  push:
    branches: [main]
  pull_request:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

permissions:
  contents: read

各文件中的作业组织方式：

lint.yml——并行运行所有代码质量检查：

作业	用途	纳入条件
code-style	格式检查（CS-Fixer、Prettier、Ruff format、rustfmt）	检测到格式化工具
lint	代码检查（ESLint、Ruff check、Clippy、golangci-lint）	检测到代码检查工具
static-analysis	类型检查 / 静态分析（PHPStan、Psalm、mypy、tsc）	检测到静态分析工具
rector	Rector 试运行（仅 PHP）	检测到 Rector

所有作业并行运行（不使用 needs）。如果只检测到一个工具（例如，仅使用 golangci-lint 的 Go 项目），文件中只有一个作业也可以。

tests.yml——测试套件：

作业	用途	纳入条件
tests	单元/集成测试	始终纳入
tests-<service>	需要服务容器的测试	检测到 services_needed

矩阵构建（多个语言版本）仅放在此文件中。

build.yml——构建验证：

作业	用途	备注
build	验证编译/打包	可以通过 workflow_run 依赖外部工作流，也可以独立运行

security.yml——安全扫描：

作业	用途	额外触发器
dependency-audit	漏洞扫描	schedule: cron '0 6 * * 1'（每周）
dependency-review	PR 依赖项差异检查	仅在 pull_request 时运行

各作业规则：

1. 每个作业都应拥有各自的设置步骤（检出、语言设置、缓存、依赖项安装）
2. 使用内置缓存的语言专用设置操作：
   • PHP：使用带有 tools: 参数的 shivammathur/setup-php@v2
   • Node.js：使用带有 cache: 参数的 actions/setup-node@v4
   • Python：使用 astral-sh/setup-uv@v5（如果使用 uv）或 actions/setup-python@v5（如果使用 pip）
   • Go：使用 actions/setup-go@v5（自动缓存）
   • Rust：使用 dtolnay/rust-toolchain@stable + Swatinem/rust-cache@v2
   • Java：使用带有 cache: 参数的 actions/setup-java@v4
3. 在矩阵构建中使用 fail-fast: false
4. 当设置了 WANT_COVERAGE 时，将覆盖率作为构件上传

矩阵构建（当设置了 WANT_MATRIX 时）：

只有 tests 作业使用矩阵。Lint/SA 作业仅使用最新版本运行。

tests:
  name: Tests (${{ matrix.<language>-version }})
  strategy:
    fail-fast: false
    matrix:
      <language>-version: <language_versions from PROJECT_PROFILE>

合并 linter 作业：

如果项目在同一生态系统中同时使用格式化工具和 linter，请将它们合并到一个作业中：

• PHP：php-cs-fixer 检查 + 其他 lint -> code-style 作业
• Node.js：eslint + prettier -> lint 作业。Biome 可同时替代 ESLint 和 Prettier——如果检测到 Biome，则只在单个 lint 作业中使用 npx biome check .
• Python：ruff check + ruff format --check -> lint 作业（Ruff 可处理两者）
• Rust：cargo fmt + cargo clippy -> 可以分开运行（fmt 速度快，clippy 需要编译）

不要将 lint/SA 与测试合并——它们应各自独立失败并提供明确反馈。

以 templates/github/ 和 templates/gitlab/ 中的模板作为生成工作流文件的基础。遵循上文所述的标头模式（name、on、concurrency、permissions）和按文件组织作业的方式。

4.2 GitLab CI 生成

输出文件：.gitlab-ci.yml

有关 GitLab 专用的流水线结构、缓存策略、报告格式集成和语言专用模式 → 请阅读 references/GITLAB-PATTERNS.md

流水线阶段：install → lint → test → build → security

4.3 服务容器

如果 services_needed 不为空，则在测试作业中添加服务容器。 有关 GitHub Actions 和 GitLab CI 服务容器语法 → 请阅读 references/SERVICE-CONTAINERS.md

质量检查（写入前）

写入前验证生成的流水线：

正确性：

• 每个作业都有检出/设置/安装步骤
• 已针对正确的锁文件配置缓存
• 所有命令都对应项目中实际存在的工具
• 矩阵版本符合项目的版本约束
• 服务容器配置了健康检查

最佳实践：

• 已设置 concurrency 组（GitHub Actions）
• 已设置 permissions: contents: read（GitHub Actions）
• 已设置 interruptible: true（GitLab CI）
• 已定义 workflow.rules（GitLab CI）
• 尽可能并行运行作业（不设置不必要的 needs）
• 矩阵构建设置了 fail-fast: false

避免过度设计：

• 不为项目中不存在的工具创建作业
• 如果项目只针对一个版本，则不进行矩阵构建
• 除非用户要求或已安装相关工具，否则不进行安全扫描
• 如果项目没有构建步骤，则不创建构建作业

---

第 5 步：增强 / 审计现有流水线

当 MODE = "enhance" 或 MODE = "audit" 时，根据项目配置和最佳实践分析 EXISTING_CONTENT。

5.1 差距分析

将现有流水线与 PROJECT_PROFILE 进行比较：

缺少的作业：

• 已安装 Linter，但 CI 中没有 lint 作业？
• 已安装 SA 工具，但没有 SA 作业？
• 存在测试，但没有测试作业？
• 已安装安全工具，但没有安全作业？

配置问题：

• 未配置缓存？
• 没有并发组（GitHub Actions）？
• 使用了已弃用的 Action（例如，使用 dtolnay/rust-toolchain 而不是 actions-rs）？
• 将语言版本硬编码，而不是使用变量/矩阵？
• 矩阵中缺少 fail-fast: false？
• 在所有 GitLab 作业中都使用 policy: pull-push，而不是在非安装作业中使用 pull？

缺少的功能：

• 有可用的覆盖率工具，但没有覆盖率报告？
• 未集成 JUnit/代码质量报告（GitLab）？
• 单体仓库未配置路径筛选？
• 没有 workflow_dispatch 触发器（GitHub Actions）？

5.2 审计报告与修复

有关审计报告格式、修复流程选项和展示模板 → 阅读 references/AUDIT-REPORT.md

使用表格展示结果，并为每项检查标注 ✅/❌/⚠️。按严重程度（CRITICAL、HIGH、MEDIUM、LOW）对建议进行分类。请用户选择：全部修复、仅修复严重问题，或先查看详情。

**如果进行修复：**保留现有结构、作业名称和排序惯例。

---

步骤 6：编写文件

6.1 生成模式 — 编写流水线

GitHub Actions：

Bash: mkdir -p .github/workflows
Write .github/workflows/lint.yml        # If linters/SA detected
Write .github/workflows/tests.yml       # Always
Write .github/workflows/build.yml       # If has_build_step
Write .github/workflows/security.yml    # If WANT_SECURITY

仅为检测到的问题创建文件。若只有 lint 和测试，则创建两个文件。若项目非常简单（只有一个 lint 作业和一个测试作业），可以只创建一个 ci.yml。

GitLab CI：

Write .gitlab-ci.yml

GitLab CI 使用单个 .gitlab-ci.yml 文件，通过 stages 和 DAG（needs:）实现作业分离。

6.2 增强 / 审计模式 — 更新现有文件

使用 Edit 工具编辑现有文件。保留原有结构，仅添加或修改必要内容。

---

步骤 7：总结与后续操作

7.1 显示总结

使用 references/AUDIT-REPORT.md 中的格式（Summary Display Template 部分）显示总结。展示平台、创建的文件、功能和快速入门命令。

7.2 推荐后续技能

推荐：/aif-build-automation，用于在 Makefile/Taskfile 中配置 CI 目标；/aif-dockerize，用于容器化。

产物归属与配置策略

• 主要归属：CI 流水线产物，例如 .github/workflows/* 和 .gitlab-ci.yml。
• 允许的配套更新：默认不更新 CI 文件以外的任何内容。
• 配置策略：设计上与配置无关。此技能依赖仓库检测和用户明确选择，而非 config.yaml。