@yfwu2020/dsh-selection-explain 0.10.3 → 0.10.5

package/lib/types/host/settings-store.d.ts

@@ -0,0 +1,8 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Config } from './config.js';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/** Owns settings-store state for one plugin instance. */
+export declare function createSettingsStore(ctx: Context, config: Config): {
+    loadSettings: () => Promise<void>;
+    handleSettings: (req: IncomingMessage, res: ServerResponse) => void;
+};

package/lib/types/host/speech.d.ts

@@ -0,0 +1,23 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Config } from './config.js';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/**
+ * 校验客户端送上来的音频是不是**规范**的 16kHz 单声道 PCM16 WAV。
+ *
+ * 为什么抠得这么死：这个格式是浏览器端编码器（MediaRecorder → decodeAudioData →
+ * OfflineAudioContext 重采样 → 手写 WAV 头）唯一会产出的形状。逐字段对齐之后，
+ * "音频不对"就只剩两种可能——客户端版本对不上、或者有人手工构造了这个请求。
+ * 光看二进制长度不算数：头里写的采样率/声道/位深必须是那一套，否则识别服务会按
+ * 错误的采样率解释这段音频（听起来像快放/慢放），识别结果自然全错。
+ *
+ * @param audio 完整音频字节
+ * @param maxSeconds 允许的最长时长
+ * @returns 时长（秒）
+ */
+export declare function validateWave(audio: Buffer, maxSeconds: number): number;
+/** Owns speech state for one plugin instance. */
+export declare function createSpeech(ctx: Context, config: Config): {
+    handleSpeech: (req: IncomingMessage, res: ServerResponse) => void;
+    handleSpeechTranscribe: (req: IncomingMessage, res: ServerResponse) => void;
+    handleSpeechPrepare: (req: IncomingMessage, res: ServerResponse) => void;
+};

package/lib/types/host/tools.d.ts

@@ -0,0 +1,39 @@
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import type { Context } from '@deepseek-ai/cordis';
+/**
+ * 决定这一轮给模型哪些工具（纯函数，便于单测）。
+ *
+ * 规则：
+ *   ① 首选清单里**确实存在**的直接放行；
+ *   ② 如果首选里的**联网工具一个都不在**（例如没装 free-search 插件），
+ *      就把备用清单里存在的补上 —— 否则小窗会变成完全不能联网；
+ *   ③ 备用只补"联网"这一类，不会顺手把别的东西带进来。
+ */
+export declare function resolveToolNames(preferred: string[], fallback: string[], visible: string[]): string[];
+export declare function webFetchUsable(): Promise<{
+    usable: boolean;
+    sample: string;
+}>;
+/**
+ * 路径是否落在允许的根目录里（root 为空 = 不设限）。
+ *
+ * 为什么需要它：read/grep/glob 能读**用户有权读的任何文件**（`~/.ssh/id_rsa`、`.env`、
+ * `~/.dsh/settings.yaml`……），而划词的触发源（选中文字/上下文/搜索结果）可能是别人写的。
+ * 这里只做词法判断（`resolve` 不跟随符号链接），挡住"顺着一段被注入的文字去读项目外的机密"。
+ */
+export declare function isInsideRoot(root: string, target: string): boolean;
+/** 文件类工具：这些工具的参数里有 path，需要过边界检查。 */
+export declare const FS_TOOL_NAMES: string[];
+/** 工具调用的人类可读描述（给前端状态栏用）。 */
+export declare function describeToolCall(name: string, args: unknown): string;
+/** 从工具结果里抽出：文本长度 / 预览 / 链接（前端只用它拼追问摘要，**不渲染**）。 */
+export declare function digestToolResult(content: ContentBlock[]): {
+    chars: number;
+    preview: string;
+    urls: string[];
+};
+/** 执行一个工具并把结果压成模型可读的内容块（带长度上限）。 */
+export declare function runTool(ctx: Context, name: string, args: unknown, signal: AbortSignal, maxChars: number, agent: unknown): Promise<{
+    content: ContentBlock[];
+    isError: boolean;
+}>;

package/lib/types/host/types.d.ts

