@yfwu2020/dsh-selection-explain 0.10.4 → 0.10.6

package/lib/types/config-values.d.ts

@@ -0,0 +1,175 @@
+/** Shared defaults and boundaries; no host or browser dependencies. */
+/** 插件配置。 */
+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;
+}
+export declare const CONFIG_DEFAULTS: Readonly<Config>;
+export declare const CONFIG_LIMITS: {
+    readonly historyMaxEntries: {
+        readonly min: 0;
+        readonly max: 500;
+    };
+    readonly temperature: {
+        readonly min: -1;
+        readonly max: 2;
+    };
+    readonly maxTokens: {
+        readonly min: 0;
+        readonly max: 32000;
+    };
+    readonly timeoutMs: {
+        readonly min: 5000;
+        readonly max: 600000;
+    };
+    readonly maxSelectionChars: {
+        readonly min: 20;
+        readonly max: 20000;
+    };
+    readonly maxContextChars: {
+        readonly min: 200;
+        readonly max: 60000;
+    };
+    readonly maxRequestsPerMinute: {
+        readonly min: 1;
+        readonly max: 600;
+    };
+    readonly sessionContextMaxMessages: {
+        readonly min: 1;
+        readonly max: 200;
+    };
+    readonly sessionContextFastMessages: {
+        readonly min: 1;
+        readonly max: 200;
+    };
+    readonly sessionContextMaxChars: {
+        readonly min: 0;
+        readonly max: 2000000;
+    };
+    readonly quoteContextRounds: {
+        readonly min: 0;
+        readonly max: 10;
+    };
+    readonly quoteContextMaxCharsPerTurn: {
+        readonly min: 200;
+        readonly max: 20000;
+    };
+    readonly quoteContextMaxChars: {
+        readonly min: 400;
+        readonly max: 100000;
+    };
+    readonly resultCacheTtlMs: {
+        readonly min: 0;
+        readonly max: 86400000;
+    };
+    readonly maxToolRounds: {
+        readonly min: 0;
+        readonly max: 8;
+    };
+    readonly toolResultMaxChars: {
+        readonly min: 200;
+        readonly max: 20000;
+    };
+    readonly pillIdleMs: {
+        readonly min: 2000;
+        readonly max: 600000;
+    };
+};

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

@@ -0,0 +1,10 @@
+import type { createHistoryStore } from './history-store.js';
+import type { createSessions } from './sessions.js';
+import type { createModels } from './models.js';
+import type { Context } from '@deepseek-ai/cordis';
+import type { Config } from './config.js';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/** Owns analyze state for one plugin instance. */
+export declare function createAnalyze(ctx: Context, config: Config, models: ReturnType<typeof createModels>, sessions: ReturnType<typeof createSessions>, historyStore: ReturnType<typeof createHistoryStore>): {
+    handleAnalyze: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+};

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

@@ -0,0 +1,147 @@
+import z from '@deepseek-ai/schemastery';
+import type { Config as PluginConfig } from '../config-values.js';
+export type Config = PluginConfig;
+/** 配置 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>;
+}>>;
+/** Preserve nullish-default semantics without duplicating the defaults. */
+export declare function resolveConfig(rawConfig?: Partial<Config>): Config;

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

@@ -0,0 +1,24 @@
+/** 插件名（= 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 一个字都没落盘 —— 新会话只剩表头。
+ * 离线测试也照样全绿（校验发生在真实内核里，不在构建期），所以另配了
+ * tests/unit/format.test.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 declare const API_PREFIX = "/selection-explain/api";

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

@@ -0,0 +1,41 @@
+import type { AnalyzeBody, BackgroundOptions, SessionBackground } from './types.js';
+/** 请求里带的会话 id（空串 = 客户端没取到）。 */
+export declare function sessionIdOf(body: AnalyzeBody): string;
+/**
+ * 把会话的当前模型界面整理成「会话背景」文本。
+ *
+ * 只保留**真实对话**：用户真正发的话（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;

package/lib/types/host/design-skill.d.ts

@@ -0,0 +1 @@
+export declare function loadDesignSkill(): Promise<string>;

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

@@ -0,0 +1,61 @@
+/**
+ * 规范四格 → 当前模型**真实声明**的档位（返回 '' 表示这个模型没有可发的档位）。
+ *
+ * 规则一条到底（对 `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。
+ */
+export declare function mapEffortToModel(declared: Array<{
+    id: string;
+    name?: string;
+}>, canonical: string): string;
+/**
+ * 一个模型的四格映射（设置页给用户看的就是它；请求时也走这份算）。
+ * 返回空串的格子表示"没有可发的档位"（模型不支持推理时四个格子都是空串）。
+ */
+export declare function effortMapOf(declared: Array<{
+    id: string;
+    name?: string;
+}>): Record<string, string>;
+/** 档位的中文名（notice 文案用，与客户端 TIER_LABEL 一致）。 */
+export declare const EFFORT_LABEL: 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（以后再也不发这个档）、清掉用户选的档位。
+ */
+export declare function looksLikeUnsupportedTier(message: string): boolean;
+/** 上游要求"必须开推理"——只有在**我们这次把推理关掉**（发的 off）时，这句才是冲我们来的。 */
+export declare function looksLikeReasoningRequired(message: string): boolean;
+/**
+ * 换一个"没试过的"档位（重试用）。
+ *
+ * 为什么**绝不能省略档位**（老代码就是省略）：省略 = 请求里不带 reasoning，
+ * 对"必须开推理"的端点等于把推理关掉 —— 实测 20 次这样的重试 **0 次成功**，
+ * 而同一档位首发成功率约 60%。省略比"发一个可能不被接受的档"更糟。
+ *
+ * 顺序：模型自己声明的 defaultEffort → 沿档位阶梯往上走一格（离"关"越远越安全）。
+ * 返回空串表示"没档位可换了"，调用方就不重试。
+ */
+export declare function pickNextEffort(declared: string[], defaultEffort: string | null | undefined, rejected: string, tried: Set<string>): string;

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

