AI Skills
asc-workflow

asc-workflow

热门

通过当前的 `asc workflow` 命令与 `.asc/workflow.json` 配置文件，定义、校验、运行、恢复及审计仓库本地的多步骤自动化流程，支持步骤输出传递以及安全的 App Store 发布/TestFlight 工作流。

948Star
50Fork
更新于 2026/7/31
获取 Skill源代码

相关 Skills

github-actions-hardening3.9万dnanexus-integration4.2万security-and-hardening7.7万
SKILL.md
只读
名称
asc-workflow
描述

通过当前的 `asc workflow` 命令与 `.asc/workflow.json` 配置文件，定义、校验、运行、恢复及审计仓库本地的多步骤自动化流程，支持步骤输出传递以及安全的 App Store 发布/TestFlight 工作流。

asc workflow

当需要在 CLI 中进行流水线式（lane-style）自动化操作时使用此 Skill，相关命令包括：

  • asc workflow validate
  • asc workflow list
  • asc workflow run

Workflow 是保存在仓库本地的自动化配置文件。它们会运行可信的 shell 命令，将步骤执行过程实时输出到 stderr，并将 stdout 保持为机器可读的 JSON 格式。

查看命令用法

在执行前，建议先通过 --help 参数确认各命令支持的选项：

asc workflow --help
asc workflow validate --help
asc workflow list --help
asc workflow run --help

端到端完整流程

  1. 编写 .asc/workflow.json 文件。
  2. 校验文件语法结构与引用：
asc workflow validate
  1. 查看可用的公共工作流：
asc workflow list
asc workflow list --all
  1. 预演执行（Dry-run）：
asc workflow run --dry-run beta BUILD_ID:123456789 GROUP_ID:abcdef
  1. 正式执行：
asc workflow run beta BUILD_ID:123456789 GROUP_ID:abcdef
  1. 如果由于可恢复的原因导致运行失败，可以使用 JSON 结果中的运行 ID（run ID）继续恢复执行：
asc workflow run release --resume "release-20260312T120000Z-deadbeef"

注意：使用 --resume 时无需重复传递 KEY:VALUE 参数，系统会自动复用已保存的工作流文件、参数及已持久化的输出数据。

文件位置与格式

  • 默认路径：.asc/workflow.json
  • 指定路径：asc workflow run --file ./path/to/workflow.json <name>
  • 支持 JSONC 注释。
  • 顶层 Hook 钩子：before_all、after_all、error
  • 工作流字段：description、private、env、steps
  • 步骤（Step）书写形式：
    • 简写字符串形式："echo hello"
    • run：执行 shell 命令
    • workflow：调用子工作流（sub-workflow）
    • name：步骤标签/名称
    • if：根据变量名进行条件判断
    • with：为子工作流调用覆盖环境变量
    • outputs：用于从指定 run 步骤的 JSON stdout 中提取输出的映射配置

输出变量（Outputs）

run 步骤可以声明输出变量。由于命令必须在 stdout 输出 JSON 数据，因此在调用会产生输出的 asc 命令时请加上 --output json 参数。

引用输出变量的语法格式：

${steps.step_name.OUTPUT_NAME}

规则：

  • 声明了 outputs 的步骤必须拥有符合引用规范的唯一 name。
  • 仅 run 步骤支持设置 outputs，子工作流调用步骤（workflow-call）不支持。
  • 在同一个运行图（run graph）中可能同时执行的工作流之间，产生输出的步骤名称（name）必须保持唯一。
  • 持久化的输出数据会保存在工作流运行状态中，请勿将敏感密钥（Secrets）映射到 outputs 中。

运行时参数（Runtime params）

asc workflow run <name> [KEY:VALUE ...] 同时支持以下两种分隔符：

asc workflow run beta VERSION:2.1.0
asc workflow run beta VERSION=2.1.0

如果重复传递相同的键，以最后传入的值为准（last-write-wins）。在 shell 命令中，可以通过 shell 变量展开形式（如 $VERSION）来引用这些参数。

环境变量优先级（Env precedence）

主工作流执行：

definition.env < workflow.env < CLI 参数

使用 with 调用子工作流：

子工作流 env < 调用方 env 与参数 < 步骤中的 with

条件判断（Conditionals）

在步骤中添加 "if": "VAR_NAME"。不区分大小写的前提下，真值（Truthy）包括 1、true、yes、y 和 on。变量查找顺序为：优先检查合并后的工作流环境变量/参数，其次检查系统进程环境变量。

工作流配置示例

{
  "env": {
    "APP_ID": "123456789",
    "VERSION": "1.0.0",
    "GROUP_ID": ""
  },
  "before_all": "asc auth status",
  "after_all": "echo workflow_done",
  "error": "echo workflow_failed",
  "workflows": {
    "beta": {
      "description": "获取最新构建版本并分发至 TestFlight",
      "steps": [
        {
          "name": "resolve_build",
          "run": "asc builds info --app $APP_ID --latest --platform IOS --output json",
          "outputs": {
            "BUILD_ID": "$.data.id"
          }
        },
        {
          "name": "list_groups",
          "run": "asc testflight groups list --app $APP_ID --limit 20 --output json"
        },
        {
          "name": "add_build_to_group",
          "if": "GROUP_ID",
          "run": "asc builds add-groups --build-id ${steps.resolve_build.BUILD_ID} --group $GROUP_ID"
        }
      ]
    },
    "release": {
      "description": "校验、预发布并提交 App Store 版本",
      "steps": [
        {
          "name": "validate",
          "run": "asc validate --app $APP_ID --version $VERSION --platform IOS --output json"
        },
        {
          "name": "stage",
          "run": "asc release stage --app $APP_ID --version $VERSION --build $BUILD_ID --metadata-dir ./metadata/version/$VERSION --confirm --output json"
        },
        {
          "name": "submit",
          "if": "SUBMIT_FOR_REVIEW",
          "run": "asc review submit --app $APP_ID --version $VERSION --build $BUILD_ID --confirm --output json"
        }
      ]
    },
    "publish-appstore": {
      "description": "高阶上传及 App Store 审核提交",
      "steps": [
        {
          "name": "publish",
          "run": "asc publish appstore --app $APP_ID --ipa ./build/MyApp.ipa --version $VERSION --wait --submit --confirm --output json"
        }
      ]
    }
  }
}

常用命令示例

asc workflow validate | jq -e '.valid == true'
asc workflow list --pretty
asc workflow list --all --pretty
asc workflow run --dry-run beta BUILD_ID:123 GROUP_ID:grp_abc
asc workflow run beta BUILD_ID:123 GROUP_ID:grp_abc | jq -e '.status == "ok"'
asc workflow run release BUILD_ID:123 SUBMIT_FOR_REVIEW:true
asc workflow run release --resume "release-20260312T120000Z-deadbeef"

安全守则

  • 将 .asc/workflow.json 视作代码对待，仅运行可信的工作流文件。
  • 避免在包含敏感密钥的环境中运行来自不可信 PR 的工作流。
  • 务必将工作流文件纳入版本控制。
  • 遵循“先校验（validate）、再预演（dry-run）、最后运行”的步骤。
  • 对于涉及修改/变动的步骤，请使用显式的 ID 和 --confirm 参数。
  • 请使用 asc validate、asc release stage、asc review submit 以及 asc publish appstore 命令；切勿使用已废弃的提交命令。