github volcengine/OpenViking v0.4.18
on GitHub

latest releases: cli@0.4.18, python-sdk@0.1.10
5 hours ago

中文

版本概览

OpenViking v0.4.18 包含 106 个 commit，核心是为共享资源引入资源级 ACL 与用户组授权，并围绕它补齐向量权限过滤、账号级开关和安全的本地 schema 更新；同时恢复并稳定了 cp/mv 的事务化转移语义，修复 Watch 的首次导入与目标占用问题，为 ls/tree 增加分页与排序，并改进各 Agent 插件的记忆归属与可靠性。同时欢迎以下 15 位首次贡献者，感谢他们为本次版本带来的改进。

升级前请阅读文末的「兼容性与升级说明」：本版本包含一项 ACL 字段的破坏性变更、一项 CLI 参数的破坏性变更，以及若干需要留意的行为变化。资源 ACL 默认关闭，关闭状态下共享区完全沿用原有 namespace 规则，因此升级后默认行为不变。

主要更新

  • 资源级 ACL 与用户组授权：viking://resources/... 共享区新增资源级 ACL，把身份角色、资源授权、文件操作、检索过滤和后台维护收敛到同一套权限模型。授权对象支持 user:{user_id}、group:{group_id} 和 user:*，等级分为 read/write/manage；子节点只能在祖先授权基础上增加，不能收窄。向量检索会按有效权限过滤命中结果。
  • 账号级 ACL 开关：账号配置统一为 {"acl":{"enabled":true|false}}，CLI 对应 --acl-enabled true|false。关闭时不解析 ACL、不执行 ACL 鉴权、也不追加 ACL 检索过滤，完全恢复 ACL 引入前的共享行为；开启后新建共享资源会写入创建者 manage。开关在服务启动时载入内存，PATCH 设置成功后同步更新当前进程状态。
  • cp / mv 事务化转移与覆盖合并：新增 POST /api/v1/fs/cp 与 ov cp（-r 递归），复制时同步迁移已有向量记录，避免重复解析、文件级 VLM 和 embedding。mv 恢复文件覆盖与目录合并，cp 采用相同规则：源目录的 a.md 覆盖目标同名文件，目标独有的 only.md 保留。路径锁缩小到源和目标本身（文件用两个 Exact 锁、目录用两个 Tree 锁），不再锁住父目录整棵树，避免无关同级 add_resource 与目录移动互相冲突。
  • ls / tree 分页与排序：ls 和 tree 新增 offset、limit 分页，覆盖 HTTP API、CLI、Python/Go/TypeScript SDK 和 MCP；CLI 与 MCP 的 ls 另外支持排序。不传新参数时行为不变。
  • tags 写入与文件系统过滤：write 可在首次写入时设置 tags；ls、tree、grep、glob 支持按 tags 做 AND 过滤并按需返回 tags；CLI 统一为 --tags team=search,env=prod；HTTP API 与三个 SDK 保持一致。未请求 tags 也未按 tags 过滤时，不会新增 VectorDB 查询。
  • VectorDB 本地 schema 安全更新：local/cuVS backend 在启动时比较目标 schema 与本地实际 collection/index，仅追加缺失字段和 scalar index。新 scalar bitmap 从 Store 快照完整构建、Native 层成功后原子替换，不重建 vector index、不调用 drop_index()，持久化成功后才更新 index metadata，旧索引在新版本写完前始终可恢复。远端 VectorDB 启动行为不变。
  • Watch 修复：完善首次导入、定时刷新与状态查询链路，支持暂停创建（is_active=false 时仍执行一次首轮导入，后续周期调度保持暂停）、最近执行结果查询、Connector 增量刷新，以及飞书不同 Refresh Token 格式；区分原生与 Connector Watch 的目标占用规则，允许多个 Connector Watch 共用目录，避免导入操作覆盖或暂停已有任务。
  • 检索：filter 可独立于 query：find() 在带 filter 时接受空 query，结果完全由 filter 决定，直接从元数据存储解析，score 保持 0 而不是编造一个相似度值。search() 保持不变，因为它依赖 session 上下文扩展意图。
  • 文件系统支持向量记录 ID：集中化确定性向量记录 ID 生成，stat/read 可按 ID 解析文件并给出可行动的缺索引诊断；ls、tree、glob 支持可选字段和脚本友好输出。基于 URI 的行为保持不变。
  • 临时上传按小时分桶：shared TempUpload 改为按 UTC 小时分桶存储，把清理和本地磁盘 IO 移出请求路径，并把清理重写为有界的 best-effort 方式，解决单层目录膨胀到数十万条、单轮清理耗时数分钟的问题。
  • AnyDoc 0.2 适配：适配 firecrawl-anydoc 0.2.4 文档模型，修复含列表的 Office 文档解析抛 AttributeError: 'anydoc.ListItem' object has no attribute 'checked' 并以 SERVER_TASK_FAILED 结束的问题，同时承接新增的 checkbox 与 math 模型；依赖范围收敛为 >=0.2.4,<0.3。
  • 插件记忆归属改为按仓库：peer.source 默认改为 git，用归一化的 origin URL（回退到仓库根）作为 workspace peer，同一个仓库在任意 clone、worktree、机器或子目录下都是同一个 peer；不在仓库内则不发送 peer，记忆落到用户级空间。claude-code 与 codex 还可读取仓库自带的 <root>/.openviking/config.json、config.local.json 和每机注册表，仅投影白名单键，连接与凭据类键会被剥离并告警。
  • 插件收敛回共享库：四个 harness 插件此前各自偏离 examples/memory-plugin-shared/lib/，本次收敛回共享实现并让相关检查真正生效；同时修复只生效一半的 dsh 开关、误判 git worktree 的安装器和漏掉三个文件的测试矩阵。
  • OpenClaw 服务端装配 auto-recall：把 OpenClaw auto-recall 的客户端 find/rerank/read 链路替换为一次 session-aware 的服务端 context search，保留目标选择、actor/tenant 路由、注入标记、超时控制和 recall trace，同时启用 query 扩展与五轮去重。
  • Agent 插件修复：Codex 在 SessionEnd hook 提交并保留 SessionStart sweep 兜底、修复过期 takeover 把锁交给两个持有者、修复 hook 脚本路径未加引号、codex-doctor 接受 [features] hooks = true；OpenCode 修复 prependSyntheticRecallPart 的 messageID 必填、隔离 flushAll 的单 session 失败、共享凭据未定义时回退到 config peerId；DSH 在 pre-step 并行执行 profile 与 recall；pi extension 不再让 session_start 阻塞在 OV 服务链路上、离线积压改走批量端点、容忍缺少 buildContextEntries 的宿主；安装器不再在凭据向导中中止。
  • VikingBot：openviking_multi_read 可按 OpenViking 资源类型返回适合模型使用的多模态内容（不新增 SDK/API，也不通过 user message 注入媒体）；修复 SDK、exec 与 cron 选项未生效；限制并发 subagent 数量。
  • Web Studio：搜索面板扩展为 files/find/search/grep/glob 五种模式并支持 Tab 循环切换，结果中的目录可预览 L0/L1，右侧交互面板可折叠且状态持久化，新增结构化 JSONL 渲染；支持受信用户切换；修复 L0/L1 sidecar 元数据渲染、外部删除后 context 树未刷新，以及鉴权模式解析完成前的路由问题。
  • 记忆与检索可靠性：修复 Experience 更新租约未包含 trajectory 反向链接、Event 记忆写入复用已有 page ID、生成的 URI 在 Windows 上非法、抽取时未脱敏行内图片字节、动态 URI 值跨越多个路径段、批量写入丢失记忆元数据、记忆遥测占位 URI 处理；语义侧不再实体化缺失的 DAG 根、VikingFS.find 保持 quick 模式、跳过竞争中的父目录新鲜度更新、限制 OpenAI embedder 的 HTTP 连接池上限，并支持显式启用 OpenAI-compatible 多模态 embedding。
  • Session：在每个 create_session 调用点透传 CreateSessionOptions 中的 memory_policy，patch 合并使用 session skill schema，工作记忆遵循输出语言设置，token 重建移出事件循环，commit phase1 延迟下降。
  • SDK、CLI 与服务端：SDK 保留 unavailable 错误详情；CLI 在改写配置时保留 ovcli.conf 中未建模的键、资源 URI 分段与记忆 URI 一样做 Windows 安全化；list_accounts/list_users 排序改为可选；rerank 对显式配置的 provider 校验凭据；VLM 拒绝不支持的 stream 配置；新增 pathlock 过期空锁令牌恢复与 remove_token 的 force 参数，支持关闭鉴权锁；改进无效配置的诊断信息；privacy 配置变更在 pathlock 下串行化并向上传递存储错误。
  • RAGFS 与缓存：统一 CacheRuntime 与 Redis 支持的 CacheFS/QueueFS；通过版本化 C ABI 重构支持 DynamicProvider；无 redirects 时跳过 redirect 元数据读取；账号目录初始化改为批量。
  • 其他：支持本地文件进入 external-queue；新增目录理解能力；修复 Markdown 中尖括号包裹的图片路径；新增 sessions compile skill 与 agent logo 本地化。

