用途与实际影响
这项功能怎样使用
为什么需要它
密钥文件丢失、内容被改过，或者新机器缺少对应依赖，都可能表现为打不开。只有把格式、参数、凭据和环境分开检查，才能知道当前缺的究竟是哪一类条件；没有恢复服务能替代遗失的密码。
举个实际例子
“我记得密码，新电脑却打不开库。”工具先看这份库当初要求的格式、密钥文件和运行环境；必要条件缺失会直接说明，不请本人把密码发到聊天。
最后我会得到什么
先得到这份库需要哪些条件的说明；本人在本地提供正确条件并真实解开后，才得到内容或具体失败原因。结构检查不能代替实际解密。
正常时
格式、参数、凭据和运行依赖匹配，真实认证解密得到相应内容。
发现问题时
参数异常、结构损坏、凭据不匹配或明确选择的算法不可用时说明原因范围，不静默改选。
入口不可用或证据不足时
必要密码、精确密钥文件或运行依赖缺失时停止；没有找回、猜测或另一套账号代开。
从哪里开始
在已接通本机 vault-workflow 的 AI 对话中说“检查这份库为什么打不开”；先用只读 Inspect，真正恢复由本人在本地提供密码及密钥文件。
需要准备什么
- 打不开的库
- 本人是否还持有密码和原密钥文件（在本地提供）
- 具体错误或换机情境
从开始到拿到结果
- 1
先辨认格式
只读检查库结构、派生参数、密钥文件要求与本机依赖。
- 2
本人本地尝试恢复
凭据齐全后按原格式真实解密并认证；密码或密钥文件缺失时停止，不猜测重置。
- 3
交回实际结果
成功才确认取回内容；结构合格或参数存在只能说明可尝试，不能算恢复。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
三代读取与当前格式加密已实现关键规则与设计选择
密钥文件依赖的是内容，重命名通常不改变它，重新保存或压缩可能改变。
Windows 标准库加系统加密接口，不等于所有平台都零依赖。
KDF 校准是速度与资源的取舍，不是密码强度或破解时间的证明。
本模块用到的名词
- scrypt / Argon2id（两种密码派生方式）
- 决定如何从密码产生密钥及消耗多少资源；恢复使用容器记下的方式，不是随便互换的插件。
- AAD（附加认证数据）
- 没有被加密但被认证的格式头信息；改头也可能使认证失败。
- nonce（一次性随机值）
- 每次加密使用的随机参数，不是另一个由本人记忆的密码。
专业定义
解锁条件不只有密码；精确密钥文件、原格式参数和恢复依赖同样重要。
解决什么
防止密码、密钥文件、格式兼容与算法依赖混淆，使本可解释的恢复条件变成盲试。
当前怎样实现
- VAULT03：tar+gzip 明文包经 AES-256-GCM 加密；公共头包括 7 字节魔数、标志位与 KDF id/参数，作为 AAD（附加认证数据）的一部分。每层使用随机盐、随机 nonce（一次性随机值）和认证标签。
- scrypt 将密码与可选密钥文件 SHA-256 混合后派生 32 字节密钥；SHA-256 在这里是本地派生步骤，密钥文件内容及其摘要不成为公开样例证据。
- 默认直接封装参数为 N=2^17、r=8、p=1；交互加密可以校准到约 0.6 秒，N 上限 2^20。Argon2id 可选，校准内存上限 1 GiB；选择和实际执行必须一致。
- Windows 使用系统 CNG（Windows 加密接口）bcrypt.dll；非 Windows 使用 cryptography。Argon2id 需要 argon2-cffi；缺依赖与密码错误不是同一种结果。
- 结构与真正KDF执行前分别检查容器长度、参数正值及关系、内存和普通工作量预算；派生内存硬上限为4GiB，不是总进程内存上限。合法但异常昂贵旧库须显式--allow-expensive-kdf，仍不放宽硬内存上限。
- VAULT02 使用 scrypt+AES-GCM；VAULT01 使用 600,000 次 PBKDF2-SHA256 与 AES-CBC/PKCS#7。旧格式可读不表示它们的认证特性与 VAULT03 相同。
- 整体打包会同时持有若干内容与容器副本；支持任意类型不等于已经验证任意体积或流式处理，超大文件需要按实际资源判断。
执行流程
- 1
先只读识别格式、结构、参数与密钥文件要求。
- 2
确认当前平台和所需依赖，不先让本人重复试密码。
- 3
由本人在本机提供相应密码及精确密钥文件。
- 4
执行当前格式真实解密与认证。
- 5
交回相应内容或失败边界，不把结构检查或参数存在当成原文通过。
边界
- 密码和密钥文件丢失没有重置途径；网页或 AI 不能恢复这些条件。
- 不得把 AES 算法名称、内存参数或密码强度条换算成已验证的绝对破解保证。
- 本轮 Windows 实际样例不证明 Linux/macOS 与干净新机已验收。
失败与恢复
- 知道密码但缺少原密钥文件
- 说明需要精确字节，停止解锁；不能拿同名文件或另一张相似图片代替。
- 明确算法缺少依赖
- 报告所需依赖并保持选择，不静默降级后说指定算法成功。
- 认证失败或容器截断
- 拒绝读取；结构错误可以明确指出，认证失败不能无证据断言一定是密码错或一定被改动。
真实入口
E:\Projects\Tools\vault-tool\vault_tool.py平台接口、KDF、密钥文件、三代容器与结构检查
E:\Projects\Tools\vault-tool\test_vault_tool.py各代往返、错误输入、截断、参数及密钥文件回归
E:\Projects\Tools\vault-tool\README.md人工选择方式与跨平台恢复要求，须与代码实况共同解释
如何验证
- 实际虚构样例使用真实 KDF 与 Windows 加密接口，不以算法替身冒充往返。
- 错误口令和改动密文均被本轮对应样例拒绝，结论只限所测试输入。
- 本轮没有密码强度、破解成本、真实私人密钥或跨平台恢复证明。
与其他模块的关系
本模块解释能否打开；库维护模块解释改变凭据与版本后的结果，双密码模块解释一个容器里的不同层。