creating-replay-vision-scanners

创建 Replay Vision 扫描器

扫描器是在会话录制内容上持续运行的 LLM 探测器。创建并启用后，它会按每 5 分钟扫描一次的 Temporal 计划运行，将提示词应用于每个新匹配的录制内容，并将结果记录为一条观察（可查询的 $recording_observed 事件）。每条观察都会从组织当前计费周期的预算中扣除额度（1 个额度 = $0.01），而观察的价格取决于扫描器的 model——因此请按额度估算支出，并将用户提供的任何观察次数按该模型的价格换算成额度。

正因如此，创建扫描器时必须先仔细评估：如果查询条件过于宽泛且采样率为 100%，扫描器会自动开始产生支出，并可能在前几轮扫描内耗尽整个计费周期的预算。创建操作本身不会检查配额——只有在产生观察时才会进行保护，而到那时预算可能已经用完。

首先：扫描器真的合适吗？

扫描器是持续监控未来录制内容的工具。如果用户已经有特定会话，并且想了解这些会话的情况，他们根本不需要扫描器——他们需要的是 vision-scanners-inline-scan，它接收 session_ids 和 prompt，不会保存任何内容，也不会安排扫描。

如果会话已经确定，请使用内联扫描：“这五段录制内容中出了什么问题”、“昨天的结账会话中有没有遇到优惠券错误”等等；任何原本会通过创建扫描器并在之后将其删除来回答的问题，都适合使用内联扫描。它的每个会话费用相同，而且当同一个问题被重复提问时会复用答案，因此重复提问的成本很低。

只有当用户希望自动扫描尚未发生的录制内容时，才创建扫描器。如果你打算创建扫描器、查看一次结果，然后将其删除，请停下来改用内联扫描——一次性扫描器会留下持续运行的定时扫描任务，扫描所有符合其查询条件的未来录制内容。

核心原则：发布前先估算

切勿在未评估的情况下创建已启用的扫描器。估算其每月额度支出，检查剩余额度预算；如果预计支出占剩余额度的比例较高，请先向用户展示相关数字并征得确认，再创建扫描器。这是本技能的核心；其余内容都是辅助说明。

流程

第 1 步：扫描器应该做什么？

如果问题、类型或提示词仍然模糊，请先运行 [[designing-replay-vision-scanners]]。它会把一个想法转化为一个明确的问题，并确定固定的答案格式、证明规则，以及允许回答无法确定。确定这些内容后，再回到这里。

选择一个 scanner_type 并编写其 scanner_config。每种类型都需要一个 prompt；其余配置因类型而异：

类型	产出内容	scanner_config 结构
monitor	根据提示词进行开放式观察（例如“标记愤怒点击”）	{"prompt": "..."}；可选 "allow_inconclusive": true（默认关闭，因此模型必须回答是或否）
classifier	从固定标签集中分配标签	{"prompt": "...", "tags": ["tag-a", "tag-b"]} — tags 至少需要 1 项；可选 "multi_label": false（默认为 true）、"allow_freeform_tags": true（默认关闭）
scorer	根据评分标准给出数值评分	{"prompt": "...", "scale": {"min": 1, "max": 5, "label": "frustration"}} — min < max；label 可选
summarizer	自由文本摘要	{"prompt": "..."}；可选 "length": "short" | "medium" | "long"（默认为 "medium"）。始终启用嵌入

创建后，scanner_type 将被锁定——若要更改，必须删除并重新创建。因此，请一开始就确认类型正确，并确保 scanner_config 结构正确（结构错误会导致创建失败，而不是静默使用默认值；未知键也会被拒绝）。

如果用户的意图已明确到足以确定类型和提示词，就直接继续，不要盘问他们。 如果用户只有一个目标（“找出用户在引导流程中卡住的地方”），vision-scanners-draft 会为你拟定类型、配置、查询、模型和采样设置，供你审核；它不会保存任何内容。 询问用户希望使用多少额度，并提供两种选择：免费（free_only: true，仅使用组织的每月免费额度，绝不产生额外费用），或由用户指定每月额度。切勿擅自编造额度。将草案中的 free_only 和 credit_limit 传递给 vision-scanners-create。

第 2 步：选择哪些会话？

query 是一种 RecordingsQuery 结构，用于选择扫描器要查看的录制内容。date_from 和 date_to 会被忽略（时间由计划控制），因此不必设置。请将查询范围缩小到真正相关的会话——可按事件、URL、人员属性、时长等条件筛选。缩小查询范围是控制成本最有效的手段。

