bili-transcript 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dongliang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,136 @@
-# Temporary Holding Version
+# bili-transcript
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+提取 B 站视频的**文字稿、字幕和 AI 总结**。零依赖，扫码登录，纯命令行。
+
+```sh
+npx bili-transcript BV1xx411c7mD --plain
+```
+
+## 它能做什么
+
+- 把任意 B 站视频的字幕扒成文字，带不带时间戳都行
+- 拿 B 站官方的 **AI 视频总结**（带章节和时间点）
+- 支持 BV 号 / av 号 / 完整链接 / b23.tv 短链
+- 支持合集视频的分P
+- 给 agent 用的 `--json` 结构化输出
+
+## 安装
+
+```sh
+npm install -g bili-transcript     # 全局
+npx bili-transcript <目标>          # 或者直接用，不装
+```
+
+需要 **Node 18+**（用到内置 fetch）。没有其他依赖，一条 `npm i` 装完不到 100 KB。
+
+装好后有两个等价的命令：**`bili-transcript`**（全名）和 **`bili`**（简写）。
+
+> 全局安装报 `EACCES: permission denied, mkdir '/usr/lib/node_modules/...'`？
+> 那是 npm 想往系统目录写。别用 sudo，改成装到自己的目录：
+> ```sh
+> npm config set prefix ~/.local
+> npm install -g bili-transcript
+> ```
+> 再把 `~/.local/bin` 加进 PATH（fish：`fish_add_path ~/.local/bin`）。
+> 或者干脆不装，用 `npx`。
+
+## 快速开始
+
+```sh
+bili login                          # 扫码登录，一次就够
+bili BV1xx411c7mD --plain           # 提取文字稿
+bili "https://b23.tv/xxxxx" --plain -o out.txt
+bili BV1xx411c7mD --summary         # 顺带拿 AI 总结
+bili doctor                         # 出问题了先跑这个
+```
+
+## 为什么需要登录
+
+B 站的字幕接口现在强制登录。不登录的话，接口返回的是**空数组**——看起来像"这视频没字幕"，其实是被挡住了。所以必须先登一次。
+
+**登录全程在你的机器上完成，凭据只存在本地。** 扫码用的是 B 站官方的二维码登录接口（就是网页版"扫码登录"用的那个），和任何第三方服务器无关。凭据写在 `~/.config/bili/auth.json`，权限 `0600`。
+
+扫码登录**不会把你手机上的 B 站 App 踢下线**——同一个账号支持多端同时在线。
+
+## 命令
+
+```
+bili <BV号|av号|URL> [选项]     提取文字稿（默认动作）
+bili fetch <目标> [选项]        同上，显式写法
+bili login [选项]              扫码登录
+bili doctor                    自检：环境 / 凭据 / 接口
+bili install-skill [选项]      把 skill 装到本地 agent
+```
+
+### 提取选项
+
+| 选项 | 作用 |
+|---|---|
+| `--plain` | 只出连续文字，不带时间戳 |
+| `--json` | 结构化输出，给程序或 agent 解析 |
+| `-p, --page N` | 取第 N 个分P |
+| `--list` | 只列出字幕轨，不下载正文 |
+| `--summary` | 附带 B 站 AI 总结 |
+| `-o, --out FILE` | 写入文件 |
+
+### 登录选项
+
+| 选项 | 作用 |
+|---|---|
+| `--png <路径>` | 额外写出二维码图片 |
+| `--qr-only` | 只生成二维码，稍后用 `--resume` 继续 |
+| `--resume` | 用上次的二维码继续轮询 |
+| `--timeout N` | 轮询超时秒数（默认 180） |
+| `--force` | 已登录时强制重新登录 |
+
+## 给 agent 用
+
+```sh
+npx skills add dongliang/bili-transcript
+```
+
+装了之后 Claude Code、Codex 这类 agent 会在你提到"这个视频讲了什么"时自动调用它。
+
+agent 内部请用 `--json` 拿结构化数据：
+
+```json
+{
+  "ok": true,
+  "bvid": "BV14Z4R6KEHS",
+  "title": "128G 超大内存，密密麻麻全是颗粒",
+  "duration": 175,
+  "uploader": "韩宇修机",
+  "lines": [{ "from": 0, "to": 1.96, "text": "128G大内存" }],
+  "summary": { "text": "…", "outline": [] }
+}
+```
+
+## 已知限制
+
+- **字幕是 AI 自动生成的，有错别字。** 实测中 `CAMM` 被写成 "cam"、`信号线阻值` 被写成 "信号线组织"。**专有名词请核实物件丝印或官方资料**，别直接引用。
+- 没有字幕轨的视频（纯音乐、MV、CG 常见）拿不到文字，会明确告诉你而不是编造。
+- 只支持 B 站。其他平台是另一件事。
+- 登录状态会过期（通常几个月）。失效时 `doctor` 会告诉你，重新 `bili login --force` 即可。
+
+## 设计说明
+
+**零依赖是刻意的。** 核心只用 Node 内置的 `fetch`、`crypto`、`fs`。唯一的难点是二维码——没有引 `qrcode` 这类库，而是自己实现了一个（GF(256) 纠错、Reed-Solomon、掩码择优、连 PNG 都是手写的）。代价是 13 KB 代码，换来的是整个包不到 100 KB，且没有供应链风险。
+
+**只用 `x/player/wbi/v2` 拿字幕，不回退到旧接口。** 旧接口 `x/player/v2` 会返回**别的视频**的字幕——对一条无字幕的 MV 连测 4 次，拿到 4 段完全无关的内容。这种错用户看不出来，只会觉得字幕莫名其妙，所以宁可报"没有字幕"也不给错数据。
+
+**内置数据自洽校验。** 拿到字幕后会检查末条时间戳贴不贴合视频时长。不贴合就告警——这是防"拿到错误数据"的最后一道闸。
+
+## 开发
+
+```sh
+git clone https://github.com/dongliang/bili-transcript
+cd bili-transcript
+npm link            # 让全局 bili 指向本地代码
+sh tests/fulltest.sh
+```
+
+测试脚本在 `tests/`。改动二维码编码器（`src/qr.mjs`）后必须跑二维码的两个专项测试——**二维码错了不会报错，只会扫不出来**。
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: bilibili-transcript
+description: 提取 B 站视频的文字稿/字幕/文案，或拿 B 站官方的 AI 视频总结；也用于帮用户登录 B 站账号。当用户给了一个 bilibili.com 链接、BV 号、av 号（包括 b23.tv 短链），并说"把字幕扒下来""视频讲了什么""转成文字""要文字稿/文案""总结这个视频""提取台词"时使用。也适用于用户说"帮我看这个视频的内容"而没有时间自己看的情况。
+---
+
+# B 站视频文字稿
+
+用 `bili` 命令。已装（`npm i -g bili-transcript` 或 `npx bili-transcript`）。
+
+## 提取文字稿
+
+```sh
+bili <BV号|av号|URL> --plain        # 最常用：连续文字，无时间戳
+bili <目标> -o out.txt              # 长视频务必写文件
+bili <目标> --json                  # 给程序解析
+```
+
+| 选项 | 作用 |
+|---|---|
+| `--plain` | 只出连续文字，不带时间戳。**给 AI 读、给人读都用这个** |
+| `--json` | 结构化输出（含 `lines[]` / `subtitles[]` / `summary`） |
+| `-p N` | 取第 N 个分P（合集视频必用） |
+| `--list` | 只列出字幕轨 |
+| `--summary` | 附带 B 站 AI 总结（带章节时间点） |
+| `-o FILE` | 写入文件 |
+
+**b23.tv 短链先解析**：
+
+```sh
+curl -s -o /dev/null -w '%{url_effective}' -L "https://b23.tv/XXXXXX"
+```
+
+## 凭据
+
+字幕接口强制登录。凭据查找顺序（自动，不用问用户要）：
+
+1. 环境变量 `BILI_SESSDATA`
+2. `~/.config/bili/auth.json`（`bili login` 写的位置）
+3. `/var/minis/offloads/env_cookies_bilibili*.sh`（Minis 里浏览器导出的 cookie）
+
+**任何时候不要打印 SESSDATA 的值**，只说"有没有"。
+
+## 登录（扫码）
+
+```sh
+bili login                      # 终端画出二维码（SSH / CI 也能用）
+bili login --png /tmp/qr.png    # 额外写图片，方便手机扫
+bili login --qr-only            # 只生成二维码，存下 key
+bili login --resume             # 用存下的 key 继续轮询
+bili login --force              # 已登录时强制重登
+```
+
+**推荐两步走**：先 `--qr-only --png <路径>` 生成 → 把图片展示给用户 → 再 `--resume`。用户有充足时间扫，不会因轮询超时白扫。
+
+轮询间隔 2 秒，二维码约 3 分钟过期。成功后整组 5 个 cookie 存到 `~/.config/bili/auth.json`（0600）。
+
+## 出问题了先跑自检
+
+```sh
+bili doctor
+```
+
+它会分清是**接口变了**、**凭据过期了**、还是**环境有问题**。凭据失效时输出里会出现 `-101`，让用户 `bili login --force` 重登即可。
+
+## 踩过的坑（别重犯）
+
+1. **只用 `x/player/wbi/v2`，绝对不要碰 `x/player/v2`。** 老接口会返回**别的视频**的字幕——实测对一条无字幕的 MV 连测 4 次，得到 4 段完全无关的内容。工具已改成拿不到就明说，**不要静默给出错误数据**。
+2. **wbi 签名**：`w_rid` = md5(排序后 query + mixin)。混淆表要完整。
+3. **`getSetCookie()` 在部分 Node 构建上对 fetch 响应不可用**，`get('set-cookie')` 可能返回**数组**。两种都兼容。
+4. `x/web-interface/search/type` 未登录会 HTTP 412（风控）。
+5. 字幕 CDN 链接的 `auth_key` 有时效（几小时），别存下来当永久地址。
+6. `--list` 输出每次都会变（auth_key 是时间签名），别拿它做逐字节比对。
+
+## 输出给用户时
+
+- 长视频文字稿**不要打印到对话里**，写文件 + 给 `[name](minis://workspace/...)` 链接。
+- 字幕是 **AI 自动生成**的，错别字和发音误识别很常见。实测例：`CAMM` 全篇写成 "cam"、`信号线阻值` 写成 "信号线组织"、`焊球` 写成 "气球"。
+- **遇到专有名词，别信字幕，去核实物件上的丝印或官方资料。** 硬件类视频尤其如此——封面标签往往比口播准确。
+- 没有字幕轨（纯音乐/MV/CG 常见）就直说没有，别硬编。
+
+## 不接受的情况
+
+- 用户明确说"不要登录""别用我账号"→ 只剩"下音频 + 外部 ASR"。如实说明，不要假装能本地跑。
+- **不要打包浏览器、不要去读系统浏览器的 cookie 库。** 扫码方案已验证可行且更轻。

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "bili-transcript",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "提取 B 站视频的文字稿、字幕和 AI 总结。零依赖，扫码登录，纯命令行。",
+  "type": "module",
+  "bin": {
+    "bili-transcript": "src/cli.mjs",
+    "bili": "src/cli.mjs"
+  },
+  "files": [
+    "src/",
+    "SKILL.md",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "bilibili",
+    "b站",
+    "字幕",
+    "subtitle",
+    "transcript",
+    "cli",
+    "agent-skill",
+    "claude-code",
+    "codex"
+  ],
+  "license": "MIT",
+  "author": "dongliang",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dongliang/bili-transcript.git"
+  },
+  "homepage": "https://dongliang.github.io/bili-transcript/",
+  "bugs": {
+    "url": "https://github.com/dongliang/bili-transcript/issues"
+  },
+  "scripts": {
+    "test": "node tests/ci-check.mjs",
+    "doctor": "node src/cli.mjs doctor"
+  },
+  "dependencies": {},
+  "optionalDependencies": {}
+}

