@xzxzzx/bilibili-mcp 1.10.0 → 1.11.0

package/README.md

@@ -1,7 +1,3 @@
-<p align="center">
-  <img src="./assets/readme/hero.svg" width="100%" alt="Bilibili MCP：从视频搜索到带时间定位的字幕证据">
-</p>
-
 # Bilibili MCP
 
 <p align="center">
@@ -10,76 +6,209 @@
   <a href="https://www.gnu.org/licenses/gpl-3.0"><img src="https://img.shields.io/badge/License-GPLv3-blue.svg" alt="GPL-3.0 license"></a>
 </p>
 
-<p align="center">
-  让 Codex、Claude、Cursor 等 AI 客户端直接搜索 Bilibili 或读取当前账号收藏夹，并获取字幕、时间定位、元数据、章节与热门评论。
-</p>
+Bilibili MCP 是一个本地 MCP server，让 AI Agent 读取 Bilibili 内容：读取字幕与评论，按主题搜索视频，遍历自己账号的收藏夹。即使视频没有字幕，通过 `setup` 安装本地 ASR 模型后也能读到它的文字内容。
 
 <p align="center">
   <a href="./README_EN.md">English</a> ·
-  <a href="./docs/client-setup.md">全部 Agent / 客户端配置</a> ·
+  <a href="./docs/client-setup.md">客户端配置指南</a> ·
   <a href="./docs/tool-reference.md">工具参考</a> ·
+  <a href="#本地-asr可选">本地 ASR（可选）</a> ·
   <a href="./CHANGELOG.md">更新日志</a> ·
-  <a href="https://www.npmjs.com/package/@xzxzzx/bilibili-mcp">npm</a> ·
   <a href="https://github.com/XZXZZX-Ai/bilibili-mcp/releases/latest">最新 Release</a>
 </p>
 
