OpenViking v0.4.20 Release Notes / 发布说明

中文

版本概览

本文以 v0.4.18 为基线，覆盖升级到 v0.4.20 的全部变化，包含 v0.4.19 已引入的能力，共 95 个提交。

这次升级将 Compile 的任务管理移到 OpenViking：应用提交后，由 OpenViking 持久化、排队、查询和取消任务，Runtime 负责执行和写回产物。Git 技能由服务端统一导入与更新，Studio 增加用户记忆策略、Agent 经验视图和任务执行记录；记忆抽取默认采用受限 Python DSL，长会话按策略分批处理。飞书目录导入和资源权限继承也得到扩展。

升级时重点检查 Compile 旧接口停用、CLI 等待／超时参数移除，以及记忆抽取默认协议变化，详见下文的迁移表。

感谢社区在这段升级范围内的贡献，特别欢迎 7 位首次贡献者；完整名单与对应贡献见贡献者致谢。

主要更新

1. Compile 从 Bot 代理转为 OpenViking 托管任务

v0.4.18 中，OpenViking 将 Compile 请求转发给 VikingBot，由 Bot 创建和管理任务。v0.4.19 开始，任务生命周期由 OpenViking 托管；v0.4.20 在这条链路上补齐同目标排队、执行记录和凭证隔离。应用现在通过统一任务接口查看 Compile，与其他后台任务使用相同的查询和取消方式。

v0.4.18
应用 / CLI → OpenViking /bot/v1/compile 代理
           → VikingBot 创建任务 → 执行 Skill → 写回 OpenViking
查询 / 取消 → OpenViking Bot 代理 → VikingBot 任务记录

v0.4.20
应用 / CLI / SDK → OpenViking /api/v1/compile
                → 校验来源、Skill 和目标权限
                → 持久化任务 + 入队 → 返回 OpenViking task_id
                → 按目标调度 → Runtime 执行 → 写回 OpenViking
OpenViking      → 轮询 Runtime → 保存状态、结果和执行记录
应用            → /api/v1/tasks/{task_id} 查询 / 取消

同一 account 下，规范化后的 to 完全相同的 Compile 任务会轮转排队。例如，两次写入 viking://resources/team-wiki 的任务依次执行，另一个目标的任务仍可并行。任务不会合并；恢复时会保留已提交、尚未结束任务的目标占用。该调度由单个服务实例维护，按精确目标 URI 匹配，不提供跨实例或父子目录之间的互斥保证。

Studio 任务详情可查看持久化执行记录，包括创建、状态与阶段变化、错误，以及等待下游工作；HTTP 使用 include_events=true 获取记录。任务列表和详情统一以服务端状态为准。

接入独立 Runtime 时，OpenViking 调用 POST /runtime/v1/tasks，发送 {task_type: "compile", payload: {...}}，并以自身 task_id 设置 Idempotency-Key。Runtime 对同一用户、同一幂等键必须返回同一个 session_id；后续通过 /runtime/v1/tasks/status 和 /runtime/v1/tasks/cancel 查询与取消。两者的请求体均为 {"session_id":"..."}。OpenViking 会转交当前用户的 API Key，配置后还会发送 X-Gateway-Token。内置 VikingBot 使用相同协议。

链路变更见 #4436，目标排队见 #4863，完整请求协议见 Agent Runtime API。

2. Git 技能统一由服务端导入和更新

ov add-skill 与 ov skills add 现在使用相同参数和导入流程。支持 Git 仓库、GitHub 分支／子目录链接，以及本地技能目录；通过 --list 查看集合、--skill 选择技能。

HTTP POST /api/v1/skills 新增 Git URL 输入、skills 选择列表和 list_only 预览。服务端记录来源仓库、引用和子目录，后续 ov skills update 可从记录的 Git 来源更新。批量导入中的每个技能保留自己的后台任务 ID。远程仓库由服务端访问，本地文件仍通过上传接口传入。

3. Studio 增加用户记忆策略与 Agent 经验视图

在用户管理页创建用户时选择策略，也可以修改已有用户的策略。提供三种预设和自定义配置：

配置保存后生效，已有记忆保留；Session 自身的策略覆盖仍按既有优先级解析。自定义扩展类型必须已在服务端注册。Peer 记忆需要应用标记 peer_id，且不抽取 cases。

Studio 新增 Agent Experience 模块，可浏览经验资产、查看相关执行轨迹及结果分布，并沿关联记录追溯来源。结合账户级 Agent Evolution 开关，维护者可以检查经验是否生成、来自哪些会话，以及后续的使用记录。该页面展示已有记录，不代表对效果提升作出保证。

4. 记忆抽取默认使用受限 Python DSL，长会话分批处理