package/src/api.mjs

@@ -0,0 +1,74 @@
+// B 站接口封装 —— wbi 签名、请求、错误处理
+import { createHash } from 'node:crypto';
+import { findSessdata } from './auth.mjs';
+
+export const API = 'https://api.bilibili.com';
+export const UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
+
+const MIXIN_TAB = [
+  46,47,18,2,53,8,23,32,15,50,10,31,58,3,45,35,27,43,5,49,33,9,42,19,
+  29,28,14,39,12,38,41,13,37,48,7,16,24,55,40,61,26,17,0,1,60,51,30,4,
+  22,25,54,21,56,59,6,63,57,62,11,36,20,34,44,52,
+];
+
+export function headers() {
+  const h = { 'User-Agent': UA, Referer: 'https://www.bilibili.com/' };
+  const { value } = findSessdata();
+  if (value) h.Cookie = 'SESSDATA=' + value;
+  return h;
+}
+
+export async function getJson(url, extraHeaders) {
+  const r = await fetch(url, { headers: { ...headers(), ...(extraHeaders || {}) } });
+  return r.json();
+}
+
+/** wbi 签名：w_rid = md5(排序后 query + mixin) */
+export async function wbiQuery(params) {
+  const nav = (await getJson(API + '/x/web-interface/nav')).data.wbi_img;
+  const orig = nav.img_url.split('/').pop().split('.')[0] + nav.sub_url.split('/').pop().split('.')[0];
+  const mixin = MIXIN_TAB.map((i) => orig[i]).join('').slice(0, 32);
+  const p = { ...params, wts: Math.floor(Date.now() / 1000) };
+  const enc = (o) => new URLSearchParams(Object.entries(o).sort((a, b) => (a[0] < b[0] ? -1 : 1))).toString();
+  const q = enc(p).replace(/[!'()*]/g, '');
+  p.w_rid = createHash('md5').update(q + mixin).digest('hex');
+  return enc(p);
+}
+
+export class BiliError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = 'BiliError';
+  }
+}
+
+export function check(r, what) {
+  if (r.code !== 0) {
+    if (r.code === -101) {
+      throw new BiliError(-101, `${what}：账号未登录。请先运行 \`bili login\` 扫码登录。`);
+    }
+    throw new BiliError(r.code, `${what} 失败：code=${r.code} ${r.message || ''}`);
+  }
+  return r.data;
+}
+
+export function parseBvid(s) {
+  let m = String(s).match(/BV[0-9A-Za-z]{10}/);
+  if (m) return m[0];
+  m = String(s).match(/av(\d+)/i);
+  if (m) return 'av' + m[1];
+  throw new BiliError('bad-input', `认不出视频号：${s}`);
+}
+
+/** 时间戳格式化：<1 分钟用 mm:ss.mmm，超过 1 小时用 hh:mm:ss.mmm */
+export function ts(sec) {
+  sec = Number(sec || 0);
+  const h = Math.floor(sec / 3600);
+  const m = Math.floor((sec % 3600) / 60);
+  const s = sec % 60;
+  const p = (n, w) => String(n).padStart(w, '0');
+  const ms = p(Math.round((s % 1) * 1000), 3);
+  return h ? `${p(h, 2)}:${p(m, 2)}:${p(Math.floor(s), 2)}.${ms}`
+           : `${p(m, 2)}:${p(Math.floor(s), 2)}.${ms}`;
+}

