@yfwu2020/dsh-selection-explain 0.1.3 → 0.4.0

package/lib/index.js

@@ -59,6 +59,9 @@ export const Config = z.object({
     sessionContextMaxMessages: z.number().min(1).max(200).default(24),
     sessionContextFastMessages: z.number().min(1).max(200).default(8),
     sessionContextMaxChars: z.number().min(0).max(2000000).default(0),
+    quoteContextRounds: z.number().min(0).max(10).default(1),
+    quoteContextMaxCharsPerTurn: z.number().min(200).max(20000).default(2000),
+    quoteContextMaxChars: z.number().min(400).max(100000).default(6000),
     resultCacheTtlMs: z.number().min(0).max(86400000).default(600000),
     tools: z.boolean().default(true),
     /**
@@ -82,6 +85,11 @@ export const Config = z.object({
     toolResultMaxChars: z.number().min(200).max(20000).default(3000),
     toolReadRoot: z.string().default(''),
     chatReasoningEffort: z.string().default('high'),
+    /**
+     * 侧边栏 HTML 预览里的划词桥。关掉就不往预览帧里注入桥脚本，
+     * 侧边栏网页里选中文字不会再弹「解读」。
+     */
+    bridgeSidebarPreview: z.boolean().default(true),
 });
 /** 联网类工具名：用来判断"首选里的联网工具在不在"。 */
 const SEARCH_TOOL_NAMES = ['advanced_search', 'platform_search', 'web_search'];
@@ -387,6 +395,65 @@ function clampText(raw, max) {
     const text = typeof raw === 'string' ? raw.trim() : '';
     return text.length > max ? `${text.slice(0, max)}\n…（已截断）` : text;
 }
