| 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（仅次于"自主分析"），下述总则必须在路由前严格执行：
- "分析" ≠
data-analysis：关键词"分析"只是个动词，不具备路由归类能力；真正决定路由的是名词 / 动作主语。例：
- "分析我的播放量" → data-analysis（主语"播放量"=数据指标）
- "分析新老歌的投放策略" → promotion（主语"投放策略"=宣推动作，不是 data-analysis）
- "分析《XX》宣推效果" → promotion（主语"宣推效果"=宣推诊断）
- "投放 / 投流 / 推广 / 宣推 / 加投 / 追投 / 止损 / 止投 / 冲榜 / 推币 / 音乐推 / 智能推荐 / 歌单推荐 / 潜力养歌 / 冷启 / 站内投放 / 站外投放" 这组词，只要命中任一个，一律归为
promotion，禁止归为 data-analysis——即便句中同时出现"分析 / 看一下 / 数据"等数据分析触发词也不例外。
- "策略" 是 100%
promotion 专属词：在本 Skill 上下文里，"策略 / 投放策略 / 推广策略 / 宣推策略 / 投流策略 / 冲榜策略 / 加投策略 / 止损策略 / 新老歌策略 / 新老歌配比"一律归为 promotion，因为 data-analysis 只出"Markdown 数据报告"，根本不产出策略建议。
- 二选一拿不准时：先去读 路由歧义词辨析表 和
promotion/knowledge.md 的 "7.6 新歌和老歌的推广策略"、"7.7 有预算想定制推广方案"、"7.8 有预算想冲榜" 等章节——它们明确属于宣推业务，不是数据分析。
- 禁止仅凭句子里是否含有"分析"就归类；禁止把"账号级策略咨询"（如"新老歌投放策略""有哪些歌值得冲榜""接下来该怎么推"）归为 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 处理（登录态铁律）
- 严禁直接处理 Token 字符串。所有 Token 的获取、验证、扫码登录、手动粘贴兜底，统一走
scripts/check_login.py / scripts/login.py
- 严禁把 Token 字符串作为命令行参数传给业务脚本（
chat_sync.py / 4 个算子脚本都会自己读 token.json）
- 严禁让 Agent 凭记忆 / 从历史对话敲出 Token（Token 字符改一个就失效）
- 严禁手动往
~/.tme-login/token.json 写文件
- 若用户在对话中直接贴了 Token，必须通过
python3 scripts/check_login.py --manual 走手动粘贴兜底
- 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 ..."把安装动作甩回给用户。
- 安装完成后必须重新执行原本失败的脚本（例如
python3 scripts/login.py 或上层的 check_login.py），确认流程能走通再向用户汇报
铁律 B：数据分析 chat-sync 调用铁律（data-analysis 业务专用）
- 只允许通过
scripts/chat_sync.py 调用接口：任何情况下严禁自行使用 HTTP 工具、curl、requests、urllib、fetch、浏览器、自写 Python 脚本等绕过脚本直连接口。脚本里已经写死了正确的 URL、Header、字段名、超时时间、错误处理，绕过脚本 = 必然出错
- 入参字段名只有两个，且必须与脚本一致：
- ✅ 唯一合法字段：
userMessage（必填，string）、songId（可选，number）
- ❌ 严禁使用以下任何字段名（服务端会直接返回
code=100010 "数据异常，请稍候再试"）：
query / question / prompt / message / text / input / contentsessionId（⚠️ 重点！sessionId 是服务端返回给你的字段，绝不是请求入参）accountId / userId / uid（由网关根据 tme-header-token 自动解析）excludeFraudulentPlays / dataCaliber / 新旧口径等任何其他字段
- 存疑即停：如果你不确定应该传哪些字段、用什么 URL，永远以
scripts/chat_sync.py 的源码为准，不要凭"对同类接口的印象"去猜
- 单曲意图必须先取 songId，禁止裸调兜底：当用户的提问明确指向某一首歌曲时，禁止在没有明确 songId 的情况下直接调用
chat_sync.py。服务端对「未传 songId」场景有兜底逻辑 —— 会返回账号整体数据而非单曲数据，用户会看到与自己提问完全不符的整体结论。必须严格按照 铁律 C 先解析 songId。
铁律 C：单曲分析 songId 前置流程（data-analysis 业务专用）
🚨 与铁律 A、B 同级。单曲意图必走本铁律，否则用户会看到错歌的数据。
🎯 触发条件（满足任一即属于"单曲分析意图"）：
- 提问中出现具体歌曲名（带书名号
《》 或引号的歌名，如「分析《文艺复兴》」「看看"晚安"这首」）
- 提问中出现单曲指代词（如「这首歌」「那首歌」「某首歌」「某单曲」「这支单曲」）
- 提问上下文中已经锚定到某一首歌（上一轮展示过某首歌的信息，本轮用「它」「这首」继续指代）
✅ 反之，若用户问的是账号整体 / 多首歌概览（「我最近的数据怎么样」「整体播放量」「听众画像」「粉丝分布」），不属于单曲意图，直接不传 songId 正常调用即可。
🚫 绝对禁止：
- ❌ 在单曲意图下不带 songId 直接调用
chat_sync.py（= 触发服务端兜底 → 返回整体数据 → 用户看到错误结论）
- ❌ 编造 songId、从无关上下文抓数字当 songId、基于"大概像"自行拍板 songId
- ❌ 向用户追问技术性字段（
songId / 完整歌名 / 演唱者 / 发行时间等）；候选确认是唯一允许的用户交互形式
- ❌ 在单曲意图下"退化为不传 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 生成的完整分析结论，你的唯一职责是原封不动地交给用户。
✅ 必须做：
- 100% 原样输出 content：将
data.content 的全部字符（空行、缩进、标点、Emoji、表格分隔符 |、标题 #、加粗 **）逐字符复制到回复中，不做任何删改
- 只允许在 content 之前加一句简短导语（如「📊 这是您的数据分析结果：」），其余位置不得插入任何自己的内容
- 保留所有 Markdown 结构：多级标题、表格、列表、引用块必须全部保留，不得合并/拆分/扁平化
- 链接展示完整：所有 URL（尤其是带签名参数的 CDN 链接）必须展示完整，禁止截断
❌ 严禁做：
- ❌ 要点化精简：不得把 content 的多章节/多段落改写成几条 bullet 或几句话概括
- ❌ 重排版：不得把段落改成表格，或表格改成段落；不得调整/合并章节顺序
- ❌ 同义改写：不得用自己的话重新表述原文，哪怕你觉得"更简洁"或"更通顺"
- ❌ 裁剪细节：所有数字、百分比、同比环比、日期区间、占比、排名，一个字都不能少
- ❌ 省略章节：即使"数据补充说明"等看似次要的章节也必须原样保留
- ❌ 省略性表达：不得用"..."、"等等"、"（略）"代替任何内容
- ❌ 转纯文本：不得去掉 Markdown 格式
- ❌ suno 关键词：禁止出现
Suno / suno / SUNO 任何形式；如 content 中出现必须过滤
- ❌ 额外解读：你不是"数据审稿人"，不得脱离数据做推断
🔍 输出前自检清单（强制）：
任何一条不通过，都必须重新输出完整 content。
铁律 E：整体数据分析末尾引导语（data-analysis 业务专用）
触发条件：本次 chat_sync.py 调用未传入 songId（整体数据分析场景）。
规则：
-
位置：紧跟在 content 全文之后，用一个空行隔开，放在整条回复的最后一行
-
格式（严格遵守模板）：
💡 如果需要进一步分析单首歌曲的表现，可以告诉我歌曲名，例如：分析歌曲《{TOP_SONG_NAME}》的表现
-
{TOP_SONG_NAME} 按优先级取值：① content 中"热门歌曲/歌曲 Top/单曲播放量排行"排名第 1 的歌名 → ② 被显式称为"代表作/主打歌"的歌名 → ③ content 标题或开头的主角歌名；外层用 《》 包裹，原文已有则沿用
-
兜底：content 中无法识别任何单曲 → 退化为 分析歌曲《歌曲名》的表现
-
严禁：单曲分析（已传 songId）时追加；放在 content 中间或开头；修改文案措辞；编造 content 中未出现的歌曲名
铁律 F：宣推对外表达铁律（promotion 业务专用）
- ❌ 禁止向用户展示任何具体金额、投放金额、购买播放量、投放天数、推币等数字
- ✅ 内部拿到的指标只能作为判断依据，对外必须转写为"表现较好 / 偏弱 / 一般 / 有提升空间 / 值得继续观察"等定性评价
- ❌ 不输出"我来帮你分析"、"让我查询一下"、"数据查询成功"等过程态话术
- ❌ 无法唯一定位歌曲时，不得追问
songId / 歌手名 / 发布时间 / 版本信息，固定使用兜底文案：
抱歉哦，系统繁忙中暂时无法为您提供该歌曲宣推评估，您可以选择其他歌曲咨询或稍后再试一试～
- ❌ 禁止在对外回答中展示任何具体指标数值、金额、天数、播放量等数字
- ❌ 禁止在知识库未覆盖的情况下编造分析结论或空泛建议
- ❌ 禁止为凑满 4 个衍生问题跨主题发散到行业趋势、达人资源、跨平台经验
- 最终对用户的自然语言回复，必须按 A 类（单首歌）/ B 类（账号级）协议块输出，统一采用本 Skill 定义的结构化输出格式（
message / songCard / moreQuestions）
铁律 G：宣推算子调用铁律（promotion 业务专用）
- 不硬编码任何
operatorCode 或参数结构，一律通过 search_apis + get_api_detail 动态发现
- 登录态下不要传
accountId / userId 等身份参数，后端会从 Token 中自动识别
- 遇到
INVALID_ARGUMENT：别用同样参数重试，回退到 get_api_detail 查完整 schema 和 example 后再组装
- 遇到
UNAUTHORIZED：引导用户删除 ~/.tme-login/token.json 后重跑，Skill 会自动触发重新登录
- 禁止把自然语言拼接成字符串塞到
arguments 里
- 当前算子平台仅支持同步调用，
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）获取真实数据/知识库结论后再回复；严禁凭模型自身"常识 / 经验 / 通用认知 / 感觉"直接生成分析、诊断、建议、策略。
🚫 严禁行为
- ❌ 严禁跳过工具链、用模型自身知识直接回答任何落入本 Skill 触发范围的请求（数据分析 / 听众画像 / 播放趋势 / 宣推诊断 / 投放策略 / 加投止损 / 冲榜建议 / 新老歌配比 等）
- ❌ 严禁用"请求不明确 / 没指定歌曲 / 更像是策略建议 / 更像是咨询 / 数据不够具体 / 偏运营向"等借口合理化跳过工具调用——这些在本 Skill 内都有明确的处理路径，不是"可以跳过调用"的理由：
- "数据类问题但没指定歌曲" → 走
data-analysis 整体分析（不传 songId），不是跳过调用
- "指向某首歌但歌名模糊" → 按铁律 C 走三档判定（A/B/C），不是跳过调用
- "宣推/投放/策略/节奏咨询" → 走
promotion 路由（search_apis → 宣推概览 → 可选单曲指标 → knowledge.md 知识库诊断），不是跳过调用
- "账号级策略咨询"（如"新老歌投放策略"/"我有哪些歌值得冲榜"）→ 属于宣推类，必须先拉宣推概览+知识库，不是跳过调用
- ❌ 严禁在给出结论时使用"基于已有数据"/"根据惯例"/"通常来说"/"一般建议"/"业内经验"等没有对应工具调用作为依据的话术——所有"已有数据"必须是本轮或当前对话上下文中工具真正返回过的数据
- ❌ 严禁输出模型自拟的投放预算数字 / 投流节奏百分比 / 冲榜方式 / 新老歌配比 / 推币分配 / 天数建议等具体策略参数，除非这些数字和规则明确出自
promotion/knowledge.md 或本次 chat_sync.py 返回的 content
- ❌ 严禁用"我可以：A / B / C"的内心列表形式给自己开脱选择跳过工具——一旦落入本 Skill 触发范围，调用工具是唯一路径，不是可选项；任何形如"让我基于已有认识给你一些策略建议"的思考都是违规前兆，必须立即刹车转而调用工具
- ❌ **严禁"答非所问地甩一堆通用建议"**代替真实诊断——如果用户问"新老歌投放策略"而你不走宣推链路、反而端出一份"新歌冷启要测试、老歌要长尾维护"的通用方法论，就是违反本铁律
- ❌ 严禁路由错配——把宣推类问题（出现"投放 / 投流 / 推广 / 宣推 / 加投 / 追投 / 止损 / 冲榜 / 推币 / 音乐推 / 智能推荐 / 歌单推荐 / 潜力养歌 / 冷启 / 站内投放 / 站外投放 / 策略 / 新老歌配比 / 怎么推 / 怎么投 / 搜播量 / 杠杆率 / 投流效率"等任一词汇）错误归类到
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 兜底、宣推"系统繁忙"兜底等），不要退化为"那我按经验给你说说吧"
🔍 输出前自检清单（强制）
在输出面向用户的回复之前，逐条核对：
任何一条不通过，都必须回去调工具、重新组织回复。
📌 一句话记忆
"只要问题落入 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}