模型的记忆写入输出从默认 JSON 切换为受限 Python DSL。模型可以表达创建、字段修改、删除和关联等操作；服务端通过受限语法解析为既有记忆操作，再由统一写入流程处理。它不是任意 Python 执行环境，不开放模块导入、文件系统或网络访问，也不要求应用执行模型生成的脚本。原有记忆存储格式保持不变，仍可显式选择 JSON 协议。

读取较大记忆时，抽取器会提示检查内容是否需要整理、拆分或压缩；memory.maintenance_review_tokens 默认是 1,000，这是整理提示阈值，不是自动截断或删除阈值。

会话提交的 Phase 2 使用提交时保存的 auto_commit_policy，按 pending_token_threshold 和 message_count_threshold 分批处理长期记忆抽取；Working Memory 摘要也支持按批推进。分批优先保留完整用户轮次，超大轮次再按步骤／消息拆分，单条超大消息仍独立处理。同一次提交保留一个归档与任务，长期记忆各批次的变更合并到该归档的 memory_diff.json。未设置正数阈值时不启用这套分批限制。

相关变更：默认抽取协议 #4581、分批抽取 #4644。

5. 共享资源可限制权限继承

资源目录新增 acl_mode: "restricted"：该节点仅以直接授权计算访问权限，阻断父目录授权继续生效，其子目录继承限制后的有效权限。例如，团队共享目录下的项目子目录可以只向指定成员授权。

父目录授权仍会记录和更新，切回 inherit 时恢复继承最新授权。账户管理员的隐式管理权限仍有效；仅支持共享 viking://resources 范围。详见 ACL API。

6. 会话重置与插件记忆链路更可靠

• 新增会话提交参数 reset_context：清空后续注入的会话上下文，保留 Session ID、原始历史和长期记忆，并阻止后续摘要继续继承重置前的 overview。OpenClaw reset hook 已接入。
• OpenClaw 根据宿主版本选择 afterTurn 或 commitTurn 捕获消息；持久投递路径在写入失败时向宿主返回失败以便重试。召回改用本轮传入的 prompt，避免用历史消息代替当前问题。
• OpenClaw 可选择 commitRetentionMode: "turn_budget"，按用户轮次和 token 预算保留近期上下文；同时修复相关 pending_tokens 计数。
• Claude Code 与 Codex 插件增加有序正则输入过滤，可分别处理召回 query 和待捕获内容。
• dsh 插件在进程内重试待发送队列，短暂写入失败恢复后无需重启；pi 插件修复 camelCase toolResult 消息遗漏。

7. 飞书导入、解析桥接与实验示例

飞书导入支持 Drive 文件／文件夹，以及通过 args.feishu_recursive: true 递归导入 Wiki 子树。Wiki 默认仍只导入指定节点。目录先展开和准备内容，再按内容类型接入内部解析或 Understanding；配置外部解析后，文件夹中的文档和文件也能走同一导入流程。目录和文件准备使用飞书应用凭证或 args.feishu_access_token；args.lark_file 仅用于直接提交单文档的 Understanding 场景。

提供 LlamaParse v2 bridge，通过已有 Understanding API 接入托管解析服务，返回 Markdown 与图片。它是需要单独部署的示例服务，需要 LlamaCloud API Key；不支持视频、需凭证访问的文档 URL 或 lark_file 输入。

新增 pi 上下文管理实验：Agent 通过 new_context 归档当前窗口，以交接说明和 Working Memory 开启新窗口，并通过 history 回读历史。该扩展仍是实验示例，不应与原 openviking 扩展同时加载；其测试尚未纳入仓库常规 CI。

新功能用法

以下 CLI 示例假设已配置 OpenViking 连接，并具备对应目录权限。HTTP 示例中的 your-key、TASK_ID 和 SESSION_ID 需替换为实际值。

导入技能并运行 Compile

从本版本导入共享 LLM Wiki 技能：

ov add-skill https://github.com/volcengine/OpenViking/tree/v0.4.20/examples/compile/ov-compile-skills/llm-wiki \
  -p viking://agent/skills

ov task status TASK_ID

本地技能集合也可以先预览、再选择；以下命令在仓库根目录运行：

ov skills add ./examples/compile/ov-compile-skills --list
ov skills add ./examples/compile/ov-compile-skills \
  --skill llm-wiki daily-report

在共享技能导入任务为 completed，且来源目录 viking://resources/research 已准备好后运行：

ov compile \
  --from viking://resources/research \
  --to viking://resources/research-wiki \
  --skill viking://agent/skills/llm-wiki \
  --instruction "整理为可检索的团队知识库，为每个结论保留来源"

Compile 需要已配置的执行端。命令立即返回 task_id，后续查询：

ov task status TASK_ID

需要停止时执行 ov task cancel TASK_ID；收到 cancelling 后继续查询直到终态。

配置 Compile 执行端

本地使用内置 VikingBot 时，以 openviking-server --with-bot 启动，并配置好 Bot 所需模型。接入独立 Runtime 时，将以下字段合并到服务端 ov.conf 后重启；地址需替换为实际执行服务：

