# dsh-soul Release Notes

`dsh-soul` 为 DeepSeek Harness（DSH）提供「个性化设置」能力：通过 Web 设置页或斜杠命令配置「关于你」（昵称、职业、介绍）、回复风格和语调、特质（标题和列表 / 表情符号 / 表格）、回复长度偏好、输出语言与自定义指令，配置实时编译为 system prompt，**下一次请求即生效**（section 每次装配重算 + 活动会话主动注入，双通道兜底）。

## 功能

**设置页**
- 启用开关、「关于你」（昵称 / 职业 / 介绍）、「特质」（回复风格和语调 / 标题和列表 / 表情符号 / 表格 / 回复长度）、输出语言、自定义指令
- 人设预设分组：7 个内置人设（随插件提供、不可删除）+ 保存当前为预设、一键使用（★ 标记当前匹配项）、删除（二次确认）；每行摘要显示风格与「偏离默认值」的维度，便于横向比较
- Agent 工具分组：`set_persona` 确认模式开关
- 输入框光轨：Agent 回复中时输入框边框的流光动效——开关、预设色板 + 取色器 + 十六进制输入、流动速度（慢 / 中 / 快）、光带粗细（细 / 中 / 粗），以及随配置实时联动的效果示例
- 关键字段带 ⓘ 提示图标；保存 / 重置结果以内联提示展示（成功绿字、失败红字，与宿主模型设置页同款形态），失败时页面内另有错误条
- 中英双语文案（跟随界面语言）；dirty 检测（无改动禁用保存 + 未保存提示）；保存结果区分「已保存 / 无变化」
- 提示词预览折叠区（只读）：无未保存编辑时展示「当前生效提示词」；一旦表单有改动，就改为在保存前编译草稿、展示「保存后将生效的提示词」——边改边看（停止输入 400ms 后自动重编译），并在保存 / 重置 / 应用预设后自动刷新；未通过校验的字段会如实列出、且不计入预览，避免「预览悄悄用了旧值」
- **变更记录**：每次配置改动都留痕（时间 · 来源 · 字段级 `原值 → 新值`），可**撤销**、可**恢复被删的预设**、可**清空**。入口在**插件详情页**（宿主的插件管理 → 已安装插件 → dsh-soul），设置页只在「人设预设」展开区给出指引；保留条数在设置页可调（50 / 100 / 200 / 500，默认 200）。详见下方 v0.8.0 段

**Soul 人设总览**（侧栏面板，默认开启）
- 侧栏入口「个性化」→「Soul 人设总览」，打开中间列的主面板。三段结构：**当前生效**（全局人设 + 就地切换）·**工作区**（人设覆盖 + 展开后的会话清单 + 就地改绑）·**预设库**（只读清单，指引去设置页增删改）
- **会话口径与左侧栏一致**：注册表成员 − 归档 − 子代理会话。任一环节缺服务时如实标注（数字可能偏大），不静默给出错数
- **会话标题**直接读宿主已维护的标题投影（`sessions.list` 快照里的 `projectionValues.title`），**零日志读取**，第一屏就有标题；不走「折叠整条事件流」那条要几秒的路径
- **会话行可点击**跳到该会话（键盘 Enter / Space 亦可）；拿不到 `uiWorkspace` 服务时不带可点样式，不画点不动的按钮
- **空会话如实标注并默认隐藏**：从未产生 user/assistant 消息的会话（只有系统事件与插件注入的人设快照）折叠不出标题，界面标为「（空会话 · 未开始对话）」并默认收起，末尾留一行「显示 N 个空会话」的开关
- **切回面板自动重拉**：订阅 `soulController` store 的关键字段指纹（人设库 / 工作区绑定 / 人格字段），别处改了人设或绑定，面板自动跟上；同时监听 `layout.panelInfo` 的 `activePanelId`，切回本面板也重拉一次
- **面板自滚动**：展开多个工作区后内容变长时，沿祖先链找到真正裁剪内容的容器，用它的可见高度作上限，预设库不会被顶出视野

**斜杠命令**（输出语言跟随配置 `language`，中英文案）

```text
/soul show        查看当前配置（含确认模式与预设数量）
/soul set k=v     修改配置项（如 /soul set style=humorous language=en；特质：tables=more replyLength=concise；光轨字段：trailColor / trailSpeed / trailWidth / trailEnabled）
/soul save <名>   保存当前配置为人设预设（内置名不可占用）
/soul use <名>    应用人设预设（内置预设同样可用）
/soul list        查看人设预设（✔ 标记当前匹配项；内置项带 [内置] 标记；并报告每个预设覆盖的维度数）
/soul del <名>    删除人设预设（delete / rm 别名；内置预设不可删）
/soul confirm     应用待确认的人设变更（确认模式）
/soul reject      拒绝待确认的人设变更
/soul reset       重置默认值（保留人设预设库）
/soul enable      启用
/soul disable     禁用
/soul <昵称>      设置昵称（保留原始大小写）
```

**配置与集成**
- 持久化：`$DSH_HOME/soul-config.json`（用户预设存于同文件 `personas` 字段；内置人设只在代码 `lib/personas.mjs` 里，不落盘，因此升级时自动更新、也无法被删除或篡改）
- 服务：`soulConfig`（`getConfig` / `updateConfig` / `getSystemPrompt` / `resetConfig`）
- HTTP API：`/api/soul/config`（GET/POST）、`/api/soul/prompt`（已生效提示词）、`/api/soul/prompt/preview`（POST 草稿，不落盘、不影响生效提示词）、`/api/soul/config/reset`、`/api/soul/status`（GET，诊断两条送达通道与配置状态）、`/api/soul/personas`（GET）、`/api/soul/personas/save|use|delete`（POST）
- 输入校验：字段白名单、类型、长度上限与枚举校验，HTTP 保存 / `/soul` 命令 / `set_persona` 工具 / `soulConfig` 服务共用；非法或超限字段整单拒绝
- Agent 工具：`set_persona`（需宿主安装 `@deepseek-ai/dsh-tools`；缺失或不兼容时自动跳过，其余功能不受影响；确认模式下返回 `pending` 提议）
- 插件图标：`package.json` 的 `icon` 指向 `assets/icon.svg`（36×36 viewBox，随 npm 包发布）
- 设置导航图标：设置面板左侧「个性化」那一项显示与插件图标同一套几何的图标（DSH 的导航图标按 section id 硬编码、插件声明不了，故由客户端做 DOM 替换，见下）

## 已知限制

- 安装 / 升级后需完全重启 DSH 并刷新浏览器，设置栏目才会出现
- 保存配置后在**下一次请求**生效：配置变化同时走 system prompt section（每一步装配时重新求值）与活动会话注入（保存后主动推送快照），不会打断进行中的请求，也不会改写历史消息
- 有效配置变化会在会话里留下一条 `[dsh-soul 个性化配置已更新]` 消息（user 角色）——它是「即时生效」的可见载体；纯外观配置（输入框光轨）只落盘，不产生该消息
- 两条通道**缺一不可**：底座是宿主「每步重新装配 + 不对函数式 section 文本做缓存」，`npm run verify:host` 用宿主的真实实现直接验证它；而本版实测证明**只有底座不够**（会话进行中改配置不生效），因此注入是必需的第二条通道，不要单独删除（见 `DEBUGGING.md` 3.5）
- 「改了配置不生效」有三处可查：`/soul show` 末尾的「送达」行、`GET /api/soul/status`、设置页的提示条（`configError` = 配置读不出来；`deliveryWarning` = 配置送不到活动会话）
- 配置文件**损坏**时普通保存会被拒绝（以免以默认值为底覆盖你的内容），设置页的**重置**是逃生口：它把损坏文件另存为 `soul-config.json.corrupt` 后再写入默认值
- `npm run verify` 里可能包含**跳过**（无浏览器 / 定位不到 DSH）：跳过会显式打印未执行的断言数，但退出码仍为 0；需要「跳过即失败」时用 `npm run verify:strict`
- 仅支持 `web` 平台客户端

## 兼容性

peerDependencies（DSH 在装载插件前校验，**比较对象是 DSH 运行时版本**，即 `@deepseek-ai/dsh-app-boot` 的 version）：

| 包 | 范围 | DSH 是否校验 |
| --- | --- | --- |
| `@deepseek-ai/dsh-llm` | `>=0.1.1-rc.2 <0.3.0-0` | 是 |
| `@deepseek-ai/dsh-tools` | `>=0.1.0-rc.6 <0.3.0-0` | 是 |
| `@deepseek-ai/cordis` | `^4.0.1 \|\| ^4.0.5-alpha.1` | 否（名称不以 `@deepseek-ai/dsh-` 开头，不参与判定） |

即支持 DSH **0.1.x 与 0.2.x**（含 prerelease）。DSH 进入 0.3.x 线后需重新评估再放宽，流程见 `PUBLISHING.md`。

用 `npm run verify:compat` 可在升级 DSH 后一条命令确认声明是否仍然成立（见 `DEBUGGING.md` 第四节）；`npm run verify:host` / `npm run verify:e2e` 另可确认「改配置 → 下一轮生效」这条链路在升级后依然成立。

---

## 版本历史

### v0.10.0（2026-11-02）

延续 v0.9.0 的开发线，共 31 个提交。主题是**把「谁在生效」这件事搬到一个面板上**，并顺手把整个插件的按钮规格与宿主对齐。

**新增**

- **「Soul 人设总览」面板**（侧栏入口 + 中间列 main 面板，默认开启）：当前生效 / 工作区 × 会话级联 / 预设库三段。侧栏入口与 main 面板**成对注册**（只注册一侧会得到「点了没反应」的空壳）
- **就地操作，少跳页面**：
  - 「切换 ▾」直接换全局人设（原先要 设置页 → 个性化 → 展开人设预设 → 找到卡 → 点使用，四步）
  - 失效绑定的「修复」就地展开预设胶囊改绑（原先要跳到插件详情页，改完还得切回来）
  - 为此给「用这个」与「取消本会话的临时人设」拆了独立类名：两者尺寸需求不同（前者与主按钮配对走 md，后者是列表语义），共用一个类改一个会坏另一个
- **会话行可点击跳到主视图**：键盘 Enter / Space 亦可；id 形式**两种都试**（无前缀 / 注册表原样）——宿主 `resolveTarget` 的校验依赖运行时状态（`summaries` 是否已加载、`sessions` 是否已实例化），押一种会静默失败
- **空会话识别与默认隐藏**：判据是**逐帧解压日志找 user/assistant 消息**，不是文件大小（实测真实空会话 8.6KB～22.6KB，按大小判会误判），也不是只解首帧（实测会把 18 个有对话的会话误判成空）
- **自动刷新**：订阅 `soulController` store 的关键字段指纹 + 监听 `layout.panelInfo`。用指纹而非全量响应，是为了避开 `saving`/`loading` 这类高频字段把面板刷成幻灯片

**改进**

- **标题读取改走宿主投影**：原先靠 `readTitleSnapshots` 为每个会话折叠整条事件流（34 个约 5 秒），只能「先显示短 id、标题稍后补」。改读 `sessions.list` 快照里的 `projectionValues.title`（侧栏用的同一份），**零日志读取**
- **首屏骨架**：数据只差约 100ms，但「加载中…」三个字一闪会让人注意到延迟；改骨架占位，读屏仍能读到加载状态
- **判空结果落盘缓存**（`$DSH_HOME/soul-blank-sessions.json`，键含 mtime）：逐帧解压 34 个会话约 400ms，全在点开面板的关键路径上。冷进程首次 408ms → 116ms
- **面板自滚动**：不假设宿主容器高度可继承（那些类名 hash 过、CSS 在 web 前端 bundle 里），直接量祖先链里第一个会裁剪的容器
- **五类按钮全部对齐宿主 `Button.module.css`**：
  | 按钮 | 规格 |
  | --- | --- |
  | 总览「切换」/「修复」 | `sm + outline`（28px / 12px / radius-sm / .5px border-l3） |
  | 工作区预设胶囊 | `sm + outline` |
  | 人设页「取消本会话的临时人设」 | `md + outline`（36px / 14px / radius-md） |
  | 人设页「用这个」 | `md + primary`（与「取消」同行，字号行高必须一致） |
- **光轨拖尾根治**：真正决定人眼可辨的是**折点间距**（= 拖尾跨度 ÷ 折点数），不是层数。8 层 22px、16 层 9.9px 都能看出分段；改成 48 层 + 8% 跨度 → **1.68px**，低于视觉分辨极限（约 2px），并把线端全改圆头
- **字体阶梯对齐宿主**：16/600 · 14/600 · 13/500 · 12/400 · 11/500，字重不超过 600

**修复**

- 会话行标题显示成字面量 `session-`（`slice(0,8)` 恰好切在前缀上）
- 会话标题全部退化成 8 位 id（阶段 2 的合并依赖函数式 setState 拿到最新 prev，改为独立 state + 渲染时查表）
- 「N 个会话」把归档会话也算进去（某工作区显示 24 而实际只列 10）
- 失效绑定的「修复」按钮太隐蔽，用户实际找不到（11px 次要灰 + 透明底）
- 会话编号与侧栏口径不一致（曾显示 49 个而侧栏 4 个）
- 光轨拖尾露出分段色阶（两次返工，见上）
- 会话行跳转静默失败（`catch {}` 吞掉了宿主的 `unknown session` 错误）
- 预设库给出一个点不动的跳转按钮（宿主设置弹窗没有公开打开方式），改为如实指引

**验证**

- 断言总数 542 → **554 项**（13 个验证脚本）
- **光轨性能实测**（Chrome headless + CDP，120 帧）：16 / 48 / 96 层均为 **60 FPS**，平均 16.67ms、p95 16.8ms —— `stroke-dashoffset` 的重绘面积始终是同一条线，与层数无关
- **亮/暗对比度实测**（真实宿主 token + alpha 合成，14 个元素）：修正了空会话开关的对比度（`label-tertiary` 亮色 3.71 → `label-secondary` 5.80）

### v0.9.0（2026-10-29）

**新增**

- **三级配置作用域（Global → Workspace → Session）**：人设不再是全局唯一 —— 工作区决定「这个项目用什么人设」，单个会话还能临时覆盖，其余字段逐级继承。合并语义与「应用预设」同一条规则（字段级部分覆盖），用户在设置页点「使用」看到的效果，与作用域里自动拿到的**逐字段一致**
  - **身份解析**：`sessionId → workspaceId` 索引在装配路径**之外**维护（宿主 `systemPrompt.section.text` 是同步调用，不能 `await` 也不能线性扫描），三个重建时机：首轮、宿主 `domain/changed` 事件、装配未命中时下一拍重扫。索引未命中回退**目录前缀匹配**（复用 0.8.1 的 `lib/bindings.mjs`），再未命中回落全局 —— 失败方向安全：任何一环不可用只能在「更精确」与「更宽松」之间移动，不会变成「错误的人设」
  - **`enabled` 任何作用域都不能覆盖**：全局总开关始终说话。工作区与会话的覆盖白名单都不含它，合并函数里还有第二道过滤 —— 否则「关掉插件」就不成立了
  - **会话覆盖存储**：`$DSH_HOME/soul-sessions/{sha256(sessionId)[:32]}.json`，与 `soul-config.json` 同级。文件名哈希而非转义（定长、无歧义、天然规避路径穿越），内容里另存原始 `sessionId` 并与文件名互校 —— 改个文件名就能读到别人的覆盖这条口子被堵死
  - **配置修订号**：每次配置替换 `configRevision +1`，装配路径**只取一次快照**并把用到的修订号写进诊断状态。修掉一个真实隐患：`configCache` 由写队列整体替换，一次装配里多次读可能拿到两个版本 —— 症状正是「System Prompt Updated 已出现、模型却仍用旧昵称」。现在 `/api/soul/status` 能回答「进模型的是哪一版」
- **会话「人设」tab**（宿主 `conversation.view` 槽位）：插件能拿到**当前会话 id** 的唯一正规入口（设置页的 `slotInject` 是空串）。左侧卡牌轮转（与设置页人设卡牌同构：中心大卡 + 两侧露边、位置指示只标中心卡），右侧详情面板与设置页卡背**逐字相同**（六个维度 + 自定义指令全文）。「用这个」即时生效不经保存按钮；提交只带该预设声明过的字段
- **插件详情页「工作区人设」**：平铺卡片，未绑定的排前面（那正是用户来这页要处理的事），点「绑定人设」内联展开人设胶囊。覆盖指向的预设被删后如实标注「人设『X』已不存在」—— 为此覆盖项里带 `__persona` 引用字段（不进合并、不进审计、只剩它时算空覆盖）
- **会话覆盖回收**：三阶段保守状态机（发现候选 → 30 天宽限期 → 可回收），判定依据是 `sessionPersistence.list()`（扫磁盘），**绝不使用 `agents.list()`** —— 那是 live registry，会话切走就消失，用它判定会误删正在使用的覆盖。双条件：时间够**且**本轮扫描完整；扫描不完整时状态机对所有条目返回 keep。双入口：`/soul sessions [--apply]` 与详情页按钮，默认 dry-run，打开详情页不自动扫描
- **工作区覆盖放 `soul-config.json`、会话覆盖放 sidecar**：前者是配置（低频、有上限、用户在意变更历史），后者是状态（高频、无上限、随会话生灭）。性质不同，存储边界不同

**修复**

- **工作区绑定误报「人设已不存在」**：失效判断只查了 `config.personas`（磁盘上的自建预设），而内置预设只存在于代码里的 `BUILTIN_PERSONAS` ⇒ 绑定指向内置预设（自驱型协作者 / 头脑风暴伙伴）被判成失效、标红。改用 `mergePersonas` 的合并视图
- **侧栏图标顶掉插件图标**：注册 `sidebar.panellist` 时复用了宿主的 id `'plugins'` —— 文档里 "reusing a shipped id puts you in THAT cell" 的含义是**替换该单元**而非并存，结果插件管理器的图标消失。已回滚为自己的 id，并暂时隐藏该入口（等独立 main 面板做好再启用）
- **工作区人设区块整块消失（React #130）**：图标名写成 `ui.IconRefreshOutline14` / `ui.IconTrashOutline16`（照抄 npm 包的 `.d.ts`），但宿主 **seed 给插件的模块表**只有 `*Regular` / `*Medium` 后缀 ⇒ `undefined` ⇒ 渲染 undefined 组件 ⇒ 宿主卸载整个 slot entry。**类型声明 ≠ 运行时可用**，判据要以宿主 bundle 的 `TU` 定义为准
- **测试桩掩盖了上面那个 #130**：`verify-client` 的 `ui` 桩原先是 Proxy 无脑返回函数，拼错的图标名静默通过。已改为白名单 + 校验，访问未声明名字直接抛错
- **绑定按钮悬停时整块变黑**：自绘 `<button>` 继承了宿主基础按钮样式（实心主色底 + 白字），插件又把文字色压成近黑 ⇒ hover 时深底深字，整块全黑。四处按钮统一改用宿主 `ui.Button`
- **切换预设后会话 header 的人设名不更新**：组件自己按 `[sessionId]` 依赖去拉，作用域变化时不会重算。改为全局 store 单一数据源（`sessionScopes`），store 必须换引用才触发重渲染
- **输入框人设标签的层级标注整块不显示**：`inject` 对 `session` 作用域收到的是**位置参数** `[sessionId]`，代码按 props 对象解构 ⇒ 恒 `undefined`
- **内置徽标在卡面上位置漂移**：`.soul-persona-badge` 有两套外观（卡面 absolute/玻璃底/白字、卡背头 描边式/inline/灰字），卡背那条**不限定上下文**，覆盖了卡面样式而自己不写 `position` —— 徽标变成「absolute 定位 + 描边式字号」的混合体在插画上漂。会话 tab 的卡面徽标因此漂移（它没有 `.soul-persona-back-head` 包裹，`position:static` 的重置不生效）。修法：卡背规则限定到 `.soul-persona-back-head` 内
- **会话覆盖读取失败时显示过期数据**：reload 失败不清空 view，界面继续渲染上一次成功的列表。现在失败即清空
- **React error #310（会话「人设」tab 崩溃）**：hook 写在 `if (view === null) return` 之后，首屏与加载后两次渲染的 hook 数不同。已提到所有提前 return 之前
- **CSS token 引用三个宿主不存在的变量**（`--dsw-font-mono` / `--dsw-alias-label-warning` / `--dsw-alias-state-warning-primary`）：`var()` 静默回退，路径掉字体、警告色变继承色

**变更**

会话「人设」tab 与周边标识做了整体重做，目标是「和宿主同一套视觉语言」：

- **人设标识出现在四处**：会话 header、新会话行（hero）、侧栏会话行（hover 徽标）、人设 tab。四处的面具图标**共用一份几何**（`SOUL_MASK_PATHS` + `soulMask()`）—— 此前各处各抄一份 path，「下巴改圆」只改了 header，另两处仍是尖下巴，同一副面具长出两种轮廓
- **面具图标**：自绘 SVG（宿主 primitives 里没有面具）。造型为戏剧双面 —— 左眼笑、右眼哭、嘴左高右低，盾形圆下巴。试过威尼斯假面与「两张交叠面具」，最终选定单张双面：14px 下三笔都清晰（交叠轮廓在 14px 会糊成一团）
- **会话人设卡牌**：200×200 → **300×300**，与右侧详情**等高**（338px = 卡 300 + gap 10 + 导航 28）；容器保持 1:1，插画 512×512 不裁；卡牌可轮播（左右箭头 + 圆点），卡本身不可点
- **详情面板固定高度**：`max-height` → `height:338px`。切换预设时面板高度不再随自定义指令长度上下跳
- **当前人设名加粗 + 非默认特质摘要**：名称后跟 11px 次要色小字，内容是「风格 + 偏离默认值的维度」，复用 `personaRowMetaOf`，与卡面摘要、详情面板同源
- **侧栏会话行 hover 徽标**：不用点开会话就能看到该会话现在是谁。数据在首次挂载时**按需自拉**（原先只有插件详情页会拉 `loadBindings`，侧栏先挂载时数据恒空 ⇒ 徽标永不渲染），模块级 in-flight 去重避免 N 行各发一个请求
- **人设显示进宿主的 hover 信息卡**：用宿主槽位 `sidebar.session.row.hover`（与自动任务摘要同一张卡），而不是另起一个自绘 tooltip。文字规格逐项对齐宿主同槽位住户（`ui-schedule` 的 `.task` 族：gap 8px / 12px / 行高 16px / 次要文字 bluish-300 / 主体 bluish-00）。**用 static 色不用 alias 色** —— 宿主卡片恒为深色，alias 会随主题翻转成深字压深底
- **徽标气泡改用宿主 `ui.Tooltip`**：原生 `title` 画的是系统浅色气泡，与隔壁「置顶/归档」的黑色气泡并排两种样式。参数照抄宿主的 `PinSessionRowButton`（side bottom / align end / delayMs 500 / portal）
- **变更记录改分页**：原先「先铺 20 条 + 还有 N 条 → 全部摊开」，摊开后比详情页还长且无法收起。现为每页 20 条 + 分页器；记录被清空或保留条数调小时页码自动收敛到最后一页
- **工作区绑定按钮统一到宿主 `ui.Button`**：自绘 `<button>` 会继承宿主基础按钮样式（实心主色底 + 白字），插件又覆盖文字色 ⇒ hover 时深底深字、整块全黑
- **工作区人设的改绑/解绑改为宿主同款文字按钮**：照抄设置-模型页的「编辑 / 删除」（`secondaryButton`：描边 + 深色文字 + 浅灰悬停；`dangerButton`：无描边 + 红字 + 浅红悬停，均 28px 高 / 12px 字号）。解绑二次确认态文字变「确认解绑…」并常亮浅红底
- **「存为预设」保存的是刚改的内容**：原先快照只取当前已保存配置，改完表单直接点「存为预设」会存成上一个预设的内容。现在客户端把草稿一并提交、服务端校验并合并
- **新增「更新到预设」**：把当前编辑内容覆盖写回一个已有自建预设（内置预设不可改），保存后表单回退到该预设
- **「存为预设」增加「保存后立即应用」**：勾选则保存后立刻切换过去，不勾选则表单回退——两种意图各有明确出口，不再互相矛盾
- **重复预设硬门禁**：要保存的内容与已有预设（含内置）投影相同时拒绝创建，避免预设库堆出多条一模一样的人设

