前言¶

在 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