@yfwu2020/dsh-selection-explain 0.7.0 → 0.8.3

package/lib/index.js

@@ -21,8 +21,29 @@ import z from '@deepseek-ai/schemastery';
 // 提示词与写作规则（纯文本常量）单独成模块：本文件是 2400+ 行的 host 全量逻辑，
 // 提示词放这里既难找也容易误改。组装逻辑仍在下方（按 stage / kind 选一套）。
 import { CHAT_SYSTEM_PROMPT, CODE_PROMPT, DETAIL_PROMPT, TRANSLATION_PROMPT, } from './prompts.js';
+// 设置页的字段声明与校验：与 Config 一一对应，GET /settings 直接把 spec 发给客户端，
+// 客户端只负责画 —— 避免 UI 的边界和 host 的 clamp 各写一份、时间久了互相漂。
+import { buildSettingsPayload, normalizeSettingsPatch, normalizeStoredSettings, PERSISTED_SETTING_KEYS, SETTINGS_KEYS } from './settings.js';
 /** 插件名（= package.json name，客户端 bundle 的模块 id 也是它）。 */
 export 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 const PLUGIN_SOURCE_KIND = `plugin:${name}`;
 /** 路由注册与模型调用所需的服务。 */
 export const inject = ['webServer', 'llm'];
 /** 路由前缀。 */
@@ -33,9 +54,11 @@ const BODY_LIMIT = 512 * 1024;
 export const Config = z.object({
     provider: z.string().default(''),
     model: z.string().default(''),
+    chatProvider: z.string().default(''),
+    chatModel: z.string().default(''),
     reasoningEffort: z.string().default('high'),
-    /** 首轮「翻译」单独一档：这一轮只挑英文片段做翻译，不需要深度推理，默认压低换首字速度。 */
-    translationReasoningEffort: z.string().default('low'),
+    /** 首轮单独一档：默认关闭思考，优先快速给出翻译、解读或注释。 */
+    translationReasoningEffort: z.string().default('off'),
     /**
      * 小窗对话历史（A′）：把整段对话落到插件自己的目录，重划同一个词直接回放。
      * 0 = 关闭历史。只留最近 N 个「划词条目」（每个条目内含它自己的全部追问轮次）。
@@ -90,6 +113,10 @@ export const Config = z.object({
      * 侧边栏网页里选中文字不会再弹「解读」。
      */
     bridgeSidebarPreview: z.boolean().default(true),
+    /** 悬浮胶囊开关（小窗设置页可改）。 */
+    pillEnabled: z.boolean().default(true),
+    /** 静置收球时长（毫秒）——默认 10 秒，见 Config 注释。 */
+    pillIdleMs: z.number().min(2000).max(600000).default(10000),
 });
 /** 联网类工具名：用来判断"首选里的联网工具在不在"。 */
 const SEARCH_TOOL_NAMES = ['advanced_search', 'platform_search', 'web_search'];
