audience-builder

用途

Audience Builder 是一个端到端的技能，用于根据自然语言描述创建或更新受众细分（audience segment）。它接收用户对目标受众的自然语言描述，最终产出一个经过验证、估算规模并确认的细分。该技能组合了 schema-discovery、filterql-builder、segment-manager 和 confirmation-gate 等子技能。

主要能力

解析自然语言描述，提取目标属性、包含条件、排除条件和时间约束。
通过 schema-discovery 技能发现匹配的字段，并根据名称匹配、类型兼容性和值分布对候选字段评分。
使用 filterql-builder 技能构建 FilterQL 过滤表达式。
调用 API 验证 FilterQL 语法，失败时最多重试 3 次。
估算细分规模。
在创建前展示完整摘要（确认门），包括字段映射、FilterQL、估算规模及原始 API 载荷，并请求用户确认。
确认后执行创建，并报告结果。
创建成功后可选提供受众快照（audience snapshot）。
支持更新已有细分（使用 PUT 而非 POST）。

使用方式

该技能需要已认证的 API 访问，凭据解析参见 ../references/auth.md。

输入包括：自然语言描述的受众需求；可选参数：细分名称、表（默认 user）、类型（默认 segment）、标签。

端到端流程：

步骤 0：检查是否更适合使用 Advisor。如果用户请求是目标导向而非具体描述，建议先使用 audience-advisor 技能。
步骤 1：解析意图，提取关键概念。
步骤 2：Schema 发现，使用 API 查找匹配字段并获取值建议。
步骤 3：构建 FilterQL。
步骤 4：验证 FilterQL。
步骤 5：估算规模。
步骤 6：展示草稿并请求确认。
步骤 7：批准后执行创建。

涉及的主要 API 调用示例：

获取字段：

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

获取字段值建议：

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/schema/user/fieldsuggest/${FIELD}?q=${QUERY}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

验证 FilterQL：

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/validate" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: text/plain" \
  -d 'FILTER AND (country = "US", NOT products_purchased INTERSECTS ("socks")) FROM user ALIAS us_no_socks'

估算规模：

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/size" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: text/plain" \
  -d 'FILTER AND (country = "US", NOT products_purchased INTERSECTS ("socks")) FROM user ALIAS us_no_socks'

创建细分：

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

更新已有细分：先 GET /v2/segment/${ID}?inline=true 获取当前细分，展示当前 FilterQL 和拟议更改，然后使用 PUT /v2/segment/${ID}。

适用场景

用户希望根据自然语言描述构建、创建或定义受众或细分。
需要将业务描述转化为可执行的过滤条件并验证。
需要估算细分规模并在创建前确认。
需要更新已有细分。

限制

需要已认证的 API 访问。
字段映射存在歧义时，会展示候选字段并让代理根据上下文选择，仅在真正无法确定时才询问用户。
无匹配字段时会报告并建议用户换一种方式描述数据。
验证失败重试 3 次后仍失败，会展示 FilterQL 和错误并请求帮助。
空细分（规模为 0）会警告并建议放宽条件。
超大细分（超过总数 90%）会提示并确认意图。
依赖 schema-discovery、filterql-builder、segment-manager 技能以及 ../references/confirmation-gate.md、../references/auth.md、../references/filterql-grammar.md、../references/field-types.md。

技能介绍

用途

主要能力

使用方式

适用场景

限制