export-debugger

导出调试器

用途

诊断特定用户为何被导出或未被导出到外部平台。追踪完整的导出流程：分群归属 -> 任务状态 -> 流程状态 -> 静默时段 -> 导出日志。只读诊断。

环境

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

输入

• 用户身份（字段 + 值，例如 email [email protected]）
• 导出目标：任务 ID、任务名称、平台名称或流程名称
• 表（默认值：user）

诊断流程

步骤 1：确定导出任务

如果用户提供了任务 ID，直接获取该任务。否则，查找相关任务：

# List all jobs to find the export
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/job" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

按名称、工作流类型或平台进行匹配。从任务的 config 字段中提取 segment_id——这是该任务导出的来源分群。

如果用户提到某个流程，获取该流程并追踪到导出步骤：

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/flow/ui/${FLOW_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

查找 type_hint: "work_export" 的步骤，并获取其 work_id 以确定导出任务。

步骤 2：检查用户的分群归属

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

检查：用户是否属于导出任务的目标分群？

• 是 -> 继续步骤 3（任务应会导出该用户）
• 否 -> 这很可能就是原因。使用 profile-investigator skill 说明用户为何不在该分群中。

步骤 3：检查任务状态

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/job/${JOB_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

状态	诊断
runnable	任务处于活动状态——检查日志以了解导出详情
sleeping	任务处于两次运行之间。检查 sleep_until——可能处于静默时段或预定延迟期间
paused	任务已暂停。用户或系统暂停了任务——导出已停止
fault	任务出现错误。检查日志中的错误详情
failed	任务已彻底失败。检查日志以查明根本原因
killed	任务已被手动停止

步骤 4：检查静默时段

如果任务设有静默时段，请计算当前是否处于静默时段：

在任务响应中检查以下字段：

• quiet_time_of_day ——例如，“2:00pm”
• quiet_timezone ——例如，“America/Los_Angeles”
• quiet_period ——静默时长（小时），例如 4

如果这三个字段都已设置，请计算：

Quiet window: quiet_time_of_day to (quiet_time_of_day + quiet_period hours)
              in the configured timezone

Example: 2:00pm - 6:00pm America/Los_Angeles

如果当前时间处于静默时段内，任务将进入休眠状态，并且在该时段结束前不会导出。检查任务响应中的 sleep_until 以确认。

如果 drop_events_during_quiet_window 为 true，则静默时段内到达的事件会被永久丢弃，而不会排队等待处理。

步骤 5：检查流程状态（适用于基于流程的导出）

如果导出由流程触发，请检查用户当前所在的步骤：

步骤 2 中的实体响应包含 flows_step_slugs：

{
  "flows_step_slugs": {
    "flow_id-1": "welcome_email_step"
  }
}

对照流程的步骤列表，确定：

• 用户是否已到达导出步骤？（可能仍处于延迟步骤或更早的步骤）
• 用户是否在到达导出步骤前退出了流程？
• 用户是否处于不会导向导出的条件分支中？

步骤 6：检查任务日志

调试时始终使用 include_errors=true，以获取完整的错误详情：

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/job/${JOB_ID}/logs?include_errors=true" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

查找以下信息：

• 导出数量：日志上下文中的 added、omitted、removed
• 错误：目标平台的速率限制、身份验证失败、API 错误
• 时间戳：任务上次成功运行的时间
• 用户级错误：某些平台会报告单个用户的失败（例如，电子邮件格式无效）

输出格式

## Export Debug Report

### User: [email protected]
### Destination: Facebook Custom Audiences (job: "fb_export_high_value")

### Diagnostic Results

1. SEGMENT MEMBERSHIP: PASS
   User IS in segment "High Value Customers" (id: seg123)

2. JOB STATUS: PASS
   Job is "runnable" -- actively processing

3. QUIET WINDOW: FAIL
   Job is currently in quiet window (2:00pm - 6:00pm PT)
   Will resume at: 6:00pm PT (2026-03-19T01:00:00Z)
   drop_events_during_quiet_window: false (events are queued)

4. FLOW STATE: N/A
   Export is not flow-based

5. JOB LOGS: INFO
   Last export: 2026-03-19 09:45:00 UTC
   Added: 145, Omitted: 3, Removed: 12
   No errors in recent logs

### Diagnosis
The user IS in the export segment and the job is active, but the job
is currently in its quiet window (2:00pm-6:00pm PT). The user should
be exported when the job resumes at 6:00pm PT. Events are being
queued, not dropped.

常见诊断

症状	可能原因	解决方法
用户不在分群中	未满足 FilterQL 条件	使用 profile-investigator 查看哪些条件未满足
作业已暂停	手动暂停或自动暂停	恢复作业
作业发生故障	身份验证已过期、达到速率限制、API 错误	检查日志，修复身份验证问题，或等待速率限制重置
作业休眠中	静默时段或计划延迟	等待静默时段结束
用户处于错误的流程步骤	延迟步骤或条件分支	检查流程结构和时间安排
用户已导出但未显示	平台同步延迟	检查平台端，可能需要几分钟到几小时
日志中显示 “Omitted”	用户被导出配置筛除	检查作业配置中除分群以外的其他筛选条件

错误处理

• 未找到作业：列出作业并帮助用户确定正确的作业
• 未找到用户：尝试其他身份字段
• 同一平台存在多个导出作业：全部列出并请用户选择
• 无可用日志：作业可能是新建的，或日志可能已过期

依赖项

• 组合使用：job-manager skill、entity-lookup skill、segment-manager skill、flow-manager skill
• 相关：profile-investigator skill（用于诊断分群成员资格）
• 参考：../references/auth.md、../references/api-client.md