OpenViking v0.4.12 Release Notes

Release date: 2026-08-01

[Full Changelog](v0.4.11...v0.4.12)

中文

版本摘要

v0.4.12 让 OpenViking 从“统一保存与检索上下文”进一步走向“基于上下文生产知识”。本版本的核心是全新的 ov compile：它可以读取 viking:// 中的来源，按照指定 Skill 在独立 AgentLoop 中完成整理、校验和提交，并将结果写回目标 URI。

围绕完整的上下文生命周期，本版本还新增了 OpenViking Assets Manifest、按逻辑轮次保留 Session 上下文、任务取消和单文件快照 Diff。同时，Session 与 Memory、存储可靠性、解析与检索、文档测试和安全边界均获得了系统性改进。

升级前请重点检查两项行为变化：HTTP Server 的 Agent Evolution 默认关闭；旧 Code API 与 MCP Code Tools 已移除。具体影响与迁移动作见“升级说明”。

新功能

⭐ 核心亮点：ov compile，从上下文生成可复用知识

ov compile 是一个由 Skill 驱动的异步编译任务。它读取一个或多个 viking:// 来源目录，使用当前认证用户的权限加载指定 Skill，在任务独享的 AgentLoop 中生成并校验产物，最后将产物提交到目标 Resource、Memory 或受支持的 Skill 命名空间。

viking:// 来源 → Skill → 独立 AgentLoop → 产物校验 → 目标 URI

这使 OpenViking 不再只负责“找到已有上下文”，还可以把分散的研究材料、项目记录或长期记忆编译为结构稳定、可继续浏览和检索的知识库。例如，将研究目录整理为研究 Wiki：

ov compile \
  --from viking://resources/research \
  --to viking://resources/research-wiki \
  --skill viking://user/default/skills/research-compiler \
  --reason "追踪历史进展，并保留支撑证据。" \
  --wait

• --from 可重复指定多个来源目录；--to 是产物目标目录；--skill 指向 Skill 目录或 SKILL.md。
• 不加 --wait 时，命令立即返回 Task ID；也可通过 GET /bot/v1/compile/{task_id} 查询任务状态。
• 完成结果会区分 created、updated 和 unchanged，并返回页面数、链接数、警告和 OKF 版本，便于审计编译产物。
• --timeout 只限制 CLI 本地等待时间，不会取消 Server 上仍在执行的任务。
• Compile 默认不能使用 Direct Sandbox 执行主机命令。若 Skill 声明的二进制或环境变量不可用，任务会以 SKILL_CAPABILITY_UNAVAILABLE 失败。显式开启 Direct Sandbox 会让编译代码继承 VikingBot 主机权限，应仅在可信环境中使用。
• 任务只对创建它的 Principal 可见；并发达到准入上限时会返回 429 RESOURCE_EXHAUSTED。

OpenViking Assets Manifest：用声明式清单管理外部资产

OpenViking Assets Manifest 使用 openviking-assets/1 协议，以 YAML 声明资产目录、连接方式和参数。它支持内联或独立 Catalog、凭据别名、Git 只读预检、Dry Run、Create/Sync 状态记录和 Watch 间隔覆盖，适合把可重复同步的资产配置纳入版本管理。

最小 Manifest：

protocol: openviking-assets/1

catalog:
  - name: openviking
    connector: git
    params:
      repo_url: https://github.com/volcengine/OpenViking
      branch: main

先执行 Dry Run 检查协议、认证引用和远端 Git 可访问性，再执行实际同步：

ov add-resource --manifest manifest.yaml --args dry_run:true
ov add-resource --manifest manifest.yaml --wait --timeout 600

Dry Run 只输出 Create/Sync 计划，不会创建本地副本、Resource、任务或状态文件。执行状态保存在 <manifest>.state.json；从 Manifest 中移除资产只会将其标记为 Orphan，不会自动删除已有内容。同一个 Manifest 当前不提供跨进程锁，请避免并发执行。

Session 按逻辑轮次保留上下文

Session Commit 新增 turn_budget 保留模式。它按完整的用户轮次而不是固定消息条数保留最近上下文，并允许通过 Token Budget 控制原始内容规模；当某一轮只能部分保留时，会生成 Checkpoint，确保后续归档摘要能够按顺序继续推进。

通过 Commit API 启用：

curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/commit \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "retention_mode": "turn_budget",
    "keep_recent_turn_count": 2,
    "retained_message_token_budget": 12000,
    "min_raw_tail_steps": 2
  }'

