ADR-0007：现有归档的安全更新

状态

接受，2026-08-31。该能力在 0.1.9 候选中由核心 API、CLI、Worker 和两套桌面 UI 共同接入。

背景

用户需要从归档浏览页把新文件或文件夹加入现有归档，也需要删除已选归档条目。ZIP 和 7z 没有在当前 Provider 边界内提供可复用的原地追加或删除抽象；TAR 组合也需要重新写出外层流。直接覆盖原文件会让编码失败、取消或磁盘错误留下不可用归档。

决策

• 只对 ZIP、7z 和 TAR-family 多项目容器公开更新；gzip、Zstandard、XZ、LZMA、Bzip2、LZ4、Brotli 是单文件流，RAR/CAB 支持创建但不支持更新或重命名。
• 核心先完整列出并安全解包原归档到原文件同目录的临时工作区，再按来源根目录合并新增项，或按归档相对路径删除所选条目及其后代；同名普通文件覆盖，文件/目录类型冲突拒绝，链接和 reparse point 拒绝。
• 合并后重新应用同一组安全限制、密码、取消令牌和进度通道，完整重建归档；任何阶段失败或取消都不触碰原文件。
• 重建成功后使用平台原子替换语义提交：Windows 使用 MoveFileExW 的 replace/write-through 标志，其他平台使用 rename。临时工作区由 RAII 清理，不作为发布资产。
• UI 只依据 ArchiveFormat::supports_update() 显示更新操作；CLI 和 Worker 对不支持格式返回明确的 UnsupportedOperation，不静默尝试其他编码器。

取舍与后续

这种方案需要完整解包和重建，速度和临时磁盘占用都不等同于专用归档编辑器的增量更新，但实现边界统一、可测试，并保留原文件的失败安全性。未来若引入真正的增量 Provider，必须保留相同的原子提交、限制、取消和链接拒绝契约，并增加独立互操作证据。