兼容性与升级说明

  • Breaking change（ACL 字段）：资源 ACL 的派生状态由布尔 acl_enabled 改为字符串 acl_mode（#4768）。ACL report 和 context 记录中 {"acl_enabled": false} / {"acl_enabled": true} 变为 {"acl_mode": "none"} / {"acl_mode": "inherit"}；判断是否进入 ACL 控制域请统一改为检查 acl_mode != "none"。本次只改状态表示，实际权限计算不变；账号级 acl.enabled 仍是布尔值。
  • Breaking change（CLI 参数）：ov add-resource 与 ov reindex 的标签参数由可重复的 --tag k=v 改为逗号分隔的 --tags k=v,k2=v2（#4599），与 write/ls/tree/grep/glob 保持一致。请更新调用这两个命令的脚本。
  • 行为变更（cp/mv 覆盖）：转移操作现在允许覆盖已有目标并合并目录（#4718）。沿用弱回滚原则：不备份被覆盖的旧目标，也不承诺文件系统与向量库的跨库事务——文件复制失败可能留下部分目标内容，向量阶段失败清理目标时可能连同原目标已有内容一起删除，被覆盖的数据无法恢复。请勿依赖「目标已存在则失败」作为保护手段。
  • 行为变更（空内容资源）：add_resource 现在在摄入阶段拒绝没有内容的源（#4571），此前会被接受。依赖旧行为的调用方和测试需要相应更新。
  • 行为变更（插件 peer）：workspace peer 由 cwd 派生改为从 git 派生（#4595）。无需手工迁移：旧 id 是 cwd 的纯函数，客户端会重算并仍能读到写在旧 id 下的内容；默认 peer_scope: "all" 时服务端跨 peer 扫描已覆盖，actor 时插件会单独询问该 peer。不在 git 仓库内时不再发送 peer，记忆改落到用户级空间。
  • 部署注意（ACL 存量 collection）：启动时的 ACL 破坏性 schema 自动迁移已被移除（#4522），服务不再在启动时覆盖 collection schema 或 drop_index/create_index 重建已有索引。已有远端 VikingDB collection 需要部署方在控制台预先配置 ACL 字段及对应标量索引；local/cuVS 的存量 collection 由 #4700 在启动时安全地追加补齐。新建 collection 不受影响。
  • 默认行为不变：资源 ACL 由账号级 acl.enabled 控制且默认关闭，关闭时共享区完全沿用升级前的 namespace 规则。当前 account 的 ADMIN 对 viking://resources/... 隐式拥有 manage，不写入 ACL 也不能被 ACL 删除。
  • 未变更：检索标签的字符集与长度限制在本区间内先引入（#4599）后移除（#4761），相对 v0.4.17.1 净效果为零——tags 仍只要求「恰好一个 = 且两侧非空」，特殊字符和长 key/value 继续被接受。阿里云 OSS vendor 支持同样先合入（#4564）后回滚（#4603），本版本不包含该能力。

