dsh-soul 0.7.1 → 0.7.2

package/index.mjs

@@ -19,6 +19,7 @@
 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,7 @@ import {
   sanitizePersonaName
 } from './lib/config.mjs'
 import { createInjectionSource } from './lib/injection.mjs'
-import { isBuiltinPersona, mergePersonas, personaMatches, resolvePersona, declaredPersonaKeys } 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'
@@ -56,6 +57,100 @@ function pluginVersion() {
   }
 }
 
+// ==================== 人设插画（方案 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 / 会话注入 / 工具返回的文本，
@@ -114,6 +209,8 @@ const PROMPT_TEXT = {
     toolNoChanges: '没有要更改的设置',
     toolValidationFailed: '配置校验失败：',
     toolProposal: '已收到人设变更请求（确认模式已开启，尚未生效）：',
+    toolRejected: '你在审批面板中拒绝了这次人设变更，未做任何修改。',
+    toolApprovalDisabled: '说明：本次会话的审批通道已被禁用（approval policy = never），因此没有弹出确认面板；这不代表你做了拒绝操作。',
     toolProposalHint: '在用户确认前不会生效；用户可用 /soul confirm 确认，或 /soul reject 拒绝。'
   },
   en: {
@@ -169,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.'
   }
 }
@@ -688,6 +787,15 @@ 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 {
           // 经由逃生口：配置损坏时这是设置页唯一还能成功的写操作。
           // backupPath 非 null 说明刚才确实丢弃了一份损坏的配置（已备份），
@@ -979,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) }))
+        }
+      }
+    })
   })
 }
 
@@ -1496,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 的守卫）。
@@ -1591,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)
@@ -1605,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)
@@ -1614,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 命令）竞态；

package/lib/personas.mjs

@@ -14,12 +14,25 @@
 //      pickPersonaValues，两者都只遍历 PERSONA_FIELDS）。v0.7.1 之前自建预设是
 //      「完整配置快照」、会写回这三个字段，旧数据由 normalizePersonas 迁移剥离。
 //
-//   2) **只声明要覆盖的字段**。预设是「部分覆盖」语义：应用时只写入预设实际
-//      声明的键，未声明的保持用户当前值。所以内置预设只写它真正要改变的人格维度。
+//   2) **声明全部 6 个人格维度**。每个内置预设都显式列出 style / headingLists /
+//      emoji / tables / replyLength / customInstructions，即使某项就是默认值。
+//
+//      理由：这份声明列表**同时驱动应用与匹配**，而两者的需求相反 ——
+//        应用时「只写声明字段」⇒ 声明越少越不越权；
+//        匹配时「只比声明字段」⇒ 声明越少越宽松。
+//      早期为「不越权」只声明要改的维度，代价是匹配退化成宽松比较：改一个预设
+//      未声明的特质后 ★ 仍挂在它身上，而且**同一动作结果随预设而变**（改 emoji
+//      在「极简主义者」上丢 ★，在「苏格拉底式提问者」上不丢）—— 用户无法形成
+//      稳定预期（实测确认）。统一为全量声明后语义单一可预期：
+//      **改任何特质 ⇒ 不再属于该预设**。
+//
+//      代价（刻意接受）：应用预设会把 6 个人格维度整体复位到预设值，而不是
+//      「只改一部分、其余保留我手动的」—— 这与「用预设就是不想逐项自己配」
+//      的心智模型一致。
 //
 //   3) **内置预设一律不声明 `language`**。输出语言在预设范围内（自建预设会保存
 //      与还原它），但内置预设是给任何语言用户共用的通用人格：写死 zh 会让英文用户
-//      应用一次就被强行切回中文。省略即「不动它」。
+//      应用一次就被强行切回中文。省略即「不动它」——这是全量声明唯一的例外。
 //
 //   4) **内置预设不进磁盘**。它们只存在于本文件，磁盘上的 `config.personas`
 //      仅存用户自己保存的预设。好处有三：升级时内置内容自动更新（不会被用户
