asc-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ASC Workflows (lane-style automation)

ASC Workflows（流水线式自动化）

Use this skill when you need to create or run

.asc/workflow.json

workflows via:

```
asc workflow run
```
```
asc workflow validate
```
```
asc workflow list
```

Workflows are a lane-style "lanes" replacement: named, multi-step automation sequences that compose existing

asc

commands and normal shell commands.

当你需要通过以下命令创建或运行

.asc/workflow.json

工作流时，可以使用该技能：

```
asc workflow run
```
```
asc workflow validate
```
```
asc workflow list
```

工作流是流水线式“lanes”的替代方案：即命名的多步骤自动化序列，可组合现有的

asc

命令和常规Shell命令。

Command discovery

命令发现

Always use

--help

to confirm flags and subcommands:

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

始终使用

--help

来确认标志和子命令：

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

Key commands (typical flow)

核心命令（典型流程）

Validate the workflow file (CI gate):
- ```
asc workflow validate
```
Dry-run a workflow (no side effects):
- ```
asc workflow run --dry-run beta
```

Run the workflow with runtime parameters:

asc workflow run beta BUILD_ID:123456789 GROUP_ID:abcdef

List available workflows (for discovery):
- ```
asc workflow list
```
- Include private workflows:
```
asc workflow list --all
```

验证工作流文件（CI关卡）：
- ```
asc workflow validate
```
试运行工作流（无副作用）：
- ```
asc workflow run --dry-run beta
```

使用运行时参数运行工作流：

asc workflow run beta BUILD_ID:123456789 GROUP_ID:abcdef

列出可用工作流（用于发现）：
- ```
asc workflow list
```
- 包含私有工作流：
```
asc workflow list --all
```

File location and format

文件位置与格式

Default file path:
```
.asc/workflow.json
```
(repo-local; commit it with your code).
The workflow file supports JSONC comments (
```
//
```
and
```
/* */
```
).

默认文件路径：
```
.asc/workflow.json
```
（仓库本地；随代码一起提交）。
工作流文件支持JSONC注释（
```
//
```
和
```
/* */
```
）。

Output contract (agent-friendly)

输出约定（Agent友好型）

stdout: JSON-only (structured result)
stderr: step/hook command output and dry-run previews

This makes it safe to do:

bash

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

stdout：仅JSON格式（结构化结果）
stderr：步骤/钩子命令输出和试运行预览

这使得以下操作是安全的：

bash

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

Runtime params (KEY:VALUE / KEY=VALUE)

运行时参数（KEY:VALUE / KEY=VALUE）

asc workflow run <name> [KEY:VALUE ...]

supports both separators:

```
VERSION:2.1.0
```
```
VERSION=2.1.0
```

In steps, reference params via
```
$VAR
```
(shell expansion).
Avoid putting secrets in
```
.asc/workflow.json
```
; pass them via CI secrets/env.

asc workflow run <name> [KEY:VALUE ...]

支持两种分隔符：

```
VERSION:2.1.0
```
```
VERSION=2.1.0
```

在步骤中，通过
```
$VAR
```
引用参数（Shell展开）。
不要在
```
.asc/workflow.json
```
中存放密钥；请通过CI密钥/环境变量传递。

Hooks

钩子（Hooks）

Workflows support definition-level hooks:

```
before_all
```
: runs once before any steps
```
after_all
```
: runs once after all steps (only if steps succeeded)
```
error
```
: runs on any failure

When hook output matters, keep hooks simple and write their logs to stderr.

工作流支持定义级别的钩子：

```
before_all
```
：在所有步骤执行前运行一次
```
after_all
```
：在所有步骤成功完成后运行一次
```
error
```
：在任何失败时运行

当钩子输出很重要时，保持钩子简单，并将其日志写入stderr。

Conditionals (

if

)

条件判断（

if

）

Add
```
"if": "VAR_NAME"
```
to a step to skip it when
```
VAR_NAME
```
is falsy.
The conditional checks workflow env/params first, and then falls back to
```
os.Getenv(VAR_NAME)
```
.
Truthy values:
```
1
```
,
```
true
```
,
```
yes
```
,
```
y
```
,
```
on
```
(case-insensitive).

为步骤添加
```
"if": "VAR_NAME"
```
，当
```
VAR_NAME
```
为假值时跳过该步骤。
条件判断优先检查工作流环境/参数，然后回退到
```
os.Getenv(VAR_NAME)
```
。
真值包括：
```
1
```
、
```
true
```
、
```
yes
```
、
```
y
```
、
```
on
```
（不区分大小写）。