**暂缓**

- 0.8.1 的「按目录绑人设」设置页分组**未随本版发布**（逻辑层保留，作为工作区层的 cwd 回退底座）：它的交互按目录字符串思考，与工作区卡牌完全不同，留下它只会让用户先学一套即将被替换的操作方式

**校验**

- 全链 422 → **509 项**：新增 `verify-scope`（22 项，工作区覆盖纯函数）、`verify-session-scope`（23 项，会话覆盖与回收状态机含真实文件系统）、`verify-bindings`（47 项）、`verify-e2e-prompt` 90 → 100（S1–S10 三级作用域真挂载）、`verify-client` 28 → 52、`verify-config` 134 → 157
- **判断力对照的五条教训**（每一组漏网都记进了对应提交）:
  1. **桩的输入形状决定断言能不能看见问题** —— 预设桩不带 `updatedAt`/`builtin` 时，「整份照发」与「白名单筛选」产出的请求体一模一样
  2. **子串判据在近义词之间没有判别力** —— S5 用 `includes('幽默')` 判断会话层生效，而工作区层 roast 的文案含「犀利幽默」，会话层完全不生效也命中
  3. **容器存在 ≠ 内容存在** —— 断言 `.soul-persona-dims` 容器 ≥ 1 时，把维度列表换成空数组仍然通过，界面却是「一块空白」
  4. **测试台的通过只证明「在垫片的执行模型下是对的」** —— React error #310（hook 顺序）在垫片里结构性不可见：垫片从不模拟「先 null 后有值」的两段式挂载
  5. **渲染树断言看不出 CSS 层面的冲突** —— 同一 class 下两条规则的优先级与上下文限定，只能靠源码契约
- 接线断言（0.9.0-b/c）：纯函数层测好了不等于接上了。装配不查索引、sessionId 取空、事件重建被删、工作区层被短路、回收用 `agents.list` 判定、默认就删 —— 六组变异初跑**全部漏网**，补接线断言后全部拦住

### v0.8.0（2026-10-15）

**新增**

- **变更记录（配置改动审计）**：每次配置改动都追加一条记录——时间、**来源**、字段级 `原值 → 新值`。记录写在 `$DSH_HOME/soul-config.history.jsonl`（append-only JSONL，一行一条，人能直接读）
  - **埋点选在唯一漏斗**：`index.mjs` 的 `commitConfig(mutate)` 是全部配置写路径的收敛点，实测 16 个调用点，给它加第二个参数 `source` 即可覆盖全部写入，不必逐个路由埋点。`source` **刻意不给默认值**——有默认值的话，忘了标注的调用点会静默落进某个桶里，看起来「有记录」而实际归属错误；不给默认值则漏标会让断言当场变红。16 处归属：web 的 save / reset / savePreset / deletePreset，persona 的 use，command 的 nickname / enable / disable / savePreset / deletePreset / set / confirm / reset，tool 的 setPersona，service 的 update / reset
  - **只存变化字段，不存快照**：实测 `soul-config.json` 4886 字节，快照式记账每条 4.8 KB；只记 `before`/`after` 差异后通常几十字节
  - 代价是回滚必须**反向还原**，因此每条带 `configHash` 链式指纹。指纹只覆盖 `DEFAULT_CONFIG` 的键——把 `personas` 算进去的话，「存一个预设」会让「撤销一次 style」因哈希对不上被拒
  - **预设库单独记事件**：`index.mjs` 的 `diffKeys` 里有 `if (key === 'personas') continue`（那是刻意的——预设库不是活动配置、不该触发提示词刷新），于是预设的增删改**不会**出现在 `changed` 里。审计若复用它就会**静默漏记**，而这三类恰恰最容易丢内容（覆盖同名预设、删除预设）。现显式比对前后差异，记 `added` / `updated` / `removed`
  - **追加在配置落盘之后**，且以 `saveConfig` 的**返回值**为差分基准（`saveConfig` 会剔除 `tone` / `presets` / `examples`，拿 `mutate` 的产物去比会把废弃字段误报成变更）
  - **审计失败不影响配置写入**：追加失败只记 `lastHistoryFailure` 并继续返回成功，原因经 `GET /api/soul/history` 的 `warning` 回传。审计是次级设施，不该让用户连设置都存不了
  - 「什么都没变」在构造条目**之前**用字段差分判掉，不靠 `buildHistoryEntry` 返回 null 表达——后者会把「真的没变」与「条目 shape 不对（如漏标 `source`）」混成同一个返回值，表现就是「配置改了、记录里没有、也没有任何告警」
  - 上限 200 条 / 512 KB，超限压实；读取窗口 4 MiB / 1000 行；单行 64 KiB
- **插件详情页「变更记录」区块**（宿主 `plugins.detail.section` 槽位）：时间线（相对时间 · 来源徽标 · 字段名列表），展开任一行为逐字段 `原值 → 新值`；每条可**撤销**，删过预设的记录额外给「恢复此预设」；顶部一行状态（最近 N 条 · 最多保留 M 条）+ 右侧「清空记录」
  - **为什么放在详情页而不是设置页**：变更记录是低频的回顾性信息，长期占着设置页主区不值得；详情页地方大，可以按宿主 `detailSection` 的排版充分展示。设置页只留指引（且指引本身也不占独立一行，见下）
  - 挂载时才拉取（比设置页的「展开才拉」更懒）；`subject` 只认自己的 `pkg.name === 'dsh-soul'` 且 `kind === 'bundle'`，其他插件的详情页渲染 `null`（槽位契约原话："renders null for a subject it has nothing for"）
  - **保留条数可自定义**：50 / 100 / 200 / 500 四档下拉（默认 200）。下限 50 是因为再小则「上一轮就没了」；上限 500 是因为条目只存变化字段、远在 512 KB 之内。这个字段**也进审计**——否则用户改了容量在记录里查不到是谁改的。*（0.8.1 起这个下拉从设置页迁到插件详情页的变更记录区块内，见 v0.8.1 段）*
  - 越界值**夹取而非拒绝**：容量参数不是用户内容，「要 30 给 50」是可解释的放宽，报错只会让用户面对死胡同。但**类型检查必须在转换之前**——先 `Number(value)` 会把 `null` / `''` / `false` / `[]` 全变成 `0` 再被夹成下限 50，配置里一处脏数据就会**安静地把撤销窗口缩到最小档**，而「变小」恰好表现为「老记录不见了」，正是最不该静默的错
  - 设置页**不再有**「变更记录」分组（0.8.0-d 曾把它做成第 5 个配置分组，0.8.1 双入口时撤销）；原先挂在折叠标题旁的问号提示也一并取消——折叠态挂问号等于把说明放在「还没展开就能看到」的位置，而它解释的恰恰是展开后的东西。现说明一律写进「人设预设」展开区的正文块（能直接读的文字优先于 hover），与预设收录范围的说明合并展示
  - **撤销的语义是「撤销这一次改动以及它之后的全部改动」**（实现阶段推翻了草案）：草案写的是「回到那条记录刚做完的样子」，有两个硬伤——点最新一条会变成空操作（而最新那条恰恰最想撤）；点中间一条的结果与行内容相反（记录 ①改 `style`、②改 `emoji`，点 ① 那一行会把 `emoji` 退回去而 `style` 留着）。为什么必须连带撤销它之后的：条目只记变化字段，后一条的 `before` 是它自己那次改动的前提，跳过中间某条单独还原更早的字段，会算出一份**从未存在过**的混合状态
  - 每一步都先验 `configHash`：当前配置的指纹必须等于该条目的指纹，对不上返回 `diverged` 并回 **409**，而不是算出一份从未存在过的配置。值一律过 `sanitizeConfig` 白名单后再合并——记录文件是**不可信输入**（用户可手改、可被别的工具写坏），校验不过的字段进 `skipped` 如实回报，不静默丢弃
  - 「恢复此预设」逐个说明为什么没恢复（`invalid-name` / `builtin` / `exists`），**绝不静默覆盖同名条目**（删掉「架构师」之后你可能又新建了一个同名不同内容的）
  - 撤销与清空都是破坏性操作，走**内联二次确认**（首次点击只 arm、按钮变「撤销？」/「确认清空？」，5 秒超时复位），不用原生 `confirm`。危险色只给「清空记录」（不可逆），「撤销这一次」是可逆的、用次要色
  - 记录是**回顾性**信息：只在展开分组时才拉取，不挂全局轮询；失败 / 空态 / 「可能不完整」（`warning`）都留在**这一组内**提示，不占用页面顶部红条——拉不到记录不该把整个设置页标成出错
  - 空值与取值都显式渲染：空串显示「（空）」而不是留白；布尔显示「已开启 / 未开启」；枚举值查词典、**枚举外的取值原样显示**（先校验再转换，否则非法值会被渲染成裸键名 `trail.speed.turbo`）
- **变更记录四条 HTTP 路由**：`GET /api/soul/history`（列表，`?limit=` 只截本次返回、不动 `max`）、`POST /api/soul/history/rollback`（撤销）、`POST /api/soul/history/restore-persona`（恢复预设）、`POST /api/soul/history/clear`（清空）。四条**一律先校验 `req.method`**（教训来自 0.7.2 的 `config/reset` 缺校验：一个 GET 就能重置用户配置）
  - 撤销在**配置写队列内**读记录：放到队列外会与并发写入形成窗口，规划建立在已被别人改过的配置上，指纹校验随后报出一个看起来像「数据损坏」的 `diverged`，排查方向完全跑偏
  - 清空同样借队列串行，否则可能与并发追加撞车（刚清完又冒出一条）
  - 撤销与恢复预设自己也走 `commitConfig`，因此**自己也会留一条记录**——时间线成链，撤销可被再撤销
  - 「记录文件读不出来」回 500 并中止，不按空记录继续（否则用户会看到「还没有任何变更记录」而以为记录被清空了）

**修复**

- **补上一类静默漏记**：预设库的增删改此前既不触发提示词刷新、也不进 `changed`（`diffKeys` 刻意跳过 `personas`），审计若复用同一套判据就会漏记。现已显式记录三类预设事件
  - 「原样再存一遍」**不留假记录**：内容指纹只比 `PERSONA_FIELDS`、**刻意不比 `updatedAt`**（每次保存都会变，算进来会让「原样再存一遍」留下一条「覆盖了预设 X」的记录——**假记录比漏记更糟**）
  - `personas.updated` / `personas.removed` 都额外带**覆盖前 / 删除前**的条目内容：这两类都会丢内容，只记名字的话「恢复此预设」无从恢复
- **相对时间不显示负数**：时间差为负（本机时钟回拨、或服务端时间略快）时归入「刚刚」，而不是显示「-3 分钟前」——那会让人以为记录坏了
- **`NON_PROMPT_FIELDS` 从手写清单改为推导**（打磨轮发现）：它原先只列了 `trail*` 四项，`requireToolConfirmation` 与新增的 `historyMaxEntries` 都不在其中 ⇒ 改一次「保留条数」会重新注册 system prompt section、并向所有活动会话注入一条「配置已更新」，用户视角是「我只调了个容量，Agent 却被通知了一遍配置变了」。现改为 `DEFAULT_CONFIG` 减去 `PROMPT_INPUT_FIELDS` 推导；推导的安全前提（`compilePrompt` 只读已登记字段）另配源文本契约钉住
- **`clampHistoryMaxEntries` 的类型检查前置**（打磨轮发现）：原 `Number(value)` 会把 `null` / `''` / `false` / `[]` 全转成 `0` 再夹成下限 50，配置里一处脏数据就会**安静地把撤销窗口缩到最小档**——而「变小」恰好表现为「老记录不见了」，正是最不该静默的错
- **变更记录指引不再挂在折叠标题旁**：折叠态挂问号等于把说明放在「还没展开就能看到」的位置，而它解释的恰恰是展开后的东西。现说明一律写进「人设预设」展开区的正文块（能直接读的文字优先于 hover），与预设收录范围的说明合并展示；承载它的 `.soul-accordion-head` 层一并删除

**变更**

- `README` / `README_EN`：功能列表新增「变更记录与回滚」一条；路线图状态同步
- `RELEASE_NOTES.md` 功能节里「保存 / 重置按钮带 toast」的描述订正为**内联提示**（成功绿字、失败红字）——0.7.2 就已改掉，文档一直滞后
- `PUBLISHING.md` 发布包清单 32 → **36 个文件**（补 `lib/history.mjs`、`lib/bindings.mjs`、`scripts/verify-history.mjs`、`scripts/verify-bindings.mjs`），`scripts/verify-*.mjs` 与 `lib/*.mjs` 注释同步
- `DEBUGGING.md` 新增变更记录的排查要点：兄弟路径 `soul-config.history.jsonl`（与 `soul-config.json` 同目录）、三个读取上限、出现 grep 不到的半行意味着进程死在追加中途、`diverged` 意味着有人手工改过配置、两种清空方式、以及「设置页找不到变更记录不是坏了」（主入口在插件详情页）

**校验**

- `verify-history` **新增，43 项**（纯函数层：指纹键序不敏感（含嵌套）、差分三向、条目构造与 17 种坏形状、JSONL 解析与三个上限、文件读写与压实、回滚链七种情形、模块边界「不依赖 cordis / 无 console / 内容不进提示词」、条数上限可由调用方指定且非法值回退常量）
  - 两个读取窗口边界用例用**等长行**精确构造（8192 整除 4 MiB ⇒ 起点落在行首；9000 不整除 ⇒ 落在行中间），断言精确到 **id 序列**——只断言条数的话「丢首行」与「少读一行」会互相掩盖。行长还必须让窗口容量**小于** `MAX_READ_LINES`，否则条数上限先切掉老条目，两个边界算出的结果完全相同、**判别力归零**（初版就踩了这个坑）
- `verify-config` 115 → **132 项**：16 处来源归属逐点 + 留痕时机与失败隔离 + 四条路由（方法校验 / 撤销语义 / 恢复预设的护栏）+ 字段标签覆盖率（新增配置字段时不得在时间线里露出裸键名）+ 保留条数的四条契约（默认值与 `lib/history.mjs` 的 `MAX_ENTRIES` 一致、`clampHistoryMaxEntries` 逐值、`sanitizeConfig` 夹取而非拒绝、`migrateConfig` 一致策略）+ 下拉档位与后端区间对齐 + **`NON_PROMPT_FIELDS` 必须推导且编译源码读取的字段全部已登记**
- `verify-client` 23 → **28 项**：新增 C24–C28，按**用户看到的字**断言（不展开不拉取、`原值 → 新值` 与空值占位、两处二次确认、20 条折叠、`warning` 不得染成错误块、说明块并入展开区且两行顺序固定）
- `verify-e2e-prompt` 38 → **77 项**：真实挂载 + 真实临时 `DSH_HOME`，把请求打进去看返回码（405 / 400 / 409），含**手工伪造**记录文件验证「读侧按不可信输入二次校验」；E10c 对 5 个非提示词字段（`historyMaxEntries` / `requireToolConfirmation` / 三个 `trail*`）逐个走**真实 HTTP 写路径**，断言 section 与注入都不增加
- 全链 241 → **402 项**（其中 392 项为九个脚本自报数之和，另有 `verify-compat` 声明的 10 项按「跳过多少」对账）
- 判断力探针分五批共 **83 组变异**（`0.8.0-b` 11 组 / `b-c` 12 组 / `d` 18 组 / 双入口 20 组 / 打磨 22 组），最终全部被拦。**各轮初跑共漏网 5 条，每一条都暴露一种不同的失效：**
  - `b` ⑪ **失败的是探针本身而不是实现**：初版变异在告警行**之前**插了一行 `lastHistoryFailure = null`，紧接着的原始赋值又把它覆盖回真实原因——根本没制造出「静默跳过」这个故障，却让人误以为「这条断言守不住」。**变异没被拦时，先证明变异真的制造了故障，再怀疑断言**
  - `c` M12 **断言覆盖缺口**：`restore-persona` 的 `skipped` 原先只钉了 `reason: 'exists'`，于是删掉 `invalid-name` 那条分支没人发现。那条分支**可达**：`normalizePersonaEvents` 只看「非空且不超长」，三条空格 `'   '` 满足它，而 `sanitizePersonaName` 会拒绝——恰恰是最该回报的一类（用户只看到「恢复了 2 个」，不知道有 1 个被丢掉了）
  - `d` ③ **样本覆盖死角**：负时间差会落到 `Math.floor(diff / 60000)` 上，界面显示「-3 分钟前」，但样本时间戳**全在过去**，负分支一次都没被执行过。补法：加一条 `at` 在未来的记录，断言它归入「刚刚」
  - `d` ⑦ **条件存在但从未为假**：枚举值先校验再查词典，而样本里的取值**全合法**，那个校验条件永远为真。补法：样本里加一个枚举外的取值，断言它原样显示——凡是「先校验再转换」的分支，样本里都要有一条**校验不通过**的
  - `d` ⑯ **期望值是实现的同义反复**：路由桩返回 `max: 200`、断言也写 `'200'`，而那个 `200` 正好等于实现里的 `MAX_ENTRIES`，于是「写死常量」这条断言零判别力。**变体强度不只指变体写法像不像真的，也包括期望值不能是实现的同义反复**
  - 打磨批 ⓰ **「仍通过」其实是探针挂错了脚本**：`label.htmlFor` 的改名是源文本契约（归 `verify-config` 守），却被挂在渲染层脚本上，于是断言根本没机会看见它。**没被拦时除了怀疑断言，还要怀疑「这条变异该由谁来拦」**——单独复现一次即可分清（复现后 `verify-config` 当即变红）。同批还有 3 条只是锚点串没对上真实源码：锚点自检脚本（`_p0822/anchors.mjs`）把「跑一轮几分钟」的代价降到秒级，改锚点不必重跑整批

### v0.8.1（未发布 · 特性已撤下，逻辑层并入 0.9.0）

> ⚠️ **这一段描述的功能没有随 0.8.0 发布。** 设置页的「工作区绑定」分组在 0.8.0 发版前
> 被撤下：按目录绑人设要被 **0.9.0 的三级隔离**（Global → Workspace → Session）整体接管，
> 而那个交互是按「目录字符串」思考的，与工作区平铺卡片完全不同，留下它只会让用户先学一套
> 即将被替换的操作方式。
>
> **代码没有删除**：`lib/bindings.mjs` 的路径规范化 / realpath / 前缀匹配、宿主侧的 cwd 解析、
> 三条绑定路由全部保留 —— 0.9.0 直接把它们作为「Workspace 层解析」的底座。
> 由于特性从未发布，没有任何用户持有 `soul-bindings.json`，解析恒为 `null`、
> 行为与「没有绑定功能」完全一致。下面的描述保留作 0.9.0 的设计输入。

**新增**

- **人设工作区绑定**：让**目录**决定 Agent 用什么人设——在绑定的目录（含子目录）里开的会话自动用那个人设，其它目录回落全局配置。绑定记住的是目录而不是会话，因此新开的会话自动命中，不需要每次手动切
  - `lib/bindings.mjs`（0.8.1-a）：路径规范化（盘符大小写 / 尾分隔符 / `..` 收敛）、最长前缀匹配、绑定表读写与校验，纯函数层不依赖 cordis、也不触碰提示词装配（目录路径只在本地用于选人设，绝不进 system prompt）
  - 宿主侧解析（0.8.1-b）：`registerSystemPrompt` 按会话 cwd 解析，**逐 agent 编译**，不共用一份全局文本；Junction / symlink 入口按**用户写的那个键**命中（展示键优先于身份键），造不出链接的环境如实跳过并申报
  - 绑定路由（0.8.1-c）：`GET/POST /api/soul/bindings` 与 `POST /api/soul/bindings/delete`，一律先校验 `req.method`；非绝对路径、指向不存在的人设都拒绝并给出可直接展示的理由；写入后重注册 section（绑定不改 `soul-config.json`，`promptChanged` 门控看不见它）
- **设置页「工作区绑定」分组**（0.8.1-d）：夹在「人设预设」与「Agent 工具」之间，**展开才拉取**（挂载即等于用户主动打开了它）
  - ① 当前会话目录卡：先回答「我这个项目现在是谁」——目录、生效人设、来源（直接绑定 / 上级继承 / 全局配置）。优先挑**有 cwd 的**会话当「当前」，没有目录的会话任何绑定都不会命中
  - ② 新建 / 改绑入口：点选与手输填的是**同一个字段**（「选择目录…」只是把路径填进来，两者不会给出不同结果）
  - ③ 绑定列表：父目录排在子目录前，`└` 标出子树关系；命中当前生效链的行左侧带主色竖条；失效引用（人设已删）原样列出不自动删除——用户可能只是临时改名
  - ④ 未绑定回落行：把「未绑定的目录用全局配置」这条隐式规则显式写成一条可改的规则
  - **点选走动态 `ctx.inject(['uiWorkspace'], …)`**，不进静态 `inject` 数组：目录选择器只是便利，缺它时整插件不该跟着不激活。服务缺席时**不渲染点选按钮**（否则点下去是对 null 取属性），`pickDirectory()` 抛错后也不再给按钮——宿主能力在启动时判定一次、之后不会变，留着它只会让用户反复点一个确定会失败的东西
  - 解绑走**内联二次确认**（首次点击只 arm、5 秒复位），与删除预设、撤销变更同一套形态，不用原生 `confirm`

**变更**

- **「保留条数」从设置页迁到变更记录区块内**：它描述的是「这个区块自己保留多少条」，就该放在这个区块旁边——用户在详情页看到「最近 37 条 · 最多保留 200 条」，想改这个 200 时就地能改，不必先去设置页的「人设预设」组里找（那个位置本来也解释不清：它既不是预设，也不是设置页任何分组的容量）。
  - **改完即时落盘**，不再经过设置页那个「保存设置」按钮——用户在详情页改完就走人了，要求他再去设置页点一次保存等于挖坑。因此 `historyMaxEntries` 退出设置页表单：`FIELD_KEYS` 拆成 `FORM_FIELD_KEYS`（表单持有）+ `EXTERNALLY_MANAGED_FIELDS`（别处就地管理），**dirty 只看表单段**。全集表仍与宿主 `DEFAULT_CONFIG` 逐字段对账，防漂移一条不少。
  - 只 POST 这一个字段（服务端 POST 体本来就是 patch 语义），不回传整份配置——否则会把别的标签页刚改的字段覆盖回旧值。
  - 服务端会**夹取**（`clampHistoryMaxEntries`）：绿字回读的是它实际接受的值，而不是客户端发出去的那个。改完顺手重拉一次列表——窗口变小（200 → 50）时界面上不该还挂着按旧上限读来的条目。