{
  "compile_api": {
    "base_url": "http://runtime.example:8080",
    "http_timeout_seconds": 10,
    "poll_interval_ms": 30000
  },
  "queue_workers": {
    "external_task": {"max_concurrent": 10}
  }
}

compile_api.base_url 非空时优先使用独立 Runtime；若两种执行端都未配置，Compile 不可用。外部调用需要可转交的 OpenViking 用户 API Key，可按执行服务要求另设 compile_api.gateway_token。http_timeout_seconds 是单次 HTTP 请求超时，poll_interval_ms 是轮询间隔，不是整个 Compile 的执行时限。内置 VikingBot 不接受非空 args；外部 Runtime 可按自身契约扩展参数。

限制子目录的继承权限

在拥有管理权限的共享资源子目录上设置直接授权并限制继承：

ov acl set viking://resources/team/project-a \
  --acl-mode restricted --entry user:bob=read

--acl-mode inherit 可恢复父目录授权的继承。

查询任务执行记录

curl -sS 'http://localhost:1933/api/v1/tasks/TASK_ID?include_events=true' \
  -H 'X-API-Key: your-key'

执行记录位于 HTTP 响应的 result.execution_events。收到 task_id 只表示已提交；completed 表示成功，failed、cancelled 表示其他终态，cancelling 仍需继续查询。停止查询或等待超时不会取消后台任务。

配置召回与捕获过滤

将相关配置合并到 ~/.openviking/ovcli.conf 的 plugin 段。以下示例对 Claude Code 去掉 query 的 ultrathink 前缀、跳过 slash／shell 命令召回，并在捕获内容中替换匹配到的 token：

{
  "plugin": {
    "claude_code": {
      "recallQueryFilters": ["s/^\\s*ultrathink\\s+//i", "d|^\\s*[/!]|"],
      "captureFilters": ["s/\\b(sk|ghp)_[A-Za-z0-9_-]{10,}/[redacted]/g"]
    }
  }
}

Codex 使用 plugin.codex 下的同名字段。规则支持替换、命中丢弃、仅命中保留，以及 user:／assistant: 角色前缀。这里只处理新发送的内容，不会重写已有记忆；示例正则也不是通用的密钥检测器。无效规则会被跳过，ov-memory-doctor 会报告错误。含逗号的规则需使用 JSON 数组，不能放入按逗号切分的环境变量列表。

重置会话上下文，或启用按轮次保留

清空指定会话的上下文：

curl -sS -X POST 'http://localhost:1933/api/v1/sessions/SESSION_ID/commit' \
  -H 'X-API-Key: your-key' \
  -H 'Content-Type: application/json' \
  -d '{"reset_context":true,"keep_recent_count":0}'

reset_context 不能与非零 keep_recent_count 或 retention_mode 同用。没有 live messages 时也会建立重置边界；旧归档的记忆提取仍可继续。本版本未新增 SDK／CLI 的专用 reset 参数。

若希望 OpenClaw 自动提交按轮次保留近期上下文，在已有 OpenClaw 插件配置中加入：

{
  "commitRetentionMode": "turn_budget"
}

这会使用服务端默认保留策略：最多 3 个最近用户轮次、12,000 token 预算，以及至少最后一个 assistant／tool step。最新轮次过大时会保留用户问题和近期步骤，并归档前缀；必要尾部可超过预算。commitKeepRecentCount 在此模式下不生效。未设置时仍按消息数保留，手动 commit 和 /compact 仍归档全部消息。

接入 LlamaParse bridge

按 bridge README 设置好 .env 中的 LLAMA_CLOUD_API_KEY 和至少 32 字符的 PARSER_BRIDGE_API_KEY 后，从仓库根目录启动：

uv run --env-file examples/llamaparse-understanding-bridge/.env \
  --project examples/llamaparse-understanding-bridge \
  openviking-llamaparse-bridge

将以下部分合并到 OpenViking 的 ov.conf，在启动服务端的环境中设置同一个 PARSER_BRIDGE_API_KEY，然后重启服务：

{
  "parser_api": {
    "enable": true,
    "host": "http://127.0.0.1:8080",
    "api_key": "${PARSER_BRIDGE_API_KEY}",
    "extensions": ["pdf", "docx", "pptx", "xlsx"],
    "http_timeout_seconds": 130
  }
}

host 必须是 OpenViking 可访问的 bridge 地址；跨容器部署也要正确设置 bridge 的 BRIDGE_PUBLIC_URL。保持 parser_api.enable_resumable_upload 关闭。仅配置的扩展名走该桥接；部分页面解析失败时，会保留可用 Markdown 并标注失败页。

MCP 按行读取文本

MCP read 新增 offset 与 limit，例如从第 101 行开始读取 40 行：

{"uris":"viking://resources/research/notes.md","offset":100,"limit":40}

