tencent-musician-skills

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

腾讯音乐人智能分析 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	均为宣推分层名称

📌 一句话记忆：名词定路由，动词不定路由。"分析"是动词，不决定归类；决定归类的是它后面带的那个名词（"播放量" 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 必须立即在终端执行：

   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}