package/src/auth.mjs

@@ -0,0 +1,45 @@
+// 凭据管理 —— 查找、读取、保存、校验
+import { readFileSync, writeFileSync, mkdirSync, chmodSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+
+export const AUTH_PATH = join(homedir(), '.config', 'bili', 'auth.json');
+export const COOKIE_DIR = '/var/minis/offloads';
+
+/** 按 环境变量 → auth.json → 浏览器导出文件 的顺序找 SESSDATA */
+export function findSessdata() {
+  const env = (process.env.BILI_SESSDATA || '').trim();
+  if (env) return { value: env, source: 'env BILI_SESSDATA' };
+
+  if (existsSync(AUTH_PATH)) {
+    try {
+      const c = JSON.parse(readFileSync(AUTH_PATH, 'utf8'));
+      if (c.SESSDATA) return { value: c.SESSDATA, source: AUTH_PATH };
+    } catch { /* 坏了就当没有 */ }
+  }
+
+  try {
+    const files = readdirSync(COOKIE_DIR)
+      .filter((f) => f.startsWith('env_cookies_bilibili'))
+      .map((f) => join(COOKIE_DIR, f))
+      .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
+    if (files.length) {
+      const m = readFileSync(files[0], 'utf8').match(/^(?:export\s+)?COOKIE_SESSDATA=(.+)$/m);
+      if (m) return { value: m[1].trim().replace(/^["']|["']$/g, ''), source: files[0] };
+    }
+  } catch { /* 目录不存在就算了 */ }
+
+  return { value: null, source: null };
+}
+
+export function loadAuth() {
+  if (!existsSync(AUTH_PATH)) return null;
+  try { return JSON.parse(readFileSync(AUTH_PATH, 'utf8')); } catch { return null; }
+}
+
+export function saveAuth(jar) {
+  mkdirSync(dirname(AUTH_PATH), { recursive: true });
+  writeFileSync(AUTH_PATH, JSON.stringify(jar, null, 2) + '\n', 'utf8');
+  try { chmodSync(AUTH_PATH, 0o600); } catch { /* 有的文件系统不支持，忽略 */ }
+  return AUTH_PATH;
+}

package/src/cli.mjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+// bili —— B 站视频文字稿提取工具
+//
+//   bili <BV号|av号|URL> [选项]     提取文字稿（最常用，可省略 fetch）
+//   bili fetch <目标> [选项]        同上
+//   bili login [选项]              扫码登录
+//   bili doctor                    自检
+//   bili install-skill [选项]      把 skill 装到本地 agent
+//
+import { writeFileSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { fetchVideo, renderText } from './fetch.mjs';
+import { login } from './login.mjs';
+import { BiliError } from './api.mjs';
+
+// 版本号从 package.json 读，避免写死后漂移
+const VERSION = (() => {
+  try {
+    const p = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+    return JSON.parse(readFileSync(p, 'utf8')).version;
+  } catch { return 'unknown'; }
+})();
+
+const HELP = `
+bili-transcript —— B 站视频文字稿提取
+（命令名 bili-transcript，简写 bili，两者等价）
+
+用法
+  bili <BV号|av号|URL> [选项]     提取文字稿
+  bili fetch <目标> [选项]        同上（显式写法）
+  bili login [选项]              扫码登录
+  bili doctor                    自检：环境 / 凭据 / 接口
+  bili install-skill [选项]      安装 agent skill
+  bili --help                    看这份帮助
+  bili --version                 看版本
+
+提取选项
+  --plain            只出连续文字，不带时间戳（喂给 AI 用这个）
+  --json             输出 JSON（给程序/agent 解析）
+  -p, --page N       取第 N 个分P
+  --list             只列出字幕轨，不下载正文
+  --summary          附带 B 站 AI 总结
+  -o, --out FILE     写入文件
+
+登录选项
+  --png <路径>       额外写出二维码图片
+  --qr-only          只生成二维码，稍后用 --resume 继续
+  --resume           用上次的二维码继续轮询
+  --timeout N        轮询超时秒数（默认 180）
+  --force            已登录时强制重新登录
+
+示例
+  bili BV1xx411c7mD --plain
+  bili "https://b23.tv/xxxxx" --summary -o out.txt
+  bili login --png /tmp/qr.png
+  bili login --qr-only && bili login --resume
+`.trim();
+
+function parseArgs(argv) {
+  const o = { _: [], plain: false, json: false, list: false, summary: false, out: null, page: 1 };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--plain') o.plain = true;
+    else if (a === '--json') o.json = true;
+    else if (a === '--list') o.list = true;
+    else if (a === '--summary') o.summary = true;
+    else if (a === '--qr-only') o.qrOnly = true;
+    else if (a === '--resume') o.resume = true;
+    else if (a === '--force') o.force = true;
+    else if (a === '-p' || a === '--page') o.page = parseInt(argv[++i], 10);
+    else if (a === '-o' || a === '--out') o.out = argv[++i];
+    else if (a === '--png') o.png = argv[++i];
+    else if (a === '--timeout') o.timeout = parseInt(argv[++i], 10);
+    else if (a === '-h' || a === '--help') o.help = true;
+    else if (a === '-v' || a === '--version') o.version = true;
+    else o._.push(a);
+  }
+  return o;
+}
+
+function die(msg, code = 1) {
+  console.error(msg);
+  process.exit(code);
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (!argv.length) { console.log(HELP); return; }
+
+  // 允许 `bili --help` / `bili --json <url>` 这类全局选项打头
+  const SUBCOMMANDS = ['fetch', 'login', 'doctor', 'install-skill'];
+  let cmd, rest;
+  if (SUBCOMMANDS.includes(argv[0])) {
+    cmd = argv[0]; rest = argv.slice(1);
+  } else {
+    cmd = 'fetch'; rest = argv;
+  }
+  const o = parseArgs(rest);
+  if (o.help) { console.log(HELP); return; }
+  if (o.version) { console.log(VERSION); return; }
+
+  // ---- login ----
+  if (cmd === 'login') {
+    try {
+      const r = await login(o);
+      if (r.qrOnly && o.json) console.log(JSON.stringify(r, null, 2));
+    } catch (e) { die(`登录失败：${e.message}`); }
+    return;
+  }
+
+  // ---- doctor ----
+  if (cmd === 'doctor') {
+    const { runDoctor } = await import('./doctor.mjs');
+    const ok = await runDoctor({ json: o.json });
+    process.exit(ok ? 0 : 1);
+  }
+
+  // ---- install-skill ----
+  if (cmd === 'install-skill') {
+    const { installSkill } = await import('./install-skill.mjs');
+    const ok = await installSkill(o);
+    process.exit(ok ? 0 : 1);
+  }
+
+  // ---- fetch（默认动作）----
+  const target = o._[0];
+  if (!target) die('请提供视频 BV号 / av号 / URL。用 `bili --help` 看用法。');
+
+  let v;
+  try {
+    v = await fetchVideo(target, { page: o.page, summary: o.summary });
+  } catch (e) {
+    if (e instanceof BiliError && e.code === -101) die(e.message);
+    die(e.message || String(e));
+  }
+
+  let text;
+  if (o.json) {
+    text = JSON.stringify({
+      ok: true,
+      bvid: v.bvid, title: v.title, part: v.part, page: v.page, pageCount: v.pageCount,
+      duration: v.duration, uploader: v.uploader, url: v.url,
+      subtitles: v.subtitles,
+      lines: v.body,
+      warning: v.warning,
+      noSubtitleReason: v.noSubtitleReason || null,
+      summary: v.summary,
+    }, null, 2) + '\n';
+  } else {
+    text = renderText(v, { plain: o.plain, list: o.list });
+  }
+
+  if (o.out) {
+    writeFileSync(o.out, text, 'utf8');
+    console.log(`已写入 ${o.out}（${text.length} 字符，${v.body.length} 条字幕）`);
+  } else {
+    process.stdout.write(text);
+  }
+}
+
+main().catch((e) => die(e.stack || String(e)));

package/src/doctor.mjs

@@ -0,0 +1,83 @@
+// 自检 —— 一眼分清「接口变了」还是「该重新登录了」
+import { API, getJson, wbiQuery, headers } from './api.mjs';
+import { findSessdata, AUTH_PATH } from './auth.mjs';
+
+const R = { pass: 0, fail: 0, warn: 0 };
+const ok = (m) => { R.pass++; console.log(`  ✅ ${m}`); };
+const bad = (m) => { R.fail++; console.log(`  ❌ ${m}`); };
+const soft = (m) => { R.warn++; console.log(`  ⚠️  ${m}`); };
+
+export async function runDoctor({ json = false } = {}) {
+  const log = json ? () => {} : console.log;
+
+  log('\n== 运行时 ==');
+  const major = Number(process.versions.node.split('.')[0]);
+  major >= 18 ? ok(`Node ${process.versions.node}`) : bad(`Node ${process.versions.node} 太旧，需要 >=18（自带 fetch）`);
+  typeof fetch === 'function' ? ok('全局 fetch 可用') : bad('没有全局 fetch');
+
+  log('\n== 凭据 ==');
+  const { value: sd, source } = findSessdata();
+  if (sd) ok(`SESSDATA 长度 ${sd.length}，来自 ${source}`);
+  else bad(`找不到凭据。运行 \`bili login\` 扫码登录（默认位置 ${AUTH_PATH}）`);
+
+  if (sd) {
+    log('\n== 凭据可用性 ==');
+    const r = await getJson(`${API}/x/web-interface/nav`).catch(() => null);
+    if (r && r.code === 0 && r.data.isLogin) ok(`已登录：${r.data.uname}（uid ${r.data.mid}）`);
+    else if (r && r.code === -101) bad('凭据已失效，运行 `bili login --force` 重新登录');
+    else bad(`nav 接口异常：${r ? 'code=' + r.code : '连不上'}`);
+  }
+
+  log('\n== 接口连通 ==');
+  const BV = 'BV14Z4R6KEHS';   // 固定样本，便于跨时间对比
+  const view = await getJson(`${API}/x/web-interface/view?bvid=${BV}`).catch(() => null);
+  if (view && view.code === 0) ok(`view 接口正常（${String(view.data.title).slice(0, 20)}…）`);
+  else { bad(`view 接口异常：${view ? 'code=' + view.code : '连不上'}`); return finish(json); }
+
+  const { cid, aid, duration } = view.data;
+  log('\n== 字幕接口 ==');
+  let pv;
+  try {
+    const qs = await wbiQuery({ bvid: BV, cid, aid });
+    pv = await getJson(`${API}/x/player/wbi/v2?${qs}`);
+  } catch (e) { bad(`字幕接口请求失败：${e.message}`); return finish(json); }
+
+  if (pv.code !== 0) {
+    bad(`wbi/v2 异常 code=${pv.code} ${pv.message || ''}`);
+  } else {
+    const subs = pv.data.subtitle?.subtitles || [];
+    subs.length ? ok(`wbi/v2 正常，${subs.length} 条字幕轨`)
+                : bad(`wbi/v2 返回 0 条字幕轨（need_login=${pv.data.need_login_subtitle}）`);
+    if (subs.length) {
+      let u = subs[0].subtitle_url;
+      if (u.startsWith('//')) u = 'https:' + u;
+      const body = (await getJson(u).catch(() => null))?.body || [];
+      body.length ? ok(`字幕正文可取（${body.length} 条）`) : bad('字幕正文取不到');
+      if (body.length) {
+        const end = Number(body[body.length - 1].to || 0);
+        // 这一项是防「拿到别的视频字幕」的关键校验
+        end >= duration * 0.7
+          ? ok(`末条 ${end.toFixed(1)}s 贴合视频时长 ${duration}s（数据自洽）`)
+          : bad(`末条只到 ${end.toFixed(1)}s，视频有 ${duration}s —— 可能拿到错误数据！`);
+      }
+    }
+  }
+
+  log('\n== AI 总结接口 ==');
+  if (sd) {
+    try {
+      const qs = await wbiQuery({ bvid: BV, cid, up_mid: String(view.data.owner.mid) });
+      const c = await getJson(`${API}/x/web-interface/view/conclusion/get?${qs}`);
+      c.code === 0 && c.data ? ok('AI 总结可用') : soft(`AI 总结不可用 code=${c.code}`);
+    } catch (e) { soft(`AI 总结请求失败：${e.message}`); }
+  } else soft('无凭据，跳过');
+
+  return finish(json);
+}
+
+function finish(json) {
+  const line = `通过 ${R.pass} / ${R.pass + R.fail}${R.warn ? `（${R.warn} 条提示）` : ''}`;
+  if (json) console.log(JSON.stringify({ ok: R.fail === 0, pass: R.pass, fail: R.fail, warn: R.warn }, null, 2));
+  else console.log(`\n== 结果：${line} ==\n`);
+  return R.fail === 0;
+}