使用示例

# ls / tree 分页与排序
ov ls viking://resources/docs --offset 100 --limit 50
ov tree viking://resources/docs --limit 200

# tags 写入与过滤（注意：add-resource / reindex 现在用 --tags）
ov add-resource ./report.pdf --to viking://resources/docs/report.pdf --tags team=search,env=prod
ov ls viking://resources/docs --tags team=search,env=prod --fields tags
ov grep "TODO" --uri viking://resources/docs --tags team=search,env=prod

# 复制与移动：目标已存在时覆盖文件、合并目录
ov cp viking://resources/a/report.md viking://resources/b/report.md
ov cp -r viking://resources/a viking://resources/b

# 账号级 ACL 开关
ov admin set-account-settings acme --acl-enabled true
PATCH /api/v1/admin/accounts/acme/settings
{"acl": {"enabled": true}}
# find 在带 filter 时可以不传 query，score 恒为 0
results = client.find(
    query="",
    target_uri="viking://resources",
    options={"tags": ["external_id=order-42"]},
    limit=10,
)

首次贡献者

感谢以下 15 位首次参与 OpenViking 的贡献者：

完整变更记录：v0.4.17.1...49afccd

English

Overview

OpenViking v0.4.18 contains 106 commits. Its centerpiece is resource-level ACL with user-group authorization for the shared space, together with vector permission filtering, an account-level switch, and safe local schema updates to support it. The release also restores and stabilizes transactional cp/mv semantics, fixes Watch first-import and target-occupancy handling, adds pagination and sorting to ls/tree, and improves memory attribution and reliability across the Agent plugins. We also welcome 15 first-time contributors and thank them for their improvements in this release.