offset 从 0 开始，limit: -1 表示不限制行数。图片和音频仍使用原有媒体返回方式。

体验与兼容性改进

• 检索与存储性能：VikingDB／Volcengine 客户端复用 HTTP 连接池；上下文组装与用户私有／共享技能检索复用请求内的 query embedding，并隔离单个等待者取消的影响。内部文件元数据检查不再默认查询路径锁，公开 HTTP stat 仍返回锁状态。
• 多用户管理：trusted 模式异步批量登记数据面请求中的 account／user，默认每 300 秒刷盘，不生成用户 API Key、不改已有角色或 group。登记后的身份最终可在既有管理接口查询。账户／用户列表按需要读取对应注册表，减少无关全量加载。
• 执行线程配置：新增 server.executor_threads，控制每个服务进程的 asyncio 默认线程池；0 沿用 Python 默认策略，与服务进程数 workers 分开配置。以下仅展示相关配置字段：

{
  "server": {
    "executor_threads": 32,
    "trusted_identity_flush_interval_seconds": 300
  }
}

将 trusted_identity_flush_interval_seconds 设为 0 可关闭上述身份登记。

• 飞书与 Lark：飞书通道可配置 domain，HTTP 与 WebSocket 使用同一域名。对接 Lark 时，在已有 type: "feishu" 的通道配置中加入：

{"domain":"https://open.larksuite.com"}

默认仍为飞书域名。飞书消息卡片支持显式 Markdown viking:// 图片引用，使用原始发送者身份读取图片；普通 URI 引用和代码示例不会触发发送。

升级与回滚注意事项

修复

• 本地向量库 schema 自动升级采用有界批量处理，降低大数据集升级时的内存占用；cp／mv 的向量路径查询统一后端算子，修复部分后端不兼容的问题。
• 本地文件／目录扫描保留正确的错误分类；队列消息的创建时间改为每实例生成，避免沿用模块加载时的时间。
• 插件将 camelCase isError 正确识别为工具失败；MCP 本地代理超时返回 -32004，与服务不可达区分。Codex 复用共享召回压缩流程。
• Understanding 上传保留原始文件名及已识别的扩展名，避免临时文件名或无扩展名标题导致外部解析器误判。
• 支持文件路径中的 #，修正 Markdown 引用编码与解析，并避免清理孤立向量时误删同名真实文件对应的记录。
• 启动／账户初始化补齐 viking://agent 及 skills、endpoints、tools、payments 的预设目录和缺失的 L0／L1 元数据，保留已有内容；异常摘要元数据不再阻断启动。
• 路径锁读取遇到并发写入产生的短暂残缺 token 时重读；摘要写入保留锁获取错误类型，使既有重试路径可以识别。
• S3／TOS 虚拟目录缺少修改时间时仍可列出；WebDAV GET 的 Content-Length 与实际返回字节一致。
• Windows PID 检查改用进程句柄查询，避免检查存活状态时向目标进程发送信号。
• 技能策略更新保留提取出的 description、allowed_tools 与 tags；重复删除已不存在的任务记录按删除成功处理。
• Studio 的 Agent Evolution 设置跟随所选 account；会话页按 Agent 消息分组，改善工具输出和聊天内容的可读性。
• Bot 使用 --with-bot 时保留配置的 OpenViking 凭证；代理正确传递 actor_peer_id；cron 文件使用原子替换，减少写入中断造成的损坏。
• X-Request-ID 允许斜杠；无效值会替换为新 ID，而非仅因追踪标识返回 400。
• OpenAI 兼容 VLM 后端将显式 reasoning_effort 与模型默认参数分开处理，避免第三方兼容模型被套用不合适的 token／temperature 参数。

文档、测试与安全

• 资源导入等示例统一采用“提交 → 保存 task_id → 查询终态”的流程，明确等待超时仅停止等待，不代表后台任务失败或被取消。
• Agent Plugins 新增 ov-memory-troubleshoot 技能，沿“记忆文件 → 归档 memory_diff.json → 会话消息”只读追溯异常抽取来源。
• Compile 转发执行参数时将 api_key／user_key 与公开任务数据分开，任务结果也会移除这些字段；Bot 代理移除客户端自带的 openviking_connection，再注入经过认证的身份。
• Bot 的 send:// 只接受单个文件名，拒绝包含路径的输入；Git 技能导入校验来源地址、子目录与符号链接边界。
• MCP search 的上下文参数校验与 HTTP 对齐，包括 token 预算、去重轮次、排除 URI 数量和重写条数。
• 源码构建新增 OV_SKIP_CPP_BUILD=1；OV_SKIP_OV_BUILD=1 可跳过可选 CLI 构建，即使本地没有预构建 CLI。ragfs-python 仍是必需的 native 产物，wheel 仍按平台打包。
• CI 补齐 crates/ 变更对 Rust 构建／检查的触发，OpenCode npm 发布改为自动计算版本；仓库补充了任务事件、会话重置、插件恢复及解析桥接等回归覆盖。

