@pls-compile-owo/fisheye 0.3.0 → 0.7.1

package/CHANGELOG.md

@@ -2,6 +2,75 @@
 
 本项目遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 规范与 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [0.7.1] - 2026-11-14
+
+### Added
+
+- `auto --resume`：断点续跑完整版——manifest 与计划一致且拼图齐全时**跳过抽帧**，直接复用已有拼图继续后续阶段（`--force` 强制重跑）。
+
+## [0.7.0] - 2026-11-14
+
+### Added
+
+- `batch <清单文件|条目...> [--concurrency N]` 子命令：一次处理多个 BV/本地文件/URL（`lib/batch.mjs`）。
+- 字幕翻译：外文视频的官方字幕会同时读取 B站 翻译轨（`translated` 字段，落盘 `<BV>-official-subs-translated.txt`）。
+- 断点续跑基础（`lib/resume.mjs`）：manifest 记录计划/阶段，重跑时提示可复用产物（`--force` 强重跑）。
+- 进度辅助（`lib/progress.mjs`）：分段抽帧进度、阶段计时。
+- MCP server 入包（`mcp-video-server.js`，可选组件，需自装 @modelcontextprotocol/sdk / zod）+ 中英 README + CONFIG 文档。
+
+## [0.6.0] - 2026-11-14
+
+### Added
+
+- OCR 画面文字识别：`ocr <图片路径>` 子命令（tesseract，可选）；selftest 显示 OCR 可用性（`lib/ocr.mjs`）。
+- 任意平台视频：`url <视频链接>` 子命令（yt-dlp，可选，下载后走本地视频流程）（`lib/ytdlp.mjs`）。
+- `clean [--target cache|out|all] [--yes]` 子命令：清理缓存/产物（dry-run 默认，--yes 才删）。
+- `auto --audio`：无官方字幕时自动用 whisper 转写台词，跳过烧录字幕带。
+
+### Changed
+
+- selftest 增加 OCR / yt-dlp 检查项。
+
+## [0.5.0] - 2026-11-14
+
+### Added
+
+- `transcribe <BV> [--lang zh]` 子命令：用 whisper.cpp 转写音频，文本落 `out/<BV>-audio-transcript.txt`。
+- `lib/audio.mjs` 自动探测 whisper.cpp 官方 Windows 包解压结构（`whisper/Release/`）。
+- 单元测试覆盖扩展到全部模块：retry / budget / i18n / frame / env / audio / bili（共 46 个用例）。
+- 外部自检脚本增加「模块导入冒烟」（10 个 lib 模块全部可加载）。
+
+## [0.4.2] - 2026-11-14
+
+### Fixed
+
+- `lib/env.mjs` 缺少 `execFileSync` 导入：`onPath()` 失败导致 PATH 上的 ffmpeg/python 永远无法被识别（影响 `resolveTool` 的 PATH 兜底）。
+- `selftest`：PATH 上的 python 无法执行（如 Windows 商店占位符）时降级为跳过而不是失败。
+
+## [0.4.1] - 2026-11-14
+
+### Added
+
+- 音频转写能力探测（`lib/audio.mjs`）：检测 whisper.cpp，`selftest` 显示音频转写是否可用；不可用时优雅提示安装方式。
+- README 环境变量表补充 `FISHEYE_WHISPER` / `FISHEYE_WHISPER_MODEL`。
+
+### Fixed
+
+- 首次运行（`out/`、`cache/` 目录不存在）时字幕缓存写入与视频下载不再报 ENOENT。
+
+## [0.4.0] - 2026-11-14
+
+### Added
+
+- B站 API 请求自动重试：网络错误 / 超时 / 5xx / 429 自动重试，指数退避 + 抖动；4xx 不重试（`lib/retry.mjs`）。
+- token 预算估算可配置：`FISHEYE_TOKENS_PER_GRID` / `FISHEYE_TOKENS_PER_SUBS` / `FISHEYE_TOKENS_PER_FINE` 覆盖单张成本，`FISHEYE_TOKEN_MODEL`（gpt / qwen / gemini / 数字）按模型 tokenizer 修正（`lib/budget.mjs`）。
+- CLI 中英双语：`FISHEYE_LANG=en` 输出英文，默认中文（`lib/i18n.mjs`）。
+
+### Changed
+
+- `lib/bili.mjs` 的请求统一走 `fetchWithRetry`（函数签名与返回值不变）。
+- `lib/stages.mjs` 的预算估算改用 `lib/budget.mjs`（默认值与旧 COST 一致）。
+
 ## [0.3.0] - 2026-11-14
 
 ### Changed

package/README.md

@@ -68,6 +68,18 @@ npm link   # 可选：装成全局命令
 
 > ⚠️ 这个文件已被 `.gitignore` 排除，**永远不要提交**。
 