@@ -0,0 +1,89 @@
+/** 一次请求的入参。 */
+export interface AnalyzeBody {
+    text?: unknown;
+    context?: unknown;
+    label?: unknown;
+    title?: unknown;
+    url?: unknown;
+    /** 当前会话 id（客户端从 ctx.sessions.list 快照取），用于拉取会话背景。 */
+    sessionId?: unknown;
+    /** 「重新生成」用：为 true 时跳过共享结果缓存。 */
+    refresh?: unknown;
+    /** 两阶段：'translation'（首轮，仅翻译 + 8 条背景）| 'detail'（按需，详解 + 完整背景）。 */
+    stage?: unknown;
+    /** 'code' | 'text'：选中文字是不是代码（代码走「注释」提示词：代码块 + 逐句注释 + 小结）。 */
+    kind?: unknown;
+    /** 本会话已用过的工具结果摘要（追问时带上，避免重复联网）。 */
+    toolDigest?: unknown;
+    /** 小窗对话历史（A′）：整段对话的持久化条目。 */
+    key?: unknown;
+    parts?: unknown;
+    pinned?: unknown;
+    /** 单次请求的推理档位覆盖（off / low / high / max）；不传用插件配置。 */
+    effort?: unknown;
+    /** 小窗的「模型」控件：显式指定 provider + model（按清单校验，缺省跟随会话默认）。 */
+    provider?: unknown;
+    model?: unknown;
+    /** 网页模式（小窗里的开关）：复杂问题默认用网页回答，并注入设计规范。 */
+    webAnswer?: unknown;
+    /** 客户端上报的当前深浅（'dark' | 'light'）：网页输出按它选配色。 */
+    theme?: unknown;
+    /** 追问模式下用户这一轮的问题。 */
+    question?: unknown;
+    /** 追问模式下的历史轮次：[{ role: 'user' | 'assistant', text }]。 */
+    history?: unknown;
+    /** 升格为正式会话时的入参。 */
+    translation?: unknown;
+    detail?: unknown;
+    turns?: unknown;
+    /** 诊断开关：为 true 时把实际发给模型的提示词回传在 SSE 的 start 事件里（客户端不传）。 */
+    debug?: unknown;
+}
+/** 会话背景读取结果。 */
+export interface SessionBackground {
+    /** 已格式化的对话记录（时间顺序，最后一条最新）。 */
+    transcript: string;
+    /** 是否在记录里标出了选中文字所在的消息。 */
+    marked: boolean;
+}
+/** 会话背景读取入参。 */
+export interface BackgroundOptions {
+    maxMessages: number;
+    maxChars: number;
+    /** 用于在记录里定位选中位置（归一化后做包含匹配）。 */
+    marker: string;
+}
+/**
+ * ctx.sessionQuery 的宽松视图。
+ *
+ *   · readSurface —— 会话的**消息表面**（对话背景用）。
+ *   · readSession —— **原始事件**（带 data）。读会话模型必须走它：
+ *     `model/selection` 在文档里写明是 log-only，"never enters derived model history"，
+ *     所以它**不会**出现在 readSurface 的 surface 里（实测：用它读到的永远是空）。
+ */
+export interface SessionQueryLike {
+    readSurface?: (sessionId: string) => Promise<{
+        events?: readonly unknown[];
+    }>;
+    readSession?: (sessionId: string) => Promise<{
+        events?: readonly unknown[];
+    }>;
+}
+/**
+ * ctx.sessions 的宽松视图 —— 只用来做"会话有没有新事件"的零成本探测。
+ *
+ * `seq` 是 Session 上的 getter（= 日志长度，每次 append 都会涨），同步读、不碰日志；
+ * 拿它跟上次解析时记下的值一比，就知道"结论有没有可能变"（见 liveSeqOf）。
+ */
+export interface SessionsLike {
+    get?: (sessionId: string) => {
+        seq?: number;
+    } | undefined;
+}
+/** 解析出的模型路由。 */
+export interface Route {
+    provider: string;
+    model: string;
+}
+/** 会话自己记的模型选择（与 Route 同形，单独取名是为了在注释里说清"来源不同"）。 */
+export type SessionModel = Route;

package/lib/types/index.d.ts

