TME OpenAPI（腾讯音乐开放平台算子客户端）
✨ 自包含：本 Skill 已内嵌完整登录能力，不依赖任何外部 Skill。首次使用会自动弹出浏览器扫码登录，Token 有效期约 30 天，之后日常调用秒级无感。
⚠️ 定位说明：本 Skill 是纯通用能力层，不包含任何业务语义。业务 Skill（如 ai-promotion-query）应当引用本 Skill完成 API 发现与调用，自己只负责业务编排、参数组装、结果解读、对外表达规则。
是什么
腾讯音乐开放平台后端有一套「算子」体系：- 每个算子 = 一个可被 Agent 调用的后端 API
- 算子的配置（名称、入参 schema、出参 schema 等）存储在数据库中，可随时新增和修改
- 上层 Agent / Skill 不应硬编码任何算子的 operatorCode 或参数结构，而是通过本 Skill 提供的 4 个工具动态发现和调用
- 当前算子平台仅支持同步调用——
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，四级回退：
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/python3 -m playwright，避免pip/playwright不在 PATH 里导致的误判 - 若当前处于虚拟环境或 conda 环境，继续在该环境中执行即可，不要切换到系统 Python
playwright install chromium会下载约 150MB 浏览器二进制，首次耗时 1-2 分钟是正常的- 安装完成后必须重新执行原本失败的脚本（例如
python3 scripts/login.py或上层的check_login.py），确认流程能走通再向用户汇报 - 禁止向用户输出”请你先执行 pip install …”这类把安装动作甩回给用户的话
Chromium 约 150MB，仅本 Skill 使用，不影响系统浏览器。
登录相关脚本（普通调用方不需要直接用）
强制重新登录（Token 过期或失效）
可用 Tools（算子平台调用）
脚本一览
这 4 个脚本仅用 Python 3 标准库（urllib/json），零额外依赖。Token 由内部模块_token.py自动管理，调用方无需传任何参数或设置任何环境变量。
标准调用流程
当前算子平台仅支持同步调用，invoke_api 一次请求即可拿到最终结果。如未来新增异步算子，会另行在本 Skill 中补回轮询能力，业务 Skill 无需关心。
关于 detailedDescription 字段
get_api_detail 返回的详情中包含一个 detailedDescription 字段（Markdown 格式的长文本），是算子作者为该能力撰写的详细使用说明，通常包含：
- 该算子具体是什么、适用场景
- 参数的详细含义、约束和取值范围
- 调用注意事项和最佳实践
- 常见错误和处理建议
⚠️ 强烈建议：在首次调用一个不熟悉的算子之前，先通过get_api_detail获取详情，仔细阅读detailedDescription字段的内容，再组装参数发起调用。这能大幅减少因参数错误导致的调用失败。
判断是否需要查 detail 的经验法则
可以跳过 detail 直接 invoke — 当以下三个条件同时满足：search/list返回的inputSchema信息齐全，所有required参数你都能确定值- 参数结构是扁平的（没有嵌套的 object/array），或者嵌套结构你已完全理解
- 对参数含义没有任何歧义
inputSchema有嵌套 object 或 array，你不确定内部结构- 对某个参数的含义、格式、取值范围有疑问
- 想参考
exampleInput/exampleOutput来确认参数怎么组装 - 想查看
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：发现 + 调用算子（自动处理登录态）
示例 2：对参数有疑问时先查 detail
示例 3：主动刷新登录态（Token 过期）
给上层业务 Skill 的使用契约
业务 Skill（如ai-promotion-query）引用本 Skill 时，只需要做 2 件事：
- 通过本 Skill 的 4 个算子脚本完成调用——不要自己写 HTTP 请求，Token 由本 Skill 自动处理
- 自己负责业务编排——包括：
- 业务场景 → 关键词的映射（如”宣推概览”该搜什么词）
operatorCode的缓存策略（是否每次都search_apis）- 返回结果的业务解读与对外表达
业务 Skill 无需做任何登录态相关的事情，也无需引用其他 Skill 来获取 Token——本 Skill 已自包含。本 Skill 不关心、不干涉业务语义，只保证”给算子 code 和参数，就能拿到调用结果”这一通用契约。