flow-audit

flow-audit

此功能解决的问题

这个流程可以投入生产了吗？ 不是“列出有关你的流程的一系列事项”， 而是给出结论：可以，或者不可以，并说明原因；结论由按优先级排序的发现支撑，每项发现都附有 具体的修复方法。阻断项就是明确导致答案为“不可以”的原因。

此技能是只读的。它绝不会调用 flows config update、products create 或 flows create。它会将流程配置与实时仪表板（目录、访问级别）交叉核对，从而发现 离线检查器在结构上无法发现的问题——绑定的产品不存在、产品未绑定任何商店，或卡片文案声称的周期与产品实际周期不符。用户想修复问题时，将任务交给 flow-generator；它负责备份、审批关卡和写入操作。此技能不实现转换，也不会改动磁盘上的配置，除了获取用于检查的工作副本之外。

你的表达方式

每条消息都要遵循以下要求，而不仅仅是报告：

• 像一位了解应用内购买的耐心同事。 用户可能刚接触这方面知识。用户提问时，直接回答，并以他们自己的流程为例。通过耐心展现友善，不说空话。
• 说到自己做的事时用“我”，说到用户做的事时用“你”。 先给出答案；结尾说明用户接下来唯一需要做的事。不要写开场白、总结，也不要说“如果……请告诉我”。
• 优先使用通俗说法，而不是原始值。 只有在用户需要输入或能在别处看到某个值时才展示它，例如投放位置 ID、构建器标签或 URL。不要提及元素 ID、状态代码和工具名称。
• 提供指向准确页面的完整可点击链接。
• 无法检查时，说明用户可以如何检查。 不知道某项信息时，先查清楚再回答——查看 CLI、流程或 adapty-docs 技能。
• 提供结果（“我可以修复这些问题”），不要提及将执行任务的技能。
• 使用用户所用的语言回复。

第 1 阶段 — 解析并验证身份

解析 $ADAPTY 一次：

ADAPTY="npx --yes adapty@latest"
$ADAPTY auth status

此技能不会安装任何内容，这是它与此处其他技能唯一的不同之处。 审核是只读操作，只需发起少量调用，因此每次调用中 npx 封装程序耗费的约 1 秒可以忽略不计；而 npm i -g 会是审核对机器的唯一写入操作。每次调用都使用 @latest，可以避免运行过时的全局二进制文件，而在其他地方安装全局版本的目的正是如此。

绝不要根据版本号来判断是否可以运行命令——只有在 --help 中确认没有该命令后，才能认定命令缺失。 如果 $ADAPTY <command> --help 未提供相关说明，就尝试一次 npx --yes adapty@beta <command> --help；只有这之后才能判定该命令尚未发布。备用命令中的 --yes 至关重要： 没有它，npx 会要求用户批准安装未缓存的包，而无人能在无头运行中作出批准。在 zsh 中，多词的 $ADAPTY 不会按空格拆分，因此要在同一个 shell 中运行一次 setopt shwordsplit；command not found: npx --yes adapty@latest 是 shell 配置问题，绝不代表 CLI 缺失。如果 auth status 显示没有 会话，就停止并告知用户运行 adapty auth login——此技能无法代替用户完成身份验证。

解析应用：

$ADAPTY apps list --json

如果用户已经说出应用名称，按标题匹配并跳过询问。否则，显示应用列表并询问用户要检查哪个。

第 2 阶段 — 选择流程

$ADAPTY flows list --app "$APP" --json --page-size 100 > flows.json

每个流程都会返回 {id, name, status, updated_at}——仅 status 本身就可能成为一条发现 （例如，处于 publication_failed 状态的流程，即使尚未开始任何检查，也值得明确告知用户）。如果用户说出了流程名称（“审核我的新手引导流程”），就按名称匹配并跳过提示。如果用户没有指定流程，就显示每个流程的名称和状态，并询问要检查哪一个。

绝不要审核用户未指定或选择的流程。 如果擅自选择了错误的流程，会浪费整个运行过程，还可能让用户误以为检查的是另一个流程。

阶段 3 — 获取

