@pls-compile-owo/fisheye 0.7.1 → 0.7.2

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 本项目遵循 [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

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

@@ -177,7 +177,13 @@ node fisheye.mjs auto BV1xxx --budget 20000 --force    # 强制全部重跑
 | `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`（它会下载）。
 
@@ -226,6 +232,12 @@ node fisheye.mjs transcribe BV1xxx [--lang zh]
 模型放 `~/.dsh/surfcore/whisper/`（`ggml-*.bin`）或用 `FISHEYE_WHISPER_MODEL` 指定。
 转写文本落 `out/<BV>-audio-transcript.txt`。
 
+### 字幕翻译
+
+外文视频（英文/日文等）的官方字幕会同时读取 B站 的**中文翻译轨**（l2 机器翻译），
+转写结果旁会打印翻译行数，翻译文本落盘 `out/<BV>-official-subs-translated.txt`。
+没有翻译轨的视频不会凭空翻译（不接外部翻译 API）。
+
 ## OCR（图片文字识别）
 
 装了 tesseract 后可以识别图片/画面里的文字：
@@ -247,6 +259,23 @@ 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
@@ -254,6 +283,60 @@ node fisheye.mjs clean                    # 预览将清理的缓存/产物（dr
 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`。
+
 ## 它怎么工作
 
 ```
@@ -352,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pls-compile-owo/fisheye",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "Token-budget-aware video understanding for AI agents: official subtitles -> burned-in subtitle band -> danmaku highlights -> adaptive keyframe grids -> targeted refine.",
   "type": "module",
   "bin": {