finding-replay-for-issue

查找适用于错误跟踪问题的最佳回放

当用户说“给我看看这个错误的回放”或“查找问题 X 的录制内容”时， 目标不只是找到任意关联会话，而是找到最能展示错误发生原因的会话。 热门问题可能关联数百个会话，其中大多数只是崩溃片段 或重复事件。这项技能会挑选出最有用的会话。

可用工具

工具	用途
posthog:query-error-tracking-issue	获取问题详情（指纹、状态、数量）
posthog:execute-sql	查询异常事件，查找关联会话
posthog:query-session-recordings-list	获取候选会话的录制元数据
posthog:session-recording-get	获取所选录制的完整详情
posthog:vision-observations-list	检查是否已有 Replay Vision AI 摘要
posthog:vision-scanners-list	查找摘要扫描器（scanner_type=summarizer）
posthog:vision-scanners-scan-session	对录制运行摘要扫描器（可选，速度较慢）

工作流

步骤 1 — 获取问题详情

获取错误跟踪问题，了解要查找的内容：

posthog:query-error-tracking-issue
{
  "issueId": "<issue_id>"
}

记下问题的 fingerprint、name 和 description——你需要使用指纹 查找关联会话。

步骤 2 — 查找出现此错误的会话

查询异常事件，获取发生此错误的会话 ID。 按时间先后排序，并包含基本上下文：

posthog:execute-sql
SELECT
    $session_id AS session_id,
    count() AS occurrences,
    min(timestamp) AS first_seen,
    max(timestamp) AS last_seen,
    any(properties.$current_url) AS url
FROM events
WHERE event = '$exception'
    AND properties.$exception_fingerprint = '<fingerprint>'
    AND $session_id IS NOT NULL
    AND timestamp > now() - INTERVAL 30 DAY
GROUP BY session_id
ORDER BY last_seen DESC
LIMIT 20

这会提供最多 20 个候选会话。候选会话越多，选择就越理想。

步骤 3 — 为候选项排序

获取候选会话的录制元数据，为其排序：

posthog:query-session-recordings-list
{
  "session_ids": ["<id1>", "<id2>", "<id3>", ...],
  "date_from": "-30d"
}

先筛除不合适的候选项，再为剩余项排序，选出最佳录制：

筛除：

• 时长不足 10 秒的会话（只有崩溃片段，没有错误发生前的上下文）
• 时长超过 1 小时的会话（要加载的数据太多，错误就像大海捞针）

排序依据：

1. 理想时长——2-15 分钟为宜。足以展示用户在错误发生前的操作过程， 也足够简短，便于观看或生成摘要。
2. 活跃时间占比——比较 active_seconds 和 recording_duration。一段 20 分钟的 录制只有 10 秒活跃时间，说明标签页大多处于闲置状态——用户离开了。 优先选择 active_seconds / recording_duration 高于 0.3（30%）的会话。
3. 活动评分——activity_score 越高，说明用户交互越活跃， 而非处于闲置状态。这样的会话更值得观看。
4. 时间新近度——越近期的会话越能反映应用当前的行为。

步骤 4 — 展示查找结果

获取所选录制的完整详情：

posthog:session-recording-get
{
  "id": "<best_recording_id>"
}

向用户展示：

• 录制内容及其观看链接
• 选择原因——简要说明为何选择此录制（“出现该错误的最长会话， 用户在遇到错误前浏览了 3 个页面”）
• 错误发生前的上下文——用户访问过的页面和异常发生前的关键操作， 根据步骤 2 中的事件查询结果（url 和 first_seen 列）得出
• 错误频率——该错误在此会话中发生的次数

可选：通过 Replay Vision 生成 AI 摘要

如果用户想要文字总结而不想观看，请使用 Replay Vision — “先检查再扫描”，因为扫描器只能观察给定会话一次。

1. 检查所选录制内容是否已有摘要：

   posthog:vision-observations-list
   {
     "session_id": "<best_recording_id>"
   }
   

   如果某条观察记录的 scanner_snapshot.scanner_type 为 summarizer，且 status 为 succeeded，请读取 scanner_result.model_output（title、summary、 intent、outcome、friction_points、keywords）——完成。

2. 查找摘要扫描器（如果不存在）：

   posthog:vision-scanners-list
   {
     "scanner_type": "summarizer"
   }
   

   找到一个 → 使用它。找到多个 → 询问用户选择哪一个（展示名称 + 提示词）。没有 → 提议通过 creating-replay-vision-scanners 技能创建一个。

3. 使用选定的扫描器扫描录制内容（异步，耗时数分钟）：

   posthog:vision-scanners-scan-session
   {
     "id": "<scanner_id>",
     "session_id": "<best_recording_id>"
   }
   

4. 检索结果：轮询 vision-observations-list，直到状态为 succeeded。

提示

• 如果所有候选会话都很短（<10 秒），错误可能会导致页面立即崩溃。请注明这一点——即使没有较长的回放记录，这也是有用的背景信息。
• 如果与问题关联的会话很少（<3 个），请跳过排序，直接展示现有内容，并注明样本量较小。
• 如果许多异常事件的 $session_id 为 null，则受影响用户可能未启用会话回放。请将此作为可能的缺失情况提及。
• Replay Vision 没有单次调用的焦点参数——摘要扫描器的焦点由其自身提示词决定。对于聚焦错误的摘要，优先选择（或创建）提示词针对错误/异常上下文而非整个会话的摘要扫描器。

相关技能

• investigating-error-issue — 定量分析：同一问题的发生量、细分情况和堆栈跟踪
• investigating-replay — 深入调查一个关联会话
• diagnosing-missing-recordings — 异常事件没有 $session_id 或关联录制内容已丢失时使用