如果目标是某个实验中实际曝光的人群，那应该使用专门的流程——请使用 scanning-experiments-with-replay-vision 技能。它会根据实验的曝光条件推导查询，而不是让你手动构建。

还有两个筛选项可进一步缩小范围，应用顺序如下：

• sampling_mode（默认为 comprehensive）是对匹配会话的质量预筛选：focused 仅保留显现评分最高的会话，balanced 会剔除质量最低的会话，comprehensive 则全部保留。使用它可以把预算花在值得查看的会话上，而不是随机缩小覆盖范围。
• sampling_rate（0..1，默认为 1.0）是在此之后应用的随机降采样。调低此值可用覆盖范围换取预算。设为 0 会暂停扫描；低于 0.0001 的非零值会被拒绝。

哪个模型？

model 决定扫描器每次观察的费用，因此它既是质量调节手段，也是成本调节手段： gemini-3.5-flash-lite（2 积分）、gemini-3-flash-preview（5 积分，默认值）和 gemini-3.8-flash （15 积分）。从默认值开始，只有在较低价位的模型明显无法发现扫描器要查找的内容时，才使用 gemini-3.8-flash。

第 3 步：估算规模 — 直觉检查（不要跳过）

创建前，先执行以下两项检查，并结合起来判断：

1. 估算支出 — 使用拟定的 query、sampling_rate、 sampling_mode 和 model 调用 vision-scanners-estimate。它会返回 matched_sessions_in_window、测量的 window_days、 estimated_observations_per_month、credits_per_observation、estimated_credits_per_month，以及 other_enabled_scanners_monthly_credits（组织中其他已启用扫描器预计的支出）。编辑现有扫描器时，传入其 scanner_id，以免重复计算该扫描器的估算值。
2. 检查预算 — 调用 vision-quota-get，获取相对于组织 credit_limit 的 remaining 和 exhausted（单位为积分，1 积分 = $0.01；未设上限时为 null），以及当前周期的 period_start/period_end。

像产品界面那样，在相同时间范围内比较积分和积分 — remaining 的单位是积分，而不是观察次数，因此将其与 estimated_observations_per_month 比较会低估成本，低估幅度取决于模型每次观察的价格。 remaining 表示当前周期剩余时间内可用的额度，因此应按该时间段折算月度预测值，而不是拿整月费用与之比较：

fleet_monthly    = estimated_credits_per_month + other_enabled_scanners_monthly_credits
period_days      = period_end - period_start        (in days)
days_left        = period_end - now                 (in days, floored at 0)
rest_of_period   = fleet_monthly * days_left / period_days

然后根据 remaining 判断 rest_of_period：

• 如果费用明显低于 remaining，可以继续。
• 如果费用占 remaining 很大一部分（或超出 remaining），先停下来，告诉用户具体数字 （例如：“预计此扫描器每月支出约 X 积分，约合 $Y；本周期还剩 N 天，期间预计支出约 R 积分，而您还剩 Z 积分。”），然后在创建前征求确认。缩小 query 范围、将 sampling_mode 改为 focused、降低 sampling_rate 或选择更便宜的 model，都可以降低费用。
• 也要说明 estimated_credits_per_month，因为该扫描器在本周期重置后，每个完整周期都会产生这笔费用。周期中途创建的扫描器可能适合 remaining，但仍可能超出下一周期的预算。
• 如果组织已经 exhausted，请明确说明。在预算重置前，新的已启用扫描器不会产生任何结果：计划中的观察会被静默跳过，按需扫描则会直接被拒绝。
• 如果估算支出占 remaining 很大一部分，但用户仍想创建扫描器，可以提供单个扫描器的上限：创建时设置 credit_limit，限制该扫描器在每个计费周期内最多只能支出指定积分数。当剩余积分不足以支付下一次观察时，它会停止扫描，并在周期重置后恢复。达到上限期间跳过的会话之后不会补扫。
• 如果用户用观察次数表示上限（“达到 200 次观察后停止”），目前没有次数上限字段。将次数乘以该扫描器所用 model 的 credits_per_observation，设置 credit_limit（估算结果和扫描器响应中都会返回此值），并告知用户设置的积分数。上限始终以积分计，因此之后更换模型时，积分数不变，但可覆盖的观察次数会改变。

