planning-user-interviews

规划用户访谈

当有人要求安排用户访谈时使用此技能，以便通过语音对话与客户交流、了解他们的感受或收集定性反馈。访谈计划会记录为 UserInterviewTopic，之后由语音 Agent 执行。

完整的主题需要包含哪些内容

调用 user-interview-topics-create 前，先收集以下信息：

1. 访谈对象 — 至少提供以下一项：
   • interviewee_emails — 电子邮件地址列表
   • interviewee_distinct_ids — PostHog distinct ID 列表
2. 访谈内容 — topic（必填的自由文本）
3. Agent 应如何引导对话 — 可选的 agent_context（额外的系统提示词）
4. 需要依次讨论的问题 — 可选的有序 questions 列表

主题会在创建时保存目标受众的快照，不会动态关联 cohort。如果用户指定了 cohort，你（Agent）需要在调用 user-interview-topics-create 前，将 cohort 成员解析为电子邮件地址／distinct ID。有关解析流程和 500 名成员上限的交互说明，请参阅步骤 2。

API 会拒绝没有目标受众的主题，因此最终的 interviewee_emails 和／或 interviewee_distinct_ids 必须非空。

步骤 1：明确意图

如果请求含糊不清，请询问：

• 要了解哪项功能或行为？ “结账”可能指点击按钮、查看页面或提交付款——请将范围缩小到一个事件。
• 你想了解什么？ 他们为何离开？什么让他们感到困惑？他们尝试过哪些替代方案？目标会影响受众和问题的设计。
• 哪些类型的用户？ 高频用户（哪些方面有效）、中途退出的用户（哪些因素阻碍采用）、有流失风险的用户（哪些因素影响留存），或以上几类的组合。

只有在用户已经回答这些问题时，才跳过询问。

步骤 2：选择受众

根据用户的描述，选择以下一种路径：

• 用户指定了 cohort（“我们的重度用户”“上周注册试用的用户”）——使用 cohorts-list（或通过 system.cohorts 执行 SQL 搜索）查找 cohort，确认匹配后，将 cohort 成员解析为电子邮件地址／distinct ID（参阅下文“解析 cohort”）。
• 用户描述了某类人，但不存在对应的 cohort——提供两种选择：先创建 cohort（cohorts-create），然后进行解析；或改为按行为查找用户（见下文）。
• 用户提供了电子邮件地址或 distinct ID——直接接受，无需查找 cohort。
• 用户描述了行为，而非 cohort（“尝试结账但未完成的用户”“过去使用深色模式、后来停止使用的人”）——通过查询他们的事件来查找（见下文）。
• 用户描述含糊（“一些客户”“一些重度用户”）——询问他们更倾向于哪种方式：
  • 选择现有 cohort → cohorts-list
  • 按姓名或电子邮件查找特定人员 → persons-list 并提供搜索查询
  • 按行为查找用户 → 见下文
  • 粘贴电子邮件地址列表

每个电子邮件地址都会经过 DRF 电子邮件验证（除纯地址 [email protected] 外，也接受显示名称格式 Paul D'Ambra <[email protected]>）。

解析队列

主题会在创建时快照其受众。用户选择队列后，必须先将成员列表写入 interviewee_emails（没有邮箱的成员则写入 interviewee_distinct_ids），再创建主题。

1. 先统计队列人数。 这是开销较小的查询，用于决定下一步：

   SELECT count() FROM persons WHERE id IN COHORT <cohort_id>
   

2. **如果队列成员不超过 500 人，**则获取他们的邮箱：

   SELECT properties.email AS email
   FROM persons
   WHERE id IN COHORT <cohort_id> AND properties.email IS NOT NULL
   LIMIT 500
   

   将每一行写入 interviewee_emails。去重。

   默认不包含没有邮箱属性的队列成员——persons.id 列是人员 UUID，不是 SDK distinct_id，因此如果不通过 pdi.distinct_id 进行联接，就不能将它用作 interviewee_distinct_id。如果确实需要联系仅以 distinct ID 存在的成员，请先询问用户，然后再显式执行联接。

3. **如果队列成员超过 500 人，**请停止并询问用户。不要默默截断、抽样或改用其他队列——需要由用户做出选择。说明以下信息：

   • 队列名称和人数（例如：“PostHog Team 有 28,563 名成员，超过 500 人的上限。”）
   • 设置上限的原因（“我们会在创建时快照受众；500 人是 Agent 端设置的防护上限，目的是让单个访谈活动保持可管理规模——后端本身不会限制数组长度。”）
   • 用户可以选择：
     • 缩小队列范围——描述他们实际需要的子集（例如“仅工程师”“过去 30 天内活跃的成员”）。你可以提出编写更具体的 HogQL 筛选条件，或通过 cohorts-create 创建新的、更小的队列。
     • 随机抽样——确认人数（例如 200），并在队列查询中使用 ORDER BY rand() LIMIT <n>。明确说明是随机抽样，让他们知道选出的并非“排名靠前”的成员。
     • 粘贴筛选后的名单——由用户接手，直接提供邮箱。

   与用户确定方案后，重新执行解析。没有得到明确决定前，绝不要继续。

