​

腾讯音乐人智能数据分析助手

📌 固定接口：POST https://y.tencentmusic.com/openapi/v1/musician/data/agent/chat-sync

​

第一步：确保登录态

⚠️ 前置依赖：本 Skill 的登录能力完全委托给同目录下的 tme-openapi skill，本 Skill 不再包含任何独立的登录逻辑。

​

登录态来源（唯一可信路径）

┌─────────────────────────────────────┐        生产           ┌──────────────────────────┐
│    tme-openapi skill                │ ─────────────────────▶│  ~/.tme-login/token.json │
│ (_token.py / check_login.py / login)│                        └────────────┬─────────────┘
└─────────────────────────────────────┘                                     │ 读取
                                                                            ▼
                                                        ┌──────────────────────────────┐
                                                        │  ai-data-analysis skill      │
                                                        │  (chat_sync.py / 本 skill)   │
                                                        └──────────────────────────────┘

📌 缓存目录名沿用 ~/.tme-login/ 是历史约定，当前由 tme-openapi skill 自包含维护，与是否存在独立的 tme-login skill 无关。

​

🚨 Token 处理铁律（最高优先级，严禁违反）

本 Skill 的 Agent 不要直接处理 Token 字符串。所有 Token 的获取、验证、扫码登录、手动粘贴兜底等环节全部由 tme-openapi skill 负责。

1. 严禁在 ai-data-analysis 的脚本里重新实现登录流程
2. 严禁把 Token 字符串作为命令行参数传给 ai-data-analysis 的任何脚本
3. 严禁让 Agent 凭记忆 / 从历史对话敲出 Token（Token 字符改一个就失效）
4. 严禁绕过 tme-openapi 直接往 ~/.tme-login/token.json 写文件
5. 若用户在对话中直接贴了 Token，必须转交给 tme-openapi 处理（参见下方 Step 2）

​

获取登录态的标准流程

​

Step 1：调用本 skill 的 check_login.py（推荐，零感知）

python3 scripts/check_login.py

1. 优先通过 sys.path 注入同目录下的 tme-openapi/scripts/，调用 _token.get_tme_header_token() Python API 拿 Token（秒级命中 ~/.tme-login/token.json）
2. Python API 不可用 → 回退到子进程调起 tme-openapi/scripts/check_login.py，由它完成「缓存 → 无头刷新 → 必要时扫码登录」的完整获取链
3. 仍拿不到 → 打印引导信息到 stderr 并 exit 1

# 仅校验登录态是否就绪（stdout 会输出 Token 本体一行）
TOKEN=$(python3 scripts/check_login.py)

# 或者直接进入业务调用——chat_sync.py 内部会自己读 token.json，不需要显式 export
python3 scripts/chat_sync.py "我最近7天的播放量怎么样？"

💡 chat_sync.py 已内置 ~/.tme-login/token.json 读取逻辑，绝大多数场景无需显式调用 check_login.py，直接调 chat_sync.py 即可。check_login.py 主要用于调试或在新环境中提前验证登录态。

​

Step 2：本地无有效 Token 或用户想重新登录时

• 用户未登录过 / Token 过期 / API 返回 UNAUTHORIZED：
  # 运行 tme-openapi 的登录流程（会弹出浏览器扫码或走无头刷新）
  python3 ../tme-openapi/scripts/login.py
  # 或
  python3 ../tme-openapi/scripts/check_login.py
  
  登录成功后 Token 会自动写入 ~/.tme-login/token.json，本 skill 的后续调用就能直接复用。
• 用户在对话中直接贴了 Token： 交由 tme-openapi skill 规范处理（可执行 python3 ../tme-openapi/scripts/check_login.py --manual 走手动粘贴兜底）。不要让 ai-data-analysis 的脚本接收 Token。

​

Step 3：验证某个 Token 是否有效

python3 scripts/verify_token.py "<tme-header-token-value>"

​

登录错误处理

​

第 1.5 步：单曲分析前置流程（songId 获取铁律）

🚨 本节是最高优先级规则，与登录规则、调用方式铁律同级。 ⚠️ 常见错误背景：用户说「帮我分析一下《XXX》这首歌的情况」时，Agent 很容易直接调用 chat_sync.py "分析《XXX》这首歌的情况"（不带 songId）。但服务端对「未传 songId」场景有兜底逻辑：当识别到用户在问单曲但调用方没有传 songId 时，会降级返回账号整体数据，导致用户看到的结论完全不是他问的那首歌。这是本 Skill 最严重的错误之一，必须通过本节流程彻底规避。

