AI Skills
asc-workflow

asc-workflow

热门

借助当前的 `asc workflow` 和 `.asc/workflow.json`，在项目本地定义、校验、运行、恢复及审计多步骤自动化流程，支持步骤输出传递以及安全的发布与 TestFlight 工作流。

952Star
51Fork
更新于 2026/8/5
获取 Skill源代码

相关 Skills

api-security-best-practices4.3万security-review3.7万capability-evolver8962
SKILL.md
只读
名称
asc-workflow
描述

借助当前的 `asc workflow` 和 `.asc/workflow.json`，在项目本地定义、校验、运行、恢复及审计多步骤自动化流程，支持步骤输出传递以及安全的发布与 TestFlight 工作流。

asc workflow

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

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

工作流文件是保存在代码库本地的自动化配置文件。它们会运行可信的 shell 命令，将每步的输出实时流式传输至 stderr，并保持 stdout 为机器可读的 JSON 格式。

查看命令说明

始终使用以下命令核对参数与 Flag：

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. 预览执行（试运行）：
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 进行恢复：
asc workflow run release --resume "release-20260312T120000Z-deadbeef"

使用 --resume 时无需传入额外的 KEY:VALUE 参数；系统会自动复用保存的工作流文件、初始参数以及持久化的输出。

文件路径与格式

  • 默认路径：.asc/workflow.json
  • 自定义覆盖路径：asc workflow run --file ./path/to/workflow.json <name>
  • 支持带有注释的 JSON（JSONC）。
  • 顶层 Hook 挂钩：before_all、after_all、error
  • Workflow key 字段：description、private、env、steps
  • 步骤形式（Step forms）：
    • 简写字符串："echo hello"
    • run shell 命令
    • workflow 子工作流调用
    • name 步骤标签名称
    • if 条件变量名
    • with 为子工作流调用步骤指定的环境变量覆盖
    • outputs 映射表，用于从具名 run 步骤的 JSON stdout 中提取数据

输出传递（Outputs）

run 步骤可以声明输出。被调用的命令必须在 stdout 上输出 JSON 格式，因此对于产生输出的 asc 命令，请务必加上 --output json。

输出引用方式：

${steps.step_name.OUTPUT_NAME}

规则：

  • 声明了 outputs 的步骤必须具有符合引用规范的 name。
  • 仅允许在 run 步骤上定义 outputs，子工作流调用步骤不支持。
  • 在同一个运行图（Run graph）中可同时执行的工作流之间，产生输出的步骤名称必须保持唯一。
  • 持久化的输出会保存在工作流运行状态中，请勿将敏感信息（Secrets）映射到 outputs 中。

运行时参数

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

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

重复传入相同 Key 时，以后者为准（Last-write-wins）。在 shell 命令中，可以通过 Shell 变量展开方式引用参数，例如 $VERSION。

环境变量优先级

主工作流运行：

definition.env < workflow.env < CLI 参数

带有 with 的子工作流调用：

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

条件判断

在步骤中添加 "if": "VAR_NAME"。当值为 1、true、yes、y 和 on（不区分大小写）时视为真值（Truthy）。查找时会优先检查合并后的工作流环境变量/参数，然后再检查进程环境变量。

工作流示例

{
  "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": "Resolve the latest build and distribute it to 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": "Validate, stage, and submit an App Store version",
      "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": "High-level upload plus App Store review submission",
      "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；仅运行可信的工作流文件。
  • 避免运行包含敏感信息（Secrets）且来自不可信 PR 的工作流。
  • 将工作流文件纳入版本控制（Git 追踪）。
  • 先校验（validate），再试运行（dry-run），最后才正式执行。
  • 针对修改/变更类的步骤，使用明确的 ID 和 --confirm 标志。
  • 使用 asc validate、asc release stage、asc review submit 和 asc publish appstore；请勿使用已被废弃或移除的提交命令。