⚡

asc工作流Skill asc-workflow

asc工作流是一个CLI工具技能，用于在代码仓库中定义、验证和运行多步骤自动化工作流。它支持条件执行、子工作流调用、钩子函数和运行时参数，适用于CI/CD管道、发布流程和DevOps自动化。关键词：自动化工作流、CLI工具、CI/CD、验证、子工作流、条件执行。

DevOps 0 次安装 0 次浏览 更新于 3/13/2026

名称: asc-workflow 描述: 使用 asc workflow 和 .asc/workflow.json 定义、验证和运行仓库本地多步骤自动化工作流。适用于从车道工具迁移、连接CI管道或编排可重复的 asc + shell发布流程，支持钩子、条件执行和子工作流。

asc workflow

当您需要在CLI内部使用车道式自动化时，请使用此技能，通过：

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

此功能最适合确定性自动化，它驻留在您的仓库中，可在PR中审查，并且可以在本地和CI中以相同方式运行。

命令发现

  • 始终使用 --help 来确认标志和子命令：
    • asc workflow --help
    • asc workflow run --help
    • asc workflow validate --help
    • asc workflow list --help

端到端流程

  1. 编写 .asc/workflow.json
  2. 验证结构和引用：
    • asc workflow validate
  3. 发现可用工作流：
    • asc workflow list
    • asc workflow list --all (包括私有助手)
  4. 预览执行而不产生副作用：
    • asc workflow run --dry-run beta
  5. 使用运行时参数执行：
    • asc workflow run beta BUILD_ID:123456789 GROUP_ID:abcdef

文件位置和格式

  • 默认路径：.asc/workflow.json
  • 覆盖路径：asc workflow run --file ./path/to/workflow.json <名称>
  • 支持JSONC注释 (// 和 /* ... */)

输出和CI合同

  • stdout: 结构化JSON结果 (status, steps, 持续时间)
  • stderr: 步骤命令输出、钩子输出、干运行预览
  • asc workflow validate 始终打印JSON并在无效时返回非零值

这支持机器安全检查：

asc workflow validate | jq -e '.valid == true'
asc workflow run beta BUILD_ID:123 GROUP_ID:xyz | jq -e '.status == "ok"'

架构（功能支持的内容）

顶级键：

  • env: 全局默认值
  • before_all: 在步骤之前运行一次的命令
  • after_all: 在步骤成功后运行一次的命令
  • error: 当任何失败发生时运行的命令
  • workflows: 命名工作流映射

工作流键：

  • description
  • private (不可直接运行)
  • env
  • steps

步骤形式：

  • 字符串简写："echo hello" -> 运行步骤
  • 对象包含：
    • run: shell命令
    • workflow: 调用子工作流
    • name: 报告标签
    • if: 条件变量名
    • with: 仅用于工作流调用步骤的环境覆盖

运行时参数 (KEY:VALUE / KEY=VALUE)

  • asc workflow run <名称> [KEY:VALUE ...] 支持两种分隔符：
    • VERSION:2.1.0
    • VERSION=2.1.0
  • 如果两种分隔符都存在，第一个获胜。
  • 重复键采用最后写入胜出。
  • 在步骤命令中，通过shell扩展引用参数 ($VAR)。
  • 避免在 .asc/workflow.json 中放置机密；通过CI机密/环境传递它们。

运行后标志

asc workflow run 在工作流名称后也接受核心标志：

  • --dry-run
  • --pretty
  • --file

示例：

  • asc workflow run beta --dry-run
  • asc workflow run beta --file .asc/workflow.json BUILD_ID:123

执行语义

  • before_all 在步骤执行前运行一次
  • after_all 仅在步骤成功时运行
  • error 在失败时运行（步骤失败、前/后钩子失败）
  • 子工作流作为调用步骤的一部分内联执行
  • 最大子工作流嵌套深度为16

环境优先级

主工作流运行：

  • definition.env < workflow.env < CLI参数

子工作流调用步骤 ("workflow": "...", "with": {...})：

  • 子工作流 env 默认值
  • 调用者环境（包括CLI参数）覆盖
  • 步骤 with 覆盖所有

子工作流和私有工作流

  • 使用 "workflow": "<名称>" 调用助手工作流。
  • 使用 "private": true 用于仅助手工作流。
  • 私有工作流：
    • 不能直接运行
    • 可以被其他工作流调用
    • 在 asc workflow list 中隐藏，除非使用 --all
  • 验证捕获未知工作流引用和循环引用。

条件 (if)

  • 在步骤上添加 "if": "VAR_NAME"。
  • 步骤仅在 VAR_NAME 为真时运行。
  • 真值：1, true, yes, y, on (不区分大小写)。
  • if 查找的解析顺序：
    1. 合并的工作流环境/参数
    2. os.Getenv(VAR_NAME)

干运行行为

  • asc workflow run --dry-run <名称> 不执行命令。
  • 它将预览打印到 stderr。
  • 干运行显示原始命令（无环境扩展），有助于避免预览中的机密泄漏。

Shell行为

  • 运行步骤在bash可用时使用 bash -o pipefail -c。
  • 回退是当bash不可用时使用 sh -c。
  • 因此，管道在大多数CI shell中当bash存在时正确失败。

实用编写规则

  • 将工作流文件保持在版本控制中。
  • 在可能的情况下，在步骤命令中使用ID以实现确定性自动化。
  • 在步骤内部的破坏性 asc 操作中使用 --confirm。
  • 先验证，然后干运行，再真实运行。
  • 保持钩子轻量级并注意副作用。
{
  "env": {
    "APP_ID": "123456789",
    "VERSION": "1.0.0"
  },
  "before_all": "asc auth status",
  "after_all": "echo workflow_done",
  "error": "echo workflow_failed",
  "workflows": {
    "beta": {
      "description": "将构建分发到TestFlight组并通知",
      "env": {
        "GROUP_ID": ""
      },
      "steps": [
        {
          "name": "list_builds",
          "run": "asc builds list --app $APP_ID --sort -uploadedDate --limit 5"
        },
        {
          "name": "list_groups",
          "run": "asc testflight beta-groups list --app $APP_ID --limit 20"
        },
        {
          "name": "add_build_to_group",
          "if": "BUILD_ID",
          "run": "asc builds add-groups --build $BUILD_ID --group $GROUP_ID"
        },
        {
          "name": "notify",
          "if": "SLACK_WEBHOOK",
          "run": "echo sent_release_notice"
        }
      ]
    },
    "release": {
      "description": "提交版本进行App Store审核",
      "steps": [
        {
          "workflow": "sync-metadata",
          "with": {
            "METADATA_DIR": "./metadata"
          }
        },
        {
          "name": "submit",
          "run": "asc submit create --app $APP_ID --version $VERSION --build $BUILD_ID --confirm"
        }
      ]
    },
    "sync-metadata": {
      "private": true,
      "description": "私有助手工作流（仅通过工作流步骤可调用）",
      "steps": [
        {
          "name": "migrate_validate",
          "run": "echo METADATA_DIR_is_$METADATA_DIR"
        }
      ]
    }
  }
}

有用调用

# 验证并在无效文件时使CI失败
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"'