贡献者致谢

感谢每一位推动 OpenViking 前进的贡献者！从 v0.4.18 升级到 v0.4.20 的范围包含 95 个 PR、34 个 PR 作者账号，下面按 GitHub 账号排序列出作者及代表性贡献。功能开发、问题修复、文档和测试的改进，都值得被看见。

也感谢共同作者 @starslittle（#4972）、@hotplex-ai（#4847），以及提交记录中的 chenpengfei、chenxiaobin.monkey、linweiye、mac 和 pc.yu。

欢迎首次贡献者

特别欢迎以下 7 位在本次升级范围内完成首次贡献的社区成员，名单依据 v0.4.19 发布记录与 v0.4.20 发布记录：

• @alanhuangyoo — #4892
• @feel-think — #4724
• @GoneWithTheFlow — #4791
• @hrygo — #4847
• @lucndm — #4827
• @nanhanq1 — #4940
• @ralf003 — #4720

也感谢提交 Issue、提供复现步骤、参与评审和验证升级的社区成员。你们提供的反馈帮助我们发现问题、确认修复，并让 OpenViking 更贴近实际使用。

English

Overview

These notes use v0.4.18 as the baseline and cover the full upgrade to v0.4.20, including changes first shipped in v0.4.19: 95 commits in total.

OpenViking now owns Compile task persistence, scheduling, status, and cancellation, while the Runtime executes the work and writes its artifacts. Git skills gain server-side import and update support. Studio adds user memory policies, Agent experience views, and task events. Memory extraction defaults to a restricted Python DSL, and long sessions are processed in policy-sized batches. Feishu directory imports and resource ACL inheritance are also expanded.

Before upgrading, check the retired Compile endpoints, removed CLI wait/timeout options, and changed memory extraction default in the migration table below.

Thank you to everyone who contributed across this upgrade range, and welcome to seven first-time contributors. See Contributors for the people behind these changes.

Highlights

1. OpenViking takes ownership of Compile tasks

In v0.4.18, OpenViking forwarded Compile requests to VikingBot, which created and managed the tasks. v0.4.19 moved task lifecycle ownership into OpenViking. v0.4.20 adds destination scheduling, persisted events, and credential isolation to that flow. Applications can now inspect and cancel Compile through the same task API as other background work.

v0.4.18
Application / CLI → OpenViking /bot/v1/compile proxy
                  → VikingBot creates task → executes Skill → writes to OpenViking
Status / cancel   → OpenViking Bot proxy → VikingBot task records

v0.4.20
Application / CLI / SDK → OpenViking /api/v1/compile
                        → validate sources, Skill, and destination access
                        → persist task + enqueue → return OpenViking task_id
                        → schedule by destination → Runtime executes and writes artifacts
OpenViking              → poll Runtime → persist status, result, and events
Application             → /api/v1/tasks/{task_id} for status / cancellation

Compile tasks in the same account with exactly the same normalized to rotate through the queue. Two submissions to viking://resources/team-wiki execute sequentially, while a different destination can proceed concurrently. Tasks are not merged. Recovery reserves destinations for submitted work that has not finished. Scheduling is maintained by one server instance and matches exact URIs; it does not provide cross-instance or ancestor/descendant directory locking.

Studio task details expose persisted events for creation, status/stage changes, errors, and waiting for descendant work. HTTP callers request them with include_events=true. Both task lists and details follow server status.

For independent Runtime integrations, OpenViking calls POST /runtime/v1/tasks with {task_type: "compile", payload: {...}} and its own task_id as Idempotency-Key. For the same user and key, the Runtime must return the same session_id. OpenViking then calls /runtime/v1/tasks/status and /runtime/v1/tasks/cancel, both with {"session_id":"..."}. It forwards the current user's API key and, when configured, X-Gateway-Token. Built-in VikingBot implements the same protocol.

See #4436 for lifecycle ownership, #4863 for scheduling, and the Agent Runtime API for the full protocol.

2. Server-side Git skill imports and updates

ov add-skill and ov skills add now share their arguments and import flow. They accept Git repositories, GitHub branch/subdirectory links, and local skill directories. Use --list to inspect a collection and --skill to select entries.

HTTP POST /api/v1/skills adds Git URL input, a skills selection list, and list_only preview. The server records the repository, ref, and subdirectory so ov skills update can refresh a recorded Git source. Each skill in a bulk import retains its own background task ID. The server accesses remote repositories; local files still use the upload endpoint.

3. User memory policies and Agent experience in Studio

Choose a policy when creating a user, or edit an existing user's policy from user management:

Changes take effect after saving and retain existing memories. Session-level overrides still follow the existing precedence rules. Custom types must already be registered on the server. Peer memory requires the application to supply peer_id and does not extract cases.