+### 环境变量
+
+| 变量 | 说明 |
+|---|---|
+| `FISHEYE_LANG` | CLI 输出语言：`zh`（默认）/ `en` |
+| `FISHEYE_TOKENS_PER_GRID` / `FISHEYE_TOKENS_PER_SUBS` / `FISHEYE_TOKENS_PER_FINE` | 单张拼图 / 字幕带 / 精读帧的 token 估算覆盖（默认 1200 / 1000 / 1300） |
+| `FISHEYE_TOKEN_MODEL` | 按模型 tokenizer 修正估算：`gpt`（1.0）/ `qwen`（1.35）/ `gemini`（0.8）/ 数字 |
+| `FISHEYE_WHISPER` | whisper.cpp 可执行文件路径（音频转写，可选；不装则跳过） |
+| `FISHEYE_WHISPER_MODEL` | whisper 模型文件（ggml-*.bin，可选） |
+| `FISHEYE_HOME` | 数据目录（cache/out 位置，默认项目目录） |
+| `FFMPEG` / `PYTHON` / `BILI_CRED` | 工具与登录态路径覆盖 |
+
 ### 依赖路径（一般不用管）
 
 fisheye 按这个顺序找 ffmpeg / python / 凭证：
@@ -147,6 +159,15 @@ node fisheye.mjs grab BV1ziWP6qENy 82.5,145.0
        00:27  弹幕热区  —— 弹幕热区 19 条
 ```
 
+## 断点续跑
+
+长视频处理中断后，重新跑同样的命令会提示可复用产物：
+
+```bash
+node fisheye.mjs auto BV1xxx --budget 20000 --resume   # 跳过已抽帧阶段，复用拼图
+node fisheye.mjs auto BV1xxx --budget 20000 --force    # 强制全部重跑
+```
+
 ## 命令
 
 | 命令 | 作用 |
@@ -193,6 +214,46 @@ node fisheye.mjs local <视频文件> [--grid 3x3] [--from 30] [--to 90]
 不依赖 B站 登录与字幕：ffmpeg 解析时长 → 按 grid 等间隔抽帧拼图 → 输出 `SHEET: <拼图路径>`。
 把拼图路径交给模型 `read_image` 即可"看"本地视频。适合 mp4/mkv/avi/mov/webm。
 
+## 音频转写
+
+装了 whisper.cpp 后，可以给无字幕视频做语音转写：
+
+```bash
+node fisheye.mjs transcribe BV1xxx [--lang zh]
+```
+
+自动探测顺序：`FISHEYE_WHISPER` 环境变量 → PATH → 常见安装路径（含 `~/.dsh/surfcore/whisper/Release/`）。
+模型放 `~/.dsh/surfcore/whisper/`（`ggml-*.bin`）或用 `FISHEYE_WHISPER_MODEL` 指定。
+转写文本落 `out/<BV>-audio-transcript.txt`。
+
+## OCR（图片文字识别）
+
+装了 tesseract 后可以识别图片/画面里的文字：
+
+```bash
+node fisheye.mjs ocr screenshot.png [--lang chi_sim+eng]
+```
+
+自动探测 `FISHEYE_TESSERACT` → PATH → 常见安装路径；语言包缺 `chi_sim` 时自动降级到 `eng`。
+识别结果落 `out/<图片名>.ocr.txt`。
+
+## 任意平台视频（yt-dlp）
+
+装了 yt-dlp 后可以直接给任意平台（YouTube/抖音/Twitter…）的链接：
+
+```bash
+node fisheye.mjs url "https://www.youtube.com/watch?v=xxx"
+```
+
+下载（yt-dlp）→ 自动走本地视频抽帧流程。探测顺序：`FISHEYE_YTDLP` → PATH → 常见安装路径。
+
+## 清理
+
+```bash
+node fisheye.mjs clean                    # 预览将清理的缓存/产物（dry-run）
+node fisheye.mjs clean --target out --yes # 实际删除 out/
+```
+
 ## 它怎么工作
 
 ```
@@ -240,7 +301,7 @@ B 站的弹幕密度本身就是内容信号。实测一条 40 分钟视频：
 ## 开发
 
 ```bash
-node --test test/                # 单元测试（参数解析 / 弹幕分析）
+node --test test/                # 单元测试（全部模块：46 个用例）
 node test-danmaku-filter.js      # 弹幕过滤规则测试（51 条用例）
 node fisheye.mjs selftest --deep # 含抽帧/字幕带实测的自检
 ```

package/fisheye.mjs

