前言¶

在 DeepSeek Harness（DSH）里做智能体或本地工作流时，偶尔会需要把 B 站上的讲解、教程或素材落到本机，再交给转写、剪辑或其它工具处理。单独开一个命令行下载器、再手动拷路径，和「在宿主里一点就开始、任务在后台跑」的体验不一致。dsh-bili-downloader 是社区维护的 DSH 插件（联网工具类），把下载能力和扫码登录接到宿主工具与左侧栏面板上，并支持分片下载与 ffmpeg 合流。下面按定位、能力、安装配置和用法说明如何接入。

这是什么¶

插件全名 dsh-bili-downloader，维护者为 AlanZhaofeng，当前包版本 0.2.1（MIT 许可证）。它在 DSH 里提供：

• 工具 bili_download：下载视频或纯音频（audio 得 .m4a，audio-mp3 得 .mp3），支持分 P、清晰度与编码偏好。
• 工具 bili_login：扫码登录（start / poll / status / logout），二维码在本地页面展示，用手机扫屏幕。
• 左侧栏 「B 站下载器」 面板：账号状态、扫码登录、新建下载、任务进度、配置与最近日志。

实现思路文档化在仓库内的 bili_dl/B站下载器-完整方案.md；命令行侧 bili_api.py / bili_login.py 已在维护者本机跑通 4K 场景。目录页：SkillHub 插件条目；源码：GitHub AlanZhaofeng/dsh-bili-downloader。

核心功能¶

工具与面板分工¶

客户端在 lib/client.js 里向 sidebar.panellist 注册图标、向 main 注册同名面板；主题色使用 DSH 变量（--dsw-alias-*），浅色/深色随宿主切换。二维码约每 1.5 秒轮询状态，过期或成功后自动换图，也可手动「换一张」。

清晰度与合流（README 本机实测）¶

错误处理原则：宁可明确失败，也不要「下了一半 480P 却报成功」。常见错误码包括 NOT_FOUND、LOGIN_REQUIRED、GEO_BLOCKED、VIP_REQUIRED、QUALITY_UNAVAILABLE、NO_FFMPEG、NO_SPACE、MAX_BYTES、NETWORK、STREAM_EXPIRED、ABORTED、BAD_INPUT 等。

宿主 HTTP 路由¶

面板与扫码页依赖宿主注册的路由，例如：

• /dsh-bili-downloader/qr — 扫码页
• /dsh-bili-downloader/download — POST 发起下载（面板使用）
• /dsh-bili-downloader/tasks — 后台任务
• /dsh-bili-downloader/graph — 客户端模块图诊断（可看 hasClient: true）
• /dsh-bili-downloader/status — 登录态与配置路径等状态页

完整列表见仓库 README「页面」一节。

安装与启用¶

在 DSH 的插件管理里安装本插件 bundle 即可；也可在 profile 里手动 link 本地目录：

// profiles/<profile>/package.json
"dependencies": { "dsh-bili-downloader": "link:C:/path/to/dsh-bili-downloader" },
"dsh": { "profile": { "bundles": [ ..., "dsh-bili-downloader" ] } }

注意两点：

1. 宿主侧修改 package.json 或 bundle 列表后，需要重启 DSH（或在插件管理里关闭再打开该条目）。
2. 客户端侧装好后，浏览器里刷新一次页面（F5）。客户端模块图在宿主启动时组装，插件会自检并写入模块图；已打开的页面需重新拉启动清单才能看到左侧栏 B 站图标。可用 /dsh-bili-downloader/graph 确认 hasClient: true。

插件以当前 DSH 进程权限访问网络与本机磁盘；安装前请自行查看源码与 MIT 许可证，确认符合你的环境策略。

配置¶

首次运行会在数据目录生成 config.json（路径：%DSH_HOME%\bili-downloader\config.json）：

{
  "outputDir": "C:\\Users\\<你>\\Downloads\\bili",
  "defaultQuality": "best",
  "defaultCodec": "avc",
  "concurrency": 4,            // 分片并发，1~8
  "chunkSize": 8388608,        // 8MB 一片
  "maxBytes": 8589934592,      // 单文件上限 8GB
  "ffmpegPath": "auto",        // auto：PATH + WinGet 目录
  "keepSeparateStreams": false // true 时保留 video.m4s / audio.m4s
}

同目录还有 cookies.json（登录态，仅本插件使用，日志与工具返回值不回显完整 cookie）、login-qr.png（无 webServer 时的二维码兜底）、diag.log（诊断日志，超过 2MB 自动轮转）。

典型用法¶

左侧栏面板¶

1. 刷新页面后，点左侧栏 B 站图标，中间列进入「B 站下载器」。
2. 在面板粘贴 /video/BV… 链接，选择清晰度等选项后发起下载；进度条实时更新。
3. 需要高清晰度或会员流时，在面板内完成扫码登录（或先用 bili_login 工具）。

再点一次侧栏图标或切回会话，可回到对话界面；后台任务继续执行。

工具调用（智能体 / 脚本）¶

• bili_login：start 生成二维码 → poll 轮询 → status 查看是否已登录 → 不用时 logout。
• bili_download：传入 BV 链接与质量、编码等参数；纯音频模式无需 ffmpeg。

仓库提供自测命令，可在开发环境验证注册与选流逻辑（示例）：

node test/smoke.mjs          # 720P、纯音频、错误路径
node test/smoke.mjs --full     # 再加 1080P 合流
node test/smoke.mjs --4k       # 再加 4K（体积较大）
node test/resume.mjs           # 断点续传

故障排查摘要¶

面板停在「二维码准备中」或「正在连接宿主」时，可先测宿主路由：

Invoke-WebRequest http://127.0.0.1:<端口>/dsh-bili-downloader/status

返回 JSON 表示宿主正常，可刷新页面；404 可能是路由未注册（0.2.1 起用 ctx.inject(['webServer'], …) 等待 webServer；仍异常可在插件管理里重开插件）。工具报 NETWORK 时，0.2.1 起 request() 会自动重试一次，仍失败可再重试工具调用。

适用场景与注意¶

适合：已在用 DSH、希望在本机归档普通 B 站视频（/video/BV…）或提取音频，并希望在同一界面完成登录与进度查看的开发者。

边界（README 明示）：

• 仅支持普通视频页；番剧、课程、直播地址不支持。
• 不绕过会员或地区限制；拿不到流则报错。
• 流地址约 2 小时过期且绑定 IP；中断后可在分片大小不变前提下对 .part 续传。
• 侧栏文案目前为中文硬编码，未接 Client locale 字典。

结尾¶

dsh-bili-downloader 把 B 站下载拆成 bili_download、bili_login 两个宿主工具，并用左侧栏面板承接扫码、任务与配置，分片下载与 ffmpeg 合流在配置项里可调。接入时记住：宿主改 bundle 要重启，浏览器要刷新一次才能看到侧栏入口。

• 插件目录：https://www.skillhub.cn/plugins/AlanZhaofeng/dsh-bili-downloader
• 源码与详细说明：https://github.com/AlanZhaofeng/dsh-bili-downloader