Studio also adds an Agent Experience module for browsing experience assets, related trajectories, outcome distributions, and source links. Together with the account-level Agent Evolution switch, it helps maintainers inspect generated experience, its source sessions, and recorded usage. These views show recorded evidence; they do not establish an improvement in outcomes.

4. Restricted Python DSL extraction and session batching

Memory extraction now defaults to a restricted Python DSL instead of JSON. Model output can express creation, field edits, deletion, and links. A restricted parser converts it into the existing memory operation model, which uses the shared write path. This is not arbitrary Python execution: module imports, filesystem access, and networking are unavailable, and applications do not execute generated scripts. Stored memory formats are unchanged, and JSON remains selectable.

When reading a large memory, the extractor receives a notice to consider reorganizing, splitting, or compacting it. memory.maintenance_review_tokens defaults to 1,000; this is a review threshold, not automatic truncation or deletion.

Session commit Phase 2 uses the auto_commit_policy saved at submission to batch long-term extraction by pending_token_threshold and message_count_threshold. Working Memory summaries also support batch progression. The planner preserves complete user turns where possible, then splits oversized turns by step/message; a single oversized message is processed on its own. One commit retains one archive and task, with long-term memory changes merged into that archive's memory_diff.json. Without positive thresholds, these batch limits are disabled.

See extraction protocol #4581 and batch extraction #4644.

5. Restricted inheritance for shared resources

Resource directories add acl_mode: "restricted". The node uses direct grants for effective access, blocking parent grants from taking effect; descendants inherit those restricted effective permissions. A project directory under a team share can therefore grant access only to selected members.

Parent grants remain recorded and updated. Switching back to inherit restores the latest inherited grants. Account administrators retain implicit management access. This mode applies to shared viking://resources paths. See the ACL API.

6. Session resets and more reliable plugin memory flows

• The new session commit option reset_context clears session context for subsequent injection while retaining the Session ID, original history, and long-term memory. Later summaries stop inheriting pre-reset overviews. The OpenClaw reset hook uses this option.
• OpenClaw selects afterTurn or commitTurn capture based on the host version. Durable delivery reports write failures to the host for retry. Recall uses the incoming prompt instead of a historical message.
• OpenClaw can opt into commitRetentionMode: "turn_budget" to retain recent context by user turn and token budget. Related pending_tokens accounting is corrected.
• Claude Code and Codex plugins add ordered regex filters for recall queries and captured content.
• The dsh plugin retries pending writes within the running process after transient failures. The pi plugin preserves camelCase toolResult messages.

7. Feishu imports, parser bridge, and experimental context management

Feishu imports support Drive files/folders and recursive Wiki subtrees through args.feishu_recursive: true. Wiki imports still include only the selected node by default. Directory preparation expands the source before routing content to internal parsing or Understanding, allowing documents and files in folders to use the configured parsing flow. Preparation uses Feishu application credentials or args.feishu_access_token; args.lark_file is limited to direct single-document Understanding submissions.

The LlamaParse v2 bridge connects a hosted parser through the existing Understanding API and returns Markdown plus images. It is a separately deployed example service requiring a LlamaCloud API key. Video, credential-gated document URLs, and lark_file inputs are unsupported.

The new pi context-management experiment lets an Agent call new_context to archive a window, open another with handoff notes and Working Memory, and revisit previous windows through history. It remains an experimental example. Do not load it alongside the original openviking extension; its tests are not yet part of regular repository CI.

New Feature Usage

These CLI examples assume a configured OpenViking connection and permission to access the relevant directories. Replace your-key, TASK_ID, and SESSION_ID in HTTP examples with actual values.

Import a skill and run Compile

Import this release's LLM Wiki skill into the shared namespace:

ov add-skill https://github.com/volcengine/OpenViking/tree/v0.4.20/examples/compile/ov-compile-skills/llm-wiki \
  -p viking://agent/skills

ov task status TASK_ID

To inspect and select from a local collection, run from the repository root:

ov skills add ./examples/compile/ov-compile-skills --list
ov skills add ./examples/compile/ov-compile-skills \
  --skill llm-wiki daily-report

Once the shared skill's import task is completed and viking://resources/research is ready:

ov compile \
  --from viking://resources/research \
  --to viking://resources/research-wiki \
  --skill viking://agent/skills/llm-wiki \
  --instruction "Organize a searchable team knowledge base and preserve sources for every claim"

Compile requires a configured runtime and returns a task_id immediately. Inspect it afterward:

ov task status TASK_ID

To stop it, run ov task cancel TASK_ID. Continue polling while its status is cancelling.

Configure the Compile runtime

For built-in VikingBot, start with openviking-server --with-bot and configure its model. For an independent Runtime, merge the following into the server's ov.conf, replace the address with the actual service, and restart:

{
  "compile_api": {
    "base_url": "http://runtime.example:8080",
    "http_timeout_seconds": 10,
    "poll_interval_ms": 30000
  },
  "queue_workers": {
    "external_task": {"max_concurrent": 10}
  }
}