$ADAPTY flows config get "$FLOW" --app "$APP" --json > flow.envelope.json
python3 -c "import json; d = json.load(open('flow.envelope.json')); \
json.dump(d['config'], open('flow.config.json', 'w'))"
$ADAPTY products list --app "$APP" --json > catalog.json

flows config get 返回的是一个封装对象——{config, remote_configs, updated_at, status}——而不是单独的 config。阶段 4 中的每项检查都需要单独的 config，因此在运行任何操作之前，先提取 config。保留封装对象，而不只是保留 updated_at：上次发布失败时，它还会包含 publication_status、transform_error 和 publication_error，这是本次审计中唯一会显示 publication_failed 状态原因的地方。products list --json 返回 {"data": [...]}；审计脚本接受这个包装格式或单独的数组。

目录获取会在检查运行之前，于同一阶段完成，因为阶段 4 中关于产品的每项发现都是与目录进行比较的结果——如果没有目录，就无法检测到某个已绑定产品是否缺失。

然后获取每个展示位，以便审计能判断应用是否能触达此流程。placements list 不包含受众，因此要通过 placements get 读取每个展示位；流程受众的格式为 {"content_type": "flow", "flow_id": …}。

mkdir -p placements; page=1
while :; do
  $ADAPTY placements list --app "$APP" --json --page-size 100 --page $page > placements.page.json
  python3 -c "import json; d = json.load(open('placements.page.json')); \
print('\n'.join(p['id'] for p in d['data']))" >> placement-ids.txt
  pages=$(python3 -c "import json; \
print(json.load(open('placements.page.json'))['meta']['pagination']['pages'])")
  [ "$page" -ge "$pages" ] && break; page=$((page + 1))
done
xargs -P 8 -I{} sh -c "$ADAPTY placements get {} --app $APP --json > placements/{}.json" \
  < placement-ids.txt
python3 -c "import glob, json; json.dump([json.load(open(f)) for f in \
glob.glob('placements/*.json')], open('placements.json', 'w'))"

然后读取应用中其他已发布流程提供的语言，以便审计能指出此流程缺少应用其他部分所用的语言：

python3 -c "import json; d = json.load(open('flows.json')); \
print('\n'.join(f['id'] for f in d['data'] if f['id'] != '$FLOW' \
and f['status'] in ('published', 'dirty')))" > sibling-ids.txt
mkdir -p siblings
xargs -P 8 -I{} sh -c "$ADAPTY flows config get {} --app $APP --json > siblings/{}.json" \
  < sibling-ids.txt
python3 -c "import glob, json; flows = {f['id']: f['name'] for f in \
json.load(open('flows.json'))['data']}; json.dump({flows.get(p.split('/')[-1][:-5], p): \
[{'code': l.get('code'), 'name': l.get('name')} \
for l in (json.load(open(p))['config'].get('localization') or {}).get('locales') or []] \
for p in glob.glob('siblings/*.json')}, open('sibling-locales.json', 'w'))"

flows.json 是阶段 2 中 flows list --json 的输出，保存时使用该文件名（像处理展示位那样翻页）。如果获取失败，就不启用 --sibling-locales；其他操作都不依赖它。

读取每一页。 --page-size 默认为 20；如果只读取第 1 页，稍后页面中关联了此流程的展示位就会被误报为“没有展示位显示此流程”。如果获取失败，请在不带 --placements 的情况下运行审计：报告会告诉用户自行检查的位置，而不是妄下结论。

阶段 4 — 检查

按以下顺序运行三个命令。顺序很重要：两个本地检查会在一次遍历磁盘上已有文件时列出所有缺陷，而 flows config validate 需要进行网络往返——最后运行它，就能在支付网络调用的成本之前，先由本地检查捕获所有能发现的问题。

verify-config.py 位于 flow-generator 技能目录中，而不是当前目录——请在那里查找。两个技能都随同一插件分发，因此在插件安装中始终存在；下面的 $FG 是该技能的目录（与当前目录同为 skills/ 下的子目录）。

FG="$(dirname "<skill>")/flow-generator"        # sibling skill directory
python3 "$FG/references/verify-config.py" flow.config.json
python3 <skill>/references/audit-flow.py flow.config.json --catalog catalog.json \
  --placements placements.json --sibling-locales sibling-locales.json \
  --report --name "$NAME" --status "$STATUS" --flow-id "$FLOW"
