asc-plugins

asc plugins

在 ~/.asc/plugins/<name>/ 中安装可执行插件，以处理 ASC 生命周期事件 — 发送 Slack 消息、发布到 Telegram、触发 Webhook，或在构建上传或版本提交时运行任意自定义自动化。

命令

list — 显示所有已安装的插件

asc plugins list [--pretty]

install — 从本地目录安装

asc plugins install <path>   # directory must contain manifest.json + run executable

uninstall

asc plugins uninstall --name <name>

enable / disable

asc plugins enable  --name <name>
asc plugins disable --name <name>   # leaves plugin installed, just suppressed

run — 手动测试插件

asc plugins run --name <name> --event <event> \
  [--app-id <id>] [--version-id <id>] [--build-id <id>]

事件：build.uploaded · version.submitted · version.approved · version.rejected

插件协议

插件是包含以下内容的任意目录：

文件	用途
manifest.json	名称、版本、描述、订阅的事件
run	可执行文件（任意语言，chmod +x）

stdin → 插件：

{
  "event": "build.uploaded",
  "payload": {
    "event": "build.uploaded",
    "appId": "123456789",
    "buildId": "upload-42",
    "timestamp": "2026-03-01T12:00:00Z",
    "metadata": {}
  }
}

插件 → stdout：

{"success": true, "message": "Slack notification sent"}

退出代码 0 = 成功。非零退出代码 = 记录到 stderr，其他插件不受影响，继续运行。

manifest.json

{
  "name": "slack-notify",
  "version": "1.0.0",
  "description": "Send Slack notifications for App Store events",
  "author": "Your Name",
  "events": ["build.uploaded", "version.submitted"]
}

典型工作流 — 创建并安装 Slack 插件

# 1. Create plugin directory
mkdir ~/slack-notify
cat > ~/slack-notify/manifest.json <<'EOF'
{
  "name": "slack-notify",
  "version": "1.0.0",
  "description": "Slack notifications",
  "events": ["build.uploaded", "version.submitted"]
}
EOF

cat > ~/slack-notify/run <<'EOF'
#!/bin/bash
INPUT=$(cat)
EVENT=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin)['event'])")
curl -s -X POST "$SLACK_WEBHOOK_URL" \
  -H 'Content-type: application/json' \
  --data "{\"text\":\":rocket: ASC event: $EVENT\"}" > /dev/null
echo '{"success": true, "message": "Sent to Slack"}'
EOF
chmod +x ~/slack-notify/run

# 2. Install
asc plugins install ~/slack-notify

# 3. Test (dry-run before uploading a real build)
asc plugins run --name slack-notify --event build.uploaded \
  --app-id 123456789 --build-id test-build --pretty

# 4. Get next build number and upload — plugin fires automatically
BUILD_NUMBER=$(asc builds next-number --app-id 123456789 --version 1.0.0 --platform ios)
asc builds upload --app-id 123456789 --file MyApp.ipa --version 1.0.0 --build-number $BUILD_NUMBER

# 5. Manage
asc plugins list
asc plugins disable --name slack-notify
asc plugins enable  --name slack-notify
asc plugins uninstall --name slack-notify

自动触发的事件

命令	发出的事件
asc builds upload（成功）	build.uploaded — 包含 appId、buildId
asc versions submit（成功）	version.submitted — 包含 appId、versionId

单个插件的失败会记录到 stderr，且绝不会阻止其他插件运行或影响主命令的输出。

JSON 输出

{
  "data": [
    {
      "affordances": {
        "disable":               "asc plugins disable --name slack-notify",
        "listPlugins":           "asc plugins list",
        "run.build.uploaded":    "asc plugins run --name slack-notify --event build.uploaded",
        "run.version.submitted": "asc plugins run --name slack-notify --event version.submitted",
        "uninstall":             "asc plugins uninstall --name slack-notify"
      },
      "author": "Your Name",
      "description": "Send Slack notifications for App Store events",
      "executablePath": "~/.asc/plugins/slack-notify/run",
      "id": "slack-notify",
      "isEnabled": true,
      "name": "slack-notify",
      "subscribedEvents": ["build.uploaded", "version.submitted"],
      "version": "1.0.0"
    }
  ]
}

已禁用的插件会显示 "enable" 选项，而不是 "disable"。

插件存储

~/.asc/plugins/
└── slack-notify/
    ├── manifest.json
    ├── run              ← executable (chmod +x)
    └── .disabled        ← optional: present = disabled

另请参阅

• 完整功能文档：docs/features/plugins.md
• CAEOAS：根据任何 asc plugins list 响应中的 affordances.listPlugins 操作