bili-transcript 0.0.0-stage → 1.0.0

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,125 @@
-# 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。
+
+## 快速开始
+
+```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,44 @@
 {
   "name": "bili-transcript",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "提取 B 站视频的文字稿、字幕和 AI 总结。零依赖，扫码登录，纯命令行。",
+  "type": "module",
+  "bin": {
+    "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": "sh tests/fulltest.sh",
+    "selftest": "node src/selftest.mjs"
+  },
+  "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,151 @@
+#!/usr/bin/env node
+// bili —— B 站视频文字稿提取工具
+//
+//   bili <BV号|av号|URL> [选项]     提取文字稿（最常用，可省略 fetch）
+//   bili fetch <目标> [选项]        同上
+//   bili login [选项]              扫码登录
+//   bili doctor                    自检
+//   bili install-skill [选项]      把 skill 装到本地 agent
+//
+import { writeFileSync } from 'node:fs';
+import { fetchVideo, renderText } from './fetch.mjs';
+import { login } from './login.mjs';
+import { BiliError } from './api.mjs';
+
+const HELP = `
+bili —— B 站视频文字稿提取
+
+用法
+  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(process.env.npm_package_version || '1.0.0'); 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;
+}

package/src/fetch.mjs

@@ -0,0 +1,128 @@
+// 提取字幕 / AI 总结 —— 核心逻辑，返回结构化数据
+import { API, getJson, wbiQuery, check, parseBvid, ts } from './api.mjs';
+
+/**
+ * 取视频信息 + 字幕 +（可选）AI 总结
+ * 返回结构化对象，由调用方决定怎么渲染。
+ */
+export async function fetchVideo(target, { page = 1, summary = false } = {}) {
+  const vid = parseBvid(target);
+  const view = check(
+    await getJson(vid.startsWith('av')
+      ? `${API}/x/web-interface/view?aid=${vid.slice(2)}`
+      : `${API}/x/web-interface/view?bvid=${vid}`),
+    '视频信息');
+
+  const bvid = view.bvid;
+  const pages = view.pages;
+  if (page > pages.length) {
+    const e = new Error(`该视频只有 ${pages.length} 个分P`);
+    e.code = 'bad-page';
+    throw e;
+  }
+  const pg = pages[page - 1];
+  const aid = view.aid;
+  const cid = pg.cid;
+
+  const result = {
+    bvid,
+    aid,
+    cid,
+    title: view.title,
+    part: pages.length > 1 ? pg.part : null,
+    page,
+    pageCount: pages.length,
+    duration: pg.duration,
+    uploader: view.owner.name,
+    uploaderMid: view.owner.mid,
+    url: `https://www.bilibili.com/video/${bvid}`,
+    subtitles: [],
+    // ⚠️ 只用 wbi 版。老接口 x/player/v2 会返回别的视频的字幕，绝不回退。
+    body: [],
+    warning: null,
+    summary: null,
+  };
+
+  const pv = check(await getJson(`${API}/x/player/wbi/v2?${await wbiQuery({ bvid, cid, aid })}`), '字幕列表');
+  const subs = (pv.subtitle && pv.subtitle.subtitles) || [];
+  result.subtitles = subs.map((s) => ({
+    lan: s.lan,
+    lanDoc: s.lan_doc,
+    url: s.subtitle_url && s.subtitle_url.startsWith('//') ? 'https:' + s.subtitle_url : s.subtitle_url,
+  }));
+
+  if (!subs.length) {
+    result.noSubtitleReason = pv.need_login_subtitle ? 'need-login' : 'none-available';
+    return result;
+  }
+
+  const items = (await getJson(result.subtitles[0].url)).body || [];
+  result.body = items
+    .filter((it) => (it.content || '').trim())
+    .map((it) => ({ from: Number(it.from || 0), to: Number(it.to || 0), text: it.content.trim() }));
+
+  // 数据自洽校验：防「拿到别的视频的字幕」
+  if (result.body.length) {
+    const end = result.body[result.body.length - 1].to;
+    if (end < pg.duration * 0.7) {
+      result.warning = `字幕只到 ${end.toFixed(0)}s，视频有 ${pg.duration}s，可能是分段轨或数据不匹配，请核对。`;
+    }
+  }
+
+  if (summary) {
+    try {
+      const qs = await wbiQuery({ bvid, cid, up_mid: String(view.owner.mid) });
+      const r = await getJson(`${API}/x/web-interface/view/conclusion/get?${qs}`);
+      if (r.code === 0 && r.data) {
+        const m = r.data.model_result || {};
+        result.summary = {
+          text: m.summary || '',
+          outline: (m.outline || []).map((o) => ({
+            title: o.title,
+            points: (o.part_outline || []).map((pt) => ({
+              timestamp: Number(pt.timestamp || 0),
+              text: pt.content,
+            })),
+          })),
+        };
+      }
+    } catch { /* 拿不到总结不算失败 */ }
+  }
+
+  return result;
+}
+
+/** 渲染成人读的文本 */
+export function renderText(v, { plain = false, list = false } = {}) {
+  const out = [];
+  out.push('# ' + v.title + (v.part ? `  [P${v.page} ${v.part}]` : ''));
+  out.push(`UP: ${v.uploader} | 时长 ${v.duration}s | ${v.url}`);
+
+  if (v.noSubtitleReason === 'need-login') {
+    out.push('\n[字幕接口要求登录：当前无有效凭据，拿不到字幕轨。运行 `bili login` 扫码登录]');
+  } else if (v.noSubtitleReason === 'none-available') {
+    out.push('\n[该视频没有字幕轨。纯音乐 / MV / CG 类视频通常没有。可加 --summary 试试 B 站的 AI 总结。]');
+  }
+
+  if (list) {
+    if (!v.subtitles.length) out.push('该视频没有字幕轨。');
+    for (const s of v.subtitles) out.push(`- ${s.lanDoc} (${s.lan}) ${s.url}`);
+  }
+
+  if (v.body.length) {
+    out.push(`\n## 字幕：${v.subtitles[0].lanDoc || v.subtitles[0].lan}（${v.body.length} 条）\n`);
+    if (v.warning) out.push(`⚠️ ${v.warning}\n`);
+    for (const it of v.body) out.push(plain ? it.text : `[${ts(it.from)}] ${it.text}`);
+  }
+
+  if (v.summary) {
+    out.push('\n## B站 AI 总结\n');
+    if (v.summary.text) out.push(v.summary.text);
+    for (const o of v.summary.outline) {
+      out.push(`\n### ${o.title}`);
+      for (const p of o.points) out.push(`- [${ts(p.timestamp)}] ${p.text}`);
+    }
+  }
+
+  return out.join('\n') + '\n';
+}

