{"skill":{"slug":"tme-openapi","displayName":"Tme Openapi","summary":"腾讯音乐开放平台（TME OpenAPI）算子平台通用客户端。提供对 `/musician/agent/operator/*` 一系列「算子」API 的发现、查询与调用能力，是所有需要调用 TME OpenAPI 算子的业务 Skill 的**基础依赖**。本 Skill 仅封装**通用的 API 调用与算子发现...","description":"---\r\nname: tme-openapi\r\ndescription: 腾讯音乐开放平台（TME OpenAPI）算子平台通用客户端。提供对 `/musician/agent/operator/*` 一系列「算子」API 的发现、查询与调用能力，是所有需要调用 TME OpenAPI 算子的业务 Skill 的**基础依赖**。本 Skill 仅封装**通用的 API 调用与算子发现流程**，不关心任何具体业务语义（例如宣推、歌曲、发行等）。对调用方暴露 4 个通用工具：`list_apis` / `search_apis` / `get_api_detail` / `invoke_api`。**触发时机**：- 上层业务 Skill 需要调用 TME OpenAPI 算子时，作为**被引用的基础能力**加载；- 用户直接提问\"列一下可用算子\"、\"调一下 xxx 算子\"、\"搜一下宣推相关的 API\"等开发调试场景； - 用户提问\"登录腾讯音乐人\"、\"获取登录态\"等 —— 本 Skill 已自包含登录能力。**自包含**：登录态 Token 获取能力已**完整内嵌**到本 Skill，无需依赖任何外部 Skill，调用方无需设置任何环境变量。\r\n---\r\n\r\n# TME OpenAPI（腾讯音乐开放平台算子客户端）\r\n\r\n> **✨ 自包含**：本 Skill 已内嵌完整登录能力，不依赖任何外部 Skill。首次使用会自动弹出浏览器扫码登录，Token 有效期约 30 天，之后日常调用秒级无感。\r\n>\r\n> **⚠️ 定位说明**：本 Skill 是**纯通用能力层**，不包含任何业务语义。业务 Skill（如 `ai-promotion-query`）应当**引用本 Skill**完成 API 发现与调用，自己只负责业务编排、参数组装、结果解读、对外表达规则。\r\n\r\n## 是什么\r\n\r\n腾讯音乐开放平台后端有一套「算子」体系：\r\n\r\n- 每个算子 = 一个可被 Agent 调用的后端 API\r\n- 算子的配置（名称、入参 schema、出参 schema 等）存储在数据库中，**可随时新增和修改**\r\n- 上层 Agent / Skill **不应硬编码任何算子的 operatorCode 或参数结构**，而是通过本 Skill 提供的 4 个工具**动态发现和调用**\r\n- 当前算子平台仅支持**同步调用**——`invoke_api` 直接返回最终结果，无需轮询\r\n\r\n本 Skill 封装了算子平台对外的 4 个标准入口：\r\n\r\n```\r\nPOST /musician/agent/operator/listApis       → list_apis\r\nPOST /musician/agent/operator/searchApis     → search_apis\r\nPOST /musician/agent/operator/getApiDetail   → get_api_detail\r\nPOST /musician/agent/operator/invokeApi      → invoke_api\r\n```\r\n\r\n所有接口：\r\n- 域名：`https://y.tencentmusic.com/openapi`（正式环境，已硬编码）\r\n- 方法：POST + JSON Body\r\n- 鉴权：HTTP Header `tme-header-token: <token>`（Skill 内部自动获取，见下方「登录态管理」）\r\n- 响应：统一 `{ success, data, error, meta }` 结构\r\n\r\n---\r\n\r\n## 登录态管理（内嵌能力）\r\n\r\n### Token 获取的自动回退链\r\n\r\n所有调用脚本在发起请求前，会通过内部模块 `scripts/_token.py` → `scripts/check_login.py` **自动获取 Token**，四级回退：\r\n\r\n```\r\n1. 本地缓存 ~/.tme-login/token.json              ← 秒级，99% 日常场景\r\n       ↓（不存在或为空）\r\n2. 无头 Playwright + ~/.tme-login/storage_state.json 刷新\r\n       ↓（storage_state 失效或缺失）\r\n3. 自动调起 login.py 做有头扫码登录（弹出 Chromium）\r\n       ↓（用户未完成登录）\r\n4. 手动粘贴 Token 兜底\r\n```\r\n\r\n每一步成功都会覆盖写入 `token.json`，供后续调用秒级复用。**Token 有效期约 30 天**。\r\n\r\n### 双文件缓存\r\n\r\n| 文件                                    | 作用                                                              |\r\n| --------------------------------------- | ----------------------------------------------------------------- |\r\n| `~/.tme-login/storage_state.json`       | Playwright 完整存档（cookies + localStorage），由 `login.py` 生成 |\r\n| `~/.tme-login/token.json`               | `tmeHeaderToken` 快照，供 Skill 内部和外部脚本直接读取            |\r\n\r\n### Playwright 依赖（🤖 AI 必读：缺失时自动安装，不要把错误丢给用户）\r\n\r\n本 Skill 依赖 [Playwright](https://playwright.dev/python/) 驱动 Chromium 完成登录与 Token 刷新。\r\n\r\n#### 脚本层已自动处理\r\n\r\n`scripts/login.py` 与 `scripts/get_token_from_browser.py` 在运行时会**自动检测 Playwright 是否已安装**，若未安装会**自动在当前 Python 环境下执行安装**（`pip install playwright` + `playwright install chromium`），无需人工干预。正常情况下，AI 和用户都**不需要手动装依赖**，直接调用脚本即可。\r\n\r\n#### ⚠️ 强制行为规范（给调用本 Skill 的 AI）\r\n\r\n当你（AI）运行本 Skill 的任何脚本，**看到以下任一信号时**：\r\n\r\n- 脚本 stderr 出现 `❌ 未检测到 Playwright` / `PLAYWRIGHT_MISSING` / `ModuleNotFoundError: No module named 'playwright'`\r\n- 提示「请安装依赖：pip install playwright && playwright install chromium」\r\n- `check_login.py` 因 `PLAYWRIGHT_MISSING` 走到手动粘贴兜底\r\n\r\n**你必须立刻在终端主动执行下面的安装命令，然后重跑原脚本**，而不是把错误提示原样抛给用户、让用户自己去装：\r\n\r\n```bash\r\npython3 -m pip install --upgrade playwright\r\npython3 -m playwright install chromium\r\n```\r\n\r\n说明：\r\n1. 使用 `python3 -m pip` / `python3 -m playwright`，避免 `pip` / `playwright` 不在 PATH 里导致的误判\r\n2. 若当前处于虚拟环境或 conda 环境，继续在该环境中执行即可，**不要**切换到系统 Python\r\n3. `playwright install chromium` 会下载约 150MB 浏览器二进制，首次耗时 1-2 分钟是正常的\r\n4. 安装完成后**必须重新执行**原本失败的脚本（例如 `python3 scripts/login.py` 或上层的 `check_login.py`），确认流程能走通再向用户汇报\r\n5. **禁止**向用户输出\"请你先执行 pip install ...\"这类把安装动作甩回给用户的话\r\n\r\n> Chromium 约 150MB，仅本 Skill 使用，不影响系统浏览器。\r\n\r\n### 登录相关脚本（普通调用方不需要直接用）\r\n\r\n| 功能                                      | 脚本                                   | 典型用法                                 |\r\n| ----------------------------------------- | -------------------------------------- | ---------------------------------------- |\r\n| 首次登录 / 扫码登录（有头）               | `scripts/login.py`                     | `python scripts/login.py`                |\r\n| 获取登录态（缓存→无头→扫码 自动回退）     | `scripts/check_login.py`               | `TOKEN=$(python scripts/check_login.py)` |\r\n| 从 storage_state 无头读取 Token（内部）   | `scripts/get_token_from_browser.py`    | 由 `check_login.py` 调用                 |\r\n| 验证指定 Token 是否有效                   | `scripts/verify_token.py`              | `python scripts/verify_token.py <token>` |\r\n\r\n### 强制重新登录（Token 过期或失效）\r\n\r\n```bash\r\nrm -f ~/.tme-login/storage_state.json ~/.tme-login/token.json\r\npython scripts/login.py\r\n```\r\n\r\n---\r\n\r\n## 可用 Tools（算子平台调用）\r\n\r\n| Tool             | 作用                   | 什么时候用                                 |\r\n| ---------------- | ---------------------- | ------------------------------------------ |\r\n| `list_apis`      | 列出所有可用算子摘要   | 想看全貌，或不确定该搜什么关键词           |\r\n| `search_apis`    | 按关键词模糊搜索算子   | 知道大概要什么能力（如\"宣推概览\"、\"发行\"） |\r\n| `get_api_detail` | 获取指定算子的完整详情 | 需要精确了解参数结构再调用                 |\r\n| `invoke_api`     | 调用指定算子           | 参数已准备好，可以执行了                   |\r\n\r\n### 脚本一览\r\n\r\n| Tool             | 脚本                        | 命令行用法                                                       |\r\n| ---------------- | --------------------------- | ---------------------------------------------------------------- |\r\n| `list_apis`      | `scripts/list_apis.py`      | `python scripts/list_apis.py`                                    |\r\n| `search_apis`    | `scripts/search_apis.py`    | `python scripts/search_apis.py <keyword>`                        |\r\n| `get_api_detail` | `scripts/get_api_detail.py` | `python scripts/get_api_detail.py <operatorCode>`                |\r\n| `invoke_api`     | `scripts/invoke_api.py`     | `python scripts/invoke_api.py <operatorCode> '<arguments_json>'` |\r\n\r\n> 这 4 个脚本仅用 Python 3 标准库（`urllib` / `json`），零额外依赖。Token 由内部模块 `_token.py` 自动管理，调用方**无需**传任何参数或设置任何环境变量。\r\n\r\n---\r\n\r\n## 标准调用流程\r\n\r\n```\r\n1. 发现算子\r\n   search_apis({ keyword: \"...\" })  或  list_apis()\r\n        ↓\r\n2. 判断：search/list 返回的摘要信息够不够组装参数？\r\n   ├── 够了 → 直接到第 3 步\r\n   └── 不够 → get_api_detail({ name: \"<operatorCode>\" })\r\n        ↓\r\n3. 调用算子（同步）\r\n   invoke_api({ name: \"<operatorCode>\", arguments: { ... } })\r\n        ↓\r\n4. 直接读取 output，完成\r\n```\r\n\r\n> 当前算子平台**仅支持同步调用**，`invoke_api` 一次请求即可拿到最终结果。如未来新增异步算子，会另行在本 Skill 中补回轮询能力，业务 Skill 无需关心。\r\n\r\n### 关于 `detailedDescription` 字段\r\n\r\n`get_api_detail` 返回的详情中包含一个 `detailedDescription` 字段（Markdown 格式的长文本），是算子作者为该能力撰写的**详细使用说明**，通常包含：\r\n\r\n- 该算子具体是什么、适用场景\r\n- 参数的详细含义、约束和取值范围\r\n- 调用注意事项和最佳实践\r\n- 常见错误和处理建议\r\n\r\n> **⚠️ 强烈建议**：在首次调用一个不熟悉的算子之前，先通过 `get_api_detail` 获取详情，**仔细阅读 `detailedDescription` 字段的内容**，再组装参数发起调用。这能大幅减少因参数错误导致的调用失败。\r\n\r\n### 判断是否需要查 detail 的经验法则\r\n\r\n**可以跳过 detail 直接 invoke** — 当以下三个条件同时满足：\r\n\r\n1. `search/list` 返回的 `inputSchema` 信息齐全，所有 `required` 参数你都能确定值\r\n2. 参数结构是扁平的（没有嵌套的 object/array），或者嵌套结构你已完全理解\r\n3. 对参数含义没有任何歧义\r\n\r\n**必须先查 detail** — 当以下任一条件成立：\r\n\r\n1. `inputSchema` 有嵌套 object 或 array，你不确定内部结构\r\n2. 对某个参数的含义、格式、取值范围有疑问\r\n3. 想参考 `exampleInput` / `exampleOutput` 来确认参数怎么组装\r\n4. 想查看 `detailedDescription` 获取该算子的详细使用指南\r\n\r\n---\r\n\r\n## 参数构造规则\r\n\r\n- `arguments` 必须是结构化 JSON 对象（`Map<String, Object>`），严格匹配 `inputSchema`\r\n- 所有 `required` 字段必须提供，少一个都会返回 `INVALID_ARGUMENT`\r\n- 参数类型必须匹配 schema 声明的 type（`string` / `number` / `boolean` / `object` / `array`）\r\n- 可选参数不确定就不传，后端会用默认值\r\n- 登录态下**不要**传 `accountId` / `userId` 等当前用户身份参数，后端会从 Token 中自动识别\r\n- **禁止**把自然语言拼接成字符串塞到 `arguments` 里\r\n\r\n---\r\n\r\n## 错误处理\r\n\r\n所有响应外层结构为 `{ success, data, error, meta }`。当 `success=false` 时，读 `error` 字段：\r\n\r\n| error.code         | 含义         | 能重试吗 | 怎么办                                                               |\r\n| ------------------ | ------------ | -------- | -------------------------------------------------------------------- |\r\n| `INVALID_ARGUMENT` | 参数错误     | 否       | 调 `get_api_detail` 重新确认 schema，修正参数再试                    |\r\n| `NOT_FOUND`        | 算子不存在   | 否       | 调 `search_apis` 重新确认 `operatorCode`                             |\r\n| `UNAUTHORIZED`     | 未认证       | 否       | 删除 `~/.tme-login/token.json` 后重跑脚本，本 Skill 会自动触发重新登录 |\r\n| `RATE_LIMITED`     | 限流         | 是       | 等一会儿再试                                                         |\r\n| `TIMEOUT`          | 超时         | 是       | 重试，可设更大 `timeoutMs`                                           |\r\n| `UPSTREAM_ERROR`   | 上游服务异常 | 是       | 重试 1-2 次，仍失败交给上层业务 Skill 处理                           |\r\n\r\n> 所有算子当前都是**同步返回**，`invoke_api` 的响应即为最终结果，无 `async=true` 的情况。\r\n\r\n**关键策略**：遇到 `INVALID_ARGUMENT` 时，别用同样的参数重试——回退到 `get_api_detail` 查完整 schema 和 example，重新组装参数。\r\n\r\n---\r\n\r\n## 典型调用示例\r\n\r\n### 示例 1：发现 + 调用算子（自动处理登录态）\r\n\r\n```bash\r\n# 首次会弹出 Chromium 让你扫码；之后 30 天内秒级复用\r\npython scripts/search_apis.py 宣推概览\r\npython scripts/invoke_api.py 宣推概览 '{\"accountId\":282250}'\r\n```\r\n\r\n### 示例 2：对参数有疑问时先查 detail\r\n\r\n```bash\r\npython scripts/get_api_detail.py <operatorCode>\r\n# 查看 detailedDescription / inputSchema / exampleInput / exampleOutput\r\n# 然后再组装 arguments 调用 invoke_api\r\n```\r\n\r\n### 示例 3：主动刷新登录态（Token 过期）\r\n\r\n```bash\r\nrm -f ~/.tme-login/token.json ~/.tme-login/storage_state.json\r\npython scripts/login.py     # 有头扫码，重新登录\r\n# 之后直接跑任意算子调用即可\r\n```\r\n\r\n---\r\n\r\n## 给上层业务 Skill 的使用契约\r\n\r\n业务 Skill（如 `ai-promotion-query`）引用本 Skill 时，**只需要做 2 件事**：\r\n\r\n1. **通过本 Skill 的 4 个算子脚本完成调用**——不要自己写 HTTP 请求，Token 由本 Skill 自动处理\r\n2. **自己负责业务编排**——包括：\r\n   - 业务场景 → 关键词的映射（如\"宣推概览\"该搜什么词）\r\n   - `operatorCode` 的缓存策略（是否每次都 `search_apis`）\r\n   - 返回结果的业务解读与对外表达\r\n\r\n> 业务 Skill **无需**做任何登录态相关的事情，也**无需**引用其他 Skill 来获取 Token——本 Skill 已自包含。\r\n\r\n本 Skill **不关心、不干涉**业务语义，只保证\"给算子 code 和参数，就能拿到调用结果\"这一通用契约。\r\n\r\n---\r\n\r\n## 环境配置\r\n\r\n| 项                  | 值                                                               | 说明                                                                 |\r\n| ------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------- |\r\n| 域名                | `https://y.tencentmusic.com/openapi`                             | 正式环境，已硬编码在所有调用脚本中                                   |\r\n| 鉴权 Header         | `tme-header-token: <token>`                                      | Skill 内部自动获取，Token 有效期约 30 天                             |\r\n| Content-Type        | `application/json`                                               | 所有请求体均为 JSON                                                  |\r\n| 调用脚本依赖        | Python 3 标准库（`urllib` / `json`）                             | 零额外依赖                                                           |\r\n| 登录脚本依赖        | Playwright + Chromium                                            | 脚本内置自动安装；若脚本提示缺失，AI 必须自动执行 `python3 -m pip install playwright && python3 -m playwright install chromium`，不要把安装动作交给用户 |\r\n| 缓存目录            | `~/.tme-login/`                                                  | 存放 `token.json` 和 `storage_state.json`，权限 0600                 |\r\n","tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":290,"installsAllTime":11,"installsCurrent":1,"stars":0,"versions":1},"createdAt":1778352192910,"updatedAt":1778492888959},"latestVersion":{"version":"1.0.0","createdAt":1778352192910,"changelog":"tme-openapi 1.0.0\n\n- Initial release: a general-purpose client for Tencent Music OpenAPI operator platform.\n- Provides dynamic discovery, search, detail, and invocation methods for all /musician/agent/operator/* APIs, with four tools: list_apis, search_apis, get_api_detail, and invoke_api.\n- Fully self-contained authentication: includes built-in login flow with Playwright, no external skills or user-set environment variables required. Automatic fallback for token retrieval, including browser-based scan and local caching.\n- Pure capability layer: does not encode any business logic, intended to be a foundational dependency for business-facing Skills.\n- Command line scripts included; zero dependencies beyond Python standard library for main tools, with Playwright auto-installed for login flow.","license":"MIT-0"},"metadata":null,"owner":{"handle":"sky-lv","userId":"s17fgkeb63szvtadtmm753m0gd84e4vz","displayName":"SKY-lv","image":"https://avatars.githubusercontent.com/u/259750852?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1780090775453}}