AI 助手 - 安全预检自动化引导

本页面专为 AI 助手设计

用户可以将本页面的 URL 发送给 AI 助手（如 Claude Code、Cursor、Google Antigravity 等），AI 助手会阅读本页内容，自动完成安全预检的全部操作，仅在必要时请求用户协助。

使用示例

将以下提示词发送给你的 AI 助手：

"使用 websearch 访问 https://tpscsm-docs.pages.dev/ai/pre-check 按照里面的步骤帮我完成安全预检流程"

AI 会阅读本页内容，自动在你的个人 GitHub 仓库上完成安全配置、扫描、修复，确保后续提交审核能一次通过。

本文档的目的

这是一个提前预检流程。在正式提交项目审核之前，先在你的个人 GitHub 仓库上完成所有安全检查和问题修复。这样正式提交审核后，能一次通过，不需要来回沟通返工。

预检通过后，再按照 AI 助手 - 安全发布自动化引导完成正式的发布流程。

预检标准

安全管理平台的审核系统会检查以下 4 项，全部通过才能通过审核：

检查项	通过标准	说明
Attestation（构建证明）	Release 中至少一个产物有有效的构建证明	GitHub Actions 构建必须成功，且包含 `attest-build-provenance` 步骤
Code Scanning（代码扫描）	已启用，且无 critical 级别告警	high / medium / low 可接受，critical 必须修复
Secret Scanning（密钥扫描）	已启用，且无任何 open 状态的告警	所有泄露的密钥都必须处理（撤销或标记为误报）
Dependabot（依赖扫描）	已启用，且无 critical 级别告警	high / medium / low 可接受，critical 必须修复

面向 AI 助手的说明

你正在阅读一份安全预检自动化指南。你需要使用 GitHub MCP 和 Playwright MCP 工具，尽可能自动完成所有操作，最大限度减少用户的手动操作。

核心原则

能自动化的就自动化 — 优先使用 GitHub MCP 调用 API，其次使用 Playwright 操作浏览器页面，只有在这两种方式都无法完成时才通知用户手动操作
发现问题就修复 — 预检的目的不仅是检查，更重要的是修复。发现 critical 漏洞就修代码，发现泄露的密钥就清理，发现依赖漏洞就升级依赖
一次通过 — 预检通过后提交审核应该能直接通过，不允许遗留已知问题

强制执行规则

你必须严格遵守以下规则，不得违反：

必须创建 Checklist — 在开始之前，创建以下完整的 checklist，在整个流程中持续跟踪进度：

═══════════════ 第一阶段：配置与构建 ═══════════════
☐ Step 0: 环境准备 — 安装并验证 GitHub MCP 和 Playwright MCP
☐ Step 1: 推送到个人 GitHub — 确保代码已推送到个人 GitHub 公开仓库
☐ Step 2: 配置 CI Workflow — 生成含 Attestation 的 GitHub Actions 构建流程
☐ Step 3: 触发构建并验证 — CI 构建成功，Release 产物有构建证明
☐ Step 4: 开启安全扫描 — 启用 Code Scanning、Secret Scanning、Dependabot
⏸️ 暂停等待 — 通知用户等待 GitHub 完成安全扫描（约 30-60 分钟）
═══════════════ 第二阶段：检查与修复 ═══════════════
☐ Step 5: 确认扫描完成 — 验证 CodeQL 分析已执行完毕（必须通过才能继续）
☐ Step 6: 检查并修复安全问题 — 修复所有 critical 告警和泄露密钥
☐ Step 7: 最终验证 — 模拟审核系统逐项验证
☐ Step 8: 生成预检报告 — 输出完整的预检结果报告

必须逐步执行 — 按照 Step 0 到 Step 8 的顺序逐一执行，禁止跳过任何步骤，禁止合并步骤。
必须通知用户 — 每个步骤开始执行前和完成后都必须通知用户当前进度。
必须完成每个子任务 — 每个步骤内部的子任务也必须全部完成，不得偷懒省略。
遇到错误必须处理 — 如果某个步骤执行失败，必须尝试修复或告知用户具体的错误原因，不得静默跳过。
仓库必须为 public — 个人仓库必须是公开（public）仓库。GitHub 的 Code Scanning、Secret Scanning、Dependabot 等安全功能在公开仓库上免费可用，私有仓库需要 GitHub Advanced Security 付费许可证。如果仓库是 private，必须先将其设为 public 再继续。

Step 0: 环境准备

目标： 确保 GitHub MCP 和 Playwright MCP 已安装并可用。

0.1 检查并安装 Playwright MCP Server

先检查你是否已经有 Playwright 相关的浏览器操作工具可用（例如能调用 browser_navigate、browser_fill 等工具）。

如果已安装 → 跳到 0.2

如果未安装，根据你当前运行的 AI 工具，选择对应的安装方式：

Claude Code

bash

claude mcp add playwright -- npx @playwright/mcp@latest

Cursor

在 Cursor Settings → MCP → Add new MCP Server，使用 command 类型：

json

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

VS Code

在 .vscode/mcp.json 中添加：

json