​

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

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

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

​

🚫 绝对禁止

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

​

✅ 标准流程（三步）

​

Step ①：检查会话上下文是否已有可用的 (songId, songName) 映射

• 如果同会话内前面已经做过一次整体数据分析，其 content 中通常含有歌曲排行/热门歌曲表格，里面就有 songId ↔ songName 对照 → 直接进入 Step ③
• 如果没有，先执行 Step ②

​

Step ②：内部发起一次整体数据分析以提取映射（仅供内部使用，不展示给用户）

python3 scripts/chat_sync.py "看看我的整体歌曲表现"

⚠️ 这一次调用不传 songId，目的是拿到包含歌曲列表的 content。此次内容不直接展示给用户，仅用于内部提取 songId 映射；Step ③ 成功取到 songId 后，再以用户原始提问发起正式的单曲分析。

​

Step ③：三档判定（A / B / C），决定下一步动作

📖 档 B 的”候选确认话术”与档 C 的”匹配失败兜底话术”完整模板详见 references/module-a-data-analysis.md → 「songId 获取流程与兜底话术」章节。必须使用该文档中的固定话术，严禁暴露 songId、“映射”、“候选池”、“相似度” 等技术字眼。

​

🚨 档 C（无法匹配）处理铁律（与本节其他规则同级优先级）

核心原则：找不到 = 直接告知不支持，一步终止，不再尝试任何其他途径。

1. 直接输出匹配失败兜底话术（严格按此文案，只替换 {USER_SONG_NAME} 为用户提到的歌名，不改动其他字符）：
   很抱歉，暂时不支持对《{USER_SONG_NAME}》这首歌进行数据分析，您可以尝试分析其他歌曲~
   
2. 输出后立即结束本轮回答，不再执行任何后续动作。
3. 静默输出铁律（最高优先级，严禁违反）：面向用户的最终回复 有且仅有上方那一行固定话术，严禁在其前、其后、其中附加任何其他文字。
   • ❌ 严禁把内部推理过程写给用户（诸如此类描述一律不得出现在回复里）：
     • 「两次整体分析的结果中都只出现了 Top N 波动歌曲」
     • 「《\{USER_SONG_NAME\}》不在其中 / 未匹配到该歌 / 没找到这首歌」
     • 「属于档 C / 无法匹配 / 需要输出固定兜底话术」
     • 「经过查询 / 根据分析结果 / 基于数据库检索」等任何说明来源的文字
   • ❌ 严禁暴露技术术语：songId、「映射」「候选池」「相似度」「档 A/B/C」「匹配失败」「系统未识别」「数据库未查到」「内部分析」「整体分析 content」
   • ❌ 严禁在兜底话术之后追加引导尾巴，诸如：
     • 「您也可以问问整体歌曲表现、听众画像等整体维度的数据哦~」
     • 「需要换一首歌试试吗？」「要不然我帮您看看整体数据？」
     • 任何形式的「额外建议」「引导问题」「撤一步的尝试」 都不要主动说
   • ❌ 严禁输出元信息 / 折叠面板描述：如「已完成思考」「思考过程」「展开答案」——全部保留在推理内部，不要出现在面向用户的文字里
   • ✅ 自检标准：把准备回复的全部文字拿出来，除了一行固定兜底话术之外如果还有其他任何字，都属于违规
4. 绝对禁止的「其他途径」（以下行为全部视为严重违规）：
   • ❌ 用 《》宽松匹配、去揉字/同音词、子串包含、编辑距离 等方式”拼一拼”强行匹配某个候选
   • ❌ 向用户追问「您是不是指 XX」「请提供歌曲全名/演唱者/发行时间」「歌名是不是打错了」等任何补充信息
   • ❌ 尝试「换个提问方式再调一次整体分析」「限定其他时间窗口再提取歌曲列表」等重试手段
   • ❌ 改用账号整体分析结论“代替”给用户（即不传 songId 裸调 chat_sync.py 后把整体数据当作该歌结论展示）
   • ❌ 导向其他 skill / 其他接口去查 songId（如搜索歌库、调用歌曲元数据接口等）
   • ❌ 进行任何「后续解读」「纪录下来后续再查」「已启动查询」等待续暗示
