# 命定之诗 · 快照全量修改器（酒馆助手版）v2.14.3

命定之诗角色卡的运行变量编辑脚本，运行于 [SillyTavern](https://github.com/SillyTavern/SillyTavern) + 酒馆助手（tavern_helper）隐藏 iframe 中。

- **开发与测试环境**：角色卡 V4.3.3、SillyTavern 1.18.0、酒馆助手 4.9.3
- **酒馆版本支持**：当前活动版本只适配 SillyTavern 1.18.0；其它版本不在支持承诺内
- **适配范围**：以 V4.3.3 为主；V4.3.2、V4.3.1 保留未知字段兼容读写；不支持 V4.2.1
- **运行依赖**：零运行时第三方依赖
- **作者**：@gunkoishi_50181
- **npm 版本**：`mingding-snap-modifier@2.14.3`（界面显示 v2.14.3）

## 功能

- 编辑并安全写回 MVU 消息变量中的 `stat_data`（主角 / NPC / 世界 / 日历 / 新闻 / 任务等）；
- 暂时隐藏主角身份的常规编辑入口：V4.3.3 的主校验不能可靠保留身份修改。已有身份数据不删除、不转存职业，NPC 身份仍正常编辑；高级入口的修改未被角色卡接受时会提示未生效；
- 同步 `date`、`calendar_float_store` 与聊天模板变量（chat_metadata.variables）；
- 自定义开局界面的临时转生点（reincarnationPoints）独立即时处理；
- 变量解读区分正文中已有指令与待提交修改；支持编辑、删除正文指令，实际数值仅在单独执行“重新处理”时重算，增减指令可能重复生效；
- 默认“撤销本次操作”只恢复该次改过的字段与相关指令块，保留后来无关的变化；另有“完整快照恢复”。两者均不回滚剧情，旧记录缺失的指令无法补回；
- 效果支持结构化添加、改名、编辑和删除；每张复杂卡片可切换原始 JSON，格式错误不会静默丢弃；
- 背包等集合通过名称搜索与普通下拉框选择，只显示当前条目的详情；内部使用分隔标题，标签直接逐行增删，下拉、搜索和标签输入采用统一配色；
- 大型变量页面按需创建编辑控件；已经打开过的条目会在当前页面缓存，切换回来不重复读取快照。面板关闭时不保留后台轮询，输入中的草稿和错误提示仍按原规则保留；
- 回滚历史、操作日志和正文注入记录保存在浏览器原生 IndexedDB 中；等待备份结果并重新核对数据后写入，容量不足时按下述规则降级并提示；
- 默认经典主题与固定深色，另提供平面分区的简洁主题；已有配色选择继续保留；
- 统一「编辑 → 只读变更预览 → 用户确认 → MVU 处理一次并应用 → 写后核验」流程；
- 构建时按模块化原生 JS 打包，产物为可读单文件。

## 安装

1. 在酒馆助手新建脚本，粘贴 `dist/mingding-modifier.js` 内容；
2. 开启脚本并刷新页面；
3. 进入命定之诗聊天，点击悬浮球打开面板并读取变量；标题栏可拖动，并提供刷新、最小化、全屏和关闭操作。

也可直接导入 `dist/命定之诗全量修改器_v2_14_3_tavernhelper导入.json`，无需手动复制源码。

链接安装沿用旧版方式：在酒馆助手新建脚本，填入以下语句后启用。使用完整源码、导入 JSON 或链接安装三种方式之一即可，升级时先停用旧修改器。

```javascript
import 'https://cdn.jsdelivr.net/npm/mingding-snap-modifier@2.14.3/dist/mingding-modifier.js';
```

`dist/命定之诗全量修改器_v2_14_3_链接版世界书.json` 的 `content` 与 `originalContent` 同步保存上述安装语句。世界书条目保持禁用，只作为安装说明载体；导入世界书本身不会自动安装脚本。链接锁定 2.14.3，不会自动升级到未来版本，加载时需要网络及 CDN 可用。

## 本地历史

首次使用会读取能识别的旧 v2.14 历史、日志与注入记录，复制到浏览器数据库；保留原 localStorage 键，不清除其他脚本的数据。无法迁移的记录会提示原因，不把缺少聊天目标的旧 v2.13 记录绑定到当前聊天。

回滚历史默认最多 20 条，可设置 1 至 100 条，同时受 1 MiB 总量限制；操作日志最多 200 条，正文注入记录最多 50 条。正常保留变量快照和相关指令块，达到设置的条数上限自动替换最旧记录。因空间不足需要额外删除旧记录、只保存变量或不保留持久备份时，先询问一次；取消不会继续修改或删减已有备份。接受后才按实际需要依次降级，连快照也存不下时明确提示“本次没有持久回滚备份”。失败试写保留旧磁盘历史，不把较早准备阶段的恢复点当最新备份。

只有明确的空间不足才能使用上述降级；权限拒绝、数据库不可用或损坏等错误仍会停止写入。日志单独保存失败不会撤销已经完成的修改，界面会提示记录未保存。窗口与主题设置继续使用 localStorage，因此迁移历史不等于清空它或保证所有设置一定有空间可存。

预览只展示待提交的修改，不执行 MVU 或角色卡自动化，取消预览不会累计 FP。确认后备份、读取最新数据、正式处理一次，再按实际改动合并。自动化已保存相同结果时直接接受；同字段出现不同值时，展示原值、现在的值和你的修改，可选“按我的修改覆盖”“保留当前值”或取消。数组整项选择，移动来源与去向联动；保留的项不会被重新注入正文。弹窗等待后只复核相关变化，不重演 MVU。无关字段、剧情与无关指令块变化不再要求手动刷新；真正换目标、生成中或角色卡校验规则改变仍停止。

消息更新、生成结束/停止及实际公开的 MVU 完成事件会合并触发同步；面板隐藏时等下次打开再读。有输入时保留草稿及原目标，无关通知不再迫使用户手动刷新后才能应用；真正换聊天、回复或 swipe 时不会把旧草稿搬到新目标。没有通知的第三方静默更新无法主动获知，应用时仍会读取最新数据。自动同步只读取快照，不自动提交你的编辑；成功应用后也会自动读回。

默认撤销依据实际操作前后值，只撤回本次字段和相关指令；同一字段后来又变过会询问覆盖或保留。明确覆盖其他脚本的新值后再撤销，会恢复被覆盖的新值。“完整快照恢复”才恢复备份那一刻的所列完整变量范围，可能覆盖之后无关的数值修改。旧记录没有逐项信息时只能使用完整入口。相关指令仍存在且唯一时，旁边剧情改变不阻断恢复；相关块被改写，或删除块的插入位置不唯一时不猜测恢复位置。

新记录标明已应用、未应用或需要核对；确定未执行的记录不能当作成功修改来回滚。解析可能触发角色卡自行保存统计，解析后失败不宣称数据完全没动。自动补偿只撤回属于本次最终写入的字段，不保证撤销监听器额外写入；如果保存调用已执行，但实值检查或补偿失败，会提示重新读取检查，不是误报 AI 生成中。成功后的逐项记录保存失败只警告，保留原快照，不能假称已有完整的逐项撤销信息。

数字与 JSON 的错误在输入时提示，无有效快照时不能应用。尚未失焦或无效 JSON 的输入仍会保留；未改过的旧异常字段不再触发前端整树拒绝，最终仍须通过角色卡规则。MVU 不可用时不提供绕过它的写入方式。

## 开发

```bash
npm install          # 无运行时依赖；仅开发用（无第三方依赖）
npm test             # node:test 全量单元测试
npm run check        # node --check 语法检查
npm run build        # 生成 dist/mingding-modifier.js 等发行载体
node scripts/verify-dist.js   # 核对各载体 content 与 js 逐字节一致
```

源码按职责分层：`src/host`（宿主适配 / 目标解析 / 生命周期）、`src/data`（快照 / 字段模型 / 补丁 / ChangeSet / 历史）、`src/apply`（MVU 适配 / 事务 / 正文合并 / 应用流程 / 转生点）、`src/ui`（面板 / 样式 / 可访问性 / 脏状态）、`src/main`（装配入口）。

## 安全与数据完整性

- 每次读取 / 写入绑定同一聊天、消息楼层与活动 swipe；目标变化即中止；
- `stat_data` 只经当前 MVU API 与角色卡 Zod 校验写入，校验失败默认不写入；
- `_` 开头字段全模式只读；事件 `信号` 只允许纯追加；
- 跨存储区尽力事务 + 补偿回滚，部分失败明确报告；
- 面板关闭零常驻轮询；卸载后监听 / DOM / 定时器 / 对象 URL / 父窗口标记全部清理。

## 测试边界

自动化测试覆盖模块协议、补丁、历史、事务、回滚、目标锁定、构建及载体一致性。当前 DOM 专项为 `scripts/qa-operation-recovery.cjs`（冲突选择、局部回滚、容量取消/降级、输入保护、恢复默认及连续应用）与 `scripts/qa-preview-automation.cjs`（取消预览零解析、确认单次解析、FP 同结果合流）。旧 `qa-apply-single-pass.cjs` 的预览解析计数及 `qa-write-merge-controls.cjs` 的三次重试预期仅留作历史。QA 使用已有 Playwright 与 Edge，在隔离页面操作实际控件和原生数据库；不进入运行包，不连接真实聊天。

MVU 的整体替换接口不提供原子比较写入。当前合并可以保留最近读取到的无关业务数据，但不能保证解析与写入之间不存在并发，也不能完全证明第三方同时修改资源上限等关联字段后，全树规则仍成立。`display_data`、`delta_data` 是本次解析重建的报告，采用解析输出，不承诺保留同时写入的旧报告。

这些检查不等于所有 SillyTavern 环境都已通过。真实生成、角色卡远程 MVU/Zod、第三方插件通知、自定义开局及实际聊天的兼容性仍取决于使用环境。发布授权不代表 SillyTavern 1.18.0 人工验收完成。历史检查与已知限制详见 `docs/v2.14迭代说明.md`。

## 许可

MIT，见 `LICENSE`。