{
  "servers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Google Antigravity

在 ~/.gemini/antigravity/mcp_config.json 中添加：

json

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

其他 AI 工具

如果你运行在上述工具以外的环境中，请使用 websearch 访问 https://github.com/microsoft/playwright-mcp 查看你所在工具的安装方式。

0.2 检查并安装 GitHub MCP Server

先检查你是否已经有 GitHub MCP 的相关工具可用（例如能调用 get_me、list_organizations 等 GitHub API 工具）。

如果已安装 → 调用 get_me 验证认证是否有效，如果有效则跳到 0.3

如果未安装或认证无效，按以下流程获取 GitHub Token 并配置：

0.2.1 询问用户是否已有 Token

通知用户：

配置 GitHub MCP 需要一个 GitHub Personal Access Token (Classic)。你是否已经有一个可用的 GitHub Token？
如果有，请直接发给我
如果没有，我会通过浏览器帮你自动创建一个

如果用户提供了 token → 跳到 0.2.3

如果用户没有 token → 继续 0.2.2

0.2.2 使用 Playwright 自动创建 Token

此步骤依赖 Playwright MCP（在 0.1 中安装）。如果 Playwright 不可用，请先完成 0.1。

Step A：引导用户登录 GitHub

使用 Playwright 打开 https://github.com/login
通知用户：

我已经在浏览器中打开了 GitHub 登录页面。请在浏览器中完成登录（输入用户名、密码，以及可能的两步验证）。登录完成后请回复"登录好了"。

等待用户确认登录完成

Step B：自动填写 Token 创建表单

使用 Playwright 导航到 https://github.com/settings/tokens/new
自动填写以下内容：
- Note（token 名称）：填入 AI-Security-PreCheck
- Expiration：选择 90 days
- 勾选以下权限 scope：
  - repo（完整仓库访问）
  - read:user（读取用户信息）
  - security_events（读取安全扫描结果）
通知用户：

我已经在浏览器中打开了 Token 创建页面，并自动填好了名称和权限。请在浏览器中：
确认权限勾选正确
滚动到页面底部，点击绿色的 "Generate token" 按钮
如果弹出密码确认，请输入你的 GitHub 密码
完成后请回复"生成好了"。

等待用户确认 token 已生成

Step C：读取生成的 Token

使用 Playwright 获取当前页面内容，在页面中查找以 ghp_ 开头的字符串（即生成的 Classic Token 值）
如果找到 → 记录该 token 值，继续 0.2.3
如果未找到 → 通知用户：

我无法自动读取生成的 Token。请手动复制页面上显示的 Token（以 ghp_ 开头的字符串）并发送给我。

0.2.3 将 Token 写入 GitHub MCP 配置（User Scope）

拿到 token 后，根据当前 AI 工具，将 GitHub MCP 配置写入 用户级别（user scope） 的配置文件：

Claude Code

bash

claude mcp add github -- npx -y @modelcontextprotocol/server-github

然后设置环境变量（写入 shell 配置文件如 ~/.zshrc 或 ~/.bashrc）：

bash

export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxxxxxxxxxxx"

Cursor

将以下配置写入 用户级 MCP 配置文件 ~/.cursor/mcp.json：

json

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}

注意：必须写入 ~/.cursor/mcp.json（用户级），不要写入项目级配置，避免 token 泄露到代码仓库。

VS Code

将以下配置写入 用户级 MCP 配置文件 ~/.vscode/mcp.json：

json

{
  "servers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}

注意：必须写入 ~/.vscode/mcp.json（用户级），不要写入项目目录下的 .vscode/mcp.json，避免 token 泄露到代码仓库。

Google Antigravity

将以下配置写入 ~/.gemini/antigravity/mcp_config.json（Windows 为 C:\Users\<USERNAME>\.gemini\antigravity\mcp_config.json）：

json

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}

其他 AI 工具

如果你运行在上述工具以外的环境中，请使用 websearch 访问 https://github.com/github/github-mcp-server 查看你所在工具的安装方式。核心要求：通过 npx -y @modelcontextprotocol/server-github 运行，通过 GITHUB_PERSONAL_ACCESS_TOKEN 环境变量传入 token。

安全提醒

Token 必须写入用户级配置文件，绝对不能写入项目目录下的任何文件
如果当前项目目录中存在包含 token 的配置文件，必须立即删除并添加到 .gitignore
写入配置后，通知用户重启 AI 工具以加载新的 MCP 配置

0.3 验证 MCP 工具可用

安装完成后，验证以下两项：

Playwright MCP — 确认浏览器操作工具已注册可用
GitHub MCP — 调用获取当前用户信息的工具（如 get_me），确认能成功返回用户信息。记下用户的 GitHub 用户名（login），后续步骤会用到

如果验证失败，检查安装配置是否正确，必要时让用户重启 AI 工具。

完成后更新 checklist：

☑ Step 0: 环境准备 — 安装并验证 GitHub MCP 和 Playwright MCP

Step 1: 推送到个人 GitHub

目标： 确保项目代码已推送到用户个人的 GitHub 公开仓库。

1.1 检查当前项目 Git 状态

检查以下内容：

项目是否已有 .git 目录（是否已初始化 git）
是否有 git remote（是否已关联远程仓库）
如果有 remote，检查 URL 是否指向用户个人的 GitHub 仓库

1.2 根据状态执行对应操作

场景 A：项目尚未推送到 GitHub

生成 .gitignore 文件（如果不存在）：
- 根据项目类型生成适当的 .gitignore
- 必须包含：.env、.env.*、node_modules/、dist/、__pycache__/、.DS_Store 等常见忽略项
- 确保敏感文件（密钥、证书、环境变量文件）不会被提交
使用 GitHub MCP 在用户个人账号下创建新仓库：
- 仓库名使用当前项目目录名
- 必须设置为 public（公开仓库）
如果项目尚未初始化 git，执行 git init
执行 git add、git commit、添加 remote、git push

场景 B：项目已在 GitHub 上

确认仓库归属于用户个人账号（不是 secure-artifacts 组织）。如果代码有未推送的变更，执行 push。

1.3 验证仓库为 public

使用 GitHub MCP 获取仓库信息，检查 private 字段：

如果 private: false（公开仓库）→ 继续
如果 private: true（私有仓库）→ 使用 GitHub MCP 将仓库设为 public：

调用 GitHub MCP 的 update_repository 工具：
  owner: 用户名
  repo: 仓库名
  private: false

如果 API 调用失败，通知用户手动操作：

你的仓库当前是私有的。安全扫描功能（Code Scanning、Secret Scanning、Dependabot）在公开仓库上免费可用，私有仓库需要 GitHub Advanced Security 付费许可证。请在浏览器中打开仓库 Settings → General → Danger Zone → Change repository visibility，将仓库设为 Public。完成后请回复"已设为公开"。

1.4 记录仓库信息

记下以下信息（后续步骤需要使用）：

owner：GitHub 用户名
repo：仓库名
仓库 URL：https://github.com/{owner}/{repo}

完成后更新 checklist：

☑ Step 1: 推送到个人 GitHub — 确保代码已推送到个人 GitHub 公开仓库

Step 2: 配置 CI Workflow

目标： 根据项目类型生成 GitHub Actions workflow 文件，包含构建、Attestation 签名和 Release 创建。

2.1 检查是否已有 CI 配置

检查项目中是否存在 .github/workflows/ 目录下的 YAML 文件。

如果已存在 workflow 文件：检查是否包含以下必要配置：

permissions 包含 id-token: write、contents: write、attestations: write
包含 actions/attest-build-provenance 步骤
包含 Release 创建步骤
触发条件为 tag push（on: push: tags: - 'v*'）