@@ -0,0 +1,20 @@
+export declare function createThinkFilter(): {
+    push: (text: string) => {
+        text: string;
+        think: string;
+    };
+    flush: () => {
+        text: string;
+        think: string;
+    };
+};
+/**
+ * 宽松判据：开头是**英文盘算**、后面才是**中文答案**。
+ * 只用来"记住这个模型在关档会泄漏"（下次自动抬档），**不用来裁剪** ——
+ * 裁错了会误删正文，而记错了只是下次少一个档位可选，代价不对称。
+ */
+export declare function looksLikeLeakedReasoning(text: string): boolean;
+export declare function splitLeakedReasoning(text: string): {
+    prefix: string;
+    rest: string;
+};

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

@@ -0,0 +1,13 @@
+import type { createSettingsStore } from './settings-store.js';
+import type { createModels } from './models.js';
+import type { Context } from '@deepseek-ai/cordis';
+import type { Config } from './config.js';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/** Owns history-store state for one plugin instance. */
+export declare function createHistoryStore(ctx: Context, config: Config, models: ReturnType<typeof createModels>, settingsStore: ReturnType<typeof createSettingsStore>): {
+    clampText: (value: unknown, max: number) => string;
+    historyFile: () => string;
+    handleHistory: (req: IncomingMessage, res: ServerResponse) => void;
+    handlePanelSize: (req: IncomingMessage, res: ServerResponse) => void;
+    handlePillPos: (req: IncomingMessage, res: ServerResponse) => void;
+};

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

@@ -0,0 +1,8 @@
+import type { ServerResponse, IncomingMessage } from 'node:http';
+/** 单次请求体上限（字节）。 */
+export declare const BODY_LIMIT: number;
+/** 写一条 SSE 事件。 */
+export declare function sse(res: ServerResponse, payload: unknown): void;
+export declare function sendJson(res: ServerResponse, status: number, body: unknown): void;
+/** 读取请求体（带长度上限）。 */
+export declare function readBody(req: IncomingMessage, limit: number): Promise<string>;

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

@@ -0,0 +1,13 @@
+import { createSystemMessage } from '@deepseek-ai/dsh-llm';
+/**
+ * `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)` —— 第二参数是历史遗留，传了会被忽略。
+ *
+ * 所以这里把它当"接受可选第二参数"的函数来调：两个版本都编译得过，运行时也都正确
+ * （旧版正好拿到它想要的"组装这段提示词的插件名"，新版直接忽略）。
+ */
+export declare const systemMessageOf: (text: string, plugin?: string) => ReturnType<typeof createSystemMessage>;

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

@@ -0,0 +1,17 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/**
+ * 停掉探针（没人看了 / 插件卸载）。**下次有人来问会重新启动**。
+ *
+ * 注意 available 要跟着回落到 false：探针都停了，再报"正在录"就是过期数据 ——
+ * 客户端看到 !available 会停掉轮询（不假装），这正是我们要的。
+ */
+export declare function stopMicProbe(): void;
+/**
+ * GET /selection-explain/api/mic
+ *   → { ok, available, capturing, processes:[{pid,bundleId,name}], reason }
+ *
+ * 客户端只关心 `capturing` 和某个进程的 bundleId 是不是目标输入法；
+ * 一次把所有占用者给全，是因为"同时在录的还有别的 App"很常见（会议软件、录音工具），
+ * 只报第一个会让特性在那种情况下静默失效。
+ */
+export declare const handleMic: (req: IncomingMessage, res: ServerResponse) => void;

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

