AI 助手 - 安全发布自动化引导

本页面专为 AI 助手设计

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

使用示例

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

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

AI 会阅读本页内容，自动配置环境、检查权限、生成 CI 文件、推送代码、提交审核。

前置条件

用户需要拥有一个 GitHub 账号。如果没有，请先访问 https://github.com/signup 注册。

面向 AI 助手的说明

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

强制执行规则

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

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

☐ Step 0: 环境准备 — 安装并验证 GitHub MCP 和 Playwright MCP
☐ Step 1: 组织权限检查 — 确认用户已加入 secure-artifacts 组织
☐ Step 2: 生成 CI 文件 — 根据项目类型生成 GitHub Actions workflow（Swift 项目额外生成 codeql.yml）
☐ Step 3: 推送到 GitHub — 将项目代码推送到 secure-artifacts 组织
☐ Step 4: 触发 CI 构建 — 创建 tag 触发 CI，更新 README
☐ Step 5: 提交项目审核 — 在安全管理平台提交审核申请
☐ Step 6: 通知管理员 — 生成 Teams 通知消息
☐ Step 7: 等待审核并生成报告 — 完成后生成完整报告

必须逐步执行 — 按照 Step 0 到 Step 7 的顺序逐一执行，禁止跳过任何步骤，禁止合并步骤。
必须通知用户 — 每个步骤开始执行前和完成后都必须通知用户当前进度。
必须完成每个子任务 — 每个步骤内部的子任务也必须全部完成，不得偷懒省略。
遇到错误必须处理 — 如果某个步骤执行失败，必须尝试修复或告知用户具体的错误原因，不得静默跳过。

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-Release
- Expiration：选择 No expiration（或 90 days，取决于页面选项）
- 勾选以下权限 scope：
  - repo（完整仓库访问）
  - admin:org（组织管理）
  - read:user（读取用户信息）
通知用户：

我已经在浏览器中打开了 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），确认能成功返回用户信息

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

完成后更新 checklist：

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

Step 1: 组织权限检查

目标： 确认用户已加入 secure-artifacts GitHub 组织。如未加入，自动提交申请。

1.1 获取当前用户信息

使用 GitHub MCP 获取当前认证用户的信息，记下：

GitHub 用户名（login）
GitHub 主页链接（https://github.com/用户名）

1.2 检查组织成员资格

使用 GitHub MCP 检查当前用户是否为 secure-artifacts 组织的成员。

如果已是成员 → 通知用户"您已在 secure-artifacts 组织中"，跳到 Step 2

如果不是成员 → 执行以下步骤：

1.3 提交加入组织申请

使用 Playwright 打开页面：https://tpscsm-web.pages.dev/submit/join
在 "GitHub 用户名或主页链接" 输入框中填入用户的 GitHub 用户名或主页链接（在 1.1 中获取的）
询问用户开发者名称：

请提供你的姓名（开发者名称），用于后续软件出现问题时联系你进行反馈。

在 "开发者名称" 输入框中填入用户提供的姓名
通知用户：

我已经在浏览器中打开了组织申请页面，并填好了你的 GitHub 信息和开发者名称。请在浏览器中完成以下操作：
完成 reCAPTCHA 人机验证
点击"提交申请"按钮
完成后请回复"提交完了"。

等待用户回复"提交完了"

1.4 等待管理员审核

通知用户：

申请已提交！接下来请做以下事情：
到 Teams 群里通知管理员你已提交了加入组织的申请
等待管理员审核通过后，你会收到 GitHub 组织邀请
访问 https://github.com/orgs/secure-artifacts/invitation 接受邀请
管理员审核通过并且你接受邀请后，请回复"已完成"，我们继续下一步。

等待用户确认已完成。

完成后更新 checklist：

☑ Step 1: 组织权限检查 — 确认用户已加入 secure-artifacts 组织

Step 2: 生成 CI 文件

目标： 根据当前项目类型，生成 GitHub Actions workflow 文件。

2.1 检测项目类型

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

