前言¶
给智能体接信息源时，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 。
