tangent

用途

Tangent 用于展示 Superwall 应用中付费墙 A/B 测试的运行情况：每个正在运行的实验、来自 Superwall Results 标签页的精确数字，以及每个付费墙的截图，最终生成一份完整报告。使用者的职责是运行它、发布它产出的内容，并给出简短摘要；不要重新推导数字，也不要手工搭建面板。

主要能力

• 一条命令发现应用中所有正在运行的实验。
• 通过 readout.py 拉取每个实验的 Results 标签页数字。readout.py 是仪表盘自身 SQL 的移植版本，因此数字与客户在 Superwall 中看到的一致。
• 渲染每个付费墙并生成成品报告。
• 输出多种产物：artifact.html（作为 Artifact 片段的报告，内嵌截图，含浅色与深色主题）、report.html（同一页面的独立版本，可在本地打开）、widgets/overview.html（仅含数字的概览，用于聊天内联小组件）、read.json（全部数字）以及 history/（每次运行一个快照）。

使用方式

第 0 步 — 仅首次运行

• 需要 Python 3.9+（用 python3 --version 检查）。
• Superwall CLI：用 superwall --help 检查。若缺失，运行 npm install -g superwall（需要 Node 18+）。
• 登录：用 superwall whoami --json 检查。若未认证，请对方在自己的终端运行 superwall bootstrap，用其 Superwall 账户登录，然后选择其组织。登录是浏览器流程。切勿索取、接受、回显或存储密码或 API 密钥。（脚本化环境可以改为在 shell 中导出 SUPERWALL_API_KEY 和 SUPERWALL_ORG_ID——那是他们自己的选择，不是由本技能设置或读回的。）
• 应用 id：传入 --app <id>（Superwall URL 中的数字），或在本文件旁的 config.json 中设置 app_id。若账户中只有一个应用，会自动找到。

第 1 步 — 运行

python3 "<this folder>/tangent.py" --app <id>

选项：--filter <text>（仅包含名称中含有该文本的活动/受众）、--include-paused、--no-images、--refresh-images（重新渲染缓存的截图）、--compare（与上次运行相比有哪些变化）。每个实验大约需要一分钟。

输出位于脚本旁的 out/<app_id>/（脚本会打印确切路径）：

• artifact.html — 作为 Artifact 片段的报告（截图内嵌，浅色 + 深色主题）
• report.html — 同一页面，独立版本；若没有 Artifact 工具可在本地打开
• widgets/overview.html — 仅含数字的概览，用于内联聊天小组件
• read.json — 全部数字；history/ — 每次运行一个快照

第 2 步 — 展示（每次运行都要两部分）

• 聊天中的概览。将 out/<app_id>/widgets/overview.html 原样渲染为内联小组件（小组件/可视化工具，例如 show_widget）。每个实验一行，附其结论。这是对方最先读到的内容。
• 完整报告作为链接。用 Artifact 工具按文件路径发布 out/<app_id>/artifact.html（标题在文件内；首次发布时 favicon 为 📊；复用同一路径，或传入先前的 URL，使每个应用的链接保持稳定）。报告包含付费墙截图和每个实验的面板。图片绝不经过聊天——带截图的报告约 1 MB。

回退方案：没有内联小组件工具 → 跳过第 1 部分，用文字描述表格。没有 Artifact 工具 → 告诉对方打开 out/<app_id>/report.html。切勿将每个实验的面板或图片粘贴到聊天中，切勿编辑数字，切勿手工重新设计样式或组合面板。

第 3 步 — 摘要

最多五行，来自脚本打印的控制台表格：每个实验一行——名称、状态、最关键的那个数字（APPU 差距和置信度 %），然后是任何被跳过的项。仅在 act（推广）、lost（停止挑战者）或 applied 行上给出行动建议；watch、tie、thin 和 dark 除“保持运行”外不给建议。始终提及来源表格：脚本打印的那一行。状态定义见 PRINCIPLES.md。

适用场景

• 需要快速了解 Superwall 应用中所有正在运行的付费墙 A/B 测试表现。
• 需要与 Superwall 仪表盘 Results 标签页一致的精确数字。
• 需要带付费墙截图的完整报告，用于分享或存档。
• 需要每次运行的历史快照，以及与前一次运行相比的变化（--compare）。

限制

• 只读：脚本发出 GET 请求和 SELECT 查询，无法更改付费墙、活动或权重。除发送到 Superwall 外，不会发送到任何其他地方。
• 需要 Python 3.9+、Superwall CLI（Node 18+）以及已认证的 Superwall 账户。
• 每个实验大约需要一分钟。
• 图片不经过聊天；带截图的报告约 1 MB。
• 截图缺失时，报告回退到静态预览或链接；付费墙图片仅来自 GET /v2/paywalls/{id}/preview-images（服务端渲染，含真实价格；退出/放弃表单以 kind: "overlay" 页面形式到达，显示在其宿主页面之后）。此处绝不添加浏览器或 Playwright 步骤。

故障排除

• 未登录 → 在其终端运行 superwall bootstrap。
• app … is not visible to org → 登录属于不同组织；用拥有该应用的账户登录。
• 某 readout 行被跳过 → 该受众尚无生产数据，或查询超时；重跑一次。
• 未找到正在运行的实验 → 每个受众只有一个付费墙（无可比较），或全部已暂停；尝试 --include-paused。
• 截图缺失 → Superwall 的渲染器繁忙；报告回退到静态预览或链接。稍后重跑；结果按付费墙版本缓存。