5. 允许且仅允许的后续交互：用户主动提出新请求（如改问另一首歌、改问账号整体数据）时，从「第 1.5 步」开头重新走一次完整流程，不是在当前回复继续扩展。

档 C 正反示例

很抱歉，暂时不支持对《一首根本不存在的歌》这首歌进行数据分析，您可以尝试分析其他歌曲~

​

Step ④：档 A 确认后的单曲分析调用

python3 scripts/chat_sync.py "<用户原始 userMessage>" <songId>

​

🧭 流程图

用户提问
   │
   ├── 是否属于"单曲分析意图"？（本节「触发条件」三条任一）
   │      │
   │      ├── 否 → 直接不传 songId 调用 chat_sync.py（整体分析）
   │      │
   │      └── 是 ↓
   │
   ├── 会话中是否已有整体分析 content（含歌曲映射）？
   │      │
   │      ├── 有 → 跳到「三档判定」
   │      │
   │      └── 无 → 先内部调一次整体分析提取映射（不展示给用户）
   │                         │
   │                         ↓
   │
   ├── 三档判定：
   │      ├── 档 A（唯一精准命中） → 取 songId，发起单曲分析 → 展示结果
   │      ├── 档 B（相似命中多条） → 输出候选确认话术 → 等用户选择 → 取 songId → 发起单曲分析
   │      └── 档 C（完全无法匹配） → 输出匹配失败兜底话术 → 终止，不调接口

​

📌 一句话记忆

“只要用户在问某一首歌，就必须先拿到确定的 songId 才准调 chat_sync.py；拿不到就按话术兜底，绝不裸调让服务端兜底。“

​

第二步：调用智能数据分析接口（固定流程）

​

🚨 调用方式铁律（最高优先级，严禁违反）

以下规则与登录规则同级，属于绝对红线。

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 是服务端返回给你的字段，绝不是请求入参，调用方传 sessionId 一定会失败）
     • accountId、userId、uid（由网关根据 tme-header-token 自动解析，调用方传必失败）
     • excludeFraudulentPlays、dataCaliber、新旧口径等任何其他字段（服务端根据账号灰度自动判定）
3. 错误调用反例（严禁模仿）：
   // ❌ 错误 1：把 userMessage 改成了 query，并自作主张传 sessionId
   {
     "query": "分析《文艺复兴》这首歌近期的播放量表现",
     "sessionId": "chat-bi.data.agent:chat-bi.data.agent:835586:20260422"
   }
   // 服务端返回：{"code":"100010","message":"数据异常，请稍候再试",...}
   
   // ❌ 错误 2：自己 curl 直连，改了字段名
   curl -X POST ".../chat-sync" -d '{"question":"...", "accountId":123}'
   

4. **存疑即停**：如果你不确定应该传哪些字段、用什么 URL，**永远**以 `scripts/chat_sync.py` 的源码为准，不要凭"对同类接口的印象"去猜
5. **单曲意图必须先取 songId，禁止裸调兜底**：当用户的提问**明确指向某一首歌曲**（例如「分析《XXX》这首歌」「这首歌表现怎么样」「XXX 的数据」等），**禁止**在没有明确 songId 的情况下直接调用 `chat_sync.py`。服务端对「未传 songId」场景**有兜底逻辑 —— 会返回账号整体数据而非单曲数据**，用户会看到**与自己提问完全不符的整体结论**。必须严格按照 **本文档「第 1.5 步：单曲分析前置流程」** 先解析 songId，再发起单曲分析。

### 接口定义


| 项           | 值                                                                       |
| ------------ | ------------------------------------------------------------------------ |
| URL          | `https://y.tencentmusic.com/openapi/v1/musician/data/agent/chat-sync` |
| Method       | `POST`                                                                   |
| Content-Type | `application/json`                                                       |
| 认证 Header  | `tme-header-token: <TOKEN>`                                              |
| 正常耗时     | 20 ~ 90 秒，偶发可达 3 分钟                                              |
| 服务端超时   | 240 秒                                                                   |
| 脚本超时     | 260 秒（`scripts/chat_sync.py` 已设置）                                  |

### 请求参数（完整且唯一，严禁自行新增/改名）


