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

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 支持的来源类型

类型	示例
本地文件	./docs/api.md、./team_building.jpg、/User/volcengine/Documents/project.docx
本地目录	/User/volcengine/Photo/Travels/2026/
ZIP 压缩包	./docs-of-project.zip（服务端自动解压）
URL	https://example.com/guide.md、https://arxiv.org/pdf/2602.09540
Git 仓库	https://github.com/volcengine/OpenViking、[e-mail]: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 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 关键参数速查

参数	说明
--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 / 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.2 ov 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.3 ov 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

维度	find	search
意图分析	无	有
会话上下文	无	有
查询扩展	无	有
默认结果数	10	10
适用场景	简单直接查询	对话式检索

6.5 公共参数与结果结构

参数	说明
--uri	限定检索的 URI 前缀
--node-limit / --limit	最大结果数
--threshold / --score-threshold	最低相关度（0-1）
--after	时间下界（2h、7d、ISO 8601）
--before	时间上界（30m、ISO 8601）
--time-field	updated_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 时任务绑定到 --to URI；否则绑定到导入产生的 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 生命周期速查

动作	命令
创建/更新	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 0

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 上下文工程的日常操作。