volcengine/OpenViking v0.5.5

on GitHub

中文

主要更新

• PostgreSQL 部署选项：新增 pgvector 向量后端（storage.vectordb.backend: "pgvector"，支持精确检索和 HNSW 检索，需要安装 openviking[pgvector]）和 PostgreSQL PathLock（storage.agfs.pathlock.provider: "postgres"）。多进程、多主机部署不依赖 Redis，也可以共享向量数据和路径锁租约。#7516、#7481
• 多节点协调：新增 storage.agfs.coordination（memory / sqlite / cache），统一负责 Watch 选主和语义任务版本；只有已持久化的工作才会取代旧任务，按 key 的状态保留一天后过期。#7466
• 快照路径历史索引：snapshot/log?paths=... 改用派生索引查找改动过指定路径的提交，默认为 SQLite，多实例部署可选 MySQL，设为 none 则保持原来的扫描方式。快照提交、文件内容和 API 响应都不变。#7505
• Gateway Context Profile：新增 recall_peer_scope（all / actor），可把召回限制在当前 peer；新增 capture_memory_types，限制 capture 抽取的记忆类型；capture 会话保留用户自己的记忆策略。#7389、#7367、#7429
• 使用次数统计与批量标签：set_tags 的 append 模式支持 k+=number / k-=number（十进制加减，key 不存在时从 0 开始），可用于计数；新增 POST /api/v1/content/batch_set_tags，一次 1–50 个 URI，返回成功项 items 和失败项 failed，部分失败时仍返回 200。CLI（ov attrs batch-set-tags）和 Python、TypeScript、Go SDK 均已提供。#7405
• 静态 soul.md 与预置策略：memories/soul.md 改为可编辑的静态 Agent 指令，VikingBot 每轮优先读取 OpenViking 中的 soul.md；开启 server.user_config_defaults.preset_global_policy 后，初始化用户时会创建内置的 GLOBAL_POLICY.md（默认关闭）。#7328、#7512
• 导入与检索：首次非严格导入允许部分成功（此前任一文件失败即整体失败）；支持 Wiki 托管的飞书文件和原生飞书幻灯片导入；远程 PathGlob 由 storage.vectordb.enable_path_glob 控制，未设置时沿用各适配器的默认值。#7427、#7153、#7461

发布版本

主包 openviking==0.5.5、Python SDK openviking-sdk==0.1.20、独立 CLI 0.5.3。batch_set_tags 和 ov attrs batch-set-tags 需要 0.5.5 服务端。

pip install --upgrade 'openviking==0.5.5' 'openviking-sdk==0.1.20'

升级与迁移

