OpenViking 资源管理命令实战指南：ov CLI 下的增删改查、定时刷新与语义检索

OpenViking 资源管理命令实战指南：ov CLI 下的增删改查、定时刷新与语义检索

【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking

OpenViking 是面向 AI Agent 的"自进化上下文数据库"，其ov命令行工具把外部知识导入、资源树文件系统、语义检索、定时刷新（watch）与 ovpack 备份恢复统一收敛到viking://resources/命名空间之下。本篇基于 ov-resources skill 的常用命令模式文档，结合其配套的 add-resource、filesystem、search、watch-management、ovpack 参考文档与仓库源码，为你梳理一套可直接照抄的 CLI 命令速查手册，并讲清每条命令背后的 URI 语义与底层处理流程。读完后，你将能独立完成"导入外部知识 → 浏览与读取 → 增量写入 → 定时刷新 → 语义检索 → 备份迁移"的完整资源管理闭环。

一、命令全景：一个ov，三大命令族

OpenViking 的ov命令组将资源管理拆分为三族：

• 资源接入族：add-resource、task watch、export、import、backup、restore
• 文件系统族：ls、tree、read、write、mkdir、rm、mv、grep、glob
• 语义检索族：find、search

从源码结构看，ov子命令的解析集中在 crates/ov_cli/src/main.rs，其中add-resource、abstract、overview、find、search、grep、glob、backup、restore等均被识别为合法的资源类子命令；task watch则在更细粒度的 token 解析中被单独路由（见 main.rs）。而真正发往服务端的 HTTP 调用集中在 crates/ov_cli/src/client.rs 的add_resource、export_ovpack、backup_ovpack、import_ovpack、restore_ovpack等方法中。

在进入命令细节前，先理解两个贯穿全文的基础概念：

1. Viking URI：所有资源统一以viking://resources/...定位。viking://~/resources/...是"当前用户私有资源根"的 home 别名，展开为viking://user/{user_id}/resources/...；旧的 uid-less 写法viking://user/resources/...已被废弃，会返回指向viking://~/...写法的错误提示。peer_id路径段必须是安全单段标识符（如web-visitor-alice），含:、+、.、..或路径分隔符的值会被拒绝。
2. L0/L1/L2 三级语义：OpenViking 为资源树维护分层语义——L0 摘要（abstract，约 100 tokens）、L1 概览（overview）、L2 全文（content）。read/abstract/overview分别对应这三个层级，find/search的--level参数也基于此分层。

二、资源导入：ov add-resource的六类来源与目标定位

ov add-resource是资源管理的入口，默认将外部资源写入共享账户资源根viking://resources/，也可显式指向当前用户或指定 peer 的资源根。

2.1 支持的来源类型

对应命令示例：

# 本地文件 ov add-resource ./docs/api.md # 本地目录 + 过滤 ov add-resource ./project --include "*.py,*.md" --ignore-dirs "node_modules" # URL ov add-resource https://example.com/guide.md # Git 仓库 + 定时刷新（每 60 分钟） ov add-resource https://github.com/volcengine/OpenViking \ --to "viking://resources/repos/OpenViking" \ --watch-interval 60

2.2 目标定位：--to、--parent与自动建父目录

默认资源落在共享的viking://resources/下，可用以下参数覆盖目标位置：

# 精确目标（目标必须不存在） ov add-resource ./docs --to "viking://resources/2026/2026-01-01/" # 放入已存在的父目录下 ov add-resource ./docs --parent "viking://resources/docs/" # 放入当前用户私有资源根 ov add-resource ./docs --parent "viking://~/resources/docs/" # 放入指定 peer 的私有资源根 ov add-resource ./docs --parent "viking://user/alice/peers/web-visitor-alice/resources/docs/" # 自动创建缺失的父路径（支持 {calendar:today} 等路径变量） ov add-resource ./docs --parent-auto-create "viking://resources/docs/2026/05/07" ov add-resource ./guide.md -p "viking://resources/docs/{calendar:today}"

约束要点：path与temp_file_id互斥；--to与--parent互斥；当--to指向已存在的资源时，调用会触发增量更新。

2.3 过滤、结构与异步控制

# 过滤：include / exclude / ignore-dirs 三件套 ov add-resource ./project --include "*.py,*.md" ov add-resource ./project --exclude "*.tmp,*.log" ov add-resource ./project --ignore-dirs "node_modules,target,.git" # 保留目录结构 ov add-resource ./project --preserve-structure # 等待语义处理完成（默认是后台异步） ov add-resource ./docs --wait ov add-resource ./docs --wait --timeout 60