@@ -15,40 +15,30 @@
 // · 拼图每格顺序固定，manifest 按「从左到右、从上到下」记录时间，供 agent 对照
 // · 拼图与精读用同一种 seek，保证同一时间戳取到同一帧
 // · 所有子进程用 stdio:'ignore'（沙箱禁管道捕获），数据走临时文件
+import fs from 'node:fs'
 import path from 'node:path'
 import { PKG_DIR, WS, CFG_FILE, FFMPEG, CRED } from './lib/env.mjs'
 import { parseTime, num, pageNum } from './lib/util.mjs'
-import { stageAuto, stageGrid, stageSubs, stageSelftest, stageRefine, stageGrab, stageLocal } from './lib/stages.mjs'
+import { t } from './lib/i18n.mjs'
+import { stageAuto, stageGrid, stageSubs, stageSelftest, stageRefine, stageGrab, stageLocal, stageTranscribe, stageClean, stageOcr, stageUrl, stageBatch } from './lib/stages.mjs'
 
 const IS_SELFTEST = process.argv[2] === 'selftest'
 
 // local 处理本地文件，不需要 B站 登录态（但仍然需要 ffmpeg）
 const IS_LOCAL = process.argv[2] === 'local'
+// clean / ocr 只动本地文件，不需要 ffmpeg 与 B站 凭证
+const IS_CLEAN = process.argv[2] === 'clean'
+const IS_OCR = process.argv[2] === 'ocr'
+// url 需要 yt-dlp + ffmpeg，但不需要 B站 凭证
+const IS_URL = process.argv[2] === 'url'
 
