8473a02fb9
SafeMode.md records how safe mode is entered, what the rescue resets and keeps, when the startup page answers it, and how to restore the previous settings; the in-app assistant reads it through tt-docs. The startup flow now lists the prompt and the later user.css load, and the backend layout links to it. Each README tells users who cannot open the app at all how to reach safe mode.
4.8 KiB
安全模式
安全模式是在启动开头执行的一次恢复：扩展、设置与自定义 CSS 回到出厂状态，角色、聊天等内容原样保留。恢复完成后应用照常运行，代码里没有“正处于安全模式”这一状态。
1. 进入
两个入口都只记下一个请求，由下一次启动执行：
- 连续启动：setup 在读取任何用户数据之前，把本次启动记入
app_root/safe-mode.json。3 分钟内第 5 次启动时，页面询问是否进入安全模式，并倒计时 10 秒，走完即进入。倒计时只在页面可见时走，切到后台会暂停。选择正常启动会清空计数。 - 启动失败对话框：其中的“进入安全模式”按钮。
请求保存后，桌面端自动退出；移动端提示用户彻底退出后重新打开。一次启动指一次进程启动，切到后台再回来不算；iOS 从多任务界面上划、Android 从最近任务划掉或在根页面按返回，都会结束进程。
启动记录属于安装，不随 data_root、备份或导入迁移。记录读不出时从空记录开始。本次启动写不进记录时按普通启动处理，否则一个清不掉的请求会让每次启动都执行恢复。请求在执行前就从记录中清除，一个请求只执行一次。
2. 恢复
恢复在后端初始化开头执行：先完成数据迁移，再恢复，然后才读取启动配置，所以本次启动用的已经是恢复后的设置。
- 把当前设置（含用户设定）存为一份设置快照，与手动快照一样放在
backups/。 - 关闭自动同步，避免把出厂设置同步到其他设备。
- SillyTavern 设置回到出厂，只保留用户设定的状态。
firstRun记为 false，不再显示首次使用引导。用户与全局扩展目录中的第三方扩展全部加入停用列表，扩展文件不动。 - 宿主设置回到首次启动写入的初始值，只沿用聊天备份设置，因为备份上限决定启动后哪些聊天备份会被删除。读不出或不合法的上限按不限处理。
user.css回到出厂内容。
角色卡、聊天、世界书、预设与主题文件、用户设定、密钥、扩展文件和聊天备份都不受影响。
被替换的宿主设置文件和 user.css 以 <文件名>.safe-mode-<时间> 留在原文件旁；内容没有变化的文件不动。
第一次写回之前，快照已经写好、自动同步已经关闭、需要的数据都已读完，所以中途失败时，设置要么原样未动，要么能从快照找回。失败与其他后端初始化失败一样显示启动失败对话框。
宿主设置的初始值带有构建注入的出厂 profile。iOS 分发构建都注入了 profile，所以恢复后的设置不会沿用本机缓存的策略，见 iOS 策略。
3. 启动页面
页面在外壳渲染后答复询问，在后端就绪后显示恢复结果，之后才加载 css/user.css 并读取设置。对话框上因此不会出现任何用户样式，扩展也还没有运行。启动顺序见 启动流程。
结果对话框说明扩展已停用、设置已恢复默认，以及在哪里找回原先的设置；关闭了自动同步时多一句提示。询问、结果、“请重新打开”与启动失败对话框共用一个原语，在 Shadow DOM 中渲染，不受主题和自定义 CSS 影响。
Web Host 没有启动记录，不会出现询问和结果；失败对话框里的“进入安全模式”会报不支持。
4. 找回原先的设置
用户设置 → 杂项 → 设置快照 列出所有快照，安全模式存的那份也在其中。恢复快照会一并恢复扩展的启用状态。宿主设置和 user.css 不在快照里，需要时从旁边的 .safe-mode-* 副本手动找回。
安全模式不提供撤销。误入时从快照恢复设置和扩展，其余手动重设；真正卡住的用户撤销后仍会卡住。
5. 源码入口
| 职责 | 入口 |
|---|---|
| 启动记录 | 计数规则、记录文件 |
| 宿主状态与命令 | 宿主状态、命令 |
| 恢复 | 恢复用例；原件留存见 file_system.rs 的 replace_keeping_original_blocking |
| 页面 | 询问与结果、对话框原语 |
询问或恢复时，日志记录本次决定（Safe mode decision=…）；恢复完成时记录快照文件名。