dsh-soul 0.6.2 → 0.7.1

package/index.mjs

@@ -16,14 +16,15 @@
 //   - 注入系统提示词到 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 { createUserMessage } from '@deepseek-ai/dsh-llm'
 import {
   DEFAULT_CONFIG,
   STYLE_VALUES,
   TRAIT_VALUES,
+  REPLY_LENGTH_VALUES,
   LANGUAGE_VALUES,
   PERSONA_FIELDS,
   PERSONA_NAME_MAX,
@@ -32,6 +33,8 @@ import {
   sanitizePersonaName
 } from './lib/config.mjs'
 import { createInjectionSource } from './lib/injection.mjs'
+import { isBuiltinPersona, mergePersonas, personaMatches, resolvePersona, declaredPersonaKeys } from './lib/personas.mjs'
+import { configWriteRefusal, describeConfigFailure, moveAsideConfigFile, readConfigFile, writeConfigFile } from './lib/store.mjs'
 
 const name = 'soul'
 
@@ -40,6 +43,19 @@ 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
+  }
+}
+
 // ==================== 提示词文案与构建器 ====================
 
 // 提示词固定文案表：所有进入 system prompt / 会话注入 / 工具返回的文本，
@@ -69,6 +85,14 @@ const PROMPT_TEXT = {
       more: '在回复中使用较多表情符号',
       less: '尽量减少使用表情符号'
     },
+    tables: {
+      more: '在呈现对比、多字段信息或结构化内容时优先使用表格',
+      less: '避免使用表格，改用列表或段落文本呈现'
+    },
+    replyLength: {
+      concise: '回答尽量简洁，直击要点，不展开无关内容',
+      detailed: '回答尽量详尽，充分展开背景、步骤与推理过程'
+    },
     replyLanguage: {
       zh: '必须使用简体中文回复',
       en: '必须使用英语（English）回复'
@@ -116,6 +140,14 @@ const PROMPT_TEXT = {
       more: 'Use emojis fairly often in replies',
       less: 'Keep emoji usage to a minimum'
     },
+    tables: {
+      more: 'Prefer tables when presenting comparisons, multi-field or structured information',
+      less: 'Avoid tables; use lists or paragraph text instead'
+    },
+    replyLength: {
+      concise: 'Keep answers concise: hit the key points and skip unrelated elaboration',
+      detailed: 'Give detailed answers: fully expand on background, steps and reasoning'
+    },
     replyLanguage: {
       zh: '必须使用简体中文回复',
       en: 'You must reply in English.'
@@ -155,12 +187,16 @@ function buildUserProfile(config, T) {
   return lines.join('\n')
 }
 
-// 行为块：回复风格和语调 + 特质 + 输出语言
+// 行为块：回复风格和语调 + 特质（标题和列表 / 表情符号 / 表格）+ 回复长度 + 输出语言。
+// 缺项（如 tables=default、replyLength=normal）在文案表中没有对应键，直接跳过、不产生文本，
+// 因此默认配置编译出的提示词与新增这两个维度之前完全一致。
 function buildBehavior(config, T) {
   const parts = []
   if (config.style && T.styles[config.style]) parts.push(`${T.styleLabel}${T.styles[config.style]}`)
   if (config.headingLists && T.headingLists[config.headingLists]) parts.push(T.headingLists[config.headingLists])
   if (config.emoji && T.emoji[config.emoji]) parts.push(T.emoji[config.emoji])
+  if (config.tables && T.tables[config.tables]) parts.push(T.tables[config.tables])
+  if (config.replyLength && T.replyLength[config.replyLength]) parts.push(T.replyLength[config.replyLength])
   if (config.language && T.replyLanguage[config.language]) parts.push(T.replyLanguage[config.language])
   return parts.join(T.joiner)
 }
@@ -176,29 +212,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
 }
@@ -255,6 +310,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)
@@ -329,14 +409,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
   }
 
@@ -344,7 +491,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: [{
@@ -355,17 +506,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)
@@ -388,7 +561,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) {
@@ -412,7 +596,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' })
           }
@@ -433,6 +617,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 })
@@ -442,7 +633,50 @@ function registerRoutes(ctx) {
       }
     })
     