-if (!IS_SELFTEST) {
+if (!IS_SELFTEST && !IS_CLEAN && !IS_OCR) {
   if (!FFMPEG) {
-    console.error(`找不到 ffmpeg。
-
-安装方式（任选其一）：
-  1. 装到 PATH：https://ffmpeg.org/download.html （Windows 用 gyan.dev 的 build）
-  2. 放项目里：把 ffmpeg 可执行文件放到 ${path.join(PKG_DIR, 'bin')}/
-  3. 设环境变量：FFMPEG=<ffmpeg 完整路径>
-  4. 写配置：${CFG_FILE} 里加 {"ffmpeg": "<完整路径>"}`)
+    console.error(t('err.ffmpeg.missing', { binDir: path.join(PKG_DIR, 'bin'), cfgFile: CFG_FILE }))
     process.exit(2)
   }
-  if (!IS_LOCAL && !CRED) {
-    console.error(`找不到 B站登录态文件。
-
-创建 ${path.join(WS, 'credentials.json')}，内容：
-  {
-    "sessdata": "<B站 SESSDATA>",
-    "bili_jct": "<bili_jct>",
-    "buvid3": "<buvid3>"
-  }
-获取方法：浏览器登录 B站 → F12 → Application → Cookies → bilibili.com，
-复制这三个值。或用环境变量 BILI_CRED=<文件路径> 指向已有文件。
-
-（也可以只跑 selftest 先看环境是否就绪：node fisheye.mjs selftest）`)
+  if (!IS_LOCAL && !IS_CLEAN && !IS_OCR && !IS_URL && !CRED) {
+    console.error(t('err.cred.missing', { credPath: path.join(WS, 'credentials.json') }))
     process.exit(2)
   }
 }
@@ -71,7 +61,7 @@ const opt = (name, dflt) => {
 if (stage === 'local') {
   const fileArg = argv[1]
   if (!fileArg || fileArg.startsWith('--')) {
-    console.error('用法: node fisheye.mjs local <视频文件> [--grid 3x3] [--from t] [--to t]')
+    console.error(t('err.local.usage'))
     process.exit(2)
   }
   try {
@@ -81,25 +71,77 @@ if (stage === 'local') {
       to: parseTime(opt('to', null), 'to')
     })
   } catch (error) {
-    console.error(`[错误] ${error?.message ?? error}`)
+    console.error(t('err.local.failed', { message: error?.message ?? error }))
     process.exit(1)
   }
   process.exit(0)
 }
-if (!stage || (stage !== 'selftest' && !bvid)) {
+
+if (stage === 'ocr') {
+  const img = argv[1]
+  if (!img || img.startsWith('--')) {
+    console.error(t('err.ocr.usage'))
+    process.exit(2)
+  }
+  try {
+    await stageOcr(img, { lang: opt('lang', null) })
+  } catch (error) {
+    console.error(t('err.local.failed', { message: error?.message ?? error }))
+    process.exit(1)
+  }
+  process.exit(0)
+}
+if (stage === 'url') {
+  const link = argv[1]
+  if (!link || link.startsWith('--')) {
+    console.error(t('err.url.usage'))
+    process.exit(2)
+  }
+  try {
+    await stageUrl(link, {
+      grid: opt('grid', '3x3'),
+      from: parseTime(opt('from', null), 'from'),
+      to: parseTime(opt('to', null), 'to')
+    })
+  } catch (error) {
+    console.error(t('err.local.failed', { message: error?.message ?? error }))
+    process.exit(1)
+  }
+  process.exit(0)
+}
+
+
+if (stage === 'batch') {
+  const arg = argv[1]
+  const listText = (arg && !arg.startsWith('--') && fs.existsSync(arg))
+    ? fs.readFileSync(arg, 'utf8')
+    : argv.slice(1).filter((a) => !a.startsWith('--')).join('\n')
+  if (!listText.trim()) {
+    console.error(t('err.batch.usage'))
+    process.exit(2)
+  }
+  try {
+    await stageBatch(listText, {
+      concurrency: num(opt('concurrency', 1), 'concurrency', { min: 1, max: 8 }),
+      budget: opt('budget', null) ? num(opt('budget'), 'budget', { min: 2000, max: 200000 }) : 20000,
+      grid: opt('grid', '3x3'),
+      audio: argv.includes('--audio'),
+      lang: opt('lang', null),
+      from: parseTime(opt('from', null), 'from'),
+      to: parseTime(opt('to', null), 'to')
+    })
+  } catch (error) {
+    console.error(t('err.local.failed', { message: error?.message ?? error }))
+    process.exit(1)
+  }
+  process.exit(0)
+}
+
+if (!stage || (stage !== 'selftest' && stage !== 'clean' && stage !== 'ocr' && stage !== 'url' && stage !== 'batch' && !bvid)) {
   if (rawBvid && stage !== 'selftest') {
-    console.error(`[错误] BV 号格式不对：${rawBvid}（应为 BV + 10 位字母数字，如 BV1ziWP6qENy）\n`)
+    console.error(`${t('err.bvFormat', { raw: rawBvid })}\n`)
   }
-  console.log('用法:')
-  console.log('  node fisheye.mjs auto <BV> [--budget 20000] [--density 6]      ← 推荐：自动规划并铺网')
-  console.log('  node fisheye.mjs refine <BV> --template                         ← 生成精读决策模板')
-  console.log('  node fisheye.mjs refine <BV> --decisions <file.json>            ← 按模型判断精读')
-  console.log('  node fisheye.mjs refine <BV>                                    ← 几何兜底（零 token）')
-  console.log('  node fisheye.mjs grid <BV> [--chunk 60] [--grid 3x3]')
-  console.log('  node fisheye.mjs subs <BV> [--count 12] [--band auto|0.22]')
-  console.log('  node fisheye.mjs grab <BV> <t1,t2,t3>                           ← 手动指定时间点')
-  console.log('  node fisheye.mjs local <视频文件> [--grid 3x3] [--from t] [--to t]  ← 看本地视频（mp4/mkv/...）')
-  console.log('  node fisheye.mjs selftest [--deep]                              ← 自检（依赖/凭证/API/缓存/磁盘）')
+  console.log(t('usage'))
   process.exit(2)
 }
 // 顶层错误兜底：不要把堆栈直接甩给用户
@@ -119,7 +161,9 @@ try {
     await stageAuto(bvid,
       num(opt('budget', 20000), 'budget', { min: 2000, max: 200000 }),
       { density: d === null ? null : num(d, 'density', { min: 0.5, max: 60 }), page, from, to,
-        useDanmakuFrames: !argv.includes('--no-danmaku-frames') })
+        useDanmakuFrames: !argv.includes('--no-danmaku-frames'),
+        audio: argv.includes('--audio'), audioLang: opt('lang', null),
+        resume: argv.includes('--resume'), force: argv.includes('--force') })
   } else if (stage === 'refine') {
     await stageRefine(bvid, { template: argv.includes('--template'), decisions: opt('decisions', null) })
   } else if (stage === 'grid') {
@@ -133,9 +177,14 @@ try {
       opt('band', 'auto'),
       { page, range })
   } else if (stage === 'grab') await stageGrab(bvid, argv[2] ?? '', { page })
-  else { console.error('未知阶段: ' + stage); process.exit(2) }
+  else if (stage === 'clean') {
+    // 清理缓存/产物：本地操作，不需要 BV 号
+    await stageClean({ target: opt('target', 'all'), yes: argv.includes('--yes') })
+  }
+  else if (stage === 'transcribe') await stageTranscribe(bvid, { page, lang: opt('lang', null) })
+  else { console.error(t('err.unknownStage', { stage })); process.exit(2) }
 } catch (e) {
-  console.error(`\n错误：${e.message}`)
+  console.error(t('err.fatal', { message: e.message }))
   if (process.env.FISHEYE_DEBUG) console.error(e.stack)
   process.exit(1)
 }