@yfwu2020/dsh-selection-explain 0.10.4 → 0.10.6

package/lib/host/sessions.js

@@ -0,0 +1,181 @@
+import { name } from './constants.js';
+import { transcriptOf } from './context.js';
+/** Owns sessions state for one plugin instance. */
+export function createSessions(ctx, config) {
+    /** 会话背景短缓存：同一会话 10 秒内复用（连续划词不重复读日志）。 */
+    const backgroundCache = new Map();
+    /**
+     * 「本会话在用哪个模型」的短缓存 —— 只给按秒轮询的 `/route` 用（见 sessionModelOf）。
+     *
+     * 为什么需要：`readSession` 会把整份日志重放成一个 Session、再逐条深拷贝一遍
+     * （本机实测 1.5MB 的会话一次 80~125ms）。跟随状态下**小窗一开着**就要每 2 秒问一次，
+     * 不缓存等于每 2 秒在宿主进程里重放一次会话日志。
+     *
+     * 变更探测用 live 会话的 `seq`（同步、零成本，见 liveSeqOf）：没涨就直接回缓存；
+     * 涨了（主会话正在连续对话时每轮都在涨）也至少隔 SESSION_MODEL_MIN_MS 才重读一次，
+     * 否则"小窗开着 + 主会话在聊"时每 2 秒照样重放。非 live（磁盘上的旧会话，读不到 seq）按 TTL 兜底。
+     */
+    const sessionModelCache = new Map();
+    /** 同一会话正在飞的读取（读可能比轮询间隔还慢，叠起来没意义）。 */
+    const sessionModelPending = new Map();
+    /** live 会话两次重读之间的最短间隔（挡住"事件一直在涨"时的连续重放）。 */
+    const SESSION_MODEL_MIN_MS = 3_000;
+    /** 读不到 seq（非 live）时的兜底 TTL。 */
+    const SESSION_MODEL_TTL_MS = 10_000;
+    /**
+     * live 会话的事件数（`Session.seq` = 日志长度，每次 append 都会涨）。
+     *
+     * 这是**零成本**的同步读取：不用读日志、不用重放，就能判断"会话有没有新事件"。
+     * 拿不到（会话不在内存里 / 老内核没有 sessions 服务）返回 null，调用方退回 TTL。
+     */
+    const liveSeqOf = (sessionId) => {
+        const sessions = ctx.get('sessions');
+        const seq = sessions?.get?.(sessionId)?.seq;
+        return typeof seq === 'number' ? seq : null;
+    };
+    /** 读取当前会话的模型界面事件（live 优先；失败/超时一律降级为「无背景」）。 */
+    const readSurfaceEvents = async (sessionId) => {
+        const cached = backgroundCache.get(sessionId);
+        if (cached && Date.now() - cached.at < 10_000)
+            return cached.events;
+        const sessionQuery = ctx.get('sessionQuery');
+        if (typeof sessionQuery?.readSurface !== 'function')
+            return [];
+        const timeout = new Promise((resolve) => setTimeout(() => resolve(null), 2000));
+        try {
+            const surface = await Promise.race([sessionQuery.readSurface(sessionId), timeout]);
+            const events = surface && Array.isArray(surface.events) ? surface.events : [];
+            backgroundCache.set(sessionId, { at: Date.now(), events });
+            if (backgroundCache.size > 8) {
+                const oldest = backgroundCache.keys().next().value;
+                if (oldest !== undefined)
+                    backgroundCache.delete(oldest);
+            }
+            return events;
+        }
+        catch (error) {
+            ctx.logger?.warn?.(`[${name}] 读取会话背景失败（${sessionId}）：${String(error?.message ?? error)}`);
+            return [];
+        }
+    };
+    /**
+     * 真读一次：拿会话原始事件里的最后一条 `model/selection`。
+     *
+     * 来源：会话事件流里的 `model/selection`（每条 = 一次"后续请求用这个模型"的选择，
+     * 形如 `{ type:'model/selection', data:{ provider, model, reasoningEffort? } }`）。
+     * 取**最后一条** = 会话当前在用的那个；一条都没有（新会话）就返回 null，调用方落回全局默认。
+     */
+    const readSessionModel = async (sessionId) => {
+        if (!sessionId)
+            return null;
+        const sessionQuery = ctx.get('sessionQuery');
+        if (typeof sessionQuery?.readSession !== 'function')
+            return null;
+        let events = [];
+        try {
+            const timeout = new Promise((resolve) => setTimeout(() => resolve(null), 2000));
+            const log = await Promise.race([sessionQuery.readSession(sessionId), timeout]);
+            events = log && Array.isArray(log.events) ? (log.events) : [];
+        }
+        catch {
+            return null;
+        }
+        for (let i = events.length - 1; i >= 0; i -= 1) {
+            const event = events[i];
+            if (!event || typeof event !== 'object')
+                continue;
+            const typed = event;
+            if (typed.type !== 'model/selection')
+                continue;
+            const data = (typed.data ?? {});
+            if (typeof data.provider === 'string' && data.provider && typeof data.model === 'string' && data.model) {
+                return { provider: data.provider, model: data.model };
+            }
+        }
+        return null;
+    };
+    /**
+     * 记下这次的结论（连同"读到它时的 seq"）：下次轮询就能靠 seq 判断结论还有效没。
+     *
+     * 顺手也把"用户动作路径"读到的值种进缓存 —— 那是**此刻**那一份，
+     * 种进来只会让轮询更少重读、更不容易报旧值。
+     */
+    const rememberSessionModel = (sessionId, seq, value) => {
+        sessionModelCache.set(sessionId, { at: Date.now(), seq, value });
+        if (sessionModelCache.size > 8) {
+            const oldest = sessionModelCache.keys().next().value;
+            if (oldest !== undefined)
+                sessionModelCache.delete(oldest);
+        }
+    };
+    /**
+     * 读**当前会话**自己的模型选择。
+     *
+     * `useCache` 只给按秒轮询的 `/route` 打开；用户动作路径（analyze / models / ping）一律直读，
+     * 拿到的必须是**此刻**那一份 —— 不能让人刚在主会话里换完模型、划词却按旧模型解析。
+     * 直读的结果会顺手种进缓存（见 rememberSessionModel）。
+     */
+    const sessionModelOf = async (sessionId, useCache = false) => {
+        if (!sessionId)
+            return null;
+        if (!useCache) {
+            // seq 在读**之前**取：读的过程中若又落了事件，缓存就应当被视为旧值（宁可下次重读）
+            const seqNow = liveSeqOf(sessionId);
+            const value = await readSessionModel(sessionId);
+            rememberSessionModel(sessionId, seqNow, value);
+            return value;
+        }
+        const seq = liveSeqOf(sessionId);
+        const cached = sessionModelCache.get(sessionId);
+        if (cached) {
+            // 事件没涨 → 结论不可能变。只对 live 会话成立：`seq` 是同步的，每次 append 都会涨。
+            if (seq !== null && cached.seq === seq)
+                return cached.value;
+            // 涨了也不立刻重读：主会话正在连续对话时事件一直在涨，否则每 2 秒照样重放一次日志。
+            const floor = seq === null ? SESSION_MODEL_TTL_MS : SESSION_MODEL_MIN_MS;
+            if (Date.now() - cached.at < floor)
+                return cached.value;
+        }
+        // 同一会话的轮询叠在一起（读可能比轮询间隔还慢）时共用一个在飞的请求
+        const pending = sessionModelPending.get(sessionId);
+        if (pending)
+            return pending;
+        const task = readSessionModel(sessionId)
+            .then((value) => {
+            rememberSessionModel(sessionId, seq, value);
+            return value;
+        })
+            .finally(() => {
+            sessionModelPending.delete(sessionId);
+        });
+        sessionModelPending.set(sessionId, task);
+        return task;
+    };
+    /** 组装会话背景文本。 */
+    const loadSessionBackground = async (sessionId, options) => {
+        const events = await readSurfaceEvents(sessionId);
+        if (events.length === 0)
+            return null;
+        const background = transcriptOf(events, options);
+        return background.transcript ? background : null;
+    };
+    /** 解析一个会话的工作目录（同项目 = 同 cwd）。 */
+    const resolveSessionCwd = async (sessionId) => {
+        if (!sessionId)
+            return undefined;
+        const sessions = ctx.get('sessions');
+        const live = sessions?.get?.(sessionId)?.header?.cwd;
+        if (live)
+            return live;
+        const sessionQuery = ctx.get('sessionQuery');
+        try {
+            const log = await sessionQuery?.readSession?.(sessionId);
+            return log?.session?.cwd;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    return { sessionModelOf, loadSessionBackground, resolveSessionCwd, readSurfaceEvents };
+}
+//# sourceMappingURL=sessions.js.map

package/lib/host/sessions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.js","sourceRoot":"","sources":["../../src/host/sessions.ts"],"names":[],"mappings":"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"}

package/lib/host/settings-store.js

@@ -0,0 +1,140 @@
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { SETTINGS_KEYS, PERSISTED_SETTING_KEYS, normalizeStoredSettings, normalizeSettingsPatch, buildSettingsPayload } from '../settings.js';
+import { readFile, mkdir, writeFile } from 'node:fs/promises';
+import { name } from './constants.js';
+import { readBody, sendJson } from './http.js';
+/** Owns settings-store state for one plugin instance. */
+export function createSettingsStore(ctx, config) {
+    /**
+     * 出厂默认值（**不含**用户在设置页改过的部分）。
+     *
+     * 为什么单独留一份：设置页的「恢复默认」要能把值写回这里，
+     * 而"这一项改过没有"也要拿它对比 —— 只有一个 config 的话，改完就再也说不出原值是什么。
+     * 注意它取的是 rawConfig（cordis.patch.yml 里的配置），所以 yml 里写过的值也算"默认"：
+     * 用户在设置页恢复默认，应该回到 yml 写的那个数，而不是硬编码的出厂数。
+     */
+    const configDefaults = { ...config };
+    /**
+     * 设置页写入的覆盖值（**只存改过的键**）。
+     *
+     * 落盘在插件自己的目录（与 history.json / pill.json 同级），不碰 cordis.patch.yml：
+     * 那个文件是**装配清单**，让 UI 去改它既容易写坏结构，也要重启才生效。
+     * 这里的内存值即刻生效（下方所有 config.x 都是每次请求现读的），落盘只为跨重启保留。
+     */
+    let settingsOverrides = {};
+    let settingsLoaded = false;
+    let settingsTimer = null;
+    const settingsFile = () => join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'selection-explain', 'settings.json');
+    /**
+     * 把覆盖值套用到 config 上。
+     *
+     * 只接受 SETTINGS_KEYS 里的键，并且**类型必须与默认值一致** ——
+     * 文件是手工可编辑的（也可能被旧版本写坏），不能让它把 boolean 写成字符串，
+     * 那会让 `if (config.tools)` 这种判断悄悄变成永真。
+     */
+    function applyOverrides(patch) {
+        const target = config;
+        for (const [key, value] of Object.entries(patch)) {
+            if (!SETTINGS_KEYS.includes(key) && !PERSISTED_SETTING_KEYS.includes(key))
+                continue;
+            if (typeof value !== typeof configDefaults[key])
+                continue;
+            target[key] = value;
+        }
+    }
+    /** 读设置覆盖文件（进程内只读一次，与 loadHistory / loadPillPos 同节奏）。 */
+    async function loadSettings() {
+        if (settingsLoaded)
+            return;
+        settingsLoaded = true;
+        try {
+            const parsed = JSON.parse(await readFile(settingsFile(), 'utf8'));
+            const raw = parsed?.values;
+            if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+                const values = normalizeStoredSettings(raw);
+                settingsOverrides = values;
+                applyOverrides(values);
+            }
+        }
+        catch {
+            // 没存过 / 坏了都当作"没改过"：出厂默认本来就是可用状态，没必要因此报错
+            settingsOverrides = {};
+        }
+    }
+    /** 落盘（防抖：拖数字输入框会连发多次，没必要每次都写文件）。 */
+    function scheduleSettingsWrite() {
+        if (settingsTimer)
+            clearTimeout(settingsTimer);
+        settingsTimer = setTimeout(() => {
+            settingsTimer = null;
+            void (async () => {
+                try {
+                    await mkdir(join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'selection-explain'), { recursive: true });
+                    await writeFile(settingsFile(), JSON.stringify({ version: 1, values: settingsOverrides }, null, 0), 'utf8');
+                }
+                catch (error) {
+                    ctx.logger?.warn?.(`[${name}] 写入设置失败：${String(error?.message ?? error)}`);
+                }
+            })();
+        }, 300);
+        settingsTimer.unref?.();
+    }
+    /** 当前生效值（按 spec 的键序取，客户端可以直接对比 defaults 判断改过没有）。 */
+    function currentSettings() {
+        const target = config;
+        const values = {};
+        for (const key of SETTINGS_KEYS)
+            values[key] = target[key];
+        return values;
+    }
+    /**
+     * 设置页的读写口。
+     *
+     *   GET  → { groups, values, defaults }：spec 一并下发，客户端只负责画
+     *   POST → { values: {...} }：归一 → 立刻生效（改内存）→ 防抖落盘
+     *   POST { reset: true }    ：清空覆盖，回到 cordis.patch.yml / 出厂默认
+     *
+     * 为什么不是"写回 cordis.patch.yml"：那是装配清单，
+     * 让 UI 去改它既要人肉重启、又可能把 YAML 结构写坏；这里落在插件自己的目录，改完即时生效。
+     */
+    const handleSettings = (req, res) => {
+        void (async () => {
+            await loadSettings();
+            if (req.method === 'POST') {
+                const raw = await readBody(req, 200_000);
+                let body = {};
+                try {
+                    body = raw ? JSON.parse(raw) : {};
+                }
+                catch {
+                    sendJson(res, 400, { ok: false, error: '请求体不是合法 JSON' });
+                    return;
+                }
+                if (body.reset === true) {
+                    settingsOverrides = {};
+                    applyOverrides(configDefaults);
+                    scheduleSettingsWrite();
+                    sendJson(res, 200, { ok: true, values: currentSettings(), rejected: [] });
+                    return;
+                }
+                const result = normalizeSettingsPatch(body.values);
+                if (Object.keys(result.values).length === 0 && result.rejected.length > 0) {
+                    sendJson(res, 400, { ok: false, error: '没有可写入的字段', rejected: result.rejected });
+                    return;
+                }
+                // 合并而不是覆盖：只发一个键的补丁不该把其它改过的项抹掉
+                settingsOverrides = { ...settingsOverrides, ...result.values };
+                applyOverrides(result.values);
+                scheduleSettingsWrite();
+                sendJson(res, 200, { ok: true, values: currentSettings(), rejected: result.rejected });
+                return;
+            }
+            sendJson(res, 200, { ok: true, ...buildSettingsPayload(currentSettings(), configDefaults) });
+        })().catch((error) => {
+            sendJson(res, 500, { ok: false, error: String(error?.message ?? error) });
+        });
+    };
+    return { loadSettings, handleSettings };
+}
+//# sourceMappingURL=settings-store.js.map