**修复**

- **`pickDirectory()` 的降级判据是「调用失败」而不是「预读后端种类」**：宿主 `UiWorkspaceService.pickDirectory()` 把底层错误（含 `capability` 字段）包装成了普通 `Error`，客户端读不到种类
- **`uiWorkspace` 缺席时点选按钮仍会渲染**（判断力对照发现）：按钮渲染判断原先只看 `pickerFailed`，于是没有该服务的连接方式下，按钮画得出来、点下去在 `handlePick` 里对 `null` 取属性，用户看到一个看不懂的 `TypeError`。现按钮渲染与 `handlePick` **各自判空**——服务可能在按钮画出来之后被撤走
- **CSS 引用了三个宿主不存在的 token**（`--dsw-font-mono` / `--dsw-alias-label-warning` / `--dsw-alias-state-warning-primary`）：`var()` 会静默回退，路径与警告字样会变成继承色/默认字体。路径改用系统等宽字体栈；「看到的不是全部」不是失败，改用次要色与红字错误区分

**校验**

- `verify-config` 134 → **137 项**：新增三条源文本契约（`uiWorkspace` 只走动态 inject 且 `handlePick` 自己判空 / `SoulBindings` 引用的每个 `bindings.*` 键在 zh·en 里都存在且占位符一致 / 组件用到的每个 `soul-bindings-*` class 都有样式规则）。`FIELD_KEYS` 那条改为按**组合语义**解析：仍要求与宿主 `DEFAULT_CONFIG` 逐字段相等，另加「表单段与别处管理段互斥」与「dirty 只看 `FORM_FIELD_KEYS`」两条
- `verify-client` 28 → **30 项**：新增 C34–C35（C34 守「保留条数只在详情页、改一次只发这一个字段、设置页任何分组里都不得再有它」；C35 守「工作区绑定分组不得出现在设置页」）。原 C29–C33（工作区绑定交互）随该分组一并撤下，理由见下方「暂缓」
- `verify-e2e-prompt` 保持 **90 项**，但 W11 的前置条件改为 `skipNote`：造不出 junction 的环境如实申报「W11–W13 未执行」，而不是塞一条永远红的失败项把整链拖红
- 全链 417 → **422 项**
- 判断力探针本轮共 **10 组变异全部被拦**：工作区绑定 6 组（删按钮判空 / 删 `handlePick` 判空 / `uiWorkspace` 挪进静态 inject / `data-current` 写死 false / 删 `.soul-bindings` 外层样式 / `handleBind` 直接返回），保留条数迁位 4 组（删掉详情页的 retention 块 / 请求体回传整份配置 / 不再调 `saveConfig` / 把下拉塞回设置页；另含「dirty 改用全集」一组，由 `verify-config` 拦下）。其中「删 `handlePick` 判空」初跑**漏网**——只为「服务缺席」做了渲染层断言，没有为「按钮已在屏幕上、服务被撤走」这条时间窗口做断言，补了源文本契约才拦住
- 测试台两处修正：`settle()` 返回的必须是**稳定后那一帧**（原先返回的是「effect 刚改完状态、还没重画」的旧树，断言读到的永远是上一屏）；绑定接口桩必须带 `ok: true`（服务端每条路由都是 `send(res, 200, { ok: true, ... })`，桩漏了会被客户端 `postJSON` 判成失败，整条成功链路一次都没被走过）

### v0.7.2（2026-10-10）

**新增**

- **插件列表里的展示名可自定义**：新增 `locale/en.json` 与 `locale/zh.json`，把展示名从包名 `dsh-soul` 换成 **Soul**（英文）/ **Soul 人设**（中文）
  - 机制：宿主的 `readPluginMeta` 先读 `<包>/locale/<语言>.json` 的 `meta.title` / `meta.description`，读不到才回退到 `package.json` 的 `name` / `description`（见 `dsh-app-boot` 的 `readPluginMeta` 与 `dictionariesOf`）；`dictionariesOf` 会扫描 `locale/` 下**所有** `.json`，文件名即语言 id，所以加语言只需加文件
  - 三处漏任一处都会**静默回退成包名**（不报错、只是显示成 `dsh-soul`），故各配了断言：① `files` 白名单加 `locale`（否则不进发布包）；② `exports` 声明 `"./locale/*.json"`（本包有 `exports` 字段，未声明的子路径会被挡住）；③ JSON 必须是 `{ meta: { title } }` 结构（`dictionariesOf` 读的是 `meta?.title`）
  - 断言还要求**英文展示名不得等于包名** —— 否则「生效」与「回退」无法区分，等于这条契约没生效
  - 行为层直接调宿主导出的 `readPluginMeta` 校验解析结果（title 与 `locale/*.json` 一致、且无 `error` 字段）；判断力用 **7 组变异**验证（删 `locale` 目录 / 去 `exports` 子路径 / 拆 `meta` 外层 / title 空串 / 改回包名 / 删 `zh.json` / title 非字符串），7/7 被拦
  - 顺带修掉一处：手动同步 profile 副本时若漏了 `assets/`，图标解析会失败（`readPluginMeta` 会保留文本但附带 `error`）—— 发布包 21 → **23 个文件**（新增 `locale/en.json`、`locale/zh.json`）

**修复**

- **`set_persona` 每次成功调用都会在结果渲染阶段抛错**（本版审计发现，0.7.1 起存在）：工具定义只给了 `output.schema`、**没给 `output.render`**。`defineTool` 会**无条件**把 `options.output.render` 包成 `render(args, value) { return userRender(args, value) }`，而 `userRender` 是 `undefined` ⇒ **注册照样通过**（底层 `register` 校验的是包装后的函数），但宿主 `createSuccessResult` 在**每次工具成功执行后都会无条件调用**它（`dsh-tools` 的 `createSuccessResult`，`lib/index.js:3541-3548`）⇒ 抛 `TypeError: userRender is not a function`，被包成 `projectionError("render")`。用户视角是「Agent 说改了人设却报错」。自查 DSH 自带插件：**19 个都提供 `render`，只有 2 个没有**（且那 2 个未注册工具）。现补上 `render`，把 `message`（已是完整一句话，含 pending 提议与失败原因）作为给模型读的文本，避免再套一层 `JSON.stringify`
  - 根因是**校验缺口**：原断言只验到「`defineTool` 不抛错 = 注册成功」，**没走结果渲染那一步** —— 这正是「断言只到注册、没到能用」。现该断言升级为：抽出真实 `defineTool({...})` 定义对象整体求值 → 用真实 `defineTool` 注册 → **再逐种返回值走一遍 `output.render`**，要求返回 `[{ type: 'text', text }]` 且文本非空（4 种：成功 / pending 提议 / 失败 / 无变化）。判断力：删掉 `render` 立刻被拦，报错直指根因
- **设置页轮询在页面隐藏时仍在跑**：`visibilitychange` 此前只处理了「变可见」这一半（`if (visible) refresh()`），而 `setInterval(refresh, 2000)` 无条件执行 ⇒ 后台标签页每 2s 仍发两个请求（config + personas），实测 250ms 内触发 4 次。修法是把守卫放进 `refresh` 本身（`interval` 与 `focus` 都走它，一处覆盖两条路径、无需重建定时器）。断言钉住「守卫必须在发请求之前」并含防回归（不得把轮询整个删掉当修好）；判断力 3 组变异（去守卫 / 守卫后置 / 删轮询），3/3 被拦

**变更**

- **设置页样式统一到宿主设置语言**（方案 A：去外层盒子 + 分组卡片化）：此前 `.soul-section` 自带 `margin/padding/border/background`，等于在宿主设置内容区（已有 `padding:0 24px 24px`）里**又套了一层盒子** —— 这是观感与「模型」「插件」等栏目不一致最直接的原因。现按宿主各栏目的实际写法对齐：
  - **容器**：去掉外盒与背景，改 `display:flex;flex-direction:column;gap:12px;max-width:760px`，与宿主 `.zGbnIq_section` / `.pbvGtq_section` / `.qSYn7G_section` 同构
  - **分组卡片**：`.5px` 描边 + `settings-card-stroke` / `settings-card-fill` + `radius-xl`(20px)，对齐宿主 `.zGbnIq_rowCard` / `.qSYn7G_card`（此前是 `1px` + `border-l2` + `6~8px` 圆角 + `bg-layer-1`）
  - **标题**：`16px/500/24px`（此前字重 600，宿主用 500）；**字段标签**：`12px/500/18px`（此前 13px）
  - **徽标**：`.5px` 描边 + `radius-xs` + `11px/16px`，对齐宿主 `.zGbnIq_rowTag`（此前 10px、无描边）
  - **提示条**：硬编码的 `#f6ffed` / `#52c41a` / `#fff1f0` / `#f5222d` 全部换成 `state-success-primary` / `state-error-primary` + `bg-module-platform`——**原先在深色主题下完全不可用**
  - **提示气泡**：`#ffffff` / `rgba(0,0,0,.85)` 硬编码同样改走 `bg-module-platform` / `label-primary`（深色主题下原本是白底黑字）
- **修掉一类静默失效：CSS 引用了宿主不存在的 token**。`--dsw-alias-label-error` **在宿主主题里根本不存在**（宿主表达错误色统一用 `--dsw-alias-state-error-primary`），而我们在 3 处用了它：`var()` 对未定义变量会**静默回退成继承值**——真实 Chrome 实测渲染为 `rgb(0,0,0)`（黑色），不报错、不警告。后果是**错误提示、危险按钮、快捷开关失败态全部不红**，而 200+ 项断言全绿。现已全部纠正，并新增断言要求「CSS 引用的每个 `--dsw-*` token 必须在真实主题包里存在」（本机解析不到主题包时 `skipNote`）。判断力：把 token 改回 `label-error` 立刻被拦，报错直指不存在的名字
- **人设预设列表改为卡片式，操作按钮对齐宿主列表按钮**：
  - 每个预设从「共用容器 + 虚线分隔」改为**独立卡片**（`.5px` 描边 + `settings-card-fill` + `radius-lg`），卡片间 `gap:8px`（对齐宿主 `.zGbnIq_rows` 的 `gap:8px`）—— 这同时给出「每个人设之间有一点间隔」的观感
  - **操作按钮**从「下划线文字链接」改为宿主列表按钮规格：`.soul-persona-action` 对齐 `.zGbnIq_linkButton`（`height:28px` / `radius-sm` / `padding:0 10px` / `12px-18px` / `label-tertiary` / 透明底无边框 / hover 用 `interactive-bg-hover`）；「删除」对齐 `.zGbnIq_dangerButton`（同尺寸，`state-error-primary`，hover 用 `interactive-bg-hover-danger`）。操作区间距也改为宿主的 `gap:4px`
  - **去掉内置行的灰色底**：宿主**不给行容器加 hover 底色**（`interactive-bg-*` 只用于按钮等可点元素），灰底在白色卡片群里会被误读成 hover 态。来源区分交给「内置」徽标 —— 宿主也是用 `rowTag` 标「默认」而非改底色
  - 「自我介绍」等多行输入框最小高度 `100px → 120px`（小档 `60px → 72px`）
  - 顺带删掉已无使用者的 `.soul-prompt-link` 两条规则（改按钮类名后成为孤儿样式）
  - 新增断言「人设行操作按钮规格对齐宿主列表按钮」（尺寸 / 圆角 / 内边距 / 字号 / 行高 / 默认色 / hover 两态 / 列表间距 / 卡片化 / 不得加行底色），判断力 5 组变异全部被拦（高度 36px / 圆角 6px / gap 归零 / 行改回共用容器 / 加回行底色）；另修掉一条**耦合实现细节**的断言：它把旧类名 `soul-prompt-link soul-persona-danger` 写死，改样式即失效，现改为只钉「带 `soul-persona-danger` 的按钮」
- **人设预设改为卡片堆叠轮播**（一次一张 + 滑动 + 叠放）：预设不再平铺成列表，而是**一次只展示一张卡片**，左右各留一张做层叠露边，切换时卡片带 `transform` 滑动与轻微入场动效形成纵深
  - 层叠几何：当前张居中（`offset 0`），`±1` 两张分别向左右偏移 34px、下移 6px、缩小 5.5%、透明度 0.55；偏移量刻意远大于卡片内边距，否则只露一条缝、看不出「一叠卡片」（断言要求 ≥20px，实测 0 与 8 都被拦）
  - 堆叠容器固定 `min-height:118px` 且左右各留 40px：三张卡片绝对定位在同一容器，若走文档流则切到末张时容器高度会突然塌陷（断言要求 ≥100px，实测 0 被拦）
  - **对「一次只见一张」的补偿**（列表本可一眼扫完，这是该改造的主要代价）：卡片内显示 `i / n` 位置指示、下方圆点可直达任意预设、左右翻页按钮在首/末张分别禁用；`aria-selected` 标注当前圆点
  - 非当前卡片 `aria-hidden` 且不参与 Tab 焦点（避免读屏念出重复内容）；索引在渲染时**夹取**（预设被删除后会越界，实测去掉夹取即被拦）
  - 位置指示只渲染在当前卡片上 —— 初版无条件渲染，导致左右露边的卡片也显示同一个 `i / n`，看起来像显示错误（**由行为断言 C16 抓出**）
  - 滑动与入场动效同样纳入 `prefers-reduced-motion`（该规则现覆盖光轨层 / 开关圆点 / 提示条 / **卡片**四处）
  - C16 从「断言渲染两行」改造成卡片堆叠的行为断言（卡片数、当前张唯一、★ 两方向、内置徽标、位置指示内容、翻页按钮禁用边界、**真的点一下翻页**并断言卡片内容与位置指示同步变化）；判断力 5 组变异全部被拦（去索引夹取 / 去「下一张」禁用 / 位置指示无条件渲染 / 卡片不绝对定位 / 翻页 onClick 置空）
  - 顺带给测试台加了 `findAllByClass`（**类名 token 精确匹配**）：此前用 `className.includes('soul-persona-card')` 会同时命中 `-card-head` / `-card-pos`，把 2 张卡片数成 6 个节点、报出误导性的失败信息

- **当前生效的人设一眼可辨**：此前只有名称前的 ★ 能表明哪张卡是当前配置，而按钮一律写「使用」，不够醒目。现在生效中那张的按钮文字变 **「使用中」**（英文 Active），样式改为**描边式**（透明底 + 品牌色字与框），与其它卡片的实心主色按钮形成对比 —— 三重标识叠加：★ + 「使用中」+ 描边样式
  - 描边用 `box-shadow: inset` 而非 `border`：基类已是 `border:0`，加 border 会改变盒模型尺寸，导致「使用中」与其它按钮不等高、切换时布局跳动（断言钉住「不得用 border」）
  - 按钮**仍可点击**（不 disabled）：重复应用是幂等操作（宿主回「配置无变化」），禁用反而让人以为界面卡住
  - 判断力 5 组变异全部被拦（文字不随状态变 / 去掉 active 类 / 样式改回实心主色 / 用 border 画描边 / 删掉中文文案键）
- **展开「人设预设」时自动定位到当前生效的那张**：此前轮播固定从第 1 张开始，而内置项排在前面、生效项（尤其自建）往往在后面 —— 点开分组要翻好几下才看得到自己正在用的是哪个。现在每次展开都会直接停在生效项上
  - 只在「展开」这一刻定位，展开期间**不**持续定位：否则 2s 轮询刷新预设列表会把用户手动翻到的位置拽回去（用 ref 记住「本次展开已定位过」）
  - 折叠时重置标记 ⇒ 下次展开重新定位（这正是需求：「每次点击开」都要展示当前使用的）
  - 无生效人设（或签名对不上任何一项）时退回第 1 张，总要给个确定落点
  - **预设列表未就绪时不下手**：personaNames 为 null 时定位会对 null 调 indexOf 抛 TypeError、直接打断设置页渲染。真实触发场景是「先应用过预设 → 刷新页面」，此时配置先到、列表还在路上
  - 新增 C18 行为断言（7 个子场景：生效项在末张/在首张/无生效项/手动翻页不被轮询拽回/折叠再展开/列表加载中/列表加载中且已有生效人设）；判断力 **4/4** 组变异全部被拦（去掉自动定位 / 去掉折叠重置 / 去掉只定位一次守卫 / 去掉空值守卫）
- **删除预设改用内联二次确认**（去掉原生 `window.confirm`）
  - 起因：用户实测「创建人设后删除，整个设置页的下拉框与输入框都无法操作」，**最小化再恢复就正常**。原生模态框在 webview 里可能把文档焦点留在异常状态，而 `focus`/`visibilitychange` 正好能重置它。宿主自己的设置页也不用原生 confirm
  - 交互：第一次点「删除」→ 按钮变**实心危险色的「确认删除？」**（普通态是描边，颜色与文案双重区分）；再点一次才真删
  - **5 秒超时复位**：没有这道兜底，「确认删除？」会一直挂着，用户过一会儿随手一点就真删了
  - 待确认态**自动放宽按钮宽度**：普通态按「删除」两字定宽 43px，而「确认删除？」有五个字，沿用原宽会把文字挤到溢出（Chrome 实测 `scrollWidth` 80 > 43 确认溢出；改为 `flex:0 0 auto` 后实测 82px、无溢出）
- **「存为预设」入口移到「保存设置」旁**（用户反馈原位置「比较迷茫」）
  - 原问题：它被塞在预设列表最下面，而用户此时的心理模型是「我在看别人的预设」，说不清「保存当前」的「当前」指什么；而真正被保存的是「关于你/特质」里的字段（在**别的分组**里）；且「保存设置」与「保存当前为预设」两个保存并列、语义未区分，名字还要先想好才能点
  - 改法：做成「保存设置」旁的**同级动作**（`保存设置` ｜ `存为预设…` ｜ `重置默认`），**点开才问名字**，命名弹层里明确列出「将保存：…」与「不含：昵称/职业/介绍」—— 最后这行直接消灭了「不知道存了哪些值」的困惑
  - 弹层支持遮罩点击、取消按钮、`Esc`、`Enter` 提交；预设列表区域只保留「浏览 / 使用 / 删除」
- **卡背（详情面）展示全部维度与全文**：正面效果栏是截断的（首句 + 60 字 + 3 行 clamp），最长的人设（自驱型协作者 339 字）被砍掉约 85%。卡背列出**全部 6 个维度** + `customInstructions` **全文**
  - **卡背不是轮播的第 N+1 张**，而是当前卡的另一种「面」—— 否则 total 要变 2N、位置指示与圆点全要改。翻页翻的是「卡」，翻面翻的是「面」，索引逻辑一行未动
  - 翻面状态绑**人设名**而非索引：删除/刷新后同名的卡仍是同一张，绑索引会在列表变短时翻错面
  - 动效取「淡入淡出 + 轻微 `rotateY(±12deg)`」而非真 3D 翻转：卡片的 `transform` 已被**叠层偏移**占用，把 `rotateY(180deg)` 写进去会让两者抢同一个 `transform` ⇒ 叠层几何变脆。故翻面只作用于内层 face，外层 transform 原样不动
  - 背面**不放**「使用/删除」按钮（阅读态；且实测卡背内容已占 370/372px 无余量），只留「返回」
  - 修掉两个渲染缺陷（均为实测发现）：① 卡背徽标沿用了「压在插画上」的 `position:absolute`，在卡背 flex 行里脱离文档流**与名称重叠**（实测徽标 [44,77] 压住名称）⇒ 重置为 `static`；② 名称用 `flex:1` 会撑满整行、把徽标挤到同一位置 ⇒ 改 `flex:0 1 auto`
  - 修掉一个滚动缺陷：滚动原放在 face 上会让**「返回」按钮跟着滚出视野并被文字压住** ⇒ 移到全文块自身
  - 新增断言「卡背（详情面）展示全部维度与全文，且不动卡片 transform」，判断力 **7/7** 组变异被拦（全文改回截断 / 滚动放 face / 徽标不重置 static / 名称改 flex:1 / 卡片 transform 混入 rotateY / 维度列表写死 / 背面加使用按钮）
- **输入框展示当前人设（A + B 组合）**：用户反馈「输入框位置有点紧张」，故主位置不放在已被占满的底栏
  - **A（主位置）：输入框卡片之上的独立一行**（`conversation.input.dock`）。宿主源码里该槽位渲染在 `composerStack` 中 `inputBar` 之**前**，不参与底栏的水平排布 ⇒ 零挤压、抬眼即见。底栏当时已有「+ 附件 / 完全权限 / 个性化」+「模型 / 积分 / 发送」共 6 个控件，再塞必然继续挤
  - **B（互相印证）：底栏「个性化已启用」缀上当前人设名**（`· 苏格拉底式提问者`），与上方标签呼应；**仅在已启用且匹配到预设时显示**（关闭时挂着人设名会误导）
  - 标签**可点**：弹出全部预设（复刻设置页排序，内置在前），当前项带 ★，点选即应用；支持点空白关闭、`aria-haspopup` / `aria-expanded` / `aria-selected`
  - 名字可能很长（自建预设上限 30 字）⇒ 标签与底栏缀名**都单行省略**，底栏额外限宽 `max-width:9em`，避免把底栏撑开
  - 鲸鱼标记用 `currentColor` + `mask` 绘制（不引图片、避免额外请求）；初版用了 `#000` 被「CSS 不得硬编码颜色」断言拦下，已改
  - 新增断言（钉住注册在 dock 而非 left、未启用时不渲染、点选后必须写回 store、可关闭、两处都必须单行省略、文案键中英各一份）；判断力 **6/6** 组变异被拦
- **卡背改为真 3D 翻转**：此前的「淡入淡出 + 轻微 `rotateY(±12deg)` 暗示」效果一般，改为标准 3D 翻转
  - **三层职责分离**是能做真 3D 而不伤叠层几何的关键：`.soul-persona-card`（叠层位置 translateX/Y/scale）→ `.soul-persona-flipper`（rotateY 0↔180）→ `.soul-persona-face-*`（两个面）。若把 rotateY 写进卡片，就要与叠层偏移合成同一个 transform 字符串，偏移几何会变脆
  - `perspective:1000px` 挂在卡片上（必须挂在**翻转元素的父级**才生效）；`.soul-persona-flipper` 用 `transform-style:preserve-3d`；背面预先 `rotateY(180deg)`，两面均 `backface-visibility:hidden`
  - **卡片的 `overflow:hidden` 已移除**：CSS 规范规定 `overflow != visible` 会强制 `transform-style: flat`，3D 会被压平。裁切职责下沉到 `.soul-persona-face`（带 `overflow:hidden` + `border-radius:inherit`，效果等价）
  - 几何自检（真实 Chrome 固定角度渲染）：**90° 时两个面都不可见**（完全空白）——这正是真 3D 的判据（两面同时侧立于视线）；45°/135° 出现透视收缩。若是平面淡入淡出，90° 必然有一面可见
  - 未翻面时背面 `pointer-events:none`（它被 backface 隐藏但仍在树里）；`prefers-reduced-motion` 下去掉翻转过渡
  - 断言相应改写（钉住 flipper 的 preserve-3d、翻转 180°、卡片 perspective、背面预转 180°、两面 backface-visibility、卡片不得有 overflow）；判断力 **6/6** 组变异被拦
