integration-advisor

集成顾问

用途

引导用户从“我想连接 X”到完成配置并运行集成。除了基本的增删改查，还会建议使用哪种工作流、如何智能地映射字段，以及如何根据用户的特定使用场景配置集成。Lytics 有 110 多个提供商，各自使用不同的身份验证方式、配置结构和字段映射模式，顾问会帮助用户理清这些复杂情况。

支持：

• 导出：“将我的高价值受众导出到 Facebook Custom Audiences”
• 导入：“从 Salesforce 导入联系人”
• 丰富数据：“使用 Clearbit 数据丰富用户档案”

环境

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

集成架构

集成采用三层模型：

Provider -- what platform
  → Auth -- how to authenticate
    → Connection -- optional, for data source integrations
      → Job -- what to do, runs a specific workflow

流程

步骤 1：了解目标

对用户意图进行分类：

• 平台名称（Facebook、Salesforce、Google 等）
• 方向：导入、导出或丰富数据
• 数据类型：受众、事件、用户档案、转化
• 是否提及特定细分群体

步骤 2：查找提供商

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

按名称查找匹配的提供商。如果存在多个匹配项，请显示匹配的提供商并让用户选择。注意提供商是否显示 is_connected: true（表示已经存在身份验证）。

步骤 3：检查现有身份验证和连接

# Check for existing auth credentials
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/auth" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# Check for existing connections
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/connection" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

• 如果该提供商已有有效的身份验证，则计划复用
• 如果已存在连接，检查它是否适用
• 如果没有身份验证，则根据身份验证方式指导用户：

身份验证方式	指引
OAuth2	“你需要在浏览器中完成 OAuth 流程。请前往 Lytics UI 中的 Settings > Integrations > [Platform] 进行授权。连接成功后，我就可以为你设置作业。”
API Key	“你需要获取 [Platform] 的 API 密钥。拿到后，我可以创建身份验证。”
凭据	“你需要提供 [Platform] 的用户名和密码。”

重要：无法在 CLI 中完成 OAuth 流程。务必引导用户前往 Lytics UI 进行 OAuth 授权，然后通过 API 获取已创建的 auth_id。

步骤 4：推荐工作流

每个提供商可能有多个工作流。请根据用户的目标推荐合适的工作流：

如果有多个工作流都适用，请说明各自的优缺点：

“Facebook 有两种导出选项：

1. Custom Audiences —— 将细分群体同步为 Facebook 受众，用于广告定向
2. Conversion API —— 发送转化事件，用于归因

针对你重新触达流失用户的目标，Custom Audiences 是更合适的选择。”

步骤 5：分析字段映射

对于导出 —— 将 Lytics 架构与目标平台接受的字段交叉比对：

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

根据字段名称相似度和类型兼容性建议映射。检查目标细分群体中的字段覆盖率，以预测匹配率：

“我会将以下 Lytics 字段映射到 Facebook：

• email -> EMAIL（覆盖率为 92%，有助于提高匹配率）
• first_name -> FN（覆盖率为 85%）
• last_name -> LN（覆盖率为 85%）
• phone -> PHONE（覆盖率为 45%，可用于补充匹配）”

对于导入 —— 扫描外部数据源架构：

# List tables in the connection
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/connection/${CONNECTION_ID}/schema" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# Get column schema for a specific table
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/connection/${CONNECTION_ID}/schema/${TABLE}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# Sample data to verify
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/connection/${CONNECTION_ID}/scan" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT * FROM table LIMIT 5", "primary_keys": ["user_id"]}'

建议将外部列映射到 Lytics 架构字段：

• 根据名称相似度自动匹配（例如，email_address -> email）
• 标记可能的身份字段（email、user_id、phone）
• 对未映射字段发出警告，并建议是否包含这些字段

步骤 6：检查细分群体（用于导出）

如果用户提到了细分群体，请验证它是否存在：

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

如果用户未指定用于导出的细分群体，请建议：

“你需要一个细分群体才能进行导出。需要我帮你创建一个吗？我可以分析你的数据，并为你的目标推荐最合适的受众。” 然后转交给 audience-advisor skill 或 audience-builder skill。

步骤 7：构建作业配置并确认

组装完整的作业配置，并按照确认门模式呈现：

## Proposed Integration: Export High-Value Users to Facebook Custom Audiences

**Workflow**: facebook_custom_audiences
**Auth**: Facebook OAuth (connected as [email protected])
**Segment**: High Value Customers (12,400 users)

**Field Mappings**:
  email -> EMAIL
  first_name -> FN
  last_name -> LN

**Schedule**: Continuous sync

然后显示原始 API 负载：

{
  "name": "Export High Value to Facebook",
  "workflow": "facebook_custom_audiences",
  "config": {
    "segment_id": "abc123",
    "field_mappings": { ... }
  },
  "auth_ids": ["auth_456"]
}

步骤 8：经批准后执行

按依赖顺序创建资源：

# Create job
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/job/${WORKFLOW}" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ ... approved config ... }'

对于需要新连接的导入，先创建连接：

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/connection" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ ... connection config ... }'

步骤 9：验证

创建后，检查作业状态：

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

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

报告初始状态并建议持续监控：

“作业已创建并正在运行。初始状态：active。几分钟后查看首次同步结果，或之后让我检查作业状态。”

常见集成模式

目标	工作流类型	关键配置
在广告中重新定位受众	Export - Custom Audiences	segment_id、字段映射
发送转化事件	Export - Conversion API	事件映射、像素/标签 ID
导入 CRM 联系人	Import - Contact sync	对象类型、字段映射、身份字段
导入行为事件	Import - Event stream	事件类型、时间戳字段
同步到电子邮件平台	Export - List sync	segment_id、列表 ID、字段映射
导出到数据仓库	Export - Table write	数据集、表、写入模式、分区

字段映射启发式规则

常见的 Lytics 到平台字段映射：

Lytics 字段	Facebook	Google Ads	Salesforce	通用
email	EMAIL	hashedEmail	Email	email
first_name	FN	firstName	FirstName	first_name
last_name	LN	lastName	LastName	last_name
phone	PHONE	hashedPhone	Phone	phone
country	COUNTRY	countryCode	MailingCountry	country
city	CT	city	MailingCity	city
zip	ZIP	zipCode	MailingPostalCode	postal_code

错误处理

• 未找到提供商：列出类似的提供商，并请用户澄清
• 不存在身份验证：引导用户前往 Lytics UI 设置 OAuth，或协助创建 API 密钥身份验证
• 身份验证已过期：建议在 Lytics UI 中重新授权
• 没有匹配的工作流：列出该提供商可用的工作流
• 未找到细分：建议使用 audience-builder 或 audience-advisor 创建一个
• 连接扫描失败：检查身份验证凭据，以及对外部系统的网络访问
• 作业创建失败：解析错误，并检查必需的配置字段

依赖项

• 组合使用：connection-manager skill、job-manager skill、schema-discovery skill、../references/confirmation-gate.md
• 参考：../references/auth.md
• 相关：audience-advisor skill、audience-builder skill（用于创建要导出的细分）