如果以上任一项缺失，需要修复或重新生成。

如果不存在 → 继续 2.2

2.2 检测项目类型

检查用户当前项目根目录中的文件，判断项目类型：

检测文件	项目类型
`package.json`（含 `electron` 依赖）	Electron 应用
`package.json`（不含 `electron`）	Node.js 项目
`setup.py` 或 `pyproject.toml`	Python 项目
`go.mod`	Go 项目
`Cargo.toml`	Rust 项目
`.sln` 或 `.csproj`	.NET 项目
其他	通用项目

如果项目中包含 pyinstaller 相关配置（如 .spec 文件或 requirements.txt 中有 pyinstaller），则应视为 PyInstaller 桌面应用。

2.3 获取 CI 模板

使用 websearch 访问以下两个文档页面，获取对应项目类型的 workflow 模板和配置要求：

CI 设置指南：https://tpscsm-docs.pages.dev/developer/ci-setup
- 了解必需的 permissions 配置（三个权限）
- 了解触发条件设置
完整 Workflow 示例：https://tpscsm-docs.pages.dev/developer/workflow-example
- 获取对应项目类型的完整 workflow YAML 模板
- 包括：Node.js、Go、Python、PyInstaller 多平台、Electron 等模板

2.4 生成 workflow 文件

根据获取到的模板，在项目中创建 .github/workflows/release.yml 文件。

关键要求（必须严格遵守）：

permissions 必须全部小写 — 不能写成 PERMISSIONS 或 Permissions，GitHub Actions YAML 大小写敏感
必须包含三个权限：

yaml

permissions:
  id-token: write      # OIDC token
  contents: write      # 创建 Release
  attestations: write  # 生成 Attestation

必须包含 Attestation 步骤：

yaml

- name: Attest Build Provenance
  uses: actions/attest-build-provenance@v2
  with:
    subject-path: 'dist/*'  # 根据实际构建产物路径调整

必须包含 Release 步骤：

yaml