Read the compatibility notes at the end before upgrading: this release contains one breaking ACL field change, one breaking CLI flag change, and several behavior changes worth checking. Resource ACL is off by default, and with it off the shared space follows exactly the previous namespace rules, so default behavior is unchanged after upgrading.

Highlights

  • Added resource-level ACL for viking://resources/..., unifying identity roles, resource grants, file operations, retrieval filtering, and background maintenance under one permission model. Principals are user:{user_id}, group:{group_id}, and user:*; levels are read/write/manage. Child nodes can only add to ancestor grants, never narrow them, and vector retrieval filters hits by effective permission.
  • Added an account-level ACL switch as {"acl":{"enabled":true|false}} (CLI --acl-enabled). When disabled, ACLs are not parsed, enforced, or added as retrieval filters, fully restoring pre-ACL sharing behavior; when enabled, new shared resources record manage for their creator.
  • Added transactional POST /api/v1/fs/cp and ov cp (-r for recursion) that migrate existing vector records instead of re-parsing, and restored overwrite-and-merge semantics for mv and cp: same-named targets are overwritten while target-only entries are kept. Path locks now cover only the source and destination rather than the whole parent tree, so unrelated sibling add_resource calls no longer conflict with directory moves.
  • Added offset/limit pagination for ls and tree across the HTTP API, CLI, Python/Go/TypeScript SDKs, and MCP, plus ls sorting in the CLI and MCP. Behavior is unchanged when the new parameters are omitted.
  • Added tags on first write, AND-filtering and optional tag return for ls, tree, grep, and glob, and unified the CLI on --tags team=search,env=prod. Requests that neither ask for nor filter by tags issue no additional VectorDB query.
  • Added safe startup schema updates for the local/cuVS VectorDB: missing fields and scalar indexes are appended only, new scalar bitmaps are built from a Store snapshot and swapped atomically, drop_index() is never called, and index metadata is updated only after a successful persist, so the previous complete index stays recoverable. Remote VectorDB startup behavior is unchanged.
  • Fixed Watch first-import, scheduled refresh, and status queries, including paused creation (is_active=false still runs the first import, then stays paused), latest-run results, Connector incremental refresh, and additional Lark refresh-token formats. Native and Connector Watches now have distinct target-occupancy rules so multiple Connector Watches can share a directory without overwriting or pausing existing tasks.
  • Allowed find() to run without a query when a filter is given; the result is fully determined by the filter, resolved from the metadata store, with score left at 0 instead of a fabricated value. search() is deliberately unchanged because it expands intent from session context.
  • Added deterministic vector record IDs across the filesystem APIs, ID-based stat/read with actionable missing-index diagnostics, and selectable fields with script-friendly ls, tree, and glob output. URI-based behavior is unchanged.
  • Reworked shared temp uploads into UTC hour buckets, moved cleanup and local disk IO off the request path, and rewrote cleanup as a bounded best-effort pass, fixing single-directory growth into the hundreds of thousands and multi-minute cleanup rounds.
  • Adapted the parser to the firecrawl-anydoc 0.2.4 document model, fixing Office documents with lists failing as SERVER_TASK_FAILED via AttributeError: 'anydoc.ListItem' object has no attribute 'checked', and picking up the new checkbox and math models. The dependency range is now >=0.2.4,<0.3.
  • Changed the plugin workspace peer to derive from git — the normalized origin URL, falling back to the repository root — so one repository is one peer across clones, worktrees, machines, and subdirectories; outside a repository no peer is sent and memories go to the user-level space. claude-code and codex additionally read repository-carried <root>/.openviking/config.json, config.local.json, and a per-machine registry, projecting allowlisted keys only and stripping connection and credential keys with a warning.
  • Converged four harness plugin forks back onto examples/memory-plugin-shared/lib/ and made the drift checks real, along with a half-working dsh toggle, an installer that misread git worktrees, and a test matrix that skipped three files.
  • Replaced OpenClaw auto-recall's client-side find/rerank/read path with a single session-aware server-side context search, preserving target selection, actor/tenant routing, injection markers, timeout controls, and recall traces while enabling query expansion and five-turn deduplication.
  • Fixed Agent plugins across harnesses: Codex commit on SessionEnd with a SessionStart sweep fallback, stale-takeover double lock handover, unquoted hook script paths, and [features] hooks = true in codex-doctor; OpenCode optional messageID, isolated flushAll session failures, and config peerId fallback; DSH parallel profile and recall on pre-step; pi extension non-blocking session_start, batched offline backlog replay, and tolerance for hosts without buildContextEntries; and an installer that no longer aborts inside the credentials wizard.
  • Added multimodal OpenViking resource reads to VikingBot's openviking_multi_read, fixed SDK, exec, and cron options, and bounded concurrent subagents.
  • Expanded Web Studio with five search modes (files/find/search/grep/glob) cycled by Tab, L0/L1 previews for directories in results, a collapsible and persistent right-hand panel, structured JSONL rendering, and trusted user switching; fixed L0/L1 sidecar metadata rendering, context-tree refresh after external deletion, and routing before the auth mode resolves.
  • Fixed memory and retrieval reliability: trajectory backlinks in the experience update lease, Event memory writes reusing page IDs, Windows-unsafe generated URIs, inline image bytes leaking into extraction, dynamic URI values spanning path segments, metadata loss in batch writes, and telemetry placeholder URIs; plus missing DAG root materialization, VikingFS.find quick mode, contended parent freshness updates, unbounded OpenAI embedder connection pools, and opt-in OpenAI-compatible multimodal embedding.
  • Fixed sessions: memory_policy passed through CreateSessionOptions at every call site, session skill schema for patch merges, output language for working memory, token rebuild moved off the event loop, and lower commit phase-1 latency.
  • Improved SDK, CLI, and server behavior: preserved unavailable error details, unmodeled ovcli.conf keys kept through config rewrites, Windows-safe resource URI segments, opt-in list_accounts/list_users sorting, credential validation for explicitly configured rerank providers, rejection of unsupported VLM stream configuration, expired empty pathlock token recovery, a force parameter on remove_token, an auth-lock disable switch, better invalid-config diagnostics, and privacy config mutations serialized under pathlock with storage errors propagated.
  • Unified CacheRuntime with Redis-backed CacheFS/QueueFS, added DynamicProvider support through a versioned C ABI refactor, skipped redirect metadata reads when there are no redirects, and batched account directory initialization.
  • Added local files to the external queue, directory understanding, angle-bracket image paths in Markdown, a sessions compile skill, and localized agent logos.

