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.
package/index.js CHANGED
@@ -31,12 +31,26 @@ module.exports.inject = ['skills'];
31
31
  * 支持 `config: { outputDir: ... }` 与 `config: { options: { outputDir: ... } }` 两种写法。
32
32
  */
33
33
  function normalizeOptions(config) {
34
- const raw = config && Object.prototype.hasOwnProperty.call(config, 'options') ? config.options : config;
34
+ let raw = config && Object.prototype.hasOwnProperty.call(config, 'options') ? config.options : config;
35
+ if (raw && typeof raw === 'object' && !Array.isArray(raw) && raw === config) {
36
+ raw = Object.assign({}, raw);
37
+ delete raw.customParsersDir; // plugin-only executable extension directory
38
+ }
35
39
  return normalizeWorkflowOptions(raw, { mode: 'config', warn: function (message) { console.warn(message); } });
36
40
  }
37
41
 
42
+ function configuredRegistry(config) {
43
+ if (!config || !Object.prototype.hasOwnProperty.call(config, 'customParsersDir')) return parsers.registry;
44
+ const dir = config.customParsersDir;
45
+ if (typeof dir !== 'string' || !dir.trim() || /[\u0000\r\n]/.test(dir)) {
46
+ console.warn('[deep-read-summarize] ignoring config.customParsersDir — expected a non-empty directory path');
47
+ return parsers.registry;
48
+ }
49
+ return new parsers.ParserRegistry({ customParsersDir: dir });
50
+ }
51
+
38
52
  /** 组装技能内容:SKILL.md + workflow meta/script/args 示例(script 为自包含版本)。 */
