bilinote

B 站视频转笔记工具集：把 B 站的字幕、语音转写、搜索、评论、合集等能力， 整理成 AI 编码工具（Claude Code / Codex / ZCode / DSH）可直接挂载的 MCP 工具面， 外加一个久经打磨的 批量字幕/音频命令行工具。

agent（Claude Code / Codex / ZCode / DSH）与人类用户
 │  MCP (stdio)                        │ shell
 ├── bilinote-mcp（15 个工具）──────────┤
 │        │                            ▼
 │        │                    bili-subtitle（批量 CLI）
 │        ▼                            │
 │   batch.py 批量引擎（续跑/熔断/并发/进度回调）
 │        │                            │
 └────────► bili/ 协议层（自维护，Wbi 签名）──► B 站 Web API

• 协议层自维护：核心端点为自实现（参考 biliAPI / bilibili-API-collect）， 不依赖第三方 B 站 SDK；Wbi 签名已内置（搜索/播放器接口已签名）。
• 单运行时：纯 Python（>=3.10），无 node 工具链。

安装

推荐：从 PyPI 安装（隔离环境，不碰你的 Python 环境）

pipx install bilinote
# 或：uv tool install bilinote

pipx 把 bilinote 及其全部依赖装进独立虚拟环境，只把 bili-subtitle 与 bilinote-mcp 两个命令暴露到 PATH——安装/升级/卸载都不影响你已有的任何 Python 项目。 升级：pipx upgrade bilinote（uv 用户：uv tool upgrade bilinote）。

给 MCP 用的话，可以完全不安装——uvx 直接从 PyPI 拉起服务器，见下一节。

从 git 安装（想跟 main 或使用尚未发布的改动时）：

pipx install git+https://github.com/caiqianzhang/bilinote.git@v0.2.0
# 或传统方式（装进当前 Python 环境，与已安装的包共享解释器）：
pip install git+https://github.com/caiqianzhang/bilinote.git@v0.2.0

离线 / 内网：从 Releases 下载 bilinote-<版本>-py3-none-any.whl 后 pipx install ./bilinote-0.2.0-py3-none-any.whl。 安装期不需要联网拉构建依赖，适合不可达 PyPI 的机器。

开发者：克隆 + pip install -e .[dev]；发版流程（PyPI Trusted Publishing）见 docs/release.md。

要求 Python ≥ 3.10（CI 覆盖 3.10 / 3.12 / 3.14）。安装后获得两个命令： bili-subtitle（批量下载 CLI）与 bilinote-mcp（MCP 服务器）。

MCP 接入

服务器是 stdio 模式。默认接入方式：uvx 直接运行已发布的包，无需预先安装 （需要本机有 uv：pipx install uv 或 curl -LsSf https://astral.sh/uv/install.sh | sh）。各家注册示例见 docs/setup，速查：

// Claude Code（.mcp.json 或 claude mcp add）/ ZCode 通用 JSON 形态
{ "mcpServers": { "bilinote": { "command": "uvx", "args": ["--from", "bilinote", "bilinote-mcp"] } } }

# Codex CLI（~/.codex/config.toml）
[mcp_servers.bilinote]
command = "uvx"
args = ["--from", "bilinote", "bilinote-mcp"]

已用 pipx install bilinote 装过的话，直接调命令即可（少一次 uvx 解析）：

[mcp_servers.bilinote]
command = "bilinote-mcp"

--from bilinote 是必要的：包名是 bilinote，而可执行文件名是 bilinote-mcp， uvx 默认按命令名找同名包，不写 --from 会去找并不存在的 bilinote-mcp 包。

想在配置里锁版本，把包名换成带版本约束的形式即可（升级靠手动改这里）：

"args": ["--from", "bilinote==0.2.0", "bilinote-mcp"]

首次 uvx 运行会下载并缓存依赖到 ~/.cache/uv，之后启动直接命中缓存； 若客户端从 GUI 启动、PATH 里找不到 uvx，用 which uvx 的绝对路径填 command。

DeepSeek Harness（DSH）：若其支持标准 stdio MCP 客户端，用同一命令即可； 不支持时可用 bili-subtitle CLI 兜底（任何能跑 shell 的 agent 都能用）。

工具清单（15 个）

CLI（批量字幕/音频）

bili-subtitle "https://www.bilibili.com/video/BVxxx" --all-parts --format srt --output notes.srt
bili-subtitle "https://www.bilibili.com/video/BVxxx" --audio --audio-dir out/audio

支持：全部分 P、?p=N/短链解析、断点续跑（已存在跳过）、并发 --jobs + 全局限速 --rate、 连续失败熔断 --fail-fast、浏览器 Cookie 自动读取。音频走 playurl 直连（0.2.0 起不再依赖 yt-dlp）。 详细参数 bili-subtitle -h。

登录与 Cookie

扫码登录（推荐）：

bili-subtitle --login    # 终端显示二维码，B 站 App 扫码确认，Cookie 存 cookies.json

MCP 里用 qr_login_start（返回二维码图片内容 + PNG 路径 + ASCII 文本 + 链接， 四层展示任选）+ qr_login_poll 轮询；cookies.json 会被自动发现并加载。

优先级：显式参数 > 环境变量 BILI_COOKIE > cookies.json > 浏览器自动读取 > 匿名。 匿名可用：搜索 / 视频信息 / 部分字幕 / 音频。需登录：高清晰度播放流、收藏夹、 以及多数视频的 CC/AI 字幕（B 站策略）。

安全边界（有意设计）：不提供任何读取/导出 Cookie 的工具；全部工具为只读， 唯一的批量写路径是"下载文件到本地"。投稿/点赞/评论发布等账号写操作不在此库范围内。

已知限制（如实记录）

• 必剪 ASR：全链路可用（实测 7 分钟音频 → 162 段中文识别 → SRT 正确）。 该免费接口有 IP 频控：短时间内反复上传会触发临时 -412（request was banned）， 等待数分钟冷却即自行恢复，请勿高频连续调用。
• UP 主投稿列表：B 站风控较严，出现 -412 时需提供登录 Cookie。
• 弹幕（protobuf）、直播回放、历史记录在路线图中未实现，见 docs/architecture.md。

测试

python -m pytest tests/ -q --cov=bilinote       # 离线 130 项（128 通过 + 2 跳过）
BILINOTE_LIVE=1 python -m pytest -m live -q     # 真实网络 11 项（搜索/字幕/合集/多P/收藏/入口/MCP 协议）

分层说明：离线测试覆盖 Wbi 签名/客户端重试与缓存、CLI 回归（28 项迁移基准）、 真实响应结构冻结（test_parsing.py）、MCP 工具包装层、ASR 状态机与导出格式、 扫码登录各状态解析；live 测试打 @live 标记，验证链路可用性，断言宽松（内容依赖）。 cli.py 为行为冻结区，不纳入覆盖率统计。

CI 另有一条 package-smoke 任务：构建 sdist/wheel → twine check --strict → 装进干净虚拟环境跑离线测试，确保发布出去的那份 wheel（而不是工作树）是好的。

许可证

MIT © 2026 caiqianzhang。B 站接口协议参考了社区公开文档 （bilibili-API-collect、 renmu123/biliAPI），实现为原创。

仅用于个人学习与效率工具用途，请遵守 B 站用户协议，勿用于批量抓取等滥用场景。