用途
apple-ads-audit 用于对已连接的 Apple Ads 账户进行只读诊断。它的定位是先读取账户、解释可观测到的现象，并在任何变更之前停止。该技能没有写入路径；若用户决定采取行动，应将修复建议转交给 apple-ads 处理。
主要能力
- 账户健康审计：覆盖投放服务状态、性能警告，以及 Apple 与 Adapty 安装量的对比。
- 结构审计：检查实时结构、重复投放目标、流量归属，以及缺失的交叉否定关键词。
- 数据读取与归一化：执行 whoami、list、get、metrics 和 metrics overview 等读取操作，对返回的实体进行归一化与比较，并产出发现结果与交接建议。
- 安装量对比：在同一范围和精确日期窗口内，比较 Apple 的 total_installs 与 Adapty 的 adapty_installs，展示两值及绝对差值 absolute_gap；当 apple_installs 大于 0 时展示相对差值 relative_gap。任一值缺失则标记为 unknown；Apple 安装量为零时说明百分比未定义。该对比明确说明两个系统的归因与事件定义不同，不应期待完全一致，也不做归因诊断、责任判定或原因断言。
使用方式
- 预检：每次会话先运行 adapty asa whoami。若 CLI、认证、订阅或 Apple 连接不可用，转交 adapty-cli-setup 并停止。若访问就绪，从列表结果中解析组织、应用和请求范围，不得凭空构造或复用其他公司的标识符。若用户没有已连接账户但想要一个建议结构，使用 apple-ads-strategy。
- 路由单个审计问题：打开 references/INDEX.md，阅读其中指定的一个 playbook。整体健康、投放服务、性能警告或 Apple 对 Adapty 安装量对比走 references/playbooks/account-health.md；实时结构、重复目标、流量归属或缺失交叉否定关键词走 references/playbooks/structure-audit.md；周度或月度运营复盘先走 apple-ads，再走其 weekly-review.md。默认不同时运行两个审计 playbook；完成所请求的审计后，若证据指向另一方向，可作为单独后续项提供。
- 当完整插件已安装时，使用运营技能同步的 CLI 参考：../apple-ads/references/asa-management.md 用于实体和目录读取，../apple-ads/references/asa-metrics.md 用于性能读取和指标定义。若本技能单独安装且这些文件缺失，使用 adapty asa <topic> <command> --help 查看已安装版本。playbook 会列出允许的读取命令，切勿凭记忆重建缺失的 flag 或 endpoint。
只读边界
允许的工作：whoami、list、get、metrics 和 metrics overview 读取；对返回实体进行归一化和比较；产出发现和拟议的交接。
禁止的工作：任何 create、update、add、sync、pause、enable 或自动化变更；在审计结果中包含可直接运行的写入命令；在本技能激活期间请求写入批准。
当用户要求修复某个发现时，关闭审计并将所选发现作为新任务交给 apple-ads，操作方必须重新解析 id 并自行获得确认。
诊断方法
- 框定问题：记录应用、范围、日期窗口、成功指标和任何用户定义的阈值，只索要会实质性影响结果的缺失输入。
- 规划读取：实体计数用 list 计数，指标用服务端聚合；标准审计保持在分析预算之内，绝不按实体或按天循环。
- 归一化证据：为每条返回行或元数据事实赋予证据 id，保留来源、窗口、实体 id 和指标；仅对 revenue、roas、arpu、arppu、arpas 或 roi 保留 cohort 窗口。
- 分离层次：先写观察，再写解释，最后写建议；绝不把解释当作观察到的事实呈现。
- 应用适用性：无法评估的控制项标记为 unknown 或 not_applicable，不当作失败计分。
- 报告并停止：建议最小的有用下一步，但不执行它。
发现契约
每次审计响应包含：summary（简短通俗的回答）、scope（公司、应用、实体范围及所用标识符）、date_window（精确日期与分组，仅 cohort 根包含 cohort 窗口）、findings（按严重性排序）、evidence（将每项主张映射到返回数据的 id）、confidence（总体置信度及限制性缺失数据）、unknowns（现有数据面无法回答的问题）、recommended_actions（只读后续或操作方交接）。
每条发现包含：status（healthy、attention、critical、unknown 或 not_applicable）、observation（返回数据直接显示的内容）、explanation（最简单且有支撑的解释，明确标注）、evidence（证据 id、指标名、窗口和受影响实体 id）、confidence（high、medium 或 low，并附原因）、recommendation（下一步读取或 apple-ads 交接）、limitations（妨碍更强结论的因素）。critical 仅用于已确认的投放服务失败或确实被突破的用户定义阈值；attention 用于有支撑但缺乏该证明的担忧。绝不编造数字健康分数或通用阈值。
适用场景
- 需要了解已连接 Apple Ads 账户整体健康状况或性能警告。
- 需要检查实时广告系列与广告组结构、重复目标、流量归属或交叉否定关键词。
- 需要对比 Apple 与 Adapty 的安装量差异。
- 需要只读审计并希望将变更严格留给后续流程。
限制
- 本技能完全没有写入路径，任何变更都必须交由 apple-ads 处理。
- 缺少业务目标时只报告事实，不评判优劣。
- cohort 样本过少或不成熟时，结论为 unknown，而非不盈利。
- 未限定范围的元数据读取可能混合应用或广告系列，此时应停止并解析范围。
- 若 429 到达 agent，则停止，不要循环休眠重试。
- 重新设计未来账户属于 apple-ads-strategy；修改任何内容属于审计完成后的 apple-ads。