@yfwu2020/dsh-selection-explain 0.4.1 → 0.7.1

package/src/index.ts

@@ -36,6 +36,25 @@ import {
 /** 插件名（= 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']
 
@@ -1381,6 +1400,94 @@ export function apply(ctx: Context, rawConfig: Config): void {
   const historyFile = (): string =>
     join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'selection-explain', 'history.json')
 
+  /**
+   * 悬浮胶囊"拖到别处"后的位置（用户要求记住，存 host 上 —— 不用 localStorage）。
+   * 只记自由摆放的**右边缘 + 垂直中心**：收球/展开都以右边缘为锚（client 半的 applyFreePill 用 CSS right 钉住）。
+   * 吸附回右下角（anchor）时会清掉 —— 那是默认位置，不需要记。
+   */
+  const pillPosFile = (): string =>
+    join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'selection-explain', 'pill.json')
+
+  let pillPos: { right: number; y: number } | null = null
+  let pillPosLoaded = false
+  let pillPosTimer: ReturnType<typeof setTimeout> | null = null
+
+  /** 位置校验：只接受有限数值，并夹到一个"任何屏幕都放得下"的量级。 */
+  function normalizePillPos(input: unknown): { right: number; y: number } | null {
+    const value = input as { right?: unknown; y?: unknown } | null | undefined
+    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: number): number => Math.round(Math.min(40000, Math.max(-40000, n)))
+    return { right: clamp(right), y: clamp(y) }
+  }
+
+  async function loadPillPos(): Promise<void> {
+    if (pillPosLoaded) return
+    pillPosLoaded = true
+    try {
+      const parsed = JSON.parse(await readFile(pillPosFile(), 'utf8')) as { position?: unknown }
+      pillPos = normalizePillPos(parsed?.position)
+    } catch {
+      pillPos = null // 没存过 / 坏了都当作"没记过"
+    }
+  }
+
+  function schedulePillPosWrite(): void {
+    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 as Error)?.message ?? error)}`)
+        }
+      })()
+    }, 300)
+    pillPosTimer.unref?.()
+  }
+
+  /**
+   * 胶囊位置：GET 读回来（挂载时恢复）、POST 存（{right,y}）或清（{clear:true}，吸附回右下角时调）。
+   */
+  const handlePillPos = (req: IncomingMessage, res: ServerResponse): void => {
+    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: { position?: unknown; clear?: unknown } = {}
+      try {
+        body = raw ? (JSON.parse(raw) as { position?: unknown; clear?: unknown }) : {}
+      } 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: unknown, max: number): string => (typeof value === 'string' ? value.slice(0, max) : '')
 
   async function loadHistory(): Promise<void> {
@@ -2039,7 +2146,7 @@ export function apply(ctx: Context, rawConfig: Config): void {
 
   /**
    * 把划词解读小窗「升格」成正式会话（建在来源会话同一个项目下）：
-   *   ① 建会话 → ② 注入上下文消息（选中文字/所在位置/上下文片段，plugin 来源的 context 消息）
+   *   ① 建会话 → ② 注入上下文消息（选中文字/所在位置/上下文片段，生产者自有 kind 的 context 消息）
    *   → ③ 把首轮解读写成助手消息 → ④ 把追问逐轮写成真实的 user/assistant 历史消息
    *   → ⑤ 送一条短开场消息让 agent 接手（这样整段历史才会落盘）。
    * 这样新会话里看到的就是一段真实的多轮对话，而不是一大坨打包文本。
@@ -2178,7 +2285,10 @@ export function apply(ctx: Context, rawConfig: Config): void {
           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}`,
@@ -2193,8 +2303,7 @@ export function apply(ctx: Context, rawConfig: Config): void {
             id: `sel-ctx-${stamp}`,
             role: 'user',
             source: {
-              kind: 'plugin',
-              plugin: name,
+              kind: PLUGIN_SOURCE_KIND,
               form: 'snapshot',
               sections: [
                 { name: '划词解读 · 选中文字', text },
@@ -3004,6 +3113,10 @@ export function apply(ctx: Context, rawConfig: Config): void {
     () => 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`,