Skip to content

docs: unify BiliDigest brand and first-export guide #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
JackMeds wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

docs: unify BiliDigest brand and first-export guide #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
66521b7
docs: unify BiliDigest brand and first-export guide
JackMeds Sep 5, 2026
fc339a1
ci: pin cross-platform brand renderer
JackMeds Sep 5, 2026
7f0eba5
design: remove fixed project indexes from brand artwork
JackMeds Sep 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions .github/workflows/brand-check.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
name: Brand presentation
on:
pull_request:
paths:
- 'README*'
- 'docs/**'
- 'assets/brand/**'
- 'project-brand.json'
- '.github/workflows/brand-check.yml'
workflow_dispatch:
permissions:
contents: read
jobs:
brand:
uses: JackMeds/github-brand/.github/workflows/check.yml@078435fe0dc47d75d46e3faf96bd1d366c10d056
with:
toolkit-ref: 078435fe0dc47d75d46e3faf96bd1d366c10d056
179 changes: 47 additions & 132 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,172 +1,87 @@
# 哔哩摘要笔记
<!-- jackmeds-brand:start -->
<picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/brand/hero-dark.svg">
<img src="assets/brand/hero-light.svg" alt="BiliDigest / 哔哩摘要笔记 — A video queue, ready for your next idea." width="1200">
</picture>
<!-- jackmeds-brand:end -->

面向个人 Agent 工作流的 B站收藏与稍后再看摘要工具。
# BiliDigest / 哔哩摘要笔记

[English README](README_en.md)
把“稍后再看”里的视频，整理成能检索、能回看来源的笔记。

许可证：GPL-3.0-or-later。
面向个人 Agent 工作流的 B站字幕与摘要导出工具。读取本人已登录账号的稍后再看与收藏夹，优先使用现成字幕和 B站 AI 小助手总结，输出 Markdown、SRT 与 JSON。