这里的确认是对话中的步骤，并非 API 功能 — 说明取舍并让用户选择。当预计支出明显低于预算时，无需征求确认。

第 4 步：创建

调用 vision-scanners-create。最简示例：

{
  "name": "Rage click monitor",
  "scanner_type": "monitor",
  "scanner_config": { "prompt": "Flag sessions where the user repeatedly clicks the same element in frustration." },
  "query": { "kind": "RecordingsQuery", "events": [{ "id": "$rageclick", "type": "events" }] },
  "sampling_rate": 1.0,
  "sampling_mode": "comprehensive",
  "model": "gemini-3-flash-preview",
  "enabled": true
}

name 在团队内必须唯一。如果用户想先暂停创建（不设置计划、不消耗配额），之后再启用，请设置 enabled: false。

另一个值得了解的开关是 emits_signals: true：它会在提示词中加入 Signals 支线任务，并将每条发现作为一个信号推送到 PostHog Signals 收件箱，让不同会话中的发现相互印证并汇总成报告。如果用户希望扫描器将发现发送到收件箱，而不是只积累需要他们自行查看的观察结果，请启用此项。

创建后

• 从响应中展示扫描器的 PostHog URL，方便用户在界面中查看。
• 结果需要几分钟才会出现（将录制内容光栅化为视频以及大模型调用都比较慢）。如需查看某个扫描器随时间产生的结果，请使用 vision-scanners-observations-list；如需查看单个会话中所有扫描器的发现，请使用 vision-observations-list（需要 session_id）。如需深入调查录制内容，请转交给 investigating-replay 技能。
• 历史记录需要主动启用。 新扫描器只会查看从现在开始的录制内容。如需覆盖过去的记录，请先针对相应时间范围运行 vision-scanners-backfills-estimate，告知用户 total_sessions 和 total_credits，并且只有在用户同意后，才调用 vision-scanners-backfills-create，同时将该 total_credits 作为 max_total_credits 传入。如果因当前时间范围的费用更高而导致创建被拒绝，请重新估算并再次征求用户同意。使用 vision-scanners-backfills-get 查看进度。
• 有数据后再创建仪表板。 当 vision-scanners-get 返回 dashboard_suggested: true 时（扫描器已有足够的观察结果，且尚无仪表板），主动提议一次使用 vision-scanners-dashboard-create 创建仪表板。如果用户拒绝，不要重复提议。全新的扫描器不会触发建议，因为还没有可用于绘图的数据。
• 通知与摘要。 vision-alerts-create（以及一个目标地址）会在发现问题时发送通知；vision-scanners-scouts-create 会添加定时侦察任务，生成关于扫描器发现的报告。
• 说明如何改进扫描器。 初始提示词只是猜测，第一次扫描才能对其进行修正。告诉用户使用 vision-observations-label-create 对结果点踩或点赞，并说明扫描器做对或做错了什么。大多数扫描器从未被评分，因此会一直基于最初的猜测运行。exploring-replay-vision-observations 技能介绍了这一反馈流程。

更新现有扫描器

vision-scanners-update 支持部分更新——只发送发生变化的字段。每当扩大范围或提高费用时，都要重新执行第 3 步的合理性检查：更宽泛的 query、更高的 sampling_rate、限制更宽松的 sampling_mode，或价格更高的 model，都会增加月度开销，和新建一个范围较广的扫描器一样。 切换 enabled、调整提示词或缩小查询范围，无需重新估算。 如果更改带有 credit_limit 的扫描器的 model，积分数量会保持不变，因此上限覆盖的观察结果数量也会发生变化。告知用户新的数量，并询问他们是否想调整 credit_limit 以保持原来的数量。编辑配置会更新 scanner_version；过去的观察结果仍会保留旧配置的快照。

注意事项

• 每个（扫描器，会话）组合只有一条观察结果。 对已观察过的会话重新运行扫描器——即使之前的观察结果失败或不符合条件——也不会执行任何操作，因此不会产生新的扫描结果。使用 vision-observations-retry 替换失败或不符合条件的观察结果。
• 不符合条件 ≠ 失败。 观察结果可能为 ineligible（例如 too_short、no_recording）——这是终止状态，但不属于错误。排查扫描器为何没有产生结果时，请检查 error_reason。
• 当前版本仅支持 Google/Gemini 作为提供商/模型。