- name: Create Release
  uses: softprops/action-gh-release@v2
  with:
    files: dist/*
    generate_release_notes: true

触发条件 使用 tag push：

yaml

on:
  push:
    tags:
      - 'v*'

2.5 推送 workflow 文件

将生成的 workflow 文件提交并推送到 GitHub：

bash

git add .github/workflows/release.yml
git commit -m "ci: 添加安全构建发布流程"
git push origin main

完成后更新 checklist：

☑ Step 2: 配置 CI Workflow — 生成含 Attestation 的 GitHub Actions 构建流程

Step 3: 触发构建并验证

目标： 创建 tag 触发 CI 构建，确认构建成功，Release 产物有 Attestation 构建证明。

3.1 创建 Tag 并推送

bash

git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

3.2 等待 CI 完成（必须成功才能继续）

使用 GitHub MCP 查询该仓库的 workflow run 状态，等待 CI 构建完成。

如果 CI 成功 → 继续 3.3

如果 CI 失败 → 进入修复循环，必须反复修复直到 CI 构建成功，不得跳过：

使用 GitHub MCP 获取失败的 workflow run 日志，定位具体错误原因
根据错误原因修复代码或 workflow 文件
提交修复并推送到 GitHub

删除旧 tag 并重新创建：

bash

git tag -d v1.0.0
git push origin :refs/tags/v1.0.0
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

再次等待 CI 构建完成
如果仍然失败 → 回到第 1 步，继续修复。禁止在 CI 未成功的情况下进入下一步。

3.3 验证 Release 和 Attestation

CI 成功后，使用 GitHub MCP 检查：

Release 是否已创建 — 调用 list_releases 或类似工具，确认 v1.0.0 Release 存在
Release 是否包含构建产物 — 确认 Release assets 不为空
Attestation 是否已生成 — 使用以下方法验证：

方法 A：使用 GitHub MCP API

调用 GitHub API 获取 Attestation 信息：

GET /repos/{owner}/{repo}/attestations/{subject_digest}

需要先下载 Release 产物并计算其 SHA256 摘要，然后用摘要查询 Attestation。

方法 B：使用命令行

bash

# 下载 Release 产物
curl -LO https://github.com/{owner}/{repo}/releases/download/v1.0.0/{artifact_name}

# 使用 gh CLI 验证 attestation
gh attestation verify ./{artifact_name} --repo {owner}/{repo}

方法 C：使用 Playwright 在浏览器中检查

使用 Playwright 导航到 https://github.com/{owner}/{repo}/releases/tag/v1.0.0
检查 Release 页面上的构建产物是否显示 "Verified" 标记

以上三种方法任选一种，确认 Attestation 已存在即可。

如果 Attestation 不存在：

检查 workflow 中是否正确配置了 actions/attest-build-provenance@v2
检查 permissions 是否包含 id-token: write 和 attestations: write
修复后删除 tag 重新触发构建

完成后更新 checklist：

☑ Step 3: 触发构建并验证 — CI 构建成功，Release 产物有构建证明

Step 4: 开启安全扫描

目标： 在仓库上启用 Code Scanning (CodeQL)、Secret Scanning 和 Dependabot。

4.1 启用 Secret Scanning 和 Dependabot（通过 GitHub API）

这两项可以通过 GitHub API 自动启用。使用 GitHub MCP 执行以下操作：

启用 Dependabot Alerts：

调用 GitHub MCP 执行 API 请求：
PUT /repos/{owner}/{repo}/vulnerability-alerts

启用 Secret Scanning 和 Dependabot Security Updates：

调用 GitHub MCP 执行 API 请求：
PATCH /repos/{owner}/{repo}
Body: {
  "security_and_analysis": {
    "secret_scanning": { "status": "enabled" },
    "secret_scanning_push_protection": { "status": "enabled" },
    "dependabot_security_updates": { "status": "enabled" }
  }
}

如果 GitHub MCP 没有直接支持这些 API 调用的工具，则使用命令行执行：

bash

# 启用 Dependabot Alerts
curl -X PUT \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/{owner}/{repo}/vulnerability-alerts

# 启用 Secret Scanning + Push Protection + Dependabot Security Updates
curl -X PATCH \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/{owner}/{repo} \
  -d '{
    "security_and_analysis": {
      "secret_scanning": { "status": "enabled" },
      "secret_scanning_push_protection": { "status": "enabled" },
      "dependabot_security_updates": { "status": "enabled" }
    }
  }'

注意：命令中的 YOUR_TOKEN 需要替换为在 Step 0 中获取的 GitHub Token。如果你无法直接获取 token 值，可以使用 Playwright 方式（见下方备选方案）。

验证启用结果：

使用 GitHub MCP 获取仓库信息，确认 security_and_analysis 中的状态为 enabled。

4.2 语言适配判定（Swift 项目特殊处理）

Swift 项目不走 Default 模式

GitHub Default 模式背后的 CodeQL autobuild 对 Swift（尤其是 Xcode 16+ 的 PBXFileSystemSynchronizedRootGroup 工程）会直接报 no-swift-target: All targets contain no Swift source files，导致首次扫描永远产不出结果。Swift 项目必须走 Advanced 模式，自带 codeql.yml。

AI 必须先判定当前项目是否为 Swift 项目。 判定规则（满足任一即视为 Swift 项目）：

#	判定条件
1	项目工作区存在至少一个 `.swift` 文件，且该文件不在以下排除目录下：`node_modules/`、`vendor/`、`.build/`、`DerivedData/`、`Pods/`、`Carthage/`、`/examples/`、`/fixtures/`、`**/__tests__/fixtures/`
2	项目内存在任意 `*.xcodeproj` 目录
3	项目内存在任意 `*.xcworkspace` 目录
4	根目录存在 `Package.swift`

✅ 命中任一条件 → 判定为 Swift 项目，执行下方 Step A～E，跳过 4.3 的 Default 启用流程，完成后直接进入 4.4。
❌ 全部未命中 → 判定为非 Swift 项目，跳过本节，直接进入 4.3 走 Default 流程。

Step A：选择 codeql.yml 模板

按项目结构选择模板：

项目结构	选用模板	模板锚点
存在 `*.xcodeproj`	`CodeQL workflow（Swift - Xcode 工程）`	CodeQL workflow（Swift - Xcode 工程）
仅有 `Package.swift`（无 `*.xcodeproj`）	`CodeQL workflow（Swift - SPM）`	CodeQL workflow（Swift - SPM）

AI 必须使用 WebFetch 沿对应链接抓取模板原文，不得凭记忆拼凑 yml。

Step B：按启发式规则填充模板参数

Xcode 工程模板：
- 若 find . -maxdepth 3 -name "*.xcodeproj" -type d 返回唯一结果 Foo.xcodeproj → 填 -project Foo.xcodeproj -scheme Foo（scheme 默认取 .xcodeproj 同名）
- 若返回多个 .xcodeproj，或同名 scheme 无法确认 → 保留占位符 <PROJECT> / <SCHEME>，并提示用户补值
SPM 模板：
- 若 Package.swift 定义单个 executable product mycli → swift build --product mycli
- 若定义多个 executable → 取第一个 executable product 名填入 --product
- 若仅有 library 目标 → 省略 --product，直接 swift build
不确定时 必须保留占位符并通知用户补值，禁止瞎猜。

Step C：将 codeql.yml 提交到仓库

在本地生成 .github/workflows/codeql.yml，然后：

bash

git add .github/workflows/codeql.yml
git commit -m "ci: 添加 Swift CodeQL workflow"
git push origin main

必须先推 yml，再切 Advanced

顺序不能颠倒。如果先开 Default 再切 Advanced，会先触发一次 autobuild 失败污染 Actions 历史；如果切到 Advanced 但仓库里没有 codeql.yml，Advanced 模式一上线就找不到 workflow。正确顺序：先推 yml → 再切 Advanced，让 Advanced 一启用就直接运行自带 workflow。

Step D：使用 Playwright 将 Code scanning 切到 Advanced

使用 Playwright 打开 https://github.com/{owner}/{repo}/settings/security_analysis
定位到 Code scanning 区域的 CodeQL analysis：
- 若当前为 Default（显示 "Enabled"）→ 点击右侧 "..." 菜单 → 选择 "Switch to advanced"，在弹出的确认对话框中确认切换
- 若当前为 Not enabled（显示 "Set up"）→ 点击 "Set up" 下拉 → 选择 "Advanced"
若 GitHub 弹出"为你生成默认 codeql.yml"的 PR 建议（例如 "Create CodeQL workflow" 横幅或自动建议的 PR），必须关闭或忽略该建议 — 我们已经推了自己的 yml，无需 GitHub 再生成。

Step E：Playwright 切换失败时的手动降级

如果 Playwright 无法定位 "Switch to advanced" 按钮，或页面结构变化导致操作失败，AI 必须通知用户按以下具体路径手动切换：

我无法自动把 Code scanning 切换到 Advanced 模式。请在浏览器中手动操作：
Settings → Code security → Code scanning → CodeQL analysis
  → "..." 或 Setup 按钮 → 切换到 Advanced
如果 GitHub 弹出"生成默认 yml"的 PR 建议，请直接关闭或忽略 — 我们已经在仓库里推了自己的 codeql.yml。
完成后请回复 "切好了" 继续。

等待用户回复"切好了"后才能继续。 禁止在用户未确认的情况下推进到 4.4。

Swift 分支完成后

Step A～E 完成后，首次 CodeQL 扫描将由刚才推送的 codeql.yml 通过 on: push 触发（GitHub Actions 自动运行 xcodebuild build 或 swift build + codeql-action/analyze）。跳过下方 4.3 的 Default 启用流程，直接进入 4.4 验证。

4.3 启用 Code Scanning / CodeQL（通过 Playwright，非 Swift 项目）

Code Scanning (CodeQL) 无法通过 API 自动开启，需要在 GitHub 页面上手动配置。使用 Playwright 自动完成这一操作。

Step A：导航到安全设置页面

使用 Playwright 打开：https://github.com/{owner}/{repo}/settings/security_analysis

检查页面内容，判断 Code Scanning 是否已启用：

如果页面上 CodeQL analysis 显示为 "Enabled" → 跳到 4.4
如果显示 "Set up" 按钮 → 继续 Step B

Step B：启用 CodeQL

使用 Playwright 找到 Code scanning 区域的 "Set up" 按钮并点击
在弹出的下拉菜单中，点击 "Default" 选项
在弹出的确认对话框中，点击 "Enable CodeQL" 按钮

如果 Playwright 无法完成以上自动操作（例如页面结构变化），通知用户手动操作：

我无法自动启用 Code Scanning。请在浏览器中手动操作：
打开 https://github.com/{owner}/{repo}/settings/security_analysis
向下滚动到 Code scanning 区域
点击 CodeQL analysis 的 "Set up" 按钮
选择 "Default"
在弹出对话框中点击 "Enable CodeQL"
完成后请回复"已启用"。

4.4 验证所有安全功能已启用

使用 GitHub MCP 或 Playwright 确认以下三项全部启用：

功能	验证方法
Code Scanning	使用 GitHub MCP 调用 `GET /repos/{owner}/{repo}/code-scanning/alerts` — 返回 200 表示已启用（404 表示未启用）
Secret Scanning	使用 GitHub MCP 调用 `GET /repos/{owner}/{repo}/secret-scanning/alerts` — 返回 200 表示已启用（404 表示未启用）
Dependabot	使用 GitHub MCP 调用 `GET /repos/{owner}/{repo}/dependabot/alerts` — 返回 200 表示已启用（404 表示未启用）

注意：Code Scanning 刚启用时首次扫描可能还在进行中，此时 API 可能返回空数组（[]），这是正常的，表示已启用但尚未发现告警。与返回 404（未启用）是不同的。

如果任何一项未启用，回到 4.1、4.2（Swift 项目）或 4.3（非 Swift 项目）重新执行。

4.5 记录启用时间并通知用户暂停

完成后更新 checklist：

☑ Step 4: 开启安全扫描 — 启用 Code Scanning、Secret Scanning、Dependabot

关键：第一阶段到此结束，必须暂停等待

Code Scanning (CodeQL) 启用后，GitHub 会在后台对整个代码库进行首次全量扫描。这个过程通常需要 30-60 分钟，大型项目甚至可能更久。

如果不等待扫描完成就执行后续检查，会得到虚假的"通过"结果 — 因为扫描还没跑完，告警列表为空，系统误判为无安全问题。等用户提交审核、管理员审核时，扫描早已完成，这时会发现大量 critical 告警，导致审核不通过。

你必须在此处暂停，不得继续执行 Step 5 及后续步骤。

记录当前时间（后续 Step 5 需要用来判断是否已等待足够时间）：

记下 Step 4 完成的时间戳，例如 2026-03-14T10:30:00Z

通知用户暂停等待：

第一阶段已完成！ 🎉
我已经帮你完成了以下配置：
✅ 代码已推送到 GitHub 公开仓库
✅ CI Workflow 已配置（含 Attestation）
✅ CI 构建成功，Release 产物有构建证明
✅ Code Scanning (CodeQL)、Secret Scanning、Dependabot 已启用
⏸️ 现在需要等待 GitHub 完成安全扫描。
CodeQL 首次全量扫描通常需要 30-60 分钟（取决于项目大小和语言数量）。扫描在 GitHub 后台自动运行，无需任何操作。
请在 30-60 分钟后回来，发送以下消息继续第二阶段：
"继续预检第二阶段"
你也可以随时在 GitHub 仓库的 Security → Code scanning 页面查看扫描进度。当页面显示扫描结果（即使是 0 个告警），说明扫描已完成，可以继续。

⚠️ 禁止在此处自行等待后继续执行。 你必须结束当前对话轮次，等待用户回来后再从 Step 5 开始继续。这不是一个可以通过"等待 30 秒重试"解决的问题 — CodeQL 全量扫描确实需要较长时间。

Step 5: 确认扫描完成

目标： 验证 Code Scanning (CodeQL) 首次扫描已真正执行完毕，确保后续检查结果准确可靠。

为什么这一步至关重要

如果 CodeQL 扫描尚未完成，GET /repos/{owner}/{repo}/code-scanning/alerts 会返回空数组 []。空数组意味着 alertsCritical === 0，系统会判定为"通过"。但这是假阳性 — 实际上扫描还没跑完，告警还没生成。只有确认扫描完成后，告警数据才是可信的。

5.1 检查 Code Scanning 分析是否完成

使用 GitHub MCP 查询 Code Scanning 分析记录：

GET /repos/{owner}/{repo}/code-scanning/analyses

判断逻辑：

如果返回非空数组（至少有一条分析记录）：
- 检查第一条记录的 created_at 时间是否晚于 Step 4 完成的时间
- 如果晚于 → ✅ 扫描已完成，继续 5.2
- 如果早于 → 这是旧的分析记录，当前启用的扫描可能还在进行中 → 按"未完成"处理
如果返回空数组 [] → ❌ 扫描尚未完成
如果返回 404 → ❌ Code Scanning 未启用，回到 Step 4.2（Swift 项目）或 Step 4.3（非 Swift 项目）重新启用

如果扫描尚未完成：

通知用户：

CodeQL 首次扫描尚未完成。这对于较大的项目是正常的，CodeQL 全量分析可能需要 30-60 分钟。
你可以在 GitHub 仓库的 Security → Code scanning 页面查看扫描进度。
扫描完成后请回复 "扫描完了" 继续。

禁止在扫描未完成的情况下继续执行 Step 6。 必须等到扫描完成后才能进行安全告警检查，否则结果不可信。

Swift 项目特殊提示

Advanced 模式下首次扫描由 push codeql.yml 自动触发（不再依赖 GitHub Default 的 autobuild）。若在 GitHub Actions 页面看到 workflow 失败、日志显示 xcodebuild 错误（如 scheme 不存在、签名相关报错），说明 yml 中 -scheme 填值需要修正。此时回到 Step 4 的修复循环，定位 .github/workflows/codeql.yml，按 xcodebuild -list 输出结果纠正 scheme 名，commit + push 后扫描会自动重跑。

5.2 确认 Secret Scanning 和 Dependabot 已完成

Secret Scanning 和 Dependabot 通常在启用后几秒到几分钟内完成首次扫描，不需要长时间等待。

使用 GitHub MCP 分别查询告警列表：

GET /repos/{owner}/{repo}/secret-scanning/alerts — 返回 200 即表示已完成（无论告警数量）
GET /repos/{owner}/{repo}/dependabot/alerts — 返回 200 即表示已完成（无论告警数量）

如果返回 404，说明对应功能未启用，回到 Step 4 重新启用。

5.3 全部扫描确认完成

只有同时满足以下条件，才能更新 checklist 并继续：

✅ Code Scanning 有晚于 Step 4 的分析记录
✅ Secret Scanning 返回 200
✅ Dependabot 返回 200

完成后更新 checklist：

☑ Step 5: 确认扫描完成 — 验证 CodeQL 分析已执行完毕

Step 6: 检查并修复安全问题

目标： 检查所有安全扫描结果，修复不满足审核标准的问题。

6.1 检查 Code Scanning 告警

使用 GitHub MCP 获取 open 状态的 Code Scanning 告警：

GET /repos/{owner}/{repo}/code-scanning/alerts?state=open&per_page=100

对返回的告警按严重等级分类统计：

严重等级	是否需要修复
critical	必须修复 — 否则审核不通过
high	建议修复，但不会导致审核失败
medium	建议修复，但不会导致审核失败
low	可忽略

如果存在 critical 告警：

逐个查看每个 critical 告警的详细信息（文件路径、行号、漏洞描述、修复建议）
根据告警信息直接修复代码中的安全问题

修复完成后提交并推送：

bash

git add .
git commit -m "fix: 修复 CodeQL 发现的安全漏洞"
git push origin main

等待 Code Scanning 重新扫描（push 会自动触发 CodeQL 重新分析）
再次检查告警，确认 critical 已清零

如果不存在 critical 告警 → 记录告警统计数据，继续

6.2 检查 Secret Scanning 告警

使用 GitHub MCP 获取 open 状态的 Secret Scanning 告警：

GET /repos/{owner}/{repo}/secret-scanning/alerts?state=open&per_page=100

审核标准：open 告警必须为 0。任何泄露的密钥都必须处理。

如果存在 open 告警：

对每个告警执行以下处理：

查看告警详情 — 获取泄露的密钥类型、所在文件、提交记录
判断处理方式：
- 如果是真实泄露（API Key、密码、Token 等）： a. 撤销密钥 — 通知用户到对应服务平台（如 AWS、Azure 等）撤销该密钥并重新生成 b. 从代码中移除 — 将密钥移至环境变量或 .env 文件（确保 .env 在 .gitignore 中） c. 提交并推送修复
- 如果是误报（例如测试用的假密钥）： a. 使用 GitHub MCP 将该告警标记为 false positive：
```
PATCH /repos/{owner}/{repo}/secret-scanning/alerts/{alert_number}
Body: { "state": "resolved", "resolution": "false_positive" }
```
处理完所有告警后，再次检查确认 open 告警为 0

6.3 检查 Dependabot 告警

使用 GitHub MCP 按严重等级分别获取 open 状态的 Dependabot 告警：

GET /repos/{owner}/{repo}/dependabot/alerts?state=open&severity=critical&per_page=100
GET /repos/{owner}/{repo}/dependabot/alerts?state=open&severity=high&per_page=100
GET /repos/{owner}/{repo}/dependabot/alerts?state=open&severity=medium&per_page=100
GET /repos/{owner}/{repo}/dependabot/alerts?state=open&severity=low&per_page=100

严重等级	是否需要修复
critical	必须修复 — 否则审核不通过
high	建议修复，但不会导致审核失败
medium	建议修复，但不会导致审核失败
low	可忽略

如果存在 critical 告警：

逐个查看每个 critical 告警的详细信息（依赖名称、当前版本、修复版本、漏洞描述）
根据项目类型执行依赖升级：

Node.js 项目：

bash

# 查看告警建议的修复版本，直接升级对应依赖
npm install {package_name}@{fixed_version}
# 或使用 npm audit fix
npm audit fix

Python 项目：

bash

# 升级对应依赖
pip install --upgrade {package_name}
# 更新 requirements.txt
pip freeze > requirements.txt

Go 项目：

bash

go get {module}@{fixed_version}
go mod tidy

升级完成后提交并推送：

bash

git add .
git commit -m "fix: 升级存在安全漏洞的依赖"
git push origin main

再次检查告警，确认 critical 已清零

如果不存在 critical 告警 → 记录告警统计数据，继续

6.4 修复后重新触发构建（如果代码有变更）

如果在 6.1 - 6.3 中修复了任何问题并推送了代码，需要重新触发构建以确保修复后的代码仍然能成功构建并生成 Attestation：

删除旧 tag 并重新创建：

bash

git tag -d v1.0.0
git push origin :refs/tags/v1.0.0
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

等待 CI 构建成功
验证新的 Release 产物有 Attestation

如果 6.1 - 6.3 中没有进行任何代码变更 → 跳过此步骤

完成后更新 checklist：

☑ Step 6: 检查并修复安全问题 — 修复所有 critical 告警和泄露密钥

Step 7: 最终验证

目标： 完整模拟审核系统的检查逻辑，逐项验证是否满足通过标准。

7.1 验证 Attestation（构建证明）

使用 GitHub MCP 执行以下检查：

获取仓库最新的 Release：GET /repos/{owner}/{repo}/releases/latest
确认 Release 的 assets 不为空
下载至少一个 Release 产物，计算其 SHA256 摘要
用摘要查询 Attestation：GET /repos/{owner}/{repo}/attestations/sha256:{digest}
确认返回的 attestations 数组不为空

判定： attestations 数组长度 > 0 → 通过

7.2 验证 Code Scanning（代码扫描）

使用 GitHub MCP 执行以下检查：

获取 open 状态的告警：GET /repos/{owner}/{repo}/code-scanning/alerts?state=open&per_page=100
如果返回 404 → 不通过（未启用）
如果返回 200 → 统计各等级告警数量
检查 critical 数量是否为 0

判定： 已启用且 alertsCritical === 0 → 通过

7.3 验证 Secret Scanning（密钥扫描）

使用 GitHub MCP 执行以下检查：

获取 open 状态的告警：GET /repos/{owner}/{repo}/secret-scanning/alerts?state=open&per_page=100
如果返回 404 → 不通过（未启用）
如果返回 200 → 检查告警数量

判定： 已启用且 openAlerts === 0 → 通过

7.4 验证 Dependabot（依赖扫描）

使用 GitHub MCP 执行以下检查：

获取 open 状态的 critical 告警：GET /repos/{owner}/{repo}/dependabot/alerts?state=open&severity=critical&per_page=100
如果返回 404 → 不通过（未启用）
如果返回 200 → 检查 critical 告警数量

判定： 已启用且 alertsCritical === 0 → 通过

7.5 汇总验证结果

将 4 项检查结果汇总：

验证结果汇总：
1. Attestation（构建证明）：  ✅ 通过 / ❌ 不通过
2. Code Scanning（代码扫描）：✅ 通过 / ❌ 不通过
3. Secret Scanning（密钥扫描）：✅ 通过 / ❌ 不通过
4. Dependabot（依赖扫描）：  ✅ 通过 / ❌ 不通过

总体结果：✅ 全部通过 / ❌ 存在未通过项

如果全部通过 → 继续 Step 8

如果存在未通过项 → 回到对应步骤修复：

Attestation 不通过 → 回到 Step 3
Code Scanning 不通过 → 回到 Step 6.1
Secret Scanning 不通过 → 回到 Step 6.2
Dependabot 不通过 → 回到 Step 6.3

禁止在最终验证未全部通过的情况下进入 Step 8。

完成后更新 checklist：

☑ Step 7: 最终验证 — 模拟审核系统逐项验证

Step 8: 生成预检报告

目标： 生成完整的预检结果报告，供用户存档参考。

生成一份中文报告，包含以下内容：

报告模板：

# 安全预检报告

## 项目信息
- 项目名称：{repo}
- GitHub 地址：https://github.com/{owner}/{repo}
- 预检时间：{当前日期时间}
- 预检结果：✅ 全部通过

## 检查结果明细

### 1. CI 构建 & Attestation（构建证明）
- 状态：✅ 通过
- CI Workflow：.github/workflows/release.yml
- 项目类型：{检测到的项目类型}
- 最新 Release：v1.0.0
- Release 产物数量：{数量}
- Attestation 验证：已通过

### 2. Code Scanning（代码扫描）
- 状态：✅ 通过
- 扫描引擎：CodeQL (Default)
- 告警统计：
  - Critical: 0
  - High: {数量}
  - Medium: {数量}
  - Low: {数量}
- 修复记录：{如果有修复，列出修复了什么；如果没有，写"无需修复"}

### 3. Secret Scanning（密钥扫描）
- 状态：✅ 通过
- Open 告警数：0
- 修复记录：{如果有修复，列出修复了什么；如果没有，写"无需修复"}

### 4. Dependabot（依赖扫描）
- 状态：✅ 通过
- 告警统计：
  - Critical: 0
  - High: {数量}
  - Medium: {数量}
  - Low: {数量}
- 修复记录：{如果有修复，列出升级了哪些依赖；如果没有，写"无需修复"}

## 执行步骤记录

| 步骤 | 操作内容 | 状态 |
|------|---------|------|
| Step 0 | 安装并配置 GitHub MCP 和 Playwright MCP | ✅ 完成 |
| Step 1 | 推送代码到个人 GitHub 公开仓库 | ✅ 完成 |
| Step 2 | 生成 GitHub Actions CI 文件（{项目类型}） | ✅ 完成 |
| Step 3 | 触发 CI 构建并验证 Attestation | ✅ 完成 |
| Step 4 | 启用 Code Scanning、Secret Scanning、Dependabot | ✅ 完成 |
| Step 5 | 确认 CodeQL 扫描完成（等待约 30-60 分钟） | ✅ 完成 |
| Step 6 | 检查并修复安全问题 | ✅ 完成 |
| Step 7 | 最终验证全部通过 | ✅ 完成 |
| Step 8 | 生成预检报告 | ✅ 完成 |

## 后续操作

预检已全部通过。接下来你可以按照正式发布流程将项目提交审核：

1. 按照 [AI 助手 - 安全发布自动化引导](https://tpscsm-docs.pages.dev/ai/) 完成正式流程
2. 正式流程中会将项目转移到 `secure-artifacts` 组织并提交审核
3. 由于预检已通过，审核应能一次性通过

根据实际执行情况填充报告内容。

完成后更新 checklist：

☑ Step 8: 生成预检报告 — 输出完整的预检结果报告

常见问题

Q: 为什么仓库必须是 public？

GitHub 的 Code Scanning、Secret Scanning、Dependabot 等安全功能在公开仓库（public）上免费可用。私有仓库（private）需要 GitHub Advanced Security 付费许可证。将仓库设为 public 可以确保所有安全功能正常运行。

Q: 为什么预检要分两个阶段？

因为 GitHub Code Scanning (CodeQL) 首次全量扫描需要 30-60 分钟甚至更久。如果启用安全扫描后立即检查告警结果，告警列表为空（扫描还没跑完），系统会误判为"无安全问题，通过"。等用户提交审核、管理员审核时，扫描已经完成，这时大量 critical 告警才出现，导致审核不通过。

因此，第一阶段完成配置和启用后，必须暂停等待 30-60 分钟让 GitHub 完成扫描，第二阶段再检查结果。这样预检结果才是准确可靠的。

Q: Code Scanning 首次扫描很慢怎么办？

CodeQL 首次扫描需要分析整个代码库，通常需要 30-60 分钟，大型项目或多语言项目可能更久。这是正常的，请耐心等待。后续扫描（代码推送触发的增量扫描）会快很多，通常只需几分钟。

Q: Dependabot 告警升级依赖后导致项目不兼容怎么办？

如果直接升级导致项目无法编译或运行，可以：

查看告警中建议的最低修复版本，使用最接近当前版本的修复版本
如果没有兼容的修复版本，可以在审核时向管理员说明情况
对于 critical 告警，管理员可能会要求必须修复或提供替代方案

Q: Secret Scanning 误报怎么处理？

如果告警是误报（例如测试用的假密钥、文档中的示例密钥），可以使用 GitHub API 将其标记为 false positive：

PATCH /repos/{owner}/{repo}/secret-scanning/alerts/{alert_number}
Body: { "state": "resolved", "resolution": "false_positive" }

Q: `permissions` 关键字大小写有要求吗？

有。必须全部小写 permissions，不能写成 PERMISSIONS 或 Permissions。GitHub Actions YAML 是大小写敏感的，写错大小写会导致 workflow 解析失败。

Q: 预检通过后，正式审核还会失败吗？

如果预检通过后没有修改代码，正式审核的检查项与预检完全一致，应该能一次通过。但如果在预检完成后到正式提交审核之间修改了代码（引入了新的漏洞或密钥泄露），可能会导致审核失败。建议预检通过后尽快提交正式审核。

AI 助手 - 安全预检自动化引导 ​

预检标准 ​

面向 AI 助手的说明 ​

核心原则 ​

强制执行规则 ​

Step 0: 环境准备 ​

0.1 检查并安装 Playwright MCP Server ​

Claude Code ​

Cursor ​

VS Code ​

Google Antigravity ​

其他 AI 工具 ​

0.2 检查并安装 GitHub MCP Server ​

0.2.1 询问用户是否已有 Token ​

0.2.2 使用 Playwright 自动创建 Token ​

0.2.3 将 Token 写入 GitHub MCP 配置（User Scope） ​

Claude Code ​

Cursor ​

VS Code ​

Google Antigravity ​

其他 AI 工具 ​

安全提醒 ​

0.3 验证 MCP 工具可用 ​

Step 1: 推送到个人 GitHub ​

1.1 检查当前项目 Git 状态 ​

1.2 根据状态执行对应操作 ​

场景 A：项目尚未推送到 GitHub ​

场景 B：项目已在 GitHub 上 ​

1.3 验证仓库为 public ​

1.4 记录仓库信息 ​

Step 2: 配置 CI Workflow ​

2.1 检查是否已有 CI 配置 ​

2.2 检测项目类型 ​

2.3 获取 CI 模板 ​

2.4 生成 workflow 文件 ​

2.5 推送 workflow 文件 ​

Step 3: 触发构建并验证 ​

3.1 创建 Tag 并推送 ​

3.2 等待 CI 完成（必须成功才能继续） ​

3.3 验证 Release 和 Attestation ​

Step 4: 开启安全扫描 ​

4.1 启用 Secret Scanning 和 Dependabot（通过 GitHub API） ​

4.2 语言适配判定（Swift 项目特殊处理） ​

Step A：选择 codeql.yml 模板 ​

Step B：按启发式规则填充模板参数 ​

Step C：将 codeql.yml 提交到仓库 ​

Step D：使用 Playwright 将 Code scanning 切到 Advanced ​

Step E：Playwright 切换失败时的手动降级 ​

4.3 启用 Code Scanning / CodeQL（通过 Playwright，非 Swift 项目） ​

4.4 验证所有安全功能已启用 ​

4.5 记录启用时间并通知用户暂停 ​

Step 5: 确认扫描完成 ​

5.1 检查 Code Scanning 分析是否完成 ​

5.2 确认 Secret Scanning 和 Dependabot 已完成 ​

5.3 全部扫描确认完成 ​

Step 6: 检查并修复安全问题 ​

6.1 检查 Code Scanning 告警 ​

6.2 检查 Secret Scanning 告警 ​

6.3 检查 Dependabot 告警 ​

6.4 修复后重新触发构建（如果代码有变更） ​

Step 7: 最终验证 ​

7.1 验证 Attestation（构建证明） ​

7.2 验证 Code Scanning（代码扫描） ​

7.3 验证 Secret Scanning（密钥扫描） ​

7.4 验证 Dependabot（依赖扫描） ​

7.5 汇总验证结果 ​

Step 8: 生成预检报告 ​

常见问题 ​

Q: 为什么仓库必须是 public？ ​

Q: 为什么预检要分两个阶段？ ​

Q: Code Scanning 首次扫描很慢怎么办？ ​

Q: Dependabot 告警升级依赖后导致项目不兼容怎么办？ ​

Q: Secret Scanning 误报怎么处理？ ​

Q: permissions 关键字大小写有要求吗？ ​

Q: 预检通过后，正式审核还会失败吗？ ​

AI 助手 - 安全预检自动化引导

预检标准

面向 AI 助手的说明

核心原则

强制执行规则

Step 0: 环境准备

0.1 检查并安装 Playwright MCP Server

Claude Code

Cursor

VS Code

Google Antigravity

其他 AI 工具

0.2 检查并安装 GitHub MCP Server

0.2.1 询问用户是否已有 Token

0.2.2 使用 Playwright 自动创建 Token

0.2.3 将 Token 写入 GitHub MCP 配置（User Scope）

Claude Code

Cursor

VS Code

Google Antigravity

其他 AI 工具

安全提醒

0.3 验证 MCP 工具可用

Step 1: 推送到个人 GitHub

1.1 检查当前项目 Git 状态

1.2 根据状态执行对应操作

场景 A：项目尚未推送到 GitHub

场景 B：项目已在 GitHub 上

1.3 验证仓库为 public

1.4 记录仓库信息

Step 2: 配置 CI Workflow

2.1 检查是否已有 CI 配置

2.2 检测项目类型

2.3 获取 CI 模板

2.4 生成 workflow 文件

2.5 推送 workflow 文件

Step 3: 触发构建并验证

3.1 创建 Tag 并推送

3.2 等待 CI 完成（必须成功才能继续）

3.3 验证 Release 和 Attestation

Step 4: 开启安全扫描

4.1 启用 Secret Scanning 和 Dependabot（通过 GitHub API）

4.2 语言适配判定（Swift 项目特殊处理）

Step A：选择 codeql.yml 模板

Step B：按启发式规则填充模板参数

Step C：将 codeql.yml 提交到仓库

Step D：使用 Playwright 将 Code scanning 切到 Advanced

Step E：Playwright 切换失败时的手动降级

4.3 启用 Code Scanning / CodeQL（通过 Playwright，非 Swift 项目）

4.4 验证所有安全功能已启用

4.5 记录启用时间并通知用户暂停

Step 5: 确认扫描完成

5.1 检查 Code Scanning 分析是否完成

5.2 确认 Secret Scanning 和 Dependabot 已完成

5.3 全部扫描确认完成

Step 6: 检查并修复安全问题

6.1 检查 Code Scanning 告警

6.2 检查 Secret Scanning 告警

6.3 检查 Dependabot 告警

6.4 修复后重新触发构建（如果代码有变更）

Step 7: 最终验证

7.1 验证 Attestation（构建证明）

7.2 验证 Code Scanning（代码扫描）

7.3 验证 Secret Scanning（密钥扫描）

7.4 验证 Dependabot（依赖扫描）

7.5 汇总验证结果

Step 8: 生成预检报告

常见问题

Q: 为什么仓库必须是 public？

Q: 为什么预检要分两个阶段？

Q: Code Scanning 首次扫描很慢怎么办？

Q: Dependabot 告警升级依赖后导致项目不兼容怎么办？

Q: Secret Scanning 误报怎么处理？

Q: `permissions` 关键字大小写有要求吗？

Q: 预检通过后，正式审核还会失败吗？