- **修掉卡背「返回」按钮高度异常**（新建预设指令较短时按钮被拉伸到 98px）
  - 根因是 **CSS 选择器权重与声明顺序**：`.soul-persona-back-btn{flex:none}` 与基类 `.soul-persona-action{flex:1 1 auto}` 都是单类选择器（权重相同）⇒ **后声明者胜**；本规则排在基类之前，于是 `flex:none` 被覆盖，按钮变成弹性元素。短文本时剩余空间把它拉伸到 98px（正常 35px），长文本时又被压缩到 21px
  - 修法：选择器加祖先前缀 `.soul-persona-face-back .soul-persona-back-btn` 提高权重，**与声明顺序解耦**（挪顺序易被后续编辑打乱，治标不治本）
- **修掉「应用预设后点保存，人设被打回旧值」**（用户实测：点「使用」显示正常，但「保存设置」亮起；一点保存，刚选的人设状态变回默认）
  - 根因：表单回填 effect 原是「`dirty || saving` 就**整体**不回填」。应用预设后 store 先变、本地表单还是旧值 ⇒ 那一次渲染 `dirty` 恒为 true ⇒ 回填被挡 ⇒ 表单停在旧值 ⇒ 「保存」把**旧表单值**整体 POST 上去，把刚应用的预设覆盖回旧配置
  - 修法：**按字段**判断 —— 记录「上次与 store 同步时的本地快照」（`lastSyncRef`）；某字段当前本地值仍等于快照 ⇒ 用户没动过 ⇒ 跟随 store 回填；不等于 ⇒ 用户正在编辑 ⇒ 保留。既修掉「保存误亮」，又逐字段保留了「轮询不覆盖正在编辑内容」的原有保护
  - `saving` 期间仍整体跳过（保存流程自身会带着响应回填，中途再插一次只会闪烁）
  - 新增 **C19** 行为断言（5 个子场景）：应用后保存按钮禁用 / store 写回 / 无 dirty 提示 / **手改字段后保存按钮恢复可用** / **编辑中字段不被外部写入覆盖**（`loadConfig` 返回不同的 style 来模拟「别处改了配置」—— 若返回相同值，effect 依赖不变根本不跑，测不出差异）
  - 判断力 **4/4** 组变异被拦（改回 dirty 整体跳过 / 无条件跟随 / 去掉快照记录 / 判断反转）；verify-client 18 → 19 项
- **保存成功提示对齐宿主模型设置页（内联绿字，不再走 toast）**（用户反馈「保存设置的提示和全局不统一」，并指出模型页保存后是在上方出现一行绿字「已保存 DeepSeek (deepseek-official)。」）
  - 查证宿主源码（`dsh-client-ui-settings-models`）：保存成功的提示**不是 toast**，而是设置页顶部的一行内联绿字 `.savedNotice` —— `color:var(--dsw-alias-state-success-primary)`、`margin:0`、12px/18px、`role:status` + `aria-live:polite`，位于标题/简介之后、分组列表之前；文案 `已保存 {provider}。`
  - 生命周期也对齐：**不会自动消失**，只在开始编辑/删除/新增时清除（宿主用 `setSavedTarget(void 0)`；我们用 `dirty` 变 true 时清除）
  - 保存/重置/应用预设/存为预设/删除预设的成功提示全部改为内联绿字；文案对齐宿主语气（句末带句号、无 emoji 装饰、带上下文对象名）
  - **错误提示仍走 ui.Toast**（打断性提示浮层更合适，失败原因要读得完 ⇒ 停留 5s）
  - 新增断言钉住：内联 `<p>` + role/aria-live、绿字规格、dirty 清除、成功文案不得再走 toast、失败仍走 Toast 且停留 5s、8 个 `notice.*` 文案键双语齐备
  - 期间踩坑：清除用的 effect 一度写在 `dirty` 声明之前 —— 依赖数组在渲染期求值 ⇒ TDZ（`Cannot access 'dirty' before initialization`），已移到定义之后
- **失败提示也对齐宿主（内联红字，彻底不用 toast）**：继成功绿字后，用户指出错误提示也应与全局一致。再次查证宿主（`dsh-client-ui-settings-models`）：**Toast 引用 = 0**，错误全部是内联红字 `.error`（`state-error-primary`、margin:0、12px/18px、`role:alert`），共 11 处使用，就地出现在问题发生处
  - 保存/重置/预设操作的 6 处失败 toast 全部改为内联红字 `.soul-error-notice`（规格照抄 `.zGbnIq_error`），与绿字同位互斥（失败压过成功 —— 用户要看最新一次操作的结果）
  - `ui.Toast` 与 `showToast` 随之整体移除（不再有任何 toast 路径）；`prefers-reduced-motion` 断言同步简化
  - 断言重写为对称契约：绿字/红字规格、role=status/alert、互斥逻辑、dirty 清除、无任何 toast 残留、8 个 `notice.*` + 3 个失败键双语齐备
  - 附带清理：一处 CSS 行与过时注释被意外拼接（此前编辑遗留），已恢复
- **「默认」成为实体预设（列表首位）+ 删除按钮移到卡背**（两个想法都来自用户对「★ 语义」与「删除位置」的反馈）
  - **默认人设实体化**：Agent 出生即有人设（`DEFAULT_CONFIG` 那套值），此前它不可见 —— 配置不匹配任何预设时 `activeName=null`、dock 标签显示「未匹配预设」，是一个无归属的漂移状态。现在把出厂状态包装成列表第一位的预设「默认」（声明全部 6 个人格维度，`language` 按既有约定豁免），三条不变量成立：**任意时刻都有活动人设**；**改任何特质 ⇒ 丢 ★**（对默认的匹配是事实上的全量比较 —— 正是用户期望的严格语义；其余内置保持部分覆盖不变）；**应用「默认」= 一键恢复出厂人格**（比「重置默认」轻，不动关于你/光轨）
  - 「默认」与内置同权保护：删除/保存同名一律 400（端到端实测：删除报「内置预设，无法删除」、保存报「请换一个名称」）
  - 徽标区分：默认卡显示「默认」徽标（新词典键 `personas.default`），其余内置仍显示「内置」
  - **删除按钮移到卡背**：用户反馈自定义卡的删除夹在「使用/详情」中间的 43px 窄条观感怪异（实测自建卡 234px 里三钮 88/43/88，且内置卡两钮 113/113 反而整齐）。现在正面统一为「使用 + 详情」两钮；删除移到卡背底部按钮行与「返回」并排（零高度成本），二次确认（armed 态 + 5s 超时）逻辑不变 —— 背面是「查看/管理」语境，删除放这里语义更顺，且破坏性操作天然远离高频操作
  - 端到端实测（真实宿主路由）：列表首位=默认/总数 8、出厂 `activeName=默认`、改特质后 `activeName=null`（诚实）、改回后恢复「默认」、删除与保存同名均被拒
  - 断言同步：内置遍历改走 `mergePersonas` 视图（默认不在 `BUILTIN_PERSONAS` 字面量里）、默认的空 `customInstructions` 豁免、正面无删除/占位、卡背有删除与按钮行容器、back-btn 弹性占满
- **卡牌正面任意处点击即可翻到卡背**（用户需求：不用精准点到「详情」小按钮）
  - `onClick` 挂在正面 face 上（`cursor:pointer` 提示整面可点）；「使用」按钮 `stopPropagation` —— 点了就该用，不能顺带翻面；「详情」本就是翻面语义，不拦
  - 背面**不**加整面点击返回：背面有全文滚动区与文字选择需求，整面点击会与之冲突，「返回」按钮仍是唯一返回入口
  - 过程中一处编辑工具事故（注释+字面 `\\n`+CSS 被拼进同一字符串 ⇒ CSS 规则失效），由新断言「`cursor:pointer`」当场暴露并修复 —— 新断言顺手拦下了自己的回归
  - 断言钉住：face onClick、使用按钮 stopPropagation、cursor:pointer
- **修掉「点侧边卡切换人设时新卡自动翻面」**（用户实测）
  - 根因：上一版把整面翻面的 `onClick` 挂在了**所有卡**的正面 face 上。点叠层侧边卡时，事件先冒泡到它 face 的 `setFlippedName(侧边卡名)`，再冒泡到卡片的 `go()` 翻页 ⇒ 翻页后它成了当前卡 ⇒ `flippedName === 它` ⇒ 一上来就以背面姿态出现
  - 修法：face 的 `onClick` 限定 `current`（叠层卡的点击留给 `go()` 翻页）；`cursor:pointer` 同理只给当前卡（叠层卡点击是翻页，不该提示「可翻面」）
  - 行为层回归测试 **C20**：侧边卡正面不得挂 onClick → 点它只翻页 → 新当前卡 `data-flipped=false` → 当前卡正面仍可点翻面 → **翻到背面后正面撤掉整面点击**（不重复触发）
  - 判断力 **3/3**：去掉 `current` 守卫（bug 复发）/ 漏掉 `!flipped` 守卫 / 侧边卡又被挂上 onClick —— 全部被拦
  - verify-client 19 → 20 项
- **卡背整面点击返回正面**（与正面「整面点击翻到背面」对称，用户需求）
  - **必须排除「拖选文字」**：卡背有 339 字可滚动全文，用户很可能拖选复制；拖选结束会触发一次 click，不判断就等于「一选就跳回正面」。判据用 `getSelection()` 是否折叠且非空 —— 有选区说明是选择操作，不返回
  - 「删除」按钮 `stopPropagation`：卡背整面点击=返回，不挡住的话「确认删除」会被返回动作打断（翻回正面、看不到确认态）
  - `cursor` 区分：卡背整体 `pointer`（可点返回），全文块 `text`（可选中）
  - 顺带修掉两处**断言自身的脆弱点**（都被这次改动暴露）：① `backBlock` 切片原用固定 2600 字符，内容一长（加了删除按钮）就截断 ⇒ 断言「看不到」新元素而误报，改到稳定锚点（`const cards = []`）为界；② 正则在 PowerShel 替换中被写成双反斜杠 ⇒ 匹配字面反斜杠而非括号
  - C20 扩到 7 个子场景（含拖选保护与无选区正常返回）；判断力 **4/4**：去掉整面 onClick / 去掉拖选保护 / 删除不 stopPropagation / 永不返回 —— 全部被拦
- **内置预设统一声明全 6 个人格维度**（language 豁免）—— 修掉「同一动作结果随预设而变」
  - 问题：声明列表**同时驱动应用与匹配**，两者需求相反 —— 应用时「只写声明字段」希望少声明不越权，匹配时「只比声明字段」希望全声明才严格。早期为不越权只声明要改的维度，导致匹配退化成宽松比较：**改一个预设未声明的特质后 ★ 仍挂着**，而且结果随预设而变（改 emoji 在「极简主义者」上丢 ★、在「苏格拉底式提问者」上不丢）⇒ 用户无法形成稳定预期
  - 现统一全量声明，语义单一可预期：**改任何特质 ⇒ 不再属于该预设**
  - 代价（刻意接受）：应用预设会把 6 个人格维度整体复位到预设值，而不是「只改一部分、其余保留我手动的」—— 与「用预设就是不想逐项自己配」的心智模型一致
  - language 仍豁免（全量声明唯一例外）：内置是跨语言共用的通用人格，写死 zh 会让英文用户应用一次就被切回中文
  - 新增断言「每个内置预设都声明全 6 维」：逐人设校验 6 维齐全 + language 必须缺席 + **行为闭环**（应用后匹配自己、改任一特质维度都失去匹配、改 language 不移除匹配）
- **配置偏离任何预设时给「存为新预设」出口**（承接「改任何特质都丢 ★」）
  - 全量声明后 ctiveName=null 成为常见状态，它诚实但**没有出路** —— 用户刚调出来的配置无处安放
  - 预设分组底部出现：一句说明「当前配置与任何预设都不一致。」+ 描边式「存为新预设」按钮，**复用已有命名弹层**（不另造保存流程）
  - 判据 ctivePersona === null && personaNames !== null && !personasError：加载中/加载失败不算偏离；全部默认值命中的是「默认」预设，也不会走到这里
  - 新增断言钉住判据、提示块、文案键（双语）、复用命名弹层、以及「弱化底 + 描边式次要按钮」的样式规格
- **移除输入框上方的人设标签（dock 行）**（用户判断：「显示没有太大意义」）
  - 移除组件 SoulPersonaChip、槽位注册、全部 chip CSS、6 条 chip.* 文案键；人设切换与状态展示统一收敛到设置页卡片区
  - 判断力 **5/5**：去掉某维声明 / 内置声明 language / 去掉偏离提示 / 出口按钮不复用弹层 / 偏离判据缺「列表已就绪」守卫 —— 全部被拦
  - verify-config 107 → 108 项
- **移除「默认」预设**（用户判断：人设卡片里的默认人设可以删除了）
  - 上一版把出厂配置包装成列表首位的「默认」预设，本意是给「无匹配」状态一个落点。但配合「改任何特质都丢 ★」之后，落点由**偏离出口**（存为新预设）承担即可，多一个「默认」反而是噪音
  - 数据层清理：删 `DEFAULT_PERSONA` 定义与 `personaEntry` 辅助、`builtinPersonaNames` 不再前置、`isBuiltinPersona` 去掉特判、`mergePersonas`/`resolvePersona` 改回直取 `BUILTIN_PERSONAS`
  - 副作用（正面）：**「默认」不再是保留名**，用户现在可以自己创建名为「默认」的预设（端到端实测保存返回 200）
  - 客户端清掉徽标分支与 `personas.default` 文案键；出厂 `activeName` 回到 `null`（诚实：没有任何预设被应用）
- **底栏开关始终展示当前人设**（用户需求：未匹配时显示「自定义」）
  - 此前只有匹配到预设才缀名字，手改过特质后留空 —— 等于「我现在用的是什么」没答案；「未匹配预设」那种说法又听着像报错
  - 现在：匹配到预设显示预设名，未匹配显示**「自定义」**；关闭个性化时不显示（人设此刻不生效，挂名字会误导）
  - 新增 **C21** 行为断言覆盖三种状态（匹配/未匹配/关闭）
  - 判断力 **4/4**：「默认」回到列表 / 底栏留空 / 关闭时仍显示人名 / 人名不限宽 —— 全部被拦
  - verify-config 108 → 109、verify-client 20 → 21
- **修掉 hover 提示被手风琴裁掉顶部**（用户实测：Agent 工具下「人设变更需确认」右侧的提示被上方遮住一部分）
  - 根因：`.soul-accordion{overflow:hidden}`（本为把触发器的方形 hover 背景裁进圆角）。而该分组里提示是**第一个元素**，上方只有 14px 内边距，提示高 72px ⇒ 必然越界被裁
  - 实测数据（真实 Chrome，几何测量）：**旧实现裁掉 19px，修复后 0px**；触发器顶圆角 19.5px（= 20px 圆角 − 0.5px 边框）、展开态底角 0
  - 修法：容器不再裁剪，改为给触发器补顶圆角（视觉等价、不裁剪）；收起态只有一个触发器 ⇒ 四角都圆
  - 新增断言「手风琴不得裁剪向上弹出的提示」：**这是本项目第一条几何契约断言** —— 有没有 `overflow:hidden` 不等于会不会被裁（取决于提示高度、上方留白、祖先链），字符串检查钉不住，故按「禁止裁剪 + 必须有圆角补偿」三条一起钉
  - 判断力 **4/4**：`overflow:hidden` 加回容器 / 触发器不补圆角 / 收起态圆角规则被删 / hint 自身加 overflow —— 全部被拦
  - verify-config 109 → 110 项
- **翻页会复位翻面态**（用户实测：翻开 A 卡背面 → 切到 B → 切回 A，A 仍以背面出现）
  - 根因：`flippedName` 记住「哪张卡被翻开过」，而 `go()` 只改索引、不清它 ⇒ 切回来时 `current && flippedName === name` 又成立，于是「记得」上次的面
  - 语义判断：翻面是「看这张卡背面」的**临时阅读动作**，翻页是「换一张看」—— 注意力已重置。记住它会让用户以为这张卡「默认就是背面」
  - 两处换卡入口都复位：`go()`（翻页按钮/圆点/侧边卡）与**展开自动定位**（折叠后重新展开会定位回 activePersona，若不清就会带出旧背面）
  - **刻意不在「折叠」那一刻清**：折叠期间 body 不渲染、翻面态在 UI 上不可观测，清与不清行为等价（判断力验证证实）—— 职责收敛到可观测的「自动定位」一处，避免两处重复同一件事
  - 新增 **C22**（5 个场景，含圆点导航这条独立路径与折叠→展开）；verify-client 21 → 22 项
  - 判断力 **4/4 有效变异被拦**：`go()` 不复位（原 bug）/ 自动定位不复位 / 两处 `current` 限定同时移除 / 翻页后把状态写回旧卡
- **两处测试自省（判断力验证逼出来的）**
  - 场景⑤ 初版**没有判别力**：它翻的是第 1 张、而自动定位回到第 0 张，两卡不同 ⇒ `flippedName` 天然不匹配 ⇒ 即使不清理也「永远通过」。修法：用独立 world 让 `activeName` 就是被翻的那张，自动定位必须落回同一张卡
  - 变异③ 初版（只删判据处的 `current`）**无法制造故障**：`current` 限定在赋值侧（`onClick: (current && !flipped) ? ...`）与判据侧（`const flipped = current && ...`）各有一处，是纵深防御，删一处另一处仍守住。改为「两处同时移除」才是有判别力的变异
- **自建预设改用专用默认贴图**（本版仅样式调整；用户上传本地图片作插画留待后续版本）
  - 此前自建预设**完全不出图**，插画区只有主题色渐变底，与内置卡并排时明显缺一块主视觉
  - 新画 `assets/personas/custom-placeholder.svg`（512×512，与内置插画同规格）：**调色板 + 画笔**，与官方的鲸鱼形态区分 —— 鲸鱼 = 官方提供的人格，调色板 = 你自己配的，语义不依赖文字即可自解释
  - 宿主 `resolvePersonaArt` 对**非内置名**返回该固定贴图；内置名仍走按名查找（缺图回退鲸鱼占位）
  - 客户端去掉 `builtin &&` 条件 ⇒ 所有卡片都渲染插画；`onError` 兜底保留（路由不可用时退化为渐变底而非破图）
  - **安全不变量保持**：非内置名分支**不用 name 拼路径**（一律返回固定文件）⇒ 路径穿越从结构上不可能。端到端实测：`../../package.json` 与 URL 编码变体均返回 2448 字节的 SVG（贴图），而非 2563 字节的 package.json
  - 内置人设**不允许**覆盖插画（随包发布、升级自动更新；覆盖会引出「如何还原内置图」的新状态）
  - 新增 2 条断言：宿主对非内置名返回贴图且不拼路径 / 客户端对所有卡片都渲染 img（不得再被 builtin 条件限制）；判断力 **4/4**：客户端改回仅内置出图 / 宿主返回 null / 自建也走按名拼路径（穿越风险）/ 贴图文件被删 —— 全部被拦
  - verify-config 110 → 112 项
- **默认贴图换为用户提供的插画**（鲸鱼剪影）
  - `assets/personas/custom-placeholder.svg`（调色板）→ `custom-placeholder.webp`（鲸鱼剪影 + 装饰元素）
  - 转换规格对齐内置插画：**1024×1024 JPEG 93.7KB → 512×512 WebP 9.5KB**（内置插画均为 512×512 WebP，31–59KB）；裁掉白边留白（内容包围盒 x 84–950 / y 137–872）、居中成正方形、四周留 12% 呼吸
  - **MIME 改为按扩展名取**，不写死：贴图格式变过一次（svg → webp），写死会让浏览器把它当 octet-stream 下载而不是渲染
  - 旧调色板 SVG 已删除（目录里不留未引用文件）；孤儿白名单同步为 .webp
  - 断言同步：常量与文件路径改为 .webp、改用 **RIFF/WEBP 魔数**校验格式（不引入图像库解析）、新增「MIME 必须按扩展名取」断言
  - 判断力 **5/5**：客户端改回仅内置出图 / 宿主返回 null / 自建也走按名拼路径（穿越风险）/ **MIME 写死为 svg** / 贴图文件被删 —— 全部被拦
  - 端到端实测：自建预设 200 + image/webp + 9496B + RIFF/WEBP；穿越尝试仍返回贴图而非 package.json
- **修掉「/soul confirm 后底栏人设名不刷新」**（用户实测）
  - 现象：set_persona + /soul confirm 后宿主已正确写盘（核对配置文件无误），但底栏「个性化已启用 · 人设名」仍显示旧值
  - 根因是**结构性缺口**：三条刷新路径（setInterval / ocus / isibilitychange）**全部注册在 SoulSettings 组件内**。底栏是常驻组件（conversation.input.left），它的数据链路却挂在设置页的生命周期上 ⇒ 设置页没挂载时无人拉数据
  - 修法：轮询**上移到 pply()**（装配层，与页面无关，注册一次全生命周期有效）；事件监听同步上移
  - loadPersonas 的「拉取 + 写 store」逻辑**下沉到 controller**（装配层与设置页共用一份实现，避免两套写 store 的代码）；设置页保留薄包装，调用点不变
  - 设置页改为只同步**暂停标记**（controller.paused）：有未保存编辑时暂停刷新，卸载时必须复位 —— 否则底栏永久停摆（本次 bug 的镜像形态）
  - 消除重复请求：装配阶段原有的 controller.loadConfig() 与全局轮询的首次 refresh() 重复，已删（首次拉取并入轮询，C2 断言依然通过）
  - 全客户端 setInterval 收敛为**唯一一处**（不会出现底栏与设置页各自轮询 ⇒ 请求翻倍）
  - 新增 **C23**（5 个场景：定时器在装配层 / focus 监听 / visibilitychange 监听 / 暂停语义 / 卸载复位）；**测试台补齐 unmount() 能力** —— 垫片原先只在依赖变化时跑清理、卸载时从不执行，导致「卸载必须复位」这类契约根本无法触发
  - 判断力 **5/5**：全局轮询被删 / 不监听 focus / 不注册 interval / paused 守卫失效 / 卸载不复位 —— 全部被拦
  - verify-client 22 → 23 项
- **人设变更确认改为宿主原生审批面板**（用户需求：不再手敲 /soul confirm，而是弹出选项框）
  - 查证结论：宿主**已内置**完整审批能力 —— 宿主侧 `dsh-user-approval`（`ApprovalService`，dsh 主包直接依赖）、客户端 `dsh-client-ui-approval`（**已在 dsh-web-app 默认依赖清单里**，自己注册了 `approval/request` 的应答者）。事件 `approval/request` 在 `API_REMOTE_FORWARDED_EVENTS` 白名单里（`mode: waterfall`）
  - **因此本插件只作为 asker 发起请求，客户端无需改一行** —— 不注册 answerer，避免与宿主应答者形成 waterfall 竞争
  - 三态映射（`approvalOutcomeOf`）：`allowed-once` → 继续落盘；`rejected` → 不落盘并如实告知；`cancelled` / `unavailable` → 归为不可用走退化
  - **退化路径保留**：`exec.agent` 缺失（宿主客户端靠 agent 解析会话归属，拿不到会放弃应答）、宿主未装审批服务、纯 TUI 无应答者 ⇒ 退化为原有的 `/soul confirm` 文本流程。删掉它会让这些场景彻底无法确认
  - 不设超时（用户决定）：用户不点就一直等，与宿主其它审批一致 —— 加超时会产生「只是没来得及点就被自动拒绝」这种难以解释的行为
  - 关键实现点：`execute(args, exec)` 接住工具执行上下文（`dsh-tools` 的调用形态是 `tool.execute(exec.arguments, exec)`，`exec` 含 `agent` / `callId` / `signal`）；服务经 `ctx.get('approval')` 可选获取
  - 行为验证 **6/6**（隔离进程）：批准 ⇒ 落盘 / 拒绝 ⇒ 不落盘 / 无审批服务 ⇒ 退化 / 无 agent ⇒ 退化 / 审批抛异常 ⇒ 退化 / 确认模式关闭 ⇒ 不经审批直接落盘
  - 判断力 **6/6**：execute 不接 exec / agent 缺失时硬发请求 / **cancelled 被当作批准** / rejected 被误当作批准 / 去掉 catch 兜底 / 退化路径被删 —— 全部被拦
  - 其中③⑥ 首轮**漏网**（判断力只有 4/6），暴露断言过弱：只钉了三态映射的片段，未逐字校验整个函数（cancelled 若返回 allowed，撤回的请求会被应用）；只钉了 `pendingPersonaProposal` 赋值，未验证退化分支真实可达（改成 `if (false)` 能悄悄删掉它）。已改为切片逐字校验
  - verify-config 112 → 113 项
