dsh-soul 0.7.0 → 0.7.2

package/index.mjs

@@ -16,9 +16,10 @@
 //   - 注入系统提示词到 Agent
 //   - 配置写入统一走写队列，返回 changed（有无实际变更）与 promptChanged（是否需要刷新提示词并注入会话）
 
-import { readFile, writeFile, mkdir } from 'node:fs/promises'
 import { join } from 'node:path'
 import { homedir } from 'node:os'
+import { createRequire } from 'node:module'
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import {
   DEFAULT_CONFIG,
@@ -33,7 +34,8 @@ import {
   sanitizePersonaName
 } from './lib/config.mjs'
 import { createInjectionSource } from './lib/injection.mjs'
-import { isBuiltinPersona, mergePersonas, personaMatches, resolvePersona } from './lib/personas.mjs'
+import { isBuiltinPersona, builtinPersonaNames, mergePersonas, personaMatches, resolvePersona, declaredPersonaKeys } from './lib/personas.mjs'
+import { configWriteRefusal, describeConfigFailure, moveAsideConfigFile, readConfigFile, writeConfigFile } from './lib/store.mjs'
 
 const name = 'soul'
 
@@ -42,6 +44,113 @@ function configPath() {
   return join(process.env.DSH_HOME || join(homedir(), '.dsh'), 'soul-config.json')
 }
 
+// 版本号：唯一来源是 package.json。
+//
+// 刻意**不**在这里再写一个常量 —— 需要手工同步的版本号已经有三处
+// （package.json / client 的 VERSION / RELEASE_NOTES.md），再加一处只会多一个漂移点。
+// 读不到就返回 null：诊断端点不应该因为版本读不出来而失败。
+function pluginVersion() {
+  try {
+    return createRequire(import.meta.url)('./package.json').version || null
+  } catch {
+    return null
+  }
+}
+
+// ==================== 人设插画（方案 C：卡片左侧方图） ====================
+//
+// 图放 assets/personas/<内置人设名>.webp，随包发布；客户端按人设名请求
+// `/api/soul/persona-art/<name>`，宿主读文件返回。三条设计取舍：
+//
+//   ① **不进客户端包**：客户端模块由宿主注入，把 7 张图内联成 data URL 会让
+//      客户端包从 114KB 涨到 1MB+；走路由则按需加载、可缓存。
+//   ② **缺图回退占位而不是报错**：只有部分人设配了图时，其余显示官方鲸鱼轮廓的
+//      占位图。用户看到的是「一只鲸鱼」而不是破图，且新增人设不必同时补图。
+//   ③ **只服务内置人设名**：文件名由人设名构成，必须经白名单校验 —— 否则
+//      `/api/soul/persona-art/../../package.json` 这类路径穿越能读到包内任意文件。
+
+const PERSONA_ART_DIR = 'assets/personas'
+// 允许的图片扩展名（宿主对插件资源的白名单：SVG / PNG / JPEG / WebP）
+const ART_EXTENSIONS = ['.webp', '.png', '.jpg', '.jpeg', '.svg']
+// MIME 表：必须显式给出，否则浏览器可能按 octet-stream 下载而不是渲染
+const ART_MIME = {
+  '.webp': 'image/webp',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.svg': 'image/svg+xml'
+}
+const PLACEHOLDER_FILE = 'placeholder.svg'
+// 自定义（自建）预设的默认贴图：鲸鱼剪影 + 装饰元素，用户提供的品牌插画。
+// 与内置插画同为 512×512 WebP、视觉重量一致，但形态是无五官的剪影 ——
+// 内置是有具体人格的具象插画，自建是「还没定制」的中性底图，一眼可区分。
+const CUSTOM_ART_FILE = 'custom-placeholder.webp'
+
+// 包根目录下的 assets/personas 绝对路径
+function personaArtDir() {
+  try {
+    const pkgDir = createRequire(import.meta.url).resolve('./package.json').replace(/[\\/]package\.json$/, '')
+    return join(pkgDir, PERSONA_ART_DIR)
+  } catch {
+    return null
+  }
+}
+
+// 解析某个内置人设的插画（返回文件名，或回退到占位图；都不可用返回 null）
+//
+// 白名单校验用 isBuiltinPersona：人设名因此只能是既定 7 个之一，不含 / 与 ..，
+// 路径穿越从结构上不可能发生（而不是靠字符串替换去猜）。
+function resolvePersonaArt(name) {
+  const dir = personaArtDir()
+  if (!dir || typeof name !== 'string') return null
+  // 自建预设没有配套插画 ⇒ 用专用默认贴图（本版只做样式调整；
+  // 允许用户上传本地图片作为插画是后续版本的功能）。
+  //
+  // 这里**仍不接受任意名字拼路径**：只有内置名会走下面的按名查找，
+  // 非内置名一律返回固定文件，路径穿越依然不可能发生。
+  if (!isBuiltinPersona(name)) {
+    const custom = join(dir, CUSTOM_ART_FILE)
+    // MIME 按扩展名取，不写死 —— 贴图格式变过一次（svg → webp），
+    // 写死会让浏览器把它当 octet-stream 下载而不是渲染。
+    const ext = CUSTOM_ART_FILE.slice(CUSTOM_ART_FILE.lastIndexOf('.'))
+    return existsSync(custom) ? { file: custom, mime: ART_MIME[ext] } : null
+  }
+  for (const ext of ART_EXTENSIONS) {
+    const file = join(dir, `${name}${ext}`)
+    if (existsSync(file)) return { file, mime: ART_MIME[ext] }
+  }
+  const fallback = join(dir, PLACEHOLDER_FILE)
+  if (existsSync(fallback)) return { file: fallback, mime: ART_MIME['.svg'] }
+  return null
+}
+
+// 已配图的人设名列表（诊断端点用：一眼看出哪几个还缺图）
+function personasWithArt() {
+  const dir = personaArtDir()
+  if (!dir || !existsSync(dir)) return []
+  let files = []
+  try {
+    files = readdirSync(dir)
+  } catch {
+    return []
+  }
+  const out = []
+  for (const name of builtinPersonaNamesSafe()) {
+    if (ART_EXTENSIONS.some((ext) => files.includes(`${name}${ext}`))) out.push(name)
+  }
+  return out
+}
+
+// builtinPersonaNames 的容错包装：诊断路径不应因为导入异常而失败
+function builtinPersonaNamesSafe() {
+  try {
+    return builtinPersonaNames()
+  } catch {
+    return []
+  }
+}
+
+
 // ==================== 提示词文案与构建器 ====================
 
 // 提示词固定文案表：所有进入 system prompt / 会话注入 / 工具返回的文本，
@@ -100,6 +209,8 @@ const PROMPT_TEXT = {
     toolNoChanges: '没有要更改的设置',
     toolValidationFailed: '配置校验失败：',
     toolProposal: '已收到人设变更请求（确认模式已开启，尚未生效）：',
+    toolRejected: '你在审批面板中拒绝了这次人设变更，未做任何修改。',
+    toolApprovalDisabled: '说明：本次会话的审批通道已被禁用（approval policy = never），因此没有弹出确认面板；这不代表你做了拒绝操作。',
     toolProposalHint: '在用户确认前不会生效；用户可用 /soul confirm 确认，或 /soul reject 拒绝。'
   },
   en: {
@@ -155,6 +266,8 @@ const PROMPT_TEXT = {
     toolNoChanges: 'No settings to change',
     toolValidationFailed: 'Config validation failed: ',
     toolProposal: 'Persona change requested (confirmation mode is on — not applied yet):',
+    toolRejected: 'You rejected this persona change in the approval panel — nothing was modified.',
+    toolApprovalDisabled: 'Note: the approval channel is disabled in this session (approval policy = never), so no confirmation panel appeared; this does not mean you rejected anything.',
     toolProposalHint: 'It stays pending until the user confirms with /soul confirm or rejects with /soul reject.'
   }
 }
@@ -198,29 +311,48 @@ const MAX_BODY_BYTES = 64 * 1024
 // 内存中的配置缓存
 let configCache = null
 
-// 读取配置
+// 磁盘上的配置存在但不可用（读不出来 / 不是合法 JSON）时的记录。
+// 置位后 saveConfig 会拒绝写入，避免把损坏的配置静默清空成默认值。
+let configLoadFailure = null
+
+// 读取配置。
+//
+// 文件不存在（首次运行）与文件损坏是两件不同的事，必须分开处理：
+//   - 不存在  → 回退默认值，正常路径，可以照常保存；
+//   - 损坏    → 也回退默认值（保证插件与设置页仍可用），但记录失败原因，
+//               并让写入路径拒绝保存。否则「回退默认」会在下一次保存时变成
+//               「以默认值为底写回磁盘」，用户的自定义指令与预设库就永久丢了。
+//
+// 失败时刻意**不写 configCache**：这样用户修好文件后，下一次读取会自动恢复正常，
+// 不必重启 DSH。
 async function loadConfig() {
   if (configCache) return configCache
-  
-  try {
-    const data = await readFile(configPath(), 'utf8')
-    configCache = migrateConfig(JSON.parse(data))
-  } catch {
-    configCache = { ...DEFAULT_CONFIG }
+  configLoadFailure = null
+
+  const { value, exists, failure } = await readConfigFile(configPath())
+  if (failure) {
+    configLoadFailure = failure
+    return { ...DEFAULT_CONFIG }
   }
+
+  configCache = exists ? migrateConfig(value) : { ...DEFAULT_CONFIG }
   return configCache
 }
 
-// 保存配置
+// 保存配置（原子写，见 lib/store.mjs 的 writeConfigFile）。
+// 磁盘配置损坏时拒绝写入：拒绝的原因与恢复方式由 lib/store.mjs 统一生成。
 async function saveConfig(config) {
-  const dir = join(configPath(), '..')
-  await mkdir(dir, { recursive: true })
+  const refusal = configWriteRefusal(configLoadFailure, configPath())
+  if (refusal) {
+    throw new Error(refusal)
+  }
+
   // 过滤已废弃字段（旧客户端可能仍携带 tone / presets / examples）
   const clean = { ...config }
   delete clean.tone
   delete clean.presets
   delete clean.examples
-  await writeFile(configPath(), JSON.stringify(clean, null, 2), 'utf8')
+  await writeConfigFile(configPath(), clean)
   configCache = clean
   return clean
 }
@@ -277,6 +409,31 @@ function defaultConfigPreservingPersonas(current) {
   return next
 }
 
+// 重置：配置损坏时的**逃生口**。
+//
+// 损坏状态下所有写入都被 saveConfig 拒绝 —— 包括重置。但「一个出口都没有」意味着
+// 用户只能自己去删文件，所以「重置」被定义为**刻意丢弃**：先把损坏的文件移开
+// （＝备份到 <config>.corrupt），路径随即回到「首次运行」分支，这次写入才能真正落盘。
+//
+// 这与 R3 的「损坏配置绝不**静默**被覆盖」不冲突：静默覆盖被禁止，而重置是用户显式
+// 发起的动作、且覆盖前先留下备份。
+//
+// 复用 commitConfig 的「读—改—写」，不另写一份；写入失败时恢复失败标记，
+// 避免把「文件仍然不可用」误报成正常状态。
+async function resetConfigWithEscape() {
+  const failure = configLoadFailure
+  const backupPath = failure ? await moveAsideConfigFile(configPath()) : null
+  if (failure) configLoadFailure = null
+
+  try {
+    const result = await commitConfig((current) => defaultConfigPreservingPersonas(current))
+    return { ...result, backupPath }
+  } catch (err) {
+    if (failure) configLoadFailure = failure
+    throw err
+  }
+}
+
 // 将字段级校验错误汇总为一行文本（HTTP 错误信息 / 工具返回消息共用）
 function formatFieldErrors(errors) {
   return Object.entries(errors)
@@ -351,14 +508,81 @@ function compilePrompt(config) {
   return parts.join('\n')
 }
 
-// ==================== Agent 上下文注入 ====================
+// ==================== 配置生效链路的送达诊断 ====================
+
+// 「改配置 → 下一轮生效」由两条通道共同承载：system prompt section（底座）与
+// 活动会话注入（立即见效）。任一条静默失效，表面症状都是「改了人设不生效」而没有
+// 任何报错 —— 正是本插件历史上最难排查的一类问题（见 DEBUGGING.md 3.5）。
+//
+// 因此这里如实记录事实，并让三处可读到：日志（同因只告一次）、GET /api/soul/status、
+// /soul show。诊断本身不改变行为，只在真的出问题时才说话（正常状态不打扰）。
+const deliveryState = {
+  injectedAt: null,        // 最近一次注入尝试的时间（ISO）
+  agents: 0,               // 最近一次看到的活动会话数
+  delivered: 0,            // 最近一次成功注入的会话数
+  failed: 0,               // 最近一次注入抛错的会话数
+  injectionProblem: null,  // 未能如实送达的原因；正常为 null
+  sectionRegisteredAt: null // section 最近一次注册成功的时间（ISO）
+}
+
+// 同一原因只告一次警，避免每次保存都刷屏；一旦恢复正常则清掉记录，
+// 这样「好了又坏」会再次告警。
+const warnedReasons = new Set()
 
-// 将最新配置作为 model-facing context 注入所有活动会话。
+function warnOnce(ctx, reason, message) {
+  if (warnedReasons.has(reason)) return
+  warnedReasons.add(reason)
+  try {
+    ctx.logger?.warn?.(`[dsh-soul] ${message}`)
+  } catch {
+    // 日志不可用不应影响功能
+  }
+}
+
+// 把内部原因码翻译成一句能直接看懂的话（/soul show、设置页、状态端点共用）。
+//
+// 文案取自 **COMMAND_MESSAGES**（不是 PROMPT_TEXT）：delivery* 系列键只定义在命令文案表里，
+// 两者都按 config.language 提供中英两套。这里此前误用 promptTextOf ⇒ 该函数在
+// 'agents-service-unavailable' 分支返回 undefined（JSON 序列化时字段整个消失，故障对
+// 用户不可见），在 'inject-failed' 分支直接抛 TypeError（保存已落盘却报 HTTP 500）。
+function deliveryProblemText(config) {
+  const problem = deliveryState.injectionProblem
+  if (!problem) return null
+  const T = commandMessages(config)
+  if (problem === 'agents-service-unavailable') return T.deliveryNoAgentsService
+  return T.deliveryInjectFailed(problem.replace(/^inject-failed:\s*/, ''))
+}
+
+// 把最新配置作为 model-facing context 注入所有活动会话。
 // inject() 不会唤醒 Agent，也不改写普通用户消息；会在下一次 step 被模型读取。
 function injectPromptToAllAgents(ctx, config) {
+  const stamp = new Date().toISOString()
+  const unavailable = (reason, message) => {
+    deliveryState.injectedAt = stamp
+    deliveryState.agents = 0
+    deliveryState.delivered = 0
+    deliveryState.failed = 0
+    deliveryState.injectionProblem = reason
+    warnOnce(ctx, reason, message)
+  }
+
   const agents = ctx.get('agents')
   if (!agents || typeof agents.list !== 'function') {
-    // console.warn('[dsh-soul] agents 服务不可用，跳过最新配置注入')
+    unavailable(
+      'agents-service-unavailable',
+      'agents 服务不可用：新配置只能经 system prompt section 送达，保存后可能要到新会话才生效'
+    )
+    return
+  }
+
+  let listed
+  try {
+    listed = agents.list()
+  } catch (err) {
+    unavailable(
+      'agents-service-unavailable',
+      `列出活动会话失败（${String((err && err.message) || err)}）：新配置只能经 system prompt section 送达`
+    )
     return
   }
 
@@ -366,7 +590,11 @@ function injectPromptToAllAgents(ctx, config) {
   const prompt = compilePrompt(config)
   const snapshotText = prompt || T.injectDisabled
 
-  for (const agent of agents.list()) {
+  let delivered = 0
+  let failed = 0
+  let lastError = null
+
+  for (const agent of listed) {
     try {
       agent.inject(createUserMessage({
         content: [{
@@ -377,17 +605,39 @@ function injectPromptToAllAgents(ctx, config) {
         // 会让每一轮在 step 开始前失败（issue #1，构造与校验见 lib/injection.mjs）
         source: createInjectionSource(snapshotText)
       }))
-      // console.log(`[dsh-soul] 已向 Agent ${agent.id} 注入最新配置`)
+      delivered++
     } catch (err) {
-      // console.error(`[dsh-soul] 向 Agent ${agent.id} 注入配置失败:`, err)
+      failed++
+      lastError = err
+      try {
+        ctx.logger?.warn?.(`[dsh-soul] 向会话 ${agent?.id} 注入配置失败：${String((err && err.message) || err)}`)
+      } catch {
+        // 同上：日志失败不影响功能
+      }
     }
   }
+
+  deliveryState.injectedAt = stamp
+  deliveryState.agents = listed.length
+  deliveryState.delivered = delivered
+  deliveryState.failed = failed
+  deliveryState.injectionProblem = failed > 0
+    ? `inject-failed: ${String((lastError && lastError.message) || lastError)}`
+    : null
+
+  // 恢复正常后允许再次告警（「好了又坏」不该被静默）
+  if (failed === 0) warnedReasons.delete('agents-service-unavailable')
+  else warnedReasons.add('agents-service-unavailable')
 }
 
 function refreshPromptAndInject(ctx, config) {
   if (globalUpdatePrompt) {
     globalUpdatePrompt().catch(err => {
-      // console.error('[dsh-soul] 更新系统提示词失败:', err)
+      try {
+        ctx.logger?.warn?.(`[dsh-soul] 重新注册 system prompt section 失败：${String((err && err.message) || err)}`)
+      } catch {
+        // 同上
+      }
     })
   }
   injectPromptToAllAgents(ctx, config)
@@ -410,7 +660,18 @@ function registerRoutes(ctx) {
         try {
           if (req.method === 'GET') {
             const config = await loadConfig()
-            send(200, { ok: true, config })
+            // configError：磁盘配置存在但不可用时上报（此时 config 是回退的默认值）。
+            // 让设置页能直接说明「人设为什么像是被重置了」，而不是让用户自己发现；
+            // 正常情况下该字段为 null，不影响既有客户端。
+            send(200, {
+              ok: true,
+              config,
+              configError: configLoadFailure ? describeConfigFailure(configLoadFailure) : null,
+              // deliveryWarning：配置送达异常时上报（例如 agents 服务不可用）。
+              // 与 configError 分开：configError 是「配置读不出来」，这里是「配置送不到会话」，
+              // 两者症状都表现为「改了人设不生效」，但处理方式完全不同。
+              deliveryWarning: deliveryProblemText(config)
+            })
           } else if (req.method === 'POST') {
             const parsed = await readJsonBody(req)
             if (!parsed.ok) {
@@ -434,7 +695,7 @@ function registerRoutes(ctx) {
               refreshPromptAndInject(ctx, updated)
             }
 
-            send(200, { ok: true, config: updated, changed })
+            send(200, { ok: true, config: updated, changed, deliveryWarning: deliveryProblemText(updated) })
           } else {
             send(405, { ok: false, error: 'Method not allowed' })
           }
@@ -455,6 +716,13 @@ function registerRoutes(ctx) {
         }
         
         try {
+          // 方法校验：本端点只读。此前是唯一不判 method 的端点（同文件其余 7 处都有
+          // 405 分支），实测 POST /api/soul/prompt 会拿到 200 —— 宿主只做路径匹配，
+          // method 判定确实是 handler 的责任。
+          if (req.method !== 'GET') {
+            send(405, { ok: false, error: 'Method not allowed' })
+            return
+          }
           const config = await loadConfig()
           const prompt = compilePrompt(config)
           send(200, { ok: true, prompt, enabled: config.enabled })
@@ -519,15 +787,77 @@ function registerRoutes(ctx) {
           res.end(JSON.stringify(body))
         }
 
+        // 方法校验：这是**破坏性写**入口（重置配置、必要时丢弃并备份损坏文件），
+        // 缺了它任何 HTTP 方法都能触发 —— 而 GET 是浏览器预取、爬虫、<img src>、
+        // 链接预览都会发出的方法，一个 GET 就能重置用户配置。
+        // 同期的 personas/save、personas/delete 都有此校验，此处属遗漏。
+        if (req.method !== 'POST') {
+          send(405, { ok: false, error: 'Method not allowed' })
+          return
+        }
+
         try {
-          const { config, changed, promptChanged } = await commitConfig(current => defaultConfigPreservingPersonas(current))
+          // 经由逃生口：配置损坏时这是设置页唯一还能成功的写操作。
+          // backupPath 非 null 说明刚才确实丢弃了一份损坏的配置（已备份），
+          // 客户端据此给出「备份在哪」的提示，而不是让用户以为数据凭空消失。
+          const { config, changed, promptChanged, backupPath } = await resetConfigWithEscape()
 
           // 仅影响 Agent 行为的字段变化才刷新提示词并注入会话
           if (promptChanged.length > 0) {
             refreshPromptAndInject(ctx, config)
           }
 
-          send(200, { ok: true, config, changed })
+          send(200, { ok: true, config, changed, backupPath, deliveryWarning: deliveryProblemText(config) })
+        } catch (err) {
+          send(500, { ok: false, error: String(err.message || err) })
+        }
+      }
+    })
+
+    // 生效链路诊断：两条通道（system prompt section / 活动会话注入）的当前状态。
+    // 设置页与 /soul show 之外，这是给「改了配置不生效」提供的第三个、也是脚本化的观察点。
+    wsCtx.webServer.register({
+      kind: 'exact',
+      path: '/api/soul/status',
+      handler: async (req, res) => {
+        const send = (status, body) => {
+          res.writeHead(status, { 'content-type': 'application/json' })
+          res.end(JSON.stringify(body))
+        }
+
+        try {
+          if (req.method !== 'GET') {
+            send(405, { ok: false, error: 'Method not allowed' })
+            return
+          }
+
+          const config = await loadConfig()
+          const injection = {
+            lastAt: deliveryState.injectedAt,
+            agents: deliveryState.agents,
+            delivered: deliveryState.delivered,
+            failed: deliveryState.failed,
+            problem: deliveryState.injectionProblem
+          }
+
+          send(200, {
+            ok: true,
+            version: pluginVersion(),
+            enabled: config.enabled,
+            configPath: configPath(),
+            configError: configLoadFailure ? describeConfigFailure(configLoadFailure) : null,
+            promptChars: compilePrompt(config).length,
+            channels: {
+              // section 是底座：它一旦注册成功，宿主每一步装配都会重新求值
+              // （不依赖任何缓存，见 scripts/verify-live-prompt.mjs）
+              section: {
+                registered: deliveryState.sectionRegisteredAt !== null,
+                registeredAt: deliveryState.sectionRegisteredAt
+              },
+              injection
+            },
+            deliveryWarning: deliveryProblemText(config)
+          })
         } catch (err) {
           send(500, { ok: false, error: String(err.message || err) })
         }
@@ -543,14 +873,21 @@ function registerRoutes(ctx) {
 // 待确认的人设变更提议（set_persona 确认模式；进程内短生命周期，不做持久化）
 let pendingPersonaProposal = null
 
-// 从配置中提取人设字段快照（作为预设保存的内容）
+// 从配置中提取人设快照（作为预设保存的内容）。
+//
+// 只遍历 PERSONA_FIELDS ⇒ **不含「关于你」（昵称 / 职业 / 介绍）**：预设是 Agent 的
+// 人格存档，不是使用者身份存档。切换预设不该把你的昵称职业一起换掉。
+// 输出语言在范围内（它决定 Agent 用什么语言作答）。
 function personaSnapshotOf(config) {
   const values = {}
   for (const key of PERSONA_FIELDS) values[key] = config[key]
   return values
 }
 
-// 从预设条目中挑出人设字段（忽略 updatedAt 等元数据）
+// 从预设条目中挑出人设字段（忽略 updatedAt 等元数据与「关于你」）。
+// `if (key in persona)` 即「部分覆盖」语义：只应用条目**实际声明**的键，
+// 未声明的保持用户当前值；而遍历白名单本身则是第二道防线——即便磁盘上残留了
+// nickname / occupation / bio（历史数据），也不会被写回活动配置。
 function pickPersonaValues(persona) {
   const values = {}
   for (const key of PERSONA_FIELDS) {
@@ -580,6 +917,27 @@ function findActivePersonaName(config) {
   return null
 }
 
+// 应用一个预设条目：过白名单 → 写队列合并。
+//
+// **必须回报被丢弃的字段**：normalizePersonas 只按字段名过滤、不校验取值，所以磁盘上
+// 残留的历史值（例如 v0.1.x 的合法 style 'friendly'）或手改的异常值会走到这里被
+// sanitizeConfig 拒绝。此前两条应用路径都只取 patch、把 errors 丢掉 ⇒ 预设被「部分
+// 应用」却返回 ok:true / 「已应用」，用户以为整套生效了（实测：style 与 emoji 被静默
+// 丢弃，只有 customInstructions 写回）。
+//
+// 语义选择：应用**合法部分**并如实回报被丢弃的字段，而不是整单拒绝 —— 后者会让一个
+// 只差一个字段的旧预设彻底不可用，代价更高；而「部分应用 + 明示」与 /api/soul/prompt/
+// preview 的 invalid 约定一致。
+async function applyPersonaEntry(ctx, entry) {
+  const { patch, errors } = sanitizeConfig(pickPersonaValues(entry))
+  const invalid = Object.keys(errors)
+  const { config: updated, changed, promptChanged } = await commitConfig(c => ({ ...c, ...patch }))
+  if (promptChanged.length > 0) refreshPromptAndInject(ctx, updated)
+  // applied 是「通过校验的字段数」——与 changed（实际产生差异的字段）不同：
+  // 全部非法时 applied 为 0，此时不能报「已应用」，也不能报「与当前配置一致」。
+  return { updated, changed, promptChanged, invalid, applied: Object.keys(patch).length }
+}
+
 // 预设库的对外视图（内置 + 用户）与当前命中项，供三个路由的响应复用。
 function personaLibrary(config) {
   return { personas: mergePersonas(config.personas), activeName: findActivePersonaName(config) }
@@ -676,12 +1034,14 @@ function registerPersonaRoutes(ctx) {
           }
           // 内置预设已在代码里写过一遍；用户预设保存时也校验过。此处统一再过一遍
           // 白名单，防御手改 config.json 注入的异常数据。
-          const { patch } = sanitizeConfig(pickPersonaValues(entry))
-          const { config: updated, changed, promptChanged } = await commitConfig(c => ({ ...c, ...patch }))
-          if (promptChanged.length > 0) {
-            refreshPromptAndInject(ctx, updated)
+          // invalid = 因取值非法而被丢弃的字段名：必须回报，不能静默部分应用。
+          const { updated, changed, invalid, applied } = await applyPersonaEntry(ctx, entry)
+          // 一个合法字段都没有 ⇒ 什么都没应用，按失败处理（与 /soul use 同语义）
+          if (applied === 0) {
+            send(res, 400, { ok: false, error: `预设「${personaName}」没有可应用的合法字段`, invalid })
+            return
           }
-          send(res, 200, { ok: true, config: updated, changed, unchanged: changed.length === 0 })
+          send(res, 200, { ok: true, config: updated, changed, unchanged: changed.length === 0, invalid })
         } catch (err) {
           send(res, 500, { ok: false, error: String(err.message || err) })
         }
@@ -727,6 +1087,45 @@ function registerPersonaRoutes(ctx) {
         }
       }
     })
+
+    // 人设插画：/api/soul/persona-art/<内置人设名>
+    //
+    // 用 prefix 路由（WebRouteKind 支持 'exact' | 'prefix'）而不是 query 参数：
+    // 路径里直接带人设名，浏览器可对每个 URL 独立缓存与复用连接。
+    // 名字必须命中内置人设白名单（isBuiltinPersona），路径穿越因此不可能发生。
+    wsCtx.webServer.register({
+      kind: 'prefix',
+      path: '/api/soul/persona-art',
+      handler: async (req, res) => {
+        try {
+          if (req.method !== 'GET') {
+            res.writeHead(405, { 'content-type': 'application/json' })
+            res.end(JSON.stringify({ ok: false, error: 'Method not allowed' }))
+            return
+          }
+          const raw = String(req.url || '').split('?')[0]
+          const name = decodeURIComponent(raw.slice('/api/soul/persona-art'.length).replace(/^\/+/, ''))
+          const art = resolvePersonaArt(name)
+          if (!art) {
+            // 图与占位图都没有（理论上只会在 assets 被外部删空时出现）
+            res.writeHead(404, { 'content-type': 'application/json' })
+            res.end(JSON.stringify({ ok: false, error: `没有可用的插画：${name || '(空)'}` }))
+            return
+          }
+          const body = readFileSync(art.file)
+          res.writeHead(200, {
+            'content-type': art.mime,
+            'content-length': String(body.length),
+            // 图随包发布、路径即内容标识 ⇒ 可长期缓存；换图必然伴随版本号变化
+            'cache-control': 'public, max-age=86400'
+          })
+          res.end(body)
+        } catch (err) {
+          res.writeHead(500, { 'content-type': 'application/json' })
+          res.end(JSON.stringify({ ok: false, error: String(err.message || err) }))
+        }
+      }
+    })
   })
 }
 
@@ -786,7 +1185,9 @@ const COMMAND_MESSAGES = {
     onLabel: '开启',
     offLabel: '关闭',
     personasLabel: '人设预设',
-    pendingHint: '⚠ 有待确认的人设变更：/soul confirm 确认，/soul reject 拒绝',
+    // 提议是**内存态**（重启即失效）、也没有 TTL，所以必须让用户看到它是什么时候提出的，
+    // 否则一条陈旧提议会一直挂着而无法判断新鲜度（proposedAt 此前只写不读）。
+    pendingHint: (at) => `⚠ 有待确认的人设变更（提出于 ${at}）：/soul confirm 确认，/soul reject 拒绝`,
     noPending: '没有待确认的人设变更',
     confirmDone: (detail) => `✅ 已应用人设变更：${detail}`,
     rejectDone: '✅ 已拒绝待确认的人设变更',
@@ -797,20 +1198,32 @@ const COMMAND_MESSAGES = {
     builtinDeleteBlocked: (name) => `「${name}」是内置预设，无法删除`,
     useDone: (name) => `✅ 已应用预设「${name}」`,
     useUnchanged: (name) => `ℹ 预设「${name}」与当前配置一致，无需变更`,
+    // 预设里部分字段的取值非法（历史值或手改）：合法字段照常应用，被跳过的必须说出来
+    usePartial: (name, fields) => `⚠ 预设「${name}」已部分应用，以下字段取值非法、已跳过：${fields}`,
+    useAllInvalid: (name, fields) => `✗ 预设「${name}」没有可应用的合法字段：${fields}`,
     personaMissing: (name) => `预设「${name}」不存在`,
     delDone: (name) => `✅ 已删除预设「${name}」`,
     listTitle: '📋 人设预设',
     listEmpty: '暂无人设预设，使用 /soul save <名称> 保存当前配置',
+    // 列表行报告预设实际覆盖的人格维度数量（取代 v0.7.1 起恒为空的「昵称」列）
+    listCovers: (n) => `覆盖 ${n} 项`,
     saveUsage: '用法：/soul save <名称>（1-30 个字符）',
     useUsage: '用法：/soul use <名称>',
     delUsage: '用法：/soul del <名称>',
     setUsage: '用法：/soul set key=value ...（可用字段：enabled / style / headingLists / emoji / tables / replyLength / language / nickname / occupation / bio / customInstructions / trailEnabled / trailColor / trailSpeed / trailWidth）',
     unknownField: '未知配置项',
-    invalidBoolean: (key) => `${key} 取值必须为 true / false`,
+    invalidBoolean: (key, value) => `${key} 取值必须为 true / false（收到：${JSON.stringify(value)}）`,
     setNoChanges: '配置无变化，未做修改',
     setDone: (keys) => `✅ 已更新：${keys.join('、')}`,
     help: '使用 /soul show 查看详情\n使用 /soul set style=humorous 修改配置项\n使用 /soul save <名称> 保存预设；/soul use <名称> 应用；/soul list 查看；/soul del <名称> 删除\n使用 /soul confirm 或 /soul reject 处理待确认的人设变更\n使用 /soul reset 重置配置\n使用 /soul enable 启用；/soul disable 禁用\n使用 /soul 昵称xxx 设置昵称',
     resetDone: '✅ 配置已重置为默认值',
+    resetRecovered: (file) => `✅ 配置已重置为默认值（损坏的文件已备份为 ${file}）`,
+    deliveryLabel: '送达：',
+    deliveryOk: (delivered, total) => total === 0
+      ? '暂无活动会话（配置将在新会话生效）'
+      : `已注入 ${delivered}/${total} 个活动会话`,
+    deliveryNoAgentsService: 'agents 服务不可用 —— 新配置只能经 system prompt section 送达，保存后可能要到新会话才生效',
+    deliveryInjectFailed: (detail) => `向活动会话注入失败：${detail}`,
     enableDone: '✅ 个性化设置已启用',
     disableDone: '✅ 个性化设置已禁用',
     nicknameDone: (n) => `✅ 昵称已设置为：${n}`,
@@ -867,7 +1280,9 @@ const COMMAND_MESSAGES = {
     onLabel: 'on',
     offLabel: 'off',
     personasLabel: 'Personas',
-    pendingHint: '⚠ Pending persona proposal: /soul confirm to apply, /soul reject to discard',
+    // 提议是**内存态**（重启即失效）、也没有 TTL，所以必须让用户看到它是什么时候提出的，
+    // 否则一条陈旧提议会一直挂着而无法判断新鲜度（proposedAt 此前只写不读）。
+    pendingHint: (at) => `⚠ Pending persona proposal (raised at ${at}): /soul confirm to apply, /soul reject to discard`,
     noPending: 'No pending persona proposal',
     confirmDone: (detail) => `✅ Persona changes applied: ${detail}`,
     rejectDone: '✅ Pending persona proposal discarded',
@@ -877,20 +1292,32 @@ const COMMAND_MESSAGES = {
     builtinDeleteBlocked: (name) => `"${name}" is a built-in persona and cannot be deleted`,
     useDone: (name) => `✅ Persona "${name}" applied`,
     useUnchanged: (name) => `ℹ Persona "${name}" matches the current config`,
+    // 预设里部分字段的取值非法（历史值或手改）：合法字段照常应用，被跳过的必须说出来
+    usePartial: (name, fields) => `⚠ Persona "${name}" applied partially; skipped as invalid: ${fields}`,
+    useAllInvalid: (name, fields) => `✗ Persona "${name}" has no applicable field: ${fields}`,
     personaMissing: (name) => `Persona "${name}" does not exist`,
     delDone: (name) => `✅ Persona "${name}" deleted`,
     listTitle: '📋 Personas',
     listEmpty: 'No personas yet — save the current config with /soul save <name>',
+    // 列表行报告预设实际覆盖的人格维度数量（取代 v0.7.1 起恒为空的「昵称」列）
+    listCovers: (n) => `covers ${n} field${n === 1 ? '' : 's'}`,
     saveUsage: 'Usage: /soul save <name> (1-30 chars)',
     useUsage: 'Usage: /soul use <name>',
     delUsage: 'Usage: /soul del <name>',
     setUsage: 'Usage: /soul set key=value ... (fields: enabled / style / headingLists / emoji / tables / replyLength / language / nickname / occupation / bio / customInstructions / trailEnabled / trailColor / trailSpeed / trailWidth)',
     unknownField: 'Unknown field',
-    invalidBoolean: (key) => `${key} must be true or false`,
+    invalidBoolean: (key, value) => `${key} must be true or false (got: ${JSON.stringify(value)})`,
     setNoChanges: 'No config changes to apply',
     setDone: (keys) => `✅ Updated: ${keys.join(', ')}`,
     help: 'Use /soul show for details\nUse /soul set style=humorous to change fields\nUse /soul save <name> / use <name> / list / del <name> for personas\nUse /soul confirm or /soul reject for pending persona proposals\nUse /soul reset to reset\nUse /soul enable / disable to toggle\nUse /soul <nickname> to set your nickname',
     resetDone: '✅ Configuration reset to defaults',
+    resetRecovered: (file) => `✅ Configuration reset to defaults (the damaged file was backed up as ${file})`,
+    deliveryLabel: 'Delivery: ',
+    deliveryOk: (delivered, total) => total === 0
+      ? 'no active sessions (the config will apply in a new session)'
+      : `injected into ${delivered}/${total} active sessions`,
+    deliveryNoAgentsService: 'the `agents` service is unavailable — the new config can only travel via the system prompt section, so it may take a new session to apply',
+    deliveryInjectFailed: (detail) => `injection into active sessions failed: ${detail}`,
     enableDone: '✅ Personalization enabled',
     disableDone: '✅ Personalization disabled',
     nicknameDone: (n) => `✅ Nickname set to: ${n}`,
@@ -908,6 +1335,17 @@ const COMMAND_KEYWORDS = new Set(['show', 'reset', 'enable', 'disable', 'save',
 // /soul set 中按布尔解析的键；其余键以原始字符串交给 sanitizeConfig 校验
 const COMMAND_BOOLEAN_KEYS = new Set(['enabled', 'trailEnabled'])
 
+// 配置字段名 → 小写形式。子命令关键字本就忽略大小写（见 handler 里的 toLowerCase），
+// 键名此前却严格区分：`/soul set STYLE=humorous` 会报「未知配置项」，与用户预期不一致。
+// 这里按小写**映射回真实字段名**（不是把键 toLowerCase —— 那会把 headingLists 压成
+// headinglists，反而匹配不上白名单）。非配置字段仍按未知处理。
+const COMMAND_FIELD_BY_LOWER = new Map(Object.keys(DEFAULT_CONFIG).map((key) => [key.toLowerCase(), key]))
+
+// 归一化 /soul set 的键名：命中真实字段则用其准确写法，否则原样交给白名单判未知
+function normalizeSetKey(key) {
+  return COMMAND_FIELD_BY_LOWER.get(key.toLowerCase()) || key
+}
+
 // 解析 /soul set 的键值参数：key=value 对；不含 = 的 token 追加到上一个值
 // （支持含空格的文本值，如：/soul set bio=写代码 多年 经验）
 function parseSetArgs(rest) {
@@ -963,26 +1401,37 @@ function registerCommands(ctx) {
               `${t.replyLengthLabel}=${t.replyLengthNames[config.replyLength] || config.replyLength}`
             ].join(t.listSep)
             const instructions = config.customInstructions || t.notSet
-            const personaCount = Object.keys(config.personas || {}).length
-            const pendingLine = pendingPersonaProposal ? `\n${t.pendingHint}` : ''
+            // 预设数量用**合并视图**（内置 + 用户），与 /soul list 和 Web UI 一致：
+            // 此前只数 config.personas（磁盘上的用户预设），于是同一个「人设预设」
+            // 在 show 里显示 2、在 list 里显示 9。
+            const personaCount = Object.keys(mergePersonas(config.personas)).length
+            const pendingLine = pendingPersonaProposal
+              ? `\n${t.pendingHint(new Date(pendingPersonaProposal.proposedAt).toLocaleString())}`
+              : ''
             const trailText = t.trailLine(
               config.trailEnabled ? t.enabled : t.disabled,
               config.trailColor,
               t.trailSpeedNames[config.trailSpeed] || config.trailSpeed,
               t.trailWidthNames[config.trailWidth] || config.trailWidth
             )
+            // 送达状态：直接回答「我刚改了配置，为什么没生效」这个高频疑问 ——
+            // 两条通道里注入是否真的送到了活动会话，此前完全没有可观测点。
+            const delivery = deliveryProblemText(config) || t.deliveryOk(deliveryState.delivered, deliveryState.agents)
 
             return {
               kind: 'success',
-              text: `${t.showTitle}\n\n${t.statusLabel}${t.colon}${status}\n${t.nicknameLabel}${t.colon}${nickname}\n${t.occupationLabel}${t.colon}${occupation}\n${t.bioLabel}${t.colon}${bio}\n${t.styleLabel}${t.colon}${styleName}\n${t.traitsLabel}${t.colon}${traitsLine}\n${t.trailLabel}${t.colon}${trailText}\n${t.instructionsLabel}${t.colon}${instructions}\n${t.toolConfirmLabel}${t.colon}${config.requireToolConfirmation ? t.onLabel : t.offLabel}\n${t.personasLabel}${t.colon}${personaCount}${pendingLine}\n\n${t.help}`
+              text: `${t.showTitle}\n\n${t.statusLabel}${t.colon}${status}\n${t.nicknameLabel}${t.colon}${nickname}\n${t.occupationLabel}${t.colon}${occupation}\n${t.bioLabel}${t.colon}${bio}\n${t.styleLabel}${t.colon}${styleName}\n${t.traitsLabel}${t.colon}${traitsLine}\n${t.trailLabel}${t.colon}${trailText}\n${t.instructionsLabel}${t.colon}${instructions}\n${t.toolConfirmLabel}${t.colon}${config.requireToolConfirmation ? t.onLabel : t.offLabel}\n${t.personasLabel}${t.colon}${personaCount}${pendingLine}\n${t.deliveryLabel}${t.colon}${delivery}\n\n${t.help}`
             }
           }
 
           if (first === 'reset') {
-            // 重置活动配置，但保留人设预设库
-            const { config: updated, promptChanged } = await commitConfig(current => defaultConfigPreservingPersonas(current))
+            // 重置活动配置，但保留人设预设库。
+            // 经由逃生口：配置损坏时这是唯一还能落盘的操作（先备份损坏文件）。
+            const { config: updated, promptChanged, backupPath } = await resetConfigWithEscape()
             if (promptChanged.length > 0) refreshPromptAndInject(ctx, updated)
-            return { kind: 'success', text: t.resetDone }
+            return backupPath
+              ? { kind: 'success', text: t.resetRecovered(backupPath) }
+              : { kind: 'success', text: t.resetDone }
           }
 
           if (first === 'enable') {
@@ -1020,13 +1469,20 @@ function registerCommands(ctx) {
             if (!entry) {
               return { kind: 'error', text: t.personaMissing(personaName) }
             }
-            // 预设值保存时已校验；此处再过一遍白名单，防御手改文件等异常数据
-            const { patch } = sanitizeConfig(pickPersonaValues(entry))
-            const { config: updated, changed, promptChanged } = await commitConfig(c => ({ ...c, ...patch }))
+            // 预设值保存时已校验；此处再过一遍白名单，防御手改文件等异常数据。
+            // 非法字段不再被静默丢弃：applied=0 ⇒ 报错；有部分非法 ⇒ 明示被跳过的字段。
+            const { changed, invalid, applied } = await applyPersonaEntry(ctx, entry)
+            const fieldsText = invalid.join(t.listSep)
+            // 预设未声明任何字段（applied=0 且 invalid=0）不是错误，是「无可应用内容」
+            if (invalid.length > 0 && applied === 0) {
+              return { kind: 'error', text: t.useAllInvalid(personaName, fieldsText) }
+            }
+            if (invalid.length > 0) {
+              return { kind: 'success', text: t.usePartial(personaName, fieldsText) }
+            }
             if (changed.length === 0) {
               return { kind: 'success', text: t.useUnchanged(personaName) }
             }
-            if (promptChanged.length > 0) refreshPromptAndInject(ctx, updated)
             return { kind: 'success', text: t.useDone(personaName) }
           }
 
@@ -1041,9 +1497,13 @@ function registerCommands(ctx) {
             const lines = names.map((personaName) => {
               const entry = view[personaName]
               const styleText = STYLE_VALUES.includes(entry.style) ? (t.styleNames[entry.style] || entry.style) : (entry.style || '-')
-              const nickText = entry.nickname || '-'
+              // 原先这里显示 `昵称=${entry.nickname || '-'}`，但 v0.7.1 起预设**不含**
+              // 「关于你」（PERSONA_FIELDS 里没有 nickname，normalizePersonas 也会剥离）
+              // ⇒ 该列恒为「昵称=-」，是一列永远没有信息的死数据。改为报告它实际
+              // 覆盖了几个人格维度：这才是「应用这个预设会改变多少东西」的有效信息。
+              const covers = declaredPersonaKeys(entry).length
               const mark = entry.builtin ? ` [${t.builtinName}]` : ''
-              return `${personaName === activeName ? '✔ ' : '• '}${personaName}${mark} ｜ ${t.styleLabel}=${styleText} ｜ ${t.nicknameLabel}=${nickText}`
+              return `${personaName === activeName ? '✔ ' : '• '}${personaName}${mark} ｜ ${t.styleLabel}=${styleText} ｜ ${t.listCovers(covers)}`
             })
             return { kind: 'success', text: `${t.listTitle} [${names.length}]\n${lines.join('\n')}` }
           }
@@ -1069,12 +1529,17 @@ function registerCommands(ctx) {
             const pairs = parseSetArgs(rest)
             if (!pairs || pairs.length === 0) return { kind: 'error', text: t.setUsage }
             const rawPatch = {}
-            for (const [key, value] of pairs) {
+            for (const [rawKey, rawValue] of pairs) {
+              // 键名忽略大小写（与子命令关键字一致）；值统一 trim（枚举此前不 trim）
+              const key = normalizeSetKey(rawKey)
+              const value = rawValue.trim()
               if (COMMAND_BOOLEAN_KEYS.has(key)) {
                 const flag = value.toLowerCase()
                 if (['true', '1', 'on', 'yes'].includes(flag)) rawPatch[key] = true
                 else if (['false', '0', 'off', 'no'].includes(flag)) rawPatch[key] = false
-                else return { kind: 'error', text: t.failed(t.invalidBoolean(key)) }
+                // 带上收到的实际值：`enabled=true extra` 会解析成值 "true extra"，
+                // 只说「必须为 true / false」会让人以为是关键字写错了
+                else return { kind: 'error', text: t.failed(t.invalidBoolean(key, value)) }
               } else {
                 rawPatch[key] = value
               }
@@ -1084,7 +1549,9 @@ function registerCommands(ctx) {
             if (errorKeys.length > 0) {
               return { kind: 'error', text: t.failed(`${errorKeys[0]}: ${errors[errorKeys[0]]}`) }
             }
-            const droppedKeys = Object.keys(rawPatch).filter((key) => !(key in patch))
+            // hasOwn 而非 `in`：后者会命中原型链（`constructor` 之类恒为 true），
+            // 让真正未知的字段被误判成「已识别」而不进 droppedKeys。
+            const droppedKeys = Object.keys(rawPatch).filter((key) => !hasOwn(patch, key))
             if (Object.keys(patch).length === 0) {
               return { kind: 'error', text: t.failed(droppedKeys.length > 0 ? `${t.unknownField}: ${droppedKeys.join(', ')}` : t.setUsage) }
             }
@@ -1129,21 +1596,33 @@ function registerSystemPrompt(ctx) {
     let disposeSection = null
 
     const registerSection = () => {
-      // 重新注册前先移除旧 section，触发 system-prompt/change，
-      // 让 DSH 丢弃当前会话已经缓存的 system prompt 快照。
+      // 重新注册前先移除旧 section。
+      //
+      // 注意：这里**不是**靠 `system-prompt/change` 让宿主丢弃快照 —— 该事件当前全树
+      // 没有任何消费者（只在 dsh-system-prompt 内部 emit）。真正让新配置生效的是
+      // section 的 text provider 在每次装配时重新求值（宿主对函数式 text 不做缓存），
+      // 以及活动会话注入这条第二条通道。两件事都有回归兜底：
+      // scripts/verify-live-prompt.mjs / verify-e2e-prompt.mjs。
+      //
+      // 保留「先移除再注册」是因为宿主按名字插入、同名会抛重复错。
       disposeSection?.()
 
       disposeSection = spCtx.systemPrompt.section({
         name: 'soul:persona',
         order: 0,
-        text: () => {
-          const prompt = compilePrompt(configCache || DEFAULT_CONFIG)
-          if (prompt) {
-            // console.log(`[dsh-soul] 系统提示词已组装：${prompt.substring(0, 100)}...`)
-          }
-          return prompt
-        }
+        // 关闭宿主的提示词插值（默认开启）。插值是严格模式：文本里每一对完整的
+        // {{...}} 都必须命中一个已注册变量，否则 renderPrompt 抛错；而本 section
+        // 的装配里变量集为空 ⇒ 用户在「自定义指令」里写一句模板语法（例如 {{name}}）
+        // 就会让整个 system prompt 装配失败。该抛错位于 agent.step() 开头且无
+        // try/catch ⇒ 不是「忽略那段文字」，而是**该会话的每一轮都失败**。
+        //
+        // 代价为 0：我们不使用任何宿主提示词变量（需要上下文时，text 本身就是
+        // provider）。关掉它同时让「预览所见」与「真实注入」逐字符一致。
+        interpolate: false,
+        text: () => compilePrompt(configCache || DEFAULT_CONFIG)
       })
+
+      deliveryState.sectionRegisteredAt = new Date().toISOString()
     }
 
     registerSection()
@@ -1151,12 +1630,12 @@ function registerSystemPrompt(ctx) {
     globalUpdatePrompt = async () => {
       await loadConfig()
       registerSection()
-      // console.log('[dsh-soul] 系统提示词已更新，当前会话下一次请求将使用最新配置')
     }
 
     ctx.effect(() => () => {
       disposeSection?.()
       disposeSection = null
+      deliveryState.sectionRegisteredAt = null
       if (globalUpdatePrompt) {
         globalUpdatePrompt = null
       }
@@ -1164,6 +1643,117 @@ function registerSystemPrompt(ctx) {
   })
 }
 
+// ==================== 人设变更的宿主审批 ====================
+//
+// 确认模式开启时，人设变更走**宿主的原生审批交互**（输入框处的
+// 「允许一次 / 拒绝」面板），而不是让用户手敲 /soul confirm。
+//
+// 为什么复用宿主审批而不是自绘弹框：
+//   · 面板、键盘（Enter 允许 / Esc 拒绝）、读屏、一次性授权语义都由宿主实现；
+//   · ask / decided 会写入会话审计日志（谁在何时批准了什么人设变更）；
+//   · 多个插件同时要审批时由 waterfall 自然排队，不会出现两个弹框抢焦点。
+//
+// 返回三态，调用方据此决定继续落盘 / 拒绝 / 退化：
+//   'allowed'    —— 用户批准，调用方继续写盘
+//   'rejected'   —— 用户拒绝，调用方返回失败
+//   'unavailable'—— 拿不到审批能力（无 agent、宿主未装审批服务、无 Web UI 应答者），
+//                    调用方退化到 /soul confirm 文本流程
+//
+// 刻意**不加超时**：用户不点就一直等，与宿主其它审批一致。
+// 加超时会产生「只是没来得及点就被自动拒绝」这种难以解释的行为。
+function approvalOutcomeOf(outcome) {
+  if (outcome === 'allowed-once') return 'allowed'
+  if (outcome === 'rejected') return 'rejected'
+  // 'cancelled'（请求被撤回）与 'unavailable'（无应答者）都归为「审批不可用」，
+  // 交由文本流程兜底 —— 用户仍有机会通过 /soul confirm 应用这次变更。
+  return 'unavailable'
+}
+
+// 读取当前生效的审批策略。复刻宿主 ApprovalService.effectivePolicy 的算法
+// （overrideOf(session) ?? config.policy ?? 'ask'）。
+//
+// 任一项不可读时保守回落到 'ask' —— 回落到 ask 意味着「仍去问用户」，
+// 失败方向是「多问一次」而不是「静默改配置」。
+function resolveApprovalPolicy(approval, agent) {
+  try {
+    const session = agent && agent.session
+    if (typeof approval.overrideOf === 'function' && session) {
+      const override = approval.overrideOf(session)
+      if (override === 'never' || override === 'ask') return override
+    }
+    const configured = approval.config && approval.config.policy
+    if (configured === 'never' || configured === 'ask') return configured
+  } catch {
+    // 读策略失败不应影响主流程 —— 继续按 ask 走（让宿主的真实判定说话）
+  }
+  return 'ask'
+}
+
+async function requestToolApproval(ctx, exec, changes) {
+  try {
+    // agent 是必须的：宿主客户端表单靠它解析会话归属，拿不到就会放弃应答
+    //（dsh-client-ui-approval 里 scopeOf(owner) === undefined 时直接 next()）。
+    const agent = exec && exec.agent
+    if (!agent) return 'unavailable'
+    // 服务解析：以**注册工具的 ctx**（toolsCtx）为主 —— 这与 dsh-tools 自己的
+    // serviceAsk 写法一致（它在工具执行中用 this.ctx.get('approval')）。
+    //
+    // 实测教训：最初传的是 registerTools 的根 ctx，ctx.get('approval') 返回
+    // undefined ⇒ 每次都退化成 /soul confirm 文本流程，看起来像「功能没生效」。
+    // 另外 cordis 的 agent 作用域可能更精确（审批本就该路由到该 agent 的会话），
+    // 故一并作为候选，任一命中即用。
+    const candidates = []
+    if (agent && typeof agent.ctx === 'object' && agent.ctx && typeof agent.ctx.get === 'function') candidates.push(agent.ctx)
+    if (ctx && typeof ctx.get === 'function') candidates.push(ctx)
+    let approval
+    for (const c of candidates) {
+      const found = c.get('approval')
+      if (found && typeof found.request === 'function') { approval = found; break }
+    }
+    if (!approval || typeof approval.request !== 'function') return 'unavailable'
+
+    // —— 策略预判：避免把「通道被禁用」误报成「用户拒绝」——
+    //
+    // 宿主在 effectivePolicy(session) === 'never' 时**不问任何人**，直接返回
+    // 'rejected'（见 dsh-user-approval 的 decide()）。而 'rejected' 这个取值把
+    // 两件完全不同的事混在一起：
+    //   ① 用户真的点了「拒绝」
+    //   ② 审批通道被策略禁用，无人被询问
+    // 若不区分，就会向用户报告一件**从未发生的事**（实测踩过：策略为 never 时
+    // 提示「你在审批面板中拒绝了」，而用户根本没看到面板）。
+    //
+    // 故在发起请求前复刻宿主的策略算法，判定为 'never' 时直接走文本确认
+    // （与 'unavailable' 同一落点），并给出准确文案。
+    //
+    // 为什么不直接应用变更（把 never 当作「无需确认」）：requireToolConfirmation
+    // 是用户为本功能单独设的偏好，而 never 是会话级的审批通道策略。用后者悄悄推翻
+    // 前者，等于让一个通道开关替用户取消了他自己的功能选择。真要免确认，正确做法是
+    // 关掉设置页里的「人设变更需确认」开关 —— 那才是为这件事准备的开关。
+    if (resolveApprovalPolicy(approval, agent) === 'never') return 'policy-disabled'
+
+    const detail = Object.entries(changes)
+      .map(([key, value]) => `${key}=${JSON.stringify(value)}`)
+      .join(', ')
+    const outcome = await approval.request({
+      agent,
+      toolName: 'set_persona',
+      ...(exec && exec.callId !== undefined ? { callId: exec.callId } : {}),
+      ...(exec && exec.signal !== undefined ? { signal: exec.signal } : {}),
+      reason: '人设变更需要你的确认',
+      // 中英并列：宿主按当前 UI 语言选取，审计日志里仍保留 reason 原文
+      displayReason: {
+        en: 'Persona change requires your confirmation',
+        zh: '人设变更需要你的确认',
+        'zh-Hans': '人设变更需要你的确认'
+      }
+    })
+    return approvalOutcomeOf(outcome)
+  } catch {
+    // 审批链路任何异常都不应让人设变更彻底失败 —— 退化为文本确认
+    return 'unavailable'
+  }
+}
+
 // ==================== Agent 可调用工具 ====================
 
 // tools 是可选 host 服务且 ABI 版本敏感（同 dsh-share-page 的守卫）。
@@ -1177,53 +1767,62 @@ function registerTools(ctx) {
       }
       toolsCtx.tools.register(defineTool({
         name: 'set_persona',
+        // 描述是**模型侧**文本，中英并列：工具 schema 只在 apply 时注册一次，而
+        // `tools.register` 对同名重注册会抛 "already registered"，语言切换时无法
+        // 原地换描述（registry 只在注销旧句柄后才接受同名）。并列两种语言既覆盖
+        // zh / en 两种界面，又不必引入重注册的时序风险。
         description:
-          '调整当前个性化人设（昵称、回复风格和语调、自定义指令）。' +
+          '调整当前个性化设置（昵称、回复风格和语调、自定义指令）。' +
           '当用户明确要求改变称呼、语气、风格或角色时使用。' +
-          '只需要传入要修改的字段，未提供的字段保持不变。',
+          '只需要传入要修改的字段，未提供的字段保持不变。\n' +
+          'Adjust the current personalization settings (nickname, reply style & tone, custom instructions). ' +
+          'Use it when the user explicitly asks to change how they are addressed, the tone, the style, or the role. ' +
+          'Pass only the fields to change; omitted fields keep their current values.',
         parameters: {
-          nickname: { type: 'string', description: '用户昵称，回复时会使用这个称呼。' },
-          occupation: { type: 'string', description: '用户的职业。' },
-          bio: { type: 'string', description: '关于用户的介绍。' },
+          nickname: { type: 'string', description: '用户昵称，回复时会使用这个称呼。/ The nickname to address the user by.' },
+          occupation: { type: 'string', description: '用户的职业。/ The user’s occupation.' },
+          bio: { type: 'string', description: '关于用户的介绍。/ Background about the user.' },
           style: {
             type: 'string',
             enum: STYLE_VALUES,
-            description: '回复风格和语调：professional=专业严谨，casual=轻松自然，humorous=幽默风趣，roast=吐槽达人，efficient=高效干练。'
+            description: '回复风格和语调：professional=专业严谨，casual=轻松自然，humorous=幽默风趣，roast=吐槽达人，efficient=高效干练。/ Reply style & tone.'
           },
           language: {
             type: 'string',
             enum: LANGUAGE_VALUES,
-            description: '回复语言：zh=简体中文，en=English。'
+            description: '回复语言：zh=简体中文，en=English。/ Reply language.'
           },
           headingLists: {
             type: 'string',
             enum: TRAIT_VALUES,
-            description: '特质·标题和列表：default=默认，more=增强（采用清晰格式和列表结构），less=减弱（使用更多段落文本）。'
+            description: '特质·标题和列表：default=默认，more=增强（采用清晰格式和列表结构），less=减弱（使用更多段落文本）。/ Headings & lists.'
           },
           emoji: {
             type: 'string',
             enum: TRAIT_VALUES,
-            description: '特质·表情符号：default=默认，more=增强（使用较多表情符号），less=减弱（尽量减少使用表情符号）。'
+            description: '特质·表情符号：default=默认，more=增强（使用较多表情符号），less=减弱（尽量减少使用表情符号）。/ Emoji usage.'
           },
           tables: {
             type: 'string',
             enum: TRAIT_VALUES,
-            description: '特质·表格：default=默认，more=增强（呈现对比、多字段或结构化信息时优先使用表格），less=减弱（避免表格，改用列表或段落文本）。'
+            description: '特质·表格：default=默认，more=增强（呈现对比、多字段或结构化信息时优先使用表格），less=减弱（避免表格，改用列表或段落文本）。/ Table usage.'
           },
           replyLength: {
             type: 'string',
             enum: REPLY_LENGTH_VALUES,
-            description: '回复长度偏好：concise=简洁（直击要点、不展开），normal=适中（不额外约束），detailed=详尽（充分展开背景、步骤与推理）。'
+            description: '回复长度偏好：concise=简洁（直击要点、不展开），normal=适中（不额外约束），detailed=详尽（充分展开背景、步骤与推理）。/ Reply length preference.'
           },
-          customInstructions: { type: 'string', description: '额外的自定义指令，用于覆盖或补充当前人设。' },
+          customInstructions: { type: 'string', description: '额外的自定义指令，用于覆盖或补充当前人设。/ Extra custom instructions that override or extend the current persona.' },
         },
         output: {
           schema: {
             type: 'object',
             additionalProperties: false,
-            required: ['ok'],
+            // 注意：DSH 的 schema DSL **不支持根级 required**（作者错误：
+            // "schema.required is not supported by the value schema DSL"）。
+            // 必填只能标在属性上（property.required must be true when present）。
             properties: {
-              ok: { type: 'boolean' },
+              ok: { type: 'boolean', required: true },
               message: { type: 'string' },
               pending: {
                 type: 'boolean',
@@ -1232,6 +1831,9 @@ function registerTools(ctx) {
               changes: {
                 type: 'object',
                 description: '实际发生变化的字段',
+                // object 节点必须显式声明 additionalProperties
+                // （作者错误："...additionalProperties must be explicitly true or false"）
+                additionalProperties: false,
                 properties: {
                   nickname: { type: 'string' },
                   occupation: { type: 'string' },
@@ -1247,8 +1849,23 @@ function registerTools(ctx) {
               },
             },
           },
+          // 结果渲染：宿主每次工具**成功执行**后都会无条件调用它
+          // （dsh-tools 的 createSuccessResult → tool.output.render(...)）。
+          // 不提供会怎样：defineTool 无条件下包一份 `render(args, value) { return userRender(...) }`，
+          // 而 userRender 是 undefined ⇒ 注册能过（底层 register 校验的是包装后的函数），
+          // 但**每次成功调用都在渲染阶段抛 TypeError: userRender is not a function**，
+          // 宿主把它包成 projectionError("render")，用户视角是「Agent 说改了却报错」。
+          // 自带插件 19 个都提供它。契约：返回 [{ type: 'text', text }]（无损 JSON）。
+          render: (_args, value) => {
+            // 直接把 message 作为给模型读的文本：它已经是完整的一句话（含 pending 提议与
+            // 失败原因），再套一层 JSON.stringify 只会让模型多解析一层转义。
+            const text = typeof value?.message === 'string' && value.message.length > 0
+              ? value.message
+              : (value?.ok === true ? 'ok' : 'failed')
+            return [{ type: 'text', text }]
+          },
         },
-        async execute(args) {
+        async execute(args, exec) {
           try {
             // 与 HTTP 保存共用同一套校验（白名单 / 类型 / 长度 / 枚举）
             const { patch, errors } = sanitizeConfig(args)
@@ -1261,7 +1878,22 @@ function registerTools(ctx) {
               return { ok: true, message: T0.toolNoChanges }
             }
 
-            // 确认模式：不落盘，返回待确认提议（/soul confirm 应用、/soul reject 拒绝）
+            // 确认模式：先走**宿主的原生审批交互**（输入框处的「允许一次 / 拒绝」面板）。
+            //
+            // 三态处理：
+            //   allowed     → 用户已批准，继续往下走写盘（故这里不 return）
+            //   rejected    → 用户拒绝，返回失败且不落盘
+            // 三态 + 一个策略态：
+            //   allowed         → 用户已批准，继续往下走写盘（故这里不 return）
+            //   rejected        → 用户明确拒绝，返回失败且不落盘
+            //   unavailable     → 拿不到审批能力（无 agent / 宿主未装审批服务 /
+            //                     客户端没有应答者），退化到 /soul confirm 文本流程
+            //   policy-disabled → 审批通道被会话策略禁用（never）⇒ 同样走文本流程，
+            //                     但文案必须说明「通道被禁用」，不能谎称用户拒绝
+            //
+            // 退化路径必须保留：纯 TUI 或无 Web UI 的场景没有应答者，审批会返回
+            // 'unavailable'，此时文本流程是唯一可用的确认途径。删掉它会让这些场景
+            // 彻底无法确认人设变更。
             const snapshot = await loadConfig()
             if (snapshot.requireToolConfirmation) {
               const T0 = promptTextOf(snapshot)
@@ -1270,14 +1902,24 @@ function registerTools(ctx) {
                 return { ok: true, message: T0.toolNoChanges }
               }
               const proposalChanges = Object.fromEntries(pendingKeys.map((key) => [key, patch[key]]))
-              pendingPersonaProposal = { patch: proposalChanges, proposedAt: new Date().toISOString() }
-              const detail = pendingKeys.map((key) => `${key}=${JSON.stringify(patch[key])}`).join(', ')
-              return {
-                ok: true,
-                pending: true,
-                changes: proposalChanges,
-                message: `${T0.toolProposal}\n${detail}\n${T0.toolProposalHint}`
+              const verdict = await requestToolApproval(toolsCtx, exec, proposalChanges)
+              if (verdict === 'rejected') {
+                return { ok: false, message: T0.toolRejected }
+              }
+              if (verdict === 'unavailable' || verdict === 'policy-disabled') {
+                pendingPersonaProposal = { patch: proposalChanges, proposedAt: new Date().toISOString() }
+                const detail = pendingKeys.map((key) => `${key}=${JSON.stringify(patch[key])}`).join(', ')
+                // 通道被禁用时补一句准确说明：否则用户会以为是面板出了问题，
+                // 或误以为是自己拒绝了（此前的错误措辞正是这么来的）。
+                const why = verdict === 'policy-disabled' ? `${T0.toolApprovalDisabled}\n` : ''
+                return {
+                  ok: true,
+                  pending: true,
+                  changes: proposalChanges,
+                  message: `${T0.toolProposal}\n${detail}\n${why}${T0.toolProposalHint}`
+                }
               }
+              // verdict === 'allowed' ⇒ 落到下面的写盘路径
             }
 
             // 写队列内合并，避免与其他写入方（Web UI、/soul 命令）竞态；
@@ -1328,7 +1970,10 @@ export async function apply(ctx) {
       if (Object.keys(errors).length > 0) {
         throw new Error('配置校验失败：' + formatFieldErrors(errors))
       }
-      const { config } = await commitConfig(current => ({ ...current, ...patch }))
+      const { config, promptChanged } = await commitConfig(current => ({ ...current, ...patch }))
+      // 送达与另外三条写路径保持一致：服务调用方（其它插件）改配置后同样应当
+      // 立即反映到活动会话，否则「改了配置不生效」会从服务这条路再次出现。
+      if (promptChanged.length > 0) refreshPromptAndInject(ctx, config)
       return config
     },
     async getSystemPrompt() {
@@ -1336,7 +1981,9 @@ export async function apply(ctx) {
       return compilePrompt(config)
     },
     async resetConfig() {
-      const { config } = await commitConfig(current => defaultConfigPreservingPersonas(current))
+      // 与 HTTP / 斜杠命令两条重置入口共用逃生口
+      const { config, promptChanged } = await resetConfigWithEscape()
+      if (promptChanged.length > 0) refreshPromptAndInject(ctx, config)
       return config
     }
   })