AI Skills
asc-shots-pipeline

asc-shots-pipeline

热门

编排 iOS 截图自动化流程：使用 xcodebuild/simctl 进行构建与运行、AXe 执行 UI 操作、JSON 配置文件与执行计划（plan）、基于 Koubou 的带壳合成（`asc screenshots frame`）以及截图上传（`asc screenshots upload`）。当用户需要自动截屏、AXe 驱动的模拟器操作流程、带壳合成或“截屏到上传”完整流水线时使用此 Skill。

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

相关 Skills

tiledbvcf4.2万geofeed-tuner3.8万senior-architect4.5万
SKILL.md
只读
名称
asc-shots-pipeline
描述

编排 iOS 截图自动化流程：使用 xcodebuild/simctl 进行构建与运行、AXe 执行 UI 操作、JSON 配置文件与执行计划（plan）、基于 Koubou 的带壳合成（`asc screenshots frame`）以及截图上传（`asc screenshots upload`）。当用户需要自动截屏、AXe 驱动的模拟器操作流程、带壳合成或“截屏到上传”完整流水线时使用此 Skill。

asc screenshots pipeline (xcodebuild -> AXe -> frame -> asc)

当需要由 Agent 驱动截图工作流（通过 Xcode CLI 工具构建并启动 App、用 AXe 驱动 UI 交互，并使用 asc 批量上传截图）时，使用此 Skill。

当前功能范围

  • 目前已实现：构建/运行、AXe 计划驱动截屏、带壳合成（framing）以及上传。
  • 设备探索功能内置于 asc screenshots list-frame-devices 中。
  • 本地截图自动化命令在 asc cli 中仍处于实验阶段。
  • 带壳合成固定使用 Koubou 0.18.1，以保证输出效果一致可预测。
  • 反馈与 Issue 提交：https://github.com/rorkai/App-Store-Connect-CLI/issues/new/choose

默认路径与配置

  • 配置文件：.asc/shots.settings.json
  • 截图计划：.asc/screenshots.json
  • 原始截图目录：./screenshots/raw
  • 带壳截图目录：./screenshots/framed
  • 默认带壳设备：iphone-air

1) 首先创建配置 JSON 文件

创建或更新 .asc/shots.settings.json：

{
  "version": 1,
  "app": {
    "bundle_id": "com.example.app",
    "project": "MyApp.xcodeproj",
    "scheme": "MyApp",
    "simulator_udid": "booted"
  },
  "paths": {
    "plan": ".asc/screenshots.json",
    "raw_dir": "./screenshots/raw",
    "framed_dir": "./screenshots/framed"
  },
  "pipeline": {
    "frame_enabled": true,
    "upload_enabled": false
  },
  "upload": {
    "version_localization_id": "",
    "device_type": "IPHONE_65",
    "source_dir": "./screenshots/framed"
  }
}

如果故意跳过带壳合成步骤，请设置：

  • "frame_enabled": false
  • "upload.source_dir": "./screenshots/raw"

2) 在模拟器上构建并运行 App

使用 Xcode CLI 进行构建、安装与启动：

xcrun simctl boot "$UDID" || true

xcodebuild \
  -project "MyApp.xcodeproj" \
  -scheme "MyApp" \
  -configuration Debug \
  -destination "platform=iOS Simulator,id=$UDID" \
  -derivedDataPath ".build/DerivedData" \
  build

xcrun simctl install "$UDID" ".build/DerivedData/Build/Products/Debug-iphonesimulator/MyApp.app"
xcrun simctl launch "$UDID" "com.example.app"

如果 App 的 bundle 路径与默认路径不一致，可使用 xcodebuild -showBuildSettings 查看实际路径。

3) 使用 AXe（或 asc screenshots run）捕获截图

优先推荐基于执行计划（plan）驱动截图捕获：

asc screenshots run --plan ".asc/screenshots.json" --udid "$UDID" --output json

在编写截图计划时常用的 AXe 原语（操作指令）：

axe describe-ui --udid "$UDID"
axe tap --id "search_field" --udid "$UDID"
axe type "wwdc" --udid "$UDID"
axe screenshot --output "./screenshots/raw/home.png" --udid "$UDID"

.asc/screenshots.json 最小示例：

{
  "version": 1,
  "app": {
    "bundle_id": "com.example.app",
    "udid": "booted",
    "output_dir": "./screenshots/raw"
  },
  "steps": [
    { "action": "launch" },
    { "action": "wait", "duration_ms": 800 },
    { "action": "screenshot", "name": "home" }
  ]
}

4) 使用 asc screenshots frame 给截图合成设备外壳

asc CLI 将带壳合成固化为 Koubou 0.18.1。
在运行带壳合成步骤前，请先安装并核验版本：