4. 告知用户解析结果。 解析完成后、创建主题之前，先确认：“队列 ‘X’ 有 N 名成员，解析得到 E 个邮箱和 D 个 distinct ID（快照——队列后续发生变化时不会更新）。”这样可以明确告知用户快照语义。

按行为查找用户

当用户用行为描述他们想交谈的对象时，请在项目自身的数据中查找：

1. 找到合适的事件。 调用 read-data-schema，列出项目中实际存在的事件。不要根据训练数据猜测事件名称——PostHog 事件分类是针对各项目定制的。将用户的描述与一两个候选事件匹配；如果有多个合理的匹配项，请列出并询问用户关注哪种行为。
2. 查询用户。 使用 HogQL 调用 execute-sql。筛选过去 60 天内所选事件，按 person 分组——优先使用 person.properties.email（可直接用于 interviewee_emails），其次使用 distinct_id（用于 interviewee_distinct_ids）。保留两种类型的行。每个模板中的聚合字段（event_count、last_seen、days_since_last_seen）将为第 5 步提供每位受访者的上下文。将 <event_name> 替换为所选事件，将 <id> 替换为 person.properties.email 或 distinct_id：
   • 重度用户 — SELECT <id> AS id, count() AS event_count, max(timestamp) AS last_seen, dateDiff('day', max(timestamp), now()) AS days_since_last_seen FROM events WHERE event = '<event_name>' AND timestamp > now() - INTERVAL 60 DAY GROUP BY <id> HAVING count() >= 5 ORDER BY count() DESC LIMIT 20
   • 流失用户（尝试过一两次后就再也没回来）— SELECT <id> AS id, count() AS event_count, max(timestamp) AS last_seen, dateDiff('day', max(timestamp), now()) AS days_since_last_seen FROM events WHERE event = '<event_name>' AND timestamp > now() - INTERVAL 60 DAY GROUP BY <id> HAVING count() <= 2 AND dateDiff('day', max(timestamp), now()) > 14 ORDER BY count() ASC LIMIT 20
   • 有流失风险的用户（曾经活跃，如今已沉寂）— SELECT <id> AS id, count() AS event_count, max(timestamp) AS last_seen, dateDiff('day', max(timestamp), now()) AS days_since_last_seen FROM events WHERE event = '<event_name>' AND timestamp > now() - INTERVAL 60 DAY GROUP BY <id> HAVING count() >= 3 AND dateDiff('day', max(timestamp), now()) > 14 ORDER BY days_since_last_seen DESC LIMIT 20
3. 构建均衡的样本。 除非用户指定了某个细分群体，否则混合选取 5 名重度用户、3 名流失用户和 2 名有流失风险的用户，可以让访谈最具行动价值：了解哪些做法有效、哪些因素阻碍用户采用，以及哪些问题导致用户留存率下降。根据用户的实际需求调整人数。

将邮箱行作为 interviewee_emails 传入，将 distinct ID 行作为 interviewee_distinct_ids 传入——两者可以针对同一主题同时设置。保留每个人的 event_count 和 days_since_last_seen，这样第 5 步便能综合得出上下文，例如“过去 60 天结账了 47 次；2 天前最后一次出现”。

第 3 步：记录主题

topic 是一到两句话，用于说明访谈内容。尽可能根据上下文推断——不要让用户重复说明。

示例：“询问试用用户为何没有转化” → topic: "Why trial users didn't convert in the first 14 days"。

第 4 步：准备语音 Agent

两个字段决定 Agent 在通话中实际会做什么。创建主题前，务必询问这两项。

始终询问：他们想问哪些问题？

questions 是 Agent 依次询问的问题列表。它们是引导方向，而不是照本宣科的脚本——Agent 会灵活调整措辞。问题应保持开放式：

• ✅「是什么让你决定试用 PostHog？」
• ❌「你喜欢 PostHog 吗？」

如果用户在原始请求中已经列出问题，就使用这些问题并向用户确认。否则，明确询问：「你希望 Agent 问哪些问题？」

如果用户一时想不出问题，就根据 topic 提出 3–5 个开放式问题，供用户审核后再创建。

该字段在 API 中实际上是可选的，但不要默默跳过——没有问题的访谈往往没什么用。

按研究目标划分的问题模板：

• 了解用户为何流失：
  • 「说说你上次尝试 [feature] 的情况——你当时想做什么？」
  • 「请按步骤说说当时发生了什么。」
  • 「你预期的情况和实际发生的情况有什么不同？」
  • 「是什么让你停止使用或决定不再继续？」
  • 「需要做出哪些改变，你才会定期使用 [feature]？」
• 了解重度用户为何喜欢某项功能：
  • 「说说你如何使用 [feature]——它帮你解决了什么问题？」
  • 「请说说你通常的工作流。」
  • 「如果没有 [feature]，你会怎么做？」
  • 「你第一次尝试时，有什么差点让你放弃使用？」
  • 「你希望它在哪一点上有所不同？」
• 了解用户为何尚未尝试某项功能：
  • 「你注意到产品中的 [feature] 了吗？」
  • 「是什么让你一直没尝试它？」
  • 「要满足什么条件，你才会觉得值得一试？」