- **修掉审批服务的 ctx 取错问题**（~~实测发现：审批从未真正生效~~ —— 此表述已纠正，见下方「纠正一处错误技术记录」）
  - 根因：`requestToolApproval(ctx, ...)` 传的是 `registerTools` 的**根 ctx**，而 cordis 的服务按 fiber 作用域可见 —— 根 ctx 上 `get('approval')` 返回 undefined ⇒ 每次都走 `unavailable` 退化分支，功能「看起来没生效」
  - 权威参照：`dsh-tools` 自己的 `serviceAsk` 用**持有 tools 服务的 ctx** 取 `approval`
  - 修法：调用处改传 `toolsCtx`；服务解析改为多候选（`agent.ctx`（agent-scoped，审批本就该路由到该 agent 的会话）→ `toolsCtx` 兜底），任一命中即用。已查证 `Agent` 接口确有 `readonly ctx: Context`（`dsh-agent/lib/types/runtime-types.d.ts`）
  - 断言同步：改为钉「多候选解析 + 调用处必须传 toolsCtx」，而非字面 `ctx.get('approval')`
- **区分「审批通道被禁用」与「用户真的拒绝」**（用户反馈：策略已是 never，为何还要拒绝？）
  - 问题：宿主在 `effectivePolicy(session) === 'never'` 时**不问任何人**，直接返回 `'rejected'`（见 `dsh-user-approval` 的 `decide()`）。而 `'rejected'` 这个取值把两件完全不同的事混在一起：① 用户真的点了拒绝；② 审批通道被策略禁用、无人被询问。此前不区分，于是向用户报告了一件**从未发生的事**（提示「你在审批面板中拒绝了」，而用户根本没看到面板）
  - 修法：发起请求前先解析策略（复刻宿主 `effectivePolicy` 算法：`overrideOf(session) ?? config.policy ?? 'ask'`），判定为 `never` 时返回 `policy-disabled` 并走文本确认，同时追加一句准确说明（`toolApprovalDisabled`：「本次会话的审批通道已被禁用……这不代表你做了拒绝操作」）
  - **不直接应用变更**（即不把 `never` 当作「无需确认」）：`requireToolConfirmation` 是用户为本功能单独设的偏好，`never` 是会话级审批通道策略。用后者悄悄推翻前者，等于让一个通道开关替用户取消了他自己的功能选择。真要免确认，正确做法是关掉设置页里那个开关
  - 不可读策略时保守回落到 `ask`：失败方向是「多问一次」，而不是「静默改配置」
  - 行为验证 **5/5**：never ⇒ 文本确认 + 准确文案（且不白问一次）/ ask+真拒绝 ⇒ 措辞指向用户拒绝 / ask+允许 ⇒ 落盘 / 会话级覆盖优先于部署默认 / 读策略抛异常 ⇒ 保守按 ask
  - 判断力 **5/5**：去掉预判 / 丢掉会话级覆盖 / 读失败回落到 never / 不追加说明 / 真拒绝被误报成成功 —— 全部被拦
- **纠正一处错误技术记录**：上一笔提交（`ab01958`）把「root ctx 取不到 approval」写成**实测结论**，实为**推断**。已查明真因是 **DSH 未重启**（进程启动 16:14:53，早于修复写入 16:48:40；宿主侧插件代码只在启动时加载一次），期间还叠加了会话策略 `never`。`ctx` 那处修改**本身仍然正确**（`dsh-tools` 的权威写法就是用持有 tools 的 ctx 取审批服务），只是并非「审批未生效」的原因。`RELEASE_NOTES.md` 中该表述已标注纠正
- **「人设变更需确认」的 ⓘ 提示重写**（用户需求：提示要反映新行为，并声明完全权限下建议关闭）
  - 旧文案已过时：主路径早已从「/soul confirm 文本确认」改为**宿主审批面板**（composer takeover，Enter 允许 / Esc 拒绝），但提示仍只说文本流程，用户不知道会弹面板
  - 新文案三条同时讲清：① 主路径是审批面板；② 通道不可用（策略 `never`）时退化为待确认提议、需 `/soul confirm`；③ **完全权限（策略 never）下面板不会出现、每次都要手输命令，建议关闭本开关**
  - 长度有上限：tooltip 是向上弹出的浮层，过长会盖住大半个分组。实测（chrome 渲染）中文 124 字 ≈ 108px 高、英文 343 字符 ≈ 162px，均在可接受范围；断言按字符数设了粗粒度上限（中 ≤160 字 / 英 ≤400 字符），防止后续追加内容把浮层撑到不可用
  - 断言 1 条（同时校验中英双语、面板路径、never 退化、关闭建议、长度上限）；判断力 **5/5**：退回旧文案 / 去掉关闭建议 / 去掉 never 说明 / 英文缺建议 / 中文改得过长 —— 全部被拦
  - verify-config 113 → 114 项
- **【安全】`/api/soul/config/reset` 缺 HTTP 方法校验**（发版前安全收口实测发现）
  - 缺陷：该路由**完全没有**方法校验，任何 HTTP 方法都会执行破坏性写入（重置配置、必要时丢弃并备份损坏文件）
  - 风险不低的原因：**GET 不是「安全」的同义词** —— 浏览器预取、爬虫、`<img src>`、链接预览、代理探测都会发 GET。缺校验意味着**一个 GET 就能重置用户配置**
  - 同期的 `personas/save`、`personas/use`、`personas/delete` 都有 405 校验，此处属遗漏
  - 修法：前置 `if (req.method !== 'POST') return 405`
  - 断言按**两类端点分别判定**（新写 1 条覆盖全部写端点，而非只钉 reset 这一处）：
    ① 读写复用端点（`/api/soul/config`）要求显式 `GET` / `POST` 分支；
    ② 纯写端点（`reset` / `save` / `use` / `delete`）要求前置拦截非 POST 且回 405
    —— 前者用后者的尺子会误报（实测踩过：`/api/soul/config` 是读写复用，用「必须有前置 405」判定会误报）
  - 判断力 **4/4**：reset 去掉校验 / personas/delete 去掉校验 / config 去掉 GET 分支 / 405 改成 200 —— 全部被拦
  - verify-config 114 → 115 项
- **发版前安全与边界收口实测**（本轮共 27 项，结论记录如下）
  - **安全边界 18/18**：4 组路径穿越变体（`../`、URL 编码、`....//`、`%2e%2e`）均返回贴图而非 `package.json`；`__proto__` 注入被忽略；超长 / 非法枚举 / 畸形 JSON 均 400 不 500；内置预设不可删不可覆盖；`__proto__` / `constructor` / `prototype` 保留名被拒
  - **并发与健壮性 8/9**：10 个并发写全部成功且配置仍是合法 JSON（写队列串行化正确）；配置文件损坏时降级为默认值 + 附带 `configError`（不 500、不静默）；重置能从损坏态恢复；无配置文件时用出厂默认且**不报** `configError`（缺失 ≠ 损坏）
  - **旧版本迁移**：`style: friendly` + `tone` 迁移为新枚举、`emoji: 'yes'` 回退默认、自建预设里残留的「关于你」被剥离、废弃字段（`tone`/`presets`）被丢弃 —— 均验证通过
  - **打包产物**：32 文件 / 581 KB，插画（7 内置 + 1 自建贴图）、图标、双语文案齐备；无 `.git` / `node_modules` / `.env` 等敏感物泄漏
  - **一处低风险观察（未改）**：磁盘上的未知字段会被 `migrateConfig` 的 `{...DEFAULT_CONFIG, ...raw}` 原样透传到响应。经查证 `compilePrompt` **只逐字段白名单读取**，未知字段不进入提示词、不影响行为，故不构成缺陷。刻意不改的理由：过滤会破坏前向兼容（未来版本新增字段时旧客户端读不到）
  - **一处测试假设修正（记录以免重蹈）**：`loadConfig()` 有内存缓存（`if (configCache) return configCache`，仅写入时更新），直改磁盘后调 `GET /config` 读到的仍是缓存值 ⇒ 边界测试必须**每场景独立进程**；另 `migrateConfig` 是**纯函数**，只在读入内存时规范化、**不回写磁盘**（刻意不擅改用户文件），故断言对象必须是**响应里的 config** 而非磁盘原文
**校验**

