用途与实际影响
这项功能怎样使用
为什么需要它
“把文件放进去”不等于“原来的都还在”。直接重建 source/ 可能遗漏旧文件，错误的同名合并次序又会把刚准备的新版本换回旧版。产品需要先说明这两个不同问题，再执行加密。
举个实际例子
“给原来的库加一份新清单，保留里面的附件；若暂存区已有新版同名清单，不要用旧库的版本把它盖回去。”入口先解开本次有权打开的旧内容，再按明确规则合并。
最后我会得到什么
得到一个 vault.enc 与实际处理结果；来源副本、source/ 暂存、合并后的内容和本次能保留的层次分别说明。不能仅凭新库存在就声称整份旧库都保留了。
正常时
范围明确，合并次序与内容核对正确，密文经过写入和读回验证；原件默认保留，明确选择的清理另报结果。
发现问题时
同名、新旧版本、另一层或写入结果无法保持时先说明，不悄悄丢文件。
入口不可用或证据不足时
没有文件、路径不可读或本人取消密码输入时停止本次操作，不把空库或取消当成完成。
从哪里开始
在已接通本机 vault-workflow 的 AI 对话中说“把这些明确文件追加到这份库”；本人在本地窗口输入凭据。直接 encrypt 是新建或替换路线，不能当追加。
需要准备什么
- 要加入的文件或目录
- 现有库或新库目标
- 追加、替换及同名文件的选择
- 需要解锁时本人在本地掌握的凭据
从开始到拿到结果
- 1
先核对输入和库结构
工具检查选定原件、目标库格式和追加或替换的影响；旧成员的同名关系要在本地解锁后才能确认。
- 2
本地解锁并装入
本人只在本机提供凭据，工具打开相应层并处理同名文件，再把明确新文件合并加密；其他打不开的层保持原密文。
- 3
核对再交付
读回新容器中的预期文件并报告成功或失败；原件默认仍在原处，清理要另行明确。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
打包、合并与同名新版优先已验证关键规则与设计选择
已有库要追加时用菜单添加；encrypt 和启动脚本不会自动合并。
source/和复制前的原路径都默认保留；--cleanup-source只处理本次已归档且仍完全相符的文件，不清理新增、变化、占用、硬链接或无法确认的对象。
菜单追加只修改当前解锁层，未解锁槽位保留密文字节；直接encrypt是另一种重建意图，不把一个密码可打开误认为整库所有层都已验证。
本模块用到的名词
- source（明文暂存目录）
- 入库前打包的工作目录，不能因为名字像来源就默认它是永不删除的原件库。
- merge（合并）
- 把旧库本次打开的成员与新文件放在一起；不是恢复另一未打开层，也不是自动版本管理。
- round trip（加密再解密往返）
- 对同一份明确输入比较取回内容，用于证明这一次容器处理与预期一致。
专业定义
保存哪几个文件、旧库是否合并、同名以谁为准，都在加密前说明。
解决什么
防止新建、追加、整库替换和同名更新混为一谈，导致内容静默遗漏或回退。
当前怎样实现
- BASE 取 vault_tool.py 所在目录；普通入口使用其 source/、vault.enc 与日志路径，不是随当前终端工作目录任意变化。
- 对source/建立稳定清单，检查原路径、链接/重解析点、对象身份、大小与修改时间，确认读取中没有变化；_make_tar按相对路径打包，gzip头时间固定为0，tar仍保留必要成员属性。
- add_files_mode在内存中展开当前密码对应层，与明确新输入合并，不将旧库内容先写进source/；未解锁槽位保持原密文字节。直接encrypt仍处理source/，二者不能互换。
- encrypt_mode 直接处理当前 source/，已有库先询问覆盖。Start-KeyVaultEncrypt.ps1 先复制 AddPath，再调用 encrypt；不调用菜单的旧库合并步骤。
- 候选密文先在内存中验证，再写同目录临时密文并刷新落盘，读回重新验证；提交前核对原目标未变，提交后再校验。覆盖既有库时保留不会覆盖旧备份的独立恢复副本，失败与回滚分别报告。
- 默认保留source/和原路径文件。只有--cleanup-source才清理本次快照；Windows在同一个独占句柄里比较文件身份与SHA-256并执行逻辑删除。无法取得这一保护的平台保留原件，不退回存在竞态的覆写删除。
执行流程
- 1
固定文件与目录范围，区分保留原库、追加与整库替换。
- 2
已有库追加时先由本人提供对应凭据，并说明只能打开相应层。
- 3
处理旧库与暂存区的同名关系，再复制本次明确新路径。
- 4
打包、压缩、加密并核对新容器可解回预期内容。
- 5
核对密文写入和读回；默认保留原件，若明确选择清理，另报实际删除、保留与未确认项。
边界
- 任意文件类型可以作为字节入库，不代表任意文件都能在内存文本界面直接阅读。
- 没有后台目录监听、全盘扫描或自动上传。
- 合并的旧库内容只在内存处理；新输入的source/仍是明文且默认保留。内存合并不等于整个程序或操作系统没有其他内存副本。
失败与恢复
- 准备区已有同名新版
- 按明确的新旧优先顺序保留预期版本，并用实际内容回归；不能只验证成员数量。
- 取消、没有输入或新库自检失败
- 返回未完成或失败，保留尚未成功提交时需要的原文与原库，不输出完成证据。
- 旧库可能含另一密码对应的层
- 菜单追加和VAULT03槽位改密保留未解锁槽位的密文字节，不声称已经打开它。共享密钥文件、容量或格式需要变化时生成新副本，不能静默覆盖未知层。
真实入口
E:\Projects\Tools\vault-tool\vault_tool.py文件枚举、相对路径打包、加密与引导式添加
E:\Projects\Tools\vault-tool\scripts\Start-KeyVaultEncrypt.ps1本地终端与 AddPath 到直接 encrypt 的真实路线
E:\Projects\Tools\vault-tool\test_vault_tool.py虚构文件往返、追加与同名内容回归
synthetic-roundtrip.json本轮虚构文件实际算法验证原始JSON；含很小的测试参数，不能作为真实资料配置建议
如何验证
- 来源独立审查分别读取了加密、合并和启动脚本，没有把三个入口混成一条。
- 本轮虚构三文件已经实际加密并取回；同名内容曾复现旧版覆盖新版，修复和后续回归结果见当前快照。
- 没有对本人真实 source/、vault.enc 或私人文件执行这些操作。
与其他模块的关系
这里决定什么进入库；密码与格式模块解释怎样打开，查看与提取模块解释怎样使用，库维护模块解释后续重建及旧库。