+<p align="center">
+  <img src="./assets/readme/hero-overview.png" width="100%" alt="搜索到的视频经过本地 MCP server 处理，产出带时间点的字幕、章节、评论和收藏夹结果">
+</p>
+
+<p align="center"><sub>搜索候选 → 本地 MCP → 字幕定位 · 章节 · 评论 · 收藏夹</sub></p>
+
+## 它能做什么
+
+- **读字幕与评论**：读取字幕全文，或用关键词搜索原话——每条命中附带上下文、时间点和可直接跳转的 B 站时刻链接；阅读按热度（默认）或时间排序的评论与回复，含时间戳的评论会被优先保留。
+- **读单个视频**：查看标题、作者、播放量等元数据，以及分 P 结构和章节。
+- **找到视频**：按主题搜索 B 站，得到按平台综合排序、带标题、UP 主、时长和 BVID 的候选列表。
+- **浏览收藏夹**：遍历当前登录账号创建、且 Bilibili 当前可见的全部收藏夹，逐页读取其中的视频。
+- **无字幕时本地转录**：对确认没有字幕的视频，可显式选择用本机 ASR（faster-whisper）转录，得到与字幕相同结构的转录结果。默认关闭，可在 `setup` 时选择下载 ASR 模型，详见[本地 ASR（可选）](#本地-asr可选)。
+
+## 快速开始
+
+### 让 Agent 辅助安装（推荐）
+
+把以下提示词完整复制给 Agent：它会完成自己擅长的事（确认客户端、写入 server 配置、检查登录状态），所有涉及 Cookie 的环节都会暂停，交由你本人在本地终端完成。
+
+```text
+请帮我安装 Bilibili MCP server：@xzxzzx/bilibili-mcp。
+
+1. 先确认我当前使用的 MCP 客户端，无法确定时请询问我，不要猜测。
+   同时运行 node --version 确认 Node.js 为 20 或更高；未安装或版本过低时，先引导我安装或升级。
+2. 打开 https://github.com/XZXZZX-Ai/bilibili-mcp/blob/master/docs/client-setup.md，
+   找到与当前客户端匹配的配置小节，添加本地 stdio server：
+   - server 名称：bilibili-mcp
+   - command：npx
+   - args：["-y", "@xzxzzx/bilibili-mcp@latest"]
+3. 不要要求、接收、收集或显示我的 Cookie 值，也不要自行将其写入聊天或客户端配置中。
+4. 暂停并引导我本人在本地终端运行：
+   npx -y @xzxzzx/bilibili-mcp@latest setup
+   npx -y @xzxzzx/bilibili-mcp@latest check
+   npx -y @xzxzzx/bilibili-mcp@latest doctor --json
+   doctor --json 只检查本机配置状态，不能代替后面的实时登录验证。
+   setup 会询问是否安装可选的本地 ASR 模型，选否即可。
+5. 让我重启或重连客户端。你无法代替我完成这一步时，请明确让我操作。
+6. 重连后调用 MCP 工具 check_bilibili_credentials。
+   只有 configured: true 且 logged_in: true 才报告成功。
+   - configured: false 或 needs_credentials → 让我运行 npx -y @xzxzzx/bilibili-mcp@latest setup
+   - logged_in: false → 让我运行 npx -y @xzxzzx/bilibili-mcp@latest config 强制重配，然后重连再检查
+   - MCP server 不可用 → 检查客户端配置并重连
+7. 验证成功后：调用一次 search_bilibili_videos（任选主题，如"离散数学"），
+   能返回视频列表即说明 Agent 已可读取 Bilibili。
+```
+
+### 手动安装
+
+**前置条件：**[Node.js](https://nodejs.org/) 20+
+
+不想用 Agent 辅助时，按下面四步完成同样的流程：
+
+1. **确认环境** — 在终端运行 `node --version` 和 `npx --version`，确保 Node.js 为 v20 或更高版本。
+2. **添加服务** — 在 MCP 客户端中新增 stdio server：`command` 设为 `npx`，`args` 设为 `-y`, `@xzxzzx/bilibili-mcp@latest`。具体操作见[客户端配置指南](./docs/client-setup.md#客户端配置)。
+3. **本地配置** — 在终端运行 `npx -y @xzxzzx/bilibili-mcp@latest setup` 配置凭证，再运行 `npx -y @xzxzzx/bilibili-mcp@latest check` 确认凭证已加载。`npx -y @xzxzzx/bilibili-mcp@latest doctor --json` 可获取不含秘密的本机配置状态。
+
+   输入不回显，Cookie 只进入本地隐藏提示符，不要粘贴到 Agent 聊天或客户端配置里。凭证字段怎么找：见[从浏览器获取凭证字段](./docs/client-setup.md#从浏览器获取凭证字段)。`setup` 还会询问是否安装可选的本地 ASR 模型（默认否），见[本地 ASR（可选）](#本地-asr可选)。
+4. **验证登录** — 重连客户端后，让 Agent 调用 MCP 工具 `check_bilibili_credentials` 确认 `configured: true` 且 `logged_in: true`。`doctor --json` 只检查本机状态，不能代替这一步的实时登录验证。验证成功后，再让 Agent 调用一次 `search_bilibili_videos`（任选主题），能返回视频列表即安装完成。
+
+<p align="center">
+  <img src="./assets/readme/install-flow.svg" width="100%" alt="安装流程：环境 → 接入 → 凭证 → 验证 → 成功，手动与 Agent 辅助安装共用同一骨架">
+</p>
+
+凭证保存在 `~/.bilibili-mcp/config.json`（Windows：`%USERPROFILE%\.bilibili-mcp\config.json`），不保证操作系统级加密。登录失败时的排查路径见[客户端配置指南](./docs/client-setup.md#凭证配置与验证)。
+
+## 使用示例
+
+### 读取视频的字幕与评论
+
+```text
+读取 BV1Eb411u7Fw 的字幕，带时间戳返回；
+再获取这个视频最热门的评论和回复。
+```
+
+Agent 返回带时间戳的字幕文本，以及热门评论与回复；含时间戳的评论会被优先保留。
+
+### 按主题搜索视频
+
+```text
+搜索 B 站上关于"离散数学"的视频，按 B 站综合排序列出 5 个候选，
+包含标题、UP 主、时长和 BVID；先不要读取字幕。
+```
+
+Agent 返回 5 个候选，各带标题、UP 主、时长和 BVID。选中候选后，把 BVID 直接交给转录、元数据、章节或评论工具。
+
+### 在转录中定位原话和时刻
+
+```text
+读取 BV1Eb411u7Fw 的 P4 字幕，搜索"函数"，
+返回命中上下文、时间点和可以直接打开的 B 站链接。
+```
+
+每条命中附带原文上下文、时间点和可直达的 B 站时刻链接。
+
 > [!NOTE]
-> **真实验收链路：**搜索视频 → 选择 `BV1Eb411u7Fw` 的 P4 → 在字幕中搜索“函数” → 返回上下文与可直达的 [`?p=4&t=1.12`](https://www.bilibili.com/video/BV1Eb411u7Fw/?p=4&t=1.12) 证据链接。搜索与转录成功结果同时提供兼容文本和 MCP `structuredContent`。
+> **已验证的验收链路：**搜索视频 → 选择 `BV1Eb411u7Fw` 的 P4 → 在字幕中搜索 `函数` → 返回上下文与可直达的 [`?p=4&t=1.12`](https://www.bilibili.com/video/BV1Eb411u7Fw/?p=4&t=1.12) 证据链接。Bilibili 可能移除或变更该示例视频。
 
-## ⚡ 安装与配置
+### 遍历全部收藏夹
 
-Agent 安装提示词、全部客户端配置位置、CLI / JSON / TOML 示例、Cookie 配置与登录验证步骤，都集中在：
+<p align="center">
+  <img src="./assets/readme/hero.svg" width="100%" alt="收藏夹遍历流程：收藏夹 → 读一页 → next_cursor → 完成，分页循环直到 next_cursor 不再出现">
+</p>
 
-### [打开完整 Agent / 客户端安装指南 →](./docs/client-setup.md)
+```text
+遍历我当前登录账号创建且 Bilibili 当前可见的全部收藏夹。持续跟随
+next_cursor 直到结束；按收藏夹列出成功读取的视频标题和 B 站视频 ID（BVID），
+并报告 skipped_count。
+```
 
-> [!IMPORTANT]
-> 本 README 不再重复任何安装或配置方法。请以安装指南为唯一完整来源。
+每次 MCP 调用最多读取一个 20 条的上游页面；Agent 使用返回的 `next_cursor` 继续调用，直到该字段不再出现。最终按收藏夹输出成功读取的标题与 BVID 列表，以及被跳过的条目计数。
 
-安装完成后，可以直接向 AI 提问：
+### 给没有字幕的视频做本地转录
 
 ```text
-搜索 Bilibili 上的 MCP 入门视频，选一个候选，
-再从字幕中找出“工具调用”的出现位置并给我时间链接。
+这个视频没有字幕。请调用 get_video_transcript 并把 fallback_to_asr 设为 true，
+用本地 ASR 转录当前这一 P，返回带时间戳的文本。
 ```
 
-## 🧰 工具一览
+前提是已经通过 `setup` 安装了模型且 `doctor --json` 报告 `asr.status: ready`，否则会返回 `ASR_NOT_READY` 并附带安装指引。原生字幕始终优先：只有确认没有可用字幕时才会启动一次本地转录，结果返回 `data_source: "asr"`，并复用与字幕相同的时间戳、区间过滤、关键词搜索和时刻链接。详见[本地 ASR](#本地-asr可选)。
 
-| 目标 | 工具 | 返回重点 |
-|---|---|---|
-| 只有主题，还没有视频链接 | `search_bilibili_videos` | 最多 10 个普通视频候选及可继续调用的 BVID |
-| 从我的 Bilibili 收藏夹开始读取 | `list_bilibili_favorite_videos` | 当前账号下所有创建的收藏夹的分页视频；按 `next_cursor` 翻页直到结束 |
-| 获取纯字幕或定位关键词 | `get_video_transcript` | 转录文本、语言、时间戳、区间过滤、关键词上下文与证据链接 |
-| 让 AI 总结视频 | `get_video_info` | 字幕优先；无字幕时可返回标题、简介和标签 |
-| 查看结构化视频信息 | `get_video_metadata` | 标题、作者、时长、发布时间、标签、统计数据和多 P 列表 |
-| 查看视频章节 | `get_video_chapters` | 创作者或平台定义的章节标题与起止时间 |
-| 查看观众反馈 | `get_video_comments` | 热门评论、时间戳评论和可选回复 |
-| 获取安全配置步骤 | `get_credential_setup_instructions` | 本机凭证配置命令与双语安全提醒 |
-| 检查登录凭证 | `check_bilibili_credentials` | 配置来源、登录状态和下一步建议，不返回 Cookie |
-| 检查 MCP 更新 | `check_mcp_update` | 当前版本、最新版本和安全更新命令 |
+## 本地 ASR（可选）
+
+有些视频没有任何字幕。安装本地 ASR 模型后，`get_video_transcript` 可以在你显式开启 `fallback_to_asr` 时，对已解析的这一 P 做一次本地转录。
 
-完整参数、JSON 示例、结构化错误和请求控制见[工具参考](./docs/tool-reference.md)。
+**安装：**凭证配置完成后，`setup` 会询问是否安装本地 ASR 模型（默认否 `[y/N]`，需要 Python 3.9+）。可选模型：
 
-### 关键能力
+| 模型 | 大小 | 说明 |
+|---|---|---|
+| tiny | ~78 MB | 最小占用 |
+| base | ~148 MB | 折中选择 |
+| small | ~486 MB | 推荐，Enter 默认选中 |
 
-- **先发现、再阅读**：按主题搜索普通视频候选，或从当前账号的收藏夹分页发现视频，再把返回的 BVID 交给字幕、元数据、章节或评论工具。
-- **可验证的字幕证据**：支持多 P、语言偏好、时间戳、时间区间和关键词上下文；命中项包含可直达播放时刻的 `timestamp_url`。
-- **结构化输出**：视频搜索、视频转录和收藏夹分页的成功结果同时提供兼容文本与 MCP `structuredContent`。
-- **明确的失败语义**：区分凭证失效、无字幕、访问受限、限流、超时和其他 API 错误，并给出下一步建议。
-- **安全的凭证助手**：检查凭证状态时不返回 `SESSDATA`、`bili_jct`、`DedeUserID` 或完整 Cookie。
+Runtime 固定为 `faster-whisper==1.2.1`，模型存放在用户目录 `~/.bilibili-mcp/asr/`，通过 CPU INT8 加载验证后才算就绪，不需要系统 FFmpeg；同一目录仅保留一个活跃模型。`doctor --json` 的 `asr.status` 和 `asr.model` 报告就绪状态与已选模型（纯信息字段，不影响凭证退出状态）。
 
-## 🧭 行为边界
+**边界：**本地转录始终被约束在安全范围内——显式选择、资源受限、Cookie 隔离：
 
-- 视频搜索要求已配置且有效的 Bilibili 登录 Cookie，不提供匿名降级。
-- 收藏夹发现要求已登录的当前账号身份，每次调用仅返回一个上游 20 条资源页；`next_cursor` 是无状态、版本化的不透明令牌，仅包含下一个 Folder 与页码，不会编码 Cookie、账号 ID、Folder 标题或视频数据。
-- `get_video_transcript` 默认在无字幕时返回 `SUBTITLE_UNAVAILABLE`；只有显式设置 `fallback_to_description: true` 才会退回简介。
-- 时间戳、区间过滤和关键词搜索不会静默退回简介，避免把描述误当作字幕证据。
-- 章节来自 Bilibili 创作者或平台数据；没有章节时返回空列表，不推断章节。
-- 本项目不会绕过付费、会员、地区、私密、下架或其他访问限制。
-- 所有请求由用户本机发起；本项目是第三方工具，不是 Bilibili 官方服务。
+- 原生 B 站字幕始终优先；只有确认无字幕、且你显式传了 `fallback_to_asr: true` 才启动转录。
+- MCP 调用不会下载或切换模型；模型只通过 `setup` 安装。
+- 一次只运行一个转录任务；单 P 时长上限 2 小时、音频上限 128 MiB、转录超时 30 分钟。
+- 临时音频在成功、失败、超时等所有路径上都会被清理。
+- Cookie 只发给 B 站官方接口，绝不发给 CDN 或本地 Python 子进程。
+- 凭证、HTTP、限流等错误照常返回，不会被伪装成"没有字幕"。
 
-## 🛠️ 开发
+`ASR_NOT_READY`、`ASR_BUSY`、`ASR_TRANSCRIPTION_TIMEOUT` 等错误码的完整语义见[工具参考](./docs/tool-reference.md)。
 
-源码开发环境的安装步骤也集中在[完整安装指南：从源码开发](./docs/client-setup.md#从源码开发)。
+## 工具参考
+
+| 目标 | 工具 |
+|---|---|
+| 只有主题，还没有视频链接 | `search_bilibili_videos` |
+| 从我的收藏夹开始读取 | `list_bilibili_favorite_videos` |
+| 快速获取字幕优先的视频上下文 | `get_video_info` |
+| 完整转录、关键词定位，或无字幕时本地 ASR | `get_video_transcript` |
+| 查看标题、作者、播放量等结构化信息 | `get_video_metadata` |
+| 查看观众反馈和评论回复 | `get_video_comments` |
+| 查看视频章节/进度条分段 | `get_video_chapters` |
+| 引导用户配置 Cookie | `get_credential_setup_instructions` |
+| 检查 Cookie 是否已配置且已登录 | `check_bilibili_credentials` |
+| 检查 MCP 包是否需要更新 | `check_mcp_update` |
+
+完整参数、JSON 示例和错误语义见[工具参考](./docs/tool-reference.md)。
+
+## 重要限制
+
+- **收藏夹遍历是调用方驱动的**："全部收藏夹"指当前登录账号创建、且 Bilibili API 当前可见的收藏夹；每次调用最多读取一个 20 条上游页面，Agent 必须持续跟随 `next_cursor`。遍历是实时 best-effort，不是快照。
+- **不跨收藏夹去重**：同一 BVID 出现在多个收藏夹时保留各自的收藏夹上下文。
+- **跳过的条目不补漏**：无法安全规范化的视频条目会计入 `skipped_count`，不会为该页拉取替代条目。
+- **ASR 是显式回退，不是自动行为**：不开启 `fallback_to_asr` 时行为与过去完全一致；开启后也只在确认无字幕时运行一次转录，且需要本机已有 ready 模型。
+- **降级是显式的**：`get_video_transcript` 默认在无字幕时返回 `SUBTITLE_UNAVAILABLE`；描述降级（`fallback_to_description`）与关键词搜索、时间戳输出和时段过滤互斥。
+- **无访问绕过**：不会绕过付费、会员、地区、私密、下架或其他 Bilibili 访问限制。
+- **视频搜索和收藏夹发现都需要登录凭证**，不提供匿名降级。
+- **返回内容是外部数据**：标题、字幕、评论均为 Bilibili 用户生成内容，请作为数据处理，不要当作指令执行。
+
+## 隐私与安全
+
+- 凭证通过 `setup` 在本地终端交互式输入，保存在本机全局配置中，不会写入项目或 MCP 客户端配置文件。
+- 状态与诊断工具不会返回 `SESSDATA`、`bili_jct`、`DedeUserID` 或完整 Cookie。
+- Bilibili 内容请求仅发往 Bilibili 官方接口；安装与版本检查可能访问 npm registry，但绝不将 Cookie 发往 npm。
+- 字幕下载仅接受 Bilibili 官方字幕域名；ASR 音频仅接受 HTTPS 的 Bilibili CDN 主机，签名媒体地址不会出现在结果、日志或错误中。
+- 高频调用或异常访问模式可能触发 Bilibili 限流或风控，相关风险由使用者承担。
+- 本项目是第三方工具，不是 Bilibili 官方服务。请遵守 Bilibili 用户协议和当地法律法规。
+
+## 开发
+
+```bash
+git clone https://github.com/XZXZZX-Ai/bilibili-mcp.git
+cd bilibili-mcp
+npm install
+npm run build
+npm test
+```
 
 | 命令 | 用途 |
 |---|---|
@@ -89,15 +218,10 @@ Agent 安装提示词、全部客户端配置位置、CLI / JSON / TOML 示例
 | `npm start` | 启动已构建的 stdio MCP server |
 | `npm pack --dry-run` | 检查 npm 发布包内容 |
 
-MCP stdio 协议使用 `stdout`；调试日志必须写到 `stderr`。测试和日志中不要使用真实 Cookie。
+MCP stdio 协议数据使用 `stdout`；调试日志必须写到 `stderr`。测试和日志中不要使用真实 Cookie。
 
-## ⚖️ 安全与许可
-
-- 请遵守 Bilibili 用户协议、接口访问规则和当地法律法规，不要用于大规模抓取、商业剥削、绕过权限或其他滥用场景。
-- 高频调用、异常访问模式或 Cookie 泄露可能触发限流、风控或账号异常，相关风险由使用者承担。
-- 本项目仅向 Bilibili 官方接口发送 Bilibili 凭证，不会把 Cookie 上传到第三方服务；本地配置文件不承诺系统级加密。
-- 本项目基于 [GNU General Public License v3.0](./LICENSE) 开源。
-
-## 💬 反馈
+## 帮助与许可
 
 遇到问题或有功能建议，请提交 [GitHub Issue](https://github.com/XZXZZX-Ai/bilibili-mcp/issues)；一般讨论可前往 [GitHub Discussions](https://github.com/XZXZZX-Ai/bilibili-mcp/discussions)。
+
+本项目基于 [GNU General Public License v3.0](./LICENSE) 开源。

package/README_EN.md

@@ -1,7 +1,3 @@
-<p align="center">
-  <img src="./assets/readme/hero-en.svg" width="100%" alt="Bilibili MCP: from video discovery to timestamped transcript evidence">
-</p>
-
 # Bilibili MCP
 
 <p align="center">
@@ -10,76 +6,215 @@
   <a href="https://www.gnu.org/licenses/gpl-3.0"><img src="https://img.shields.io/badge/License-GPLv3-blue.svg" alt="GPL-3.0 license"></a>
 </p>
 
-<p align="center">
-  Search Bilibili or read the current account's Favorite Folders from Codex, Claude, Cursor, and other AI clients, then retrieve transcripts, timestamps, metadata, chapters, and popular comments.
-</p>
+Bilibili MCP is a local MCP server that lets AI agents read Bilibili: transcripts and comments, video search by topic, and a walk through your account's Favorite Folders. Even videos without subtitles become readable once you install the local ASR model.
 
 <p align="center">
   <a href="./README.md">简体中文</a> ·
-  <a href="./docs/client-setup.en.md">All agent / client setups</a> ·
+  <a href="./docs/client-setup.en.md">Client setup guide</a> ·
   <a href="./docs/tool-reference.en.md">Tool reference</a> ·
+  <a href="#local-asr-optional">Local ASR (optional)</a> ·
   <a href="./CHANGELOG_EN.md">Changelog</a> ·
-  <a href="https://www.npmjs.com/package/@xzxzzx/bilibili-mcp">npm</a> ·
   <a href="https://github.com/XZXZZX-Ai/bilibili-mcp/releases/latest">Latest release</a>
 </p>
 
+<p align="center">
+  <img src="./assets/readme/hero-overview.png" width="100%" alt="Searched videos pass through the local MCP server and yield timestamped transcripts, chapters, comments, and Favorite Folder results">
+</p>
+
+<p align="center"><sub>Search candidates → local MCP → transcript search · chapters · comments · favorites</sub></p>
+
+## What it does
+
+- **Read transcripts and comments** — pull the full transcript or search it for keywords, every match carrying context, a timestamp, and a direct Bilibili link to that moment; read hot- (default) or time-sorted comments and replies, with timestamped comments kept with priority.
+- **Read a single video** — fetch metadata such as title, creator, and play counts, plus the multi-part structure and chapters.
+- **Find videos** — search Bilibili by topic and get candidates in Bilibili's platform order, each with title, creator, duration, and BVID.
+- **Browse favorites** — traverse every Favorite Folder your logged-in account created and Bilibili currently shows, page by page.
+- **Transcribe subtitle-less videos locally** — for videos confirmed to have no subtitles, opt in to a local faster-whisper transcription that returns the same transcript shape as subtitles. Off by default; you can choose to download an ASR model during `setup`. See [Local ASR (optional)](#local-asr-optional).
+
+## Get started
+
+### Install with Agent assistance (recommended)
+
+Copy the full prompt below to your Agent. It handles everything it safely can — identifying your client, writing the server configuration, and checking login state — and pauses for you whenever a step touches your Cookie:
+
+```text
+Please help me install the Bilibili MCP server: @xzxzzx/bilibili-mcp.
+
+1. First identify which MCP client I'm using. Ask me if you can't tell — don't guess.
+   Also run node --version to confirm Node.js is 20 or newer; if missing or older, guide me to install or upgrade first.
+2. Open https://github.com/XZXZZX-Ai/bilibili-mcp/blob/master/docs/client-setup.en.md,
+   find the matching client section, and add a local stdio server:
+   - server name: bilibili-mcp
+   - command: npx
+   - args: ["-y", "@xzxzzx/bilibili-mcp@latest"]
+3. Never request, receive, collect, or display my Cookie values, and never write
+   them into chat or client config yourself.
+4. Stop and guide me to run these in my own local terminal:
+   npx -y @xzxzzx/bilibili-mcp@latest setup
+   npx -y @xzxzzx/bilibili-mcp@latest check
+   npx -y @xzxzzx/bilibili-mcp@latest doctor --json
+   doctor --json checks local configuration only; it does not replace the live login verification below.
+   setup will ask about installing the optional local ASR model; choosing no is fine.
+5. Ask me to restart or reconnect the client. When you can't do it for me,
+   tell me explicitly to do it myself.
+6. After reconnect, call the MCP tool check_bilibili_credentials.
+   Only report success when configured: true and logged_in: true.
+   - configured: false or needs_credentials → have me run npx -y @xzxzzx/bilibili-mcp@latest setup
+   - logged_in: false → have me run npx -y @xzxzzx/bilibili-mcp@latest config to force
+     reconfiguration, then reconnect and recheck
+   - MCP server unavailable → review client config and reconnect
+7. After verification succeeds: call search_bilibili_videos once (any topic, e.g.
+   "discrete mathematics"). A returned video list confirms the Agent can read Bilibili.
+```
+
+### Install manually
+
+**Prerequisite:** [Node.js](https://nodejs.org/) 20+
+
+Prefer to do it yourself? The same flow takes four steps:
+
+1. **Check your environment** — run `node --version` and `npx --version` in a terminal to confirm Node.js is v20 or later.
+2. **Add the server** — add a stdio server in your MCP client: `command` set to `npx`, `args` set to `-y`, `@xzxzzx/bilibili-mcp@latest`. Per-client steps live in the [client setup guide](./docs/client-setup.en.md#client-configuration).
+3. **Configure locally** — run `npx -y @xzxzzx/bilibili-mcp@latest setup` in your terminal to configure credentials, then `npx -y @xzxzzx/bilibili-mcp@latest check` to confirm they load. `npx -y @xzxzzx/bilibili-mcp@latest doctor --json` reports the secret-free local configuration state.
+
+   Input is not echoed; Cookie values go only into hidden local prompts — never paste them into Agent chat or client configuration. Where to find each field: [Finding credential fields in your browser](./docs/client-setup.en.md#finding-credential-fields-in-your-browser). `setup` also asks whether to install an optional local ASR model (default no); see [Local ASR (optional)](#local-asr-optional).
+4. **Verify the login** — after reconnecting the client, have your Agent call the MCP tool `check_bilibili_credentials` and confirm `configured: true` and `logged_in: true`. `doctor --json` only inspects local state; it does not replace this live login check. Once verification passes, have the Agent call `search_bilibili_videos` once (any topic); a returned video list means the installation is complete.
+
+<p align="center">
+  <img src="./assets/readme/install-flow-en.svg" width="100%" alt="Installation flow: Runtime → Connect → Credentials → Verify → Success — one skeleton shared by manual and Agent-assisted installs">
+</p>
+
+Credentials are stored at `~/.bilibili-mcp/config.json` (Windows: `%USERPROFILE%\.bilibili-mcp\config.json`). Operating-system-level encryption is not guaranteed. For login-failure troubleshooting, see the [client setup guide](./docs/client-setup.en.md#credential-setup-and-verification).
+
+## Usage examples
+
+### Read a video's transcripts and comments
+
+```text
+Read the transcript of BV1Eb411u7Fw with timestamps,
+then pull its most popular comments and replies.
+```
+
+The Agent returns timestamped transcript lines, then hot comments with replies; comments containing timestamps are kept with priority.
+
+### Search for videos by topic
+
+```text
+Search Bilibili for videos about "discrete mathematics". List 5 candidates
+in Bilibili's overall platform order, with title, creator, duration, and
+BVID. Do not fetch transcripts yet.
+```
+
+The agent returns 5 candidates with title, creator, duration, and BVID. After choosing a candidate, pass its BVID straight to the transcript, metadata, chapter, or comment tools.
+
+### Find exact lines and moments in a transcript
+
+```text
+Read Part 4 of BV1Eb411u7Fw and search its transcript for the Chinese keyword
+"函数". Return the matching context, time, and a Bilibili link to that moment.
+```
+
+Each hit comes with the surrounding text, a timestamp, and a direct Bilibili moment link.
+
 > [!NOTE]
-> **Verified workflow:** search → select Part 4 of `BV1Eb411u7Fw` → search its transcript for “函数” → receive bounded context and a direct [`?p=4&t=1.12`](https://www.bilibili.com/video/BV1Eb411u7Fw/?p=4&t=1.12) evidence link. Successful search and transcript calls provide both compatible text and MCP `structuredContent`.
+> **Verified workflow:** search → select Part 4 of `BV1Eb411u7Fw` → search its transcript for `函数` → receive bounded context and a direct [`?p=4&t=1.12`](https://www.bilibili.com/video/BV1Eb411u7Fw/?p=4&t=1.12) evidence link. Bilibili may remove or change this example video.
 
-## ⚡ Installation and configuration
+### Traverse every visible Favorite Folder
 
-The copyable Agent prompt, every client configuration location, CLI / JSON / TOML examples, Cookie setup, and login-verification flow are centralized in:
+<p align="center">
+  <img src="./assets/readme/hero-en.svg" width="100%" alt="Favorites traversal flow: Folders → Read page → next_cursor → Complete, looping until next_cursor stops appearing">
+</p>
 
-### [Open the complete Agent / client installation guide →](./docs/client-setup.en.md)
+```text
+Traverse every Favorite Folder created by my currently logged-in account and
+currently visible through Bilibili. Keep following next_cursor until complete.
+Group successfully read video titles and Bilibili video IDs (BVIDs) by Folder,
+and report skipped_count.
+```
 
-> [!IMPORTANT]
-> This README no longer duplicates installation or configuration methods. Treat the installation guide as the complete source.
+Each MCP call reads at most one upstream page of 20 rows. The Agent continues with the returned `next_cursor` until that field is absent. The final answer lists successfully read titles and BVIDs per folder, plus the skipped-entry count.
 
-After installation, ask your AI client:
+### Transcribe a video that has no subtitles
 
 ```text
-Search Bilibili for an introductory MCP video, select one candidate,
-then find “tool call” in its transcript and give me a timestamp link.
+This video has no subtitles. Call get_video_transcript with fallback_to_asr
+set to true and transcribe the current Part with local ASR. Return timestamped
+text.
 ```
 
-## 🧰 Tool overview
+This requires a model installed through `setup` and `doctor --json` reporting `asr.status: ready`; otherwise the call returns `ASR_NOT_READY` with setup guidance. Native subtitles always win: a local transcription starts only when subtitles are confirmed unavailable, returns `data_source: "asr"`, and reuses the same timestamps, range filters, keyword search, and moment links. See [Local ASR](#local-asr-optional).
 
-| Goal | Tool | What it returns |
-|---|---|---|
-| Start with a topic, not a video URL | `search_bilibili_videos` | Up to 10 normal-video candidates with reusable BVIDs |
-| Start from my Bilibili Favorites | `list_bilibili_favorite_videos` | One bounded page of videos from the current account's created Favorite Folders; follow `next_cursor` until it is absent |
-| Get a transcript or locate a keyword | `get_video_transcript` | Text, language, timestamps, range filters, keyword context, and evidence links |
-| Ask AI to summarize a video | `get_video_info` | Subtitles first; title, description, and tags when subtitles are unavailable |
-| Inspect structured video information | `get_video_metadata` | Title, creator, duration, publish time, tags, statistics, and multi-Part listing |
-| Read video chapters | `get_video_chapters` | Creator- or platform-defined chapter titles and time ranges |
-| Inspect viewer feedback | `get_video_comments` | Popular comments, timestamped comments, and optional replies |
-| Get safe credential instructions | `get_credential_setup_instructions` | Local setup commands and bilingual security notes |
-| Check login credentials | `check_bilibili_credentials` | Source, login status, and recovery steps without Cookie values |
-| Check for package updates | `check_mcp_update` | Current/latest versions and safe update commands |
+## Local ASR (optional)
+
+Some videos ship without any subtitle. Once you install a local ASR model, `get_video_transcript` can run one bounded local transcription of the resolved Part when you explicitly pass `fallback_to_asr`.
 
-See the [tool reference](./docs/tool-reference.en.md) for complete parameters, JSON examples, structured errors, and request controls.
+**Installation:** after credentials are configured, `setup` asks whether to install a local ASR model (defaults to No `[y/N]`, requires Python 3.9+). Available models:
 
-### Key capabilities
+| Model | Size | Notes |
+|---|---|---|
+| tiny | ~78 MB | smallest footprint |
+| base | ~148 MB | middle ground |
+| small | ~486 MB | recommended, selected on Enter |
 
-- **Discover, then inspect:** search by topic, or page through the current account's Favorite Folders, then pass a returned BVID to transcript, metadata, chapter, or comment tools.
-- **Verifiable transcript evidence:** select a Part and language, include timestamps, filter time ranges, or search with bounded context; each match can include a direct `timestamp_url`.
-- **Structured output:** successful video search, transcript, and Favorites-page calls provide compatible text plus MCP `structuredContent`.
-- **Explicit failures:** distinguish expired credentials, missing subtitles, access restrictions, rate limits, timeouts, and other API errors, with actionable recovery steps.
-- **Credential-safe helpers:** status checks never return `SESSDATA`, `bili_jct`, `DedeUserID`, or a complete Cookie.
+The runtime is pinned to `faster-whisper==1.2.1`. Models live under `~/.bilibili-mcp/asr/`, are verified by a CPU INT8 load before being marked ready, and do not require system FFmpeg; only one active model is kept per directory. `doctor --json` reports readiness and the selected model via `asr.status` and `asr.model` (informational fields that never affect credential exit codes).
 
-## 🧭 Behavior boundaries
+**Boundaries:** local transcription stays within safe bounds — opt-in, resource-capped, Cookie-isolated:
 
-- Video search requires a configured, valid Bilibili login Cookie and does not fall back to anonymous search.
-- Favorites discovery requires the current logged-in account identity, returns at most one upstream 20-row resource page per call, and the `next_cursor` is a stateless, versioned opaque token that encodes only the next Folder and page number — never Cookie values, account IDs, Folder titles, or Video data.
-- `get_video_transcript` returns `SUBTITLE_UNAVAILABLE` by default when no subtitle exists; it falls back to the description only when `fallback_to_description: true` is explicit.
-- Timestamp output, time-range filtering, and keyword search never silently fall back to a description.
-- Chapters come from Bilibili creator/platform data. The tool returns an empty list when no chapter data exists; it does not infer chapters.
-- This project does not bypass paid, member-only, regional, private, removed, or other access restrictions.
-- Requests originate on the user's machine. This is a third-party project, not an official Bilibili service.
+- Native Bilibili subtitles always win; transcription starts only on confirmed no-subtitle states with an explicit `fallback_to_asr: true`.
+- MCP calls never download or switch models; models install only through `setup`.
+- One transcription at a time; per-Part duration capped at 2 hours, audio at 128 MiB, transcription timeout at 30 minutes.
+- Temporary audio is removed on every success, failure, and timeout path.
+- The Cookie goes only to official Bilibili APIs — never to CDN hosts or the local Python child process.
+- Credential, HTTP, and throttling errors surface as-is; they are never disguised as "no subtitles".
 
-## 🛠️ Development
+For the full semantics of error codes such as `ASR_NOT_READY`, `ASR_BUSY`, and `ASR_TRANSCRIPTION_TIMEOUT`, see the [tool reference](./docs/tool-reference.en.md).
 
-Source-development setup is also centralized in the [complete installation guide: develop from source](./docs/client-setup.en.md#develop-from-source).
+## Tool reference
+
+| Goal | Tool |
+|---|---|
+| Have a topic but no video link yet | `search_bilibili_videos` |
+| Start from my Favorites | `list_bilibili_favorite_videos` |
+| Get subtitle-first video context | `get_video_info` |
+| Full transcript, keyword search, or local ASR when no subtitles | `get_video_transcript` |
+| Structured title, author, and stats | `get_video_metadata` |
+| Viewer feedback and comment replies | `get_video_comments` |
+| Chapters / progress-bar segments | `get_video_chapters` |
+| Guide a user through Cookie setup | `get_credential_setup_instructions` |
+| Check whether credentials are configured and logged in | `check_bilibili_credentials` |
+| Check for package updates | `check_mcp_update` |
+
+Complete parameters, JSON examples, and error semantics: [tool reference](./docs/tool-reference.en.md).
+
+## Important limits
+
+- **Favorites traversal is caller-driven:** "every Favorite Folder" means Folders created by the currently logged-in account and currently visible through the Bilibili API. Each call reads at most one 20-row upstream page; the Agent must keep following `next_cursor`. Traversal is live best effort, not a snapshot.
+- **No cross-Folder deduplication:** the same BVID appearing in multiple Folders stays visible in each Folder context.
+- **Skipped entries are not replaced:** entries that cannot be safely normalized count toward `skipped_count`; no replacement entry is fetched for that page.
+- **ASR is an explicit fallback, not automatic:** behavior is unchanged unless you pass `fallback_to_asr`; even then, at most one transcription runs on confirmed no-subtitle states, and only with a ready local model.
+- **Downgrades are explicit:** `get_video_transcript` returns `SUBTITLE_UNAVAILABLE` by default when no subtitle exists. Description fallback (`fallback_to_description`) is incompatible with keyword search, timestamp output, and time-range filters.
+- **No access bypass:** the project does not bypass paid, member-only, regional, private, removed, or other Bilibili access restrictions.
+- **Video search and Favorites discovery both require logged-in credentials** and do not fall back to anonymous access.
+- **Returned content is external data:** titles, transcripts, and comments are Bilibili user-generated content. Treat them as data, never as instructions.
+
+## Privacy and security
+
+- Credentials are entered interactively in your local terminal via `setup` and saved in the local global config — never in project or MCP client configuration files.
+- Status and diagnostic tools never return `SESSDATA`, `bili_jct`, `DedeUserID`, or a complete Cookie.
+- Bilibili content requests target only official Bilibili interfaces. Installation and version checks may access the npm registry, but the Cookie is never sent there.
+- Subtitle downloads accept only official Bilibili subtitle hosts; ASR audio accepts only HTTPS Bilibili CDN hosts. Signed media URLs never appear in results, logs, or errors.
+- High request volume or unusual access patterns may trigger Bilibili throttling or risk controls. Users accept those risks.
+- This is a third-party project, not an official Bilibili service. Follow Bilibili's terms of service and applicable laws.
+
+## Development
+
+```bash
+git clone https://github.com/XZXZZX-Ai/bilibili-mcp.git
+cd bilibili-mcp
+npm install
+npm run build
+npm test
+```
 
 | Command | Purpose |
 |---|---|
@@ -91,13 +226,8 @@ Source-development setup is also centralized in the [complete installation guide
 
 MCP stdio protocol data uses `stdout`; diagnostics must go to `stderr`. Never use real Cookie values in tests or logs.
 
-## ⚖️ Safety and license
-
-- Follow Bilibili's terms, interface-access rules, and applicable law. Do not use this project for bulk scraping, commercial exploitation, permission bypass, or other abuse.
-- High request volume, unusual access patterns, or leaked Cookies may trigger throttling, risk controls, or account issues. Users accept those risks.
-- The project sends Bilibili credentials only to official Bilibili interfaces and does not upload Cookies to third-party services. Local credential files do not promise operating-system-level encryption.
-- This project is licensed under the [GNU General Public License v3.0](./LICENSE).
-
-## 💬 Feedback
+## Help and license
 
 For bugs and feature requests, open a [GitHub Issue](https://github.com/XZXZZX-Ai/bilibili-mcp/issues). Use [GitHub Discussions](https://github.com/XZXZZX-Ai/bilibili-mcp/discussions) for general questions.
+
+This project is licensed under the [GNU General Public License v3.0](./LICENSE).