investigating-replay

调查一次会话录制

当用户询问“这次会话中发生了什么？”或提供录制 ID／会话 ID 进行调查时，应并行收集所有相关上下文，而不是让用户逐项询问。

可用工具

工具	用途
posthog:session-recording-get	录制元数据（时长、计数、状态）
posthog:persons-retrieve	人员资料（属性、不同 ID）
posthog:execute-sql	查询会话中的事件、错误和页面浏览
posthog:query-error-tracking-issues-list	查找与会话关联的错误跟踪问题
posthog:vision-observations-list	检查是否已有 Replay Vision AI 摘要
posthog:vision-observations-get	完整读取一条观察记录（scanner_result）
posthog:vision-scanners-inline-scan	生成会话的 AI 摘要（耗时较长，可选）
posthog:vision-scanners-list	查找已保存的摘要扫描器（scanner_type=summarizer）
posthog:vision-scanners-scan-session	对会话运行已保存的摘要扫描器（耗时较长）

工作流

步骤 1 — 获取录制元数据和人员资料

先查询录制以获取元数据和人员的不同 ID：

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

录制 id 与事件 $session_id 是同一个值。此处用它选择录制，并在步骤 2 中选择同一会话的事件。响应包含 distinct_id、person、start_time、end_time、时长、交互次数、控制台错误数和观看状态。使用 distinct_id 获取完整人员资料：

posthog:persons-retrieve
{
  "id": "<person_uuid_from_recording>"
}

步骤 2 — 查询同一会话的事件

将步骤 1 中的录制 id 用作 $session_id 值。获取用户在会话期间的操作时间线：

posthog:execute-sql
SELECT
    timestamp,
    event,
    properties.$current_url AS url,
    properties.$browser AS browser,
    properties.$os AS os,
    properties.$device_type AS device_type,
    properties.$screen_width AS screen_width
FROM events
WHERE $session_id = '<session_id>'
ORDER BY timestamp ASC
LIMIT 200

对于事件较多的会话，应重点关注信息量最大的事件：

posthog:execute-sql
SELECT
    timestamp,
    event,
    properties.$current_url AS url,
    if(event = '$exception', properties.$exception_values[1], null) AS exception_message,
    if(event = '$exception', properties.$exception_types[1], null) AS exception_type
FROM events
WHERE $session_id = '<session_id>'
    AND event IN ('$pageview', '$pageleave', '$autocapture', '$exception', '$rageclick')
ORDER BY timestamp ASC
LIMIT 100

没有结果？恢复事件会话 ID

录制 id 就是会话 ID。如果没有结果，说明会话事件在写入时未带上该 ID。按照回放事件查询的方式，在录制时间窗口前后各扩展 100 秒，从该人员的事件中查找候选项。person_id 会涵盖此人的所有不同 ID：

posthog:execute-sql
SELECT
    properties.$session_id AS session_id,
    count() AS event_count,
    min(timestamp) AS first_seen,
    max(timestamp) AS last_seen
FROM events
WHERE person_id = '<person_uuid>'
    AND timestamp >= toDateTime('<start_time>') - INTERVAL 100 SECOND
    AND timestamp <= toDateTime('<end_time>') + INTERVAL 100 SECOND
    AND properties.$session_id IS NOT NULL
GROUP BY session_id
ORDER BY event_count DESC
LIMIT 10

只有在某个会话 ID 明确匹配时才继续。仅在步骤 2 和步骤 3 的查询中使用它。回放 URL 和所有 Replay Vision 调用都使用录制 id。

步骤 3 — 检查关联的错误跟踪问题

如果录制中有控制台错误或异常，请查找相关的错误跟踪问题：

posthog:execute-sql
SELECT DISTINCT
    properties.$exception_fingerprint AS fingerprint,
    properties.$exception_types[1] AS type,
    properties.$exception_values[1] AS message,
    count() AS occurrences
FROM events
WHERE $session_id = '<session_id>'
    AND event = '$exception'
