[Feature Request] 支持 ov cp 复制文件/目录并复用底层向量

[KCHENPENGFEI]

背景

OpenViking 当前已经支持 ls、tree、rm、mv 等文件系统操作，但缺少 cp。

在实际使用中，同一份资源（文件、图片、音视频或目录）经常需要出现在多个 viking:// 路径下。当前只能对相同源重复执行 add-resource，这会重复触发下载/上传、解析、VLM 理解、摘要生成和 embedding，不仅耗时，也会产生不必要的模型调用与计算成本。

如果资源已经被 OpenViking 完整处理过，复制其文件树、派生内容、元数据和向量记录，就可以直接得到一个可检索的副本，无需重新走资源入库流水线。

为什么值得做

以一份已经完成解析和索引的视频为例：

ov add-resource ./demo.mp4 --to viking://resources/project-a/demo.mp4
ov add-resource ./demo.mp4 --to viking://resources/project-b/demo.mp4

第二次导入会重复执行昂贵的处理步骤。更合理的方式是：

ov add-resource ./demo.mp4 --to viking://resources/project-a/demo.mp4
ov cp viking://resources/project-a/demo.mp4 \
      viking://resources/project-b/demo.mp4

cp 的收益包括：

• 避免对相同内容重复 parse、VLM 和 embedding；
• 降低大文件、图片、音视频和大型目录的复制延迟及模型成本；
• 让 OpenViking 的文件系统接口更完整，也更符合用户对 ls/tree/rm/mv/cp 的直觉；
• 为资源模板、跨项目复用、数据集分支和实验副本提供基础能力。

从当前实现看，这个方向也有较好的基础：底层 AGFS 已提供 cp，VikingFS 的 mv 已采用“复制文件树 → 更新向量 URI → 删除源”的流程，并在 URI 变化时复用已有向量而不重新 embedding。cp 需要在此基础上新增“克隆向量记录并保留源记录”的能力，而不是重新设计完整复制链路。

建议的 CLI

单文件复制

ov cp <source-uri> <destination-uri>

# 示例
ov cp viking://resources/project-a/readme.md \
      viking://resources/project-b/readme.md

目录递归复制

ov cp -r <source-directory-uri> <destination-directory-uri>

# 示例
ov cp -r viking://resources/project-a/assets \
         viking://resources/project-b/assets

建议首期行为：

• 文件使用 ov cp；
• 目录必须显式指定 -r/--recursive，否则返回错误；
• source 不存在时返回 not found；
• destination 已存在时默认拒绝，不静默覆盖；覆盖、合并目录等语义可后续单独讨论；
• 首期只支持同一 account、权限允许的 viking:// 路径之间复制。

核心语义：文件与向量一起复制

cp 不能只复制底层文件，否则目标 URI 虽然可以被 ls/read 看到，却无法得到与源一致的检索结果。

复制范围应包括：

1. 源文件或目录树中的普通文件；
2. 已生成的 .abstract.md、.overview.md 等语义派生文件；
3. 与源 URI/子树关联的元数据；
4. L0/L1/L2 等全部向量记录。

向量复制建议采用 clone 语义：

• 读取源 URI 对应的完整向量记录，包括已有 dense vector；
• 将 uri、parent_uri 以及其他路径派生字段改写为目标 URI；
• 按目标 URI 和 level 生成新的 record id；
• 复用原 vector 和语义字段写入目标记录，不调用 embedding provider；
• 保留源向量记录，不执行 mv 当前使用的源记录删除步骤。

对于目录，以上规则递归应用到整个子树。复制出的节点不应重新解析、调用 VLM 或重新 embedding。由于目标父目录新增了子项，目标路径祖先的 L0/L1 摘要可能需要走现有增量刷新机制；这类父目录刷新应与“复制子树本身无需重新处理”区分开。

一致性与失败语义

建议将文件副本和向量副本视为一次逻辑操作：

1. 校验 source、destination、权限以及 -r；
2. 对 source 子树和 destination 获取合适的路径锁；
3. 复制文件/目录树；
4. 克隆并改写向量记录；
5. 必要时刷新目标父目录语义信息；
6. 全部成功后返回。

如果向量复制失败，应清理尚未提交的目标文件和目标向量，源始终保持不变。至少需要保证操作失败后不会留下“文件存在但不可检索”或“向量存在但文件不存在”的半成品。

目录复制应考虑大规模子树，不应把全部文件内容或向量一次性加载到内存；建议分页枚举并批量复制，同时返回可观测的复制数量、向量数量和失败阶段。是否需要异步 task、进度查询和断点恢复，可以根据目录规模另行确定。

与 mv 的关系

两者可以共享大部分内部能力，但语义不同：

mv = copy files + rewrite/move vector records + delete source
cp = copy files + clone vector records + keep source

建议先抽象一个可复用的复制事务，再分别实现 mv 和 cp，避免两套文件遍历、路径锁和失败回滚逻辑逐渐分叉。

非目标（首期）

• 跨 account 或绕过现有权限边界复制；
• destination 已存在时的自动覆盖或目录合并；
• 通过 cp 重新解析、重新生成摘要或强制重新 embedding；
• 把本地路径与 viking:// 之间的上传/下载也纳入 cp；这仍由 add-resource 和 get 负责。

待讨论问题

1. destination 已存在时，首期是否统一拒绝？未来更适合 --force、--no-clobber，还是目录 merge 语义？
2. 复制内容中的绝对 viking:// 引用，应该保持指向源，还是将指向源子树内部的引用改写到目标子树？
3. 大目录复制是否应直接设计为异步 task，并支持进度、取消和失败清理？
4. 文件复制成功但目标父目录摘要刷新失败时，应整体回滚，还是返回“复制成功、语义刷新待重试”的状态？
5. 是否需要在 Python SDK 和 HTTP API 同时提供 cp(from_uri, to_uri, recursive=False)，以保证 CLI 只是薄封装？

建议的验收标准

• ov cp 能复制单文件，源文件保持不变；
• ov cp -r 能完整复制目录、空目录和全部后代节点；
• 对目录执行不带 -r 的 ov cp 会明确失败；
• 目标已存在时不会静默覆盖；
• 目标文件和目录可以正常 ls/tree/read/stat/find/search；
• 目标的 L0/L1/L2 向量与源一致，但 URI、路径派生字段和 record id 属于目标路径；
• 复制过程中不触发源内容的 parse、VLM 或 embedding；
• 失败不会破坏源，也不会留下文件/向量不一致的目标半成品；
• 覆盖单文件、深层目录、大文件、图片/视频、空目录、锁冲突和中途失败测试。