- `verify-config` 91 → **115 项**（新增「展示名走 locale/*.json」结构层、「展示名能被宿主真实解析」行为层、「轮询在不可见时暂停」、「CSS token 存在性」、「样式对齐宿主栏目」、「人设行操作按钮规格对齐宿主列表按钮」六条；「set_persona 输出 schema」那条同时升级为**注册 + 结果渲染**两段，并用真实定义对象整体求值取代原先的文本切片）。样式相关的 13 组变异全部被拦（不存在 token / 加回 padding / 分组退回旧边框 / 标题字重 600 / 标签字号 13px / 硬编码颜色 / 按钮高度 36px / 圆角 6px / 列表 gap 归零 / 行改回共用容器 / 加回行底色 / 删 render / 轮询去掉守卫）；本次另加「审批策略预判」契约（策略算法逐字校验 + policy-disabled 文案），5 组变异全部被拦

### v0.7.1（2026-10-10）

**新增**

- 内置人设新增**「自驱型协作者」**（第 7 个）：`professional` 风格 + 更多标题和列表 + 更多表情符号，行为准则是「先自己动手再开口」
  - 五条行为规则：**先自己动手**（能读的先读、能查的先查、能验证的先验证掉，确实卡住才提问，并把已排查范围与还缺什么一并说明）；**给出明确判断**（比较方案时指明推荐哪条及理由，不以「都可以，看需求」收尾）；**以可核实的依据为准**（事实 / 接口 / 参数 / 版本先查证再断言，查不到就说不确定，不用听起来合理的说法填空）；**实质优先于形式**（不复述用户已说清的需求、不用开场垫话，礼貌体现在措辞而非铺垫）；**区分两类动作**（读文件 / 检索 / 整理这类内部动作大胆做，发消息 / 提交 / 发布 / 删除这类对外动作先确认）
  - 与既有内置一致：不声明 `nickname` / `occupation` / `bio`（「关于你」是使用者本人的资料，预设不该动）与 `language`（内置是给任何语言用户共用的通用人格，写死会让英文用户应用一次就被切回中文），因此应用它不会动你的昵称职业
  - 名字与被参照的原始预设不同：原名含个人昵称，不适合作内置名，故按行为核心重新命名。原有的自建预设不受影响，两者可并存（★ 各自独立判定）

**变更**

- **人设预设从此只管 Agent 的人格，不再包含「关于你」**：「关于你」（昵称 / 职业 / 介绍）是使用者本人的身份信息，预设是 Agent 的回复风格存档 —— 两者是两码事，切换预设应该只换说话方式，不该动你的资料。此前**自建**预设是「保存那一刻的完整配置快照」，应用时会把这三个字段一并写回（内置预设一直省略它们），同一件事因此有两套语义
  - 改法是把边界下沉到字段白名单：三个身份字段移出 `PERSONA_FIELDS`，另立 `PROFILE_FIELDS` 标明它们的位置，于是**保存快照**（`personaSnapshotOf`）、**应用取键**（`pickPersonaValues`）、**★ 匹配判据**（`declaredPersonaKeys`）、**磁盘归一化**（`normalizePersonas`）四条路径同时排除它们 ⇒ 内置与自建**行为一致**，「切换预设换掉了我的昵称」从结构上不再可能发生
  - 输出语言（`language`）**留在预设范围内**：它决定 Agent 用什么语言作答，属于人格的一部分；自建预设会保存并在应用时还原它。内置预设作为通用人格仍然刻意不声明它
  - **已有自建预设无需处理**：早期版本存下的完整快照会在**读取时**自动剥离三个身份字段（无损 —— 这些值同时存在于活动配置里，预设只是保存那一刻的拷贝），清理结果随下一次写入落盘。可见变化有二：预设行摘要不再显示昵称（它已不属于预设），★ 判定也不再受昵称影响

**修复**

- **关闭宿主提示词插值**（`interpolate: false`）：在「自定义指令」里写出任意一对完整的 `{{…}}`（`{{cwd}}`、`{{ item.name }}`、甚至 `{{}}`）都会让 system prompt 装配抛错——而该抛错位于 `agent.step()` 开头且没有 try/catch，结果不是「忽略那段文字」，而是**该会话的每一轮都失败**（实测 8 例中 6 例抛错，连 `{{cwd}}` 这种规范写法也抛，因为它同样没注册）。插件不使用任何宿主提示词变量，关闭插值的代价为 0；顺带让「预览所见」与「实际生效的文本」逐字符一致
- **配置写入原子化**：先写同目录 `.tmp` 再 `rename` 覆盖，写盘中途中断不再留下截断的 JSON。原有写队列解决的是并发丢更新，与原子性互补、两者都保留
- **配置损坏不再被静默覆盖**：读取区分「文件不存在」（回退默认，属正常首启路径）与「文件损坏」（保留原文件、另存 `.corrupt` 备份、**拒绝在此基础上写入**）。此前 `catch {}` 会静默回退成默认值，并在下一次保存时以默认值为底写回磁盘 ⇒ 自定义指令与人设库**永久丢失且全程没有任何提示**。读取失败时刻意不写缓存，用户修好文件后**不必重启 DSH** 即自动恢复；设置页会直接显示原因与备份位置
- 新增 `lib/store.mjs` 收口全部配置读写（校验/迁移留在 `lib/config.mjs`，`index.mjs` 只管缓存与状态，且不再直接 import `node:fs/promises`）
- **撤回本版草稿中的「移除会话注入」**（同版本内回退，未发布）：删除 `injectPromptToAllAgents` 与 `lib/injection.mjs` 的理由是「宿主每一步都重新装配提示词、对函数式 section 文本不做缓存、文本变化时自行提交新的 system 快照 ⇒ 注入冗余」。实测该推理**不足以支撑删除** —— 只保留 section 通道时，**会话进行中修改人设不会在下一轮生效**。现已恢复注入、`lib/injection.mjs` 与 `@deepseek-ai/dsh-llm` 依赖：配置变化继续走**双通道**（section 每次装配重算 + 保存后主动推送活动会话），两者互为兜底
- **配置损坏时不再是死路**：此前损坏状态下「保存 / 重置 / 斜杠命令 / 工具 / 服务」五条写路径**全部被拒**，用户除手删文件外没有出路。现在「重置」被定义为**刻意丢弃**——先把损坏文件移开（备份为 `.corrupt`）再写入默认值，并且**重置本身也走同一个写入路径**（不另写一份「读—改—写」）。这与上一条「损坏配置绝不被**静默**覆盖」不冲突：静默覆盖仍被禁止，而重置是用户显式发起的动作
- **重置失败不再被报成成功**：客户端此前无条件弹「已重置为默认值」，即使请求失败（配置损坏时那条必然失败的重置正落在这里）。现在失败给失败提示，成功且丢弃过损坏文件时告知「已备份」
- **人设预设行的「使用」按钮跨行不同列**：操作区是内容驱动的 flex，内置行只有「使用」、自建行是「使用 + 删除」，后者被判据挤左约 34px（一个删除按钮 + 间距），于是点「使用」时鼠标要跟着行类型左右挪。改用**名称 / 摘要 / 操作三列网格**并把操作区做成**两条等宽固定轨道**（`1fr 1fr`，整体固定宽度）：内置行第 2 轨放 `span` 空占位（不是按钮——否则是个点了没反应的控件），两类行的「使用」「删除」因此**跨行严格同列**（无头浏览器实测四行「使用」左边缘均为 647px、偏差 0；zh / en 两种文案下都成立，操作区无溢出）
- **「内置」徽标从操作区移到名称旁**：徽标说明「这个预设从哪来」，属于名称的修饰而非操作；留在操作区会占掉「使用」的列位（这正是上一处错位的直接原因）。同时弱化其样式（去掉边框、字号 11→10、改用更淡的 `label-tertiary`），并给**内置行加底色**（`interactive-bg-hover`）+ 去掉分隔虚线，来源一眼可辨且不再与按钮抢注意力
- **`set_persona` 工具在真实 DSH 下必然注册失败**（本版实测发现，此前 196 项断言全绿却无人察觉）：输出 schema 用了**根级 `required: ['ok']`**，而 DSH 的 value-schema DSL 不支持根级 required（作者错误 `schema.required is not supported by the value schema DSL`）；去掉后又撞上第二个错误 `schema.properties.changes.additionalProperties must be explicitly true or false`。`defineTool` 抛错被 `.catch()` 降级成一条 warn ⇒ 插件其余功能正常（9 条路由 + `/soul` 命令健在）、**只有工具静默缺失**，用户侧表现为「Agent 改不了人设」。现改为属性级 `ok: { type: 'boolean', required: true }` + `changes.additionalProperties: false`（用真实 `dsh-tools@0.2.1-alpha.1` 实测注册成功、`execute` 正常返回）。根因是校验缺口：全链只造了 `dsh-llm` 桩，**从未用真实 DSL 校验过 schema**
- **送达诊断读错文案表，导致诊断失效并可直接打挂接口**：`deliveryProblemText` 用 `promptTextOf(config)`（→ `PROMPT_TEXT`）取 `deliveryNoAgentsService` / `deliveryInjectFailed`，而这两个键**只定义在 `COMMAND_MESSAGES`** 里。实测两种后果：① `agents` 服务不可用时函数返回 `undefined`，`deliveryWarning` 字段在 JSON 序列化时**整个消失**（响应只剩 `ok/config/changed`），客户端 `typeof payload.deliveryWarning === 'string'` 永远为假 ⇒ 后台故障对用户完全不可见，`/soul show` 的送达行还会静默回落成「已注入 0/0」**谎报正常**；② 注入抛错时走 `T.deliveryInjectFailed(...)` 分支直接抛 `TypeError` ⇒ **配置已落盘却返回 HTTP 500**。现改用 `commandMessages(config)`，两个分支实测均恢复（200 + 完整文案 / 200 + 「向活动会话注入失败：…」）
- **应用预设时非法取值被静默丢弃、却报成功**：两条应用路径都写 `const { patch } = sanitizeConfig(...)` 只取 patch、把 `errors` 丢掉。而 `normalizePersonas` 只按**字段名**过滤、不校验取值，所以磁盘上的历史值会自然触发——实测一份 `{style:'friendly', emoji:'lots', customInstructions:'…'}` 的旧预设：`style` 与 `emoji` 被静默丢弃、只有 `customInstructions` 写回，接口却返回 `ok: true`、`/soul use` 报「已应用」。注意 `'friendly'` 曾是 v0.1.x 的**合法** style 名，而 `LEGACY_STYLE_MAP` 只迁移活动配置、**不迁移预设库内的值**，所以这是真实升级路径而非人为构造。现在两条路径收口到同一个 `applyPersonaEntry`，合法部分照常应用、被丢弃的字段经 `invalid` 如实回报（HTTP 带 `invalid` 数组；一个合法字段都没有时返回 400 / `kind:'error'`，不再假装成功）
- **输入框快捷开关保存失败完全静默**：`toggle` 调 `saveConfig` 后不检查返回值，而失败时 `enabled` 取自 store 且未变 ⇒ 按钮外观、文案、`title` 全部不变，用户视角就是「点了没反应」（错误只写进 store.error，而设置页通常没打开）。现在失败时置 `data-failed`、小圆点转红并停止脉冲、把失败原因同时写进 `title` 与 `aria-label`（读屏用户同样拿得到）
- **预设列表拉取失败会永远停在「加载中...」**：`loadPersonas` 是空 `catch`，失败后 `personas` 恒为 `null`，而界面以 `null` 判定加载态 ⇒ 与「真的还没有预设」无从区分，且无任何失败信息。现在失败写入 `personasError` 并在分组内优先渲染失败原因（折叠态摘要也显示「加载失败」），拉取成功时自动清除
- **本版第二轮审计（P2）修复的细节问题**：
  - `/soul list` 恒显示 `昵称=-`：v0.7.1 起预设不含「关于你」、`normalizePersonas` 也会剥离 `nickname`，所以该列是一列**永远没有信息的死数据**。改为报告「覆盖 N 项」（`declaredPersonaKeys` 的长度，与客户端摘要同源）
  - `POST /api/soul/prompt` 返回 200：该端点此前是**唯一**不判 `req.method` 的（同文件其余 7 处都有 405 分支；宿主只做路径匹配，method 判定确实是 handler 的责任）。现已补 405
  - `/soul set` 的三处不一致：① 键名大小写敏感（`/soul set STYLE=humorous` 报「未知配置项」，而同命令的子命令关键字本就忽略大小写）——现按「小写 → 真实字段名」查表还原（**不是**简单 `toLowerCase`，那会把 `headingLists` 压成 `headinglists` 反而匹配不上白名单）；② 枚举值不 trim（`style= humorous` 被拒，而 `bio= 张三` 能成功）——现与文本字段同规则 trim；③ 布尔解析失败只说「必须为 true / false」，`enabled=true extra` 这类多打一个词的情形看不出实际收到了什么——现回显实际值
  - 客户端 dirty 判据与服务端 trim 不一致：服务端对字符串字段一律 trim，客户端却按原始串比较 ⇒「敲了个首尾空格 → 保存按钮亮了 → 保存成功却提示『配置无变化』」。现 `dirty` 与 `promptDirty` 共用同一个 trim 判据（不另造一份 `TEXT_FIELDS` 复刻表，避免多一处需手工同步的常量）
  - 输入框光轨示例的标签用了没有 `htmlFor` 的 `<label>`（指向空的标签）：改为同风格的 `div.soul-field-label`
  - 客户端每个字符串字段的 trim 语义、`{fields}` 列表分隔符：英文界面此前硬编码中文顿号，渲染成 `...excluded from this preview: style、tables`（中英混排）。现在分隔符进词典（中文 `、` / 英文 `, `）
  - 导航图标替换后**卸载不还原**：`replaceChildren` 覆盖了宿主齿轮的几何，清理时只摘 marker 属性 ⇒ 禁用插件 / HMR 之后导航栏仍显示插件图标。现在改画前记下原始子节点、卸载时还原；`MutationObserver` 的 100ms 防抖补了**最长等待**（会话流式输出时 body 每帧都在变，纯防抖会让图标替换永远排不到）
  - 提示气泡只有 `:hover` 可达、toast 无 live region：前者补 `tabIndex` 与 `:focus-visible`（键盘 / 读屏用户也能拿到字段说明），后者补 `role="status"/"alert"` 与 `aria-live`
  - 清理死代码：[`prompt.view` / `prompt.hide`] 两个零引用文案键、store 里只写不读的 `loading` 与 `lastChanged`、光轨示例组件里永不执行的 `enabled` 关闭分支；设置页每 2s 轮询造成的**无谓整页重渲染**（`store.update` 现在值全等时不换引用也不通知，键集取并集比较以免漏掉「删键」而静默不更新）
  - 应用预设时清掉上一轮的失败提示：该端点不返回 `deliveryWarning`，此前一旦上一轮保存失败过，切预设成功后红色错误条会一直挂着
  - 校验脚本自身两处脆弱点：`verify-trail` 的切片终点锚在**注释文案**上（仅改写那句注释就假失败），改用代码锚点；`verify-config` 对源码的正/负断言全部改为先 `stripComments()`（长度保持不变的注释剥离），并按括号配平取 `section(...)` 选项对象取代「anchor 起 1500 字符」的固定窗口
  - `set_persona` 的**模型侧描述**改为中英并列：工具 schema 只在 `apply` 时注册一次，而宿主 registry 对同名重注册会抛 `tool "set_persona" is already registered`（实测 `dsh-tools` 源码确认）⇒ 语言切换时**无法**原地换描述，并列两种语言才能覆盖 zh / en 两种界面
  - `/soul show` 的两处不一致：预设数量此前只数磁盘上的用户预设（显示 2），而 `/soul list` 与 Web UI 用合并视图（显示 9）—— 现统一为合并视图；待确认提议此前只有一个静态提示，`proposedAt` **只写不读**，而提议是内存态、无 TTL，陈旧提议会一直挂着而无法判断新鲜度 —— 现把提出时间显示出来
  - 新增 **C15 / C17** 两条客户端行为断言：只改首尾空格不得被判成「未保存的更改」（与服务端 trim 判据一致，防空过含「真有改动必须提示」的反例，C15）；应用预设成功后不得残留上一轮的失败提示（C17）
  - **修掉一处测试替身与真实协议的漂移**（C16）：`verify-client` 的 `GET /api/soul/personas` 桩此前返回 `{ personas: [], activePersona: null }`，而宿主真实返回 `{ personas: <对象 map>, activeName: <名字|null> }`（`index.mjs` 的 `personaLibrary`）—— 字段名错、类型也错。后果是**人设行渲染与 ★ 生效标记在行为层从未被执行过**（把桩改成真实形状后整套 C 系列仍全绿，实测），而 v0.7.1 的主打功能之一只剩源文本断言看护。现已改为真实形状并补 C16：断言 `activeName` 真的写进 `store.activePersona`、两行预设都渲染、生效行带 `★` 而非生效行不带（两个方向都断言，故「恒加 ★」与「恒不加 ★」都能被拦）、内置行带「内置」标记且不渲染删除按钮。判断力用 3 组变异验证（字段名写错 / ★ 恒不加 / ★ 恒加），3/3 被拦。附带确认：`mergePersonas` **恒含 7 个内置人设**（实测 `mergePersonas(null)` 也有 7 个键），所以真实环境下 `personas.empty`（「暂无人设预设」）分支**不可达** —— 桩此前恰好只喂了那个不可达的输入
  - 提示条补上 `prefers-reduced-motion`：`toast` 用内联 `fadeInOut`，此前被漏掉，开了「减少动态效果」的用户每次保存/失败仍会看到平移缩放淡出。已并入既有 media 规则（`.soul-toast{animation:none!important}`）。**实测确认层叠行为**（真实 Chrome + `--force-prefers-reduced-motion`）：内联 `animation` 属 author 普通声明，样式表的普通声明同样能覆盖它，`!important` 并非必需、但更稳。新增断言要求 reduced-motion 规则同时覆盖光轨层 / 快捷开关圆点 / 提示条三处，判断力用「删掉 toast 那条」验证（被拦）

**优化**

- 修正 `registerSection` 中一处与事实不符的注释：原先称「重新注册会触发 `system-prompt/change`，让 DSH 丢弃已缓存的快照」——该事件当前**没有任何消费者**（只在 `dsh-system-prompt` 内部 emit）
- **「改了配置不生效」从此有据可查**（此前是全静默：`agents` 服务不可用时直接 `return`，注入异常被 `catch {}` 吞掉，日志全被注释）：
  - `injectPromptToAllAgents` 如实统计送达结果（活动会话数 / 成功数 / 失败数 / 原因），并经 `ctx.logger` 告警（同一原因只告一次，恢复正常后允许再次告警）
  - 新增 `GET /api/soul/status`：报告两条通道的状态、配置路径与版本号
  - `/soul show` 末尾新增「送达」一行（是否有活动会话、注入是否成功）
  - 设置页新增 `deliveryWarning` 提示：与 `configError`（配置读不出来）分开上报——两者症状相同、处理方式不同
  - `soulConfig` 服务的 `updateConfig` 现在也走「变更即送达」，与服务之外的另外三条写路径保持一致
- **`npm run verify` 不再「假绿」**：`verify-trail` / `verify-nav-icon` 在无浏览器时、`verify-e2e` / `verify:host` / `verify:compat` 在定位不到 DSH 时会**跳过并返回 0**，此前混在 `&&` 链里看起来一片绿，实际有几十项断言根本没跑。现在跳过会显式说明「有 N 项断言未执行」，并新增 `npm run verify:strict`（跳过即失败）。各脚本还会在跑完时校验实际断言数与声明值一致，避免数字变成谎话
- **`verify:host` 不再由当前工作目录决定验证哪一份宿主**：锚点原先以 `process.cwd()` 开头，而模块解析会从锚点向上找 `node_modules` ⇒ 换个目录跑就可能命中另一份 DSH 安装（本机同时存在 0.2.1-alpha.1 与用户主目录 pnpm store 里的 0.1.0-rc.8，后者不支持 `interpolate`）。现在优先「装了本插件的 profile」，并在解析到多份副本时逐一打印、说明本次验证的是哪一份；`--dsh` 指向非 DSH 目录时直接报错，不再悄悄退回自动定位

- **卡背整面点击返回正面**（与正面「整面点击翻到背面」对称，用户需求）
  - **必须排除「拖选文字」**：卡背有 339 字可滚动全文，用户很可能拖选复制；拖选结束会触发一次 click，不判断就等于「一选就跳回正面」。判据用 `getSelection()` 是否折叠且非空 —— 有选区说明是选择操作，不返回
  - 「删除」按钮 `stopPropagation`：卡背整面点击=返回，不挡住的话「确认删除」会被返回动作打断（翻回正面、看不到确认态）
  - `cursor` 区分：卡背整体 `pointer`（可点返回），全文块 `text`（可选中）
  - 顺带修掉两处**断言自身的脆弱点**（都被这次改动暴露）：① `backBlock` 切片原用固定 2600 字符，内容一长（加了删除按钮）就截断 ⇒ 断言「看不到」新元素而误报，改到稳定锚点（`const cards = []`）为界；② 正则在 PowerShel 替换中被写成双反斜杠 ⇒ 匹配字面反斜杠而非括号
  - C20 扩到 7 个子场景（含拖选保护与无选区正常返回）；判断力 **4/4**：去掉整面 onClick / 去掉拖选保护 / 删除不 stopPropagation / 永不返回 —— 全部被拦
- **内置预设统一声明全 6 个人格维度**（language 豁免）—— 修掉「同一动作结果随预设而变」
  - 问题：声明列表**同时驱动应用与匹配**，两者需求相反 —— 应用时「只写声明字段」希望少声明不越权，匹配时「只比声明字段」希望全声明才严格。早期为不越权只声明要改的维度，导致匹配退化成宽松比较：**改一个预设未声明的特质后 ★ 仍挂着**，而且结果随预设而变（改 emoji 在「极简主义者」上丢 ★、在「苏格拉底式提问者」上不丢）⇒ 用户无法形成稳定预期
  - 现统一全量声明，语义单一可预期：**改任何特质 ⇒ 不再属于该预设**
  - 代价（刻意接受）：应用预设会把 6 个人格维度整体复位到预设值，而不是「只改一部分、其余保留我手动的」—— 与「用预设就是不想逐项自己配」的心智模型一致
  - language 仍豁免（全量声明唯一例外）：内置是跨语言共用的通用人格，写死 zh 会让英文用户应用一次就被切回中文
  - 新增断言「每个内置预设都声明全 6 维」：逐人设校验 6 维齐全 + language 必须缺席 + **行为闭环**（应用后匹配自己、改任一特质维度都失去匹配、改 language 不移除匹配）
- **配置偏离任何预设时给「存为新预设」出口**（承接「改任何特质都丢 ★」）
  - 全量声明后 ctiveName=null 成为常见状态，它诚实但**没有出路** —— 用户刚调出来的配置无处安放
  - 预设分组底部出现：一句说明「当前配置与任何预设都不一致。」+ 描边式「存为新预设」按钮，**复用已有命名弹层**（不另造保存流程）
  - 判据 ctivePersona === null && personaNames !== null && !personasError：加载中/加载失败不算偏离；全部默认值命中的是「默认」预设，也不会走到这里
  - 新增断言钉住判据、提示块、文案键（双语）、复用命名弹层、以及「弱化底 + 描边式次要按钮」的样式规格
- **移除输入框上方的人设标签（dock 行）**（用户判断：「显示没有太大意义」）
  - 移除组件 SoulPersonaChip、槽位注册、全部 chip CSS、6 条 chip.* 文案键；人设切换与状态展示统一收敛到设置页卡片区
  - 判断力 **5/5**：去掉某维声明 / 内置声明 language / 去掉偏离提示 / 出口按钮不复用弹层 / 偏离判据缺「列表已就绪」守卫 —— 全部被拦
  - verify-config 107 → 108 项
- **移除「默认」预设**（用户判断：人设卡片里的默认人设可以删除了）
  - 上一版把出厂配置包装成列表首位的「默认」预设，本意是给「无匹配」状态一个落点。但配合「改任何特质都丢 ★」之后，落点由**偏离出口**（存为新预设）承担即可，多一个「默认」反而是噪音
  - 数据层清理：删 `DEFAULT_PERSONA` 定义与 `personaEntry` 辅助、`builtinPersonaNames` 不再前置、`isBuiltinPersona` 去掉特判、`mergePersonas`/`resolvePersona` 改回直取 `BUILTIN_PERSONAS`
  - 副作用（正面）：**「默认」不再是保留名**，用户现在可以自己创建名为「默认」的预设（端到端实测保存返回 200）
  - 客户端清掉徽标分支与 `personas.default` 文案键；出厂 `activeName` 回到 `null`（诚实：没有任何预设被应用）
- **底栏开关始终展示当前人设**（用户需求：未匹配时显示「自定义」）
  - 此前只有匹配到预设才缀名字，手改过特质后留空 —— 等于「我现在用的是什么」没答案；「未匹配预设」那种说法又听着像报错
  - 现在：匹配到预设显示预设名，未匹配显示**「自定义」**；关闭个性化时不显示（人设此刻不生效，挂名字会误导）
  - 新增 **C21** 行为断言覆盖三种状态（匹配/未匹配/关闭）
  - 判断力 **4/4**：「默认」回到列表 / 底栏留空 / 关闭时仍显示人名 / 人名不限宽 —— 全部被拦
  - verify-config 108 → 109、verify-client 20 → 21
- **修掉 hover 提示被手风琴裁掉顶部**（用户实测：Agent 工具下「人设变更需确认」右侧的提示被上方遮住一部分）
  - 根因：`.soul-accordion{overflow:hidden}`（本为把触发器的方形 hover 背景裁进圆角）。而该分组里提示是**第一个元素**，上方只有 14px 内边距，提示高 72px ⇒ 必然越界被裁
  - 实测数据（真实 Chrome，几何测量）：**旧实现裁掉 19px，修复后 0px**；触发器顶圆角 19.5px（= 20px 圆角 − 0.5px 边框）、展开态底角 0
  - 修法：容器不再裁剪，改为给触发器补顶圆角（视觉等价、不裁剪）；收起态只有一个触发器 ⇒ 四角都圆
  - 新增断言「手风琴不得裁剪向上弹出的提示」：**这是本项目第一条几何契约断言** —— 有没有 `overflow:hidden` 不等于会不会被裁（取决于提示高度、上方留白、祖先链），字符串检查钉不住，故按「禁止裁剪 + 必须有圆角补偿」三条一起钉
  - 判断力 **4/4**：`overflow:hidden` 加回容器 / 触发器不补圆角 / 收起态圆角规则被删 / hint 自身加 overflow —— 全部被拦
  - verify-config 109 → 110 项
- **翻页会复位翻面态**（用户实测：翻开 A 卡背面 → 切到 B → 切回 A，A 仍以背面出现）
  - 根因：`flippedName` 记住「哪张卡被翻开过」，而 `go()` 只改索引、不清它 ⇒ 切回来时 `current && flippedName === name` 又成立，于是「记得」上次的面
  - 语义判断：翻面是「看这张卡背面」的**临时阅读动作**，翻页是「换一张看」—— 注意力已重置。记住它会让用户以为这张卡「默认就是背面」
  - 两处换卡入口都复位：`go()`（翻页按钮/圆点/侧边卡）与**展开自动定位**（折叠后重新展开会定位回 activePersona，若不清就会带出旧背面）
  - **刻意不在「折叠」那一刻清**：折叠期间 body 不渲染、翻面态在 UI 上不可观测，清与不清行为等价（判断力验证证实）—— 职责收敛到可观测的「自动定位」一处，避免两处重复同一件事
  - 新增 **C22**（5 个场景，含圆点导航这条独立路径与折叠→展开）；verify-client 21 → 22 项
  - 判断力 **4/4 有效变异被拦**：`go()` 不复位（原 bug）/ 自动定位不复位 / 两处 `current` 限定同时移除 / 翻页后把状态写回旧卡
- **两处测试自省（判断力验证逼出来的）**
  - 场景⑤ 初版**没有判别力**：它翻的是第 1 张、而自动定位回到第 0 张，两卡不同 ⇒ `flippedName` 天然不匹配 ⇒ 即使不清理也「永远通过」。修法：用独立 world 让 `activeName` 就是被翻的那张，自动定位必须落回同一张卡
  - 变异③ 初版（只删判据处的 `current`）**无法制造故障**：`current` 限定在赋值侧（`onClick: (current && !flipped) ? ...`）与判据侧（`const flipped = current && ...`）各有一处，是纵深防御，删一处另一处仍守住。改为「两处同时移除」才是有判别力的变异
- **自建预设改用专用默认贴图**（本版仅样式调整；用户上传本地图片作插画留待后续版本）
  - 此前自建预设**完全不出图**，插画区只有主题色渐变底，与内置卡并排时明显缺一块主视觉
  - 新画 `assets/personas/custom-placeholder.svg`（512×512，与内置插画同规格）：**调色板 + 画笔**，与官方的鲸鱼形态区分 —— 鲸鱼 = 官方提供的人格，调色板 = 你自己配的，语义不依赖文字即可自解释
  - 宿主 `resolvePersonaArt` 对**非内置名**返回该固定贴图；内置名仍走按名查找（缺图回退鲸鱼占位）
  - 客户端去掉 `builtin &&` 条件 ⇒ 所有卡片都渲染插画；`onError` 兜底保留（路由不可用时退化为渐变底而非破图）
  - **安全不变量保持**：非内置名分支**不用 name 拼路径**（一律返回固定文件）⇒ 路径穿越从结构上不可能。端到端实测：`../../package.json` 与 URL 编码变体均返回 2448 字节的 SVG（贴图），而非 2563 字节的 package.json
  - 内置人设**不允许**覆盖插画（随包发布、升级自动更新；覆盖会引出「如何还原内置图」的新状态）
  - 新增 2 条断言：宿主对非内置名返回贴图且不拼路径 / 客户端对所有卡片都渲染 img（不得再被 builtin 条件限制）；判断力 **4/4**：客户端改回仅内置出图 / 宿主返回 null / 自建也走按名拼路径（穿越风险）/ 贴图文件被删 —— 全部被拦
  - verify-config 110 → 112 项
- **默认贴图换为用户提供的插画**（鲸鱼剪影）
  - `assets/personas/custom-placeholder.svg`（调色板）→ `custom-placeholder.webp`（鲸鱼剪影 + 装饰元素）
  - 转换规格对齐内置插画：**1024×1024 JPEG 93.7KB → 512×512 WebP 9.5KB**（内置插画均为 512×512 WebP，31–59KB）；裁掉白边留白（内容包围盒 x 84–950 / y 137–872）、居中成正方形、四周留 12% 呼吸
  - **MIME 改为按扩展名取**，不写死：贴图格式变过一次（svg → webp），写死会让浏览器把它当 octet-stream 下载而不是渲染
  - 旧调色板 SVG 已删除（目录里不留未引用文件）；孤儿白名单同步为 .webp
  - 断言同步：常量与文件路径改为 .webp、改用 **RIFF/WEBP 魔数**校验格式（不引入图像库解析）、新增「MIME 必须按扩展名取」断言
  - 判断力 **5/5**：客户端改回仅内置出图 / 宿主返回 null / 自建也走按名拼路径（穿越风险）/ **MIME 写死为 svg** / 贴图文件被删 —— 全部被拦
  - 端到端实测：自建预设 200 + image/webp + 9496B + RIFF/WEBP；穿越尝试仍返回贴图而非 package.json
- **修掉「/soul confirm 后底栏人设名不刷新」**（用户实测）
  - 现象：set_persona + /soul confirm 后宿主已正确写盘（核对配置文件无误），但底栏「个性化已启用 · 人设名」仍显示旧值
  - 根因是**结构性缺口**：三条刷新路径（setInterval / ocus / isibilitychange）**全部注册在 SoulSettings 组件内**。底栏是常驻组件（conversation.input.left），它的数据链路却挂在设置页的生命周期上 ⇒ 设置页没挂载时无人拉数据
  - 修法：轮询**上移到 pply()**（装配层，与页面无关，注册一次全生命周期有效）；事件监听同步上移
  - loadPersonas 的「拉取 + 写 store」逻辑**下沉到 controller**（装配层与设置页共用一份实现，避免两套写 store 的代码）；设置页保留薄包装，调用点不变
  - 设置页改为只同步**暂停标记**（controller.paused）：有未保存编辑时暂停刷新，卸载时必须复位 —— 否则底栏永久停摆（本次 bug 的镜像形态）
  - 消除重复请求：装配阶段原有的 controller.loadConfig() 与全局轮询的首次 refresh() 重复，已删（首次拉取并入轮询，C2 断言依然通过）
  - 全客户端 setInterval 收敛为**唯一一处**（不会出现底栏与设置页各自轮询 ⇒ 请求翻倍）
  - 新增 **C23**（5 个场景：定时器在装配层 / focus 监听 / visibilitychange 监听 / 暂停语义 / 卸载复位）；**测试台补齐 unmount() 能力** —— 垫片原先只在依赖变化时跑清理、卸载时从不执行，导致「卸载必须复位」这类契约根本无法触发
  - 判断力 **5/5**：全局轮询被删 / 不监听 focus / 不注册 interval / paused 守卫失效 / 卸载不复位 —— 全部被拦
  - verify-client 22 → 23 项
- **人设变更确认改为宿主原生审批面板**（用户需求：不再手敲 /soul confirm，而是弹出选项框）
  - 查证结论：宿主**已内置**完整审批能力 —— 宿主侧 `dsh-user-approval`（`ApprovalService`，dsh 主包直接依赖）、客户端 `dsh-client-ui-approval`（**已在 dsh-web-app 默认依赖清单里**，自己注册了 `approval/request` 的应答者）。事件 `approval/request` 在 `API_REMOTE_FORWARDED_EVENTS` 白名单里（`mode: waterfall`）
  - **因此本插件只作为 asker 发起请求，客户端无需改一行** —— 不注册 answerer，避免与宿主应答者形成 waterfall 竞争
  - 三态映射（`approvalOutcomeOf`）：`allowed-once` → 继续落盘；`rejected` → 不落盘并如实告知；`cancelled` / `unavailable` → 归为不可用走退化
  - **退化路径保留**：`exec.agent` 缺失（宿主客户端靠 agent 解析会话归属，拿不到会放弃应答）、宿主未装审批服务、纯 TUI 无应答者 ⇒ 退化为原有的 `/soul confirm` 文本流程。删掉它会让这些场景彻底无法确认
  - 不设超时（用户决定）：用户不点就一直等，与宿主其它审批一致 —— 加超时会产生「只是没来得及点就被自动拒绝」这种难以解释的行为
  - 关键实现点：`execute(args, exec)` 接住工具执行上下文（`dsh-tools` 的调用形态是 `tool.execute(exec.arguments, exec)`，`exec` 含 `agent` / `callId` / `signal`）；服务经 `ctx.get('approval')` 可选获取
  - 行为验证 **6/6**（隔离进程）：批准 ⇒ 落盘 / 拒绝 ⇒ 不落盘 / 无审批服务 ⇒ 退化 / 无 agent ⇒ 退化 / 审批抛异常 ⇒ 退化 / 确认模式关闭 ⇒ 不经审批直接落盘
  - 判断力 **6/6**：execute 不接 exec / agent 缺失时硬发请求 / **cancelled 被当作批准** / rejected 被误当作批准 / 去掉 catch 兜底 / 退化路径被删 —— 全部被拦
  - 其中③⑥ 首轮**漏网**（判断力只有 4/6），暴露断言过弱：只钉了三态映射的片段，未逐字校验整个函数（cancelled 若返回 allowed，撤回的请求会被应用）；只钉了 `pendingPersonaProposal` 赋值，未验证退化分支真实可达（改成 `if (false)` 能悄悄删掉它）。已改为切片逐字校验
  - verify-config 112 → 113 项
- **修掉审批服务的 ctx 取错问题**（~~实测发现：审批从未真正生效~~ —— 此表述已纠正，见下方「纠正一处错误技术记录」）
  - 根因：`requestToolApproval(ctx, ...)` 传的是 `registerTools` 的**根 ctx**，而 cordis 的服务按 fiber 作用域可见 —— 根 ctx 上 `get('approval')` 返回 undefined ⇒ 每次都走 `unavailable` 退化分支，功能「看起来没生效」
  - 权威参照：`dsh-tools` 自己的 `serviceAsk` 用**持有 tools 服务的 ctx** 取 `approval`
  - 修法：调用处改传 `toolsCtx`；服务解析改为多候选（`agent.ctx`（agent-scoped，审批本就该路由到该 agent 的会话）→ `toolsCtx` 兜底），任一命中即用。已查证 `Agent` 接口确有 `readonly ctx: Context`（`dsh-agent/lib/types/runtime-types.d.ts`）
  - 断言同步：改为钉「多候选解析 + 调用处必须传 toolsCtx」，而非字面 `ctx.get('approval')`
**校验**

- `verify-config` 59 → **91 项**（新增：重置逃生口单一实现、注入失败必须留痕、诊断端点形状、两类问题分开上报、版本号不新增常量、三张双语文案表逐键对齐、`verify` 与 `verify:strict` 两条链同序且逐项带 `--strict`；本版追加「预设范围只含人设」「残留的『关于你』不参与匹配与取值」「`normalizePersonas` 剥离历史快照」「保存与应用只遍历同一份白名单」「客户端预设行摘要不读『关于你』」五项，以及**客户端复刻常量对齐**、**人设行对齐机制**、**set_persona schema 真实 DSL 校验**、**deliveryProblemText 取表方向**、**预设应用单一实现路径 + `invalid` 回报**与**命令层三处行为契约**断言）；`verify-store` 14 → **18 项**（新增 `moveAsideConfigFile` 的四条行为断言）
- **补上「客户端复刻常量 == 宿主定义」这组断言（4 条）**：浏览器模块表不允许 `client/index.mjs` import `lib/config.mjs`，所以客户端必须复刻一份枚举与字段表；这些常量旁都写着「与 lib/config.mjs 保持一致」，但那只是注释。实测证明此前**完全无人看管**：把 `FIELD_KEYS` 漏掉 `tables`、`STYLE_VALUES` 换掉一项、`REPLY_LENGTH_VALUES` 漏 `detailed`、`LANGUAGE_VALUES` 增 `jp`、乃至把标题徽标的 `VERSION` 改成 `9.9.9`，整套 `npm run verify` **依然全绿**。新断言从两端各取一次真相再比对（宿主用 import 到的真实值，客户端按源文本解析），覆盖 `STYLE_VALUES` / `TRAIT_VALUES` / `REPLY_LENGTH_VALUES` / `LANGUAGE_VALUES` / `FIELD_KEYS`（须与 `DEFAULT_CONFIG` 字段集完全相同且无重复）/ `VERSION`（须等于 `package.json`）/ 「版本常量唯一」。判断力用 **8 组破坏对照**逐一验证（上面五类漂移 + 两档 `TRAIT_VALUES` + `FIELD_KEYS` 重复字段 + 新增第二个版本常量），8/8 被拦下且报错指出具体漂移内容
- **人设行对齐机制断言（1 条 + 原有 1 条改写）**：钉住「徽标在名称列、不在操作区」「内置行有操作区空占位且必须是 `span` 而非按钮」「人设行与操作区都用网格」「两条轨道等宽固定且操作区有固定宽度」。判断力用 **5 组破坏对照**验证（徽标搬回操作区 / 空占位改成 button / 轨道退回 `auto` / 取消固定宽度 / 人设行退回 flex），5/5 被拦下。定界统一改用**括号配平**（`extractCall`）：原先的缩进定界（`\s{22}`）与真实闭合（24 空格）不符，捕获越界吞掉摘要列与操作区，把徽标挪到摘要列也能通过（变异实测）——为此新增了自检断言「名称列捕获不得含 meta/actions」，定界一旦再次失效会先在自家测试里炸出来
- **源码契约断言全面去注释化**：所有对 `index.mjs` / 链上脚本源文本的正则断言改为先 `stripComments()` 再匹配（长度保持不变的注释剥离），堵住「把真实调用注释掉、在注释里留同样字样」这类绕过（M5 类漏洞，`writeConfigFile` 与链守护两处变异实测修复前可绕过、修复后被拦）。链守护同步加严：① **链覆盖与 scripts 目录对账**（对称删掉一个脚本不再被静默放过）；② `assertCount` 必须是**被消费的结果**（`if (!assertCount(...))` 或 `skipExit(..., NOMINAL_ASSERTIONS, ...)`），返回值丢弃 / 只剩注释均不算
- **`set_persona` 输出 schema 契约断言（新增 1 条）**：结构层禁止根级 `required`、强制属性级 `required: true` 与 `changes.additionalProperties: false`；行为层在本机能解析到真实 `@deepseek-ai/dsh-tools` 时，抽出插件里真实的 schema 字面量交**真实 `defineTool`** 校验（未装 DSH 时以 `skipNote` 报告，`--strict` 下按失败处理）。此前的 196 项断言全绿而工具注册必败，正是因为全链只有 `dsh-llm` 桩、从未用真实 DSL 校验过 schema
- **修复两个校验脚本自身的失效**（它们此前的「绿」不代表验证过）：
  - `verify-nav-icon` 的浏览器发现在 Linux 分支上 push 的是**裸命令名**并用 `fs.existsSync` 判定 —— `existsSync` 不做 PATH 查找（实测 `existsSync('google-chrome')`、甚至 `existsSync('node')` 恒为 `false`），于是 ubuntu runner 上这 16 项**永远走跳过分支**，而 `ci.yml` 声称「用 runner 自带的 Chrome 真跑」。现改为绝对路径（`/usr/bin/google-chrome` 等，与 `verify-trail` 对齐）+ 按 `PATH` 各目录拼绝对路径兜底
  - `verify-compat` 是链上**唯一绕过 `assertCount`** 的脚本：`NOMINAL_ASSERTIONS` 只在 `skipExit` 里被当事实打印，通过时完全无人校验（实测把它改成 999 仍 `exit 0`）。现在逐项累加真实执行数并与声明对账（`declared = NOMINAL - skipped`，与 `verify-store` 的 inode 口径一致）；同时它的**三处内部跳过**（准入校验器不可用、校验器未拒绝废弃形态、子包未解析）此前只打印一行「– 跳过」后继续，`--strict` 也照样 `exit 0`——现全部改走 `skipNote`，strict 下判失败。判断力实测：改 999 → 被拦；构造「校验器不可用」→ 非 strict 提示 2 项未执行且 `exit 0`、`--strict` 下 `exit 1`
- 新增两个回归并入 `npm run verify`，把「改配置 → 下一轮生效」的两条通道分别钉住（上述撤回正是由它们暴露的）：
  - `verify:host`（20 项 + 3 项判断力对照）：用宿主的**真实实现**验证底座 —— 真实 `SystemPrompt` + 真实 Cordis Context 跑「改值→再装配即读到新值、改回又读到旧值」，原样切片 `SystemPromptProjection` 跑「文本变了才提交、没变不提交、清空则归一化」，外加 `preStep` / `assemble` 的源文本契约。**注意它只证明底座成立，不等于端到端一定生效**（这正是本版撤回的原因）
  - `verify:e2e`（**38 项** + 2 项判断力对照）：用**真实 `index.mjs`** + 假宿主在纯 Node 里跑通 `POST /api/soul/config` → 原子落盘 → 两条通道各拿到新文本（E4 / E8 断言 section provider 立即读到新值；E13 / E16 断言活动会话确实收到注入快照、且来源符合会话格式 v4 准入），另起一个**配置损坏场景**验证逃生口（E18–E24：如实上报、拒绝保存且不改动原文件、重置可用并回报备份、重置后免重启恢复、诊断端点可用）；另有 **E25–E30** 钉住「人设预设与『关于你』的边界」——应用**任何**预设（内置 E25 / 自建 E27）都不得改动昵称 / 职业 / 介绍，同时它声明过的人格维度必须真的写回、含输出语言（E26 是防止 E25「因为没改所以通过」的防空过护栏，E28 证明语言在预设范围内）；E29 / E30 另起一份**带着 v0.7.1 之前那套完整快照的旧配置**，验证历史残留既在读取时被迁移剥离（内存与落盘各断言一次）、也不会在应用时写回。**E31–E33** 钉住「预设含非法取值时不得静默部分应用」：预置一份 `{style:'friendly'（v0.1.x 旧名，预设库不做值迁移）, emoji:'default', customInstructions:'…'}` 与一份全非法预设，E31 断言被丢弃字段出现在 `invalid` 且合法部分确实写回、E32 断言无任何合法字段时返回 400（不再 `ok:true`）、E33 断言正常预设的 `invalid` 为空数组（防空过：判定写反则 E31 通过而这条必炸）；**E34** 断言只读端点拒绝非 GET（`POST /api/soul/prompt` 必须 405 —— 该端点此前是唯一漏判 method 的：实测 POST 也能拿到 200）。插件挂载前会在临时目录生成 `@deepseek-ai/dsh-llm` 的形状兼容桩，因此不依赖本机是否装过 DSH
  - 另有「纯外观字段既不刷新也不注入」（E10 / E10b）与「草稿预览是只读旁路」（E17）；两者都配**判断力对照**（改坏关键条件必须失败）。E25–E30 同样配了判断力对照：把身份字段加回 `PERSONA_FIELDS`（等价于回到「完整快照」）⇒ E27 必须失败；让 `normalizePersonas` 不再过滤 ⇒ E29 必须失败；把语言移出 `PERSONA_FIELDS` ⇒ E28 必须失败；而 E25 只在内置数据被改坏时才失败（精确，不误伤）
- 新增 **`verify-client`（23 项）**，把「客户端行为」补成独立一层：把**真实的 `client/index.mjs`** 原样载入纯 Node（一小撮 React 垫片 + 假 `window` / `document` / `fetch` / 定时器），跑真实的 `apply(ctx)`，再**像用户一样点按钮**，断言**用户实际会看到的那句提示**。守的是本版修过、此前只有「源文本契约」看护的四处：两类问题分开上报且 `configError` 优先（C3–C5）、保存成功带回的 `deliveryWarning` 要落到提示条（C6）、保存失败必须返回 falsy（C7）、**重置失败不得被报成成功**（C8）、重置丢弃过损坏文件时提示「已备份」且普通重置不留残余警告（C9 / C10）、保存失败不得误报「配置无变化」（C11）。**C13** 钉住输入框快捷开关的失败反馈（此前 `toggle` 不检查返回值 ⇒ 按钮外观与文案全不变，用户视角是「点了没反应」）：像用户一样点它、让 `/api/soul/config` 返回 500，断言 `data-failed="true"` 且失败原因同时出现在 `title` 与 `aria-label` 上；并含**成功路径反例**（`data-failed` 必须为 false，否则断言等于写死）。**C14** 钉住预设列表拉取失败不再永远停在「加载中...」：先像用户一样展开折叠的人设分组，再让 `/api/soul/personas` 返回 500，断言渲染出失败提示与原因、且**不再**出现「加载中...」；同样含正常加载反例。之所以需要它：源文本断言证明不了运行时走了哪条分支——把 `if (!payload)` 改成常量、或让 `resetConfig` 永不返回 `undefined`，源码看起来依然正确
- `scripts/lib/skip-report.mjs` 新增 `skipNote`：区分「**整个脚本**跳过」（`skipExit`，直接结束进程）与「**脚本内某一项**跳过」（`skipNote`，其余断言照跑、该项不计入声明数、`--strict` 下判失败），用于 `verify-store` 的 inode 探测（各平台上 `stat.ino` 的可用性不同，不该让整脚本陪葬）；`assertCount` 覆盖到 `verify-config` / `verify-store` / `verify-client`，三条链上的脚本现在都自校验断言数
- `verify-config` 新增一条**加严的链断言**：逐个读链上脚本的源文本，要求它**真正 `import` 了 `./lib/skip-report.mjs`**（只在注释里出现不算）、**把断言数交给了 skip-report**（`assertCount` 精确校验，或 `NOMINAL_ASSERTIONS` 供 `skipExit` 报告）、且**不得自己解析 `--strict`**（否则两处判定会漂移）。三条都是「判断力对照」逼出来的——注释替身与装饰性 `--strict` 都曾真的骗过更宽松的写法；`npm run verify` 因此从 7 → **8 个脚本**
- 新增 `LICENSE`（MIT），补 `homepage` / `bugs`；发布包 19 → **21 个文件**（新增 `LICENSE` 与 `scripts/verify-client.mjs`）
- 新增 **CI**：`.github/workflows/ci.yml` 在 push / PR 时跑 `npm run verify`，并单独一步报告 runner 上是否有 Chrome（渲染层两套在 ubuntu runner 上是真跑，不像本机沙箱里恒跳过）。它**不装依赖**——仓库只有 `pnpm-lock.yaml`，`npm ci` 必失败，而校验链本身零依赖。同时把 `npm run verify` 加为 `publish.yml` 的**发布门槛**（发布不可逆、同版本号不能重发，宁可多花一分钟）

### v0.7.0（2026-10-08）

**新增**
- 特质新增**表格**维度（`tables`）：`default`（默认，不额外约束）、`more`（增强，呈现对比、多字段或结构化信息时优先使用表格）、`less`（减弱，避免表格、改用列表或段落）。与「标题和列表」「表情符号」同档，设置页下拉 / `/soul set` / `set_persona` 工具 / 人设预设四处入口齐备
- 新增**回复长度偏好**（`replyLength`）：`concise`（简洁，只讲要点、不展开）、`normal`（适中，不额外约束，**默认**）、`detailed`（详尽，充分展开背景、步骤与推理）
- 两个维度均进入 `PERSONA_FIELDS`，因此人设预设会一并保存与还原；`/soul show` 的特质行也一并展示
- **插件图标**：新增 `assets/icon.svg` 并在 `package.json` 声明 `icon` 字段，插件管理列表与侧栏入口不再显示默认插图
  - 图形沿用插件自身的视觉语汇：一枚「灵魂火花」（四芒星，上浅下深渐变）加一段绕行约 250° 的光轨（尾端渐隐），与输入框光轨同色系（`#679EFE`）
  - 36×36 viewBox，与 DSH 自带插画同尺寸；两处渐变让图形在浅色 / 深色主题下都保留体积感，不会塌成一块
  - 宿主一侧由 `dsh-app-boot` 的 `readPluginMeta` / `iconOf` 消费，规则比想象中严格：只接受**相对路径**（绝对路径、Windows 盘符、任何带 scheme 的 URL 一律报错），realpath 解析后必须仍在声明它的目录内，扩展名限 SVG / PNG / JPEG / WebP，体积不超过 256 KiB，最终**内联为 `data:` URL** 交给客户端。正因如此图标里的渐变 / 引用必须自足，不能依赖外部资源
  - 图标解析失败只丢图标，用 `package.json` 的 `name` / `description` 兜底，不会导致插件装载失败——所以「图标没生效」是一类不会报错的静默失败
  - `assets/` 已加入 `files` 白名单（发布包 11 → 12 个文件）；漏加会表现为「仓库里有、装完没有」
- **设置导航图标**：设置面板左侧「个性化」那一项不再显示 DSH 给未知 section 兜底的齿轮，改用与插件图标同一套几何的图形
  - 为什么不是原生能力：设置导航的图标由壳层 `ui-settings-general` 的 `navIcon(id)` 硬编码——只认 `account` / `models` / `agent-presets` / `plugins` / `archived-sessions` 五个 id，**其余一律回退成设置齿轮**；而 `settings.section` 槽位的选项只有 `id` / `order` / `label`，插件无从声明自己的图标。所以只能走 DOM 替换（旧版用同一机制画了一颗描边五角星）
  - 替换时**只改宿主 `<svg>` 的内容与 viewBox，不换节点**：宿主的 `className`（`…navIcon{flex:none}`）、`width` / `height`（`size=16`）与 `aria-hidden` 因此原样生效，不必自己复刻一套尺寸规则；React 重建按钮后标记消失，MutationObserver 会重新画一次
  - **图形与插件图标同源，颜色则跟随邻居**：两种图标共用同一条光轨与火花路径（与 `assets/icon.svg` 逐字同源），但插件图标是彩色渐变，而设置导航那一排图标全是 `currentColor` 单色线描。导航图标因此也只取 `currentColor`——与兄弟栏目统一，且自动跟随主题、选中态与禁用态，不必自己判断暗色模式
  - 线宽同样按**显示后的像素**对齐：宿主图标是 16 网格 + 1.3 线宽，我们的窗口是 28.4 单位显示成 16px（缩放 0.5634），故取 2.3（显示后 ≈ 1.3px）。照搬 `icon.svg` 的 2.8 会比邻居粗一圈
  - 显示窗口从 `0 0 36 36` 收紧为 `3.8 3.8 28.4 28.4`（同中心 (18,18)）：宿主图标在 16px 下墨迹跨度 14.25px（占 89%），沿用 36 网格会让这个小图标显得又小又轻。窗口值是**量出来的**——把两种图标按同一尺寸渲染到 canvas 逐像素统计，不是估的
  - 宿主 `<svg>` 上挂着 `fill="none"` 与 `stroke-width="1.3"`，二者会向下继承，因此光轨与火花各自写全 `fill` / `stroke` / `stroke-width`——否则火花会被 `fill:none` 清空、光轨线宽被缩到 1.3
  - 另加一道兜底：宿主若哪天不再给 `width` / `height`（改由 CSS 控制尺寸），我们补 16——否则 `<svg>` 会退回 300×150 的默认尺寸，把导航栏撑坏
- **内置人设预设**：新增 `lib/personas.mjs`，随插件提供 6 个人设——苏格拉底式提问者、极简主义者、资深架构师、教学型讲解者、严格代码审阅者、头脑风暴伙伴
  - **只声明要覆盖的字段**：预设是「部分覆盖」语义，应用时只写它声明过的键。内置预设一律省略 `nickname` / `occupation` / `bio`（那是「关于你」的用户资料，预设去写它们等于把用户的昵称职业清空）与 `language`（输出语言属于用户偏好，写死会让另一种语言的用户被强行切回）
  - 人格差异主要靠 `customInstructions` 承载：枚举字段只能表达「更啰嗦 / 更简洁」这类粗粒度倾向，所以 6 个人设都带一段行为规则文本，写法上只描述**行为**（先问什么、先给什么、按什么顺序展开），不与风格档位的文案重复
  - **内置预设不落盘**：只存在于代码里，磁盘 `soul-config.json` 的 `personas` 字段仅存用户自建预设。好处是升级时内置内容自动更新（不会被用户的旧副本覆盖）、无法被删除或篡改、配置文件保持干净。写路径（保存 / 删除，HTTP 路由与 `/soul` 命令共 4 处）对内置名一律拒绝，读取路径（列表 / 使用 / ★ 判定）统一走 `mergePersonas` 合并视图
  - 名称冲突规则是**内置优先**：磁盘上若残留同名条目（手改文件或历史数据）会被内置内容遮蔽，不变量是「内置名永远指向内置内容」
  - 匹配语义随之修正为「只比较预设声明过的字段」：原实现按 `PERSONA_FIELDS` 全字段相等判定 ★，对省略字段的内置预设会**永远匹配不上**。判定逻辑下沉为纯模块的 `personaMatches`，宿主与回归共用同一份实现，避免两套逻辑漂移
  - 已知取舍：内置人设名是中文，英文界面下仍显示中文名。不做双语名是为了保持「一个预设一个名字」的简单语义（双语名会让同名判定与去重复杂化）
- **预设行摘要扩展**：原来只显示「风格 · 昵称」，现在额外列出所有**偏离默认值**的维度（回复长度 / 标题和列表 / 表情符号 / 表格 / 输出语言），例如「高效干练 · 简洁 · 少列表 · 少表情 · 少用表格」。只显示差异项是刻意的——把 10 个字段全列出来，每行都是一长串「默认 / 适中」，反而看不出两个预设差在哪
- 内置预设行以「内置」标记占据删除按钮的位置（后端同样拒绝删除），行宽不会因此跳动；列表排序为内置在前、用户自建在后
- **提示词预览支持未保存的编辑**：折叠区原来只能看已保存配置编译出的提示词，现在表单一有改动就改为在保存前编译**草稿**——标题随之变成「保存后将生效的提示词」，边改边看（停止输入 400ms 后自动重编译）
  - 新增 `POST /api/soul/prompt/preview`：以已保存配置为底，用请求体中**通过 `sanitizeConfig` 校验**的字段覆盖后编译；不落盘、不注入，是纯只读旁路。与保存路径共用同一套校验，非法字段既不参与预览也不落盘，并通过 `invalid` 回报给客户端——避免「预览悄悄沿用旧值」这类看不出原因的偏差（v0.1.x 的旧实现是直接展开未校验的请求体，本次一并修正）
  - 预览刷新收敛为**单一入口**（effect 驱动），保存 / 重置 / 应用预设后自动跟进——原先三个处理器各调一次，既重复请求又用**过期闭包**：保存后 `dirty` 已变 false，闭包仍是 true，会把刚保存的状态标成「未保存」
  - 新增 `PROMPT_FIELD_KEYS`（真正参与 `compilePrompt` 的字段子集）：改光轨颜色等纯外观字段不会触发重新预览，也不会把预览误标成草稿

**兼容性**
- **现有用户零行为变化**：`tables=default` 与 `replyLength=normal` 在提示词文案表中**没有对应键**，`buildBehavior` 仅在命中时才 `push`，因此不会输出任何文本。实测「不含这两个字段」与「两字段取默认档」编译出的 system prompt **逐字节相同**，提示词长度与内容都不变
- 旧配置文件（无这两个字段）由 `migrateConfig` 自动补齐默认值；两字段的脏数据（非法枚举 / 非字符串）同样回退默认值，不会让插件拒绝启动

**验证**
- `verify-config` 新增 7 项（默认值 / 合法值通过 / 非法枚举拒绝 / 脏数据回退 / `PERSONA_FIELDS` 覆盖 / 提示词文案结构 / 默认档无文案），总数 24 → **31 项**
- 其中「提示词文案结构」直接读 `index.mjs` 源文本按缩进切片，断言 `tables` 与 `replyLength` 的文案块**恰好 2 个**（zh / en），且 `default` / `normal` **不得出现**在文案表中——把「默认档零行为变更」这个不变量固化成了回归项，同时该断言的判断力已用「注入假键后必须失败」双向验证
- 图标部分另加 7 项清单契约（路径形态 / 目录逃逸 / 扩展名白名单 / 体积上限 / `files` 白名单覆盖 / SVG 命名空间与方形 viewBox / 无脚本·位图·外部引用 / 渐变引用可解析），总数 31 → **38 项**。其中「路径形态」「目录逃逸」「体积上限」「扩展名」四条是按宿主 `iconOf` 的实际判据对齐的，不是自拟标准
- 上述图标断言的判断力用 13 组对照验证：只改坏一个条件（指向不存在的文件、指向包外、绝对路径、目录不在白名单、删掉 `icon` 字段、去掉 `xmlns`、去掉 `viewBox`、viewBox 非正方形、内嵌 `<script>`、内嵌 `<image>`、引用外部资源、渐变引用未定义的 id）时**必须失败**，未改动时必须通过——13/13 符合预期
- 另用宿主自己的 `readPluginMeta('dsh-soul', <profile 目录>)` 做端到端实证：本机桌面 profile 以符号链接直连源码，因此读到的就是本仓库的清单，返回 `{ title, description, icon }` 且 `icon` 为 `data:image/svg+xml;base64,…`（解码 1270 字节，与源文件逐字节相同）；作为对照，web profile 里那份 0.6.2 旧副本（无 `icon` 字段）同一调用只返回 `{ title, description }`——说明上面那次成功确实来自本次新增的字段
- 新增 `scripts/verify-nav-icon.mjs`（`npm run verify:nav-icon`，已并入 `npm run verify`）：在复刻的导航按钮（含宿主生成的齿轮 `<svg>`）上跑**真实绘制代码**，共 **16 项**断言——替换前是宿主齿轮、替换后仍是同一个节点、宿主属性与继承属性未被破坏、显示窗口与 `icon.svg` 同心且不放大、图形占比与宿主同量级（实测 0.926）、宿主未给宽高时补默认尺寸、内容是两条 `path` 且**没有** defs / 渐变、两条 `d` 与 `icon.svg` 逐字一致、颜色（含计算值）等于按钮文字色（换个文字色会跟着变，证明没写死色值）、光轨**计算**线宽为 2.3px 而非继承的 1.3px、换算到 16px 显示后与邻居等粗、火花为纯填充、包围盒非空、仍是 16×16
- 上述断言的判断力用 6 个变体自检（viewBox 退回宿主 16 网格 / 光轨不写线宽 / 火花不关描边 / 路径换成别的图形 / 光轨改回渐变引用 / 火花写死品牌色）——每个都必须被对应那条断言判出，未改坏时必须通过。其中「光轨不写线宽」实测报出 `计算线宽=1.3px（继承未被覆盖）`，正是最容易被忽略的那个陷阱；「火花写死品牌色」报出 `火花颜色 rgb(103,158,254) ≠ 按钮文字色 rgb(26,26,26)`
- **内置人设与契约一致性**部分再增 16 项，`verify-config` 总数 38 → **54 项**：内置人设只声明 `PERSONA_FIELDS` 内的键、不含用户自有信息与输出语言、枚举与文本长度合法、都能通过 `sanitizeConfig`；`mergePersonas` 的内置优先与 `builtin` 标记；`resolvePersona` / `isBuiltinPersona` 的判定与优先级；**「应用内置预设后必须命中它自己」的 ★ 闭环**（这条是「预设能用」的最小闭环：应用 → 表单回读 → 列表应显示 ★）；部分覆盖语义的四种情形（未应用时不匹配、已声明字段变化即失配、未声明字段变化仍匹配、无声明字段的条目不匹配）；以及五项前后端契约——客户端摘要默认值表与宿主 `DEFAULT_CONFIG` **逐项一致**（漂移会让摘要显示相反的结果）、摘要覆盖的字段集合固定、12 个新增文案键在 zh / en 各一份、内置行不渲染删除按钮、服务端内置名拒绝点**恰好 4 处**且匹配逻辑只有一份实现
- 上述 16 项的判断力用 13 组破坏对照逐一验证（预设混入 `nickname` / 预设声明 `language` / 枚举取值非法 / merge 不再让内置优先 / 匹配从 `every` 退化为 `some` / 少一处内置名拒绝点 / ★ 判定改走别的函数 / 恢复本地重复实现 / 摘要默认值表漂移 / 摘要字段集合被改 / 内置标记不渲染 / 删除按钮失去 `builtin` 约束 / 缺一个文案键）——每组都必须被对应断言判出，未破坏时必须通过，实测 **13/13**。做法是把每个变体制成一次性破坏（同一次 bash 调用内「改坏 → 独立 node 进程跑 → 立即恢复」，借新进程天然绕开 ESM 缓存），跑完核对工作区回到干净状态
- 草稿预览部分再加 5 项，`verify-config` 总数 54 → **59 项**：草稿端点复用保存路径的校验与编译且不落盘不注入、客户端「参与编译的字段」与宿主 `compilePrompt` 实际读取的字段集合**相等**（这条是防漂移的关键——以后给编译器加字段却忘了同步客户端会立刻失败）、草稿分支的判定来源、预览刷新入口唯一、新增文案键中英各一份
- 上述 5 项的判断力用 6 组破坏对照验证，6/6 符合预期。其中一条第一次**没写严**：只断言了表达式里出现 `asDraft`，把它写死成常量也能「看起来正确」，补强到钉住判定来源后才判得出来
- 另用 mini-React 垫片**离线挂载真实的 `SoulSettings` 组件**（不是复刻片段）+ 桩 fetch 验证行为：无编辑时请求 `GET /api/soul/prompt`、标题为「当前生效提示词」；一有编辑就请求 `POST /api/soul/prompt/preview`、标题为「保存后将生效的提示词」且摘要含「未保存」——13 项断言全过，并截图确认渲染无误

### v0.6.2（2026-10-04）

**修复**
- **会话注入在 DSH 会话格式 v4 下每轮失败**：修复 [#1](https://github.com/Aliuyanfeng/dsh-soul/issues/1)（报告者 [@Tony-tjsn](https://github.com/Tony-tjsn)，环境 dsh 0.1.7-rc.2 + dsh-soul 0.6.0）。任意会话里发任意内容都立刻失败，界面显示「本轮运行失败 / format v4 message requires a producer-owned source kind」，会话日志里 `turn/start` 之后再无任何事件——失败发生在 step 开始之前
  - 根因：DSH 0.1.7 把会话格式升到 v4，**废弃了共享的 `kind: 'plugin'` + `plugin` 字段组合**，改为要求每个生产者声明自持 kind 并显式拒绝字面量 `'plugin'`。dsh-soul 的注入消息发往**所有活动会话**、并在下一次 step 被读取，因此每一轮都命中，整轮直接失败
  - 修复：新增 `lib/injection.mjs`，注入来源统一由 `createInjectionSource()` 构造——`kind: 'plugin:dsh-soul'` + `form: 'snapshot'` + 命名区块 `soul:persona`，且**不再携带 `plugin` 字段**（v4 迁移会主动丢弃它，保留只会在日志里留下一份易混淆的重复归属）
  - kind 取 `plugin:dsh-soul` 而非裸名：与 DSH 自带 v3→v4 迁移对第三方插件生成的 `plugin:${plugin}` 保持同一形态，使升级前后的历史事件与新增事件归属同一生产者，而不是在同一会话里出现两个身份
  - 回归验证：`verify-compat.mjs` 新增「注入来源契约」检查——用生产代码同一个构造函数取来源，交给**实际安装的** `@deepseek-ai/dsh-session-format-v3-to-v4` 准入校验器判定，并用本机 `dsh-llm` 的 `createUserMessage` 真实构造注入消息（而不是只测形状字面量）；判定前先确认该校验器确实会拒绝已废弃形态，否则本次判定没有判断力
  - issue 中「补 `engines.dsh` 字段」的建议未采纳：DSH 的装载前判定只读 `peerDependencies`（`@deepseek-ai/dsh-app-boot` 的 `evaluatePluginCompatibility()`，`engines` 字段完全不参与），兼容范围写在 peer 上才生效，见下方「与 DSH 0.2.x 的兼容性声明」
- **输入框卡片高度无界增长（composer 尺寸正反馈）**：修复 [#2](https://github.com/Aliuyanfeng/dsh-soul/issues/2)。开启光轨后，长对话中 `[data-composer-card]` 的高度会单调增长（报告者实测 87 720px → 312 712px → 503 361px），聊天区出现巨大空白、Agent 回复被顶出视口；关闭开关即恢复
  - 根因：环是「写在宿主内部、尺寸随宿主变化」的绝对定位元素。一旦类规则里的 `position:absolute` 未生效（被第三方皮肤 / 主题更具体的选择器覆盖，或样式表未加载），环就退回常规流、成为卡片 flex 列的一个子项，而它的高度由 `viewBox` 宽高比反推 ≈ 卡片自身高度，于是闭合成环：卡片变高 → `ResizeObserver` → 按新尺寸改写 SVG → 元素再变高 → 卡片再变高
  - 复现（离线隔离环境，DSH 真实 InputBar CSS + DSH 真实卡片 DOM）：**仅移除该几何规则，60 次尺寸同步就把 134px 的卡片撑到 9 202px**（`syncNoop 0/60`）；样式齐全时同一实验 60/60 次同步均为空操作——这解释了为何问题只在特定环境出现
  - 修复分三层，任一层单独即足以阻断：
    1. **挂载点改为卡片内那个 `position:absolute;height:0` 的 overlay 锚点**——锚点高度写死为 0，环即使在极端情况下退回常规流也撑不动卡片（实测：用 `!important` 把几何强制改回 `position:static` + `contain:none` 后，卡片仍 60/60 次同步不变）
    2. **关键几何全部内联**（`position` / `left` / `top` / `width` / `height` / `contain` / `overflow`）：内联样式只可能被 `!important` 击败，而单类选择器会被任何更具体的选择器击败
    3. **`contain:strict` + 墨迹收进自身盒内**（外盒每边外扩 2px，`stroke` 中心线仍压在宿主边框盒上）：尺寸、布局、绘制与外部彻底隔离，不再需要 `overflow:visible`
  - 附带加固
    - 尺寸同步改用边框盒（`offsetWidth` / `offsetHeight`，原为 `clientWidth` / `clientHeight`），环与卡片**边框盒**逐像素对齐（实测描边中心线与卡片边框盒四边偏差均为 0.0px）
    - 显隐改由**内联 `display`** 控制（原仅依赖样式表），样式表被覆盖时不会把环留在页面上
    - 新增两道熔断：卡片尺寸超过 20 000px、或首帧自检发现 `position` 被第三方样式表改掉，均停用光轨并 `console.warn` 留下线索——不再继续撑大布局，也不再画出巨大错位的图形
  - 设置页实时示例同样受益：环挂到示例内的零高度锚点（`.soul-trail-anchor`，与 DSH composer 的 `.overlayAnchor` 同形态），并与示例**边框盒**对齐（此前画在 `padding` 内侧 16px 处，与边框不重合）
  - 挂载点解析统一：`resolveTrailMountPoint` 新增「anchor 本身就是卡片直接子元素」这一落点，示例与线上从此共用同一条解析路径；此前示例靠直接传参挂到锚点、线上走解析函数，两条路径并存，且该函数对示例结构返回的是宿主本身

**新增**
- `scripts/verify-trail.mjs`：输入框光轨的**离线回归**（`npm run verify:trail`）。把 `client/index.mjs` 里那段纯 DOM 渲染层原样抽出、注入静态页，在无头浏览器里跑一组确定性模型——正常条件必须空操作且与宿主边框盒逐像素对齐；几何被 `!important` 打回常规流后必须不撑大卡片（熔断 + 零高锚点各测一次）；把环挂到卡片本身时必须复现出正反馈（作为「本实验有判断力」的对照，实测 272px → 8 912px，×32.76）；尺寸熔断；三种挂载点解析落点。抽取按标记切片并**断言补丁生效**，代码结构一变就报错退出，不会悄悄退化成永不失败的检查。需要 Chrome / Edge（可用 `CHROME_PATH` 或 `--chrome` 指定），起不来时优雅跳过（退出码 0）；另支持 `--emit` / `--dump` 两段式，便于在无法由脚本启动浏览器的受限环境里跑
- `npm run verify` 现在串联三套校验（配置层 / DSH 兼容性 / 光轨回归）；单独运行用 `npm run verify:trail`

### v0.6.1（2026-10-04）

**修复**
- **与 DSH 0.2.x 的兼容性声明**：`peerDependencies` 由 `^0.1.x` 放宽为覆盖 0.1 / 0.2 两条线，修复在 DSH 0.2.0-rc.2 及以上被拒绝装载的问题（插件管理器报「dsh-soul@0.6.0 与 DSH 0.2.0-rc.2 不兼容（要求 @deepseek-ai/dsh-llm ^0.1.1-rc.2, @deepseek-ai/dsh-tools ^0.1.0-rc.6）」）
  - 根因：DSH 以 `semver.satisfies(运行时版本, peer范围, { includePrerelease: true })` 判定，被比较的一方是 **DSH 运行时版本**而非插件实际 import 到的包版本；`^0.1.1-rc.2` 的隐含上界是 `<0.2.0-0`，因此挡住了整条 0.2.x 线
  - 新范围：`@deepseek-ai/dsh-llm` `>=0.1.1-rc.2 <0.3.0-0`、`@deepseek-ai/dsh-tools` `>=0.1.0-rc.6 <0.3.0-0`——覆盖 0.1.x 与 0.2.x 全部 prerelease
  - `@deepseek-ai/cordis` 由 `^4.0.1` 放宽为 `^4.0.1 || ^4.0.5-alpha.1`（DSH 不校验该 peer，改动只为声明准确）
  - **插件代码无需改动**：`createUserMessage`（dsh-llm）、`defineTool` 与 `TOOL_RUNTIME_SCHEDULER`（dsh-tools）、`SessionSnapshot.running`、以及 `conversation.input.left` / `conversation.input.overlay` / `settings.section` 三个槽位在新版 DSH 中均已逐项核实存在

**新增**
- `scripts/verify-compat.mjs`：DSH 兼容性自检脚本。自动定位本机 DSH 运行时，复现 DSH 的判定规则（能取到宿主时直接调用其导出的 `evaluatePluginCompatibility`），并额外抽查运行时符号与客户端 `inject` 包是否仍在；不兼容时以退出码 1 失败。支持 `--dsh <目录>` 与 `--runtime <版本>`，无法定位运行时则跳过
- `npm run verify` 串联配置层与兼容性两套校验；单独运行用 `npm run verify:compat`（v0.6.2 起又并入了光轨回归）

### v0.6.0（2026-09-20）

**新增**
- 输入框光轨：Agent 回复中时，输入框（composer）边框显示沿边循环流动的光轨
  - 触发条件：当前会话 `running === true`（DSH `SessionSnapshot.running`）且 `trailEnabled === true`
  - 实现：注册到 `conversation.input.overlay` 槽位，在输入框卡片（`[data-composer-card]`）上挂一层 SVG 圆角矩形；`pathLength` 归一化 + `stroke-dashoffset` 线性动画，按弧长匀速推进（旋转 `conic-gradient` 角速度恒定但周长线速度不均，故不采用）
  - 渐隐拖尾：8 层等长 dash 依次错位叠加、透明度递减——头部最亮、向后渐隐；各层共用同一时长，整体仍严格匀速
  - 与边框重合：`stroke` 中心线落在卡片边框盒边缘，且光轨开启时把宿主自身细边框置为透明（覆盖 `--dsw-elevation-stroke-color`），边界上只保留一条线
  - 可配置：颜色（预设色板 / 取色器 / 十六进制，默认 `#679EFE`）、流动速度（`slow` / `normal` / `fast`，默认 `slow`，对应 4.8s / 3.6s / 2.4s）、光带粗细（`thin` / `normal` / `thick`，默认 `thin`，对应 1.5 / 2.5 / 4 px）
  - 设置页「Agent 工具」分组内置实时效果示例，随颜色 / 速度 / 粗细联动
  - 尺寸同步：`ResizeObserver` 跟随输入框高度变化，不随内容增高变形；`prefers-reduced-motion` 下停用动画
  - 无障碍：光轨为纯装饰层，`pointer-events: none` + `aria-hidden`，不参与交互与读屏
- 新增配置项 `trailEnabled` / `trailColor` / `trailSpeed` / `trailWidth`；`/soul show` 展示光轨状态，`/soul set` 支持写入（布尔字段接受 true / false / on / off / 1 / 0 / yes / no）

**变更**
- 设置页折叠面板：标题行改为始终带底色（`--dsw-alias-interactive-bg-active`，悬停时加深一档），并与内容区之间保留 1px 分隔线；展开时标题行下沿改直角，形成清晰的水平交界。原因是浅色主题下 `bg-layer-1/2/3` 全为纯白，标题与内容同为一片白、展开后分不清哪块是标题
- `commitConfig` 返回值新增 `promptChanged`：`changed` 仍为全部实际变更（用于「已保存 / 无变化」判断与前端 dirty），`promptChanged` 为其中影响 Agent 行为的子集；光轨等纯外观字段只更新配置，不再刷新系统提示词、不再向活动会话注入快照
- 设置页保存失败（如颜色格式非法被服务端拒绝）改为提示「保存失败」，不再误报「配置无变化」
- 颜色归一化为大写（`#RRGGBB`），与默认值 `#679EFE` 及调色板取值一致，保证变更比对稳定

**测试**
- `scripts/verify-config.mjs` 新增光轨字段用例（默认值、大写归一化、非法颜色 / 枚举拒绝、迁移脏数据回退）

### v0.5.0（2026-09-02）

**修复**
- 暗色主题下「特质」等 `<select>` 原生下拉弹层白底白字（除选中项外选项不可读）：利用宿主主题呈现器投影的 `body[data-ds-dark-theme]` 暗色标志，以纯 CSS 属性选择器把 `color-scheme` 应用到设置栏目容器与 `select`（原生弹层、滚动条随主题切换，无需 JS 监听）；选项文字用主题变量 `--dsw-alias-label-primary` 着色（不再给 option 设 `background-color`，避免在 Chromium 上让弹层画布脱离 `color-scheme` 控制）
- 顺带修正在客户端 CSS 中误用的几个 DSW 主题变量名：`--dsw-alias-bg-l1`（实际应为 `--dsw-alias-bg-layer-1`，导致设置栏、select/textarea/input 关闭态、提示词面板背景在暗色下退化为 UA 默认色）、以及 `.soul-error` / `.soul-persona-danger` / `:focus` 中的若干杜撰 token（`bg-danger` / `border-danger` / `label-danger` / `border-focus` / `border-focus-alpha`），改为已核实的 `--dsw-alias-bg-layer-1` / `--dsw-alias-label-error` / `--dsw-alias-brand-primary`（外环用 `color-mix` 叠 25% 透明）

**新增**
- 人设预设：多套命名人设一键切换，覆盖昵称/职业/介绍/回复风格/特质/输出语言/自定义指令 8 个字段（`enabled` 全局开关不进入预设）
  - 斜杠命令：`/soul save <名称>`、`/soul use <名称>`、`/soul list`（✔ 标记当前匹配项）、`/soul del <名称>`（`delete` / `rm` 别名）
  - HTTP API：`GET /api/soul/personas`、`POST /api/soul/personas/save|use|delete`（名称 1-30 字符，拒绝保留键防原型污染）
  - 持久化于 `soul-config.json` 的 `personas` 字段；预设库增删改不触发会话注入；`/soul reset` 与「重置默认」保留预设库
- `/soul set`：键值方式修改配置项（如 `/soul set style=humorous language=en`、`/soul set enabled=true`；不含 `=` 的 token 追加到上一个值，支持含空格的文本值）
- `set_persona` 确认模式：新增配置项 `requireToolConfirmation`——开启后 Agent 的人设修改返回待确认提议（工具输出新增 `pending` 字段）而不落盘，用户以 `/soul confirm` 应用、`/soul reject` 拒绝；`/soul show` 显示确认模式状态、预设数量与待确认提示
- `readJsonBody` 请求体读取统一助手（413 / 400 语义）复用于全部 POST 端点；`verify-config.mjs` 新增人设预设与确认模式用例

### v0.4.0（2026-09-02）

**新增**
- 变更检测：写队列统一 diff 出 `changed` 字段列表，配置无实际变化时跳过系统提示词刷新与 `agent.inject()`——反复保存不再向会话堆积注入快照消息；`POST /api/soul/config` 响应新增 `changed` 字段
- 设置页「查看当前生效提示词」：只读展示当前已保存配置编译出的 system prompt 与字符数，保存后自动刷新（v0.2.0 移除的预览能力以只读形式回归）
- 设置页 dirty 检测：表单与已存配置逐字段比对，无改动时禁用「保存」按钮并显示未保存提示；保存 toast 区分「已保存 / 配置无变化」
- 设置页文案中英双语：全部 UI 文案改由宿主 locale 词典渲染（随界面语言切换），导航 label 同步本地化，图标替换按双语 label 匹配
- 提示词随输出语言本地化：`compilePrompt` 与会话注入消息、`set_persona` 返回文案按 `config.language` 使用中英两套文案表（`PROMPT_TEXT`），英文配置下 system prompt 为纯英文描述

**变更**
- 清理三层架构死代码：移除从未被引用的 `IdentityLayer.roles` / `BehaviorLayer.rules` / `StyleLayer.templates`，提示词构建重构为 `PROMPT_TEXT` + `buildUserProfile` / `buildBehavior` / `compilePrompt`；中文配置下编译结果与旧版逐字一致
- `commitConfig` 返回 `{ config, changed }`；`soulConfig.updateConfig` / `resetConfig` 服务返回值保持为配置对象

### v0.3.3（2026-09-02）

**修复**
- 配置写入输入校验：新增 `lib/config.mjs` 配置层纯函数模块，`sanitizeConfig` 提供字段白名单 + 类型断言 + 长度上限 + 枚举校验，HTTP 保存、`/soul` 命令、`set_persona` 工具与 `soulConfig` 服务共用——未知字段不再落盘；长度上限为昵称/职业 50、介绍 500、自定义指令 2000 字符，超限整单拒绝且不静默截断，防止超长文本撑爆 system prompt、缩小提示词注入面
- `POST /api/soul/config`：JSON 解析失败由 500 改为 400（附字段级 `errors` 明细）；新增 64 KB 请求体大小上限，超限返回 413
- 并发写竞态：所有配置写入路径统一进入进程内写队列串行「读—改—写」，HTTP 保存、`/soul` 命令、`set_persona` 并发执行时不再互相覆盖丢更新；`/soul enable|disable` 不再直接改写内存缓存对象，写盘失败时缓存与磁盘保持一致
- Web UI：修复设置导航图标替换的防抖失效（MutationObserver 回调未把新计时器赋回 `timer`，导致每次 DOM 变化都调度一次 sync）

**变更**
- `set_persona`：非法枚举值由静默忽略改为显式返回错误（模型可自行纠正）；文本字段统一 trim 首尾空白
- `soulConfig.updateConfig` / `resetConfig` 服务同样走校验与写队列
- 新增 `scripts/verify-config.mjs`（`npm run verify`）覆盖配置迁移与输入校验逻辑；`package.json` `files` 补充 `lib` / `scripts`

### v0.3.2（2026-09-01）

**变更**
- `package.json` 新增 `keywords` 字段（`dsh` / `dsh-plugin` / `deepseek` / `deepseek-harness` / `personalization` / `persona` / `system-prompt` / `customization` / `ai-agent` / `ai-assistant`），便于 npm 与 awesome-dsh-plugin 检索

### v0.3.1（2026-09-01）

**变更**
- `@deepseek-ai/dsh-tools` 由 `dependencies` 调整为 `peerDependencies`，对齐 awesome-dsh-plugin 收录要求；运行时仍按宿主版本动态 import + 守卫加载，缺失或不兼容时跳过 `set_persona` 工具注册，其余功能不受影响

**文档**
- README / README_EN 新增「截图」章节（设置页 + `/soul` 命令，共 4 张），托管于 `screenshots/`

### v0.3.0（2026-09-01）

> v0.2.0 曾规划但未发布，版本号直接跳至此。

**新增**
- `set_persona` 工具：Agent 在对话中直接调整 `nickname` / `occupation` / `bio` / `style` / `headingLists` / `emoji` / `language` / `customInstructions`
- 「关于你」：`occupation`、`bio` 编译进提示词，Agent 结合你的背景作答
- 特质微调：`headingLists`、`emoji` 各三档（默认 / 增强 / 减弱），与回复风格和语调叠加
- 输出语言进提示词：切换语言后 Agent 回复语言随之生效
- `/soul` 命令输出跟随配置 `language`，中英文案
- 设置页分组改版（关于你 / 特质小标题）与字段 ⓘ 提示图标

**变更**
- 回复风格和语调合并为单一选项：`professional` / `casual` / `humorous` / `roast` / `efficient`；旧 `style`+`tone` 配置自动迁移
- 发布流程改为 GitHub Release 触发（tag 由 GitHub 在发布时自动创建），新增同版本幂等守卫

**修复**
- 用户背景被模型误认为自身身份：「关于你」拆分为独立 `[用户背景]` 块，提示这是用户本人的信息
- 注入快照说明补全（含特质与输出语言）
- `/soul` 设置昵称保留原始大小写
- 提示图标 tooltip：白底 + 右展开 + 高层级，避免被左侧导航遮挡

**移除**
- 提示词预览功能、人设预设功能、示例指令模板；废弃字段 `tone` / `presets` / `examples` 加载时自动清理

### v0.1.1（2026-08-29）

**修复**
- 关闭个性化后旧人设残留：移除「空提示词直接 return」分支，改为注入显式关闭指令

### v0.1.0（2026-08-29）

首个发布版本，已包含「功能」中的全部能力。仓库 git 历史晚于该版本发布日，无代码记录。