友盟小程序推广链接管理技能

> umeng-cli 是友盟提供的命令行程序，所有操作通过执行 umeng-cli call 命令完成。

管理友盟小程序（U-MiniProgram）的推广链接资产，覆盖资产管理两类核心需求：

• 创建推广活动链接（活动名 + 渠道 + 可选落地页）
• 枚举当前小程序下全部推广活动 / 推广渠道

共 2 个接口（命名空间 com.umeng.umini，与旧 uapp-campaign skill 能力完全等价）：

> 埋点上报： AI Agent 在阅读本 Skill 文档后，请执行以下命令进行调用埋点上报：
> bash > umeng-cli trace '{"skill_name":"umeng-cli-uapp-campaign"}' >
>
> Appkey 维度打点： 当本轮任务中出现 Appkey（小程序 dataSourceId）的输入操作时，在拿到该 Appkey 之后、发起首个业务 API 调用之前，再追加执行一次带 appkey 的打点：
> bash > umeng-cli trace '{"skill_name":"umeng-cli-uapp-campaign", "appkey":"<输入的Appkey>"}' >
> 同一 Appkey 在同一会话中只打一次；若用户切换到新的 Appkey，需对新的 Appkey 再打一次。

⚠️ 适用范围限制（强制）

本 Skill 仅适用于小程序 / H5 / 小游戏类应用：

当用户对 Android / iOS App 询问"推广链接"时，应明确告知：「推广链接功能仅限小程序 / H5 / 小游戏；App 类型请改用渠道分析（umeng-cli-uapp-channel-version）」。

前置条件：安装 umeng-cli

本 Skill 的所有调用都依赖 umeng-cli 命令行工具。使用本 Skill 前，请先确保已在本机安装。

检查是否已安装

umeng-cli --version

若提示 command not found 或类似错误，按下述方式安装。

安装方式

# 方式一：通过 npm 安装（推荐，自动安装 CLI + 内置 Skills）
npm install -g @umengfe/umeng-cli

# 方式二：通过官方安装脚本（仅安装 CLI 二进制 + Skills）
curl -fsSL https://raw.githubusercontent.com/umeng/umeng-cli/main/scripts/install.sh | sh

安装完成后再次运行 umeng-cli --version 验证。

> 更多安装说明、卸载、账号管理等参考 umeng-cli SKILL 或项目主页 https://github.com/umeng/umeng-cli

适用场景与触发词

• 用户要求为某小程序创建一条推广链接（活动 + 渠道）
• 用户询问"我有哪些推广活动 / 渠道？"「查看推广链接列表」
• 关键词：推广链接、推广活动、推广渠道、创建推广、推广列表、活动列表、渠道列表

鉴权方式

• authType: umeng-aksk（友盟 OpenAPI AK/SK 签名，HMAC-SHA1）
• baseUrl: https://gateway.open.umeng.com/openapi
• endpoint 路径规则: param2/1/com.umeng.umini/<接口名>
• AK/SK 由 umeng-cli login 自动获取并加密缓存，无需手动配置 apiKey / apiSecurity

登录状态检查

umeng-cli whoami

登录要求

当接口返回未登录或登录态过期时，需要执行 umeng-cli login --no-qr 进行登录。

AI Agent 执行登录的正确方式：

> umeng-cli login --no-qr 会在输出登录链接后阻塞等待用户在浏览器中完成登录，因此 AI Agent 应该以后台模式（is_background: true）运行此命令，这样可以立即拿到输出中的登录链接并展示给用户，无需等待命令结束。命令会在用户完成登录后自动退出并保存凭证。

如果终端不支持显示二维码（如 AI Agent 终端、SSH 远程终端等），可以使用 --no-qr 参数，仅输出可点击的登录链接：

umeng-cli login --no-qr