A nonempty compile_api.base_url takes precedence over the local Runtime. Compile is unavailable if neither is configured. External execution requires a forwardable OpenViking user API key; set compile_api.gateway_token if required by the service. http_timeout_seconds limits an individual HTTP request, and poll_interval_ms controls polling; neither is the overall Compile deadline. Built-in VikingBot rejects nonempty args; external Runtimes can define their own extensions.

Restrict inherited access to a subdirectory

With management access to a shared resource subdirectory, set direct grants and restrict inheritance:

ov acl set viking://resources/team/project-a \
  --acl-mode restricted --entry user:bob=read

Use --acl-mode inherit to restore parent grant inheritance.

Inspect task execution events

curl -sS 'http://localhost:1933/api/v1/tasks/TASK_ID?include_events=true' \
  -H 'X-API-Key: your-key'

History appears in the HTTP response's result.execution_events. A task_id confirms submission; completed means success. failed and cancelled are other terminal states; continue polling while cancelling. Stopping polling or reaching a wait timeout does not cancel background work.

Filter recall queries and captured content

Merge the relevant settings into the plugin section of ~/.openviking/ovcli.conf. This Claude Code example strips an ultrathink prefix, skips recall for slash/shell commands, and replaces matching tokens before capture:

{
  "plugin": {
    "claude_code": {
      "recallQueryFilters": ["s/^\\s*ultrathink\\s+//i", "d|^\\s*[/!]|"],
      "captureFilters": ["s/\\b(sk|ghp)_[A-Za-z0-9_-]{10,}/[redacted]/g"]
    }
  }
}

Codex uses the same keys under plugin.codex. Rules support substitution, drop-on-match, keep-on-match, and user:/assistant: role prefixes. Filters affect newly sent content, not existing memories; the sample regex is not a general secret detector. Invalid rules are skipped and reported by ov-memory-doctor. Rules containing commas must use JSON arrays rather than comma-separated environment variables.

Reset session context or retain recent turns

Reset a session's context:

curl -sS -X POST 'http://localhost:1933/api/v1/sessions/SESSION_ID/commit' \
  -H 'X-API-Key: your-key' \
  -H 'Content-Type: application/json' \
  -d '{"reset_context":true,"keep_recent_count":0}'

reset_context cannot be combined with a nonzero keep_recent_count or a retention_mode. It creates a reset boundary even when no live messages remain; extraction from older archives can continue. This release does not add dedicated SDK or CLI reset arguments.

To retain recent turns during OpenClaw auto-commit, add this to the existing OpenClaw plugin configuration:

{
  "commitRetentionMode": "turn_budget"
}

This uses server defaults: up to 3 recent user turns, a 12,000-token retention budget, and at least the final assistant/tool step. An oversized newest turn retains its user question and recent steps while archiving the prefix. The mandatory tail can exceed the budget. commitKeepRecentCount is ignored in this mode. Leaving the option unset retains the existing message-count behavior; manual commit and /compact still archive all messages.

Connect the LlamaParse bridge

Following the bridge README, configure .env with LLAMA_CLOUD_API_KEY and a PARSER_BRIDGE_API_KEY of at least 32 characters, then start it from the repository root:

uv run --env-file examples/llamaparse-understanding-bridge/.env \
  --project examples/llamaparse-understanding-bridge \
  openviking-llamaparse-bridge

Merge this section into OpenViking's ov.conf, set the same PARSER_BRIDGE_API_KEY in the server's environment, and restart OpenViking:

{
  "parser_api": {
    "enable": true,
    "host": "http://127.0.0.1:8080",
    "api_key": "${PARSER_BRIDGE_API_KEY}",
    "extensions": ["pdf", "docx", "pptx", "xlsx"],
    "http_timeout_seconds": 130
  }
}

host must be reachable from OpenViking. For separate containers, also configure the bridge's BRIDGE_PUBLIC_URL. Keep parser_api.enable_resumable_upload disabled. Only the selected extensions use the bridge. Partial page failures preserve usable Markdown and add a failed-page note.

Read text by line through MCP

MCP read now accepts offset and limit. For example, read 40 lines starting at line 101:

{"uris":"viking://resources/research/notes.md","offset":100,"limit":40}

offset is zero-based; limit: -1 removes the line limit. Images and audio keep their existing media response behavior.

Improvements

• Retrieval and storage performance: VikingDB/Volcengine clients reuse pooled HTTP connections. Context assembly and private/shared skill search share query embeddings within a request, while isolating cancellation of an individual waiter. Internal metadata checks avoid default path-lock lookups; public HTTP stat still returns lock status.
• Multi-user administration: Trusted mode batches account/user registration from data-plane requests, flushing every 300 seconds by default. It creates no user API keys and changes no existing roles or groups. Registered identities become visible through existing management APIs. Account/user listings load the relevant registries instead of unrelated full state.
• Executor configuration: server.executor_threads controls the default asyncio executor in each server process. 0 keeps Python's default sizing; it is separate from the process count in workers. Relevant configuration fields are shown below:

