feat(ovpack): support vector snapshots and consistency checks

[qin-ctx]

Description

本 PR 是 OVPack v2 的完整后续增强，目标是把 OVPack 收敛为 OpenViking 的标准内容迁移/备份格式：包结构可校验、导入恢复可预测、路径语义无歧义，并支持在纯 dense 场景下选择性迁移向量快照。

整体改动分为三条主线：

• 包格式和导入恢复语义：OVPack v2 使用 manifest 描述 root、scope、文件/目录清单、文件 checksum、整体 content checksum、内部索引文件和可选 dense 快照。普通 export/import 保留包根并要求同 scope 导入；全量迁移使用 backup/restore，backup 包只能走 restore，不允许被普通 import 导入任意父目录。
• 向量快照能力：默认导入仍在目标环境重新向量化并重建运行态字段；显式 include_vectors=true 时可导出 pure-dense 快照。导入通过 vector_mode=auto|recompute|require 决定恢复快照或重新向量化。当前只支持纯 dense index，底层 VectorIndex.IndexType 为 hybrid 时拒绝导出向量快照。
• 数据一致性检查：新增公开的 consistency 能力，用于检查某个 URI 下按系统规则应该存在的 index record 是否已写入向量索引。这个能力不依赖 OVPack 包格式，可通过 HTTP、SDK 和 CLI 独立调用，也被 OVPack 的向量快照导出前置校验复用。

同时，本 PR 将 OVPack 包内物理结构调整为命名空间隔离：用户内容原样放在 <root>/files/ 下，OVPack 内部 manifest、index records 和可选 dense 向量快照放在 <root>/_ovpack/ 下。这样不再需要 _._ 点文件转义，也不会因为用户文件名如 .notes.txt、_._notes.txt、.ovpack/foo.txt 和内部文件路径发生碰撞。

这次 diff 看起来较大，主要是因为把原来集中在 local_fs.py 的 OVPack 逻辑拆成独立模块；对现有主流程的修改比较集中，review 时可以按下面的影响面看：

• 代码拆分：删除 openviking/storage/local_fs.py，新增 openviking/storage/ovpack/。这里是最大头，主要把 OVPack 的格式处理、manifest、导入策略、校验、index record、dense snapshot 和导入导出编排拆开，降低单文件复杂度。
• 对已有代码的改动：集中在 pack service/router/client 的参数接线，新增 include_vectors / vector_mode，并把调用入口切到 storage.ovpack.operations；核心存储行为没有在其他模块里扩散修改。
• 新增无耦合功能：openviking/storage/index_consistency.py 是独立的数据一致性检查能力，不依赖 OVPack 包格式，只复用系统索引规则检查“应该存在的 index record 是否存在”。
• SDK / CLI / API 接线：Python async/sync/local client、HTTP client、Rust CLI 增加向量快照参数和 ov system consistency <uri> 命令，主要是参数透传、请求结构和输出处理。
• 文档和测试：中英文 OVPack guide/API 文档同步包结构、参数和预期行为；测试集中覆盖 manifest/hash/scope/session/dense snapshot/hybrid 拒绝/consistency/路径碰撞的核心回归。

建议 review 顺序：先看 storage/ovpack/operations.py 理解整体流程，再看 policy.py / validation.py / vectors.py，最后看 index_consistency.py、SDK/CLI 接线和文档测试。

Related Issue

基于已合入 PR #1927 的后续增量。

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Performance improvement
• Test update

Changes Made

• 拆分 OVPack 实现：删除 openviking/storage/local_fs.py，将格式、manifest、index、policy、validation、vector snapshot 和 operations 分到 openviking/storage/ovpack/，避免所有 OVPack 逻辑继续堆在一个 local_fs 文件里。
• 增加 OVPack v2 manifest 和完整校验：manifest 记录 root URI/scope、目录/文件清单、文件 size/sha256、整体 content_sha256、内部 index 文件和可选 dense 文件的 hash/数量/维度；导入前完整校验 ZIP 成员、manifest、目录/文件集合、hash、scope、冲突策略，通过后才写入目标环境。
• 调整 OVPack ZIP 物理布局：用户内容统一放在 <root>/files/，内部元数据统一放在 <root>/_ovpack/，manifest 位于 <root>/_ovpack/manifest.json，index records 位于 <root>/_ovpack/index_records.jsonl，可选 dense 快照位于 <root>/_ovpack/dense.f32。
• 移除 _._ 点文件转义规则和用户路径保留名限制：.abstract.md、.overview.md、.meta.json、.notes.txt、_._notes.txt、.ovpack/foo.txt 等用户内容都按原相对路径保存在 files/ 下，导入时原样恢复。
• 支持普通 export/import 和全量 backup/restore：普通包保留包根导入，同 scope 导入；backup 包覆盖 resources/user/agent/session 公开 scope，只能通过 restore 恢复，不能通过普通 import 导入任意父目录。
• 增加可选 pure-dense 向量快照：index_records.jsonl 保存可迁移标量和 record 元信息，dense.f32 保存连续 little-endian float32 dense 向量；默认不导出向量。
• 明确 hybrid index 不支持向量快照：导出/备份 include_vectors=true 时只读取底层 VectorIndex.IndexType，如果包含 hybrid 直接拒绝；不再通过 embedding.hybrid、embedding.sparse、sparse_weight 或 EnableSparse 推断。
• 增加导入向量策略：vector_mode=auto|recompute|require。auto 在包内 dense 快照存在、embedding 元数据兼容且目标 index 不是 hybrid 时恢复，否则重新向量化；require 遇到缺快照、不兼容或 hybrid index 直接报错；recompute 始终重算。
• 增加公开一致性检查：POST /api/v1/system/consistency、Python SDK check_consistency(uri)、Rust CLI ov system consistency <uri>。一致性只检查“按系统规则应该有索引记录的内容是否存在 index record”，不再额外检查 missing vector。
• 修复一致性检查的 L0/L1 期望规则：只有 .abstract.md 存在时才要求 L0 index record，只有 .overview.md 存在时要求 L1，避免 overview-only 目录误报缺 L0。
• 保持运行态字段目标环境重建：id、uri、account_id、owner 字段、created_at、updated_at、active_count 不从包内恢复；即使恢复 dense 快照，也会按目标 URI、账号和当前时间重新生成。
• 同步更新 Rust CLI、HTTP client、Python async/sync/local client、service/router 接口，覆盖 export_ovpack、backup_ovpack、import_ovpack、restore_ovpack 和 consistency API。
• 系统重写中英文 OVPack guide，并同步中英文 filesystem/system API 文档，说明包结构、参数、导入策略、向量快照限制、全量备份恢复、一致性检查和常见错误。