| 字段          | 类型   | 必填 | 说明                                                                                      |
| ------------- | ------ | ---- | ----------------------------------------------------------------------------------------- |
| `userMessage` | string | 是   | 用户的原始自然语言提问，**不要做任何加工/改写**。字段名就是 `userMessage`，不是 `query`/`message`/`question`/`prompt` |
| `songId`      | number | 否   | **仅**在通过「第 1.5 步：单曲分析前置流程」**档 A 精准匹配**拿到确定值时传入。整体数据/多首歌概览**不要传**；用户指向单曲但未确认 songId（档 B/C）也**绝不能不传 songId 就调用**（会命中服务端兜底返回整体数据，参见第 1.5 步） |

> ⚠️ **上表就是完整且唯一的请求参数列表**。除 `userMessage` 和 `songId` 外，**没有第三个合法字段**。
>
> 🔐 **accountId 不要传**：服务端会通过 `tme-header-token` 由网关解析出当前登录用户的 accountId，调用方**无需也不应**在 body 中传 `accountId`。
>
> 🚫 **sessionId 不要传**：`sessionId` 是**响应 `data.sessionId`** 里的字段，是服务端生成后返回给调用方的，**绝不能作为请求入参**，否则接口会报 `code=100010` "数据异常"。
>
> 🚫 **不要传** `excludeFraudulentPlays`、新旧口径等任何其他参数 —— 服务端根据账号灰度自动判定。

### 返回结构

外层是标准 `BaseResponse`，`code == 0` 表示成功：