pip install koubou==0.18.1
kou --version  # 预期输出 0.18.1
# 如果 Koubou 提示缺少设备外壳素材，请在联网环境下运行一次：
kou setup-frames

先列出支持的设备型号参数：

asc screenshots list-frame-devices --output json

给单张截图加壳（默认使用 iphone-air）：

asc screenshots frame \
  --input "./screenshots/raw/home.png" \
  --output-dir "./screenshots/framed" \
  --device "iphone-air" \
  --output json

支持的 --device 取值：

  • iphone-air（默认）
  • iphone-17-pro
  • iphone-17-pro-max
  • iphone-16e
  • iphone-17
  • mac

5) 使用 asc 上传截图

在上传之前生成并预览审核产物：

asc screenshots review-generate --framed-dir "./screenshots/framed" --output-dir "./screenshots/review"
asc screenshots review-open --output-dir "./screenshots/review"
asc screenshots review-approve --all-ready --output-dir "./screenshots/review"

对于已审核的多语言截图集，推荐使用 plan/apply 流程，以便在上传前将线上已有的截图数量纳入考量：

asc screenshots plan --app "APP_ID" --version "1.2.3" --review-output-dir "./screenshots/review" --output json
asc screenshots apply --app "APP_ID" --version "1.2.3" --review-output-dir "./screenshots/review" --confirm --output json

从配置的源目录上传（启用带壳合成时默认为 ./screenshots/framed）：

asc screenshots upload \
  --version-localization "LOC_ID" \
  --path "./screenshots/framed" \
  --device-type "IPHONE_65" \
  --output json

必要时，可在上传前列出或校验截图：

asc screenshots sizes --output table
asc screenshots list --version-localization "LOC_ID" --output table

Agent 行为规范

  • 在运行命令前，务必通过 --help 确认具体的参数选项。
  • 定期通过 asc screenshots --help 重新核对命令路径，因为截图相关的命令迭代更新很快。
  • 保持输出的确定性：对于机器处理步骤，默认使用 JSON 格式。
  • 在选择外壳设备之前，优先使用 asc screenshots list-frame-devices --output json 查询列表。
  • 上传前确保截图文件确实存在。
  • 使用显式的长参数选项（如 --app、--output、--version-localization 等）。
  • 将本地截图自动化视为实验性功能，并在给用户的交接说明中明确指出。
  • 对于经过审核的批量截图，当需要根据线上现有截图数量进行追加限制保护时，请使用 asc screenshots plan / asc screenshots apply。
  • 如果带壳合成因版本错误失败，请重新安装指定版本的 Koubou：pip install koubou==0.18.1。
  • 如果带壳合成因缺少设备外壳素材失败，请在联网环境下运行一次 kou setup-frames。

6) 多语言截图捕获（可选）

请勿使用 xcrun simctl launch ... -e AppleLanguages 来实现多语言切换。
-e 属于环境变量传参模式，无法稳定可靠地切换 App 语言。

对于本流水线，建议按 UDID 为每个模拟器设置全局语言环境。这种方式适配 asc screenshots capture，后者会在内部重新启动 App。

# 将每种语言映射到专属的模拟器 UDID。
# （提前使用 `xcrun simctl create` 创建好这些模拟器。）
declare -A LOCALE_UDID=(
  ["en-US"]="UDID_EN_US"
  ["de-DE"]="UDID_DE_DE"
  ["fr-FR"]="UDID_FR_FR"
  ["ja-JP"]="UDID_JA_JP"
)

set_simulator_locale() {
  local UDID="$1"
  local LOCALE="$2"            # 例如 de-DE
  local LANG="${LOCALE%%-*}"   # de
  local APPLE_LOCALE="${LOCALE/-/_}" # de_DE

  xcrun simctl boot "$UDID" || true
  xcrun simctl spawn "$UDID" defaults write NSGlobalDomain AppleLanguages -array "$LANG"
  xcrun simctl spawn "$UDID" defaults write NSGlobalDomain AppleLocale -string "$APPLE_LOCALE"
}

for LOCALE in "${!LOCALE_UDID[@]}"; do
  UDID="${LOCALE_UDID[$LOCALE]}"
  echo "Capturing $LOCALE on $UDID..."
  set_simulator_locale "$UDID" "$LOCALE"

  xcrun simctl terminate "$UDID" "com.example.app" || true
  asc screenshots capture \
    --bundle-id "com.example.app" \
    --name "home" \
    --udid "$UDID" \
    --output-dir "./screenshots/raw/$LOCALE" \
    --output json
done

如果手动启动 App（而非使用 asc screenshots capture），请使用 App 启动参数：

xcrun simctl launch "$UDID" "com.example.app" -AppleLanguages "(de)" -AppleLocale "de_DE"

7) 并行执行提升速度

按模拟器 UDID 并行处理每个语言环境：