**BiliDigest / 哔哩摘要笔记** 用于读取本人已登录 B站账号可访问的视频，把“稍后再看”和“收藏夹”中的内容整理成 Markdown/SRT/JSON，方便 Hermes Agent、Codex 或其他 Agent 做总结、笔记和知识整理。它优先使用 B站现成字幕和 B站 AI 小助手总结，也保留 ASR/大模型转写作为显式 fallback。
[快速开始](#快速开始) · [批量处理与登录迁移](docs/usage.md) · [Agent Skill](skills/bili-digest/SKILL.md) · [English](README_en.md)

## 功能
## 从视频到笔记

- 使用统一的用户数据目录 session，并兼容迁移旧版 `.user_session.json`。
- 列出稍后再看、收藏夹目录、收藏夹内容。
- 稍后再看列表会缓存到本地，避免 Agent 重启后反复拉取 500+ 条列表。
- 列表命令会返回远端 `total`，即使用 `--limit 1` 也能快速知道稍后再看/收藏夹总数。
- 批量任务带持久状态文件，支持断点续跑、跳过已完成和失败项。
- 优先使用 B站已有字幕，不默认跑 ASR。
- 可导出 B站 AI 小助手总结。
- 输出到 `output/bilidigest/<日期>/`。
- Whisper/Qwen/OpenAI/Gemini 保留为显式 fallback，不再作为主流程。
![BiliDigest 真实命令与字幕转换输出，使用明确标记的示例数据](assets/brand/product-proof.png)

本项目不是 B站 API 文档库，也不是第三方客户端。定位是本地优先的个人 Agent 辅助工具。
字幕 Markdown 保留视频来源和时间戳链接，可以从一条笔记回到视频中的对应位置。输出目录为 `output/bilidigest/<日期>/`；字幕导出会同时保存 `.md`、`.srt` 与 `.subtitle.json`。

## 安装
## 核心能力

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

## 登录

```bash
python -m tools.bilidigest auth status
python -m tools.bilidigest auth import-browser edge
python -m tools.bilidigest auth login
```

默认登录态统一保存到 macOS 用户数据目录：

```text
~/Library/Application Support/BiliDigest/session.json
```
- **先取现成内容。** 优先导出 B站字幕和可用的 AI 小助手总结，不默认启动 ASR。
- **整理自己的收藏。** 列出稍后再看、收藏夹目录与内容，结果包含远端总数。
- **保存批量进度。** 本地缓存、快照与状态文件支持续跑，默认跳过已完成及已失败项目。
- **接入 Agent。** CLI 提供 JSON 输出和非阻塞扫码登录流程，仓库附带 `bili-digest` Skill。

`auth import-browser edge` 会通过 `yt-dlp` 导入 Microsoft Edge 里的 B站 Cookie，并保存到这份共享 session。扫码登录仍然保留：它会同时输出紧凑终端二维码、可复制登录 URL，并保存图片到 `output/login_qr.png`。旧版 BiliSubNotes session 和项目根目录 `.user_session.json` 只作为兼容 fallback；如果存在且有效，会尽量迁移到共享 session。
## 快速开始

如果调用方是 Hermes Agent、Telegram bot 或 TUI，使用非阻塞 JSON 登录流程：
需要 Python 3.10+。在终端中安装项目依赖：

```bash
python -m tools.bilidigest auth login --json --no-wait
python -m tools.bilidigest auth poll <qrcode_key> --json
python -m tools.bilidigest auth status --json
git clone https://github.com/JackMeds/BiliDigest.git
cd BiliDigest
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

第一条命令会返回 `login_url`、`qr_image`、`qrcode_key` 和 `poll_command`。聊天 Agent 把 URL 或二维码图片发给用户，再轮询直到状态变成 `logged_in`、`expired`、`scanned` 或 `pending`。

查看当前共享 session 位置：

```bash
python -m tools.bilidigest auth session-path --json
```
Windows PowerShell 的虚拟环境激活命令为 `.\.venv\Scripts\Activate.ps1`。依赖中仍包含可选转写工具使用的模型库，安装体积可能较大；基本字幕导出流程不需要另配大模型 API Key。

## 使用
### 导出第一条字幕

```bash
# 稍后再看
python -m tools.bilidigest list watch-later --limit 15
python -m tools.bilidigest list watch-later --limit 600 --no-items

# 本人收藏夹目录
python -m tools.bilidigest list favorites --mid me
# 用 Bilibili App 扫描终端中的二维码
python -m tools.bilidigest auth login

# 指定收藏夹内容
python -m tools.bilidigest list favorite --media-id 123456 --limit 15
# 先查看一条稍后再看，取得其中的真实 BV 号
python -m tools.bilidigest list watch-later --limit 1

# 导出字幕
# 将下面的占位 BV 号替换为上一步返回的 bvid
python -m tools.bilidigest transcript BVxxxxxxxxxx --format md
python -m tools.bilidigest transcript "https://www.bilibili.com/video/BVxxxxxxxxxx" --format srt

# 导出 B站 AI 小助手总结
python -m tools.bilidigest summary BVxxxxxxxxxx

# 批量处理稍后再看
python -m tools.bilidigest batch watch-later --limit 15 --with-summary
python -m tools.bilidigest batch watch-later --limit 600 --fallback-summary --with-summary
```

旧命令仍保留兼容：`python -m tools.auth --status`、`python -m tools.list --watch-later`、`python -m tools.batch_run`。
终端会返回生成文件的路径。没有字幕时，可对该视频尝试 `python -m tools.bilidigest summary BVxxxxxxxxxx`，但 AI 小助手总结也不保证可用。

### 批量处理和续跑

`batch watch-later` 默认使用本地缓存和状态文件：

```text
output/bilidigest/cache/watch-later.jsonl
output/bilidigest/cache/watch-later.meta.json
output/bilidigest/snapshots/watch-later.json
output/bilidigest/state/watch-later.json
```

默认列表缓存有效期是 24 小时。每次刷新列表时会更新快照并记录 `added`、`removed`、`changed`，方便日更自动化判断新增和移除。日常自动化或 Hermes Agent 重启后，直接重复运行同一条 `batch` 命令即可续跑；已完成视频会跳过，之前失败的视频也会跳过，避免反复请求同一个视频。

常用参数：
首次单条导出成功后，再处理最多 15 条：

```bash
# 强制刷新稍后再看列表
python -m tools.bilidigest batch watch-later --limit 600 --refresh-list

# 每天自动化：刷新列表，但只处理本次快照新增的视频
python -m tools.bilidigest batch watch-later --limit 600 --refresh-list --only-new --fallback-summary

# 忽略旧状态，从当前列表重新处理
python -m tools.bilidigest batch watch-later --limit 600 --no-resume
python -m tools.bilidigest batch watch-later --limit 15 --fallback-summary
```

`--retry-failed` 只适合人工排查某个短时间故障后手动使用，不要放进日常自动化或大批量后台任务。无字幕、无 AI 总结的视频失败一次就应保留失败状态。

如果视频没有 B站现成字幕，`--fallback-summary` 会尝试导出 B站 AI 小助手总结，并把该条记录为 `summary_only`。遇到登录失效、HTTP `412`、B站 `-352` 等风控信号时，批处理会保存状态并停止。
重复同一条批量命令即可续跑。收藏夹命令、浏览器登录态导入、缓存刷新、仅处理新增和失败状态说明见[完整使用参考](docs/usage.md)。

## Agent Skill
## 隐私与限制

Skill 位于：
- 只处理本人账号原本可访问的内容。现有字幕或 AI 总结不可用时，保留失败状态；Whisper、Qwen、OpenAI、Gemini 转写是需要显式选择的其他路径。
- Cookie 与登录 Session 保存在本机。缓存、字幕和摘要同样是本地文件；Git 忽略规则不等同于加密，分享输出前请自行检查内容。
- 请求默认限速，批量默认 15 条。遇到登录失效、HTTP `412` 或 B站 `-352` 等风控响应会保存状态并停止；不要并发启动多个批处理或在日常任务中循环重试失败项。
- 当前统一 `transcript` 入口处理视频的第一个分 P；字幕选择与结果取决于 B站接口和账号权限。

```text
skills/bili-digest/
```
## Agent 与开发文档

仓库采用 Agent Skills 标准目录：每个 Skill 是一个目录，目录内必须有 `SKILL.md`。因此标准安装器可以直接发现它：

```bash
npx skills add . --list
npx skills add . --skill bili-digest -g -a codex -y
```

如果从公开 GitHub 仓库安装，HTTPS 可以直接使用：
安装 Skill 前先保留本仓库与 Python 环境，并将 `BILIDIGEST_HOME` 设置为 clone 的绝对路径。Skill 安装器只安装指令，不安装 Python 项目本体：

```bash
npx skills add https://github.com/JackMeds/BiliDigest --skill bili-digest -g -a codex -y
```

SSH 形式也可以，但前提是 `ssh -T git@github.com` 能通过。本机当前 GitHub SSH 未打通，所以更建议用 HTTPS 或本地路径。

`npx skills` 安装的是 Skill 指令，不会自动安装 Python 项目本体。仍然需要保留本仓库 clone 和 `.venv` 依赖。Skill 内置了 `skills/bili-digest/scripts/bilidigest` 启动器，会通过 `BILIDIGEST_HOME` 或默认本机路径找到真正的 CLI。

本机开发时也可以继续用软链接安装，优点是改 Skill 文档后立即生效：

```bash
python install.py --target ~/.agents/skills
```

日常更新可以这样做：

```bash
git pull
npx skills add . --skill bili-digest -g -a codex -y
```

## 安全默认值
[中文使用参考](docs/usage.md) · [English reference](docs/usage.en.md) · [CLI 入口](tools/bilisub.py) · [现有测试](tests/)

- 批量命令默认最多处理 `15` 条。
- 请求默认故意很慢：每次 API 调用大约等待 `8-12` 秒。可以用 `BILIDIGEST_DELAY_SECONDS` 和 `BILIDIGEST_DELAY_JITTER_SECONDS` 调整。
- 大批量处理建议使用默认慢速或稍微调到 `BILIDIGEST_DELAY_SECONDS=6 BILIDIGEST_DELAY_JITTER_SECONDS=2`，不要并发启动多个批处理。
- 旧的视频/音频下载入口也会使用单 fragment 和慢速 `yt-dlp` sleep 参数。可以用 `BILIDIGEST_YTDLP_SLEEP_SECONDS` 和 `BILIDIGEST_YTDLP_MAX_SLEEP_SECONDS` 调整。
- 遇到 HTTP `412` 或 B站 `-352` 等风控信号会停止批处理。
- Cookie、Session、`.env` 和输出目录均被 Git 忽略。
- 只处理本人账号本来就能访问的内容。
贡献时可提交脱敏的错误信息、最小复现与预期输出。请不要附带 Cookie、Session、私人收藏列表或完整导出包。

## 鸣谢
## 许可与鸣谢

BiliDigest 的功能边界和安全策略参考了开源 B站工具的实践，特别是采用 GPL-3.0-or-later 协议的 [BiliTools](https://github.com/btjawa/BiliTools)。本项目不迁入 BiliTools 的 Tauri UI，只保留轻量 Python CLI，供本地 Agent 使用。归属和参考说明见 [NOTICE](NOTICE)。
本项目采用 [GPL-3.0-or-later](LICENSE)。功能边界与安全策略参考了 [BiliTools](https://github.com/btjawa/BiliTools) 的开源实践，未迁入其 Tauri UI。归属与参考说明见 [NOTICE](NOTICE)。
Loading
Loading