```json
{
"code": 0,
"message": null,
"data": {
 "sessionId": "chat-bi.data.agent:chat-bi.data.agent:<accountId>:20260422",
 "messageId": "ag-msg-xxxx",
 "content": "...Markdown 分析结论...",
 "finishReason": "COMPLETE",
 "safetyRevoked": false
}
}

sessionId 中的 <accountId> 由网关根据 tme-header-token 解析后写入，调用方无需关心。

​

调用方式：必须使用 scripts/chat_sync.py

⚠️ 强制约束：调用接口唯一合法路径就是执行 scripts/chat_sync.py。严禁使用任何其他方式（HTTP 工具、curl、自写 requests/urllib 代码、浏览器 fetch 等）直连接口——脚本里已写死所有正确参数，任何绕过都会导致字段名、Header、超时设置错误。

# 最小入参
python3 scripts/chat_sync.py "<userMessage>"

# 带 songId
python3 scripts/chat_sync.py "<userMessage>" <songId>

python3 scripts/chat_sync.py "我最近7天的播放量怎么样？"
python3 scripts/chat_sync.py "分析这首歌最近的表现" 987654

• 自动从 ~/.tme-login/token.json 读取登录态（由 tme-openapi skill 维护）；读不到再回退到环境变量 TME_HEADER_TOKEN；都拿不到则报错并提示先运行 tme-openapi
• 以 Content-Type: application/json + tme-header-token: <TOKEN> 发起 POST
• 请求体固定且仅包含 userMessage（必填）和 songId（可选）两个字段
• 把接口返回的原始 JSON 格式化后打印到 stdout，便于你直接解析使用

详细的业务规范、finishReason 处理规则、展示规范与场景示例，见 references/module-a-data-analysis.md。

​

finishReason 速查

​

BaseResponse.code != 0 的业务错误

​

⚠️ 全局信息展示规范（必须遵守）

强制约束：向用户展示任何信息时，必须严格按照以下规范执行，不得自行简化或省略。

​

🔴 数据分析结果展示规则（最高优先级，严禁违反）

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

​

✅ 唯一正确做法：全文原样复制粘贴

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

​

❌ 严禁的改写行为（这是本 Skill 最常见的错误，违反将严重影响用户体验）

特别提示：下述行为看似是”帮用户整理得更清晰”，但本质上是在丢弃原始分析的专业性与完整性，属于严重违规。

1. ❌ 严禁”要点化精简”：不得把 content 中的完整段落、多个子章节改写成几个 bullet point 或几句话概括
   • 例如 content 中有「一、整体播放表现」「二、平台差异化表现」「三、互动数据表现」「四、趋势判断与建议」「五、数据补充说明」等多级章节，必须全部保留所有章节、所有子标题、所有段落文字
   • ❌ 错误示范：把 5 个大章节压缩成「整体播放量」「各平台表现」「互动数据」「建议」4 个要点
   • ✅ 正确做法：content 里有多少章节、多少段，就原样输出多少
2. ❌ 严禁”重排版”：不得把原文的段落文字改成表格，或把表格改写成段落；不得调整章节顺序；不得合并相邻章节
3. ❌ 严禁”同义改写”：不得用”同义的话”重新表述原文，哪怕你觉得自己写得”更简洁”或”更通顺”
4. ❌ 严禁裁剪任何细节：所有数字、百分比、同比环比、日期区间、占比、排名、平台名、歌单名、解读文字、建议条目，一个字都不能少
5. ❌ 严禁省略”数据补充说明”等看似次要的章节：即使你认为”元数据说明”对用户不重要，也必须原样保留
6. ❌ 严禁用”…”、“等等”、“其他略” 等省略性表达代替任何内容
7. ❌ 严禁转成纯文本（去掉 Markdown 格式）
8. ❌ 严禁改写数字、百分比、日期等具体数据
9. ❌ 严禁截断 URL（特别是带签名参数的 CDN 链接），URL 中的任何查询参数都可能是鉴权必需的
10. ❌ 严禁自行解读、补充、点评 content 之外的内容（你不是数据审稿人）

​

🔍 自检清单（输出前必须逐条核对）

• 我输出的内容字符数是否 ≥ 原始 content 的字符数？（允许只多不少，仅比 content 多出一句导语）
• 原始 content 里的每一个 ##、### 标题是否都在我的回复中原样出现？
• 原始 content 里的每一个表格是否都完整保留（行数、列数、单元格内容一致）？
• 原始 content 里的每一个数字、百分比是否都一字不差？
• 是否没有用自己的话重新组织、概括、改写任何段落？

​

🚫 禁止内容约束

1. 严禁在任何回复中提及、输出或引用「Suno」「suno」「SUNO」等任何大小写形式的 suno 关键词
2. 如果 API 返回的数据中包含 suno 相关信息，展示时必须自动过滤或隐去该关键词，不得原样透传给用户
3. 严禁擅自解读或修改 content 中的数据结论。你的角色是”数据分析展示+简单导读”，不是”数据审稿人”

​

📣 整体数据分析的追加引导语（强制）

触发条件：当本次请求属于 “整体数据分析”（即调用 chat_sync.py 时未传入 songId，例如用户问”我的数据怎么样”、“最近播放量如何”、“看看我的整体表现”、“听众画像”、“粉丝分布”等面向账号整体、而非单首歌曲的分析）时，必须在完整展示 content 之后，在回复的最末尾 追加一行引导语。

1. 仅在整体数据分析时追加；如果请求携带了 songId（即单首歌分析），不要追加这段引导
2. 位置：紧跟在 content 全文之后，用一个空行隔开，放在整条回复的最后一行
3. 内容模板（严格按此格式输出，不要改写）：
   💡 如果需要进一步分析单首歌曲的表现，可以告诉我歌曲名，例如：分析歌曲《{TOP_SONG_NAME}》的表现
   
4. {TOP_SONG_NAME} 的取值规则：
   • 从本次返回的 content 中识别 该用户当前播放量最大的一首歌曲名：
     • 优先在 content 的”热门歌曲 / 歌曲排行 / Top 歌曲 / 单曲播放量排行”等表格或列表中，取第一行 / 播放量最高的那首歌的歌曲名
     • 如果 content 中已经突出提到某一首代表作歌曲（如”代表作《XXX》”、“主打歌《XXX》”），优先使用该歌曲名
   • 歌曲名外层使用中文书名号 《》 包裹；如果原文本身已有书名号，则沿用原文，不要重复加
5. 兜底策略：如果 content 中确实无法识别出任何具体歌曲名（例如只有总量数据、听众画像、地域分布等，完全没有出现单曲信息），则退化为通用文案：
   💡 如果需要进一步分析单首歌曲的表现，可以告诉我歌曲名，例如：分析歌曲《歌曲名》的表现
   
6. 严禁：
   • ❌ 单首歌分析（songId 已传入）时追加这段引导（会造成困扰）
   • ❌ 放在 content 中间或开头（必须在最末尾）
   • ❌ 自行改写文案措辞（必须严格使用上方模板）
   • ❌ 编造一首 content 里并未出现的歌曲名

​

⏳ 等待体验规范

数据分析正常耗时 20~90 秒，偶发可达 3 分钟。

• ✅ 「📊 正在分析中，请稍候…」
• ✅ 「⏳ 数据分析通常需要 20~90 秒，马上为您呈现结果」

• ❌ 「看起来服务有点慢」「似乎遇到延迟」「服务可能繁忙」等暗示服务异常的话术