预期行为示例：

# 默认导出不带向量，导入后重新向量化
ov export viking://resources/a ./a.ovpack
ov import ./a.ovpack viking://resources/imported/

# 显式导出 pure-dense 快照；兼容则恢复，不兼容则重算
ov export viking://resources/a ./a.ovpack --include-vectors
ov import ./a.ovpack viking://resources/imported/ --vector-mode auto

# 要求必须恢复兼容 dense 快照；没有快照、不兼容或目标 index 为 hybrid 时失败
ov import ./a.ovpack viking://resources/imported/ --vector-mode require

# 全量迁移使用 backup/restore，不用 export viking://
ov backup ./openviking-backup.ovpack --include-vectors
ov restore ./openviking-backup.ovpack --vector-mode auto --on-conflict overwrite

# 单独检查当前数据和向量索引记录是否一致
ov system consistency viking://resources/a

新 ZIP 布局示例：

my-project/
my-project/files/
my-project/files/notes.txt
my-project/files/.overview.md
my-project/files/.ovpack/foo.txt
my-project/files/_._notes.txt
my-project/_ovpack/
my-project/_ovpack/manifest.json
my-project/_ovpack/index_records.jsonl
my-project/_ovpack/dense.f32

Testing

• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I have tested this on the following platforms:
  • Linux
  • macOS
  • Windows

已执行：

.venv/bin/ruff check openviking/storage/ovpack tests/misc/test_ovpack_import_policy.py tests/client/test_import_export.py tests/server/ovpack_test_helpers.py
.venv/bin/python -m pytest tests/misc/test_ovpack_import_policy.py -q
.venv/bin/python -m pytest tests/client/test_import_export.py::TestImportOvpack::test_import_rejects_unsafe_entries -q
git diff --check

本分支此前也执行过：

cargo check -p ov_cli

结果：OVPack 核心 pytest 16 passed；client 恶意 ZIP 用例 5 passed；ruff 通过；git diff --check 通过；cargo check -p ov_cli 通过但仓库仍有既有 Rust warning，本 PR 未处理这些既有 warning。

Checklist

• My code follows the project's coding style
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• Any dependent changes have been merged and published

Screenshots (if applicable)

不适用。

Additional Notes

当前版本不支持 sparse/hybrid 向量快照。判断口径只看底层 VectorIndex.IndexType：包含 hybrid 就拒绝导出向量快照；导入时 auto 重新向量化，require 报错。这样避免把 dense-only 快照恢复到 hybrid index 后产生半迁移状态。

OVPack 尚未正式发布，因此本 PR 不为开发过程中的历史草稿包增加 fallback；当前导入只接受 current OVPack v2 manifest 和新 ZIP 布局。无 manifest 旧包仍按文档策略拒绝。

[github-actions]

PR Reviewer Guide 🔍

(Review updated until commit 79a39cf)

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis ✅ 1927 - Fully compliant Compliant requirements: OVPack v2 manifest added Pre-import validation implemented Old import parameters removed Session OVPack support added Top-level scope package support added Backup/restore capability added Export write path refactored Vector metadata migration adjusted Internal files excluded Error returns improved Docs updated Tests added

⏱️ Estimated effort to review: 4 🔵🔵🔵🔵⚪

🏅 Score: 85

🧪 PR contains tests

🔒 No security concerns identified

✅ No TODO sections

🔀 No multiple PR themes

⚡ No major issues detected

[github-actions]

PR Code Suggestions ✨

No code suggestions found for the PR.

[MaojiaSheng]

ov consistency 不建议作为一级命令

[github-actions]

Persistent review updated to latest commit 79a39cf

[github-actions]

PR Code Suggestions ✨

No code suggestions found for the PR.