deep-read-summarize 0.3.19 → 0.5.0

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.
@@ -20,9 +20,14 @@ const { spawnSync } = require('node:child_process');
20
20
  const fs = require('node:fs');
21
21
  const os = require('node:os');
22
22
  const path = require('node:path');
23
+ const transcriptCache = require('../lib/transcript-cache');
23
24
 
24
- // 版本锁定:保证作者机器与用户机器跑的是同一套(见 README「转写工具链」)。
25
+ // 新环境使用 Python 3.12;ASR 主包固定为已验证版本。
26
+ // 复用环境不强制更换解释器;实际 Python / 传递依赖版本记录在 runtime.json。
25
27
  const PY_VERSION = '3.12';
28
+ const FASTER_WHISPER_VERSION = '1.2.1';
29
+ const DEPENDENCY_MISSING = 20;
30
+ const DEPENDENCY_VERSION_MISMATCH = 21;
26
31
  const PYPI_MIRROR = 'https://pypi.tuna.tsinghua.edu.cn/simple';
27
32
  // uv 拉 CPython 走的是 GitHub(python-build-standalone),在部分网络下极慢 → 默认走镜像加速。
28
33
  // ⚠️ 镜像会失效,而且代价很大:旧的 ghproxy.com 现在 301 到 ghfast.top 并丢掉路径,返回的是