39
- function buildSkillContent(config = {}) {
53
+ function buildSkillContent(config = {}, runtime = {}) {
40
54
  const skillDir = path.join(__dirname, 'skills', 'deep-read-summarize');
41
55
  const body = readFileSync(path.join(skillDir, 'SKILL.md'), 'utf8');
42
56
  const argsExample = {
@@ -44,6 +58,12 @@ function buildSkillContent(config = {}) {
44
58
  type: 'auto',
45
59
  options: normalizeOptions(config)
46
60
  };
61
+ if (runtime.toolName) {
62
+ return [body.trim(), '', '## 调用精读工具',
63
+ '调用 `' + runtime.toolName + '`,只提交 input / type / options。工具返回完整 note 与建议 filePath;必须按上文执行同名文件询问、落盘和质量报告。',
64
+ 'args 示例(options 是本 profile 的默认值,用户另有要求时再覆盖):',
65
+ '```json', JSON.stringify(argsExample, null, 2), '```'].join('\n');
66
+ }
47
67
  return [
48
68
  body.trim(),
49
69
  '',
@@ -57,7 +77,7 @@ function buildSkillContent(config = {}) {
57
77
  '',
58
78
  'script(完整脚本,原样填入 script 参数;脚本已自包含解析器,无需宿主注入):',
59
79
  '```javascript',
60
- workflow.script,
80
+ workflow.buildSelfContainedScript(runtime.registry || configuredRegistry(config)),
61
81
  '```',
62
82
  '',
63
83
  'args 示例(options 是本 profile 的默认值,用户另有要求时再覆盖):',
@@ -67,21 +87,131 @@ function buildSkillContent(config = {}) {
67
87
  ].join('\n');
68
88
  }
69
89
 
70
- /** Cordis 插件入口:注册运行时技能,使模型可直接执行精读 workflow。 */
71
- function apply(ctx, config = {}) {
90
+ // This is the public DSH WorkflowEngine.start / ToolDefinition contract used
91
+ // by dsh-tool-workflow itself. Optional services keep older profiles working.
92
+ function optionalService(ctx, name) {
93
+ if (typeof ctx.get === 'function') return ctx.get(name);
94
+ return ctx[name];
95
+ }
96
+
97
+ function readingTool(engine, defaults, registry) {
98
+ return {
99
+ name: 'deep_read_summarize',
100
+ description: '深度精读书籍、论文、视频或网页,返回完整 Markdown 笔记、建议保存路径及原文质量核验结果。拿到结果后必须检查同名文件并保存 note;质量未通过或有内容缺口时必须报告。',
101
+ parameters: {
102
+ type: 'object', additionalProperties: false,
103
+ properties: {
104
+ input: { type: 'string', description: '内容链接或本地文件路径' },
105
+ type: { type: 'string', description: 'auto 或已注册的解析器类型,默认 auto' },
106
+ options: { type: 'object', additionalProperties: true, description: '覆盖当前 profile 的精读选项' }
107
+ }, required: ['input']
108
+ },
109
+ output: {
110
+ schema: { type: 'object', additionalProperties: true },
111
+ // Never clip the note: the main agent needs its complete value to save it.
112
+ render: function (args, value) { return [{ type: 'text', text: JSON.stringify(value) }]; }
113
+ },
114
+ async execute(args, exec) {
115
+ if (!args || typeof args !== 'object' || Array.isArray(args)) throw new Error('[FATAL] expected an input object');
116
+ if (Object.keys(args).some(function (key) { return ['input', 'type', 'options'].indexOf(key) < 0; })) throw new Error('[FATAL] unknown deep_read_summarize argument');
117
+ if (typeof args.input !== 'string' || !args.input.trim()) throw new Error('[FATAL] args.input 必须是非空字符串');
118
+ if (args.type !== undefined && typeof args.type !== 'string') throw new Error('[FATAL] args.type 必须是字符串');
119
+ if (args.options !== undefined && (!args.options || typeof args.options !== 'object' || Array.isArray(args.options))) throw new Error('[FATAL] options 必须是对象');
120
+ const options = normalizeWorkflowOptions(Object.assign({}, defaults, args.options));
121
+ if (!exec || !exec.agent) throw new Error('deep_read_summarize requires a calling agent');
122
+ if (exec.signal && exec.signal.aborted) throw new Error('deep_read_summarize was cancelled before start');
123
+ const run = engine.start({ script: workflow.buildSelfContainedScript(registry), meta: workflow.meta,
124
+ args: { input: args.input, type: args.type || 'auto', options: options }, parent: exec.agent, signal: exec.signal });
125
+ try {
126
+ const result = await run.result;
127
+ if (result.stopReason !== 'completed') throw new Error('deep_read_summarize ' + result.stopReason + ': ' + (result.error || 'workflow did not complete'));
128
+ if (!result.value || typeof result.value !== 'object' || Array.isArray(result.value)) throw new Error('deep_read_summarize returned an invalid workflow result');
129
+ return result.value;
130
+ } finally { await run.dispose(); }
131
+ }
132
+ };
133
+ }
134
+
135
+ function skillDefinition(config, runtime) {
72
136
  const skillDir = path.join(__dirname, 'skills', 'deep-read-summarize');
73
- return ctx.skills.register({
137
+ return {
74
138
  name: 'deep-read-summarize',
75
139
  description: workflow.meta.description,
76
140
  whenToUse: workflow.meta.whenToUse,
77
- content: buildSkillContent(config),
141
+ content: buildSkillContent(config, runtime),
78
142
  resourceBase: { kind: 'directory', path: skillDir },
79
- // source 是技能的「来源桶」(runtime / bundled / user-dsh …),不是自由描述:
80
- // 本技能随插件包分发,因此登记为 bundled。
81
143
  source: 'bundled'
144
+ };
145
+ }
146
+
147
+ // Cordis inject() owns a child fiber which activates/restarts as these optional
148
+ // services appear/disappear. Keep a fallback skill while that child is pending.
149
+ function applyWithServiceLifecycle(ctx, config, registry) {
150
+ let stopped = false;
151
+ let releaseSkill = ctx.skills.register(skillDefinition(config, { registry: registry }));
152
+ function replaceSkill(toolName) {
153
+ if (typeof releaseSkill === 'function') releaseSkill();
154
+ releaseSkill = undefined;
155
+ releaseSkill = ctx.skills.register(skillDefinition(config, { registry: registry, toolName: toolName }));
156
+ }
157
+ function parentCanRegister() {
158
+ // Public Cordis FiberState: LOADING=1, ACTIVE=2; never restore while unloading.
159
+ return !stopped && (!ctx.fiber || ctx.fiber.state === 1 || ctx.fiber.state === 2);
160
+ }
161
+ // Cordis treats callbacks with a prototype as constructors. An arrow keeps
162
+ // the returned cleanup function in its effect lifecycle.
163
+ const child = ctx.inject(['tools', 'workflowEngine'], (ready) => {
164
+ const tools = optionalService(ready, 'tools');
165
+ const engine = optionalService(ready, 'workflowEngine');
166
+ const releaseTool = tools.register(readingTool(engine, normalizeOptions(config), registry));
167
+ try { replaceSkill('deep_read_summarize'); }
168
+ catch (error) {
169
+ if (typeof releaseTool === 'function') releaseTool();
170
+ if (parentCanRegister()) replaceSkill();
171
+ throw error;
172
+ }
173
+ return function () {
174
+ try {
175
+ if (typeof releaseSkill === 'function') releaseSkill();
176
+ releaseSkill = undefined;
177
+ } finally {
178
+ if (typeof releaseTool === 'function') releaseTool();
179
+ if (parentCanRegister()) replaceSkill();
180
+ }
181
+ };
82
182
  });
183
+ return async function () {
184
+ stopped = true;
185
+ try { if (child && typeof child.dispose === 'function') await child.dispose(); }
186
+ finally {
187
+ if (typeof releaseSkill === 'function') releaseSkill();
188
+ releaseSkill = undefined;
189
+ }
190
+ };
83
191
  }
84
192
 
193
+ /** Cordis 插件入口:注册运行时技能,使模型可直接执行精读 workflow。 */
194
+ const apply = (ctx, config = {}) => {
195
+ const registry = configuredRegistry(config);
196
+ if (typeof ctx.inject === 'function') return applyWithServiceLifecycle(ctx, config, registry);
197
+ const tools = optionalService(ctx, 'tools');
198
+ const engine = optionalService(ctx, 'workflowEngine');
199
+ const canRunDirectly = tools && typeof tools.register === 'function' && engine && typeof engine.start === 'function';
200
+ const unregisterTool = canRunDirectly ? tools.register(readingTool(engine, normalizeOptions(config), registry)) : undefined;
201
+ let unregisterSkill;
202
+ try { unregisterSkill = ctx.skills.register(skillDefinition(config, {
203
+ registry: registry, toolName: canRunDirectly ? 'deep_read_summarize' : undefined
204
+ })); } catch (error) {
205
+ if (typeof unregisterTool === 'function') unregisterTool();
206
+ throw error;
207
+ }
208
+ if (!canRunDirectly) return unregisterSkill;
209
+ return function () {
210
+ try { if (typeof unregisterSkill === 'function') unregisterSkill(); }
211
+ finally { if (typeof unregisterTool === 'function') unregisterTool(); }
212
+ };
213
+ };
214
+
85
215
  // 兼容旧式加载(部分工具按 load() 读取插件定义)
86
216
  function load() {
87
217
  return { name: 'deep-read-summarize', workflow, parsers, schemas };
package/lib/cache.js CHANGED
@@ -17,8 +17,8 @@ const path = require("path");
17
17
  const crypto = require("crypto");
18
18
 
19
19
  /**
20
- * 规范化输入:对 http(s) URL 做归一化(host 小写、去默认端口、去 fragment、
21
- * 去空 query 的 "?"、去尾部斜杠),避免同一 URL 的不同写法产生不同指纹;
20
+ * 规范化输入:只采用 URL 标准的 host、默认端口等归一化。
21
+ * 保留尾斜杠、空 query 与 fragment:它们可能选择不同文档、路由或阅读范围。
22
22
  * 非 URL(本地路径/纯文本)原样返回。
23
23
  */
24
24
  function normalizeInput(input) {
@@ -26,19 +26,11 @@ function normalizeInput(input) {
26
26
  if (!/^https?:\/\//i.test(s)) return s;
27
27
  try {
28
28
  const url = new URL(s);
29
- url.hash = "";
30
29
  url.hostname = url.hostname.toLowerCase();
31
30
  if ((url.protocol === "http:" && url.port === "80") || (url.protocol === "https:" && url.port === "443")) {
32
31
  url.port = "";
33
32
  }
34
- if (url.pathname.length > 1 && url.pathname.endsWith("/")) {
35
- url.pathname = url.pathname.slice(0, -1);
36
- }
37
- // 去掉 URL 尾部的空 query "?"(new URL("...doc?").search 返回 "",无法靠 search 判断,
38
- // 需检查 toString() 输出;同一 URL 的 "doc" 与 "doc?" 两种写法应共享指纹)
39
- let normalized = url.toString();
40
- if (normalized.endsWith("?")) normalized = normalized.slice(0, -1);
41
- return normalized;
33
+ return url.toString();
42
34
  } catch (e) {
43
35
  return s; // 非法 URL 原样处理
44
36
  }
@@ -51,7 +43,8 @@ function fingerprint(input, fileMeta) {
51
43
  const metaStr = fileMeta
52
44
  ? "|" + (fileMeta.size ?? "") + "|" + (fileMeta.mtimeMs ?? "")
53
45
  : "";
54
- return crypto.createHash("sha256").update(base + metaStr).digest("hex").slice(0, 16);
46
+ // v2 不复用旧版过度归一化后的记录,避免旧碰撞继续导致错误跳过。
47
+ return crypto.createHash("sha256").update("drs-input-v2|" + base + metaStr).digest("hex").slice(0, 16);
55
48
  }
56
49
 
57
50
  /** 从缓存文件读取已处理记录(JSONL) */
package/lib/options.js CHANGED
@@ -6,7 +6,7 @@ function normalizeWorkflowOptions(raw, behavior) {
6
6
  minWords: 2500, fastMode: false, maxChunks: 4, transcribe: true,
7
7
  requireCitations: true, includeTimestamps: false, outputDir: './output',
8
8
  tempDir: './.tmp', whisperModel: 'small', language: 'zh', device: 'cpu',
9
- maxRetries: 0, frontmatter: 'obsidian'
9
+ maxRetries: 0, frontmatter: 'obsidian', cpuThreads: 0, transcriptCache: true
10
10
  };
11
11
  const settings = behavior || {};
12
12
  const tolerant = settings.mode === 'config';
@@ -37,9 +37,9 @@ function normalizeWorkflowOptions(raw, behavior) {
37
37
  if (!Object.prototype.hasOwnProperty.call(raw, key) || raw[key] === undefined) continue;
38
38
  let value = raw[key];
39
39
  let reason = '';
40
- if (key === 'minWords' || key === 'maxChunks' || key === 'maxRetries') {
41
- const minimum = key === 'maxRetries' ? 0 : 1;
42
- const maximum = key === 'minWords' ? 100000 : (key === 'maxRetries' ? 3 : Infinity);
40
+ if (key === 'minWords' || key === 'maxChunks' || key === 'maxRetries' || key === 'cpuThreads') {
41
+ const minimum = key === 'maxRetries' || key === 'cpuThreads' ? 0 : 1;
42
+ const maximum = key === 'cpuThreads' ? 64 : key === 'minWords' ? 100000 : (key === 'maxRetries' ? 3 : Infinity);
43
43
  if (typeof value !== 'number' || !Number.isFinite(value) || !Number.isInteger(value) || value < minimum || value > maximum) {
44
44
  reason = 'expected a finite integer in ' + minimum + '..' + (maximum === Infinity ? '12 (larger values are capped)' : maximum);
45
45
  } else if (key === 'maxChunks' && value > 12) {
@@ -34,6 +34,16 @@ function analyze(source, filename) {
34
34
  else if (pattern.type === 'ObjectPattern') pattern.properties.forEach(item => bind(item.type === 'RestElement' ? item.argument : item.value, target));
35
35
  }
36
36
  function collect(node, active, parent, key) {
37
+ if (node.type === 'SwitchStatement') {
38
+ // The discriminant is evaluated before entering the case block's lexical
39
+ // environment. A case-local `require` must not hide an outer import here.
40
+ scopes.set(node, active);
41
+ nodes.push({ node, parent, key });
42
+ collect(node.discriminant, active, node, 'discriminant');
43
+ const cases = scope(active, 'block');
44
+ node.cases.forEach(item => collect(item, cases, node, 'cases'));
45
+ return;
46
+ }
37
47
  if (/^Function/.test(node.type) || node.type === 'ArrowFunctionExpression') {
38
48
  if (node.type === 'FunctionDeclaration') bind(node.id, active);
39
49
  const parameters = scope(active, 'parameters');
@@ -49,7 +59,7 @@ function analyze(source, filename) {
49
59
  if (node.type === 'ClassDeclaration') bind(node.id, active);
50
60
  if (node.type === 'ClassDeclaration' || node.type === 'ClassExpression') {
51
61
  active = scope(active, 'block'); bind(node.id, active);
52
- } else if (['BlockStatement', 'CatchClause', 'ForStatement', 'ForInStatement', 'ForOfStatement', 'SwitchStatement'].indexOf(node.type) >= 0) {
62
+ } else if (['BlockStatement', 'CatchClause', 'ForStatement', 'ForInStatement', 'ForOfStatement'].indexOf(node.type) >= 0) {
53
63
  active = scope(active, 'block');
54
64
  } else if (node.type === 'StaticBlock') active = scope(active, 'function');
55
65
  if (node.type === 'CatchClause') bind(node.param, active);
package/lib/quality.js CHANGED
@@ -12,6 +12,7 @@ function checkNoteStructure(note, options) {
12
12
  const front = text.match(/^---[ \t]*\n([\s\S]*?)\n---[ \t]*(?:\n|$)/);
13
13
  function scalar(raw) {
14
14
  const value = raw.trim();
15
+ if (!value || /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(value)) throw new Error('missing or invalid scalar');
15
16
  if (value[0] === '"') {
16
17
  const parsed = JSON.parse(value);
17
18
  if (typeof parsed !== 'string') throw new Error('expected string');
@@ -41,8 +42,12 @@ function checkNoteStructure(note, options) {
41
42
  if (token.trim()) tokens.push(scalar(token));
42
43
  return tokens;
43
44
  }
44
- if (/[:][ \t]|[\[\]{}]|^[!&*|>]/.test(value)) throw new Error('invalid template scalar');
45
- return value.replace(/[ \t]+#.*$/, '').trim();
45
+ if (/:(?:[ \t]|$)|[\[\]{},]|^[!&*|>@`%#]|^[-?:](?:[ \t]|$)/.test(value)) throw new Error('invalid template scalar');
46
+ const plain = value.replace(/[ \t]+#.*$/, '').trim();
47
+ // Template values are strings. YAML null/booleans/numbers must stay quoted
48
+ // instead of silently passing as a different native YAML type.
49
+ if (/^(?:null|~|true|false|[-+]?(?:0o[0-7]+|0x[0-9a-f]+|[0-9]+(?:\.[0-9]*)?(?:e[-+]?[0-9]+)?|\.[0-9]+(?:e[-+]?[0-9]+)?|\.inf)|\.nan)$/i.test(plain)) throw new Error('template strings must be quoted');
50
+ return plain;
46
51
  }
47
52
  function fields(lines) {
48
53
  const values = Object.create(null);
@@ -110,6 +115,14 @@ function checkNoteStructure(note, options) {
110
115
  const lengthMet = wordCount >= opts.minWords;
111
116
  if (!lengthMet) issues.push('正文篇幅不足:计数 ' + wordCount + ',要求至少 ' + opts.minWords + '(不计 frontmatter、代码块和链接地址)');
112
117
  const quotes = [];
118
+ function inlineText(value) {
119
+ // Normalize display syntax only. Source evidence below remains literal so
120
+ // emphasis cannot make an invented quote match a different source phrase.
121
+ return value.replace(/!?\[([^\]\n]+)\]\([^\n)]*\)/g, '$1')
122
+ .replace(/(\*\*|__)(?=\S)([\s\S]*?\S)\1/g, '$2')
123
+ .replace(/(^|[^\w\\])([*_])(?=\S)([^\n]*?\S)\2/g, '$1$3')
124
+ .replace(/(`+)([^`\n]+)\1/g, '$2');
125
+ }
113
126
  const quoteStart = prose.findIndex(line => /^##[ \t]+4(?:[.、.][ \t]*|[ \t]+)\S/.test(line));
114
127
  if (quoteStart !== -1) {
115
128
  const quoteLines = [];
@@ -124,16 +137,19 @@ function checkNoteStructure(note, options) {
124
137
  let match, explicit = false;
125
138
  while ((match = expression.exec(line))) {
126
139
  explicit = true;
127
- const quote = (match[1] || match[2] || match[3]).trim();
140
+ const quote = inlineText(match[1] || match[2] || match[3]).trim();
128
141
  if (quote && quotes.indexOf(quote) === -1) quotes.push(quote);
129
142
  }
130
143
  if (!explicit && /^>[ \t]+/.test(line)) {
131
- const quote = line.replace(/^(?:>[ \t]*)+/, '').trim();
144
+ // A trailing, explicitly labelled locator belongs to the citation,
145
+ // not to the sentence. Do not remove arbitrary parenthetical prose.
146
+ const quote = inlineText(line.replace(/^(?:>[ \t]*)+/, ''))
147
+ .replace(/[ \t]*[((](?:第[ \t]*\d+[ \t]*(?:[-–][ \t]*\d+[ \t]*)?(?:行|页|章|节|段)|(?:lines?|pages?|chapter|section)[ \t]+\d+(?:[ \t]*[-–][ \t]*\d+)?|\d{1,2}:\d{2}(?::\d{2})?(?:\.\d+)?)[))][ \t]*$/i, '').trim();
132
148
  if (quote && quotes.indexOf(quote) === -1) quotes.push(quote);
133
149
  }
134
150
  }
135
151
  }
136
- return { formatComplete: frontmatterValid && sectionsComplete, lengthMet, wordCount, quotes, visibleText: proseText, issues };
152
+ return { formatComplete: frontmatterValid && sectionsComplete, lengthMet, wordCount, quotes, visibleText: inlineText(proseText), issues };
137
153
  }
138
154
 
139
155
  function validateSourceCheck(check, context) {
@@ -165,6 +181,10 @@ function validateSourceCheck(check, context) {
165
181
  if (ctx.coverageComplete !== true) {
166
182
  results.coverage = false; issues.push('获取结果缺少有效 totalLines,无法确认原文尾部是否完整覆盖');
167
183
  }
184
+ if (ctx.sourceComplete === false) {
185
+ results.coverage = false;
186
+ issues.push('来源不完整:' + (ctx.textSource === 'desc' ? '仅有视频简介,不能代替完整字幕或逐字稿' : '视频来源未经确认为完整字幕或逐字稿'));
187
+ }
168
188
  if (ctx.failedChunkIds && ctx.failedChunkIds.length) {
169
189
  results.coverage = false; issues.push('精读仍有缺口,失败块:' + ctx.failedChunkIds.join(', '));
170
190
  }
@@ -0,0 +1,173 @@
1
+ 'use strict';
2
+
3
+ const fs = require('node:fs');
4
+ const path = require('node:path');
5
+ const crypto = require('node:crypto');
6
+
7
+ const VERSION = 1;
8
+ const MAX_ENTRY_BYTES = 8 * 1024 * 1024;
9
+ const MAX_CACHE_BYTES = 128 * 1024 * 1024;
10
+ const MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
11
+ const entryName = /^[a-f0-9]{64}\.json$/;
12
+ function digest(value) { return crypto.createHash('sha256').update(value).digest('hex'); }
13
+ function directory(root) { return path.join(root, 'transcripts-v1'); }
14
+
15
+ function hashFile(file) {
16
+ const hash = crypto.createHash('sha256');
17
+ const fd = fs.openSync(file, 'r');
18
+ try {
19
+ const buffer = Buffer.alloc(1024 * 1024);
20
+ let count;
21
+ while ((count = fs.readSync(fd, buffer, 0, buffer.length, null)) > 0) hash.update(buffer.subarray(0, count));
22
+ } finally { fs.closeSync(fd); }
23
+ return hash.digest('hex');
24
+ }
25
+
26
+ // Cache only managed HF snapshots with a locally identifiable environment.
27
+ // Any installed package or model snapshot change invalidates the identity.
28
+ // Local/custom model directories deliberately bypass this cache.
29
+ function runtimeIdentity(root, model) {
30
+ try {
31
+ if (!/^[a-z0-9.-]+$/i.test(model) || fs.existsSync(model)) return null;
32
+ const venv = path.join(root, 'venv');
33
+ const sites = [path.join(venv, 'Lib', 'site-packages')];
34
+ const lib = path.join(venv, 'lib');
35
+ if (fs.existsSync(lib)) {
36
+ for (const name of fs.readdirSync(lib)) {
37
+ if (/^python\d+\.\d+$/.test(name)) sites.push(path.join(lib, name, 'site-packages'));
38
+ }
39
+ }
40
+ const packages = sites.filter(p => fs.existsSync(p)).flatMap(p => fs.readdirSync(p).filter(n => n.endsWith('.dist-info'))).sort();
41
+ if (!packages.some(n => /^faster_whisper-1\.2\.1\.dist-info$/.test(n)) ||
42
+ !packages.some(n => /^ctranslate2-/.test(n))) return null;
43
+ const hub = path.join(root, 'hf', 'hub');
44
+ const canonicalHub = fs.realpathSync(hub);
45
+ const manifest = [];
46
+ let binaries = 0;
47
+ function visit(dir, prefix, depth) {
48
+ if (depth > 5 || manifest.length > 4096) throw new Error('model manifest exceeds limits');
49
+ for (const name of fs.readdirSync(dir).sort()) {
50
+ if (manifest.length >= 4096) throw new Error('model manifest exceeds limits');
51
+ const file = path.join(dir, name);
52
+ const relative = prefix + '/' + name;
53
+ const link = fs.lstatSync(file);
54
+ if (link.isDirectory()) visit(file, relative, depth + 1);
55
+ else {
56
+ const real = fs.realpathSync(file);
57
+ const inside = path.relative(canonicalHub, real);
58
+ if (inside.startsWith('..') || path.isAbsolute(inside)) throw new Error('model file outside managed cache');
59
+ const stat = fs.statSync(file);
60
+ if (!stat.isFile()) throw new Error('non-file model artifact');
61
+ if (name === 'model.bin') binaries++;
62
+ manifest.push([relative, stat.size, stat.mtimeMs,
63
+ prefix.includes('/refs') ? fs.readFileSync(file, 'utf8') : '']);
64
+ }
65
+ }
66
+ }
67
+ for (const repo of fs.readdirSync(hub).filter(n => n.startsWith('models--')).sort()) {
68
+ for (const section of ['refs', 'snapshots']) {
69
+ const dir = path.join(hub, repo, section);
70
+ if (fs.existsSync(dir)) visit(dir, repo + '/' + section, 0);
71
+ }
72
+ }
73
+ if (!binaries) return null;
74
+ const pythonConfig = path.join(venv, 'pyvenv.cfg');
75
+ return digest(JSON.stringify({ packages, manifest,
76
+ python: fs.existsSync(pythonConfig) ? fs.readFileSync(pythonConfig, 'utf8') : '' }));
77
+ } catch (error) { return null; }
78
+ }
79
+
80
+ function identity(audioHash, args, runtime, runner) {
81
+ if (!runtime) return null;
82
+ // Timestamp presentation is excluded: canonical segments retain both times.
83
+ const config = { version: VERSION, audioHash, runtime, model: args.model,
84
+ language: args.language, device: args.device, cpuThreads: args.cpuThreads,
85
+ fasterWhisper: '1.2.1', computeType: 'int8', beamSize: 5, bestOf: 5,
86
+ vadFilter: true, conditionOnPreviousText: true,
87
+ temperature: [0, 0.2, 0.4, 0.6, 0.8, 1], pipeline: 'standard-v1', runner: digest(runner || '') };
88
+ return { key: digest(JSON.stringify(config)), config };
89
+ }
90
+
91
+ function validSegments(segments) {
92
+ return Array.isArray(segments) && segments.length > 0 && segments.every(s =>
93
+ s && typeof s.text === 'string' && s.text.trim() && !/[\u0000\r\n]/.test(s.text) &&
94
+ Number.isFinite(s.start) && Number.isFinite(s.end) && s.start >= 0 && s.end >= s.start);
95
+ }
96
+
97
+ function timestamp(seconds) {
98
+ // Match Python round() (ties to even) used by the existing runner.
99
+ const value = Math.max(0, seconds * 1000);
100
+ const floor = Math.floor(value);
101
+ let millis = value - floor === 0.5 ? floor + (floor % 2) : Math.round(value);
102
+ const hours = Math.floor(millis / 3600000); millis %= 3600000;
103
+ const minutes = Math.floor(millis / 60000); millis %= 60000;
104
+ const whole = Math.floor(millis / 1000); millis %= 1000;
105
+ return String(hours).padStart(2, '0') + ':' + String(minutes).padStart(2, '0') + ':' +
106
+ String(whole).padStart(2, '0') + '.' + String(millis).padStart(3, '0');
107
+ }
108
+ function render(segments, timestamps) {
109
+ return segments.map(s => (timestamps ? '[' + timestamp(s.start) + ' --> ' + timestamp(s.end) + '] ' : '') + s.text).join('\n');
110
+ }
111
+
112
+ function read(root, id) {
113
+ if (!id) return null;
114
+ try {
115
+ const file = path.join(directory(root), id.key + '.json');
116
+ const stat = fs.lstatSync(file);
117
+ if (!stat.isFile() || stat.size > MAX_ENTRY_BYTES) return null;
118
+ const entry = JSON.parse(fs.readFileSync(file, 'utf8'));
119
+ if (entry.version !== VERSION || entry.key !== id.key ||
120
+ JSON.stringify(entry.config) !== JSON.stringify(id.config) ||
121
+ !Number.isFinite(entry.createdAt) || entry.createdAt > Date.now() || Date.now() - entry.createdAt > MAX_AGE_MS ||
122
+ !entry.report || !validSegments(entry.report.segments) ||
123
+ entry.checksum !== digest(JSON.stringify(entry.report))) return null;
124
+ try { fs.utimesSync(file, new Date(), new Date()); } catch (error) { /* best effort LRU */ }
125
+ return entry.report;
126
+ } catch (error) { return null; }
127
+ }
128
+
129
+ function prune(root, limit = MAX_CACHE_BYTES) {
130
+ const dir = directory(root);
131
+ if (!fs.existsSync(dir)) return;
132
+ const files = fs.readdirSync(dir).filter(n => entryName.test(n)).flatMap(name => {
133
+ try {
134
+ const file = path.join(dir, name), stat = fs.lstatSync(file);
135
+ return stat.isFile() ? [{ file, size: stat.size, modified: stat.mtimeMs }] : [];
136
+ } catch (error) { return []; }
137
+ }).sort((a, b) => b.modified - a.modified);
138
+ let size = 0;
139
+ for (const file of files) {
140
+ if (size + file.size > limit || Date.now() - file.modified > MAX_AGE_MS) fs.unlinkSync(file.file);
141
+ else size += file.size;
142
+ }
143
+ }
144
+
145
+ function write(root, id, report) {
146
+ if (!id || !report || !validSegments(report.segments)) return false;
147
+ let temporary;
148
+ try {
149
+ const data = JSON.stringify({ version: VERSION, key: id.key, config: id.config,
150
+ createdAt: Date.now(), report, checksum: digest(JSON.stringify(report)) });
151
+ if (Buffer.byteLength(data) > MAX_ENTRY_BYTES) return false;
152
+ const dir = directory(root);
153
+ fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
154
+ temporary = path.join(dir, '.write-' + crypto.randomBytes(16).toString('hex'));
155
+ fs.writeFileSync(temporary, data, { flag: 'wx', mode: 0o600 });
156
+ fs.renameSync(temporary, path.join(dir, id.key + '.json'));
157
+ prune(root);
158
+ return true;
159
+ } catch (error) { return false; }
160
+ finally { if (temporary) { try { fs.unlinkSync(temporary); } catch (error) { /* already renamed */ } } }
161
+ }
162
+
163
+ // Delete only this module's strictly named entries; never recurse or touch models.
164
+ function clear(root) {
165
+ const dir = directory(root);
166
+ if (!fs.existsSync(dir)) return;
167
+ for (const name of fs.readdirSync(dir).filter(n => entryName.test(n))) {
168
+ const file = path.join(dir, name);
169
+ if (fs.lstatSync(file).isFile()) fs.unlinkSync(file);
170
+ }
171
+ }
172
+
173
+ module.exports = { hashFile, runtimeIdentity, identity, validSegments, render, read, write, clear, prune, directory };