用途与实际影响
这项功能怎样使用
为什么需要它
改密码和升级都会生成新密文。操作中的临时副本、明确保留的旧库和远端备份各有不同去向；把它们都叫“自动备份”，出问题时反而可能找不到能恢复的那一份。
举个实际例子
“给这份库换密码，先确认原来能打开的文件仍然在；失败时不要损坏旧库。”流程要先验证旧凭据，再核对重建范围与自检，并明确旧库副本是否会在成功后删除。
最后我会得到什么
得到经验证的新密码槽位、升级后的库或独立重建副本，并说明保留了哪些层、原库和恢复副本在哪里。冲突、取消和回滚失败单列；未知层的字节保留不等于已经验证其密码。
正常时
新凭据或新格式下能取回本次明确维护的内容，并说明实际留下的旧库位置和寿命。
发现问题时
自检、写入、恢复或层次保留不成立时返回失败；已经发生的变化与仍可用原件分开说明。
入口不可用或证据不足时
旧凭据无法打开、必要密钥文件缺失或当前格式不支持该维护时停止，不把它当成新建空库。
从哪里开始
在已接通本机 vault-workflow 的 AI 对话中明确说“改密”“迁移格式”或“清理旧备份”其中一项，并指定库；本人在本地提供旧凭据。
需要准备什么
- 要维护的库
- 本次是改密、迁移还是清理
- 新库或旧备份的保留选择
- 本人在本地提供旧凭据
从开始到拿到结果
- 1
分清维护目标
确认当前格式、层次和旧库位置，说明本次会生成哪份新库以及保留哪些旧文件。
- 2
生成并验证
本人提供旧凭据；工具只处理可打开的范围，写出新结果并回读，失败时保留原库或恢复原状。
- 3
确认后处理旧件
逐项交代新库、临时备份和恢复位置；旧备份清理另由本人明确决定。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
槽位改密、可验证新副本与事务回退已实现；真实私人恢复另验关键规则与设计选择
旧版升级与当前库改密是独立操作，不需要为了普通查看先升级。
临时备份成功后可能删除；不能把“执行时有备份”当成永久恢复点。
VAULT03原槽改密保留另一槽；改变共享密钥文件标志或容量必须走rebuild新副本。两密码重建需要两个已知密码分别打开不同槽位，不猜隐藏层是否存在。
本模块用到的名词
- migration（格式迁移）
- 先解读旧格式，再重新生成当前格式的密文；不是直接给旧文件换一个扩展名。
- rollback copy（回退副本）
- 操作失败时用于恢复旧状态的具体文件；必须说明它何时产生、何时仍在、何时会被删除。
- unlocked layer（本次打开的内容层）
- 当前凭据实际解出的那份内容，不自动等同双密码容器的全部内容。
专业定义
新密码能用还不够；原内容、另一层、旧库备份和失败回退必须分别核对。
解决什么
防止维护过程假成功、丢失未核对内容，以及对旧库备份产生错误预期。
当前怎样实现
- migrate_mode 识别当前格式；已有 VAULT03 则无需升级，VAULT01/02 需要原凭据解开再以当前格式重新封装。
- migrate、decoy、passwd与本地编辑复用密文事务：候选验证、临时密文、刷新与读回、并发目标检查、提交、最终验证和必要回滚。迁移与双层设置保留不会覆盖已有文件的独立密文恢复副本，不能把旧固定.bak行为当现行规则。
- passwd对VAULT03只重加密当前解锁槽，原KDF及未解锁槽位密文字节保留。共享keyfile标志不能在不知道另一层凭据时原地变更；credential-plan明确引导到rebuild --out的新副本。
- rebuild创建独立、读回验证的新容器，用于扩容、共享密钥文件变化或层次重建；可只复制当前已验证层而保留原库，也可显式输入第二个已知密码，在确认打开不同槽位并分别验证后保全两层。新库为后续编辑预留有界空间，旧槽不会静默扩大。
- 本轮修复后，VAULT03 改密和设置诱饵保留原 KDF 及全部编码参数，VAULT02 升级保留其 scrypt 参数；只有 VAULT01 迁移因原 PBKDF2 不在现有 V3 格式中，明确转为当前 scrypt。结构损坏或原算法不可用在密码、备份和写入前停止。
- clean_backups_mode 枚举实际备份并要求本人明确确认；删除只针对精确备份，不等于清理全部原文、系统历史或云端版本。
- 恢复条件包括原库字节、对应密码、精确密钥文件及运行依赖；本机 .bak、私人 Git 提交与另一磁盘副本分别证明各自保存状态。
执行流程
- 1
确认是改密、升级还是明确清理，不把三件事连成自动流程。
- 2
核对当前库、原凭据、格式和可能的其他层。
- 3
说明会保留的旧库及临时备份的实际寿命。
- 4
生成并验证本次维护结果，失败保留或恢复原件。
- 5
检查实际新内容与恢复位置，再由本人决定是否清理旧备份。
边界
- 恢复不是找回遗失密码，也不是把损坏的唯一密文自动修成原文。
- 不能为方便改密而静默改变原本声明的凭据、格式或层次范围。
- 没有实际私人备份或换机演练时，源码与样例只证明实现和所测试流程。
失败与恢复
- 旧密码或密钥文件不匹配
- 停止维护，不生成替代空库，也不把旧库删掉后让本人再试。
- 新库自检或提交失败
- 保留或恢复原库，明确是否产生临时文件，失败不能被命令行退出 0 隐藏。
- 无法保留其他内容层
- 明确本操作的维护范围并保持可恢复原件；本地编辑入口无法保真时直接拒绝，不伪称双层完整。
真实入口
E:\Projects\Tools\vault-tool\vault_tool.pymigrate_mode、change_password_mode、clean_backups_mode 与备份寿命
E:\Projects\Tools\vault-tool\test_vault_tool.py改密、旧库迁移、备份与错误分支回归
E:\Projects\Tools\vault-tool\docs\key-repository-workflow.md与私人远端密文备份区分的人工恢复流程
如何验证
- 真实虚构探针已验证旧密码拒绝、新密码往返，以及 V2→V3 内容相同并留下 .bak。
- 9月3日pwbak样例只证明当时实现；2.3.1新增槽位保全、新副本重建和不覆盖旧备份的隔离回归。网页不将历史算法样例改写为本次真实私人库维护。
- 本轮没有清理用户任何真实备份或真实维护另一密码层。
与其他模块的关系
日常内容追加在文件入库模块；双密码容器独立说明两层；远端密文保存与逐字节读回在密文备份模块。