广告洞察中枢（Ad Insight Hub）

面向广告投放与市场分析场景的结构化广告情报数据中枢。在原始 API 之上叠加参数翻译、依赖编排、缓存复用、可信度标注四层能力，让 Agent 用最少的往返拿到最可用的数据。

设计动机：四大高频痛点

快速开始（< 60 秒）

步骤 0：检查 API Key（不打印值）

[ -n "${ADMAPIX_API_KEY:-}" ] && echo ok || echo missing

步骤 1：缺失时引导配置（中文用户模板）

> 需要先配置 AdMapix API Key：
> 1. 访问 https://www.admapix.com 注册并登录
> 2. 在控制台 API Keys 创建 Key
> 3. 配置方式（任选其一）：
> - 终端环境变量：export ADMAPIX_API_KEY="你的Key"
> - 平台配置命令：参考所用 Agent 平台的密钥管理文档
> 4. 配置完成后重新发起查询

安全红线：永不接受/回显/存储来自聊天输入的 Key；永不将 Key 写入日志或链接参数；Key 仅作为 X-API-Key 请求头使用。

步骤 2：发起第一次查询

curl -s -X POST "https://api.admapix.com/api/data/search" \
  -H "X-API-Key: ${ADMAPIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"keywords":"三消","countries":["US","JP"],"trade_level1":["602"],"page":1,"page_size":10}'

端点目录（按能力域分组）

> 每个端点都是原始数据源。本技能保持"单次请求单端点"的薄客户端语义，但在 Agent 层提供编排能力（见"端点依赖图"章节）。

创意/广告域

元数据/筛选域

> 缓存建议：filter-options、distribute-dims、screen-types、page-config、store-categories、store-countries 这类元数据端点内容稳定，建议缓存 24 小时，避免每次查询都消耗配额。

应用/产品/公司域

榜单域

下载与收入估算域（第三方估算）

> 可信度强制标注：下载/收入数字均为第三方估算值，非官方数据。Agent 呈现时必须附带："本数据为第三方估算，可能存在 10%-30% 偏差，仅供参考"。本技能按以下规则分级：
> - A级（高可信）：样本量充足、多源交叉验证、方差 < 10%
> - B级（中可信）：样本量中等、单源、方差 10%-25%
> - C级（低可信）：样本量稀疏、长尾地区、方差 > 25%

分布与市场域

参数自然语言翻译层

内置高频参数的中英双语映射，避免每次查询都先调 filter-options。

行业一级分类（trade_level1）

国家/地区常用码

> 未列出的国家/子行业/媒体渠道/设备类型，请调 GET /api/data/filter-options 获取最新码表。

创意类型（常见）

端点依赖图与编排策略

Agent 在组合多端点工作流时，按依赖关系决定并行/串行：

独立可并行（首轮一次性发出）：
  filter-options / distribute-dims / screen-types / page-config
  store-categories / store-countries
  search / count / count-all / distribute
  market-search / unified-product-search / company-search

依赖前序结果（必须串行）：
  content-detail    ← 依赖 search 返回的创意 ID
  item-apps         ← 依赖 search 返回的创意 ID
  app-detail        ← 依赖 unified-product-search 或 item-apps 返回的 unifiedProductId
  developer-detail  ← 依赖 app-detail 返回的开发者 ID
  similar-apps      ← 依赖 app-detail
  sdk-detail        ← 依赖 app-detail
  product-content-search / counts  ← 依赖 product-search 的产品 ID

编排规则：
1. 首轮：把所有无依赖的查询一次性并行发出（建议 5-8 个并发）
2. 解析首轮结果，提取 ID
3. 第二轮：基于 ID 的详情查询并行发出
4. 配额紧张时：用 count 替代 search，用 count-all 替代多次 distribute

典型工作流（3 个真实场景）

场景一：竞品创意监控（买量团队）

用户意图："监控某竞品最近 7 天在美国的视频创意变化"

编排：
1. POST /api/data/product-search  → 拿到竞品 unifiedProductId
2. POST /api/data/product-content-search  (filter: 7d, US, video=010)
3. POST /api/data/product-content-counts  (同条件) → 拿到总量
4. （增量）对比上次缓存的创意 ID 列表，仅对新增项调 content-detail

输出：新增创意数、创意素材链接、创意分布变化

