@yfwu2020/dsh-selection-explain 0.4.1 → 0.7.1

package/lib/index.js

@@ -23,6 +23,24 @@ import z from '@deepseek-ai/schemastery';
 import { CHAT_SYSTEM_PROMPT, CODE_PROMPT, DETAIL_PROMPT, TRANSLATION_PROMPT, } from './prompts.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'];
 /** 路由前缀。 */
@@ -1098,6 +1116,93 @@ export function apply(ctx, rawConfig) {
     let historyLoaded = false;
     let historyTimer = null;
     const historyFile = () => join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'selection-explain', 'history.json');
+    /**
+     * 悬浮胶囊"拖到别处"后的位置（用户要求记住，存 host 上 —— 不用 localStorage）。
+     * 只记自由摆放的**右边缘 + 垂直中心**：收球/展开都以右边缘为锚（client 半的 applyFreePill 用 CSS right 钉住）。
+     * 吸附回右下角（anchor）时会清掉 —— 那是默认位置，不需要记。
+     */
+    const pillPosFile = () => join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'selection-explain', 'pill.json');
+    let pillPos = null;
+    let pillPosLoaded = false;
+    let pillPosTimer = null;
+    /** 位置校验：只接受有限数值，并夹到一个"任何屏幕都放得下"的量级。 */
+    function normalizePillPos(input) {
+        const value = input;
+        const right = typeof value?.right === 'number' && Number.isFinite(value.right) ? value.right : NaN;
+        const y = typeof value?.y === 'number' && Number.isFinite(value.y) ? value.y : NaN;
+        if (!Number.isFinite(right) || !Number.isFinite(y))
+            return null;
+        const clamp = (n) => Math.round(Math.min(40000, Math.max(-40000, n)));
+        return { right: clamp(right), y: clamp(y) };
+    }
+    async function loadPillPos() {
+        if (pillPosLoaded)
+            return;
+        pillPosLoaded = true;
+        try {
+            const parsed = JSON.parse(await readFile(pillPosFile(), 'utf8'));
+            pillPos = normalizePillPos(parsed?.position);
+        }
+        catch {
+            pillPos = null; // 没存过 / 坏了都当作"没记过"
+        }
+    }
+    function schedulePillPosWrite() {
+        if (pillPosTimer)
+            clearTimeout(pillPosTimer);
+        pillPosTimer = setTimeout(() => {
+            pillPosTimer = null;
+            void (async () => {
+                try {
+                    await mkdir(join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'selection-explain'), { recursive: true });
+                    await writeFile(pillPosFile(), JSON.stringify({ version: 1, position: pillPos }, null, 0), 'utf8');
+                }
+                catch (error) {
+                    ctx.logger?.warn?.(`[${name}] 写入胶囊位置失败：${String(error?.message ?? error)}`);
+                }
+            })();
+        }, 300);
+        pillPosTimer.unref?.();
+    }
+    /**
+     * 胶囊位置：GET 读回来（挂载时恢复）、POST 存（{right,y}）或清（{clear:true}，吸附回右下角时调）。
+     */
+    const handlePillPos = (req, res) => {
+        void (async () => {
+            await loadPillPos();
+            if (req.method === 'GET') {
+                sendJson(res, 200, { ok: true, position: pillPos });
+                return;
+            }
+            if (req.method !== 'POST') {
+                sendJson(res, 405, { ok: false, error: '只支持 GET / POST' });
+                return;
+            }
+            const raw = await readBody(req, 4_000);
+            let body = {};
+            try {
+                body = raw ? JSON.parse(raw) : {};
+            }
+            catch {
+                sendJson(res, 400, { ok: false, error: '请求体不是合法 JSON' });
+                return;
+            }
+            if (body.clear === true) {
+                pillPos = null;
+                schedulePillPosWrite();
+                sendJson(res, 200, { ok: true, position: null });
+                return;
+            }
+            const next = normalizePillPos(body.position ?? body);
+            if (!next) {
+                sendJson(res, 400, { ok: false, error: 'position 需要 { right, y } 两个有限数值' });
+                return;
+            }
+            pillPos = next;
+            schedulePillPosWrite();
+            sendJson(res, 200, { ok: true, position: pillPos });
+        })();
+    };
     const clampText = (value, max) => (typeof value === 'string' ? value.slice(0, max) : '');
     async function loadHistory() {
         if (historyLoaded)
@@ -1758,7 +1863,7 @@ export function apply(ctx, rawConfig) {
     };
     /**
      * 把划词解读小窗「升格」成正式会话（建在来源会话同一个项目下）：
-     *   ① 建会话 → ② 注入上下文消息（选中文字/所在位置/上下文片段，plugin 来源的 context 消息）
+     *   ① 建会话 → ② 注入上下文消息（选中文字/所在位置/上下文片段，生产者自有 kind 的 context 消息）
      *   → ③ 把首轮解读写成助手消息 → ④ 把追问逐轮写成真实的 user/assistant 历史消息
      *   → ⑤ 送一条短开场消息让 agent 接手（这样整段历史才会落盘）。
      * 这样新会话里看到的就是一段真实的多轮对话，而不是一大坨打包文本。
@@ -1875,7 +1980,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}`,
@@ -1889,8 +1997,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 },
@@ -2668,6 +2775,7 @@ 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}/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`);
     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`);