1. Gateway 默认开放全部 OpenViking 工具（含写工具）：Context Profile 的 disabled_tools 默认值改为空，默认开放全部工具，包括 remember、write、edit、add_resource、add_skill、forget、set_acl、cancel_watch 这 8 个会修改数据的工具（之前的版本默认关闭它们）；之后新增的工具也默认开放。已保存的 Profile 和进行中的会话不受影响；没有保存过 default Profile 的账户，以及 gateway 配置里未写 disabled_tools 的 default_profile，现在会得到全部工具。PUT /admin/policies/{id} 是全量替换：请求里省略 disabled_tools 会把已保存 Profile 的写工具全部打开。要保留原来的选择，请在 default_profile.disabled_tools 中显式列出这些工具，并在每次更新 Profile 时提交完整的 disabled_tools。#7436
2. X-OpenViking-Context 只能收窄工具权限：请求头里的 disabled_tools 会追加到 Profile 已排除的工具上，gateway_tools 也不能重新开启 Profile 关闭的工具。原来靠 {"disabled_tools":[]} 或 {"gateway_tools":true} 拿到额外工具的客户端，需要改为修改 Profile。#7446
3. soul / identity 不再自动抽取：这两种记忆类型已经下线，已持久化的策略和部署覆盖里即使写了也会被忽略；账户记忆模板接口只返回 4 个可编辑模板。已有的 soul.md 和 identity.md 保持原样；缺少 soul.md 的用户会在初始化时或下一次 self 记忆提交时，用默认内容创建。自动记忆更新不能修改 soul.md 和 identity.md，包含此类操作的整批更新会被拒绝。#7328
4. Kafka 上报配置迁入 ov.conf（breaking 配置变更）：Nacos 和外部 JSON 的读取已删除。server.observability.reporting 移除了 config_file 和 nacos_* 字段，NACOS_CONFIG_FILE、NACOS_SERVER_ADDR 等环境变量也不再读取；改为读取 reporting.kafka，并需要同时开启 reporting.enabled 和 reporting.telemetry.enabled。旧字段不会让启动失败，但不迁移就不会再上报。原来通过 Nacos 或外部 JSON 配置的部署，需要把 kafka、telemetry 两段迁入 ov.conf 后重启。部署归属可写在 reporting.telemetry.deployment，OV_METRICS_ACCOUNT_ID、OV_RESOURCE_ID、OV_REGION 仍作为回退值。#7491
5. Skill 更新不再备份和回滚：更新时直接替换旧包，失败或取消后文件、索引和隐私配置停在失败时的状态，不会恢复旧版本。SKILL.md 和 .source.json 会保留到被覆盖为止，可以直接重试更新。#7509
6. 首次非严格导入可以部分成功：之前只要有一个文件失败，目录导入就整体失败（不论 strict）。现在 strict=false（默认）时，新目标的首次导入如果有部分读取或解析失败，会提交成功的部分：任务状态为完成，结果为 status="partial"、import_complete=false，失败项列在 failed_files；只检查任务状态的调用方需要同时检查 import_complete。部分导入不会推进源 checkpoint，Watch 本轮记为 partial；源认证失败仍整体失败。strict=true 仍拒绝不完整的提交；更新已有资源时结果不完整会返回 FAILED_PRECONDITION，旧内容保持不变。#7427
7. Git 导入网络检查：Git 预检、clone 和 fetch 不再跟随 HTTP 重定向，请使用最终的仓库地址；GitHub/GitLab ZIP 下载仍跟随重定向，但每个目标地址都会校验。回环、链路本地、未指定、组播、保留地址和已知云元数据地址一律拒绝，代码托管白名单和 allow_private_networks=true 也不能放行。#7441
8. 隐私配置写接口遇锁冲突立即返回 409：显式的 HTTP 修改不再等待配置锁（原来最多等 30 秒），返回 CONFLICT，details 中 conflict_type 为 path_busy、retryable 为 true，客户端应退避重试；内部 Session/Skill 抽取仍按原来的方式等待。#7553
9. 快照路径索引默认启用：默认在 {storage.workspace}/_system/snapshot/log/snapshot_log.db 创建 SQLite 索引（每个节点各自一份）。升级后每个账户、分支的第一次提交会在后台回填全部历史，历史较长的部署会在每个节点上产生一次 CPU 和 IO 开销。多实例部署请配置 git.snapshot.log.provider: "mysql" 和 OPENVIKING_SNAPSHOT_LOG_DSN：服务启动时建表，数据库账号需要建表权限，DSN 环境变量缺失时服务无法启动。设为 none 可关闭。#7505
10. watch_leader_provider 已弃用：下一个版本将移除。请改为设置 storage.agfs.coordination.provider，并删除旧字段；cache 需要顶层 cache 配置。参与协调的节点需要使用相同的后端和顶层 service_name，建议同时升级，避免新旧节点长时间混跑。使用 cache 时语义任务版本在入队时由 Redis 分配，Redis 不可用会导致入队失败。#7466
11. 标签加减运算改变了以 + / - 结尾的 key 的含义：set_tags 的 append 模式中，key 以 + 或 - 结尾的标签按十进制加减处理（如 count+=1 把 count 加 1），不再作为普通标签保存；c++=1 现在是给 c+ 加 1。值不是数字（如 x+=abc）或已有值不是数字时返回 InvalidArgumentError。append 模式中的非法标签（如缺少 =）不再被静默丢弃，而是让请求失败。#7405
12. 依赖：LiteLLM 固定为 >=1.103.10,<1.103.11，修复 Responses 非流式回复中叙述与工具调用被拆开的问题；新增可选依赖 openviking[pgvector]。#7313、#7516
13. React 组件：@openviking/react 独立发版，本范围内有多处 breaking 接口变更，包括 WikiDashboard 操作改由宿主定义、TUI 快捷命令预设、FilePreview/FileBrowser 操作统一、公共组件改名、FileTree 的 renderDashboard 改为 renderRowTrailing、Console modes 以及移除 @openviking/react/modules/viking-bot 入口。以源码方式集成的项目请对照这些 PR 迁移。#7435、#7462、#7475、#7506、#7537、#7559

