@pls-compile-owo/fisheye 0.4.2 → 0.7.2

package/CHANGELOG.md

@@ -2,6 +2,54 @@
 
 本项目遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 规范与 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [0.7.2] - 2026-11-14
+
+### Docs
+
+纯文档同步版本（功能与 0.7.1 完全一致，无需重新安装）。
+
+- README 补全：批量处理、字幕翻译、MCP server、OCR、任意平台视频、清理、断点续跑等 0.5～0.7 新增功能的文档。
+- 第三方依赖致谢补充 whisper.cpp / Tesseract / yt-dlp。
+- 英文 README 补充 More commands 段。
+
+## [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

package/README.en.md

@@ -65,6 +65,20 @@ node fisheye.mjs grab BV1xxx 69.6,75.3
 The CLI prints `SHEET: <path>` — feed that image to your multimodal model via
 `read_image`. (Optional: wrap the CLI in an MCP server if your agent environment supports it.)
 
+## More commands
+
+```bash
+node fisheye.mjs local ./video.mp4 [--grid 4x4]   # local video
+node fisheye.mjs transcribe BV1xxx [--lang zh]    # audio transcription (whisper.cpp)
+node fisheye.mjs ocr image.png [--lang chi_sim+eng] # OCR text (tesseract)
+node fisheye.mjs url "https://..."                # any platform (yt-dlp)
+node fisheye.mjs batch list.txt --concurrency 2   # process many videos
+node fisheye.mjs clean [--target out] [--yes]     # clean artifacts
+```
+
+`auto --resume` reuses existing grids and skips frame extraction; `--force` re-runs everything.
+Optional integrations: whisper.cpp (audio), tesseract (OCR), yt-dlp (any URL), and `mcp-video-server.js` (MCP tools, needs `npm i @modelcontextprotocol/sdk zod`).
+
 ## Docs
 
 - `docs/DESIGN.md` — design rationale