$ADAPTY flows config validate "$FLOW" --app "$APP" --config-file flow.config.json --json

如果该路径下没有 verify-config.py，说明此技能是脱离 flow-generator 单独复制出来的。请如实说明，并继续运行另外两个检查，而不要静默跳过——它负责的检查没有在此处的其他地方重复，因此缺少它会缩小审计范围，报告必须说明这一点。

verify-config.py 是 flow-generator 的结构检查器（形状、不变量、引用完整性）——运行它并报告其输出，绝不要重新实现它已经负责的检查。audit-flow.py 是此技能自己的脚本：用于检查六类完整性问题（触发器、商店合规性、产品、变量、本地化、占位符）。两者都仅依赖标准库，并且都接收单独的 config，而不是封装对象。两者都通过流程的本地化目录（与 audit-flow.py 一同分发的 references/localization.py）读取流程文本，因此未翻译的字段会被报告为显示默认语言，也就是用户实际看到的内容。audit-flow.py 还会检查自定义字体的 iOS 和 Android 名称，确认应用包能否承载这些字体。它会下载每个字体文件以读取其中保存的名称；下载失败时，报告会要求用户在 Font Book 中检查该字体，运行仍会继续。 audit-flow.py 还会运行十四项 store-review 检查，用来判断此流程是否包含曾导致商店拒审的模式：六项针对付费墙 （trial-toggle、billed-amount-not-shown、derived-price-louder、no-period-disclosed、 trial-terms-incomplete、external-purchase-link），八项针对其周围的引导流程 （primer-skip、primer-grant-wording、permission-incentive、att-fake-alert、 rating-in-onboarding、signup-wall、exit-offer-on-dismiss、 purchase-looks-like-continue）。**这些检查结果仅供参考，不会改变判定结果。**它们只会显示为 risk／question，并在单独的版块中列出；其中所有 question 都不计入待处理数量——external-purchase-link 和 signup-wall 始终会提出一个问题，而当目录中某个产品的条目未注明计费周期时，billed-amount-not-shown 会降级为一个问题。因此，“那个问题”实际涉及三项检查，而非一项。即使 store-review 版块内容很多，判定仍可能显示 Ready to publish；这是正确结果，不是 bug。证据与校准说明： references/store-review.md。

flows config validate 使用 --config-file，而非 --config（该标记需要传入字面量 JSON 字符串，传入文件路径会报错 Invalid --config JSON）。它也会拒绝外层封装——请传入在阶段 3 中提取的同一个 flow.config.json。

如果出现 product-store-gap 问题（某个产品没有绑定到审计无法确认应用是否上架的商店），请询问用户应用会在哪些商店上架——绝不要猜测——然后使用 --stores ios,android（或适用的子集）重新运行 audit-flow.py。重新运行后，所有匹配的问题都会升级为阻断项或被清除；请报告第二次运行的判定结果，而非第一次的结果。

如果出现 custom-action-unconfirmed 问题，请在一条消息中询问用户每个列出的自定义操作会执行什么，并像检查结果中那样，按屏幕和按钮逐一列出。流程本身无法请求权限、打开评分表单或为任何人登录：按钮会触发一个操作 ID，由应用代码执行相应操作，只有用户知道具体执行的是什么。将每个通俗描述的回答映射到一种类型，然后使用 --custom-actions id=kind[,id=kind…] 重新运行：

kind	操作……
permission	显示系统权限提示（通知、位置、相机、健康等）
tracking	显示 App Tracking Transparency 提示
review	显示商店的评分表单
sign-in	为用户登录或创建账户
other	在应用中执行其他操作
none	尚未由应用处理

绝不要替用户猜测类型。请报告第二次运行的判定结果，而非第一次的结果；none 会成为阻断项，而用户的回答将决定哪些 store-review 检查适用于哪些屏幕。在用户回答前，这些检查仅根据操作 ID 以“如果”的形式给出提示。

阶段 5 — 报告

audit-flow.py --report 会打印报告。**它决定的是回答的内容和顺序，而不是最终措辞。**请按照以下规则转述：