# 输出:
# 🔄 正在生成登录链接...
# ✅ 登录链接生成成功
#
# 🔗 请点击或复制以下链接完成登录：
#
#   👉 点击此处登录（OSC 8 可点击链接）
#   [点击登录](https://passport.umeng.com/login?redirectURL=...)
#   https://passport.umeng.com/login?redirectURL=...
#
# ⏳ 等待登录...
# ✅ 授权成功！
# ✅ 登录完成！

为什么必须提供 dataSourceId（appkey）

与 umeng-cli-uapp-assets 资产发现型 Skill 不同，本 Skill 2 个接口都必须传入 dataSourceId（即小程序的 AppKey），因为推广资产作用域是"单个小程序"而不是"账号"。

若用户未提供 appkey：
1. 优先引导使用 umeng-cli-uapp-assets 查询小程序列表，取得 dataSourceId：
bash umeng-cli call '{"name":"umeng.umini.getAppList","api":{"method":"GET","baseUrl":"https://gateway.open.umeng.com/openapi","endpoint":"param2/1/com.umeng.umini/umeng.umini.getAppList","authType":"umeng-aksk"}}' '{"pageIndex":1,"pageSize":100}'
2. 备选引导用户从友盟官网 web.umeng.com → U-MiniProgram → 应用列表 → 复制 AppKey 获取。

⚠️ 写入风险提示（本 Skill 唯一写入接口：createCampaign）

umeng.umini.createCampaign 是变更类操作，会在用户账号下实际创建一条不可撤销的推广链接。调用前强制遵循以下规范：

1. 参数完整校验：dataSourceId / campaignName / channelName 三者必须同时确认（path 可选）。
2. 向用户复述并二次确认：执行前应以自然语言向用户复述"将为 <应用名> 创建活动「<campaignName>」渠道「<channelName>」"，获得明确"确认/继续"后再执行。
3. 活动名不得为空、不得含仅空白字符：调用前 strip，若为空必须停止并要求补齐。
4. 同名活动可重复创建：友盟允许同 campaignName + channelName 多次创建，返回不同 code（活动代码）。不要自动重试相同参数。
5. 失败语义：返回 success=false 或 code != 0 时，不要自动重试写入；将 msg 原文透传给用户。

2 个接口速查表

公共枚举：

• sourceType（仅 getSceneInfoList）：campaign / channel

接口 1：umeng.umini.createCampaign — 创建推广链接（⚠️ 写入）

参数

调用示例

# 不含落地页路径
umeng-cli call '{"name":"umeng.umini.createCampaign","api":{"method":"GET","baseUrl":"https://gateway.open.umeng.com/openapi","endpoint":"param2/1/com.umeng.umini/umeng.umini.createCampaign","authType":"umeng-aksk"}}' '{"dataSourceId":"1dfe1b2f3597245664499a91","campaignName":"春季换新季","channelName":"抖音"}'

# 含落地页路径
umeng-cli call '{"name":"umeng.umini.createCampaign","api":{"method":"GET","baseUrl":"https://gateway.open.umeng.com/openapi","endpoint":"param2/1/com.umeng.umini/umeng.umini.createCampaign","authType":"umeng-aksk"}}' '{"dataSourceId":"1dfe1b2f3597245664499a91","campaignName":"春季特卖","channelName":"微信推广","path":"pages/promo/main"}'

返回

{
  "msg": "success",
  "code": 0,
  "success": true,
  "data": "cp_5f8a3b"
}

> 说明：data 仅返回活动代码，不返回完整 URL；若需要完整链接，紧接一次 getSceneInfoList 查询即可（见 W1 工作流）。

接口 2：umeng.umini.getSceneInfoList — 获取推广活动 / 渠道清单

参数

调用示例

# 查询所有推广活动
umeng-cli call '{"name":"umeng.umini.getSceneInfoList","api":{"method":"GET","baseUrl":"https://gateway.open.umeng.com/openapi","endpoint":"param2/1/com.umeng.umini/umeng.umini.getSceneInfoList","authType":"umeng-aksk"}}' '{"dataSourceId":"1dfe1b2f3597245664499a91","sourceType":"campaign"}'

