deep-read-summarize 0.3.9 → 0.3.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -3,6 +3,31 @@
3
3
  All notable changes to this project will be documented in this file.
4
4
  The format is based on [Keep a Changelog](https://keepachangelog.com/).
5
5
 
6
+ ## [0.3.10] — 2026-09-24
7
+
8
+ 对**已发布的 0.3.9** 做的一轮审计修复。审计对象是 **npm 上那份字节**(不是工作区):先确认 29 个文件与 tag `v0.3.9` **逐字节一致**,再在解包目录里跑该包自带的门禁(lint / security / 35 fixture / 38 node:test 全绿),然后逐项找问题。
9
+
10
+ ### Fixed
11
+
12
+ - **uv 的 CPython 镜像已失效,会让「首次安装」的机器彻底装不上**(P1;继承自 0.3.6 的 PowerShell 脚本,不是 0.3.9 新引入)。镜像写死 `ghproxy.com`,而它现在 **301 到 `ghfast.top` 并丢掉路径** —— 返回的是 HTML 而不是资产,uv 拿到 HTML 报 `Invalid gzip header`,而且**不会自己回退 GitHub**。真机验证:`uv venv --python 3.11` 带该镜像 → 退出码 2 失败;不带镜像(对照)→ 成功。踩到的恰好是**本机没有任何 Python 3.12 的新用户**。
13
+ - 现在:默认镜像换成实测可用的继任服务,**失败自动改用直连 GitHub 重试一次**(并清理失败留下的半个 venv);另可用环境变量 `DRS_UV_PYTHON_MIRROR` 覆盖(空字符串 = 完全不用镜像)。
14
+ - **转写结果为 0 字节时仍返回成功**(P2)。纯静音 / 纯 BGM 视频会被 VAD 全部滤掉,脚本却以退出码 0 结束、只留一条 stderr 警告,并且留下一个 0 字节文件;而调用方按「输出文件非空」判断完成、提示词里又有一条「日志出现 DONE」——**空逐字稿会被当成转写成功**,再拿去做精读。现在:删除空文件、以退出码 **3** 结束,并明确要求按降级处理。
15
+ - **`--audio` 指向目录时报错晦涩**(P3):此前 `existsSync` 直接放行,最后抛出 python 的 `PermissionError: [Errno 13] Permission denied`。现在先校验是否为普通文件,直接报「不是文件(是不是给了目录?)」。
16
+
17
+ ### Changed
18
+
19
+ - **`docs/RELEASE.md` 两处与实况不符**(P2,会随包发给用户):
20
+ - 「当前版本速览」停留在 v0.1.x / v0.2.x + 计划中的 v1.0.0,**完全没有 0.3.x**;现在补全,并加了一道断言守着它(发版忘了更新会让 `npm run test:node` 变红)。
21
+ - 发布流程教的是「建 Release → 触发 publish.yml」+「用 `npm view` 验证」—— **恰好就是实测踩到的两个坑**。现在改为:手动 dispatch 为主路径;Release 事件投递不稳、只当记录;并写明判据(看日志的 `+ 包名@版本` 与 provenance;registry 有 1–2 分钟延迟,当场查必然 E404;dry-run 全绿不算发布成功)。
22
+ - `README.md` / `README.en.md`:选项示例补上 `maxRetries`(SKILL.md 与代码本来就有它);转写工具链一节补上「镜像可覆盖 + 失败自动回退直连」。
23
+ - `parsers/video.js` 提示词:转写步骤明确「脚本以非 0 退出也算失败」,包含「结果为空」的情况。
24
+
25
+ ### Compatibility
26
+
27
+ - 无破坏性变更,默认值与既有行为不变(`device` 仍默认 `cpu`、`transcribe` 仍默认 `true`)。
28
+ - 唯一可感知的变化:**纯静音音频现在会「失败」而不是「成功返回空文本」** —— 这正是修复目的,调用方本就应该走降级路径。
29
+ - `DRS_UV_PYTHON_MIRROR` 是新增的可选环境变量;不设时行为与 0.3.9 相同(只是默认镜像换成了还活着的那个)。
30
+
6
31
  ## [0.3.9] — 2026-09-22
7
32
 
8
33
  **macOS / Linux 支持**。这一版补上最后一块 Windows-only 的拼图:此前「无字幕视频自动转写」依赖 `scripts/transcribe.ps1`(PowerShell),SKILL.md 里明确写着「**目前仅在 Windows 可用**」;现在换成跨平台的 Node 脚本,三平台同一份实现、同一条命令。
package/README.en.md CHANGED
@@ -102,7 +102,7 @@ deep-read-summarize is a DSH plugin installable via npm, the dsh.so ecosystem, o
102
102
  npm install deep-read-summarize
103
103
 
104
104
  # or local install (dsh profile directory)
105
- pnpm add ./deep-read-summarize-0.3.9.tgz
105
+ pnpm add ./deep-read-summarize-0.3.10.tgz
106
106
  # then append to the dsh config's dsh.profile.bundles:
107
107
  # - deep-read-summarize
108
108
  # restart dsh web (POST /dsh-market/restart)
@@ -178,6 +178,7 @@ Pass this JSON to DSH's workflow tool:
178
178
  "whisperModel": "small", // video ASR tier: small | base | medium
179
179
  "language": "zh", // video ASR language: use "en" for English-only videos
180
180
  "device": "cpu", // ASR device: cpu (default) | auto | cuda; auto/cuda needs a CUDA runtime and falls back to cpu
181
+ "maxRetries": 0, // quality-check retries (default 0 = no retry; retrying is noticeably slower)
181
182
  "requireCitations": true, // whether key conclusions must carry citations
182
183
  "includeTimestamps": false,
183
184
  "outputDir": "./output", // note output directory (can point at your Obsidian vault)
@@ -209,7 +210,7 @@ Video text extraction is a **unified pipeline** (the old "three tiers" are gone)
209
210
 
210
211
  `options.transcribe`: **default `true`** (auto-transcribe when no subtitles); set `false` to skip transcription (use subtitles/desc or degrade).
211
212
 
212
- **Transcription toolchain (identical for you and the author)**: the script **bootstraps itself** — it uses `uv` to create a **Python 3.12** environment + **Tsinghua mirror** to install `faster-whisper`, downloads the model via `HF_ENDPOINT=https://hf-mirror.com` and **caches it for reuse**; faster-whisper bundles PyAV to decode audio, so **no separate ffmpeg** is needed; **versions are pinned** (Python 3.12 / faster-whisper / uv) so the author's environment matches yours. The script is written in **Node**, so **Windows / macOS / Linux share one implementation and one command** (`node scripts/transcribe.js --audio <file> --out <txt>`). Transcription runs on **CPU** by default (`options.device`); GPU needs a CUDA runtime (cuBLAS/cuDNN), so `options.device: "auto"` is opt-in and falls back to CPU automatically. Cache location per platform: Windows `%LOCALAPPDATA%\deep-read-summarize`, macOS `~/Library/Caches/deep-read-summarize`, Linux `$XDG_CACHE_HOME/deep-read-summarize`.
213
+ **Transcription toolchain (identical for you and the author)**: the script **bootstraps itself** — it uses `uv` to create a **Python 3.12** environment + **Tsinghua mirror** to install `faster-whisper`, downloads the model via `HF_ENDPOINT=https://hf-mirror.com` and **caches it for reuse**; faster-whisper bundles PyAV to decode audio, so **no separate ffmpeg** is needed; **versions are pinned** (Python 3.12 / faster-whisper / uv) so the author's environment matches yours. The script is written in **Node**, so **Windows / macOS / Linux share one implementation and one command** (`node scripts/transcribe.js --audio <file> --out <txt>`). Transcription runs on **CPU** by default (`options.device`); GPU needs a CUDA runtime (cuBLAS/cuDNN), so `options.device: "auto"` is opt-in and falls back to CPU automatically. Cache location per platform: Windows `%LOCALAPPDATA%\deep-read-summarize`, macOS `~/Library/Caches/deep-read-summarize`, Linux `$XDG_CACHE_HOME/deep-read-summarize`. Python provisioning uses a mirror for speed and **falls back to a direct GitHub download when the mirror fails** (a dead mirror must not make the feature uninstallable); override it with the `DRS_UV_PYTHON_MIRROR` environment variable (empty string = never use a mirror).
213
214
 
214
215
  > ⚠️ **The first transcription downloads the model first (small ≈ 484 MB, via hf-mirror, not GitHub) and may take a few minutes** — please be patient; **it downloads only once** on your machine, then every later transcription uses the cache and starts instantly. **Only subtitle-less videos trigger transcription** (subtitled videos use their subtitles directly — no trigger, no download).
215
216
 
package/README.md CHANGED
@@ -102,7 +102,7 @@ deep-read-summarize 是 DSH 插件,可通过 npm、dsh.so 生态或本地安
102
102
  npm install deep-read-summarize
103
103
 
104
104
  # 或本地安装(dsh profile 目录)
105
- pnpm add ./deep-read-summarize-0.3.9.tgz
105
+ pnpm add ./deep-read-summarize-0.3.10.tgz
106
106
  # 然后在 dsh 配置的 dsh.profile.bundles 追加:
107
107
  # - deep-read-summarize
108
108
  # 重启 dsh web 即可(POST /dsh-market/restart)
@@ -178,6 +178,7 @@ parsers: book, paper, video, web
178
178
  "whisperModel": "small", // 视频转写模型档位:small | base | medium
179
179
  "language": "zh", // 视频转写语言:纯英文视频可设 "en"
180
180
  "device": "cpu", // 转写设备:cpu(默认)| auto | cuda;auto/cuda 需自备 CUDA 运行库,失败自动回退 cpu
181
+ "maxRetries": 0, // 质量校验重试次数(默认 0 = 不重试,重试会明显变慢)
181
182
  "requireCitations": true, // 关键结论是否必须标注出处
182
183
  "includeTimestamps": false,
183
184
  "outputDir": "./output", // 笔记输出目录(可指向 Obsidian 仓库)
@@ -209,7 +210,7 @@ parsers: book, paper, video, web
209
210
 
210
211
  `options.transcribe`:**默认 `true`**(无字幕自动转写);设为 `false` 则跳过转写(只用字幕/desc 或降级)。
211
212
 
212
- **转写工具链(本机/用户一致)**:脚本**自举**——用 `uv` 建 **Python 3.12** 环境 + **清华镜像**装 `faster-whisper` + `HF_ENDPOINT=https://hf-mirror.com` 下模型并**缓存复用**;faster-whisper 内置 PyAV 解码音频,**无需单独 ffmpeg**;**版本已锁定**(Python 3.12 / faster-whisper / uv),保证本机与用户环境一致。脚本是 **Node** 写的,**Windows / macOS / Linux 同一份实现、同一条命令**(`node scripts/transcribe.js --audio <音频> --out <txt>`);转写默认走 **CPU**(`options.device` 默认 `cpu`),GPU 需自备 CUDA 运行库(cuBLAS/cuDNN),可设 `options.device: "auto"` 尝试,失败会自动回退 CPU。缓存目录按平台取:Windows `%LOCALAPPDATA%\deep-read-summarize`、macOS `~/Library/Caches/deep-read-summarize`、Linux `$XDG_CACHE_HOME/deep-read-summarize`。
213
+ **转写工具链(本机/用户一致)**:脚本**自举**——用 `uv` 建 **Python 3.12** 环境 + **清华镜像**装 `faster-whisper` + `HF_ENDPOINT=https://hf-mirror.com` 下模型并**缓存复用**;faster-whisper 内置 PyAV 解码音频,**无需单独 ffmpeg**;**版本已锁定**(Python 3.12 / faster-whisper / uv),保证本机与用户环境一致。脚本是 **Node** 写的,**Windows / macOS / Linux 同一份实现、同一条命令**(`node scripts/transcribe.js --audio <音频> --out <txt>`);转写默认走 **CPU**(`options.device` 默认 `cpu`),GPU 需自备 CUDA 运行库(cuBLAS/cuDNN),可设 `options.device: "auto"` 尝试,失败会自动回退 CPU。缓存目录按平台取:Windows `%LOCALAPPDATA%\deep-read-summarize`、macOS `~/Library/Caches/deep-read-summarize`、Linux `$XDG_CACHE_HOME/deep-read-summarize`。 装 Python 时默认走镜像加速,**镜像失败会自动改用直连 GitHub 重试**(镜像挂掉不该让用户彻底装不上);可用环境变量 `DRS_UV_PYTHON_MIRROR` 覆盖(设为空字符串 = 完全不用镜像)。
213
214
 
214
215
  > ⚠️ **首次转写会先下载模型(small 约 484MB,走 hf-mirror,非 GitHub),可能需要几分钟**,请耐心等待;**本机只下这一次**,之后所有视频转写用缓存、秒开。**只有「无字幕」视频才会触发转写**(有字幕的视频直接用字幕,不触发、不下载)。
215
216
 
package/docs/RELEASE.md CHANGED
@@ -37,7 +37,7 @@
37
37
  ### 首选:npm Trusted Publishing(OIDC,无 token、无 OTP)
38
38
 
39
39
  ```yaml
40
- .github/workflows/publish.yml → 在 GitHub Release 被发布时自动发布
40
+ .github/workflows/publish.yml ← 手动 dispatch(首选,可靠)/ Release 被发布 / 历史 tag 补发
41
41
  ```
42
42
 
43
43
  凭据由 GitHub OIDC 在运行时现场换取,仓库里不存任何 npm token,也不会触发 npm 的 2FA 提示。
@@ -46,16 +46,35 @@
46
46
  # 1. 本地全绿
47
47
  npm run lint && npm test && npm run test:node && npm run validate
48
48
 
49
- # 2. 打 tag 并推送
49
+ # 2. 打 tag 并推送(publish.yml 只接受 tag ref)
50
50
  git tag -a vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z
51
51
 
52
- # 3. 建 Release —— 这一步触发 publish.yml
53
- gh release create vX.Y.Z --title "vX.Y.Z" --notes-file <notes 文件>
52
+ # 3. 触发发布:手动 dispatch(可靠)。先干跑一次也行:加 -f dry_run=true
53
+ gh workflow run publish.yml --ref main -f publish_ref=refs/tags/vX.Y.Z
54
+ gh run watch
54
55
 
55
- # 4. 验证线上
56
- npm view deep-read-summarize --prefer-online
56
+ # 4. 建 Release(记录用;见下方「别把建 Release 当主路径」)
57
+ gh release create vX.Y.Z --title "vX.Y.Z" --notes-file <notes 文件> <从 npm 拉回的 tgz>
57
58
  ```
58
59
 
60
+ > ⚠️ **别把「建 Release」当发布主路径**:`release: published` 事件的投递**不稳**
61
+ > (实测:同一天里,给一个历史 tag 补建 Release 没触发,另一个又正常触发)。
62
+ > Release 仍然要建——用户看的是它——但**发布动作交给第 3 步的 dispatch**。
63
+ > 两条都跑时 workflow 是幂等的:第二次会跳过发布步骤并留一条 warning,不会变红。
64
+
65
+ **怎么算发成功了(判据,2026-09-24 实测)**:
66
+
67
+ 1. **只看运行日志**:出现 `+ deep-read-summarize@X.Y.Z` 与 `Signed provenance statement`
68
+ (另有一条 sigstore 透明日志链接)。
69
+ 2. **不要用 `npm view` 的即时结果判断**:registry 要 **1–2 分钟**才对外可见,
70
+ 当场查必然是 **E404**、看着像失败(实测 t+40s 仍是 404,t+120s 才可见)。
71
+ 3. **`--dry-run` 全绿不等于发布成功**:npm 的 OIDC 换票失败会被 CLI 静默吞掉,
72
+ 真正的校验发生在写 registry 的那一刻(未配 Trusted Publisher 时报 404)。
73
+ 4. 最后再 `npm view deep-read-summarize dist-tags --json --prefer-online` 复核 `latest`。
74
+
75
+ **发完别忘了**:用 `npm pack <包>@<版本>` 拉回 registry 那一份字节,挂成 Release 资产
76
+ (本地构建的 tarball 与 CI 的不保证同字节),并把 SHA-256 写进 release notes。
77
+
59
78
  **前置(每个包一次性,只能在网页上配)**:
60
79
  `https://www.npmjs.com/package/<包名>/access` → Trusted Publishers → Add,填
61
80
  Provider `GitHub Actions` / Organization or user `PensiveFei` / Repository `deep-read-summarize` /
@@ -87,8 +106,12 @@ npm view deep-read-summarize --prefer-online # 验证线
87
106
 
88
107
  | 版本 | 状态 | 说明 |
89
108
  |------|------|------|
90
- | v0.1.0/v0.1.1 | git tag | 早期迭代,未上 npm |
109
+ | v0.1.0 / v0.1.1 | git tag | 早期迭代,未上 npm |
91
110
  | v0.2.x | npm 已发布 | 首个 npm 版本,含发布门禁 |
111
+ | v0.3.0 – v0.3.7 | npm 已发布 | 解析器插件化、幂等缓存、视频转写流水线 |
112
+ | v0.3.8 | **仅 GitHub** | 打了 tag 与 Release 但漏发到 npm(Trusted Publishing 迁移期的缺口;修复已随 0.3.9 交付) |
113
+ | v0.3.9 | npm 已发布 | macOS / Linux 支持(转写链路跨平台) |
114
+ | **v0.3.10** | **npm 已发布(当前)** | 修:失效的 uv 镜像、空转写被当成成功、发布文档过时 |
92
115
  | v1.0.0 | 计划 | API 稳定后发布 |
93
116
 
94
117
  > 早期迭代用 0.x 表达不稳定;API 稳定后再发 1.0.0。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "deep-read-summarize",
3
- "version": "0.3.9",
3
+ "version": "0.3.10",
4
4
  "description": "Deep reading & summarization for DSH: books/papers/videos/web → structured Obsidian notes. Plugin parsers, MapReduce deep-read, JSON Schema-constrained sub-tasks.",
5
5
  "type": "commonjs",
6
6
  "main": "index.js",
package/parsers/video.js CHANGED
@@ -65,7 +65,7 @@ module.exports = {
65
65
  " ① 先取音频:B站用 playurl(curl 'https://api.bilibili.com/x/player/playurl?avid=<aid>&cid=<cid>&fnval=16&fourk=1' 的 dash.audio[0].baseUrl)或 yt-dlp,下载存到 '" + tempDir + "/audio.m4a';\n" +
66
66
  " ② 定位插件转写脚本(文件名固定 `transcribe.js`):Windows 用 `Get-ChildItem -Path $env:USERPROFILE/.dsh -Recurse -Filter transcribe.js`;macOS/Linux 用 `find \"$HOME/.dsh\" -name transcribe.js`(也可直接用 glob 搜 *transcribe.js);\n" +
67
67
  " ③ 运行(**三平台命令行完全一致**,脚本是 Node 写的,与 pwsh / bash 无关):`node <脚本路径> --audio '" + tempDir + "/audio.m4a' --out '" + tempDir + "/transcript.txt' --device " + device + " --model " + whisperModel + " --language " + language + "`;\n" +
68
- " ④ 转写可能较慢:用 run_in_background: true 启动后,轮询输出文件 '" + tempDir + "/transcript.txt' 是否写出内容(非空且稳定),或日志出现 DONE;设合理超时,超时/失败则降级;\n" +
68
+ " ④ 转写可能较慢:用 run_in_background: true 启动后,轮询输出文件 '" + tempDir + "/transcript.txt' 是否写出内容(非空且稳定),或日志出现 DONE;设合理超时,超时/失败则降级;**脚本以非 0 退出也算失败**——包括「转写结果为空」(纯静音 / 纯音乐常见,脚本此时会删掉空文件),务必按降级处理,不要把空文件当成功;\n" +
69
69
  " ⑤ 成功后读取 transcript.txt 作为全文(textSource=transcription)。脚本自举:uv 建 Python 3.12 环境 + 镜像装 faster-whisper + hf-mirror 下模型并缓存;Windows/macOS/Linux 是**同一份实现**。**⚠️ 首次转写会先下载模型(small 约 484MB,hf-mirror,非 GitHub)并较慢——先向用户说明这是正常的一次性下载,勿当成卡死;之后缓存复用、秒开。**\n" +
70
70
  " ⑥ 若 `node` 不在 PATH(macOS 从图形界面启动时常见),先用 `command -v node` 确认;确认不可用就直接降级,不要为了跑转写脚本去安装 Node。"
71
71
  );
@@ -24,9 +24,14 @@ const path = require('node:path');
24
24
  // 版本锁定:保证作者机器与用户机器跑的是同一套(见 README「转写工具链」)。
25
25
  const PY_VERSION = '3.12';
26
26
  const PYPI_MIRROR = 'https://pypi.tuna.tsinghua.edu.cn/simple';
27
- // uv 拉 CPython 走的是 GitHub(python-build-standalone),在部分网络下极慢 → 走镜像。
28
- const UV_PYTHON_INSTALL_MIRROR =
29
- 'https://ghproxy.com/https://github.com/astral-sh/python-build-standalone/releases/download';
27
+ // uv 拉 CPython 走的是 GitHub(python-build-standalone),在部分网络下极慢 → 默认走镜像加速。
28
+ // ⚠️ 镜像会失效,而且代价很大:旧的 ghproxy.com 现在 301 到 ghfast.top 并丢掉路径,返回的是
29
+ // HTML 而不是资产;uv 拿到 HTML 会报 "Invalid gzip header",**不会**自己回退 GitHub ——
30
+ // 于是「慢但能装」变成「彻底装不上」,而踩到的恰好是没有 3.12 的新用户。
31
+ // 所以镜像只当加速用:失败后自动改用直连再试一次(见 venvEnvAttempts)。
32
+ // 覆盖方式:环境变量 DRS_UV_PYTHON_MIRROR(设为空字符串 = 完全不使用镜像)。
33
+ const UV_PYTHON_INSTALL_MIRROR_DEFAULT =
34
+ 'https://ghfast.top/https://github.com/astral-sh/python-build-standalone/releases/download';
30
35
  const HF_ENDPOINT = 'https://hf-mirror.com';
31
36
  const UV_INSTALL_SH = 'curl -LsSf https://astral.sh/uv/install.sh | sh';
32
37
  const CACHE_DIR_NAME = 'deep-read-summarize';
@@ -47,9 +52,7 @@ function context(overrides) {
47
52
  platform: o.platform || process.platform,
48
53
  env: o.env || process.env,
49
54
  home: o.home || os.homedir(),
50
- isFile: o.isFile || function (p) {
51
- try { return fs.statSync(p).isFile(); } catch (e) { return false; }
52
- }
55
+ isFile: o.isFile || isFileAt
53
56
  };
54
57
  }
