> ## Documentation Index > Fetch the complete documentation index at: https://docs.newenergycoder.club/llms.txt > Use this file to discover all available pages before exploring further. # ai-promotion-query > 腾讯音乐人宣推数据查询能力。当用户提到"我这些歌宣推情况如何"、"看一下宣推数据"、"这首歌宣推效果怎么样"、"我有哪些歌在投放"、"这首歌还要不要继续投"、"宣推诊断"、"宣推表现"、"投放效果"等与宣推数据查询相关的请求时触发。本 Skill 整合了两大子场景：① **宣推概览**——拉取当前… | 项目 | 内容 | | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 来源 | [skills/ai-promotion-query/SKILL.md](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/ai-promotion-query/SKILL.md) | | 分类 | 效率 & 头脑风暴 | | 安装 | 克隆 [Skill 分支](https://github.com/new-energy-coder-club/new_energy_coder_club/tree/Skill) 后，将 `skills/ai-promotion-query/` 目录复制到 `~/.claude/skills/`（Claude Code）、`~/.trae/skills/`（Trae IDE）或 `~/.qclaw/skills/`（QClaw/OpenClaw），详见 [Skill 安装方式](/community/skill-branch) | # AI Promotion Query（腾讯音乐人宣推数据查询） > **✨ 自包含登录态**：本 Skill 需要用户登录态，已由 `tme-openapi` Skill 自动处理——**无需任何手动架设**。首次使用会弹出浏览器扫码登录，Token 有效期约 30 天。 > > **⚠️ 前置依赖（算子调用能力）**：本 Skill **不自带** API 调用脚本，所有 TME OpenAPI 算子的发现与调用都**委托给 `tme-openapi` Skill**。你需要了解 `tme-openapi` 提供的 4 个通用工具（`list_apis` / `search_apis` / `get_api_detail` / `invoke_api`）及其标准调用流程。 > > **⚠️ 对外表达依赖**：本 Skill 的输出是上层 Agent（`ai-promotion/readme.md`）的**内部数据依据**，不直接面向用户。最终对用户的自然语言回复，必须遵守 `ai-promotion/readme.md` 的对外规则，并统一通过 `宣推结构化输出` skill 输出。 本 Skill 分为两个部分： * **Part 1 — 宣推数据查询业务流程**：基于 `tme-openapi` 的通用调用能力，完成"宣推概览查询"和"获取歌曲宣推指标查询"两个子场景的业务编排。 * **Part 2 — 宣推指标分析**：按需读取 `knowledge.md`，把查询结果归类到推广前 / 推广中 / 推广后规则，再生成定性判断、动作建议和衍生问题。 *** ## 基础能力依赖：`tme-openapi` 本 Skill 的所有后端调用都通过 `tme-openapi` Skill 完成。该 Skill 提供 4 个通用工具来发现和调用腾讯音乐开放平台的「算子」API： | Tool（来自 `tme-openapi`） | 作用 | 在本业务中的典型用途 | | ---------------------- | ----------- | ------------------------------------------ | | `search_apis` | 按关键词模糊搜索算子 | 用关键词定位"宣推概览"、"获取歌曲宣推指标"算子 | | `list_apis` | 列出所有可用算子摘要 | 搜索失败时兑底探查 | | `get_api_detail` | 获取指定算子的完整详情 | 调用前查 `inputSchema` / `detailedDescription` | | `invoke_api` | 调用指定算子 | 真正发起业务调用（同步返回结果） | **标准调用流程（由 `tme-openapi` 定义）**： ``` search_apis(keyword) → [可选] get_api_detail(operatorCode) → invoke_api(operatorCode, arguments) ``` > 当前算子平台仅支持**同步调用**，`invoke_api` 一次请求即为终态，无需轮询异步结果。 ### 脚本路径约定 `tme-openapi` 的脚本位于同级目录 `../tme-openapi/scripts/`。在 qclaw / Code Buddy 中，脚本安装路径为 `~/./skills/tme-openapi/scripts/`。本 Skill 正文中的「搜索算子」「调用算子」等步骤，都是对这些脚本的逻辑调用，不再赘述具体命令行形式——按 `tme-openapi/SKILL.md` 的"标准调用流程"执行即可。 ### 核心编排原则（从 `tme-openapi` 继承） * 不硬编码任何 `operatorCode` 或参数结构，一律通过 `search_apis` / `get_api_detail` 动态发现 * 登录态下**不要**传 `accountId` / `userId` 等身份参数，后端会从 Token 中自动识别 * 遇到 `INVALID_ARGUMENT`，回退到 `get_api_detail` 重新确认 schema 和 example 后再试 * 遇到 `UNAUTHORIZED`，引导用户删除 `~/.tme-login/token.json` 后重跑，`tme-openapi` 会自动触发重新登录 * 错误码含义与重试策略的完整表格，见 `tme-openapi/SKILL.md` *** ## Part 1：宣推数据查询业务流程 **注意**：本 Skill 不硬编码任何算子 code 或参数结构。关于算子的参数细节、取值约束、返回结构等信息，请通过 `tme-openapi` 的 `get_api_detail` 获取详情后，阅读 `detailedDescription` 字段，并参考本目录下 `detailed_description_overview.md` / `detailed_description_metric.md` 两份本地说明作为辅助。 ### 核心背景 宣推数据查询是音乐人宣推助手的基础能力： 1. **宣推概览** — 拉取当前登录用户名下所有宣推歌曲的整体情况（账号级摘要 + 单曲摘要列表），用于回答"我这些歌宣推情况如何"这类账号级问题，也用于后续从中筛选出目标 `songId` 即 `yyrSongId`字段。 2. **获取歌曲宣推指标** — 按 `songId` 获取单首歌的完整宣推指标，用于回答单首歌的宣推表现、诊断、加投/止损判断等问题。 两个接口均为**同步接口**，`invoke_api` 直接返回结果，无需关心异步轮询。 ### 对外表达总原则（⚠️ 贯穿两个场景） * ❌ 禁止向用户展示任何具体金额、投放金额、购买播放量、投放天数等数字 * ✅ 内部拿到的指标只能作为判断依据，对外必须转写为"表现较好 / 偏弱 / 一般 / 有提升空间 / 值得继续观察"等定性评价 * ✅ 不输出"我来帮你分析"、"让我查询一下"、"数据查询成功"等过程态话术 * ✅ 无法唯一定位歌曲时，不得追问 `songId` / 歌手名 / 发布时间 / 版本信息，固定使用 `ai-promotion/readme.md` 中的兜底文案 *** ### 场景一：宣推概览查询 当用户说"我这些歌宣推情况怎么样"、"看一下宣推数据"、"我有哪些歌在投放"、"宣推表现如何"等**账号级 / 未指定具体歌曲**的问题时： #### 核心约束 * 当前登录用户由登录态 Token 自动透传，**不需要**调用方传 `userId` * 若接口支持分页，`pageNo` 默认 1、`pageSize` 默认 10（以 `inputSchema` 为准） * **不要**向用户暴露技术参数名称（如 `pageNo` / `pageSize`），对用户使用自然语言描述 * 更多参数/返回细节参见 `detailed_description_overview.md` #### Step 1：搜索宣推概览算子 通过 `tme-openapi` 的 `search_apis`： ``` search_apis({ keyword: "宣推概览" }) ``` 若无命中，换用备选关键词重试：`宣推歌曲`、`宣推列表`、`宣推数据`。 从返回中定位名称/描述与"宣推概览 / 宣推歌曲概览"匹配的条目，记住其 `name`（operatorCode）。 #### Step 2：获取算子详情（强烈建议） **首次调用前，务必先获取详情**： ``` get_api_detail({ name: "<上一步找到的 operatorCode>" }) ``` 仔细阅读 `detailedDescription`、`inputSchema`、`exampleOutput`。如与本地 `detailed_description_overview.md` 冲突，**以后端返回为准**。 #### Step 3：调用宣推概览算子 根据 `inputSchema` 构造参数并通过 `tme-openapi` 的 `invoke_api` 调用： ``` invoke_api({ name: "", arguments: { /* 以 get_api_detail 返回的 inputSchema 为准，通常可传空对象 {} 或 { pageNo, pageSize } */ } }) ``` #### Step 4：处理返回并组装内部上下文 从返回中提取： * 账号级信息（是否曾有宣推歌曲、当前在投数量等） * 单曲摘要列表（`songId`、`songName`、`promotionStatus`、定性标签等） 该结果 **不直接对外**，而是作为上层 `ai-promotion/readme.md` 判断问题类型、组装回答所需的内部数据。 #### 场景一对外输出要点（遵循 `ai-promotion/readme.md` 的 B 类或 A 类规则） * 用户问的是**整体情况 / 账号级 / 不指向具体一首** → 走 B 类规则：一个或多个 `message` + 最后一个 `moreQuestions`（4 个衍生问题），**不输出 `songCard`** * 用户问的是**某一首但歌名模糊** → 先在概览里做匹配，若能唯一定位到一首，带着 `songId` 进入场景二；若无法唯一定位，按 `ai-promotion/readme.md` 的"单首歌无法定位规则"输出固定兜底文案 * 禁止在对外回复中直接展示歌曲列表的原始数值字段（如具体播放量），只做定性总结 #### 场景一边界情况 | 情况 | 内部处理 | 对外表达 | | ---------------------- | ------------------------ | ----------------------------------------------------------- | | 返回列表为空 | 判断是否从未宣推过 | 用定性语言告知"当前没有在宣推的歌曲"，不要暴露技术细节 | | `UNAUTHORIZED` | 登录态失效 | 引导用户删除 `~/.tme-login/token.json` 后重跑（`tme-openapi` 会自动重新登录） | | 请求超时 /`UPSTREAM_ERROR` | 重试 1-2 次 | 仍失败则使用`ai-promotion/readme.md` 中的"系统繁忙"兜底文案 | | 用户继续问某一首 | 从概览结果中匹配`songName` / 关键词 | 匹配成功则进入场景二；匹配失败按"单首歌无法定位规则"输出兜底文案 | *** ### 场景二：获取歌曲宣推指标 当用户说"这首歌宣推效果怎么样"、"《XXX》宣推诊断"、"这首歌要不要继续投"、"这首歌宣推有什么问题"等**指向单首歌**的问题时： #### 核心约束 * `songId` **必填**。如无 `songId`，先走场景一拿到候选池并匹配 * 已在上下文中（概览结果、做歌结果、发行结果、上层透传）拿到 `songId` 的，直接使用，**不要**再向用户追问 * 本接口通常为同步，直接返回结果 * **不要**向用户暴露 `songId` / 技术参数名称 * 更多参数/返回细节参见 `detailed_description_metric.md` #### Step 1：准备 `songId` 按优先级尝试： 1. 上下文中已存在 `songId`（上层 Agent 透传、概览匹配结果、做歌/发行透传） → 直接使用 2. 用户给了歌名 → 先调用场景一的"宣推概览"，在返回列表里按 `songName` 匹配 3. 依然无法唯一定位 → **不要追问用户**，按 `ai-promotion/readme.md` 的"单首歌无法定位规则"输出固定兜底文案（`抱歉哦，系统繁忙中暂时无法为您提供该歌曲宣推评估...`） #### Step 2：搜索获取歌曲宣推指标算子 通过 `tme-openapi` 的 `search_apis`： ``` search_apis({ keyword: "获取歌曲宣推指标" }) ``` 若无命中，换用备选关键词：`宣推指标`、`宣推数据详情`、`单曲宣推`、`歌曲宣推详情`。 记下匹配条目的 `name`（operatorCode）。 #### Step 3：获取算子详情（强烈建议） ``` get_api_detail({ name: "<上一步找到的 operatorCode>" }) ``` 仔细阅读 `detailedDescription` / `inputSchema` / `exampleOutput`。若与本地 `detailed_description_metric.md` 冲突，以后端为准。 #### Step 4：调用获取歌曲宣推指标算子 通过 `tme-openapi` 的 `invoke_api`： ``` invoke_api({ name: "", arguments: { "songId": "<目标歌曲ID>" /* 其他字段以 inputSchema 为准，如 startDate / endDate */ } }) ``` #### Step 5：组装内部上下文，交由 Part 2 做分析 拿到返回后： * 提取基础信息（歌名、封面、发行时间、生命周期阶段等） * 提取核心宣推指标（播放表现、完播、转化、投放节奏、素材维度等）——**仅作为内部判断依据** * 提取定性标签（如后端已提供 `performanceTag` / `diagnosisTag`），优先用定性字段对外 后续分析与回答组装逻辑，见 **Part 2：宣推指标分析**。 #### 场景二对外输出要点（A 类问题，严格遵循 `ai-promotion/readme.md`） A 类问题必须按以下顺序输出 4 个协议块（全部通过 `宣推结构化输出` skill 输出）： 1. 总结性 `message` — 对该歌曲当前宣推表现的定性总结（亮点 / 短板 / 当前状态），**严禁展示具体指标数值** 2. `songCard` — `{"songId":"<真实可定位的 songId>"}` 3. 建议性 `message` — 围绕该单首歌的具体、可落地的操作建议，必须说明依据，避免空泛 4. `moreQuestions` — 4 个衍生问题，优先落在知识库已覆盖主题（数据解读 / 问题诊断 / 投流节奏 / 素材优化 / 生命周期 / 加投止损判断） #### 场景二边界情况 | 情况 | 内部处理 | 对外表达 | | ---------------------- | ------------------------------- | ------------------------------------------------------------- | | 无`songId` 且场景一无法匹配 | 不向用户追问任何补充信息 | 按`ai-promotion/readme.md` 的"单首歌无法定位规则"输出固定兜底文案，不输出 `songCard` | | `songId` 不存在 / 无权访问 | 回到场景一重取候选池 | 用定性语言提示"无法获取到该歌曲的宣推数据"，不要暴露 `songId` 字段 | | 歌曲不在宣推中 | 无宣推数据可分析 | 用定性语言提示"该歌曲暂无宣推数据，可以从其他歌曲入手" | | `INVALID_ARGUMENT` | 回退到`get_api_detail` 重新确认 schema | 内部修正后重试，不要外露过程 | | `UNAUTHORIZED` | 登录态失效 | 引导用户删除 `~/.tme-login/token.json` 后重跑（`tme-openapi` 会自动重新登录） | | 请求超时 /`UPSTREAM_ERROR` | 重试 1-2 次 | 仍失败则输出"系统繁忙"固定兜底文案 | *** ### 场景组合：先概览后指标（最常见） ``` 1. 场景一：查宣推概览 → 拿到账号级摘要 + 单曲候选池 ↓ 2. 按用户问题定位目标 songId（或直接回答账号级问题并结束） ↓ 3. 场景二：按 songId 获取歌曲宣推指标 → 拿到单首完整指标 ↓ 4. Part 2：结合宣推知识库做分析 → 按 A 类结构输出 ``` *** ## Part 2：宣推指标分析 ### 定位 本部分负责**把 Part 1 查到的原始指标，结合本地知识库 [knowledge.md](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/ai-promotion-query/knowledge.md)，转化为对用户可用的诊断与建议**。 Part 2 现在按固定流程执行。执行时必须： 1. 先判断问题属于账号级概览还是单首歌诊断 2. 再判断歌曲当前所处的推广阶段：推广前 / 推广中 / 推广后 3. 最后按 `knowledge.md` 的对应章节生成定性判断、动作建议和 `moreQuestions` ### 知识库使用方式 优先读取本地文件： * [knowledge.md](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/ai-promotion-query/knowledge.md)：宣推知识库主文件，包含指标口径、三阶段策略、特殊场景、FAQ、Agent 落地规则 按需读取，不要把整份知识库搬进回答。优先定位以下标题： * `## 2. 核心指标口径` * `## 3. 推广前判断` * `## 4. 推广中判断` * `## 5. 推广结束后的复盘判断` * `## 6. 特殊场景适配` * `## 7. FAQ 归纳` * `## 8. 面向 Agent 的落地规则` ### 输入 * 场景一返回的账号级概览 + 单曲摘要列表 * 场景二返回的目标歌曲完整指标 * 当前对话上下文中的用户原问题 * 如有：后端直接返回的定性字段（如 `performanceTag`、`diagnosisTag`、`promotionStatus`） ### 分析主流程 #### Step 1：先判断问题类型 * 用户问账号整体情况、歌曲集合表现、有哪些歌在投放 → 走账号级总结 * 用户问某一首歌值不值得继续投、效果怎么样、哪里有问题 → 走单首歌分析 账号级问题以概览结果为主，不强行展开到单曲深诊断；单曲问题以 `songId` 对应的指标详情为主。 #### Step 2：判断推广阶段 结合用户问题、接口字段和知识库语义，把当前歌曲归到以下三类之一： * **推广前**：更像是在问“值不值得推”“怎么起量”“适合哪种方式”，或当前主要是基础质量判断/冷启判断 * **推广中**：更像是在问“效果怎么样”“要不要继续投”“要不要换策略”，且有投流消耗、转化增长、杠杆率等在投指标 * **推广后**：更像是在问“这轮投完之后要不要再追投”“是否还有长尾价值”，或上下文明确推广已结束 若阶段不明确，优先按用户问法判断；若问法也不明确，再按数据字段判断。仍无法确定时，只输出保守结论，不越级给出强动作建议。 #### Step 3：读取对应知识库章节 * 推广前：读取 `knowledge.md` 的 `## 2` 与 `## 3` * 推广中：读取 `knowledge.md` 的 `## 2` 与 `## 4` * 推广后：读取 `knowledge.md` 的 `## 2` 与 `## 5` * 遇到新歌无数据 / 小众风格 / 机构批量异质歌曲：额外读取 `## 6` * 用户问解释型问题（如“什么是推币”“为什么消耗慢”）：优先读取 `## 7` * 准备最终输出前：回看 `## 8`，确保没有把内部阈值直接说给用户 #### Step 4：把原始指标映射成定性档位 必须先做内部映射，再决定怎么说给用户。映射时遵守以下原则： * 优先使用知识库中已有的量化阈值和分层名称 * 若后端已经给了定性标签，优先把后端标签和知识库规则交叉验证，而不是另起一套口径 * 若缺少某些关键字段，只在已有证据覆盖的维度下结论，不补造缺失维度 重点关注： * 歌曲潜力：播放量、搜播量、转发量、收藏率、完播率、搜播率 * 投流质量：投流消耗率、投流效率、杠杆率、收藏增量、下载量等转化增长 * 生命周期与后续价值：是否适合追投、长尾维护或转自然运营 #### Step 5：生成内部分析结论 结论至少包含以下三部分： 1. **当前判断**：如“更适合小额冷启”“当前投放表现良好”“本轮更像长尾维护价值” 2. **判断依据**：引用命中的知识库逻辑与已拿到的数据维度 3. **下一步动作**：给出继续加投 / 维持观察 / 切换方式 / 暂停付费 / 转自然运营等建议 若是账号级问题，可按“当前整体盘子 + 候选重点歌曲 + 共性建议”组织；若是单首歌问题，必须围绕当前这首歌给出判断。 ### 三类阶段的具体规则 #### 推广前 读取 `knowledge.md` 的 `## 3` 后，优先把歌曲归入： * 优质飙升 * 优质潜力 * 冷启歌曲 * 其他歌曲 然后按用户身份给建议： * 个人音乐人：强调是否适合直接推广、小额冷启、还是先做内容铺垫 * 机构用户：强调是否纳入核心清单、次核心清单或剔除清单 补充平台与方式建议时，优先使用： * 智能推荐 * 歌单推荐 * 潜力养歌 #### 推广中 读取 `knowledge.md` 的 `## 4` 后，优先把歌曲归入： * 优质投放 * 良好投放 * 待调整投放 * 低效投放 动作建议必须四选一为主： * 继续加投 * 维持观察 * 切换方式 * 暂停付费 若需要补充原因，优先解释： * 消耗是否足够快 * 转化是否有增长 * 杠杆率是否说明付费投流正在撬动自然流量 #### 推广后 读取 `knowledge.md` 的 `## 5` 后，优先把歌曲归入： * 推荐追投 * 长尾维护价值 * 自然运营价值 后续建议要围绕： * 是否做二次追投 * 是否保留轻量智能推荐 * 是否转私域/短视频/直播等自然运营 ### 特殊场景规则 遇到以下情况时，必须额外套用 `knowledge.md` 的 `## 6`： * **新歌无数据**：按冷启歌曲处理，不做硬性卡线 * **小众风格歌曲**：允许柔性放宽标准，但只能给“小额冷启 / 继续观察”这类保守建议 * **机构批量异质歌曲**：按赛道分组理解，不把所有歌混成一个结论 ### 输出约束 分析结果**不直接对外**，而是作为 A 类或 B 类问题输出结构的数据源，交由上层 `ai-promotion/readme.md`。 生成时必须遵守： * ❌ **严禁**在对外回答中展示任何具体指标数值、金额、天数、播放量等数字 * ❌ **严禁**在知识库未覆盖的情况下编造分析结论或空泛建议 * ❌ **严禁**为凑满 4 个衍生问题跨主题发散到行业趋势、达人资源、跨平台经验等方向 * ✅ 无数据时，必须明确说明边界，不得伪造单曲数据或账号数据 * ✅ 建议必须具体、可执行、围绕当前单首歌或当前账号问题展开，并说明判断依据 ### `moreQuestions` 生成规则 `moreQuestions` 必须从知识库已覆盖主题里挑 4 个，优先级如下： 1. 数据解读 2. 问题诊断 3. 投流节奏 4. 素材优化 5. 生命周期判断 6. 加投/止损判断 避免生成以下无依据问题： * 行业大盘趋势 * 达人资源获取 * 站外广告经验泛谈 * 未在知识库中定义的跨平台打法 *** ## 本地参考文档 | 文件 | 说明 | | ---------------------------------- | ------------------------------------------- | | `detailed_description_overview.md` | "宣推概览"算子的调用指引、参数参考骨架、返回结构参考、边界 | | `detailed_description_metric.md` | "获取歌曲宣推指标"算子的调用指引、参数参考骨架、返回结构参考、边界 | | `knowledge.md` | 宣推知识库主文件：指标口径、推广前/中/后规则、特殊场景、FAQ、Agent 输出约束 | > 以上两份文档为**参考骨架**，真实 schema 和字段以后端 `get_api_detail` 返回的 `detailedDescription` / `inputSchema` / `exampleOutput` 为准。 *** ## 依赖链条总览 ``` ai-promotion/readme.md ← 最上层：音乐人宣推助手人设，定对外表达规则 │ ▼ ai-promotion-query (本 Skill) ← 本层：业务编排（宣推概览 / 宣推指标 / 指标分析） │ ▼ tme-openapi ← 基础能力：算子发现 + 调用，同时内嵌登录态获取（自包含） ```