OpenViking OVPack 完全指南.ovpack 资源树的导出、导入、备份与恢复【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenVikingOVPack 是 OpenViking 专为 AI Agent 上下文库设计的.ovpack归档格式用于在实例之间备份与迁移资源树resources/user 等公共作用域下的文件与索引数据。本文将围绕官方技能文档 ovpack.md 展开逐一讲解ov export、ov import、ov backup、ov restore四个命令的用法、.ovpack内部格式与校验机制并结合仓库源码openviking/storage/ovpack/说明冲突策略、向量快照、完整性校验等底层原理。读完本文你将能独立完成资源树的打包迁移、整库备份与恢复并理解 OVPack 的安全边界与适用前提。OVPack 是什么面向资源树的便携归档格式OVPackopenviking.ovpack是一个 ZIP 结构的归档格式把 OpenViking 资源树包括文件内容、目录结构、可移植的索引标量字段以及可选的稠密向量快照封装为单个.ovpack文件便于跨实例备份、迁移与分发。从源码常量可以确认其格式身份format.pyOVPACK_FORMAT_VERSION 3当前格式版本导入时会严格校验版本一致OVPACK_KIND openviking.ovpackmanifest 中的类型标识内部目录_ovpack/元数据与files/用户内容并存于同一个 ZIP 根下备份包专用标识package_type backup根名称固定为openviking-backup。权限要求执行导出、导入、备份、恢复需要 ROOT 或 ADMIN 权限。具体到 HTTP APIpack.py/api/v1/pack/export与/api/v1/pack/import允许 ROOT、ADMIN、USER 三类角色而/api/v1/pack/backup与/api/v1/pack/restore仅限 ROOT 与 ADMINpack.py。导出ov export把资源树打包为 .ovpackov export将指定 URI 下的整棵资源树导出为一个.ovpack文件。# 导出整棵资源树 ov export viking://resources/my-project/ ./exports/my-project.ovpack # 附带稠密向量快照 ov export viking://resources/my-project/ ./exports/my-project.ovpack --include-vectors命令语义与实现要点pack.rs第一参数是源 URI第二参数是输出路径目标既可以是.ovpack文件路径也可以是已存在的目录此时自动生成为目录/节点名.ovpack见 operations.py未以.ovpack结尾的输出路径会自动补全扩展名format.py--include-vectorsCLI 定义见 main.rs为布尔开关决定是否把纯稠密pure-dense向量快照写入包内。.ovpack 内部结构导出的 ZIP 以根节点名/为单一根目录可移植性要求用户内容位于root/files/元数据位于root/_ovpack/format.pyZIP 内路径说明root/files/...用户文件与目录按资源树的相对路径一一映射operations.pyroot/_ovpack/manifest.json清单条目列表含path、size、sha256、content_sha256以及root、format_version、kind等顶层字段index.pyroot/_ovpack/index_records.jsonl可移植索引标量字段每行一条 JSON 记录含record_id、path、kind、level、text、scalarsindex.pyroot/_ovpack/dense.f32纯稠密 float32 向量快照仅--include-vectors时存在小端序、连续存储vectors.pyindex_records.jsonl中可移植的标量字段在源码中固定为uri、type、context_type、level、name、description、tags、abstractindex.py这保证了资源在导入后可恢复基本的语义检索元数据。稠密向量快照与混合索引的限制当使用--include-vectors时导出前会先做索引一致性检查任何不一致都会导致导出失败operations.py避免把不完整的向量索引快照写入包内。注意混合索引hybrid index会拒绝向量快照导出vectors.py。这是因为dense.f32快照只承载纯稠密 float32 向量当当前向量索引类型为 hybrid含稀疏分量时快照无法表达完整索引语义导出会直接报错。也就是说向量快照功能面向的是纯稠密向量索引的部署形态。导入ov import恢复资源树到目标位置ov import把一个.ovpack文件恢复到指定的目标 URI 下。# 基础导入 ov import ./exports/my-project.ovpack viking://resources/imported/ # 显式指定冲突策略 ov import ./exports/my-project.ovpack viking://resources/imported/ --on-conflict overwrite # 要求必须存在兼容的稠密向量快照 ov import ./exports/my-project.ovpack viking://resources/imported/ --vector-mode require冲突策略 on-conflict取值行为fail默认目标位置已存在资源时直接失败抛出 ConflictErroroverwrite先递归删除既有根节点再写入导入内容skip目标已存在时跳过该次导入返回既有根 URI三个取值在 format.py 中定义为枚举集合缺省值归一化为failformat.py。导入时的实际分支逻辑见 operations.pyskip直接返回fail抛冲突错误并提示改用overwriteoverwrite则调用_remove_existing_root做递归删除后重建。向量模式 vector-mode取值行为auto默认快照存在且与当前 embedding 配置兼容时直接恢复快照否则回退为重新计算向量recompute忽略包内快照一律在导入后重新向量化require快照缺失、不兼容或当前索引不支持快照恢复时直接报错向量动作的决策函数choose_vector_restore_actionvectors.py依次检查索引类型是否支持快照、包内是否存在稠密快照、快照是否完整、向量库是否可写、以及embedding 配置是否与导出时一致。所谓兼容要求provider、model、input、query_param、document_param、dimensions六项元数据全部匹配vectors.py确保导入实例使用相同的 embedding 模型时才能直接复用向量。若最终采取recompute路径导入完成后会对整棵恢复树直接排队向量化_enqueue_direct_vectorizationoperations.py目录的.abstract.md/.overview.md与索引标量覆盖信息都会被用于重建索引session 命名空间则跳过向量化。导入校验流程导入并非简单解压而是先经过多道结构校验operations.py从 ZIP 成员确定根目录名base_name并强制要求所有成员路径以该根开头读取并解析manifest.json校验format_version与kindmanifest.py校验 manifest 中root.name与 ZIP 根目录一致、root.uri与用户归属一致逐条校验 manifest 条目与 ZIP 成员一一对应文件/目录均不可多、不可缺校验content_sha256与每个文件条目的size、sha256校验index_records.jsonl的条数、每条记录的sha256与记录字段校验dense.f32的sha256、维度一致性以及向量偏移的连续性validation.py。导入过程中还会做路径安全校验拒绝绝对路径、Windows 盘符、反斜杠与..穿越format.py防止恶意包在解压时逃逸出目标目录。备份ov backup整库备份公共作用域ov backup会把 OpenViking 的所有公共作用域根resources、user打包成一个restore-only的.ovpack备份包。ov backup ./backups/openviking.ovpack ov backup ./backups/openviking.ovpack --include-vectors与ov export的区别在于operations.py备份范围固定为公共作用域resources与user源码中PUBLIC_SCOPES (resources, user)见 policy.py不包含 session 等运行时数据生成包根目录固定为openviking-backupmanifest 中标记package_type backup与scopes字段备份包是restore-only的普通ov import会直接拒绝备份包必须使用ov restore或对应 restore APIpolicy.py。恢复ov restore将备份还原到原始作用域根ov restore把ov backup生成的备份包恢复到原有的公共作用域根位置。ov restore ./backups/openviking.ovpack --on-conflict overwrite ov restore ./backups/openviking.ovpack --on-conflict overwrite --vector-mode require恢复流程要点operations.py只接受标记为 backup 的包普通导出包会被拒绝operations.py冲突策略作用于作用域根viking://resources、viking://user/user_idfail/skip按根级判断overwrite对文件/目录类型不一致的既有节点先删后写session 文件恢复时不进行向量化对于 resources 与 user 作用域恢复完成后按分组排队直接向量化或恢复向量快照恢复后运行时字段id、uri、account_id、created_at、updated_at会重新生成不会沿用导出时的值。重要注意事项与边界结合文档 Important Notes 与源码实现归纳如下关键约束无 manifest 的包一律拒绝manifest.json缺失时导入/恢复直接失败并提示用当前 OVPack 格式重新导出manifest.py。内容完整性强制校验文件大小、sha256、content_sha256、index_records的 sha256、dense.f32的 sha256 与偏移连续性都会逐一核验validation.py任何不匹配都会中止操作。运行时字段导入时重新生成id、uri、account_id、created_at、updated_at属于运行时状态不会也不应跨实例迁移。顶层作用域包只能导入到viking://例如viking://resources/整作用域的包必须导入到viking://根反之普通资源树包不允许导入到viking://policy.py。备份包不能走普通导入ov import遇到 backup 包会报错提示改用ov restoreoperations.py 对应的 policy 判定。混合索引不支持向量快照无论是导出--include-vectors还是--vector-mode require在 hybrid 索引下都会失败vectors.py。备份/恢复仅限 ROOT 与 ADMIN导出/导入允许 USER 角色pack.py。底层调用链与 HTTP APIov命令行Rust 实现通过 HTTP 客户端调用服务端 pack 接口client.rs 中的export_ovpack/import_ovpack/backup_ovpack/restore_ovpack服务端路由定义于 pack.py命令HTTP 端点角色限制ov exportPOST /api/v1/pack/exportROOT / ADMIN / USERov importPOST /api/v1/pack/importROOT / ADMIN / USERov backupPOST /api/v1/pack/backupROOT / ADMINov restorePOST /api/v1/pack/restoreROOT / ADMIN导入/恢复端点接收temp_file_id先经/api/v1/resources/temp_upload上传获得服务端消费后即清理临时文件pack.py。CLI 侧的导出、备份命令实现在 pack.rs命令行参数--include-vectors、--on-conflict、--vector-mode的定义见 main.rs。仓库自带的 CLI 集成测试覆盖了导出/导入主流程ov export URI TO后ov import FILE URI --forcetest_ov.sh可作为验证本机 OVPack 功能是否正常的快速手段。总结与适用场景OVPack 为 OpenViking 提供了四层能力单资源树迁移ov export/ov import适合把某个项目资源从 A 实例搬到 B 实例或作为资源快照归档整库备份ov backup/ov restore适合对公共作用域做周期性全量备份与灾难恢复向量数据保留通过--include-vectors与--vector-mode精确控制是否携带稠密向量快照在 embedding 配置一致的前提下可免去重新向量化的开销安全与完整性严格的 manifest、哈希校验与路径安全校验让.ovpack可以放心地跨实例传递。使用前请确认账号具备 ROOT/ADMIN 权限备份/恢复必须、向量索引为纯稠密类型若需向量快照、目标实例的 embedding 配置与导出实例一致若需直接恢复快照。如需查看 OVPack 相关的其他技能文档可继续阅读 ov-resources/docs 下的 filesystem.md、add-resource.md、search.md 等。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考