GROUP BY fingerprint, type, message
ORDER BY occurrences DESC
LIMIT 10

如果找到指纹，请搜索相应的错误跟踪问题，以提供链接和状态：

posthog:query-error-tracking-issues-list
{
  "searchQuery": "<exception_type or message>"
}

步骤 4 — 综合调查结果

将调查结果整理成连贯的叙述：

1. 谁 — 人员属性（姓名、电子邮件、国家／地区、套餐等）
2. 做了什么 — 浏览页面的顺序和执行的关键操作
3. 问题 — 异常、控制台错误、愤怒点击及其发生频率
4. 相关问题 — 关联的错误跟踪问题及其状态（活跃／已解决）
5. 背景信息 — 会话时长、设备／浏览器、活动评分

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

如果用户想要更深入地分析，而不想手动逐条阅读事件， 可以提供 Replay Vision 摘要。遵循“先检查，再扫描”——不要盲目扫描， 扫描器对同一个会话只能观察一次。

1. 检查是否已有摘要。 定时扫描器可能已经生成了摘要：

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

   返回的行会筛选为 id、session_id、status、summary_line 和 scanner_id。查找 status 为 succeeded 的记录，然后使用 vision-observations-get 完整读取该 id 对应的记录：其中的 scanner_snapshot.scanner_type 会告诉你它是否为 summarizer， 而 scanner_result.model_output 包含 title、summary、intent、outcome、friction_points 和 keywords。如果找到，就可以结束了——无需重新扫描。

2. 生成摘要。 对内置摘要执行一次内联扫描。它与播放器的“总结”按钮执行相同的扫描， 因此你或用户发起的摘要会共享；而自定义提示词则会创建单独的扫描器和单独的摘要。

   posthog:vision-scanners-inline-scan
   {
     "session_ids": ["<session_id>"],
     "built_in": "summarize_recording"
   }
   

   不要填写 model，以使用服务端默认值。告知用户这是异步操作， 需要几分钟时间（栅格化 + LLM）。不会安排任何任务，也无需清理： 内联扫描创建的扫描器不会自行执行扫描。这里出现 400 错误通常意味着 组织尚未批准 AI 数据处理。

3. 轮询前先读取 results[0].scan_outcome。 started 表示轮询 vision-observations-list（步骤 1），直到新观察记录达到 succeeded。 already_scanned 表示已有终态观察记录——通过步骤 1 读取；如果其状态为 failed 或 ineligible，应如实说明，而不是继续轮询。scan_id 为 null 或状态为 skipped_quota 表示没有执行扫描：报告配额情况，不要轮询。

项目已配置摘要扫描器

即便如此，临时摘要也应使用内联扫描。只有当用户想使用已保存扫描器自己的提示词，而非内置提示词时， 才使用已保存的扫描器：

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

向用户展示扫描器（名称 + 提示词），询问要使用哪一个，然后针对该会话运行扫描，并轮询 vision-observations-list，直到观察记录达到 succeeded：

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

切勿为了回答单个问题而创建扫描器——vision-scanners-create 会留下定时扫描任务，而内联扫描不会。

提示

• 尽可能并行执行步骤 1-3——它们是相互独立的查询。
• 如果录制的事件很少，会话很可能非常短。 应说明这一点，而不是暗示出了故障。
• 录制元数据中的控制台错误数有助于判断是否需要深入检查异常。如果为 0，则跳过步骤 3。
• 录制中的 start_url 会告诉你用户旅程的起点—— 用它来组织叙述。
• 如果录制中的 person 为 null，则用户是匿名用户。 无法获取用户属性，但仍可查看事件。

相关技能

• finding-sessions-to-watch — 首先选择值得调查的会话
• finding-replay-for-issue — 从错误跟踪问题入手，查找关联的录制
• diagnosing-missing-recordings — 预期存在的录制却未出现时使用
• creating-replay-vision-scanners — 将此类观看自动化为定时扫描器