检测文件	项目类型
`manifest.json`（含 `content_scripts` / `background` / `action` 任一字段）	浏览器扩展项目
`package.json`（含 `electron` 依赖）	Electron 应用
`package.json`（不含 `electron`）	Node.js 项目
`setup.py` 或 `pyproject.toml`	Python 项目
`go.mod`	Go 项目
`Cargo.toml`	Rust 项目
`.sln` 或 `.csproj`	.NET 项目
`.xcodeproj` / `.xcworkspace` / `Package.swift` / 含 `.swift` 源文件	Swift 项目
其他	通用项目

浏览器扩展判定优先级高于 Node.js

浏览器扩展项目一般同时含 package.json（用于 npm 脚本和构建工具），必须先按 manifest.json 判定为浏览器扩展，不得按 Node.js 项目匹配。判定条件：项目根存在 manifest.json，且其 JSON 中至少包含 content_scripts / background / action 三个字段中的一个。

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

审核类型（kind）透传到 Step 5

这里对项目类型的判定结果会在 Step 5.2 提交表单时映射到"审核类型"字段（API 层 kind 字段，枚举 "software" | "browser_extension" | "source_only"）：

本步判定为浏览器扩展项目 → Step 5.2 选择"浏览器扩展"（kind=browser_extension）
用户明确要求「仅做源码审核 / 不需要构建产物 / 不需要 CI」 → Step 5.2 选择"源码审核"（kind=source_only），并跳过 Step 2 ~ Step 4（无需生成 CI、无需触发构建、无需 Attestation）
其他任何项目类型 → Step 5.2 选择"软件"（kind=software，也是默认值）

kind 字段可选不强制：AI 调用公开提交接口 POST /api/submissions 时不传 kind 也兼容（服务端兜底为 "software"），但通过 Step 5.2 UI 提交时该字段必填。

source_only 分流

若判定为"源码审核"（kind=source_only），平台只执行 Code Scanning、Secret Scanning、Dependabot 三项源码级检查，跳过 Attestation 与 Release 采集（verified=true、latestVersion=null、downloadUrls={}）。项目不会出现在公开首页的"软件 / 浏览器扩展"列表中，而是在独立的 /source-only 页面按 Critical / High / Medium / Low 告警维度展示。因此当前 AI 流程中涉及生成 release.yml、推送 tag 触发构建、验证 Attestation 的所有环节对该类型都不适用，应直接跳到 Step 5 提交审核。

Swift 项目特别说明

Swift 项目必须同时生成两份 workflow 文件（release.yml + codeql.yml），不能只生成其中一份。详见下方 2.3 Swift 项目额外步骤。判定规则：项目根及子目录中存在任何 .swift 文件（排除 node_modules/、vendor/、.build/、DerivedData/、Pods/、Carthage/、**/examples/、**/fixtures/ 等目录），或存在 *.xcodeproj / *.xcworkspace / Package.swift，即判定为 Swift 项目。

2.2 获取 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.3 Swift 项目额外步骤（仅 Swift 项目执行）

若在 2.1 中识别为 Swift 项目，AI 除了生成 release.yml 之外，必须额外生成一份 .github/workflows/codeql.yml，用于代码扫描。两份 workflow 职责不同：

文件	触发方式	作用
`release.yml`	tag push (`v*`)	构建产物 + Attestation + 创建 Release
`codeql.yml`	push to main / PR / weekly cron	CodeQL 代码扫描（swift autobuild 对 Xcode 16+ 同步组不工作，必须走 Advanced 模式自带 workflow）

2.3.1 选择 release.yml 模板（按项目形态三选一）

Swift 项目在 workflow-example 文档中有三份 release 模板，AI 必须按项目形态挑选对应的一份，不能套错。判定规则：

项目形态判定	选用模板
仅有 `Package.swift`，定义了 executable product，无 `*.xcodeproj`	Swift 项目示例 - SPM CLI 工具
有 `*.xcodeproj`，target 类型是 `application`（macOS App）	Swift 项目示例 - macOS 应用
有 `*.xcodeproj`，但 target 类型是 CLI / framework / library	需要用户确认交付形态（`.app` DMG 还是 CLI 二进制）后再挑，默认按 CLI 走 SPM 模板或请用户指定

