mcpField
A
audience-builder

audience-builder

github.com/lytics营销与增长449 次安装3 周前更新
代码仓库

关于 audience-builder

audience-builder 将明确的自然语言受众描述转为经过验证、估算规模的细分群体方案，并在确认后创建。它面向已认证的 Lytics API 用户，结合字段发现、FilterQL 构建与验证及规模估算。

主要功能

  1. 01解析受众条件
  2. 02发现匹配的架构字段
  3. 03构建并验证 FilterQL
  4. 04估算细分群体规模
  5. 05创建前请求确认

适用场景

  1. 01根据明确的受众条件创建细分群体
  2. 02创建前查看受众规模
  3. 03按拟议筛选条件更新现有细分群体

MCP 相关

输入未说明 MCP 连接或相关行为。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/lytics/agent-skills --skill audience-builder

安装后在 Claude Code 中输入/audience-builder确认已加载。

详细介绍

受众构建器

用途

主要的端到端技能。接收自然语言的受众描述，并生成经过验证、规模估算和确认的细分群体。整合 schema-discovery、filterql-builder、segment-manager 和 confirmation-gate。

环境

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

输入

  • 目标受众的自然语言描述
  • 可选：细分群体名称、表（默认值：user）、类型（默认值：segment）、标签

端到端流程

步骤 0：检查 Advisor 是否更合适

如果用户的请求以目标为导向，而不是具体明确（例如，“我想提高转化率”而非“访问过 5 次以上的美国用户”），建议先从 audience-advisor skill 入手：

"听起来你有一个业务目标。你希望我先分析你的数据，再推荐最佳定位策略吗？我可以查看机器学习模型、字段分布和现有细分群体，并据此建议有数据依据的筛选条件。"

如果用户提供了具体的受众描述，则直接继续步骤 1。

步骤 1：解析意图

从自然语言描述中提取关键概念：

  • 目标属性（人口统计信息、行为、属性）
  • 纳入条件（他们拥有或做过什么）
  • 排除条件（他们缺少或没做过什么）
  • 时间限制（基于时间的条件）

示例：“一年多未购买袜子的美国客户”

  • 属性：country = US
  • 排除：未购买袜子
  • 时间：一年多以前
步骤 2：发现架构

使用 schema-discovery skill 查找匹配字段：

# Get all fields to find candidates
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/user/field" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

根据名称匹配度、类型兼容性和值分布为候选字段评分。以上述示例为例：

  • “美国客户” -> 查找：country、geo_country、country_code（字符串类型）
  • “购买过袜子” -> 查找：products_purchased（集合）、purchase_categories（集合）、last_purchase_date（日期）

获取排名靠前的候选字段的值建议——q 参数为必填项：

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

示例：/api/schema/user/fieldsuggest/country?q=US

确认字段值匹配（例如，country 包含“US”，products_purchased 包含“socks”）。

步骤 3：构建 FilterQL

使用 filterql-builder skill 构建筛选表达式。

根据字段类型将每个概念映射到 FilterQL 条件（参见 ../references/field-types.md）：

  • 字符串相等：country = "US"
  • 集合不包含：NOT products_purchased INTERSECTS ("socks")
  • 日期比较：last_sock_purchase < "now-1y"

使用 AND/OR 组合：

FILTER AND (
  country = "US",
  NOT products_purchased INTERSECTS ("socks")
) FROM user ALIAS us_no_socks
步骤 4：验证 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'

如果验证失败：

  1. 解析错误消息
  2. 找出语法问题
  3. 修正 FilterQL
  4. 重试（最多 3 次）
  5. 如果仍然失败，则显示错误并请用户提供指导
步骤 5：估算规模
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'
步骤 6：展示草稿（确认关卡）

创建之前向用户展示完整摘要：

## Proposed Audience: US Non-Sock Buyers

**Name**: US Non-Sock Buyers
**Slug**: us_no_socks
**Table**: user
**Kind**: segment

**Description**: US customers who have not purchased socks

**Field Mapping**:
- "US customers" -> `country = "US"` (field type: string, sample values: US, CA, UK)
- "haven't purchased socks" -> `NOT products_purchased INTERSECTS ("socks")` (field type: []string)

**FilterQL**:
FILTER AND (country = "US", NOT products_purchased INTERSECTS ("socks")) FROM user ALIAS us_no_socks

**Estimated Size**: ~45,000 profiles

然后展示原始 API 负载：

{
  "name": "US Non-Sock Buyers",
  "slug_name": "us_no_socks",
  "description": "US customers who have not purchased socks",
  "segment_ql": "FILTER AND (country = \"US\", NOT products_purchased INTERSECTS (\"socks\")) FROM user ALIAS us_no_socks",
  "kind": "segment",
  "table": "user",
  "is_public": true,
  "save_hist": true,
  "tags": []
}

请求确认：“要继续创建此细分群体吗？（是/否）”

步骤 7：获准后执行
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 ... }'

报告结果：

Successfully created segment "US Non-Sock Buyers" (id: abc123)
View at: ${LYTICS_API_URL}/segment/us_no_socks

创建成功后，询问用户是否需要受众快照： “细分群体已成功创建。你想查看受众快照，了解人口统计信息细分和字段分布吗？” 如果用户回答是，则使用新的细分群体 ID 调用 audience-snapshot skill。

处理歧义

字段映射存在歧义（多个候选字段的匹配度相同）时：

  1. 展示排名靠前的候选字段及其示例值
  2. 让 Agent 根据上下文选择最佳匹配——除非确实存在歧义，否则不要询问用户
  3. 只有在确实无法区分，或字段用途不明确时才询问用户

更新现有细分群体

如果用户想更新现有细分群体：

  1. 获取当前细分群体：GET /v2/segment/${ID}?inline=true
  2. 展示当前 FilterQL 和拟议的更改
  3. 使用 PUT /v2/segment/${ID}，而不是 POST

错误处理

  • 没有匹配字段：清楚地报告，并建议用户用其他方式描述其数据
  • 重试 3 次后仍验证失败：展示 FilterQL 和错误信息，并请求帮助
  • 细分群组为空（大小为 0）：发出警告，并建议放宽筛选条件
  • 细分群组非常大（超过总数的 90%）：指出这一点，并确认用户的意图

依赖项

  • 组合使用：schema-discovery skill、filterql-builder skill、segment-manager skill、../references/confirmation-gate.md
  • 参考：../references/auth.md、../references/filterql-grammar.md、../references/field-types.md

评论

支持 Markdown