企业官网建设流程全解析

还在 App Store Connect 网页里手动导出分析报表吗？本文面向 iOS 开发者与数据分析师，介绍 app-store-connect-cli-skills 项目中的asc-analytics-reports技能：它配合 App Store Connect 命令行工具asc，一键完成 App Store 分析数据的自动化采集——从发现报表请求、按处理日期与粒度筛选报表实例，到批量下载全部报表分段，并用 Apple 提供的大小与 MD5 元数据逐文件校验，最终交给你一套可直接分析的、完整性可证明的私有数据文件。

🚀 快速上手：一条命令安装 asc 技能包

asc-analytics-reports是 app-store-connect-cli-skills 技能包中的成员，安装有两种方式：

1️⃣推荐：直接用asc自带命令安装全部技能：

asc install-skills

2️⃣手动：克隆仓库后交给 Agent Skills 安装器（如 Codex）：

git clone https://gitcode.com/gh_mirrors/ap/app-store-connect-cli-skills npx skills add gh_mirrors/ap/app-store-connect-cli-skills

安装完成后无需手动激活，Agent 检测到"下载分析报表"这类任务时会自动调用该技能。技能完整定义见 skills/asc-analytics-reports/SKILL.md。

📌 第一步：校验 asc 版本与命令契约

自动化之前，先确认本地asc支持所需的筛选参数：

asc analytics view --help

只有当帮助信息中同时列出--processing-date、--granularity、--paginate和--include-segments时才继续——这些参数需要asc 3.5.0 及以上版本。特别提醒：不要用已废弃的--date参数替代，它做的是本地粗略匹配，而非 Apple 服务端的处理日期过滤，容易拿到错误的报表实例。

📁 第二步：先建私有目录，再谈数据采集

分析报表属于机密商业数据，技能的第一步反而是"建保险箱"：

umask 077 ASC_ANALYTICS_DIR="$(mktemp -d "${TMPDIR:-/tmp}/asc-analytics.XXXXXX")" mkdir -m 700 "$ASC_ANALYTICS_DIR/segments"

这条命令在系统临时目录中创建一个仅属主可读写（700 权限）的目录，后续的报表清单 JSON、下载的分段文件、错误日志全部写入其中，而不是散落在仓库或聊天窗口里。整个采集流程的纪律是：原始 JSON 与报错输出绝不粘贴进聊天、commit、issue 或 PR。

🔍 第三步：优先复用已有报表请求

创建报表请求会改变 App Store Connect 的服务端状态，且需要 Admin 权限的密钥档案，因此技能规定先查后建：

asc --profile "$PROFILE" analytics requests \ --app "$APP_ID" \ --paginate \ --output json

• 找到可用请求：直接记录返回的requestId，继续往下走；
• 找不到：停下来征求你的明确批准，再创建ONGOING（持续）或ONE_TIME_SNAPSHOT（一次性快照）类型的请求，并加上--reuse-existing参数避免重复创建。

整个流程永不删除或替换已有请求，已验证文件之外不做任何破坏性操作。

🎯 第四步：按处理日期与粒度，精准检索报表实例

拿到requestId后，分两步发现报表。先用asc analytics view --request-id "$REQUEST_ID" --paginate --output json拉取报表与实例元数据（不带分段 URL），挑选可用的processingDate和粒度；再带上过滤条件拉取完整清单：

asc --profile "$PROFILE" analytics view \ --request-id "$REQUEST_ID" \ --processing-date "$PROCESSING_DATE" \ --granularity "$GRANULARITY" \ --paginate \ --include-segments \ --output json

两个实用细节：

• 粒度参数接受DAILY、WEEKLY、MONTHLY，可用逗号组合（如DAILY,WEEKLY）；非法值会被直接报错拦下，不会静默丢弃；
• --processing-date是 Apple 处理报表的日期，不一定是报表行数据所代表的时间周期，理解这一点能避免"数据日期对不上"的困惑。

全程使用--paginate让asc自动跟随 Apple 的分页链接，切勿手工拼接分页 URL。

⬇️ 第五步：下载全部报表分段，一个都不少

解析清单 JSON 时，逐个实例枚举其所有分段（segment），并记下每个分段的sizeInBytes与checksum元数据（这是第六步校验的"答案"）：

asc --profile "$PROFILE" analytics download \ --request-id "$REQUEST_ID" \ --instance-id "$INSTANCE_ID" \ \ --segment-id "$SEGMENT_ID" \ --output "$ASC_ANALYTICS_DIR/segments/$SEGMENT_ID.txt.gz"

三个关键约定：

• 分析报表是制表符分隔的文本，所以扩展名用.txt.gz而非 CSV 暗示；
• 校验之前不要加--decompress，保持压缩字节原样；
• 一个实例可能有多个分段，必须全部下载——只拿第一个分段就当作完整报表是最常见的错误。

✅ 第六步：大小 + MD5 双重校验，确认数据完好

每个下载完的文件都要与 Apple 元数据对账：压缩字节数等于sizeInBytes，且小写 MD5 摘要等于checksum：

actual_size="$(wc -c < "$SEGMENT_FILE" | tr -d ' ')" actual_md5="$(openssl dgst -md5 -r "$SEGMENT_FILE" | awk '{print tolower($1)}')"

校验不一致时分段即标记失败：由于asc analytics download拒绝覆盖已有输出，技能会重试一次到新路径（如$SEGMENT_ID.retry-1.txt.gz）并独立复验，两项检查都通过才采用。任何一段失败或缺失，都不得宣称"采集完整"，也绝不在校验通过前解析文件内容。

🛡️ 安全护栏：私有数据始终可控

这套流程把"数据安全"写进了每一步，值得单独记住：

最终汇报只包含：所选处理日期与粒度、报表/实例/分段的数量统计、完整性结论、失败分段 ID 列表（不含签名 URL 与报表行）——敏感值、凭据、原始数据行一概不进入任何公开产物。

💡 常见问题

Q：--processing-date和我理解的"报表日期"是一回事吗？不是。它表示 Apple 服务端处理该报表的日期；报表里的行数据可能覆盖更早的统计周期。

Q：每次运行都要创建新请求吗？不需要。技能优先发现并复用已有请求，只有在读不到可用请求、且你明确批准后，才创建ONGOING或ONE_TIME_SNAPSHOT请求。

Q：下载的文件能直接当 CSV 分析吗？不能。文件是.txt.gz压缩的制表符分隔文本，且必须先通过大小 + MD5 校验，才能交给下游分析流程解析。

Q：命令参数拿不准怎么办？随时用asc analytics view --help自查，并参考技能包中的 skills/asc-cli-usage/SKILL.md——它汇总了asc的规范动词、参数约定、分页与输出格式等通用用法。

📚 小结

asc-analytics-reports把"从 App Store Connect 拿分析数据"这件重复又易错的事，收敛为一条有纪律的流水线：验证版本契约 → 隔离私有存储 → 复用报表请求 → 按处理日期与粒度筛选实例 → 下载全部分段 → 大小 + MD5 双重校验。它只负责采集与验证，不做数据解读——这正是它的边界价值：交给下游的，永远是完整且可证明未被篡改的私有报表文件。技能全文可查阅 skills/asc-analytics-reports/SKILL.md，更多配套技能（发布流程、TestFlight 编排、崩溃诊断等）见 README.md。