友盟自定义事件管理技能

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

管理友盟自定义事件（埋点）定义，覆盖两类核心需求：

• 写入：创建 App 类型单个事件、批量创建小程序事件（友盟小程序端无单创接口，单事件也走批量接口）
• 只读辅助：查询 App / 小程序事件列表（用于创建前重复性预检、创建后 --verify 回查）

共 4 个接口（跨 com.umeng.uapp + com.umeng.umini 两个命名空间，按平台自动分流）：

> 🔗 与 umeng-cli-uapp-event 的边界分工：本 Skill 仅覆盖事件定义管理（写入 + 列表）；事件触发次数、独立用户、参数列表、参数取值分布等只读统计查询归属 umeng-cli-uapp-event。
> 🔗 与 umeng-cli-uapp-assets 的边界分工：查询"账户下都有哪些 App / 小程序"归属 umeng-cli-uapp-assets；本 Skill 以 appkey / dataSourceId 为输入。
> ⚠️ 不支持的操作：友盟 OpenAPI 不提供事件删除、事件重命名、事件显示名编辑接口，Skill 也不承担这些能力。

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

⚠️ 写入风险提示（本 Skill 含 2 个写入接口）

umeng.uapp.event.create 和 umeng.umini.batchCreateEvent 均为变更类操作，会在用户账号下实际创建不可删除、不可重命名的事件定义（友盟 OpenAPI 未开放删除/编辑接口）。调用前强制遵循以下规范：

1. 参数完整校验：appkey / dataSourceId + eventName + eventDisplayName 三者必须同时确认。
2. 命名规范校验（本地先校验，不满足不得调用）：
   - eventName：正则 ^[a-zA-Z0-9_]+$，禁止特殊字符 ? / . \ < > 和空格、中文
   - eventDisplayName：允许中文 + 英文 + 数字 + 下划线，禁止特殊字符 ? / . \ < >
3. 创建前预检（强烈建议）：先调 event.list / getEventList，确认 eventName 不重复再写入；重复创建可能报错或生成混淆记录。
4. 向用户复述并二次确认：执行前应以自然语言向用户复述"将为 <应用名> 创建事件「<eventName>」（显示名「<eventDisplayName>」）"，获得明确"确认/继续"后再执行；批量场景需列出完整事件清单供用户核对。
5. 失败语义：返回 status != 0（App）或 success=false / code != 0（小程序）时，不要自动重试写入；将 msg 原文透传给用户。
6. 创建后同步延迟：事件同步需数秒，立即调 --verify（event.list）可能返回"不存在"；建议延迟 3–5 秒后再回查，或一次性延迟后核对全部事件名。
7. 不可撤销：友盟 OpenAPI 不提供事件删除 / 重命名 / 显示名编辑接口；创建错了只能忍受历史残留，务必在写入前完成二次确认。

前置条件：安装 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

适用场景与触发词

• 用户要求"创建一个叫 xxx 的事件" / "添加埋点" / "新增一个自定义事件"
• 用户要求"批量创建这几个小程序事件" / 提供 JSON 清单一次性创建
• 用户要求"验证某事件是否已经创建"（走事件列表回查）
• 用户要求"查看当前应用有哪些自定义事件"（事件定义清单，与"事件统计"区分）
• 关键词：创建事件、添加埋点、批量创建事件、事件列表、自定义事件管理、新增埋点、事件创建、event.create、batchCreateEvent、显示名、eventName、displayName

鉴权方式

• authType: umeng-aksk（友盟 OpenAPI AK/SK 签名，HMAC-SHA1）
• baseUrl: https://gateway.open.umeng.com/openapi
• endpoint 路径规则：
• App 接口：param2/1/com.umeng.uapp/<接口名>
• 小程序接口：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=...
#
# ⏳ 等待登录...
# ✅ 授权成功！
# ✅ 登录完成！

平台分流规则（强制）

本 Skill 同时适用于 App 和小程序，根据 platform 自动选择命名空间与接口：

关键差异：

