{
"canonical_name": "lucaperret/tidal-cli",
"compilation_id": "pack_962af3c8af2247deb09b48cd1e652a43",
"created_at": "2026-05-15T05:09:37.753815+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `npm install -g @lucaperret/tidal-cli` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "npm install -g @lucaperret/tidal-cli",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_a016e44b36754805b88be903f4409b31"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_4a5ad214e747d2fa707cd8d0383b6cac",
"canonical_name": "lucaperret/tidal-cli",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/lucaperret/tidal-cli",
"slug": "tidal-cli",
"source_packet_id": "phit_2aa07bb71656456c80ea55ebfb6a9339",
"source_validation_id": "dval_96e5a3a8426245738a3d6af1675d094b"
},
"merchandising": {
"best_for": "需要工具连接与集成能力，并使用 mcp_host的用户",
"github_forks": 1,
"github_stars": 3,
"one_liner_en": "Control Tidal from your terminal — search, playlists, playback, library, and recommendations via the Tidal API v2. Ships as a CLI, a remote MCP server for Claude Desktop/Smithery, and an OpenClaw skill. Built for scripting, LLM agent automation, and AI workflows. TypeScript, MIT.",
"one_liner_zh": "Control Tidal from your terminal — search, playlists, playback, library, and recommendations via the Tidal API v2. Ships as a CLI, a remote MCP server for Claude Desktop/Smithery, and an OpenClaw skill. Built for scripting, LLM agent automation, and AI workflows. TypeScript, MIT.",
"primary_category": {
"category_id": "tool-integrations",
"confidence": "high",
"name_en": "Tool Integrations",
"name_zh": "工具连接与集成",
"reason": "matched_keywords:mcp, api, server"
},
"target_user": "使用 mcp_host, claude 等宿主 AI 的用户",
"title_en": "tidal-cli",
"title_zh": "tidal-cli 能力包",
"visible_tags": [
{
"label_en": "Browser Agents",
"label_zh": "浏览器 Agent",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-browser-agents",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Browser Automation",
"label_zh": "浏览器自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-browser-automation",
"type": "core_capability"
},
{
"label_en": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Local-first",
"label_zh": "本地优先",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-local-first",
"type": "selection_signal"
}
]
},
"packet_id": "phit_2aa07bb71656456c80ea55ebfb6a9339",
"page_model": {
"artifacts": {
"artifact_slug": "tidal-cli",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "npm install -g @lucaperret/tidal-cli",
"label": "Node.js / npm · 官方安装入口",
"source": "https://github.com/lucaperret/tidal-cli#readme",
"verified": true
}
],
"display_tags": [
"浏览器 Agent",
"网页任务自动化",
"浏览器自动化",
"节点式流程编排",
"本地优先"
],
"eyebrow": "工具连接与集成",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要工具连接与集成能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Control Tidal from your terminal — search, playlists, playback, library, and recommendations via the Tidal API v2. Ships as a CLI, a remote MCP server for Claude Desktop/Smithery, and an OpenClaw skill. Built for scripting, LLM agent automation, and AI workflows. TypeScript, MIT."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host, claude",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。",
"category": "配置坑",
"evidence": [
"capability.host_targets | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | host_targets=mcp_host, claude"
],
"severity": "medium",
"suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。",
"title": "可能修改宿主 AI 配置",
"user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 1,
"forks": 1,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 3
},
"source_url": "https://github.com/lucaperret/tidal-cli",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Control Tidal from your terminal — search, playlists, playback, library, and recommendations via the Tidal API v2. Ships as a CLI, a remote MCP server for Claude Desktop/Smithery, and an OpenClaw skill. Built for scripting, LLM agent automation, and AI workflows. TypeScript, MIT.",
"title": "tidal-cli 能力包",
"trial_prompt": "# tidal-cli - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 tidal-cli 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client / claude\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-1：项目简介与安装。围绕“项目简介与安装”模拟一次用户任务，不展示安装或运行结果。\n2. page-2：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. page-3：搜索与浏览功能。围绕“搜索与浏览功能”模拟一次用户任务，不展示安装或运行结果。\n4. page-4：播放列表管理。围绕“播放列表管理”模拟一次用户任务，不展示安装或运行结果。\n5. page-5：媒体库管理。围绕“媒体库管理”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-1\n输入：用户提供的“项目简介与安装”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-2\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-3\n输入：用户提供的“搜索与浏览功能”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-4\n输入：用户提供的“播放列表管理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-5\n输入：用户提供的“媒体库管理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-1：Step 1 必须围绕“项目简介与安装”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-2：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-3：Step 3 必须围绕“搜索与浏览功能”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-4：Step 4 必须围绕“播放列表管理”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-5：Step 5 必须围绕“媒体库管理”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/lucaperret/tidal-cli\n- https://github.com/lucaperret/tidal-cli#readme\n- skills/tidal-cli/SKILL.md\n- README.md\n- package.json\n- CLAUDE.md\n- src/index.ts\n- src/auth.ts\n- site/app/layout.tsx\n- src/search.ts\n- src/artist.ts\n- src/album.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 tidal-cli 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "当前没有项目级社区来源；不会把未抓取讨论包装成社会证明。",
"items": [],
"status": "待发现 Agent 补证",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "工具连接与集成",
"desc": "Control Tidal from your terminal — search, playlists, playback, library, and recommendations via the Tidal API v2. Ships as a CLI, a remote MCP server for Claude Desktop/Smithery, and an OpenClaw skill. Built for scripting, LLM agent automation, and AI workflows. TypeScript, MIT.",
"effort": "安装已验证",
"forks": 1,
"icon": "link",
"name": "tidal-cli 能力包",
"risk": "需复核",
"slug": "tidal-cli",
"stars": 3,
"tags": [
"浏览器 Agent",
"网页任务自动化",
"浏览器自动化",
"节点式流程编排",
"本地优先"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/lucaperret/tidal-cli 项目说明书\n\n生成时间：2026-05-13 13:31:09 UTC\n\n## 目录\n\n- [项目简介与安装](#page-1)\n- [系统架构](#page-2)\n- [搜索与浏览功能](#page-3)\n- [播放列表管理](#page-4)\n- [媒体库管理](#page-5)\n- [播放系统与质量设置](#page-6)\n- [认证与会话管理](#page-7)\n- [发现与推荐系统](#page-8)\n- [MCP 服务器集成](#page-9)\n- [Web 端与部署](#page-10)\n\n\n\n## 项目简介与安装\n\n### 相关页面\n\n相关主题：[系统架构](#page-2), [认证与会话管理](#page-7)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n- [site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n- [site/app/terms/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/terms/page.tsx)\n- [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n- [site/app/components/Terminal.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/components/Terminal.tsx)\n \n\n# 项目简介与安装\n\n## 概述\n\ntidal-cli 是一个开源的命令行工具，允许用户通过终端与 Tidal 音乐流媒体服务进行交互。该工具由 Node.js 构建，支持搜索、播放列表管理、音乐库控制等功能，专为个人使用和 LLM 代理自动化设计。\n\n**核心特点：**\n\n- 支持搜索艺术家、专辑、曲目、视频和播放列表\n- 完整的播放列表管理功能\n- 音乐播放控制\n- 发现和推荐功能\n- JSON 输出支持，便于脚本和自动化\n- MCP Server 集成，可与 Claude Desktop 等 AI 代理配合使用\n\n资料来源：[site/app/terms/page.tsx:28-31]()\n\n---\n\n## 系统要求\n\n| 要求项 | 最低版本 | 说明 |\n|--------|----------|------|\n| Node.js | >= 20 | 必须安装 Node.js 运行环境 |\n| Tidal 账户 | 必需 | 需要有效的 Tidal 账户进行认证 |\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n---\n\n## 安装流程\n\n### 全局安装\n\n通过 npm 进行全局安装：\n\n```bash\nnpm install -g @lucaperret/tidal-cli\n```\n\n资料来源：[site/app/page.tsx:72-76]()\n\n### 认证配置\n\n安装完成后，需要进行一次性认证：\n\n```bash\ntidal-cli auth\n```\n\n该命令会打开浏览器进行 Tidal 授权，认证成功后用户 ID 将显示在终端中。\n\n认证完成后，所有后续操作无需交互式操作，工具会自动处理 token 刷新。\n\n资料来源：[site/app/page.tsx:72-76]()\n\n---\n\n## 项目架构\n\n### 组件架构\n\n```mermaid\ngraph TD\n A[用户终端] --> B[tidal-cli CLI]\n B --> C[本地会话存储
~/.tidal-cli/session.json]\n B --> D[Tidal API
openapi.tidal.com]\n D --> E[Tidal 服务]\n \n F[AI Agent
Claude Desktop] --> G[MCP Server
tidal-cli.lucaperret.ch/api/mcp]\n G --> H[Redis 加密存储
Upstash]\n G --> D\n \n style A fill:#e1f5fe\n style E fill:#f3e5f5\n style G fill:#fff3e0\n```\n\n### 数据流向\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant CLI as tidal-cli\n participant Tidal as Tidal API\n participant Session as 本地会话\n\n User->>CLI: tidal-cli auth\n CLI->>Tidal: OAuth 授权请求\n Tidal->>User: 浏览器授权页面\n User->>Tidal: 确认授权\n Tidal->>CLI: 返回 Access Token\n CLI->>Session: 存储会话信息\n Session-->>CLI: 确认存储\n CLI-->>User: 认证成功\n\n User->>CLI: tidal-cli search track \"xxx\"\n CLI->>Session: 读取 Token\n CLI->>Tidal: API 请求\n Tidal-->>CLI: 搜索结果\n CLI-->>User: 显示结果\n```\n\n资料来源：[site/app/privacy/page.tsx:48-54]()\n\n---\n\n## 核心功能模块\n\n| 模块 | 功能描述 | 示例命令 |\n|------|----------|----------|\n| **搜索** | 搜索艺术家、专辑、曲目、视频、播放列表 | `tidal-cli search track \"Teardrop\"` |\n| **艺术家** | 获取艺术家信息、专辑、相似艺术家 | `tidal-cli artist info ` |\n| **专辑** | 专辑详情、条形码查询 | `tidal-cli album info ` |\n| **曲目** | 曲目详情、相似曲目、ISRC 查询 | `tidal-cli track info ` |\n| **播放列表** | 列表、创建、添加曲目/专辑 | `tidal-cli playlist list` |\n| **播放** | 播放控制、音质选择 | `tidal-cli playback play ` |\n| **发现** | 推荐、混音、播放历史 | `tidal-cli recommend` |\n| **保存** | 稍后保存、分享链接 | `tidal-cli saved list` |\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n---\n\n## JSON 输出模式\n\n所有命令支持 JSON 输出格式，便于脚本处理和自动化流程：\n\n```bash\n# 搜索结果 JSON 输出\ntidal-cli --json search track \"Around the World\"\n\n# 播放列表 JSON 输出\ntidal-cli --json playlist list\n\n# 艺术家信息 JSON 输出\ntidal-cli --json artist similar 8992\n```\n\nJSON 输出模式的特点：\n\n- 每个命令都支持 `--json` 参数\n- 结构化数据便于程序解析\n- 适合 LLM 代理和自动化脚本使用\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n---\n\n## MCP Server 集成\n\ntidal-cli 可作为远程 MCP 服务器与 AI 代理集成：\n\n### 集成地址\n\n```\nhttps://tidal-cli.lucaperret.ch/api/mcp\n```\n\n### Claude Desktop 配置\n\n1. 打开 Settings → Connectors → Add custom connector\n2. 添加上述 MCP 服务器地址\n3. 连接后即可通过自然语言控制 Tidal\n\n```mermaid\ngraph LR\n A[Claude Desktop] -->|MCP 协议| B[tidal-cli MCP Server]\n B --> C[Tidal API]\n C --> D[Tidal 服务]\n \n B -->|加密存储| E[Upstash Redis]\n \n style A fill:#e1f5fe\n style E fill:#fff3e0\n```\n\n资料来源：[site/app/page.tsx:38-48]()\n\n---\n\n## 隐私与数据存储\n\n### CLI 模式\n\n在命令行模式下，tidal-cli 直接与 Tidal API 服务器通信：\n\n- **认证令牌存储位置**：`~/.tidal-cli/session.json`\n- **数据流向**：设备 → Tidal API（无中间服务器）\n- **数据收集**：不收集、存储或传输任何个人数据\n\n资料来源：[site/app/privacy/page.tsx:48-54]()\n\n### MCP Server 模式\n\n当作为 MCP 连接器使用时：\n\n- 认证令牌存储在 Upstash 托管的加密 Redis 数据库中\n- 数据存储在 Vercel 平台上\n\n资料来源：[site/app/privacy/page.tsx:55-58]()\n\n---\n\n## 快速入门命令\n\n```bash\n# 安装 tidal-cli\nnpm install -g @lucaperret/tidal-cli\n\n# 认证\ntidal-cli auth\n\n# 搜索曲目\ntidal-cli search track \"Around the World\"\n\n# 获取艺术家详情\ntidal-cli artist info 8992\n\n# 播放曲目\ntidal-cli playback play 5756235\n\n# 列出播放列表\ntidal-cli playlist list\n\n# 获取推荐\ntidal-cli recommend\n\n# 查看播放历史\ntidal-cli history tracks\n```\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n---\n\n## 许可与开源\n\ntidal-cli 采用 MIT 许可证开源，源代码托管在 GitHub 上：\n\n- **开源仓库**：[github.com/lucaperret/tidal-cli](https://github.com/lucaperret/tidal-cli)\n- **许可证**：MIT License\n- **项目维护者**：Luca Perret\n\n该项目为独立开发工具，与 Tidal 无附属关系。\n\n资料来源：[site/app/terms/page.tsx:80-97]()\n\n---\n\n## 相关链接\n\n| 资源 | 链接 |\n|------|------|\n| GitHub 仓库 | https://github.com/lucaperret/tidal-cli |\n| 官方网站 | https://tidal-cli.lucaperret.ch |\n| Smithery 集成 | https://smithery.ai/servers/lucaperret/tidal |\n| ClawHub | https://clawhub.ai/lucaperret/tidal-cli |\n| Tidal 服务 | https://tidal.com |\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目简介与安装](#page-1), [认证与会话管理](#page-7), [MCP 服务器集成](#page-9)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n- [site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n- [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n- [site/app/terms/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/terms/page.tsx)\n- [site/app/components/Terminal.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/components/Terminal.tsx)\n \n\n# 系统架构\n\ntidal-cli 是一个开源的命令行工具，用于与 Tidal 音乐流媒体服务进行交互。该项目采用模块化架构设计，同时支持命令行直接使用和 MCP（Model Context Protocol）服务器模式集成到 AI 助手（如 Claude）中。\n\n## 1. 整体架构概览\n\ntidal-cli 项目包含三个主要组件：\n\n| 组件 | 说明 | 部署位置 |\n|------|------|----------|\n| CLI 工具 | 命令行界面，直接与用户交互 | 用户本地设备 |\n| MCP 服务器 | 远程 MCP 连接器，供 AI 代理调用 | Vercel 服务端点 |\n| Web 前端 | 文档和 Landing Page | Vercel/Site |\n\n资料来源：[site/app/page.tsx:1-50]()\n\n```mermaid\ngraph TB\n subgraph 用户端\n CLI[tidal-cli CLI]\n end\n \n subgraph 云端服务\n MCP[MCP Server
tidal-cli.lucaperret.ch/api/mcp]\n Web[Web Frontend
tidal-cli.lucaperret.ch]\n end\n \n subgraph 第三方服务\n TidalAPI[Tidal API
openapi.tidal.com]\n TidalAuth[Tidal Auth
login.tidal.com
auth.tidal.com]\n Upstash[Upstash Redis
Token 存储]\n end\n \n CLI --> TidalAPI\n CLI --> TidalAuth\n MCP --> TidalAPI\n MCP --> TidalAuth\n MCP --> Upstash\n Web --> MCP\n```\n\n## 2. CLI 工具架构\n\n### 2.1 安装与入口\n\nCLI 工具通过 npm 全局安装：\n\n```bash\nnpm install -g @lucaperret/tidal-cli\n```\n\n安装后可通过 `tidal-cli` 命令调用，支持全局参数 `--json` 输出 JSON 格式结果。\n\n资料来源：[README.md:1-30]()\n\n### 2.2 命令模块\n\nCLI 工具按功能划分为以下命令模块：\n\n| 命令模块 | 功能描述 | 示例命令 |\n|----------|----------|----------|\n| `search` | 搜索艺术家、专辑、曲目、视频、播放列表 | `tidal-cli search track \"Teardrop\"` |\n| `artist` | 获取艺术家信息和相关资源 | `tidal-cli artist info ` |\n| `album` | 专辑信息和条形码查询 | `tidal-cli album info ` |\n| `track` | 曲目详情和相似推荐 | `tidal-cli track info ` |\n| `playlist` | 播放列表管理 | `tidal-cli playlist list` |\n| `playback` | 播放控制 | `tidal-cli playback play ` |\n| `library` | 个人音乐库管理 | `tidal-cli library favorite-tracks` |\n| `history` | 播放历史和搜索历史 | `tidal-cli history tracks` |\n| `saved` | 稍后播放列表管理 | `tidal-cli saved list` |\n| `recommend` | 音乐推荐和混音 | `tidal-cli recommend` |\n| `share` | 创建分享链接 | `tidal-cli share track ` |\n\n资料来源：[README.md:50-120]()\n\n## 3. MCP 服务器架构\n\n### 3.1 连接配置\n\nMCP 服务器作为远程连接器运行于 `https://tidal-cli.lucaperret.ch/api/mcp`，可与 Claude Desktop 或 claude.ai 集成。\n\n资料来源：[site/app/page.tsx:15-25]()\n\n```mermaid\ngraph LR\n A[Claude Desktop
或 claude.ai] -->|MCP Protocol| B[MCP Connector]\n B --> C[Tidal API]\n B --> D[Upstash Redis
Token 存储]\n```\n\n### 3.2 可用工具\n\nMCP 服务器提供约 40 个工具，涵盖以下功能类别：\n\n- 搜索（Search）\n- 播放列表管理（Playlists）\n- 音乐库访问（Library）\n- 推荐服务（Recommendations）\n- 稍后播放（Save-for-later）\n- 分享功能（Sharing）\n\n资料来源：[site/app/page.tsx:45-55]()\n\n### 3.3 认证流程\n\nMCP 服务器模式下的认证流程：\n\n1. 用户通过 OAuth 连接 Tidal 账户\n2. 认证令牌存储于 Upstash Redis 数据库（加密存储）\n3. MCP 服务器使用存储的令牌访问 Tidal API\n\n资料来源：[site/app/privacy/page.tsx:60-80]()\n\n## 4. Web 前端架构\n\n### 4.1 技术栈\n\nWeb 前端基于 Next.js 构建，包含以下页面：\n\n| 页面路径 | 功能 |\n|----------|------|\n| `/` | Landing Page，包含安装说明和功能展示 |\n| `/privacy` | 隐私政策页面 |\n| `/terms` | 服务条款页面 |\n| `/api/mcp` | MCP 服务器端点 |\n\n资料来源：[site/app/page.tsx:1-30]()\n资料来源：[site/app/privacy/page.tsx:1-30]()\n资料来源：[site/app/terms/page.tsx:1-30]()\n\n### 4.2 组件结构\n\n```mermaid\ngraph TD\n Layout[layout.tsx
根布局] --> Nav[Nav.tsx
导航栏]\n Layout --> Page[page.tsx
主页内容]\n Page --> Terminal[Terminal.tsx
终端模拟组件]\n Page --> Footer[页脚]\n```\n\nWeb 前端主要使用 Framer Motion 实现动画效果，采用 Tidal 品牌配色方案。\n\n资料来源：[site/app/components/Terminal.tsx:1-30]()\n资料来源：[site/app/components/Nav.tsx:1-20]()\n\n## 5. 认证与数据存储\n\n### 5.1 CLI 模式下的数据存储\n\n在命令行模式下使用时，认证令牌存储在用户本地：\n\n```\n~/.tidal-cli/session.json\n```\n\n资料来源：[site/app/privacy/page.tsx:45-55]()\n\n### 5.2 MCP 模式下的数据存储\n\n| 存储类型 | 位置 | 说明 |\n|----------|------|------|\n| 认证令牌 | Upstash Redis（Vercel） | 加密存储 |\n| 传输协议 | 直接与 Tidal API 通信 | 不经过中间服务器 |\n\n资料来源：[site/app/privacy/page.tsx:65-75]()\n\n### 5.3 OAuth 流程\n\ntidal-cli 使用 OAuth 2.0 与 Tidal 进行认证集权，支持以下端点：\n\n| 用途 | 端点 |\n|------|------|\n| 用户登录 | `login.tidal.com` |\n| OAuth 授权 | `auth.tidal.com` |\n| 音乐 API | `openapi.tidal.com` |\n\n资料来源：[site/app/privacy/page.tsx:85-100]()\n\n## 6. 数据流\n\n### 6.1 CLI 命令执行流程\n\n```mermaid\nsequenceDiagram\n participant User\n participant CLI\n participant TidalAuth\n participant TidalAPI\n \n User->>CLI: tidal-cli search track \"Teardrop\"\n CLI->>TidalAuth: 验证本地 token\n alt Token 有效\n CLI->>TidalAPI: 搜索请求\n TidalAPI-->>CLI: 搜索结果\n CLI-->>User: 显示结果\n else Token 无效或过期\n CLI->>TidalAuth: 发起 OAuth 流程\n TidalAuth-->>User: 浏览器授权\n User->>TidalAuth: 确认授权\n TidalAuth-->>CLI: 新 token\n CLI->>TidalAPI: 搜索请求\n TidalAPI-->>CLI: 搜索结果\n CLI-->>User: 显示结果\n end\n```\n\n### 6.2 MCP 集成流程\n\n```mermaid\nsequenceDiagram\n participant User\n participant Claude\n participant MCP\n participant Redis\n participant TidalAPI\n \n User->>Claude: 请求查询音乐\n Claude->>MCP: 调用搜索工具\n MCP->>Redis: 获取认证令牌\n Redis-->>MCP: Token\n MCP->>TidalAPI: API 请求\n TidalAPI-->>MCP: 音乐数据\n MCP-->>Claude: 工具响应\n Claude-->>User: 自然语言回复\n```\n\n## 7. 服务部署\n\n### 7.1 部署平台\n\n| 组件 | 托管平台 |\n|------|----------|\n| Web 前端 | Vercel |\n| MCP 服务器 | Vercel Serverless Functions |\n| Token 存储 | Upstash Redis |\n\n### 7.2 可用集成平台\n\ntidal-cli MCP 连接器可在多个平台使用：\n\n- Claude Desktop / claude.ai（主要）\n- Smithery AI\n- ClawHub\n\n资料来源：[site/app/page.tsx:35-45]()\n\n## 8. 安全与隐私\n\n### 8.1 数据收集政策\n\ntidal-cli 本身不收集、存储或传输任何个人数据到第三方服务器。所有用户数据均直接与 Tidal 服务器交互。\n\n资料来源：[site/app/privacy/page.tsx:35-45]()\n\n### 8.2 数据删除\n\n| 使用模式 | 删除方式 |\n|----------|----------|\n| CLI 模式 | `rm -rf ~/.tidal-cli` |\n| MCP 模式 | 通过 Tidal 账户设置撤销访问权限 |\n\n资料来源：[site/app/privacy/page.tsx:130-145]()\n\n## 9. 开源许可\n\ntidal-cli 采用 MIT 许可证开源，源代码托管于 GitHub：\n\n- 仓库地址：`github.com/lucaperret/tidal-cli`\n- 许可证：`MIT License`\n\n资料来源：[site/app/terms/page.tsx:110-130]()\n\n## 10. 系统要求\n\n| 要求 | 版本 |\n|------|------|\n| Node.js | >= 20 |\n| Tidal 账户 | 需要 |\n\n资料来源：[README.md:25-30]()\n\n---\n\n\n\n## 搜索与浏览功能\n\n### 相关页面\n\n相关主题：[播放系统与质量设置](#page-6), [发现与推荐系统](#page-8)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/search.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/search.ts)\n- [src/artist.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/artist.ts)\n- [src/album.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/album.ts)\n- [src/track.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/track.ts)\n- [src/user.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/user.ts)\n \n\n# 搜索与浏览功能\n\ntidal-cli 提供了完整的搜索与浏览功能，允许用户通过命令行接口访问 Tidal 音乐服务中的各类资源。这些功能涵盖了艺术家、专辑、曲目、视频、播放列表以及编辑推荐等多个维度的内容发现。\n\n## 功能概述\n\n搜索与浏览模块是 tidal-cli 的核心功能之一，提供了对 Tidal 音乐目录的全面访问能力。用户可以通过结构化的命令查询各类媒体资源，并获取详细的元数据信息。\n\n### 核心能力\n\n该模块支持以下主要功能领域：\n\n- **搜索功能**：按类型搜索艺术家、专辑、曲目、视频、播放列表\n- **艺术家浏览**：获取艺术家信息、热门曲目、专辑列表、相似推荐\n- **专辑浏览**：查看专辑详情、曲目列表、条形码查询\n- **曲目浏览**：获取曲目信息、ISRC 识别、相似推荐\n- **用户历史**：查看和管理搜索历史、播放历史\n\n## 搜索功能详解\n\n### 搜索命令结构\n\ntidal-cli 的搜索功能采用统一的命令格式，支持多种内容类型的搜索。\n\n```bash\ntidal-cli search <类型> <查询词>\n```\n\n### 支持的搜索类型\n\n| 类型 | 说明 | 示例命令 |\n|------|------|----------|\n| `artist` | 搜索艺术家 | `tidal-cli search artist \"Gorillaz\"` |\n| `album` | 搜索专辑 | `tidal-cli search album \"Mezzanine\"` |\n| `track` | 搜索曲目 | `tidal-cli search track \"Teardrop\"` |\n| `video` | 搜索视频 | `tidal-cli search video \"Stylo\"` |\n| `playlist` | 搜索播放列表 | `tidal-cli search playlist \"Electronic\"` |\n| `suggest` | 自动建议 | `tidal-cli search suggest \"daft punk\"` |\n| `editorial` | 编辑推荐 | `tidal-cli search editorial \"indie rock\"` |\n\n### 搜索历史管理\n\n系统会记录用户的搜索历史，并提供管理功能：\n\n```bash\ntidal-cli search history # 查看搜索历史\ntidal-cli search history-delete # 删除单条历史记录\ntidal-cli search history-clear # 清空所有历史记录\n```\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## 艺术家浏览\n\n艺术家模块提供对艺术家完整信息的访问能力。\n\n### 可用命令\n\n| 命令 | 功能描述 |\n|------|----------|\n| `tidal-cli artist info ` | 获取艺术家基本信息 |\n| `tidal-cli artist tracks ` | 获取艺术家的热门曲目 |\n| `tidal-cli artist albums ` | 获取艺术家的专辑列表 |\n| `tidal-cli artist similar ` | 查找相似艺术家 |\n| `tidal-cli artist radio ` | 获取艺术家电台（推荐曲目） |\n\n### 数据获取流程\n\n```mermaid\ngraph TD\n A[输入 artist 命令] --> B[解析命令参数]\n B --> C[调用 Tidal API]\n C --> D{查询类型}\n D -->|info| E[获取艺术家详情]\n D -->|tracks| F[获取热门曲目]\n D -->|albums| G[获取专辑列表]\n D -->|similar| H[获取相似艺术家]\n D -->|radio| I[生成艺术家电台]\n E --> J[格式化输出]\n F --> J\n G --> J\n H --> J\n I --> J\n```\n\n## 专辑浏览\n\n专辑模块支持专辑信息和曲目列表的查询。\n\n### 可用命令\n\n| 命令 | 功能描述 |\n|------|----------|\n| `tidal-cli album info ` | 获取专辑详细信息 |\n| `tidal-cli album barcode ` | 通过 EAN 条形码查询专辑 |\n\n### 专辑信息内容\n\n专辑信息通常包含以下内容：\n\n- 专辑标题和艺术家名称\n- 发行日期\n- 曲目数量\n- 专辑封面\n- 音频质量信息\n\n## 曲目浏览\n\n曲目模块提供曲目级别的详细信息和元数据。\n\n### 可用命令\n\n| 命令 | 功能描述 |\n|------|----------|\n| `tidal-cli track info ` | 获取曲目详细信息 |\n| `tidal-cli track similar ` | 查找相似曲目 |\n| `tidal-cli track isrc ` | 通过 ISRC 码识别曲目 |\n| `tidal-cli track radio ` | 获取基于该曲目的电台 |\n\n### ISRC 查询功能\n\nISRC（国际标准录音代码）是曲目的唯一标识符，支持精确的曲目识别：\n\n```bash\ntidal-cli track isrc \n```\n\n此功能允许用户通过已知的 ISRC 码快速定位特定曲目，适用于从其他来源获取的曲目元数据。\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## 发现与推荐\n\n### 推荐功能\n\ntidal-cli 提供个性化推荐功能，支持多种推荐类型：\n\n```bash\ntidal-cli recommend # 获取所有推荐分类\ntidal-cli recommend --type daily # 每日推荐\ntidal-cli recommend --type discovery # 发现推荐\ntidal-cli recommend --type new-release # 新发行\ntidal-cli recommend --type offline # 离线推荐\n```\n\n### Mix 内容\n\n获取 Mix 详情：\n\n```bash\ntidal-cli mix items --type daily\n```\n\n支持的 Mix 类型包括 `daily`、`discovery`、`new-release`、`offline`。\n\n### 用户历史\n\n查看个人使用历史：\n\n```bash\ntidal-cli history tracks # 播放过的曲目\ntidal-cli history albums # 播放过的专辑\ntidal-cli history artists # 播放过的艺术家\n```\n\n### 用户资料\n\n获取当前登录用户的信息：\n\n```bash\ntidal-cli user profile\n```\n\n此命令返回用户账户的详细信息，包括订阅状态、用户 ID 等。\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## JSON 输出\n\n所有搜索和浏览命令支持 JSON 格式输出，便于程序化处理和脚本集成。\n\n### 使用方式\n\n在命令前添加 `--json` 标志：\n\n```bash\ntidal-cli --json search track \"Around the World\"\ntidal-cli --json playlist list\ntidal-cli --json artist similar 8992\n```\n\n### 输出格式\n\nJSON 输出包含完整的 API 响应数据，结构化呈现所有可用字段。\n\n## 命令索引表\n\n### 搜索命令\n\n| 命令 | 描述 |\n|------|------|\n| `search artist ` | 搜索艺术家 |\n| `search album ` | 搜索专辑 |\n| `search track ` | 搜索曲目 |\n| `search video ` | 搜索视频 |\n| `search playlist ` | 搜索播放列表 |\n| `search suggest ` | 自动建议 |\n| `search editorial ` | 编辑推荐 |\n| `search history` | 查看搜索历史 |\n| `search history-delete ` | 删除历史记录 |\n| `search history-clear` | 清空历史记录 |\n\n### 浏览命令\n\n| 命令 | 描述 |\n|------|------|\n| `artist info ` | 艺术家详情 |\n| `artist tracks ` | 艺术家曲目 |\n| `artist albums ` | 艺术家专辑 |\n| `artist similar ` | 相似艺术家 |\n| `artist radio ` | 艺术家电台 |\n| `album info ` | 专辑详情 |\n| `album barcode ` | 条形码查询 |\n| `track info ` | 曲目详情 |\n| `track similar ` | 相似曲目 |\n| `track isrc ` | ISRC 查询 |\n| `track radio ` | 曲目电台 |\n| `user profile` | 用户资料 |\n\n### 发现命令\n\n| 命令 | 描述 |\n|------|------|\n| `recommend` | 获取所有推荐 |\n| `recommend --type ` | 指定类型推荐 |\n| `mix items --type ` | Mix 内容 |\n| `history tracks` | 播放历史-曲目 |\n| `history albums` | 播放历史-专辑 |\n| `history artists` | 播放历史-艺术家 |\n\n## 技术架构\n\n### 模块组织\n\n搜索与浏览功能分布在以下核心模块中：\n\n- **src/search.ts**：搜索命令实现，支持多种类型的搜索查询\n- **src/artist.ts**：艺术家相关功能，包括信息、曲目、专辑、相似推荐\n- **src/album.ts**：专辑浏览和条形码查询功能\n- **src/track.ts**：曲目查询、ISRC 识别、相似曲目\n- **src/user.ts**：用户资料和历史记录管理\n\n### API 交互\n\n所有搜索和浏览功能通过 Tidal API 进行数据获取，命令行工具负责：\n\n1. 解析用户输入的命令和参数\n2. 调用相应的 Tidal API 端点\n3. 格式化并输出返回的数据\n4. 支持 JSON 和人类可读两种输出格式\n\n## 最佳实践\n\n### 高效搜索\n\n- 使用精确的曲目名称可获得更准确的结果\n- 搜索专辑时使用完整的专辑名称\n- ISRC 查询是定位精确曲目的最可靠方式\n\n### 结果处理\n\n- 使用 `--json` 标志便于程序化处理\n- 结合 shell 管道处理大规模数据\n- 利用播放历史功能追踪音乐偏好\n\n### 错误处理\n\n- 确保 Tidal 账户已通过 `tidal-cli auth` 认证\n- 检查网络连接状况\n- 确认 API 配额未超限\n\n---\n\n\n\n## 播放列表管理\n\n### 相关页面\n\n相关主题：[搜索与浏览功能](#page-3), [媒体库管理](#page-5)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/playlist.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/playlist.ts)\n- [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n \n\n# 播放列表管理\n\ntidal-cli 的播放列表管理功能提供了一套完整的命令行接口，用于在 Tidal 音乐平台上创建、编辑和操作个人播放列表。该模块支持查看列表详情、添加/移除曲目、重命名、删除以及生成分享链接等核心操作。\n\n## 功能概述\n\n播放列表管理模块的核心职责包括：\n\n- **列表查询**：查看用户所有播放列表及其基本信息\n- **创建与删除**：新建播放列表或删除已有列表\n- **曲目管理**：向播放列表添加或移除曲目\n- **编辑操作**：重命名播放列表\n- **分享功能**：生成可公开访问的分享链接\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## 命令行接口\n\n### 播放列表查询\n\n| 命令 | 说明 |\n|------|------|\n| `tidal-cli playlist list` | 列出用户所有播放列表 |\n| `tidal-cli playlist info ` | 获取指定播放列表的详细信息 |\n\n### 播放列表操作\n\n| 命令 | 说明 |\n|------|------|\n| `tidal-cli playlist create ` | 创建新播放列表 |\n| `tidal-cli playlist rename --name ` | 重命名播放列表 |\n| `tidal-cli playlist delete ` | 删除播放列表 |\n| `tidal-cli playlist share ` | 生成播放列表分享链接 |\n\n### 曲目管理\n\n| 命令 | 说明 |\n|------|------|\n| `tidal-cli playlist add --track-id ` | 向播放列表添加曲目 |\n| `tidal-cli playlist remove --track-id ` | 从播放列表移除曲目 |\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## JSON 输出支持\n\n所有播放列表命令均支持 `--json` 参数，可直接用于程序化处理：\n\n```bash\ntidal-cli --json playlist list\ntidal-cli --json playlist info \n```\n\nJSON 输出格式示例：\n\n```json\n[{\n \"id\": \"a20fff4a-...\",\n \"name\": \"Late Night Electronic\",\n \"numberOfItems\": 24,\n \"createdAt\": \"2025-04-20T...\"\n}, ...]\n```\n\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n## 使用流程图\n\n```mermaid\ngraph TD\n A[开始] --> B{选择操作}\n B -->|查看列表| C[playlist list]\n B -->|创建列表| D[playlist create]\n B -->|管理曲目| E[playlist add/remove]\n B -->|其他操作| F[info/rename/delete/share]\n \n C --> G[显示播放列表]\n D --> H[输入列表名称]\n H --> I[创建成功]\n E --> J[输入播放列表ID和曲目ID]\n J --> K[操作完成]\n F --> L[执行相应操作]\n \n G --> M[结束]\n I --> M\n K --> M\n L --> M\n```\n\n## 典型使用场景\n\n### 创建并填充播放列表\n\n```bash\n# 1. 创建新播放列表\ntidal-cli playlist create \"My Favorites\"\n\n# 2. 搜索曲目获取ID\ntidal-cli search track \"Teardrop\"\n\n# 3. 添加曲目到播放列表\ntidal-cli playlist add --track-id \n```\n\n### 查看和管理已有列表\n\n```bash\n# 查看所有播放列表\ntidal-cli playlist list\n\n# 查看特定列表详情\ntidal-cli playlist info \n\n# 重命名列表\ntidal-cli playlist rename --name \"New Name\"\n\n# 移除不需要的曲目\ntidal-cli playlist remove --track-id \n```\n\n## 数据存储\n\ntidal-cli 将用户认证信息和会话数据存储在本地 `~/.tidal-cli` 目录中。播放列表数据通过 Tidal API 实时获取，不在本地缓存。\n\n如需清除所有本地数据（包括播放列表相关的认证信息）：\n\n```bash\nrm -rf ~/.tidal-cli\n```\n\n资料来源：[site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n\n## 与 MCP 集成\n\n播放列表管理功能可通过 MCP（Model Context Protocol）协议供 AI 代理调用：\n\n```\ntidal-cli search history\ntidal-cli library favorite-playlists\n```\n\nMCP 端点地址：`https://tidal-cli.lucaperret.ch/api/mcp`\n\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n---\n\n\n\n## 媒体库管理\n\n### 相关页面\n\n相关主题：[播放列表管理](#page-4), [播放系统与质量设置](#page-6)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n- [src/library.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/library.ts) — 核心媒体库模块\n- [src/saved.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/saved.ts) — 稍后再听与收藏管理\n- [src/history.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/history.ts) — 播放历史记录\n- [src/search-history.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/search-history.ts) — 搜索历史管理\n \n\n# 媒体库管理\n\ntidal-cli 的媒体库管理模块为用户提供了一套完整的个人音乐库访问与操作接口。该模块涵盖了发现推荐、播放历史、搜索历史、收藏管理以及个人资料查询等核心功能。通过命令行界面，用户可以高效地管理与 Tidal 账户关联的所有媒体资源，无需依赖图形界面即可完成复杂的媒体库操作。\n\n## 功能架构概览\n\n媒体库管理功能由四个主要子模块组成，分别负责不同的管理职责。这些模块之间相互协作，共同构成了 tidal-cli 的完整媒体库管理体系。\n\n```mermaid\ngraph TD\n A[媒体库管理] --> B[library.ts]\n A --> C[saved.ts]\n A --> D[history.ts]\n A --> E[search-history.ts]\n \n B --> F[发现推荐]\n B --> G[用户资料]\n \n C --> H[稍后再听]\n C --> I[分享链接]\n \n D --> J[播放历史]\n \n E --> K[搜索历史]\n```\n\n## 发现与推荐系统\n\ntidal-cli 提供了强大的音乐发现功能，帮助用户探索 Tidal 平台上的新内容。该功能支持多种推荐类型和播放列表生成。\n\n### 推荐类型\n\n系统支持三种主要的推荐模式，每种模式针对不同的用户场景：\n\n| 推荐类型 | 命令参数 | 说明 |\n|---------|---------|------|\n| 每日推荐 | `--type daily` | 基于用户音乐品味的每日个性化推荐 |\n| 发现推荐 | `--type discovery` | 探索用户可能喜欢但尚未听过的新音乐 |\n| 新发行 | `--type new-release` | 最近上架的新专辑和新单曲 |\n| 离线推荐 | `--type offline` | 可供离线下载的推荐内容 |\n\n```bash\ntidal-cli recommend # 获取所有推荐分类\ntidal-cli recommend --type daily # 仅获取每日推荐\ntidal-cli mix items --type daily # 查看特定推荐中的曲目\n```\n\n### 播放列表电台\n\n除了固定的推荐列表外，tidal-cli 还支持动态播放列表电台功能。这种模式会根据用户当前播放的内容，实时生成类似风格的播放列表。\n\n```bash\ntidal-cli artist radio # 获取艺术家电台\ntidal-cli track radio # 获取歌曲电台\n```\n\n## 播放历史记录\n\n播放历史模块允许用户查看和管理自己的音乐收听记录。该功能支持多种内容类型的历史查询。\n\n### 历史查询命令\n\n```bash\ntidal-cli history tracks # 查看播放过的歌曲历史\ntidal-cli history albums # 查看播放过的专辑历史\ntidal-cli history artists # 查看播放过的艺术家历史\n```\n\n### 历史记录数据结构\n\n播放历史记录包含以下关键信息：\n\n| 字段 | 说明 |\n|-----|------|\n| 播放时间戳 | 记录歌曲何时被播放 |\n| 内容类型 | 歌曲、专辑或艺术家 |\n| 内容标识 | 对应的 Tidal ID |\n| 播放时长 | 实际播放的时长信息 |\n\n历史数据通过 Tidal API 的 `user/history` 端点获取，支持分页查询以便处理大量历史记录。\n\n## 搜索历史管理\n\ntidal-cli 提供了完整的搜索历史管理功能，帮助用户追踪和管理过往的搜索记录。\n\n### 搜索历史操作\n\n```bash\ntidal-cli search history # 查看最近的搜索记录\ntidal-cli search history-delete # 删除单条搜索记录\ntidal-cli search history-clear # 清除所有搜索历史\n```\n\n### 数据存储位置\n\n搜索历史记录存储在本地配置目录中：\n\n- **存储路径**: `~/.tidal-cli/search-history.json`\n- **数据格式**: JSON 数组，每条记录包含搜索关键词和时间戳\n\n## 收藏与稍后再听\n\n`saved.ts` 模块实现了\"稍后再听\"（Saved for Later）功能，这是 tidal-cli 中最常用的媒体库管理功能之一。用户可以将任意媒体内容添加到稍后再听列表中稍后播放。\n\n### 收藏管理命令\n\n```bash\ntidal-cli saved list # 列出所有收藏内容\ntidal-cli saved add --type tracks --id # 添加歌曲到收藏\ntidal-cli saved remove --type albums --id # 从收藏中移除专辑\n```\n\n### 支持的媒体类型\n\n| 类型参数 | 说明 |\n|---------|------|\n| `tracks` | 单曲歌曲 |\n| `albums` | 完整专辑 |\n| `artists` | 艺术家页面 |\n| `playlists` | 播放列表 |\n| `videos` | 音乐视频 |\n\n## 分享功能\n\ntidal-cli 内置了社交分享功能，允许用户为任意媒体内容生成公开分享链接。\n\n### 分享命令\n\n```bash\ntidal-cli share track # 生成歌曲分享链接\ntidal-cli share album # 生成专辑分享链接\n```\n\n分享链接会调用 Tidal API 生成临时或永久的公开访问地址，接收方无需登录即可预览或播放分享的内容（受 Tidal 服务条款限制）。\n\n## 用户资料查询\n\n通过用户资料命令，用户可以查看与当前账户相关的完整信息。\n\n```bash\ntidal-cli user profile # 查看当前用户资料\n```\n\n### 用户资料包含的信息\n\n- **账户类型**: Free、HiFi 或 HiFi Plus 订阅等级\n- **用户 ID**: Tidal 平台唯一标识符\n- **账户状态**: 有效、过期等状态信息\n- **配额信息**: 剩余的下载配额或离线播放限额\n\n## 数据流与交互\n\n```mermaid\nsequenceDiagram\n participant User as 用户终端\n participant CLI as tidal-cli CLI\n participant API as Tidal API\n participant Store as 本地存储\n\n User->>CLI: 执行媒体库命令\n CLI->>API: 发送认证请求\n API-->>CLI: 返回认证令牌\n CLI->>API: 请求媒体库数据\n API-->>CLI: 返回媒体信息\n CLI->>Store: 缓存热门数据\n CLI-->>User: 格式化输出结果\n\n Note over CLI,Store: 保存功能 (saved add)\n User->>CLI: 保存媒体到收藏\n CLI->>API: 提交保存请求\n API-->>CLI: 确认保存成功\n CLI->>Store: 更新本地索引\n```\n\n## 与 MCP 服务器的集成\n\ntidal-cli 的媒体库管理功能也通过 MCP（Model Context Protocol）服务器对外暴露，使得 AI 代理（如 Claude）能够以编程方式控制 Tidal 媒体库。\n\n### MCP 工具可用性\n\n以下媒体库操作可通过 MCP 接口调用：\n\n- `library list-saved` — 列出收藏内容\n- `library add-saved` — 添加收藏\n- `library remove-saved` — 移除收藏\n- `library history` — 查询播放历史\n- `library recommend` — 获取推荐内容\n- `user profile` — 用户资料查询\n\n## 输出格式\n\n所有媒体库命令支持 JSON 格式输出，便于脚本处理和自动化工作流。\n\n```bash\ntidal-cli --json search track \"Around the World\"\ntidal-cli --json playlist list\ntidal-cli --json artist similar 8992\n```\n\n添加 `--json` 参数后，命令输出为纯 JSON 格式，不再包含任何装饰性文本或进度提示。\n\n## 本地数据存储\n\ntidal-cli 在本地存储以下与媒体库相关的数据：\n\n| 存储内容 | 文件路径 | 说明 |\n|---------|---------|------|\n| 认证令牌 | `~/.tidal-cli/session.json` | OAuth 访问令牌 |\n| 搜索历史 | `~/.tidal-cli/search-history.json` | 本地搜索缓存 |\n| 配置文件 | `~/.tidal-cli/config.json` | 用户偏好设置 |\n\n数据以加密形式存储认证敏感信息，本地存储目录权限应限制为仅当前用户可访问。\n\n## 相关文档\n\n- **安装指南**: 请参考 [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md) 的安装章节\n- **服务条款**: 使用本工具需遵守 [Tidal 服务条款](https://tidal.com/terms)\n- **隐私政策**: 详见 [隐私政策页面](/privacy)\n\n---\n\n\n\n## 播放系统与质量设置\n\n### 相关页面\n\n相关主题：[搜索与浏览功能](#page-3), [媒体库管理](#page-5)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n- [src/auth.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/auth.ts)\n- [site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n- [site/app/terms/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/terms/page.tsx)\n- [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n \n\n# 播放系统与质量设置\n\n## 概述\n\ntidal-cli 的播放系统允许用户通过命令行直接控制 Tidal 音乐的播放功能。该系统提供了播放指定曲目、获取播放信息、获取音频流 URL 等核心能力，并支持多种音频质量级别。\n\n播放命令基于 Tidal API 的播放端点实现，支持通过曲目 ID 进行播放操作。 资料来源：[README.md:1-100]()\n\n## 播放命令架构\n\n### 子命令结构\n\ntidal-cli 的播放功能通过 `playback` 子命令组织，包含以下操作：\n\n| 子命令 | 说明 | 参数 |\n|--------|------|------|\n| `play` | 播放指定曲目 | `` 曲目 ID，可选 `--quality` 参数 |\n| `info` | 获取曲目播放信息 | `` 曲目 ID |\n| `url` | 获取音频流 URL | `` 曲目 ID |\n\n资料来源：[README.md:1-100]()\n\n### 基本使用方式\n\n```bash\n# 播放指定曲目\ntidal-cli playback play \n\n# 以无损质量播放\ntidal-cli playback play --quality LOSSLESS\n\n# 获取播放信息\ntidal-cli playback info \n\n# 获取音频流 URL\ntidal-cli playback url \n```\n\n资料来源：[README.md:1-100]()\n\n## 音频质量设置\n\n### 支持的质量级别\n\ntidal-cli 支持四种音频质量级别，通过 `--quality` 参数指定：\n\n| 质量级别 | 说明 | 适用场景 |\n|----------|------|----------|\n| `LOW` | 低比特率 | 节省带宽/流量 |\n| `HIGH` | 高比特率 | 标准音质 |\n| `LOSSLESS` | 无损音质 | 高保真聆听 |\n| `HI_RES` | 高解析音频 | 发烧友级别 |\n\n资料来源：[README.md:1-100]()\n\n### 质量选择示例\n\n```bash\n# 默认质量播放\ntidal-cli playback play 5756235\n\n# 指定无损质量播放\ntidal-cli playback play 5756235 --quality LOSSLESS\n\n# 高解析音频播放\ntidal-cli playback play 5756235 --quality HI_RES\n```\n\n> **注意**: 实际可用的音频质量取决于用户的 Tidal 订阅计划。例如，HI_RES 质量仅对 HiFi Plus 订阅用户可用。\n\n资料来源：[README.md:1-100]()\n资料来源：[site/app/terms/page.tsx:1-50]()\n\n## 工作流程\n\n### 播放流程图\n\n```mermaid\ngraph TD\n A[用户执行 playback play 命令] --> B[解析曲目 ID 和质量参数]\n B --> C{是否指定质量}\n C -->|是| D[使用指定质量级别]\n C -->|否| E[使用账户默认质量]\n D --> F[调用 Tidal API 播放端点]\n E --> F\n F --> G{API 响应状态}\n G -->|成功| H[开始播放音频流]\n G -->|失败| I[输出错误信息]\n```\n\n## 与其他系统的集成\n\n### 播放与发现功能结合\n\n播放系统可与搜索、历史等功能结合使用：\n\n```bash\n# 搜索后播放\ntidal-cli search track \"Teardrop\"\n# 获取曲目 ID 后\ntidal-cli playback play <找到的ID>\n\n# 播放历史记录中的曲目\ntidal-cli history tracks\n# 选择曲目 ID 后\ntidal-cli playback play <历史曲目ID>\n```\n\n### 与 AI Agent 的集成\n\n通过 MCP 连接器，用户可以让 AI Agent 智能选择并播放音乐：\n\n```bash\n# AI Agent 可执行的操作示例\n\"Play me something by Boards of Canada\" # 搜索并播放\n```\n\n资料来源：[site/app/page.tsx:1-50]()\n\n## JSON 输出支持\n\n播放相关命令支持 `--json` 参数以结构化格式输出：\n\n```bash\n# JSON 格式获取播放信息\ntidal-cli --json playback info \n\n# JSON 格式获取音频 URL\ntidal-cli --json playback url \n```\n\n此功能便于脚本处理和程序化调用。\n\n资料来源：[README.md:1-100]()\n\n## 认证要求\n\n播放功能需要有效的 Tidal 认证会话。用户需在首次使用前完成身份验证：\n\n```bash\n# 身份验证命令\ntidal-cli auth\n```\n\n认证成功后，OAuth 令牌将存储在本地 `~/.tidal-cli/session.json` 文件中。令牌会自动刷新以维持会话有效性。\n\n资料来源：[README.md:1-100]()\n资料来源：[site/app/privacy/page.tsx:1-50]()\n\n## 技术限制\n\n- 播放功能依赖 Tidal API，可能受 Tidal 服务可用性影响\n- API 变更可能导致播放功能暂时不可用\n- 某些地区可能存在播放限制\n\n> tidal-cli is provided **\"as is\"** without warranty of any kind. Tidal may change their API at any time, which could affect functionality.\n\n资料来源：[site/app/terms/page.tsx:1-50]()\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| 播放失败 | 未认证或会话过期 | 运行 `tidal-cli auth` 重新认证 |\n| 质量设置无效 | 订阅计划不支持 | 升级 Tidal 订阅计划 |\n| 无法获取 URL | API 限制 | 检查网络连接或稍后重试 |\n\n资料来源：[site/app/privacy/page.tsx:1-50]()\n\n---\n\n\n\n## 认证与会话管理\n\n### 相关页面\n\n相关主题：[系统架构](#page-2), [发现与推荐系统](#page-8), [MCP 服务器集成](#page-9)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/auth.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/auth.ts)\n- [src/session.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/session.ts)\n- [site/app/mcp-lib/tidal-oauth.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/mcp-lib/tidal-oauth.ts)\n- [site/app/mcp-lib/constants.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/mcp-lib/constants.ts)\n- [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n \n\n# 认证与会话管理\n\n## 概述\n\ntidal-cli 的认证与会话管理系统是该项目的核心基础设施，负责处理用户与 Tidal API 之间的安全通信。该模块基于 OAuth 2.0 授权码模式配合 PKCE（Proof Key for Code Exchange）扩展实现无密钥的安全认证流程。系统设计了双轨制架构，分别支持命令行工具（CLI）的本地会话存储和 MCP 服务器的服务端会话管理，确保用户凭证在传输和存储过程中的安全性。\n\n## 认证机制\n\n### OAuth 2.0 + PKCE 架构\n\ntidal-cli 采用公开客户端（Public Client）OAuth 流程，无需客户端密钥即可完成认证。系统利用 PKCE 机制替代传统客户端密钥，通过动态生成的代码挑战和验证器来保障授权码交换的安全性。\n\n```mermaid\ngraph TD\n A[用户执行 tidal-cli auth] --> B[生成 code_verifier 和 code_challenge]\n B --> C[构建授权 URL]\n C --> D[启动本地回调服务器]\n D --> E[打开浏览器跳转至 Tidal 授权页]\n E --> F[用户登录并授权]\n F --> G[Tidal 重定向至本地回调服务器]\n G --> H[交换授权码获取 Access Token]\n H --> I[保存会话至 ~/.tidal-cli/session.json]\n I --> J[认证成功]\n```\n\n### 认证流程详解\n\n#### 第一阶段：启动本地服务器\n\n```typescript\nserver.listen(REDIRECT_PORT, () => {\n console.log('\\nOpening browser for Tidal authorization...');\n console.log(`If the browser doesn't open, visit:\\n ${loginUrl}\\n`);\n console.log('Waiting for authorization...');\n openBrowser(loginUrl);\n});\n```\n\n系统在本地随机端口启动 HTTP 服务器，监听来自 Tidal OAuth 服务的回调请求。此服务器作为授权码的接收端点，确保令牌交换过程在用户本地完成，避免凭证经过第三方服务器。\n\n#### 第二阶段：令牌交换\n\n授权码交换过程采用 PKCE 验证机制：\n\n| 参数 | 说明 | 来源 |\n|------|------|------|\n| `grant_type` | 授权类型，值为 `authorization_code` | RFC 6749 标准 |\n| `code` | Tidal 返回的授权码 | 回调请求参数 |\n| `client_id` | Tidal 应用客户端 ID | 硬编码配置 |\n| `code_verifier` | 高熵随机字符串（43-128字符） | 动态生成 |\n| `redirect_uri` | 回调地址 | `http://localhost:{REDIRECT_PORT}` |\n\n### CLI 与 MCP 认证差异\n\ntidal-cli 提供两种使用模式，认证存储策略存在本质区别：\n\n| 模式 | 存储位置 | 加密方式 | 有效期 |\n|------|----------|----------|--------|\n| CLI | `~/.tidal-cli/session.json` | 无加密（文件权限保护） | 令牌自身过期时间 |\n| MCP | Upstash Redis | TLS 传输加密 | 30 天 TTL |\n\n资料来源：[site/app/privacy/page.tsx]()\n\nCLI 模式下，用户的 OAuth 令牌以 JSON 格式持久化至用户主目录下的隐藏文件夹，依赖操作系统文件权限机制进行保护。MCP 模式则将令牌托管于 Vercel 部署的 Upstash Redis 缓存服务，通过服务端加密确保传输安全，并设置 30 天生存时间自动过期。\n\n## 会话存储\n\n### 本地会话管理\n\n#### Session 模块架构\n\n```mermaid\nclassDiagram\n class SessionStorage {\n +getItem(key): string | null\n +setItem(key, value): void\n +removeItem(key): void\n +clear(): void\n }\n class EventTarget {\n +addEventListener()\n +removeEventListener()\n +dispatchEvent()\n }\n class StorageEvent {\n +key: string\n +newValue: string\n +oldValue: string\n }\n\n SessionStorage --|> EventTarget\n SessionStorage ..> StorageEvent : creates\n```\n\ntidal-cli 在 Node.js 环境中实现了 `localStorage` 和 `EventTarget` API 的 polyfill，使得标准 Web 存储接口可直接用于服务端环境。\n\n#### 会话文件格式\n\n```json\n{\n \"access_token\": \"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"refresh_token\": \"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"expires_at\": 1710489600000,\n \"userId\": \"123456789\"\n}\n```\n\n会话文件采用 JSON 格式存储关键认证信息，包含访问令牌、刷新令牌、过期时间戳及用户 ID。访问令牌用于 API 请求认证，刷新令牌用于获取新的访问令牌而无需用户重新授权。\n\n### 服务端会话管理（MCP）\n\n#### Redis 存储策略\n\nMCP 连接器使用 Upstash Redis 实现跨会话持久化：\n\n```typescript\n// 伪代码示例\nconst sessionData = {\n token: encryptedOAuthToken,\n userId: extractedUserId,\n createdAt: Date.now()\n};\n\n// 设置 30 天过期时间\nawait redis.setex(sessionKey, 30 * 24 * 60 * 60, JSON.stringify(sessionData));\n```\n\n资料来源：[site/app/privacy/page.tsx]()\n\n服务端存储采用加密机制保护敏感令牌数据，所有通过 MCP 协议进行的 API 调用都需要从 Redis 中提取有效会话信息。30 天 TTL 确保长期未使用的会话自动清理，减少安全风险。\n\n## API 客户端\n\n### getApiClient 函数\n\n```typescript\nexport async function getApiClient(): Promise {\n await ensureInit();\n\n // Verify we have valid credentials\n const creds = await credentialsProvider.getCredentials();\n if (!creds.token) {\n console.error('Error: Not authenticated. Run `tidal-cli auth` first.');\n process.exit(1);\n }\n\n return createAPIClient(credentialsProvider);\n}\n```\n\n该函数是获取 Tidal API 客户端的主入口点，核心职责包括：\n\n1. **初始化检查**：调用 `ensureInit()` 确保认证模块已正确初始化\n2. **凭证验证**：从凭证提供者获取当前会话凭证\n3. **错误处理**：检测到未认证状态时输出错误信息并终止程序\n4. **客户端创建**：返回配置了凭证的 API 客户端实例\n\n资料来源：[src/auth.ts]()\n\n### getCountryCode 函数\n\n```typescript\nlet cachedCountryCode: string | null = null;\n\nexport async function getCountryCode(): Promise {\n if (cachedCountryCode) return cachedCountryCode;\n\n try {\n const client = await getApiClient();\n const { data } = await client.GET('/users/{id}' as any, {\n // ...\n });\n // 从用户配置中提取国家代码\n } catch {\n // 降级策略\n }\n}\n```\n\n国家代码自动检测机制遵循以下优先级：\n\n| 优先级 | 来源 | 说明 |\n|--------|------|------|\n| 1 | 用户资料 | 通过 `/users/me` API 获取用户账户国家 |\n| 2 | 环境变量 | `TIDAL_COUNTRY` 环境变量 |\n| 3 | 默认值 | `US` |\n\n该机制确保 API 请求携带正确的地区标识，获取符合用户所在区域的内容目录和播放限制信息。\n\n## Token 自动刷新\n\n### 刷新机制流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant CLI as tidal-cli\n participant T as Tidal API\n participant FS as 文件系统\n\n U->>CLI: 执行任意命令\n CLI->>T: 发送带 Access Token 的请求\n T-->>CLI: Token 有效\n CLI-->>U: 返回请求结果\n\n Note over CLI,T: Token 过期场景\n U->>CLI: 执行任意命令\n CLI->>T: 发送带 Access Token 的请求\n T-->>CLI: 401 Unauthorized\n CLI->>T: 使用 Refresh Token 获取新 Token\n T-->>CLI: 返回新 Access Token + 新 Refresh Token\n CLI->>FS: 更新 session.json\n CLI->>T: 重试原请求\n CLI-->>U: 返回请求结果\n```\n\n### 刷新触发条件\n\n自动刷新机制在以下场景触发：\n\n- **令牌过期**：API 返回 401 状态码时自动尝试刷新\n- **令牌临近过期**：部分实现会在令牌即将过期前主动刷新\n- **首次认证**：执行 `tidal-cli auth` 命令后立即保存初始令牌\n\n刷新成功后，新的访问令牌和刷新令牌会持久化至 `~/.tidal-cli/session.json`，确保下次启动时使用最新凭证。\n\n## 数据安全\n\n### 隐私保护措施\n\ntidal-cli 在设计层面采取多重数据保护策略：\n\n| 措施 | CLI 模式 | MCP 模式 |\n|------|----------|----------|\n| 凭证传输 | 直接与 Tidal API 通信 | 经由 Vercel 服务器转发 |\n| 凭证存储 | 本地文件系统 | Upstash Redis（加密） |\n| 数据收集 | 无分析、无遥测 | 无分析、无遥测 |\n| Cookie 使用 | 无 | 仅 Tidal OAuth 流程所需 |\n\n资料来源：[site/app/privacy/page.tsx]()\n\n### 第三方服务依赖\n\n认证流程涉及以下 Tidal 官方服务端点：\n\n| 服务 | 端点 | 用途 |\n|------|------|------|\n| Tidal API | `openapi.tidal.com` | 音乐目录、播放列表访问 |\n| Tidal Auth | `login.tidal.com` | 用户登录界面 |\n| Tidal Auth | `auth.tidal.com` | OAuth 令牌交换 |\n\n所有通信遵循 Tidal 官方隐私政策，用户凭证永远不会经过 tidal-cli 维护者的服务器（除 MCP 模式的服务端存储）。\n\n### 数据删除\n\n用户可通过以下方式清除所有本地认证数据：\n\n```bash\nrm -rf ~/.tidal-cli\n```\n\n此命令删除包含 OAuth 令牌和会话信息的整个目录。删除后用户需重新执行 `tidal-cli auth` 进行认证。\n\n## 相关命令\n\n### auth 命令\n\n```bash\ntidal-cli auth\n```\n\n启动 OAuth 认证流程，打开浏览器引导用户完成 Tidal 账户授权。\n\n### 依赖模块\n\n| 模块 | 文件路径 | 功能描述 |\n|------|----------|----------|\n| 认证核心 | `src/auth.ts` | OAuth 流程、API 客户端获取 |\n| 会话存储 | `src/session.ts` | localStorage polyfill 实现 |\n| MCP OAuth | `site/app/mcp-lib/tidal-oauth.ts` | 服务端 OAuth 处理 |\n| MCP 常量 | `site/app/mcp-lib/constants.ts` | 配置常量和端点定义 |\n\n## 总结\n\ntidal-cli 的认证与会话管理系统通过 OAuth 2.0 + PKCE 协议实现了安全的无密钥认证，结合本地和服务端双轨存储策略兼顾了 CLI 用户的数据主权和 MCP 用户的使用便利性。Token 自动刷新机制确保长时间使用的连贯体验，而清晰的数据安全设计让用户对自己的凭证拥有完全控制权。\n\n---\n\n\n\n## 发现与推荐系统\n\n### 相关页面\n\n相关主题：[搜索与浏览功能](#page-3), [媒体库管理](#page-5)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/recommend.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/recommend.ts)\n- [src/mix.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/mix.ts)\n- [src/share.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/share.ts)\n- [src/history.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/history.ts)\n- [src/saved.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/saved.ts)\n- [src/user.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/user.ts)\n \n\n# 发现与推荐系统\n\n## 概述\n\ntidal-cli 的发现与推荐系统为用户提供了一套完整的音乐探索功能，包括个性化推荐、智能混音、用户历史记录管理以及社交分享能力。该系统与 Tidal API 深度集成，使用户能够在命令行环境中完成传统桌面或移动应用中的所有发现操作。\n\n## 系统架构\n\n发现与推荐系统由多个相互协作的模块组成，每个模块负责特定的功能域：\n\n| 模块 | 功能描述 | 主要命令 |\n|------|----------|----------|\n| `recommend` | 个性化推荐与混音获取 | `tidal-cli recommend` |\n| `mix` | 混音曲目管理 | `tidal-cli mix items` |\n| `history` | 用户行为历史记录 | `tidal-cli history tracks` |\n| `saved` | 稍后播放与收藏管理 | `tidal-cli saved list` |\n| `share` | 公开分享链接生成 | `tidal-cli share track` |\n| `user` | 用户资料获取 | `tidal-cli user profile` |\n\n## 推荐与混音\n\n### 获取推荐内容\n\n`tidal-cli recommend` 命令用于获取系统推荐的各种混音类型：\n\n```bash\ntidal-cli recommend # 获取所有混音类别\ntidal-cli recommend --type daily # 每日推荐混音\ntidal-cli recommend --type discovery # 发现混音\ntidal-cli recommend --type new-release # 新发行混音\ntidal-cli recommend --type offline # 离线可用混音\n```\n\n### 混音曲目管理\n\n获取特定混音后，可通过 `mix items` 命令查看混音内的所有曲目：\n\n```bash\ntidal-cli mix items --type daily\n```\n\n## 历史记录系统\n\n### 播放历史\n\ntidal-cli 记录并管理用户的三类播放历史：\n\n| 命令 | 功能 |\n|------|------|\n| `tidal-cli history tracks` | 查看最近播放的曲目 |\n| `tidal-cli history albums` | 查看最近播放的专辑 |\n| `tidal-cli history artists` | 查看最近播放的艺术家 |\n\n### 搜索历史\n\n系统同时维护用户的搜索历史，支持以下操作：\n\n```bash\ntidal-cli search history # 查看最近的搜索记录\ntidal-cli search history-delete # 删除单条搜索记录\ntidal-cli search history-clear # 清空全部搜索历史\n```\n\n## 保存与收藏\n\n### 稍后播放列表\n\n`saved` 命令提供对“稍后播放”列表的管理功能：\n\n```bash\ntidal-cli saved list # 列出所有已保存的项目\ntidal-cli saved add --type tracks --id # 添加曲目到保存列表\ntidal-cli saved add --type albums --id # 添加专辑到保存列表\ntidal-cli saved add --type artists --id # 添加艺术家到保存列表\ntidal-cli saved add --type playlists --id # 添加播放列表\ntidal-cli saved add --type videos --id # 添加视频到保存列表\n```\n\n### 移除已保存项目\n\n```bash\ntidal-cli saved remove --type albums --id \n```\n\n## 分享功能\n\ntidal-cli 支持生成公开分享链接，允许用户与他人共享音乐内容：\n\n```bash\ntidal-cli share track # 创建曲目的公开分享链接\ntidal-cli share album # 创建专辑的公开分享链接\n```\n\n分享功能会通过 Tidal API 生成标准化的分享 URL，接收方可直接在浏览器中打开查看。\n\n## 用户资料\n\n获取当前登录用户的完整资料：\n\n```bash\ntidal-cli user profile\n```\n\n该命令返回用户账户信息，包括订阅状态、用户名等个人资料数据。\n\n## JSON 输出\n\n所有发现与推荐相关的命令都支持 JSON 格式输出，便于脚本处理和程序化调用：\n\n```bash\ntidal-cli --json recommend\ntidal-cli --json history tracks\ntidal-cli --json saved list\ntidal-cli --json search history\n```\n\n## 数据流向\n\n```mermaid\ngraph TD\n A[用户请求] --> B[tidal-cli CLI]\n B --> C{命令类型}\n C -->|recommend| D[Tidal API: /recommendations]\n C -->|history| E[Tidal API: /history]\n C -->|saved| F[Tidal API: /library]\n C -->|share| G[Tidal API: /share]\n C -->|user| H[Tidal API: /user]\n D --> I[JSON 输出]\n E --> I\n F --> I\n G --> I\n H --> I\n```\n\n## 典型使用场景\n\n### 每日音乐探索流程\n\n```bash\n# 1. 查看每日推荐混音\ntidal-cli recommend --type daily\n\n# 2. 获取混音中的曲目\ntidal-cli mix items --type daily\n\n# 3. 播放感兴趣的曲目\ntidal-cli playback play \n\n# 4. 查看播放历史\ntidal-cli history tracks\n```\n\n### 个人资料管理\n\n```bash\n# 查看个人资料\ntidal-cli user profile\n\n# 查看播放历史\ntidal-cli history tracks\ntidal-cli history albums\ntidal-cli history artists\n\n# 管理已保存内容\ntidal-cli saved list\n```\n\n## 隐私说明\n\n根据 tidal-cli 隐私政策，使用 CLI 模式时所有数据直接在你的设备与 Tidal API 服务器之间传输，不经过任何中介服务器。认证令牌存储在本地文件 `~/.tidal-cli/session.json` 中。\n\n如需清除所有本地存储的发现历史和缓存数据，可执行：\n\n```bash\nrm -rf ~/.tidal-cli\n\n---\n\n\n\n## MCP 服务器集成\n\n### 相关页面\n\n相关主题：[认证与会话管理](#page-7), [Web 端与部署](#page-10)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n- [site/app/mcp-lib/tools.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/mcp-lib/tools.ts)\n- [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n- [src/auth.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/auth.ts)\n- [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n \n\n# MCP 服务器集成\n\n## 概述\n\nMCP（Model Context Protocol）服务器集成为 tidal-cli 提供了与 AI 助手（特别是 Claude Desktop 和 claude.ai）的无缝集成能力。通过这一集成，用户可以通过自然语言指令与 Tidal 账户进行交互，实现音乐搜索、播放列表管理、资料库操作等功能。\n\ntidal-cli 作为远程 MCP 服务器运行，允许 AI 代理直接调用 Tidal API 的各项功能，无需用户在本地安装任何软件。所有认证令牌存储在 Upstash 托管的加密 Redis 数据库中，确保了安全性和跨设备访问能力。\n\n## 架构设计\n\n### 系统组件\n\n| 组件 | 描述 | 位置 |\n|------|------|------|\n| MCP 路由端点 | 处理 MCP 协议请求的主入口 | `/api/mcp` |\n| 授权端点 | OAuth 授权流程处理 | `/api/authorize` |\n| 回调端点 | OAuth 回调处理 | `/api/callback` |\n| Token 端点 | Token 刷新与管理 | `/api/token` |\n| 注册端点 | 用户会话注册 | `/api/register` |\n| 工具定义 | 40 个可用的 MCP 工具 | `mcp-lib/tools.ts` |\n| Redis 存储 | 加密的会话数据存储 | `mcp-lib/redis.ts` |\n\n### 认证流程\n\n```mermaid\nsequenceDiagram\n participant User\n participant Claude\n participant MCP_Server\n participant Tidal_API\n participant Redis\n\n User->>Claude: 请求连接 Tidal\n Claude->>MCP_Server: 通过 /api/mcp 连接\n MCP_Server->>User: 重定向到授权页面\n User->>Tidal_API: 输入 Tidal 凭据\n Tidal_API->>MCP_Server: 返回 OAuth Code\n MCP_Server->>Tidal_API: 交换 Access Token\n Tidal_API->>MCP_Server: 返回 Token\n MCP_Server->>Redis: 加密存储会话\n Redis->>MCP_Server: 确认存储\n MCP_Server->>Claude: 连接成功\n Claude->>User: 显示可用工具\n```\n\n## MCP 连接配置\n\n### 连接地址\n\nMCP 服务器通过以下端点对外提供服务：\n\n```\nhttps://tidal-cli.lucaperret.ch/api/mcp\n```\n\n该端点托管在 Vercel 平台上，响应 MCP 协议的标准请求。\n\n### Claude Desktop 配置\n\n在 Claude Desktop 中配置自定义连接器的步骤如下：\n\n1. 打开 Claude Desktop 设置页面\n2. 导航至 **Connectors**（连接器）部分\n3. 点击 **Add custom connector**（添加自定义连接器）\n4. 输入上述 MCP 端点 URL\n5. 点击 **Connect**（连接）并使用 Tidal 账户登录\n\n## 可用工具\n\ntidal-cli MCP 集成提供了 40 个工具，覆盖以下功能类别：\n\n### 搜索功能\n\n| 工具名称 | 描述 |\n|---------|------|\n| `tidal_search_tracks` | 搜索曲目 |\n| `tidal_search_albums` | 搜索专辑 |\n| `tidal_search_artists` | 搜索艺术家 |\n| `tidal_search_playlists` | 搜索播放列表 |\n| `tidal_search_videos` | 搜索视频 |\n| `tidal_search_suggest` | 获取搜索建议 |\n| `tidal_search_history` | 查看搜索历史 |\n| `tidal_search_history_delete` | 删除单条历史记录 |\n| `tidal_search_history_clear` | 清空所有历史 |\n\n### 播放列表管理\n\n| 工具名称 | 描述 |\n|---------|------|\n| `tidal_playlist_list` | 列出用户播放列表 |\n| `tidal_playlist_create` | 创建新播放列表 |\n| `tidal_playlist_add_track` | 添加曲目到播放列表 |\n| `tidal_playlist_add_album` | 添加专辑到播放列表 |\n| `tidal_playlist_remove_track` | 从播放列表移除曲目 |\n| `tidal_playlist_delete` | 删除播放列表 |\n\n### 资料库操作\n\n| 工具名称 | 描述 |\n|---------|------|\n| `tidal_library_tracks` | 获取资料库中的曲目 |\n| `tidal_library_albums` | 获取资料库中的专辑 |\n| `tidal_library_artists` | 获取资料库中的艺术家 |\n| `tidal_library_playlists` | 获取资料库中的播放列表 |\n| `tidal_library_favorite_tracks` | 获取收藏的曲目 |\n| `tidal_library_favorite_artists` | 收藏艺术家 |\n| `tidal_library_favorite_albums` | 收藏专辑 |\n| `tidal_recently_added` | 最近添加的项目 |\n\n### 艺术家相关\n\n| 工具名称 | 描述 |\n|---------|------|\n| `tidal_artist_info` | 获取艺术家信息 |\n| `tidal_artist_tracks` | 获取艺术家的曲目 |\n| `tidal_artist_albums` | 获取艺术家的专辑 |\n| `tidal_artist_similar` | 获取相似艺术家 |\n| `tidal_artist_radio` | 获取艺术家电台 |\n\n### 专辑相关\n\n| 工具名称 | 描述 |\n|---------|------|\n| `tidal_album_info` | 获取专辑详细信息 |\n| `tidal_album_by_barcode` | 通过条形码查找专辑 |\n\n### 曲目相关\n\n| 工具名称 | 描述 |\n|---------|------|\n| `tidal_track_info` | 获取曲目信息 |\n| `tidal_track_similar` | 获取相似曲目 |\n| `tidal_track_radio` | 获取曲目电台 |\n\n### 播放控制\n\n| 工具名称 | 描述 |\n|---------|------|\n| `tidal_playback_play` | 播放指定曲目 |\n| `tidal_playback_info` | 获取播放信息 |\n| `tidal_playback_url` | 获取播放 URL |\n\n### 推荐与历史\n\n| 工具名称 | 描述 |\n|---------|------|\n| `tidal_recommend` | 获取推荐内容 |\n| `tidal_mix_items` | 获取混合播放列表内容 |\n| `tidal_history_tracks` | 播放历史（曲目） |\n| `tidal_history_albums` | 播放历史（专辑） |\n| `tidal_history_artists` | 播放历史（艺术家） |\n\n### 其他功能\n\n| 工具名称 | 描述 |\n|---------|------|\n| `tidal_user_profile` | 获取用户资料 |\n| `tidal_share_track` | 创建曲目分享链接 |\n| `tidal_share_album` | 创建专辑分享链接 |\n| `tidal_saved_list` | 列出稍后保存的项目 |\n| `tidal_saved_add` | 添加到保存列表 |\n| `tidal_saved_remove` | 从保存列表移除 |\n\n## 工具定义规范\n\n每个 MCP 工具都遵循统一的定义规范，包含以下元数据：\n\n```typescript\nserver.tool(\n 'tool_name', // 工具标识符\n 'Tool description', // 工具描述\n { /* 参数 Schema */ }, // Zod 参数验证\n { \n readOnlyHint: boolean, // 是否只读操作\n destructiveHint: boolean, // 是否为破坏性操作\n openWorldHint: boolean, // 是否涉及外部网络\n title: string // 人类可读标题\n },\n async (params, extra) => {\n // 工具实现\n }\n);\n```\n\n### 工具提示语义\n\n| 提示 | 含义 | 示例 |\n|------|------|------|\n| `readOnlyHint: true` | 只读操作，不修改数据 | 搜索、查看信息 |\n| `destructiveHint: false` | 非破坏性操作 | 播放、添加 |\n| `openWorldHint: true` | 涉及外部 API 调用 | 所有 Tidal API 调用 |\n\n## 认证与令牌管理\n\n### OAuth 认证流程\n\nMCP 服务器使用标准的 OAuth 2.0 流程进行身份验证：\n\n1. **授权请求**：用户发起连接请求后，被重定向至 Tidal 登录页面\n2. **用户授权**：用户在 Tidal 页面输入凭据并授权 tidal-cli 访问\n3. **回调处理**：Tidal 通过回调 URL 返回授权码\n4. **令牌交换**：服务器将授权码交换为访问令牌和刷新令牌\n5. **会话存储**：加密后的令牌存储至 Upstash Redis\n\n### 令牌存储\n\nCLI 模式下，令牌存储在本地：`~/.tidal-cli/session.json`\n\nMCP 模式下，令牌存储在服务器端加密的 Redis 数据库中，由 Upstash（Vercel 生态）托管。\n\n## 使用示例\n\n### 自然语言交互\n\n用户可以通过以下方式与 Tidal 交互：\n\n| 用户请求 | AI 执行的操作 |\n|---------|--------------|\n| 创建包含 Daft Punk Discovery 专辑最佳曲目的播放列表 | 搜索曲目、创建播放列表、添加曲目 |\n| 查找与 Massive Attack 相似的艺术家并添加其热门曲目到资料库 | 发现相似艺术家、添加收藏 |\n| 列出我的播放列表，将 LCD Soundsystem 新专辑添加到第一个 | 列出播放列表、搜索专辑、添加曲目 |\n| 播放 Boards of Canada 的歌曲 | 搜索艺术家、选择曲目、播放 |\n\n### 质量参数\n\n播放功能支持指定音质：\n\n```bash\ntidal-cli playback play --quality LOSSLESS\n```\n\n可用质量选项：`LOW`、`HIGH`、`LOSSLESS`、`HI_RES`\n\n## 隐私与安全\n\n### 数据存储\n\n根据隐私政策，MCP 集成遵循以下数据处理原则：\n\n- tidal-cli 不向开发者服务器收集或传输任何个人数据\n- 认证令牌加密存储在 Upstash Redis 中\n- 所有 Tidal API 通信直接通过用户设备与 Tidal 服务器进行\n\n### 数据删除\n\n用户可通过以下方式删除所有存储的数据：\n\n1. 在 Tidal 账户设置中撤销 tidal-cli 的访问权限\n2. 删除本地会话文件（CLI 模式）：`rm -rf ~/.tidal-cli`\n\n## Smithery 集成\n\n除 Claude Desktop 外，tidal-cli MCP 服务器还可在 Smithery 平台获取：\n\n```\nhttps://smithery.ai/servers/lucaperret/tidal\n```\n\n## 相关资源\n\n- 官方文档：[github.com/lucaperret/tidal-cli](https://github.com/lucaperret/tidal-cli)\n- 隐私政策：[tidal-cli.lucaperret.ch/privacy](https://tidal-cli.lucaperret.ch/privacy)\n- 服务条款：[tidal-cli.lucaperret.ch/terms](https://tidal-cli.lucaperret.ch/terms)\n\n---\n\n\n\n## Web 端与部署\n\n### 相关页面\n\n相关主题：[系统架构](#page-2), [MCP 服务器集成](#page-9)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n- [site/app/terms/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/terms/page.tsx)\n- [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n- [site/app/og-banner/route.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/og-banner/route.tsx)\n- [site/app/banner/route.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/banner/route.tsx)\n- [site/app/components/Nav.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/components/Nav.tsx)\n- [site/app/components/Terminal.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/components/Terminal.tsx)\n \n\n# Web 端与部署\n\n## 概述\n\ntidal-cli 项目不仅包含核心的命令行工具，还维护了一个完整的 Web 前端站点（位于 `site/` 目录）。该站点主要用于：\n\n- 展示项目功能和使用说明\n- 提供 MCP（Model Context Protocol）服务器端点，供 AI 代理（如 Claude）远程调用 Tidal API\n- 生成社交分享用的 OG（Open Graph）图片和横幅\n\n站点采用 [Next.js](https://nextjs.org/) 框架构建，部署在 **Vercel** 平台，并集成了 **Upstash Redis** 用于 MCP 模式下的认证令牌存储。\n\n## 技术架构\n\n### 技术栈\n\n| 层级 | 技术 | 说明 |\n|------|------|------|\n| 框架 | Next.js | 基于 React 的全栈框架，支持 App Router |\n| 语言 | TypeScript | 类型安全的 JavaScript 超集 |\n| 样式 | Tailwind CSS | 原子化 CSS 框架 |\n| 动画 | Framer Motion | React 动画库 |\n| 数据库 | Upstash Redis | MCP 服务器端认证令牌存储 |\n| 部署 | Vercel | 边缘部署平台 |\n\n### 目录结构\n\n```\nsite/\n├── app/\n│ ├── components/ # React 组件\n│ │ ├── Nav.tsx # 顶部导航栏\n│ │ └── Terminal.tsx # 终端模拟展示组件\n│ ├── api/ # API 路由\n│ │ └── mcp/ # MCP 服务器端点\n│ ├── terms/ # 服务条款页面\n│ ├── privacy/ # 隐私政策页面\n│ ├── og-banner/ # OG 图片生成路由\n│ ├── banner/ # 横幅生成路由\n│ └── page.tsx # 首页\n├── package.json\n└── vercel.json\n```\n\n## 核心组件\n\n### 导航组件\n\n`site/app/components/Nav.tsx` 提供了站点的顶部导航栏功能：\n\n- 左侧显示 tidal-cli Logo\n- 右侧提供 GitHub 链接入口\n- 响应式设计，在移动端隐藏部分链接\n\n```tsx\n// Nav.tsx 核心结构\n\n```\n\n资料来源：[site/app/components/Nav.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/components/Nav.tsx)\n\n### 终端展示组件\n\n`site/app/components/Terminal.tsx` 是一个用于模拟命令行终端界面的 React 组件，支持动画效果和命令展示：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| title | string | 终端窗口标题 |\n| lines | Line[] | 命令行内容数组 |\n| compact | boolean | 是否启用紧凑模式 |\n\n```tsx\ninterface Line {\n prompt?: boolean; // 是否显示 $ 提示符\n text: string; // 命令文本\n dim?: boolean; // 是否显示为灰色（注释）\n}\n```\n\n组件使用 Framer Motion 实现逐行动画效果，每行动画延迟 80ms：\n\n```tsx\n\n {line.prompt && $ }\n \n {line.text}\n \n\n```\n\n资料来源：[site/app/components/Terminal.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/components/Terminal.tsx)\n\n## 首页结构\n\n`site/app/page.tsx` 是站点的首页，包含以下主要区域：\n\n### 功能展示区\n\n展示 tidal-cli 的核心命令功能，包括搜索、艺术家信息、播放列表、播放控制、媒体库管理等。\n\n| 功能模块 | 命令示例 |\n|----------|----------|\n| 搜索 | `search track \"Around the World\"` |\n| 艺术家 | `artist info `, `artist albums ` |\n| 发现 | `artist similar `, `recommend` |\n| 播放列表 | `playlist list`, `playlist create --name \"Chill\"` |\n| 播放控制 | `playback play `, `playback url ` |\n| 媒体库 | `library add --track-id ...`, `history tracks` |\n\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n### 安装区域\n\n提供 npm 安装命令和 OAuth 认证流程说明：\n\n```bash\nnpm install -g @lucaperret/tidal-cli\ntidal-cli auth\n```\n\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n### MCP 集成区域\n\n说明如何将 tidal-cli 作为远程 MCP 服务器连接到 Claude Desktop：\n\n1. 在 Claude 设置中添加自定义连接器\n2. 输入 MCP 端点 URL：`https://tidal-cli.lucaperret.ch/api/mcp`\n\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n### AI 代理示例区域\n\n展示用户可以通过自然语言让 AI 代理执行复杂的 Tidal 操作：\n\n| 示例提示 | 执行操作 |\n|----------|----------|\n| 创建 Discovery 专辑的最佳曲目播放列表 | 搜索、创建播放列表、添加曲目 |\n| 添加类似 Massive Attack 的艺术家到我的媒体库 | 发现相似艺术家、添加到收藏 |\n| 播放 Boards of Canada 的音乐 | 搜索、选择曲目、播放 |\n\n## MCP 服务器端点\n\nMCP 服务器通过 API 路由 `/api/mcp` 提供服务，允许 AI 代理远程调用 tidal-cli 功能。\n\n### 认证机制\n\n根据隐私政策，MCP 模式下的认证令牌存储在服务器端：\n\n> 当使用 tidal-cli 作为 MCP 连接器时（例如通过 Claude Desktop 或 claude.ai），认证令牌存储在 Upstash（通过 Vercel）托管的加密 Redis 数据库中。\n\n资料来源：[site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n\n### 数据流向\n\n```mermaid\ngraph TD\n A[Claude Desktop] -->|MCP Protocol| B[tidal-cli.lucaperret.ch/api/mcp]\n B --> C[Upstash Redis]\n C -->|Session Tokens| B\n B -->|Tidal API| D[openapi.tidal.com]\n B -->|OAuth| E[login.tidal.com / auth.tidal.com]\n```\n\n## OG 图片与横幅生成\n\n### OG Banner 路由\n\n`site/app/og-banner/route.tsx` 和 `site/app/banner/route.tsx` 提供了动态生成 Open Graph 图片的功能。\n\n这些路由使用 Next.js 的 Image Response API 生成 SVG 格式的横幅图片：\n\n```tsx\nnew ImageResponse(\n (\n \n ),\n { width: 1280, height: 240 }\n);\n```\n\n生成内容包括：\n\n- tidal-cli 标题文字\n- 功能标签（Search、Playlists、Playback、Discovery）\n- AI Agent Ready 标识\n\n资料来源：[site/app/og-banner/route.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/og-banner/route.tsx)\n\n## 隐私与合规\n\n### 数据收集策略\n\n| 使用模式 | 数据存储位置 | 说明 |\n|----------|--------------|------|\n| CLI 模式 | 本地 `~/.tidal-cli/session.json` | 直接与 Tidal API 通信，无中间服务器 |\n| MCP 模式 | Upstash Redis | 服务器端加密存储认证令牌 |\n\n资料来源：[site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n\n### 外部服务依赖\n\n| 服务 | 用途 | 隐私政策 |\n|------|------|----------|\n| Tidal API | 访问音乐库、播放列表和目录 | Tidal 隐私政策 |\n| Tidal Auth | OAuth 身份验证 | Tidal 隐私政策 |\n| Upstash | MCP 模式认证令牌存储 | Upstash 隐私政策 |\n\n资料来源：[site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n\n### 数据删除\n\n用户可通过以下方式删除所有本地存储数据：\n\n```bash\nrm -rf ~/.tidal-cli\n```\n\n资料来源：[site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n\n## 服务条款\n\n`site/app/terms/page.tsx` 明确了使用条款：\n\n### 用户责任\n\n- 遵守 Tidal 的服务条款\n- 对账户所有操作负责\n\n### 可接受使用\n\n用户同意不：\n\n- 将 tidal-cli 用于任何非法目的\n- 尝试绕过 Tidal 的访问控制或 DRM\n- 使用服务下载或重新分发受版权保护的内容\n- 进行超出正常使用的过度或自动请求\n\n### 免责声明\n\ntidal-cli 按\"原样\"提供，不提供任何明示或暗示的保证。维护者不保证不间断或无错误的运行。Tidal 可能随时更改其 API，这可能影响功能。\n\n资料来源：[site/app/terms/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/terms/page.tsx)\n\n## 部署流程\n\n### Vercel 部署\n\n站点部署在 Vercel 平台，利用边缘函数提供低延迟的 MCP 服务。\n\n### 部署检查清单\n\n1. 确保 `site/` 目录包含所有必要的配置文件\n2. 配置环境变量（如有）\n3. 通过 GitHub 集成连接到 Vercel\n4. 启用自动部署\n\n## 相关链接\n\n| 资源 | URL |\n|------|-----|\n| 官方网站 | https://tidal-cli.lucaperret.ch |\n| MCP 端点 | https://tidal-cli.lucaperret.ch/api/mcp |\n| GitHub 仓库 | https://github.com/lucaperret/tidal-cli |\n| Smithery 集成 | https://smithery.ai/servers/lucaperret/tidal |\n| ClawHub 集成 | https://clawhub.ai/lucaperret/tidal-cli |\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：lucaperret/tidal-cli\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。\n\n## 1. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | host_targets=mcp_host, claude\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | release_recency=unknown\n\n\n",
"markdown_key": "tidal-cli",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1183583268",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/lucaperret/tidal-cli"
},
{
"evidence_id": "art_9ee9219e0e994ec8ae228f35cc158018",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/lucaperret/tidal-cli#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "tidal-cli 说明书",
"toc": [
"https://github.com/lucaperret/tidal-cli 项目说明书",
"目录",
"项目简介与安装",
"概述",
"系统要求",
"安装流程",
"项目架构",
"核心功能模块",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "be4269e6190924779877e2ab14c5ed11bc9e483d",
"repo_inspection_error": null,
"repo_inspection_files": [
"package.json",
"README.md",
"src/artist.ts",
"src/search.ts",
"src/playlist.ts",
"src/history.ts",
"src/user.ts",
"src/share.ts",
"src/saved.ts",
"src/index.ts",
"src/mix.ts",
"src/track.ts",
"src/types.ts",
"src/album.ts",
"src/search-history.ts",
"src/auth.ts",
"src/recommend.ts",
"src/playback.ts",
"src/session.ts",
"src/library.ts",
"src/__tests__/saved.test.ts",
"src/__tests__/session.test.ts",
"src/__tests__/mix.test.ts",
"src/__tests__/library.test.ts",
"src/__tests__/playlist.test.ts",
"src/__tests__/artist.test.ts",
"src/__tests__/track.test.ts",
"src/__tests__/recommend.test.ts",
"src/__tests__/search-history.test.ts",
"src/__tests__/search.test.ts",
"src/__tests__/auth.test.ts",
"src/__tests__/share.test.ts",
"src/__tests__/album.test.ts"
],
"repo_inspection_verified": true,
"review_reasons": [
"community_discussion_evidence_below_public_threshold"
],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# @lucaperret/tidal-cli - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 @lucaperret/tidal-cli 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`skills/tidal-cli/SKILL.md` Claim：`clm_0004` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`skills/tidal-cli/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `npm install -g @lucaperret/tidal-cli` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `git clone https://github.com/lucaperret/tidal-cli.git` 证据：`README.md` Claim：`clm_0006` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：真实输出质量不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`skills/tidal-cli/SKILL.md` Claim：`clm_0004` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`skills/tidal-cli/SKILL.md` Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0005` supported 0.86\n\n### 现在还不能相信\n\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`CLAUDE.md`, `skills/tidal-cli/SKILL.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`CLAUDE.md`, `skills/tidal-cli/SKILL.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`CLAUDE.md`, `site/app/mcp-lib/redis.ts`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0007` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0008` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`skills/tidal-cli/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：111\n- 重要文件覆盖：33/111\n- 证据索引条目：33\n- 角色 / Skill 条目：1\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 @lucaperret/tidal-cli 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 @lucaperret/tidal-cli 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 @lucaperret/tidal-cli 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 1 个角色 / Skill / 项目文档条目。\n\n- **tidal-cli**（skill）：Control Tidal music streaming from the terminal. Use when the user wants to search Tidal's catalog artists, albums, tracks, videos, playlists , manage playlists create, rename, delete, add/remove tracks , manage library/favorites, play music, explore artist/track info, find similar artists or tracks, get personalized recommendations, or view user profile. Triggers on: music-related requests mentioning Tidal, playlis… 激活提示：当用户任务与“tidal-cli”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/tidal-cli/SKILL.md`\n\n## 证据索引\n\n- 共索引 33 条证据。\n\n- **CLAUDE.md**（documentation）：tidal-cli — TypeScript CLI for Tidal music streaming. Designed for LLM agent automation via OpenClaw. 证据：`CLAUDE.md`\n- **tidal-cli**（documentation）：! npm https://img.shields.io/npm/v/@lucaperret/tidal-cli https://www.npmjs.com/package/@lucaperret/tidal-cli ! CI https://img.shields.io/github/actions/workflow/status/lucaperret/tidal-cli/ci.yml?label=tests https://github.com/lucaperret/tidal-cli/actions ! smithery badge https://smithery.ai/badge/lucaperret/tidal https://smithery.ai/servers/lucaperret/tidal ! License https://img.shields.io/badge/license-MIT-blue.svg LICENSE ! Node https://img.shields.io/badge/node-%3E%3D20-green.svg https://nodejs.org 证据：`README.md`\n- **Package**（package_manifest）：{ \"name\": \"@lucaperret/tidal-cli\", \"version\": \"1.2.4\", \"description\": \"CLI for Tidal music streaming service, designed for LLM agent automation\", \"main\": \"dist/index.js\", \"bin\": { \"tidal-cli\": \"dist/index.js\" }, \"scripts\": { \"build\": \"tsc\", \"dev\": \"tsc --watch\", \"test\": \"vitest run\", \"test:watch\": \"vitest\", \"prepublishOnly\": \"npm run build\" }, \"keywords\": \"tidal\", \"music\", \"cli\", \"streaming\", \"llm\", \"agent\", \"automation\", \"openclaw\", \"playlist\", \"hifi\" , \"author\": \"Luca Perret\", \"license\": \"MIT\", \"homepage\": \"https://github.com/lucaperret/tidal-cli\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/lucaperret/tidal-cli.git\" }, \"bugs\": { \"url\": \"https://github.com/lucaperret/tid… 证据：`package.json`\n- **Package**（package_manifest）：{ \"name\": \"site\", \"version\": \"0.1.0\", \"private\": true, \"scripts\": { \"dev\": \"next dev\", \"prebuild\": \"node scripts/copy-cli-dist.js\", \"build\": \"next build\", \"start\": \"next start\" }, \"dependencies\": { \"@modelcontextprotocol/sdk\": \"^1.26.0\", \"@tidal-music/api\": \"^0.22.0\", \"@tidal-music/auth\": \"^1.6.0\", \"@tidal-music/common\": \"^0.2.0\", \"@upstash/redis\": \"^1.37.0\", \"@vercel/analytics\": \"^2.0.1\", \"framer-motion\": \"^12.38.0\", \"mcp-handler\": \"^1.1.0\", \"next\": \"^16.2.4\", \"react\": \"^19.2.5\", \"react-dom\": \"^19.2.5\", \"zod\": \"^4.4.3\" }, \"devDependencies\": { \"@tailwindcss/postcss\": \"^4.2.4\", \"@types/node\": \"^25.6.0\", \"@types/react\": \"^19.2.14\", \"@types/react-dom\": \"^19.2.3\", \"tailwindcss\": \"^4.2.4\", \"type… 证据：`site/package.json`\n- **tidal-cli**（skill_instruction）：CLI for Tidal music streaming. Search catalog, manage playlists, control library, play tracks, explore artists, discover new music. 证据：`skills/tidal-cli/SKILL.md`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2017\", \"lib\": \"dom\", \"dom.iterable\", \"esnext\" , \"allowJs\": true, \"skipLibCheck\": true, \"strict\": true, \"noEmit\": true, \"esModuleInterop\": true, \"module\": \"esnext\", \"moduleResolution\": \"bundler\", \"resolveJsonModule\": true, \"isolatedModules\": true, \"jsx\": \"react-jsx\", \"incremental\": true, \"plugins\": { \"name\": \"next\" } , \"paths\": { \"@/ \": \"./ \" } }, \"include\": \"next-env.d.ts\", \" / .ts\", \" / .tsx\", \".next/types/ / .ts\", \".next/dev/types/ / .ts\", \" / .mts\" , \"exclude\": \"node modules\" } 证据：`site/tsconfig.json`\n- **Vercel**（structured_config）：{ \"buildCommand\": \"npm run build\", \"outputDirectory\": \".next\", \"framework\": \"nextjs\" } 证据：`site/vercel.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2022\", \"module\": \"commonjs\", \"lib\": \"ES2022\" , \"types\": \"node\" , \"outDir\": \"dist\", \"rootDir\": \"src\", \"strict\": true, \"esModuleInterop\": true, \"skipLibCheck\": true, \"forceConsistentCasingInFileNames\": true, \"resolveJsonModule\": true, \"declaration\": true, \"sourceMap\": true }, \"include\": \"src/ / \" , \"exclude\": \"node modules\", \"dist\" } 证据：`tsconfig.json`\n- **Next.js site**（source_file）：node modules/ dist/ .env .env.local .skill 证据：`.gitignore`\n- **.npmignore**（source_file）：src/ site/ skills/ .ts tsconfig.json .gitignore .env .skill ROADMAP.md 证据：`.npmignore`\n- **See https://help.github.com/articles/ignoring-files/ for more about ignoring files.**（source_file）：See https://help.github.com/articles/ignoring-files/ for more about ignoring files. 证据：`site/.gitignore`\n- **Next.Config**（source_file）：import type { NextConfig } from \"next\"; 证据：`site/next.config.ts`\n- **Postcss.Config**（source_file）：const config = { plugins: { \"@tailwindcss/postcss\": {}, }, }; 证据：`site/postcss.config.mjs`\n- **Album**（source_file）：import { getApiClient, getCountryCode } from './auth'; import type { AlbumInfo, AlbumResult } from './types'; export type { AlbumInfo, AlbumResult }; 证据：`src/album.ts`\n- **Artist**（source_file）：import { getApiClient, getCountryCode } from './auth'; import type { ArtistInfo, ArtistTrack, ArtistAlbum, SimilarArtist, RadioPlaylist } from './types'; export type { ArtistInfo, ArtistTrack, ArtistAlbum, SimilarArtist }; 证据：`src/artist.ts`\n- **Auth**（source_file）：import { installLocalStorage } from './session'; 证据：`src/auth.ts`\n- **History**（source_file）：import { getApiClient, getCountryCode } from './auth'; import type { RecentItem, RecentType } from './types'; export type { RecentItem, RecentType }; 证据：`src/history.ts`\n- **!/usr/bin/env node**（source_file）：// Suppress \"TrueTime is not yet synchronized\" warnings from @tidal-music/auth const originalWarn = console.warn; console.warn = ...args: unknown = { if typeof args 0 === 'string' && args 0 .includes 'TrueTime' return; originalWarn ...args ; }; 证据：`src/index.ts`\n- **Library**（source_file）：import { getApiClient } from './auth'; import type { LibraryResourceType } from './types'; export type { LibraryResourceType }; 证据：`src/library.ts`\n- **Mix**（source_file）：import { getApiClient, getCountryCode } from './auth'; import type { MixCategory, MixItem } from './types'; export type { MixItem }; 证据：`src/mix.ts`\n- **Playback**（source_file）：import { getApiClient } from './auth'; import { exec } from 'child process'; import as fs from 'fs'; import as path from 'path'; import as os from 'os'; import type { PlaybackInfo, PlaybackUrl } from './types'; export type { PlaybackInfo, PlaybackUrl }; 证据：`src/playback.ts`\n- **Playlist**（source_file）：import { getApiClient, getCountryCode } from './auth'; import type { PlaylistInfo } from './types'; export type { PlaylistInfo }; 证据：`src/playlist.ts`\n- **Recommend**（source_file）：import { getApiClient, getCountryCode } from './auth'; import type { MixCategory, RecommendationItem } from './types'; export type { MixCategory, RecommendationItem }; 证据：`src/recommend.ts`\n- **Saved**（source_file）：import { getApiClient } from './auth'; import type { SavedItem, SavedItemType } from './types'; export type { SavedItem, SavedItemType }; 证据：`src/saved.ts`\n- **Search History**（source_file）：import { getApiClient, getCountryCode } from './auth'; import type { SearchHistoryEntry } from './types'; export type { SearchHistoryEntry }; 证据：`src/search-history.ts`\n- **Search**（source_file）：import { getApiClient, getCountryCode } from './auth'; import type { SearchType, SearchResult, SearchSuggestionsResult } from './types'; export type { SearchType, SearchResult, SearchSuggestionsResult }; 证据：`src/search.ts`\n- **Session**（source_file）：import as fs from 'fs'; import as path from 'path'; import as os from 'os'; 证据：`src/session.ts`\n- **Share**（source_file）：import { getApiClient } from './auth'; import type { ShareLink } from './types'; export type { ShareLink }; 证据：`src/share.ts`\n- **Track**（source_file）：import { getApiClient, getCountryCode } from './auth'; import type { TrackInfo, SimilarTrack, RadioPlaylist } from './types'; export type { TrackInfo, SimilarTrack }; 证据：`src/track.ts`\n- **Types**（source_file）：// Shared types for Data functions used by both CLI and MCP server 证据：`src/types.ts`\n- **User**（source_file）：import { getApiClient } from './auth'; import type { UserProfile } from './types'; export type { UserProfile }; 证据：`src/user.ts`\n- **Vitest.Config**（source_file）：import { defineConfig } from 'vitest/config'; 证据：`vitest.config.ts`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`CLAUDE.md`, `README.md`, `package.json`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`CLAUDE.md`, `README.md`, `package.json`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目简介与安装**：importance `high`\n - source_paths: README.md, package.json, CLAUDE.md\n- **系统架构**：importance `high`\n - source_paths: src/index.ts, src/auth.ts, site/app/layout.tsx, CLAUDE.md\n- **搜索与浏览功能**：importance `high`\n - source_paths: src/search.ts, src/artist.ts, src/album.ts, src/track.ts, src/user.ts\n- **播放列表管理**：importance `high`\n - source_paths: src/playlist.ts\n- **媒体库管理**：importance `high`\n - source_paths: src/library.ts, src/saved.ts, src/history.ts, src/search-history.ts\n- **播放系统与质量设置**：importance `medium`\n - source_paths: src/playback.ts, src/share.ts\n- **认证与会话管理**：importance `high`\n - source_paths: src/auth.ts, src/session.ts, site/app/mcp-lib/tidal-oauth.ts, site/app/mcp-lib/constants.ts\n- **发现与推荐系统**：importance `medium`\n - source_paths: src/recommend.ts, src/mix.ts, src/share.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `be4269e6190924779877e2ab14c5ed11bc9e483d`\n- inspected_files: `package.json`, `README.md`, `src/artist.ts`, `src/search.ts`, `src/playlist.ts`, `src/history.ts`, `src/user.ts`, `src/share.ts`, `src/saved.ts`, `src/index.ts`, `src/mix.ts`, `src/track.ts`, `src/types.ts`, `src/album.ts`, `src/search-history.ts`, `src/auth.ts`, `src/recommend.ts`, `src/playback.ts`, `src/session.ts`, `src/library.ts`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 可能修改宿主 AI 配置\n\n- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Evidence: capability.host_targets | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | host_targets=mcp_host, claude\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：lucaperret/tidal-cli\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host, claude\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## 项目专属踩坑\n\n- 可能修改宿主 AI 配置（medium）：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n- 存在评分风险（medium）：风险会影响是否适合普通用户安装。 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/lucaperret/tidal-cli 项目说明书\n\n生成时间：2026-05-13 13:31:09 UTC\n\n## 目录\n\n- [项目简介与安装](#page-1)\n- [系统架构](#page-2)\n- [搜索与浏览功能](#page-3)\n- [播放列表管理](#page-4)\n- [媒体库管理](#page-5)\n- [播放系统与质量设置](#page-6)\n- [认证与会话管理](#page-7)\n- [发现与推荐系统](#page-8)\n- [MCP 服务器集成](#page-9)\n- [Web 端与部署](#page-10)\n\n\n\n## 项目简介与安装\n\n### 相关页面\n\n相关主题：[系统架构](#page-2), [认证与会话管理](#page-7)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n- [site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n- [site/app/terms/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/terms/page.tsx)\n- [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n- [site/app/components/Terminal.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/components/Terminal.tsx)\n \n\n# 项目简介与安装\n\n## 概述\n\ntidal-cli 是一个开源的命令行工具，允许用户通过终端与 Tidal 音乐流媒体服务进行交互。该工具由 Node.js 构建，支持搜索、播放列表管理、音乐库控制等功能，专为个人使用和 LLM 代理自动化设计。\n\n**核心特点：**\n\n- 支持搜索艺术家、专辑、曲目、视频和播放列表\n- 完整的播放列表管理功能\n- 音乐播放控制\n- 发现和推荐功能\n- JSON 输出支持，便于脚本和自动化\n- MCP Server 集成，可与 Claude Desktop 等 AI 代理配合使用\n\n资料来源：[site/app/terms/page.tsx:28-31]()\n\n---\n\n## 系统要求\n\n| 要求项 | 最低版本 | 说明 |\n|--------|----------|------|\n| Node.js | >= 20 | 必须安装 Node.js 运行环境 |\n| Tidal 账户 | 必需 | 需要有效的 Tidal 账户进行认证 |\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n---\n\n## 安装流程\n\n### 全局安装\n\n通过 npm 进行全局安装：\n\n```bash\nnpm install -g @lucaperret/tidal-cli\n```\n\n资料来源：[site/app/page.tsx:72-76]()\n\n### 认证配置\n\n安装完成后，需要进行一次性认证：\n\n```bash\ntidal-cli auth\n```\n\n该命令会打开浏览器进行 Tidal 授权，认证成功后用户 ID 将显示在终端中。\n\n认证完成后，所有后续操作无需交互式操作，工具会自动处理 token 刷新。\n\n资料来源：[site/app/page.tsx:72-76]()\n\n---\n\n## 项目架构\n\n### 组件架构\n\n```mermaid\ngraph TD\n A[用户终端] --> B[tidal-cli CLI]\n B --> C[本地会话存储
~/.tidal-cli/session.json]\n B --> D[Tidal API
openapi.tidal.com]\n D --> E[Tidal 服务]\n \n F[AI Agent
Claude Desktop] --> G[MCP Server
tidal-cli.lucaperret.ch/api/mcp]\n G --> H[Redis 加密存储
Upstash]\n G --> D\n \n style A fill:#e1f5fe\n style E fill:#f3e5f5\n style G fill:#fff3e0\n```\n\n### 数据流向\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant CLI as tidal-cli\n participant Tidal as Tidal API\n participant Session as 本地会话\n\n User->>CLI: tidal-cli auth\n CLI->>Tidal: OAuth 授权请求\n Tidal->>User: 浏览器授权页面\n User->>Tidal: 确认授权\n Tidal->>CLI: 返回 Access Token\n CLI->>Session: 存储会话信息\n Session-->>CLI: 确认存储\n CLI-->>User: 认证成功\n\n User->>CLI: tidal-cli search track \"xxx\"\n CLI->>Session: 读取 Token\n CLI->>Tidal: API 请求\n Tidal-->>CLI: 搜索结果\n CLI-->>User: 显示结果\n```\n\n资料来源：[site/app/privacy/page.tsx:48-54]()\n\n---\n\n## 核心功能模块\n\n| 模块 | 功能描述 | 示例命令 |\n|------|----------|----------|\n| **搜索** | 搜索艺术家、专辑、曲目、视频、播放列表 | `tidal-cli search track \"Teardrop\"` |\n| **艺术家** | 获取艺术家信息、专辑、相似艺术家 | `tidal-cli artist info ` |\n| **专辑** | 专辑详情、条形码查询 | `tidal-cli album info ` |\n| **曲目** | 曲目详情、相似曲目、ISRC 查询 | `tidal-cli track info ` |\n| **播放列表** | 列表、创建、添加曲目/专辑 | `tidal-cli playlist list` |\n| **播放** | 播放控制、音质选择 | `tidal-cli playback play ` |\n| **发现** | 推荐、混音、播放历史 | `tidal-cli recommend` |\n| **保存** | 稍后保存、分享链接 | `tidal-cli saved list` |\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n---\n\n## JSON 输出模式\n\n所有命令支持 JSON 输出格式，便于脚本处理和自动化流程：\n\n```bash\n# 搜索结果 JSON 输出\ntidal-cli --json search track \"Around the World\"\n\n# 播放列表 JSON 输出\ntidal-cli --json playlist list\n\n# 艺术家信息 JSON 输出\ntidal-cli --json artist similar 8992\n```\n\nJSON 输出模式的特点：\n\n- 每个命令都支持 `--json` 参数\n- 结构化数据便于程序解析\n- 适合 LLM 代理和自动化脚本使用\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n---\n\n## MCP Server 集成\n\ntidal-cli 可作为远程 MCP 服务器与 AI 代理集成：\n\n### 集成地址\n\n```\nhttps://tidal-cli.lucaperret.ch/api/mcp\n```\n\n### Claude Desktop 配置\n\n1. 打开 Settings → Connectors → Add custom connector\n2. 添加上述 MCP 服务器地址\n3. 连接后即可通过自然语言控制 Tidal\n\n```mermaid\ngraph LR\n A[Claude Desktop] -->|MCP 协议| B[tidal-cli MCP Server]\n B --> C[Tidal API]\n C --> D[Tidal 服务]\n \n B -->|加密存储| E[Upstash Redis]\n \n style A fill:#e1f5fe\n style E fill:#fff3e0\n```\n\n资料来源：[site/app/page.tsx:38-48]()\n\n---\n\n## 隐私与数据存储\n\n### CLI 模式\n\n在命令行模式下，tidal-cli 直接与 Tidal API 服务器通信：\n\n- **认证令牌存储位置**：`~/.tidal-cli/session.json`\n- **数据流向**：设备 → Tidal API（无中间服务器）\n- **数据收集**：不收集、存储或传输任何个人数据\n\n资料来源：[site/app/privacy/page.tsx:48-54]()\n\n### MCP Server 模式\n\n当作为 MCP 连接器使用时：\n\n- 认证令牌存储在 Upstash 托管的加密 Redis 数据库中\n- 数据存储在 Vercel 平台上\n\n资料来源：[site/app/privacy/page.tsx:55-58]()\n\n---\n\n## 快速入门命令\n\n```bash\n# 安装 tidal-cli\nnpm install -g @lucaperret/tidal-cli\n\n# 认证\ntidal-cli auth\n\n# 搜索曲目\ntidal-cli search track \"Around the World\"\n\n# 获取艺术家详情\ntidal-cli artist info 8992\n\n# 播放曲目\ntidal-cli playback play 5756235\n\n# 列出播放列表\ntidal-cli playlist list\n\n# 获取推荐\ntidal-cli recommend\n\n# 查看播放历史\ntidal-cli history tracks\n```\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n---\n\n## 许可与开源\n\ntidal-cli 采用 MIT 许可证开源，源代码托管在 GitHub 上：\n\n- **开源仓库**：[github.com/lucaperret/tidal-cli](https://github.com/lucaperret/tidal-cli)\n- **许可证**：MIT License\n- **项目维护者**：Luca Perret\n\n该项目为独立开发工具，与 Tidal 无附属关系。\n\n资料来源：[site/app/terms/page.tsx:80-97]()\n\n---\n\n## 相关链接\n\n| 资源 | 链接 |\n|------|------|\n| GitHub 仓库 | https://github.com/lucaperret/tidal-cli |\n| 官方网站 | https://tidal-cli.lucaperret.ch |\n| Smithery 集成 | https://smithery.ai/servers/lucaperret/tidal |\n| ClawHub | https://clawhub.ai/lucaperret/tidal-cli |\n| Tidal 服务 | https://tidal.com |\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目简介与安装](#page-1), [认证与会话管理](#page-7), [MCP 服务器集成](#page-9)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n- [site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n- [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n- [site/app/terms/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/terms/page.tsx)\n- [site/app/components/Terminal.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/components/Terminal.tsx)\n \n\n# 系统架构\n\ntidal-cli 是一个开源的命令行工具，用于与 Tidal 音乐流媒体服务进行交互。该项目采用模块化架构设计，同时支持命令行直接使用和 MCP（Model Context Protocol）服务器模式集成到 AI 助手（如 Claude）中。\n\n## 1. 整体架构概览\n\ntidal-cli 项目包含三个主要组件：\n\n| 组件 | 说明 | 部署位置 |\n|------|------|----------|\n| CLI 工具 | 命令行界面，直接与用户交互 | 用户本地设备 |\n| MCP 服务器 | 远程 MCP 连接器，供 AI 代理调用 | Vercel 服务端点 |\n| Web 前端 | 文档和 Landing Page | Vercel/Site |\n\n资料来源：[site/app/page.tsx:1-50]()\n\n```mermaid\ngraph TB\n subgraph 用户端\n CLI[tidal-cli CLI]\n end\n \n subgraph 云端服务\n MCP[MCP Server
tidal-cli.lucaperret.ch/api/mcp]\n Web[Web Frontend
tidal-cli.lucaperret.ch]\n end\n \n subgraph 第三方服务\n TidalAPI[Tidal API
openapi.tidal.com]\n TidalAuth[Tidal Auth
login.tidal.com
auth.tidal.com]\n Upstash[Upstash Redis
Token 存储]\n end\n \n CLI --> TidalAPI\n CLI --> TidalAuth\n MCP --> TidalAPI\n MCP --> TidalAuth\n MCP --> Upstash\n Web --> MCP\n```\n\n## 2. CLI 工具架构\n\n### 2.1 安装与入口\n\nCLI 工具通过 npm 全局安装：\n\n```bash\nnpm install -g @lucaperret/tidal-cli\n```\n\n安装后可通过 `tidal-cli` 命令调用，支持全局参数 `--json` 输出 JSON 格式结果。\n\n资料来源：[README.md:1-30]()\n\n### 2.2 命令模块\n\nCLI 工具按功能划分为以下命令模块：\n\n| 命令模块 | 功能描述 | 示例命令 |\n|----------|----------|----------|\n| `search` | 搜索艺术家、专辑、曲目、视频、播放列表 | `tidal-cli search track \"Teardrop\"` |\n| `artist` | 获取艺术家信息和相关资源 | `tidal-cli artist info ` |\n| `album` | 专辑信息和条形码查询 | `tidal-cli album info ` |\n| `track` | 曲目详情和相似推荐 | `tidal-cli track info ` |\n| `playlist` | 播放列表管理 | `tidal-cli playlist list` |\n| `playback` | 播放控制 | `tidal-cli playback play ` |\n| `library` | 个人音乐库管理 | `tidal-cli library favorite-tracks` |\n| `history` | 播放历史和搜索历史 | `tidal-cli history tracks` |\n| `saved` | 稍后播放列表管理 | `tidal-cli saved list` |\n| `recommend` | 音乐推荐和混音 | `tidal-cli recommend` |\n| `share` | 创建分享链接 | `tidal-cli share track ` |\n\n资料来源：[README.md:50-120]()\n\n## 3. MCP 服务器架构\n\n### 3.1 连接配置\n\nMCP 服务器作为远程连接器运行于 `https://tidal-cli.lucaperret.ch/api/mcp`，可与 Claude Desktop 或 claude.ai 集成。\n\n资料来源：[site/app/page.tsx:15-25]()\n\n```mermaid\ngraph LR\n A[Claude Desktop
或 claude.ai] -->|MCP Protocol| B[MCP Connector]\n B --> C[Tidal API]\n B --> D[Upstash Redis
Token 存储]\n```\n\n### 3.2 可用工具\n\nMCP 服务器提供约 40 个工具，涵盖以下功能类别：\n\n- 搜索（Search）\n- 播放列表管理（Playlists）\n- 音乐库访问（Library）\n- 推荐服务（Recommendations）\n- 稍后播放（Save-for-later）\n- 分享功能（Sharing）\n\n资料来源：[site/app/page.tsx:45-55]()\n\n### 3.3 认证流程\n\nMCP 服务器模式下的认证流程：\n\n1. 用户通过 OAuth 连接 Tidal 账户\n2. 认证令牌存储于 Upstash Redis 数据库（加密存储）\n3. MCP 服务器使用存储的令牌访问 Tidal API\n\n资料来源：[site/app/privacy/page.tsx:60-80]()\n\n## 4. Web 前端架构\n\n### 4.1 技术栈\n\nWeb 前端基于 Next.js 构建，包含以下页面：\n\n| 页面路径 | 功能 |\n|----------|------|\n| `/` | Landing Page，包含安装说明和功能展示 |\n| `/privacy` | 隐私政策页面 |\n| `/terms` | 服务条款页面 |\n| `/api/mcp` | MCP 服务器端点 |\n\n资料来源：[site/app/page.tsx:1-30]()\n资料来源：[site/app/privacy/page.tsx:1-30]()\n资料来源：[site/app/terms/page.tsx:1-30]()\n\n### 4.2 组件结构\n\n```mermaid\ngraph TD\n Layout[layout.tsx
根布局] --> Nav[Nav.tsx
导航栏]\n Layout --> Page[page.tsx
主页内容]\n Page --> Terminal[Terminal.tsx
终端模拟组件]\n Page --> Footer[页脚]\n```\n\nWeb 前端主要使用 Framer Motion 实现动画效果，采用 Tidal 品牌配色方案。\n\n资料来源：[site/app/components/Terminal.tsx:1-30]()\n资料来源：[site/app/components/Nav.tsx:1-20]()\n\n## 5. 认证与数据存储\n\n### 5.1 CLI 模式下的数据存储\n\n在命令行模式下使用时，认证令牌存储在用户本地：\n\n```\n~/.tidal-cli/session.json\n```\n\n资料来源：[site/app/privacy/page.tsx:45-55]()\n\n### 5.2 MCP 模式下的数据存储\n\n| 存储类型 | 位置 | 说明 |\n|----------|------|------|\n| 认证令牌 | Upstash Redis（Vercel） | 加密存储 |\n| 传输协议 | 直接与 Tidal API 通信 | 不经过中间服务器 |\n\n资料来源：[site/app/privacy/page.tsx:65-75]()\n\n### 5.3 OAuth 流程\n\ntidal-cli 使用 OAuth 2.0 与 Tidal 进行认证集权，支持以下端点：\n\n| 用途 | 端点 |\n|------|------|\n| 用户登录 | `login.tidal.com` |\n| OAuth 授权 | `auth.tidal.com` |\n| 音乐 API | `openapi.tidal.com` |\n\n资料来源：[site/app/privacy/page.tsx:85-100]()\n\n## 6. 数据流\n\n### 6.1 CLI 命令执行流程\n\n```mermaid\nsequenceDiagram\n participant User\n participant CLI\n participant TidalAuth\n participant TidalAPI\n \n User->>CLI: tidal-cli search track \"Teardrop\"\n CLI->>TidalAuth: 验证本地 token\n alt Token 有效\n CLI->>TidalAPI: 搜索请求\n TidalAPI-->>CLI: 搜索结果\n CLI-->>User: 显示结果\n else Token 无效或过期\n CLI->>TidalAuth: 发起 OAuth 流程\n TidalAuth-->>User: 浏览器授权\n User->>TidalAuth: 确认授权\n TidalAuth-->>CLI: 新 token\n CLI->>TidalAPI: 搜索请求\n TidalAPI-->>CLI: 搜索结果\n CLI-->>User: 显示结果\n end\n```\n\n### 6.2 MCP 集成流程\n\n```mermaid\nsequenceDiagram\n participant User\n participant Claude\n participant MCP\n participant Redis\n participant TidalAPI\n \n User->>Claude: 请求查询音乐\n Claude->>MCP: 调用搜索工具\n MCP->>Redis: 获取认证令牌\n Redis-->>MCP: Token\n MCP->>TidalAPI: API 请求\n TidalAPI-->>MCP: 音乐数据\n MCP-->>Claude: 工具响应\n Claude-->>User: 自然语言回复\n```\n\n## 7. 服务部署\n\n### 7.1 部署平台\n\n| 组件 | 托管平台 |\n|------|----------|\n| Web 前端 | Vercel |\n| MCP 服务器 | Vercel Serverless Functions |\n| Token 存储 | Upstash Redis |\n\n### 7.2 可用集成平台\n\ntidal-cli MCP 连接器可在多个平台使用：\n\n- Claude Desktop / claude.ai（主要）\n- Smithery AI\n- ClawHub\n\n资料来源：[site/app/page.tsx:35-45]()\n\n## 8. 安全与隐私\n\n### 8.1 数据收集政策\n\ntidal-cli 本身不收集、存储或传输任何个人数据到第三方服务器。所有用户数据均直接与 Tidal 服务器交互。\n\n资料来源：[site/app/privacy/page.tsx:35-45]()\n\n### 8.2 数据删除\n\n| 使用模式 | 删除方式 |\n|----------|----------|\n| CLI 模式 | `rm -rf ~/.tidal-cli` |\n| MCP 模式 | 通过 Tidal 账户设置撤销访问权限 |\n\n资料来源：[site/app/privacy/page.tsx:130-145]()\n\n## 9. 开源许可\n\ntidal-cli 采用 MIT 许可证开源，源代码托管于 GitHub：\n\n- 仓库地址：`github.com/lucaperret/tidal-cli`\n- 许可证：`MIT License`\n\n资料来源：[site/app/terms/page.tsx:110-130]()\n\n## 10. 系统要求\n\n| 要求 | 版本 |\n|------|------|\n| Node.js | >= 20 |\n| Tidal 账户 | 需要 |\n\n资料来源：[README.md:25-30]()\n\n---\n\n\n\n## 搜索与浏览功能\n\n### 相关页面\n\n相关主题：[播放系统与质量设置](#page-6), [发现与推荐系统](#page-8)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/search.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/search.ts)\n- [src/artist.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/artist.ts)\n- [src/album.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/album.ts)\n- [src/track.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/track.ts)\n- [src/user.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/user.ts)\n \n\n# 搜索与浏览功能\n\ntidal-cli 提供了完整的搜索与浏览功能，允许用户通过命令行接口访问 Tidal 音乐服务中的各类资源。这些功能涵盖了艺术家、专辑、曲目、视频、播放列表以及编辑推荐等多个维度的内容发现。\n\n## 功能概述\n\n搜索与浏览模块是 tidal-cli 的核心功能之一，提供了对 Tidal 音乐目录的全面访问能力。用户可以通过结构化的命令查询各类媒体资源，并获取详细的元数据信息。\n\n### 核心能力\n\n该模块支持以下主要功能领域：\n\n- **搜索功能**：按类型搜索艺术家、专辑、曲目、视频、播放列表\n- **艺术家浏览**：获取艺术家信息、热门曲目、专辑列表、相似推荐\n- **专辑浏览**：查看专辑详情、曲目列表、条形码查询\n- **曲目浏览**：获取曲目信息、ISRC 识别、相似推荐\n- **用户历史**：查看和管理搜索历史、播放历史\n\n## 搜索功能详解\n\n### 搜索命令结构\n\ntidal-cli 的搜索功能采用统一的命令格式，支持多种内容类型的搜索。\n\n```bash\ntidal-cli search <类型> <查询词>\n```\n\n### 支持的搜索类型\n\n| 类型 | 说明 | 示例命令 |\n|------|------|----------|\n| `artist` | 搜索艺术家 | `tidal-cli search artist \"Gorillaz\"` |\n| `album` | 搜索专辑 | `tidal-cli search album \"Mezzanine\"` |\n| `track` | 搜索曲目 | `tidal-cli search track \"Teardrop\"` |\n| `video` | 搜索视频 | `tidal-cli search video \"Stylo\"` |\n| `playlist` | 搜索播放列表 | `tidal-cli search playlist \"Electronic\"` |\n| `suggest` | 自动建议 | `tidal-cli search suggest \"daft punk\"` |\n| `editorial` | 编辑推荐 | `tidal-cli search editorial \"indie rock\"` |\n\n### 搜索历史管理\n\n系统会记录用户的搜索历史，并提供管理功能：\n\n```bash\ntidal-cli search history # 查看搜索历史\ntidal-cli search history-delete # 删除单条历史记录\ntidal-cli search history-clear # 清空所有历史记录\n```\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## 艺术家浏览\n\n艺术家模块提供对艺术家完整信息的访问能力。\n\n### 可用命令\n\n| 命令 | 功能描述 |\n|------|----------|\n| `tidal-cli artist info ` | 获取艺术家基本信息 |\n| `tidal-cli artist tracks ` | 获取艺术家的热门曲目 |\n| `tidal-cli artist albums ` | 获取艺术家的专辑列表 |\n| `tidal-cli artist similar ` | 查找相似艺术家 |\n| `tidal-cli artist radio ` | 获取艺术家电台（推荐曲目） |\n\n### 数据获取流程\n\n```mermaid\ngraph TD\n A[输入 artist 命令] --> B[解析命令参数]\n B --> C[调用 Tidal API]\n C --> D{查询类型}\n D -->|info| E[获取艺术家详情]\n D -->|tracks| F[获取热门曲目]\n D -->|albums| G[获取专辑列表]\n D -->|similar| H[获取相似艺术家]\n D -->|radio| I[生成艺术家电台]\n E --> J[格式化输出]\n F --> J\n G --> J\n H --> J\n I --> J\n```\n\n## 专辑浏览\n\n专辑模块支持专辑信息和曲目列表的查询。\n\n### 可用命令\n\n| 命令 | 功能描述 |\n|------|----------|\n| `tidal-cli album info ` | 获取专辑详细信息 |\n| `tidal-cli album barcode ` | 通过 EAN 条形码查询专辑 |\n\n### 专辑信息内容\n\n专辑信息通常包含以下内容：\n\n- 专辑标题和艺术家名称\n- 发行日期\n- 曲目数量\n- 专辑封面\n- 音频质量信息\n\n## 曲目浏览\n\n曲目模块提供曲目级别的详细信息和元数据。\n\n### 可用命令\n\n| 命令 | 功能描述 |\n|------|----------|\n| `tidal-cli track info ` | 获取曲目详细信息 |\n| `tidal-cli track similar ` | 查找相似曲目 |\n| `tidal-cli track isrc ` | 通过 ISRC 码识别曲目 |\n| `tidal-cli track radio ` | 获取基于该曲目的电台 |\n\n### ISRC 查询功能\n\nISRC（国际标准录音代码）是曲目的唯一标识符，支持精确的曲目识别：\n\n```bash\ntidal-cli track isrc \n```\n\n此功能允许用户通过已知的 ISRC 码快速定位特定曲目，适用于从其他来源获取的曲目元数据。\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## 发现与推荐\n\n### 推荐功能\n\ntidal-cli 提供个性化推荐功能，支持多种推荐类型：\n\n```bash\ntidal-cli recommend # 获取所有推荐分类\ntidal-cli recommend --type daily # 每日推荐\ntidal-cli recommend --type discovery # 发现推荐\ntidal-cli recommend --type new-release # 新发行\ntidal-cli recommend --type offline # 离线推荐\n```\n\n### Mix 内容\n\n获取 Mix 详情：\n\n```bash\ntidal-cli mix items --type daily\n```\n\n支持的 Mix 类型包括 `daily`、`discovery`、`new-release`、`offline`。\n\n### 用户历史\n\n查看个人使用历史：\n\n```bash\ntidal-cli history tracks # 播放过的曲目\ntidal-cli history albums # 播放过的专辑\ntidal-cli history artists # 播放过的艺术家\n```\n\n### 用户资料\n\n获取当前登录用户的信息：\n\n```bash\ntidal-cli user profile\n```\n\n此命令返回用户账户的详细信息，包括订阅状态、用户 ID 等。\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## JSON 输出\n\n所有搜索和浏览命令支持 JSON 格式输出，便于程序化处理和脚本集成。\n\n### 使用方式\n\n在命令前添加 `--json` 标志：\n\n```bash\ntidal-cli --json search track \"Around the World\"\ntidal-cli --json playlist list\ntidal-cli --json artist similar 8992\n```\n\n### 输出格式\n\nJSON 输出包含完整的 API 响应数据，结构化呈现所有可用字段。\n\n## 命令索引表\n\n### 搜索命令\n\n| 命令 | 描述 |\n|------|------|\n| `search artist ` | 搜索艺术家 |\n| `search album ` | 搜索专辑 |\n| `search track ` | 搜索曲目 |\n| `search video ` | 搜索视频 |\n| `search playlist ` | 搜索播放列表 |\n| `search suggest ` | 自动建议 |\n| `search editorial ` | 编辑推荐 |\n| `search history` | 查看搜索历史 |\n| `search history-delete ` | 删除历史记录 |\n| `search history-clear` | 清空历史记录 |\n\n### 浏览命令\n\n| 命令 | 描述 |\n|------|------|\n| `artist info ` | 艺术家详情 |\n| `artist tracks ` | 艺术家曲目 |\n| `artist albums ` | 艺术家专辑 |\n| `artist similar ` | 相似艺术家 |\n| `artist radio ` | 艺术家电台 |\n| `album info ` | 专辑详情 |\n| `album barcode ` | 条形码查询 |\n| `track info ` | 曲目详情 |\n| `track similar ` | 相似曲目 |\n| `track isrc ` | ISRC 查询 |\n| `track radio ` | 曲目电台 |\n| `user profile` | 用户资料 |\n\n### 发现命令\n\n| 命令 | 描述 |\n|------|------|\n| `recommend` | 获取所有推荐 |\n| `recommend --type ` | 指定类型推荐 |\n| `mix items --type ` | Mix 内容 |\n| `history tracks` | 播放历史-曲目 |\n| `history albums` | 播放历史-专辑 |\n| `history artists` | 播放历史-艺术家 |\n\n## 技术架构\n\n### 模块组织\n\n搜索与浏览功能分布在以下核心模块中：\n\n- **src/search.ts**：搜索命令实现，支持多种类型的搜索查询\n- **src/artist.ts**：艺术家相关功能，包括信息、曲目、专辑、相似推荐\n- **src/album.ts**：专辑浏览和条形码查询功能\n- **src/track.ts**：曲目查询、ISRC 识别、相似曲目\n- **src/user.ts**：用户资料和历史记录管理\n\n### API 交互\n\n所有搜索和浏览功能通过 Tidal API 进行数据获取，命令行工具负责：\n\n1. 解析用户输入的命令和参数\n2. 调用相应的 Tidal API 端点\n3. 格式化并输出返回的数据\n4. 支持 JSON 和人类可读两种输出格式\n\n## 最佳实践\n\n### 高效搜索\n\n- 使用精确的曲目名称可获得更准确的结果\n- 搜索专辑时使用完整的专辑名称\n- ISRC 查询是定位精确曲目的最可靠方式\n\n### 结果处理\n\n- 使用 `--json` 标志便于程序化处理\n- 结合 shell 管道处理大规模数据\n- 利用播放历史功能追踪音乐偏好\n\n### 错误处理\n\n- 确保 Tidal 账户已通过 `tidal-cli auth` 认证\n- 检查网络连接状况\n- 确认 API 配额未超限\n\n---\n\n\n\n## 播放列表管理\n\n### 相关页面\n\n相关主题：[搜索与浏览功能](#page-3), [媒体库管理](#page-5)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/playlist.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/playlist.ts)\n- [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n \n\n# 播放列表管理\n\ntidal-cli 的播放列表管理功能提供了一套完整的命令行接口，用于在 Tidal 音乐平台上创建、编辑和操作个人播放列表。该模块支持查看列表详情、添加/移除曲目、重命名、删除以及生成分享链接等核心操作。\n\n## 功能概述\n\n播放列表管理模块的核心职责包括：\n\n- **列表查询**：查看用户所有播放列表及其基本信息\n- **创建与删除**：新建播放列表或删除已有列表\n- **曲目管理**：向播放列表添加或移除曲目\n- **编辑操作**：重命名播放列表\n- **分享功能**：生成可公开访问的分享链接\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## 命令行接口\n\n### 播放列表查询\n\n| 命令 | 说明 |\n|------|------|\n| `tidal-cli playlist list` | 列出用户所有播放列表 |\n| `tidal-cli playlist info ` | 获取指定播放列表的详细信息 |\n\n### 播放列表操作\n\n| 命令 | 说明 |\n|------|------|\n| `tidal-cli playlist create ` | 创建新播放列表 |\n| `tidal-cli playlist rename --name ` | 重命名播放列表 |\n| `tidal-cli playlist delete ` | 删除播放列表 |\n| `tidal-cli playlist share ` | 生成播放列表分享链接 |\n\n### 曲目管理\n\n| 命令 | 说明 |\n|------|------|\n| `tidal-cli playlist add --track-id ` | 向播放列表添加曲目 |\n| `tidal-cli playlist remove --track-id ` | 从播放列表移除曲目 |\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## JSON 输出支持\n\n所有播放列表命令均支持 `--json` 参数，可直接用于程序化处理：\n\n```bash\ntidal-cli --json playlist list\ntidal-cli --json playlist info \n```\n\nJSON 输出格式示例：\n\n```json\n[{\n \"id\": \"a20fff4a-...\",\n \"name\": \"Late Night Electronic\",\n \"numberOfItems\": 24,\n \"createdAt\": \"2025-04-20T...\"\n}, ...]\n```\n\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n## 使用流程图\n\n```mermaid\ngraph TD\n A[开始] --> B{选择操作}\n B -->|查看列表| C[playlist list]\n B -->|创建列表| D[playlist create]\n B -->|管理曲目| E[playlist add/remove]\n B -->|其他操作| F[info/rename/delete/share]\n \n C --> G[显示播放列表]\n D --> H[输入列表名称]\n H --> I[创建成功]\n E --> J[输入播放列表ID和曲目ID]\n J --> K[操作完成]\n F --> L[执行相应操作]\n \n G --> M[结束]\n I --> M\n K --> M\n L --> M\n```\n\n## 典型使用场景\n\n### 创建并填充播放列表\n\n```bash\n# 1. 创建新播放列表\ntidal-cli playlist create \"My Favorites\"\n\n# 2. 搜索曲目获取ID\ntidal-cli search track \"Teardrop\"\n\n# 3. 添加曲目到播放列表\ntidal-cli playlist add --track-id \n```\n\n### 查看和管理已有列表\n\n```bash\n# 查看所有播放列表\ntidal-cli playlist list\n\n# 查看特定列表详情\ntidal-cli playlist info \n\n# 重命名列表\ntidal-cli playlist rename --name \"New Name\"\n\n# 移除不需要的曲目\ntidal-cli playlist remove --track-id \n```\n\n## 数据存储\n\ntidal-cli 将用户认证信息和会话数据存储在本地 `~/.tidal-cli` 目录中。播放列表数据通过 Tidal API 实时获取，不在本地缓存。\n\n如需清除所有本地数据（包括播放列表相关的认证信息）：\n\n```bash\nrm -rf ~/.tidal-cli\n```\n\n资料来源：[site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n\n## 与 MCP 集成\n\n播放列表管理功能可通过 MCP（Model Context Protocol）协议供 AI 代理调用：\n\n```\ntidal-cli search history\ntidal-cli library favorite-playlists\n```\n\nMCP 端点地址：`https://tidal-cli.lucaperret.ch/api/mcp`\n\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n---\n\n\n\n## 媒体库管理\n\n### 相关页面\n\n相关主题：[播放列表管理](#page-4), [播放系统与质量设置](#page-6)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n- [src/library.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/library.ts) — 核心媒体库模块\n- [src/saved.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/saved.ts) — 稍后再听与收藏管理\n- [src/history.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/history.ts) — 播放历史记录\n- [src/search-history.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/search-history.ts) — 搜索历史管理\n \n\n# 媒体库管理\n\ntidal-cli 的媒体库管理模块为用户提供了一套完整的个人音乐库访问与操作接口。该模块涵盖了发现推荐、播放历史、搜索历史、收藏管理以及个人资料查询等核心功能。通过命令行界面，用户可以高效地管理与 Tidal 账户关联的所有媒体资源，无需依赖图形界面即可完成复杂的媒体库操作。\n\n## 功能架构概览\n\n媒体库管理功能由四个主要子模块组成，分别负责不同的管理职责。这些模块之间相互协作，共同构成了 tidal-cli 的完整媒体库管理体系。\n\n```mermaid\ngraph TD\n A[媒体库管理] --> B[library.ts]\n A --> C[saved.ts]\n A --> D[history.ts]\n A --> E[search-history.ts]\n \n B --> F[发现推荐]\n B --> G[用户资料]\n \n C --> H[稍后再听]\n C --> I[分享链接]\n \n D --> J[播放历史]\n \n E --> K[搜索历史]\n```\n\n## 发现与推荐系统\n\ntidal-cli 提供了强大的音乐发现功能，帮助用户探索 Tidal 平台上的新内容。该功能支持多种推荐类型和播放列表生成。\n\n### 推荐类型\n\n系统支持三种主要的推荐模式，每种模式针对不同的用户场景：\n\n| 推荐类型 | 命令参数 | 说明 |\n|---------|---------|------|\n| 每日推荐 | `--type daily` | 基于用户音乐品味的每日个性化推荐 |\n| 发现推荐 | `--type discovery` | 探索用户可能喜欢但尚未听过的新音乐 |\n| 新发行 | `--type new-release` | 最近上架的新专辑和新单曲 |\n| 离线推荐 | `--type offline` | 可供离线下载的推荐内容 |\n\n```bash\ntidal-cli recommend # 获取所有推荐分类\ntidal-cli recommend --type daily # 仅获取每日推荐\ntidal-cli mix items --type daily # 查看特定推荐中的曲目\n```\n\n### 播放列表电台\n\n除了固定的推荐列表外，tidal-cli 还支持动态播放列表电台功能。这种模式会根据用户当前播放的内容，实时生成类似风格的播放列表。\n\n```bash\ntidal-cli artist radio # 获取艺术家电台\ntidal-cli track radio # 获取歌曲电台\n```\n\n## 播放历史记录\n\n播放历史模块允许用户查看和管理自己的音乐收听记录。该功能支持多种内容类型的历史查询。\n\n### 历史查询命令\n\n```bash\ntidal-cli history tracks # 查看播放过的歌曲历史\ntidal-cli history albums # 查看播放过的专辑历史\ntidal-cli history artists # 查看播放过的艺术家历史\n```\n\n### 历史记录数据结构\n\n播放历史记录包含以下关键信息：\n\n| 字段 | 说明 |\n|-----|------|\n| 播放时间戳 | 记录歌曲何时被播放 |\n| 内容类型 | 歌曲、专辑或艺术家 |\n| 内容标识 | 对应的 Tidal ID |\n| 播放时长 | 实际播放的时长信息 |\n\n历史数据通过 Tidal API 的 `user/history` 端点获取，支持分页查询以便处理大量历史记录。\n\n## 搜索历史管理\n\ntidal-cli 提供了完整的搜索历史管理功能，帮助用户追踪和管理过往的搜索记录。\n\n### 搜索历史操作\n\n```bash\ntidal-cli search history # 查看最近的搜索记录\ntidal-cli search history-delete # 删除单条搜索记录\ntidal-cli search history-clear # 清除所有搜索历史\n```\n\n### 数据存储位置\n\n搜索历史记录存储在本地配置目录中：\n\n- **存储路径**: `~/.tidal-cli/search-history.json`\n- **数据格式**: JSON 数组，每条记录包含搜索关键词和时间戳\n\n## 收藏与稍后再听\n\n`saved.ts` 模块实现了\"稍后再听\"（Saved for Later）功能，这是 tidal-cli 中最常用的媒体库管理功能之一。用户可以将任意媒体内容添加到稍后再听列表中稍后播放。\n\n### 收藏管理命令\n\n```bash\ntidal-cli saved list # 列出所有收藏内容\ntidal-cli saved add --type tracks --id # 添加歌曲到收藏\ntidal-cli saved remove --type albums --id # 从收藏中移除专辑\n```\n\n### 支持的媒体类型\n\n| 类型参数 | 说明 |\n|---------|------|\n| `tracks` | 单曲歌曲 |\n| `albums` | 完整专辑 |\n| `artists` | 艺术家页面 |\n| `playlists` | 播放列表 |\n| `videos` | 音乐视频 |\n\n## 分享功能\n\ntidal-cli 内置了社交分享功能，允许用户为任意媒体内容生成公开分享链接。\n\n### 分享命令\n\n```bash\ntidal-cli share track # 生成歌曲分享链接\ntidal-cli share album # 生成专辑分享链接\n```\n\n分享链接会调用 Tidal API 生成临时或永久的公开访问地址，接收方无需登录即可预览或播放分享的内容（受 Tidal 服务条款限制）。\n\n## 用户资料查询\n\n通过用户资料命令，用户可以查看与当前账户相关的完整信息。\n\n```bash\ntidal-cli user profile # 查看当前用户资料\n```\n\n### 用户资料包含的信息\n\n- **账户类型**: Free、HiFi 或 HiFi Plus 订阅等级\n- **用户 ID**: Tidal 平台唯一标识符\n- **账户状态**: 有效、过期等状态信息\n- **配额信息**: 剩余的下载配额或离线播放限额\n\n## 数据流与交互\n\n```mermaid\nsequenceDiagram\n participant User as 用户终端\n participant CLI as tidal-cli CLI\n participant API as Tidal API\n participant Store as 本地存储\n\n User->>CLI: 执行媒体库命令\n CLI->>API: 发送认证请求\n API-->>CLI: 返回认证令牌\n CLI->>API: 请求媒体库数据\n API-->>CLI: 返回媒体信息\n CLI->>Store: 缓存热门数据\n CLI-->>User: 格式化输出结果\n\n Note over CLI,Store: 保存功能 (saved add)\n User->>CLI: 保存媒体到收藏\n CLI->>API: 提交保存请求\n API-->>CLI: 确认保存成功\n CLI->>Store: 更新本地索引\n```\n\n## 与 MCP 服务器的集成\n\ntidal-cli 的媒体库管理功能也通过 MCP（Model Context Protocol）服务器对外暴露，使得 AI 代理（如 Claude）能够以编程方式控制 Tidal 媒体库。\n\n### MCP 工具可用性\n\n以下媒体库操作可通过 MCP 接口调用：\n\n- `library list-saved` — 列出收藏内容\n- `library add-saved` — 添加收藏\n- `library remove-saved` — 移除收藏\n- `library history` — 查询播放历史\n- `library recommend` — 获取推荐内容\n- `user profile` — 用户资料查询\n\n## 输出格式\n\n所有媒体库命令支持 JSON 格式输出，便于脚本处理和自动化工作流。\n\n```bash\ntidal-cli --json search track \"Around the World\"\ntidal-cli --json playlist list\ntidal-cli --json artist similar 8992\n```\n\n添加 `--json` 参数后，命令输出为纯 JSON 格式，不再包含任何装饰性文本或进度提示。\n\n## 本地数据存储\n\ntidal-cli 在本地存储以下与媒体库相关的数据：\n\n| 存储内容 | 文件路径 | 说明 |\n|---------|---------|------|\n| 认证令牌 | `~/.tidal-cli/session.json` | OAuth 访问令牌 |\n| 搜索历史 | `~/.tidal-cli/search-history.json` | 本地搜索缓存 |\n| 配置文件 | `~/.tidal-cli/config.json` | 用户偏好设置 |\n\n数据以加密形式存储认证敏感信息，本地存储目录权限应限制为仅当前用户可访问。\n\n## 相关文档\n\n- **安装指南**: 请参考 [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md) 的安装章节\n- **服务条款**: 使用本工具需遵守 [Tidal 服务条款](https://tidal.com/terms)\n- **隐私政策**: 详见 [隐私政策页面](/privacy)\n\n---\n\n\n\n## 播放系统与质量设置\n\n### 相关页面\n\n相关主题：[搜索与浏览功能](#page-3), [媒体库管理](#page-5)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n- [src/auth.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/auth.ts)\n- [site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n- [site/app/terms/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/terms/page.tsx)\n- [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n \n\n# 播放系统与质量设置\n\n## 概述\n\ntidal-cli 的播放系统允许用户通过命令行直接控制 Tidal 音乐的播放功能。该系统提供了播放指定曲目、获取播放信息、获取音频流 URL 等核心能力，并支持多种音频质量级别。\n\n播放命令基于 Tidal API 的播放端点实现，支持通过曲目 ID 进行播放操作。 资料来源：[README.md:1-100]()\n\n## 播放命令架构\n\n### 子命令结构\n\ntidal-cli 的播放功能通过 `playback` 子命令组织，包含以下操作：\n\n| 子命令 | 说明 | 参数 |\n|--------|------|------|\n| `play` | 播放指定曲目 | `` 曲目 ID，可选 `--quality` 参数 |\n| `info` | 获取曲目播放信息 | `` 曲目 ID |\n| `url` | 获取音频流 URL | `` 曲目 ID |\n\n资料来源：[README.md:1-100]()\n\n### 基本使用方式\n\n```bash\n# 播放指定曲目\ntidal-cli playback play \n\n# 以无损质量播放\ntidal-cli playback play --quality LOSSLESS\n\n# 获取播放信息\ntidal-cli playback info \n\n# 获取音频流 URL\ntidal-cli playback url \n```\n\n资料来源：[README.md:1-100]()\n\n## 音频质量设置\n\n### 支持的质量级别\n\ntidal-cli 支持四种音频质量级别，通过 `--quality` 参数指定：\n\n| 质量级别 | 说明 | 适用场景 |\n|----------|------|----------|\n| `LOW` | 低比特率 | 节省带宽/流量 |\n| `HIGH` | 高比特率 | 标准音质 |\n| `LOSSLESS` | 无损音质 | 高保真聆听 |\n| `HI_RES` | 高解析音频 | 发烧友级别 |\n\n资料来源：[README.md:1-100]()\n\n### 质量选择示例\n\n```bash\n# 默认质量播放\ntidal-cli playback play 5756235\n\n# 指定无损质量播放\ntidal-cli playback play 5756235 --quality LOSSLESS\n\n# 高解析音频播放\ntidal-cli playback play 5756235 --quality HI_RES\n```\n\n> **注意**: 实际可用的音频质量取决于用户的 Tidal 订阅计划。例如，HI_RES 质量仅对 HiFi Plus 订阅用户可用。\n\n资料来源：[README.md:1-100]()\n资料来源：[site/app/terms/page.tsx:1-50]()\n\n## 工作流程\n\n### 播放流程图\n\n```mermaid\ngraph TD\n A[用户执行 playback play 命令] --> B[解析曲目 ID 和质量参数]\n B --> C{是否指定质量}\n C -->|是| D[使用指定质量级别]\n C -->|否| E[使用账户默认质量]\n D --> F[调用 Tidal API 播放端点]\n E --> F\n F --> G{API 响应状态}\n G -->|成功| H[开始播放音频流]\n G -->|失败| I[输出错误信息]\n```\n\n## 与其他系统的集成\n\n### 播放与发现功能结合\n\n播放系统可与搜索、历史等功能结合使用：\n\n```bash\n# 搜索后播放\ntidal-cli search track \"Teardrop\"\n# 获取曲目 ID 后\ntidal-cli playback play <找到的ID>\n\n# 播放历史记录中的曲目\ntidal-cli history tracks\n# 选择曲目 ID 后\ntidal-cli playback play <历史曲目ID>\n```\n\n### 与 AI Agent 的集成\n\n通过 MCP 连接器，用户可以让 AI Agent 智能选择并播放音乐：\n\n```bash\n# AI Agent 可执行的操作示例\n\"Play me something by Boards of Canada\" # 搜索并播放\n```\n\n资料来源：[site/app/page.tsx:1-50]()\n\n## JSON 输出支持\n\n播放相关命令支持 `--json` 参数以结构化格式输出：\n\n```bash\n# JSON 格式获取播放信息\ntidal-cli --json playback info \n\n# JSON 格式获取音频 URL\ntidal-cli --json playback url \n```\n\n此功能便于脚本处理和程序化调用。\n\n资料来源：[README.md:1-100]()\n\n## 认证要求\n\n播放功能需要有效的 Tidal 认证会话。用户需在首次使用前完成身份验证：\n\n```bash\n# 身份验证命令\ntidal-cli auth\n```\n\n认证成功后，OAuth 令牌将存储在本地 `~/.tidal-cli/session.json` 文件中。令牌会自动刷新以维持会话有效性。\n\n资料来源：[README.md:1-100]()\n资料来源：[site/app/privacy/page.tsx:1-50]()\n\n## 技术限制\n\n- 播放功能依赖 Tidal API，可能受 Tidal 服务可用性影响\n- API 变更可能导致播放功能暂时不可用\n- 某些地区可能存在播放限制\n\n> tidal-cli is provided **\"as is\"** without warranty of any kind. Tidal may change their API at any time, which could affect functionality.\n\n资料来源：[site/app/terms/page.tsx:1-50]()\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| 播放失败 | 未认证或会话过期 | 运行 `tidal-cli auth` 重新认证 |\n| 质量设置无效 | 订阅计划不支持 | 升级 Tidal 订阅计划 |\n| 无法获取 URL | API 限制 | 检查网络连接或稍后重试 |\n\n资料来源：[site/app/privacy/page.tsx:1-50]()\n\n---\n\n\n\n## 认证与会话管理\n\n### 相关页面\n\n相关主题：[系统架构](#page-2), [发现与推荐系统](#page-8), [MCP 服务器集成](#page-9)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/auth.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/auth.ts)\n- [src/session.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/session.ts)\n- [site/app/mcp-lib/tidal-oauth.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/mcp-lib/tidal-oauth.ts)\n- [site/app/mcp-lib/constants.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/mcp-lib/constants.ts)\n- [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n \n\n# 认证与会话管理\n\n## 概述\n\ntidal-cli 的认证与会话管理系统是该项目的核心基础设施，负责处理用户与 Tidal API 之间的安全通信。该模块基于 OAuth 2.0 授权码模式配合 PKCE（Proof Key for Code Exchange）扩展实现无密钥的安全认证流程。系统设计了双轨制架构，分别支持命令行工具（CLI）的本地会话存储和 MCP 服务器的服务端会话管理，确保用户凭证在传输和存储过程中的安全性。\n\n## 认证机制\n\n### OAuth 2.0 + PKCE 架构\n\ntidal-cli 采用公开客户端（Public Client）OAuth 流程，无需客户端密钥即可完成认证。系统利用 PKCE 机制替代传统客户端密钥，通过动态生成的代码挑战和验证器来保障授权码交换的安全性。\n\n```mermaid\ngraph TD\n A[用户执行 tidal-cli auth] --> B[生成 code_verifier 和 code_challenge]\n B --> C[构建授权 URL]\n C --> D[启动本地回调服务器]\n D --> E[打开浏览器跳转至 Tidal 授权页]\n E --> F[用户登录并授权]\n F --> G[Tidal 重定向至本地回调服务器]\n G --> H[交换授权码获取 Access Token]\n H --> I[保存会话至 ~/.tidal-cli/session.json]\n I --> J[认证成功]\n```\n\n### 认证流程详解\n\n#### 第一阶段：启动本地服务器\n\n```typescript\nserver.listen(REDIRECT_PORT, () => {\n console.log('\\nOpening browser for Tidal authorization...');\n console.log(`If the browser doesn't open, visit:\\n ${loginUrl}\\n`);\n console.log('Waiting for authorization...');\n openBrowser(loginUrl);\n});\n```\n\n系统在本地随机端口启动 HTTP 服务器，监听来自 Tidal OAuth 服务的回调请求。此服务器作为授权码的接收端点，确保令牌交换过程在用户本地完成，避免凭证经过第三方服务器。\n\n#### 第二阶段：令牌交换\n\n授权码交换过程采用 PKCE 验证机制：\n\n| 参数 | 说明 | 来源 |\n|------|------|------|\n| `grant_type` | 授权类型，值为 `authorization_code` | RFC 6749 标准 |\n| `code` | Tidal 返回的授权码 | 回调请求参数 |\n| `client_id` | Tidal 应用客户端 ID | 硬编码配置 |\n| `code_verifier` | 高熵随机字符串（43-128字符） | 动态生成 |\n| `redirect_uri` | 回调地址 | `http://localhost:{REDIRECT_PORT}` |\n\n### CLI 与 MCP 认证差异\n\ntidal-cli 提供两种使用模式，认证存储策略存在本质区别：\n\n| 模式 | 存储位置 | 加密方式 | 有效期 |\n|------|----------|----------|--------|\n| CLI | `~/.tidal-cli/session.json` | 无加密（文件权限保护） | 令牌自身过期时间 |\n| MCP | Upstash Redis | TLS 传输加密 | 30 天 TTL |\n\n资料来源：[site/app/privacy/page.tsx]()\n\nCLI 模式下，用户的 OAuth 令牌以 JSON 格式持久化至用户主目录下的隐藏文件夹，依赖操作系统文件权限机制进行保护。MCP 模式则将令牌托管于 Vercel 部署的 Upstash Redis 缓存服务，通过服务端加密确保传输安全，并设置 30 天生存时间自动过期。\n\n## 会话存储\n\n### 本地会话管理\n\n#### Session 模块架构\n\n```mermaid\nclassDiagram\n class SessionStorage {\n +getItem(key): string | null\n +setItem(key, value): void\n +removeItem(key): void\n +clear(): void\n }\n class EventTarget {\n +addEventListener()\n +removeEventListener()\n +dispatchEvent()\n }\n class StorageEvent {\n +key: string\n +newValue: string\n +oldValue: string\n }\n\n SessionStorage --|> EventTarget\n SessionStorage ..> StorageEvent : creates\n```\n\ntidal-cli 在 Node.js 环境中实现了 `localStorage` 和 `EventTarget` API 的 polyfill，使得标准 Web 存储接口可直接用于服务端环境。\n\n#### 会话文件格式\n\n```json\n{\n \"access_token\": \"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"refresh_token\": \"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"expires_at\": 1710489600000,\n \"userId\": \"123456789\"\n}\n```\n\n会话文件采用 JSON 格式存储关键认证信息，包含访问令牌、刷新令牌、过期时间戳及用户 ID。访问令牌用于 API 请求认证，刷新令牌用于获取新的访问令牌而无需用户重新授权。\n\n### 服务端会话管理（MCP）\n\n#### Redis 存储策略\n\nMCP 连接器使用 Upstash Redis 实现跨会话持久化：\n\n```typescript\n// 伪代码示例\nconst sessionData = {\n token: encryptedOAuthToken,\n userId: extractedUserId,\n createdAt: Date.now()\n};\n\n// 设置 30 天过期时间\nawait redis.setex(sessionKey, 30 * 24 * 60 * 60, JSON.stringify(sessionData));\n```\n\n资料来源：[site/app/privacy/page.tsx]()\n\n服务端存储采用加密机制保护敏感令牌数据，所有通过 MCP 协议进行的 API 调用都需要从 Redis 中提取有效会话信息。30 天 TTL 确保长期未使用的会话自动清理，减少安全风险。\n\n## API 客户端\n\n### getApiClient 函数\n\n```typescript\nexport async function getApiClient(): Promise {\n await ensureInit();\n\n // Verify we have valid credentials\n const creds = await credentialsProvider.getCredentials();\n if (!creds.token) {\n console.error('Error: Not authenticated. Run `tidal-cli auth` first.');\n process.exit(1);\n }\n\n return createAPIClient(credentialsProvider);\n}\n```\n\n该函数是获取 Tidal API 客户端的主入口点，核心职责包括：\n\n1. **初始化检查**：调用 `ensureInit()` 确保认证模块已正确初始化\n2. **凭证验证**：从凭证提供者获取当前会话凭证\n3. **错误处理**：检测到未认证状态时输出错误信息并终止程序\n4. **客户端创建**：返回配置了凭证的 API 客户端实例\n\n资料来源：[src/auth.ts]()\n\n### getCountryCode 函数\n\n```typescript\nlet cachedCountryCode: string | null = null;\n\nexport async function getCountryCode(): Promise {\n if (cachedCountryCode) return cachedCountryCode;\n\n try {\n const client = await getApiClient();\n const { data } = await client.GET('/users/{id}' as any, {\n // ...\n });\n // 从用户配置中提取国家代码\n } catch {\n // 降级策略\n }\n}\n```\n\n国家代码自动检测机制遵循以下优先级：\n\n| 优先级 | 来源 | 说明 |\n|--------|------|------|\n| 1 | 用户资料 | 通过 `/users/me` API 获取用户账户国家 |\n| 2 | 环境变量 | `TIDAL_COUNTRY` 环境变量 |\n| 3 | 默认值 | `US` |\n\n该机制确保 API 请求携带正确的地区标识，获取符合用户所在区域的内容目录和播放限制信息。\n\n## Token 自动刷新\n\n### 刷新机制流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant CLI as tidal-cli\n participant T as Tidal API\n participant FS as 文件系统\n\n U->>CLI: 执行任意命令\n CLI->>T: 发送带 Access Token 的请求\n T-->>CLI: Token 有效\n CLI-->>U: 返回请求结果\n\n Note over CLI,T: Token 过期场景\n U->>CLI: 执行任意命令\n CLI->>T: 发送带 Access Token 的请求\n T-->>CLI: 401 Unauthorized\n CLI->>T: 使用 Refresh Token 获取新 Token\n T-->>CLI: 返回新 Access Token + 新 Refresh Token\n CLI->>FS: 更新 session.json\n CLI->>T: 重试原请求\n CLI-->>U: 返回请求结果\n```\n\n### 刷新触发条件\n\n自动刷新机制在以下场景触发：\n\n- **令牌过期**：API 返回 401 状态码时自动尝试刷新\n- **令牌临近过期**：部分实现会在令牌即将过期前主动刷新\n- **首次认证**：执行 `tidal-cli auth` 命令后立即保存初始令牌\n\n刷新成功后，新的访问令牌和刷新令牌会持久化至 `~/.tidal-cli/session.json`，确保下次启动时使用最新凭证。\n\n## 数据安全\n\n### 隐私保护措施\n\ntidal-cli 在设计层面采取多重数据保护策略：\n\n| 措施 | CLI 模式 | MCP 模式 |\n|------|----------|----------|\n| 凭证传输 | 直接与 Tidal API 通信 | 经由 Vercel 服务器转发 |\n| 凭证存储 | 本地文件系统 | Upstash Redis（加密） |\n| 数据收集 | 无分析、无遥测 | 无分析、无遥测 |\n| Cookie 使用 | 无 | 仅 Tidal OAuth 流程所需 |\n\n资料来源：[site/app/privacy/page.tsx]()\n\n### 第三方服务依赖\n\n认证流程涉及以下 Tidal 官方服务端点：\n\n| 服务 | 端点 | 用途 |\n|------|------|------|\n| Tidal API | `openapi.tidal.com` | 音乐目录、播放列表访问 |\n| Tidal Auth | `login.tidal.com` | 用户登录界面 |\n| Tidal Auth | `auth.tidal.com` | OAuth 令牌交换 |\n\n所有通信遵循 Tidal 官方隐私政策，用户凭证永远不会经过 tidal-cli 维护者的服务器（除 MCP 模式的服务端存储）。\n\n### 数据删除\n\n用户可通过以下方式清除所有本地认证数据：\n\n```bash\nrm -rf ~/.tidal-cli\n```\n\n此命令删除包含 OAuth 令牌和会话信息的整个目录。删除后用户需重新执行 `tidal-cli auth` 进行认证。\n\n## 相关命令\n\n### auth 命令\n\n```bash\ntidal-cli auth\n```\n\n启动 OAuth 认证流程，打开浏览器引导用户完成 Tidal 账户授权。\n\n### 依赖模块\n\n| 模块 | 文件路径 | 功能描述 |\n|------|----------|----------|\n| 认证核心 | `src/auth.ts` | OAuth 流程、API 客户端获取 |\n| 会话存储 | `src/session.ts` | localStorage polyfill 实现 |\n| MCP OAuth | `site/app/mcp-lib/tidal-oauth.ts` | 服务端 OAuth 处理 |\n| MCP 常量 | `site/app/mcp-lib/constants.ts` | 配置常量和端点定义 |\n\n## 总结\n\ntidal-cli 的认证与会话管理系统通过 OAuth 2.0 + PKCE 协议实现了安全的无密钥认证，结合本地和服务端双轨存储策略兼顾了 CLI 用户的数据主权和 MCP 用户的使用便利性。Token 自动刷新机制确保长时间使用的连贯体验，而清晰的数据安全设计让用户对自己的凭证拥有完全控制权。\n\n---\n\n\n\n## 发现与推荐系统\n\n### 相关页面\n\n相关主题：[搜索与浏览功能](#page-3), [媒体库管理](#page-5)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/recommend.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/recommend.ts)\n- [src/mix.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/mix.ts)\n- [src/share.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/share.ts)\n- [src/history.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/history.ts)\n- [src/saved.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/saved.ts)\n- [src/user.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/user.ts)\n \n\n# 发现与推荐系统\n\n## 概述\n\ntidal-cli 的发现与推荐系统为用户提供了一套完整的音乐探索功能，包括个性化推荐、智能混音、用户历史记录管理以及社交分享能力。该系统与 Tidal API 深度集成，使用户能够在命令行环境中完成传统桌面或移动应用中的所有发现操作。\n\n## 系统架构\n\n发现与推荐系统由多个相互协作的模块组成，每个模块负责特定的功能域：\n\n| 模块 | 功能描述 | 主要命令 |\n|------|----------|----------|\n| `recommend` | 个性化推荐与混音获取 | `tidal-cli recommend` |\n| `mix` | 混音曲目管理 | `tidal-cli mix items` |\n| `history` | 用户行为历史记录 | `tidal-cli history tracks` |\n| `saved` | 稍后播放与收藏管理 | `tidal-cli saved list` |\n| `share` | 公开分享链接生成 | `tidal-cli share track` |\n| `user` | 用户资料获取 | `tidal-cli user profile` |\n\n## 推荐与混音\n\n### 获取推荐内容\n\n`tidal-cli recommend` 命令用于获取系统推荐的各种混音类型：\n\n```bash\ntidal-cli recommend # 获取所有混音类别\ntidal-cli recommend --type daily # 每日推荐混音\ntidal-cli recommend --type discovery # 发现混音\ntidal-cli recommend --type new-release # 新发行混音\ntidal-cli recommend --type offline # 离线可用混音\n```\n\n### 混音曲目管理\n\n获取特定混音后，可通过 `mix items` 命令查看混音内的所有曲目：\n\n```bash\ntidal-cli mix items --type daily\n```\n\n## 历史记录系统\n\n### 播放历史\n\ntidal-cli 记录并管理用户的三类播放历史：\n\n| 命令 | 功能 |\n|------|------|\n| `tidal-cli history tracks` | 查看最近播放的曲目 |\n| `tidal-cli history albums` | 查看最近播放的专辑 |\n| `tidal-cli history artists` | 查看最近播放的艺术家 |\n\n### 搜索历史\n\n系统同时维护用户的搜索历史，支持以下操作：\n\n```bash\ntidal-cli search history # 查看最近的搜索记录\ntidal-cli search history-delete # 删除单条搜索记录\ntidal-cli search history-clear # 清空全部搜索历史\n```\n\n## 保存与收藏\n\n### 稍后播放列表\n\n`saved` 命令提供对“稍后播放”列表的管理功能：\n\n```bash\ntidal-cli saved list # 列出所有已保存的项目\ntidal-cli saved add --type tracks --id # 添加曲目到保存列表\ntidal-cli saved add --type albums --id # 添加专辑到保存列表\ntidal-cli saved add --type artists --id # 添加艺术家到保存列表\ntidal-cli saved add --type playlists --id # 添加播放列表\ntidal-cli saved add --type videos --id # 添加视频到保存列表\n```\n\n### 移除已保存项目\n\n```bash\ntidal-cli saved remove --type albums --id \n```\n\n## 分享功能\n\ntidal-cli 支持生成公开分享链接，允许用户与他人共享音乐内容：\n\n```bash\ntidal-cli share track # 创建曲目的公开分享链接\ntidal-cli share album # 创建专辑的公开分享链接\n```\n\n分享功能会通过 Tidal API 生成标准化的分享 URL，接收方可直接在浏览器中打开查看。\n\n## 用户资料\n\n获取当前登录用户的完整资料：\n\n```bash\ntidal-cli user profile\n```\n\n该命令返回用户账户信息，包括订阅状态、用户名等个人资料数据。\n\n## JSON 输出\n\n所有发现与推荐相关的命令都支持 JSON 格式输出，便于脚本处理和程序化调用：\n\n```bash\ntidal-cli --json recommend\ntidal-cli --json history tracks\ntidal-cli --json saved list\ntidal-cli --json search history\n```\n\n## 数据流向\n\n```mermaid\ngraph TD\n A[用户请求] --> B[tidal-cli CLI]\n B --> C{命令类型}\n C -->|recommend| D[Tidal API: /recommendations]\n C -->|history| E[Tidal API: /history]\n C -->|saved| F[Tidal API: /library]\n C -->|share| G[Tidal API: /share]\n C -->|user| H[Tidal API: /user]\n D --> I[JSON 输出]\n E --> I\n F --> I\n G --> I\n H --> I\n```\n\n## 典型使用场景\n\n### 每日音乐探索流程\n\n```bash\n# 1. 查看每日推荐混音\ntidal-cli recommend --type daily\n\n# 2. 获取混音中的曲目\ntidal-cli mix items --type daily\n\n# 3. 播放感兴趣的曲目\ntidal-cli playback play \n\n# 4. 查看播放历史\ntidal-cli history tracks\n```\n\n### 个人资料管理\n\n```bash\n# 查看个人资料\ntidal-cli user profile\n\n# 查看播放历史\ntidal-cli history tracks\ntidal-cli history albums\ntidal-cli history artists\n\n# 管理已保存内容\ntidal-cli saved list\n```\n\n## 隐私说明\n\n根据 tidal-cli 隐私政策，使用 CLI 模式时所有数据直接在你的设备与 Tidal API 服务器之间传输，不经过任何中介服务器。认证令牌存储在本地文件 `~/.tidal-cli/session.json` 中。\n\n如需清除所有本地存储的发现历史和缓存数据，可执行：\n\n```bash\nrm -rf ~/.tidal-cli\n\n---\n\n\n\n## MCP 服务器集成\n\n### 相关页面\n\n相关主题：[认证与会话管理](#page-7), [Web 端与部署](#page-10)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n- [site/app/mcp-lib/tools.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/mcp-lib/tools.ts)\n- [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n- [src/auth.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/auth.ts)\n- [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n \n\n# MCP 服务器集成\n\n## 概述\n\nMCP（Model Context Protocol）服务器集成为 tidal-cli 提供了与 AI 助手（特别是 Claude Desktop 和 claude.ai）的无缝集成能力。通过这一集成，用户可以通过自然语言指令与 Tidal 账户进行交互，实现音乐搜索、播放列表管理、资料库操作等功能。\n\ntidal-cli 作为远程 MCP 服务器运行，允许 AI 代理直接调用 Tidal API 的各项功能，无需用户在本地安装任何软件。所有认证令牌存储在 Upstash 托管的加密 Redis 数据库中，确保了安全性和跨设备访问能力。\n\n## 架构设计\n\n### 系统组件\n\n| 组件 | 描述 | 位置 |\n|------|------|------|\n| MCP 路由端点 | 处理 MCP 协议请求的主入口 | `/api/mcp` |\n| 授权端点 | OAuth 授权流程处理 | `/api/authorize` |\n| 回调端点 | OAuth 回调处理 | `/api/callback` |\n| Token 端点 | Token 刷新与管理 | `/api/token` |\n| 注册端点 | 用户会话注册 | `/api/register` |\n| 工具定义 | 40 个可用的 MCP 工具 | `mcp-lib/tools.ts` |\n| Redis 存储 | 加密的会话数据存储 | `mcp-lib/redis.ts` |\n\n### 认证流程\n\n```mermaid\nsequenceDiagram\n participant User\n participant Claude\n participant MCP_Server\n participant Tidal_API\n participant Redis\n\n User->>Claude: 请求连接 Tidal\n Claude->>MCP_Server: 通过 /api/mcp 连接\n MCP_Server->>User: 重定向到授权页面\n User->>Tidal_API: 输入 Tidal 凭据\n Tidal_API->>MCP_Server: 返回 OAuth Code\n MCP_Server->>Tidal_API: 交换 Access Token\n Tidal_API->>MCP_Server: 返回 Token\n MCP_Server->>Redis: 加密存储会话\n Redis->>MCP_Server: 确认存储\n MCP_Server->>Claude: 连接成功\n Claude->>User: 显示可用工具\n```\n\n## MCP 连接配置\n\n### 连接地址\n\nMCP 服务器通过以下端点对外提供服务：\n\n```\nhttps://tidal-cli.lucaperret.ch/api/mcp\n```\n\n该端点托管在 Vercel 平台上，响应 MCP 协议的标准请求。\n\n### Claude Desktop 配置\n\n在 Claude Desktop 中配置自定义连接器的步骤如下：\n\n1. 打开 Claude Desktop 设置页面\n2. 导航至 **Connectors**（连接器）部分\n3. 点击 **Add custom connector**（添加自定义连接器）\n4. 输入上述 MCP 端点 URL\n5. 点击 **Connect**（连接）并使用 Tidal 账户登录\n\n## 可用工具\n\ntidal-cli MCP 集成提供了 40 个工具，覆盖以下功能类别：\n\n### 搜索功能\n\n| 工具名称 | 描述 |\n|---------|------|\n| `tidal_search_tracks` | 搜索曲目 |\n| `tidal_search_albums` | 搜索专辑 |\n| `tidal_search_artists` | 搜索艺术家 |\n| `tidal_search_playlists` | 搜索播放列表 |\n| `tidal_search_videos` | 搜索视频 |\n| `tidal_search_suggest` | 获取搜索建议 |\n| `tidal_search_history` | 查看搜索历史 |\n| `tidal_search_history_delete` | 删除单条历史记录 |\n| `tidal_search_history_clear` | 清空所有历史 |\n\n### 播放列表管理\n\n| 工具名称 | 描述 |\n|---------|------|\n| `tidal_playlist_list` | 列出用户播放列表 |\n| `tidal_playlist_create` | 创建新播放列表 |\n| `tidal_playlist_add_track` | 添加曲目到播放列表 |\n| `tidal_playlist_add_album` | 添加专辑到播放列表 |\n| `tidal_playlist_remove_track` | 从播放列表移除曲目 |\n| `tidal_playlist_delete` | 删除播放列表 |\n\n### 资料库操作\n\n| 工具名称 | 描述 |\n|---------|------|\n| `tidal_library_tracks` | 获取资料库中的曲目 |\n| `tidal_library_albums` | 获取资料库中的专辑 |\n| `tidal_library_artists` | 获取资料库中的艺术家 |\n| `tidal_library_playlists` | 获取资料库中的播放列表 |\n| `tidal_library_favorite_tracks` | 获取收藏的曲目 |\n| `tidal_library_favorite_artists` | 收藏艺术家 |\n| `tidal_library_favorite_albums` | 收藏专辑 |\n| `tidal_recently_added` | 最近添加的项目 |\n\n### 艺术家相关\n\n| 工具名称 | 描述 |\n|---------|------|\n| `tidal_artist_info` | 获取艺术家信息 |\n| `tidal_artist_tracks` | 获取艺术家的曲目 |\n| `tidal_artist_albums` | 获取艺术家的专辑 |\n| `tidal_artist_similar` | 获取相似艺术家 |\n| `tidal_artist_radio` | 获取艺术家电台 |\n\n### 专辑相关\n\n| 工具名称 | 描述 |\n|---------|------|\n| `tidal_album_info` | 获取专辑详细信息 |\n| `tidal_album_by_barcode` | 通过条形码查找专辑 |\n\n### 曲目相关\n\n| 工具名称 | 描述 |\n|---------|------|\n| `tidal_track_info` | 获取曲目信息 |\n| `tidal_track_similar` | 获取相似曲目 |\n| `tidal_track_radio` | 获取曲目电台 |\n\n### 播放控制\n\n| 工具名称 | 描述 |\n|---------|------|\n| `tidal_playback_play` | 播放指定曲目 |\n| `tidal_playback_info` | 获取播放信息 |\n| `tidal_playback_url` | 获取播放 URL |\n\n### 推荐与历史\n\n| 工具名称 | 描述 |\n|---------|------|\n| `tidal_recommend` | 获取推荐内容 |\n| `tidal_mix_items` | 获取混合播放列表内容 |\n| `tidal_history_tracks` | 播放历史（曲目） |\n| `tidal_history_albums` | 播放历史（专辑） |\n| `tidal_history_artists` | 播放历史（艺术家） |\n\n### 其他功能\n\n| 工具名称 | 描述 |\n|---------|------|\n| `tidal_user_profile` | 获取用户资料 |\n| `tidal_share_track` | 创建曲目分享链接 |\n| `tidal_share_album` | 创建专辑分享链接 |\n| `tidal_saved_list` | 列出稍后保存的项目 |\n| `tidal_saved_add` | 添加到保存列表 |\n| `tidal_saved_remove` | 从保存列表移除 |\n\n## 工具定义规范\n\n每个 MCP 工具都遵循统一的定义规范，包含以下元数据：\n\n```typescript\nserver.tool(\n 'tool_name', // 工具标识符\n 'Tool description', // 工具描述\n { /* 参数 Schema */ }, // Zod 参数验证\n { \n readOnlyHint: boolean, // 是否只读操作\n destructiveHint: boolean, // 是否为破坏性操作\n openWorldHint: boolean, // 是否涉及外部网络\n title: string // 人类可读标题\n },\n async (params, extra) => {\n // 工具实现\n }\n);\n```\n\n### 工具提示语义\n\n| 提示 | 含义 | 示例 |\n|------|------|------|\n| `readOnlyHint: true` | 只读操作，不修改数据 | 搜索、查看信息 |\n| `destructiveHint: false` | 非破坏性操作 | 播放、添加 |\n| `openWorldHint: true` | 涉及外部 API 调用 | 所有 Tidal API 调用 |\n\n## 认证与令牌管理\n\n### OAuth 认证流程\n\nMCP 服务器使用标准的 OAuth 2.0 流程进行身份验证：\n\n1. **授权请求**：用户发起连接请求后，被重定向至 Tidal 登录页面\n2. **用户授权**：用户在 Tidal 页面输入凭据并授权 tidal-cli 访问\n3. **回调处理**：Tidal 通过回调 URL 返回授权码\n4. **令牌交换**：服务器将授权码交换为访问令牌和刷新令牌\n5. **会话存储**：加密后的令牌存储至 Upstash Redis\n\n### 令牌存储\n\nCLI 模式下，令牌存储在本地：`~/.tidal-cli/session.json`\n\nMCP 模式下，令牌存储在服务器端加密的 Redis 数据库中，由 Upstash（Vercel 生态）托管。\n\n## 使用示例\n\n### 自然语言交互\n\n用户可以通过以下方式与 Tidal 交互：\n\n| 用户请求 | AI 执行的操作 |\n|---------|--------------|\n| 创建包含 Daft Punk Discovery 专辑最佳曲目的播放列表 | 搜索曲目、创建播放列表、添加曲目 |\n| 查找与 Massive Attack 相似的艺术家并添加其热门曲目到资料库 | 发现相似艺术家、添加收藏 |\n| 列出我的播放列表，将 LCD Soundsystem 新专辑添加到第一个 | 列出播放列表、搜索专辑、添加曲目 |\n| 播放 Boards of Canada 的歌曲 | 搜索艺术家、选择曲目、播放 |\n\n### 质量参数\n\n播放功能支持指定音质：\n\n```bash\ntidal-cli playback play --quality LOSSLESS\n```\n\n可用质量选项：`LOW`、`HIGH`、`LOSSLESS`、`HI_RES`\n\n## 隐私与安全\n\n### 数据存储\n\n根据隐私政策，MCP 集成遵循以下数据处理原则：\n\n- tidal-cli 不向开发者服务器收集或传输任何个人数据\n- 认证令牌加密存储在 Upstash Redis 中\n- 所有 Tidal API 通信直接通过用户设备与 Tidal 服务器进行\n\n### 数据删除\n\n用户可通过以下方式删除所有存储的数据：\n\n1. 在 Tidal 账户设置中撤销 tidal-cli 的访问权限\n2. 删除本地会话文件（CLI 模式）：`rm -rf ~/.tidal-cli`\n\n## Smithery 集成\n\n除 Claude Desktop 外，tidal-cli MCP 服务器还可在 Smithery 平台获取：\n\n```\nhttps://smithery.ai/servers/lucaperret/tidal\n```\n\n## 相关资源\n\n- 官方文档：[github.com/lucaperret/tidal-cli](https://github.com/lucaperret/tidal-cli)\n- 隐私政策：[tidal-cli.lucaperret.ch/privacy](https://tidal-cli.lucaperret.ch/privacy)\n- 服务条款：[tidal-cli.lucaperret.ch/terms](https://tidal-cli.lucaperret.ch/terms)\n\n---\n\n\n\n## Web 端与部署\n\n### 相关页面\n\n相关主题：[系统架构](#page-2), [MCP 服务器集成](#page-9)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n- [site/app/terms/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/terms/page.tsx)\n- [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n- [site/app/og-banner/route.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/og-banner/route.tsx)\n- [site/app/banner/route.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/banner/route.tsx)\n- [site/app/components/Nav.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/components/Nav.tsx)\n- [site/app/components/Terminal.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/components/Terminal.tsx)\n \n\n# Web 端与部署\n\n## 概述\n\ntidal-cli 项目不仅包含核心的命令行工具，还维护了一个完整的 Web 前端站点（位于 `site/` 目录）。该站点主要用于：\n\n- 展示项目功能和使用说明\n- 提供 MCP（Model Context Protocol）服务器端点，供 AI 代理（如 Claude）远程调用 Tidal API\n- 生成社交分享用的 OG（Open Graph）图片和横幅\n\n站点采用 [Next.js](https://nextjs.org/) 框架构建，部署在 **Vercel** 平台，并集成了 **Upstash Redis** 用于 MCP 模式下的认证令牌存储。\n\n## 技术架构\n\n### 技术栈\n\n| 层级 | 技术 | 说明 |\n|------|------|------|\n| 框架 | Next.js | 基于 React 的全栈框架，支持 App Router |\n| 语言 | TypeScript | 类型安全的 JavaScript 超集 |\n| 样式 | Tailwind CSS | 原子化 CSS 框架 |\n| 动画 | Framer Motion | React 动画库 |\n| 数据库 | Upstash Redis | MCP 服务器端认证令牌存储 |\n| 部署 | Vercel | 边缘部署平台 |\n\n### 目录结构\n\n```\nsite/\n├── app/\n│ ├── components/ # React 组件\n│ │ ├── Nav.tsx # 顶部导航栏\n│ │ └── Terminal.tsx # 终端模拟展示组件\n│ ├── api/ # API 路由\n│ │ └── mcp/ # MCP 服务器端点\n│ ├── terms/ # 服务条款页面\n│ ├── privacy/ # 隐私政策页面\n│ ├── og-banner/ # OG 图片生成路由\n│ ├── banner/ # 横幅生成路由\n│ └── page.tsx # 首页\n├── package.json\n└── vercel.json\n```\n\n## 核心组件\n\n### 导航组件\n\n`site/app/components/Nav.tsx` 提供了站点的顶部导航栏功能：\n\n- 左侧显示 tidal-cli Logo\n- 右侧提供 GitHub 链接入口\n- 响应式设计，在移动端隐藏部分链接\n\n```tsx\n// Nav.tsx 核心结构\n\n```\n\n资料来源：[site/app/components/Nav.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/components/Nav.tsx)\n\n### 终端展示组件\n\n`site/app/components/Terminal.tsx` 是一个用于模拟命令行终端界面的 React 组件，支持动画效果和命令展示：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| title | string | 终端窗口标题 |\n| lines | Line[] | 命令行内容数组 |\n| compact | boolean | 是否启用紧凑模式 |\n\n```tsx\ninterface Line {\n prompt?: boolean; // 是否显示 $ 提示符\n text: string; // 命令文本\n dim?: boolean; // 是否显示为灰色（注释）\n}\n```\n\n组件使用 Framer Motion 实现逐行动画效果，每行动画延迟 80ms：\n\n```tsx\n\n {line.prompt && $ }\n \n {line.text}\n \n\n```\n\n资料来源：[site/app/components/Terminal.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/components/Terminal.tsx)\n\n## 首页结构\n\n`site/app/page.tsx` 是站点的首页，包含以下主要区域：\n\n### 功能展示区\n\n展示 tidal-cli 的核心命令功能，包括搜索、艺术家信息、播放列表、播放控制、媒体库管理等。\n\n| 功能模块 | 命令示例 |\n|----------|----------|\n| 搜索 | `search track \"Around the World\"` |\n| 艺术家 | `artist info `, `artist albums ` |\n| 发现 | `artist similar `, `recommend` |\n| 播放列表 | `playlist list`, `playlist create --name \"Chill\"` |\n| 播放控制 | `playback play `, `playback url ` |\n| 媒体库 | `library add --track-id ...`, `history tracks` |\n\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n### 安装区域\n\n提供 npm 安装命令和 OAuth 认证流程说明：\n\n```bash\nnpm install -g @lucaperret/tidal-cli\ntidal-cli auth\n```\n\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n### MCP 集成区域\n\n说明如何将 tidal-cli 作为远程 MCP 服务器连接到 Claude Desktop：\n\n1. 在 Claude 设置中添加自定义连接器\n2. 输入 MCP 端点 URL：`https://tidal-cli.lucaperret.ch/api/mcp`\n\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n### AI 代理示例区域\n\n展示用户可以通过自然语言让 AI 代理执行复杂的 Tidal 操作：\n\n| 示例提示 | 执行操作 |\n|----------|----------|\n| 创建 Discovery 专辑的最佳曲目播放列表 | 搜索、创建播放列表、添加曲目 |\n| 添加类似 Massive Attack 的艺术家到我的媒体库 | 发现相似艺术家、添加到收藏 |\n| 播放 Boards of Canada 的音乐 | 搜索、选择曲目、播放 |\n\n## MCP 服务器端点\n\nMCP 服务器通过 API 路由 `/api/mcp` 提供服务，允许 AI 代理远程调用 tidal-cli 功能。\n\n### 认证机制\n\n根据隐私政策，MCP 模式下的认证令牌存储在服务器端：\n\n> 当使用 tidal-cli 作为 MCP 连接器时（例如通过 Claude Desktop 或 claude.ai），认证令牌存储在 Upstash（通过 Vercel）托管的加密 Redis 数据库中。\n\n资料来源：[site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n\n### 数据流向\n\n```mermaid\ngraph TD\n A[Claude Desktop] -->|MCP Protocol| B[tidal-cli.lucaperret.ch/api/mcp]\n B --> C[Upstash Redis]\n C -->|Session Tokens| B\n B -->|Tidal API| D[openapi.tidal.com]\n B -->|OAuth| E[login.tidal.com / auth.tidal.com]\n```\n\n## OG 图片与横幅生成\n\n### OG Banner 路由\n\n`site/app/og-banner/route.tsx` 和 `site/app/banner/route.tsx` 提供了动态生成 Open Graph 图片的功能。\n\n这些路由使用 Next.js 的 Image Response API 生成 SVG 格式的横幅图片：\n\n```tsx\nnew ImageResponse(\n (\n \n ),\n { width: 1280, height: 240 }\n);\n```\n\n生成内容包括：\n\n- tidal-cli 标题文字\n- 功能标签（Search、Playlists、Playback、Discovery）\n- AI Agent Ready 标识\n\n资料来源：[site/app/og-banner/route.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/og-banner/route.tsx)\n\n## 隐私与合规\n\n### 数据收集策略\n\n| 使用模式 | 数据存储位置 | 说明 |\n|----------|--------------|------|\n| CLI 模式 | 本地 `~/.tidal-cli/session.json` | 直接与 Tidal API 通信，无中间服务器 |\n| MCP 模式 | Upstash Redis | 服务器端加密存储认证令牌 |\n\n资料来源：[site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n\n### 外部服务依赖\n\n| 服务 | 用途 | 隐私政策 |\n|------|------|----------|\n| Tidal API | 访问音乐库、播放列表和目录 | Tidal 隐私政策 |\n| Tidal Auth | OAuth 身份验证 | Tidal 隐私政策 |\n| Upstash | MCP 模式认证令牌存储 | Upstash 隐私政策 |\n\n资料来源：[site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n\n### 数据删除\n\n用户可通过以下方式删除所有本地存储数据：\n\n```bash\nrm -rf ~/.tidal-cli\n```\n\n资料来源：[site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n\n## 服务条款\n\n`site/app/terms/page.tsx` 明确了使用条款：\n\n### 用户责任\n\n- 遵守 Tidal 的服务条款\n- 对账户所有操作负责\n\n### 可接受使用\n\n用户同意不：\n\n- 将 tidal-cli 用于任何非法目的\n- 尝试绕过 Tidal 的访问控制或 DRM\n- 使用服务下载或重新分发受版权保护的内容\n- 进行超出正常使用的过度或自动请求\n\n### 免责声明\n\ntidal-cli 按\"原样\"提供，不提供任何明示或暗示的保证。维护者不保证不间断或无错误的运行。Tidal 可能随时更改其 API，这可能影响功能。\n\n资料来源：[site/app/terms/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/terms/page.tsx)\n\n## 部署流程\n\n### Vercel 部署\n\n站点部署在 Vercel 平台，利用边缘函数提供低延迟的 MCP 服务。\n\n### 部署检查清单\n\n1. 确保 `site/` 目录包含所有必要的配置文件\n2. 配置环境变量（如有）\n3. 通过 GitHub 集成连接到 Vercel\n4. 启用自动部署\n\n## 相关链接\n\n| 资源 | URL |\n|------|-----|\n| 官方网站 | https://tidal-cli.lucaperret.ch |\n| MCP 端点 | https://tidal-cli.lucaperret.ch/api/mcp |\n| GitHub 仓库 | https://github.com/lucaperret/tidal-cli |\n| Smithery 集成 | https://smithery.ai/servers/lucaperret/tidal |\n| ClawHub 集成 | https://clawhub.ai/lucaperret/tidal-cli |\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：lucaperret/tidal-cli\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。\n\n## 1. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | host_targets=mcp_host, claude\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：lucaperret/tidal-cli\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。\n\n## 1. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | host_targets=mcp_host, claude\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# tidal-cli - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 tidal-cli 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client / claude\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-1：项目简介与安装。围绕“项目简介与安装”模拟一次用户任务，不展示安装或运行结果。\n2. page-2：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. page-3：搜索与浏览功能。围绕“搜索与浏览功能”模拟一次用户任务，不展示安装或运行结果。\n4. page-4：播放列表管理。围绕“播放列表管理”模拟一次用户任务，不展示安装或运行结果。\n5. page-5：媒体库管理。围绕“媒体库管理”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-1\n输入：用户提供的“项目简介与安装”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-2\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-3\n输入：用户提供的“搜索与浏览功能”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-4\n输入：用户提供的“播放列表管理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-5\n输入：用户提供的“媒体库管理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-1：Step 1 必须围绕“项目简介与安装”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-2：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-3：Step 3 必须围绕“搜索与浏览功能”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-4：Step 4 必须围绕“播放列表管理”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-5：Step 5 必须围绕“媒体库管理”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/lucaperret/tidal-cli\n- https://github.com/lucaperret/tidal-cli#readme\n- skills/tidal-cli/SKILL.md\n- README.md\n- package.json\n- CLAUDE.md\n- src/index.ts\n- src/auth.ts\n- site/app/layout.tsx\n- src/search.ts\n- src/artist.ts\n- src/album.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 tidal-cli 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：lucaperret/tidal-cli\n\n## 官方安装入口\n\n### Node.js / npm · 官方安装入口\n\n```bash\nnpm install -g @lucaperret/tidal-cli\n```\n\n来源：https://github.com/lucaperret/tidal-cli#readme\n\n## 来源\n\n- repo: https://github.com/lucaperret/tidal-cli\n- docs: https://github.com/lucaperret/tidal-cli#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_96e5a3a8426245738a3d6af1675d094b"
}