-    // 预览系统提示词端点已在 v0.2.0 移除（提示词预览功能下线）
+    // 预览「未保存的编辑」编译出的 system prompt：以已保存配置为底，用请求体中
+    // 通过校验的字段覆盖后编译。
+    //
+    // **不落盘、不注入会话** —— 纯只读旁路，供设置在保存前确认真正会被注入的内容。
+    // v0.1.x 曾有同类端点，随 v0.2.0 精简重构下线；此处恢复并修掉旧实现的一个疏漏：
+    // 旧版直接展开请求体（{ ...current, ...draft }）未经校验，而这里与保存路径共用
+    // 同一套 sanitizeConfig —— 非法字段既不参与预览、也不会落盘，并通过 invalid
+    // 回报给客户端，避免出现「预览悄悄沿用了旧值」这种看不出原因的偏差。
+    wsCtx.webServer.register({
+      kind: 'exact',
+      path: '/api/soul/prompt/preview',
+      handler: async (req, res) => {
+        const send = (status, body) => {
+          res.writeHead(status, { 'content-type': 'application/json' })
+          res.end(JSON.stringify(body))
+        }
+
+        try {
+          if (req.method !== 'POST') {
+            send(405, { ok: false, error: 'Method not allowed' })
+            return
+          }
+
+          const parsed = await readJsonBody(req)
+          if (!parsed.ok) {
+            send(parsed.status, { ok: false, error: parsed.error })
+            return
+          }
+
+          const { patch, errors } = sanitizeConfig(parsed.body)
+          const current = await loadConfig()
+          const draft = { ...current, ...patch }
+
+          send(200, {
+            ok: true,
+            prompt: compilePrompt(draft),
+            enabled: draft.enabled,
+            invalid: Object.keys(errors)
+          })
+        } catch (err) {
+          send(500, { ok: false, error: String(err.message || err) })
+        }
+      }
+    })
 
     // 重置配置
     wsCtx.webServer.register({
@@ -455,14 +689,67 @@ function registerRoutes(ctx) {
         }
 
         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) })
         }
@@ -478,14 +765,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) {
@@ -505,16 +799,42 @@ function hasOwn(obj, key) {
   return Object.prototype.hasOwnProperty.call(obj, key)
 }
 
-// 计算与当前活动配置完全一致的预设名（多个命中时取名称排序最前）
+// 计算与当前活动配置匹配的预设名（多个命中时取名称排序最前）。
+// 匹配语义是「部分覆盖」而非全字段相等，理由见 lib/personas.mjs 的 personaMatches。
 function findActivePersonaName(config) {
-  const personas = config.personas || {}
-  for (const personaName of Object.keys(personas).sort()) {
-    const entry = personas[personaName]
-    if (PERSONA_FIELDS.every((key) => entry[key] === config[key])) return personaName
+  const view = mergePersonas(config.personas)
+  for (const personaName of Object.keys(view).sort()) {
+    if (personaMatches(view[personaName], config)) return personaName
   }
   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) }
+}
+
 // 人设预设 HTTP 路由：列表 / 保存 / 使用 / 删除。
 // 保存与删除仅变更 personas 库（diffKeys 跳过该字段），不会触发会话注入；
 // 使用会变更活动配置字段，走常规 promptChanged 门控注入。
@@ -536,7 +856,7 @@ function registerPersonaRoutes(ctx) {
             return
           }
           const config = await loadConfig()
-          send(res, 200, { ok: true, personas: config.personas || {}, activeName: findActivePersonaName(config) })
+          send(res, 200, { ok: true, ...personaLibrary(config) })
         } catch (err) {
           send(res, 500, { ok: false, error: String(err.message || err) })
         }
@@ -563,12 +883,18 @@ function registerPersonaRoutes(ctx) {
             send(res, 400, { ok: false, error: `预设名称无效（1-${PERSONA_NAME_MAX} 个字符）` })
             return
           }
+          // 内置名一律不可写入：内置预设只存在于代码里，若允许同名落盘，合并视图会
+          // 遮蔽它，用户就会得到一个「保存了却看不见、也删不掉」的幽灵条目。
+          if (isBuiltinPersona(personaName)) {
+            send(res, 400, { ok: false, error: `「${personaName}」是内置预设，请换一个名称` })
+            return
+          }
           const { config: updated } = await commitConfig((current) => {
             const personas = clonePersonas(current.personas)
             personas[personaName] = { ...personaSnapshotOf(current), updatedAt: new Date().toISOString() }
             return { ...current, personas }
           })
-          send(res, 200, { ok: true, personas: updated.personas || {}, activeName: findActivePersonaName(updated) })
+          send(res, 200, { ok: true, ...personaLibrary(updated) })
         } catch (err) {
           send(res, 500, { ok: false, error: String(err.message || err) })
         }
@@ -592,17 +918,22 @@ function registerPersonaRoutes(ctx) {
           }
           const personaName = sanitizePersonaName(parsed.body && parsed.body.name)
           const current = await loadConfig()