判定方法：

若存在 *.xcodeproj，Grep project.pbxproj 查找 productType = "com.apple.product-type.application" 命中即 macOS 应用；命中 tool / framework / library 则按对应形态处理。
若仅有 Package.swift，Grep 其内容找 .executable(name: 或 executableTarget(name: 判定为 SPM CLI。
两种都没命中时，向用户询问交付形态。

AI 填写 release.yml 参数规则：

SPM CLI 模板：把 --product myapp 的 myapp 改成 Package.swift 里第一个 executable product 名；多个 executable 时取第一个或请用户指定。
macOS 应用模板：模板含 4 个占位符 <PROJECT> / <SCHEME> / <APP_NAME> / <VOLUME_NAME>——
- <PROJECT>：唯一 *.xcodeproj 同名（去掉 .xcodeproj 后缀）；多个 xcodeproj 保留占位符。
- <SCHEME>：默认等于 <PROJECT>；若 xcodebuild -list 输出与 project 名不一致则保留占位符让用户补值。
- <APP_NAME>：通常等于 <SCHEME>；若 Info.plist 的 CFBundleName 与 scheme 不同以 CFBundleName 为准。
- <VOLUME_NAME>：建议等于 <APP_NAME>（DMG 挂载卷名）。

2.3.2 选择 codeql.yml 模板

获取 CodeQL workflow 模板（Swift 版）：
Xcode 工程项目（.xcodeproj）参见 CodeQL workflow（Swift - Xcode 工程）
Swift Package Manager 项目参见 CodeQL workflow（Swift - SPM）

AI 填参数规则：
Xcode 工程：若项目根下唯一 *.xcodeproj 为 Foo.xcodeproj，填 -project Foo.xcodeproj -scheme Foo；若存在多个 .xcodeproj 或位于 workspace 内，必须保留 <PROJECT>.xcodeproj / <SCHEME> 占位符并提示用户补值。
SPM：若 Package.swift 有单个 executable product mycli，填 swift build --product mycli；多 executable 时取第一个 executable product；纯 library 项目省略 --product，仅写 swift build。

两份 workflow 文件必须在同一次 commit 中提交，commit message 示例：ci: 添加 release 与 CodeQL workflow。

2.4 浏览器扩展项目额外步骤（仅浏览器扩展项目执行）

若在 2.1 中识别为浏览器扩展项目，AI 必须按以下规则生成 release.yml，不能套用通用 Node.js 模板，否则产物 zip 将无法通过平台的 Attestation L2 校验。

2.4.1 获取浏览器扩展专用模板

使用 websearch 访问浏览器扩展项目示例，抓取完整 workflow YAML 原文，不得凭记忆拼凑。

若锚点暂时不可用（例如 developer 文档尚未上线该小节），请同时浏览 /developer/workflow-example 页面内查找"浏览器扩展"标题；两处都不存在时通知用户"浏览器扩展模板暂缺，请联系安全管理团队"而不要擅自降级为 Node.js 模板。

2.4.2 打包路径约束

模板在 build 完成后以下列方式生成最终产物：

bash

cd dist && zip -r ../<extension-name>-$\{\{ github.ref_name \}\}.zip .

其中：

<extension-name> 建议与 manifest.json 的 name 字段（去空格/小写化）或仓库名保持一致；
zip 必须在仓库根目录生成，后续 softprops/action-gh-release 与 attest-build-provenance 步骤都直接引用 *.zip 或 <extension-name>-*.zip，不允许把 artifacts 下载到本地再手工上传。

2.4.3 四项 L2 约束（必须严格遵守）

浏览器扩展 workflow 与其他语言模板一样，必须同时满足以下四项，平台 Attestation L2 校验才会通过：

tag push 触发 — on: push: tags: ['v*']，禁止使用 release: published、workflow_dispatch 或 branch push 触发；
默认 GITHUB_TOKEN 上传 — 让 softprops/action-gh-release 使用 secrets.GITHUB_TOKEN 或省略 token 参数，禁止引导用户配置个人 PAT；
action 上传 Release — 所有 asset 必须由 GitHub Actions（github-actions[bot]）上传，禁止人工在 GitHub Web UI 拖拽、粘贴、替换 asset；
attest-build-provenance 的 subject-path 指向最终 zip — 例如 '*.zip' 或 'dist/*.zip'，不得指向源码目录、未打包的 dist/、或 build 中间产物。

2.4.4 范围边界

浏览器扩展模板不包含以下内容，AI 遇到相关需求应提示"不在本流程范围内"：

CRX 打包与签名
Chrome Web Store / Edge Add-ons / Firefox AMO 发布
企业策略 extensions.install.force.list 与更新 XML
manifest.json 的 permissions / host_permissions 审计

产物仅为 zip，供员工下载后在 Chrome chrome://extensions 用"加载已解压的扩展程序"使用。

2.5 生成 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*'

Swift 项目额外关键要求（必须严格遵守）：

codeql.yml 和 release.yml 必须同时提交到同一 commit，不得分两次 commit。
codeql.yml 的 -scheme / -project / --product 参数填写必须遵循上面 2.3 的 AI 填参数规则（同名启发式 + 占位符回退）。
push 到 main 之后，必须立即按安全预检流程的 Step 4.2 "语言适配判定（Swift 项目特殊处理）"，通过 Playwright 把该仓库的 Code scanning 切到 Advanced 模式（否则 GitHub 会继续跑 Default autobuild 并失败，导致后续扫描结果为空）。

生成完成后，通知用户已创建了什么类型的 CI 文件（Swift 项目需说明已同时生成 release.yml 和 codeql.yml 两份）。

完成后更新 checklist：

☑ Step 2: 生成 CI 文件 — 根据项目类型生成 GitHub Actions workflow（Swift 项目额外生成 codeql.yml）

Step 3: 推送到 GitHub

目标： 确保项目代码已推送到 secure-artifacts 组织下。

3.1 检查当前项目 Git 状态

检查以下内容：

项目是否已有 .git 目录（是否已初始化 git）
是否有 git remote（是否已关联远程仓库）
如果有 remote，检查 URL 是否以 github.com/secure-artifacts/ 开头

3.2 根据状态执行对应操作

场景 A：项目未在 GitHub 上

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

场景 B：项目已在 GitHub 上但不在 secure-artifacts 组织中

使用 GitHub MCP 将仓库转移（transfer）到 secure-artifacts 组织。

转移完成后，更新本地 git remote URL：

bash

git remote set-url origin https://github.com/secure-artifacts/项目名.git

场景 C：项目已在 secure-artifacts 组织下

确认 Step 2 生成的 CI 文件已推送到仓库。如果有未推送的变更，执行 push。

3.3 记录项目 URL

记下项目的 GitHub URL（后续步骤需要使用）：https://github.com/secure-artifacts/项目名

完成后更新 checklist：

☑ Step 3: 推送到 GitHub — 将项目代码推送到 secure-artifacts 组织

Step 4: 触发 CI 构建 + 更新 README

目标： 创建 tag 触发 CI 构建，生成带有 Attestation 签名的 Release，并更新项目 README。

严禁人工介入 Release

AI 助手在此流程中绝对禁止执行以下操作：

在 GitHub Web UI 手动创建或编辑 Release
在 GitHub Web UI 手动上传、替换、删除 Release asset
从 Actions artifacts 下载 CI 产物再手工传入 Release

平台审核系统会校验每个 asset 的上传者必须是 github-actions[bot]，任何人工介入都会导致审核失败。

CI 构建失败时，只能通过「删除 tag → 修复代码/workflow → 重新 push tag」的方式修复，不允许任何形式的人工补救。

Swift 项目注意

codeql.yml 在每次 push 到 main 时自动运行（不依赖 tag），首次 push 完成 Swift 分支后已经自动触发一次 CodeQL 扫描。本 Step 4 仍聚焦 tag 触发的 release workflow，CodeQL 扫描结果的查验在预检流程 Step 5 进行。

4.1 创建 Tag 并推送

bash

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

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

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

如果 CI 成功 → 继续 4.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 未成功的情况下进入下一步。

4.3 更新 README.md

在项目的 README.md 中（如果不存在则创建），添加或更新以下中文内容。这份说明是写给用户看的，假设用户是编程小白，需要详细的命令演示：

在 README.md 中需要包含的内容模板（以中文编写）：

markdown

## 如何发布新版本

本项目使用 GitHub Actions 自动构建和发布。每次发布新版本只需要创建一个 Git Tag 并推送即可。

### 发布步骤

#### 1. 确保代码已提交并推送

在发布之前，确保你的所有代码改动已经提交并推送到 GitHub：

```bash
# 查看当前状态
git status

# 添加所有改动
git add .

# 提交改动（把"你的改动说明"替换成实际的描述）
git commit -m "你的改动说明"

# 推送到 GitHub
git push origin main
```

#### 2. 创建版本 Tag

Git Tag 是一个版本标记，用于标识发布的版本号。版本号格式为 `v主版本.次版本.修订版本`，例如 `v1.0.0`、`v1.1.0`、`v2.0.0`。

```bash
# 创建一个新的版本 tag（将 v1.0.1 替换为你想要的版本号）
git tag -a v1.0.1 -m "Release version 1.0.1"
```

#### 3. 推送 Tag 触发自动构建

```bash
# 推送 tag 到 GitHub（这会自动触发 CI 构建）
git push origin v1.0.1
```

推送后，GitHub Actions 会自动执行以下操作：
1. 构建项目
2. 生成安全签名（Attestation）
3. 创建 Release 并上传构建产物

#### 4. 查看构建结果

- 构建进度：访问项目的 **Actions** 页面查看
- 发布结果：访问项目的 **Releases** 页面查看已发布的文件

### 版本号说明

| 版本号格式 | 什么时候用 | 示例 |
|-----------|-----------|------|
| `vX.0.0` | 重大更新、不兼容改动 | `v2.0.0` |
| `vX.Y.0` | 新增功能 | `v1.1.0` |
| `vX.Y.Z` | 修复 bug | `v1.0.1` |

### 如果构建失败怎么办

1. 访问项目的 **Actions** 页面查看错误日志
2. 修复代码问题
3. 删除失败的 tag 并重新创建：

```bash
# 删除本地 tag
git tag -d v1.0.1

# 删除远程 tag
git push origin :refs/tags/v1.0.1

# 修复问题后，重新创建并推送
git tag -a v1.0.1 -m "Release version 1.0.1"
git push origin v1.0.1
```

将 README 变更推送到 GitHub：

bash

git add README.md
git commit -m "docs: 添加 CI 构建和发布说明"
git push origin main

完成后更新 checklist：

☑ Step 4: 触发 CI 构建 — 创建 tag 触发 CI，更新 README

Step 5: 提交项目审核

目标： 在安全管理平台提交项目审核申请。

前置条件： 当审核类型为 software / browser_extension 时，Step 4 的 CI 构建必须已成功完成（Release 已创建、Attestation 已生成）。如果 CI 尚未成功，禁止执行本步骤，必须先回到 Step 4 完成修复。source_only 是例外：该类型无需 CI / Release / Attestation，可直接执行本步骤。

5.1 打开审核页面

使用 Playwright 打开页面：https://tpscsm-web.pages.dev/submit/review

5.2 填写表单

在 "审核类型" 选择器中按 Step 2.1 的项目类型判定结果选择对应项（三选一）：
- Step 2.1 判定为浏览器扩展项目（根存在 manifest.json 且含 content_scripts / background / action 任一） → 必须切到 "浏览器扩展"
- 用户明确要求「仅做源码审核 / 不需要构建产物 / 不需要 CI」 → 必须切到 "源码审核"（此类型无需走 Step 2 ~ Step 4 的 CI 配置与构建流程，直接在此步提交即可）
- 其他任何项目类型 → 保持默认 "软件"（页面默认选中，无需改动）

分类必须与判定一致

若 Step 2.1 已识别为浏览器扩展但此处仍留在"软件"段提交，软件会被错误分类到公开站"软件"视图下，后续需要管理员在 admin 详情页手动改 kind。若用户诉求为仅源码审核但此处误选"软件"或"浏览器扩展"，平台会期望 Attestation 与 Release，审核会持续卡在失败状态。 Step 2.1 判定结果、用户审核诉求与此处选择必须一致。

在 "GitHub 项目 URL" 输入框中填入项目 URL（在 Step 3 中记录的，格式为 https://github.com/secure-artifacts/项目名）
询问用户开发者名称（如果在 Step 1 中已经获取过，可直接复用）：

请提供你的姓名（开发者名称），用于后续软件出现问题时联系你进行反馈。

在 "开发者名称" 输入框中填入用户提供的姓名

5.3 通知用户完成提交

通知用户：

我已经在浏览器中打开了项目审核提交页面，并填好了项目信息和开发者名称。请在浏览器中完成以下操作：
完成 reCAPTCHA 人机验证
点击"提交审核"按钮
完成后请回复"提交完了"。

等待用户回复"提交完了"。

完成后更新 checklist：

☑ Step 5: 提交项目审核 — 在安全管理平台提交审核申请

Step 6: 通知管理员

目标： 生成 Teams 通知消息，让用户发送给管理员。

生成以下格式的通知消息，提供给用户复制到 Teams 群发送：

你好，我已经提交了项目安全审核申请，请帮忙审核。

项目链接：https://github.com/secure-artifacts/项目名

谢谢！

通知用户：

请将以上消息复制到 Teams 群里发送给管理员，通知他们进行审核。

完成后更新 checklist：

☑ Step 6: 通知管理员 — 生成 Teams 通知消息

Step 7: 等待审核并生成报告

目标： 等待管理员完成审核，然后生成完整的中文报告。

7.1 等待审核

通知用户：

审核申请已提交完毕。管理员审核通常在 1-3 个工作日内完成，审核结果会通过 Teams 通知。审核完成后请回复"审核完了"，我将为你生成完整的报告。

注意：审核通过后，平台会持续对软件进行自动安全检查（每 6 小时版本更新检查、每周全量检查）。若检查失败，软件将从平台下架。如发现自己的软件消失，可访问安全事件公示页面查看下架原因并修复。

等待用户确认审核已完成。

7.2 生成完整报告

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

报告模板：

# 安全发布流程完成报告

## 项目信息
- 项目名称：xxx
- GitHub 地址：https://github.com/secure-artifacts/xxx
- 审核状态：已通过

## 执行步骤记录

| 步骤 | 操作内容 | 状态 |
|------|---------|------|
| Step 0 | 安装并配置 GitHub MCP 和 Playwright MCP | ✅ 完成 |
| Step 1 | 检查/申请加入 secure-artifacts 组织 | ✅ 完成 |
| Step 2 | 生成 GitHub Actions CI 文件 (xxx 类型)（Swift 项目含 codeql.yml；浏览器扩展项目含 zip 打包配置） | ✅ 完成 |
| Step 3 | 将项目推送到 secure-artifacts 组织 | ✅ 完成 |
| Step 4 | 创建 v1.0.0 tag 触发 CI 构建并更新 README | ✅ 完成 |
| Step 5 | 提交项目安全审核 | ✅ 完成 |
| Step 6 | 通知管理员审核 | ✅ 完成 |
| Step 7 | 等待审核完成并生成报告 | ✅ 完成 |

## 项目维护指南

### 如何发布新版本

每次需要发布新版本时，执行以下步骤：

1. 确保代码已推送到 GitHub
2. 创建版本 tag：`git tag -a vX.Y.Z -m "Release version X.Y.Z"`
3. 推送 tag：`git push origin vX.Y.Z`
4. GitHub Actions 会自动构建、签名并发布

### 如何修改 CI 配置

CI 配置文件位于 `.github/workflows/release.yml`。如需修改：

1. 编辑该文件
2. 提交并推送到 GitHub
3. 创建新 tag 验证构建是否正常

注意：修改 CI 文件后不要忘记重新推送。

### 重要注意事项

- 版本 tag 格式必须以 `v` 开头（如 v1.0.0）
- 构建产物会自动附带 Attestation 安全签名
- 如需帮助，可以在 Teams 群联系安全管理团队

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

完成后更新 checklist：

☑ Step 7: 等待审核并生成报告 — 完成后生成完整报告

常见问题

Q: GitHub Actions 构建失败怎么办？

使用 GitHub MCP 查询 workflow run 日志，查看具体错误
修复代码或 workflow 文件
删除失败的 tag 并重新创建

Q: 项目审核不通过怎么办？

管理员会通过 Teams 说明不通过的原因。修复问题后可以重新提交审核。

Q: permissions 中的三个权限分别是什么作用？

id-token: write — 让 GitHub Actions 生成 OIDC token，用于 Attestation 签名
contents: write — 允许创建 GitHub Release
attestations: write — 允许生成和存储 Attestation 记录

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

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

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: 组织权限检查 ​

1.1 获取当前用户信息 ​

1.2 检查组织成员资格 ​

1.3 提交加入组织申请 ​

1.4 等待管理员审核 ​

Step 2: 生成 CI 文件 ​

2.1 检测项目类型 ​

2.2 获取 CI 模板 ​

2.3 Swift 项目额外步骤（仅 Swift 项目执行） ​

2.3.1 选择 release.yml 模板（按项目形态三选一） ​

2.3.2 选择 codeql.yml 模板 ​

2.4 浏览器扩展项目额外步骤（仅浏览器扩展项目执行） ​

2.4.1 获取浏览器扩展专用模板 ​

2.4.2 打包路径约束 ​

2.4.3 四项 L2 约束（必须严格遵守） ​

2.4.4 范围边界 ​

2.5 生成 workflow 文件 ​

Step 3: 推送到 GitHub ​

3.1 检查当前项目 Git 状态 ​

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

场景 A：项目未在 GitHub 上 ​

场景 B：项目已在 GitHub 上但不在 secure-artifacts 组织中 ​

场景 C：项目已在 secure-artifacts 组织下 ​

3.3 记录项目 URL ​

Step 4: 触发 CI 构建 + 更新 README ​

4.1 创建 Tag 并推送 ​

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

4.3 更新 README.md ​

Step 5: 提交项目审核 ​

5.1 打开审核页面 ​

5.2 填写表单 ​

5.3 通知用户完成提交 ​

Step 6: 通知管理员 ​

Step 7: 等待审核并生成报告 ​

7.1 等待审核 ​

7.2 生成完整报告 ​

常见问题 ​

Q: GitHub Actions 构建失败怎么办？ ​

Q: 项目审核不通过怎么办？ ​

Q: permissions 中的三个权限分别是什么作用？ ​

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

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: 组织权限检查

1.1 获取当前用户信息

1.2 检查组织成员资格

1.3 提交加入组织申请

1.4 等待管理员审核

Step 2: 生成 CI 文件

2.1 检测项目类型

2.2 获取 CI 模板

2.3 Swift 项目额外步骤（仅 Swift 项目执行）

2.3.1 选择 release.yml 模板（按项目形态三选一）

2.3.2 选择 codeql.yml 模板

2.4 浏览器扩展项目额外步骤（仅浏览器扩展项目执行）

2.4.1 获取浏览器扩展专用模板

2.4.2 打包路径约束

2.4.3 四项 L2 约束（必须严格遵守）

2.4.4 范围边界

2.5 生成 workflow 文件

Step 3: 推送到 GitHub

3.1 检查当前项目 Git 状态

3.2 根据状态执行对应操作

场景 A：项目未在 GitHub 上

场景 B：项目已在 GitHub 上但不在 secure-artifacts 组织中

场景 C：项目已在 secure-artifacts 组织下

3.3 记录项目 URL

Step 4: 触发 CI 构建 + 更新 README

4.1 创建 Tag 并推送

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

4.3 更新 README.md

Step 5: 提交项目审核

5.1 打开审核页面

5.2 填写表单

5.3 通知用户完成提交

Step 6: 通知管理员

Step 7: 等待审核并生成报告

7.1 等待审核

7.2 生成完整报告

常见问题

Q: GitHub Actions 构建失败怎么办？

Q: 项目审核不通过怎么办？

Q: permissions 中的三个权限分别是什么作用？

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