# Tencent Musician Skills

> 腾讯音乐人智能分析助手（数据分析 + 宣推）。当用户提到以下任一类请求时触发：【数据分析类】分析数据、看播放趋势、歌曲表现、听众画像、数据洞察、粉丝构成、我的数据怎么样、分析这首歌、最近播放量、用户画像、收益分析、歌曲表现如何、粉丝分布、年龄分布、地域分布；【宣推类】我这些歌宣推情况如何、看一下宣推数据、这首歌宣推效果怎么样、我有哪些歌在投放、这首歌还要不要继续投、宣推诊断、宣推表现、投放效果、加投止损、切换方式、暂停付费。本 Skill 整合两大能力：①智能数据分析（自然语言数据分析，固定 chat-sync 同步接口）；②宣推数据查询与诊断（宣推概览+单曲宣推指标+基于知识库的三阶段诊断）。登录态自包含，首次使用会自动弹出浏览器扫码登录，Token 有效期约 30 天。

- Skill: `infometa/tencent-musician-skills` (Agent Skill, multi-file: 19 files)
- Install (CLI): `npx skillmds@latest add infometa/tencent-musician-skills`
- Raw SKILL.md: https://api.skillmd.com/api/skills/infometa/tencent-musician-skills/raw
- Safety review: pending (external: skill-scanner PASS, skillspector WARNING)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: infometa (https://skillmd.com/u/infometa)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/infometa/tencent-musician-skills

---


# 腾讯音乐人智能分析 Skill（tencent-musician-skills）

> **✨ 自包含登录态**：本 Skill 内嵌完整登录能力，不依赖任何外部 Skill，调用方无需设置任何环境变量。首次使用会自动弹出浏览器扫码登录，Token 有效期约 30 天，之后日常调用秒级无感。登录细节见 `references/auth.md`。

## 🎯 场景路由表（必须先路由，再读对应 entry.md）

**核心原则**：进入任何业务分支前，先根据用户问题定位路由键，再读对应的入口文档，不要把所有文档一股脑载入。

### 🚨 路由歧义判定总则（必读，最高优先级）

> **⚠️ 路由错配是本 Skill 第二常见的 bad case（仅次于"自主分析"），下述总则必须在路由前严格执行：**

1. **"分析" ≠ `data-analysis`**：关键词"**分析**"只是个动词，**不具备**路由归类能力；真正决定路由的是**名词 / 动作主语**。例：
   - "**分析**我的播放量" → data-analysis（主语"播放量"=数据指标）
   - "**分析**新老歌的**投放策略**" → **promotion**（主语"投放策略"=宣推动作，**不是** data-analysis）
   - "**分析**《XX》**宣推**效果" → **promotion**（主语"宣推效果"=宣推诊断）
2. **"投放 / 投流 / 推广 / 宣推 / 加投 / 追投 / 止损 / 止投 / 冲榜 / 推币 / 音乐推 / 智能推荐 / 歌单推荐 / 潜力养歌 / 冷启 / 站内投放 / 站外投放"** 这组词，**只要命中任一个，一律归为 `promotion`**，**禁止归为 `data-analysis`**——即便句中同时出现"分析 / 看一下 / 数据"等数据分析触发词也不例外。
3. **"策略"** 是 **100% `promotion` 专属词**：在本 Skill 上下文里，"策略 / 投放策略 / 推广策略 / 宣推策略 / 投流策略 / 冲榜策略 / 加投策略 / 止损策略 / 新老歌策略 / 新老歌配比"**一律归为 `promotion`**，因为 data-analysis 只出"Markdown 数据报告"，**根本不产出策略建议**。
4. **二选一拿不准时**：先去读 [路由歧义词辨析表](#-路由歧义词辨析表) 和 `promotion/knowledge.md` 的 "7.6 新歌和老歌的推广策略"、"7.7 有预算想定制推广方案"、"7.8 有预算想冲榜" 等章节——它们**明确属于宣推业务**，不是数据分析。
5. **禁止**仅凭句子里是否含有"分析"就归类；**禁止**把"账号级策略咨询"（如"新老歌投放策略""有哪些歌值得冲榜""接下来该怎么推"）归为 data-analysis。

### 📋 路由表

| 路由键          | 触发场景关键词                                                                                                   | 入口文档                    |
| -------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------- |
| `data-analysis` | 分析数据 / 播放趋势 / 歌曲表现 / 听众画像 / 数据洞察 / 粉丝构成 / 最近播放量 / 用户画像 / 粉丝分布 / 年龄分布 / 地域分布 / 分析这首歌 | `data-analysis/entry.md`   |
| `promotion`     | 我这些歌宣推情况 / 看一下宣推数据 / 我有哪些歌在投放 / 这首歌宣推效果怎么样 / 这首歌还要不要继续投 / 宣推诊断 / 宣推表现 / 投放效果 / 投放策略 / 新老歌投放策略 / 加投止损 / 切换方式 / 暂停付费 / 冲榜 / 冲榜策略 / 冷启 / 推币 / 音乐推 / 智能推荐 / 歌单推荐 / 潜力养歌 / 站内投放 / 站外投放 / 搜播量 / 杠杆率 / 投流效率 | `promotion/entry.md`       |

### 🚨 路由歧义词辨析表

> 下表列出**最容易被弱模型误判**的边界词/短语，每一条都经过真实 bad case 验证。**路由时以本表为准**，优先级高于"关键词模糊匹配"。

| 触发词 / 典型用户说法 | ✅ 正确路由 | ❌ 常见错误归类 | 判定理由 |
| --- | --- | --- | --- |
| "**投放 / 投放策略 / 投放效果 / 投放节奏**" | `promotion` | ❌ data-analysis（看到"分析"就错） | "投放"在本平台专指**付费投流**（音乐推 / 推币），属于宣推业务 |
| "**新老歌投放策略** / 新歌和老歌怎么推 / 接下来该怎么推" | `promotion` | ❌ data-analysis | 对应 `knowledge.md § 7.6`，是明确的宣推策略场景 |
| "**策略** / 推广策略 / 宣推策略 / 投流策略 / 加投策略 / 止损策略" | `promotion` | ❌ data-analysis | data-analysis **不产出策略**，只出数据报告；策略 = 宣推 |
| "**加投 / 追投 / 止损 / 止投 / 是否继续投 / 要不要加量**" | `promotion` | ❌ data-analysis | `knowledge.md § 4~5` 的推广中/推广后动作词 |
| "**冲榜 / 冲飙升榜 / 冲新歌榜 / 冲热歌榜 / 冲刺榜单**" | `promotion` | ❌ data-analysis | `knowledge.md § 7.8` 宣推专属场景 |
| "**推币 / 推币怎么花 / 推币怎么用 / 推币结算**" | `promotion` | ❌ data-analysis | 推币是宣推结算单位，不是数据指标 |
| "**音乐推 / QQ 音乐推 / 酷狗音乐推**" | `promotion` | ❌ data-analysis | 音乐推 = 付费推广产品 |
| "**智能推荐 / 歌单推荐 / 潜力养歌 / 快速起量 / 歌曲展示**" | `promotion` | ❌ data-analysis | 均为宣推方式 |
| "**冷启 / 冷启动 / 小额冷启 / 冷启歌曲**" | `promotion` | ❌ data-analysis | 宣推业务标准分层 |
| "**站内投放 / 站外投放 / 抖音快手投放 / 腾讯广告投放**" | `promotion` | ❌ data-analysis | `knowledge.md § 7.7` 套餐 1/2 专属 |
| "**搜播量 / 搜播率 / 杠杆率 / 投流消耗率 / 投流效率 / 收藏增量**" | `promotion` | ❌ data-analysis | 均为 `knowledge.md § 2` 的宣推指标 |
| "**优质飙升 / 优质潜力 / 优质投放 / 待调整投放 / 低效投放**" | `promotion` | ❌ data-analysis | 均为宣推分层名称 |
| "**长尾维护 / 自然运营 / 追投 / 复盘**（宣推语境下）" | `promotion` | ❌ data-analysis | `knowledge.md § 5` 推广后动作 |
| "**代投 / 排期 / 投放计划 / 投放门槛**" | `promotion` | ❌ data-analysis | `knowledge.md § 7.7` 专属 |
| "**推广方案 / 推广建议 / 宣推建议 / 怎么推 / 怎么投**" | `promotion` | ❌ data-analysis | 本 Skill 内"推广 / 宣推 / 投"触发词 |
| "**听众画像 / 粉丝画像 / 粉丝构成 / 年龄分布 / 性别分布 / 地域分布**" | `data-analysis` | — | 纯画像类，data-analysis 专属 |
| "**播放量 / 播放趋势 / 最近 N 天播放 / 同比环比 / 粉丝数变化**" | `data-analysis` | — | 纯数据指标趋势 |
| "**表现如何 / 效果怎么样**"（裸问） | **看修饰语** | — | 若同句有"投放/宣推/推广/加投"→ `promotion`；若指向单首歌或整体数据 → `data-analysis`（走单曲分析或整体分析） |
| "**分析一下**"（单独出现） | **看宾语** | — | 宾语是"投放/策略/宣推/冲榜" → `promotion`；宾语是"播放/画像/数据/趋势" → `data-analysis` |

> 📌 **一句话记忆**：**名词定路由，动词不定路由**。"分析"是动词，不决定归类；决定归类的是它后面带的那个**名词**（"播放量" vs "投放策略"）。

> 内部基础能力文档（业务层在 entry.md 中被引用，用户侧**不暴露**）：
> - `references/auth.md`：登录态管理（Token 回退链、重新登录、Playwright 依赖）
> - `references/openapi_reference.md`：TME OpenAPI 算子 4 件套通用调用流程（仅 `promotion` 业务使用）

## 📁 目录结构

```
tencent-musician-skills/
├── SKILL.md                              # 本文件：路由 + 全部铁律 + 错误码速查
├── scripts/                              # 共享脚本（Token 管理 + 算子调用 + chat-sync）
│   ├── _token.py                         # 登录态核心模块（Token 回退链 API）
│   ├── check_login.py                    # 获取登录态（带自动回退）
│   ├── login.py                          # 有头扫码登录
│   ├── get_token_from_browser.py         # 从 storage_state 无头读取 Token（内部）
│   ├── verify_token.py                   # 验证 Token 有效性
│   ├── list_apis.py                      # 算子：列出全部
│   ├── search_apis.py                    # 算子：按关键词搜索
│   ├── get_api_detail.py                 # 算子：获取详情
│   ├── invoke_api.py                     # 算子：发起调用
│   └── chat_sync.py                      # 数据分析：同步 chat-sync 接口
├── references/
│   ├── auth.md                           # 登录态管理
│   └── openapi_reference.md              # 算子通用调用流程 + 错误码
├── promotion/                            # 宣推业务分支
│   ├── entry.md                          # 宣推业务主流程（概览 + 指标 + 分析）
│   ├── detailed_description_overview.md  # 宣推概览算子参考骨架
│   ├── detailed_description_metric.md    # 歌曲宣推指标算子参考骨架
│   └── knowledge.md                      # 宣推知识库：三阶段规则、指标口径、FAQ
└── data-analysis/                        # 数据分析业务分支
    ├── entry.md                          # 数据分析主流程（songId 前置 + chat-sync）
    └── module-a-data-analysis.md         # 详细规范 / 场景示例 / 话术模板
```

---

## 🚨 核心铁律（跨业务通用，最高优先级）

> 以下铁律**全部在 SKILL.md 可见**，不依赖子文档。任何分支都必须遵守。

### 铁律 A：Token 处理（登录态铁律）

1. **严禁**直接处理 Token 字符串。所有 Token 的获取、验证、扫码登录、手动粘贴兜底，统一走 `scripts/check_login.py` / `scripts/login.py`
2. **严禁**把 Token 字符串作为命令行参数传给业务脚本（`chat_sync.py` / 4 个算子脚本都会自己读 `token.json`）
3. **严禁**让 Agent 凭记忆 / 从历史对话敲出 Token（Token 字符改一个就失效）
4. **严禁**手动往 `~/.tme-login/token.json` 写文件
5. 若用户在对话中直接贴了 Token，必须通过 `python3 scripts/check_login.py --manual` 走手动粘贴兜底
6. **Playwright 缺失时 AI 必须主动安装**：当脚本 stderr 出现 `❌ 未检测到 Playwright` / `PLAYWRIGHT_MISSING` / `ModuleNotFoundError: No module named 'playwright'` 时，AI 必须立即在终端执行：
   ```bash
   python3 -m pip install --upgrade playwright
   python3 -m playwright install chromium
   ```
   然后重跑原脚本。**禁止**向用户输出"请你先执行 pip install ..."把安装动作甩回给用户。
7. 安装完成后**必须重新执行**原本失败的脚本（例如 `python3 scripts/login.py` 或上层的 `check_login.py`），确认流程能走通再向用户汇报

### 铁律 B：数据分析 chat-sync 调用铁律（`data-analysis` 业务专用）

1. **只允许通过 `scripts/chat_sync.py` 调用接口**：任何情况下**严禁**自行使用 HTTP 工具、curl、`requests`、`urllib`、`fetch`、浏览器、自写 Python 脚本等**绕过脚本直连接口**。脚本里已经写死了正确的 URL、Header、字段名、超时时间、错误处理，绕过脚本 = **必然出错**
2. **入参字段名只有两个，且必须与脚本一致**：
   - ✅ 唯一合法字段：`userMessage`（必填，string）、`songId`（可选，number）
   - ❌ **严禁**使用以下任何字段名（服务端会直接返回 `code=100010` "数据异常，请稍候再试"）：
     - `query` / `question` / `prompt` / `message` / `text` / `input` / `content`
     - `sessionId`（⚠️ 重点！`sessionId` 是**服务端返回**给你的字段，**绝不是请求入参**）
     - `accountId` / `userId` / `uid`（由网关根据 `tme-header-token` 自动解析）
     - `excludeFraudulentPlays` / `dataCaliber` / 新旧口径等任何其他字段
3. **存疑即停**：如果你不确定应该传哪些字段、用什么 URL，**永远**以 `scripts/chat_sync.py` 的源码为准，不要凭"对同类接口的印象"去猜
4. **单曲意图必须先取 songId，禁止裸调兜底**：当用户的提问**明确指向某一首歌曲**时，**禁止**在没有明确 songId 的情况下直接调用 `chat_sync.py`。服务端对「未传 songId」场景**有兜底逻辑 —— 会返回账号整体数据而非单曲数据**，用户会看到**与自己提问完全不符的整体结论**。必须严格按照 **铁律 C** 先解析 songId。

### 铁律 C：单曲分析 songId 前置流程（`data-analysis` 业务专用）

> 🚨 **与铁律 A、B 同级。单曲意图必走本铁律，否则用户会看到错歌的数据。**

**🎯 触发条件**（满足任一即属于"单曲分析意图"）：

1. 提问中出现**具体歌曲名**（带书名号 `《》` 或引号的歌名，如「分析《文艺复兴》」「看看"晚安"这首」）
2. 提问中出现**单曲指代词**（如「这首歌」「那首歌」「某首歌」「某单曲」「这支单曲」）
3. 提问上下文中**已经锚定到某一首歌**（上一轮展示过某首歌的信息，本轮用「它」「这首」继续指代）

> ✅ 反之，若用户问的是账号整体 / 多首歌概览（「我最近的数据怎么样」「整体播放量」「听众画像」「粉丝分布」），**不属于**单曲意图，**直接不传 songId** 正常调用即可。

**🚫 绝对禁止**：

1. ❌ 在单曲意图下不带 songId 直接调用 `chat_sync.py`（= 触发服务端兜底 → 返回整体数据 → 用户看到错误结论）
2. ❌ 编造 songId、从无关上下文抓数字当 songId、基于"大概像"自行拍板 songId
3. ❌ 向用户追问技术性字段（`songId` / 完整歌名 / 演唱者 / 发行时间等）；候选确认是**唯一**允许的用户交互形式
4. ❌ 在单曲意图下"退化为不传 songId，让服务端自己猜" —— 服务端猜错 = 用户感知到错结果，责任在调用方

**✅ 三档判定**（设用户指向歌名 `Q`，整体 content 中候选映射集合 `M`）：

| 档位 | 判定条件 | 动作 |
| --- | --- | --- |
| **A 精准匹配** | `M` 中**恰有一条** `songName` 与 `Q` 规范化后（去书名号/空格/大小写）**完全相等** | ✅ 直接取该条 `songId`，以**用户原始 userMessage** 发起单曲分析，**无需向用户确认** |
| **B 相似命中** | 存在包含/被包含/标点差异/同名多条等**明显相似**候选 | ❔ 输出**候选确认话术**让用户选；在用户确认前**不传 songId、不调单曲分析** |
| **C 无法匹配** | `Q` 与 `M` 中所有条目都无明显相似 / `M` 为空 / content 中根本没有单曲信息 | ❌ 输出**匹配失败兜底话术**并**立即终止**：不传 songId、不调单曲分析、不退化为裸调、**不尝试任何其他途径** |

**档 C 兜底话术（字符级严格遵守）**：

```
很抱歉，暂时不支持对《{USER_SONG_NAME}》这首歌进行数据分析，您可以尝试分析其他歌曲~
```

- 只替换 `{USER_SONG_NAME}` 为用户提到的原始歌名（保留书名号/原文写法），其他字符不改
- 若用户未给出明确歌名（如「这首」「那首」），整段 `《{USER_SONG_NAME}》` 替换为「该歌曲」
- **面向用户的最终回复有且仅有上方那一行固定话术**，严禁在其前/后/中附加任何其他文字（包括推理过程、技术术语、引导尾巴、元信息）
- **禁止**"换个提问方式再调一次整体分析"/"限定其他时间窗口再提取歌曲列表"/"裸调让服务端兜底"/"导向其他 skill 查 songId" 等任何发散尝试

> 档 B 候选确认话术模板、Step ①~④ 完整流程、正反示例详见 `data-analysis/entry.md` 第 1.5 步和 `data-analysis/module-a-data-analysis.md`。

### 铁律 D：数据分析 content 展示铁律（`data-analysis` 业务专用）

> **核心原则：你是"搬运工"，不是"编辑"。** 接口返回的 `data.content` 是后端 ChatBI 生成的**完整分析结论**，你的唯一职责是**原封不动**地交给用户。

**✅ 必须做**：

1. **100% 原样输出 content**：将 `data.content` 的**全部字符**（空行、缩进、标点、Emoji、表格分隔符 `|`、标题 `#`、加粗 `**`）**逐字符复制**到回复中，不做任何删改
2. 只允许在 content 之前加**一句**简短导语（如「📊 这是您的数据分析结果：」），其余位置不得插入任何自己的内容
3. **保留所有 Markdown 结构**：多级标题、表格、列表、引用块必须全部保留，不得合并/拆分/扁平化
4. **链接展示完整**：所有 URL（尤其是带签名参数的 CDN 链接）必须展示完整，禁止截断

**❌ 严禁做**：

1. ❌ **要点化精简**：不得把 content 的多章节/多段落改写成几条 bullet 或几句话概括
2. ❌ **重排版**：不得把段落改成表格，或表格改成段落；不得调整/合并章节顺序
3. ❌ **同义改写**：不得用自己的话重新表述原文，哪怕你觉得"更简洁"或"更通顺"
4. ❌ **裁剪细节**：所有数字、百分比、同比环比、日期区间、占比、排名，**一个字都不能少**
5. ❌ **省略章节**：即使"数据补充说明"等看似次要的章节也必须原样保留
6. ❌ **省略性表达**：不得用"..."、"等等"、"（略）"代替任何内容
7. ❌ **转纯文本**：不得去掉 Markdown 格式
8. ❌ **suno 关键词**：禁止出现 `Suno` / `suno` / `SUNO` 任何形式；如 content 中出现必须过滤
9. ❌ **额外解读**：你不是"数据审稿人"，不得脱离数据做推断

**🔍 输出前自检清单（强制）**：

- [ ] 字符数是否 ≥ 原始 content？（允许只多不少，仅比 content 多出导语 + 末尾引导语）
- [ ] 每一个 `##` / `###` 标题是否都原样出现？
- [ ] 每一个表格是否都完整保留（行数、列数、单元格一致）？
- [ ] 每一个数字、百分比是否一字不差？
- [ ] 是否**没有**用自己的话重新组织/概括/改写任何段落？
- [ ] 整体分析（未传 songId）是否按规则追加了末尾引导语？
- [ ] 单曲分析（已传 songId）是否**没有**追加那句引导语？

**任何一条不通过，都必须重新输出完整 content。**

### 铁律 E：整体数据分析末尾引导语（`data-analysis` 业务专用）

**触发条件**：本次 `chat_sync.py` 调用**未传入 `songId`**（整体数据分析场景）。

**规则**：

1. 位置：紧跟在 content 全文之后，用一个空行隔开，放在整条回复的**最后一行**
2. 格式（严格遵守模板）：

   ```
   💡 如果需要进一步分析单首歌曲的表现，可以告诉我歌曲名，例如：分析歌曲《{TOP_SONG_NAME}》的表现
   ```
3. `{TOP_SONG_NAME}` 按优先级取值：① content 中"热门歌曲/歌曲 Top/单曲播放量排行"排名第 1 的歌名 → ② 被显式称为"代表作/主打歌"的歌名 → ③ content 标题或开头的主角歌名；外层用 `《》` 包裹，原文已有则沿用
4. 兜底：content 中无法识别任何单曲 → 退化为 `分析歌曲《歌曲名》的表现`
5. **严禁**：单曲分析（已传 songId）时追加；放在 content 中间或开头；修改文案措辞；编造 content 中未出现的歌曲名

### 铁律 F：宣推对外表达铁律（`promotion` 业务专用）

1. ❌ **禁止向用户展示任何具体金额、投放金额、购买播放量、投放天数、推币等数字**
2. ✅ 内部拿到的指标只能作为判断依据，对外必须转写为"表现较好 / 偏弱 / 一般 / 有提升空间 / 值得继续观察"等定性评价
3. ❌ 不输出"我来帮你分析"、"让我查询一下"、"数据查询成功"等过程态话术
4. ❌ 无法唯一定位歌曲时，**不得追问 `songId` / 歌手名 / 发布时间 / 版本信息**，固定使用兜底文案：
   ```
   抱歉哦，系统繁忙中暂时无法为您提供该歌曲宣推评估，您可以选择其他歌曲咨询或稍后再试一试～
   ```
5. ❌ 禁止在对外回答中展示任何具体指标数值、金额、天数、播放量等数字
6. ❌ 禁止在知识库未覆盖的情况下编造分析结论或空泛建议
7. ❌ 禁止为凑满 4 个衍生问题跨主题发散到行业趋势、达人资源、跨平台经验
8. 最终对用户的自然语言回复，必须按 A 类（单首歌）/ B 类（账号级）协议块输出，统一采用本 Skill 定义的结构化输出格式（`message` / `songCard` / `moreQuestions`）

### 铁律 G：宣推算子调用铁律（`promotion` 业务专用）

1. **不硬编码任何 `operatorCode` 或参数结构**，一律通过 `search_apis` + `get_api_detail` 动态发现
2. 登录态下**不要**传 `accountId` / `userId` 等身份参数，后端会从 Token 中自动识别
3. 遇到 `INVALID_ARGUMENT`：**别用同样参数重试**，回退到 `get_api_detail` 查完整 schema 和 example 后再组装
4. 遇到 `UNAUTHORIZED`：引导用户删除 `~/.tme-login/token.json` 后重跑，Skill 会自动触发重新登录
5. **禁止**把自然语言拼接成字符串塞到 `arguments` 里
6. 当前算子平台**仅支持同步调用**，`invoke_api` 一次请求即为终态，无需轮询

### 铁律 H：等待体验规范（`data-analysis` 业务专用）

数据分析正常耗时 **20~90 秒**，偶发可达 **3 分钟**。等待期间：

- ✅ 「📊 正在分析中，请稍候...」
- ✅ 「⏳ 数据分析通常需要 20~90 秒，马上为您呈现结果」
- ❌ 「看起来服务有点慢」「似乎遇到延迟」「服务可能繁忙」等暗示服务异常的话术

### 铁律 I：严禁自主分析（跨业务通用）

> 🚨 **与铁律 A~H 同级，跨 `data-analysis` / `promotion` 两大业务通用。本 Skill 最高优先级反模式规则。**

**核心原则**：任何落入本 Skill 触发范围的请求，都**必须**通过对应业务的工具链（`scripts/chat_sync.py` 或算子 4 件套 + `promotion/knowledge.md`）获取真实数据/知识库结论后再回复；**严禁**凭模型自身"常识 / 经验 / 通用认知 / 感觉"直接生成分析、诊断、建议、策略。

#### 🚫 严禁行为

1. ❌ **严禁跳过工具链、用模型自身知识直接回答**任何落入本 Skill 触发范围的请求（数据分析 / 听众画像 / 播放趋势 / 宣推诊断 / 投放策略 / 加投止损 / 冲榜建议 / 新老歌配比 等）
2. ❌ **严禁用"请求不明确 / 没指定歌曲 / 更像是策略建议 / 更像是咨询 / 数据不够具体 / 偏运营向"等借口合理化跳过工具调用**——这些在本 Skill 内**都有明确的处理路径**，不是"可以跳过调用"的理由：
   - "数据类问题但没指定歌曲" → 走 `data-analysis` 整体分析（不传 `songId`），**不是**跳过调用
   - "指向某首歌但歌名模糊" → 按铁律 C 走三档判定（A/B/C），**不是**跳过调用
   - "宣推/投放/策略/节奏咨询" → 走 `promotion` 路由（`search_apis` → 宣推概览 → 可选单曲指标 → `knowledge.md` 知识库诊断），**不是**跳过调用
   - "账号级策略咨询"（如"新老歌投放策略"/"我有哪些歌值得冲榜"）→ **属于**宣推类，必须先拉宣推概览+知识库，**不是**跳过调用
3. ❌ **严禁在给出结论时使用"基于已有数据"/"根据惯例"/"通常来说"/"一般建议"/"业内经验"**等**没有对应工具调用作为依据**的话术——所有"已有数据"必须是本轮或当前对话上下文中工具真正返回过的数据
4. ❌ **严禁输出模型自拟的投放预算数字 / 投流节奏百分比 / 冲榜方式 / 新老歌配比 / 推币分配 / 天数建议**等具体策略参数，除非这些数字和规则**明确出自** `promotion/knowledge.md` 或本次 `chat_sync.py` 返回的 `content`
5. ❌ **严禁用"我可以：A / B / C"的内心列表形式给自己开脱选择跳过工具**——一旦落入本 Skill 触发范围，**调用工具是唯一路径**，不是可选项；任何形如"让我基于已有认识给你一些策略建议"的思考都是**违规前兆**，必须立即刹车转而调用工具
6. ❌ **严禁"答非所问地甩一堆通用建议"**代替真实诊断——如果用户问"新老歌投放策略"而你不走宣推链路、反而端出一份"新歌冷启要测试、老歌要长尾维护"的通用方法论，**就是**违反本铁律
7. ❌ **严禁路由错配**——把**宣推类问题**（出现"投放 / 投流 / 推广 / 宣推 / 加投 / 追投 / 止损 / 冲榜 / 推币 / 音乐推 / 智能推荐 / 歌单推荐 / 潜力养歌 / 冷启 / 站内投放 / 站外投放 / 策略 / 新老歌配比 / 怎么推 / 怎么投 / 搜播量 / 杠杆率 / 投流效率"等任一词汇）**错误归类到 `data-analysis`** 调 `chat_sync.py`。这是本 Skill **第二严重的 bad case**，后果比"自主分析"更糟：
   - ❌ **反例**：用户问"分析新老歌投放策略" → 模型想"有'分析'二字，没指定歌曲 → 归 data-analysis → 调 `chat_sync.py`" → 拿回来的是**账号级播放量趋势报告**，**完全答非所问**，用户看完以为这就是策略
   - ✅ **正例**：用户问"分析新老歌投放策略" → 识别"投放策略"为宣推关键词 → 走 `promotion` 路由 → `search_apis("宣推概览")` + `search_apis("获取歌曲宣推指标")` + 读 `knowledge.md § 7.6 新歌和老歌的推广策略`+ 按 A/B 类协议块输出
   - **判定口诀**：**名词定路由、动词不定路由**。"分析"是动词，不具备路由归类能力；真正决定路由的是它修饰的**名词**——"播放量 / 画像" 走 `data-analysis`，"投放 / 策略 / 冲榜 / 宣推 / 推币" 走 `promotion`。路由前必读主 `SKILL.md` 的「🚨 路由歧义判定总则」和「🚨 路由歧义词辨析表」

#### ✅ 正确处理

- **数据类问题**（播放量 / 听众画像 / 粉丝分布 / 年龄分布 / 地域 / 播放趋势）→ 走 `data-analysis/entry.md`，调 `scripts/chat_sync.py`
- **宣推类问题**（投放效果 / 诊断 / 加投止损 / 策略 / 节奏 / 冲榜 / 新老歌配比 / 推币使用）→ 走 `promotion/entry.md`，调算子 4 件套 + `promotion/knowledge.md`
- **问题极度模糊、路由不清晰** → 宁可**先调一次整体分析** / **先 `search_apis` 搜一次宣推相关算子**拿到真实数据再回复，也**不要**凭模型自己的"认知"编答案
- **工具返回明确无数据 / 无权限 / 异常** → 按对应业务的兜底文案输出（档 C 兜底、宣推"系统繁忙"兜底等），**不要**退化为"那我按经验给你说说吧"

#### 🔍 输出前自检清单（强制）

在输出面向用户的回复之前，逐条核对：

- [ ] 我本轮回复的每一条"数据"/"结论"/"建议"/"策略"，是否都能追溯到**本 Skill 工具的真实返回值**或 **`knowledge.md` 的明确规则**？
- [ ] 我是否**没有**用"请求不明确"/"更像咨询"/"没指定歌曲"这类理由跳过工具调用？
- [ ] 我输出的具体数字（预算百分比、天数、推币、排名）是否都**有工具返回或知识库来源**？
- [ ] 如果工具链结果显示数据不足，我是否用了兜底文案，而**不是**补了一段"根据经验建议……"？
- [ ] 我的思考过程里是否出现过"让我基于已有认识给一些建议"/"我可以直接按通用规则回答"等信号？如果是，立即停止、调工具。

**任何一条不通过，都必须回去调工具、重新组织回复。**

#### 📌 一句话记忆

> **"只要问题落入 tencent-musician-skills 触发范围，真实数据 + 知识库规则是唯一依据；模型自己的'经验'和'常识'在本 Skill 里禁止作为回答依据。"**

---

## 🔧 调用方式速查

| 场景         | 命令                                                         |
| ------------ | ------------------------------------------------------------ |
| 整体数据分析 | `python3 scripts/chat_sync.py "<userMessage>"`               |
| 单曲数据分析 | `python3 scripts/chat_sync.py "<userMessage>" <songId>`      |
| 搜索算子     | `python3 scripts/search_apis.py <keyword>`                   |
| 查算子详情   | `python3 scripts/get_api_detail.py <operatorCode>`           |
| 调用算子     | `python3 scripts/invoke_api.py <operatorCode> '<json>'`      |
| 校验登录态   | `TOKEN=$(python3 scripts/check_login.py)`                    |
| 强制重新登录 | `rm -f ~/.tme-login/token.json ~/.tme-login/storage_state.json && python3 scripts/login.py` |

---

## ❌ 错误码速查

### chat-sync 接口（数据分析）

#### `finishReason`

| finishReason     | 含义                  | 处理                                                                                   |
| ---------------- | --------------------- | -------------------------------------------------------------------------------------- |
| `COMPLETE`       | 正常完成              | **完整原样**展示 `data.content`（见铁律 D）                                            |
| `SAFETY_REVOKED` | 输入/输出命中安全校验 | 提示用户："您的问题或 AI 回答中可能包含敏感内容，请调整提问方式后重试。"；**不要**重试 |
| `TIMEOUT`        | 同步等待超时          | 提示用户："数据分析耗时较长，请稍后再试~"；**不要**直接重试，接口不幂等                |
| `UPSTREAM_ERROR` | 上游 ChatBI 异常      | 可重试**1 次**；仍失败提示"服务繁忙，请稍后再试"                                       |

#### `BaseResponse.code != 0`

| 场景                | message / code 关键字            | 处理                                                                     |
| ------------------- | -------------------------------- | ------------------------------------------------------------------------ |
| 未登录 / Token 失效 | 非 0 code，提示未登录 / 未知用户 | 执行 `python3 scripts/login.py` 重新登录后重试业务                       |
| 日配额用尽          | 「使用次数达 10 次」             | 不要重试，直接告知："您今天的数据助手提问次数已达上限，欢迎明天再来~"    |
| 歌曲命中安全打击    | 「歌曲不支持分析」               | 告知用户："很抱歉，这首歌当前不支持数据分析。换一首试试？"；**不要**重试 |
| 参数错误            | 「userMessage 不能为空」等       | 修正入参后重试                                                           |
| **请求字段错误**    | `code = 100010` / 「数据异常，请稍候再试」 | **绝大概率是绕过脚本自己拼请求导致字段名错误**（传了 `query`/`sessionId` 等非法字段）。**不要重试**，必须改用 `python3 scripts/chat_sync.py "<userMessage>" [songId]` 正确调用 |

### TME OpenAPI 算子（宣推业务）

外层响应结构为 `{ success, data, error, meta }`，`success=false` 时读 `error.code`：

| error.code         | 含义         | 能重试 | 怎么办                                                               |
| ------------------ | ------------ | ------ | -------------------------------------------------------------------- |
| `INVALID_ARGUMENT` | 参数错误     | 否     | 调 `get_api_detail` 重新确认 schema，修正参数再试                    |
| `NOT_FOUND`        | 算子不存在   | 否     | 调 `search_apis` 重新确认 `operatorCode`                             |
| `UNAUTHORIZED`     | 未认证       | 否     | 删除 `~/.tme-login/token.json` 后重跑，Skill 会自动触发重新登录      |
| `RATE_LIMITED`     | 限流         | 是     | 等一会儿再试                                                         |
| `TIMEOUT`          | 超时         | 是     | 重试，可设更大 `timeoutMs`                                           |
| `UPSTREAM_ERROR`   | 上游服务异常 | 是     | 重试 1-2 次，仍失败则按宣推兜底文案输出                              |

---

## 📎 依赖链条总览

```
上层 Agent（若有）                                        ← 由调用方维护的对外人设与输出规则
        │
        ▼
tencent-musician-skills（本 Skill）                           ← 路由：data-analysis / promotion
        │
        ├─ data-analysis/entry.md  → scripts/chat_sync.py
        │
        └─ promotion/entry.md      → scripts/{search,get_api_detail,invoke,list}_apis.py
                                        + promotion/knowledge.md 做诊断
        │
        ▼
scripts/{_token,check_login,login,get_token_from_browser,verify_token}.py
        │                                               ← 登录态自包含
        ▼
~/.tme-login/{token.json, storage_state.json}
```