修复

• 记忆：记忆工具会展开 viking://~/memories/... 别名；跨会话的写入和删除合并规划，避免最终冲突检查失败；训练删除或合并历史经验页时保留链接并对邻居页加锁；已合并的记忆标签不再重复解析；俄罗斯所有时区都映射为 ru。#7417、#7392、#7384、#7500、#7486
• 存储与 Watch：同步失败会向上报告，不再在不完整同步后清理暂存内容或重放部分源树；增量导入分页不再漏读，并按 URI 补查索引；文件模式的 Watch 状态原样持久化，不再触发 Privacy 大小上限。#4786、#7501、#7551
• 解析：AnyDoc 输出能解析脚注、尾注中指向书签的链接，并保留段落中只含 - / = 的字面文本。#7202、#7325
• 模型与 CLI：额度耗尽归类为配额错误；CLI 设置了可识别的 OPENVIKING_LANG 时跳过首次语言初始化；同步请求的任务轮询间隔上限为 1 秒。#7308、#7439、#7572
• Gateway 与插件：修复 Windows 上 SQLite 存储初始化；Codex 插件启动补传时使用历史会话自己的 peer；Pi 扩展按分支记录 capture 进度，恢复会话后不再重复上传历史。#7474、#6406、#5855

其他更新

Console、FileBrowser、文件预览、目录引导、VikingBot 会话、经验面板和只读版本历史均有更新，FileBrowser 搜索支持四种检索模式，新增 CodeMirror 编辑。React 包已发布 0.1.9 和 0.1.10，main 上的改动自动发布 beta。另有 ragfs 的 git 服务、锁管理器和 Redis provider 模块化重构，数据库契约测试改为对真实 MySQL 和 Redis 运行，以及 Responses 认证和实时上下文入门文档。#7344、#7438、#7460、#7472、#7490、#7498、#7499、#7510、#7513、#7523、#7524、#7536、#7541、#7554、#7556、#7557、#7522、#7542、#7445、#7442、#7549、#7519、#7314、#7573

English

Highlights

• PostgreSQL deployment options: A pgvector vector backend (storage.vectordb.backend: "pgvector", with exact or HNSW search; install openviking[pgvector]) and PostgreSQL PathLock (storage.agfs.pathlock.provider: "postgres") let multi-process and multi-host deployments share vector data and path-lock leases without Redis. #7516, #7481
• Multi-node coordination: The new storage.agfs.coordination setting (memory / sqlite / cache) handles Watch leadership and semantic task revisions. Only persisted work supersedes older tasks, and per-key state expires after one day. #7466
• Snapshot path history index: snapshot/log?paths=... uses a derived index to find the commits that touched a path. SQLite is the default, MySQL is available for multi-instance deployments, and none keeps the original scan. Snapshot commits, stored content and API responses are unchanged. #7505
• Gateway context profiles: recall_peer_scope (all / actor) can restrict recall to the current peer, capture_memory_types limits which memory types capture extracts, and capture sessions preserve the user's own memory policy. #7389, #7367, #7429
• Usage counters and batch tags: append mode in set_tags accepts k+=number / k-=number patches (decimal arithmetic; a missing key starts at 0), which can serve as counters. POST /api/v1/content/batch_set_tags accepts 1-50 URIs and returns successful items and failed entries; a partial failure still returns 200. Available in the CLI (ov attrs batch-set-tags) and the Python, TypeScript and Go SDKs. #7405
• Static soul.md and preset policy: memories/soul.md is now an editable static agent instruction file, and VikingBot reads it from OpenViking on each turn. server.user_config_defaults.preset_global_policy (off by default) creates the packaged GLOBAL_POLICY.md during user initialization. #7328, #7512
• Import and retrieval: First non-strict imports can now partially succeed (previously any failed file failed the whole import); Feishu imports support Wiki-backed files and native Slides; remote PathGlob is controlled by storage.vectordb.enable_path_glob, which falls back to each adapter's default when unset. #7427, #7153, #7461

