# 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 工具链。

## 安装

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

```bash
pipx install git+https://github.com/caiqianzhang/bilinote.git
# 或 uv：uv tool install git+https://github.com/caiqianzhang/bilinote.git
```

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

**传统方式**（装进当前 Python 环境；依赖少且版本宽松，但与已安装的包共享解释器，
存在互相影响版本的可能）：

```bash
pip install git+https://github.com/caiqianzhang/bilinote.git@v0.2.0
```

**开发者**：克隆 + `pip install -e .[dev]`

要求 Python ≥ 3.10（3.10 / 3.14 由 CI 双版本验证）。安装后获得两个命令：
`bili-subtitle`（批量下载 CLI）与 `bilinote-mcp`（MCP 服务器）。

## MCP 接入

服务器命令：`bilinote-mcp`（stdio）。各家注册示例见 [docs/setup](docs/setup/)，速查：

```jsonc
// Claude Code（.mcp.json 或 claude mcp add）/ ZCode 通用 JSON 形态
{ "mcpServers": { "bilinote": { "command": "bilinote-mcp" } } }
```

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

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

## 工具清单（15 个）

| 工具 | 说明 |
|---|---|
| `search_videos` | 综合搜索（Wbi 已签名，未登录可用） |
| `get_video_info` | 视频详情 + 分 P 列表 |
| `get_video_subtitles` | 单集字幕正文（CC/AI 轨，含时间戳） |
| `get_video_chapters` | 视频章节（UP 主分段，笔记骨架） |
| `download_audio` | 音频轨直连下载（不经 yt-dlp） |
| `asr_transcribe` | 必剪 ASR 语音转字幕（srt/lrc/txt/json） |
| `list_comments` | 评论区只读（热门/最新） |
| `list_uploader_videos` | UP 主投稿列表 |
| `list_uploader_collections` / `get_collection_videos` | 合集与合集内视频 |
| `list_favorite_folders` / `list_favorite_videos` | 收藏夹只读（需登录） |
| `qr_login_start` / `qr_login_poll` | 扫码登录（跨调用轮询） |
| `batch_download_subtitles` | 批量下载（直调引擎：断点续跑、结构化进度） |

## CLI（批量字幕/音频）

```bash
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

**扫码登录（推荐）**：

```bash
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。

## 测试

```bash
python -m pytest tests/ -q --cov=bilinote       # 离线 101 项（默认跳过真实网络测试）
BILINOTE_LIVE=1 python -m pytest -m live -q     # 真实网络 11 项（搜索/字幕/合集/多P/收藏/入口/MCP 协议）
```

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

## 许可证

MIT © 2026 caiqianzhang。B 站接口协议参考了社区公开文档
（[bilibili-API-collect](https://github.com/SocialSisterYi/bilibili-API-collect)、
[renmu123/biliAPI](https://github.com/renmu123/biliAPI)），实现为原创。

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