OpenViking 多版本管理快照实战指南从 git 配置到 commit/restore掌握基于 Git 的资源版本控制【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking本文基于 OpenViking 官方的多版本管理快照指南完整讲解如何启用、配置和使用快照能力ov.conf中的git配置段local 与 S3 两种后端、工作区.ovgit目录的内部结构、commit/log/show/restore 三种调用方式Python SDK、CLI、HTTP API的最小可用流程以及.ovgitignore排除规则语法。读完本文你可以在不执行任何原生git命令的前提下把账号资源树保存为不可变快照、回溯历史并恢复到任意历史状态。工作原理VikingFS 之上的内嵌 Git 层多版本管理在 VikingFS 之上提供基于 Git 的commit/log/show/restore原语把账号下的资源树保存成一系列不可变快照支持随时回溯历史、对比版本并把工作区恢复到任意历史状态。其底层由内嵌在 Rust RAGFS 层的 gitoxide 驱动以account_id为粒度维护一个逻辑 Git 仓库每个账号一个仓库对调用方完全透明——你无需手动执行任何git命令。从源码结构看该能力的实现分布在Rust 侧的 git 模块crates/ragfs/src/git/其中 config.rs 定义git配置段的解析结构与默认值ignore.rs 实现.ovgitignore的解析与校验Python 服务侧的 HTTP 路由openviking/server/routers/snapshot.py路由前缀为/api/v1/snapshot端到端示例与测试examples/snapshot/包含 SDK、CLI、HTTP 三种方式的完整脚本。完整命令参数与响应结构参考 多版本管理 API。前置条件已有可用的ov.conf。已确认资源的读写正常多版本管理建立在文件系统资源之上。如果选择 S3 后端存放 Git 对象已准备好 bucket、region、endpoint 和访问凭据。启用多版本管理多版本管理默认开启git.enabled默认为true。Git 对象的存储后端可以选择local本地文件系统或s3S3 兼容对象存储当不显式设置git.backend时会自动继承storage.agfs.backendstorage.agfs.backend为memory时映射为local。如需关闭多版本管理把git.enabled设为false即可。从源码结构看config.rs 中的GitConfig是这些字段的最终解析目标backend未提供时解析为localdefault_branch默认main提交者信息未配置时由 Rust 层兜底源码默认值为openviking-bot/botopenviking.locals3.prefix默认.ovgitcas_mode默认native。此外该结构还包含一个文档未重点展开的tuning调优段提供两个默认开启的提交加速开关commit_index_enabled基于size/mtime_ns与上次提交索引比对跳过未变化文件的读取与 SHA-1 计算与blob_exists_precheck_enabled写入 blob 前做存在性预检避免重复的对象写入——从注释看二者只影响提交性能与后端调用次数不改变提交结果。本地后端推荐用于单机部署{ storage: { workspace: ./data }, git: { enabled: true, backend: local, default_branch: main, author_name: viking-bot, author_email: botviking.local, local: { base_dir: } } }配置说明字段默认值说明git.enabledtrue是否启用多版本管理。设为false可关闭快照功能git.backend继承storage.agfs.backendGit 对象后端local或s3。不显式设置时继承storage.agfs.backendmemory映射为localgit.default_branchmain未显式指定时使用的默认分支名git.author_nameviking-bot调用方未传author_name时使用的默认提交者名字git.author_emailbotviking.local默认提交者邮箱git.local.base_dirGit 对象/引用的存放目录。留空时默认使用{storage.workspace}/.ovgit通常把git.local.base_dir留空即可让快照数据自动落在工作区下的.ovgit目录便于和资源数据一起备份与迁移。S3 后端推荐用于分布式/云端部署把 Git 对象与引用存到 S3 兼容对象存储如火山引擎 TOS、MinIO、AWS S3。当backend为s3时必须提供git.s3段且bucket、region不能为空。提示git.s3的bucket、region、endpoint、access_key、secret_key在未显式设置时会自动继承storage.agfs.s3的对应字段。因此当storage.agfs已经配置为 s3 后端时通常无需重复填写git.s3——只要不显式设置git.backend多版本管理会直接复用storage.agfs的 bucket 与访问凭据。{ storage: { workspace: ./data }, git: { enabled: true, backend: s3, default_branch: main, author_name: viking-bot, author_email: botviking.local, s3: { bucket: your-tos-bucket, region: cn-beijing, endpoint: https://tos-s3-cn-beijing.volces.com, access_key: your-volcengine-ak, secret_key: your-volcengine-sk, prefix: .ovgit, use_path_style: false, cas_mode: native } } }配置说明字段默认值说明git.s3.bucket继承storage.agfs.s3.bucket存放 Git 对象/引用的 bucket必填可由storage.agfs.s3继承git.s3.region继承storage.agfs.s3.region否则us-east-1bucket 所在区域必填git.s3.prefix.ovgit键前缀所有数据存放在{prefix}/{account}/...下git.s3.endpoint继承storage.agfs.s3.endpoint否则自定义 S3 端点MinIO/TOS 等标准 AWS S3 留空git.s3.access_key/git.s3.secret_key继承storage.agfs.s3对应字段否则null直接读取的凭据留空则走 SDK 默认凭据链git.s3.use_path_styletruetrue用 path-style 寻址MinIO 等false用 virtual-host 寻址TOS 等git.s3.cas_modenative引用 CAS 模式。native使用 S3 条件写If-Match修改配置后重启 OpenViking 服务或重新初始化 SDK 客户端使其生效。仓库中提供了可直接参考的完整配置示例含 embedding、vlm、server 配置ov.conf.git-local.example 与 ov.conf.git-s3-tos.example。目录结构变化.ovgit目录启用local后端且base_dir留空时OpenViking 会在工作区下新增一个.ovgit目录用于存放 Git 对象和引用data/ # storage.workspace ├── viking/ # 用户可见的资源树viking:// 映射到这里 │ └── ... └── .ovgit/ # 多版本管理数据新增 └── {account_id}/ # 每个账号一个逻辑 Git 仓库 ├── objects/ # Git 对象commit/tree/blob标准 fanout 布局 aa/bb... ├── refs/ │ └── heads/ │ └── main # 分支引用内容为 40 位十六进制 OID └── HEAD # 当前分支指针内容为 ref: refs/heads/main要点.ovgit是内部数据目录不会通过viking://暴露用户在文件系统 APIls/read等中看不到也无法修改它。它与 Git 的标准对象库布局一致内容寻址的objects/、loose 引用的refs/但由 OpenViking 自动管理无需也不应手动运行git命令去操作它。备份或迁移工作区时把.ovgit一并复制即可保留完整的版本历史。选择s3后端时不会创建本地.ovgit目录数据改为存放在 bucket 的{prefix}/{account}/...键下。使用方法启用后Python SDK、CLI、HTTP API 三种调用方式都会出现快照相关命令。下面以一个提交 → 修改 → 恢复的最小流程演示更完整的端到端脚本可参考 examples/snapshot/snapshot_example.pySDK、snapshot_cli_test.pyCLI与 snapshot_http_api_test.pyHTTP。Python SDK快照方法挂在client.snapshot.*命名空间下。from openviking_sdk import SyncHTTPClient client SyncHTTPClient(urlhttp://localhost:1933, api_keyyour-key) client.initialize() root viking://resources/my_project # 1. 写入初始内容并提交 v1 client.write( urif{root}/guide.md, content# Guide\n\nv1 content\n, modecreate, waitTrue, ) v1 client.snapshot.commit(messagev1 initial import) print(v1:, v1[commit_oid]) # 2. 修改后再提交 v2 client.write( urif{root}/guide.md, content# Guide\n\nv2 content\n, modereplace, waitTrue, ) v2 client.snapshot.commit(messagev2 update) # 3. 查看历史 for c in client.snapshot.log(limit10): print(c[oid][:8], c[message]) # 4. 查看某个提交的元数据 print(client.snapshot.show(v1[commit_oid])[message]) # 5. 把工作区恢复到 v1会在 v2 之上生成一个新的“正向”提交 client.snapshot.restore(project_dirroot, source_commitv1[commit_oid], messagerestore to v1) client.close()CLICLI 子命令位于ov snapshot下# 提交当前工作区状态 ov snapshot commit -m v1 initial import -o json # 回溯历史最新在前 ov snapshot log --limit 10 -o json # 查看提交元数据 ov snapshot show commit_oid -o json # 读取某个提交中的文件内容默认输出到 stdout可用 --out-file 写入本地文件 ov snapshot show commit_oid --path viking://resources/my_project/guide.md --out-file ./guide.md # 把目录恢复到某个历史快照位置参数依次为 source_commit project_dir ov snapshot restore commit_oid viking://resources/my_project -m restore to v1 -o json # 先预演确认会改动哪些文件 ov snapshot restore commit_oid viking://resources/my_project --dry-run -o jsonHTTP API# 提交 curl -X POST http://localhost:1933/api/v1/snapshot/commit \ -H Content-Type: application/json \ -H X-API-Key: your-key \ -d {message: v1 initial import} # 回溯历史 curl -X GET http://localhost:1933/api/v1/snapshot/log?branchmainlimit10 \ -H X-API-Key: your-key # 查看提交元数据 curl -X GET http://localhost:1933/api/v1/snapshot/show?target_refcommit_oid \ -H X-API-Key: your-key # 恢复 curl -X POST http://localhost:1933/api/v1/snapshot/restore \ -H Content-Type: application/json \ -H X-API-Key: your-key \ -d {project_dir: viking://resources/my_project, source_commit: commit_oid, message: restore to v1}补充diff 命令除上述四个原语外快照 API 还提供diff命令用于以 unified diff 格式对比某个 UTF-8 文件在两个快照中的内容ov snapshot diff viking://resources/my_project/guide.md \ --from 3f2a1b9c \ --to 9a0b1c2dHTTP 对应GET /api/v1/snapshot/diff?path{uri}from{old_ref}to{new_ref}SDK 对应client.snapshot.diff(path, from_ref..., to_ref...)。省略from_ref时旧版本按空文件处理可用来查看文件的初始版本响应中的change_type为added/deleted/modified/unchanged之一。完整的参数、响应结构与大小限制单侧文件上限 10 MiB / 100,000 行diff 上限 20 MiB见 多版本管理 API。重要语义正向恢复restore采用正向恢复forward-commit它读取source_commit的内容把差异写回工作区并在当前 HEAD 之上生成一个新的提交。因此新提交的父提交是恢复操作发生前的 HEAD不是source_commit。API 文档中的响应示例也印证了这一点applied响应里的parent_commit等于恢复前的旧 HEADHEAD 始终单调向前推进历史永远不会被改写或丢失——回到旧版本本身也是一次新的提交restore只影响project_dir省略时为整棵账号树范围内的文件范围之外的文件保持不变当来源与当前状态字节级一致、无需改动时restore返回noop且不生成新提交dry_runtrue时只返回to_write/to_delete/unchanged计划差异不做任何写入。使用.ovgitignore排除文件账号根目录下的.ovgitignore是一个账号级的排除规则文件作用类似根.gitignore匹配该规则的文件在commit时被排除出快照。它与系统内置的剪枝规则_system、tasks、向量索引派生文件等叠加生效。要点规则文件本身不会被.ovgitignore规则忽略即使规则匹配.ovgitignore也会被正常纳入快照——这样规则的变更可追溯、可恢复。规则只影响commitrestore、show、log仍以提交内容为准不把当前.ovgitignore当作过滤器。因此恢复一个历史快照时即便其中某些文件匹配当前规则仍会被正常恢复。若某个文件在更早的提交中已被跟踪、之后新增规则匹配到它下一次commit会把它从新快照中移除工作区的文件本身不受影响。.ovgitignore不会进入向量索引/检索。规则语法.ovgitignore为 UTF-8 文本支持常见的 glob 子集空行被忽略。首个非空白字符为#的行是注释。行首/行尾空白会被裁剪。不支持!取反出现会让commit失败并报错。不支持Git 风格的反斜杠转义。文件大小上限 64 KiB。匹配路径使用账号相对的 Git 树路径/分隔如resources/proj/a.log。例如*.log匹配任意深度的.log文件build/匹配名为build的目录及其内容/cache/**仅匹配账号根下的cache/。管理命令SDK / CLI / HTTP# 写入规则 client.snapshot.set_gitignore(content*.log\n) # 读取不存在时返回空字符串 print(client.snapshot.get_gitignore()) # 删除不存在也视为成功幂等 client.snapshot.delete_gitignore()随后提交时匹配规则的文件会被排除响应里的ignored字段给出本次被排除的候选路径数系统内置剪枝不计入v client.snapshot.commit(messagewith ignore) print(v[result], v.get(ignored)) # created, 1CLI 对应子命令# 设置用 --content 直接传内容或用 --file 从文件读取 ov snapshot ignore-set --content *.log -o json ov snapshot ignore-set --file ./my-rules -o json # 读取-o json 返回 {result: 内容}不加 -o json 时直接把内容打到 stdout ov snapshot ignore-get -o json # 删除幂等 ov snapshot ignore-delete -o jsonHTTP API# 读取 curl -X GET http://localhost:1933/api/v1/snapshot/ignore \ -H X-API-Key: your-key # 写入 curl -X PUT http://localhost:1933/api/v1/snapshot/ignore \ -H Content-Type: application/json \ -H X-API-Key: your-key \ -d {content: *.log\n} # 删除 curl -X DELETE http://localhost:1933/api/v1/snapshot/ignore \ -H X-API-Key: your-key注意事项与错误处理修改git配置后必须重启服务 / 重新初始化客户端才能生效。启用s3后端时git.s3.bucket与git.s3.region为必填项缺失会导致初始化失败。恢复操作如涉及向量副作用写入/删除文件响应会返回一个task_id可通过GET /api/v1/tasks/{task_id}轮询后台向量重建进度参见 系统指南 与 API 概览。examples/snapshot/snapshot_example.py 中演示了对该task_id的轮询等待逻辑建议在 restore 后等待任务完成再执行检索。.ovgitignore内容过大超过 64 KiB或包含!取反、反斜杠转义等不支持语法时commit会失败并报invalid operation错误写入时set_gitignore会预先校验大小。不要手动用外部git工具去操作.ovgit目录它由 OpenViking 维护。快照 API 的常见错误场景见 多版本管理 API 的错误处理表场景HTTP 状态码错误码分支/提交不存在或show的path在该提交中不存在404NOT_FOUND未传入必要的操作范围或当前身份缺少对应 ACL 权限403PERMISSION_DENIED恢复期间分支被并发提交改写CAS 冲突409CONFLICT.ovgitignore过大、非 UTF-8或包含不支持的语法commit时校验400INVALID_ARGUMENT请求体包含未知字段400INVALID_ARGUMENT相关文档多版本管理 APIcommit/log/show/diff/restore及 ignore 管理命令的完整参数与响应参考配置说明ov.conf完整配置项多写存储指南资源数据的多后端复制【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenViking 多版本管理（快照）实战指南：从 git 配置到 commit/restore，掌握基于 Git 的资源版本控制
OpenViking 多版本管理快照实战指南从 git 配置到 commit/restore掌握基于 Git 的资源版本控制【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking本文基于 OpenViking 官方的多版本管理快照指南完整讲解如何启用、配置和使用快照能力ov.conf中的git配置段local 与 S3 两种后端、工作区.ovgit目录的内部结构、commit/log/show/restore 三种调用方式Python SDK、CLI、HTTP API的最小可用流程以及.ovgitignore排除规则语法。读完本文你可以在不执行任何原生git命令的前提下把账号资源树保存为不可变快照、回溯历史并恢复到任意历史状态。工作原理VikingFS 之上的内嵌 Git 层多版本管理在 VikingFS 之上提供基于 Git 的commit/log/show/restore原语把账号下的资源树保存成一系列不可变快照支持随时回溯历史、对比版本并把工作区恢复到任意历史状态。其底层由内嵌在 Rust RAGFS 层的 gitoxide 驱动以account_id为粒度维护一个逻辑 Git 仓库每个账号一个仓库对调用方完全透明——你无需手动执行任何git命令。从源码结构看该能力的实现分布在Rust 侧的 git 模块crates/ragfs/src/git/其中 config.rs 定义git配置段的解析结构与默认值ignore.rs 实现.ovgitignore的解析与校验Python 服务侧的 HTTP 路由openviking/server/routers/snapshot.py路由前缀为/api/v1/snapshot端到端示例与测试examples/snapshot/包含 SDK、CLI、HTTP 三种方式的完整脚本。完整命令参数与响应结构参考 多版本管理 API。前置条件已有可用的ov.conf。已确认资源的读写正常多版本管理建立在文件系统资源之上。如果选择 S3 后端存放 Git 对象已准备好 bucket、region、endpoint 和访问凭据。启用多版本管理多版本管理默认开启git.enabled默认为true。Git 对象的存储后端可以选择local本地文件系统或s3S3 兼容对象存储当不显式设置git.backend时会自动继承storage.agfs.backendstorage.agfs.backend为memory时映射为local。如需关闭多版本管理把git.enabled设为false即可。从源码结构看config.rs 中的GitConfig是这些字段的最终解析目标backend未提供时解析为localdefault_branch默认main提交者信息未配置时由 Rust 层兜底源码默认值为openviking-bot/botopenviking.locals3.prefix默认.ovgitcas_mode默认native。此外该结构还包含一个文档未重点展开的tuning调优段提供两个默认开启的提交加速开关commit_index_enabled基于size/mtime_ns与上次提交索引比对跳过未变化文件的读取与 SHA-1 计算与blob_exists_precheck_enabled写入 blob 前做存在性预检避免重复的对象写入——从注释看二者只影响提交性能与后端调用次数不改变提交结果。本地后端推荐用于单机部署{ storage: { workspace: ./data }, git: { enabled: true, backend: local, default_branch: main, author_name: viking-bot, author_email: botviking.local, local: { base_dir: } } }配置说明字段默认值说明git.enabledtrue是否启用多版本管理。设为false可关闭快照功能git.backend继承storage.agfs.backendGit 对象后端local或s3。不显式设置时继承storage.agfs.backendmemory映射为localgit.default_branchmain未显式指定时使用的默认分支名git.author_nameviking-bot调用方未传author_name时使用的默认提交者名字git.author_emailbotviking.local默认提交者邮箱git.local.base_dirGit 对象/引用的存放目录。留空时默认使用{storage.workspace}/.ovgit通常把git.local.base_dir留空即可让快照数据自动落在工作区下的.ovgit目录便于和资源数据一起备份与迁移。S3 后端推荐用于分布式/云端部署把 Git 对象与引用存到 S3 兼容对象存储如火山引擎 TOS、MinIO、AWS S3。当backend为s3时必须提供git.s3段且bucket、region不能为空。提示git.s3的bucket、region、endpoint、access_key、secret_key在未显式设置时会自动继承storage.agfs.s3的对应字段。因此当storage.agfs已经配置为 s3 后端时通常无需重复填写git.s3——只要不显式设置git.backend多版本管理会直接复用storage.agfs的 bucket 与访问凭据。{ storage: { workspace: ./data }, git: { enabled: true, backend: s3, default_branch: main, author_name: viking-bot, author_email: botviking.local, s3: { bucket: your-tos-bucket, region: cn-beijing, endpoint: https://tos-s3-cn-beijing.volces.com, access_key: your-volcengine-ak, secret_key: your-volcengine-sk, prefix: .ovgit, use_path_style: false, cas_mode: native } } }配置说明字段默认值说明git.s3.bucket继承storage.agfs.s3.bucket存放 Git 对象/引用的 bucket必填可由storage.agfs.s3继承git.s3.region继承storage.agfs.s3.region否则us-east-1bucket 所在区域必填git.s3.prefix.ovgit键前缀所有数据存放在{prefix}/{account}/...下git.s3.endpoint继承storage.agfs.s3.endpoint否则自定义 S3 端点MinIO/TOS 等标准 AWS S3 留空git.s3.access_key/git.s3.secret_key继承storage.agfs.s3对应字段否则null直接读取的凭据留空则走 SDK 默认凭据链git.s3.use_path_styletruetrue用 path-style 寻址MinIO 等false用 virtual-host 寻址TOS 等git.s3.cas_modenative引用 CAS 模式。native使用 S3 条件写If-Match修改配置后重启 OpenViking 服务或重新初始化 SDK 客户端使其生效。仓库中提供了可直接参考的完整配置示例含 embedding、vlm、server 配置ov.conf.git-local.example 与 ov.conf.git-s3-tos.example。目录结构变化.ovgit目录启用local后端且base_dir留空时OpenViking 会在工作区下新增一个.ovgit目录用于存放 Git 对象和引用data/ # storage.workspace ├── viking/ # 用户可见的资源树viking:// 映射到这里 │ └── ... └── .ovgit/ # 多版本管理数据新增 └── {account_id}/ # 每个账号一个逻辑 Git 仓库 ├── objects/ # Git 对象commit/tree/blob标准 fanout 布局 aa/bb... ├── refs/ │ └── heads/ │ └── main # 分支引用内容为 40 位十六进制 OID └── HEAD # 当前分支指针内容为 ref: refs/heads/main要点.ovgit是内部数据目录不会通过viking://暴露用户在文件系统 APIls/read等中看不到也无法修改它。它与 Git 的标准对象库布局一致内容寻址的objects/、loose 引用的refs/但由 OpenViking 自动管理无需也不应手动运行git命令去操作它。备份或迁移工作区时把.ovgit一并复制即可保留完整的版本历史。选择s3后端时不会创建本地.ovgit目录数据改为存放在 bucket 的{prefix}/{account}/...键下。使用方法启用后Python SDK、CLI、HTTP API 三种调用方式都会出现快照相关命令。下面以一个提交 → 修改 → 恢复的最小流程演示更完整的端到端脚本可参考 examples/snapshot/snapshot_example.pySDK、snapshot_cli_test.pyCLI与 snapshot_http_api_test.pyHTTP。Python SDK快照方法挂在client.snapshot.*命名空间下。from openviking_sdk import SyncHTTPClient client SyncHTTPClient(urlhttp://localhost:1933, api_keyyour-key) client.initialize() root viking://resources/my_project # 1. 写入初始内容并提交 v1 client.write( urif{root}/guide.md, content# Guide\n\nv1 content\n, modecreate, waitTrue, ) v1 client.snapshot.commit(messagev1 initial import) print(v1:, v1[commit_oid]) # 2. 修改后再提交 v2 client.write( urif{root}/guide.md, content# Guide\n\nv2 content\n, modereplace, waitTrue, ) v2 client.snapshot.commit(messagev2 update) # 3. 查看历史 for c in client.snapshot.log(limit10): print(c[oid][:8], c[message]) # 4. 查看某个提交的元数据 print(client.snapshot.show(v1[commit_oid])[message]) # 5. 把工作区恢复到 v1会在 v2 之上生成一个新的“正向”提交 client.snapshot.restore(project_dirroot, source_commitv1[commit_oid], messagerestore to v1) client.close()CLICLI 子命令位于ov snapshot下# 提交当前工作区状态 ov snapshot commit -m v1 initial import -o json # 回溯历史最新在前 ov snapshot log --limit 10 -o json # 查看提交元数据 ov snapshot show commit_oid -o json # 读取某个提交中的文件内容默认输出到 stdout可用 --out-file 写入本地文件 ov snapshot show commit_oid --path viking://resources/my_project/guide.md --out-file ./guide.md # 把目录恢复到某个历史快照位置参数依次为 source_commit project_dir ov snapshot restore commit_oid viking://resources/my_project -m restore to v1 -o json # 先预演确认会改动哪些文件 ov snapshot restore commit_oid viking://resources/my_project --dry-run -o jsonHTTP API# 提交 curl -X POST http://localhost:1933/api/v1/snapshot/commit \ -H Content-Type: application/json \ -H X-API-Key: your-key \ -d {message: v1 initial import} # 回溯历史 curl -X GET http://localhost:1933/api/v1/snapshot/log?branchmainlimit10 \ -H X-API-Key: your-key # 查看提交元数据 curl -X GET http://localhost:1933/api/v1/snapshot/show?target_refcommit_oid \ -H X-API-Key: your-key # 恢复 curl -X POST http://localhost:1933/api/v1/snapshot/restore \ -H Content-Type: application/json \ -H X-API-Key: your-key \ -d {project_dir: viking://resources/my_project, source_commit: commit_oid, message: restore to v1}补充diff 命令除上述四个原语外快照 API 还提供diff命令用于以 unified diff 格式对比某个 UTF-8 文件在两个快照中的内容ov snapshot diff viking://resources/my_project/guide.md \ --from 3f2a1b9c \ --to 9a0b1c2dHTTP 对应GET /api/v1/snapshot/diff?path{uri}from{old_ref}to{new_ref}SDK 对应client.snapshot.diff(path, from_ref..., to_ref...)。省略from_ref时旧版本按空文件处理可用来查看文件的初始版本响应中的change_type为added/deleted/modified/unchanged之一。完整的参数、响应结构与大小限制单侧文件上限 10 MiB / 100,000 行diff 上限 20 MiB见 多版本管理 API。重要语义正向恢复restore采用正向恢复forward-commit它读取source_commit的内容把差异写回工作区并在当前 HEAD 之上生成一个新的提交。因此新提交的父提交是恢复操作发生前的 HEAD不是source_commit。API 文档中的响应示例也印证了这一点applied响应里的parent_commit等于恢复前的旧 HEADHEAD 始终单调向前推进历史永远不会被改写或丢失——回到旧版本本身也是一次新的提交restore只影响project_dir省略时为整棵账号树范围内的文件范围之外的文件保持不变当来源与当前状态字节级一致、无需改动时restore返回noop且不生成新提交dry_runtrue时只返回to_write/to_delete/unchanged计划差异不做任何写入。使用.ovgitignore排除文件账号根目录下的.ovgitignore是一个账号级的排除规则文件作用类似根.gitignore匹配该规则的文件在commit时被排除出快照。它与系统内置的剪枝规则_system、tasks、向量索引派生文件等叠加生效。要点规则文件本身不会被.ovgitignore规则忽略即使规则匹配.ovgitignore也会被正常纳入快照——这样规则的变更可追溯、可恢复。规则只影响commitrestore、show、log仍以提交内容为准不把当前.ovgitignore当作过滤器。因此恢复一个历史快照时即便其中某些文件匹配当前规则仍会被正常恢复。若某个文件在更早的提交中已被跟踪、之后新增规则匹配到它下一次commit会把它从新快照中移除工作区的文件本身不受影响。.ovgitignore不会进入向量索引/检索。规则语法.ovgitignore为 UTF-8 文本支持常见的 glob 子集空行被忽略。首个非空白字符为#的行是注释。行首/行尾空白会被裁剪。不支持!取反出现会让commit失败并报错。不支持Git 风格的反斜杠转义。文件大小上限 64 KiB。匹配路径使用账号相对的 Git 树路径/分隔如resources/proj/a.log。例如*.log匹配任意深度的.log文件build/匹配名为build的目录及其内容/cache/**仅匹配账号根下的cache/。管理命令SDK / CLI / HTTP# 写入规则 client.snapshot.set_gitignore(content*.log\n) # 读取不存在时返回空字符串 print(client.snapshot.get_gitignore()) # 删除不存在也视为成功幂等 client.snapshot.delete_gitignore()随后提交时匹配规则的文件会被排除响应里的ignored字段给出本次被排除的候选路径数系统内置剪枝不计入v client.snapshot.commit(messagewith ignore) print(v[result], v.get(ignored)) # created, 1CLI 对应子命令# 设置用 --content 直接传内容或用 --file 从文件读取 ov snapshot ignore-set --content *.log -o json ov snapshot ignore-set --file ./my-rules -o json # 读取-o json 返回 {result: 内容}不加 -o json 时直接把内容打到 stdout ov snapshot ignore-get -o json # 删除幂等 ov snapshot ignore-delete -o jsonHTTP API# 读取 curl -X GET http://localhost:1933/api/v1/snapshot/ignore \ -H X-API-Key: your-key # 写入 curl -X PUT http://localhost:1933/api/v1/snapshot/ignore \ -H Content-Type: application/json \ -H X-API-Key: your-key \ -d {content: *.log\n} # 删除 curl -X DELETE http://localhost:1933/api/v1/snapshot/ignore \ -H X-API-Key: your-key注意事项与错误处理修改git配置后必须重启服务 / 重新初始化客户端才能生效。启用s3后端时git.s3.bucket与git.s3.region为必填项缺失会导致初始化失败。恢复操作如涉及向量副作用写入/删除文件响应会返回一个task_id可通过GET /api/v1/tasks/{task_id}轮询后台向量重建进度参见 系统指南 与 API 概览。examples/snapshot/snapshot_example.py 中演示了对该task_id的轮询等待逻辑建议在 restore 后等待任务完成再执行检索。.ovgitignore内容过大超过 64 KiB或包含!取反、反斜杠转义等不支持语法时commit会失败并报invalid operation错误写入时set_gitignore会预先校验大小。不要手动用外部git工具去操作.ovgit目录它由 OpenViking 维护。快照 API 的常见错误场景见 多版本管理 API 的错误处理表场景HTTP 状态码错误码分支/提交不存在或show的path在该提交中不存在404NOT_FOUND未传入必要的操作范围或当前身份缺少对应 ACL 权限403PERMISSION_DENIED恢复期间分支被并发提交改写CAS 冲突409CONFLICT.ovgitignore过大、非 UTF-8或包含不支持的语法commit时校验400INVALID_ARGUMENT请求体包含未知字段400INVALID_ARGUMENT相关文档多版本管理 APIcommit/log/show/diff/restore及 ignore 管理命令的完整参数与响应参考配置说明ov.conf完整配置项多写存储指南资源数据的多后端复制【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考