TME OpenAPI（腾讯音乐开放平台算子客户端）

✨ 自包含：本 Skill 已内嵌完整登录能力，不依赖任何外部 Skill。首次使用会自动弹出浏览器扫码登录，Token 有效期约 30 天，之后日常调用秒级无感。

⚠️ 定位说明：本 Skill 是纯通用能力层，不包含任何业务语义。业务 Skill（如 ai-promotion-query）应当引用本 Skill完成 API 发现与调用，自己只负责业务编排、参数组装、结果解读、对外表达规则。

是什么

腾讯音乐开放平台后端有一套「算子」体系：

• 每个算子 = 一个可被 Agent 调用的后端 API
• 算子的配置（名称、入参 schema、出参 schema 等）存储在数据库中，可随时新增和修改
• 上层 Agent / Skill 不应硬编码任何算子的 operatorCode 或参数结构，而是通过本 Skill 提供的 4 个工具动态发现和调用
• 当前算子平台仅支持同步调用——invoke_api 直接返回最终结果，无需轮询

本 Skill 封装了算子平台对外的 4 个标准入口：

POST /musician/agent/operator/listApis       → list_apis
POST /musician/agent/operator/searchApis     → search_apis
POST /musician/agent/operator/getApiDetail   → get_api_detail
POST /musician/agent/operator/invokeApi      → invoke_api

所有接口：

• 域名：https://y.tencentmusic.com/openapi（正式环境，已硬编码）
• 方法：POST + JSON Body
• 鉴权：HTTP Header tme-header-token: <token>（Skill 内部自动获取，见下方「登录态管理」）
• 响应：统一 { success, data, error, meta } 结构

登录态管理（内嵌能力）

Token 获取的自动回退链

所有调用脚本在发起请求前，会通过内部模块 scripts/_token.py → scripts/check_login.py 自动获取 Token，四级回退：

1. 本地缓存 ~/.tme-login/token.json              ← 秒级，99% 日常场景
       ↓（不存在或为空）
2. 无头 Playwright + ~/.tme-login/storage_state.json 刷新
       ↓（storage_state 失效或缺失）
3. 自动调起 login.py 做有头扫码登录（弹出 Chromium）
       ↓（用户未完成登录）
4. 手动粘贴 Token 兜底

每一步成功都会覆盖写入 token.json，供后续调用秒级复用。Token 有效期约 30 天。

双文件缓存

Playwright 依赖（🤖 AI 必读：缺失时自动安装，不要把错误丢给用户）

本 Skill 依赖 Playwright 驱动 Chromium 完成登录与 Token 刷新。

脚本层已自动处理

scripts/login.py 与 scripts/get_token_from_browser.py 在运行时会自动检测 Playwright 是否已安装，若未安装会自动在当前 Python 环境下执行安装（pip install playwright + playwright install chromium），无需人工干预。正常情况下，AI 和用户都不需要手动装依赖，直接调用脚本即可。

⚠️ 强制行为规范（给调用本 Skill 的 AI）

当你（AI）运行本 Skill 的任何脚本，看到以下任一信号时：

• 脚本 stderr 出现 ❌ 未检测到 Playwright / PLAYWRIGHT_MISSING / ModuleNotFoundError: No module named 'playwright'
• 提示「请安装依赖：pip install playwright && playwright install chromium」
• check_login.py 因 PLAYWRIGHT_MISSING 走到手动粘贴兜底

你必须立刻在终端主动执行下面的安装命令，然后重跑原脚本，而不是把错误提示原样抛给用户、让用户自己去装：

python3 -m pip install --upgrade playwright
python3 -m playwright install chromium

说明：

1. 使用 python3 -m pip / python3 -m playwright，避免 pip / playwright 不在 PATH 里导致的误判
2. 若当前处于虚拟环境或 conda 环境，继续在该环境中执行即可，不要切换到系统 Python
3. playwright install chromium 会下载约 150MB 浏览器二进制，首次耗时 1-2 分钟是正常的
4. 安装完成后必须重新执行原本失败的脚本（例如 python3 scripts/login.py 或上层的 check_login.py），确认流程能走通再向用户汇报
5. 禁止向用户输出"请你先执行 pip install ..."这类把安装动作甩回给用户的话

Chromium 约 150MB，仅本 Skill 使用，不影响系统浏览器。

登录相关脚本（普通调用方不需要直接用）

强制重新登录（Token 过期或失效）

rm -f ~/.tme-login/storage_state.json ~/.tme-login/token.json
python scripts/login.py

可用 Tools（算子平台调用）