@@ -899,8 +926,10 @@ export function apply(ctx, rawConfig) {
     const config = {
         provider: rawConfig?.provider ?? '',
         model: rawConfig?.model ?? '',
+        chatProvider: rawConfig?.chatProvider ?? '',
+        chatModel: rawConfig?.chatModel ?? '',
         reasoningEffort: rawConfig?.reasoningEffort ?? 'high',
-        translationReasoningEffort: rawConfig?.translationReasoningEffort ?? 'low',
+        translationReasoningEffort: rawConfig?.translationReasoningEffort ?? 'off',
         historyMaxEntries: rawConfig?.historyMaxEntries ?? 20,
         temperature: rawConfig?.temperature ?? -1,
         maxTokens: rawConfig?.maxTokens ?? 0,
@@ -924,7 +953,91 @@ export function apply(ctx, rawConfig) {
         toolReadRoot: rawConfig?.toolReadRoot ?? '',
         chatReasoningEffort: rawConfig?.chatReasoningEffort ?? 'high',
         bridgeSidebarPreview: rawConfig?.bridgeSidebarPreview ?? true,
+        pillEnabled: rawConfig?.pillEnabled ?? true,
+        pillIdleMs: rawConfig?.pillIdleMs ?? 10000,
     };
+    /**
+     * 出厂默认值（**不含**用户在设置页改过的部分）。
+     *
+     * 为什么单独留一份：设置页的「恢复默认」要能把值写回这里，
+     * 而"这一项改过没有"也要拿它对比 —— 只有一个 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;
+    }
     /** 兜底路由：第一次真实 LLM 调用后捕获。 */
     let captured = null;
     ctx.on('llm/stream', (options, next) => {
@@ -1022,7 +1135,25 @@ export function apply(ctx, rawConfig) {
         return items;
     }
     /** 请求里带 provider+model 时优先用它（并按清单校验；清单还没加载出来就只做形状校验）。 */
-    const resolveRoute = (override) => {
+    const resolveRoute = (override, 
+    /**
+     * **当前会话**自己的模型选择（见 sessionModelOf）。
+     *
+     * 为什么要有它：会话是各自选模型的（每个 Agent 一份 model-selection），
+     * 而 `agentDefaultModel.currentSelection()` 是**全局默认**、与会话无关。
+     * 以前只用后者，于是"跟随主会话"其实跟的是"全局默认"——
+     * 两个会话用不同模型时，插件对两个会话都用同一个默认模型，跟谁都对不上。
+     *
+     * 优先级：显式 override（小窗胶囊选的）→ 插件配置（设置页选的）→ **本会话的模型** → 全局默认 → 第一个可用。
+     * 会话没记过选择（新会话、或日志里没有 model/selection）时自然落回全局默认，行为与以前一致。
+     */
+    sessionModel, 
+    /**
+     * 这一轮是不是**追问**。
+     *
+     * 三个阶段沿用同一模型；旧 chatProvider/chatModel 仅保留配置兼容，不再参与路由。
+     */
+    chat) => {
         if (override?.provider && override?.model) {
             const wanted = { provider: override.provider, model: override.model };
             const known = modelCache.items.some((item) => item.provider === wanted.provider && item.model === wanted.model);
@@ -1031,6 +1162,9 @@ export function apply(ctx, rawConfig) {
         }
         if (config.provider && config.model)
             return { provider: config.provider, model: config.model };
+        if (sessionModel?.provider && sessionModel?.model) {
+            return { provider: sessionModel.provider, model: sessionModel.model };
+        }
         const service = ctx.get('agentDefaultModel');
         const selection = service?.currentSelection?.();
         if (selection?.provider && selection?.model) {
@@ -1061,6 +1195,35 @@ export function apply(ctx, rawConfig) {
     const resultKeyOf = (provider, model, sessionId, backgroundText, text, context) => createHash('sha1').update([provider, model, sessionId, backgroundText, text, context].join('\u0000')).digest('hex');
     /** 会话背景短缓存：同一会话 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);
@@ -1086,6 +1249,99 @@ export function apply(ctx, rawConfig) {
             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);
@@ -1201,7 +1457,8 @@ export function apply(ctx, rawConfig) {
                     continue;
                 history.set(entry.key, {
                     key: entry.key,
-                    text: clampText(entry.text, 4000),
+                    // 按可设置的最高选区长度保留，调低当前限制也不截断已有历史。
+                    text: clampText(entry.text, 20000),
                     context: clampText(entry.context, 20000),
                     label: clampText(entry.label, 60),
                     at: typeof entry.at === 'number' ? entry.at : Date.now(),
@@ -1256,7 +1513,7 @@ export function apply(ctx, rawConfig) {
         const previous = history.get(key);
         const entry = {
             key,
-            text: clampText(input.text, 4000),
+            text: clampText(input.text, 20000),
             context: clampText(input.context, 20000),
             label: clampText(input.label, 60),
             at: Date.now(),
@@ -1605,11 +1862,8 @@ export function apply(ctx, rawConfig) {
     };
     const handleHistory = (req, res) => {
         void (async () => {
+            await loadSettings();
             await loadHistory();
-            if (config.historyMaxEntries <= 0) {
-                sendJson(res, 200, { ok: true, entries: [] });
-                return;
-            }
             const url = new URL(req.url ?? '/', 'http://localhost');
             if (req.method === 'DELETE') {
                 // 删除一条（?key=）或清空（?all=1）。
@@ -1707,7 +1961,15 @@ export function apply(ctx, rawConfig) {
         catch (thrown) {
             error = String(thrown?.message ?? thrown);
         }
-        const current = resolveRoute();
+        // 会话级：设置页的「跟随主会话」要显示**当前会话**在用的模型
+        let modelsSessionId = '';
+        try {
+            modelsSessionId = url.searchParams.get('sessionId') ?? '';
+        }
+        catch {
+            /* 解析不了就当没带 */
+        }
+        const current = resolveRoute(undefined, await sessionModelOf(modelsSessionId));
         sendJson(res, 200, {
             ok: true,
             current,
@@ -1724,6 +1986,90 @@ export function apply(ctx, rawConfig) {
             },
         });
     }
+    /**
+     * 设置页的读写口。
+     *
+     *   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) });
+        });
+    };
+    /**
+     * 极轻的"这一轮会用哪个模型"查询。
+     *
+     *   GET /selection-explain/api/route?sessionId=…[&chat=1]
+     *
+     * 为什么单开一条：设置页要**实时**显示当前会话在用的模型，
+     * 而 /models 会去列 provider 与模型（42 个，还要端点发现）、/ping 要枚举工具表并探 DNS ——
+     * 两者都不适合按秒轮询。这条只做一次会话模型解析 + 一次 resolveRoute。
+     *
+     * 也是唯一走 `sessionModelOf(…, true)`（短缓存）的地方：客户端在小窗开着时每 2 秒问一次，
+     * 不能每拍都重放一次会话日志（见 sessionModelCache 的注释）。
+     */
+    const handleRoute = (req, res) => {
+        void (async () => {
+            await loadSettings();
+            let sessionId = '';
+            let chat = false;
+            try {
+                const url = new URL(req.url ?? '/', 'http://localhost');
+                sessionId = url.searchParams.get('sessionId') ?? '';
+                chat = url.searchParams.get('chat') === '1';
+            }
+            catch {
+                /* 解析不了就当没带 */
+            }
+            const route = resolveRoute(undefined, await sessionModelOf(sessionId, true), chat);
+            sendJson(res, 200, {
+                ok: true,
+                provider: route?.provider ?? '',
+                model: route?.model ?? '',
+                // 是不是"跟首轮/次轮同一个"：客户端据此把追问下拉显示成「跟随首轮 / 次轮」
+                chatFollows: true,
+            });
+        })().catch((error) => {
+            sendJson(res, 500, { ok: false, error: String(error?.message ?? error) });
+        });
+    };
     const handlePing = (req, res) => {
         const sessionQuery = ctx.get('sessionQuery');
         // 可以带 ?sessionId=xxx：工具是**按会话作用域**注册的，不带 id 只能看到全局视图（里面没有 web_search）
@@ -1737,6 +2083,8 @@ export function apply(ctx, rawConfig) {
         // 小窗能调哪些工具：白名单是配置，实际放行还要看本机能不能抓网页（见下）。
         // 用 async 包一层：探测 DNS 是异步的，出错也要给出结构化响应（和 history 路由同一写法）。
         void (async () => {
+            // 先把用户改过的设置套上：下面报的每一条都必须是**当前生效**的值
+            await loadSettings();
             const whitelist = config.toolNames
                 .split(',')
                 .map((item) => item.trim())
@@ -1780,7 +2128,7 @@ export function apply(ctx, rawConfig) {
             sendJson(res, 200, {
                 ok: true,
                 plugin: name,
-                route: resolveRoute(),
+                route: resolveRoute(undefined, await sessionModelOf(pingSessionId)),
                 reasoningEffort: config.reasoningEffort,
                 modelsRoute: `${API_PREFIX}/models`,
                 history: { maxEntries: config.historyMaxEntries, file: historyFile() },
@@ -1812,6 +2160,8 @@ export function apply(ctx, rawConfig) {
                 sessionContext: config.sessionContext && typeof sessionQuery?.readSurface === 'function',
                 // 侧边栏 HTML 预览里的划词桥开关：客户端据此决定要不要往预览帧注入桥脚本
                 bridgeSidebarPreview: config.bridgeSidebarPreview,
+                // 悬浮胶囊的两个偏好：跟着 ping 一起下发，省得客户端为它单开一次请求
+                pill: { enabled: config.pillEnabled, idleMs: config.pillIdleMs },
                 limits: {
                     maxSelectionChars: config.maxSelectionChars,
                     maxContextChars: config.maxContextChars,
@@ -1845,7 +2195,7 @@ export function apply(ctx, rawConfig) {
     };
     /**
      * 把划词解读小窗「升格」成正式会话（建在来源会话同一个项目下）：
-     *   ① 建会话 → ② 注入上下文消息（选中文字/所在位置/上下文片段，plugin 来源的 context 消息）
+     *   ① 建会话 → ② 注入上下文消息（选中文字/所在位置/上下文片段，生产者自有 kind 的 context 消息）
      *   → ③ 把首轮解读写成助手消息 → ④ 把追问逐轮写成真实的 user/assistant 历史消息
      *   → ⑤ 送一条短开场消息让 agent 接手（这样整段历史才会落盘）。
      * 这样新会话里看到的就是一段真实的多轮对话，而不是一大坨打包文本。
@@ -1962,7 +2312,10 @@ export function apply(ctx, rawConfig) {
                     live.append?.('step/end', { turn, step: 1 });
                     live.append?.('turn/end', { turn, reason: { kind: 'completed' } });
                 };
-                // 第 1 轮：上下文消息（plugin 来源 + snapshot 呈现）+ 首轮解读
+                // 第 1 轮：上下文消息（生产者自有的 source.kind + snapshot 呈现）+ 首轮解读
+                // ⚠️ kind 必须是 PLUGIN_SOURCE_KIND（`plugin:<插件名>`）：会话格式 v4 起不再
+                // 接受退役的 `plugin` 包装（`kind: 'plugin'` 加一个 `plugin` 字段），否则整场升格
+                // 会死在 "format v4 message requires a producer-owned source kind" 上（见文件头常量注释）。
                 const contextBody = [
                     `选中文字：${text}`,
                     `所在位置：${label}`,
@@ -1976,8 +2329,7 @@ export function apply(ctx, rawConfig) {
                     id: `sel-ctx-${stamp}`,
                     role: 'user',
                     source: {
-                        kind: 'plugin',
-                        plugin: name,
+                        kind: PLUGIN_SOURCE_KIND,
                         form: 'snapshot',
                         sections: [
                             { name: '划词解读 · 选中文字', text },
@@ -2081,7 +2433,9 @@ export function apply(ctx, rawConfig) {
         const override = typeof body.provider === 'string' && typeof body.model === 'string' && body.provider && body.model
             ? { provider: body.provider, model: body.model }
             : undefined;
-        const route = resolveRoute(override);
+        // 名字避开下面的 isChat（那里判的是"提示词用追问那套"，此处判的是"模型用追问那个"）
+        const isChatRound = typeof body.question === 'string' && body.question.trim().length > 0;
+        const route = resolveRoute(override, await sessionModelOf(sessionIdOf(body)), isChatRound);
         if (!route) {
             sendJson(res, 503, { error: '尚未确定模型路由：请先在设置里选择默认模型后重试' });
             return;
@@ -2384,7 +2738,7 @@ export function apply(ctx, rawConfig) {
                 rounds: 0,
                 error: '',
             };
-            const toolRounds = config.maxToolRounds + 1;
+            const toolRounds = config.maxToolRounds;
             // 档位被上游拒绝时（400/401/500）去掉档位重试一次：清单里声明的档位是**建议值**，
             // 实测很多模型并不接受 max（qwen3.7-max 直接 400、minimax-m2.7/gpt-5.6-luna 500）。
             const canRetryEffort = isChat && bodyEffort.length > 0;
@@ -2567,6 +2921,9 @@ export function apply(ctx, rawConfig) {
                     answer = answer.slice(0, Math.max(0, answer.length - roundText.length));
                     sse(res, { type: 'drop', chars: roundText.length, text: roundText.slice(-2000), round });
                 }
+                // 有的模型不带工具定义也会返回调用；执行端同样遵守开关和轮数上限。
+                if (wrapUp || toolSchemas.length === 0)
+                    break;
                 // 执行工具→把结果回灌，再让模型继续（上限 maxToolRounds 轮）
                 toolMessages.push(createAssistantMessage({
                     content: blocks,
@@ -2591,17 +2948,19 @@ export function apply(ctx, rawConfig) {
                     // 只认 path 的话 read 的 file_path 会是 undefined → 边界检查被静默绕过（实测踩过）。
                     const rawPath = parsed?.file_path ?? parsed?.path;
                     const wantPath = typeof rawPath === 'string' ? rawPath : '';
-                    const execution = FS_TOOL_NAMES.includes(call.name) && !isInsideRoot(readRoot, wantPath)
-                        ? {
-                            content: [
-                                {
-                                    type: 'text',
-                                    text: `（越界已拒绝：文件类工具只能访问当前项目目录${readRoot ? `（${readRoot}）` : ''}，请求的路径是 ${wantPath || '(未给)'}）`,
-                                },
-                            ],
-                            isError: true,
-                        }
-                        : await runTool(ctx, call.name, parsed, controller.signal, config.toolResultMaxChars, agent);
+                    const execution = !toolSchemas.some((schema) => schema.name === call.name)
+                        ? { content: [{ type: 'text', text: `（调用已拒绝：${call.name} 不在本次允许的工具中）` }], isError: true }
+                        : FS_TOOL_NAMES.includes(call.name) && !isInsideRoot(readRoot, wantPath)
+                            ? {
+                                content: [
+                                    {
+                                        type: 'text',
+                                        text: `（越界已拒绝：文件类工具只能访问当前项目目录${readRoot ? `（${readRoot}）` : ''}，请求的路径是 ${wantPath || '(未给)'}）`,
+                                    },
+                                ],
+                                isError: true,
+                            }
+                            : await runTool(ctx, call.name, parsed, controller.signal, config.toolResultMaxChars, agent);
                     // 结果也回传：小窗里能看见"查了什么、命中什么、链接是什么"，否则工具是个黑盒
                     const digest = digestToolResult(execution.content);
                     sse(res, {
@@ -2753,6 +3112,8 @@ export function apply(ctx, rawConfig) {
         }
     };
     ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: `${API_PREFIX}/analyze`, handler: handleAnalyze }), `${name}: analyze route`);
+    ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: `${API_PREFIX}/settings`, handler: handleSettings }), `${name}: settings route`);
+    ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: `${API_PREFIX}/route`, handler: handleRoute }), `${name}: route route`);
     ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: `${API_PREFIX}/ping`, handler: handlePing }), `${name}: ping route`);
     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}/pill`, handler: handlePillPos }), `${name}: pill position route`);