对本地目录，扫描会按标准 Git 语义遵循.gitignore；ignore_dirs、include、exclude在此基础上进一步收窄。

语义处理默认异步执行：wait=false时，非 Git 来源在上传/解析/finalize 完成后即返回，Git 来源则在做完 preflight（校验仓库、解析目标 URI、预留root_uri）后立即返回，克隆/解析/finalize 在后台继续。返回结果中包含task_id，可用GET /api/v1/tasks/{task_id}或ov observer queue追踪进度。

2.4 CLI 输出格式

默认表格输出：

Note: Resource is being processed in the background. Use 'ov wait' to wait for completion, or 'ov observer queue' to check status. status success root_uri viking://resources/01-overview task_id uuid-xxx

JSON 输出（-o json）：

{ "status": "success", "root_uri": "viking://resources/01-overview", "task_id": "uuid-xxx" }

使用--wait时，响应会额外携带queue_status（含pending、processing、completed计数）。

2.5 服务端实现佐证

add-resource对应的 HTTP 端点是POST /api/v1/resources（见 openviking/server/routers/resources.py），其请求模型 resources.py 中watch_interval默认值为0；上传内容（temp_file_id场景）下watch_interval > 0会直接报错——定时刷新只支持可重复拉取的 URL/Git 来源（resources.py）。文件上传则走POST /api/v1/resources/temp_upload暂存后引用（resources.py）。

2.6 关键参数速查

提示：要创建或更新纯文本内容，请用ov write而非add_resource。

三、浏览与读取：ls / tree / stat / read / abstract / overview

viking://resources/是一个 Unix 风格的文件系统命名空间，提供对应的浏览命令族（详细参考见 filesystem.md）。

# 顶层列表 ov ls viking://resources/ # 递归列表 ov ls viking://resources/my-project/ --recursive # 树状视图（限制深度） ov tree viking://resources/my-project/ --level-limit 3 # 仅输出简单路径 ov ls viking://resources/ --simple # 文件统计 ov stat viking://resources/docs/api.md

• ov ls支持--simple、--recursive、--show-all-hidden、--node-limit；条目的字段包括name、size、mode、modTime、isDir、uri、meta。
• ov tree额外支持--level-limit。
• ov stat对目录返回count（估算条目数）；isLocked字段报告该路径是否持有路径锁或祖先 TreeLock。

读取内容对应三级语义：

# L2 全文 ov read viking://resources/docs/api.md # 按行范围读取（offset 从 0 开始，limit 为 -1 表示全部） ov read viking://resources/docs/api.md --offset 10 --limit 20 # L0 摘要（仅目录） ov abstract viking://resources/docs/ # L1 概览（仅目录） ov overview viking://resources/docs/

细节与边界：

• ov read只接受文件 URI；传入目录会返回INVALID_ARGUMENT（400），并在结构化details中携带expected="file"、actual="directory"，客户端可据此优雅回退到ov ls。
• ov abstract读取约 100 tokens 的 L0 摘要，ov overview读取 L1 概览，两者均仅支持目录。
• 派生语义文件（.abstract.md、.overview.md）不可被直接写入。

四、内容写入：ov write 的三种模式

ov write是向资源树写入/更新文本内容的唯一正道（纯文本创建或更新请勿走 add-resource）：

# 替换已有文件（默认模式） ov write viking://resources/docs/api.md \ --content "# Updated\n\nNew content." \ --wait # 创建新文件（已存在则失败） ov write viking://resources/docs/new.md \ --content "# New doc" \ --mode create # 追加到已有文件 ov write viking://resources/docs/notes.md \ --content "\nNew line." \ --mode append

三种模式：

• replace（默认）：覆盖已有文件
• append：追加到已有文件
• create：创建新文件，已存在则失败；接受.md、.txt、.json、.yaml、.yml、.toml、.py、.js、.ts等文本扩展名

--wait会阻塞直到语义/向量刷新完成；create模式下父目录会自动创建。注意权限语义：ov write是就地替换，旧版本不保留。

五、目录管理：mkdir / mv / rm

# 创建目录 ov mkdir viking://resources/new-project/ # 带描述创建（写入 .abstract.md 并入队 L0 向量化） ov mkdir viking://resources/new-project/ --description "Project docs" # 移动 ov mv viking://resources/old-name/ viking://resources/new-name/ # 删除文件 ov rm viking://resources/docs/old.md # 递归删除目录 ov rm viking://resources/old-project/ --recursive