脚本一览

这 4 个脚本仅用 Python 3 标准库（urllib / json），零额外依赖。Token 由内部模块 _token.py 自动管理，调用方无需传任何参数或设置任何环境变量。

标准调用流程

1. 发现算子
   search_apis({ keyword: "..." })  或  list_apis()
        ↓
2. 判断：search/list 返回的摘要信息够不够组装参数？
   ├── 够了 → 直接到第 3 步
   └── 不够 → get_api_detail({ name: "<operatorCode>" })
        ↓
3. 调用算子（同步）
   invoke_api({ name: "<operatorCode>", arguments: { ... } })
        ↓
4. 直接读取 output，完成

当前算子平台仅支持同步调用，invoke_api 一次请求即可拿到最终结果。如未来新增异步算子，会另行在本 Skill 中补回轮询能力，业务 Skill 无需关心。

关于 detailedDescription 字段

get_api_detail 返回的详情中包含一个 detailedDescription 字段（Markdown 格式的长文本），是算子作者为该能力撰写的详细使用说明，通常包含：

• 该算子具体是什么、适用场景
• 参数的详细含义、约束和取值范围
• 调用注意事项和最佳实践
• 常见错误和处理建议

⚠️ 强烈建议：在首次调用一个不熟悉的算子之前，先通过 get_api_detail 获取详情，仔细阅读 detailedDescription 字段的内容，再组装参数发起调用。这能大幅减少因参数错误导致的调用失败。

判断是否需要查 detail 的经验法则

可以跳过 detail 直接 invoke — 当以下三个条件同时满足：

1. search/list 返回的 inputSchema 信息齐全，所有 required 参数你都能确定值
2. 参数结构是扁平的（没有嵌套的 object/array），或者嵌套结构你已完全理解
3. 对参数含义没有任何歧义

必须先查 detail — 当以下任一条件成立：

1. inputSchema 有嵌套 object 或 array，你不确定内部结构
2. 对某个参数的含义、格式、取值范围有疑问
3. 想参考 exampleInput / exampleOutput 来确认参数怎么组装
4. 想查看 detailedDescription 获取该算子的详细使用指南

参数构造规则

• arguments 必须是结构化 JSON 对象（Map<String, Object>），严格匹配 inputSchema
• 所有 required 字段必须提供，少一个都会返回 INVALID_ARGUMENT
• 参数类型必须匹配 schema 声明的 type（string / number / boolean / object / array）
• 可选参数不确定就不传，后端会用默认值
• 登录态下不要传 accountId / userId 等当前用户身份参数，后端会从 Token 中自动识别
• 禁止把自然语言拼接成字符串塞到 arguments 里

错误处理

所有响应外层结构为 { success, data, error, meta }。当 success=false 时，读 error 字段：

所有算子当前都是同步返回，invoke_api 的响应即为最终结果，无 async=true 的情况。

关键策略：遇到 INVALID_ARGUMENT 时，别用同样的参数重试——回退到 get_api_detail 查完整 schema 和 example，重新组装参数。

典型调用示例

示例 1：发现 + 调用算子（自动处理登录态）

# 首次会弹出 Chromium 让你扫码；之后 30 天内秒级复用
python scripts/search_apis.py 宣推概览
python scripts/invoke_api.py 宣推概览 '{"accountId":282250}'

示例 2：对参数有疑问时先查 detail

python scripts/get_api_detail.py <operatorCode>
# 查看 detailedDescription / inputSchema / exampleInput / exampleOutput
# 然后再组装 arguments 调用 invoke_api

示例 3：主动刷新登录态（Token 过期）

rm -f ~/.tme-login/token.json ~/.tme-login/storage_state.json
python scripts/login.py     # 有头扫码，重新登录
# 之后直接跑任意算子调用即可

给上层业务 Skill 的使用契约

业务 Skill（如 ai-promotion-query）引用本 Skill 时，只需要做 2 件事：

1. 通过本 Skill 的 4 个算子脚本完成调用——不要自己写 HTTP 请求，Token 由本 Skill 自动处理
2. 自己负责业务编排——包括：
   • 业务场景 → 关键词的映射（如"宣推概览"该搜什么词）
   • operatorCode 的缓存策略（是否每次都 search_apis）
   • 返回结果的业务解读与对外表达

业务 Skill 无需做任何登录态相关的事情，也无需引用其他 Skill 来获取 Token——本 Skill 已自包含。

本 Skill 不关心、不干涉业务语义，只保证"给算子 code 和参数，就能拿到调用结果"这一通用契约。

环境配置