@lrplrplrp/dsh-live2d 0.1.2 → 0.1.4

package/lib/index.js

@@ -10,6 +10,8 @@ import { createRequire } from 'node:module'
 import { createReadStream, statSync, existsSync, mkdirSync, writeFileSync, rmSync, readdirSync, readFileSync } from 'node:fs'
 import { join, extname, dirname, resolve, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
+// DSH 状态常量的单一来源（client 端由 scripts/build-client.mjs 内联同一份定义）
+import { DSHState } from './shared/states.js'
 
 const require = createRequire(import.meta.url)
 
@@ -37,10 +39,11 @@ const PLUGIN_ROOT = resolvedDir ? join(resolvedDir, '..') : null
 const LIB_DIR = PLUGIN_ROOT ? join(PLUGIN_ROOT, 'lib') : null
 const ASSETS_DIR = PLUGIN_ROOT ? join(PLUGIN_ROOT, 'assets') : null
 
-export const name = 'dsh-live2d'
+export const name = '@lrplrplrp/dsh-live2d'
 
 const STATE_ENDPOINT = '/plugins/dsh-live2d/state'
-const CONFIG_ENDPOINT = '/plugins/dsh-live2d/config'
+// 模型文件夹上传端点（multipart/form-data）。客户端配置以 localStorage 为准，不经此端点。
+const UPLOAD_ENDPOINT = '/plugins/dsh-live2d/config'
 
 // ── MIME 类型 ─────────────────────────────────────────────────────────
 const MIME = {
@@ -59,15 +62,7 @@ function guessMime(filePath) {
   return MIME[ext] || 'application/octet-stream'
 }
 
-// ── DSH 状态常量 ──────────────────────────────────────────────────────
-const DSHState = Object.freeze({
-  IDLE: 'IDLE',
-  THINKING: 'THINKING',
-  WORKING: 'WORKING',
-  SPEAKING: 'SPEAKING', // 开始输出对话内容
-  SUCCESS: 'SUCCESS',
-  ERROR: 'ERROR',
-})
+// ── 工具函数 ──────────────────────────────────────────────────────────
 
 // ── 当前状态（内存，客户端轮询读取） ──────────────────────────────────
 let currentState = DSHState.IDLE
@@ -76,6 +71,10 @@ let stateUpdatedAt = Date.now()
 // ── 工具调用跟踪 ──────────────────────────────────────────────────────
 const openTools = new Map()
 let waitingCallId = undefined
+// 本轮是否已开始输出正文（面向用户的对话）。一旦为 true，就保持「输出对话」状态
+// 直到本轮 turn 结束：模型常在输出一小段正文后立刻发起工具调用，若让 tool/call
+// 抢走状态，SPEAKING 会被反复打断成一闪而过。
+let speakingLocked = false
 
 function toolCallIdOf(event, fallback) {
   const data = event?.data || {}
@@ -124,6 +123,35 @@ function isSubagent(session) {
     || Number(session?.header?.delegationDepth ?? 0) > 0
 }
 
+// ── 「输出对话」判定 ───────────────────────────────────────────────────
+// DSH 的 assistant/chunk 既承载思维链（reasoning-delta）也承载面向用户的对话
+// 正文（text-delta）。只有后者才算“开始输出对话内容”，思维链/工具参数不算。
+// 参见 @deepseek-ai/dsh-llm 的 StreamChunk 定义。
+function chunkIsDialogue(chunk) {
+  if (!chunk || typeof chunk !== 'object') return false
+  switch (chunk.type) {
+    case 'text-delta':
+      // 正文增量：需含非空白内容（纯换行/缩进不算开始说话）
+      return typeof chunk.text === 'string' && chunk.text.trim().length > 0
+    case 'block-end':
+      // 完整块：仅 text 块算对话正文；reasoning / tool-call 等不算
+      return !!chunk.block && chunk.block.type === 'text'
+        && typeof chunk.block.text === 'string' && chunk.block.text.trim().length > 0
+    default:
+      // reasoning-delta / tool-call-delta / block-start / usage / finish 一律不算
+      return false
+  }
+}
+
+/** 持久化的 assistant/message 是否含面向用户的正文（而非仅思维链/工具调用）。 */
+function messageHasDialogue(data) {
+  const content = data?.message?.content
+  if (!Array.isArray(content)) return false
+  return content.some((block) =>
+    block && block.type === 'text'
+    && typeof block.text === 'string' && block.text.trim().length > 0)
+}
+
 function setState(state) {
   if (currentState !== state) {
     currentState = state
@@ -133,9 +161,43 @@ function setState(state) {
   }
 }
 
+// 临时状态（SUCCESS/ERROR）自动回到 IDLE：记录“本次复位对应的设置时刻”，
+// 定时器到点时只有仍处于同一次设置（时间戳未变）才复位。避免旧定时器
+// 在状态已被后续事件改写后又把 IDLE 覆盖上去。
+let pendingIdleResetAt = 0
+function scheduleIdleReset(expectedState, delayMs) {
+  const setAt = stateUpdatedAt
+  pendingIdleResetAt = setAt
+  setTimeout(() => {
+    if (pendingIdleResetAt === setAt && stateUpdatedAt === setAt && currentState === expectedState) {
+      setState(DSHState.IDLE)
+    }
+  }, delayMs)
+}
+
 // ── 状态实时推送（SSE） ──────────────────────────────────────────────
 const stateClients = new Set()
 
+/**
+ * 处理 `agent/assistant-stream` 的实时帧，用于「正文一开始输出就进入输出对话」。
+ * 帧结构见 @deepseek-ai/dsh-agent 的 AssistantStreamFrame：
+ *   { type: 'start' } | { type: 'chunk', chunk: StreamChunk } | { type: 'end', outcome }
+ * 只有面向用户的 text-delta / text 块才算正文；reasoning-delta（思维链）不算。
+ */
+function handleAssistantStream(payload) {
+  const frame = payload && payload.frame
+  if (!frame || typeof frame !== 'object') return
+  if (frame.type !== 'chunk') return
+
+  const chunk = frame.chunk
+  if (!chunkIsDialogue(chunk)) return
+  // 正文开始：立即进入「输出对话」并锁定，直到本轮结束
+  if (!speakingLocked) {
+    speakingLocked = true
+    setState(DSHState.SPEAKING)
+  }
+}
+
 function broadcastState(state) {
   const payload = `data: ${JSON.stringify({ state, updatedAt: stateUpdatedAt })}\n\n`
   for (const res of stateClients) {
@@ -152,13 +214,23 @@ function handleSessionEvent(session, event) {
     case 'turn/start':
       openTools.clear()
       waitingCallId = undefined
+      speakingLocked = false
       setState(DSHState.THINKING)
       break
 
     case 'assistant/chunk':
+      // 仅“面向用户的正文”才算开始输出对话；思维链 / 工具参数增量不改变状态
+      // （否则会在思考阶段就误报“输出对话”）。
+      if (!chunkIsDialogue(event.data?.chunk)) break
+      // 正文一开始就锁住「输出对话」，直到本轮结束（见 speakingLocked 说明）
+      speakingLocked = true
+      setState(DSHState.SPEAKING)
+      break
+
     case 'assistant/message':
-      // 没有正在执行的工具调用时，助手消息即"开始输出对话内容"
-      if (openTools.size > 0) break
+      // 持久化消息：只有含正文（text 块）才算输出对话；仅思维链/工具调用不算
+      if (!messageHasDialogue(event.data)) break
+      speakingLocked = true
       setState(DSHState.SPEAKING)
       break
 
@@ -166,6 +238,12 @@ function handleSessionEvent(session, event) {
       const callId = toolCallIdOf(event, `seq-${event.seq ?? 'unknown'}`)
       const name = String(event.data?.name ?? event.data?.message?.name ?? 'tool')
       openTools.set(callId, name)
+      // 若该工具是“向用户提问/请求确认”类（AskUserQuestion、exit plan mode 等），
+      // 标记为等待用户回答：这类调用会一直挂在 openTools 里（直到用户回复），
+      // 用户回复时靠 waitingCallId 把它清掉并回到 THINKING，否则会一直显示 WORKING。
+      if (isUserQuestionTool(name)) waitingCallId = callId
+      // 已开始输出正文：不被工具调用打断，保持「输出对话」直到本轮结束
+      if (speakingLocked) break
       setState(DSHState.WORKING)
       break
     }
@@ -174,6 +252,8 @@ function handleSessionEvent(session, event) {
       const callId = toolCallIdOf(event)
       if (callId) openTools.delete(callId)
       if (callId && callId === waitingCallId) waitingCallId = undefined
+      // 已开始输出正文：继续保持「输出对话」
+      if (speakingLocked) break
       setState(openTools.size > 0 ? DSHState.WORKING : DSHState.THINKING)
       break
     }
@@ -182,6 +262,8 @@ function handleSessionEvent(session, event) {
       if (waitingCallId) {
         openTools.delete(waitingCallId)
         waitingCallId = undefined
+        // 用户回复后新一轮开始：解除正文锁定，重新从思考开始
+        speakingLocked = false
         setState(DSHState.THINKING)
       }
       break
@@ -190,16 +272,17 @@ function handleSessionEvent(session, event) {
       openTools.clear()
       waitingCallId = undefined
       const kind = String(event.data?.reason?.kind ?? 'completed')
+      // 本轮结束：立即切到完成/错误，不再人为保留「输出对话」。
+      // 正文的开始与结束现在由 agent/assistant-stream 实时驱动（见 handleAssistantStream），
+      // SPEAKING 已覆盖真实输出时长，无需再按字数估算补一段展示时间。
+      speakingLocked = false
+
       if (kind === 'completed') {
         setState(DSHState.SUCCESS)
-        setTimeout(() => {
-          if (currentState === DSHState.SUCCESS) setState(DSHState.IDLE)
-        }, 2500)
+        scheduleIdleReset(DSHState.SUCCESS, 2500)
       } else if (kind !== 'blocked') {
         setState(DSHState.ERROR)
-        setTimeout(() => {
-          if (currentState === DSHState.ERROR) setState(DSHState.IDLE)
-        }, 4000)
+        scheduleIdleReset(DSHState.ERROR, 4000)
       }
       break
     }
@@ -221,17 +304,6 @@ function isLoopback(address) {
   return address === '127.0.0.1' || address === '::1' || address === '::ffff:127.0.0.1'
 }
 
-async function readPatch(req) {
-  const chunks = []
-  let bytes = 0
-  for await (const chunk of req) {
-    bytes += chunk.length
-    if (bytes > 65536) throw new Error('request body is too large')
-    chunks.push(chunk)
-  }
-  return JSON.parse(Buffer.concat(chunks).toString('utf8'))
-}
-
 /**
  * 把 URL 子路径解析成 `rootDir` 下的真实文件。
  * 拒绝任何逃出 rootDir 的路径（`..`、绝对路径、分隔符穿越）。
@@ -240,7 +312,9 @@ async function readPatch(req) {
 function resolveWithin(rootDir, rel) {
   if (!rootDir || !rel) return null
   if (rel.includes('\0')) return null
+  // 归一化后为空（如 "."、"./"、"//"）视为非法，避免解析到 rootDir 目录本身
   const abs = resolve(rootDir, rel)
+  if (abs === rootDir) return null
   if (abs !== rootDir && !abs.startsWith(rootDir + sep)) return null
   return abs
 }
@@ -344,6 +418,19 @@ export function apply(ctx) {
     }
   }, { global: true })
 
+  // 监听「实时助手流」（agent/assistant-stream）：
+  // session/event 是「持久化事件日志」，只在事件落盘时触发，因此正文不是流式落盘时
+  // 我们只能在 assistant/message（已完成的整条消息）才得知正文存在 —— 触发时机自然滞后。
+  // agent/assistant-stream 是逐 chunk 的实时发布（含 text-delta / reasoning-delta），
+  // 用它才能做到「正文一开始输出就进入输出对话」。
+  const offStream = ctx.on('agent/assistant-stream', (payload) => {
+    try {
+      handleAssistantStream(payload)
+    } catch (err) {
+      logger.error?.('dsh-live2d: failed to handle assistant stream', err)
+    }
+  }, { global: true })
+
   // 注册 webserver 路由
   if (typeof ctx.inject === 'function') {
     ctx.inject(['webServer'], (httpCtx) => {
@@ -398,92 +485,81 @@ export function apply(ctx) {
         'dsh-live2d: state sse endpoint',
       )
 
-      // GET/PATCH/POST /plugins/dsh-live2d/config
+      // POST /plugins/dsh-live2d/config — 上传整个模型文件夹（multipart/form-data）。
+      // 注：原先的 GET/PATCH 分支只是空壳（GET 恒返回 {ok:true}，PATCH 仅回显且从不落盘），
+      // 客户端也从不请求它们，已删除以免误导；客户端配置以 localStorage 为准。
       httpCtx.effect(
         () => httpCtx.webServer.register({
           kind: 'exact',
-          path: CONFIG_ENDPOINT,
+          path: UPLOAD_ENDPOINT,
           handler: async (req, res) => {
             if (!isLoopback(req.socket?.remoteAddress)) {
               jsonResponse(res, 403, { error: 'local access only' })
               return
             }
-            if (req.method === 'GET') {
-              jsonResponse(res, 200, { ok: true })
+            if (req.method !== 'POST') {
+              jsonResponse(res, 405, { error: 'method not allowed' })
               return
             }
-            if (req.method === 'PATCH') {
-              try {
-                const patch = await readPatch(req)
-                jsonResponse(res, 200, { ok: true, patch })
-              } catch (err) {
-                jsonResponse(res, 400, { error: err instanceof Error ? err.message : String(err) })
+            // 上传整个模型文件夹：multipart/form-data，字段 dirName + 若干 file（含 webkitRelativePath）
+            try {
+              if (!ASSETS_DIR) {
+                jsonResponse(res, 500, { error: 'assets dir unavailable' })
+                return
               }
-              return
-            }
-            if (req.method === 'POST') {
-              // 上传整个模型文件夹：multipart/form-data，字段 dirName + 若干 file（含 webkitRelativePath）
-              try {
-                if (!ASSETS_DIR) {
-                  jsonResponse(res, 500, { error: 'assets dir unavailable' })
-                  return
-                }
-                const ct = req.headers['content-type'] || ''
-                if (!ct.includes('multipart/form-data')) {
-                  jsonResponse(res, 400, { error: 'expected multipart/form-data' })
-                  return
-                }
-                const parts = await parseMultipart(req)
-                const dirField = parts.find((p) => p.name === 'dirName')
-                const dirName = (dirField ? dirField.data.toString('utf8') : '').trim()
-                if (!dirName || dirName.includes('/') || dirName.includes('\\') || dirName.includes('..') || /[^\w.\-]/.test(dirName)) {
-                  jsonResponse(res, 400, { error: 'invalid dirName' })
-                  return
-                }
-                const files = parts.filter((p) => p.filename)
-                if (files.length === 0) {
-                  jsonResponse(res, 400, { error: 'no files' })
-                  return
-                }
-                // 必须包含 model3.json
-                const hasModel3 = files.some((p) => p.filename.toLowerCase().endsWith('.model3.json'))
-                if (!hasModel3) {
-                  jsonResponse(res, 400, { error: 'missing .model3.json in folder' })
-                  return
-                }
-                const targetDir = join(ASSETS_DIR, dirName)
-                const abs = resolve(targetDir)
-                if (abs !== ASSETS_DIR && !abs.startsWith(ASSETS_DIR + sep)) {
-                  jsonResponse(res, 400, { error: 'invalid dirName' })
-                  return
-                }
-                // 覆盖式写入：先清空旧目录
-                try { rmSync(targetDir, { recursive: true, force: true }) } catch {}
-                mkdirSync(targetDir, { recursive: true })
-                let written = 0
-                for (const f of files) {
-                  // 用 webkitRelativePath（去掉首个目录段即 dirName）决定相对位置
-                  let relPath = f.webkitRelativePath || f.filename
-                  // webkitRelativePath 形如 dirName/sub/file —— 去掉开头的 dirName/
-                  const segs = relPath.split('/').filter(Boolean)
-                  if (segs.length > 1 && segs[0] === dirName) segs.shift()
-                  const rel = segs.join('/')
-                  const fpath = resolveWithin(targetDir, rel)
-                  if (!fpath) continue
-                  mkdirSync(dirname(fpath), { recursive: true })
-                  writeFileSync(fpath, f.data)
-                  written += 1
-                }
-                jsonResponse(res, 200, { ok: true, dirName, fileCount: written, modelUrl: `/plugins/dsh-live2d/assets/${dirName}/model.model3.json` })
-              } catch (err) {
-                jsonResponse(res, 400, { error: err instanceof Error ? err.message : String(err) })
+              const ct = req.headers['content-type'] || ''
+              if (!ct.includes('multipart/form-data')) {
+                jsonResponse(res, 400, { error: 'expected multipart/form-data' })
+                return
               }
-              return
+              const parts = await parseMultipart(req)
+              const dirField = parts.find((p) => p.name === 'dirName')
+              const dirName = (dirField ? dirField.data.toString('utf8') : '').trim()
+              if (!dirName || dirName.includes('/') || dirName.includes('\\') || dirName.includes('..') || /[^\w.\-]/.test(dirName)) {
+                jsonResponse(res, 400, { error: 'invalid dirName' })
+                return
+              }
+              const files = parts.filter((p) => p.filename)
+              if (files.length === 0) {
+                jsonResponse(res, 400, { error: 'no files' })
+                return
+              }
+              // 必须包含 model3.json
+              const hasModel3 = files.some((p) => p.filename.toLowerCase().endsWith('.model3.json'))
+              if (!hasModel3) {
+                jsonResponse(res, 400, { error: 'missing .model3.json in folder' })
+                return
+              }
+              const targetDir = join(ASSETS_DIR, dirName)
+              const abs = resolve(targetDir)
+              if (abs !== ASSETS_DIR && !abs.startsWith(ASSETS_DIR + sep)) {
+                jsonResponse(res, 400, { error: 'invalid dirName' })
+                return
+              }
+              // 覆盖式写入：先清空旧目录
+              try { rmSync(targetDir, { recursive: true, force: true }) } catch {}
+              mkdirSync(targetDir, { recursive: true })
+              let written = 0
+              for (const f of files) {
+                // 用 webkitRelativePath（去掉首个目录段即 dirName）决定相对位置
+                let relPath = f.webkitRelativePath || f.filename
+                // webkitRelativePath 形如 dirName/sub/file —— 去掉开头的 dirName/
+                const segs = relPath.split('/').filter(Boolean)
+                if (segs.length > 1 && segs[0] === dirName) segs.shift()
+                const rel = segs.join('/')
+                const fpath = resolveWithin(targetDir, rel)
+                if (!fpath) continue
+                mkdirSync(dirname(fpath), { recursive: true })
+                writeFileSync(fpath, f.data)
+                written += 1
+              }
+              jsonResponse(res, 200, { ok: true, dirName, fileCount: written, modelUrl: `/plugins/dsh-live2d/assets/${dirName}/model.model3.json` })
+            } catch (err) {
+              jsonResponse(res, 400, { error: err instanceof Error ? err.message : String(err) })
             }
-            jsonResponse(res, 405, { error: 'method not allowed' })
           },
         }),
-        'dsh-live2d: config endpoint',
+        'dsh-live2d: model upload endpoint',
       )
 
       // ── 模型自动扫描接口 ──────────────────────────────────
@@ -618,6 +694,12 @@ export function apply(ctx) {
                 res.end()
                 return
               }
+              // 与其他端点保持一致：仅允许本机访问
+              if (!isLoopback(req.socket?.remoteAddress)) {
+                res.writeHead(403)
+                res.end('local access only')
+                return
+              }
               const urlPath = new URL(req.url || '/', 'http://localhost').pathname
               const rel = decodeURIComponent(urlPath.slice(routePath.length).replace(/^\//u, ''))
               const filePath = resolveWithin(dir, rel)
@@ -638,5 +720,11 @@ export function apply(ctx) {
   // 清理
   ctx.effect(() => () => {
     offEvent?.()
+    offStream?.()
+    // 关闭并清空所有 SSE 连接，避免插件卸载/热重载后残留客户端（集合泄漏 + 僵尸连接）
+    for (const res of stateClients) {
+      try { res.end() } catch {}
+    }
+    stateClients.clear()
   }, 'dsh-live2d: cleanup')
 }

package/lib/shared/states.js

@@ -0,0 +1,16 @@
+// dsh-live2d — 共享的状态常量（host 与 client 的单一来源）。
+//
+// host 端（lib/index.js）直接 `import { DSHState }`；
+// client 端（lib/client.js）由 scripts/build-client.mjs 在构建时内联本文件内容
+// （浏览器侧无法 import 本地文件，client.js 必须保持单文件投放）。
+//
+// 本文件不得依赖 node 或浏览器任何专有 API，保持“纯数据 + 纯函数”以便两端复用。
+
+export const DSHState = Object.freeze({
+  IDLE: 'IDLE',
+  THINKING: 'THINKING',
+  WORKING: 'WORKING',
+  SPEAKING: 'SPEAKING', // 开始输出对话内容
+  SUCCESS: 'SUCCESS',
+  ERROR: 'ERROR',
+})

package/lib/src/00-header.js

@@ -0,0 +1,21 @@
+// dsh-live2d — Client (browser) side.
+//
+// DSH 插件：在 Web GUI 中渲染 Live2D 看板娘模型。
+//
+// 功能：
+//   - Live2D 模型渲染（PIXI.js + pixi-live2d-dsl，全部本地加载）
+//   - 鼠标拖动移动位置
+//   - DSH 状态驱动动画（思考/工作/完成/错误）
+//   - 设置页：模型列表编辑、画布大小配置、动画映射
+//   - 支持本地模型导入
+//
+// 移除了原项目的：对话框、小飞机游戏、关闭/关于/GitHub 按钮。
+
+window.__ModuleLoader__.load({ id: '@lrplrplrp/dsh-live2d', factory: (require) => {
+  var module = { exports: {} }
+  var exports = module.exports
+
+  const React = require('react')
+  const { useState, useEffect, useRef, useCallback } = React
+  const h = React.createElement
+

package/lib/src/10-config.js

@@ -0,0 +1,172 @@
+  // ══════════════════════════════════════════════════════════════════════
+  //  常量 & 配置
+  // ══════════════════════════════════════════════════════════════════════
+  //  （源码分片：常量、默认模型列表、localStorage 配置读写与内存缓存（+ 构建时内联的共享 DSHState））
+
+  const STORAGE_KEY = 'dsh-live2d.v1'
+  const POSITION_KEY = 'dsh-live2d.position'
+  const ACTIVE_MODEL_KEY = 'dsh-live2d.activeModel'
+
+  // 容器默认屏幕位置（无本地存档时使用），对应 position:fixed 的 left/top
+  const DEFAULT_POSITION = { x: 1240, y: 330 }
+
+  // 本地文件路由前缀（由 host 端 index.js 注册）
+  const LIB_BASE = '/plugins/dsh-live2d/lib/'
+  const ASSETS_BASE = '/plugins/dsh-live2d/assets/'
+
+  // 需要按【依赖顺序】加载的本地库文件，分组表示加载阶段：
+  //   - 第一段 pixi 必须先行执行完成；
+  //   - 第二段的 live2d / core / display 可并行，但都要在 pixi 之后（display 在
+  //     加载期就访问 PIXI，若与 pixi 并行下载可能因 pixi 体积大而晚到，导致报错）。
+  const LIB_PHASES = [
+    ['pixi.min.js'],
+    ['live2d.min.js', 'live2dcubismcore.min.js', 'index.min.js'],
+  ]
+
+  // DSHState 由 lib/shared/states.js 内联提供（host 与 client 的单一来源），
+  // 见 scripts/build-client.mjs —— 此处不再重复定义。
+
+  // 客户端动画状态：除 host 广播的 DSHState 外，额外含 WELCOME（欢迎）与
+  // THINK_END（思考结束过渡态，由客户端在 THINKING → 非 THINKING 时触发一次）。
+  const ANIMATION_STATES = ['WELCOME', 'IDLE', 'THINKING', 'THINK_END', 'WORKING', 'SPEAKING', 'SUCCESS', 'ERROR']
+
+  const ANIMATION_STATE_LABELS = {
+    WELCOME: '欢迎',
+    IDLE: '空闲',
+    THINKING: '开始思考',
+    THINK_END: '思考结束',
+    WORKING: '工具调用',
+    SPEAKING: '输出对话',
+    SUCCESS: '任务完成',
+    ERROR: '任务出错',
+  }
+
+  const DEFAULT_MODEL_LIST = {
+    models: [{
+      name: 'DeepSeek',
+      url: ASSETS_BASE + 'deepseek_l2d/deepseek.model3.json',
+      canvasWidth: 300,
+      canvasHeight: 400,
+      config: { x: 0, y: 0, scaleX: 1.5, scaleY: 1.5 },
+      animations: {
+        WELCOME: { motion: { group: 'Idle', index: 0 }, loop: false },
+        IDLE: { motion: { group: 'Idle', index: 0 }, loop: false },
+        THINKING: { motion: { group: 'Anima', index: 2 }, loop: true },
+        THINK_END: { motion: { group: 'Anima', index: 1 }, loop: false },
+        WORKING: { expression: 'puzzled' },
+        SPEAKING: { motion: { group: 'Anima', index: 0 }, loop: true },
+        SUCCESS: { expression: 'happy' },
+        ERROR: { expression: 'unhappy' },
+      },
+    }],
+    // 眼睛是否跟随鼠标（全局开关）
+    eyeFollow: true,
+    // 点击命中区域开关（全局开关，默认开启）
+    hitArea: true,
+  }
+
+  // ══════════════════════════════════════════════════════════════════════
+  //  配置管理（localStorage 持久化）
+  // ══════════════════════════════════════════════════════════════════════
+
+  // 规范化配置：保证 models 一定是数组，且每个 model 的动画相关字段都是数组。
+  // 兼容早期脏数据（如 models 被存成对象 {} 而非数组，或字段缺失）。
+  function normalizeConfig(cfg) {
+    if (!cfg || typeof cfg !== 'object') cfg = {}
+    var models = cfg.models
+    if (!Array.isArray(models)) models = []
+    models = models.map(function(m) {
+      if (!m || typeof m !== 'object') return { name: '', url: '', groups: [], groupCounts: {}, groupMotions: {}, expressions: [], animations: {}, timeMappings: [] }
+      return {
+        name: m.name || '',
+        url: m.url || '',
+        canvasWidth: m.canvasWidth || 300,
+        canvasHeight: m.canvasHeight || 400,
+        config: m.config || { x: 0, y: 0, scaleX: 1, scaleY: 1 },
+        groups: Array.isArray(m.groups) ? m.groups : [],
+        groupCounts: m.groupCounts && typeof m.groupCounts === 'object' ? m.groupCounts : {},
+        groupMotions: m.groupMotions && typeof m.groupMotions === 'object' ? m.groupMotions : {},
+        expressions: Array.isArray(m.expressions) ? m.expressions : [],
+        animations: m.animations && typeof m.animations === 'object' ? m.animations : {},
+        // 时间映射：[{ start: 'HH:MM', end: 'HH:MM', animation: {...} }]
+        timeMappings: Array.isArray(m.timeMappings) ? m.timeMappings : [],
+      }
+    })
+    return Object.assign({}, cfg, { models: models, eyeFollow: cfg.eyeFollow === false ? false : true, hitArea: cfg.hitArea === false ? false : true })
+  }
+
+  // 配置在内存中缓存一份：缩放 / 拖动画布这类高频操作需要在内存里连续累加，
+  // 不能每次都从 localStorage 重新解析（否则上一次的防抖写入还没落盘，会读到旧值）。
+  // 读取一律走缓存，写入由 saveConfig 防抖落盘，保证内存与持久化一致。
+  let _configCache = null
+
+  function getConfig() {
+    if (_configCache) return _configCache
+    try {
+      const raw = window.localStorage.getItem(STORAGE_KEY)
+      _configCache = raw
+        ? normalizeConfig(JSON.parse(raw))
+        : normalizeConfig(JSON.parse(JSON.stringify(DEFAULT_MODEL_LIST)))
+    } catch {
+      _configCache = normalizeConfig(JSON.parse(JSON.stringify(DEFAULT_MODEL_LIST)))
+    }
+    return _configCache
+  }
+
+  let _saveTimer = null
+  function saveConfig(cfg) {
+    // 始终以传入对象（或当前缓存）作为权威状态，确保与内存一致
+    if (cfg) _configCache = cfg
+    if (_saveTimer) clearTimeout(_saveTimer)
+    _saveTimer = setTimeout(function() {
+      _saveTimer = null
+      try {
+        if (_configCache) window.localStorage.setItem(STORAGE_KEY, JSON.stringify(_configCache))
+      } catch {}
+    }, 150)
+  }
+
+  // 立即落盘：在页面卸载/隐藏前把待写的配置同步刷入 localStorage，
+  // 避免 debounce 窗口内（150ms）用户关闭页面导致最后一次修改丢失。
+  function flushConfig() {
+    if (_saveTimer) { clearTimeout(_saveTimer); _saveTimer = null }
+    try {
+      if (_configCache) window.localStorage.setItem(STORAGE_KEY, JSON.stringify(_configCache))
+    } catch {}
+  }
+  window.addEventListener('pagehide', flushConfig)
+  window.addEventListener('beforeunload', flushConfig)
+
+  function getPosition() {
+    try {
+      const raw = window.localStorage.getItem(POSITION_KEY)
+      if (!raw) return null
+      return JSON.parse(raw)
+    } catch {
+      return null
+    }
+  }
+
+  function savePosition(x, y) {
+    try {
+      window.localStorage.setItem(POSITION_KEY, JSON.stringify({ x, y }))
+    } catch {}
+  }
+
+  function getActiveModelIndex(models) {
+    let idx = 0
+    try {
+      const raw = window.localStorage.getItem(ACTIVE_MODEL_KEY)
+      if (raw !== null) {
+        const n = parseInt(raw, 10)
+        if (Number.isFinite(n) && n >= 0 && n < models.length) idx = n
+      }
+    } catch {}
+    return idx
+  }
+
+  function saveActiveModelIndex(idx) {
+    try {
+      window.localStorage.setItem(ACTIVE_MODEL_KEY, String(idx))
+    } catch {}
+  }