@@ -45,6 +58,9 @@ import { PERSONA_FIELDS, PERSONA_META_KEYS } from './config.mjs'
 
 export const BUILTIN_PERSONAS = {
   '苏格拉底式提问者': {
+    emoji: 'default',
+    tables: 'default',
+    replyLength: 'normal',
     style: 'professional',
     headingLists: 'less',
     customInstructions:
@@ -65,6 +81,7 @@ export const BUILTIN_PERSONAS = {
       '若信息不足以回答，只问一个最关键的问题，不要罗列一串待确认项。'
   },
   '资深架构师': {
+    emoji: 'default',
     style: 'professional',
     headingLists: 'more',
     tables: 'more',
@@ -76,6 +93,8 @@ export const BUILTIN_PERSONAS = {
       '涉及取舍时给出明确推荐并说明理由，不要以「都可以，看需求」收尾。'
   },
   '教学型讲解者': {
+    emoji: 'default',
+    tables: 'default',
     style: 'casual',
     headingLists: 'more',
     replyLength: 'detailed',
@@ -98,6 +117,9 @@ export const BUILTIN_PERSONAS = {
       '没有发现问题时，明确说明检查过哪些方面，不要为凑数编造无关痛痒的意见。'
   },
   '头脑风暴伙伴': {
+    emoji: 'default',
+    tables: 'default',
+    replyLength: 'normal',
     style: 'casual',
     headingLists: 'more',
     customInstructions:
@@ -107,6 +129,8 @@ export const BUILTIN_PERSONAS = {
       '避免只给显而易见的选项，至少包含一个不常规但有可行性的思路。'
   },
   '自驱型协作者': {
+    tables: 'default',
+    replyLength: 'normal',
     style: 'professional',
     headingLists: 'more',
     emoji: 'more',
@@ -146,19 +170,20 @@ export function personaMatches(entry, config) {
   return keys.every((key) => entry[key] === config[key])
 }
 
-// 内置人设名（按定义顺序返回；UI 列表用它把内置项排在前面的展示区）
+// 内置人设名（按定义顺序返回；UI 列表用它把内置项排在前面的展示区）。
+// 「默认」排在最前 —— 它是出厂状态，列表里应当一眼可见。
 export function builtinPersonaNames() {
   return Object.keys(BUILTIN_PERSONAS)
 }
 
-// 是否为内置人设名（保存与删除路径的准入判据）
+// 是否为内置人设名（保存与删除路径的准入判据）。默认与内置同样受保护。
 export function isBuiltinPersona(name) {
   return typeof name === 'string' && Object.prototype.hasOwnProperty.call(BUILTIN_PERSONAS, name)
 }
 
 // 合并用户预设库与内置预设，返回给前端的展示视图。
 // 内置条目额外带 `builtin: true` —— 前端据此渲染「内置」标记并隐藏删除按钮；
-// 用户预设不带该字段。内置优先，同名用户条目被遮蔽（见文件头约定 3）。
+// 用户预设不带该字段。内置优先（默认在最前），同名用户条目被遮蔽（见文件头约定 3）。
 export function mergePersonas(userPersonas) {
   const out = {}
   for (const name of builtinPersonaNames()) {

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Soul",
+    "description": "Personalization for DSH: nickname, reply style and tone, traits, persona presets, and a composer light trail."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Soul 人设",
+    "description": "为 DSH 添加个性化设置：昵称、回复风格和语调、特质、人设预设，以及输入框光轨。"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-soul",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "为 DeepSeek Harness 添加个性化设置。",
   "icon": "./assets/icon.svg",
   "keywords": [
@@ -60,6 +60,7 @@
     },
     "./client": "./client/index.mjs",
     "./cordis.patch.yml": "./cordis.patch.yml",
+    "./locale/*.json": "./locale/*.json",
     "./package.json": "./package.json"
   },
   "files": [
@@ -67,6 +68,7 @@
     "lib",
     "client",
     "assets",
+    "locale",
     "cordis.patch.yml",
     "scripts",
     "README.md",