SuperAPI AI 工具集

segment-manager

数据与分析

查看项目

更新于 10-16 00:03

技能介绍

Segment Manager 用于 segment 的完整生命周期管理,包括 list、get、create、update、delete、校验 FilterQL 以及估算 segment 大小。使用前需要已认证的 API 访问权限,凭证解析方式见 ../references/auth.md。

主要能力与接口: 列出 segment:GET /v2/segment,查询参数有 table、kind、valid、sizes。 获取 segment:GET /v2/segment/${SEGMENT_ID},参数有 sizes、inline。 获取祖先 segment:GET /v2/segment/${SEGMENT_ID}/ancestors。 创建 segment:POST /v2/segment,JSON 请求体,必填字段含 name、slug_name、description、segment_ql、kind、table、is_public、save_hist,可选字段含 tags、groups、expires_at、emit_trigger、schedule_exit。 更新 segment:PUT /v2/segment/${SEGMENT_ID}。 删除 segment:DELETE /v2/segment/${SEGMENT_ID}。 校验 FilterQL:POST /api/segment/validate,请求体为纯文本 FilterQL,有效返回 200,无效返回错误信息。 估算临时 FilterQL 大小:POST /api/segment/size,请求体为纯文本 FilterQL,非 JSON。 获取已有 segment 大小:GET /api/segment/${SEGMENT_ID}/size。 获取字段信息(受众快照):GET /api/segment/${SEGMENT_ID}/fieldinfo,参数有 fields、limit(默认20,最大1000)、table、cached;详细分析建议使用 audience-snapshot 技能。 重新评估 segment:POST /v2/segment/reevaluate,JSON 请求体包含 id。

执行行为:读操作(list、get、size)立即执行并展示结果;写操作(create、update、delete)采用确认门模式:构建完整载荷、展示人类可读摘要、展示原始 API 载荷、等待用户确认、经批准后执行。

校验流程:创建或更新 segment 前先用 /api/segment/validate 校验 FilterQL;若无效则解析错误并尝试修复,最多重试 3 次;有效后用 /api/segment/size 估算大小;在继续前展示校验与大小结果。

错误处理:无效 FilterQL 解析错误并建议修复;slug 冲突(409)建议替代 slug;空 segment(大小为 0)警告并建议放宽条件;segment 过大时提示大小并请用户确认意图。

依赖:../references/auth.md、../references/api-client.md、../references/confirmation-gate.md;参考 ../references/filterql-grammar.md。Segment 类型包括 segment、aspect、goal、list、conversion、metric、managed、candidate。