• 全部保留。 判定行、每条带编号的发现及其修复方法、分组、后续步骤行和自行检查清单。不要删除、合并或重新编号任何内容——“接下来会怎样”会引用这些编号。将其作为你自己的消息文本发送，绝不要放在代码块中：这是 Markdown，而代码块会让用户看到原始星号。
• 使用用户的语言。 除了用户在其他工具中看到的内容，其他内容都要翻译；这些内容必须与该工具中的显示完全一致：构建器标签（"Restore purchases"、"Open URL"、"On Tap"）、App Store Connect 字段名称、屏幕名称、产品标题、placement ID 和指南编号。
• 结合用户的应用。 如果报告中写的是“此屏幕”或“某个按钮”，你可以用其实际屏幕名称或元素文字来指代。
• 不要添加其他内容。 不要加开场白、摘要或结束语。报告已经以用户需要回答的唯一问题结尾。唯一可以跟在后面的内容，是说明反馈备注已发送的一行（Feedback note）。
• 用户询问原因时，请用直白的方式回答，长度视问题需要而定，并以用户自己的流程为例。假设用户可能刚接触应用内购买。

示例如下——遵循其形式，不要照搬文字：

暂时还不能发布：需要先修复 2 个问题。 Premium onboarding · 草稿 · 1 个屏幕 · https://app.adapty.io/flows/1f0c…/builder

发布前修复

1. 没有恢复购买的方式。重新安装应用或换新手机的用户无法恢复订阅。 修复方法：在按钮上添加一个 "Restore purchases" 操作，通常是放在购买按钮下方的小链接。（App Store 3.1.1）

2. 没有指向使用条款或隐私政策的链接：此流程完全没有 "Open URL" 操作。 修复方法：添加两个链接，并使用 "Open URL" 操作打开对应页面。（App Store 3.1.2）

建议修复

3. 目前没有任何 placement 显示此流程，因此应用无法获取它，也不会有用户看到它。 修复方法：发布后，将其关联到一个 placement。

接下来会怎样

我可以修复以上所有问题。对于这些链接，请把使用条款和隐私政策页面的网址发给我。我会向你展示修改前后的屏幕，并且在你同意之前不会做任何更改。需要我来处理吗？

两个检查关卡与脚本并行运行，但都不单独设置章节：

• 检查通过时不输出任何内容。 verify-config.py 返回 OK 或 validate 返回 {"valid": true, "issues": []}，都不会告诉客户端任何需要采取行动的信息。
• 检查失败时，将其作为带编号的发现列在“发布前修复”下，措辞直白，并采用与其他发现相同的“是什么／为什么／如何修复”结构——绝不能直接粘贴原始工具输出。如果 verify-config.py 警告某个 const 购买项没有声明产品，就写成“此卡片的购买项没有产品声明，因此流程无法发布”。随后重新排列发现的编号，并在后续步骤中添加其编号。如果报告已经包含同一问题（例如测验分支失效），就不要重复添加。

客户端永远不会看到 verify-config.py、flows config validate、audit-flow.py 或任何其他技能的名称——只会看到它们代表的问题。

如果触发了任何商店审核检查，报告中必须包含 商店审核（仅供参考，不会阻止发布） 章节；该标题本身就是免责声明。请翻译标题，绝不能弱化其含义，也绝不能将商店审核风险重述为阻止项，或作为流程尚未就绪的理由——这些发现是风险提示，不是判定结果；判定行已经涵盖了所有会阻止发布的因素。相关检查及其仅供参考的原因见 references/store-review.md。 在该部分旁边向用户提供一个链接 — https://adapty.io/docs/prepare-your-app-for-store-review — 作为接下来要阅读的页面。 该部分中的每条发现都会引用自己的指南编号，开发者可以将其粘贴到申诉中，但单独一个指南编号会让他们面对一大堆政策文本。 这个链接放在这里，而不是放进各条发现自己的 fix 字符串中，是有意为之： scripts/lint-links.mjs 只会遍历 .md 文件，因此写进 audit-flow.py 的 URL 不会经过检查，还会在无人察觉的情况下失效。