Compatibility notes

  • Breaking change (ACL field): the derived resource ACL state moves from the boolean acl_enabled to the string acl_mode (#4768). {"acl_enabled": false} / {"acl_enabled": true} in ACL reports and context records become {"acl_mode": "none"} / {"acl_mode": "inherit"}; check acl_mode != "none" to test whether a node is under ACL control. Only the state representation changes — permission evaluation is unchanged, and the account-level acl.enabled remains a boolean.
  • Breaking change (CLI flag): ov add-resource and ov reindex move from the repeatable --tag k=v to the comma-separated --tags k=v,k2=v2 (#4599), matching write/ls/tree/grep/glob. Update scripts that call either command.
  • Behavior change (cp/mv overwrite): transfers now overwrite existing targets and merge directories (#4718) under a weak-rollback contract: overwritten targets are not backed up, and there is no cross-store transaction between the filesystem and the vector store. A failed copy can leave partial target content, and target cleanup after a vector-stage failure can remove pre-existing target content along with it. Do not rely on "fails if the target exists" as a safety net.
  • Behavior change (empty sources): add_resource now rejects a source with no content at ingestion (#4571); it was previously accepted. Update callers and tests that depend on the old behavior.
  • Behavior change (plugin peer): the workspace peer is derived from git rather than the working directory (#4595). No migration is required: the pre-git id is a pure function of the cwd, so the client recomputes it and still reaches what was written under it — the server's cross-peer sweep covers it under the default peer_scope: "all", and the plugin queries that peer separately under actor. Outside a git repository no peer is sent and memories go to the user-level space.
  • Deployment note (existing ACL collections): the destructive ACL schema auto-migration at startup has been removed (#4522); the service no longer overwrites collection schemas or drops and recreates existing indexes on boot. Existing remote VikingDB collections must have ACL fields and their scalar indexes provisioned by the operator in the console. Existing local/cuVS collections are appended safely at startup by #4700. New collections are unaffected.
  • Defaults unchanged: resource ACL is gated by the account-level acl.enabled and is off by default; with it off the shared space follows the pre-upgrade namespace rules. The current account's ADMIN implicitly holds manage over viking://resources/...; this is not stored in and cannot be removed by an ACL.
  • Not changed: the search-tag character-set and length limits were introduced (#4599) and removed (#4761) within this range, netting to zero against v0.4.17.1 — tags still only require exactly one = with non-empty sides, and special characters and long keys/values remain accepted. Aliyun OSS vendor support was likewise merged (#4564) and reverted (#4603); it is not in this release.

Usage

ov ls viking://resources/docs --offset 100 --limit 50
ov add-resource ./report.pdf --to viking://resources/docs/report.pdf --tags team=search,env=prod
ov ls viking://resources/docs --tags team=search,env=prod --fields tags
ov cp -r viking://resources/a viking://resources/b
ov admin set-account-settings acme --acl-enabled true
results = client.find(
    query="",
    target_uri="viking://resources",
    options={"tags": ["external_id=order-42"]},
    limit=10,
)

New Contributors

Thank you to our 15 first-time contributors: @jamespud, @txfang, @haddadrm, @Terminator666666, @linhongyu510, @jianxunzhang1101, @noxos-os, @SuperMarioYL, @viafcccy, @starslittle, @CryoThrust, @pperezrubio, @jr551, @AirHua-byte, and @abhaymundhara.

Full changelog: v0.4.17.1...49afccd

Check out latest releases or
releases around volcengine/OpenViking v0.4.18

Don't miss a new OpenViking release

NewReleases is sending notifications on new releases.

Get notifications