Published versions

Main package openviking==0.5.5, Python SDK openviking-sdk==0.1.20, and standalone CLI 0.5.3. batch_set_tags and ov attrs batch-set-tags require a 0.5.5 server.

pip install --upgrade 'openviking==0.5.5' 'openviking-sdk==0.1.20'

Upgrade and migration

1. Gateway profiles enable every OpenViking tool by default, including write tools. The default disabled_tools is now empty, so remember, write, edit, add_resource, add_skill, forget, set_acl and cancel_watch, which earlier releases disabled by default, are enabled, and tools added later are enabled too. Saved profiles and ongoing conversations keep their tools. Accounts without a saved default profile, and a gateway default_profile that does not set disabled_tools, now get every tool. PUT /admin/policies/{id} replaces the whole profile: omitting disabled_tools in the request enables every write tool on a saved profile. To keep the previous selection, list these tools explicitly in default_profile.disabled_tools and always send the complete disabled_tools when updating a profile. #7436
2. X-OpenViking-Context can only narrow tool access. disabled_tools in the header adds to the profile's exclusions, and gateway_tools cannot turn tools back on. Clients that relied on {"disabled_tools":[]} or {"gateway_tools":true} to get extra tools should change the profile instead. #7446
3. soul and identity are no longer extracted. Both memory types are retired and ignored in persisted policies and deployment overrides. The account memory-template API lists 4 editable templates. Existing soul.md and identity.md files are left unchanged. A missing soul.md is created from the defaults during initialization or at the next self-memory commit. Automatic memory updates cannot modify soul.md or identity.md; a batch containing such an operation is rejected. #7328
4. Kafka reporting is configured in ov.conf (breaking configuration change). Reading from Nacos or an external JSON file has been removed: server.observability.reporting drops config_file and the nacos_* fields, and NACOS_CONFIG_FILE, NACOS_SERVER_ADDR and related environment variables are no longer read. Reporting now reads reporting.kafka and requires both reporting.enabled and reporting.telemetry.enabled. The old fields do not stop the server from starting, but reporting stops until the configuration is migrated. Deployments configured through Nacos or an external JSON file must move the kafka and telemetry sections into ov.conf and restart. Deployment ownership can be set in reporting.telemetry.deployment; OV_METRICS_ACCOUNT_ID, OV_RESOURCE_ID and OV_REGION remain fallback values. #7491
5. Skill updates no longer back up or roll back. An update replaces the old package directly. After a failure or cancellation, files, index records and privacy configuration stay as they were at the point of failure, and the old version is not restored. SKILL.md and .source.json are kept until overwritten, so a failed update can be retried. #7509
6. First non-strict imports can partially succeed. Previously any failed file failed the whole directory import, regardless of strict. With strict=false (the default), a first import into a new target now commits the successful part: the task completes with status="partial", import_complete=false and the failed items in failed_files, so callers that only check the task status should also check import_complete. A partial import does not advance the source checkpoint, and the Watch run ends as partial; source authentication failures still fail the import. strict=true still rejects incomplete commits, and an incomplete update to an existing resource returns FAILED_PRECONDITION and leaves the old content in place. #7427
7. Git import network checks. Git preflight, clone and fetch no longer follow HTTP redirects, so use the final repository URL. GitHub/GitLab ZIP downloads still follow redirects and validate each destination. Loopback, link-local, unspecified, multicast, reserved and known cloud-metadata addresses are always rejected, even for allowlisted code hosts or with allow_private_networks=true. #7441
8. Privacy configuration writes return 409 on lock conflicts instead of waiting (previously up to 30 seconds). The error is CONFLICT with conflict_type: "path_busy" and retryable: true in details; clients should back off and retry. Internal session and skill extraction still waits. #7553
9. The snapshot path index is enabled by default. It creates a SQLite database at {storage.workspace}/_system/snapshot/log/snapshot_log.db on each node. After the upgrade, the first commit on each account and branch backfills the full history in the background, which costs CPU and IO once per node on deployments with long histories. For multi-instance deployments, set git.snapshot.log.provider: "mysql" and OPENVIKING_SNAPSHOT_LOG_DSN: the table is created at startup, so the database user needs CREATE privileges, and the server does not start if the DSN variable is missing. Set none to disable the index. #7505
10. watch_leader_provider is deprecated and will be removed in the next version. Set storage.agfs.coordination.provider and remove the old field; cache requires the top-level cache configuration. Participating nodes must share the backend and the top-level service_name; upgrade them together rather than running old and new nodes side by side for long. With cache, semantic task revisions are allocated in Redis at enqueue time, so enqueueing fails when Redis is unavailable. #7466
11. Tag arithmetic changes the meaning of keys ending in + or -. In append mode of set_tags, a tag whose key ends in + or - is applied as decimal addition or subtraction (count+=1 adds 1 to count) instead of being stored as an ordinary tag, so c++=1 now adds 1 to c+. A non-numeric operand (such as x+=abc) or a non-numeric existing value returns InvalidArgumentError. Invalid tags in append mode (for example, without =) are no longer silently dropped; the request fails. #7405
12. Dependencies: LiteLLM is pinned to >=1.103.10,<1.103.11, which keeps narration and function calls together in non-streaming Responses replies. The new optional extra openviking[pgvector] is available. #7313, #7516
13. React components: @openviking/react is released independently, and this range contains several breaking API changes: host-defined WikiDashboard actions, TUI quick-command presets, unified FilePreview/FileBrowser actions, renamed public components, FileTree's renderDashboard renamed to renderRowTrailing, Console modes, and removal of the @openviking/react/modules/viking-bot entry. Source integrations should migrate according to these PRs. #7435, #7462, #7475, #7506, #7537, #7559