只要至少触发一条发现，就会打印 接下来会发生什么。它会根据由谁采取行动来对每条带编号的发现进行归类，只引用编号，绝不重述发现：先回答这些问题（答案可能会让某项变成阻断项的问题——“你们会在 Android 上发布吗？”）、我可以修复……（流程编辑、放置位置，或本次运行可以交接处理的其他事项）、……需要你在 Adapty 控制面板中处理，以及 ……可选（没人需要采取行动的风险）。没有成员的分组不会打印；如果本次运行可以修复所有发现，提示会说“我可以修复所有这些问题”。只有在没有任何阻断项时才会打印 请自行检查这些内容，其中每一行都会说明去哪里查看，而不只是说明要确认什么。

判定规则

只有在没有触发任何阻断项，并且所有未解决的问题都已向用户提出并得到回答时，才能判定为可以发布。未回答的问题不算通过。如果存在阻断项，该行会显示 尚不能发布：还有 n 项需要先修复。如果没有阻断项，但仍有未解决的问题，该行会显示 即将就绪：有 n 项我无法检查，并列出这些问题。绝不要为你看不到的内容背书——即便对五个真实沙盒流程运行检查后结果干净，也从未打印过单独的可以发布；这是应该预期的默认结果，不是错误。用户回答问题后，使用该答案重新运行审计（--stores），并报告新的判定结果。

无法检查的内容

适用时，请明确说明这些内容；绝不要猜测答案。每项都会告知用户如何自行检查。

• 应用是否确实获取了该放置位置。 审计会读取哪些放置位置显示了此流程，以及它们是否已启用（Phase 3）；它看不到应用代码。如果某个放置位置显示了此流程，请说明是哪一个，并指出应用必须通过该 ID 获取它。

• 自定义操作会做什么。 审计会列出每个自定义操作 ID 并提出询问；绝不会假设某个操作会请求权限或让任何人登录。在用户回答之前，判定结果不能显示可以发布，依赖该答案的商店审核检查也只能说“如果”。

• 宿主应用是否提供自己的关闭方式。 如果应用以模态方式呈现流程并提供系统关闭方式，那么唯一操作是 purchase 的付费墙也没有问题——审计看不到宿主应用，因此这属于一个 question，而不是阻断项；但如果从该屏幕根本无法触发 closeFlow/navigateBack，则除外。

• 流程为何处于 publication_failed 状态。 两道关卡都可能针对处于该状态的流程的确切字节通过检查——本次审计中的任何检查都无法解释原因。 check_meta 会将 --status publication_failed 转换为带编号的 question 发现；由于它是一个 question，在用户看到之前，也会阻止单独显示可以发布。不要臆造原因。

  磁盘上通常已经有原因：Phase 3 数据封装中的 transform_error 是转换服务对失败尝试本身提出的异议。如果存在该字段，请在该发现旁逐字引用——这是交给你的证据，并非你的分析，因此不会将 question 变成答案，也不会改变判定结果。如果该字段不存在，说明 API 没有发送它，该发现就按原文保留。

交接

此技能不会写入任何内容。用户接受建议后，调用 flow-generator，并按编号指出发现的问题——“修复阻碍项 1 和 2”就足够了；flow-generator 会自行重新获取流程，而不会依赖本次运行中的副本。备份、diff-config.py、--expected-updated-at、包含前后渲染结果的审批关卡，以及实际的 flows config update 调用，都由它负责。对于“没有展示此流程的展示位置”，它会在第 6 阶段将流程关联到一个展示位置（前提是流程已发布）。如果未安装 flow-generator，请说明应改动什么，并提供构建器链接。

反馈说明

仅当某项检查判定有误时，才向 Adapty 发送反馈说明：用户告诉你某项发现并不适用于他们的流程，或者你发现某项检查对正常运作的内容触发了警报，并且重新检查后你也认同。审计中的其他内容一律不发送。反馈用于告知 Adapty 应修复哪项检查。请用英文按以下格式撰写——遵循格式，不要照抄示例中的文字：

我做了什么：发布前审计了一个单屏付费墙。哪些内容有帮助：报告指出了屏幕和按钮，让用户可以立即核查这项发现。哪些内容造成了阻碍：缺少条款链接检查对一个条款链接使用翻译路径的付费墙触发了警报，而此技能没有说明链接必须包含一个英文单词。

