@hyprnos/dsh-remote-plugin 0.8.8 → 0.8.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.
@@ -0,0 +1,705 @@
1
+ /* dsh-remote · 内置本地 Whisper 语音识别 provider
2
+ *
3
+ * 给 DSH 主机增加第二个可选的转写模型(providerId: whisper-local),手机端语音输入
4
+ * 的 catalog 里会与官方 SenseVoiceSmall 一起出现,中英混说时英文短词(Server Logs、
5
+ * Config 等)识别更稳。
6
+ *
7
+ * 设计约束(与官方 dsh-experimental-speech-to-text-sensevoice 的登记契约保持一致):
8
+ * - 只依赖 node: 内置模块,零新增依赖;模型不进 npm 包,首次使用时流式下载并校验。
9
+ * - 通过 cordis 动态注入登记到 ctx.speechToText:主机没启用官方语音 bundle 时本模块
10
+ * 完全不参与加载,插件不会因为缺少服务而启动失败(见 registerWhisperProvider)。
11
+ * - preparation 状态机、steps、下载失败诊断的形状对齐官方 SpeechPreparationState /
12
+ * SpeechProviderInfo / Transcript,手机端 UI 无需为 Whisper 做特判。
13
+ * - 推理走本机 whisper.cpp 的 whisper-cli,一次一个进程:串行队列、可取消、有超时。
14
+ */
15
+ import { spawn } from 'node:child_process'
16
+ import { createHash, randomUUID } from 'node:crypto'
17
+ import {
18
+ accessSync, constants as fsConstants, createReadStream, createWriteStream, statSync,
19
+ } from 'node:fs'
20
+ import { mkdir, mkdtemp, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'
21
+ import { homedir, tmpdir } from 'node:os'
22
+ import { delimiter, dirname, join } from 'node:path'
23
+ import { Readable, Transform } from 'node:stream'
24
+ import { pipeline } from 'node:stream/promises'
25
+
26
+ /** 官方 whisper.cpp 发布的 ggml 模型(q5_0 量化 large-v3-turbo)。 */
27
+ const DEFAULT_MODEL = {
28
+ name: 'ggml-large-v3-turbo-q5_0.bin',
29
+ bytes: 574041195,
30
+ sha256: '394221709cd5ad1f40c46e6031ca61bce88931e6e088c188294c6d5a55ffa7e2',
31
+ }
32
+ /** huggingface 与镜像使用同一路径(offline deployments 可换成自建镜像);两者都可用时优先官方源。 */
33
+ const MODEL_REMOTE_PREFIX = '/ggerganov/whisper.cpp/resolve/main/'
34
+ const DEFAULT_DOWNLOAD_SOURCES = ['https://huggingface.co', 'https://hf-mirror.com']
35
+ /** whisper.cpp 接受的语言代码子集(与官方 voice-input 的选项保持接近,避免 UI 列出无效项)。 */
36
+ const DEFAULT_LANGUAGES = ['auto', 'zh', 'en', 'yue', 'ja', 'ko', 'es', 'fr', 'de', 'ru', 'pt', 'it']
37
+ /** 准备流程的操作顺序:查组件 → 模型 → 校验 → 加载探测。 */
38
+ const STEP_KINDS = ['check', 'model', 'verify', 'load']
39
+ const TERMINAL_PHASES = new Set(['ready', 'failed', 'cancelled', 'unprepared'])
40
+ const MAX_PENDING_JOBS = 2
41
+ const INFERENCE_TIMEOUT_MS = 180_000
42
+ const PREPARE_TIMEOUT_MS = 3_600_000
43
+ const PROBE_TIMEOUT_MS = 20_000
44
+ const PROGRESS_INTERVAL_MS = 100
45
+ const MAX_LOG_BYTES = 8 * 1024
46
+
47
+ /** 请求本身不合法(WAV 头/语言),与运行期失败区分开。 */
48
+ class SpeechInputError extends Error {}
49
+
50
+ /** 下载/校验失败,附带可直接给 UI 本地化用的结构化诊断。 */
51
+ class SpeechDownloadError extends Error {
52
+ constructor(download, options) {
53
+ super(describeDownloadFailure(download), options)
54
+ this.name = 'SpeechDownloadError'
55
+ this.download = download
56
+ }
57
+ }
58
+
59
+ function describeDownloadFailure({ resource, source, reason, status }) {
60
+ const labels = {
61
+ network: '网络连接失败',
62
+ dns: '域名解析失败',
63
+ timeout: '下载超时',
64
+ certificate: '证书校验失败',
65
+ http: '下载源返回错误',
66
+ integrity: '模型文件校验失败(字节数或 sha256 不符)',
67
+ storage: '本地磁盘写入失败',
68
+ unknown: '下载失败',
69
+ }
70
+ const http = status === undefined ? '' : `(HTTP ${status})`
71
+ return `Whisper 模型准备失败:${labels[reason] ?? labels.unknown}${http};来源 ${source},资源 ${resource}。请检查网络后重试。`
72
+ }
73
+
74
+ function whisperMissingMessage(configured) {
75
+ const found = configured
76
+ ? `已设置 DSH_REMOTE_WHISPER_BIN=${configured},但该路径不是可执行文件。`
77
+ : '未在 PATH 中找到 whisper-cli。'
78
+ return `本机语音识别组件不可用:${found}请安装 whisper.cpp(macOS: brew install whisper-cpp),或设置环境变量 DSH_REMOTE_WHISPER_BIN 指向 whisper-cli,然后重启 DSH。`
79
+ }
80
+
81
+ function abortError(signal) {
82
+ const reason = signal?.reason
83
+ if (reason instanceof Error) return reason
84
+ const error = new Error('语音任务已取消')
85
+ error.name = 'AbortError'
86
+ return error
87
+ }
88
+
89
+ function throwIfAborted(signal) {
90
+ if (signal?.aborted) throw abortError(signal)
91
+ }
92
+
93
+ /** 组合调用方取消信号与服务生命周期信号;AbortSignal.any 不可用时手工合并。 */
94
+ function mergeSignals(signals) {
95
+ const list = signals.filter(Boolean)
96
+ if (list.length === 0) return new AbortController().signal
97
+ if (list.length === 1) return list[0]
98
+ if (typeof AbortSignal.any === 'function') return AbortSignal.any(list)
99
+ const controller = new AbortController()
100
+ const abort = () => controller.abort(list.find(signal => signal.aborted)?.reason)
101
+ for (const signal of list) {
102
+ if (signal.aborted) { abort(); break }
103
+ signal.addEventListener('abort', abort, { once: true })
104
+ }
105
+ return controller.signal
106
+ }
107
+
108
+ function originOf(value) {
109
+ try { return new URL(value).origin } catch { return undefined }
110
+ }
111
+
112
+ function classifyDownloadFailure(error) {
113
+ const code = error?.code ?? error?.cause?.code
114
+ const name = String(error?.name ?? '')
115
+ if (code === 'ETIMEDOUT' || name === 'TimeoutError') return 'timeout'
116
+ if (code === 'ENOTFOUND' || code === 'EAI_AGAIN') return 'dns'
117
+ if (code === 'ENOSPC' || code === 'EACCES' || code === 'EROFS' || code === 'EMFILE' || code === 'ENOTDIR') return 'storage'
118
+ if (typeof code === 'string' && /CERT|SELF_SIGNED|UNABLE_TO_VERIFY/i.test(code)) return 'certificate'
119
+ if (code === 'ECONNREFUSED' || code === 'ECONNRESET' || code === 'ENETUNREACH' || code === 'EPIPE') return 'network'
120
+ if (name === 'TypeError' && /fetch failed/i.test(String(error?.message ?? ''))) return 'network'
121
+ return 'unknown'
122
+ }
123
+
124
+ function responseBodyStream(body) {
125
+ // undici/Node 18+ 的 Response.body 是 web ReadableStream;pipeline 需要 Node 流。
126
+ if (typeof body?.getReader === 'function') return Readable.fromWeb(body)
127
+ return body
128
+ }
129
+
130
+ function isExecutableFile(path, platform) {
131
+ try {
132
+ if (!statSync(path).isFile()) return false
133
+ if (platform !== 'win32') accessSync(path, fsConstants.X_OK)
134
+ return true
135
+ } catch { return false }
136
+ }
137
+
138
+ /** DSH_REMOTE_WHISPER_BIN 优先,否则在 PATH 里找 whisper-cli。 */
139
+ function resolveWhisperBinary({ configured, pathEnv, platform }) {
140
+ if (configured) return isExecutableFile(configured, platform) ? configured : undefined
141
+ const names = platform === 'win32' ? ['whisper-cli.exe', 'whisper-cli'] : ['whisper-cli']
142
+ for (const entry of String(pathEnv ?? '').split(delimiter)) {
143
+ if (!entry) continue
144
+ for (const name of names) {
145
+ const candidate = join(entry, name)
146
+ if (isExecutableFile(candidate, platform)) return candidate
147
+ }
148
+ }
149
+ return undefined
150
+ }
151
+
152
+ /** 语言提示透传服务端校验过的代码;'zh-CN' 这类区域标记按主语言处理。 */
153
+ function normalizeLanguage(language) {
154
+ const raw = String(language ?? '').trim().toLowerCase()
155
+ if (!raw || raw === 'auto') return 'auto'
156
+ const base = raw.split(/[-_]/)[0]
157
+ if (DEFAULT_LANGUAGES.includes(base)) return base
158
+ return /^[a-z]{2,3}$/.test(base) ? base : 'auto'
159
+ }
160
+
161
+ /**
162
+ * 校验手机端上传的完整 WAV(16 kHz 单声道 PCM16),返回时长。
163
+ * 只读头与 data 长度,不做转码;上游已校验时这层是最后一道防线。
164
+ */
165
+ function readWaveSeconds(audio) {
166
+ if (!(audio instanceof Uint8Array) || audio.byteLength < 44) {
167
+ throw new SpeechInputError('音频必须是 16 kHz 单声道 PCM16 WAV 录音')
168
+ }
169
+ const data = Buffer.from(audio.buffer, audio.byteOffset, audio.byteLength)
170
+ if (data.toString('ascii', 0, 4) !== 'RIFF' || data.toString('ascii', 8, 12) !== 'WAVE') {
171
+ throw new SpeechInputError('音频必须是 16 kHz 单声道 PCM16 WAV 录音')
172
+ }
173
+ let format
174
+ let dataBytes
175
+ let offset = 12
176
+ while (offset + 8 <= data.length) {
177
+ const id = data.toString('ascii', offset, offset + 4)
178
+ const size = data.readUInt32LE(offset + 4)
179
+ const body = offset + 8
180
+ if (id === 'fmt ') {
181
+ if (body + 16 > data.length) break
182
+ format = {
183
+ encoding: data.readUInt16LE(body),
184
+ channels: data.readUInt16LE(body + 2),
185
+ sampleRate: data.readUInt32LE(body + 4),
186
+ bits: data.readUInt16LE(body + 14),
187
+ }
188
+ } else if (id === 'data') {
189
+ dataBytes = Math.min(size, data.length - body)
190
+ break
191
+ }
192
+ offset = body + size + (size % 2)
193
+ }
194
+ if (!format || dataBytes === undefined) {
195
+ throw new SpeechInputError('音频必须是 16 kHz 单声道 PCM16 WAV 录音')
196
+ }
197
+ if (format.encoding !== 1 || format.channels !== 1 || format.sampleRate !== 16000 || format.bits !== 16) {
198
+ throw new SpeechInputError('音频必须是 16 kHz 单声道 PCM16 WAV 录音')
199
+ }
200
+ return dataBytes / 32000
201
+ }
202
+
203
+ /** 中日韩字符(含全角标点):拼段时不在中文边界插入空格。 */
204
+ const CJK_EDGE = /[\u3000-\u303f\u3040-\u30ff\u3400-\u4dbf\u4e00-\u9fff\uff00-\uffef]/
205
+
206
+ /** whisper-cli 的 -otxt 输出按段分行;丢掉空行/静音占位后拼成一段,方便直接插入输入框。 */
207
+ function normalizeTranscript(raw) {
208
+ const lines = String(raw)
209
+ .split(/\r?\n/)
210
+ .map(line => line.replace(/\s+/g, ' ').trim())
211
+ .filter(line => line && !/^\[blank_audio\]$/i.test(line))
212
+ let text = ''
213
+ for (const line of lines) {
214
+ if (!text) { text = line; continue }
215
+ const boundary = CJK_EDGE.test(text.slice(-1)) || CJK_EDGE.test(line.slice(0, 1))
216
+ text += (boundary ? '' : ' ') + line
217
+ }
218
+ return text
219
+ }
220
+
221
+ /**
222
+ * 运行一次 whisper-cli 子进程;取消时 SIGKILL,超时同样杀掉并给出中文原因。
223
+ * @returns stderr 文本(截断),退出码非 0 或取消时 reject。
224
+ */
225
+ function runCommand(binary, args, { signal, timeoutMs, timeoutMessage = 'whisper-cli 执行超时' } = {}) {
226
+ return new Promise((resolve, reject) => {
227
+ if (signal?.aborted) { reject(abortError(signal)); return }
228
+ let child
229
+ try {
230
+ child = spawn(binary, args, { stdio: ['ignore', 'ignore', 'pipe'], windowsHide: true })
231
+ } catch (error) {
232
+ reject(new Error(`无法启动 whisper-cli:${error.message}`))
233
+ return
234
+ }
235
+ let stderr = ''
236
+ let settled = false
237
+ let timedOut = false
238
+ const kill = () => { try { child.kill('SIGKILL') } catch {} }
239
+ const timer = timeoutMs ? setTimeout(() => { timedOut = true; kill() }, timeoutMs) : undefined
240
+ timer?.unref?.()
241
+ const onAbort = () => kill()
242
+ const cleanup = () => {
243
+ if (timer) clearTimeout(timer)
244
+ signal?.removeEventListener?.('abort', onAbort)
245
+ }
246
+ signal?.addEventListener?.('abort', onAbort, { once: true })
247
+ child.stderr?.setEncoding?.('utf8')
248
+ child.stderr?.on('data', chunk => { if (stderr.length < MAX_LOG_BYTES) stderr += chunk })
249
+ child.once('error', error => {
250
+ if (settled) return
251
+ settled = true
252
+ cleanup()
253
+ reject(error.code === 'ENOENT' ? new Error(whisperMissingMessage(binary)) : new Error(`无法启动 whisper-cli:${error.message}`))
254
+ })
255
+ child.once('close', (code, closeSignal) => {
256
+ if (settled) return
257
+ settled = true
258
+ cleanup()
259
+ if (signal?.aborted) { reject(abortError(signal)); return }
260
+ if (timedOut) { reject(new Error(timeoutMessage)); return }
261
+ if (code === 0) { resolve(stderr); return }
262
+ const tail = stderr.trim().slice(-500)
263
+ reject(new Error(`whisper-cli 执行失败(退出码 ${code ?? closeSignal})${tail ? `:${tail}` : ''}`))
264
+ })
265
+ })
266
+ }
267
+
268
+ /** 准备步骤的初始形态:check 正在跑,其余等待;重试/取消后重置,避免残留上一次的失败标记。 */
269
+ function initialSteps() {
270
+ return STEP_KINDS.map(kind => (kind === 'check'
271
+ ? { kind, status: 'running', startedAt: Date.now() }
272
+ : { kind, status: 'pending' }))
273
+ }
274
+
275
+ function defaultDataRoot(env = process.env) {
276
+ const home = env.DSH_HOME || join(homedir(), '.dsh')
277
+ return join(home, 'speech-to-text', 'whisper')
278
+ }
279
+
280
+ /**
281
+ * 创建本地 Whisper provider(纯工厂,不注册、不联网、不读盘)。
282
+ * @param options 可覆盖 providerId/dataRoot/model/whisperBin/fetch 等,主要供测试注入。
283
+ */
284
+ export function createWhisperProvider(options = {}) {
285
+ return new WhisperProvider(options)
286
+ }
287
+
288
+ class WhisperProvider {
289
+ constructor(options = {}) {
290
+ this.config = {
291
+ providerId: options.providerId || 'whisper-local',
292
+ name: options.name || 'Whisper (local)',
293
+ languages: [...(options.languages || DEFAULT_LANGUAGES)],
294
+ dataRoot: options.dataRoot || defaultDataRoot(),
295
+ model: { ...DEFAULT_MODEL, ...(options.model || {}) },
296
+ downloadSources: [...(options.downloadSources || DEFAULT_DOWNLOAD_SOURCES)],
297
+ binary: options.whisperBin ?? process.env.DSH_REMOTE_WHISPER_BIN ?? '',
298
+ pathEnv: options.pathEnv ?? process.env.PATH ?? '',
299
+ platform: options.platform ?? process.platform,
300
+ fetch: options.fetch ?? globalThis.fetch,
301
+ inferenceTimeoutMs: options.inferenceTimeoutMs ?? INFERENCE_TIMEOUT_MS,
302
+ prepareTimeoutMs: options.prepareTimeoutMs ?? PREPARE_TIMEOUT_MS,
303
+ probeTimeoutMs: options.probeTimeoutMs ?? PROBE_TIMEOUT_MS,
304
+ progressIntervalMs: options.progressIntervalMs ?? PROGRESS_INTERVAL_MS,
305
+ maxPending: options.maxPending ?? MAX_PENDING_JOBS,
306
+ tmpDir: options.tmpDir,
307
+ }
308
+ this.info = Object.freeze({
309
+ id: this.config.providerId,
310
+ name: this.config.name,
311
+ location: 'host-local',
312
+ languages: Object.freeze([...this.config.languages]),
313
+ downloadSources: Object.freeze([...this.config.downloadSources]),
314
+ setupEstimate: Object.freeze({
315
+ recommendedDiskBytes: this.config.model.bytes,
316
+ expectedMemoryBytes: Math.ceil(this.config.model.bytes * 2),
317
+ minimumMinutes: 2,
318
+ maximumMinutes: 20,
319
+ }),
320
+ })
321
+ this.state = {
322
+ phase: 'unprepared',
323
+ steps: STEP_KINDS.map(kind => ({ kind, status: 'pending' })),
324
+ }
325
+ this.listeners = new Set()
326
+ this.lifetime = new AbortController()
327
+ this.tail = Promise.resolve()
328
+ this.pending = 0
329
+ this.preparing = undefined
330
+ this.lastProgressAt = 0
331
+ this.disposed = false
332
+ // 官方 provider 把 worker 直接当 preparation 用;这里显式绑定方法,避免调用方解构后丢 this。
333
+ this.preparation = Object.freeze({
334
+ snapshot: () => this.snapshot(),
335
+ subscribe: listener => this.subscribe(listener),
336
+ prepare: prepareOptions => this.prepare(prepareOptions),
337
+ cancel: () => this.cancel(),
338
+ inspect: () => this.inspect(),
339
+ })
340
+ }
341
+
342
+ /** 模型落盘位置(诊断与测试用)。 */
343
+ modelPath() {
344
+ return join(this.config.dataRoot, 'models', this.config.model.name)
345
+ }
346
+
347
+ snapshot() {
348
+ return this.state
349
+ }
350
+
351
+ subscribe(listener) {
352
+ if (typeof listener !== 'function') return () => {}
353
+ this.listeners.add(listener)
354
+ return () => { this.listeners.delete(listener) }
355
+ }
356
+
357
+ /** 发布准备状态;steps 按官方状态机推进,下载进度按进度间隔合并通知。 */
358
+ publish(next) {
359
+ if (this.preparing && TERMINAL_PHASES.has(next.phase)) this.preparing.completed = true
360
+ const previous = this.state
361
+ const steps = next.steps ?? previous.steps.map(item => {
362
+ if (next.phase === 'ready') return { ...item, status: 'complete' }
363
+ if (next.step === 'check' && item.kind !== 'check') return { kind: item.kind, status: 'pending' }
364
+ if (next.step === item.kind) {
365
+ return item.status === 'running' ? item : { kind: item.kind, status: 'running', startedAt: Date.now() }
366
+ }
367
+ if (item.status !== 'running') return item
368
+ if (next.phase === 'failed') return { ...item, status: 'failed' }
369
+ if (next.phase === 'cancelled') return { ...item, status: 'cancelled' }
370
+ return next.step === undefined ? item : { ...item, status: 'complete' }
371
+ })
372
+ this.state = { ...next, steps }
373
+ const now = Date.now()
374
+ if (next.phase === 'downloading' && previous.phase === 'downloading'
375
+ && next.resource === previous.resource && next.completedBytes !== next.totalBytes
376
+ && now - this.lastProgressAt < this.config.progressIntervalMs) return
377
+ this.lastProgressAt = now
378
+ for (const listener of [...this.listeners]) {
379
+ try { listener() } catch {}
380
+ }
381
+ }
382
+
383
+ /** 启动时只查盘:组件在不在、模型在不在;不下载、不跑推理。 */
384
+ inspect() {
385
+ if (this.disposed) return Promise.resolve()
386
+ if (this.preparing) return this.preparing.settled
387
+ return this.runPreparation(async (signal) => {
388
+ this.publish({ phase: 'checking', step: 'check', startedAt: Date.now(), steps: initialSteps() })
389
+ const binary = this.resolveBinary()
390
+ if (!binary) throw new Error(whisperMissingMessage(this.config.binary))
391
+ throwIfAborted(signal)
392
+ if (await this.modelMatches(signal)) {
393
+ this.publish({ phase: 'ready' })
394
+ return
395
+ }
396
+ this.publish({
397
+ phase: 'unprepared',
398
+ steps: STEP_KINDS.map(kind => ({ kind, status: kind === 'check' ? 'complete' : 'pending' })),
399
+ })
400
+ })
401
+ }
402
+
403
+ /**
404
+ * 开始或加入当前准备任务;完成后 phase=ready。已下载且校验通过的模型不会重复下载。
405
+ * @param prepareOptions { downloadSource?: string } 指定源时只用该源、不降级。
406
+ */
407
+ prepare(prepareOptions = {}) {
408
+ const source = prepareOptions?.downloadSource
409
+ if (source !== undefined && !this.config.downloadSources.includes(source)) {
410
+ throw new Error(`语音下载源不可用:${source}`)
411
+ }
412
+ if (this.preparing) {
413
+ if (this.preparing.downloadSource !== source) throw new Error('请先取消当前语音准备任务,再更换下载源')
414
+ return this.preparing.settled
415
+ }
416
+ if (this.disposed) return Promise.resolve()
417
+ return this.runPreparation(async (signal) => {
418
+ const model = this.config.model
419
+ this.publish({ phase: 'checking', step: 'check', startedAt: Date.now(), steps: initialSteps() })
420
+ const binary = this.resolveBinary()
421
+ if (!binary) throw new Error(whisperMissingMessage(this.config.binary))
422
+ throwIfAborted(signal)
423
+ const destination = this.modelPath()
424
+ this.publish({ phase: 'checking', step: 'model', startedAt: Date.now() })
425
+ if (!(await this.hasModelSize(signal))) await this.download(destination, source, signal)
426
+ // 已存在同字节数文件也要走校验步骤,损坏时删除重下一次。
427
+ this.publish({ phase: 'checking', step: 'verify', startedAt: Date.now() })
428
+ if (!(await this.modelMatches(signal))) {
429
+ await rm(destination, { force: true })
430
+ await this.download(destination, source, signal)
431
+ this.publish({ phase: 'checking', step: 'verify', startedAt: Date.now() })
432
+ if (!(await this.modelMatches(signal))) {
433
+ await rm(destination, { force: true })
434
+ throw new SpeechDownloadError({
435
+ resource: model.name,
436
+ source: source ?? this.config.downloadSources[0],
437
+ reason: 'integrity',
438
+ })
439
+ }
440
+ }
441
+ this.publish({ phase: 'loading', step: 'load', startedAt: Date.now() })
442
+ await this.probe(binary, signal)
443
+ throwIfAborted(signal)
444
+ this.publish({ phase: 'ready' })
445
+ }, source)
446
+ }
447
+
448
+ /** 取消未完成的准备;已完成(ready)不撤销。@returns 任务结算后返回。 */
449
+ async cancel() {
450
+ const task = this.preparing
451
+ if (!task) return
452
+ if (!task.completed) {
453
+ this.publish({ phase: 'cancelling', startedAt: Date.now() })
454
+ task.abort.abort(new Error('语音准备已取消'))
455
+ }
456
+ await task.settled
457
+ }
458
+
459
+ /** 一次完整的转写:入队(最多 1 个执行 + 2 个排队)→ 落盘 wav → whisper-cli → 读 txt。 */
460
+ async transcribe(input, signal) {
461
+ return await this.enqueue(async combined => await this.execute(input, combined), signal)
462
+ }
463
+
464
+ async dispose() {
465
+ if (this.disposed) return
466
+ this.disposed = true
467
+ this.listeners.clear()
468
+ this.lifetime.abort(new Error('Whisper provider 已卸载'))
469
+ const task = this.preparing
470
+ if (task) {
471
+ task.abort.abort(this.lifetime.signal.reason)
472
+ await task.settled
473
+ }
474
+ await this.tail
475
+ }
476
+
477
+ resolveBinary() {
478
+ return resolveWhisperBinary({
479
+ configured: this.config.binary,
480
+ pathEnv: this.config.pathEnv,
481
+ platform: this.config.platform,
482
+ })
483
+ }
484
+
485
+ async hasModelSize(signal) {
486
+ throwIfAborted(signal)
487
+ try {
488
+ const info = await stat(this.modelPath())
489
+ return info.isFile() && info.size === this.config.model.bytes
490
+ } catch (error) {
491
+ if (error.code === 'ENOENT') return false
492
+ throw error
493
+ }
494
+ }
495
+
496
+ async modelMatches(signal) {
497
+ throwIfAborted(signal)
498
+ const path = this.modelPath()
499
+ try {
500
+ const info = await stat(path)
501
+ if (!info.isFile() || info.size !== this.config.model.bytes) return false
502
+ const digest = createHash('sha256')
503
+ for await (const chunk of createReadStream(path, { signal })) digest.update(chunk)
504
+ throwIfAborted(signal)
505
+ return digest.digest('hex') === this.config.model.sha256
506
+ } catch (error) {
507
+ if (error.code === 'ENOENT') return false
508
+ if (signal?.aborted) throw abortError(signal)
509
+ throw error
510
+ }
511
+ }
512
+
513
+ /** 流式下载到临时文件,边下边算 sha256;成功后原子 rename。支持多源顺序降级。 */
514
+ async download(destination, requestedSource, signal) {
515
+ const model = this.config.model
516
+ const origins = requestedSource ? [requestedSource] : [...this.config.downloadSources]
517
+ const failures = []
518
+ for (const origin of origins) {
519
+ throwIfAborted(signal)
520
+ const url = `${origin}${MODEL_REMOTE_PREFIX}${model.name}`
521
+ let source = origin
522
+ let partial
523
+ try {
524
+ await mkdir(dirname(destination), { recursive: true })
525
+ const response = await this.config.fetch(url, { signal })
526
+ source = originOf(response?.url) ?? origin
527
+ if (!response?.ok || !response.body) {
528
+ try { await response?.body?.cancel?.() } catch {}
529
+ throw new SpeechDownloadError({
530
+ resource: model.name,
531
+ source,
532
+ reason: 'http',
533
+ status: response?.status,
534
+ })
535
+ }
536
+ partial = `${destination}.${randomUUID()}.part`
537
+ const digest = createHash('sha256')
538
+ let completedBytes = 0
539
+ const report = () => this.publish({
540
+ phase: 'downloading',
541
+ resource: model.name,
542
+ completedBytes,
543
+ totalBytes: model.bytes,
544
+ step: 'model',
545
+ })
546
+ const progress = new Transform({
547
+ transform: (chunk, _encoding, callback) => {
548
+ completedBytes += chunk.length
549
+ if (completedBytes > model.bytes) {
550
+ callback(new SpeechDownloadError({ resource: model.name, source, reason: 'integrity' }))
551
+ return
552
+ }
553
+ digest.update(chunk)
554
+ report()
555
+ callback(null, chunk)
556
+ },
557
+ })
558
+ report()
559
+ await pipeline(responseBodyStream(response.body), progress, createWriteStream(partial, { flags: 'wx', mode: 0o600 }), { signal })
560
+ throwIfAborted(signal)
561
+ if (completedBytes !== model.bytes || digest.digest('hex') !== model.sha256) {
562
+ throw new SpeechDownloadError({ resource: model.name, source, reason: 'integrity' })
563
+ }
564
+ await rename(partial, destination)
565
+ partial = undefined
566
+ return source
567
+ } catch (error) {
568
+ if (signal?.aborted) throw abortError(signal)
569
+ failures.push(error instanceof SpeechDownloadError
570
+ ? error
571
+ : new SpeechDownloadError({ resource: model.name, source, reason: classifyDownloadFailure(error) }, { cause: error }))
572
+ } finally {
573
+ if (partial) await rm(partial, { force: true }).catch(() => {})
574
+ }
575
+ }
576
+ const integrity = failures.find(item => item.download?.reason === 'integrity')
577
+ throw integrity ?? failures[failures.length - 1]
578
+ ?? new SpeechDownloadError({ resource: model.name, source: origins[0] ?? 'unknown', reason: 'unknown' })
579
+ }
580
+
581
+ /** 加载探测:确认 whisper-cli 真能运行(brew 装坏、架构不匹配等在这里暴露)。 */
582
+ async probe(binary, signal) {
583
+ await runCommand(binary, ['--help'], {
584
+ signal,
585
+ timeoutMs: this.config.probeTimeoutMs,
586
+ timeoutMessage: 'whisper-cli --help 超时',
587
+ })
588
+ }
589
+
590
+ enqueue(run, signal) {
591
+ const combined = mergeSignals([signal, this.lifetime.signal])
592
+ throwIfAborted(combined)
593
+ if (this.pending >= this.config.maxPending) {
594
+ throw new Error(`语音识别队列已满(最多排队 ${this.config.maxPending} 个),请稍后重试`)
595
+ }
596
+ this.pending += 1
597
+ const job = this.tail.then(async () => {
598
+ throwIfAborted(combined)
599
+ return await run(combined)
600
+ })
601
+ this.tail = job.then(() => undefined, () => undefined).finally(() => { this.pending -= 1 })
602
+ return job
603
+ }
604
+
605
+ async execute(input, signal) {
606
+ if (this.state.phase !== 'ready') {
607
+ throw new Error('Prepare the local speech provider before recording(Whisper 本地模型未就绪,请先点「下载并准备」)')
608
+ }
609
+ const audioSeconds = readWaveSeconds(input?.audio)
610
+ const binary = this.resolveBinary()
611
+ if (!binary) throw new Error(whisperMissingMessage(this.config.binary))
612
+ const workDir = await mkdtemp(join(this.config.tmpDir || tmpdir(), 'dsh-whisper-'))
613
+ const wavPath = join(workDir, 'input.wav')
614
+ const prefix = join(workDir, 'transcript')
615
+ const startedAt = Date.now()
616
+ try {
617
+ await writeFile(wavPath, input.audio, { mode: 0o600 })
618
+ throwIfAborted(signal)
619
+ await runCommand(binary, [
620
+ '-m', this.modelPath(),
621
+ '-f', wavPath,
622
+ '-l', normalizeLanguage(input.language),
623
+ '-nt', '-np', '-otxt',
624
+ '-of', prefix,
625
+ ], {
626
+ signal,
627
+ timeoutMs: this.config.inferenceTimeoutMs,
628
+ timeoutMessage: `Whisper 推理超时(${Math.round(this.config.inferenceTimeoutMs / 1000)} 秒)`,
629
+ })
630
+ throwIfAborted(signal)
631
+ let raw = ''
632
+ try {
633
+ raw = await readFile(`${prefix}.txt`, 'utf8')
634
+ } catch (error) {
635
+ // whisper-cli 对完全静音可能不产出文件;按空文本处理,不算失败。
636
+ if (error.code !== 'ENOENT') throw error
637
+ }
638
+ return {
639
+ text: normalizeTranscript(raw),
640
+ audioSeconds,
641
+ inferenceSeconds: Math.max(0, (Date.now() - startedAt) / 1000),
642
+ }
643
+ } finally {
644
+ await rm(workDir, { recursive: true, force: true }).catch(() => {})
645
+ }
646
+ }
647
+
648
+ /**
649
+ * 串行执行一个准备任务;取消/失败都落成可读状态,不把异常抛给调用方。
650
+ * @returns 任务结算(永远 resolve)。
651
+ */
652
+ runPreparation(run, downloadSource) {
653
+ if (this.preparing) return this.preparing.settled
654
+ if (this.disposed) return Promise.resolve()
655
+ const abort = new AbortController()
656
+ const task = { abort, settled: Promise.resolve(), completed: false, downloadSource }
657
+ this.preparing = task
658
+ const timer = setTimeout(
659
+ () => abort.abort(new Error(`语音模型准备超时(${Math.round(this.config.prepareTimeoutMs / 60000)} 分钟)`)),
660
+ this.config.prepareTimeoutMs,
661
+ )
662
+ timer.unref?.()
663
+ task.settled = (async () => {
664
+ try {
665
+ await run(abort.signal)
666
+ } catch (error) {
667
+ if (this.disposed || this.lifetime.signal.aborted) return
668
+ this.publish(abort.signal.aborted
669
+ ? { phase: 'cancelled' }
670
+ : {
671
+ phase: 'failed',
672
+ message: error instanceof Error ? error.message : String(error),
673
+ ...(error instanceof SpeechDownloadError ? { download: error.download } : {}),
674
+ })
675
+ } finally {
676
+ clearTimeout(timer)
677
+ if (this.preparing === task) this.preparing = undefined
678
+ }
679
+ })()
680
+ return task.settled
681
+ }
682
+ }
683
+
684
+ /**
685
+ * 在 DSH 主机里登记本地 Whisper provider。
686
+ * 用 cordis 动态注入而不是静态 inject:主机没启用官方语音 bundle(无 speechToText 服务)
687
+ * 时回调永不执行,插件其余功能照常启动。返回 cordis fiber。
688
+ */
689
+ export function registerWhisperProvider(ctx, options = {}) {
690
+ if (typeof ctx?.inject !== 'function') return undefined
691
+ return ctx.inject(['speechToText'], scoped => {
692
+ const provider = createWhisperProvider(options)
693
+ scoped.effect(() => {
694
+ const unregister = scoped.speechToText.register(provider)
695
+ void provider.preparation.inspect()
696
+ return async () => {
697
+ try {
698
+ await unregister()
699
+ } finally {
700
+ await provider.dispose()
701
+ }
702
+ }
703
+ }, 'dsh-remote: whisper speech provider')
704
+ })
705
+ }