keep_recent_turn_count 控制至少保留的最近轮次数，retained_message_token_budget 控制保留内容的 Token 上限，min_raw_tail_steps 保证尾部至少保留指定数量的原始步骤。Commit 仍然先同步创建归档，再异步执行摘要和长期记忆抽取，并返回可查询的 Task ID。

可取消的后台任务

任务系统新增协作式取消。取消请求会阻止任务继续提交新的 QueueFS 工作，并尝试中止当前进程内仍在运行的工作；状态会从 cancelling 进入 cancelled，重复取消保持幂等。

ov task cancel uuid-xxx

也可通过 Python SDK 调用 await client.cancel_task("uuid-xxx")。当前支持取消 add_resource、session_commit、admin_reindex 和 snapshot_restore_reindex。只有创建任务的当前用户可以取消；ROOT 不会越过任务所有权。已经完成的写入不会回滚，因此调用方应按任务最终状态和返回产物判断结果。

单文件 Snapshot Diff

Snapshot 新增 UTF-8 文本文件的 Unified Diff，可比较两个提交引用中的同一路径，并明确返回 added、deleted、modified 或 unchanged。

ov snapshot diff viking://resources/my_project/guide.md \
  --from 3f2a1b9c \
  --to 9a0b1c2d

Python SDK 可使用 client.snapshot.diff(path, from_ref=..., to_ref=...)，TypeScript SDK 和 HTTP API 也提供同等能力。to_ref 必填；省略 from_ref 时旧侧按空文件处理。每侧文件上限为 10 MiB 和 100,000 行，生成的 Diff 上限为 20 MiB；超限会返回 RESOURCE_EXHAUSTED，不会静默截断。

更新

Session 与 Memory

• 强化连续快速 Commit 的生命周期处理：归档创建、异步摘要、长期记忆任务和任务状态现在保持更清晰的因果关系，避免一次 Commit 错误消费另一轮的工作。
• 改进归档恢复与累计 Checkpoint。摘要按归档顺序推进，部分失败或恢复后不会跳过尚未纳入的历史区间。
• Phase 2 任务会记录真实 Token 使用量；Session History 和相关 SDK 路径补齐异步实现，降低长会话中的阻塞。
• 改进长期记忆去重与批量删除，补齐 delete_ids 语义，并清理指向不存在 Experience 的悬空关联。
• Session Append、Commit 和取消边界得到统一，已完成工作不会被外围状态误报为未完成或被意外覆盖。

存储、解析与检索

• S3 在递归删除部分成功时会正确失效缓存；索引清理失败时保留权威源内容，避免索引状态反向决定文件系统事实。
• LocalFS 加强挂载目录边界与写入标志校验；Vault 临时不可用时返回 503，不再重写 Root Key。
• 修复 PDF 重复 XObject、MPEG-TS 与 TypeScript 扩展名冲突、文本元数据、URL 文件名和 Markdown 本地图片解析问题。
• 改进 Search/Memory 类型判定、按账号隔离的 Watch URI、递归检索和 Rerank 边界，并优化 Markdown、Excel、Session Context 和常见检索路径的性能。

文档、测试与安全

• 扩展中英文 API 与集成文档，覆盖 Compile、Snapshot、Tasks 和 Session Commit。
• 增加针对 Compile 生命周期、Turn-aware Retention、任务取消、Snapshot Diff 和存储失败边界的契约测试。
• 收紧身份、任务所有权、文件路径、凭据和 Sandbox 边界，错误响应保留 Server、Network、Timeout、Auth、Conflict 与资源耗尽等可操作分类。

其他更新

• LangChain/LangGraph 集成补齐原生异步调用和请求级 Actor Peer，并改善异步历史、关闭与取消行为。
• VikingBot Chat API 支持 OpenAI 风格的图片输入。

升级说明

1. HTTP Server 的 Agent Evolution 默认关闭

受影响对象： 依赖 HTTP Server 在 Session Commit 后自动生成或更新 Cases、Trajectories、Experiences 的部署。

v0.4.12 中，HTTP Server 的 server.agent_evolution.enabled 默认为 false。关闭后，已有 Evolution 内容仍可读取和检索，但新的 Commit 不再生成或更新这些产物。Embedded/Local 模式保持历史启用行为。

如需延续原行为，请在解析后的 ov.conf 中显式开启：

{
  "server": {
    "agent_evolution": {
      "enabled": true
    }
  }
}

Server 会在每次 Commit 时读取当前有效配置，合法修改无需重启。

2. 旧 Code API 与 MCP Code Tools 已移除

