jerryqx/dsh-ximalaya

DeepSeek Harness 喜马拉雅播客插件。

在 DSH 的 Web 界面里直接收听喜马拉雅：搜索专辑/播客/有声书、浏览曲目列表、一键播放，聊天输入区常驻播放条（播放/暂停/上一集/下一集/快进/快退/进度拖动/音量/倍速）。还注册了 ximalaya_play 模型工具——直接在对话框里说「播放三体」「来点郭德纲相声」，节目就响起来。

界面预览

搜索专辑	专辑详情

我的订阅	关注的主播

特性

• 搜索：按关键词搜喜马拉雅专辑（封面/主播/分类/集数/完结状态/播放量卡片式展示），带搜索历史
• 专辑浏览：曲目列表分页加载（每页 30 集，可一直「加载更多」），点击即播
• 收藏的声音：「我的」页展示账号收藏（♥ 喜欢）的声音列表，分页加载、点击即播，含所属专辑/主播/时长/收藏时间
• 我的订阅：「我的」页展示账号订阅的专辑（含「最新：x天前 · 最新一集」更新提示），点击进专辑即听
• 关注的主播：「我的」页展示已关注主播（头像/简介/粉丝数/专辑数），点击主播浏览其公开专辑并进入收听
• 播放条：播放/暂停、上一集/下一集（自动连播专辑列表，翻页自动续）、快进/快退（默认步长 15 秒，播放中/暂停均可用，自动钳制在 0–总时长内；右键 ⏪/⏩ 可选 5/10/15/30/60 秒步长，配置跨刷新持久化）、可拖进度条、音量、倍速（0.75x–2x）、时间显示
• 云端同步（订阅/收藏/关注写回）：与手机 App 实时同步——专辑页「📻 订阅/已订阅」一键订阅退订；「我的」页可取消收藏声音（✕）、退订专辑、取消关注主播。⚠️ 收听历史不上云（网页端无此接口，见 FAQ）
• 音频流代理：播放地址由 Host 端解析并流式转发（支持 Range 拖动/续传），浏览器无 CORS 顾虑，登录态不出 Host
• 扫码登录（可选）：喜马拉雅 App 扫码后可播 VIP/已购内容（免费内容无需登录）
• 收藏：专辑一键收藏（♥），收藏列表跨刷新/重启保留
• 断点续播：当前专辑/曲目/进度持久化在 Host 端，刷新页面自动恢复（点 ▶ 续听）
• ximalaya_play 模型工具：agent 可按关键词搜索播放（query），或直接指定 albumId/trackId；支持 action 暂停/继续/停止/下一集/上一集
• 免登录可播全部免费专辑；付费/VIP 专辑在登录且账号有权限时可播

安装

需要已安装 dsh CLI（Node ≥ 20）。

# 把 <profile> 换成实际 profile 名，如 web
dsh plugin --profile <profile> add dsh-ximalaya

或从本地目录 / tarball 安装：

# 本地目录
dsh plugin --profile <profile> add /path/to/dsh-ximalaya

# 或先打包再安装
npm pack
dsh plugin --profile <profile> add ./dsh-ximalaya-0.5.0.tgz

安装后重启 dsh web 并刷新页面：

• 聊天输入区上方出现「📻 喜马拉雅」播放条
• 点右侧 🔎 打开面板，搜索并点专辑即可收听
• 直接对 agent 说「播放三体」也能播

使用

1. 搜索播放：面板「搜索」页输入关键词（如「三体」「郭德纲」「晓说」）→ 点专辑卡片 → 点任意曲目（或专辑头部的「▶ 播放」）
2. 连续播放：一集播完自动播下一集；⏮/⏭ 在专辑内切换；翻到已加载列表末尾会自动拉取下一页续播
3. 让 agent 播放：对话框里说「用喜马拉雅播放 XXX」；agent 会调用 ximalaya_play 工具，播放条 2 秒内响应
4. VIP/付费内容：面板「我的」页 → 喜马拉雅 App 扫码登录 → 已购/VIP 内容自动解锁（播放质量也会升到 128k M4A）
5. 收藏的声音 / 我的订阅 / 关注的主播：登录后面板「我的」页分四段——「♥ 声音」（收藏的声音，点击任意一条即播）、「📻 订阅」（订阅的专辑，卡片带最新更新提示，点进专辑即听）、「👤 主播」（关注的主播，点主播看其公开专辑）、「★ 专辑」（本插件本地收藏）
6. 倍速/音量/快进快退：播放条上点 1.0x 循环切换倍速；🔊 弹出音量条；⏪/⏩ 按步长快退/快进（默认 15 秒），右键这两个按钮可改步长（5/10/15/30/60 秒，选择会记住）
7. 云端同步（需登录）：专辑页「📻 订阅」按钮订阅/退订专辑；「我的」页每条收藏声音右侧 ✕ 取消收藏、每张订阅专辑「退订」、每位关注主播「取关」——以上操作实时同步到手机 App 的订阅/收藏/关注列表
8. 面板不遮挡播放条：面板位置与高度自动钳制，无论怎么拖都不会盖住聊天输入区的播放条按钮——面板开着也能随时暂停/继续