Sub-workflows and private workflows

子工作流与私有工作流

A step can call another workflow via
```
"workflow": "<name>"
```
.
```
"with"
```
env overrides are only valid on workflow steps (not run steps).
```
"private": true
```
workflows:
- cannot be run directly from the CLI
- can be called by other workflows as sub-workflows
- are hidden from
```
asc workflow list
```
  unless
```
--all
```
  is used

步骤可以通过
```
"workflow": "<name>"
```
调用另一个工作流。
```
"with"
```
环境覆盖仅对工作流步骤有效（对运行步骤无效）。
```
"private": true
```
的工作流：
- 无法从CLI直接运行
- 可被其他工作流作为子工作流调用
- 除非使用
```
--all
```
  参数，否则不会在
```
asc workflow list
```
  中显示

Recommended authoring approach (enterprise-friendly)

推荐的编写方法（企业友好型）

Keep steps deterministic and explicit (prefer IDs where possible).
Validate early (
```
asc workflow validate
```
) and keep the file in version control.
Start with
```
--dry-run
```
before enabling real runs in CI.
Use existing
```
asc
```
commands for the actual work (build upload, TestFlight distribution, submission).
Use
```
--confirm
```
on destructive operations inside steps; workflows should never add interactive prompts.

保持步骤确定性和明确性（尽可能使用ID）。
尽早验证（
```
asc workflow validate
```
）并将文件纳入版本控制。
在CI中启用实际运行前，先使用
```
--dry-run
```
试运行。
使用现有的
```
asc
```
命令完成实际工作（构建上传、TestFlight分发、提交审核）。
在步骤中的破坏性操作上使用
```
--confirm
```
；工作流不应添加交互式提示。

Example

.asc/workflow.json

template

示例

.asc/workflow.json

模板

This is a practical starting point for lane migration; adapt step commands to your org.

json

{
  "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": "Distribute a build to a TestFlight group",
      "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"
        }
      ]
    },
    "release": {
      "description": "Submit a version for App Store review",
      "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": "Private helper workflow (callable only via workflow steps)",
      "steps": [
        {
          "name": "migrate_validate",
          "run": "echo METADATA_DIR_is_$METADATA_DIR"
        }
      ]
    }
  }
}

这是一个用于流水线迁移的实用起点；可根据你的组织需求调整步骤命令。

json

{
  "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": "Distribute a build to a TestFlight group",
      "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"
        }
      ]
    },
    "release": {
      "description": "Submit a version for App Store review",
      "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": "Private helper workflow (callable only via workflow steps)",
      "steps": [
        {
          "name": "migrate_validate",
          "run": "echo METADATA_DIR_is_$METADATA_DIR"
        }
      ]
    }
  }
}

asc-workflow

Original

Translation

ASC Workflows (lane-style automation)

ASC Workflows（流水线式自动化）

Command discovery

命令发现

Key commands (typical flow)

核心命令（典型流程）

File location and format

文件位置与格式

Output contract (agent-friendly)

输出约定（Agent友好型）

Runtime params (KEY:VALUE / KEY=VALUE)

运行时参数（KEY:VALUE / KEY=VALUE）

Hooks

钩子（Hooks）

Conditionals (
`if`
)

条件判断（
`if`
）

Sub-workflows and private workflows

子工作流与私有工作流

Recommended authoring approach (enterprise-friendly)

推荐的编写方法（企业友好型）

Example
`.asc/workflow.json`
template

示例
`.asc/workflow.json`
模板

asc-workflow

Original

Translation

ASC Workflows (lane-style automation)

ASC Workflows（流水线式自动化）

Command discovery

命令发现

Key commands (typical flow)

核心命令（典型流程）

File location and format

文件位置与格式

Output contract (agent-friendly)

输出约定（Agent友好型）

Runtime params (KEY:VALUE / KEY=VALUE)

运行时参数（KEY:VALUE / KEY=VALUE）

Hooks

钩子（Hooks）

Conditionals (if)

条件判断（if）

Sub-workflows and private workflows

子工作流与私有工作流

Recommended authoring approach (enterprise-friendly)

推荐的编写方法（企业友好型）

Example .asc/workflow.json template

示例.asc/workflow.json模板

Conditionals (
`if`
)

条件判断（
`if`
）

Example
`.asc/workflow.json`
template

示例
`.asc/workflow.json`
模板