• App 类型无批量接口：批量创建请循环调用 umeng.uapp.event.create
• 小程序无单创接口：即使只创建 1 个事件，也走 umeng.umini.batchCreateEvent（eventList 传长度为 1 的数组）
• App 的 eventDisplayName 中文需 urlEncode（由 umeng-cli 内部处理，LLM 传原始中文即可）
• 小程序的 eventList 中 displayName 直接传原始中文（小程序批量接口不要求手工 encode）

4 个接口速查表

公共约束：

• eventName：^[a-zA-Z0-9_]+$，禁止 ? / . \ < > 和空格、中文
• eventDisplayName / displayName：允许中文 + 英文 + 数字 + 下划线，禁止 ? / . \ < >
• eventType（仅 App 可用）：true = 计算事件（数值型，用于累计值/均值/分布）；false = 计数事件（字符串型，统计消息数 + 触发设备数）；不传默认 false
• 小程序端没有 eventType 概念，batchCreateEvent 不接受此字段

接口 1：umeng.uapp.event.create — App 创建自定义事件（⚠️ 写入）

参数

调用示例

# 计数事件（默认）
umeng-cli call '{"name":"umeng.uapp.event.create","api":{"method":"GET","baseUrl":"https://gateway.open.umeng.com/openapi","endpoint":"param2/1/com.umeng.uapp/umeng.uapp.event.create","authType":"umeng-aksk"}}' '{"appkey":"5f8a123456789abcdef01234","eventName":"purchase_click","eventDisplayName":"购买点击"}'

# 计算事件（数值型）
umeng-cli call '{"name":"umeng.uapp.event.create","api":{"method":"GET","baseUrl":"https://gateway.open.umeng.com/openapi","endpoint":"param2/1/com.umeng.uapp/umeng.uapp.event.create","authType":"umeng-aksk"}}' '{"appkey":"5f8a123456789abcdef01234","eventName":"purchase_amount","eventDisplayName":"购买金额","eventType":true}'

返回字段

成功 / 失败判定

• 成功：status == 0
• 失败：status != 0，将 msg 原文透传给用户，不要自动重试

接口 2：umeng.umini.batchCreateEvent — 小程序批量创建事件（⚠️ 写入）

参数

eventDTO[] 结构：

调用示例

# 单事件（长度为 1 的数组）
umeng-cli call '{"name":"umeng.umini.batchCreateEvent","api":{"method":"GET","baseUrl":"https://gateway.open.umeng.com/openapi","endpoint":"param2/1/com.umeng.umini/umeng.umini.batchCreateEvent","authType":"umeng-aksk"}}' '{"dataSourceId":"1dfe1b2f3597245664499a91","eventList":[{"eventName":"view_page","displayName":"浏览页面"}]}'

# 批量事件
umeng-cli call '{"name":"umeng.umini.batchCreateEvent","api":{"method":"GET","baseUrl":"https://gateway.open.umeng.com/openapi","endpoint":"param2/1/com.umeng.umini/umeng.umini.batchCreateEvent","authType":"umeng-aksk"}}' '{"dataSourceId":"1dfe1b2f3597245664499a91","eventList":[{"eventName":"click_btn","displayName":"点击按钮"},{"eventName":"view_page","displayName":"浏览页面"}]}'

返回字段

成功 / 失败判定

• 成功：success == true 且 code 为成功码（0 或 200）
• 失败：整个请求失败；友盟批量接口目前不返回每个事件的单独成败，对失败用户应建议逐个改用 N=1 重试以定位问题事件
• 不要自动重试整个批量请求

接口 3：umeng.uapp.event.list — App 事件列表（📖 只读）

参数

调用示例

umeng-cli call '{"name":"umeng.uapp.event.list","api":{"method":"GET","baseUrl":"https://gateway.open.umeng.com/openapi","endpoint":"param2/1/com.umeng.uapp/umeng.uapp.event.list","authType":"umeng-aksk"}}' '{"appkey":"5f8a123456789abcdef01234","startDate":"2026-03-29","endDate":"2026-04-27","perPage":100}'

返回字段

EventInfo[] 结构： name（事件英文名）/ displayName（中文显示名）/ count（统计次数）/ id（事件 ID）

回查用法

创建 eventName="purchase_click" 后：
  → 循环拉取全部分页
  → 判断 eventInfo[].name == "purchase_click" 是否存在
  → 存在 = 回查成功

