OpenViking 0.3.x 到 0.4.0 升级与数据迁移指南User / Peer 新数据模型实战【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking从 0.3.x 升级到 0.4.0 的核心变化是 OpenViking 从Agent 为中心的数据组织方式切换到User / Peer模型User 代表自然人或业务用户Peer 代表该用户下的交互身份Session 与 Skill 都归属到具体 User 之下。本篇指南面向已经在运行 OpenViking 0.3.x 的用户完整讲解升级前需要做的准备、0.4.0 对旧用法的兼容边界、旧 Agent / Session 数据的迁移流程含 HTTP API 与ovCLI 两种操作方式、迁移结果的验证方法、应用代码改造要点以及可选的历史数据清理。读完本篇你将掌握一次可回退、可验证、可清理的完整升级路径。升级决策的核心结论是0.4.0 不强制你立刻迁移数据——服务器端保留了旧数据的运行时可读性但新的写入路径、检索行为与actor_peer_id请求级视图只属于新模型。迁移本身也设计为幂等且非破坏性只拷贝、不删除出问题可随时重跑。升级决策留在 0.3.x 与升级 0.4.0 的取舍如果继续停留在 0.3.x现有的agent_id、viking://agent/...、viking://session/...行为完全不变但你也无法使用 0.4.0 的新模型与工具没有 User / Peer 数据模型没有旧 Agent / Session 的迁移与清理命令没有请求级的actor_peer_id视角围绕新模型的后续修复与功能不会回移植到旧模型。如果升级到 0.4.0不需要立刻迁移数据运行时保持兼容旧数据依然可读agent_id可以临时继续配置。在当前的 HTTP SDK 客户端中它映射为请求级actor_peer_idviking://agent/...仍然可以读取旧 Agent 数据但只读viking://session/...仍然可以读取旧 Session 数据并与新的 Session 视图合并展示。官方推荐的操作顺序是备份 - 升级 Server / CLI / SDK - 验证旧数据仍可读 - 执行数据迁移 - 验证新路径 - 逐步更新应用用法 - 可选执行清理这一顺序保证任何一步出问题都能回到上一步先备份、再升级、确认兼容后迁移最后才清理。第一步先备份使用 0.3.x 兼容的包创建备份官方推荐0.3.24pip install openviking0.3.24 --upgrade --force-reinstall ov backup ./backups/openviking-before-0.4.0.ovpack先确认当前版本避免误操作python -c import openviking; print(openviking.__version__) ov version注意不要在 0.3.x 上运行ov --sudo admin migrate。迁移命令只在 0.4.0 及以后版本提供旧版本不存在该子命令强行执行不会得到预期结果。第二步升级 Server 与客户端安装 0.4.0重启服务器并确保 CLI / SDK 客户端与服务器保持同一版本线pip install openviking0.4.0 --upgrade --force-reinstall openviking-server --config ov.conf如果你使用的是仓库中编译的 RustovCLI需要重新构建或重新安装否则 PATH 上的ov二进制可能仍是旧版本导致命令行为与服务器不一致。升级后验证配置与旧数据读取ov config validate ov ls viking://agent ov ls viking://session ov session list一个关键点viking://session的合并兼容视图是在服务器端实现的只升级 CLI 不会改变服务器侧的读取行为。如果ov ls viking://session仍然为空请先确认服务器已经以 0.4.0 重启。兼容性矩阵旧用法在 0.4.0 中的行为下表完整列出常见旧用法在 0.4.0 中的表现是升级期间排查问题的依据旧用法0.4.0 行为客户端配置agent_id受支持。在当前 HTTP SDK 客户端中映射为请求级actor_peer_id不再单独触发旧 Agent 模式。ov ls viking://agent支持读取。若设置了agent_id/actor_peer_id只显示当前 actor peer 的旧 Agent。读取viking://agent/agent_id/...支持读取旧数据。写入viking://agent/...不支持。新写入应使用viking://user/user_id/peers/peer_id/...。ov ls viking://session支持读取。合并展示新旧 Session。读取viking://session/session_id/...支持。优先新路径旧路径作为回退。写入viking://session/...不支持。新 Session 写入viking://user/user_id/sessions/...。使用 HTTP SDKagent_id执行find/search支持。仅搜索选定的 actor peer 视图不会自动搜索未迁移的旧 Agent 数据。find/searchbody 中的peer_id不支持。新 peer 视图请使用actor_peer_id或X-OpenViking-Actor-Peer请求头。同时配置actor_peer_id和agent_id不支持。客户端/请求直接失败。使用 HTTP SDKagent_id时显式指定消息peer_id支持。消息使用显式peer_id省略时不会从agent_id推断身份。role_id内存隔离不支持。升级后该字段被忽略。从源码结构可以推断viking://session的兼容读路径在 namespace.py 中由canonical_session_root/is_session_uri支撑is_session_uri同时识别viking://session/...旧与viking://user/user/sessions/...新两种形式这正是新旧合并视图在 URI 分类层面的依据。第三步执行迁移确认旧数据可读后运行迁移ov --sudo admin migrate --output json响应返回一个任务 ID{ task_id: ... }查询任务状态ov --sudo task status task_id ov --sudo task list --task-type legacy_migrationHTTP API 方式body 可为空等价于{action: migrate}POST /api/v1/admin/migrate X-API-Key: root-key{ action: migrate }查询任务GET /api/v1/tasks/{task_id} X-API-Key: root-key从源码看admin.py 中POST /migrate端点要求 ROOT 权限require_auth_root先执行LegacyDataMigration.preflight()只有 preflight 无错误才创建任务并异步执行。任务类型为legacy_migration清理时为legacy_cleanup且ROOT 查询迁移任务时不受普通账号/用户过滤限制——迁移会为整个存储创建一个 root 级任务而不是每个账号一个任务。迁移规则旧数据落到哪里0.4.0 采用 User / Peer 模型User 自然人或业务用户 Peer User 之下的交互身份 Session User 之下的会话状态 Skill User 之下可执行的技能迁移目标映射旧数据新位置viking://agent/agent_id/memories/...viking://user/user_id/peers/agent_id/memories/...viking://agent/agent_id/resources/...viking://user/user_id/peers/agent_id/resources/...viking://agent/agent_id/skills/skill/...viking://user/user_id/skills/skill/...viking://session/session_id/...viking://user/user_id/sessions/session_id/...共享的旧 Agent 数据会拷贝到每个目标用户的 peer 目录如果旧路径已经标识出某个用户所有者则只迁移到该用户。向量记录的迁移细节迁移不只是拷贝文件。对于实际被拷贝的 memory / resource / skill 文件或目录迁移会读取旧记录的vector/sparse_vector与标量字段、重写 URI、写入新记录。底层实现在 vector_migration.py 的copy_vector_records中通过_records_in_scope按 URI 范围过滤旧向量记录_MAX_VECTOR_RECORDS_PER_SCOPE为单范围上限 100,000 条达到上限会告警并提示手动 reindex对每条记录调用rewrite_vector_record重算id、uri、owner_user_id、owner_space、context_type并保留原有向量载荷然后upsert写入。需要注意迁移不会重新做 embedding也不会自动调用reindex。如果迁移后检索结果不符合预期需要对新路径手动执行 reindex。共享旧 Agent 数据拷贝给多个用户时向量记录会按目标用户 URI 各拷贝一次。纯标量记录没有向量载荷会被跳过并计入migrated.skipped_vector_records。Session 迁移只拷贝文件状态不处理向量记录。Session 所有者的解析顺序Session 所有者按以下顺序解析.meta.json.created_by_user_id.meta.json.user_id、.meta.json.owner_user_id或.meta.json.created_by旧路径中的用户提示如/session/alice/sess-001单用户账号中唯一注册的用户对应源码实现见 legacy_migration.py 的_session_owner依次读取.meta.json中四个字段与_plan_one_session先 meta再 owner_hint再单用户推断。在多用户账号中无法识别所有者的旧 Session 会在 preflight 阶段直接失败——运行时兼容可以暂时保持该旧会话可读但应在迁移前修复所有者元数据。不会被迁移的内容旧 Agent 指令不会被迁移viking://agent/agent_id/instructions迁移会记录一条 warning且不会创建替代目录。对应源码在_plan_agent_tree中发现instructions目录只追加警告不生成TreeCopy操作legacy_migration.py。保留目录与规划器的保护逻辑源码中的_AGENT_RESERVED_SUBDIRS {skills, endpoints, tools, payments}legacy_migration.py是viking://agent/下属于新公共 scope 布局的保留子目录迁移规划器和清理规划器都不会把它们当作旧agent_id目录处理。这是升级后新旧数据能在同一 AGFS 树中并存而不互相干扰的关键设计。Preflight 预检哪些情况会失败、哪些只是警告**Preflight 失败不创建任务**的情况物理账号下存在旧数据但该账号不在 API key 用户注册表中多用户账号中存在无法识别所有者的旧 SessionSession 所有者存在但不是合法的 OpenViking user id。Preflight 记录警告或跳过、然后继续的情况目标用户已有同名 Skill旧 Skill 被跳过已有 Skill 不被覆盖发现旧 Agent 指令指令不迁移存在共享旧 Agent 但账号下没有任何目标用户。对应源码中preflight()legacy_migration.py会计算注册表账号与物理账号的差集对每个账号依次规划用户 Agent 数据、Agent 下用户数据、Sessions、共享 Agent 数据MigrationPlan.errors非空时run()直接抛出FailedPreconditionError携带details供诊断。两个补充事实如果迁移发现旧数据归属于注册表中缺失的用户会自动注册该用户。任务结果会记录创建的用户但不会返回明文用户密钥。如果开启了api_key_hashing明文密钥无法从存储中恢复需要重新生成密钥ov --sudo admin regenerate-key account_id user_id验证迁移结果检查任务结果ov --sudo task status task_id重点关注以下字段migrated.files/migrated.directoriesmigrated.vector_records/migrated.skipped_vector_recordsmigrated.operationsskippedwarningscreated_users这些字段的结构与 legacy_migration.py 中MigrationResult.to_dict()的输出一一对应operations按键排序包含agent_memories、agent_skills、sessions等类别计数created_users为{account_id, user_id}列表。验证新路径ov ls viking://user/user_id/peers/agent_id/memories ov ls viking://user/user_id/skills ov ls viking://user/user_id/sessions迁移只拷贝数据不会删除旧路径或旧向量记录。重复运行是幂等的已存在的目标文件与 Skill 会被跳过而不是覆盖。迁移流程本身从不触发 reindex检索不符合预期时请对新路径手动执行 reindex。应用代码迁移客户端配置迁移窗口期内旧配置可以继续工作{ agent_id: legacy-agent }推荐的新配置{ actor_peer_id: legacy-agent }不要同时配置两者{ actor_peer_id: customer-a, agent_id: legacy-agent }这会导致失败与兼容性矩阵中的配置同时存在即失败一致。文件路径旧路径viking://agent/code-agent/memories/profile.md viking://session/sess-001/messages.jsonl新路径viking://user/alice/peers/code-agent/memories/profile.md viking://user/alice/sessions/sess-001/messages.jsonlviking://session/session_id可以继续作为当前用户 Session 的只读别名但新的写入和长期引用应使用viking://user/user_id/sessions/session_id。find / searchfind/search不再接受旧的 Agent 身份字段也不会自动包含未迁移的旧 Agent 数据。旧的viking://agent/...路径仍可通过内容与文件系统 API 读取但在使用新检索路径之前必须先迁移。迁移完成、旧 Agent 数据不再需要后将所有客户端切到客户端/请求级的actor_peer_id。Session 消息Session 不再从旧 Agent id 推导消息归属。只要需要发言人身份就必须显式指定消息peer_id。延迟迁移过渡窗口的边界作为短期过渡是可以接受的但有明确的限制旧 Agent / Session 数据可读但旧命名空间不可写新 Session 与新资源写入新命名空间因此新旧路径会同时存在一段时间find/search默认不搜索旧的viking://agent数据多用户账号中缺少清晰所有者元数据的旧 Session运行时可能可读但会无法通过正式迁移的 preflight旧目录和旧向量记录会一直保留直到执行清理。这是一个迁移窗口而不是长期状态。可选清理验证通过后删除旧命名空间迁移验证通过后可以清理旧命名空间ov --sudo admin migrate --cleanup --output json ov --sudo task status cleanup_task_idHTTP 请求体{ action: cleanup }清理只删除以下目录/local/account/agent /local/account/session /local/account/user/user/agent清理流程legacy_migration.py会先删除这些旧 URI scope 下的旧向量记录再删除对应的 AGFS 目录。如果向量读取或删除失败该目录会被跳过避免文件被删掉而索引残留_AGENT_RESERVED_SUBDIRSskills / endpoints / tools / payments同样不会被当作旧 Agent 目录清理。清理不会删除新模型目录/local/account/user/user/peers /local/account/user/user/sessions /local/account/user/user/skills清理完成后viking://agent/...不再是读取已迁移 peer 数据的方式请使用新路径viking://session/...仍可作为当前用户新 Session 的别名。常见问题FAQov ls viking://agent只显示一个 Agent如果配置了agent_id或actor_peer_id这是预期行为——viking://agent根目录会被过滤到当前 actor peer。对应源码依据见 namespace.py 中is_hidden_by_actor_peer_view/may_include_hidden_actor_peersactor peer 视图会隐藏其他 peer 的旧 Agent 数据。ov ls viking://session仍然为空请确认服务器已用 0.4.0 重启。viking://session的合并读取视图运行在服务器端只升级 CLI 是不够的。配置中同时存在 actor_peer_id 和 agent_id不允许。保留agent_id走旧模式或者移除它改用actor_peer_id。Preflight 报告未知账号物理存储中存在某账号的旧数据但该账号不在 API key 注册表中。请先恢复或重建该账号再执行迁移。Preflight 报告无法解析 Session 所有者给旧 Session 的.meta.json添加所有者元数据或者把 Session 移到能明确标识所有者的路径下然后重新运行迁移。某个 Skill 没有迁移检查任务的skipped列表。常见原因是目标用户已有同名 Skill——迁移不会覆盖已有 Skill对应源码见_plan_agent_skills中的target skill already exists跳过逻辑legacy_migration.py。小结OpenViking 0.4.0 的 User / Peer 模型迁移是一次典型的兼容优先、渐进式升级通过服务器端只读兼容视图与agent_id→actor_peer_id的平滑映射让旧应用在迁移窗口期内继续运行通过幂等的拷贝式迁移与向量记录搬运让数据可以安全地分步搬入新命名空间通过 preflight 预检、任务化执行与可选清理让整个过程可观察、可回退、可验证。升级完成后应用的长期正确姿势是以viking://user/user_id/...为唯一写入路径以请求级actor_peer_id承载交互身份并在需要发言人身份时显式指定消息peer_id。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/11 9:48:15 · 阅读 1.2k OpenViking 0.3.x 到 0.4.0 升级与数据迁移指南：User / Peer 新数据模型实战
OpenViking 0.3.x 到 0.4.0 升级与数据迁移指南User / Peer 新数据模型实战【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking从 0.3.x 升级到 0.4.0 的核心变化是 OpenViking 从Agent 为中心的数据组织方式切换到User / Peer模型User 代表自然人或业务用户Peer 代表该用户下的交互身份Session 与 Skill 都归属到具体 User 之下。本篇指南面向已经在运行 OpenViking 0.3.x 的用户完整讲解升级前需要做的准备、0.4.0 对旧用法的兼容边界、旧 Agent / Session 数据的迁移流程含 HTTP API 与ovCLI 两种操作方式、迁移结果的验证方法、应用代码改造要点以及可选的历史数据清理。读完本篇你将掌握一次可回退、可验证、可清理的完整升级路径。升级决策的核心结论是0.4.0 不强制你立刻迁移数据——服务器端保留了旧数据的运行时可读性但新的写入路径、检索行为与actor_peer_id请求级视图只属于新模型。迁移本身也设计为幂等且非破坏性只拷贝、不删除出问题可随时重跑。升级决策留在 0.3.x 与升级 0.4.0 的取舍如果继续停留在 0.3.x现有的agent_id、viking://agent/...、viking://session/...行为完全不变但你也无法使用 0.4.0 的新模型与工具没有 User / Peer 数据模型没有旧 Agent / Session 的迁移与清理命令没有请求级的actor_peer_id视角围绕新模型的后续修复与功能不会回移植到旧模型。如果升级到 0.4.0不需要立刻迁移数据运行时保持兼容旧数据依然可读agent_id可以临时继续配置。在当前的 HTTP SDK 客户端中它映射为请求级actor_peer_idviking://agent/...仍然可以读取旧 Agent 数据但只读viking://session/...仍然可以读取旧 Session 数据并与新的 Session 视图合并展示。官方推荐的操作顺序是备份 - 升级 Server / CLI / SDK - 验证旧数据仍可读 - 执行数据迁移 - 验证新路径 - 逐步更新应用用法 - 可选执行清理这一顺序保证任何一步出问题都能回到上一步先备份、再升级、确认兼容后迁移最后才清理。第一步先备份使用 0.3.x 兼容的包创建备份官方推荐0.3.24pip install openviking0.3.24 --upgrade --force-reinstall ov backup ./backups/openviking-before-0.4.0.ovpack先确认当前版本避免误操作python -c import openviking; print(openviking.__version__) ov version注意不要在 0.3.x 上运行ov --sudo admin migrate。迁移命令只在 0.4.0 及以后版本提供旧版本不存在该子命令强行执行不会得到预期结果。第二步升级 Server 与客户端安装 0.4.0重启服务器并确保 CLI / SDK 客户端与服务器保持同一版本线pip install openviking0.4.0 --upgrade --force-reinstall openviking-server --config ov.conf如果你使用的是仓库中编译的 RustovCLI需要重新构建或重新安装否则 PATH 上的ov二进制可能仍是旧版本导致命令行为与服务器不一致。升级后验证配置与旧数据读取ov config validate ov ls viking://agent ov ls viking://session ov session list一个关键点viking://session的合并兼容视图是在服务器端实现的只升级 CLI 不会改变服务器侧的读取行为。如果ov ls viking://session仍然为空请先确认服务器已经以 0.4.0 重启。兼容性矩阵旧用法在 0.4.0 中的行为下表完整列出常见旧用法在 0.4.0 中的表现是升级期间排查问题的依据旧用法0.4.0 行为客户端配置agent_id受支持。在当前 HTTP SDK 客户端中映射为请求级actor_peer_id不再单独触发旧 Agent 模式。ov ls viking://agent支持读取。若设置了agent_id/actor_peer_id只显示当前 actor peer 的旧 Agent。读取viking://agent/agent_id/...支持读取旧数据。写入viking://agent/...不支持。新写入应使用viking://user/user_id/peers/peer_id/...。ov ls viking://session支持读取。合并展示新旧 Session。读取viking://session/session_id/...支持。优先新路径旧路径作为回退。写入viking://session/...不支持。新 Session 写入viking://user/user_id/sessions/...。使用 HTTP SDKagent_id执行find/search支持。仅搜索选定的 actor peer 视图不会自动搜索未迁移的旧 Agent 数据。find/searchbody 中的peer_id不支持。新 peer 视图请使用actor_peer_id或X-OpenViking-Actor-Peer请求头。同时配置actor_peer_id和agent_id不支持。客户端/请求直接失败。使用 HTTP SDKagent_id时显式指定消息peer_id支持。消息使用显式peer_id省略时不会从agent_id推断身份。role_id内存隔离不支持。升级后该字段被忽略。从源码结构可以推断viking://session的兼容读路径在 namespace.py 中由canonical_session_root/is_session_uri支撑is_session_uri同时识别viking://session/...旧与viking://user/user/sessions/...新两种形式这正是新旧合并视图在 URI 分类层面的依据。第三步执行迁移确认旧数据可读后运行迁移ov --sudo admin migrate --output json响应返回一个任务 ID{ task_id: ... }查询任务状态ov --sudo task status task_id ov --sudo task list --task-type legacy_migrationHTTP API 方式body 可为空等价于{action: migrate}POST /api/v1/admin/migrate X-API-Key: root-key{ action: migrate }查询任务GET /api/v1/tasks/{task_id} X-API-Key: root-key从源码看admin.py 中POST /migrate端点要求 ROOT 权限require_auth_root先执行LegacyDataMigration.preflight()只有 preflight 无错误才创建任务并异步执行。任务类型为legacy_migration清理时为legacy_cleanup且ROOT 查询迁移任务时不受普通账号/用户过滤限制——迁移会为整个存储创建一个 root 级任务而不是每个账号一个任务。迁移规则旧数据落到哪里0.4.0 采用 User / Peer 模型User 自然人或业务用户 Peer User 之下的交互身份 Session User 之下的会话状态 Skill User 之下可执行的技能迁移目标映射旧数据新位置viking://agent/agent_id/memories/...viking://user/user_id/peers/agent_id/memories/...viking://agent/agent_id/resources/...viking://user/user_id/peers/agent_id/resources/...viking://agent/agent_id/skills/skill/...viking://user/user_id/skills/skill/...viking://session/session_id/...viking://user/user_id/sessions/session_id/...共享的旧 Agent 数据会拷贝到每个目标用户的 peer 目录如果旧路径已经标识出某个用户所有者则只迁移到该用户。向量记录的迁移细节迁移不只是拷贝文件。对于实际被拷贝的 memory / resource / skill 文件或目录迁移会读取旧记录的vector/sparse_vector与标量字段、重写 URI、写入新记录。底层实现在 vector_migration.py 的copy_vector_records中通过_records_in_scope按 URI 范围过滤旧向量记录_MAX_VECTOR_RECORDS_PER_SCOPE为单范围上限 100,000 条达到上限会告警并提示手动 reindex对每条记录调用rewrite_vector_record重算id、uri、owner_user_id、owner_space、context_type并保留原有向量载荷然后upsert写入。需要注意迁移不会重新做 embedding也不会自动调用reindex。如果迁移后检索结果不符合预期需要对新路径手动执行 reindex。共享旧 Agent 数据拷贝给多个用户时向量记录会按目标用户 URI 各拷贝一次。纯标量记录没有向量载荷会被跳过并计入migrated.skipped_vector_records。Session 迁移只拷贝文件状态不处理向量记录。Session 所有者的解析顺序Session 所有者按以下顺序解析.meta.json.created_by_user_id.meta.json.user_id、.meta.json.owner_user_id或.meta.json.created_by旧路径中的用户提示如/session/alice/sess-001单用户账号中唯一注册的用户对应源码实现见 legacy_migration.py 的_session_owner依次读取.meta.json中四个字段与_plan_one_session先 meta再 owner_hint再单用户推断。在多用户账号中无法识别所有者的旧 Session 会在 preflight 阶段直接失败——运行时兼容可以暂时保持该旧会话可读但应在迁移前修复所有者元数据。不会被迁移的内容旧 Agent 指令不会被迁移viking://agent/agent_id/instructions迁移会记录一条 warning且不会创建替代目录。对应源码在_plan_agent_tree中发现instructions目录只追加警告不生成TreeCopy操作legacy_migration.py。保留目录与规划器的保护逻辑源码中的_AGENT_RESERVED_SUBDIRS {skills, endpoints, tools, payments}legacy_migration.py是viking://agent/下属于新公共 scope 布局的保留子目录迁移规划器和清理规划器都不会把它们当作旧agent_id目录处理。这是升级后新旧数据能在同一 AGFS 树中并存而不互相干扰的关键设计。Preflight 预检哪些情况会失败、哪些只是警告**Preflight 失败不创建任务**的情况物理账号下存在旧数据但该账号不在 API key 用户注册表中多用户账号中存在无法识别所有者的旧 SessionSession 所有者存在但不是合法的 OpenViking user id。Preflight 记录警告或跳过、然后继续的情况目标用户已有同名 Skill旧 Skill 被跳过已有 Skill 不被覆盖发现旧 Agent 指令指令不迁移存在共享旧 Agent 但账号下没有任何目标用户。对应源码中preflight()legacy_migration.py会计算注册表账号与物理账号的差集对每个账号依次规划用户 Agent 数据、Agent 下用户数据、Sessions、共享 Agent 数据MigrationPlan.errors非空时run()直接抛出FailedPreconditionError携带details供诊断。两个补充事实如果迁移发现旧数据归属于注册表中缺失的用户会自动注册该用户。任务结果会记录创建的用户但不会返回明文用户密钥。如果开启了api_key_hashing明文密钥无法从存储中恢复需要重新生成密钥ov --sudo admin regenerate-key account_id user_id验证迁移结果检查任务结果ov --sudo task status task_id重点关注以下字段migrated.files/migrated.directoriesmigrated.vector_records/migrated.skipped_vector_recordsmigrated.operationsskippedwarningscreated_users这些字段的结构与 legacy_migration.py 中MigrationResult.to_dict()的输出一一对应operations按键排序包含agent_memories、agent_skills、sessions等类别计数created_users为{account_id, user_id}列表。验证新路径ov ls viking://user/user_id/peers/agent_id/memories ov ls viking://user/user_id/skills ov ls viking://user/user_id/sessions迁移只拷贝数据不会删除旧路径或旧向量记录。重复运行是幂等的已存在的目标文件与 Skill 会被跳过而不是覆盖。迁移流程本身从不触发 reindex检索不符合预期时请对新路径手动执行 reindex。应用代码迁移客户端配置迁移窗口期内旧配置可以继续工作{ agent_id: legacy-agent }推荐的新配置{ actor_peer_id: legacy-agent }不要同时配置两者{ actor_peer_id: customer-a, agent_id: legacy-agent }这会导致失败与兼容性矩阵中的配置同时存在即失败一致。文件路径旧路径viking://agent/code-agent/memories/profile.md viking://session/sess-001/messages.jsonl新路径viking://user/alice/peers/code-agent/memories/profile.md viking://user/alice/sessions/sess-001/messages.jsonlviking://session/session_id可以继续作为当前用户 Session 的只读别名但新的写入和长期引用应使用viking://user/user_id/sessions/session_id。find / searchfind/search不再接受旧的 Agent 身份字段也不会自动包含未迁移的旧 Agent 数据。旧的viking://agent/...路径仍可通过内容与文件系统 API 读取但在使用新检索路径之前必须先迁移。迁移完成、旧 Agent 数据不再需要后将所有客户端切到客户端/请求级的actor_peer_id。Session 消息Session 不再从旧 Agent id 推导消息归属。只要需要发言人身份就必须显式指定消息peer_id。延迟迁移过渡窗口的边界作为短期过渡是可以接受的但有明确的限制旧 Agent / Session 数据可读但旧命名空间不可写新 Session 与新资源写入新命名空间因此新旧路径会同时存在一段时间find/search默认不搜索旧的viking://agent数据多用户账号中缺少清晰所有者元数据的旧 Session运行时可能可读但会无法通过正式迁移的 preflight旧目录和旧向量记录会一直保留直到执行清理。这是一个迁移窗口而不是长期状态。可选清理验证通过后删除旧命名空间迁移验证通过后可以清理旧命名空间ov --sudo admin migrate --cleanup --output json ov --sudo task status cleanup_task_idHTTP 请求体{ action: cleanup }清理只删除以下目录/local/account/agent /local/account/session /local/account/user/user/agent清理流程legacy_migration.py会先删除这些旧 URI scope 下的旧向量记录再删除对应的 AGFS 目录。如果向量读取或删除失败该目录会被跳过避免文件被删掉而索引残留_AGENT_RESERVED_SUBDIRSskills / endpoints / tools / payments同样不会被当作旧 Agent 目录清理。清理不会删除新模型目录/local/account/user/user/peers /local/account/user/user/sessions /local/account/user/user/skills清理完成后viking://agent/...不再是读取已迁移 peer 数据的方式请使用新路径viking://session/...仍可作为当前用户新 Session 的别名。常见问题FAQov ls viking://agent只显示一个 Agent如果配置了agent_id或actor_peer_id这是预期行为——viking://agent根目录会被过滤到当前 actor peer。对应源码依据见 namespace.py 中is_hidden_by_actor_peer_view/may_include_hidden_actor_peersactor peer 视图会隐藏其他 peer 的旧 Agent 数据。ov ls viking://session仍然为空请确认服务器已用 0.4.0 重启。viking://session的合并读取视图运行在服务器端只升级 CLI 是不够的。配置中同时存在 actor_peer_id 和 agent_id不允许。保留agent_id走旧模式或者移除它改用actor_peer_id。Preflight 报告未知账号物理存储中存在某账号的旧数据但该账号不在 API key 注册表中。请先恢复或重建该账号再执行迁移。Preflight 报告无法解析 Session 所有者给旧 Session 的.meta.json添加所有者元数据或者把 Session 移到能明确标识所有者的路径下然后重新运行迁移。某个 Skill 没有迁移检查任务的skipped列表。常见原因是目标用户已有同名 Skill——迁移不会覆盖已有 Skill对应源码见_plan_agent_skills中的target skill already exists跳过逻辑legacy_migration.py。小结OpenViking 0.4.0 的 User / Peer 模型迁移是一次典型的兼容优先、渐进式升级通过服务器端只读兼容视图与agent_id→actor_peer_id的平滑映射让旧应用在迁移窗口期内继续运行通过幂等的拷贝式迁移与向量记录搬运让数据可以安全地分步搬入新命名空间通过 preflight 预检、任务化执行与可选清理让整个过程可观察、可回退、可验证。升级完成后应用的长期正确姿势是以viking://user/user_id/...为唯一写入路径以请求级actor_peer_id承载交互身份并在需要发言人身份时显式指定消息peer_id。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考