说明：「声音 / 订阅 / 主播」三段读取的是喜马拉雅账号云端数据（App 内点 ♥ 喜欢、订阅专辑、+ 关注的都会出现），需先扫码登录；「★ 专辑」是插件本地的收藏（仅存本机）。

配置

插件为「Host 端 + Web 端」双面结构：

• Host 端（lib/index.js）：喜马拉雅接口代理（搜索/专辑/曲目/扫码登录/收藏声音/关注主播）、播放地址解析与音频流转发、ximalaya_play 工具、状态持久化
• Web 端（lib/client.js）：浏览器里的播放条 + 面板（搜索/专辑/主播/我的）

由 cordis.patch.yml 插入 ximalaya-podcast 行自动组对：

- insert:
    - id: ximalaya-podcast
      name: 'dsh-ximalaya'

状态持久化：登录态、收藏、搜索历史、音量/倍速、面板位置、上次播放（专辑/曲目/进度）全部保存在 Host 端 ~/.dsh/ximalaya-state.json，重启/刷新不丢（dsh-desktop 随机端口下同样有效）。

开发

npm install
npm test        # vitest：xmly 纯函数单测 + host 路由集成测试 + Web 渲染冒烟（55 用例）

修改 lib/ 后本地调试：

dsh plugin --profile <profile> add ./   # 或直接改 profile 里的 link 目标

结构：

lib/
├── xmly.js     # 喜马拉雅 API 库：搜索/专辑/曲目/播放地址（xm-sign 签名 + 解密）/扫码登录/收藏声音/订阅专辑/关注主播/云端写操作（订阅·收藏·关注）
├── index.js    # Host 半边：/dsh-ximalaya/* 路由、音频流代理、云端写转发、ximalaya_play 工具
└── client.js   # 浏览器半边：播放条 + 面板（slots 注入）

使用声明（重要）

本插件通过非官方接口访问喜马拉雅内容，所播放内容的版权归喜马拉雅及权利方所有。仅供个人学习、技术研究、日常试听使用，严禁用于任何商业用途、公开传播、二次分发或盈利行为。扫码登录产生的账号风控、封禁等风险由使用者自行承担。如您不同意以上条款，请勿使用本插件。

常见问题

播放条显示「浏览器拦截了自动播放」？ 浏览器安全策略禁止未交互的音频播放。首次自动播放被拦截是正常的——在播放条上点一次 ▶ 即可解锁，之后恢复自动播放。

某些曲目提示「需要登录或已购/VIP 权限」？ 该曲目是付费/VIP 内容。面板「我的」页扫码登录；若账号未购买该专辑或非 VIP，则无法播放（这是平台版权限制，插件不会绕过付费墙）。

搜索有结果但某专辑曲目为空？ 该专辑可能已下架或仅含视频内容。插件只处理音频曲目。

订阅里的专辑点进去提示「已下架」？ 部分专辑（多为播客类）已从旧版曲目接口迁移，插件会自动级联到网页播放器同款接口拉取列表——若仍失败，多为该专辑真的已下架。

扫码二维码过期了？ 二维码约 3 分钟过期，「我的」页会自动提示，点「刷新二维码」重新生成即可。

音频拖动进度后卡住？ Host 端播放地址缓存约 10 分钟过期，过期后首次请求会自动重新解析（多花 1–2 秒）。若持续失败，暂停后再点播放重试。

收听历史能同步到手机吗？ 不能。喜马拉雅网页端没有「上报收听历史」的接口（对网页播放器代码与真实播放流量均验证过），手机 App 的收听历史走 App 私有签名接口，插件无法也不应伪造。插件内播放进度只存本机（断点续播用）。可云端同步的只有订阅/收藏/关注（见「使用」第 7 条）。

为什么插件里只能「取消收藏/取关」，不能新增收藏/关注？ 经实测，点赞/关注的写方向接口有更严风控（需真实浏览器指纹签名，伪造请求会被拦截），只有取消方向与订阅的两个方向可纯接口可靠完成。要新增 ♥ 收藏或关注，请在手机 App / 网页端操作，插件内随时可查看与取消。

登录后 VIP 曲目还是不能播？ 确认账号确实拥有该内容权限（已购买专辑/有效 VIP）。播放权限由喜马拉雅服务端判定，插件只做登录态转发。

License

MIT