-          if (!personaName || !hasOwn(current.personas || {}, personaName)) {
+          // 内置与用户预设共用同一条应用路径（resolvePersona 先内置后用户）
+          const entry = personaName ? resolvePersona(personaName, current.personas) : null
+          if (!entry) {
             send(res, 400, { ok: false, error: `预设不存在：${personaName || '(空)'}` })
             return
           }
-          // 预设值保存时已校验；此处再过一遍白名单，防御手改文件等异常数据
-          const { patch } = sanitizeConfig(pickPersonaValues(current.personas[personaName]))
-          const { config: updated, changed, promptChanged } = await commitConfig(c => ({ ...c, ...patch }))
-          if (promptChanged.length > 0) {
-            refreshPromptAndInject(ctx, updated)
+          // 内置预设已在代码里写过一遍；用户预设保存时也校验过。此处统一再过一遍
+          // 白名单，防御手改 config.json 注入的异常数据。
+          // 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) })
         }
@@ -625,6 +956,13 @@ function registerPersonaRoutes(ctx) {
             return
           }
           const personaName = sanitizePersonaName(parsed.body && parsed.body.name)
+          // 内置预设不可删除。这一层必须挡在「磁盘库是否存在」之前：内置项本来就不在
+          // 磁盘库里，但手改文件可能留下同名残留，那种条目已被合并视图遮蔽、删它没有
+          // 意义，而调用方真正想删的是内置项——直接拒绝，语义才唯一。
+          if (personaName && isBuiltinPersona(personaName)) {
+            send(res, 400, { ok: false, error: `「${personaName}」是内置预设，无法删除` })
+            return
+          }
           const current = await loadConfig()
           if (!personaName || !hasOwn(current.personas || {}, personaName)) {
             send(res, 400, { ok: false, error: `预设不存在：${personaName || '(空)'}` })
@@ -635,7 +973,7 @@ function registerPersonaRoutes(ctx) {
             delete personas[personaName]
             return { ...c, personas }
           })
-          send(res, 200, { ok: true, personas: updated.personas || {}, activeName: findActivePersonaName(updated) })
+          send(res, 200, { ok: true, ...personaLibrary(updated) })
         } catch (err) {
           send(res, 500, { ok: false, error: String(err.message || err) })
         }
