Tme Openapi — Tme Open API

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

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

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

是什么

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

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

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

POST /musician/代理/operator/列出APIs → 列出_APIs POST /musician/代理/operator/搜索APIs → 搜索_APIs POST /musician/代理/operator/获取APIDetAIl → 获取_API_detAIl POST /musician/代理/operator/invokeAPI → invoke_API

所有接口：

域名：https://y.tencentmusic.com/openAPI（正式环境，已硬编码） 方法：POST + JSON Body 鉴权：HTTP Header tme-header-令牌: <令牌>（技能 内部自动获取，见下方「登录态管理」） 响应：统一 { 成功, data, error, meta } 结构 登录态管理（内嵌能力） 令牌 获取的自动回退链

所有调用脚本在发起请求前，会通过内部模块 scripts/_令牌.py → scripts/检查_记录in.py 自动获取 令牌，四级回退：

• 本地缓存 ~/.tme-记录in/令牌.json ← 秒级，99% 日常场景

↓（不存在或为空）

• 无头 Playwright + ~/.tme-记录in/storage_状态.json 刷新

↓（storage_状态 失效或缺失）

• 自动调起 记录in.py 做有头扫码登录（弹出 Chromium）

↓（用户未完成登录）

• 手动粘贴 令牌 兜底

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

双文件缓存 文件 作用 ~/.tme-记录in/storage_状态.json Playwright 完整存档（cookies + localStorage），由 记录in.py 生成 ~/.tme-记录in/令牌.json tmeHeader令牌 快照，供 技能 内部和外部脚本直接读取 Playwright 依赖（🤖 AI 必读：缺失时自动安装，不要把错误丢给用户）

本 技能 依赖 Playwright 驱动 Chromium 完成登录与 令牌 刷新。

脚本层已自动处理

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

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

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

脚本 stderr 出现 ❌ 未检测到 Playwright / PLAYWRIGHT_MISSING / 模块NotFoundError: No 模块 named 'playwright' 提示「请安装依赖：pip 安装 playwright && playwright 安装 chromium」 检查_记录in.py 因 PLAYWRIGHT_MISSING 走到手动粘贴兜底

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

python3 -m pip 安装 --升级 playwright python3 -m playwright 安装 chromium

说明：

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

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

登录相关脚本（普通调用方不需要直接用） 功能 脚本 典型用法 首次登录 / 扫码登录（有头） scripts/记录in.py python scripts/记录in.py 获取登录态（缓存→无头→扫码 自动回退） scripts/检查_记录in.py 令牌=$(python scripts/检查_记录in.py) 从 storage_状态 无头读取 令牌（内部） scripts/获取_令牌_from_browser.py 由 检查_记录in.py 调用 验证指定 令牌 是否有效 scripts/验证_令牌.py python scripts/验证_令牌.py <令牌> 强制重新登录（令牌 过期或失效） rm -f ~/.tme-记录in/storage_状态.json ~/.tme-记录in/令牌.json python scripts/记录in.py

可用 工具s（算子平台调用） 工具 作用 什么时候用 列出_APIs 列出所有可用算子摘要 想看全貌，或不确定该搜什么关键词 搜索_APIs 按关键词模糊搜索算子 知道大概要什么能力（如"宣推概览"、"发行"） 获取_API_detAIl 获取指定算子的完整详情 需要精确了解参数结构再调用 invoke_API 调用指定算子 参数已准备好，可以执行了 脚本一览 工具 脚本 命令行用法 列出_APIs scripts/列出_APIs.py python scripts/列出_APIs.py 搜索_APIs scripts/搜索_APIs.py python scripts/搜索_APIs.py 获取_API_detAIl scripts/获取_API_detAIl.py python scripts/获取_API_detAIl.py invoke_API scripts/invoke_API.py python scripts/invoke_API.py ''

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

标准调用流程

• 发现算子

搜索_APIs({ keyword: "..." }) 或 列出_APIs() ↓

• 判断：搜索/列出 返回的摘要信息够不够组装参数？

├── 够了 → 直接到第 3 步 └── 不够 → 获取_API_detAIl({ name: "" }) ↓

• 调用算子（同步）

invoke_API({ name: "", arguments: { ... } }) ↓

• 直接读取 输出，完成

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

关于 detAIledDescription 字段

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

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

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

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

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

搜索/列出 返回的 输入模式 信息齐全，所有 required 参数你都能确定值 参数结构是扁平的（没有嵌套的 object/array），或者嵌套结构你已完全理解 对参数含义没有任何歧义

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

输入模式 有嵌套 object 或 array，你不确定内部结构 对某个参数的含义、格式、取值范围有疑问 想参考 example输入 / example输出 来确认参数怎么组装 想查看 detAIledDescription 获取该算子的详细使用指南 参数构造规则 arguments 必须是结构化 JSON 对象（Map），严格匹配 输入模式 所有 required 字段必须提供，少一个都会返回 INVALID_ARGUMENT 参数类型必须匹配 模式 声明的 type（string / number / boolean / object / array） 可选参数不确定就不传，后端会用默认值 登录态下不要传 accountId / userId 等当前用户身份参数，后端会从 令牌 中自动识别 禁止把自然语言拼接成字符串塞到 arguments 里 错误处理

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

error.code 含义 能重试吗 怎么办 INVALID_ARGUMENT 参数错误