#!/bin/bash
# parallel-capture.sh

declare -A LOCALE_UDID=(
  ["en-US"]="UDID_EN_US"
  ["de-DE"]="UDID_DE_DE"
  ["fr-FR"]="UDID_FR_FR"
  ["ja-JP"]="UDID_JA_JP"
)

capture_locale() {
  local LOCALE="$1"
  local UDID="$2"
  local LANG="${LOCALE%%-*}"
  local APPLE_LOCALE="${LOCALE/-/_}"

  echo "Starting $LOCALE on $UDID"
  xcrun simctl boot "$UDID" || true
  xcrun simctl spawn "$UDID" defaults write NSGlobalDomain AppleLanguages -array "$LANG"
  xcrun simctl spawn "$UDID" defaults write NSGlobalDomain AppleLocale -string "$APPLE_LOCALE"
  xcrun simctl terminate "$UDID" "com.example.app" || true

  asc screenshots capture \
    --bundle-id "com.example.app" \
    --name "home" \
    --udid "$UDID" \
    --output-dir "./screenshots/raw/$LOCALE" \
    --output json

  echo "Completed $LOCALE"
}

for LOCALE in "${!LOCALE_UDID[@]}"; do
  capture_locale "$LOCALE" "${LOCALE_UDID[$LOCALE]}" &
done

wait
echo "All captures done. Now framing..."

或者对 locale:udid 组合使用 xargs：

printf "%s\n" \
  "en-US:UDID_EN_US" \
  "de-DE:UDID_DE_DE" \
  "fr-FR:UDID_FR_FR" \
  "ja-JP:UDID_JA_JP" | xargs -P 4 -I {} bash -c '
    PAIR="{}"
    LOCALE="${PAIR%%:*}"
    UDID="${PAIR##*:}"
    LANG="${LOCALE%%-*}"
    APPLE_LOCALE="${LOCALE/-/_}"
    xcrun simctl boot "$UDID" || true
    xcrun simctl spawn "$UDID" defaults write NSGlobalDomain AppleLanguages -array "$LANG"
    xcrun simctl spawn "$UDID" defaults write NSGlobalDomain AppleLocale -string "$APPLE_LOCALE"
    xcrun simctl terminate "$UDID" "com.example.app" || true
    asc screenshots capture --bundle-id "com.example.app" --name "home" --udid "$UDID" --output-dir "./screenshots/raw/$LOCALE" --output json
  '

8) 完整的多语言流水线示例

#!/bin/bash
# full-pipeline-multi-locale.sh

declare -A LOCALE_UDID=(
  ["en-US"]="UDID_EN_US"
  ["de-DE"]="UDID_DE_DE"
  ["fr-FR"]="UDID_FR_FR"
  ["es-ES"]="UDID_ES_ES"
  ["ja-JP"]="UDID_JA_JP"
)

DEVICE="iphone-air"
RAW_DIR="./screenshots/raw"
FRAMED_DIR="./screenshots/framed"

# 步骤 1：按模拟器语言环境默认值进行并行捕获
for LOCALE in "${!LOCALE_UDID[@]}"; do
  (
    UDID="${LOCALE_UDID[$LOCALE]}"
    LANG="${LOCALE%%-*}"
    APPLE_LOCALE="${LOCALE/-/_}"

    xcrun simctl boot "$UDID" || true
    xcrun simctl spawn "$UDID" defaults write NSGlobalDomain AppleLanguages -array "$LANG"
    xcrun simctl spawn "$UDID" defaults write NSGlobalDomain AppleLocale -string "$APPLE_LOCALE"
    xcrun simctl terminate "$UDID" "com.example.app" || true

    asc screenshots capture \
      --bundle-id "com.example.app" \
      --name "home" \
      --udid "$UDID" \
      --output-dir "$RAW_DIR/$LOCALE" \
      --output json
    echo "Captured $LOCALE"
  ) &
done
wait

# 步骤 2：并行带壳合成
for LOCALE in "${!LOCALE_UDID[@]}"; do
  (
    asc screenshots frame \
      --input "$RAW_DIR/$LOCALE/home.png" \
      --output-dir "$FRAMED_DIR/$LOCALE" \
      --device "$DEVICE" \
      --output json
    echo "Framed $LOCALE"
  ) &
done
wait

# 步骤 3：生成审核预览（单次运行，汇总所有语言）
asc screenshots review-generate \
  --framed-dir "$FRAMED_DIR" \
  --output-dir "./screenshots/review"

# 步骤 4：上传（根据需要按语言分别运行）
for LOCALE in "${!LOCALE_UDID[@]}"; do
  asc screenshots upload \
    --version-localization "LOC_ID_FOR_$LOCALE" \
    --path "$FRAMED_DIR/$LOCALE" \
    --device-type "IPHONE_65" \
    --output json
done