@@ -0,0 +1,57 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Config } from './config.js';
+import type { Route } from './types.js';
+/** 解析本次调用使用的模型路由。 */
+/**
+ * 可选模型清单（带每个模型支持的推理等级）。
+ *
+ * 用 `llm.listProviders()`（同步）→ `llm.listModels(provider)`（异步，可能触发端点发现）→
+ * `llm.resolveModel(provider, model)` 拿 `reasoning.efforts`。因为可能慢，这里做 60 秒缓存，
+ * 并且**只在 /models 路由里调用**，不进 ping / analyze 的热路径。
+ */
+export type ModelChoice = {
+    provider: string;
+    providerName: string;
+    model: string;
+    name: string;
+    efforts: Array<{
+        id: string;
+        name: string;
+    }>;
+    defaultEffort: string | null;
+    /**
+     * 这个模型到底支不支持"思考强度"：
+     *   true  = 有推理档位（efforts 非空）
+     *   false = 明确不支持（dsh-llm 的 resolveModelInfo 说它没有 reasoning）
+     *   null  = 没读到（还没加载 / 这次调用失败）→ 原样发规范档位，被拒时由换档重试兜
+     */
+    hasReasoning: boolean | null;
+    /**
+     * 规范四格 → 这个模型**真实**的档位 id（'' = 没有可发的档位）。
+     * 由 `effortMapOf(model.efforts)` 实时算出，随清单一起下发 —— 设置页据此显示"这四格现在落到哪"。
+     */
+    effortMap: Record<string, string>;
+};
+/** Owns models state for one plugin instance. */
+export declare function createModels(ctx: Context, config: Config): {
+    resolveRoute: (override?: {
+        provider?: string;
+        model?: string;
+    }, sessionModel?: {
+        provider?: string;
+        model?: string;
+    } | null, chat?: boolean) => Route | null;
+    loadLeaky: () => Promise<void>;
+    leakyOnOff: Set<string>;
+    noOffRoutes: Set<string>;
+    effortForRoute: (route: string, canonical: string) => string;
+    nextEffortFor: (route: string, rejected: string, tried: Set<string>) => string;
+    markNoOff: (route: string) => void;
+    markLeaky: (route: string) => void;
+    listModelChoices: (force?: boolean) => Promise<ModelChoice[]>;
+    readonly modelCache: {
+        at: number;
+        items: ModelChoice[];
+    };
+    MODEL_CACHE_MS: number;
+};

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

@@ -0,0 +1,3 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Config } from './config.js';
+export declare function apply(ctx: Context, rawConfig: Config): void;

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

@@ -0,0 +1,9 @@
+import type { createHistoryStore } from './history-store.js';
+import type { createSessions } from './sessions.js';
+import type { Context } from '@deepseek-ai/cordis';
+import type { Config } from './config.js';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/** Owns promote state for one plugin instance. */
+export declare function createPromote(ctx: Context, config: Config, sessions: ReturnType<typeof createSessions>, historyStore: ReturnType<typeof createHistoryStore>): {
+    handlePromote: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+};

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

@@ -0,0 +1,14 @@
+import type { createSettingsStore } from './settings-store.js';
+import type { createModels } from './models.js';
+import type { createSessions } from './sessions.js';
+import type { createHistoryStore } from './history-store.js';
+import type { Context } from '@deepseek-ai/cordis';
+import type { Config } from './config.js';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/** Owns routes state for one plugin instance. */
+export declare function createRoutes(ctx: Context, config: Config, historyStore: ReturnType<typeof createHistoryStore>, sessions: ReturnType<typeof createSessions>, models: ReturnType<typeof createModels>, settingsStore: ReturnType<typeof createSettingsStore>): {
+    handleRoute: (req: IncomingMessage, res: ServerResponse) => void;
+    handlePing: (req: IncomingMessage, res: ServerResponse) => void;
+    handleModels: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+    handleQuoteContext: (req: IncomingMessage, res: ServerResponse) => void;
+};

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

@@ -0,0 +1,14 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Config } from './config.js';
+import type { SessionModel, BackgroundOptions, SessionBackground } from './types.js';
+/** 可写的 live 会话（只用到 append）。 */
+export interface LiveSessionLike {
+    append?: (type: string, data: unknown, options?: unknown) => unknown;
+}
+/** Owns sessions state for one plugin instance. */
+export declare function createSessions(ctx: Context, config: Config): {
+    sessionModelOf: (sessionId: string, useCache?: boolean) => Promise<SessionModel | null>;
+    loadSessionBackground: (sessionId: string, options: BackgroundOptions) => Promise<SessionBackground | null>;
+    resolveSessionCwd: (sessionId: string) => Promise<string | undefined>;
+    readSurfaceEvents: (sessionId: string) => Promise<readonly unknown[]>;
+};