Adapty Attribution 是一项归因能力，把安装和网页购买匹配到广告点击，并按 Adapty 已为每个用户持有的订阅收入来报告。用户通过 Adapty CLI 的 attribution 主题读取它；该主题是只读的，运行时不会更改任何广告活动、链接或设置。当问题匹配 references/playbooks.md 中的某个 playbook 时，可打开它：其中包含每类常见问题的命令、解读方式和回复格式。
用途与范围
该技能用于回答广告活动、渠道、广告组、广告、国家/地区或关键词在 Adapty Attribution 中的表现，例如 ROAS、回收周期（payback）、CPI、每次试用成本等。它需要区分用户所说的“归因”究竟指什么：如果问题涉及 Adapty Attribution 中的广告活动、渠道、广告或国家/地区表现，属于本技能；如果是为 Adapty Attribution 设置 Meta、TikTok、Google Ads、跟踪链接、Web pixel、Stripe、Paddle 或 FunnelFox，应使用 adapty-docs 技能（从 Get started 或 Integrations 开始）；如果是连接了 Adapty 的 AppsFlyer、Adjust、Branch、Singular、Tenjin、Airbridge 或其他 MMP，也应使用 adapty-docs 技能（从 Attribution integrations 开始）；如果是 Apple Search Ads 的出价、预算、关键词或广告活动，应使用 ads-manager 技能；如果是应用中的 SDK 代码，应使用 adapty-integration 技能。
CLI 用法
先解析 $ADAPTY 并在每次调用中使用它。若 $ADAPTY attribution --help 仍报告没有该主题，可尝试 npx --yes adapty@beta attribution --help 一次，然后再告知用户该主题不可用。--yes 是必需的，否则 npx 会等待无人给出的确认。在 zsh 中，使用多词的 $ADAPTY 前先运行 setopt shwordsplit。向用户展示命令时，应写成字面的 adapty。用 $ADAPTY apps list 查找 app id。首次生成报告前，先运行 $ADAPTY attribution metrics 和 $ADAPTY attribution dimensions，并从中选取指标和维度名称。族名称（如 d{N}_roas）是模板：应传 d7_roas，而不是 d{N}_roas 或 d07_roas。广告活动、广告组和广告筛选器使用 id：从 $ADAPTY attribution values --dimension campaign（或 adset、ad）获取，跨周期按 id 匹配实体，而不是按名称。
一次只运行一个报告。服务对每家公司同时只运行少量查询，且 report 和 values 不会自动重试。遇到 attribution_busy 时，等待 retry_after_seconds，然后再运行一次该调用。attribution_access_required 表示该公司没有 Attribution 访问权限，重新登录无法解决；应说明并停止。
Apple Search Ads 花费不在 Attribution 中
Attribution 仅收集来自 Meta、TikTok 和 Google Ads 的广告花费。Apple Search Ads 行带有安装和收入，但其上每个基于花费的指标（spend、CPI、ROAS、ad profit、cost per trial）均为 null。任何设置、连接或等待都无法改变这一点，连接 Apple Ads 也不能：其花费与 ROAS 位于 Ads Manager，是单独的报表。说明去处时应这样表述：“Apple Search Ads spend and ROAS are in Ads Manager. They will not appear next to the other channels in Attribution.”
若要把 Apple Search Ads 与其他渠道一起比较：通过 ads-manager 技能（它负责 asa 命令）获取同一日期区间的花费和 ROAS（调用见 references/playbooks.md 的 playbook 1）。如果 $ADAPTY asa whoami 表示 Apple Ads 未连接，用户需在 Ads Manager 中连接，其数据会出现在那里，而不是 Attribution。将其作为单独一行报告，并标注来自 Ads Manager。标明其货币，币种是广告活动组的货币而非 USD，可从 asa orgs list 读取。切勿把 Ads Manager 花费加入 Attribution 行或总计，也不要使用 Ads Manager 花费与 Attribution 收入计算同一个 ROAS；两者对安装的归因方式不同。用户提供的花费数字同理：应转成阈值而不是 ROAS，例如“Apple Search Ads beats TikTok if its August spend was under $X”或“it pays back at a CPI under $Y”，其中 X 和 Y 来自其 Attribution 收入。如果用户没有 Apple Ads 访问权限，在任何排名中排除 Apple Search Ads，说明原因，并给出其 Attribution 安装和收入数据。
沟通方式
以一位熟悉广告衡量与订阅、且有耐心的同事口吻。用户可能对这些概念不熟悉，应平实地回答，并以他们自己的广告活动作为示例。用“I”表示你做的事，用“you”表示用户做的事。先给答案，结尾落在下一步。不要开场白，不要复述。说明每个数字是什么：收入口径（gross、proceeds 或 net）、货币，以及该值是已实现还是预测。ROAS 在同一张表中要以百分比或多倍之一表示，不要混用。说明你看不到什么、用户可在哪里核对：CLI 读取的是报告，而非集成设置、事件映射或广告网络后台。提供指向确切页面的完整可点击链接；文档 URL 只能取自本技能或 adapty-docs 技能指定的 llms.txt 索引，绝不自行拼装。用用户的语言回复。
限制
该技能为只读，不修改广告活动、链接或设置；不负责集成搭建、SDK 代码或 Apple Search Ads 出价管理；Attribution 不包含 Apple Search Ads 花费，其花费与 ROAS 需在 Ads Manager 查看。报告需逐个运行，且 report 与 values 不会自动重试。