55
58
 
@@ -121,6 +124,51 @@ function findUv(overrides) {
121
124
  return null;
122
125
  }
123
126
 
127
+ /** 当前生效的 uv CPython 镜像;返回空串表示不用镜像(直连 GitHub)。 */
128
+ function resolveUvMirror(env) {
129
+ const e = env || process.env;
130
+ const v = e.DRS_UV_PYTHON_MIRROR;
131
+ if (v === undefined) return UV_PYTHON_INSTALL_MIRROR_DEFAULT;
132
+ return String(v).trim();
133
+ }
134
+
135
+ /**
136
+ * 创建 venv 时要依次尝试的环境变量:先镜像(若配置了),失败再直连 GitHub。
137
+ * 返回 [{env, label}],调用方按顺序尝试。
138
+ */
139
+ function venvEnvAttempts(baseEnv, mirror) {
140
+ const list = [];
141
+ if (mirror) {
142
+ const withMirror = Object.assign({}, baseEnv);
143
+ withMirror.UV_PYTHON_INSTALL_MIRROR = mirror;
144
+ list.push({ env: withMirror, label: '镜像 ' + mirror });
145
+ }
146
+ const direct = Object.assign({}, baseEnv);
147
+ delete direct.UV_PYTHON_INSTALL_MIRROR;
148
+ list.push({ env: direct, label: '直连 GitHub' });
149
+ return list;
150
+ }
151
+
152
+ /**
153
+ * 判定转写产物是否可用。
154
+ * 0 字节 = VAD 把整段音频滤掉了(纯静音 / 纯 BGM)或解码失败。此时**不能算成功**:
155
+ * 调用方按「输出文件非空且稳定」判断完成,而提示词里还有一条「日志出现 DONE」——
156
+ * 两者叠加会让空逐字稿被当成转写成功,再拿去做精读。所以删掉空文件并以非 0 退出(code 3)。
157
+ */
158
+ function judgeTranscript(bytes) {
159
+ if (bytes > 0) return { ok: true, code: 0, message: '' };
160
+ return {
161
+ ok: false,
162
+ code: 3,
163
+ message: '转写结果为空(0 字节):音频可能是纯静音 / 纯音乐,或解码失败。已删除空输出文件,请按降级处理(让用户提供文案,或用 options.transcribe=false)。'
164
+ };
165
+ }
166
+
167
+ /** 路径是否为普通文件;目录一律拒绝(否则会把整个目录交给解码器,报出难懂的错误)。 */
168
+ function isFileAt(p) {
169
+ try { return fs.statSync(p).isFile(); } catch (e) { return false; }
170
+ }
171
+
124
172
  /** 解析命令行(支持 --k v、--k=v、-k v 三种写法)。 */
