mingding-snap-modifier 2.13.1 → 2.14.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 mingding-snap-modifier contributors
+Copyright (c) 2026 命定之诗修改器开发
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,42 +1,90 @@
-# 命定之诗与黄昏之歌 · 快照全量修改器 (v2.13)
+# 命定之诗 · 快照全量修改器（酒馆助手版）v2.14
 
-一个用于 [SillyTavern](https://sillytavern.app) 角色卡《命定之诗与黄昏之歌》的**快照全量修改器**（酒馆助手版 · tavern_helper）。
+命定之诗角色卡的运行变量编辑脚本，运行于 [SillyTavern](https://github.com/SillyTavern/SillyTavern) + 酒馆助手（tavern_helper）隐藏 iframe 中。
 
-在运行中的聊天里直接查看 / 修改角色的 MVU 状态数据（主角属性、金钱、NPC 好感、登神长阶、日期、日历等），支持「正文注入（默认，走 MVU 引擎）」与「直接写入（不经校验）」两种应用方式。
+- **开发与测试环境**：角色卡 V4.3.2、SillyTavern 1.13.3、酒馆助手 4.9.3
+- **适配范围**：以 V4.3.2 为主；V4.3.1 保留未知字段兼容读写；不支持 V4.2.1
+- **运行依赖**：零运行时第三方依赖
+- **作者**：@gunkoishi_50181
+- **npm 版本**：`mingding-snap-modifier@2.14.0`（界面显示 v2.14）
 
-> v2.13 修复：跟随状态栏 UI 主题失效、卡片折叠失效、Tab 切换滚动位置重置；并同步正则版主要功能（滚动记忆、折叠幂等、新增「关于」Tab、开局 Tab 移日历后）。
-> v2.13.1 新增英文文件名脚本，便于 jsDelivr 引用。
+## 功能
 
-## 内容
+- 编辑并安全写回 MVU 消息变量中的 `stat_data`（主角 / NPC / 世界 / 日历 / 新闻 / 任务等）；
+- 同步 `date`、`calendar_float_store` 与聊天模板变量（chat_metadata.variables）；
+- 自定义开局界面的临时转生点（reincarnationPoints）独立即时处理；
+- 变量解读区分正文中已有指令与待提交修改；支持编辑、删除正文指令，实际数值仅在单独执行“重新处理”时重算，增减指令可能重复生效；
+- 默认“撤销本次操作”只恢复该次改过的字段与相关指令块，保留后来无关的变化；另有“完整快照恢复”。两者均不回滚剧情，旧记录缺失的指令无法补回；
+- 效果支持结构化添加、改名、编辑和删除；每张复杂卡片可切换原始 JSON，格式错误不会静默丢弃；
+- 背包等集合通过名称搜索与普通下拉框选择，只显示当前条目的详情；内部使用分隔标题，标签直接逐行增删，下拉、搜索和标签输入采用统一配色；
+- 大型变量页面按需创建编辑控件；已经打开过的条目会在当前页面缓存，切换回来不重复读取快照。面板关闭时不保留后台轮询，输入中的草稿和错误提示仍按原规则保留；
+- 回滚历史、操作日志和正文注入记录保存在浏览器原生 IndexedDB 中；等待备份结果并重新核对数据后写入，容量不足时按下述规则降级并提示；
+- 默认经典主题与固定深色，另提供平面分区的简洁主题；已有配色选择继续保留；
+- 统一「编辑 → 只读变更预览 → 用户确认 → MVU 处理一次并应用 → 写后核验」流程；
+- 构建时按模块化原生 JS 打包，产物为可读单文件。
 
-- `dist/mingding-modifier.js` —— 修改器源码（英文名，推荐 jsDelivr 引用）
-- `dist/mingding-import.json` —— tavern_helper 导入用（英文名，推荐）
-- `dist/命定之诗全量修改器_v2_13.js` —— 修改器源码（中文名）
-- `dist/命定之诗全量修改器_v2_13_tavernhelper导入.json` —— tavern_helper 导入用（中文名）
-- `docs/v2.13迭代差分说明.md` —— 版本变更说明
+## 安装
 
-## jsDelivr 链接
+1. 在酒馆助手新建脚本，粘贴 `dist/mingding-modifier.js` 内容；
+2. 开启脚本并刷新页面；
+3. 进入命定之诗聊天，点击悬浮球打开面板并读取变量；标题栏可拖动，并提供刷新、最小化、全屏和关闭操作。
 
-- 修改器源码：`https://cdn.jsdelivr.net/npm/mingding-snap-modifier@2.13.1/dist/mingding-modifier.js`
-- tavern_helper 导入：`https://cdn.jsdelivr.net/npm/mingding-snap-modifier@2.13.1/dist/mingding-import.json`
+也可直接导入 `dist/命定之诗全量修改器_v2_14_tavernhelper导入.json`，无需手动复制源码。
 
-## 使用方法（SillyTavern）
+链接安装沿用旧版方式：在酒馆助手新建脚本，填入以下语句后启用。使用完整源码、导入 JSON 或链接安装三种方式之一即可，升级时先停用旧修改器。
 
-1. 打开 SillyTavern 的 **Extensions → tavern_helper** 面板。
-2. 删除旧版修改器脚本。
-3. 导入 `dist/mingding-import.json`（或 `dist/命定之诗全量修改器_v2_13_tavernhelper导入.json`）。
-4. 打开一个《命定之诗与黄昏之歌》聊天，状态栏设置 Tab（或悬浮球）出现「快照全量修改器」。
+```javascript
+import 'https://cdn.jsdelivr.net/npm/mingding-snap-modifier@2.14.0/dist/mingding-modifier.js';
+```
 
-## 写入方式说明
+`dist/命定之诗全量修改器_v2_14_链接版世界书.json` 的 `content` 与 `originalContent` 同步保存上述安装语句。世界书条目保持禁用，只作为安装说明载体；导入世界书本身不会自动安装脚本。链接锁定 2.14.0，不会自动升级到未来版本，加载时需要网络及 CDN 可用；完整源码和导入 JSON 不依赖此 CDN 加载。
 
-- **正文注入（默认）**：把变化的字段语句合并进最后一条 AI 回复的变量更新栏，由角色卡 MVU 引擎校验应用（走引擎流程、不浪费上下文、本轮即时生效）。
-- **直接写入**：不经校验，直接改消息变量（适用于日历 / 快照类改动，如 NPC 等级 / 经验）。
-- 修改前会自动记录回滚点，可在「操作」Tab 回滚。
+## 本地历史
 
-## 安全声明
+首次使用会读取能识别的旧 v2.14 历史、日志与注入记录，复制到浏览器数据库；保留原 localStorage 键，不清除其他脚本的数据。无法迁移的记录会提示原因，不把缺少聊天目标的旧 v2.13 记录绑定到当前聊天。
 
-本包**不包含**任何 API 密钥、token、账号凭据或外部接口地址。它只是一个纯前端变量编辑脚本，运行在 SillyTavern 内。
+回滚历史默认最多 20 条，可设置 1 至 100 条，同时受 1 MiB 总量限制；操作日志最多 200 条，正文注入记录最多 50 条。正常保留变量快照和相关指令块，达到设置的条数上限自动替换最旧记录。因空间不足需要额外删除旧记录、只保存变量或不保留持久备份时，先询问一次；取消不会继续修改或删减已有备份。接受后才按实际需要依次降级，连快照也存不下时明确提示“本次没有持久回滚备份”。失败试写保留旧磁盘历史，不把较早准备阶段的恢复点当最新备份。
 
-## License
+只有明确的空间不足才能使用上述降级；权限拒绝、数据库不可用或损坏等错误仍会停止写入。日志单独保存失败不会撤销已经完成的修改，界面会提示记录未保存。窗口与主题设置继续使用 localStorage，因此迁移历史不等于清空它或保证所有设置一定有空间可存。
 
-MIT
+预览只展示待提交的修改，不执行 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、第三方插件通知、自定义开局及实际聊天的兼容性仍取决于使用环境。2026-09-06 项目所有者授权将当前版本通过 npm 发行；该授权不替代未执行的宿主测试。历史检查与已知限制详见 `docs/v2.14迭代说明.md`。
+
+## 许可
+
+MIT，见 `LICENSE`。