受影响对象： 调用 /api/v1/code/outline、/api/v1/code/search、/api/v1/code/expand，或使用 MCP code_outline、code_search、code_expand 的客户端。

这些专用接口已移除。请改用固定的 Skeleton-first 代码摘要，以及通用 read、grep、find、search 能力。升级前应搜索自动化脚本、Agent Prompt 和 MCP Tool Allowlist 中的旧名称，并同步调整调用方式。

English

Summary

OpenViking v0.4.12 advances from unified context storage and retrieval toward knowledge production grounded in that context. The headline feature is the new ov compile command: it reads sources under viking://, applies a selected Skill in an isolated AgentLoop, validates the generated artifacts, and commits them to a target URI.

The release also adds OpenViking Assets Manifest, turn-aware Session retention, task cancellation, and single-file Snapshot Diff. Session and Memory lifecycles, storage reliability, parsing and retrieval, documentation, testing, and security boundaries all receive substantial improvements.

Before upgrading, review two behavior changes in particular: Agent Evolution is disabled by default for HTTP Server deployments, and the legacy Code APIs and MCP Code Tools have been removed. See Upgrade Notes for the exact impact and migration actions.

New Features

⭐ Headline: ov compile turns context into reusable knowledge

ov compile is an asynchronous, Skill-driven compilation task. It reads one or more viking:// source directories with the authenticated user's permissions, loads the selected Skill, generates and validates artifacts in a task-specific AgentLoop, and commits them to a target Resource, Memory, or supported Skill namespace.

viking:// sources → Skill → isolated AgentLoop → artifact validation → target URI

OpenViking can now do more than retrieve existing context: it can compile distributed research, project records, or long-term memories into structured knowledge that remains browsable and searchable. For example, compile a research directory into a research wiki:

ov compile \
  --from viking://resources/research \
  --to viking://resources/research-wiki \
  --skill viking://user/default/skills/research-compiler \
  --reason "Track historical progress and preserve supporting evidence." \
  --wait

• Repeat --from to provide multiple source directories. --to selects the artifact directory, and --skill accepts a Skill directory or SKILL.md URI.
• Without --wait, the command returns a Task ID immediately. Status is also available from GET /bot/v1/compile/{task_id}.
• Completed results distinguish created, updated, and unchanged artifacts and report page count, link count, warnings, and the OKF version.
• --timeout limits local CLI polling only; it does not cancel the server-side task.
• Compile cannot execute host commands through the Direct Sandbox by default. A Skill that declares unavailable binaries or environment variables fails with SKILL_CAPABILITY_UNAVAILABLE. Enabling the Direct Sandbox explicitly gives compiled code VikingBot host privileges and should be restricted to trusted environments.
• A task is visible only to the Principal that created it. Admission overflow returns 429 RESOURCE_EXHAUSTED.

OpenViking Assets Manifest for declarative asset management

OpenViking Assets Manifest uses the openviking-assets/1 protocol to declare asset catalogs, connectors, and parameters in YAML. It supports inline or separate catalogs, credential aliases, read-only Git preflight, dry runs, Create/Sync state, and watch interval overrides, making repeatable asset synchronization suitable for version control.

Minimal manifest:

protocol: openviking-assets/1

catalog:
  - name: openviking
    connector: git
    params:
      repo_url: https://github.com/volcengine/OpenViking
      branch: main

Run a dry run to validate the protocol, credential references, and remote Git access before applying the plan:

ov add-resource --manifest manifest.yaml --args dry_run:true
ov add-resource --manifest manifest.yaml --wait --timeout 600

A dry run only reports the Create/Sync plan; it creates no checkout, Resource, task, or state file. State is stored in <manifest>.state.json. Removing an asset from the manifest marks it as an orphan instead of deleting existing content. The same manifest is not protected by a cross-process lock, so concurrent execution should be avoided.

Turn-aware Session retention

Session Commit adds the turn_budget retention mode. It preserves complete user turns instead of a fixed number of messages and uses a token budget to bound retained raw context. When only part of a turn can be retained, OpenViking creates a checkpoint so later archive summaries continue in order.

Enable it through the Commit API:

curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/commit \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "retention_mode": "turn_budget",
    "keep_recent_turn_count": 2,
    "retained_message_token_budget": 12000,
    "min_raw_tail_steps": 2
  }'

keep_recent_turn_count preserves at least the requested number of recent turns, retained_message_token_budget bounds retained tokens, and min_raw_tail_steps keeps a minimum raw tail. Commit still creates the archive synchronously, then runs summarization and long-term memory extraction asynchronously and returns a queryable Task ID.

