ov-add-data

OpenViking (OV) add-resource

ov add-resource 命令将外部资源导入 OpenViking 的上下文数据库——支持本地文件、目录、URL 和远程资源。资源会自动经过语义分析处理，并整理到 viking://resources/ 命名空间下。

何时使用

• 导入项目文档、代码仓库或参考资料
• 添加网页、文章或在线资源以备将来检索
• 从外部来源构建知识库
• 当 Agent 遇到应当跨会话持久保存的有价值内容时
• 记录项目的产品文档、设计规范或其他有价值的材料
• 存储用户的敏感信息或私人数据，例如照片和相册

命令行选项

基本用法

导入本地文件或 URL：

# add a code repo from github or gitlab or a git address
ov add-resource https://github.com/volcengine/OpenViking
ov add-resource https://code.xxxx.org/viking/viking
ov add-resource [email protected]:viking/viking.git

# add a file from url
ov add-resource https://arxiv.org/pdf/2602.09540
ov add-resource https://raw.githubusercontent.com/volcengine/OpenViking/main/README.md

# add a file from local filesystem
ov add-resource ./docs/api-spec.md
ov add-resource ./team_building.jpg
ov add-resource /User/volcengine/Documents/profile.pdf
ov add-resource /User/volcengine/Documents/project.docx

# add a zip file from local filesystem (will be unzipped on server)
ov add-resource ./docs-of-project.zip

# add a directory from local filesystem
ov add-resource /User/volcengine/Photo/Travels/2026/ --include "*.jpg,*.jpeg,*.png"
ov add-resource /User/volcengine/Documents/OV项目设计文档/

上下文与指令（待定）

添加元数据以指导处理：未来将支持 --reason 和 --instruction。

异步处理控制

添加资源可能耗时较长（如数分钟），且语义处理可能是异步的。使用 --wait 等待处理完成。

# Wait until semantic processing finishes
ov add-resource ./docs --wait

# Wait with timeout (in seconds)
ov add-resource https://example.com/docs --wait --timeout 60

# Fire and forget (default, without --wait)
ov add-resource ./docs

如果采用即发即忘的方式，命令会在资源在服务端完全下载/上传后返回，随后 CLI 会返回所导入资源的根 URI。要检查资源状态，可以使用 ov ls 或 ov tree 列出根 URI 或 viking://resources/ 下的资源。

指定目标路径

默认情况下，资源会导入到 viking://resources/ 下。使用 --to 或 --parent 指定目标 uri。

# The data will be imported as viking://resources/2026/2026-01-01/, which should not exist before
ov add-resource /User/volcengine/Photo/Travels/2026/2026-01-01/ --to "viking://resources/2026/2026-01-01/"

# The data will be imported under viking://resources/2026, which should exist and be a directory
ov add-resource /User/volcengine/Photo/Travels/2026/2026-01-02/ --parent "viking://resources/2026/"

命令行输出

返回所导入资源的根 URI，例如：

root_uri  viking://resources/2026/2026-01-01

命令行前提条件

• 已在以下位置配置 CLI：~/.openviking/ovcli.conf
• 服务端在导入 URL 时需要网络访问权限
• CLI 在导入本地文件/目录时需要本地读取权限。

OpenViking (OV) add-memory

ov add-memory 命令添加长期持久记忆——将文本和结构化对话转换为 OpenViking 上下文数据库中可搜索、可检索的记忆。使用 ov add-memory --help 查看最新说明。

何时使用

• 在了解到值得跨会话记住的内容之后
• 持久保存对话中的见解、决策或发现
• 从交互中构建知识库
• 当 Agent 希望存储上下文以供将来检索时

输入方式

在纯文本和多轮模式之间明智选择。多轮模式可以包含更复杂的见解，让 openviking 处理记忆提取。

模式 1：用于压缩记忆的纯文本

一个简单字符串会被存储为 user 消息：

ov add-memory "User's name is Bob, he participate in Global Hackathon in 2025-01-08, and won Champion."

模式 2：用于更丰富上下文的多轮对话

由 {role, content} 对象组成的 JSON 数组，用于存储完整交流：

ov add-memory '[
  {"role": "user", "content": "I love traveling. Give me some options of Transport from Beijing to Shanghai."},
  {"role": "assistant", "content": "You can use train, bus, or plane. Train is the fastest, but you need to book in advance. Bus is cheaper, but you need to wait. Plane is the most expensive, but you can get there any time of day."},
  {"role": "user", "content": "I prefer train. I like sightseeing on the train. Can you give me the train schedule?"},
  < ... more possible conversation about schedule and tickest need to be memorized ... >
]'

输出

请求被接受后返回 OK。提交入队后，记忆提取会在服务端异步运行，因此 CLI 不会等待提取完成：

OK

Agent 最佳实践

如何编写优质记忆

1. 要具体——包含具体细节，而非模糊概括
2. 包含上下文——说明为何重要、何时适用
3. 使用结构化格式——将"是什么"与"为什么"分开

批量记录相关事实

将相关记忆归入一次调用，而不是多次零散调用：

ov add-memory '[
  {"role": "user", "content": "Key facts about the ov_cli Rust crate"},
  {"role": "assistant", "content": "1. runs faster than python cli\n2. uses HttpClient to connect openviking server\n3. Output formatting supports table and JSON modes\n4. Config lives at ~/.openviking/ovcli.conf"}
]'

前提条件

• 已配置 CLI：~/.openviking/ovcli.conf

OpenViking (OV) add-skill

ov add-skill 命令向 OpenViking 添加 Agent 能力——支持 SKILL.md 文件、MCP 工具定义和原始技能内容。技能会自动处理并整理到 viking://agent/skills/ 命名空间下，使其可被 Agent 发现和使用。

何时使用

• 添加自定义 Agent 能力和工作流
• 导入 MCP（Model Context Protocol）工具
• 在多个 Agent 会话之间持久化技能定义
• 构建可复用的 Agent 能力库
• 当 Agent 需要用自定义逻辑扩展其工具集时

输入格式

模式 1：SKILL.md 文件

从带有 YAML frontmatter 的单个 SKILL.md 文件导入：

# Add from a single SKILL.md file
ov add-skill ./skills/my-skill/SKILL.md

# Add from a directory containing SKILL.md (includes auxiliary files)
ov add-skill ./skills/my-skill/

命令行选项

异步处理控制

语义处理以异步方式执行。使用 --wait 阻塞直到完成：

# Wait until semantic processing finishes
ov add-skill ./skills/my-skill/ --wait

# Wait with timeout (in seconds)
ov add-skill ./skills/my-skill/ --wait --timeout 60

# Fire and forget (default, without --wait)
ov add-skill ./skills/my-skill/

命令行输出

返回所添加技能的 URI，例如：

uri  viking://agent/skills/my-skill/

SKILL.md 格式

技能使用带有 YAML frontmatter 的 Markdown：

---
name: skill-name
description: Brief description of the skill
allowed-tools:
  - Tool1
  - Tool2
tags:
  - tag1
  - tag2
---

## Including Auxiliary Files

When adding from a directory, all files in the directory are included as auxiliary files:

```bash
# Directory structure:
# ./skills/code-runner/
#   ├── SKILL.md
#   ├── helper.py
#   └── templates/
#       └── script.py

ov add-skill ./skills/code-runner/
# Both helper.py and templates/ are included

命令行前提条件

• 已配置命令行：~/.openviking/ovcli.conf
• 技能文件（SKILL.md）应为正确的 markdown 格式。