Metadata-Version: 2.4
Name: bilinote
Version: 0.2.0
Summary: B 站视频转笔记工具集：批量字幕下载 / 必剪 ASR 转写 / MCP 工具面
Author: caiqianzhang
License-Expression: MIT
Project-URL: Homepage, https://github.com/caiqianzhang/bilinote
Project-URL: Issues, https://github.com/caiqianzhang/bilinote/issues
Project-URL: Changelog, https://github.com/caiqianzhang/bilinote/blob/main/CHANGELOG.md
Keywords: bilibili,subtitle,mcp,mcp-server,asr,claude-code,codex,note-taking
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31
Requires-Dist: browser-cookie3>=0.16
Requires-Dist: mcp<2,>=1
Requires-Dist: qrcode>=7.2
Requires-Dist: pillow>=10
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Dynamic: license-file

# 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 环境）**

```bash
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 或使用尚未发布的改动时）：

```bash
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](https://github.com/caiqianzhang/bilinote/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](docs/release.md)。

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

## MCP 接入

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

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

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

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

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

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

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

```jsonc
"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 个）

| 工具 | 说明 |
|---|---|
| `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       # 离线 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](https://github.com/SocialSisterYi/bilibili-API-collect)、
[renmu123/biliAPI](https://github.com/renmu123/biliAPI)），实现为原创。

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