@@ -88,6 +102,9 @@ Third-party dependencies:
 |---|---|---|
 | [ffmpeg](https://ffmpeg.org/) | frame extraction, tiling, subtitle-band slicing | LGPL/GPL |
 | [numpy](https://numpy.org/) · [Pillow](https://python-pillow.org/) | subtitle-band detection (optional) | BSD / MIT-CMU |
+| [whisper.cpp](https://github.com/ggml-org/whisper.cpp) | audio transcription (optional) | MIT |
+| [Tesseract OCR](https://github.com/tesseract-ocr/tesseract) | OCR (optional) | Apache-2.0 |
+| [yt-dlp](https://github.com/yt-dlp/yt-dlp) | any-platform video download (optional) | Unlicense |
 
 ## License
 

package/README.md

@@ -159,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    # 强制全部重跑
+```
+
 ## 命令
 
 | 命令 | 作用 |
@@ -168,7 +177,13 @@ node fisheye.mjs grab BV1ziWP6qENy 82.5,145.0
 | `subs <BV>` | 只生成字幕带（`--count` 行数、`--band auto\|0.22`） |
 | `refine <BV>` | 挑出值得精读的时间点，**并直接截好原图**（三种模式：模板 / 决策文件 / 几何兜底） |
 | `grab <BV> <t1,t2>` | 按时间点截原分辨率单帧（手动指定） |
-| `selftest [--deep]` | 自检：依赖 / 凭证 / API / 缓存 / 磁盘 |
+| `local <视频文件>` | 本地视频：ffmpeg 抽帧拼图（`--grid`、`--from`/`--to`） |
+| `transcribe <BV>` | 音频转写（whisper.cpp，`--lang zh`） |
+| `ocr <图片>` | OCR 识别图片文字（tesseract，`--lang chi_sim+eng`） |
+| `url <链接>` | 任意平台视频（yt-dlp 下载后走本地流程） |
+| `batch <清单文件\|条目...>` | 批量处理（`--concurrency N` 并发） |
+| `clean [--target cache\|out\|all] [--yes]` | 清理缓存/产物（默认 dry-run） |
+| `selftest [--deep]` | 自检：依赖 / 凭证 / API / OCR / 转写 / yt-dlp / 缓存 / 磁盘 |
 
 > `grid` / `subs` / `refine` / `grab` 都要求 `cache/<BV>.mp4` 已存在——第一次用请先跑 `auto`（它会下载）。
 
@@ -205,6 +220,123 @@ 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`。
+
+### 字幕翻译
+
+外文视频（英文/日文等）的官方字幕会同时读取 B站 的**中文翻译轨**（l2 机器翻译），
+转写结果旁会打印翻译行数，翻译文本落盘 `out/<BV>-official-subs-translated.txt`。
+没有翻译轨的视频不会凭空翻译（不接外部翻译 API）。
+
+## 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 → 常见安装路径。
+
+## 批量处理
+
+一次处理多个视频（每行一个 BV / 本地路径 / URL，支持 `#` 注释）：
+
+```bash
+# 从清单文件
+node fisheye.mjs batch list.txt --concurrency 2
+
+# 直接传条目
+node fisheye.mjs batch BV1xxx BV2xxx "C:\videos\a.mp4"
+
+# 并发处理（默认 1 串行；失败不中断，最后汇总）
+node fisheye.mjs batch list.txt --concurrency 3
+```
+
+每一项按类型自动分派：BV → auto、路径 → local、链接 → url。
+
+## 清理
+
+```bash
+node fisheye.mjs clean                    # 预览将清理的缓存/产物（dry-run）
+node fisheye.mjs clean --target out --yes # 实际删除 out/
+```
+
+## MCP server（可选）
+
+`mcp-video-server.js` 把 fisheye 包装成 [MCP](https://modelcontextprotocol.io/)（Model Context Protocol）工具，让支持 MCP 的 agent 环境（DSH / Claude Code / Cursor 等）**不必自己拼命令行**就能看视频。
+
+这是**可选组件**：fisheye 核心保持零依赖，不装下面两个 npm 包也能正常用 `auto` / `local` 等命令。
+
+### 安装
+
+```bash
+# 在 fisheye 目录（含 fisheye.mjs 的那层）里执行，会生成 node_modules/
+npm i @modelcontextprotocol/sdk zod
+```
+
+除此之外还需要同目录的 `fisheye.mjs` + `lib/`、ffmpeg、B站 登录态（见上文「配置 B 站登录态」）。
+`vwatch_deep` 的「独立会话复述」额外需要本机安装 **DeepSeek Harness 桌面版**；没有时会自动降级，直接返回抽帧规划 + 官方字幕原文。
+
+### 配置
+
+把 server 注册到 MCP 客户端（Claude Code 写进项目根的 `.mcp.json`；DSH 用同样的 `mcpServers` 结构）：
+
+```json
+{
+  "mcpServers": {
+    "fisheye": {
+      "command": "node",
+      "args": ["C:/path/to/fisheye/mcp-video-server.js"]
+    }
+  }
+}
+```
+
+Windows 路径用正斜杠或双反斜杠。若用 `FISHEYE_HOME` 挪过数据目录，在 `env` 里一并传入：
+
+```json
+{
+  "mcpServers": {
+    "fisheye": {
+      "command": "node",
+      "args": ["C:/path/to/fisheye/mcp-video-server.js"],
+      "env": { "FISHEYE_HOME": "D:/video-cache" }
+    }
+  }
+}
+```
+
+### 工具
+
+| 工具 | 作用 | 参数 |
+|---|---|---|
+| `vwatch_scan` | 快速扫一眼：对开头一段抽帧拼成九宫格，**直接返回画面**（不含文字总结） | `bvid`、`grid`（`3x3` / `4x4` / `5x5`） |
+| `vwatch_deep` | 深入看懂：按 token 预算抽帧 + 优先官方字幕 → 交给独立 headless 会话读完 → **只返回完整复述**（不占当前对话上下文） | `bvid`、`from`、`to`、`page`、`budget` |
+
+> 工具名沿用旧名 `vwatch_*`，以免破坏已有的 MCP 配置。参数与 CLI 一一对应：`bvid` → BV 号，`from`/`to` → `--from`/`--to`，`page` → `--p`，`budget` → `--budget`。
+
 ## 它怎么工作
 
 ```
@@ -252,7 +384,7 @@ B 站的弹幕密度本身就是内容信号。实测一条 40 分钟视频：
 ## 开发
 
 ```bash
-node --test test/                # 单元测试（参数解析 / 弹幕分析）
+node --test test/                # 单元测试（全部模块：46 个用例）
 node test-danmaku-filter.js      # 弹幕过滤规则测试（51 条用例）
 node fisheye.mjs selftest --deep # 含抽帧/字幕带实测的自检
 ```
@@ -303,6 +435,9 @@ Copyright (c) 2026 Derpyu520 and qq-bridge / QSH contributors）。
 |---|---|---|
 | [ffmpeg](https://ffmpeg.org/) | 抽帧、拼图、字幕带切片 | LGPL/GPL |
 | [numpy](https://numpy.org/) · [Pillow](https://python-pillow.org/) | 字幕带位置检测（可选） | BSD / MIT-CMU |
+| [whisper.cpp](https://github.com/ggml-org/whisper.cpp) | 音频转写（可选，`transcribe` / `--audio`） | MIT |
+| [Tesseract OCR](https://github.com/tesseract-ocr/tesseract) | 图片文字识别（可选，`ocr`） | Apache-2.0 |
+| [yt-dlp](https://github.com/yt-dlp/yt-dlp) | 任意平台视频下载（可选，`url`） | Unlicense |
 
 ### 思想来源
 

package/fisheye.mjs

@@ -15,23 +15,29 @@
 // · 拼图每格顺序固定，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 { t } from './lib/i18n.mjs'
-import { stageAuto, stageGrid, stageSubs, stageSelftest, stageRefine, stageGrab, stageLocal } from './lib/stages.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(t('err.ffmpeg.missing', { binDir: path.join(PKG_DIR, 'bin'), cfgFile: CFG_FILE }))
     process.exit(2)
   }
-  if (!IS_LOCAL && !CRED) {
+  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)
   }
@@ -70,7 +76,68 @@ if (stage === 'local') {
   }
   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(`${t('err.bvFormat', { raw: rawBvid })}\n`)
   }
@@ -94,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') {
@@ -108,6 +177,11 @@ try {
       opt('band', 'auto'),
       { page, range })
   } else if (stage === 'grab') await stageGrab(bvid, argv[2] ?? '', { page })
+  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(t('err.fatal', { message: e.message }))

package/lib/audio.mjs

@@ -145,6 +145,7 @@ function commonWhisperPaths(env = process.env) {
     path.join(home, '.dsh', 'surfcore', 'whisper', 'bin'),
     path.join(home, '.dsh', 'surfcore', 'whisper', 'build', 'bin'),
     path.join(home, '.dsh', 'surfcore', 'whisper', 'build', 'bin', 'Release'),
+  path.join(home, '.dsh', 'surfcore', 'whisper', 'Release'),
     // 本机实际布局：ffmpeg 和 B站下载器放在 bili/bin，whisper 也可能被丢在同一处
     path.join(home, '.dsh', 'surfcore', 'bili', 'bin'),
     path.join(home, '.dsh', 'surfcore', 'bin'),

package/lib/batch.mjs

@@ -0,0 +1,191 @@
+// 批量处理核心：把多条 BV / 本地文件 / URL 交给同一个 runner 跑。
+// 纯逻辑：不读文件系统、不起子进程、不碰网络、零第三方依赖。
+// 文件是否存在、视频能不能解析，统一交给调用方传入的 runner 判断——
+// 这样 parseBatchList 是可测的纯函数，批量流程也能在单测里跑完。
+//
+// 典型接法（后续 batch 子命令）：
+//   const { items, errors } = parseBatchList(text)
+//   // errors 先报给用户，items 再进 runBatch
+//   const summary = await runBatch(items, (item) => runOne(item, opts), {
+//     concurrency: 2,
+//     onItem: (item, i) => console.log(`[${i + 1}/${items.length}] ${item.value}`)
+//   })
+//   console.log(formatBatchReport(summary))
+
+// BV 号：BV + 10 位字母数字（与 fisheye.mjs 入口校验保持一致）
+const BV_RE = /^BV[0-9A-Za-z]{10}$/
+const URL_RE = /^https?:\/\//i
+// Windows 盘符：C:\ / C:/ / 裸 C:
+const DRIVE_RE = /^[A-Za-z]:(?:[\\/]|$)/
+// 常见视频扩展名（URL 已在前面单独判定，这里只看裸文件名）
+const VIDEO_EXT_RE = /\.(mp4|mkv|avi|mov|webm)$/i
+
+// 路径形态判断（纯字符串，不看磁盘）
+function looksLikeFile(s) {
+  if (DRIVE_RE.test(s)) return true
+  if (s.startsWith('\\\\') || s.startsWith('//')) return true // UNC \\server\share
+  if (s.startsWith('./') || s.startsWith('.\\') || s.startsWith('../') || s.startsWith('..\\')) return true
+  if (s.startsWith('/')) return true
+  if (VIDEO_EXT_RE.test(s)) return true // 裸文件名：video.mp4
+  if (/[\\/]/.test(s)) return true // 含路径分隔符
+  return false
+}
+
+function classify(value) {
+  if (BV_RE.test(value)) return 'bv'
+  if (URL_RE.test(value)) return 'url'
+  if (looksLikeFile(value)) return 'file'
+  return null
+}
+
+// 统一成「物理行」数组：字符串直接按行拆；数组每项再按行拆（一项多行也认）
+function toLines(input) {
+  if (typeof input === 'string') return input.split(/\r?\n/)
+  if (!Array.isArray(input)) return null
+  const out = []
+  for (const entry of input) {
+    if (entry === null || entry === undefined) continue
+    out.push(...String(entry).split(/\r?\n/))
+  }
+  return out
+}
+
+/**
+ * 解析批量输入。
+ * 每行 trim 后：空行 / `#` 开头的注释行跳过；BV 号 → bv；http(s):// → url；
+ * 像文件路径（盘符/UNC/相对路径/含分隔符/视频扩展名）→ file；其余进 errors。
+ * @param {string|string[]} input 多行文本，或每项一行的数组
+ * @returns {{ items: Array<{kind:'bv'|'file'|'url', value:string}>,
+ *             errors: Array<{line:number, raw:string, reason:string}> }}
+ */
+export function parseBatchList(input) {
+  const lines = toLines(input)
+  // 类型不对时也走 errors，不要抛异常——CLI 层还要把错误列给用户看
+  if (lines === null) {
+    return {
+      items: [],
+      errors: [{ line: 0, raw: String(input ?? ''), reason: '批量清单必须是字符串或数组' }]
+    }
+  }
+  const items = []
+  const errors = []
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i]
+    const value = raw.trim()
+    if (value === '' || value.startsWith('#')) continue
+    const kind = classify(value)
+    if (kind) items.push({ kind, value })
+    else errors.push({ line: i + 1, raw: value, reason: '无法识别：既不是 BV 号、URL，也不是视频文件路径' })
+  }
+  return { items, errors }
+}
+
+const nowMs = () => performance.now()
+
+function errorText(error) {
+  if (error instanceof Error) return error.message || error.name || '未知错误'
+  if (typeof error === 'string') return error
+  if (error === null || error === undefined) return '未知错误'
+  try {
+    const s = JSON.stringify(error)
+    return s === undefined ? String(error) : s
+  } catch {
+    return String(error) // 循环引用、BigInt 之类
+  }
+}
+
+async function runOne(item, runner) {
+  const started = nowMs()
+  try {
+    const result = await runner(item)
+    return { item, ok: true, result, ms: Math.round(nowMs() - started) }
+  } catch (error) {
+    return { item, ok: false, error: errorText(error), ms: Math.round(nowMs() - started) }
+  }
+}
+
+function normalizeConcurrency(value, total) {
+  const n = Math.floor(Number(value))
+  if (!Number.isFinite(n) || n < 1) return 1
+  return Math.min(n, total)
+}
+
+/**
+ * 批量执行：串行或简单并发池；单项失败只记录，不中断整体。
+ * 结果顺序始终与 items 一致（并发完成顺序不回写结果顺序）。
+ * onItem 在每项 runner 之前调用，抛错会中断整批（进度回调不该抛错）。
+ * @param {Array} items parseBatchList().items 或任意可迭代项
+ * @param {(item:any, index:number)=>Promise<any>} runner 单条处理逻辑
+ * @param {{concurrency?:number, onItem?:null|((item:any, index:number)=>any)}} [options]
+ * @returns {Promise<{results: Array<{item:any, ok:boolean, result?:any, error?:string, ms:number}>,
+ *                    total:number, ok:number, failed:number}>}
+ */
+export async function runBatch(items, runner, { concurrency = 1, onItem = null } = {}) {
+  if (!Array.isArray(items)) throw new TypeError('runBatch: items 必须是数组')
+  if (typeof runner !== 'function') throw new TypeError('runBatch: runner 必须是函数')
+  if (onItem !== null && typeof onItem !== 'function') throw new TypeError('runBatch: onItem 必须是函数或 null')
+
+  const total = items.length
+  if (total === 0) return { results: [], total: 0, ok: 0, failed: 0 }
+
+  const limit = normalizeConcurrency(concurrency, total)
+  const results = new Array(total)
+  let next = 0
+
+  // 简单并发池：limit 个 worker 抢同一个游标，谁空谁取下一个
+  async function worker() {
+    for (;;) {
+      const index = next++
+      if (index >= total) return
+      const item = items[index]
+      if (onItem) await onItem(item, index)
+      results[index] = await runOne(item, runner)
+    }
+  }
+  await Promise.all(Array.from({ length: limit }, () => worker()))
+
+  const ok = results.reduce((n, r) => n + (r.ok ? 1 : 0), 0)
+  return { results, total, ok, failed: total - ok }
+}
+
+// 报告里的耗时：按 ms 展示，超过 1 秒给一位小数，超过 1 分钟给 XmYs
+function formatDuration(ms) {
+  if (!Number.isFinite(ms) || ms <= 0) return '0ms'
+  if (ms < 1000) return `${Math.round(ms)}ms`
+  if (ms < 60000) {
+    const s = Math.round(ms / 100) / 10
+    return s >= 60 ? '1m0s' : `${s.toFixed(1)}s`
+  }
+  const m = Math.floor(ms / 60000)
+  const s = Math.round((ms % 60000) / 1000)
+  return s === 60 ? `${m + 1}m0s` : `${m}m${s}s`
+}
+
+function describeItem(item) {
+  if (!item || typeof item !== 'object') return String(item)
+  const value = item.value ?? ''
+  return item.kind ? `[${item.kind}] ${value}` : String(value)
+}
+
+/**
+ * 生成人类可读的汇总文本（不含尾随换行，方便 console.log 直接用）。
+ * 耗时取 results 里各条 ms 之和（并发时是累计值，不是墙钟时间）。
+ * @param {object} summary runBatch() 的返回值
+ * @returns {string}
+ */
+export function formatBatchReport(summary) {
+  const results = Array.isArray(summary?.results) ? summary.results : []
+  const total = Number.isFinite(summary?.total) ? summary.total : results.length
+  const ok = Number.isFinite(summary?.ok) ? summary.ok : results.filter((r) => r?.ok).length
+  const failed = Number.isFinite(summary?.failed) ? summary.failed : Math.max(0, total - ok)
+  const spent = results.reduce((sum, r) => sum + (Number.isFinite(r?.ms) ? r.ms : 0), 0)
+
+  const lines = [`批量处理：共 ${total} 条，成功 ${ok} 条，失败 ${failed} 条，耗时合计 ${formatDuration(spent)}`]
+  if (failed > 0) {
+    lines.push('失败明细：')
+    const failures = results.filter((r) => r && !r.ok)
+    if (failures.length === 0) lines.push('  （没有明细）')
+    else failures.forEach((r, i) => lines.push(`  ${i + 1}. ${describeItem(r.item)} —— ${r.error ?? '未知错误'}`))
+  }
+  return lines.join('\n')
+}