{
  "server": {
    "executor_threads": 32,
    "trusted_identity_flush_interval_seconds": 300
  }
}

Set trusted_identity_flush_interval_seconds to 0 to disable that identity registration.

• Feishu and Lark: The Feishu channel accepts a configurable domain for both HTTP and WebSocket connections. For Lark, add this field to an existing type: "feishu" channel configuration:

{"domain":"https://open.larksuite.com"}

The default remains the Feishu domain. Feishu cards can deliver explicit Markdown viking:// images using the original sender's identity; ordinary URI citations and code examples do not trigger image delivery.

Upgrade and rollback notes

Fixes

• Local vector schema upgrades use bounded batches to reduce memory use on large datasets. cp/mv vector path queries use consistent operators to resolve backend incompatibilities.
• Local file/directory scans preserve error categories. Queue messages receive per-instance creation timestamps instead of a timestamp fixed at module load.
• Plugins recognize camelCase isError as tool failure. Local MCP proxy timeouts return -32004, distinct from service unreachability. Codex reuses the shared recall compressor.
• Understanding uploads preserve source filenames and resolved extensions, avoiding parser misclassification caused by temporary names or extensionless titles.
• File paths support #; Markdown references are encoded and resolved correctly. Orphan-vector cleanup preserves records for real files whose names resemble virtual chunk URIs.
• Startup/account initialization fills in viking://agent, its skills, endpoints, tools, and payments directories, and missing L0/L1 metadata while preserving existing content. Malformed preset abstracts no longer block startup.
• Path-lock reads retry a transient partial token caused by concurrent writes. Abstract generation preserves lock-acquisition errors so existing retry logic can recognize them.
• S3/TOS virtual directories remain listable without modification times. WebDAV GET Content-Length matches the actual response bytes.
• Windows PID checks use process handles instead of signaling the target process.
• Skill policy updates preserve extracted descriptions, allowed tools, and tags. Deleting an already missing task record succeeds.
• Studio's Agent Evolution settings follow the selected account. Session views group Agent messages and improve readability of chat and tool output.
• Bot retains configured OpenViking credentials with --with-bot, forwards actor_peer_id, and atomically replaces cron files to reduce interrupted-write corruption.
• X-Request-ID accepts slashes; invalid values are replaced instead of causing a 400 solely because of the trace identifier.
• The OpenAI-compatible VLM backend separates explicit reasoning_effort from model defaults, avoiding inappropriate token/temperature parameters for third-party compatible models.

Docs, Tests, and Security

• Resource import and related examples use submission, task-ID retention, and terminal-state polling. A wait timeout stops waiting without marking background work failed or cancelled.
• Agent Plugins adds ov-memory-troubleshoot for read-only investigation from memory files through archive memory_diff.json to source messages.
• Compile keeps api_key/user_key separate from public task data while forwarding runtime arguments; task results also remove those fields. The Bot proxy strips client-supplied openviking_connection before attaching authenticated identity.
• Bot send:// accepts only a bare filename, rejecting path input. Git skill imports validate remote targets, subdirectories, and symlink boundaries.
• MCP search aligns context-argument validation with HTTP, including token budget, dedup turns, excluded URI count, and rewrite bullet count.
• Source builds add OV_SKIP_CPP_BUILD=1. OV_SKIP_OV_BUILD=1 skips the optional CLI build even without a prebuilt CLI. ragfs-python remains a required native artifact, and wheels remain platform-specific.
• CI now triggers Rust builds/checks for crates/ changes, and OpenCode npm releases calculate versions automatically. The repository adds regression coverage for task events, context resets, plugin recovery, and the parser bridge.

Contributors

Thank you to everyone who moved OpenViking forward! The upgrade from v0.4.18 to v0.4.20 includes 95 PRs from 34 PR-author accounts. The table lists authors alphabetically by GitHub account and highlights representative contributions. Features, fixes, documentation, and tests all deserve recognition.

Thanks also to co-authors @starslittle (#4972), @hotplex-ai (#4847), and chenpengfei, chenxiaobin.monkey, linweiye, mac, and pc.yu as credited in the commit records.

Welcome to first-time contributors

A special welcome to these seven community members whose first contributions shipped within this upgrade range, according to the v0.4.19 release and v0.4.20 release:

• @alanhuangyoo — #4892
• @feel-think — #4724
• @GoneWithTheFlow — #4791
• @hrygo — #4847
• @lucndm — #4827
• @nanhanq1 — #4940
• @ralf003 — #4720

Thank you as well to everyone who reported issues, supplied reproductions, reviewed changes, and validated upgrades. Your feedback helps us find problems, verify fixes, and improve OpenViking for real use.