场景二：跨地区选品调研（出海团队）

用户意图："对比美国和东南亚三消类游戏的下载与收入"

编排（首轮并行）：
- POST /api/data/download-country  (US, 602, match-3)
- POST /api/data/download-country  (TH, 602, match-3)
- POST /api/data/download-country  (VN, 602, match-3)
- POST /api/data/revenue-country   (US, 602, match-3)
- POST /api/data/revenue-country   (TH, 602, match-3)
- POST /api/data/revenue-country   (VN, 602, match-3)

输出：表格对比，每行附可信度分级

场景三：开发者画像与 SDK 审计

用户意图："调研某开发者旗下所有应用的 SDK 使用情况"

编排：
1. POST /api/data/company-search → 拿到开发者 ID
2. GET /api/data/developer-detail → 拿到旗下应用列表
3. （并行）对每个应用 GET /api/data/sdk-detail
4. 聚合：SDK 使用频次、共享 SDK、独家 SDK

输出：SDK 矩阵表 + 供应链风险提示

输出规则

• 原始结构化 JSON 透传：保持 API 字段名不变，不重命名、不丢弃、不总结、不排序、不评论
• 空列表是合法结果（无匹配），非错误
• 透传附加字段（如 gptCorrect 拼写建议）原样返回，不静默替换关键词
• 估算数据必须标注：呈现下载/收入数字时，必须附带可信度分级与"第三方估算"声明
• 不在技能内做：H5/落地页/卡片/仪表盘生成、托管式深度研究、自主多步研究、分析/推荐（除非用户在收到数据后明确要求）

错误处理

Agent 层错误（未发起请求）

{ "error": { "code": "missing_api_key", "message": "缺少 ADMAPIX_API_KEY 环境变量", "retry": false } }

API 层错误（返回非 2xx）

API 返回 { "detail": "...", "code": "..." }，需透传并附加 HTTP 状态码。永不打印 Key。

{ "error": { "code": "invalid_api_key", "http_status": 401, "message": "API Key 格式无效或已禁用", "retry": false } }

常见错误码与处置

配额感知与降级

当接近调用配额时（用户配置阈值，默认剩余 < 10%）：
1. 优先用 count / count-all 替代 search（计数消耗低于搜索）
2. 元数据查询命中本地缓存，不消耗配额
3. 提示用户："配额剩余 X%，已切换为计数模式，如需完整结果请提升套餐"

缓存策略

缓存键：端点 + 规范化后的参数 JSON。缓存位置：~/.admapix-cache/（用户可清理）。

FAQ

Q1：为什么我的 page_size=50 被改成了 10？
A：创意搜索端点强制上限 10，本技能自动钳制。翻页请用 page 参数递增，建议配合缓存避免重复消耗配额。

Q2：下载/收入数字和官方财报对不上？
A：本数据为第三方估算，非官方披露。请参考可信度分级（A/B/C），C 级数据仅用于趋势判断，不用于精确决策。

Q3：如何批量导出某竞品全部创意？
A：先用 product-content-counts 拿到总量，再分页 product-content-search（每页 10），结果写入本地文件。建议在夜间低峰执行，避免限流。

Q4：totalSize 为什么是 null？
A：过滤查询时 totalSize 可能为 null，此时以 list 长度为准，或单独调 count 端点获取准确总数。

Q5：多个国家的数据能一次请求拿到吗？
A：search / distribute 支持 countries 数组，但结果会合并。如需分别对比，请并行发多个单国家请求（见"场景二"）。

故障排查

依赖说明

运行环境

• Agent 平台：支持 SKILL.md 的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
• 操作系统：Windows / macOS / Linux
• 网络：需可访问 https://api.admapix.com

第三方依赖

API Key 配置

• 环境变量（推荐）：export ADMAPIX_API_KEY="你的Key"
• 平台配置：参考所用 Agent 平台的密钥管理文档
• 安全要求：Key 仅作为 X-API-Key 请求头使用；永不写入日志、链接参数或聊天响应；永不接受用户在聊天中明文粘贴的 Key

可用性分类

• 分类：MD+EXEC（Markdown 指令驱动，需 exec 执行 curl 命令）
• 说明：基于 Markdown 的 AI Skill，通过自然语言指令驱动 Agent 调用 AdMapix REST API 并处理 JSON 结果