Cancellable background tasks

The task system now supports cooperative cancellation. A cancellation request prevents new QueueFS work from being submitted and attempts to stop in-process work that is still running. Status transitions from cancelling to cancelled, and repeated cancellation remains idempotent.

ov task cancel uuid-xxx

The Python SDK also supports await client.cancel_task("uuid-xxx"). Cancellation currently covers add_resource, session_commit, admin_reindex, and snapshot_restore_reindex. Only the current user who created the task may cancel it; ROOT does not bypass task ownership. Completed writes are not rolled back, so consumers should use the final task status and returned artifacts to determine the outcome.

Single-file Snapshot Diff

Snapshot now provides Unified Diff for UTF-8 text files at two commit references and reports added, deleted, modified, or unchanged explicitly.

ov snapshot diff viking://resources/my_project/guide.md \
  --from 3f2a1b9c \
  --to 9a0b1c2d

The Python SDK exposes client.snapshot.diff(path, from_ref=..., to_ref=...), with equivalent TypeScript SDK and HTTP APIs. to_ref is required; omitting from_ref treats the old side as empty. Each side is limited to 10 MiB and 100,000 lines, and the generated diff is limited to 20 MiB. Oversized input returns RESOURCE_EXHAUSTED instead of a silently truncated diff.

Updates

Session and Memory

• Rapid consecutive Commits now maintain a clearer causal relationship among archive creation, asynchronous summaries, long-term memory work, and task state, preventing one Commit from consuming another turn's work.
• Archive recovery and cumulative checkpoints are more robust. Summaries advance in archive order without skipping history that was not incorporated before a partial failure or recovery.
• Phase 2 tasks report actual token usage. Session History and related SDK paths gain async implementations to reduce blocking in long-running sessions.
• Long-term memory deduplication and batch deletion are improved, including consistent delete_ids semantics and cleanup of dangling Experience links.
• Session Append, Commit, and cancellation boundaries are aligned so completed work is not overwritten or misreported by surrounding state.

Storage, parsing, and retrieval

• S3 cache entries are invalidated correctly after partially successful recursive deletion. Source-of-truth content is preserved when index cleanup fails, preventing index state from overruling filesystem state.
• LocalFS strengthens mount containment and write-flag validation. A temporarily unavailable Vault returns 503 instead of rewriting the Root Key.
• Fixes cover duplicated PDF XObjects, MPEG-TS versus TypeScript extension detection, text metadata, URL-derived filenames, and local images in Markdown.
• Search/Memory type resolution, account-scoped Watch URIs, recursive retrieval, and Rerank boundaries are improved, along with performance for Markdown, Excel, Session Context, and common retrieval paths.

Documentation, tests, and security

• Expanded Chinese and English API and integration documentation covers Compile, Snapshot, Tasks, and Session Commit.
• New contract tests cover Compile lifecycle, turn-aware retention, cancellation, Snapshot Diff, and storage failure boundaries.
• Identity, task ownership, filesystem path, credential, and Sandbox boundaries are tightened while errors preserve actionable Server, Network, Timeout, Auth, Conflict, and resource-exhaustion categories.

Other updates

• LangChain/LangGraph integrations add native async execution and request-scoped Actor Peers, with improved async history, shutdown, and cancellation behavior.
• The VikingBot Chat API accepts OpenAI-style image inputs.

Upgrade Notes

1. Agent Evolution is disabled by default for HTTP Server deployments

Affected deployments: HTTP Server users that expect Session Commit to generate or update Cases, Trajectories, or Experiences automatically.

In v0.4.12, server.agent_evolution.enabled defaults to false for HTTP Server deployments. Existing Evolution content remains readable and searchable, but new Commits do not generate or update these artifacts while the feature is disabled. Embedded/Local mode retains its previous enabled behavior.

To preserve the previous HTTP Server behavior, enable it explicitly in the resolved ov.conf:

{
  "server": {
    "agent_evolution": {
      "enabled": true
    }
  }
}

The Server reads the current resolved value at Commit time, so valid configuration changes do not require a restart.

2. Legacy Code APIs and MCP Code Tools have been removed

Affected clients: callers of /api/v1/code/outline, /api/v1/code/search, or /api/v1/code/expand, and users of MCP code_outline, code_search, or code_expand.

These specialized interfaces are no longer available. Migrate to the fixed skeleton-first code summary and the generic read, grep, find, and search capabilities. Before upgrading, search automation scripts, Agent prompts, and MCP Tool allowlists for the legacy names and update their calls together.