@@ -1,444 +1,15 @@
-import type { Context } from '@deepseek-ai/cordis';
-import type { WebServer } from '@deepseek-ai/dsh-host-webserver';
-import z from '@deepseek-ai/schemastery';
-/** 插件名（= package.json name，客户端 bundle 的模块 id 也是它）。 */
-export declare const name = "@yfwu2020/dsh-selection-explain";
-/**
- * 升格时那条「上下文注入」消息的 `source.kind` —— 生产者**自有**的来源标识。
- *
- * 会话格式 v4 起（本机实测内核 0.2.0-rc.2），消息来源必须是生产者自报的 kind；
- * v3 那种 `plugin` 包装（`kind: 'plugin'` 配一个 `plugin` 字段）已经退役，会被
- * v4 准入当场拒掉：
- *   SessionFormatError: format v4 message requires a producer-owned source kind
- * 症状极具迷惑性：`↗ 升格` 的 HTTP 请求返回 `ok: true`（那时只写进了内存里的会话面），
- * 随后那轮 opener 运行失败、整个 artifact 一个字都没落盘 —— 新会话只剩表头。
- * 离线测试也照样全绿（校验发生在真实内核里，不在构建期），所以另配了
- * scripts/test-format.mjs 钉住这个 shape。
- *
- * 第三方插件的规范形态是 `plugin:<插件名>`：内核 v3→v4 迁移把那种 `plugin` 包装
- * 重写成 `plugin:<完整插件名>`（`producerKind()` 对不在同名表里的插件就是这么算的），
- * 所以这里写的与迁移结果逐字节一致 —— 新旧会话归因相同，且 v3 内核下同样合法
- * （直写的 kind 迁移时原样保留）。
- */
-export declare const PLUGIN_SOURCE_KIND = "plugin:@yfwu2020/dsh-selection-explain";
-/** 路由注册与模型调用所需的服务。 */
-export declare const inject: string[];
-/** 插件配置。 */
-export interface Config {
-    /** 固定 provider 路由；留空 = 跟随主会话（用户在 DSH 里选的默认模型）。 */
-    provider: string;
-    /** 固定 model id；留空 = 跟随主会话。 */
-    model: string;
-    /**
-     * **追问**单独用的 provider；留空 = 跟首轮/次轮同一个（默认如此）。
-     *
-     * 为什么要能单独设：首轮/次轮要的是"读懂上下文"，追问往往是"快速问一句"，
-     * 两者对模型的要求不同（一个要准、一个要快）。
-     */
-    chatProvider: string;
-    /** **追问**单独用的 model id；留空 = 跟首轮/次轮同一个。 */
-    chatModel: string;
-    /** **次轮详解**的推理档位（off / low / high / max）；留空 = 适配器默认。 */
-    reasoningEffort: string;
-    /** **首轮**（翻译 / 解读 / 注释）的推理档位。 */
-    translationReasoningEffort: string;
-    historyMaxEntries: number;
-    /** 采样温度。 */
-    temperature: number;
-    /** 输出上限。 */
-    maxTokens: number;
-    /** 单次调用超时（毫秒）。 */
-    timeoutMs: number;
-    /** 选中文字长度上限（字符）。 */
-    maxSelectionChars: number;
-    /** 上下文长度上限（字符）。 */
-    maxContextChars: number;
-    /** 每分钟最大请求数（本地限流，防止误触发刷爆额度）。 */
-    maxRequestsPerMinute: number;
-    /** 是否注入当前会话的对话背景（判断指代与前提的关键）。 */
-    sessionContext: boolean;
-    /** 会话背景最多保留多少条消息（从最新往前取）；第二阶段（详解）用这个值。 */
-    sessionContextMaxMessages: number;
-    /** 第一阶段（仅翻译）用的背景条数：更少 → 首字更快；点「展开详解」时才用上面那个上限。 */
-    sessionContextFastMessages: number;
-    /** 会话背景字符上限；0 = 不限（默认），只按消息条数取窗口。 */
-    sessionContextMaxChars: number;
-    /**
-     * 引用（❝）上下文：引用文字所在的那一组对话 ± 几组（一组 = 用户消息 + 它的助手回复）。
-     * 默认 1 = 上下各一组（需求：至少带上引用所在那一组与上下各一组）。
-     */
-    quoteContextRounds: number;
-    /** 引用上下文里单条消息的字数上限（超了**围绕引用**截断，不裁掉引用本身）。 */
-    quoteContextMaxCharsPerTurn: number;
-    /** 引用上下文整段的字数上限（超了丢最早的几组）。 */
-    quoteContextMaxChars: number;
-    /** 共享结果缓存 TTL（毫秒）：同会话+同选中+同局部片段+同背景时直接回放；0 = 关闭。 */
-    resultCacheTtlMs: number;
-    /** 是否允许解读过程调用工具（联网搜索等）。 */
-    tools: boolean;
-    /** 允许调用的工具名（逗号分隔）；默认只放联网搜索与抓取。 */
-    toolNames: string;
-    fallbackToolNames: string;
-    /** 最多几轮工具调用。 */
-    maxToolRounds: number;
-    /** 单个工具结果注入模型前的字符上限。 */
-    toolResultMaxChars: number;
-    /** 文件类工具（read/grep/glob）的读取边界：'' = 会话工作目录，'*' = 不限制，其他 = 该目录 */
-    toolReadRoot: string;
-    /** 追问（对话小窗）用的推理档位：通常比次轮详解轻，响应更快。 */
-    chatReasoningEffort: string;
-    /**
-     * 侧边栏 HTML 预览里的划词桥（默认开）。
-     *
-     * 侧边栏的预览是不透明源沙箱 iframe，父页面读不到里面的选区 —— 只有往被预览的
-     * 文档里注入一段桥脚本才能划词。代价：预览帧要多一个 `allow-scripts`
-     * （仍然**没有** `allow-same-origin`，预览页读不到 GUI 数据），基础预览那份
-     * 已清洗过的 HTML 的 CSP 会从 `script-src 'none'` 放宽到 `'unsafe-inline'`。
-     * 关掉 = 侧边栏网页里不弹「解读」按钮。
-     */
-    bridgeSidebarPreview: boolean;
-    /** 是否显示右下角悬浮胶囊（最近一次划词的状态入口）。 */
-    pillEnabled: boolean;
-    /**
-     * 静置多久把胶囊收成小球（毫秒）。
-     *
-     * 只在**没装费用胶囊**时生效 —— 有费用胶囊时两者并排，收球会让它们错位。
-     * 默认 10 秒：短于这个数会显得"刚看一眼就没了"，长了又失去"收起来不挡视线"的意义。
-     */
-    pillIdleMs: number;
-    /**
-     * 开麦结束、**一个字都没说**时，直接收起临时输入框。
-     *
-     * 默认开（2026-10-09 用户指定）：等于替用户按了 Esc（带关机动画）。
-     * 关掉则回到"卡片留着" —— 一个字没说时可以接着手动打字。
-     *
-     * 注意"结束"不是"松手那一瞬间"：输入法在松手后还会做一次**智能整理**（改写输入框内容），
-     * 所以真正动作要等到文字定稿（见客户端的 VOICE_SETTLE_MS）。否则会取消掉马上就要落进来的整理结果。
-     */
-    voiceCancelOnSilence: boolean;
-    /**
-     * 开麦结束、**已经说出文字**时，直接发送（跳过手动点发送键）。
-     *
-     * 默认开（2026-10-09 用户指定）：等于替用户点了发送键。
-     * 关掉则回到"先看一眼再点" —— 发送会开小窗、开始一次真实请求，不可逆。
-     *
-     * 同样要等文字定稿：松手那一刻输入法还没整理完，立刻发送发出去的是没整理的草稿。
-     */
-    voiceAutoSend: boolean;
-}
-/** 配置 schema（缺省值即推荐值）。 */
-export declare const Config: z<Schemastery.ObjectS<{
-    provider: z<string, string>;
-    model: z<string, string>;
-    chatProvider: z<string, string>;
-    chatModel: z<string, string>;
-    reasoningEffort: z<string, string>;
-    /** 首轮单独一档：默认关闭思考，优先快速给出翻译、解读或注释。 */
-    translationReasoningEffort: z<string, string>;
-    /**
-     * 小窗对话历史（A′）：把整段对话落到插件自己的目录，重划同一个词直接回放。
-     * 0 = 关闭历史。只留最近 N 个「划词条目」（每个条目内含它自己的全部追问轮次）。
-     */
-    historyMaxEntries: z<number, number>;
-    /** 采样温度。**默认 -1 = 不传**（交给供应商默认，与主会话一致）。0~2 之间才真的传。 */
-    temperature: z<number, number>;
-    /**
-     * 单次调用的输出上限（tokens）。**默认 0 = 不限制** —— 不传这个参数，交给模型/供应商自己的上限。
-     *
-     * 为什么不默认给个数：这是**每次调用**的上限，联网检索后的答案经常要 2~4k tokens，
-     * 之前默认 1200 会让回答"悄悄截断在句子中间"（实测）；而给死一个更大的数也一样会在别的场景截断。
-     * 想限制（控成本/控时延）就填正数，仍然生效。
-     */
-    maxTokens: z<number, number>;
-    timeoutMs: z<number, number>;
-    maxSelectionChars: z<number, number>;
-    maxContextChars: z<number, number>;
-    maxRequestsPerMinute: z<number, number>;
-    sessionContext: z<boolean, boolean>;
-    sessionContextMaxMessages: z<number, number>;
-    sessionContextFastMessages: z<number, number>;
-    sessionContextMaxChars: z<number, number>;
-    quoteContextRounds: z<number, number>;
-    quoteContextMaxCharsPerTurn: z<number, number>;
-    quoteContextMaxChars: z<number, number>;
-    resultCacheTtlMs: z<number, number>;
-    tools: z<boolean, boolean>;
-    /**
-     * 工具白名单（逗号分隔）。
-     *
-     * 默认改用 **free-search 插件**的工具（`advanced_search` / `platform_search`），不再用 `web_search`：
-     * 会话里的 `web_search` 是官方 DeepSeek 搜索（复用 @deepseek-ai/dsh-tool-web 的 schema），
-     * 而新装的 dsh-free-search 只注册了 advanced_search / platform_search / free_search_test ——
-     * 引擎更多（ddg/bing/searxng/anysearch/exa/tavily/keenable/firecrawl/parallel…）、失败自动换引擎、
-     * 还支持时间过滤与平台搜索。
-     */
-    toolNames: z<string, string>;
-    /**
-     * **备用**工具清单：只在"首选里的联网工具一个都不在"时才补进来。
-     *
-     * 场景：没装 free-search 插件（或它没注册工具）时，会话里通常仍有官方 `web_search`；
-     * 不补的话小窗会变成完全不能联网。装了 free-search 就完全用不到这一项。
-     */
-    fallbackToolNames: z<string, string>;
-    maxToolRounds: z<number, number>;
-    toolResultMaxChars: z<number, number>;
-    toolReadRoot: z<string, string>;
-    chatReasoningEffort: z<string, string>;
-    /**
-     * 侧边栏 HTML 预览里的划词桥。关掉就不往预览帧里注入桥脚本，
-     * 侧边栏网页里选中文字不会再弹「解读」。
-     */
-    bridgeSidebarPreview: z<boolean, boolean>;
-    /** 悬浮胶囊开关（小窗设置页可改）。 */
-    pillEnabled: z<boolean, boolean>;
-    /** 静置收球时长（毫秒）——默认 10 秒，见 Config 注释。 */
-    pillIdleMs: z<number, number>;
-    /** 空录音是否收起卡片（默认开，见 Config 注释）。 */
-    voiceCancelOnSilence: z<boolean, boolean>;
-    /** 有字是否自动发送（默认开，见 Config 注释）。 */
-    voiceAutoSend: z<boolean, boolean>;
-}>, Schemastery.ObjectT<{
-    provider: z<string, string>;
-    model: z<string, string>;
-    chatProvider: z<string, string>;
-    chatModel: z<string, string>;
-    reasoningEffort: z<string, string>;
-    /** 首轮单独一档：默认关闭思考，优先快速给出翻译、解读或注释。 */
-    translationReasoningEffort: z<string, string>;
-    /**
-     * 小窗对话历史（A′）：把整段对话落到插件自己的目录，重划同一个词直接回放。
-     * 0 = 关闭历史。只留最近 N 个「划词条目」（每个条目内含它自己的全部追问轮次）。
-     */
-    historyMaxEntries: z<number, number>;
-    /** 采样温度。**默认 -1 = 不传**（交给供应商默认，与主会话一致）。0~2 之间才真的传。 */
-    temperature: z<number, number>;
-    /**
-     * 单次调用的输出上限（tokens）。**默认 0 = 不限制** —— 不传这个参数，交给模型/供应商自己的上限。
-     *
-     * 为什么不默认给个数：这是**每次调用**的上限，联网检索后的答案经常要 2~4k tokens，
-     * 之前默认 1200 会让回答"悄悄截断在句子中间"（实测）；而给死一个更大的数也一样会在别的场景截断。
-     * 想限制（控成本/控时延）就填正数，仍然生效。
-     */
-    maxTokens: z<number, number>;
-    timeoutMs: z<number, number>;
-    maxSelectionChars: z<number, number>;
-    maxContextChars: z<number, number>;
-    maxRequestsPerMinute: z<number, number>;
-    sessionContext: z<boolean, boolean>;
-    sessionContextMaxMessages: z<number, number>;
-    sessionContextFastMessages: z<number, number>;
-    sessionContextMaxChars: z<number, number>;
-    quoteContextRounds: z<number, number>;
-    quoteContextMaxCharsPerTurn: z<number, number>;
-    quoteContextMaxChars: z<number, number>;
-    resultCacheTtlMs: z<number, number>;
-    tools: z<boolean, boolean>;
-    /**
-     * 工具白名单（逗号分隔）。
-     *
-     * 默认改用 **free-search 插件**的工具（`advanced_search` / `platform_search`），不再用 `web_search`：
-     * 会话里的 `web_search` 是官方 DeepSeek 搜索（复用 @deepseek-ai/dsh-tool-web 的 schema），
-     * 而新装的 dsh-free-search 只注册了 advanced_search / platform_search / free_search_test ——
-     * 引擎更多（ddg/bing/searxng/anysearch/exa/tavily/keenable/firecrawl/parallel…）、失败自动换引擎、
-     * 还支持时间过滤与平台搜索。
-     */
-    toolNames: z<string, string>;
-    /**
-     * **备用**工具清单：只在"首选里的联网工具一个都不在"时才补进来。
-     *
-     * 场景：没装 free-search 插件（或它没注册工具）时，会话里通常仍有官方 `web_search`；
-     * 不补的话小窗会变成完全不能联网。装了 free-search 就完全用不到这一项。
-     */
-    fallbackToolNames: z<string, string>;
-    maxToolRounds: z<number, number>;
-    toolResultMaxChars: z<number, number>;
-    toolReadRoot: z<string, string>;
-    chatReasoningEffort: z<string, string>;
-    /**
-     * 侧边栏 HTML 预览里的划词桥。关掉就不往预览帧里注入桥脚本，
-     * 侧边栏网页里选中文字不会再弹「解读」。
-     */
-    bridgeSidebarPreview: z<boolean, boolean>;
-    /** 悬浮胶囊开关（小窗设置页可改）。 */
-    pillEnabled: z<boolean, boolean>;
-    /** 静置收球时长（毫秒）——默认 10 秒，见 Config 注释。 */
-    pillIdleMs: z<number, number>;
-    /** 空录音是否收起卡片（默认开，见 Config 注释）。 */
-    voiceCancelOnSilence: z<boolean, boolean>;
-    /** 有字是否自动发送（默认开，见 Config 注释）。 */
-    voiceAutoSend: z<boolean, boolean>;
-}>>;
-/**
- * 决定这一轮给模型哪些工具（纯函数，便于单测）。
- *
- * 规则：
- *   ① 首选清单里**确实存在**的直接放行；
- *   ② 如果首选里的**联网工具一个都不在**（例如没装 free-search 插件），
- *      就把备用清单里存在的补上 —— 否则小窗会变成完全不能联网；
- *   ③ 备用只补"联网"这一类，不会顺手把别的东西带进来。
- */
-declare function resolveToolNames(preferred: string[], fallback: string[], visible: string[]): string[];
-/** 会话背景读取结果。 */
-interface SessionBackground {
-    /** 已格式化的对话记录（时间顺序，最后一条最新）。 */
-    transcript: string;
-    /** 是否在记录里标出了选中文字所在的消息。 */
-    marked: boolean;
-}
-/** 会话背景读取入参。 */
-interface BackgroundOptions {
-    maxMessages: number;
-    maxChars: number;
-    /** 用于在记录里定位选中位置（归一化后做包含匹配）。 */
-    marker: string;
-}
-declare function createThinkFilter(): {
-    push: (text: string) => {
-        text: string;
-        think: string;
-    };
-    flush: () => {
-        text: string;
-        think: string;
-    };
-};
-/**
- * 宽松判据：开头是**英文盘算**、后面才是**中文答案**。
- * 只用来"记住这个模型在关档会泄漏"（下次自动抬档），**不用来裁剪** ——
- * 裁错了会误删正文，而记错了只是下次少一个档位可选，代价不对称。
- */
-declare function looksLikeLeakedReasoning(text: string): boolean;
-/**
- * 规范四格 → 当前模型**真实声明**的档位（返回 '' 表示这个模型没有可发的档位）。
- *
- * 规则一条到底（对 `off>low>high>max` 这类 4 档模型恰好是恒等映射）：
- *   · 关   → 声明里**最弱**的那档（模型没有 off 这类档时，就是它"能关到"的最小思考）
- *   · 最高 → 声明里**最强**的那档
- *   · 低/高 → 在整条刻度上取 1/3、2/3 处**最近的档**；候选**排除两端**（最弱那档留给「关」、
- *     最强那档留给「最高」，四个格子于是各有落点），并保证 关 ≤ 低 ≤ 高 ≤ 最高 单调；
- *     同样近时「低」取更浅的、「高」取更深的 —— 低要省、高要深。
- *
- * ⚠️ 这里**没有**任何按模型写死的表：输入只有"这个模型自己声明的档位列表"。
- * 名字认得出来（off/low/high/max、minimal、xhigh…）就用名字的深度刻度；认不出来
- * （别的 adapter 可能叫 a/b/c、tier1/tier2，或者干脆是数字）就按**它在声明里的位置**插值 ——
- * 所以任何用户换任何模型都能落位，插件作者没见过那个模型也能映射。
- * 为什么不让「低/高」也去抢最弱那档：那两个格子表达的是"开着思考、但别太深"，
- * 落到"关"那一档等于**把用户要的思考关掉**；只有「关」该动那一档。
- * 只有一档可发时（如 kimi-k3 只有 max），四格都落到它 —— 模型没有别的选择。
- *
- * 返回 '' 表示"这个模型没有可发的档位"（声明为空），调用方据此**不带** reasoningEffort。
- */
-declare function mapEffortToModel(declared: Array<{
-    id: string;
-    name?: string;
-}>, canonical: string): string;
-/**
- * 一个模型的四格映射（设置页给用户看的就是它；请求时也走这份算）。
- * 返回空串的格子表示"没有可发的档位"（模型不支持推理时四个格子都是空串）。
- */
-declare function effortMapOf(declared: Array<{
-    id: string;
-    name?: string;
-}>): Record<string, string>;
-/**
- * 这条上游错误是不是"**我们发的这个档位**不被接受"。
- *
- * ⚠️ 判据必须窄。免费/预览端点的上游会**偶发**返回
- * `Reasoning is mandatory for this endpoint and cannot be disabled.` ——
- * 2026-10-09 实测（`opencode-go/step-5-preview-free`，交错发送排除时间漂移）：
- *   · effort=low 成功 5/8；effort=high 成功 5/8 —— **同一档位时好时坏，档位不是变量**；
- *   · 对照模型 `longcat-2.5-preview-free` 6/6 成功（连 off 都收）。
- * 所以只认"明确说这个档位无效"的措辞；"必须开推理"另有一条判据
- * （见 looksLikeReasoningRequired，只在**我们发的是关档**时才算数）。
- * 把偶发失败当成"档位不支持"会连锁出三个错：给用户一句错诊断、把失败永久记进
- * noOffRoutes（以后再也不发这个档）、清掉用户选的档位。
- */
-declare function looksLikeUnsupportedTier(message: string): boolean;
-/** 上游要求"必须开推理"——只有在**我们这次把推理关掉**（发的 off）时，这句才是冲我们来的。 */
-declare function looksLikeReasoningRequired(message: string): boolean;
-/**
- * 换一个"没试过的"档位（重试用）。
- *
- * 为什么**绝不能省略档位**（老代码就是省略）：省略 = 请求里不带 reasoning，
- * 对"必须开推理"的端点等于把推理关掉 —— 实测 20 次这样的重试 **0 次成功**，
- * 而同一档位首发成功率约 60%。省略比"发一个可能不被接受的档"更糟。
- *
- * 顺序：模型自己声明的 defaultEffort → 沿档位阶梯往上走一格（离"关"越远越安全）。
- * 返回空串表示"没档位可换了"，调用方就不重试。
- */
-declare function pickNextEffort(declared: string[], defaultEffort: string | null | undefined, rejected: string, tried: Set<string>): string;
-declare function splitLeakedReasoning(text: string): {
-    prefix: string;
-    rest: string;
-};
-/**
- * 校验客户端送上来的音频是不是**规范**的 16kHz 单声道 PCM16 WAV。
- *
- * 为什么抠得这么死：这个格式是浏览器端编码器（MediaRecorder → decodeAudioData →
- * OfflineAudioContext 重采样 → 手写 WAV 头）唯一会产出的形状。逐字段对齐之后，
- * "音频不对"就只剩两种可能——客户端版本对不上、或者有人手工构造了这个请求。
- * 光看二进制长度不算数：头里写的采样率/声道/位深必须是那一套，否则识别服务会按
- * 错误的采样率解释这段音频（听起来像快放/慢放），识别结果自然全错。
- *
- * @param audio 完整音频字节
- * @param maxSeconds 允许的最长时长
- * @returns 时长（秒）
- */
-export declare function validateWave(audio: Buffer, maxSeconds: number): number;
-/**
- * 路径是否落在允许的根目录里（root 为空 = 不设限）。
- *
- * 为什么需要它：read/grep/glob 能读**用户有权读的任何文件**（`~/.ssh/id_rsa`、`.env`、
- * `~/.dsh/settings.yaml`……），而划词的触发源（选中文字/上下文/搜索结果）可能是别人写的。
- * 这里只做词法判断（`resolve` 不跟随符号链接），挡住"顺着一段被注入的文字去读项目外的机密"。
- */
-export declare function isInsideRoot(root: string, target: string): boolean;
-/**
- * 把会话的当前模型界面整理成「会话背景」文本。
- *
- * 只保留**真实对话**：用户真正发的话（source.kind === 'user'）与助手回复的正文。
- * 三类内容一律剔除，否则会把有效窗口挤没（实测：430 条 surface 事件里绝大多数是
- * 工具调用/结果，且 harness 注入的 system-reminder 单条可达 1.2 万字）：
- *   - tool/result 与纯工具调用的助手步骤（无正文）
- *   - system/message（系统提示词）
- *   - source.kind !== 'user' 的用户角色消息（运行环境快照、skill 目录等 harness 注入）
- */
-export declare function transcriptOf(events: readonly unknown[], options: BackgroundOptions): SessionBackground;
-/** 引用上下文的结果。 */
-export interface QuoteContext {
-    /** 「用户：…／助手：…」逐行拼好的上下文（引用部分用【】标出）；没命中时为空串。 */
-    transcript: string;
-    /** 引用文字是否在会话里定位到了（没定位到 → 客户端退回自己的局部上下文）。 */
-    matched: boolean;
-    /** 带进来的对话组数（一组 = 一条用户消息 + 它的助手回复）。 */
-    rounds: number;
-}
-/** 引用上下文的窗口与长度（默认值：上下各一组、单条 2000 字、总共 6000 字）。 */
-export interface QuoteContextOptions {
-    /** 引用前后各取几组对话（默认 1）。 */
-    roundsAround?: number;
-    /** 单条消息的字数上限（超出时**围绕引用**截断，别把引用本身裁掉）。 */
-    maxCharsPerTurn?: number;
-    /** 整段上下文的字数上限（超出时丢最早的那几组）。 */
-    maxChars?: number;
-}
-/**
- * **引用上下文**：引用文字所在的那一组对话 ± N 组（一组 = 一条用户消息 + 它的助手回复）。
- *
- * 与 `transcriptOf`（解读用的会话背景）的区别，两条都是为引用量身定的：
- *   ① 窗口是**锚点两侧** —— 引用常常是"上面那句"和"下面那句"的对照，只有上文不够；
- *   ② 按**轮**取整 —— 上下各至少一整组（用户消息 + AI 回复），不会切在半个回合上。
- * 噪音过滤与 `transcriptOf` 完全一致（工具调用/结果、系统提示、harness 注入一律不进）。
- */
-export declare function quoteContextOf(events: readonly unknown[], marker: string, options?: QuoteContextOptions): QuoteContext;
-/** 注册路由、解析模型路由、转发 LLM 流。 */
-export declare function apply(ctx: Context, rawConfig: Config): void;
-/** 类型引用（供声明文件 re-export，避免仅用于类型增强的 import 被判为未使用）。 */
-export type { WebServer };
-/**
- * 纯函数内部件，仅供单测直接调用（Cordis 只用 default export，多这几个具名导出没有副作用）。
- * 这三个都是"流式文本手术刀"，靠真实请求验证会被模型的随机发挥带偏，必须能确定性单测。
- */
+/** Public DSH plugin entry; implementation lives in host/. */
+export { name, inject, PLUGIN_SOURCE_KIND } from './host/constants.js';
+export { Config } from './host/config.js';
+export { apply } from './host/plugin.js';
+export { validateWave } from './host/speech.js';
+export { isInsideRoot } from './host/tools.js';
+export { transcriptOf, quoteContextOf } from './host/context.js';
+export type { QuoteContext, QuoteContextOptions } from './host/context.js';
+export type { WebServer } from '@deepseek-ai/dsh-host-webserver';
+import { createThinkFilter, splitLeakedReasoning, looksLikeLeakedReasoning } from './host/filters.js';
+import { resolveToolNames } from './host/tools.js';
+import { looksLikeUnsupportedTier, looksLikeReasoningRequired, pickNextEffort, mapEffortToModel, effortMapOf } from './host/effort.js';
 export declare const __internals: {
     createThinkFilter: typeof createThinkFilter;
     splitLeakedReasoning: typeof splitLeakedReasoning;

package/lib/types/prompts.d.ts

@@ -9,7 +9,7 @@
  *
  * 改动提示词的注意事项：
  *   · 结构契约由客户端解析（按 `## 翻译` / `## 详解` 标题切分），改标题会同时影响渲染；
- *   · scripts/test-prompt.mjs 里有"提示词契约测试"——删掉关键约束会直接 FAIL；
+ *   · tests/unit/prompt.test.mjs 里有"提示词契约测试"——删掉关键约束会直接 FAIL；
  *   · 想知道模型**实际收到**什么（含 harness 注入与会话背景拼接结果），跑
  *     `node scripts/dump-prompt.mjs --all`（需要 DSH 正在运行）。
  */

package/lib/types/settings.d.ts

@@ -5,7 +5,7 @@
  *   · 小窗设置页要渲染 20+ 个字段，字段的标题 / 说明 / 单位 / 边界**必须**与 host 的
  *     校验规则是同一份数据 —— 分两处写迟早会漂（UI 说 1~600，host 却按 1~200 截断）。
  *     所以 GET /settings 直接把这份 spec 发给客户端，客户端只负责画，不做业务判断。
- *   · 纯数据 + 纯函数，不 import cordis / node，单测可以直接跑（见 scripts/test-settings.mjs）。
+ *   · 纯数据 + 纯函数，仅依赖共享配置，不 import cordis / node，单测可以直接跑（见 tests/unit/settings.test.mjs）。
  *
  * 分组是**导航结构**，不是装饰：20+ 项平铺会淹没用户，按"用户想去哪类事"分 6 组。
  */