package/src/install-skill.mjs

@@ -0,0 +1,63 @@
+// 安装 agent skill —— 首选 npx skills add，失败则自己往已知目录写
+import { existsSync, mkdirSync, copyFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = join(HERE, '..');
+const SKILL_MD = join(PKG_ROOT, 'SKILL.md');
+
+// 各 agent 的 skill 目录（装了就往这些地方放）
+const KNOWN_DIRS = [
+  '~/.claude/skills',
+  '~/.codex/skills',
+  '~/.config/agent-skills',
+  '~/.agents/skills',
+];
+
+export async function installSkill({ global: isGlobal = true } = {}) {
+  const log = console.log;
+
+  // 1) 首选：npx skills add（走官方生态，兼容性最好）
+  log('尝试 `npx skills add` …');
+  const r = spawnSync('npx', ['-y', 'skills@latest', 'add', 'dongliang/bili-transcript',
+                              isGlobal ? '-g' : '-p', '-y'],
+                      { stdio: 'inherit', shell: process.platform === 'win32' });
+  if (r.status === 0) {
+    log('\n✅ 已通过 npx skills 安装。');
+    return true;
+  }
+
+  // 2) 降级：自己往已知目录写
+  log(`\n⚠️  npx skills 不可用（退出码 ${r.status}），改用内置安装：`);
+  if (!existsSync(SKILL_MD)) {
+    log(`❌ 找不到 ${SKILL_MD}，无法安装。`);
+    return false;
+  }
+
+  const targets = KNOWN_DIRS
+    .map((d) => d.replace(/^~/, homedir()))
+    .filter((d) => existsSync(dirname(d)));
+
+  if (!targets.length) {
+    log('❌ 没有找到任何已知的 agent skill 目录。');
+    log('   请手动把包里的 SKILL.md 复制到你的 agent skill 目录。');
+    return false;
+  }
+
+  for (const t of targets) {
+    const dest = join(t, 'bilibili-transcript');
+    try {
+      mkdirSync(dest, { recursive: true });
+      copyFileSync(SKILL_MD, join(dest, 'SKILL.md'));
+      log(`  ✅ ${dest}/SKILL.md`);
+    } catch (e) {
+      log(`  ❌ ${dest}：${e.message}`);
+    }
+  }
+
+  log('\n注意：降级安装只放 SKILL.md，agent 需要能通过 `npx bili-transcript` 调用工具。');
+  return true;
+}

package/src/login.mjs

@@ -0,0 +1,116 @@
+// 扫码登录 —— 纯命令行，不需要任何浏览器
+import { writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { encodeQR, renderText, writePNG } from './qr.mjs';
+import { UA, API } from './api.mjs';
+import { saveAuth, AUTH_PATH, findSessdata } from './auth.mjs';
+
+const H = { 'User-Agent': UA, Referer: 'https://www.bilibili.com/' };
+const QRAPI = 'https://passport.bilibili.com/x/passport-login/web/qrcode';
+const KEYFILE = '/tmp/bili_qr.json';
+
+/** 读 cookie 头。不同 Node 构建行为不一致：getSetCookie() 可能不存在，get() 可能返回数组 */
+function readSetCookies(resp) {
+  const h = resp.headers;
+  if (typeof h.getSetCookie === 'function') {
+    const v = h.getSetCookie();
+    if (v && v.length) return v;
+  }
+  const raw = h.get('set-cookie');
+  if (Array.isArray(raw)) return raw;
+  return raw ? [raw] : [];
+}
+
+export async function whoami() {
+  const nav = await (await fetch(`${API}/x/web-interface/nav`, { headers: H })).json();
+  return nav.data?.isLogin ? nav.data : null;
+}
+
+export async function login({ png = null, qrOnly = false, resume = false, timeout = 180, force = false, log = console.log }) {
+  if (!force && !resume && !qrOnly) {
+    const who = await whoami().catch(() => null);
+    if (who) {
+      log(`已经登录过了：${who.uname}（uid ${who.mid}）`);
+      log(`凭据位置：${AUTH_PATH}`);
+      log('要重新登录请加 --force');
+      return { alreadyLoggedIn: true, user: who };
+    }
+  }
+
+  let url, key;
+  if (resume) {
+    if (!existsSync(KEYFILE)) throw new Error('没有找到之前生成的二维码，请先运行 `bili login --qr-only`');
+    const s = JSON.parse(readFileSync(KEYFILE, 'utf8'));
+    url = s.url; key = s.key;
+    const age = Math.round((Date.now() - s.ts) / 1000);
+    log(`沿用 ${age}s 前生成的二维码`);
+    if (age > 170) log('⚠️ 已接近过期，若失败请重新生成');
+  } else {
+    const gen = await (await fetch(`${QRAPI}/generate`, { headers: H })).json();
+    if (gen.code !== 0) throw new Error(`生成二维码失败：code=${gen.code} ${gen.message || ''}`);
+    url = gen.data.url; key = gen.data.qrcode_key;
+  }
+
+  const matrix = encodeQR(url);
+
+  if (!resume && !qrOnly) {
+    log('\n用手机 B 站 App 扫码登录：\n');
+    log(renderText(matrix));
+    log(`链接：${url}\n`);
+  }
+
+  if (png) {
+    const r = writePNG(matrix, png, { scale: 8, quiet: 4 });
+    log(`二维码图片已写入 ${png}（${r.width}×${r.height}）`);
+  }
+
+  if (qrOnly) {
+    writeFileSync(KEYFILE, JSON.stringify({ url, key, ts: Date.now() }) + '\n');
+    log(`已保存二维码到 ${KEYFILE}。给用户看完后用 --resume 继续轮询。`);
+    return { qrOnly: true, url, key, png };
+  }
+
+  log('等待扫码…（二维码约 3 分钟过期）');
+  const deadline = Date.now() + timeout * 1000;
+  const jar = {};
+  let lastState = null;
+
+  while (Date.now() < deadline) {
+    let resp;
+    try {
+      resp = await fetch(`${QRAPI}/poll?qrcode_key=${key}`, { headers: H });
+    } catch {
+      await sleep(2000);
+      continue;
+    }
+    for (const c of readSetCookies(resp)) {
+      const nv = c.split(';')[0];
+      const i = nv.indexOf('=');
+      if (i > 0) jar[nv.slice(0, i)] = nv.slice(i + 1);
+    }
+    let body;
+    try { body = await resp.json(); } catch { await sleep(2000); continue; }
+    const code = body.data?.code;
+    if (code !== lastState) {
+      lastState = code;
+      const label = { 86101: '未扫码', 86090: '已扫码，等待确认', 86038: '二维码已过期' }[code] || `code=${code}`;
+      log(`  [${new Date().toTimeString().slice(0, 8)}] ${label}`);
+    }
+    if (code === 0) break;
+    if (code === 86038) throw new Error('二维码已过期，请重新运行');
+    await sleep(2000);
+  }
+
+  if (!jar.SESSDATA) throw new Error('超时，或没能拿到凭据。请重试。');
+
+  saveAuth(jar);
+  const who = await whoami().catch(() => null);
+
+  log('\n=== 登录成功 ===');
+  if (who) log(`  账号：${who.uname}（uid ${who.mid}）`);
+  log(`  拿到 ${Object.keys(jar).length} 项凭据：${Object.keys(jar).join(', ')}`);
+  log(`  已保存到 ${AUTH_PATH}（权限 0600）`);
+
+  return { ok: true, user: who, cookies: Object.keys(jar) };
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

package/src/qr.mjs

@@ -0,0 +1,402 @@
+import { writeFileSync as _wfs } from 'node:fs';
+import { deflateSync } from 'node:zlib';
+// 纯 JS 二维码编码器 —— 零依赖
+// 支持：字节模式、纠错等级 M、版本 1–10、自动选版本、掩码自动择优
+// 正确性由 tests/qr-verify 与 Python qrcode 库逐模块比对验证
+
+// ---------- GF(256) ----------
+const EXP = new Uint8Array(512), LOG = new Uint8Array(256);
+(() => {
+  let x = 1;
+  for (let i = 0; i < 255; i++) { EXP[i] = x; LOG[x] = i; x <<= 1; if (x & 0x100) x ^= 0x11d; }
+  for (let i = 255; i < 512; i++) EXP[i] = EXP[i - 255];
+})();
+const gmul = (a, b) => (a === 0 || b === 0 ? 0 : EXP[LOG[a] + LOG[b]]);
+
+function rsGenPoly(n) {
+  let p = [1];
+  for (let i = 0; i < n; i++) {
+    const q = [1, EXP[i]];
+    const r = new Array(p.length + 1).fill(0);
+    for (let a = 0; a < p.length; a++)
+      for (let b = 0; b < 2; b++) r[a + b] ^= gmul(p[a], q[b]);
+    p = r;
+  }
+  return p;
+}
+
+function rsEncode(data, ecLen) {
+  const gen = rsGenPoly(ecLen);
+  const res = new Array(data.length + ecLen).fill(0);
+  data.forEach((v, i) => (res[i] = v));
+  for (let i = 0; i < data.length; i++) {
+    const coef = res[i];
+    if (coef === 0) continue;
+    for (let j = 0; j < gen.length; j++) res[i + j] ^= gmul(gen[j], coef);
+  }
+  return res.slice(data.length);
+}
+
+// ---------- 版本表（纠错等级 M，版本 1–10）----------
+// [ [块数, 每块总码字, 每块数据码字], ... ]
+const RS_M = {
+  1:  [[1, 26, 16]],
+  2:  [[1, 44, 28]],
+  3:  [[1, 70, 44]],
+  4:  [[2, 50, 32]],
+  5:  [[2, 67, 43]],
+  6:  [[4, 43, 27]],
+  7:  [[4, 49, 31]],
+  8:  [[2, 60, 38], [2, 61, 39]],
+  9:  [[3, 58, 36], [2, 59, 37]],
+  10: [[4, 69, 43], [1, 70, 44]],
+};
+const ALIGN = { 1: [], 2: [6, 18], 3: [6, 22], 4: [6, 26], 5: [6, 30],
+                6: [6, 34], 7: [6, 22, 38], 8: [6, 24, 42], 9: [6, 26, 46], 10: [6, 28, 50] };
+
+function dataCapacity(v) {
+  return RS_M[v].reduce((s, [n, , d]) => s + n * d, 0);
+}
+function ccBits(v) { return v <= 9 ? 8 : 16; }   // 字节模式字符计数指示符位数
+
+// ---------- 比特流 ----------
+class Bits {
+  constructor() { this.arr = []; }
+  put(val, len) { for (let i = len - 1; i >= 0; i--) this.arr.push((val >>> i) & 1); }
+  get length() { return this.arr.length; }
+}
+
+function encodeData(bytes, v) {
+  const cap = dataCapacity(v) * 8;
+  const b = new Bits();
+  b.put(0b0100, 4);                    // 字节模式
+  b.put(bytes.length, ccBits(v));      // 字符数
+  for (const x of bytes) b.put(x, 8);
+  // 终止符
+  const term = Math.min(4, cap - b.length);
+  b.put(0, term);
+  // 补齐到字节
+  while (b.length % 8) b.arr.push(0);
+  // 填充码字
+  const pads = [0xec, 0x11];
+  let i = 0;
+  while (b.length < cap) { b.put(pads[i++ % 2], 8); }
+  // 转成码字
+  const out = [];
+  for (let k = 0; k < b.length; k += 8) {
+    let byte = 0;
+    for (let j = 0; j < 8; j++) byte = (byte << 1) | b.arr[k + j];
+    out.push(byte);
+  }
+  return out;
+}
+
+function interleave(dataCodewords, v) {
+  const blocks = [];
+  let off = 0;
+  for (const [n, tot, dat] of RS_M[v]) {
+    for (let i = 0; i < n; i++) {
+      const d = dataCodewords.slice(off, off + dat); off += dat;
+      blocks.push({ d, e: rsEncode(d, tot - dat) });
+    }
+  }
+  const out = [];
+  const maxD = Math.max(...blocks.map((b) => b.d.length));
+  for (let i = 0; i < maxD; i++) for (const b of blocks) if (i < b.d.length) out.push(b.d[i]);
+  const maxE = Math.max(...blocks.map((b) => b.e.length));
+  for (let i = 0; i < maxE; i++) for (const b of blocks) if (i < b.e.length) out.push(b.e[i]);
+  return out;
+}
+
+// ---------- 矩阵 ----------
+function newMatrix(size) {
+  return Array.from({ length: size }, () => new Array(size).fill(null));
+}
+
+function placeFinder(m, r, c) {
+  for (let i = -1; i <= 7; i++) for (let j = -1; j <= 7; j++) {
+    const y = r + i, x = c + j;
+    if (y < 0 || x < 0 || y >= m.length || x >= m.length) continue;
+    const on = (i >= 0 && i <= 6 && (j === 0 || j === 6)) ||
+               (j >= 0 && j <= 6 && (i === 0 || i === 6)) ||
+               (i >= 2 && i <= 4 && j >= 2 && j <= 4);
+    m[y][x] = on;
+  }
+}
+
+function placeAlignment(m, size, v) {
+  const pos = ALIGN[v];
+  for (const r of pos) for (const c of pos) {
+    if ((r === 6 && c === 6) || (r === 6 && c === size - 7) || (r === size - 7 && c === 6)) continue;
+    for (let i = -2; i <= 2; i++) for (let j = -2; j <= 2; j++) {
+      m[r + i][c + j] = Math.max(Math.abs(i), Math.abs(j)) !== 1;
+    }
+  }
+}
+
+function reservedMask(size, v) {
+  const r = Array.from({ length: size }, () => new Array(size).fill(false));
+  const mark = (rr, cc) => { if (rr >= 0 && cc >= 0 && rr < size && cc < size) r[rr][cc] = true; };
+  // 定位图形 + 分隔符（锚点必须是 n-7，不是 n-8）
+  for (const [y, x] of [[0, 0], [0, size - 7], [size - 7, 0]]) {
+    for (let i = -1; i <= 7; i++) for (let j = -1; j <= 7; j++) mark(y + i, x + j);
+  }
+  // 定时图形
+  for (let i = 0; i < size; i++) { mark(6, i); mark(i, 6); }
+  // 校正图形
+  for (const rr of ALIGN[v]) for (const cc of ALIGN[v]) {
+    if ((rr === 6 && cc === 6) || (rr === 6 && cc === size - 7) || (rr === size - 7 && cc === 6)) continue;
+    for (let i = -2; i <= 2; i++) for (let j = -2; j <= 2; j++) mark(rr + i, cc + j);
+  }
+  // 格式信息
+  for (let i = 0; i <= 8; i++) { mark(8, i); mark(i, 8); }
+  for (let i = 0; i < 8; i++) { mark(8, size - 1 - i); mark(size - 1 - i, 8); }
+  // 版本信息（v>=7）
+  if (v >= 7) {
+    for (let i = 0; i < 6; i++) for (let j = 0; j < 3; j++) { mark(size - 11 + j, i); mark(i, size - 11 + j); }
+  }
+  return r;
+}
+
+function buildMatrix(v, codewords) {
+  const size = 4 * v + 17;
+  const m = newMatrix(size);
+  const res = reservedMask(size, v);
+  placeFinder(m, 0, 0); placeFinder(m, 0, size - 7); placeFinder(m, size - 7, 0);
+  placeAlignment(m, size, v);
+  for (let i = 8; i < size - 8; i++) { m[6][i] = i % 2 === 0; m[i][6] = i % 2 === 0; }
+  m[size - 8][8] = true; // 固定暗模块
+
+  // 数据按之字形填入
+  const bits = [];
+  for (const cw of codewords) for (let i = 7; i >= 0; i--) bits.push((cw >>> i) & 1);
+  let bi = 0, up = true;
+  for (let col = size - 1; col > 0; col -= 2) {
+    if (col === 6) col--;
+    for (let k = 0; k < size; k++) {
+      const row = up ? size - 1 - k : k;
+      for (const c of [col, col - 1]) {
+        if (res[row][c]) continue;
+        m[row][c] = bi < bits.length ? bits[bi++] === 1 : false;
+      }
+    }
+    up = !up;
+  }
+  return { m, res, size };
+}
+
+function maskFn(id, r, c) {
+  switch (id) {
+    case 0: return (r + c) % 2 === 0;
+    case 1: return r % 2 === 0;
+    case 2: return c % 3 === 0;
+    case 3: return (r + c) % 3 === 0;
+    case 4: return (Math.floor(r / 2) + Math.floor(c / 3)) % 2 === 0;
+    case 5: return ((r * c) % 2) + ((r * c) % 3) === 0;
+    case 6: return (((r * c) % 2) + ((r * c) % 3)) % 2 === 0;
+    case 7: return (((r + c) % 2) + ((r * c) % 3)) % 2 === 0;
+  }
+}
+
+function penalty(m, size) {
+  let p = 0;
+  // 规则 1：同色连续
+  for (let r = 0; r < size; r++) {
+    let run = 1;
+    for (let c = 1; c < size; c++) {
+      if (m[r][c] === m[r][c - 1]) run++; else { if (run >= 5) p += run - 2; run = 1; }
+    }
+    if (run >= 5) p += run - 2;
+  }
+  for (let c = 0; c < size; c++) {
+    let run = 1;
+    for (let r = 1; r < size; r++) {
+      if (m[r][c] === m[r - 1][c]) run++; else { if (run >= 5) p += run - 2; run = 1; }
+    }
+    if (run >= 5) p += run - 2;
+  }
+  // 规则 2：2x2 同色块
+  for (let r = 0; r < size - 1; r++) for (let c = 0; c < size - 1; c++) {
+    const v = m[r][c];
+    if (v === m[r][c + 1] && v === m[r + 1][c] && v === m[r + 1][c + 1]) p += 3;
+  }
+  // 规则 3：1:1:3:1:1 图形
+  const pat = [true, false, true, true, true, false, true];
+  const check = (get) => {
+    for (let i = 0; i + 7 <= size; i++) {
+      let hit = true;
+      for (let j = 0; j < 7; j++) if (get(i + j) !== pat[j]) { hit = false; break; }
+      if (!hit) continue;
+      const before = [i - 4, i - 3, i - 2, i - 1];
+      const after = [i + 7, i + 8, i + 9, i + 10];
+      const allQuiet = (idx) => idx.every((k) => k < 0 || k >= size || get(k) === false);
+      if (allQuiet(before) || allQuiet(after)) p += 40;
+    }
+  };
+  for (let r = 0; r < size; r++) check((i) => m[r][i]);
+  for (let c = 0; c < size; c++) check((i) => m[i][c]);
+  // 规则 4：暗模块比例
+  let dark = 0;
+  for (let r = 0; r < size; r++) for (let c = 0; c < size; c++) if (m[r][c]) dark++;
+  const ratio = (dark * 100) / (size * size);
+  p += Math.floor(Math.abs(ratio - 50) / 5) * 10;
+  return p;
+}
+
+const BCH_FMT = 0x537, BCH_VER = 0x1f25;
+function bch(data, gen, genBits) {
+  let d = data << (genBits - 1);
+  while (Math.floor(Math.log2(d)) >= genBits - 1) d ^= gen << (Math.floor(Math.log2(d)) - (genBits - 1));
+  return ((data << (genBits - 1)) | d);
+}
+
+function applyFormat(m, size, ecBits, maskId) {
+  const data = (ecBits << 3) | maskId;
+  const f = bch(data, BCH_FMT, 11) ^ 0x5412;
+  const bit = (i) => ((f >>> i) & 1) === 1;
+  // 垂直（列 8）：b0-b5 在行 0-5，b6/b7 在行 7/8，b8-b14 在行 n-7..n-1
+  for (let i = 0; i < 15; i++) {
+    const v = bit(i);
+    if (i < 6) m[i][8] = v;
+    else if (i < 8) m[i + 1][8] = v;
+    else m[size - 15 + i][8] = v;
+  }
+  // 水平（行 8）：b0-b7 在列 n-1..n-8，b8 在列 7，b9-b14 在列 5..0
+  for (let i = 0; i < 15; i++) {
+    const v = bit(i);
+    if (i < 8) m[8][size - i - 1] = v;
+    else if (i < 9) m[8][7] = v;
+    else m[8][14 - i] = v;
+  }
+  m[size - 8][8] = true;   // 固定暗模块
+}
+
+function applyVersionInfo(m, size, v) {
+  if (v < 7) return;
+  let d = v;
+  let rem = v;
+  for (let i = 0; i < 12; i++) {
+    rem = (rem << 1) ^ ((rem >>> 11) * BCH_VER);
+  }
+  const bits = (d << 12) | rem;
+  for (let i = 0; i < 18; i++) {
+    const b = ((bits >>> i) & 1) === 1;
+    const r = Math.floor(i / 3), c = i % 3;
+    m[size - 11 + c][r] = b;
+    m[r][size - 11 + c] = b;
+  }
+}
+
+/** 编码：返回二维布尔数组（true = 深色） */
+export function encodeQR(text, { ecc = 'M', mask: forcedMask = null } = {}) {
+  if (ecc !== 'M') throw new Error('只支持纠错等级 M');
+  const bytes = [...Buffer.from(text, 'utf8')];
+  let v = 1;
+  // 头部位数：模式(4) + 计数(ccBits) ；需要字节对齐后的总位数 <= 容量
+  for (v = 1; v <= 10; v++) {
+    const need = 4 + ccBits(v) + bytes.length * 8;
+    if (need <= dataCapacity(v) * 8) break;
+  }
+  if (v > 10) throw new Error('内容太长（超过版本 10 容量）');
+
+  const dataCw = encodeData(bytes, v);
+  const all = interleave(dataCw, v);
+  const { m, res, size } = buildMatrix(v, all);
+
+  // 掩码择优（forcedMask 用于测试）
+  let best = null, bestScore = Infinity;
+  for (let mask = 0; mask < 8; mask++) {
+    if (forcedMask !== null && mask !== forcedMask) continue;
+    const t = m.map((row) => row.slice());
+    for (let r = 0; r < size; r++) for (let c = 0; c < size; c++) {
+      if (res[r][c]) continue;
+      if (maskFn(mask, r, c)) t[r][c] = !t[r][c];
+    }
+    applyVersionInfo(t, size, v);
+    applyFormat(t, size, 0, mask);   // 纠错等级 M 的 ecBits = 0
+    const s = penalty(t, size);
+    if (s < bestScore) { bestScore = s; best = t; }
+  }
+  return best;
+}
+
+/** 渲染成文本（两个字符一行，便于终端显示） */
+export function renderText(matrix, dark = '██', light = '  ') {
+  return matrix.map((row) => row.map((b) => (b ? dark : light)).join('')).join('\n');
+}
+
+// ---------- 极简 PNG 写出（1 位灰度，零依赖）----------
+const CRC_TABLE = (() => {
+  const t = new Int32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    t[n] = c;
+  }
+  return t;
+})();
+function crc32(buf) {
+  let c = -1;
+  for (let i = 0; i < buf.length; i++) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ -1) >>> 0;
+}
+function chunk(type, data) {
+  const len = Buffer.alloc(4); len.writeUInt32BE(data.length);
+  const td = Buffer.concat([Buffer.from(type, 'ascii'), data]);
+  const crc = Buffer.alloc(4); crc.writeUInt32BE(crc32(td));
+  return Buffer.concat([len, td, crc]);
+}
+
+/** 把矩阵写成 PNG 文件（白底黑点，带静默区） */
+export function writePNG(matrix, path, { scale = 8, quiet = 4 } = {}) {
+  const n = matrix.length;
+  const w = (n + quiet * 2) * scale;
+  const h = w;
+  const rowBytes = Math.ceil(w / 8);
+  const raw = Buffer.alloc((rowBytes + 1) * h, 0xff);   // 全白
+  for (let y = 0; y < h; y++) raw[y * (rowBytes + 1)] = 0;  // 过滤器类型 0
+  for (let r = 0; r < n; r++) {
+    for (let c = 0; c < n; c++) {
+      if (!matrix[r][c]) continue;
+      for (let dy = 0; dy < scale; dy++) {
+        const y = (r + quiet) * scale + dy;
+        const base = y * (rowBytes + 1) + 1;
+        for (let dx = 0; dx < scale; dx++) {
+          const x = (c + quiet) * scale + dx;
+          raw[base + (x >> 3)] &= ~(0x80 >> (x & 7));   // 置为黑
+        }
+      }
+    }
+  }
+
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(w, 0); ihdr.writeUInt32BE(h, 4);
+  ihdr[8] = 1;   // 位深 1
+  ihdr[9] = 0;   // 灰度
+  const png = Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk('IHDR', ihdr),
+    chunk('IDAT', deflateSync(raw, { level: 9 })),
+    chunk('IEND', Buffer.alloc(0)),
+  ]);
+  _wfs(path, png);
+  return { width: w, height: h, bytes: png.length };
+}
+
+/** 调试用：导出中间产物 */
+export function debugCodewords(text) {
+  const bytes = [...Buffer.from(text, 'utf8')];
+  let v = 1;
+  for (v = 1; v <= 10; v++) {
+    if (4 + ccBits(v) + bytes.length * 8 <= dataCapacity(v) * 8) break;
+  }
+  const dataCw = encodeData(bytes, v);
+  return { version: v, dataCw, all: interleave(dataCw, v) };
+}
+
+/** 调试用：导出「非数据格」分布 */
+export function debugReserved(version) {
+  const size = 4 * version + 17;
+  const res = reservedMask(size, version);
+  return res.map((row) => row.map((b) => (b ? 1 : 0)).join(''));
+}