行为细节：

• ov mkdir的--description会写入.abstract.md并排队触发 L0 向量化，使新目录立即可被语义检索命中。
• ov rm是幂等的：删除不存在的合法 URI 会成功；非法 URI 格式返回INVALID_URI；递归删除返回estimated_deleted_count。
• 危险操作提醒（skill 边界）：ov rm --recursive是破坏性操作，执行前应获得用户明确确认，切忌对viking://resources/这类宽泛路径直接执行。

六、检索：grep / glob 与语义检索 find / search

6.1 基于文本/路径的检索

# 正则检索内容（响应含 uri / line / content） ov grep "TODO" --uri viking://resources/ --ignore-case # Glob 匹配文件路径 ov glob "**/*.md" --uri viking://resources/ ov glob "**/*.py" --uri viking://resources/

ov grep参数：uri、pattern（必填）、--ignore-case、--exclude-uri、--node-limit、--level-limit。ov glob参数：pattern（必填）、--uri、--node-limit。

6.2ov find：纯向量相似度检索

ov find执行不携带会话上下文的层级向量相似度检索，适合简单直接的查询（详见 search.md）：

# 全上下文检索 ov find "how to handle API rate limits" # 限定 URI 范围 ov find "authentication flow" --uri "viking://resources/my-project" # 限制结果数 + 相关度阈值 ov find "error handling" --node-limit 5 --threshold 0.3 # 时间过滤 ov find "invoice" --after 7d --time-field created_at # 仅 L0 摘要 ov find "overview" --level 0 # 多层级 ov find "details" -L 1,2

6.3ov search：带意图分析的上下文检索

ov search在find()之上叠加了会话上下文理解与意图分析（含查询扩展），更贴合对话式检索：

# 携带会话上下文 ov search "best practices" --session-id abc123 # 时间区间过滤 ov search "watch vs scheduled" --after 2026-03-15 --before 2026-03-20 # 无会话也执行意图分析 ov search "how to implement OAuth 2.0 authorization code flow" # 层级过滤 ov search "best practices" --level 0 ov search "how to implement OAuth" -L 1,2

6.4 find vs search

6.5 公共参数与结果结构

结果按context_type分组（memories/resources/skills）：

{ "memories": [], "resources": [ { "uri": "viking://resources/docs/auth.md", "context_type": "resource", "level": 2, "score": 0.95, "abstract": "OAuth 2.0 best practices...", "overview": "This guide covers...", "match_reason": "Context-aware match: OAuth login best practices" } ], "skills": [], "total": 1, "query_plan": { "reasoning": "User is asking about OAuth implementation...", "queries": [...] } }

query_plan仅出现在search结果中。URI 范围还可定位到记忆与技能命名空间：viking://resources（仅资源）、viking://~/memories（仅记忆）、viking://~/skills（仅技能）。

6.6 检索与浏览的组合套路

# 第 1 步：语义检索定位相关目录 ov find "authentication" --uri "viking://resources/project-A" # 第 2 步：读取目录概览获取上下文 ov overview viking://resources/project-A/backend # 第 3 步：精读具体文件 ov read viking://resources/project-A/backend/auth.md

这一"先找、再览、后读"的三段式是 Agent 在 OpenViking 中完成上下文编译的推荐工作流。

七、定时刷新：watch 任务的完整生命周期

通过ov add-resource --watch-interval <分钟>即可创建定时重新导入任务，控制面命令统一收敛在ov task watch下（详见 watch-management.md）。

7.1 核心概念

• 创建：在ov add-resource上设置watch_interval > 0即创建或更新 watch 任务。
• 绑定：提供--to时任务绑定到--toURI；否则绑定到导入产生的root_uri。因此对长期稳定的 watch，优先使用--to。
• 调度：WatchScheduler每 60 秒检查一次到期任务（对应实现见 openviking/server/routers/watches.py 附近）。
• 暂停/恢复：is_active与watch_interval相互正交——暂停不会丢失刷新节奏，恢复后按原间隔继续。

7.2 子命令一览

# 仅列出活动任务 ov task watch ls --active-only # 列出全部（含已暂停） ov task watch ls # 查看单个任务（key 自动分类：viking:// URI 按 URI 路由，其余视为任务 ID） ov task watch show viking://resources/guide.md ov task watch show <task_id> # 暂停（保留 watch_interval） ov task watch pause viking://resources/guide.md # 恢复 ov task watch resume viking://resources/guide.md # 更新参数 ov task watch update viking://resources/guide.md --interval 30 ov task watch update viking://resources/guide.md \ --reason "Updated docs" \ --instruction "Focus on API changes" # 立即触发一次刷新（fire-and-forget，后台重导入） ov task watch trigger viking://resources/guide.md # 移除 watch 任务 ov task watch rm viking://resources/guide.md

