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。 对于分类器，vision-scanners-suggest-tags 会根据项目数据提出标签。

步骤 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（额度；1 个额度 = $0.01；未设上限时为 null）的 remaining 和 exhausted，以及当前周期的 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 次观察后停止”），系统没有次数上限字段。请将 credit_limit 设为次数乘以此扫描器所用 model 的 credits_per_observation（估算结果和扫描器响应都会返回该值），并告知用户设置的额度数值。上限以额度为单位，因此以后更换模型时，额度不变，但可覆盖的观察次数会改变。

此处的确认是对话流程，而不是 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，方便用户在 UI 中查看。
• 结果需要几分钟才会出现（将录制内容栅格化为视频和 LLM 调用都比较慢）。使用 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 提供方和模型。