[Feature Request] ov get 支持可恢复的目录逐文件下载

[KCHENPENGFEI]

背景

当前 ov get <uri> <local-path> 只支持下载单个文件。需要下载目录时，用户只能先枚举文件，再逐个执行 ov get，或者使用语义不同的 .ovpack 导入导出流程。

更重要的是，当前单文件下载链路本身还不是端到端流式的：服务端会把文件完整读取为 bytes，CLI 也会把整个响应读取为 Vec<u8> 后再写入本地。因此，即使只下载一个超大文件，也存在服务端或客户端 OOM 的风险。

目录可能达到 TB 级，并包含数百万个文件。将目录动态打包成一个流式 ZIP 虽然能降低内存和临时磁盘占用，但无法可靠解决断点续传、单文件重试、长连接超时、服务重启以及下载期间目录变化等问题，不适合作为目录下载的默认方案。

本提案建议：

1. 先把单文件下载改造成端到端分块流式、可校验、可断点续传；
2. 再由 CLI 通过可分页 Manifest 编排目录内的普通文件下载请求；
3. 一个文件失败时只重试该文件，重新执行命令时可以继续未完成的下载；
4. 目录下载必须将指向本次下载集合的 viking:// 引用改写为本地相对路径，确保下载结果可在本地直接使用。

建议的命令形式

# 单文件：保持现有命令形式
ov get viking://resources/project/video.mp4 ./video.mp4

# 目录：自动识别目标类型，下载为本地目录
ov get viking://resources/project/assets ./assets/

• 不新增 --recursive；ov get 自动识别远端目标是文件还是目录。
• 下载目录时必须显式提供本地目录，避免默认 ZIP、默认解压目录等隐式行为。
• 单文件的最终目标已存在时继续拒绝覆盖。
• 目录重试时允许目标目录已存在，但只恢复由匹配 checkpoint 管理的下载；遇到未受管理的同名文件或内容冲突时返回错误，不静默覆盖。

为什么不采用目录默认 ZIP

对于 1TB 目录，即使 ZIP 是真正流式生成的，仍有以下风险：

• 动态生成的 ZIP 通常无法从中间可靠续传，连接中断后需要重新生成和下载；
• ZIP 中央目录位于文件尾部，未完成的 .zip.part 通常不可正常使用；
• 一个请求可能持续数小时或数天，容易受到网关超时、服务重启和负载均衡切换影响；
• 单个文件失败会导致整个归档失败，无法只重试失败文件；
• 下载期间目录变化时，归档可能混合多个时间点的内容；
• 海量小文件会带来大量归档元数据和服务端状态管理成本；
• 下载内容中的 viking:// 引用改写需要知道完整导出集合，会进一步增加状态和一致性复杂度。

因此，ZIP 可以作为未来针对中小目录的显式便利功能，或由后台任务生成稳定对象后通过 Range 下载，但不作为本提案的默认模式或首期范围。

第一阶段：单文件端到端流式下载

服务端

扩展现有单文件下载接口，使其具备：

• 从存储层按固定大小分块读取，不把完整文件加载到内存；
• 支持 Range 请求；
• 返回 Accept-Ranges: bytes、Content-Length、ETag；
• Range 请求返回 206 Partial Content 和正确的 Content-Range；
• 支持 If-Match，当文件版本变化时返回 412 Precondition Failed；
• 保持现有权限检查和路径可见性规则。

底层 AGFS 已支持 offset、size 和流式读取，可作为实现基础，但 HTTP 层和 CLI 目前尚未暴露这条能力。

CLI

• 将响应分块写入同目录下的临时文件，例如 video.mp4.part；
• 在 sidecar/checkpoint 中记录 URI、ETag、预期大小、已完成偏移和 checksum 信息；
• 重试时只有在 URI 和 ETag 匹配的情况下才从 .part 当前长度继续；
• 下载完成后校验大小和 checksum，再原子 rename 为最终文件；
• 网络失败、进程退出或服务端重启后保留可恢复状态；
• 最终目标文件已存在时不覆盖。

第二阶段：Manifest 驱动的目录下载

可分页 Manifest

目录下载开始时，CLI 调用 Manifest 接口，按稳定 cursor 分页取得目录内容。每个条目至少包含：

• relative_path；
• 类型：文件或目录；
• 文件大小；
• ETag 或不可变内容版本；
• checksum；
• 空目录信息。

Manifest 必须绑定稳定的目录视图或 snapshot token。后续分页和文件下载都应引用同一个 snapshot，避免目录变化造成文件重复、遗漏或内容版本不一致。

如果某个后端暂时无法提供目录快照，只能降级为明确标记的 best-effort 模式：每个文件仍使用 ETag/If-Match 校验，发生变化时报告具体文件，不能静默下载不同版本。

Manifest 只返回调用方有权访问且对调用方可见的内容，不包含 .path.ovlock、临时锁和其他运行时内部文件。

CLI 编排

• Manifest 分页结果增量写入本地 checkpoint，不能要求百万条记录全部驻留内存；
• 大规模任务建议使用 SQLite 等可增量查询的本地状态，而不是一个巨大的内存对象或 JSON 文件；
• 为每个文件调用第一阶段的普通文件下载接口；
• 默认使用有限并发，例如 4，可在合理范围内配置；
• 单文件失败只重试该文件；
• 已完成且 checksum 匹配的文件直接跳过；
• 重新执行同一命令时，从 checkpoint 恢复未完成文件；
• 所有原始文件下载并通过源 checksum 校验后，进入引用改写阶段；
• 所有支持文本文件完成 viking:// 引用改写后，才提交目录下载完成状态。

