App Store 预检技能：iOS/macOS 应用提交前自动检查，避免常见拒绝

app-store-preflight-skills by truongduy2611/app-store-preflight-skills

323 周安装量

912 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/truongduy2611/app-store-preflight-skills --skill app-store-preflight-skills

iOS 自动化测试

🇨🇳中文介绍

App Store 预检技能

在您的 iOS/macOS 项目上运行提交前检查，以捕获常见的 App Store 拒绝模式。

前提条件

asc CLI — 通过 Homebrew 安装：brew install asc (App-Store-Connect-CLI)
ASC CLI Skills — app-store-connect-cli-skills 用于 asc 使用模式
jq — 可选，但规则文档中的一些 JSON 检查示例会用到它

步骤 1：识别应用类型 → 加载检查清单

通过从 references/guidelines/by-app-type/ 加载相关的检查清单来确定适用的指南。始终从 all_apps.md 开始，然后添加特定于应用类型的清单：

应用类型	检查清单
所有应用

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

步骤 2：拉取元数据以供检查

使用 asc CLI 拉取最新的 App Store 元数据：

# 拉取您要审查的版本的规范元数据 JSON
asc metadata pull --app "<APP_ID>" --version "<VERSION>" --dir ./metadata

asc metadata pull 将应用信息文件写入 ./metadata/app-info/*.json，将版本本地化文件写入 ./metadata/version/<VERSION>/*.json。

下面的大多数规则示例都假设使用 asc metadata pull 写入的规范 JSON 布局。

如果您已有其他布局的元数据（例如 fastlane metadata/），请调整文件路径示例以适应该结构，或者先拉取规范的 asc 布局。

步骤 3：运行拒绝规则检查

对于每个类别，从 references/rules/ 加载相关的规则文件并进行检查。每个规则包含：检查内容、检测方法、解决方案和拒绝示例。

类别	规则文件
元数据	`references/rules/metadata/*.md`
订阅	`references/rules/subscription/*.md`
隐私	`references/rules/privacy/*.md`
设计	`references/rules/design/*.md`
权利	`references/rules/entitlements/*.md`

步骤 4：报告发现的问题

使用此模板生成摘要报告：

## 预检报告

### ❌ 发现的拒绝项 (N)
- [指南 X.X.X] 问题描述
  - 文件：违规文件路径
  - 修复：需要做什么

### ⚠️ 警告 (N)
- [指南 X.X.X] 潜在问题

### ✅ 通过 (N)
- [类别] 所有检查已通过

按严重性排序：先拒绝项，然后是警告，最后是通过项。

步骤 5：自动修复 + 验证

一些问题可以自动修复：

竞争对手术语 → 建议替换文本，移除竞争对手名称
元数据字符限制 → 显示当前长度与最大长度
缺失的链接 → 生成模板服务条款/隐私政策 URL

应用任何自动修复后，重新运行受影响的检查以确认修复解决了违规问题。只有在重新扫描通过后才能标记为已解决。

对于需要手动干预的问题（截图、UI 重新设计），请提供清晰的说明，但不要自动修复。

中国商店 — 被禁止的 AI 术语（ChatGPT、Gemini 等）会在所有语言环境中检查，而不仅仅是 zh-Hans。Apple 会检查中国商店中可见的每个语言环境。
隐私清单 — 即使您的应用不直接调用必需原因 API，也需要 PrivacyInfo.xcprivacy。使用 UserDefaults 或 NSFileManager 的第三方 SDK（Firebase、Amplitude 等）会间接触发此要求。
asc 认证 — asc metadata pull 需要 App Store Connect 身份验证。请先运行 asc auth login，或者设置 ASC_KEY_ID、ASC_ISSUER_ID 以及 ASC_PRIVATE_KEY_PATH / ASC_PRIVATE_KEY / ASC_PRIVATE_KEY_B64 中的一个。如果不确定 asc 使用了哪个，请运行 asc auth doctor。
订阅元数据 — Apple 要求服务条款/隐私政策链接同时出现在 App Store 描述中和应用内订阅购买屏幕上。缺少任何一个都会导致单独的拒绝。
macOS 权利 — Apple 会要求您为每个临时例外权利（com.apple.security.temporary-exception.*）提供理由。请移除您未主动使用的权利。

在相应的 references/rules/ 子目录中创建一个 .md 文件：

# 规则：[简短标题]
- **指南**：[Apple 指南编号]
- **严重性**：REJECTION | WARNING
- **类别**：metadata | subscription | privacy | design | entitlements

## 检查内容
## 检测方法
## 解决方案
## 拒绝示例

🇺🇸English

App Store Preflight Skill

Run pre-submission checks on your iOS/macOS project to catch common App Store rejection patterns.

Prerequisites

asc CLI — Install via Homebrew: brew install asc (App-Store-Connect-CLI)
ASC CLI Skills — app-store-connect-cli-skills for asc usage patterns
jq — Optional, but used by some JSON-inspection examples in the rule docs

Step 1: Identify App Type → Load Checklist

Determine which guidelines apply by loading the relevant checklist from references/guidelines/by-app-type/. Always start with all_apps.md, then add the app-type-specific one:

App Type	Checklist
Every app	`references/guidelines/by-app-type/all_apps.md`
Subscriptions / IAP	`references/guidelines/by-app-type/subscription_iap.md`
Social / UGC	`references/guidelines/by-app-type/social_ugc.md`
Kids Category	`references/guidelines/by-app-type/kids.md`
Health & Fitness	`references/guidelines/by-app-type/health_fitness.md`
Games	`references/guidelines/by-app-type/games.md`
macOS

Full guideline index: references/guidelines/README.md

Step 2: Pull Metadata for Inspection

Pull the latest App Store metadata using the asc CLI:

# Pull canonical metadata JSON for the version you want to review
asc metadata pull --app "<APP_ID>" --version "<VERSION>" --dir ./metadata

asc metadata pull writes app info files to ./metadata/app-info/*.json and version-localization files to ./metadata/version/<VERSION>/*.json.

Most rule examples below assume the canonical JSON layout written by asc metadata pull.

If you already have metadata in another layout (for example fastlane metadata/), either adapt the file-path examples to that structure or pull the canonical asc layout first.

Step 3: Run Rejection Rule Checks

For each category, load the relevant rule files from references/rules/ and inspect. Each rule contains: What to Check , How to Detect , Resolution , and Example Rejection.

Category	Rule Files
Metadata	`references/rules/metadata/*.md`
Subscription	`references/rules/subscription/*.md`
Privacy	`references/rules/privacy/*.md`
Design	`references/rules/design/*.md`
Entitlements	`references/rules/entitlements/*.md`

Step 4: Report Findings

Produce a summary report using this template:

## Preflight Report

### ❌ Rejections Found (N)
- [GUIDELINE X.X.X] Description of issue
  - File: path/to/offending/file
  - Fix: What to do

### ⚠️ Warnings (N)
- [GUIDELINE X.X.X] Potential issue

### ✅ Passed (N)
- [Category] All checks passed

Order by severity: rejections first, then warnings, then passed.

Step 5: Autofix + Validate

Some issues can be auto-fixed:

Competitor terms → Suggest replacement text with competitor names removed
Metadata character limits → Show current vs. max length
Missing links → Generate template ToS/PP URLs

After applying any auto-fix, re-run the affected checks to confirm the fix resolved the violation. Only mark as resolved once the re-scan passes.

For issues requiring manual intervention (screenshots, UI redesign), provide clear instructions but do not auto-fix.

Gotchas

China storefront — Banned AI terms (ChatGPT, Gemini, etc.) are checked across ALL locales, not just zh-Hans. Apple checks every locale visible in the China storefront.
Privacy manifests — PrivacyInfo.xcprivacy is required even if your app doesn't call Required Reason APIs directly. Third-party SDKs (Firebase, Amplitude, etc.) that use UserDefaults or NSFileManager trigger this requirement transitively.
asc auth — asc metadata pull requires App Store Connect authentication. Run asc auth login first, or set ASC_KEY_ID, ASC_ISSUER_ID, and one of ASC_PRIVATE_KEY_PATH / / . If you're unsure what is picking up, run .

Adding New Rules

Create a .md file in the appropriate references/rules/ subdirectory:

# Rule: [Short Title]
- **Guideline**: [Apple Guideline Number]
- **Severity**: REJECTION | WARNING
- **Category**: metadata | subscription | privacy | design | entitlements

## What to Check
## How to Detect
## Resolution
## Example Rejection

Weekly Installs

323

Repository

truongduy2611/a…t-skills

GitHub Stars

912

First Seen

6 days ago

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

codex315

cursor312

gemini-cli311

kimi-cli311

github-copilot311

amp311

xdrop 文件传输脚本：Bun 环境下安全上传下载工具，支持加密分享

20,700 周安装

ASC_PRIVATE_KEY_B64

Subscription metadata — Apple requires ToS/PP links in BOTH the App Store description AND the in-app subscription purchase screen. Missing either one is a separate rejection.

macOS entitlements — Apple will ask you to justify every temporary exception entitlement (com.apple.security.temporary-exception.*). Remove entitlements you don't actively use.