OpenViking 资源管理命令实战指南ov CLI 下的增删改查、定时刷新与语义检索【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenVikingOpenViking 是面向 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等方法中。在进入命令细节前先理解两个贯穿全文的基础概念Viking URI所有资源统一以viking://resources/...定位。viking://~/resources/...是当前用户私有资源根的 home 别名展开为viking://user/{user_id}/resources/...旧的 uid-less 写法viking://user/resources/...已被废弃会返回指向viking://~/...写法的错误提示。peer_id路径段必须是安全单段标识符如web-visitor-alice含:、、.、..或路径分隔符的值会被拒绝。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 支持的来源类型类型示例本地文件./docs/api.md、./team_building.jpg、/User/volcengine/Documents/project.docx本地目录/User/volcengine/Photo/Travels/2026/ZIP 压缩包./docs-of-project.zip服务端自动解压URLhttps://example.com/guide.md、https://arxiv.org/pdf/2602.09540Git 仓库https://github.com/volcengine/OpenViking、gitcode.xxxx.org:viking/viking.git对应命令示例# 本地文件 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 602.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 语义遵循.gitignoreignore_dirs、include、exclude在此基础上进一步收窄。语义处理默认异步执行waitfalse时非 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-xxxJSON 输出-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 关键参数速查参数说明--to精确目标 URI与--parent互斥--parent/-p父目录 URI--parent-auto-create父目录缺失时自动创建--reason添加原因实验性--instruction处理指令实验性--wait阻塞等待语义处理完成--timeout配合--wait的超时秒数--strict严格模式--ignore-dirs忽略的目录名逗号分隔--include包含的文件 glob 模式--exclude排除的文件 glob 模式--watch-interval定时刷新间隔分钟提示要创建或更新纯文本内容请用ov write而非add_resource。三、浏览与读取ls / tree / stat / read / abstract / overviewviking://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.mdov 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_ARGUMENT400并在结构化details中携带expectedfile、actualdirectory客户端可据此优雅回退到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 / search6.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,26.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,26.4 find vs search维度findsearch意图分析无有会话上下文无有查询扩展无有默认结果数1010适用场景简单直接查询对话式检索6.5 公共参数与结果结构参数说明--uri限定检索的 URI 前缀--node-limit/--limit最大结果数--threshold/--score-threshold最低相关度0-1--after时间下界2h、7d、ISO 8601--before时间上界30m、ISO 8601--time-fieldupdated_at默认或created_at--level/-L限定层级0、1、2、0,1,2--peer-id稳定交互 peer ID--session-id会话 ID仅search结果按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.mdov task watch update支持的字段--interval、--active/--no-active、--reason、--instruction。7.3 生命周期速查动作命令创建/更新ov add-resource source --to uri --watch-interval minutes列出ov task watch ls [--active-only]查看ov task watch show key暂停ov task watch pause key恢复ov task watch resume key更新节奏ov task watch update key --interval minutes立即触发ov task watch trigger key移除ov task watch rm key通过 add-resource 取消ov add-resource source --to uri --watch-interval 0key既可以是viking://URI也可以是任务 ID。从服务端实现看PATCH更新时watch_interval必须 0——暂停请用is_activefalse而不是把间隔改成 0watches.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_sha256index_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_ovpackclient.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考