package/lib/host/settings-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-store.js","sourceRoot":"","sources":["../../src/host/settings-store.ts"],"names":[],"mappings":"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"}

package/lib/host/speech.js

@@ -0,0 +1,320 @@
+import { sendJson, readBody } from './http.js';
+// ────────────────────────────── 语音输入（小窗麦克风） ──────────────────────────────
+//
+// 小窗的追问输入框加一个麦克风：录一段话 → 转成文字**插进输入框**（不是直接发送，
+// 识别错了还能改）。转写这条链路在 host 这一侧收口：
+//
+//   GET  ${API_PREFIX}/speech            识别服务目录 + 就绪状态（客户端据此决定麦克风能不能点）
+//   POST ${API_PREFIX}/speech/transcribe 一段 16kHz 单声道 PCM16 WAV（base64）→ 文字
+//   POST ${API_PREFIX}/speech/prepare    显式准备本地识别模型（首次要下载，必须用户点头）
+//
+// 为什么不让浏览器自己去连识别服务：音频、provider 选择、模型路径全部留在 host，
+// 客户端只拿到"一段话的文字"；而且**音频不落盘、不进会话**（转写完即丢）。
+// 识别服务（@deepseek-ai/dsh-experimental-speech-to-text）是实验性的、可以不装：
+// 拿不到该服务就整条链路优雅降级（目录接口回 available:false，麦克风点了只给一句解释）。
+/** 单次录音时长上限（秒）：到了就自动收尾去识别，不让用户对着麦克风发呆。 */
+const SPEECH_MAX_SECONDS = 60;
+/** 单条音频的字节上限（≈ 2 分钟 16kHz 单声道 PCM16）；与识别服务默认的 4MB 对齐。 */
+const SPEECH_MAX_BYTES = 4 * 1024 * 1024;
+/** 识别请求体上限：base64 会膨胀 4/3，再留点余量给 JSON 外壳。 */
+const SPEECH_BODY_LIMIT = Math.ceil(SPEECH_MAX_BYTES / 3) * 4 + 4096;
+/** 单次识别的等待上限（毫秒）：真机上 60 秒音频几秒内就回来了，这是兜底。 */
+const SPEECH_TIMEOUT_MS = 120_000;
+/**
+ * 校验客户端送上来的音频是不是**规范**的 16kHz 单声道 PCM16 WAV。
+ *
+ * 为什么抠得这么死：这个格式是浏览器端编码器（MediaRecorder → decodeAudioData →
+ * OfflineAudioContext 重采样 → 手写 WAV 头）唯一会产出的形状。逐字段对齐之后，
+ * "音频不对"就只剩两种可能——客户端版本对不上、或者有人手工构造了这个请求。
+ * 光看二进制长度不算数：头里写的采样率/声道/位深必须是那一套，否则识别服务会按
+ * 错误的采样率解释这段音频（听起来像快放/慢放），识别结果自然全错。
+ *
+ * @param audio 完整音频字节
+ * @param maxSeconds 允许的最长时长
+ * @returns 时长（秒）
+ */
+export function validateWave(audio, maxSeconds) {
+    if (audio.length < 46 ||
+        audio.toString('ascii', 0, 4) !== 'RIFF' ||
+        audio.toString('ascii', 8, 12) !== 'WAVE' ||
+        audio.toString('ascii', 12, 16) !== 'fmt ' ||
+        audio.readUInt32LE(16) !== 16 ||
+        audio.readUInt16LE(20) !== 1 || // PCM
+        audio.readUInt16LE(22) !== 1 || // 单声道
+        audio.readUInt32LE(24) !== 16000 || // 16kHz
+        audio.readUInt32LE(28) !== 32000 || // 字节率 = 16000 × 1ch × 2B
+        audio.readUInt16LE(32) !== 2 || // 块对齐
+        audio.readUInt16LE(34) !== 16 || // 16 bit
+        audio.toString('ascii', 36, 40) !== 'data' ||
+        audio.readUInt32LE(4) !== audio.length - 8 ||
+        audio.readUInt32LE(40) !== audio.length - 44 ||
+        (audio.length - 44) % 2 !== 0) {
+        throw new Error('音频格式不是 16kHz 单声道 PCM16 WAV');
+    }
+    const seconds = (audio.length - 44) / 32000;
+    if (seconds <= 0)
+        throw new Error('录音是空的');
+    if (seconds > maxSeconds)
+        throw new Error(`录音超过 ${maxSeconds} 秒`);
+    return seconds;
+}
+/** Owns speech state for one plugin instance. */
+export function createSpeech(ctx, config) {
+    /** ctx.speechToText：装了就给，没装/被停用给 undefined（麦克风据此优雅降级）。 */
+    const speechService = () => {
+        try {
+            const service = ctx.get('speechToText');
+            return service && typeof service.transcribe === 'function' ? service : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    /**
+     * 语音目录：有哪些识别器、各自什么状态、默认选谁、这次能录多久。
+     *
+     * 客户端据此决定麦克风的形态：能用 / 要先把模型准备好 / 这个部署根本没有识别服务。
+     * 不认识的状态一律当成"不能录"（宁可让用户看到一句解释，也不要录完才发现转不了）。
+     */
+    const speechCatalog = () => {
+        const service = speechService();
+        const limits = { maxSeconds: SPEECH_MAX_SECONDS, maxBytes: SPEECH_MAX_BYTES };
+        if (!service) {
+            return {
+                ok: true,
+                available: false,
+                reason: 'missing',
+                error: '这个 DSH 没有启用语音识别服务（缺 @deepseek-ai/dsh-experimental-speech-to-text）',
+                providers: [],
+                selection: null,
+                limits,
+            };
+        }
+        let snapshot;
+        try {
+            snapshot = service.snapshot();
+        }
+        catch (error) {
+            return {
+                ok: true,
+                available: false,
+                reason: 'error',
+                error: String(error?.message ?? error),
+                providers: [],
+                selection: null,
+                limits,
+            };
+        }
+        const providers = (snapshot?.providers ?? []).map((provider) => {
+            const preparation = provider.preparation ?? { phase: 'ready' };
+            return {
+                id: String(provider.id),
+                name: String(provider.name ?? provider.id),
+                location: String(provider.location ?? ''),
+                languages: Array.isArray(provider.languages) ? provider.languages.map(String) : [],
+                // 下载源：本地模型已经装好时是空数组（没有可选项），装了才有得选
+                downloadSources: Array.isArray(provider.downloadSources) ? provider.downloadSources.map(String) : [],
+                phase: String(preparation.phase ?? 'unprepared'),
+                step: preparation.step ? String(preparation.step) : '',
+                // 下载进度（只在 downloading 时有意义）：客户端显示"还要下多少"
+                completedBytes: typeof preparation.completedBytes === 'number' ? preparation.completedBytes : 0,
+                totalBytes: typeof preparation.totalBytes === 'number' ? preparation.totalBytes : 0,
+                message: preparation.message ? String(preparation.message) : '',
+            };
+        });
+        const selection = snapshot?.selection
+            ? { providerId: String(snapshot.selection.providerId), language: String(snapshot.selection.language) }
+            : null;
+        // 能录 = 至少有一个识别器已经就绪（standby 也算：本机模型在磁盘上，用到才唤醒）
+        const usable = providers.filter((provider) => provider.phase === 'ready' || provider.phase === 'standby');
+        return {
+            ok: true,
+            available: usable.length > 0,
+            reason: usable.length > 0 ? '' : providers.length > 0 ? 'unprepared' : 'empty',
+            error: '',
+            providers,
+            selection,
+            limits,
+        };
+    };
+    const handleSpeech = (req, res) => {
+        if (req.method !== 'GET') {
+            sendJson(res, 405, { ok: false, error: '只支持 GET' });
+            return;
+        }
+        sendJson(res, 200, speechCatalog());
+    };
+    /**
+     * 显式准备识别模型（首次要下 1G 左右的模型，所以**只有用户点了才做**，不自动触发）。
+     * 只是把任务交给识别服务，进度走目录接口轮询（下载在 host 上跑，关掉页面也继续）。
+     */
+    const handleSpeechPrepare = (req, res) => {
+        void (async () => {
+            if (req.method !== 'POST') {
+                sendJson(res, 405, { ok: false, error: '只支持 POST' });
+                return;
+            }
+            const service = speechService();
+            if (!service) {
+                sendJson(res, 200, { ok: false, error: '这个 DSH 没有启用语音识别服务' });
+                return;
+            }
+            let body = {};
+            try {
+                const raw = await readBody(req, 20_000);
+                body = raw ? JSON.parse(raw) : {};
+            }
+            catch {
+                sendJson(res, 400, { ok: false, error: '请求体不是合法 JSON' });
+                return;
+            }
+            const catalog = speechCatalog();
+            const wanted = typeof body.providerId === 'string' && body.providerId ? body.providerId : '';
+            const providers = catalog.providers ?? [];
+            const target = wanted || (providers.find((item) => item.phase !== 'ready' && item.phase !== 'standby')?.id ?? providers[0]?.id ?? '');
+            if (!target) {
+                sendJson(res, 200, { ok: false, error: '没有可用的识别器' });
+                return;
+            }
+            try {
+                const source = typeof body.downloadSource === 'string' && body.downloadSource ? body.downloadSource : undefined;
+                service.prepare(target, source === undefined ? undefined : { downloadSource: source });
+            }
+            catch (error) {
+                // 已经在准备中 / 下载源不认 / 服务生命周期已结束：都不算致命，把状态回给客户端自己看
+                sendJson(res, 200, { ok: false, error: String(error?.message ?? error), catalog: speechCatalog() });
+                return;
+            }
+            sendJson(res, 200, { ok: true, providerId: target, catalog: speechCatalog() });
+        })().catch((error) => {
+            sendJson(res, 500, { ok: false, error: String(error?.message ?? error) });
+        });
+    };
+    /**
+     * 转写一段录音。
+     *
+     * 输入是浏览器端编码好的规范 WAV（base64），输出就是一段文字——**不落盘、不进会话**，
+     * 也不给模型看（用户要的是"把我说的变成字"，不是"让模型处理我的录音"）。
+     * 识别失败一律回 200 + { ok:false, code }：这是"这一句话没听清"，
+     * 不是 HTTP 层面的错误，客户端按 code 给不同的话术（换 HTTP 状态码反而会被
+     * 各种中间层改写或吞掉，用户看到的就只剩"请求失败"）。
+     */
+    const handleSpeechTranscribe = (req, res) => {
+        void (async () => {
+            if (req.method !== 'POST') {
+                sendJson(res, 405, { ok: false, error: '只支持 POST' });
+                return;
+            }
+            const service = speechService();
+            if (!service) {
+                sendJson(res, 200, {
+                    ok: false,
+                    code: 'missing',
+                    error: '这个 DSH 没有启用语音识别服务（缺 @deepseek-ai/dsh-experimental-speech-to-text）',
+                });
+                return;
+            }
+            let body = {};
+            try {
+                const raw = await readBody(req, SPEECH_BODY_LIMIT);
+                body = raw ? JSON.parse(raw) : {};
+            }
+            catch (error) {
+                sendJson(res, 200, { ok: false, code: 'transport', error: String(error?.message ?? error) });
+                return;
+            }
+            const encoded = typeof body.audioBase64 === 'string' ? body.audioBase64 : '';
+            if (!encoded) {
+                sendJson(res, 200, { ok: false, code: 'audio', error: '没有收到音频' });
+                return;
+            }
+            let audio;
+            let seconds = 0;
+            try {
+                if (encoded.length > Math.ceil(SPEECH_MAX_BYTES / 3) * 4)
+                    throw new Error('录音太大了');
+                audio = Buffer.from(encoded, 'base64');
+                // 规范 base64：随手传一段别的东西进来会在这一步被挡掉（解出来对不上原文）
+                if (audio.toString('base64') !== encoded)
+                    throw new Error('音频不是合法 base64');
+                if (audio.length > SPEECH_MAX_BYTES)
+                    throw new Error('录音太大了');
+                seconds = validateWave(audio, SPEECH_MAX_SECONDS);
+            }
+            catch (error) {
+                sendJson(res, 200, { ok: false, code: 'audio', error: String(error?.message ?? error) });
+                return;
+            }
+            const catalog = speechCatalog();
+            const providers = catalog.providers ?? [];
+            // 这个部署默认用的语言（识别服务里配的，auto = 自动判断）；请求里带了就以请求为准
+            const catalogLanguage = String(catalog.selection?.language ?? '');
+            const wanted = typeof body.providerId === 'string' && body.providerId ? body.providerId : '';
+            const picked = providers.find((item) => item.id === wanted) ??
+                providers.find((item) => item.phase === 'ready' || item.phase === 'standby') ??
+                providers[0];
+            if (!picked) {
+                sendJson(res, 200, { ok: false, code: 'empty', error: '没有可用的识别器' });
+                return;
+            }
+            if (picked.phase !== 'ready' && picked.phase !== 'standby') {
+                sendJson(res, 200, {
+                    ok: false,
+                    code: 'unprepared',
+                    providerId: picked.id,
+                    phase: picked.phase,
+                    error: `识别模型还没准备好（${picked.name}：${picked.phase}）`,
+                    catalog,
+                });
+                return;
+            }
+            // 客户端断开 / 用户取消 → 立刻掐掉识别（本机模型在跑推理，不能让它白跑）
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(new Error('识别超时')), SPEECH_TIMEOUT_MS);
+            const onClose = () => controller.abort(new Error('客户端已断开'));
+            req.on('close', onClose);
+            const startedAt = Date.now();
+            try {
+                const language = typeof body.language === 'string' && body.language ? body.language : undefined;
+                const spec = service.resolve({
+                    audio,
+                    ...(wanted ? { providerId: wanted } : {}),
+                    ...(language === undefined ? {} : { language }),
+                });
+                const transcript = await service.transcribe(spec, controller.signal);
+                const text = String(transcript?.text ?? '').trim();
+                if (!text) {
+                    sendJson(res, 200, { ok: false, code: 'empty-transcript', error: '没听清（这段录音里没有识别到内容）' });
+                    return;
+                }
+                sendJson(res, 200, {
+                    ok: true,
+                    text,
+                    providerId: picked.id,
+                    providerName: picked.name,
+                    language: language ?? catalogLanguage,
+                    seconds,
+                    elapsedMs: Date.now() - startedAt,
+                });
+            }
+            catch (error) {
+                const message = String(error?.message ?? error);
+                const aborted = error?.name === 'AbortError' || controller.signal.aborted;
+                // 超时/断开与"识别失败"分开报：前者是这一句没转成，后者是识别服务本身有问题
+                sendJson(res, 200, {
+                    ok: false,
+                    code: aborted ? 'aborted' : 'failed',
+                    error: aborted ? `这次识别被打断了（${message}）` : message,
+                });
+            }
+            finally {
+                clearTimeout(timer);
+                req.off('close', onClose);
+            }
+        })().catch((error) => {
+            sendJson(res, 500, { ok: false, error: String(error?.message ?? error) });
+        });
+    };
+    return { handleSpeech, handleSpeechTranscribe, handleSpeechPrepare };
+}
+//# sourceMappingURL=speech.js.map