125
173
  function parseArgs(argv) {
126
174
  const out = { audio: '', out: '', model: 'small', language: 'zh', device: 'cpu', selfCheck: false, help: false, unknown: [] };
@@ -237,6 +285,7 @@ function main(argv) {
237
285
  return fail('--audio 与 --out 都是必填的。');
238
286
  }
239
287
  if (!fs.existsSync(args.audio)) return fail('音频文件不存在:' + args.audio);
288
+ if (!isFileAt(args.audio)) return fail('--audio 不是文件(是不是给了目录?):' + args.audio);
240
289
  if (uv === null) {
241
290
  return fail('没有找到 uv。请先安装:' + uvInstallHint(c) + '(装好后重跑本脚本;或改用 options.transcribe=false / 手动提供转写文本降级)');
242
291
  }
@@ -247,12 +296,25 @@ function main(argv) {
247
296
  fs.mkdirSync(path.dirname(path.resolve(args.out)), { recursive: true });
248
297
 
249
298
  const childEnv = Object.assign({}, process.env);
250
- childEnv.UV_PYTHON_INSTALL_MIRROR = UV_PYTHON_INSTALL_MIRROR;
251
299
 
252
- // 1) venv:优先复用已装好的 3.12,没有才让 uv 装(走镜像)
300
+ // 1) venv:优先复用已装好的 3.12,没有才让 uv 装。
301
+ // 镜像只用于加速;失败就换直连重试 —— 镜像挂掉不该让用户彻底装不上。
253
302
  if (!fs.existsSync(py)) {
254
303
  process.stdout.write('[transcribe] 创建 venv(Python ' + PY_VERSION + '):' + venvDir + '\n');
255
- runStep(uv, ['venv', '--python', PY_VERSION, venvDir], childEnv, 'uv venv');
304
+ const attempts = venvEnvAttempts(childEnv, resolveUvMirror(process.env));
305
+ let lastErr = null;
306
+ for (let i = 0; i < attempts.length; i++) {
307
+ try {
308
+ runStep(uv, ['venv', '--python', PY_VERSION, venvDir], attempts[i].env, 'uv venv');
309
+ } catch (e) { lastErr = e; }
310
+ if (fs.existsSync(py)) break;
311
+ // 失败的尝试可能留下半个 venv 目录,重试前先清掉
312
+ try { fs.rmSync(venvDir, { recursive: true, force: true }); } catch (e) { /* 清不掉就让下一次尝试自己报错 */ }
313
+ if (i + 1 < attempts.length) {
314
+ process.stderr.write('[transcribe] 用 ' + attempts[i].label + ' 创建 venv 失败,改用 ' + attempts[i + 1].label + ' 重试…\n');
315
+ }
316
+ }
317
+ if (!fs.existsSync(py)) throw (lastErr || new Error('uv venv 失败:' + venvDir));
256
318
  }
257
319
 
258
320
  // 2) faster-whisper:只在 import 失败时才装(离线/已装时零网络请求)
@@ -281,8 +343,11 @@ function main(argv) {
281
343
 
282
344
  const bytes = fs.statSync(args.out).size;
283
345
  process.stdout.write('TRANSCRIBED ' + bytes + ' bytes to ' + args.out + '\n');
284
- if (bytes === 0) {
285
- process.stderr.write('[transcribe] 输出为 0 字节:音频可能是纯静音(VAD 过滤)或解码失败,请按降级处理。\n');
346
+ const verdict = judgeTranscript(bytes);
347
+ if (!verdict.ok) {
348
+ // 删掉空文件:留着它会让「文件存在」被当成完成
349
+ try { fs.rmSync(args.out, { force: true }); } catch (e) { /* 删不掉也要如实报错 */ }
350
+ return fail(verdict.message, verdict.code);
286
351
  }
287
352
  return 0;
288
353
  } catch (e) {
@@ -296,6 +361,11 @@ if (require.main === module) {
296
361
 
297
362
  module.exports = {
298
363
  cacheRoot: cacheRoot,
364
+ resolveUvMirror: resolveUvMirror,
365
+ venvEnvAttempts: venvEnvAttempts,
366
+ judgeTranscript: judgeTranscript,
367
+ isFileAt: isFileAt,
368
+ UV_PYTHON_INSTALL_MIRROR_DEFAULT: UV_PYTHON_INSTALL_MIRROR_DEFAULT,
299
369
  venvPython: venvPython,
300
370
  uvInstallHint: uvInstallHint,
301
371
  uvCandidates: uvCandidates,
@@ -396,3 +396,61 @@ test('video prompt: the transcription block is a single numbered step', () => {
396
396
  'the ①-⑥ sub-steps must not be numbered as a top-level step of their own');
397
397
  assert.ok(/[0-9]+\. 转写执行/.test(on), 'the block still gets exactly one top-level number');
398
398
  });
399
+
400
+ // ============================================================================
401
+ // 0.3.10 回归:审计 0.3.9 时查出的三个问题
402
+ // ============================================================================
403
+ const { spawnSync } = require('node:child_process');
404
+
405
+ test('transcribe: the uv mirror is configurable and falls back to a direct download', () => {
406
+ // 旧的 ghproxy.com 已 301 到 ghfast.top 并丢掉路径(返回 HTML 而不是资产),
407
+ // uv 拿到 HTML 会报 "Invalid gzip header" 且不会自己回退 —— 于是「慢但能装」变成「装不上」。
408
+ assert.ok(transcribe.UV_PYTHON_INSTALL_MIRROR_DEFAULT.indexOf('ghproxy.com') === -1,
409
+ 'ghproxy.com moved and drops the path; it must not come back as the default');
410
+ assert.strictEqual(transcribe.resolveUvMirror({}), transcribe.UV_PYTHON_INSTALL_MIRROR_DEFAULT);
411
+ assert.strictEqual(transcribe.resolveUvMirror({ DRS_UV_PYTHON_MIRROR: 'https://mirror.example/' }),
412
+ 'https://mirror.example/', 'env override must win');
413
+ assert.strictEqual(transcribe.resolveUvMirror({ DRS_UV_PYTHON_MIRROR: '' }), '',
414
+ 'empty string = never use a mirror');
415
+
416
+ const attempts = transcribe.venvEnvAttempts({ PATH: '/x' }, 'https://mirror.example/');
417
+ assert.strictEqual(attempts.length, 2, 'mirror first, then a direct download');
418
+ assert.strictEqual(attempts[0].env.UV_PYTHON_INSTALL_MIRROR, 'https://mirror.example/');
419
+ assert.ok(!('UV_PYTHON_INSTALL_MIRROR' in attempts[1].env), 'the fallback must not carry the mirror');
420
+ assert.strictEqual(attempts[1].env.PATH, '/x', 'the base env must survive');
421
+
422
+ const directOnly = transcribe.venvEnvAttempts({}, '');
423
+ assert.strictEqual(directOnly.length, 1, 'no mirror configured -> a single direct attempt');
424
+ assert.strictEqual(directOnly[0].env.UV_PYTHON_INSTALL_MIRROR, undefined);
425
+ });
426
+
427
+ test('transcribe: a 0-byte transcript is a failure, not a success', () => {
428
+ // 调用方按「输出文件非空且稳定」判断完成,提示词里还有一条「日志出现 DONE」;
429
+ // 两者叠加会让纯静音视频的空逐字稿被当成转写成功,再拿去精读。
430
+ assert.strictEqual(transcribe.judgeTranscript(57).ok, true);
431
+ assert.strictEqual(transcribe.judgeTranscript(57).code, 0);
432
+ const empty = transcribe.judgeTranscript(0);
433
+ assert.strictEqual(empty.ok, false, 'a silent video must not look like a successful transcription');
434
+ assert.notStrictEqual(empty.code, 0, 'a distinct non-zero exit code is what makes the caller degrade');
435
+ assert.ok(/降级/.test(empty.message), 'the message must tell the caller to degrade');
436
+ });
437
+
438
+ test('transcribe: --audio pointing at a directory fails fast and leaves no output', () => {
439
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'drs-audio-'));
440
+ const out = path.join(dir, 'out.txt');
441
+ try {
442
+ const r = spawnSync(process.execPath,
443
+ [path.join(__dirname, '..', 'scripts', 'transcribe.js'), '--audio', dir, '--out', out],
444
+ { encoding: 'utf8' });
445
+ assert.notStrictEqual(r.status, 0, 'a directory must be rejected');
446
+ assert.ok(/不是文件/.test(r.stderr), 'expected a clear message, got: ' + r.stderr);
447
+ assert.ok(!fs.existsSync(out), 'no output file may be left behind');
448
+ } finally { fs.rmSync(dir, { recursive: true, force: true }); }
449
+ });
450
+
451
+ test('docs: RELEASE.md lists the version we are about to ship', () => {
452
+ const rel = fs.readFileSync(path.join(__dirname, '..', 'docs', 'RELEASE.md'), 'utf8');
453
+ const ver = require('../package.json').version;
454
+ assert.ok(rel.indexOf('v' + ver) >= 0,
455
+ 'docs/RELEASE.md 的「当前版本速览」必须包含当前版本 v' + ver + '(每次发版都要更新,别再让它停在旧版本)');
456
+ });