# https://github.com/lucaperret/tidal-cli 项目说明书 生成时间：2026-05-13 13:31:09 UTC ## 目录 - [项目简介与安装](#page-1) - [系统架构](#page-2) - [搜索与浏览功能](#page-3) - [播放列表管理](#page-4) - [媒体库管理](#page-5) - [播放系统与质量设置](#page-6) - [认证与会话管理](#page-7) - [发现与推荐系统](#page-8) - [MCP 服务器集成](#page-9) - [Web 端与部署](#page-10) ## 项目简介与安装 ### 相关页面 相关主题：[系统架构](#page-2), [认证与会话管理](#page-7)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md) - [site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx) - [site/app/terms/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/terms/page.tsx) - [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx) - [site/app/components/Terminal.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/components/Terminal.tsx)
# 项目简介与安装 ## 概述 tidal-cli 是一个开源的命令行工具，允许用户通过终端与 Tidal 音乐流媒体服务进行交互。该工具由 Node.js 构建，支持搜索、播放列表管理、音乐库控制等功能，专为个人使用和 LLM 代理自动化设计。 **核心特点：** - 支持搜索艺术家、专辑、曲目、视频和播放列表 - 完整的播放列表管理功能 - 音乐播放控制 - 发现和推荐功能 - JSON 输出支持，便于脚本和自动化 - MCP Server 集成，可与 Claude Desktop 等 AI 代理配合使用 资料来源：[site/app/terms/page.tsx:28-31]() --- ## 系统要求 | 要求项 | 最低版本 | 说明 | |--------|----------|------| | Node.js | >= 20 | 必须安装 Node.js 运行环境 | | Tidal 账户 | 必需 | 需要有效的 Tidal 账户进行认证 | 资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md) --- ## 安装流程 ### 全局安装 通过 npm 进行全局安装： ```bash npm install -g @lucaperret/tidal-cli ``` 资料来源：[site/app/page.tsx:72-76]() ### 认证配置 安装完成后，需要进行一次性认证： ```bash tidal-cli auth ``` 该命令会打开浏览器进行 Tidal 授权，认证成功后用户 ID 将显示在终端中。 认证完成后，所有后续操作无需交互式操作，工具会自动处理 token 刷新。 资料来源：[site/app/page.tsx:72-76]() --- ## 项目架构 ### 组件架构 ```mermaid graph TD A[用户终端] --> B[tidal-cli CLI] B --> C[本地会话存储
~/.tidal-cli/session.json] B --> D[Tidal API
openapi.tidal.com] D --> E[Tidal 服务] F[AI Agent
Claude Desktop] --> G[MCP Server
tidal-cli.lucaperret.ch/api/mcp] G --> H[Redis 加密存储
Upstash] G --> D style A fill:#e1f5fe style E fill:#f3e5f5 style G fill:#fff3e0 ``` ### 数据流向 ```mermaid sequenceDiagram participant User as 用户 participant CLI as tidal-cli participant Tidal as Tidal API participant Session as 本地会话 User->>CLI: tidal-cli auth CLI->>Tidal: OAuth 授权请求 Tidal->>User: 浏览器授权页面 User->>Tidal: 确认授权 Tidal->>CLI: 返回 Access Token CLI->>Session: 存储会话信息 Session-->>CLI: 确认存储 CLI-->>User: 认证成功 User->>CLI: tidal-cli search track "xxx" CLI->>Session: 读取 Token CLI->>Tidal: API 请求 Tidal-->>CLI: 搜索结果 CLI-->>User: 显示结果 ``` 资料来源：[site/app/privacy/page.tsx:48-54]() --- ## 核心功能模块 | 模块 | 功能描述 | 示例命令 | |------|----------|----------| | **搜索** | 搜索艺术家、专辑、曲目、视频、播放列表 | `tidal-cli search track "Teardrop"` | | **艺术家** | 获取艺术家信息、专辑、相似艺术家 | `tidal-cli artist info ` | | **专辑** | 专辑详情、条形码查询 | `tidal-cli album info ` | | **曲目** | 曲目详情、相似曲目、ISRC 查询 | `tidal-cli track info ` | | **播放列表** | 列表、创建、添加曲目/专辑 | `tidal-cli playlist list` | | **播放** | 播放控制、音质选择 | `tidal-cli playback play ` | | **发现** | 推荐、混音、播放历史 | `tidal-cli recommend` | | **保存** | 稍后保存、分享链接 | `tidal-cli saved list` | 资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md) --- ## JSON 输出模式 所有命令支持 JSON 输出格式，便于脚本处理和自动化流程： ```bash # 搜索结果 JSON 输出 tidal-cli --json search track "Around the World" # 播放列表 JSON 输出 tidal-cli --json playlist list # 艺术家信息 JSON 输出 tidal-cli --json artist similar 8992 ``` JSON 输出模式的特点： - 每个命令都支持 `--json` 参数 - 结构化数据便于程序解析 - 适合 LLM 代理和自动化脚本使用 资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md) --- ## MCP Server 集成 tidal-cli 可作为远程 MCP 服务器与 AI 代理集成： ### 集成地址 ``` https://tidal-cli.lucaperret.ch/api/mcp ``` ### Claude Desktop 配置 1. 打开 Settings → Connectors → Add custom connector 2. 添加上述 MCP 服务器地址 3. 连接后即可通过自然语言控制 Tidal ```mermaid graph LR A[Claude Desktop] -->|MCP 协议| B[tidal-cli MCP Server] B --> C[Tidal API] C --> D[Tidal 服务] B -->|加密存储| E[Upstash Redis] style A fill:#e1f5fe style E fill:#fff3e0 ``` 资料来源：[site/app/page.tsx:38-48]() --- ## 隐私与数据存储 ### CLI 模式 在命令行模式下，tidal-cli 直接与 Tidal API 服务器通信： - **认证令牌存储位置**：`~/.tidal-cli/session.json` - **数据流向**：设备 → Tidal API（无中间服务器） - **数据收集**：不收集、存储或传输任何个人数据 资料来源：[site/app/privacy/page.tsx:48-54]() ### MCP Server 模式 当作为 MCP 连接器使用时： - 认证令牌存储在 Upstash 托管的加密 Redis 数据库中 - 数据存储在 Vercel 平台上 资料来源：[site/app/privacy/page.tsx:55-58]() --- ## 快速入门命令 ```bash # 安装 tidal-cli npm install -g @lucaperret/tidal-cli # 认证 tidal-cli auth # 搜索曲目 tidal-cli search track "Around the World" # 获取艺术家详情 tidal-cli artist info 8992 # 播放曲目 tidal-cli playback play 5756235 # 列出播放列表 tidal-cli playlist list # 获取推荐 tidal-cli recommend # 查看播放历史 tidal-cli history tracks ``` 资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md) --- ## 许可与开源 tidal-cli 采用 MIT 许可证开源，源代码托管在 GitHub 上： - **开源仓库**：[github.com/lucaperret/tidal-cli](https://github.com/lucaperret/tidal-cli) - **许可证**：MIT License - **项目维护者**：Luca Perret 该项目为独立开发工具，与 Tidal 无附属关系。 资料来源：[site/app/terms/page.tsx:80-97]() --- ## 相关链接 | 资源 | 链接 | |------|------| | GitHub 仓库 | https://github.com/lucaperret/tidal-cli | | 官方网站 | https://tidal-cli.lucaperret.ch | | Smithery 集成 | https://smithery.ai/servers/lucaperret/tidal | | ClawHub | https://clawhub.ai/lucaperret/tidal-cli | | Tidal 服务 | https://tidal.com | --- ## 系统架构 ### 相关页面 相关主题：[项目简介与安装](#page-1), [认证与会话管理](#page-7), [MCP 服务器集成](#page-9)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md) - [site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx) - [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx) - [site/app/terms/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/terms/page.tsx) - [site/app/components/Terminal.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/components/Terminal.tsx)
# 系统架构 tidal-cli 是一个开源的命令行工具，用于与 Tidal 音乐流媒体服务进行交互。该项目采用模块化架构设计，同时支持命令行直接使用和 MCP（Model Context Protocol）服务器模式集成到 AI 助手（如 Claude）中。 ## 1. 整体架构概览 tidal-cli 项目包含三个主要组件： | 组件 | 说明 | 部署位置 | |------|------|----------| | CLI 工具 | 命令行界面，直接与用户交互 | 用户本地设备 | | MCP 服务器 | 远程 MCP 连接器，供 AI 代理调用 | Vercel 服务端点 | | Web 前端 | 文档和 Landing Page | Vercel/Site | 资料来源：[site/app/page.tsx:1-50]() ```mermaid graph TB subgraph 用户端 CLI[tidal-cli CLI] end subgraph 云端服务 MCP[MCP Server
tidal-cli.lucaperret.ch/api/mcp] Web[Web Frontend
tidal-cli.lucaperret.ch] end subgraph 第三方服务 TidalAPI[Tidal API
openapi.tidal.com] TidalAuth[Tidal Auth
login.tidal.com
auth.tidal.com] Upstash[Upstash Redis
Token 存储] end CLI --> TidalAPI CLI --> TidalAuth MCP --> TidalAPI MCP --> TidalAuth MCP --> Upstash Web --> MCP ``` ## 2. CLI 工具架构 ### 2.1 安装与入口 CLI 工具通过 npm 全局安装： ```bash npm install -g @lucaperret/tidal-cli ``` 安装后可通过 `tidal-cli` 命令调用，支持全局参数 `--json` 输出 JSON 格式结果。 资料来源：[README.md:1-30]() ### 2.2 命令模块 CLI 工具按功能划分为以下命令模块： | 命令模块 | 功能描述 | 示例命令 | |----------|----------|----------| | `search` | 搜索艺术家、专辑、曲目、视频、播放列表 | `tidal-cli search track "Teardrop"` | | `artist` | 获取艺术家信息和相关资源 | `tidal-cli artist info ` | | `album` | 专辑信息和条形码查询 | `tidal-cli album info ` | | `track` | 曲目详情和相似推荐 | `tidal-cli track info ` | | `playlist` | 播放列表管理 | `tidal-cli playlist list` | | `playback` | 播放控制 | `tidal-cli playback play ` | | `library` | 个人音乐库管理 | `tidal-cli library favorite-tracks` | | `history` | 播放历史和搜索历史 | `tidal-cli history tracks` | | `saved` | 稍后播放列表管理 | `tidal-cli saved list` | | `recommend` | 音乐推荐和混音 | `tidal-cli recommend` | | `share` | 创建分享链接 | `tidal-cli share track ` | 资料来源：[README.md:50-120]() ## 3. MCP 服务器架构 ### 3.1 连接配置 MCP 服务器作为远程连接器运行于 `https://tidal-cli.lucaperret.ch/api/mcp`，可与 Claude Desktop 或 claude.ai 集成。 资料来源：[site/app/page.tsx:15-25]() ```mermaid graph LR A[Claude Desktop
或 claude.ai] -->|MCP Protocol| B[MCP Connector] B --> C[Tidal API] B --> D[Upstash Redis
Token 存储] ``` ### 3.2 可用工具 MCP 服务器提供约 40 个工具，涵盖以下功能类别： - 搜索（Search） - 播放列表管理（Playlists） - 音乐库访问（Library） - 推荐服务（Recommendations） - 稍后播放（Save-for-later） - 分享功能（Sharing） 资料来源：[site/app/page.tsx:45-55]() ### 3.3 认证流程 MCP 服务器模式下的认证流程： 1. 用户通过 OAuth 连接 Tidal 账户 2. 认证令牌存储于 Upstash Redis 数据库（加密存储） 3. MCP 服务器使用存储的令牌访问 Tidal API 资料来源：[site/app/privacy/page.tsx:60-80]() ## 4. Web 前端架构 ### 4.1 技术栈 Web 前端基于 Next.js 构建，包含以下页面： | 页面路径 | 功能 | |----------|------| | `/` | Landing Page，包含安装说明和功能展示 | | `/privacy` | 隐私政策页面 | | `/terms` | 服务条款页面 | | `/api/mcp` | MCP 服务器端点 | 资料来源：[site/app/page.tsx:1-30]() 资料来源：[site/app/privacy/page.tsx:1-30]() 资料来源：[site/app/terms/page.tsx:1-30]() ### 4.2 组件结构 ```mermaid graph TD Layout[layout.tsx
根布局] --> Nav[Nav.tsx
导航栏] Layout --> Page[page.tsx
主页内容] Page --> Terminal[Terminal.tsx
终端模拟组件] Page --> Footer[页脚] ``` Web 前端主要使用 Framer Motion 实现动画效果，采用 Tidal 品牌配色方案。 资料来源：[site/app/components/Terminal.tsx:1-30]() 资料来源：[site/app/components/Nav.tsx:1-20]() ## 5. 认证与数据存储 ### 5.1 CLI 模式下的数据存储 在命令行模式下使用时，认证令牌存储在用户本地： ``` ~/.tidal-cli/session.json ``` 资料来源：[site/app/privacy/page.tsx:45-55]() ### 5.2 MCP 模式下的数据存储 | 存储类型 | 位置 | 说明 | |----------|------|------| | 认证令牌 | Upstash Redis（Vercel） | 加密存储 | | 传输协议 | 直接与 Tidal API 通信 | 不经过中间服务器 | 资料来源：[site/app/privacy/page.tsx:65-75]() ### 5.3 OAuth 流程 tidal-cli 使用 OAuth 2.0 与 Tidal 进行认证集权，支持以下端点： | 用途 | 端点 | |------|------| | 用户登录 | `login.tidal.com` | | OAuth 授权 | `auth.tidal.com` | | 音乐 API | `openapi.tidal.com` | 资料来源：[site/app/privacy/page.tsx:85-100]() ## 6. 数据流 ### 6.1 CLI 命令执行流程 ```mermaid sequenceDiagram participant User participant CLI participant TidalAuth participant TidalAPI User->>CLI: tidal-cli search track "Teardrop" CLI->>TidalAuth: 验证本地 token alt Token 有效 CLI->>TidalAPI: 搜索请求 TidalAPI-->>CLI: 搜索结果 CLI-->>User: 显示结果 else Token 无效或过期 CLI->>TidalAuth: 发起 OAuth 流程 TidalAuth-->>User: 浏览器授权 User->>TidalAuth: 确认授权 TidalAuth-->>CLI: 新 token CLI->>TidalAPI: 搜索请求 TidalAPI-->>CLI: 搜索结果 CLI-->>User: 显示结果 end ``` ### 6.2 MCP 集成流程 ```mermaid sequenceDiagram participant User participant Claude participant MCP participant Redis participant TidalAPI User->>Claude: 请求查询音乐 Claude->>MCP: 调用搜索工具 MCP->>Redis: 获取认证令牌 Redis-->>MCP: Token MCP->>TidalAPI: API 请求 TidalAPI-->>MCP: 音乐数据 MCP-->>Claude: 工具响应 Claude-->>User: 自然语言回复 ``` ## 7. 服务部署 ### 7.1 部署平台 | 组件 | 托管平台 | |------|----------| | Web 前端 | Vercel | | MCP 服务器 | Vercel Serverless Functions | | Token 存储 | Upstash Redis | ### 7.2 可用集成平台 tidal-cli MCP 连接器可在多个平台使用： - Claude Desktop / claude.ai（主要） - Smithery AI - ClawHub 资料来源：[site/app/page.tsx:35-45]() ## 8. 安全与隐私 ### 8.1 数据收集政策 tidal-cli 本身不收集、存储或传输任何个人数据到第三方服务器。所有用户数据均直接与 Tidal 服务器交互。 资料来源：[site/app/privacy/page.tsx:35-45]() ### 8.2 数据删除 | 使用模式 | 删除方式 | |----------|----------| | CLI 模式 | `rm -rf ~/.tidal-cli` | | MCP 模式 | 通过 Tidal 账户设置撤销访问权限 | 资料来源：[site/app/privacy/page.tsx:130-145]() ## 9. 开源许可 tidal-cli 采用 MIT 许可证开源，源代码托管于 GitHub： - 仓库地址：`github.com/lucaperret/tidal-cli` - 许可证：`MIT License` 资料来源：[site/app/terms/page.tsx:110-130]() ## 10. 系统要求 | 要求 | 版本 | |------|------| | Node.js | >= 20 | | Tidal 账户 | 需要 | 资料来源：[README.md:25-30]() --- ## 搜索与浏览功能 ### 相关页面 相关主题：[播放系统与质量设置](#page-6), [发现与推荐系统](#page-8)
相关源码文件 以下源码文件用于生成本页说明： - [src/search.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/search.ts) - [src/artist.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/artist.ts) - [src/album.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/album.ts) - [src/track.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/track.ts) - [src/user.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/user.ts)
# 搜索与浏览功能 tidal-cli 提供了完整的搜索与浏览功能，允许用户通过命令行接口访问 Tidal 音乐服务中的各类资源。这些功能涵盖了艺术家、专辑、曲目、视频、播放列表以及编辑推荐等多个维度的内容发现。 ## 功能概述 搜索与浏览模块是 tidal-cli 的核心功能之一，提供了对 Tidal 音乐目录的全面访问能力。用户可以通过结构化的命令查询各类媒体资源，并获取详细的元数据信息。 ### 核心能力 该模块支持以下主要功能领域： - **搜索功能**：按类型搜索艺术家、专辑、曲目、视频、播放列表 - **艺术家浏览**：获取艺术家信息、热门曲目、专辑列表、相似推荐 - **专辑浏览**：查看专辑详情、曲目列表、条形码查询 - **曲目浏览**：获取曲目信息、ISRC 识别、相似推荐 - **用户历史**：查看和管理搜索历史、播放历史 ## 搜索功能详解 ### 搜索命令结构 tidal-cli 的搜索功能采用统一的命令格式，支持多种内容类型的搜索。 ```bash tidal-cli search <类型> <查询词> ``` ### 支持的搜索类型 | 类型 | 说明 | 示例命令 | |------|------|----------| | `artist` | 搜索艺术家 | `tidal-cli search artist "Gorillaz"` | | `album` | 搜索专辑 | `tidal-cli search album "Mezzanine"` | | `track` | 搜索曲目 | `tidal-cli search track "Teardrop"` | | `video` | 搜索视频 | `tidal-cli search video "Stylo"` | | `playlist` | 搜索播放列表 | `tidal-cli search playlist "Electronic"` | | `suggest` | 自动建议 | `tidal-cli search suggest "daft punk"` | | `editorial` | 编辑推荐 | `tidal-cli search editorial "indie rock"` | ### 搜索历史管理 系统会记录用户的搜索历史，并提供管理功能： ```bash tidal-cli search history # 查看搜索历史 tidal-cli search history-delete # 删除单条历史记录 tidal-cli search history-clear # 清空所有历史记录 ``` 资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md) ## 艺术家浏览 艺术家模块提供对艺术家完整信息的访问能力。 ### 可用命令 | 命令 | 功能描述 | |------|----------| | `tidal-cli artist info ` | 获取艺术家基本信息 | | `tidal-cli artist tracks ` | 获取艺术家的热门曲目 | | `tidal-cli artist albums ` | 获取艺术家的专辑列表 | | `tidal-cli artist similar ` | 查找相似艺术家 | | `tidal-cli artist radio ` | 获取艺术家电台（推荐曲目） | ### 数据获取流程 ```mermaid graph TD A[输入 artist 命令] --> B[解析命令参数] B --> C[调用 Tidal API] C --> D{查询类型} D -->|info| E[获取艺术家详情] D -->|tracks| F[获取热门曲目] D -->|albums| G[获取专辑列表] D -->|similar| H[获取相似艺术家] D -->|radio| I[生成艺术家电台] E --> J[格式化输出] F --> J G --> J H --> J I --> J ``` ## 专辑浏览 专辑模块支持专辑信息和曲目列表的查询。 ### 可用命令 | 命令 | 功能描述 | |------|----------| | `tidal-cli album info ` | 获取专辑详细信息 | | `tidal-cli album barcode ` | 通过 EAN 条形码查询专辑 | ### 专辑信息内容 专辑信息通常包含以下内容： - 专辑标题和艺术家名称 - 发行日期 - 曲目数量 - 专辑封面 - 音频质量信息 ## 曲目浏览 曲目模块提供曲目级别的详细信息和元数据。 ### 可用命令 | 命令 | 功能描述 | |------|----------| | `tidal-cli track info ` | 获取曲目详细信息 | | `tidal-cli track similar ` | 查找相似曲目 | | `tidal-cli track isrc ` | 通过 ISRC 码识别曲目 | | `tidal-cli track radio ` | 获取基于该曲目的电台 | ### ISRC 查询功能 ISRC（国际标准录音代码）是曲目的唯一标识符，支持精确的曲目识别： ```bash tidal-cli track isrc ``` 此功能允许用户通过已知的 ISRC 码快速定位特定曲目，适用于从其他来源获取的曲目元数据。 资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md) ## 发现与推荐 ### 推荐功能 tidal-cli 提供个性化推荐功能，支持多种推荐类型： ```bash tidal-cli recommend # 获取所有推荐分类 tidal-cli recommend --type daily # 每日推荐 tidal-cli recommend --type discovery # 发现推荐 tidal-cli recommend --type new-release # 新发行 tidal-cli recommend --type offline # 离线推荐 ``` ### Mix 内容 获取 Mix 详情： ```bash tidal-cli mix items --type daily ``` 支持的 Mix 类型包括 `daily`、`discovery`、`new-release`、`offline`。 ### 用户历史 查看个人使用历史： ```bash tidal-cli history tracks # 播放过的曲目 tidal-cli history albums # 播放过的专辑 tidal-cli history artists # 播放过的艺术家 ``` ### 用户资料 获取当前登录用户的信息： ```bash tidal-cli user profile ``` 此命令返回用户账户的详细信息，包括订阅状态、用户 ID 等。 资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md) ## JSON 输出 所有搜索和浏览命令支持 JSON 格式输出，便于程序化处理和脚本集成。 ### 使用方式 在命令前添加 `--json` 标志： ```bash tidal-cli --json search track "Around the World" tidal-cli --json playlist list tidal-cli --json artist similar 8992 ``` ### 输出格式 JSON 输出包含完整的 API 响应数据，结构化呈现所有可用字段。 ## 命令索引表 ### 搜索命令 | 命令 | 描述 | |------|------| | `search artist ` | 搜索艺术家 | | `search album ` | 搜索专辑 | | `search track ` | 搜索曲目 | | `search video ` | 搜索视频 | | `search playlist ` | 搜索播放列表 | | `search suggest ` | 自动建议 | | `search editorial ` | 编辑推荐 | | `search history` | 查看搜索历史 | | `search history-delete ` | 删除历史记录 | | `search history-clear` | 清空历史记录 | ### 浏览命令 | 命令 | 描述 | |------|------| | `artist info ` | 艺术家详情 | | `artist tracks ` | 艺术家曲目 | | `artist albums ` | 艺术家专辑 | | `artist similar ` | 相似艺术家 | | `artist radio ` | 艺术家电台 | | `album info ` | 专辑详情 | | `album barcode ` | 条形码查询 | | `track info ` | 曲目详情 | | `track similar ` | 相似曲目 | | `track isrc ` | ISRC 查询 | | `track radio ` | 曲目电台 | | `user profile` | 用户资料 | ### 发现命令 | 命令 | 描述 | |------|------| | `recommend` | 获取所有推荐 | | `recommend --type ` | 指定类型推荐 | | `mix items --type ` | Mix 内容 | | `history tracks` | 播放历史-曲目 | | `history albums` | 播放历史-专辑 | | `history artists` | 播放历史-艺术家 | ## 技术架构 ### 模块组织 搜索与浏览功能分布在以下核心模块中： - **src/search.ts**：搜索命令实现，支持多种类型的搜索查询 - **src/artist.ts**：艺术家相关功能，包括信息、曲目、专辑、相似推荐 - **src/album.ts**：专辑浏览和条形码查询功能 - **src/track.ts**：曲目查询、ISRC 识别、相似曲目 - **src/user.ts**：用户资料和历史记录管理 ### API 交互 所有搜索和浏览功能通过 Tidal API 进行数据获取，命令行工具负责： 1. 解析用户输入的命令和参数 2. 调用相应的 Tidal API 端点 3. 格式化并输出返回的数据 4. 支持 JSON 和人类可读两种输出格式 ## 最佳实践 ### 高效搜索 - 使用精确的曲目名称可获得更准确的结果 - 搜索专辑时使用完整的专辑名称 - ISRC 查询是定位精确曲目的最可靠方式 ### 结果处理 - 使用 `--json` 标志便于程序化处理 - 结合 shell 管道处理大规模数据 - 利用播放历史功能追踪音乐偏好 ### 错误处理 - 确保 Tidal 账户已通过 `tidal-cli auth` 认证 - 检查网络连接状况 - 确认 API 配额未超限 --- ## 播放列表管理 ### 相关页面 相关主题：[搜索与浏览功能](#page-3), [媒体库管理](#page-5)
相关源码文件 以下源码文件用于生成本页说明： - [src/playlist.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/playlist.ts) - [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)
# 播放列表管理 tidal-cli 的播放列表管理功能提供了一套完整的命令行接口，用于在 Tidal 音乐平台上创建、编辑和操作个人播放列表。该模块支持查看列表详情、添加/移除曲目、重命名、删除以及生成分享链接等核心操作。 ## 功能概述 播放列表管理模块的核心职责包括： - **列表查询**：查看用户所有播放列表及其基本信息 - **创建与删除**：新建播放列表或删除已有列表 - **曲目管理**：向播放列表添加或移除曲目 - **编辑操作**：重命名播放列表 - **分享功能**：生成可公开访问的分享链接 资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md) ## 命令行接口 ### 播放列表查询 | 命令 | 说明 | |------|------| | `tidal-cli playlist list` | 列出用户所有播放列表 | | `tidal-cli playlist info ` | 获取指定播放列表的详细信息 | ### 播放列表操作 | 命令 | 说明 | |------|------| | `tidal-cli playlist create ` | 创建新播放列表 | | `tidal-cli playlist rename --name ` | 重命名播放列表 | | `tidal-cli playlist delete ` | 删除播放列表 | | `tidal-cli playlist share ` | 生成播放列表分享链接 | ### 曲目管理 | 命令 | 说明 | |------|------| | `tidal-cli playlist add --track-id ` | 向播放列表添加曲目 | | `tidal-cli playlist remove --track-id ` | 从播放列表移除曲目 | 资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md) ## JSON 输出支持 所有播放列表命令均支持 `--json` 参数，可直接用于程序化处理： ```bash tidal-cli --json playlist list tidal-cli --json playlist info ``` JSON 输出格式示例： ```json [{ "id": "a20fff4a-...", "name": "Late Night Electronic", "numberOfItems": 24, "createdAt": "2025-04-20T..." }, ...] ``` 资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx) ## 使用流程图 ```mermaid graph TD A[开始] --> B{选择操作} B -->|查看列表| C[playlist list] B -->|创建列表| D[playlist create] B -->|管理曲目| E[playlist add/remove] B -->|其他操作| F[info/rename/delete/share] C --> G[显示播放列表] D --> H[输入列表名称] H --> I[创建成功] E --> J[输入播放列表ID和曲目ID] J --> K[操作完成] F --> L[执行相应操作] G --> M[结束] I --> M K --> M L --> M ``` ## 典型使用场景 ### 创建并填充播放列表 ```bash # 1. 创建新播放列表 tidal-cli playlist create "My Favorites" # 2. 搜索曲目获取ID tidal-cli search track "Teardrop" # 3. 添加曲目到播放列表 tidal-cli playlist add --track-id ``` ### 查看和管理已有列表 ```bash # 查看所有播放列表 tidal-cli playlist list # 查看特定列表详情 tidal-cli playlist info # 重命名列表 tidal-cli playlist rename --name "New Name" # 移除不需要的曲目 tidal-cli playlist remove --track-id ``` ## 数据存储 tidal-cli 将用户认证信息和会话数据存储在本地 `~/.tidal-cli` 目录中。播放列表数据通过 Tidal API 实时获取，不在本地缓存。 如需清除所有本地数据（包括播放列表相关的认证信息）： ```bash rm -rf ~/.tidal-cli ``` 资料来源：[site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx) ## 与 MCP 集成 播放列表管理功能可通过 MCP（Model Context Protocol）协议供 AI 代理调用： ``` tidal-cli search history tidal-cli library favorite-playlists ``` MCP 端点地址：`https://tidal-cli.lucaperret.ch/api/mcp` 资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx) --- ## 媒体库管理 ### 相关页面 相关主题：[播放列表管理](#page-4), [播放系统与质量设置](#page-6)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md) - [src/library.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/library.ts) — 核心媒体库模块 - [src/saved.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/saved.ts) — 稍后再听与收藏管理 - [src/history.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/history.ts) — 播放历史记录 - [src/search-history.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/search-history.ts) — 搜索历史管理
# 媒体库管理 tidal-cli 的媒体库管理模块为用户提供了一套完整的个人音乐库访问与操作接口。该模块涵盖了发现推荐、播放历史、搜索历史、收藏管理以及个人资料查询等核心功能。通过命令行界面，用户可以高效地管理与 Tidal 账户关联的所有媒体资源，无需依赖图形界面即可完成复杂的媒体库操作。 ## 功能架构概览 媒体库管理功能由四个主要子模块组成，分别负责不同的管理职责。这些模块之间相互协作，共同构成了 tidal-cli 的完整媒体库管理体系。 ```mermaid graph TD A[媒体库管理] --> B[library.ts] A --> C[saved.ts] A --> D[history.ts] A --> E[search-history.ts] B --> F[发现推荐] B --> G[用户资料] C --> H[稍后再听] C --> I[分享链接] D --> J[播放历史] E --> K[搜索历史] ``` ## 发现与推荐系统 tidal-cli 提供了强大的音乐发现功能，帮助用户探索 Tidal 平台上的新内容。该功能支持多种推荐类型和播放列表生成。 ### 推荐类型 系统支持三种主要的推荐模式，每种模式针对不同的用户场景： | 推荐类型 | 命令参数 | 说明 | |---------|---------|------| | 每日推荐 | `--type daily` | 基于用户音乐品味的每日个性化推荐 | | 发现推荐 | `--type discovery` | 探索用户可能喜欢但尚未听过的新音乐 | | 新发行 | `--type new-release` | 最近上架的新专辑和新单曲 | | 离线推荐 | `--type offline` | 可供离线下载的推荐内容 | ```bash tidal-cli recommend # 获取所有推荐分类 tidal-cli recommend --type daily # 仅获取每日推荐 tidal-cli mix items --type daily # 查看特定推荐中的曲目 ``` ### 播放列表电台 除了固定的推荐列表外，tidal-cli 还支持动态播放列表电台功能。这种模式会根据用户当前播放的内容，实时生成类似风格的播放列表。 ```bash tidal-cli artist radio # 获取艺术家电台 tidal-cli track radio # 获取歌曲电台 ``` ## 播放历史记录 播放历史模块允许用户查看和管理自己的音乐收听记录。该功能支持多种内容类型的历史查询。 ### 历史查询命令 ```bash tidal-cli history tracks # 查看播放过的歌曲历史 tidal-cli history albums # 查看播放过的专辑历史 tidal-cli history artists # 查看播放过的艺术家历史 ``` ### 历史记录数据结构 播放历史记录包含以下关键信息： | 字段 | 说明 | |-----|------| | 播放时间戳 | 记录歌曲何时被播放 | | 内容类型 | 歌曲、专辑或艺术家 | | 内容标识 | 对应的 Tidal ID | | 播放时长 | 实际播放的时长信息 | 历史数据通过 Tidal API 的 `user/history` 端点获取，支持分页查询以便处理大量历史记录。 ## 搜索历史管理 tidal-cli 提供了完整的搜索历史管理功能，帮助用户追踪和管理过往的搜索记录。 ### 搜索历史操作 ```bash tidal-cli search history # 查看最近的搜索记录 tidal-cli search history-delete # 删除单条搜索记录 tidal-cli search history-clear # 清除所有搜索历史 ``` ### 数据存储位置 搜索历史记录存储在本地配置目录中： - **存储路径**: `~/.tidal-cli/search-history.json` - **数据格式**: JSON 数组，每条记录包含搜索关键词和时间戳 ## 收藏与稍后再听 `saved.ts` 模块实现了"稍后再听"（Saved for Later）功能，这是 tidal-cli 中最常用的媒体库管理功能之一。用户可以将任意媒体内容添加到稍后再听列表中稍后播放。 ### 收藏管理命令 ```bash tidal-cli saved list # 列出所有收藏内容 tidal-cli saved add --type tracks --id # 添加歌曲到收藏 tidal-cli saved remove --type albums --id # 从收藏中移除专辑 ``` ### 支持的媒体类型 | 类型参数 | 说明 | |---------|------| | `tracks` | 单曲歌曲 | | `albums` | 完整专辑 | | `artists` | 艺术家页面 | | `playlists` | 播放列表 | | `videos` | 音乐视频 | ## 分享功能 tidal-cli 内置了社交分享功能，允许用户为任意媒体内容生成公开分享链接。 ### 分享命令 ```bash tidal-cli share track # 生成歌曲分享链接 tidal-cli share album # 生成专辑分享链接 ``` 分享链接会调用 Tidal API 生成临时或永久的公开访问地址，接收方无需登录即可预览或播放分享的内容（受 Tidal 服务条款限制）。 ## 用户资料查询 通过用户资料命令，用户可以查看与当前账户相关的完整信息。 ```bash tidal-cli user profile # 查看当前用户资料 ``` ### 用户资料包含的信息 - **账户类型**: Free、HiFi 或 HiFi Plus 订阅等级 - **用户 ID**: Tidal 平台唯一标识符 - **账户状态**: 有效、过期等状态信息 - **配额信息**: 剩余的下载配额或离线播放限额 ## 数据流与交互 ```mermaid sequenceDiagram participant User as 用户终端 participant CLI as tidal-cli CLI participant API as Tidal API participant Store as 本地存储 User->>CLI: 执行媒体库命令 CLI->>API: 发送认证请求 API-->>CLI: 返回认证令牌 CLI->>API: 请求媒体库数据 API-->>CLI: 返回媒体信息 CLI->>Store: 缓存热门数据 CLI-->>User: 格式化输出结果 Note over CLI,Store: 保存功能 (saved add) User->>CLI: 保存媒体到收藏 CLI->>API: 提交保存请求 API-->>CLI: 确认保存成功 CLI->>Store: 更新本地索引 ``` ## 与 MCP 服务器的集成 tidal-cli 的媒体库管理功能也通过 MCP（Model Context Protocol）服务器对外暴露，使得 AI 代理（如 Claude）能够以编程方式控制 Tidal 媒体库。 ### MCP 工具可用性 以下媒体库操作可通过 MCP 接口调用： - `library list-saved` — 列出收藏内容 - `library add-saved` — 添加收藏 - `library remove-saved` — 移除收藏 - `library history` — 查询播放历史 - `library recommend` — 获取推荐内容 - `user profile` — 用户资料查询 ## 输出格式 所有媒体库命令支持 JSON 格式输出，便于脚本处理和自动化工作流。 ```bash tidal-cli --json search track "Around the World" tidal-cli --json playlist list tidal-cli --json artist similar 8992 ``` 添加 `--json` 参数后，命令输出为纯 JSON 格式，不再包含任何装饰性文本或进度提示。 ## 本地数据存储 tidal-cli 在本地存储以下与媒体库相关的数据： | 存储内容 | 文件路径 | 说明 | |---------|---------|------| | 认证令牌 | `~/.tidal-cli/session.json` | OAuth 访问令牌 | | 搜索历史 | `~/.tidal-cli/search-history.json` | 本地搜索缓存 | | 配置文件 | `~/.tidal-cli/config.json` | 用户偏好设置 | 数据以加密形式存储认证敏感信息，本地存储目录权限应限制为仅当前用户可访问。 ## 相关文档 - **安装指南**: 请参考 [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md) 的安装章节 - **服务条款**: 使用本工具需遵守 [Tidal 服务条款](https://tidal.com/terms) - **隐私政策**: 详见 [隐私政策页面](/privacy) --- ## 播放系统与质量设置 ### 相关页面 相关主题：[搜索与浏览功能](#page-3), [媒体库管理](#page-5)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md) - [src/auth.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/auth.ts) - [site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx) - [site/app/terms/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/terms/page.tsx) - [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)
# 播放系统与质量设置 ## 概述 tidal-cli 的播放系统允许用户通过命令行直接控制 Tidal 音乐的播放功能。该系统提供了播放指定曲目、获取播放信息、获取音频流 URL 等核心能力，并支持多种音频质量级别。 播放命令基于 Tidal API 的播放端点实现，支持通过曲目 ID 进行播放操作。 资料来源：[README.md:1-100]() ## 播放命令架构 ### 子命令结构 tidal-cli 的播放功能通过 `playback` 子命令组织，包含以下操作： | 子命令 | 说明 | 参数 | |--------|------|------| | `play` | 播放指定曲目 | `` 曲目 ID，可选 `--quality` 参数 | | `info` | 获取曲目播放信息 | `` 曲目 ID | | `url` | 获取音频流 URL | `` 曲目 ID | 资料来源：[README.md:1-100]() ### 基本使用方式 ```bash # 播放指定曲目 tidal-cli playback play # 以无损质量播放 tidal-cli playback play --quality LOSSLESS # 获取播放信息 tidal-cli playback info # 获取音频流 URL tidal-cli playback url ``` 资料来源：[README.md:1-100]() ## 音频质量设置 ### 支持的质量级别 tidal-cli 支持四种音频质量级别，通过 `--quality` 参数指定： | 质量级别 | 说明 | 适用场景 | |----------|------|----------| | `LOW` | 低比特率 | 节省带宽/流量 | | `HIGH` | 高比特率 | 标准音质 | | `LOSSLESS` | 无损音质 | 高保真聆听 | | `HI_RES` | 高解析音频 | 发烧友级别 | 资料来源：[README.md:1-100]() ### 质量选择示例 ```bash # 默认质量播放 tidal-cli playback play 5756235 # 指定无损质量播放 tidal-cli playback play 5756235 --quality LOSSLESS # 高解析音频播放 tidal-cli playback play 5756235 --quality HI_RES ``` > **注意**: 实际可用的音频质量取决于用户的 Tidal 订阅计划。例如，HI_RES 质量仅对 HiFi Plus 订阅用户可用。 资料来源：[README.md:1-100]() 资料来源：[site/app/terms/page.tsx:1-50]() ## 工作流程 ### 播放流程图 ```mermaid graph TD A[用户执行 playback play 命令] --> B[解析曲目 ID 和质量参数] B --> C{是否指定质量} C -->|是| D[使用指定质量级别] C -->|否| E[使用账户默认质量] D --> F[调用 Tidal API 播放端点] E --> F F --> G{API 响应状态} G -->|成功| H[开始播放音频流] G -->|失败| I[输出错误信息] ``` ## 与其他系统的集成 ### 播放与发现功能结合 播放系统可与搜索、历史等功能结合使用： ```bash # 搜索后播放 tidal-cli search track "Teardrop" # 获取曲目 ID 后 tidal-cli playback play <找到的ID> # 播放历史记录中的曲目 tidal-cli history tracks # 选择曲目 ID 后 tidal-cli playback play <历史曲目ID> ``` ### 与 AI Agent 的集成 通过 MCP 连接器，用户可以让 AI Agent 智能选择并播放音乐： ```bash # AI Agent 可执行的操作示例 "Play me something by Boards of Canada" # 搜索并播放 ``` 资料来源：[site/app/page.tsx:1-50]() ## JSON 输出支持 播放相关命令支持 `--json` 参数以结构化格式输出： ```bash # JSON 格式获取播放信息 tidal-cli --json playback info # JSON 格式获取音频 URL tidal-cli --json playback url ``` 此功能便于脚本处理和程序化调用。 资料来源：[README.md:1-100]() ## 认证要求 播放功能需要有效的 Tidal 认证会话。用户需在首次使用前完成身份验证： ```bash # 身份验证命令 tidal-cli auth ``` 认证成功后，OAuth 令牌将存储在本地 `~/.tidal-cli/session.json` 文件中。令牌会自动刷新以维持会话有效性。 资料来源：[README.md:1-100]() 资料来源：[site/app/privacy/page.tsx:1-50]() ## 技术限制 - 播放功能依赖 Tidal API，可能受 Tidal 服务可用性影响 - API 变更可能导致播放功能暂时不可用 - 某些地区可能存在播放限制 > tidal-cli is provided **"as is"** without warranty of any kind. Tidal may change their API at any time, which could affect functionality. 资料来源：[site/app/terms/page.tsx:1-50]() ## 故障排除 ### 常见问题 | 问题 | 可能原因 | 解决方案 | |------|----------|----------| | 播放失败 | 未认证或会话过期 | 运行 `tidal-cli auth` 重新认证 | | 质量设置无效 | 订阅计划不支持 | 升级 Tidal 订阅计划 | | 无法获取 URL | API 限制 | 检查网络连接或稍后重试 | 资料来源：[site/app/privacy/page.tsx:1-50]() --- ## 认证与会话管理 ### 相关页面 相关主题：[系统架构](#page-2), [发现与推荐系统](#page-8), [MCP 服务器集成](#page-9)
相关源码文件 以下源码文件用于生成本页说明： - [src/auth.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/auth.ts) - [src/session.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/session.ts) - [site/app/mcp-lib/tidal-oauth.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/mcp-lib/tidal-oauth.ts) - [site/app/mcp-lib/constants.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/mcp-lib/constants.ts) - [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)
# 认证与会话管理 ## 概述 tidal-cli 的认证与会话管理系统是该项目的核心基础设施，负责处理用户与 Tidal API 之间的安全通信。该模块基于 OAuth 2.0 授权码模式配合 PKCE（Proof Key for Code Exchange）扩展实现无密钥的安全认证流程。系统设计了双轨制架构，分别支持命令行工具（CLI）的本地会话存储和 MCP 服务器的服务端会话管理，确保用户凭证在传输和存储过程中的安全性。 ## 认证机制 ### OAuth 2.0 + PKCE 架构 tidal-cli 采用公开客户端（Public Client）OAuth 流程，无需客户端密钥即可完成认证。系统利用 PKCE 机制替代传统客户端密钥，通过动态生成的代码挑战和验证器来保障授权码交换的安全性。 ```mermaid graph TD A[用户执行 tidal-cli auth] --> B[生成 code_verifier 和 code_challenge] B --> C[构建授权 URL] C --> D[启动本地回调服务器] D --> E[打开浏览器跳转至 Tidal 授权页] E --> F[用户登录并授权] F --> G[Tidal 重定向至本地回调服务器] G --> H[交换授权码获取 Access Token] H --> I[保存会话至 ~/.tidal-cli/session.json] I --> J[认证成功] ``` ### 认证流程详解 #### 第一阶段：启动本地服务器 ```typescript server.listen(REDIRECT_PORT, () => { console.log('\nOpening browser for Tidal authorization...'); console.log(`If the browser doesn't open, visit:\n ${loginUrl}\n`); console.log('Waiting for authorization...'); openBrowser(loginUrl); }); ``` 系统在本地随机端口启动 HTTP 服务器，监听来自 Tidal OAuth 服务的回调请求。此服务器作为授权码的接收端点，确保令牌交换过程在用户本地完成，避免凭证经过第三方服务器。 #### 第二阶段：令牌交换 授权码交换过程采用 PKCE 验证机制： | 参数 | 说明 | 来源 | |------|------|------| | `grant_type` | 授权类型，值为 `authorization_code` | RFC 6749 标准 | | `code` | Tidal 返回的授权码 | 回调请求参数 | | `client_id` | Tidal 应用客户端 ID | 硬编码配置 | | `code_verifier` | 高熵随机字符串（43-128字符） | 动态生成 | | `redirect_uri` | 回调地址 | `http://localhost:{REDIRECT_PORT}` | ### CLI 与 MCP 认证差异 tidal-cli 提供两种使用模式，认证存储策略存在本质区别： | 模式 | 存储位置 | 加密方式 | 有效期 | |------|----------|----------|--------| | CLI | `~/.tidal-cli/session.json` | 无加密（文件权限保护） | 令牌自身过期时间 | | MCP | Upstash Redis | TLS 传输加密 | 30 天 TTL | 资料来源：[site/app/privacy/page.tsx]() CLI 模式下，用户的 OAuth 令牌以 JSON 格式持久化至用户主目录下的隐藏文件夹，依赖操作系统文件权限机制进行保护。MCP 模式则将令牌托管于 Vercel 部署的 Upstash Redis 缓存服务，通过服务端加密确保传输安全，并设置 30 天生存时间自动过期。 ## 会话存储 ### 本地会话管理 #### Session 模块架构 ```mermaid classDiagram class SessionStorage { +getItem(key): string | null +setItem(key, value): void +removeItem(key): void +clear(): void } class EventTarget { +addEventListener() +removeEventListener() +dispatchEvent() } class StorageEvent { +key: string +newValue: string +oldValue: string } SessionStorage --|> EventTarget SessionStorage ..> StorageEvent : creates ``` tidal-cli 在 Node.js 环境中实现了 `localStorage` 和 `EventTarget` API 的 polyfill，使得标准 Web 存储接口可直接用于服务端环境。 #### 会话文件格式 ```json { "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "expires_at": 1710489600000, "userId": "123456789" } ``` 会话文件采用 JSON 格式存储关键认证信息，包含访问令牌、刷新令牌、过期时间戳及用户 ID。访问令牌用于 API 请求认证，刷新令牌用于获取新的访问令牌而无需用户重新授权。 ### 服务端会话管理（MCP） #### Redis 存储策略 MCP 连接器使用 Upstash Redis 实现跨会话持久化： ```typescript // 伪代码示例 const sessionData = { token: encryptedOAuthToken, userId: extractedUserId, createdAt: Date.now() }; // 设置 30 天过期时间 await redis.setex(sessionKey, 30 * 24 * 60 * 60, JSON.stringify(sessionData)); ``` 资料来源：[site/app/privacy/page.tsx]() 服务端存储采用加密机制保护敏感令牌数据，所有通过 MCP 协议进行的 API 调用都需要从 Redis 中提取有效会话信息。30 天 TTL 确保长期未使用的会话自动清理，减少安全风险。 ## API 客户端 ### getApiClient 函数 ```typescript export async function getApiClient(): Promise { await ensureInit(); // Verify we have valid credentials const creds = await credentialsProvider.getCredentials(); if (!creds.token) { console.error('Error: Not authenticated. Run `tidal-cli auth` first.'); process.exit(1); } return createAPIClient(credentialsProvider); } ``` 该函数是获取 Tidal API 客户端的主入口点，核心职责包括： 1. **初始化检查**：调用 `ensureInit()` 确保认证模块已正确初始化 2. **凭证验证**：从凭证提供者获取当前会话凭证 3. **错误处理**：检测到未认证状态时输出错误信息并终止程序 4. **客户端创建**：返回配置了凭证的 API 客户端实例 资料来源：[src/auth.ts]() ### getCountryCode 函数 ```typescript let cachedCountryCode: string | null = null; export async function getCountryCode(): Promise { if (cachedCountryCode) return cachedCountryCode; try { const client = await getApiClient(); const { data } = await client.GET('/users/{id}' as any, { // ... }); // 从用户配置中提取国家代码 } catch { // 降级策略 } } ``` 国家代码自动检测机制遵循以下优先级： | 优先级 | 来源 | 说明 | |--------|------|------| | 1 | 用户资料 | 通过 `/users/me` API 获取用户账户国家 | | 2 | 环境变量 | `TIDAL_COUNTRY` 环境变量 | | 3 | 默认值 | `US` | 该机制确保 API 请求携带正确的地区标识，获取符合用户所在区域的内容目录和播放限制信息。 ## Token 自动刷新 ### 刷新机制流程 ```mermaid sequenceDiagram participant U as 用户 participant CLI as tidal-cli participant T as Tidal API participant FS as 文件系统 U->>CLI: 执行任意命令 CLI->>T: 发送带 Access Token 的请求 T-->>CLI: Token 有效 CLI-->>U: 返回请求结果 Note over CLI,T: Token 过期场景 U->>CLI: 执行任意命令 CLI->>T: 发送带 Access Token 的请求 T-->>CLI: 401 Unauthorized CLI->>T: 使用 Refresh Token 获取新 Token T-->>CLI: 返回新 Access Token + 新 Refresh Token CLI->>FS: 更新 session.json CLI->>T: 重试原请求 CLI-->>U: 返回请求结果 ``` ### 刷新触发条件 自动刷新机制在以下场景触发： - **令牌过期**：API 返回 401 状态码时自动尝试刷新 - **令牌临近过期**：部分实现会在令牌即将过期前主动刷新 - **首次认证**：执行 `tidal-cli auth` 命令后立即保存初始令牌 刷新成功后，新的访问令牌和刷新令牌会持久化至 `~/.tidal-cli/session.json`，确保下次启动时使用最新凭证。 ## 数据安全 ### 隐私保护措施 tidal-cli 在设计层面采取多重数据保护策略： | 措施 | CLI 模式 | MCP 模式 | |------|----------|----------| | 凭证传输 | 直接与 Tidal API 通信 | 经由 Vercel 服务器转发 | | 凭证存储 | 本地文件系统 | Upstash Redis（加密） | | 数据收集 | 无分析、无遥测 | 无分析、无遥测 | | Cookie 使用 | 无 | 仅 Tidal OAuth 流程所需 | 资料来源：[site/app/privacy/page.tsx]() ### 第三方服务依赖 认证流程涉及以下 Tidal 官方服务端点： | 服务 | 端点 | 用途 | |------|------|------| | Tidal API | `openapi.tidal.com` | 音乐目录、播放列表访问 | | Tidal Auth | `login.tidal.com` | 用户登录界面 | | Tidal Auth | `auth.tidal.com` | OAuth 令牌交换 | 所有通信遵循 Tidal 官方隐私政策，用户凭证永远不会经过 tidal-cli 维护者的服务器（除 MCP 模式的服务端存储）。 ### 数据删除 用户可通过以下方式清除所有本地认证数据： ```bash rm -rf ~/.tidal-cli ``` 此命令删除包含 OAuth 令牌和会话信息的整个目录。删除后用户需重新执行 `tidal-cli auth` 进行认证。 ## 相关命令 ### auth 命令 ```bash tidal-cli auth ``` 启动 OAuth 认证流程，打开浏览器引导用户完成 Tidal 账户授权。 ### 依赖模块 | 模块 | 文件路径 | 功能描述 | |------|----------|----------| | 认证核心 | `src/auth.ts` | OAuth 流程、API 客户端获取 | | 会话存储 | `src/session.ts` | localStorage polyfill 实现 | | MCP OAuth | `site/app/mcp-lib/tidal-oauth.ts` | 服务端 OAuth 处理 | | MCP 常量 | `site/app/mcp-lib/constants.ts` | 配置常量和端点定义 | ## 总结 tidal-cli 的认证与会话管理系统通过 OAuth 2.0 + PKCE 协议实现了安全的无密钥认证，结合本地和服务端双轨存储策略兼顾了 CLI 用户的数据主权和 MCP 用户的使用便利性。Token 自动刷新机制确保长时间使用的连贯体验，而清晰的数据安全设计让用户对自己的凭证拥有完全控制权。 --- ## 发现与推荐系统 ### 相关页面 相关主题：[搜索与浏览功能](#page-3), [媒体库管理](#page-5)
相关源码文件 以下源码文件用于生成本页说明： - [src/recommend.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/recommend.ts) - [src/mix.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/mix.ts) - [src/share.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/share.ts) - [src/history.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/history.ts) - [src/saved.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/saved.ts) - [src/user.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/user.ts)
# 发现与推荐系统 ## 概述 tidal-cli 的发现与推荐系统为用户提供了一套完整的音乐探索功能，包括个性化推荐、智能混音、用户历史记录管理以及社交分享能力。该系统与 Tidal API 深度集成，使用户能够在命令行环境中完成传统桌面或移动应用中的所有发现操作。 ## 系统架构 发现与推荐系统由多个相互协作的模块组成，每个模块负责特定的功能域： | 模块 | 功能描述 | 主要命令 | |------|----------|----------| | `recommend` | 个性化推荐与混音获取 | `tidal-cli recommend` | | `mix` | 混音曲目管理 | `tidal-cli mix items` | | `history` | 用户行为历史记录 | `tidal-cli history tracks` | | `saved` | 稍后播放与收藏管理 | `tidal-cli saved list` | | `share` | 公开分享链接生成 | `tidal-cli share track` | | `user` | 用户资料获取 | `tidal-cli user profile` | ## 推荐与混音 ### 获取推荐内容 `tidal-cli recommend` 命令用于获取系统推荐的各种混音类型： ```bash tidal-cli recommend # 获取所有混音类别 tidal-cli recommend --type daily # 每日推荐混音 tidal-cli recommend --type discovery # 发现混音 tidal-cli recommend --type new-release # 新发行混音 tidal-cli recommend --type offline # 离线可用混音 ``` ### 混音曲目管理 获取特定混音后，可通过 `mix items` 命令查看混音内的所有曲目： ```bash tidal-cli mix items --type daily ``` ## 历史记录系统 ### 播放历史 tidal-cli 记录并管理用户的三类播放历史： | 命令 | 功能 | |------|------| | `tidal-cli history tracks` | 查看最近播放的曲目 | | `tidal-cli history albums` | 查看最近播放的专辑 | | `tidal-cli history artists` | 查看最近播放的艺术家 | ### 搜索历史 系统同时维护用户的搜索历史，支持以下操作： ```bash tidal-cli search history # 查看最近的搜索记录 tidal-cli search history-delete # 删除单条搜索记录 tidal-cli search history-clear # 清空全部搜索历史 ``` ## 保存与收藏 ### 稍后播放列表 `saved` 命令提供对“稍后播放”列表的管理功能： ```bash tidal-cli saved list # 列出所有已保存的项目 tidal-cli saved add --type tracks --id # 添加曲目到保存列表 tidal-cli saved add --type albums --id # 添加专辑到保存列表 tidal-cli saved add --type artists --id # 添加艺术家到保存列表 tidal-cli saved add --type playlists --id # 添加播放列表 tidal-cli saved add --type videos --id # 添加视频到保存列表 ``` ### 移除已保存项目 ```bash tidal-cli saved remove --type albums --id ``` ## 分享功能 tidal-cli 支持生成公开分享链接，允许用户与他人共享音乐内容： ```bash tidal-cli share track # 创建曲目的公开分享链接 tidal-cli share album # 创建专辑的公开分享链接 ``` 分享功能会通过 Tidal API 生成标准化的分享 URL，接收方可直接在浏览器中打开查看。 ## 用户资料 获取当前登录用户的完整资料： ```bash tidal-cli user profile ``` 该命令返回用户账户信息，包括订阅状态、用户名等个人资料数据。 ## JSON 输出 所有发现与推荐相关的命令都支持 JSON 格式输出，便于脚本处理和程序化调用： ```bash tidal-cli --json recommend tidal-cli --json history tracks tidal-cli --json saved list tidal-cli --json search history ``` ## 数据流向 ```mermaid graph TD A[用户请求] --> B[tidal-cli CLI] B --> C{命令类型} C -->|recommend| D[Tidal API: /recommendations] C -->|history| E[Tidal API: /history] C -->|saved| F[Tidal API: /library] C -->|share| G[Tidal API: /share] C -->|user| H[Tidal API: /user] D --> I[JSON 输出] E --> I F --> I G --> I H --> I ``` ## 典型使用场景 ### 每日音乐探索流程 ```bash # 1. 查看每日推荐混音 tidal-cli recommend --type daily # 2. 获取混音中的曲目 tidal-cli mix items --type daily # 3. 播放感兴趣的曲目 tidal-cli playback play # 4. 查看播放历史 tidal-cli history tracks ``` ### 个人资料管理 ```bash # 查看个人资料 tidal-cli user profile # 查看播放历史 tidal-cli history tracks tidal-cli history albums tidal-cli history artists # 管理已保存内容 tidal-cli saved list ``` ## 隐私说明 根据 tidal-cli 隐私政策，使用 CLI 模式时所有数据直接在你的设备与 Tidal API 服务器之间传输，不经过任何中介服务器。认证令牌存储在本地文件 `~/.tidal-cli/session.json` 中。 如需清除所有本地存储的发现历史和缓存数据，可执行： ```bash rm -rf ~/.tidal-cli --- ## MCP 服务器集成 ### 相关页面 相关主题：[认证与会话管理](#page-7), [Web 端与部署](#page-10)
相关源码文件 以下源码文件用于生成本页说明： - [site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx) - [site/app/mcp-lib/tools.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/mcp-lib/tools.ts) - [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md) - [src/auth.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/auth.ts) - [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)
# MCP 服务器集成 ## 概述 MCP（Model Context Protocol）服务器集成为 tidal-cli 提供了与 AI 助手（特别是 Claude Desktop 和 claude.ai）的无缝集成能力。通过这一集成，用户可以通过自然语言指令与 Tidal 账户进行交互，实现音乐搜索、播放列表管理、资料库操作等功能。 tidal-cli 作为远程 MCP 服务器运行，允许 AI 代理直接调用 Tidal API 的各项功能，无需用户在本地安装任何软件。所有认证令牌存储在 Upstash 托管的加密 Redis 数据库中，确保了安全性和跨设备访问能力。 ## 架构设计 ### 系统组件 | 组件 | 描述 | 位置 | |------|------|------| | MCP 路由端点 | 处理 MCP 协议请求的主入口 | `/api/mcp` | | 授权端点 | OAuth 授权流程处理 | `/api/authorize` | | 回调端点 | OAuth 回调处理 | `/api/callback` | | Token 端点 | Token 刷新与管理 | `/api/token` | | 注册端点 | 用户会话注册 | `/api/register` | | 工具定义 | 40 个可用的 MCP 工具 | `mcp-lib/tools.ts` | | Redis 存储 | 加密的会话数据存储 | `mcp-lib/redis.ts` | ### 认证流程 ```mermaid sequenceDiagram participant User participant Claude participant MCP_Server participant Tidal_API participant Redis User->>Claude: 请求连接 Tidal Claude->>MCP_Server: 通过 /api/mcp 连接 MCP_Server->>User: 重定向到授权页面 User->>Tidal_API: 输入 Tidal 凭据 Tidal_API->>MCP_Server: 返回 OAuth Code MCP_Server->>Tidal_API: 交换 Access Token Tidal_API->>MCP_Server: 返回 Token MCP_Server->>Redis: 加密存储会话 Redis->>MCP_Server: 确认存储 MCP_Server->>Claude: 连接成功 Claude->>User: 显示可用工具 ``` ## MCP 连接配置 ### 连接地址 MCP 服务器通过以下端点对外提供服务： ``` https://tidal-cli.lucaperret.ch/api/mcp ``` 该端点托管在 Vercel 平台上，响应 MCP 协议的标准请求。 ### Claude Desktop 配置 在 Claude Desktop 中配置自定义连接器的步骤如下： 1. 打开 Claude Desktop 设置页面 2. 导航至 **Connectors**（连接器）部分 3. 点击 **Add custom connector**（添加自定义连接器） 4. 输入上述 MCP 端点 URL 5. 点击 **Connect**（连接）并使用 Tidal 账户登录 ## 可用工具 tidal-cli MCP 集成提供了 40 个工具，覆盖以下功能类别： ### 搜索功能 | 工具名称 | 描述 | |---------|------| | `tidal_search_tracks` | 搜索曲目 | | `tidal_search_albums` | 搜索专辑 | | `tidal_search_artists` | 搜索艺术家 | | `tidal_search_playlists` | 搜索播放列表 | | `tidal_search_videos` | 搜索视频 | | `tidal_search_suggest` | 获取搜索建议 | | `tidal_search_history` | 查看搜索历史 | | `tidal_search_history_delete` | 删除单条历史记录 | | `tidal_search_history_clear` | 清空所有历史 | ### 播放列表管理 | 工具名称 | 描述 | |---------|------| | `tidal_playlist_list` | 列出用户播放列表 | | `tidal_playlist_create` | 创建新播放列表 | | `tidal_playlist_add_track` | 添加曲目到播放列表 | | `tidal_playlist_add_album` | 添加专辑到播放列表 | | `tidal_playlist_remove_track` | 从播放列表移除曲目 | | `tidal_playlist_delete` | 删除播放列表 | ### 资料库操作 | 工具名称 | 描述 | |---------|------| | `tidal_library_tracks` | 获取资料库中的曲目 | | `tidal_library_albums` | 获取资料库中的专辑 | | `tidal_library_artists` | 获取资料库中的艺术家 | | `tidal_library_playlists` | 获取资料库中的播放列表 | | `tidal_library_favorite_tracks` | 获取收藏的曲目 | | `tidal_library_favorite_artists` | 收藏艺术家 | | `tidal_library_favorite_albums` | 收藏专辑 | | `tidal_recently_added` | 最近添加的项目 | ### 艺术家相关 | 工具名称 | 描述 | |---------|------| | `tidal_artist_info` | 获取艺术家信息 | | `tidal_artist_tracks` | 获取艺术家的曲目 | | `tidal_artist_albums` | 获取艺术家的专辑 | | `tidal_artist_similar` | 获取相似艺术家 | | `tidal_artist_radio` | 获取艺术家电台 | ### 专辑相关 | 工具名称 | 描述 | |---------|------| | `tidal_album_info` | 获取专辑详细信息 | | `tidal_album_by_barcode` | 通过条形码查找专辑 | ### 曲目相关 | 工具名称 | 描述 | |---------|------| | `tidal_track_info` | 获取曲目信息 | | `tidal_track_similar` | 获取相似曲目 | | `tidal_track_radio` | 获取曲目电台 | ### 播放控制 | 工具名称 | 描述 | |---------|------| | `tidal_playback_play` | 播放指定曲目 | | `tidal_playback_info` | 获取播放信息 | | `tidal_playback_url` | 获取播放 URL | ### 推荐与历史 | 工具名称 | 描述 | |---------|------| | `tidal_recommend` | 获取推荐内容 | | `tidal_mix_items` | 获取混合播放列表内容 | | `tidal_history_tracks` | 播放历史（曲目） | | `tidal_history_albums` | 播放历史（专辑） | | `tidal_history_artists` | 播放历史（艺术家） | ### 其他功能 | 工具名称 | 描述 | |---------|------| | `tidal_user_profile` | 获取用户资料 | | `tidal_share_track` | 创建曲目分享链接 | | `tidal_share_album` | 创建专辑分享链接 | | `tidal_saved_list` | 列出稍后保存的项目 | | `tidal_saved_add` | 添加到保存列表 | | `tidal_saved_remove` | 从保存列表移除 | ## 工具定义规范 每个 MCP 工具都遵循统一的定义规范，包含以下元数据： ```typescript server.tool( 'tool_name', // 工具标识符 'Tool description', // 工具描述 { /* 参数 Schema */ }, // Zod 参数验证 { readOnlyHint: boolean, // 是否只读操作 destructiveHint: boolean, // 是否为破坏性操作 openWorldHint: boolean, // 是否涉及外部网络 title: string // 人类可读标题 }, async (params, extra) => { // 工具实现 } ); ``` ### 工具提示语义 | 提示 | 含义 | 示例 | |------|------|------| | `readOnlyHint: true` | 只读操作，不修改数据 | 搜索、查看信息 | | `destructiveHint: false` | 非破坏性操作 | 播放、添加 | | `openWorldHint: true` | 涉及外部 API 调用 | 所有 Tidal API 调用 | ## 认证与令牌管理 ### OAuth 认证流程 MCP 服务器使用标准的 OAuth 2.0 流程进行身份验证： 1. **授权请求**：用户发起连接请求后，被重定向至 Tidal 登录页面 2. **用户授权**：用户在 Tidal 页面输入凭据并授权 tidal-cli 访问 3. **回调处理**：Tidal 通过回调 URL 返回授权码 4. **令牌交换**：服务器将授权码交换为访问令牌和刷新令牌 5. **会话存储**：加密后的令牌存储至 Upstash Redis ### 令牌存储 CLI 模式下，令牌存储在本地：`~/.tidal-cli/session.json` MCP 模式下，令牌存储在服务器端加密的 Redis 数据库中，由 Upstash（Vercel 生态）托管。 ## 使用示例 ### 自然语言交互 用户可以通过以下方式与 Tidal 交互： | 用户请求 | AI 执行的操作 | |---------|--------------| | 创建包含 Daft Punk Discovery 专辑最佳曲目的播放列表 | 搜索曲目、创建播放列表、添加曲目 | | 查找与 Massive Attack 相似的艺术家并添加其热门曲目到资料库 | 发现相似艺术家、添加收藏 | | 列出我的播放列表，将 LCD Soundsystem 新专辑添加到第一个 | 列出播放列表、搜索专辑、添加曲目 | | 播放 Boards of Canada 的歌曲 | 搜索艺术家、选择曲目、播放 | ### 质量参数 播放功能支持指定音质： ```bash tidal-cli playback play --quality LOSSLESS ``` 可用质量选项：`LOW`、`HIGH`、`LOSSLESS`、`HI_RES` ## 隐私与安全 ### 数据存储 根据隐私政策，MCP 集成遵循以下数据处理原则： - tidal-cli 不向开发者服务器收集或传输任何个人数据 - 认证令牌加密存储在 Upstash Redis 中 - 所有 Tidal API 通信直接通过用户设备与 Tidal 服务器进行 ### 数据删除 用户可通过以下方式删除所有存储的数据： 1. 在 Tidal 账户设置中撤销 tidal-cli 的访问权限 2. 删除本地会话文件（CLI 模式）：`rm -rf ~/.tidal-cli` ## Smithery 集成 除 Claude Desktop 外，tidal-cli MCP 服务器还可在 Smithery 平台获取： ``` https://smithery.ai/servers/lucaperret/tidal ``` ## 相关资源 - 官方文档：[github.com/lucaperret/tidal-cli](https://github.com/lucaperret/tidal-cli) - 隐私政策：[tidal-cli.lucaperret.ch/privacy](https://tidal-cli.lucaperret.ch/privacy) - 服务条款：[tidal-cli.lucaperret.ch/terms](https://tidal-cli.lucaperret.ch/terms) --- ## Web 端与部署 ### 相关页面 相关主题：[系统架构](#page-2), [MCP 服务器集成](#page-9)
相关源码文件 以下源码文件用于生成本页说明： - [site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx) - [site/app/terms/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/terms/page.tsx) - [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx) - [site/app/og-banner/route.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/og-banner/route.tsx) - [site/app/banner/route.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/banner/route.tsx) - [site/app/components/Nav.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/components/Nav.tsx) - [site/app/components/Terminal.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/components/Terminal.tsx)
# Web 端与部署 ## 概述 tidal-cli 项目不仅包含核心的命令行工具，还维护了一个完整的 Web 前端站点（位于 `site/` 目录）。该站点主要用于： - 展示项目功能和使用说明 - 提供 MCP（Model Context Protocol）服务器端点，供 AI 代理（如 Claude）远程调用 Tidal API - 生成社交分享用的 OG（Open Graph）图片和横幅 站点采用 [Next.js](https://nextjs.org/) 框架构建，部署在 **Vercel** 平台，并集成了 **Upstash Redis** 用于 MCP 模式下的认证令牌存储。 ## 技术架构 ### 技术栈 | 层级 | 技术 | 说明 | |------|------|------| | 框架 | Next.js | 基于 React 的全栈框架，支持 App Router | | 语言 | TypeScript | 类型安全的 JavaScript 超集 | | 样式 | Tailwind CSS | 原子化 CSS 框架 | | 动画 | Framer Motion | React 动画库 | | 数据库 | Upstash Redis | MCP 服务器端认证令牌存储 | | 部署 | Vercel | 边缘部署平台 | ### 目录结构 ``` site/ ├── app/ │ ├── components/ # React 组件 │ │ ├── Nav.tsx # 顶部导航栏 │ │ └── Terminal.tsx # 终端模拟展示组件 │ ├── api/ # API 路由 │ │ └── mcp/ # MCP 服务器端点 │ ├── terms/ # 服务条款页面 │ ├── privacy/ # 隐私政策页面 │ ├── og-banner/ # OG 图片生成路由 │ ├── banner/ # 横幅生成路由 │ └── page.tsx # 首页 ├── package.json └── vercel.json ``` ## 核心组件 ### 导航组件 `site/app/components/Nav.tsx` 提供了站点的顶部导航栏功能： - 左侧显示 tidal-cli Logo - 右侧提供 GitHub 链接入口 - 响应式设计，在移动端隐藏部分链接 ```tsx // Nav.tsx 核心结构 ``` 资料来源：[site/app/components/Nav.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/components/Nav.tsx) ### 终端展示组件 `site/app/components/Terminal.tsx` 是一个用于模拟命令行终端界面的 React 组件，支持动画效果和命令展示： | 属性 | 类型 | 说明 | |------|------|------| | title | string | 终端窗口标题 | | lines | Line[] | 命令行内容数组 | | compact | boolean | 是否启用紧凑模式 | ```tsx interface Line { prompt?: boolean; // 是否显示 $ 提示符 text: string; // 命令文本 dim?: boolean; // 是否显示为灰色（注释） } ``` 组件使用 Framer Motion 实现逐行动画效果，每行动画延迟 80ms： ```tsx {line.prompt && $ } {line.text} ``` 资料来源：[site/app/components/Terminal.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/components/Terminal.tsx) ## 首页结构 `site/app/page.tsx` 是站点的首页，包含以下主要区域： ### 功能展示区 展示 tidal-cli 的核心命令功能，包括搜索、艺术家信息、播放列表、播放控制、媒体库管理等。 | 功能模块 | 命令示例 | |----------|----------| | 搜索 | `search track "Around the World"` | | 艺术家 | `artist info `, `artist albums ` | | 发现 | `artist similar `, `recommend` | | 播放列表 | `playlist list`, `playlist create --name "Chill"` | | 播放控制 | `playback play `, `playback url ` | | 媒体库 | `library add --track-id ...`, `history tracks` | 资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx) ### 安装区域 提供 npm 安装命令和 OAuth 认证流程说明： ```bash npm install -g @lucaperret/tidal-cli tidal-cli auth ``` 资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx) ### MCP 集成区域 说明如何将 tidal-cli 作为远程 MCP 服务器连接到 Claude Desktop： 1. 在 Claude 设置中添加自定义连接器 2. 输入 MCP 端点 URL：`https://tidal-cli.lucaperret.ch/api/mcp` 资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx) ### AI 代理示例区域 展示用户可以通过自然语言让 AI 代理执行复杂的 Tidal 操作： | 示例提示 | 执行操作 | |----------|----------| | 创建 Discovery 专辑的最佳曲目播放列表 | 搜索、创建播放列表、添加曲目 | | 添加类似 Massive Attack 的艺术家到我的媒体库 | 发现相似艺术家、添加到收藏 | | 播放 Boards of Canada 的音乐 | 搜索、选择曲目、播放 | ## MCP 服务器端点 MCP 服务器通过 API 路由 `/api/mcp` 提供服务，允许 AI 代理远程调用 tidal-cli 功能。 ### 认证机制 根据隐私政策，MCP 模式下的认证令牌存储在服务器端： > 当使用 tidal-cli 作为 MCP 连接器时（例如通过 Claude Desktop 或 claude.ai），认证令牌存储在 Upstash（通过 Vercel）托管的加密 Redis 数据库中。 资料来源：[site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx) ### 数据流向 ```mermaid graph TD A[Claude Desktop] -->|MCP Protocol| B[tidal-cli.lucaperret.ch/api/mcp] B --> C[Upstash Redis] C -->|Session Tokens| B B -->|Tidal API| D[openapi.tidal.com] B -->|OAuth| E[login.tidal.com / auth.tidal.com] ``` ## OG 图片与横幅生成 ### OG Banner 路由 `site/app/og-banner/route.tsx` 和 `site/app/banner/route.tsx` 提供了动态生成 Open Graph 图片的功能。 这些路由使用 Next.js 的 Image Response API 生成 SVG 格式的横幅图片： ```tsx new ImageResponse( (
tidal-cli
), { width: 1280, height: 240 } ); ``` 生成内容包括： - tidal-cli 标题文字 - 功能标签（Search、Playlists、Playback、Discovery） - AI Agent Ready 标识 资料来源：[site/app/og-banner/route.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/og-banner/route.tsx) ## 隐私与合规 ### 数据收集策略 | 使用模式 | 数据存储位置 | 说明 | |----------|--------------|------| | CLI 模式 | 本地 `~/.tidal-cli/session.json` | 直接与 Tidal API 通信，无中间服务器 | | MCP 模式 | Upstash Redis | 服务器端加密存储认证令牌 | 资料来源：[site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx) ### 外部服务依赖 | 服务 | 用途 | 隐私政策 | |------|------|----------| | Tidal API | 访问音乐库、播放列表和目录 | Tidal 隐私政策 | | Tidal Auth | OAuth 身份验证 | Tidal 隐私政策 | | Upstash | MCP 模式认证令牌存储 | Upstash 隐私政策 | 资料来源：[site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx) ### 数据删除 用户可通过以下方式删除所有本地存储数据： ```bash rm -rf ~/.tidal-cli ``` 资料来源：[site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx) ## 服务条款 `site/app/terms/page.tsx` 明确了使用条款： ### 用户责任 - 遵守 Tidal 的服务条款 - 对账户所有操作负责 ### 可接受使用 用户同意不： - 将 tidal-cli 用于任何非法目的 - 尝试绕过 Tidal 的访问控制或 DRM - 使用服务下载或重新分发受版权保护的内容 - 进行超出正常使用的过度或自动请求 ### 免责声明 tidal-cli 按"原样"提供，不提供任何明示或暗示的保证。维护者不保证不间断或无错误的运行。Tidal 可能随时更改其 API，这可能影响功能。 资料来源：[site/app/terms/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/terms/page.tsx) ## 部署流程 ### Vercel 部署 站点部署在 Vercel 平台，利用边缘函数提供低延迟的 MCP 服务。 ### 部署检查清单 1. 确保 `site/` 目录包含所有必要的配置文件 2. 配置环境变量（如有） 3. 通过 GitHub 集成连接到 Vercel 4. 启用自动部署 ## 相关链接 | 资源 | URL | |------|-----| | 官方网站 | https://tidal-cli.lucaperret.ch | | MCP 端点 | https://tidal-cli.lucaperret.ch/api/mcp | | GitHub 仓库 | https://github.com/lucaperret/tidal-cli | | Smithery 集成 | https://smithery.ai/servers/lucaperret/tidal | | ClawHub 集成 | https://clawhub.ai/lucaperret/tidal-cli | --- --- ## Doramagic 踩坑日志 项目：lucaperret/tidal-cli 摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。 ## 1. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。 - 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。 - 证据：capability.host_targets | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | host_targets=mcp_host, claude ## 2. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 建议检查：将假设转成下游验证清单。 - 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。 - 证据：capability.assumptions | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | README/documentation is current enough for a first validation pass. ## 3. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。 - 防护动作：维护活跃度未知时，推荐强度不能标为高信任。 - 证据：evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | last_activity_observed missing ## 4. 安全/权限坑 · 下游验证发现风险项 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：下游已经要求复核，不能在页面中弱化。 - 建议检查：进入安全/权限治理复核队列。 - 防护动作：下游风险存在时必须保持 review/recommendation 降级。 - 证据：downstream_validation.risk_items | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | no_demo; severity=medium ## 5. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 建议检查：把风险写入边界卡，并确认是否需要人工复核。 - 防护动作：评分风险必须进入边界卡，不能只作为内部分数。 - 证据：risks.scoring_risks | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | no_demo; severity=medium ## 6. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 建议检查：抽样最近 issue/PR，判断是否长期无人处理。 - 防护动作：issue/PR 响应未知时，必须提示维护风险。 - 证据：evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | issue_or_pr_quality=unknown ## 7. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 建议检查：确认最近 release/tag 和 README 安装命令是否一致。 - 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。 - 证据：evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | release_recency=unknown