profile-investigator

Profile Investigator

用途

深入诊断和探索用户档案。可回答以下问题：

• “为什么这个用户属于细分 X？”
• “为什么这个用户不属于细分 Y？”
• “这个用户发生了什么？”（数据沿袭）
• “这个用户是什么样的？”（完整用户档案及所属细分）

它不止是基本的用户档案查询，还会将用户档案数据与细分 FilterQL 交叉核对，明确指出哪些条件匹配或不匹配。

环境

需要经过身份验证的 API 访问权限。凭证解析方式请参阅 ../references/auth.md。

输入

• 身份字段和值（例如，email、[email protected]）
• 细分名称或 ID（用于诊断成员关系）
• 或用自然语言提出诊断问题

诊断流程

流程 A：“为什么这个用户属于／不属于细分 X？”

第 1 步：查找用户档案

获取包含细分成员关系的完整用户档案：

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/entity/user/${FIELD}/${VALUE}?segments=true&allsegments=true" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

返回内容包括：

• 所有用户档案字段及其值
• segments——用户所属细分的名称列表
• segments_all——所有细分 ID 的列表

立即检查：目标细分是否在成员列表中？

第 2 步：获取细分的 FilterQL

获取细分及其完整解析后的 FilterQL（所有 INCLUDE 指令均已内联）：

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment/${SEGMENT_ID}?inline=true" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

ql_resolved 字段包含完整的筛选表达式，其中的嵌套细分已展开。

第 3 步：根据用户档案评估每个条件

将 FilterQL 解析为各个条件，并根据用户档案中的实际字段值逐一检查。

对于 FilterQL 中的每个条件，按以下方式报告：

如果用户属于该细分：

## Why [email protected] IS in "High Value Customers"

FilterQL: FILTER AND (visit_count >= 5, email_engagement > 0.3, country = "US") FROM user

All conditions PASS:
  visit_count >= 5        PASS  (actual: 12)
  email_engagement > 0.3  PASS  (actual: 0.72)
  country = "US"          PASS  (actual: "US")

如果用户不属于该细分：

## Why [email protected] is NOT in "High Value Customers"

FilterQL: FILTER AND (visit_count >= 5, email_engagement > 0.3, country = "US") FROM user

Condition results:
  visit_count >= 5        PASS  (actual: 12)
  email_engagement > 0.3  FAIL  (actual: 0.15, required: > 0.3)
  country = "US"          PASS  (actual: "US")

The user fails the email_engagement condition. Their value (0.15) is below
the threshold (0.3). This is the reason they are excluded from the segment.

第 4 步：检查包含的细分

如果 FilterQL 通过 INCLUDE 引用了其他细分，也要检查用户是否属于这些细分：

Segment "High Value Customers" includes "Email Subscribers":
  Email Subscribers membership: YES

  Combined evaluation:
    INCLUDE Email Subscribers   PASS
    visit_count >= 5            PASS  (actual: 12)
    last_purchase > "now-90d"   FAIL  (actual: 2025-01-15, ~63 days ago -- outside 90d window)

流程 B：“这个用户发生了什么？”（数据沿袭）

第 1 步：以 Explain 模式获取实体

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/entity/user/${FIELD}/${VALUE}?explain=true" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

返回内容包括：

• entity——解析后的用户档案
• fragments——数据片段数组，显示每条数据的来源
• keys——来源引用（片段别名）

第 2 步：展示数据沿袭

## Data Lineage: [email protected]

### Identity Resolution
Linked identities:
  email: [email protected]
  _uid: abc-def-123
  user_id: 98765

### Data Sources (N fragments)
Fragment 1: stream "web_events" (last seen: 2026-03-18)
  -> visit_count, pages_viewed, last_visit, referrer

Fragment 2: stream "salesforce_contacts" (last seen: 2026-03-15)
  -> first_name, last_name, company, phone

Fragment 3: stream "email_events" (last seen: 2026-03-19)
  -> email_engagement, newsletters, last_email_open

流程 C：完整用户档案摘要

第 1 步：获取用户档案和细分

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/entity/user/${FIELD}/${VALUE}?segments=true&allsegments=true&meta=true" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

第 2 步：展示结构化摘要

## Profile: [email protected]

### Identity
  email: [email protected]
  _uid: abc-def-123

### Key Attributes
  Name: Jane Smith
  Country: US
  Created: 2024-01-15
  Last Active: 2026-03-18
  Visit Count: 12

### Segment Memberships (5 segments)
  - High Value Customers (segment)
  - Email Subscribers (aspect)
  - US Users (aspect)
  - Q1 Campaign (list)
  - Active Last 30 Days (segment)

### NOT in these commonly-checked segments
  [If the user asks about specific segments, show which they're not in and why]

条件评估

将 FilterQL 条件与用户档案数据交叉核对时，请按条件类型处理各个运算符：

FilterQL 条件	检查方法
field = "value"	将用户档案中的字段值与字面值进行比较
field > N	将用户档案中的值进行数值比较
field > "now-Nd"	将用户档案中的日期字段与计算得出的阈值进行比较
EXISTS field	检查用户档案中是否存在该字段且其值非空
NOT EXISTS field	检查该字段是否缺失或为空
field INTERSECTS ("a", "b")	检查用户档案中的集合字段是否包含所列值中的任意一个
field NOT INTERSECTS ("a")	检查用户档案中的集合字段是否不包含所列值中的任何一个
field CONTAINS "substr"	检查用户档案中的字符串字段是否包含该子字符串
field IN ("a", "b")	检查用户档案中的值是否在列表中
INCLUDE segment_slug	检查用户是否属于所引用的细分

对于每个条件，始终显示：

• 条件本身
• PASS 或 FAIL
• 用户档案中的实际值（如果字段缺失，则显示“字段不存在”）
• 对于 FAIL：需要什么值才能通过

错误处理

• 未找到用户档案：尝试其他身份字段，并建议检查拼写。对包含特殊字符的值进行 URL 编码。
• 未找到细分：列出名称相似的细分，并建议检查 slug。
• 复杂 FilterQL：对于嵌套较深的表达式，先评估顶层条件，再深入检查未通过的分支。
• 缺失字段：如果用户档案中不存在 FilterQL 引用的字段，请明确报告——这通常是根本原因。

Dependencies

• Composes: entity-lookup skill, segment-manager skill
• References: ../references/filterql-grammar.md, ../references/auth.md, ../references/api-client.md