OVPack 导入导出

OVPack 是 OpenViking 的打包格式，用于导出/导入任意上下文子树（例如资源、记忆），以便备份、迁移和分享。

快速开始

导出资源

将 OpenViking 中的资源导出为 .ovpack 文件。

CLI

openviking export viking://resources/my-project/ ./exports/my-project.ovpack

Python SDK

from openviking import AsyncOpenViking

async def export_example():
    client = AsyncOpenViking()
    await client.initialize()
    try:
        exported_path = await client.export_ovpack(
            uri="viking://resources/my-project/",
            to="./exports/my-project.ovpack"
        )
        print(f"导出成功: {exported_path}")
    finally:
        await client.close()

HTTP API

curl -X POST http://localhost:1933/api/v1/pack/export \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "uri": "viking://resources/my-project/",
    "to": "./exports/my-project.ovpack"
  }'

导入资源

将 .ovpack 文件导入到 OpenViking 中。

CLI

# 基本导入
openviking import ./exports/my-project.ovpack viking://resources/imported/

# 强制覆盖
openviking import ./exports/my-project.ovpack viking://resources/imported/ --force

# 跳过向量化（更快）
openviking import ./exports/my-project.ovpack viking://resources/imported/ --no-vectorize

Python SDK

from openviking import AsyncOpenViking

async def import_example():
    client = AsyncOpenViking()
    await client.initialize()
    try:
        imported_uri = await client.import_ovpack(
            file_path="./exports/my-project.ovpack",
            parent="viking://resources/imported/",
            force=True,
            vectorize=True
        )
        print(f"导入成功: {imported_uri}")
        await client.wait_processed()
    finally:
        await client.close()

HTTP API

# 第一步：上传本地 ovpack 文件
TEMP_FILE_ID=$(
  curl -sS -X POST http://localhost:1933/api/v1/resources/temp_upload \
    -H "X-API-Key: your-key" \
    -F 'file=@./exports/my-project.ovpack' \
  | jq -r '.result.temp_file_id'
)

# 第二步：使用 temp_file_id 导入
curl -X POST http://localhost:1933/api/v1/pack/import \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d "{
    \"temp_file_id\": \"$TEMP_FILE_ID\",
    \"parent\": \"viking://resources/imported/\",
    \"force\": true,
    \"vectorize\": true
  }"

记忆导入导出

OpenViking 的记忆会写入固定的目录结构中：

• 用户记忆：viking://user/{user_space}/memories/
• Agent 记忆：viking://agent/{agent_id}/memories/ 或 viking://agent/{agent_id}/user/{user_id}/memories/

使用 OVPack 迁移记忆时，必须把 .ovpack 导入到对应 space 的父目录（而不是随便一个目录），否则会变成例如 .../memories/memories/... 的路径，OpenViking 将无法按“记忆”语义访问和使用这些文件。

导出/导入用户记忆（CLI）

# 导出：整个用户 memories 子树
openviking export viking://user/default/memories/ ./exports/user-memories.ovpack

# 导入：注意 parent 需要是 user space 根目录（导入后会生成 viking://user/default/memories/）
openviking import ./exports/user-memories.ovpack viking://user/default/ --force

导出/导入 Agent 记忆（CLI）

# isolate_agent_scope_by_user = false
openviking export viking://agent/default/memories/ ./exports/agent-memories.ovpack
openviking import ./exports/agent-memories.ovpack viking://agent/default/ --force

# isolate_agent_scope_by_user = true
openviking export viking://agent/default/user/alice/memories/ ./exports/agent-memories.ovpack
openviking import ./exports/agent-memories.ovpack viking://agent/default/user/alice/ --force

导出/导入记忆（Python SDK）

from openviking import AsyncOpenViking

async def export_import_user_memories():
    client = AsyncOpenViking()
    await client.initialize()
    try:
        await client.export_ovpack(
            uri="viking://user/default/memories/",
            to="./exports/user-memories.ovpack",
        )

        await client.import_ovpack(
            file_path="./exports/user-memories.ovpack",
            parent="viking://user/default/",
            force=True,
            vectorize=True,
        )
    finally:
        await client.close()

async def export_import_agent_memories():
    client = AsyncOpenViking()
    await client.initialize()
    try:
        await client.export_ovpack(
            uri="viking://agent/default/memories/",
            to="./exports/agent-memories.ovpack",
        )
        await client.import_ovpack(
            file_path="./exports/agent-memories.ovpack",
            parent="viking://agent/default/",
            force=True,
            vectorize=True,
        )
    finally:
        await client.close()

导出/导入记忆（HTTP API）

# 导出用户记忆
curl -X POST http://localhost:1933/api/v1/pack/export \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "uri": "viking://user/default/memories/",
    "to": "./exports/user-memories.ovpack"
  }'

# 导入用户记忆（先上传，再用 temp_file_id 导入）
TEMP_FILE_ID=$(
  curl -sS -X POST http://localhost:1933/api/v1/resources/temp_upload \
    -H "X-API-Key: your-key" \
    -F 'file=@./exports/user-memories.ovpack' \
  | jq -r '.result.temp_file_id'
)
curl -X POST http://localhost:1933/api/v1/pack/import \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d "{
    \"temp_file_id\": \"$TEMP_FILE_ID\",
    \"parent\": \"viking://user/default/\",
    \"force\": true,
    \"vectorize\": true
  }"

导入后是否向量化

• 默认会向量化（便于 find/search 检索）。
• 如果只做快速恢复、稍后再统一处理，可使用 --no-vectorize：

openviking import ./exports/user-memories.ovpack viking://user/default/ --force --no-vectorize

使用场景

资源备份

DATE=$(date +%Y%m%d)
openviking export viking://resources/ ./backups/backup_${DATE}.ovpack

资源迁移

# 机器 A 导出
openviking export viking://resources/my-project/ ./migration.ovpack

# 机器 B 导入
openviking import ./migration.ovpack viking://resources/ --force

资源分享

# 导出
openviking export viking://resources/shared-docs/ ./shared-docs.ovpack

# 接收者导入
openviking import ./shared-docs.ovpack viking://resources/team-shared/

常见问题

Q: OVPack 文件可以手动解压查看吗？ A: 可以！OVPack 是标准的 ZIP 格式，可以用任何解压工具打开。

Q: 大体积 OVPack 导入很慢怎么办？ A: 使用 --no-vectorize 先快速导入，之后再统一向量化。

Q: 导入时如何处理重名资源？ A: 使用 --force 参数覆盖已存在的资源。