始终提供选项：为访谈提供额外背景信息

agent_context 是可选的，但在这里补充几句话能显著改善对话。始终让用户有机会提供这些信息，例如：

「想给 Agent 提供一些额外背景信息吗？例如语气、需要避免的内容，或受访者的背景，都有助于引导对话。此项为可选。」

有用的背景信息类型：

• 语气：「亲切、自然地交流」「省去寒暄——这是一次 10 分钟的通话」
• 限制：「不要承诺交付功能」「不要讨论定价」
• Agent 应了解的背景：「该用户刚从 Scale 套餐流失，请保持体谅」「此人 6 个月前试用过 PostHog，后来就不再使用了」
• 角色设定：「你是 Sam，一名 PostHog 产品研究员」

如果用户拒绝，也没关系——将 agent_context 留空并继续。

调用 user-interview-topics-create

收集好所需信息后：

{
  "topic": "Why trial users churned in week 2",
  "interviewee_emails": ["[email protected]", "[email protected]"],
  "interviewee_distinct_ids": ["distinct-id-with-no-email"],
  "agent_context": "Be warm. The interviewee just churned — don't pitch.",
  "questions": [
    "What were you hoping PostHog would help with?",
    "Where did you get stuck?",
    "What would have made you stay?"
  ]
}

创建完成后，记录返回的主题 ID——Step 5 和交接给语音 Agent 时都需要它。

Step 5：可选择添加每位受访者的背景信息

主题级别的 agent_context 适用于每位受访者。如果用户了解某位受访者的具体情况，且这些信息应影响与该受访者的对话，请通过 user-interview-topics-interviewees-create 将其作为每位受访者对应的行附加。这是可选步骤——大多数主题都不需要这样做。

每行包含一个 interviewee_identifier（必须与父主题定向对象中的某个电子邮件地址或唯一 ID 相符）和一个 agent_context 字符串。每个（主题、受访者）组合最多对应一行。用户可以不添加任何行。

适用于每位受访者的背景信息示例：

• 「使用回放产品，但从未使用过摘要功能」
• 「上个月从 Scale 套餐流失——请保持体谅，不要推销」
• 「创始人，技术能力很强，跳过基础产品介绍」

Step 4 成功后，询问用户：「要添加每位受访者的背景信息吗？当不同受访者的背景差异很大时，这会很有用。你可以口述各行内容，也可以粘贴 CSV。」

如果你在 Step 2 中通过行为查询找到了受众，就已经掌握了每个人的背景信息（使用次数、休眠时间段）。请利用这些信息：对于重度用户，例如填写 "used checkout 47 times in last 60 days; last seen 2 days ago"；对于流失用户，例如填写 "tried checkout once 18 days ago, never returned"。

接受 CSV 输入

如果用户粘贴了 CSV，预期包含两列：identifier,context。可以有标题行，也可以没有。示例：

[email protected],uses replay but never summarization
[email protected],founder; very technical; skip product basics

或使用标题行：

identifier,context
abc-distinct-id-1,churned from Scale last month — be empathetic

解析 CSV，然后针对每一行调用一次 user-interview-topics-interviewees-create，并传入获取到的 topic_id。跳过空行。按照标准 CSV 规则，对 context 单元格中的逗号进行引号转义。

如果某行的标识符不在父主题的 interviewee_emails 或 interviewee_distinct_ids 中，请在创建前提醒用户：语音 Agent 会通过精确字符串匹配查找上下文，因此标识符不匹配时，运行时会直接忽略该上下文。

边缘情况

• 没有用户符合行为查询条件。 可能的原因包括：事件未触发、日期范围太窄，或者没有用户的个人属性中记录了电子邮件地址。可以建议扩大日期范围、尝试其他事件，或改用群组 / 明确指定的电子邮件地址。
• 用户符合条件，但只有少数人有电子邮件地址。 PostHog 会存储 SDK 捕获的内容。如果匹配用户中只有少数人的个人资料里有电子邮件地址，请告知用户数量，并询问是使用较小的样本、改用 interviewee_distinct_ids（Agent 仍可通过应用内交付触达这些用户），还是跳过行为查询，直接让用户粘贴电子邮件地址。
• 事件名称有歧义。 如果 read-data-schema 返回多个候选项（例如 checkout_started、checkout_completed、checkout_abandoned），请列出候选项及其数量，让用户选择想要了解的行为。不要擅自选择。
• 用户要求只采访流失用户（或只采访某个细分群体）。 这没有问题，但请说明其中的取舍：只采访流失用户能告诉你哪些地方出了问题，却无法告诉你哪些地方运行良好。除非用户有理由缩小样本范围，否则建议加入 2–3 位成功用户进行对比。

此技能不适用于

• 上传已录制的访谈——这属于单独的 UserInterview 模型（使用音频文件调用 user_interviews_create）。流程和模型均不同。
• 列出现有主题——user-interview-topics-list 可直接通过 search、limit 和 offset 处理。无需使用技能。
• 访谈结束后分析文字稿——这不在此处的范围内；应使用已录制的 UserInterview 流程处理。