@@ -171,19 +176,24 @@ function isFileAt(p) {
171
176
 
172
177
  /** 解析命令行(支持 --k v、--k=v、-k v 三种写法)。 */
173
178
  function parseArgs(argv) {
174
- const out = { audio: '', out: '', model: 'small', language: 'zh', device: 'cpu', timestamps: false, selfCheck: false, help: false, unknown: [] };
179
+ const out = { audio: '', out: '', model: 'small', language: 'zh', device: 'cpu', cpuThreads: 0,
180
+ cache: true, refreshCache: false, clearCache: false, timestamps: false, selfCheck: false, help: false, unknown: [] };
175
181
  const takes = {
176
182
  '--audio': 'audio', '-a': 'audio',
177
183
  '--out': 'out', '-o': 'out',
178
184
  '--model': 'model', '-m': 'model',
179
185
  '--language': 'language', '-l': 'language', '--lang': 'language',
180
- '--device': 'device', '-d': 'device'
186
+ '--device': 'device', '-d': 'device', '--cpu-threads': 'cpuThreads'
181
187
  };
182
188
  const list = argv || [];
183
189
  for (let i = 0; i < list.length; i++) {
184
190
  const a = String(list[i]);
185
191
  if (a === '--help' || a === '-h') { out.help = true; continue; }
186
192
  if (a === '--self-check') { out.selfCheck = true; continue; }
193
+ if (a === '--no-cache' || a === '--cache=false') { out.cache = false; continue; }
194
+ if (a === '--cache' || a === '--cache=true') { out.cache = true; continue; }
195
+ if (a === '--refresh-cache') { out.refreshCache = true; continue; }
196
+ if (a === '--clear-cache') { out.clearCache = true; continue; }
187
197
  if (a === '--timestamps' || a === '--timestamps=true') { out.timestamps = true; continue; }
188
198
  if (a === '--no-timestamps' || a === '--timestamps=false') { out.timestamps = false; continue; }
189
199
  if (takes[a]) {
@@ -204,15 +214,84 @@ function parseArgs(argv) {
204
214
  const PY_RUNNER = [
205
215
  "import os",
206
216
  "import sys",
207
- "from faster_whisper import WhisperModel",
217
+ "import json",
218
+ "import tempfile",
219
+ "import time",
220
+ "import importlib.metadata as metadata",
221
+ "runner_started = time.perf_counter()",
222
+ "timings = {'import': 0, 'modelLoad': 0, 'prepare': 0, 'inference': 0, 'write': 0}",
223
+ "",
224
+ "def bootstrap_required(code, reason, message):",
225
+ " status_file = os.environ.get('DRS_BOOTSTRAP_STATUS')",
226
+ " if status_file:",
227
+ " with open(status_file, 'w', encoding='utf-8') as f:",
228
+ " json.dump({'code': code, 'reason': reason}, f)",
229
+ " print('[transcribe] ' + message, file=sys.stderr)",
230
+ " sys.exit(code)",
231
+ "",
232
+ "expected_version = os.environ.get('DRS_FASTER_WHISPER_VERSION')",
233
+ "if expected_version:",
234
+ " try:",
235
+ " installed_version = metadata.version('faster-whisper')",
236
+ " except metadata.PackageNotFoundError:",
237
+ " bootstrap_required(" + DEPENDENCY_MISSING + ", 'missing-dependency', 'faster-whisper is not installed')",
238
+ " if installed_version != expected_version:",
239
+ " bootstrap_required(" + DEPENDENCY_VERSION_MISMATCH + ", 'version-mismatch', 'faster-whisper %s requires %s' % (installed_version, expected_version))",
240
+ "",
241
+ "try:",
242
+ " from faster_whisper import WhisperModel",
243
+ "except ModuleNotFoundError as exc:",
244
+ " bootstrap_required(" + DEPENDENCY_MISSING + ", 'missing-dependency', 'missing import dependency: %s' % exc)",
245
+ "timings['import'] = (time.perf_counter() - runner_started) * 1000",
246
+ "",
247
+ "runtime_versions = None",
248
+ "def record_runtime(device, phase):",
249
+ " global runtime_versions",
250
+ " target = os.environ.get('DRS_RUNTIME')",
251
+ " if not target:",
252
+ " return",
253
+ " if runtime_versions is None:",
254
+ " runtime_versions = {}",
255
+ " for name in ('faster-whisper', 'ctranslate2', 'av', 'huggingface-hub', 'tokenizers', 'onnxruntime'):",
256
+ " try:",
257
+ " runtime_versions[name] = metadata.version(name)",
258
+ " except metadata.PackageNotFoundError:",
259
+ " runtime_versions[name] = None",
260
+ " runtime = {'python': sys.version.split()[0], 'packages': runtime_versions, 'model': os.environ['DRS_MODEL'], 'device': device, 'computeType': 'int8', 'cpuThreads': int(os.environ.get('DRS_CPU_THREADS', '0')), 'phase': phase}",
261
+ " temporary = None",
262
+ " try:",
263
+ " with tempfile.NamedTemporaryFile(mode='w', encoding='utf-8', dir=os.path.dirname(target), prefix='.runtime-', suffix='.json', delete=False) as f:",
264
+ " temporary = f.name",
265
+ " json.dump(runtime, f, ensure_ascii=False, indent=2)",
266
+ " os.replace(temporary, target)",
267
+ " except OSError as exc:",
268
+ " print('[transcribe] runtime record unavailable: %s' % exc, file=sys.stderr)",
269
+ " finally:",
270
+ " if temporary and os.path.exists(temporary):",
271
+ " try:",
272
+ " os.unlink(temporary)",
273
+ " except OSError:",
274
+ " pass",
275
+ " print('[transcribe] runtime python=%s faster-whisper=%s device=%s phase=%s' % (runtime['python'], runtime_versions['faster-whisper'], device, phase), file=sys.stderr)",
208
276
  "",
209
277
  "def load(device):",
210
- " return WhisperModel(os.environ['DRS_MODEL'], device=device, compute_type='int8')",
278
+ " return WhisperModel(os.environ['DRS_MODEL'], device=device, compute_type='int8', cpu_threads=int(os.environ.get('DRS_CPU_THREADS', '0')))",
211
279
  "",
212
280
  "def run(device):",
213
- " model = load(device)",
281
+ " started = time.perf_counter()",
282
+ " try:",
283
+ " model = load(device)",
284
+ " finally:",
285
+ " timings['modelLoad'] += (time.perf_counter() - started) * 1000",
286
+ " started = time.perf_counter()",
214
287
  " segs, info = model.transcribe(os.environ['DRS_AUDIO'], vad_filter=True, language=(os.environ.get('DRS_LANG') or None))",
215
- " return [{'start': s.start, 'end': s.end, 'text': s.text.strip()} for s in segs], info",
288
+ " timings['prepare'] += (time.perf_counter() - started) * 1000",
289
+ " started = time.perf_counter()",
290
+ " try:",
291
+ " segments = [{'start': s.start, 'end': s.end, 'text': s.text.strip().replace('\\r', ' ').replace('\\n', ' ')} for s in segs if s.text.strip()]",
292
+ " finally:",
293
+ " timings['inference'] += (time.perf_counter() - started) * 1000",
294
+ " return segments, info, getattr(getattr(model, 'model', None), 'device', device)",
216
295
  "",
217
296
  "def timestamp(seconds):",
218
297
  " millis = max(0, int(round(float(seconds) * 1000)))",
@@ -224,16 +303,21 @@ const PY_RUNNER = [
224
303
  "# device 默认 cpu:ctranslate2 只要探测到 NVIDIA 显卡就会在 auto 下选 CUDA,",
225
304
  "# 而多数机器没装 cuBLAS/cuDNN(cublas64_12.dll),会在推理时硬失败(实测 RTX 3050 复现)。",
226
305
  "device = os.environ.get('DRS_DEVICE') or 'cpu'",
306
+ "record_runtime(device, 'starting')",
227
307
  "try:",
228
- " segments, info = run(device)",
308
+ " segments, info, device = run(device)",
229
309
  "except Exception as exc:",
230
310
  " if device == 'cpu':",
231
311
  " raise",
232
312
  " print('[transcribe] device=%s failed (%s); retrying on cpu' % (device, exc), file=sys.stderr)",
233
- " segments, info = run('cpu')",
313
+ " device = 'cpu'",
314
+ " record_runtime(device, 'starting')",
315
+ " segments, info, device = run('cpu')",
316
+ "record_runtime(device, 'completed')",
234
317
  "",
235
318
  "# DRS_OUT 是本次调用独有的暂存路径;Node 校验后才原子发布到最终路径。",
236
319
  "# 先收集全部分段再落盘,中途推理失败不会留下半截文本。",
320
+ "write_started = time.perf_counter()",
237
321
  "include_timestamps = os.environ.get('DRS_TIMESTAMPS') == '1'",
238
322
  "lines = []",
239
323
  "for segment in segments:",
@@ -245,6 +329,11 @@ const PY_RUNNER = [
245
329
  " lines.append(text)",
246
330
  "with open(os.environ['DRS_OUT'], 'w', encoding='utf-8', newline='\\n') as f:",
247
331
  " f.write('\\n'.join(lines))",
332
+ "timings['write'] = (time.perf_counter() - write_started) * 1000",
333
+ "timings['total'] = (time.perf_counter() - runner_started) * 1000",
334
+ "if os.environ.get('DRS_SEGMENTS'):",
335
+ " with open(os.environ['DRS_SEGMENTS'], 'w', encoding='utf-8') as f:",
336
+ " json.dump({'segments': segments, 'device': device, 'cpuThreads': int(os.environ.get('DRS_CPU_THREADS', '0')), 'duration': getattr(info, 'duration', None), 'durationAfterVad': getattr(info, 'duration_after_vad', None), 'timings': timings}, f, ensure_ascii=False, allow_nan=False)",
248
337
  ""
249
338
  ].join("\n");
250
339
 
@@ -258,7 +347,9 @@ const USAGE = [
258
347
  '',
259
348
  '选项:--audio/-a --out/-o --model/-m(默认 small) --language/-l(默认 zh)',
260
349
  ' --device(默认 cpu;auto/cuda 需自备 CUDA 运行库,失败会自动回退 cpu)',
261
- ' --timestamps(逐段保留真实起止时间;默认关闭,关闭时仍按段换行)'
350
+ ' --timestamps(逐段保留真实起止时间;默认关闭,关闭时仍按段换行)',
351
+ ' --cpu-threads 0..64(0 保持库默认值);--no-cache 禁用逐字稿缓存',
352
+ ' --refresh-cache 强制重转写并更新缓存;--clear-cache 仅清理逐字稿缓存'
262
353
  ].join('\n');
263
354
 
264
355
  function fail(msg, code) {
@@ -268,11 +359,28 @@ function fail(msg, code) {
268
359
 
269
360
  function runStep(cmd, cmdArgs, env, errLabel) {
270
361
  const r = spawnSync(cmd, cmdArgs, { stdio: 'inherit', env: env, shell: false });
362
+ checkStep(r, cmd, errLabel);
363
+ }
364
+
365
+ function checkStep(r, cmd, errLabel) {
271
366
  if (r.error) throw new Error(errLabel + ' 无法执行(' + cmd + '):' + r.error.message);
272
367
  if (r.status !== 0) throw new Error(errLabel + ' 失败(退出码 ' + r.status + ')');
273
368
  }
274
369
 
370
+ /** 仅 runner 导入/版本预检写出的特定状态允许安装,推理失败不能触发安装。 */
371
+ function needsBootstrap(result, statusFile) {
372
+ if (result.error || (result.status !== DEPENDENCY_MISSING && result.status !== DEPENDENCY_VERSION_MISMATCH)) return false;
373
+ try {
374
+ const status = JSON.parse(fs.readFileSync(statusFile, 'utf8'));
375
+ return status.code === result.status &&
376
+ ((status.code === DEPENDENCY_MISSING && status.reason === 'missing-dependency') ||
377
+ (status.code === DEPENDENCY_VERSION_MISMATCH && status.reason === 'version-mismatch'));
378
+ } catch (e) { return false; }
379
+ }
380
+
275
381
  function main(argv) {
382
+ const startedAt = Date.now();
383
+ const timing = { hash: 0, environment: 0, cacheLookup: 0, dependencyInstall: 0, python: 0, publish: 0, total: 0 };
276
384
  const args = parseArgs(argv);
277
385
  const c = context({});
278
386
  const root = cacheRoot(c);
@@ -281,7 +389,6 @@ function main(argv) {
281
389
  const uv = findUv(c);
282
390
 
283
391
  if (args.help) { process.stdout.write(USAGE + '\n'); return 0; }
284
-
285
392
  // --self-check:CI 与排查用,只报告解析结果,不产生任何副作用。
286
393
  if (args.selfCheck) {
287
394
  process.stdout.write(JSON.stringify({
@@ -292,12 +399,22 @@ function main(argv) {
292
399
  uv: uv,
293
400
  uvInstallHint: uvInstallHint(c),
294
401
  pythonVersion: PY_VERSION,
402
+ fasterWhisperVersion: FASTER_WHISPER_VERSION,
403
+ runtimeRecord: path.join(root, 'runtime.json'),
295
404
  node: process.version
296
405
  }, null, 2) + '\n');
297
406
  return 0;
298
407
  }
299
408
 
409
+ if (args.clearCache) {
410
+ try { transcriptCache.clear(root); process.stdout.write('[transcribe] transcript cache cleared\n'); return 0; }
411
+ catch (error) { return fail('无法清理逐字稿缓存:' + error.message); }
412
+ }
413
+
300
414
  if (args.unknown.length) process.stderr.write('[transcribe] 忽略未知参数:' + args.unknown.join(', ') + '\n');
415
+ if (!/^\d+$/.test(String(args.cpuThreads))) return fail('--cpu-threads 必须为 0..64 的整数');
416
+ args.cpuThreads = Number(args.cpuThreads);
417
+ if (!Number.isInteger(args.cpuThreads) || args.cpuThreads < 0 || args.cpuThreads > 64) return fail('--cpu-threads 必须为 0..64 的整数');
301
418
  if (!args.audio || !args.out) {
302
419
  process.stderr.write(USAGE + '\n');
303
420
  return fail('--audio 与 --out 都是必填的。');
@@ -315,9 +432,6 @@ function main(argv) {
315
432
  fs.rmSync(outputPath, { force: true });
316
433
  if (!fs.existsSync(args.audio)) return fail('音频文件不存在:' + args.audio);
317
434
  if (!isFileAt(args.audio)) return fail('--audio 不是文件(是不是给了目录?):' + args.audio);
318
- if (uv === null) {
319
- return fail('没有找到 uv。请先安装:' + uvInstallHint(c) + '(装好后重跑本脚本;或改用 options.transcribe=false / 手动提供转写文本降级)');
320
- }
321
435
 
322
436
  fs.mkdirSync(root, { recursive: true });
323
437
  // 输出目录可能在别处(如 ./.tmp),提前建好,免得 python 侧报一句难懂的错
@@ -325,37 +439,56 @@ function main(argv) {
325
439
  // 与最终文件处于同一文件系统,rename 才能原子发布;每次调用独占暂存目录。
326
440
  stagingDir = fs.mkdtempSync(path.join(path.dirname(outputPath), '.drs-transcribe-'));
327
441
  const stagingOutput = path.join(stagingDir, 'transcript.txt');
442
+ const segmentsFile = path.join(stagingDir, 'segments.json');
443
+ const hashStarted = Date.now();
444
+ const audioHash = args.cache ? transcriptCache.hashFile(args.audio) : null;
445
+ timing.hash = Date.now() - hashStarted;
446
+ const lookupStarted = Date.now();
447
+ const runtimeBefore = args.cache ? transcriptCache.runtimeIdentity(root, args.model) : null;
448
+ const id = transcriptCache.identity(audioHash, args, runtimeBefore, PY_RUNNER);
449
+ const cached = args.cache && !args.refreshCache ? transcriptCache.read(root, id) : null;
450
+ timing.cacheLookup = Date.now() - lookupStarted;
451
+ if (cached) {
452
+ fs.writeFileSync(stagingOutput, transcriptCache.render(cached.segments, args.timestamps), 'utf8');
453
+ const publishStarted = Date.now();
454
+ fs.renameSync(stagingOutput, outputPath);
455
+ timing.publish = Date.now() - publishStarted;
456
+ timing.total = Date.now() - startedAt;
457
+ process.stdout.write('[transcribe] metrics ' + JSON.stringify({ cacheHit: true, device: cached.device,
458
+ cpuThreads: cached.cpuThreads, duration: cached.duration, timings: timing }) + '\n');
459
+ process.stdout.write('TRANSCRIBED ' + fs.statSync(outputPath).size + ' bytes to ' + args.out + '\nDONE\n');
460
+ return 0;
461
+ }
328
462
 
329
463
  const childEnv = Object.assign({}, process.env);
464
+ const environmentStarted = Date.now();
330
465
 
331
466
  // 1) venv:优先复用已装好的 3.12,没有才让 uv 装。
332
467
  // 镜像只用于加速;失败就换直连重试 —— 镜像挂掉不该让用户彻底装不上。
333
- if (!fs.existsSync(py)) {
468
+ if (!isFileAt(py)) {
469
+ if (uv === null) throw new Error('需要创建 Python 环境,但没有找到 uv。请先安装:' + uvInstallHint(c));
334
470
  process.stdout.write('[transcribe] 创建 venv(Python ' + PY_VERSION + '):' + venvDir + '\n');
335
471
  const attempts = venvEnvAttempts(childEnv, resolveUvMirror(process.env));
336
472
  let lastErr = null;
473
+ let created = false;
337
474
  for (let i = 0; i < attempts.length; i++) {
338
475
  try {
339
476
  runStep(uv, ['venv', '--python', PY_VERSION, venvDir], attempts[i].env, 'uv venv');
477
+ if (!isFileAt(py)) throw new Error('uv venv 未生成 Python 解释器文件:' + py);
478
+ created = true;
340
479
  } catch (e) { lastErr = e; }
341
- if (fs.existsSync(py)) break;
480
+ if (created) break;
342
481
  // 失败的尝试可能留下半个 venv 目录,重试前先清掉
343
482
  try { fs.rmSync(venvDir, { recursive: true, force: true }); } catch (e) { /* 清不掉就让下一次尝试自己报错 */ }
344
483
  if (i + 1 < attempts.length) {
345
484
  process.stderr.write('[transcribe] 用 ' + attempts[i].label + ' 创建 venv 失败,改用 ' + attempts[i + 1].label + ' 重试…\n');
346
485
  }
347
486
  }
348
- if (!fs.existsSync(py)) throw (lastErr || new Error('uv venv 失败:' + venvDir));
349
- }
350
-
351
- // 2) faster-whisper:只在 import 失败时才装(离线/已装时零网络请求)
352
- const probe = spawnSync(py, ['-c', 'import faster_whisper'], { stdio: 'ignore', shell: false });
353
- if (probe.status !== 0) {
354
- process.stdout.write('[transcribe] 安装 faster-whisper(清华镜像)…\n');
355
- runStep(uv, ['pip', 'install', '--python', py, 'faster-whisper', '-i', PYPI_MIRROR], childEnv, 'faster-whisper 安装');
487
+ if (!created) throw (lastErr || new Error('uv venv 失败:' + venvDir));
356
488
  }
357
489
 
358
- // 3) 运行时环境变量:hf-mirror + 关掉会绕开镜像并 401 的 hf-xet 后端
490
+ // 2) 健康环境直接运行;不另开 Python 重复 import,也不要求 uv 仍在 PATH。
491
+ // 运行时环境变量:hf-mirror + 关掉会绕开镜像并 401 的 hf-xet 后端
359
492
  childEnv.HF_ENDPOINT = HF_ENDPOINT;
360
493
  childEnv.HF_HOME = path.join(root, 'hf');
361
494
  childEnv.HF_HUB_DISABLE_XET = '1';
@@ -366,19 +499,65 @@ function main(argv) {
366
499
  childEnv.DRS_LANG = args.language;
367
500
  childEnv.DRS_DEVICE = args.device;
368
501
  childEnv.DRS_TIMESTAMPS = args.timestamps ? '1' : '0';
502
+ childEnv.DRS_CPU_THREADS = String(args.cpuThreads);
503
+ childEnv.DRS_SEGMENTS = segmentsFile;
504
+ childEnv.DRS_FASTER_WHISPER_VERSION = FASTER_WHISPER_VERSION;
505
+ childEnv.DRS_RUNTIME = path.join(root, 'runtime.json');
506
+ const bootstrapStatus = path.join(stagingDir, 'bootstrap-status.json');
507
+ childEnv.DRS_BOOTSTRAP_STATUS = bootstrapStatus;
369
508
 
370
509
  const pyScript = path.join(stagingDir, 'transcribe_run.py');
371
510
  fs.writeFileSync(pyScript, PY_RUNNER, 'utf8');
372
-
373
- // 4) 转写(首次会下载模型到 HF_HOME,之后缓存复用)
374
- runStep(py, [pyScript], childEnv, '转写');
511
+ timing.environment = Date.now() - environmentStarted;
512
+ const pythonStarted = Date.now();
513
+
514
+ // 3) 转写(首次会下载模型到 HF_HOME,之后缓存复用)。
515
+ // 只有导入缺失/明确版本不符才允许自举并重试一次,解码/CUDA/推理失败不重装。
516
+ const result = spawnSync(py, [pyScript], { stdio: 'inherit', env: childEnv, shell: false });
517
+ if (needsBootstrap(result, bootstrapStatus)) {
518
+ if (uv === null) throw new Error('需要安装 faster-whisper==' + FASTER_WHISPER_VERSION + ',但没有找到 uv。请先安装:' + uvInstallHint(c));
519
+ process.stdout.write('[transcribe] 安装 faster-whisper==' + FASTER_WHISPER_VERSION + '(清华镜像)…\n');
520
+ const installStarted = Date.now();
521
+ runStep(uv, ['pip', 'install', '--python', py, 'faster-whisper==' + FASTER_WHISPER_VERSION, '-i', PYPI_MIRROR], childEnv, 'faster-whisper 安装');
522
+ timing.dependencyInstall = Date.now() - installStarted;
523
+ fs.rmSync(bootstrapStatus, { force: true });
524
+ runStep(py, [pyScript], childEnv, '转写');
525
+ } else {
526
+ checkStep(result, py, '转写');
527
+ }
528
+ timing.python = Date.now() - pythonStarted - timing.dependencyInstall;
375
529
 
376
530
  const bytes = fs.statSync(stagingOutput).size;
377
531
  const verdict = judgeTranscript(bytes);
378
532
  if (!verdict.ok) {
379
533
  return fail(verdict.message, verdict.code);
380
534
  }
535
+ let report = null;
536
+ try {
537
+ const candidate = JSON.parse(fs.readFileSync(segmentsFile, 'utf8'));
538
+ if (transcriptCache.validSegments(candidate.segments) &&
539
+ transcriptCache.render(candidate.segments, args.timestamps) === fs.readFileSync(stagingOutput, 'utf8')) report = candidate;
540
+ } catch (error) { /* A missing diagnostic must not discard a valid transcript. */ }
541
+ const publishStarted = Date.now();
381
542
  fs.renameSync(stagingOutput, outputPath);
543
+ timing.publish = Date.now() - publishStarted;
544
+ if (args.cache && report) {
545
+ try {
546
+ const runtimeAfter = transcriptCache.runtimeIdentity(root, args.model);
547
+ // Do not cache audio modified during inference, or a model/environment
548
+ // changed concurrently. A newly bootstrapped environment is eligible.
549
+ if ((!runtimeBefore || runtimeBefore === runtimeAfter) && audioHash === transcriptCache.hashFile(args.audio)) {
550
+ const stored = transcriptCache.write(root, transcriptCache.identity(audioHash, args, runtimeAfter, PY_RUNNER), report);
551
+ if (!stored) process.stderr.write('[transcribe] transcript cache unavailable; current result retained\n');
552
+ }
553
+ } catch (error) {
554
+ process.stderr.write('[transcribe] transcript cache unavailable; current result retained\n');
555
+ }
556
+ }
557
+ timing.total = Date.now() - startedAt;
558
+ process.stdout.write('[transcribe] metrics ' + JSON.stringify({ cacheHit: false, device: report && report.device,
559
+ cpuThreads: args.cpuThreads, duration: report && report.duration, timings: timing,
560
+ runnerTimings: report && report.timings }) + '\n');
382
561
  process.stdout.write('TRANSCRIBED ' + bytes + ' bytes to ' + args.out + '\n');
383
562
  process.stdout.write('DONE\n');
384
563
  return 0;
@@ -409,5 +588,9 @@ module.exports = {
409
588
  findUv: findUv,
410
589
  parseArgs: parseArgs,
411
590
  PY_VERSION: PY_VERSION,
591
+ FASTER_WHISPER_VERSION: FASTER_WHISPER_VERSION,
592
+ DEPENDENCY_MISSING: DEPENDENCY_MISSING,
593
+ DEPENDENCY_VERSION_MISMATCH: DEPENDENCY_VERSION_MISMATCH,
594
+ needsBootstrap: needsBootstrap,
412
595
  PY_RUNNER: PY_RUNNER
413
596
  };
@@ -13,7 +13,7 @@ whenToUse: 用户提供一本书、论文(arXiv/PDF)、视频链接(YouTub
13
13
  ## 能力
14
14
 
15
15
  - 书籍(PDF/EPUB/MOBI)、论文(arXiv/PDF/HTML)、视频(字幕优先,无字幕自动转写)、网页
16
- - 长内容分块后由并行子代理精读(MapReduce),不溢出上下文
16
+ - 长内容分块后由并行子代理精读(MapReduce),降低单个代理的上下文压力;超长资料仍受宿主上下文和工具读取上限约束
17
17
  - 获取/分块与质量校验的输出受 JSON Schema 约束,结构稳定、下游可解析
18
18
  - 分块计划与子代理数量受 `maxChunks` 强制约束(计划失控会顶穿单次调用时限)
19
19
  - 关键引用标注页码/章节/段落,降低编造风险
@@ -23,7 +23,9 @@ whenToUse: 用户提供一本书、论文(arXiv/PDF)、视频链接(YouTub
23
23
  ## 输入
24
24
 
25
25
  用户提供:内容链接或本地文件路径。
26
- 可选参数:`type`(auto/book/paper/video/web)、`options`(minWords / fastMode / maxChunks / maxRetries / requireCitations / includeTimestamps / transcribe / whisperModel / language / device / outputDir / tempDir / frontmatter)。
26
+ 可选参数:`type`(auto/book/paper/video/web)、`options`(minWords / fastMode / maxChunks / maxRetries / requireCitations / includeTimestamps / transcribe / whisperModel / language / device / cpuThreads / transcriptCache / outputDir / tempDir / frontmatter)。
27
+
28
+ 优先调用插件提供的 `deep_read_summarize` 工具,参数为 `{ input, type, options }`。如果当前宿主没有这个工具,按技能末尾提供的 meta / script / args 调用 `workflow` 工具。两种入口执行相同的获取、精读与质量核验。
27
29
 
28
30
  `options.frontmatter` 决定 frontmatter 用哪套键(默认 `obsidian`,与历史行为一致):
29
31
  - `obsidian`:title / aliases / author / year / type / url / tags / created / status —— 配 Dataview 用这套
@@ -37,16 +39,16 @@ whenToUse: 用户提供一本书、论文(arXiv/PDF)、视频链接(YouTub
37
39
  1. **配置校验**:缺 input 或 type 非法 → 报 FATAL 终止
38
40
  2. **幂等检查(由你执行,脚本不做)**:脚本在沙箱内没有文件系统,写不了指纹记录。落盘前先看目标 `filePath` 是否已有同名笔记——已存在就问用户是覆盖还是跳过,别默默重跑一遍烧 token。(要在程序里做去重,可用插件导出的 `lib/cache.js`:fingerprint / hasProcessed / markProcessed。)
39
41
  3. **解析器选择**:按类型从 parsers 注册表选解析器(book/paper/video/web)。`auto` 对明确视频链接、arXiv 论文链接、电子书扩展名直接分流;同站的图文/频道/帮助页、PDF/未知网页/文本等模糊输入先轻量识别,不能固定当作网页。识别失败返回 `stage: "detect"`,再请用户显式指定类型
40
- 4. **波次1 获取+分块**:解析器获取全文 → 写入本次独立的临时子目录 → 生成分块计划(JSON Schema 校验)。`tempDir` 是根目录,不要复用其他 `run-*` 任务的 input/audio/transcript;分块超过上限时合并相邻区间,保持从第 1 行到 totalLines 的完整覆盖
41
- 5. **波次2 并行精读**:每个分块一个子代理深度精读(Map)
42
+ 4. **波次1 获取+分块**:解析器获取全文 → 写入本次独立的临时子目录 → 生成分块计划(JSON Schema 校验)。`tempDir` 是根目录,不要复用其他 `run-*` 任务的 input/audio/transcript;规范化全部区间并按行数均衡工作量,保持从第 1 行到 totalLines 的完整覆盖,不得截断原文
43
+ 5. **波次2 并行精读**:每个分块一个子代理深度精读(Map),最多三个槽位同时工作,空闲即领取下一块,输出保持分块顺序
42
44
  6. **波次3 合并成稿**:整合为完整笔记(Reduce),内嵌质量自检
43
- 7. **质量校验**:程序检查 frontmatter 模板、必要章节和篇幅;核验代理必须读取本次原文,逐块提供摘录、对第 4 节逐字引用提供原句与行号。不得只看笔记或仅返回 pass。`qualityEvidence` 可供回查;核验失败必须如实报告。`maxRetries` 为 0–3,修订失败、空结果或结构退化时保留上一份有效成稿
44
- 8. **落盘(必须,别跳过)**:workflow 工具只返回 `note`(笔记正文)与 `filePath`(建议路径)——**脚本本身没有文件系统权限**。拿到结果后要用 `write` 工具把 `note` 原样写入 `filePath`(目录不存在就先创建);不写就等于笔记丢了,用户只会看到一段返回文本
45
+ 7. **质量校验**:程序检查 frontmatter 模板、必要章节和篇幅;核验代理必须读取本次原文,逐块提供摘录、对第 4 节逐字引用提供原句与行号。不得只看笔记或仅返回 pass。`qualityEvidence` 可供回查;核验失败必须如实报告。`maxRetries` 为 0–3,修订失败、空结果或结构退化时保留上一份有效成稿。缺总行数、精读失败、仅简介或未知视频来源等问题不能靠改写笔记消除,不进行徒劳全文修订
46
+ 8. **落盘(必须,别跳过)**:精读工具只返回 `note`(笔记正文)与 `filePath`(建议路径)——**脚本本身没有文件系统权限**。拿到结果后要用 `write` 工具把 `note` 原样写入 `filePath`(目录不存在就先创建);不写就等于笔记丢了,用户只会看到一段返回文本
45
47
  9. **如实交代结果**:`ok: false` 要说明卡在哪一步(`stage`)和原因,别拿半成品冒充成品;`qualityPassed: false`、`qualityIssues` 非空、或 `failedChunks > 0`(有块精读失败、笔记存在缺口)时,必须在回复里点出来
46
48
 
47
49
  ## 输出
48
50
 
49
- workflow 返回 `{ ok, filePath, note, qualityPassed, qualityIssues, qualityChecks, qualityEvidence, failedChunks, coverageComplete, textSource }`。`coverageComplete: false` 表示获取结果缺少有效总行数,无法确认尾部覆盖;此时质量状态也会降级,必须向用户说明。
51
+ 精读工具返回 `{ ok, filePath, note, qualityPassed, qualityIssues, qualityChecks, qualityEvidence, failedChunks, coverageComplete, sourceComplete, textSource, timings }`。`coverageComplete: false` 表示缺少有效总行数,无法确认尾部覆盖;`sourceComplete: false` 表示视频仅有简介或来源未确认,笔记会保留来源限制且质量降级。来源完整性仍依据获取代理声明,不能当作视频真实内容已全部证明。`timings` 提供 detect/fetch/read/draft/quality/total 毫秒耗时,不能由此推测未提供的 token 用量。
50
52
 
51
53
  > ⚠️ **`note` 就是完整笔记正文,`filePath` 只是建议路径**:脚本运行在无文件系统的沙箱里(DSH 的 workflow 契约:脚本只负责协调子代理),**它不会替你写文件**。必须由你(主代理)在拿到结果后用 `write` 工具把它写到 `filePath`——默认 `./output/`,可用 `options.outputDir` 指向 Obsidian 仓库或静态站点的内容目录。
52
54
 
@@ -79,7 +81,9 @@ status: 已完成
79
81
  3. 都不行 → 降级提示用户手动提供转写文本,或退回 desc 作背景;**绝不阻塞、绝不自动装重依赖**。
80
82
  - `options.transcribe`:**默认 true**(无字幕自动转写);设为 `false` 则跳过转写(只用字幕/desc 或降级)。
81
83
  - **转写工具链**:脚本自举,本机/用户一致——`uv` 建 Python 3.12 环境 + 清华镜像装 `faster-whisper` + `HF_ENDPOINT=https://hf-mirror.com` 下模型并缓存;脚本是 **Node** 写的,三平台**同一份实现、同一条命令**(`node <脚本路径> --audio <音频> --out <txt>`);转写默认 **CPU**(`options.device` 默认 `cpu`),GPU 需自备 CUDA 运行库(设 `options.device: "auto"`,失败自动回退 CPU);faster-whisper 内置 PyAV 解码音频,**无需单独 ffmpeg**。
82
- - **⚠️ 首次转写会先下载 small 模型(约 484MB,hf-mirror,非 GitHub),可能较慢**——执行转写前**先向用户说明**这是正常的一次性下载,之后缓存复用、秒开;不要当成卡死而中断。
84
+ - **⚠️ 首次转写会先下载 small 模型(约 484MB,hf-mirror,非 GitHub),可能较慢**——执行转写前**先向用户说明**这是正常的一次性下载;之后复用模型文件,新音频仍需推理,不保证秒开。
85
+ - `options.transcriptCache` 默认 true:只有脚本核对音频内容、受管理的模型快照、环境和解码配置后才可复用逐字稿,命中也必须确认本次进程成功并发布本次产物,不能直接使用别的任务的旧文件。缓存含本地文本、有效期 30 天、总量上限 128 MiB;`--clear-cache` 只清理逐字稿。设 false 禁用读写,`--refresh-cache` 可强制重转写。缓存不会跳过精读和独立核验。
86
+ - `options.cpuThreads` 为 0–64 的整数,默认 0 保持库默认策略。记录转写日志的 metrics:cacheHit、实际设备、音频时长与阶段耗时;命中缓存时不要引用上次推理耗时,也不要由此推测 token。笔记核验不能证明音轨听写准确,线程或 GPU 调优需单独比对音频,不自行降低模型或解码门槛。
83
87
  - **质量/速度**:small/int8 + VAD 静音过滤,中文质量可用且 CPU 友好;有字幕视频不转写(快)。装不上/失败则降级,不静默。
84
88
  - YouTube 用 yt-dlp 抓 CC;未装时**绝不下载 exe 二进制**(GitHub 直连易卡死),按系统装(Windows `winget install yt-dlp.yt-dlp` / macOS `brew install yt-dlp` / 任意平台 `pip install -U yt-dlp`);仍不可用则转写或降级。
85
89
  - 运行 yt-dlp 加 `--socket-timeout 15 --retries 3` 防超时。
package/workflow.js CHANGED
@@ -48,7 +48,6 @@ const schemas = require("./schemas");
48
48
  const { buildParserBundle } = require("./lib/parser-bundle");
49
49
  const { normalizeWorkflowOptions } = require("./lib/options");
50
50
  const quality = require("./lib/quality");
51
- const parserRegistry = parsers.registry;
52
51
 
53
52
  /**
54
53
  * 把注册表里的解析器(buildPrompt)连同其依赖的 buildFetchPrompt 内联进
@@ -61,7 +60,7 @@ const parserRegistry = parsers.registry;
61
60
  * 和这里两道关都被丢掉)。fetchSchema 同样从 schemas/index.js 注入,
62
61
  * 保持单一真相,不再和脚本里的副本各自漂移。
63
62
  */
64
- function buildSelfContainedScript() {
63
+ function buildSelfContainedScript(parserRegistry = parsers.registry) {
65
64
  const parserNames = Object.keys(parserRegistry.parsers);
66
65
  // kind 的合法取值跟着解析器表走(含自定义类型),不再写死四个内置类型。
67
66
  const fetchSchema = JSON.parse(JSON.stringify(schemas.fetchResultSchema));
@@ -78,12 +77,12 @@ function buildSelfContainedScript() {
78
77
  if (!RAW_SCRIPT.includes(marker)) {
79
78
  throw new Error("workflow script marker not found: " + marker);
80
79
  }
81
- return 'const normalizeWorkflowOptions = ' + normalizeWorkflowOptions.toString() + ';\n' +
80
+ const runtimePaths = { transcribeScript: fs.realpathSync(path.join(__dirname, 'scripts', 'transcribe.js')) };
81
+ return 'const __runtimePaths = ' + JSON.stringify(runtimePaths) + ';\n' +
82
+ 'const normalizeWorkflowOptions = ' + normalizeWorkflowOptions.toString() + ';\n' +
82
83
  'const __quality = { checkNoteStructure: ' + quality.checkNoteStructure.toString() +
83
84
  ', validateSourceCheck: ' + quality.validateSourceCheck.toString() + ' };\n' +
84
85
  RAW_SCRIPT.replace(marker, impl + "\nconst parsers = args._parsers || __parsers;");
85
86
  }
86
87
 
87
- const script = buildSelfContainedScript();
88
-
89
- module.exports = { meta, script, parsers, buildSelfContainedScript };
88
+ module.exports = { meta, get script() { return buildSelfContainedScript(); }, parsers, buildSelfContainedScript };