ov task watch update支持的字段：--interval、--active/--no-active、--reason、--instruction。

7.3 生命周期速查

key既可以是viking://URI，也可以是任务 ID。从服务端实现看，PATCH更新时watch_interval必须> 0——暂停请用is_active=false而不是把间隔改成 0（watches.py），这也印证了is_active与间隔正交的设计。

八、OVPack：导出、导入、备份与恢复

OVPack 是.ovpack格式的资源树归档格式，用于 OpenViking 资源树的备份与迁移，需要 ROOT 或 ADMIN 权限（详见 ovpack.md）。

8.1 导出与导入

# 导出资源树到 .ovpack 文件 ov export viking://resources/my-project/ ./backups/my-project.ovpack # 附带稠密向量快照导出 ov export viking://resources/my-project/ ./backups/my-project.ovpack --include-vectors # 导入到目标位置 ov import ./backups/my-project.ovpack viking://resources/imported/ # 显式指定冲突策略 ov import ./backups/my-project.ovpack viking://resources/imported/ --on-conflict overwrite # 要求兼容的稠密向量快照 ov import ./backups/my-project.ovpack viking://resources/imported/ --vector-mode require

归档内部结构：ZIP 中用户内容存放在<root>/files/，元数据存放在<root>/_ovpack/，包含：

• manifest.json— 条目清单（path、size、sha256、content_sha256）
• index_records.jsonl— 可移植的索引标量字段
• dense.f32— 纯稠密 float32 向量快照（仅在--include-vectors时生成）

约束：混合索引类型会拒绝向量快照导出。

8.2 备份与恢复

# 备份全部公共 scope 根（resources / user / agent / session） ov backup ./backups/openviking.ovpack # 备份含向量 ov backup ./backups/openviking.ovpack --include-vectors # 恢复到原始公共 scope 根 ov restore ./backups/openviking.ovpack --on-conflict overwrite # 恢复并要求向量快照 ov restore ./backups/openviking.ovpack --on-conflict overwrite --vector-mode require

关键语义：

• 冲突策略：fail（默认）、overwrite、skip。
• 向量模式：auto（默认）、recompute、require。
• 常规ov import会拒绝备份包（backup 包只能由ov restore消费）。
• 会话文件恢复时不进行向量化。
• 无 manifest 的包被拒绝；内容完整性校验基于文件大小、sha256、content_sha256。
• 导入时会重新生成运行时字段（id、uri、account_id、created_at、updated_at）。
• 顶层 scope 包（如viking://resources/）必须导入到viking://根。

从源码看，export会自动补全.ovpack扩展名（crates/ov_cli/src/client.rs），导出走/api/v1/pack/export，备份走/api/v1/pack/backup，导入与恢复分别对应import_ovpack与restore_ovpack（client.rs）；服务端backup_ovpack、restore_ovpack端点在 openviking/server/routers/pack.py 中实现。

九、补充：WebDAV 适配层与 Skill 边界

除 CLI 外，OpenViking 还在/webdav/resources暴露了极简 WebDAV 适配层：

• 仅暴露资源（记忆、技能、会话不暴露）
• PUT仅接受 UTF-8 文本
• 支持方法：OPTIONS、PROPFIND、GET、HEAD、PUT、DELETE、MKCOL、MOVE
• 语义 sidecar 与内部文件隐藏
• PUT不会自动创建父集合，需先用MKCOL
• 创建或替换文件会触发语义生成

最后提醒两条使用边界（源自 SKILL.md 的职责划分）：

• ov add-skill/ov skills属于 skill 管理，由ov-skills处理，与资源命令不等价；
• ov add-memory属于记忆管理，不在资源命令范围内。

从仓库视角看，commands.md 是 ov-resources skill 的实战速查，与之配套的 SKILL.md 定义了 Agent 调用这些命令的触发条件、输入参数、权限要求与验证步骤，五份参考文档（add-resource、filesystem、search、watch-management、ovpack）则为每条命令提供了更细的参数语义。将本文与这些文档、以及 crates/ov_cli/src 与 openviking/server/routers 下的实现对照阅读，即可从"命令可用"深入到"原理可解释"，把 OpenViking 的资源管理能力真正变成 Agent 上下文工程的日常操作。

【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking