前言¶
給智能體接信息源時，B 站是繞不開的一類：找某個主題的視頻、總結一期內容、覈對視頻裏實際講了什麼。麻煩在於，B 站頁面高度動態，直接抓網頁不可靠；只給模型字幕文本也不夠——字幕寫「如圖所示」時，模型並不知道畫面裏是什麼。
DeepSeek Harness（DSH）的思路是一切皆插件，外部能力以工具形式掛進會話。dsh-plugin-bilibili 做的就是這件事：安裝後智能體獲得五個 bilibili_* 工具，覆蓋關鍵詞檢索、視頻元數據、字幕文稿、直鏈播放地址與視頻幀。其中幀以圖像塊返回，具備圖像能力的模型可以直接看真實畫面，而不是隻靠字幕推斷。下面介紹它的功能、安裝與配置。
這是什麼¶
dsh-plugin-bilibili 是面向 DeepSeek Harness 的 B 站檢索插件，由 moxingovo 維護，許可證 MIT，當前版本 0.2.1。
它的默認形態是匿名可用：搜索自動引導匿名 cookie，元數據始終可用。可選配置一個 SESSDATA，解鎖登錄字幕軌（多數 AI 字幕所在）、更高畫質的播放地址與幀預覽路徑。插件只讀取元數據、字幕與幀圖片，不存儲、不重新上傳視頻，也不下載視頻或音頻。
核心功能：五個工具¶
- bilibili_search — 按關鍵詞查找視頻，返回標題、UP 主、播放量、時長、發佈日期
- bilibili_video — 單個視頻的完整元數據：各項計數、分區、分 P 頁面、簡介
- bilibili_subtitles — 單個視頻的字幕文稿，合併爲純文本
- bilibili_playurl — 直接 mp4 播放地址（含授權畫質與大小），用於下載或抽幀
- bilibili_frames — 真實視頻幀（預覽雪碧圖網格、封面回退或 ffmpeg 抽幀）以圖像塊返回，供具備圖像能力的模型觀看實際畫面
串起來的流程是：先 bilibili_search 找到候選，再用 bilibili_video 確認元數據；需要文字內容時取 bilibili_subtitles，需要畫面時經 bilibili_playurl 拿直鏈、由 bilibili_frames 返回圖像塊。
安裝與啓用¶
一條命令安裝：
dsh plugin --profile web add dsh-plugin-bilibili
也可以直接從 Git 倉庫安裝：
dsh plugin --profile web add git+https://github.com/moxingovo/dsh-bilibili
安裝後重啓 dsh web，新會話會自動獲得上述五個工具。其中 bilibili_frames 另需 attachments 服務，標準 web bundle 已經掛載，通常無需額外操作。
有一個已知的上游問題需要留意：官方 DeepSeek Harness 早期 rc 包（dsh-agent / dsh-session 的 0.0.1-rc.1 與 0.0.1-rc.2）聲明瞭一個未發佈的 peer dependency @deepseek-ai/dsh-type-meta，全新安裝解析到這些版本時可能 404。規避方式有兩種：在插件倉庫內用鎖定的 package-lock.json 執行 npm ci，或在已裝好的 harness workspace 內執行 dsh plugin add。這屬於上游 rc 階段的發佈問題，上游修復元數據後即消失。
可選：配置 SESSDATA¶
不配置 SESSDATA 也能用，但只能拿到公開可見的字幕軌；需要登錄的字幕會失敗並返回結構化錯誤碼 BILIBILI_LOGIN_REQUIRED。若需要登錄字幕與更高畫質，先做三步：
1、登錄 bilibili.com，打開 DevTools → Application → Cookies → bilibili.com 條目；
2、複製 SESSDATA 的裸 token（不是整個 cookie 頭）；
3、寫入環境變量，或寫入 DSH_HOME 下的 .env：
BILIBILI_SESSDATA=<your-bare-token>
配置項¶
插件提供以下默認值：
| 配置項 | 默認值 | 含義 |
|---|---|---|
| cookieEnv | BILIBILI_SESSDATA | 存放 SESSDATA 的環境變量名 |
| requestTimeoutMs | 30000 | 單次請求超時（毫秒） |
| subtitleLanguage | zh-CN | 首選字幕語言，精確匹配優先，否則取第一條軌 |
| searchMaxPageSize | 20 | bilibili_search 的分頁上限 |
| subtitleMaxChars | 80000 | 字幕文稿字符上限，超出會截斷並附帶 truncated 標記 |
所有字段都可以在 profiles/web/cordis.patch.yml 中覆蓋，後層按行生效。
錯誤碼與安全設計¶
工具失敗時返回結構化錯誤，主要錯誤碼：
- BILIBILI_RISK_CONTROL — 對應 -412 風控，稍後重試，插件已內置匿名 cookie 引導
- BILIBILI_FORBIDDEN — 對應 -403
- BILIBILI_NOT_FOUND — 對應 -404
- BILIBILI_LOGIN_REQUIRED — 對應 -101，多見於字幕
- BILIBILI_SUBTITLES_UNAVAILABLE — 無可訪問字幕軌或正文爲空
- BILIBILI_REDIRECT_REFUSED — 憑據安全護欄：所有請求拒絕重定向
- BILIBILI_BAD_RESPONSE — 響應非 JSON 或缺少 code 包裹
- BILIBILI_REQUEST_FAILED — 網絡錯誤
- BILIBILI_WBI_KEYS_UNAVAILABLE — 簽名密鑰缺失
安全方面有四條明確約束：cookie 僅從環境變量讀取，不進入配置文件、日誌或工具輸出；所有請求拒絕重定向，cookie 不會被轉發到其他源；cookie 只發送至 api.bilibili.com，字幕 CDN 下載不帶 cookie；不下載視頻或音頻。
配套技能與本地開發¶
倉庫 skills/ 目錄帶兩個配套技能：plugin-tool-bilibili 講工具用法，plugin-web-bilibili 講服務配置與錯誤碼。把它們複製進 harness 的 skills 目錄，智能體會在調用前先查閱。
想改代碼或跑測試：Node 22 及以上，先 npm ci 再 npm test。測試套件完全離線（mock HTTP），typecheck 針對已發佈的 DeepSeek Harness 包。
npm ci
npm test
適用場景與注意事項¶
適合的對象：在 dsh web 上運行、需要 B 站作爲信息源的智能體，尤其是要讀字幕文本，或讓多模態模型直接看畫面覈對內容的任務。
幾點注意：
1、插件以當前 dsh 進程權限運行，安裝前應檢查源碼與許可證（本項目爲 MIT）；
2、SESSDATA 是登錄憑據，插件的讀取與發送範圍見上一節，建議只在受信任的環境使用；
3、遇到 BILIBILI_RISK_CONTROL（-412）屬於風控，按提示稍後重試；
4、插件不下載視頻或音頻，bilibili_frames 另需 attachments 服務（標準 web bundle 已掛載）。
小結¶
dsh-plugin-bilibili 把 B 站的檢索、字幕與畫面接進了 DSH 的工具體系：默認匿名可用，配 SESSDATA 後覆蓋登錄字幕與更高畫質，錯誤碼結構化，憑據的讀取與發送路徑都有明確約束。社區插件目錄頁在 https://www.skillhub.cn/plugins/moxingovo/dsh-bilibili ，源碼與 README 見 https://github.com/moxingovo/dsh-bilibili 。