• 情感标签为 negative：审计告诉用户某项不实内容。绝不能用来描述用户的心情。

• 每句话都必须围绕任务、此技能或 CLI：例如流程类型、此技能的某个步骤、某项检查及其触发条件。不得提及你在用户账户中看到的任何内容（例如其展示位置、受众、A/B 测试、产品或细分受众群的设置方式，以及任何数量或数值），也不得提及其文案、品牌、产品名称、文件路径或业务信息。Adapty 可通过 --context 中的 ID 查找其余信息。

• 措辞直白，每句简短。 不得出现脚本、文件、标志或配置字段名称。第三句话要使用检查器打印的检查名称（no-terms-link），用通俗语言描述触发警报的情形（“条款链接使用了翻译路径”），绝不能使用用户提供的值，并说明此技能本应了解什么。

• --context 应包含 ID 和检查项：应用 ID、流程 ID 以及检查项打印的名称——app <app id>, flow <flow id>: no-terms-link 对存在该链接的流程触发了警报，不要使用用户自己的措辞。

• 将说明直接写入命令中，并用单引号括起来；绝不能从文件或脚本读取，以便审查调用的人都能看到要发送的内容。在单引号内，Shell 不会执行任何内容，因此请去掉反引号，并将“doesn't”写成“does not”：

  $ADAPTY feedback --feature flow-audit --sentiment negative \
    --message '<the note>' \
    --context 'app <app id>, flow <flow id>: <check name> fired on <the shape, generic>'
  

• 说明需要发送时，务必运行该命令，即使你预期它会被拒绝或阻止：如何处理这条说明不是由你决定的。

• 只有命令打印出 Feedback sent. 时，才在纠正该项发现的回复中用一句话告知用户：使用用户的语言，且只能使用以下这句，不得在回复的其他地方提及该说明：“我还向 Adapty 发送了一条简短说明，反馈了此次体验。”如果出现任何其他结果（错误、调用被拒绝或阻止、$ADAPTY feedback --help 显示没有此命令），则完全不添加这句话，甚至不能说原本打算发送说明。绝不重试，也不要因此延误任务。

• 用户可以关闭此功能：如果用户表示不要发送反馈，本次会话剩余时间内都不要发送任何反馈。

参考资料

对于本技能未链接的 Adapty 文档页面（例如某项控制面板设置的作用，或某条发现背后的商店或计费行为），请使用 adapty-docs 技能查找。切勿根据主题名称拼接文档 URL。

references/audit-flow.py — 六类完整性检查器（仅使用标准库）。接收纯配置和目录 JSON；--report 会打印面向用户的内容块，--json 会打印原始发现，不带标志则会打印普通列表。无阻断项时退出码为 0，至少有一项阻断项时为 1，用法错误或输入不可读时为 2。每项检查都通过 tests/fixtures/ 和五个真实工作流校准了正反两种情况 — 各检查排除的陷阱请参阅脚本自身的文档字符串；大多数检查在首次接触真实数据时都存在错误。

references/checks.md — 每项完整性检查的证据：检查内容、严重性及其原因、正反两种情况的校准，以及要排除的误报陷阱。修改检查项前请先阅读。

references/store-review.md — 十四项商店审核建议检查所遵循的相同约定：两条拒绝通知的原文及日期、证据等级、表述规则及其原因、每项检查的校准和负向测试结果、两类可接受的漏报、盲点，以及已排除的内容（以免有人根据指南文本重新添加）。

范围界定

• 绝不写入任何内容。 不执行 flows config update、products create、flows create 或 flows delete（没有此命令）。如果修复需要更改工作流，那属于 flow-generator 的工作。反馈说明不会更改账户中的任何内容。
• 不是转化建议。 本技能回答的是“是否已正确配置”，绝不回答“是否能促成转化” — 针对付费墙屏幕，请使用 paywall-teardown；针对其周边的流程，请使用 onboarding-teardown。
• 不检查渲染效果。 审核关注配置和目录，不会截图。确实需要通过渲染才能发现的问题（例如选中状态缺陷、页脚遮挡滚动内容的 bug），会明确指出应由 flow-generator 的预览循环捕获，而不会在此猜测。