# 查询所有推广渠道
umeng-cli call '{"name":"umeng.umini.getSceneInfoList","api":{"method":"GET","baseUrl":"https://gateway.open.umeng.com/openapi","endpoint":"param2/1/com.umeng.umini/umeng.umini.getSceneInfoList","authType":"umeng-aksk"}}' '{"dataSourceId":"1dfe1b2f3597245664499a91","sourceType":"channel"}'

返回

{
  "msg": "success",
  "code": 0,
  "success": true,
  "data": [
    {
      "code": "cp_5f8a3b",
      "name": "春季换新季",
      "url": "https://m.umeng.com/...",
      "createDateTime": "2026-04-20 10:12:33"
    }
  ]
}

> 本接口不支持分页：一次性返回当前小程序全部活动 / 渠道；若列表极长可由客户端过滤。

典型问法与内部意图映射

工作流

W1：创建推广链接（含二次确认 + 回查 URL）

目标：为某小程序创建活动链接并立即返回可分享的完整 URL。

步骤：

1. 准备阶段：向用户复述 dataSourceId 对应的小程序名 + campaignName + channelName（+ 可选 path），获得明确"继续/确认"。
2. 执行：调用 createCampaign，取得返回中的 data（活动代码）。
3. 回查：紧接调用 getSceneInfoList(sourceType=campaign)，在返回数组中按 code == 步骤 2 返回的 data 过滤出刚创建的活动，读取其 url 字段作为推广链接交付给用户。

示例序列：

# Step 2
umeng-cli call '{"name":"umeng.umini.createCampaign",...}' '{"dataSourceId":"1dfe...","campaignName":"春季换新季","channelName":"抖音"}'
# 返回 data: "cp_5f8a3b"

# Step 3
umeng-cli call '{"name":"umeng.umini.getSceneInfoList",...}' '{"dataSourceId":"1dfe...","sourceType":"campaign"}' \
  | jq '.data[] | select(.code == "cp_5f8a3b")'

W2：推广资产盘点（活动 + 渠道合并）

目标：一次给出小程序所有推广资产的总览。

# 活动清单
umeng-cli call '{...}' '{"dataSourceId":"...","sourceType":"campaign"}'
# 渠道清单
umeng-cli call '{...}' '{"dataSourceId":"...","sourceType":"channel"}'

客户端按 name / createDateTime 排序合并，输出「共 N 个活动 + M 个渠道」。

W3：Android/iOS App 退回（异常规避）

• 若用户是 Android/iOS App 询问"推广链接" → 直接回复"推广链接仅限小程序 / H5 / 小游戏；App 渠道分析请使用 umeng-cli-uapp-channel-version"。

字段别名与旧参数对照表

本 Skill 直达友盟 OpenAPI 参数名，旧 scripts/campaign.py 的 CLI 抽象层参数对应关系如下：

边界与异常处理

与其他 Skill 的边界

历史产物说明

• 旧实现 skills/uapp-campaign/ 目录 + scripts/campaign.py（Python SDK + apiKey/apiSecurity 落盘配置）保留兼容，不删除。
• 旧打包 skills/uapp-campaign-1.1.0.zip 保留兼容。
• 本 Skill 与旧 uapp-campaign 能力完全等价（零能力扩展）：覆盖相同的 2 个接口（createCampaign + getSceneInfoList），仅做调用形态（CLI 化）与鉴权（umeng-aksk）的升级。

快速自检清单（AI 使用本 Skill 前自检）

• [ ] 已确认用户小程序（非 App），已取得 dataSourceId
• [ ] 调用 createCampaign 前已向用户复述 campaignName + channelName，并获得确认
• [ ] createCampaign 返回 success=false 时，不自动重试，原文透传 msg