对于百万级小文件，可以在后续评估 HTTP/2 连接复用、小文件批次或可恢复分片对象，但不使用一个不可恢复的超长 multipart/mixed 响应承载整个目录。

本地路径安全

目录下载必须在写入前验证每个 Manifest 相对路径，包括：

• 拒绝 ..、绝对路径、反斜杠逃逸和空路径；
• 防止已有符号链接或下载期间路径被替换导致目录逃逸；
• 处理大小写不敏感文件系统上的路径碰撞；
• 检测 Unicode 规范化碰撞；
• 检测文件与目录同名冲突；
• 兼容或明确拒绝 Windows 保留文件名；
• 所有文件使用 .part 和原子 rename，不直接覆盖最终路径。

下载前应汇总预期总大小和文件数，并在本地磁盘容量明显不足时尽早失败；实际下载仍需处理配额变化和写盘失败。

viking:// 引用改写

单文件下载保持原始内容，不要求改写引用；目录下载则必须改写。目录已经脱离 OpenViking 运行环境，本地文件中的 viking:// URI 无法直接使用，只有指向同一下载集合的本地相对路径才有意义。因此，引用改写是目录下载的完成条件，而不是可选增强。

改写在所有原始文件下载并通过源 checksum 校验后执行：

1. checkpoint/本地索引保存 viking_uri -> relative_path 映射；
2. 仅改写 Manifest 中实际下载成功的目标，且相对路径以引用所在文件的目录为基准；
3. 覆盖 Markdown 普通链接、图片链接以及其他能够安全识别的受支持文本引用；
4. 按支持的文本格式和链接语法进行结构化处理，跳过二进制文件、代码块和行内代码，不做无差别字符串替换；
5. 子树外、无权限或未下载的目标保持原始 viking:// URI，避免生成无效本地链接；
6. 正确处理嵌套目录、中文或空格文件名、URI 编码、查询参数和 #fragment；
7. 改写只影响本地副本，不修改 OpenViking 中的源文件；
8. checkpoint 分别记录 downloaded_verified 和 references_rewritten 状态，因为改写后的本地内容不再匹配源 checksum；
9. 改写中断或失败时，目录任务保持未完成，重新执行命令从 checkpoint 继续改写，不重新下载已校验文件。

完整映射应保存在 SQLite 等可增量查询的本地状态中，不能要求百万级 URI 全部驻留内存。只有所有支持文本文件完成改写后，目录任务才能进入 completed 状态。

与 ov export 的关系

ov get 面向用户可直接使用的普通文件和目录；ov export/.ovpack 面向 OpenViking 数据迁移和恢复，两者语义保持独立。

当前 .ovpack 下载同样存在完整响应缓冲问题。在完成流式生成、稳定对象和 Range/续传能力之前，不应把 ov export 视为 TB 级目录下载的替代方案。

非目标

首期不包含：

• 目录默认 ZIP；
• --recursive；
• 在一个 multipart/mixed 响应中连续传输整个目录；
• 静默覆盖本地已有文件；
• 将 .ovpack 作为普通目录下载格式。

建议的实施顺序

1. 单文件服务端分块读取和 HTTP Range/ETag/If-Match；
2. CLI .part、checkpoint、断点续传、校验和原子提交；
3. 稳定且可分页的目录 Manifest/snapshot；
4. CLI 目录重建、有限并发、逐文件重试和恢复；
5. 目录下载完成前执行强制的本地 viking:// 引用改写，并支持从 checkpoint 恢复；
6. 根据实际需求另行评估显式归档模式。

验收标准

单文件下载

• 服务端和 CLI 的内存占用不随文件总大小线性增长；
• 正确支持完整请求和合法/非法/越界 Range；
• ETag 不匹配时拒绝继续下载；
• 中断后能够从已验证偏移继续；
• 完成前只存在 .part，校验成功后原子提交；
• 不覆盖已有最终文件；
• 覆盖大文件、空文件、二进制文件、网络中断和服务重启测试。

目录下载

• ov get 自动识别目录，不需要 --recursive；
• 目录下载到显式指定的本地目录，而不是 ZIP；
• Manifest 支持稳定分页，并绑定 snapshot 或明确的内容版本；
• 正确保留嵌套目录、空目录、二进制文件和 UTF-8 文件名；
• checkpoint 不要求完整目录集合驻留内存；
• 单文件失败只重试该文件，重新执行命令可以继续；
• 已完成且校验一致的文件能够跳过；
• 下载集合内部的 viking:// 引用必须改写为正确的本地相对路径；
• 子树外、无权限或未下载的 URI 保持原样；
• 改写失败时任务不进入完成状态，重新执行能够从改写阶段继续；
• 正确处理 Markdown 链接、图片、嵌套目录、UTF-8/空格路径、URI 编码和 fragment，并跳过二进制与代码块；
• 限制并发，不因海量文件压垮服务端或本地磁盘；
• 不泄露内部文件或无权限内容；
• 覆盖路径穿越、符号链接逃逸、路径碰撞、目录变化、本地冲突和磁盘不足测试。