@@ -667,11 +1005,19 @@ const COMMAND_MESSAGES = {
     traitsLabel: '特质',
     headingListsLabel: '标题和列表',
     emojiLabel: '表情符号',
+    tablesLabel: '表格',
+    replyLengthLabel: '回复长度',
     traitNames: {
       default: '默认',
       more: '增强',
       less: '减弱'
     },
+    replyLengthNames: {
+      concise: '简洁',
+      normal: '适中',
+      detailed: '详尽'
+    },
+    listSep: '，',
     trailLabel: '输入框光轨',
     trailLine: (status, color, speedName, widthName) => `${status}（${color} / ${speedName} / ${widthName}）`,
     trailSpeedNames: {
@@ -692,27 +1038,45 @@ 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: '✅ 已拒绝待确认的人设变更',
     saveDone: (name) => `✅ 已保存预设「${name}」`,
+    // 内置预设（随插件发布、不落盘）：不可用同名保存，也不可删除
+    builtinName: '内置',
+    builtinSaveBlocked: (name) => `「${name}」是内置预设，请换一个名称`,
+    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 / language / nickname / occupation / bio / customInstructions / trailEnabled / trailColor / trailSpeed / trailWidth）',
+    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}`,
@@ -736,11 +1100,19 @@ const COMMAND_MESSAGES = {
     traitsLabel: 'Traits',
     headingListsLabel: 'Headings & lists',
     emojiLabel: 'Emoji',
+    tablesLabel: 'Tables',
+    replyLengthLabel: 'Reply length',
     traitNames: {
       default: 'Default',
       more: 'More',
       less: 'Less'
     },
+    replyLengthNames: {
+      concise: 'Concise',
+      normal: 'Balanced',
+      detailed: 'Detailed'
+    },
+    listSep: ', ',
     trailLabel: 'Composer light trail',
     trailLine: (status, color, speedName, widthName) => `${status} (${color} / ${speedName} / ${widthName})`,
     trailSpeedNames: {
@@ -761,27 +1133,44 @@ 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',
     saveDone: (name) => `✅ Persona "${name}" saved`,
+    builtinName: 'built-in',
+    builtinSaveBlocked: (name) => `"${name}" is a built-in persona — pick another name`,
+    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 / language / nickname / occupation / bio / customInstructions / trailEnabled / trailColor / trailSpeed / trailWidth)',
+    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}`,
@@ -799,6 +1188,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) {
@@ -847,29 +1247,44 @@ function registerCommands(ctx) {
             const occupation = config.occupation || t.notSet
             const bio = config.bio || t.notSet
             const styleName = t.styleNames[config.style] || config.style || t.notSet
-            const hlName = t.traitNames[config.headingLists] || config.headingLists
-            const emojiName = t.traitNames[config.emoji] || config.emoji
+            const traitsLine = [
+              `${t.headingListsLabel}=${t.traitNames[config.headingLists] || config.headingLists}`,
+              `${t.emojiLabel}=${t.traitNames[config.emoji] || config.emoji}`,
+              `${t.tablesLabel}=${t.traitNames[config.tables] || config.tables}`,
+              `${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}${t.headingListsLabel}=${hlName}，${t.emojiLabel}=${emojiName}\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') {
@@ -888,6 +1303,9 @@ function registerCommands(ctx) {
           if (first === 'save') {
             const personaName = sanitizePersonaName(rest)
             if (!personaName) return { kind: 'error', text: t.saveUsage }
+            if (isBuiltinPersona(personaName)) {
+              return { kind: 'error', text: t.builtinSaveBlocked(personaName) }
+            }
             await commitConfig((current) => {
               const personas = clonePersonas(current.personas)
               personas[personaName] = { ...personaSnapshotOf(current), updatedAt: new Date().toISOString() }
@@ -899,31 +1317,46 @@ function registerCommands(ctx) {
           if (first === 'use') {
             const personaName = sanitizePersonaName(rest)
             if (!personaName) return { kind: 'error', text: t.useUsage }
-            if (!hasOwn(config.personas || {}, personaName)) {
+            // 内置与用户预设共用同一条应用路径（resolvePersona 先内置后用户）
+            const entry = resolvePersona(personaName, config.personas)
+            if (!entry) {
               return { kind: 'error', text: t.personaMissing(personaName) }
             }
-            // 预设值保存时已校验；此处再过一遍白名单，防御手改文件等异常数据
-            const { patch } = sanitizeConfig(pickPersonaValues(config.personas[personaName]))
-            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) }
           }
 
           if (first === 'list') {
-            const personas = config.personas || {}
-            const names = Object.keys(personas).sort()
+            // 与 Web UI 一致：列出合并视图（内置 + 用户），并标出内置项
+            const view = mergePersonas(config.personas)
+            const names = Object.keys(view).sort()
             if (names.length === 0) {
               return { kind: 'success', text: `${t.listTitle}\n${t.listEmpty}` }
             }
             const activeName = findActivePersonaName(config)
             const lines = names.map((personaName) => {
-              const entry = personas[personaName]
+              const entry = view[personaName]
               const styleText = STYLE_VALUES.includes(entry.style) ? (t.styleNames[entry.style] || entry.style) : (entry.style || '-')
-              const nickText = entry.nickname || '-'
-              return `${personaName === activeName ? '✔ ' : '• '}${personaName} ｜ ${t.styleLabel}=${styleText} ｜ ${t.nicknameLabel}=${nickText}`
+              // 原先这里显示 `昵称=${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.listCovers(covers)}`
             })
             return { kind: 'success', text: `${t.listTitle} [${names.length}]\n${lines.join('\n')}` }
           }
@@ -931,6 +1364,9 @@ function registerCommands(ctx) {
           if (first === 'del' || first === 'delete' || first === 'rm') {
             const personaName = sanitizePersonaName(rest)
             if (!personaName) return { kind: 'error', text: t.delUsage }
+            if (isBuiltinPersona(personaName)) {
+              return { kind: 'error', text: t.builtinDeleteBlocked(personaName) }
+            }
             if (!hasOwn(config.personas || {}, personaName)) {
               return { kind: 'error', text: t.personaMissing(personaName) }
             }
@@ -946,12 +1382,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
               }
@@ -961,7 +1402,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) }
             }
@@ -1006,21 +1449,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()
@@ -1028,12 +1483,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
       }
@@ -1054,43 +1509,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=减弱（避免表格，改用列表或段落文本）。/ Table usage.'
+          },
+          replyLength: {
+            type: 'string',
+            enum: REPLY_LENGTH_VALUES,
+            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',
@@ -1099,6 +1573,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' },
@@ -1107,6 +1584,8 @@ function registerTools(ctx) {
                   language: { type: 'string' },
                   headingLists: { type: 'string' },
                   emoji: { type: 'string' },
+                  tables: { type: 'string' },
+                  replyLength: { type: 'string' },
                   customInstructions: { type: 'string' },
                 },
               },
@@ -1193,7 +1672,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() {
@@ -1201,7 +1683,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
     }
   })