接口 4：umeng.umini.getEventList — 小程序事件列表（📖 只读）

参数

调用示例

umeng-cli call '{"name":"umeng.umini.getEventList","api":{"method":"GET","baseUrl":"https://gateway.open.umeng.com/openapi","endpoint":"param2/1/com.umeng.umini/umeng.umini.getEventList","authType":"umeng-aksk"}}' '{"dataSourceId":"1dfe1b2f3597245664499a91"}'

返回字段

返回结构为嵌套 data.data[]（也可能直接 data[]，需客户端兼容两种形态）：

回查用法

创建 eventName="view_page" 后：
  → 调用 getEventList
  → 展开 data.data 或 data 数组
  → 判断其中某项 eventName == "view_page"
  → 存在 = 回查成功

典型工作流（W1–W5）

W1：App 单事件创建 + 回查验证

1. 确认 appkey（必要时用 umeng-cli-uapp-assets 查询）
2. 本地校验 eventName / eventDisplayName 是否合法
3. 调用 umeng.uapp.event.list 预检（可选但推荐）—— 若事件已存在则提醒并停止
4. 向用户复述并二次确认
5. 调用 umeng.uapp.event.create
6. 判断 status == 0，失败则透传 msg 不重试
7. 等待 3–5 秒
8. 调用 umeng.uapp.event.list 回查 eventName 是否出现

W2：小程序单事件创建（走批量接口 N=1）

1. 确认 dataSourceId
2. 本地校验 eventName / displayName
3. （可选）调用 umeng.umini.getEventList 预检
4. 向用户复述并二次确认
5. 调用 umeng.umini.batchCreateEvent，eventList=[{"eventName":"...","displayName":"..."}]
6. 判断 success == true 且 code 为成功码
7. 等待 3–5 秒
8. 调用 umeng.umini.getEventList 回查

W3：小程序批量事件创建 + 回查校对

1. 获取用户提供的事件清单（JSON 数组或用户口述）
2. 本地逐项校验 eventName / displayName
3. 去重：按 eventName 去重
4. 调用 umeng.umini.getEventList 预检并剔除已存在项
5. 向用户列出完整待创建清单，请求二次确认
6. 调用 umeng.umini.batchCreateEvent
7. 失败时建议用户将失败批改为 N=1 逐个试，以定位问题事件（整批失败不自动重试）
8. 等待 3–5 秒
9. 再调 umeng.umini.getEventList 核对每个 eventName 是否存在

W4：创建前重复性预检（避免重复创建）

场景：用户要求"创建 purchase_click 事件"
  → 先调事件列表（App 走 event.list，小程序走 getEventList）
  → 搜索目标 eventName
  → 已存在 → 告知用户"事件已存在，无需创建"
  → 不存在 → 按 W1 / W2 流程继续

W5：跨平台事件清单盘点

1. 调用 umeng-cli-uapp-assets 获取账户下 App + 小程序列表
2. 对 App 类 appkey 调用 umeng.uapp.event.list
3. 对小程序类 dataSourceId 调用 umeng.umini.getEventList
4. 客户端合并 + 去重输出
（注意：两接口响应字段不同，App 用 name，小程序用 eventName，合并时需要映射）

字段别名与旧参数对照表

边界与异常处理

典型问法与内部意图映射

快速自检清单

调用前自检：

• [ ] 平台类型已确认，走正确命名空间（App→com.umeng.uapp，小程序/H5→com.umeng.umini）
• [ ] appkey / dataSourceId 已拿到（必要时先走 umeng-cli-uapp-assets）
• [ ] eventName 满足 ^[a-zA-Z0-9_]+$
• [ ] eventDisplayName / displayName 不含 ? / . \ < >
• [ ] 写入前已做重复性预检（event.list / getEventList）
• [ ] 写入前已向用户复述并二次确认
• [ ] 失败时不自动重试写入
• [ ] 写入成功后延迟 3–5 秒再做回查

调用后自检：

• [ ] App：status == 0 判成功；小程序：success == true 且 code 为成功码
• [ ] 已执行回查（event.list / getEventList）并反馈给用户
• [ ] 用户要求删除 / 重命名时明确告知不支持