Fixes

• Memory: Memory tools expand viking://~/memories/... aliases. Cross-session writes and deletes are planned together, so the final conflict check no longer fails. Training keeps links and locks neighbouring pages when it deletes or merges historical experience pages. Merged memory tags are not parsed again, and every Russian time zone maps to ru. #7417, #7392, #7384, #7500, #7486
• Storage and Watches: Failed syncs are reported instead of being followed by staged-content cleanup or a replay of a partially moved source tree. Incremental-import pagination no longer misses entries and looks up indexes by URI. File-mode Watch state is persisted verbatim and no longer hits the Privacy size limit. #4786, #7501, #7551
• Parsing: AnyDoc output resolves bookmark links found in notes and preserves literal - / = lines in paragraphs. #7202, #7325
• Models and CLI: Exhausted credit balances are classified as quota errors. The CLI skips first-run language setup when a recognized OPENVIKING_LANG is set. Synchronous task waits poll at least once per second. #7308, #7439, #7572
• Gateway and plugins: SQLite stores initialize on Windows. The Codex plugin's startup sweep keeps each historical session's own peer, and the Pi extension tracks capture progress per branch, so resumed sessions no longer re-upload history. #7474, #6406, #5855

Other updates

Console, FileBrowser, file previews, directory guidance, VikingBot conversations, the experience dashboard and read-only version history are updated. FileBrowser search offers four retrieval modes, and file previews gain CodeMirror editing. React 0.1.9 and 0.1.10 are published, and changes on main now publish beta builds automatically. This release also modularizes the ragfs git service, lock manager and Redis provider, runs the database contract tests against real MySQL and Redis, and adds documentation for Responses authentication and a live-context walkthrough. #7344, #7438, #7460, #7472, #7490, #7498, #7499, #7510, #7513, #7523, #7524, #7536, #7541, #7554, #7556, #7557, #7522, #7542, #7445, #7442, #7549, #7519, #7314, #7573

首次贡献者 / New contributors

感谢 / Thanks to daniil4545 (#7486) and mmhh256 (#7474).

完整变更 / Full changelog