+// ────────────────────────────── 语音输入（小窗麦克风） ──────────────────────────────
+//
+// 小窗的追问输入框加一个麦克风：录一段话 → 转成文字**插进输入框**（不是直接发送，
+// 识别错了还能改）。转写这条链路在 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;
+}
 /**
  * 「网页模式」的设计规范：从插件自带的 `skills/web-design/SKILL.md` 读（按 mtime 缓存）。
  *
@@ -579,6 +646,18 @@ async function runTool(ctx, name, args, signal, maxChars, agent) {
         return { content: [{ type: 'text', text: `工具执行失败：${String(error?.message ?? error)}` }], isError: true };
     }
 }
+/**
+ * `createSystemMessage` 的**跨版本兼容调用**。
+ *
+ * 这个函数的签名在两个版本间不一样，而两份类型都得能编译通过：
+ *   · **0.1.5-rc.3**（npm 上按 peer 范围 `>=0.1.5-rc <2` 解析到的就是它，CI 的构建校验用的这份）：
+ *     `createSystemMessage(text, plugin)` —— 两个都必填，少传一个直接 TS2554（发布被卡过一次）；
+ *   · **0.1.7-rc.x**（本机/新运行时）：`createSystemMessage(text)` —— 第二参数是历史遗留，传了会被忽略。
+ *
+ * 所以这里把它当"接受可选第二参数"的函数来调：两个版本都编译得过，运行时也都正确
+ * （旧版正好拿到它想要的"组装这段提示词的插件名"，新版直接忽略）。
+ */
+const systemMessageOf = createSystemMessage;
 /** 请求里带的会话 id（空串 = 客户端没取到）。 */
 function sessionIdOf(body) {
     return typeof body.sessionId === 'string' ? body.sessionId.trim() : '';
@@ -683,6 +762,138 @@ export function transcriptOf(events, options) {
     const transcript = picked.map((entry) => `${entry.marked ? '▶ ' : '  '}${entry.role}：${entry.text}`).join('\n');
     return { transcript, marked: picked.some((entry) => entry.marked) };
 }
+/** 在文本里找到引用文字并套上【】（直接找不到就按"空白等价"再找一次）。 */
+function markQuoteInText(text, marker) {
+    if (!text || !marker)
+        return text;
+    const at = text.indexOf(marker);
+    if (at >= 0)
+        return `${text.slice(0, at)}【${marker}】${text.slice(at + marker.length)}`;
+    // 归一化后匹配：把引用按空白切开，逐段允许任意空白（选中文字常与消息原文差在换行/缩进）
+    const tokens = marker.split(/\s+/).filter(Boolean).map((token) => token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+    if (tokens.length === 0)
+        return text;
+    try {
+        const hit = new RegExp(tokens.join('\\s+')).exec(text);
+        if (hit && typeof hit.index === 'number') {
+            return `${text.slice(0, hit.index)}【${hit[0]}】${text.slice(hit.index + hit[0].length)}`;
+        }
+    }
+    catch {
+        /* 正则构造失败（极端输入）：不标记，客户端会把原文另起一段补上 */
+    }
+    return text;
+}
+/** 围绕引用截断长消息（引用本身必须留下；找不到引用就从头截）。 */
+function clampAroundQuote(text, marker, max) {
+    if (text.length <= max)
+        return text;
+    const at = marker ? text.indexOf(marker) : -1;
+    if (at < 0)
+        return `${text.slice(0, max)}…（已截断）`;
+    const half = Math.max(0, Math.floor((max - marker.length) / 2));
+    const from = Math.max(0, at - half);
+    const to = Math.min(text.length, at + marker.length + half);
+    return `${from > 0 ? '…' : ''}${text.slice(from, to)}${to < text.length ? '…' : ''}`;
+}
+/**
+ * **引用上下文**：引用文字所在的那一组对话 ± N 组（一组 = 一条用户消息 + 它的助手回复）。
+ *
+ * 与 `transcriptOf`（解读用的会话背景）的区别，两条都是为引用量身定的：
+ *   ① 窗口是**锚点两侧** —— 引用常常是"上面那句"和"下面那句"的对照，只有上文不够；
+ *   ② 按**轮**取整 —— 上下各至少一整组（用户消息 + AI 回复），不会切在半个回合上。
+ * 噪音过滤与 `transcriptOf` 完全一致（工具调用/结果、系统提示、harness 注入一律不进）。
+ */
+export function quoteContextOf(events, marker, options = {}) {
+    const roundsAround = Math.max(0, options.roundsAround ?? 1);
+    const maxCharsPerTurn = Math.max(200, options.maxCharsPerTurn ?? 2000);
+    const maxChars = Math.max(400, options.maxChars ?? 6000);
+    const entries = [];
+    for (const event of events) {
+        if (!event || typeof event !== 'object')
+            continue;
+        const typed = event;
+        const data = (typed.data ?? {});
+        let role = '';
+        let content;
+        if (typed.type === 'user/message') {
+            if (data.source && data.source.kind !== 'user')
+                continue;
+            role = '用户';
+            content = data.content;
+        }
+        else if (typed.type === 'assistant/message') {
+            role = '助手';
+            content = data.message?.content;
+        }
+        else {
+            continue;
+        }
+        const text = messageText(content);
+        if (!text)
+            continue;
+        entries.push({ role, text, marked: false });
+    }
+    if (entries.length === 0)
+        return { transcript: '', matched: false, rounds: 0 };
+    const needle = normalizeSpace(marker);
+    let anchor = -1;
+    if (needle.length >= 2) {
+        for (let i = entries.length - 1; i >= 0; i -= 1) {
+            if (normalizeSpace(entries[i]?.text ?? '').includes(needle)) {
+                anchor = i;
+                break;
+            }
+        }
+    }
+    if (anchor < 0)
+        return { transcript: '', matched: false, rounds: 0 };
+    // 按"轮"分组：一条用户消息开一轮（它之前的助手消息归上一轮）
+    const roundOf = [];
+    let round = -1;
+    for (const entry of entries) {
+        if (entry.role === '用户' || round < 0)
+            round += 1;
+        roundOf.push(round);
+    }
+    const anchorRound = roundOf[anchor] ?? 0;
+    const fromRound = Math.max(0, anchorRound - roundsAround);
+    const toRound = Math.min(round, anchorRound + roundsAround);
+    const picked = [];
+    for (let i = 0; i < entries.length; i += 1) {
+        const r = roundOf[i] ?? 0;
+        if (r < fromRound || r > toRound)
+            continue;
+        const entry = entries[i];
+        const isAnchor = i === anchor;
+        const raw = isAnchor ? markQuoteInText(entry.text, marker) : entry.text;
+        picked.push({
+            role: entry.role,
+            text: clampAroundQuote(raw, marker, maxCharsPerTurn),
+            marked: isAnchor,
+        });
+    }
+    // 总量上限：超了先丢最早的几组，再丢引用之后的几组（**引用所在那条永远保留**）
+    let used = picked.reduce((sum, entry) => sum + entry.text.length, 0);
+    let droppedBefore = 0;
+    let droppedAfter = 0;
+    while (picked.length > 1 && used > maxChars && picked[0] && !picked[0].marked) {
+        const first = picked.shift();
+        droppedBefore += 1;
+        used -= first ? first.text.length : 0;
+    }
+    while (picked.length > 1 && used > maxChars && picked[picked.length - 1] && !picked[picked.length - 1]?.marked) {
+        const last = picked.pop();
+        droppedAfter += 1;
+        used -= last ? last.text.length : 0;
+    }
+    if (droppedBefore > 0)
+        picked.unshift({ role: '提示', text: `（引用之前还有 ${droppedBefore} 条消息，未包含）`, marked: false });
+    if (droppedAfter > 0)
+        picked.push({ role: '提示', text: `（引用之后还有 ${droppedAfter} 条消息，未包含）`, marked: false });
+    const transcript = picked.map((entry) => `${entry.role}：${entry.text}`).join('\n');
+    return { transcript, matched: true, rounds: toRound - fromRound + 1 };
+}
 /** 注册路由、解析模型路由、转发 LLM 流。 */
 export function apply(ctx, rawConfig) {
     const config = {
@@ -701,6 +912,9 @@ export function apply(ctx, rawConfig) {
         sessionContextMaxMessages: rawConfig?.sessionContextMaxMessages ?? 24,
         sessionContextFastMessages: rawConfig?.sessionContextFastMessages ?? 8,
         sessionContextMaxChars: rawConfig?.sessionContextMaxChars ?? 0,
+        quoteContextRounds: rawConfig?.quoteContextRounds ?? 1,
+        quoteContextMaxCharsPerTurn: rawConfig?.quoteContextMaxCharsPerTurn ?? 2000,
+        quoteContextMaxChars: rawConfig?.quoteContextMaxChars ?? 6000,
         resultCacheTtlMs: rawConfig?.resultCacheTtlMs ?? 600000,
         tools: rawConfig?.tools ?? true,
         toolNames: rawConfig?.toolNames ?? 'advanced_search,platform_search,read,grep,glob',
@@ -709,6 +923,7 @@ export function apply(ctx, rawConfig) {
         toolResultMaxChars: rawConfig?.toolResultMaxChars ?? 3000,
         toolReadRoot: rawConfig?.toolReadRoot ?? '',
         chatReasoningEffort: rawConfig?.chatReasoningEffort ?? 'high',
+        bridgeSidebarPreview: rawConfig?.bridgeSidebarPreview ?? true,
     };
     /** 兜底路由：第一次真实 LLM 调用后捕获。 */
     let captured = null;
@@ -999,6 +1214,308 @@ export function apply(ctx, rawConfig) {
         hasDetail: entry.parts.detail.length > 0,
         pinned: entry.pinned,
     });
+    /**
+     * 引用上下文：客户端点了「❝ 引用」之后，拿引用文字来换它所在的那一组对话 ± 一组。
+     *
+     * 为什么走 host 而不是客户端读 DOM：会话正文的**干净文本**只有 host 这边有
+     * （`readSurface` 的事件流里工具调用/结果、系统提示、harness 注入全都被 `transcriptOf`
+     * 那套规则滤掉过）。客户端 DOM 里读到的会是"渲染后的样子"——思考块、工具卡片、
+     * 按钮文案全混在里面。定位不到（引用来自侧边栏网页/文档预览）就返回 matched:false，
+     * 客户端退回它自己采的局部上下文。
+     */
+    const handleQuoteContext = (req, res) => {
+        void (async () => {
+            if (req.method !== 'POST') {
+                sendJson(res, 405, { ok: false, error: '只支持 POST' });
+                return;
+            }
+            const raw = await readBody(req, 200_000);
+            let body = {};
+            try {
+                body = raw ? JSON.parse(raw) : {};
+            }
+            catch {
+                sendJson(res, 400, { ok: false, error: '请求体不是合法 JSON' });
+                return;
+            }
+            const sessionId = typeof body.sessionId === 'string' ? body.sessionId.trim() : '';
+            const text = clampText(body.text, config.maxSelectionChars);
+            if (!sessionId || !text.trim()) {
+                sendJson(res, 200, { ok: true, matched: false, context: '', rounds: 0 });
+                return;
+            }
+            const events = await readSurfaceEvents(sessionId);
+            const context = quoteContextOf(events, text, {
+                roundsAround: config.quoteContextRounds,
+                maxCharsPerTurn: config.quoteContextMaxCharsPerTurn,
+                maxChars: config.quoteContextMaxChars,
+            });
+            sendJson(res, 200, {
+                ok: true,
+                matched: context.matched,
+                context: context.transcript,
+                rounds: context.rounds,
+                chars: context.transcript.length,
+            });
+        })().catch((error) => {
+            sendJson(res, 500, { ok: false, error: String(error?.message ?? error) });
+        });
+    };
+    /** 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) });
+        });
+    };
     const handleHistory = (req, res) => {
         void (async () => {
             await loadHistory();
@@ -1206,12 +1723,16 @@ export function apply(ctx, rawConfig) {
                     fetchBlocked,
                 },
                 sessionContext: config.sessionContext && typeof sessionQuery?.readSurface === 'function',
+                // 侧边栏 HTML 预览里的划词桥开关：客户端据此决定要不要往预览帧注入桥脚本
+                bridgeSidebarPreview: config.bridgeSidebarPreview,
                 limits: {
                     maxSelectionChars: config.maxSelectionChars,
                     maxContextChars: config.maxContextChars,
                     sessionContextMaxMessages: config.sessionContextMaxMessages,
                     sessionContextFastMessages: config.sessionContextFastMessages,
                     sessionContextMaxChars: config.sessionContextMaxChars,
+                    quoteContextRounds: config.quoteContextRounds,
+                    quoteContextMaxChars: config.quoteContextMaxChars,
                 },
             });
         })().catch((error) => {
@@ -1793,7 +2314,12 @@ export function apply(ctx, rawConfig) {
                     ...(sessionId ? { sessionId: sessionId } : {}),
                     system: undefined,
                     messages: [
-                        createSystemMessage(wrapUp
+                        // 第二参数（组装这段提示词的插件名）：**新老版本签名不一样，两边都得能编译**——
+                        //   · npm 上按 peer 范围 `>=0.1.5-rc <2` 解析到的是 0.1.5-rc.3：`(text, plugin)` 两个必填
+                        //     （CI 就是拿这份类型做构建校验的，少传就 TS2554）；
+                        //   · 本机 / 新版运行时（0.1.7-rc.x）：只剩 `(text)`，多传的参数会被忽略。
+                        // 所以统一走 systemMessageOf 这个宽松别名（见文件下方的定义），两边都调得动。
+                        systemMessageOf(wrapUp
                             ? `${systemPrompt}\n\n【收尾】工具轮次已用完：直接基于已经拿到的信息给出结论，不要再请求工具，也不要复述查询过程。` +
                                 '正文里不要出现任何工具调用格式（包括 DeepSeek 的 DSML 写法，如 invoke/parameter 标记）——那些会被当作乱码展示给用户。'
                             : systemPrompt, name),
@@ -2036,7 +2562,8 @@ export function apply(ctx, rawConfig) {
                             ...(sessionId ? { sessionId: sessionId } : {}),
                             system: undefined,
                             messages: [
-                                createSystemMessage(systemPrompt, name),
+                                // 同上：多传的插件名在老版本运行时会被忽略，新版本类型上却是必填
+                                systemMessageOf(systemPrompt, name),
                                 createUserMessage({ source: { kind: 'user' }, content: [{ type: 'text', text: conclusionUser }] }),
                             ],
                             ...(config.temperature >= 0 ? { temperature: config.temperature } : {}),
@@ -2143,6 +2670,10 @@ export function apply(ctx, rawConfig) {
     ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: `${API_PREFIX}/history`, handler: handleHistory }), `${name}: history route`);
     ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: `${API_PREFIX}/models`, handler: handleModels }), `${name}: models route`);
     ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: `${API_PREFIX}/promote`, handler: handlePromote }), `${name}: promote route`);
+    ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: `${API_PREFIX}/quote-context`, handler: handleQuoteContext }), `${name}: quote-context route`);
+    ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: `${API_PREFIX}/speech`, handler: handleSpeech }), `${name}: speech catalog route`);
+    ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: `${API_PREFIX}/speech/transcribe`, handler: handleSpeechTranscribe }), `${name}: speech transcribe route`);
+    ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: `${API_PREFIX}/speech/prepare`, handler: handleSpeechPrepare }), `${name}: speech prepare route`);
     ctx.logger?.info?.(`[${name}] 划词解读路由就绪：${API_PREFIX}/analyze`);
 }
 /**