Skip to content

v0.4.14

Latest
Latest

Choose a tag to compare

View all tags
@qin-ctx qin-ctx released this 17 Aug 06:28
· 4 commits to main since this release
v0.4.14
6e77291
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

OpenViking v0.4.14 Release Notes / 发布说明

Release date / 发布日期: 2026-08-17

Full Changelog / 完整变更记录: [v0.4.13...v0.4.14](v0.4.13...v0.4.14)

This release contains 82 commits. / 本版本包含 82 个提交。

中文

版本概览

v0.4.14 让 viking:// 更接近 Agent 可直接使用的工作区：MCP 新增目录树浏览、文本写入和精确编辑，资源导入扩展到固定 Git commit、私有仓库、飞书云盘目录与文件，Session 则获得事件标签和可更新的自动提交策略。

本版本也收敛了客户端和记忆架构。Python 调用统一迁移到 HTTP SDK，记忆抽取统一使用 V3，Qdrant 和 openGauss 向量后端被移除。升级前请重点阅读“升级与兼容性”。

主要更新

  • Agent 可直接读写 viking://：MCP 新增 tree、write 和 edit。write 支持创建、覆盖和追加，edit 执行精确字符串替换并在匹配不明确时保持文件不变；wait=true 可等待语义和向量索引刷新。当前用户还可以使用 viking://user/... 短路径保存普通文本文件。
  • 可移植 Agent Plugins 1.0 包：新增 agent-plugins/，包含标准清单、零 npm 运行时依赖的 stdio-to-HTTP MCP 代理和 openviking-memory Skill。它适用于遵循 Agent Plugins 1.0、但没有专属 hooks 集成的客户端；自动会话捕获和 prompt 前自动召回不在该规范范围内。
  • DeepSeek Harness 新插件：新增 @openviking/dsh-memory-plugin，提供自动召回、Session 捕获、失败写入重放、viking:// 路径保护和模型可调用的记忆工具。插件使用 DSH 原生 tool/message 构造器，并严格适配 @deepseek-ai/dsh 0.1.0-rc.6。
  • DeerFlow 与 TRAE 集成：DeerFlow 新增 MemoryManager 和 MCP 两种接入指南，前者负责自动写入、召回和注入，后者负责 Agent 主动检索与管理，建议同时启用。TRAE/TRAE CN 的 Hook + MCP 集成覆盖自动召回、逐轮捕获和短会话 commit，本版本还会在 commit 日志中保留 trace_id。OpenCode 同时新增仅 Hooks 模式。
  • 资源导入与同步增强：OpenViking Assets 支持固定的 40 位 Git commit、显式 to 目标和 HTTPS 私有仓库凭据；普通 add_resource 和 Watch 也支持私有 Git 鉴权。飞书/Lark 导入新增 Drive 文件与递归目录支持。Web Studio 补齐远程资源选项和 Watch 的查看、编辑、暂停、恢复、触发与历史流程。
  • Session 与 Memory 能力收敛：记忆抽取统一走 V3。Session 可在创建时设置事件记忆默认标签，之后通过配置接口更新，并在单次 commit 时覆盖或清空；自动提交策略也可动态更新或禁用。配置 experiences 会一起启用 cases 和 trajectories，且只有实际产生 case 时才继续生成 Agent Evolution 派生记忆。
  • 检索标签与 Agent Evolution 查询：reindex 可用 replace 或 append 模式更新本次成功重建记录的标签。Experience 的 Trajectory 列表和结果分布接口新增 UTC 日期范围过滤。
  • Studio 与管理体验：Web Studio 新增账号删除流程、按作用域分组的 Skill 视图，并改进资源导入和定时同步管理；删除用户时会立即撤销身份，再由持久队列清理用户数据。

新功能用法

DeepSeek Harness（DSH）记忆插件

前置要求：@deepseek-ai/dsh 必须使用精确版本 0.1.0-rc.6，Node.js 使用 ^22.19.0 或 >=24，并准备一个可访问的 OpenViking Server。

export OPENVIKING_URL=http://127.0.0.1:1933
export OPENVIKING_API_KEY=your-api-key

dsh plugin --profile default add @openviking/dsh-memory-plugin
dsh --profile default --dump-config

需要注意：

  • 插件在 agent/pre-step 注入带来源的 user message，而不是修改 system prompt，因此在 persona.complete: true 的 preset 下也不会被静默丢弃。
  • session/event 捕获消息，turn/end 达到阈值后 commit；可重试失败会进入 pending queue，在下次 Session 启动时重放。
  • 设置 OPENVIKING_WORKSPACE_PEER=1 可按工作区派生 actor peer；OPENVIKING_RECALL_PEER_SCOPE=actor 可限制只召回当前工作区记忆。
  • 插件暴露 viking_search、viking_read、viking_browse、viking_remember、viking_add_resource 等工具。viking_forget 会永久删除数据，只应在用户明确要求时调用。

DeerFlow：MemoryManager + MCP

DeerFlow 的两个入口职责不同，建议同时配置：

  • MemoryManager：自动把对话写入 OpenViking，在模型调用前召回并注入记忆。
  • MCP：让 Agent 按需调用 search、read、write、edit 等工具；只配置 MCP 不会自动写入或自动召回。

在 DeerFlow 项目根目录的 .env 中配置 USER API Key：

OPENVIKING_API_KEY=your-api-key

将 config.yaml 的 memory 段切换到 OpenViking：

memory:
  enabled: true
  injection_enabled: true
  shutdown_flush_timeout_seconds: 30
  manager_class: openviking
  mode: middleware
  backend_config:
    base_url: https://openviking.example.com
    owner_user_id: default
    api_key_env: OPENVIKING_API_KEY
    startup_policy: fail_fast
    failure_policy:
      read: fail_open
      write: log_and_drop

复制并编辑 extensions_config.json，启用 OpenViking MCP：

cp extensions_config.example.json extensions_config.json
{
  "mcpServers": {
    "openviking": {
      "enabled": true,
      "type": "http",
      "url": "https://openviking.example.com/mcp",
      "headers": {"X-API-Key": "$OPENVIKING_API_KEY"}
    }
  }
}

保存后运行 make dev 重启 DeerFlow。read: fail_open 表示召回失败时主 Agent 仍会继续回答；write: log_and_drop 表示写入失败只记录日志，不会自动补写。OpenViking 的摘要与记忆抽取是异步任务，消息写入成功后不会立即出现长期记忆。

TRAE / TRAE CN 记忆集成

前置要求：macOS 或 Linux、Node.js 18+，以及支持 SessionStart、UserPromptSubmit、PreToolUse、Stop Hook 的 TRAE/TRAE CN 版本。

# 同时安装 TRAE 和 TRAE CN
bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh) \
  --harness trae,trae-cn

安装器询问连接方式时，火山引擎云服务用户选择“火山引擎 OpenViking 云服务”；只有本机已运行 OpenViking Server 时才选择“自建 / 本地”。安装完成后必须彻底退出并重启 TRAE/TRAE CN，再新建 Agent Session。

集成通过 SessionStart 加载画像和项目记忆，通过 UserPromptSubmit 自动召回，通过 Stop 捕获并立即 commit 当前轮次，因此短会话也能进入记忆抽取。MCP 同时提供主动检索和管理工具。v0.4.14 会在 commit 日志中输出 trace_id，失败时可设置 OPENVIKING_DEBUG=1 并检查：

  • TRAE：~/.openviking/logs/trae-hooks.log
  • TRAE CN：~/.openviking/logs/trae-cn-hooks.log

如果 GitHub 无法访问，可将安装命令替换为 TOS 镜像，并追加 --dist tos：

bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh) \
  --harness trae,trae-cn --dist tos

没有 Hooks 的 Agent Plugins 1.0 客户端

让兼容客户端加载仓库中的 agent-plugins/ 目录即可获得 OpenViking MCP 和 openviking-memory Skill。该包依赖模型主动执行召回与沉淀；如果客户端支持专属 Hooks，应优先使用对应集成，以获得自动捕获和 prompt 前自动召回。

升级与兼容性

  • Python 嵌入式客户端已移除：OpenViking、SyncOpenViking、AsyncOpenViking、LocalClient 及对应嵌入式实现不再导出。服务端安装 openviking 并独立运行；只需要连接现有服务的应用可单独安装 openviking-sdk

  • MinerU 接口切换到官方协议：mineru_endpoint 现在是 base URL，OpenViking 调用 POST {endpoint}/file_parse；mineru_params 改为 mineru_bodys，mineru_api_key 已移除。strategy="mineru" 会在服务初始化时强制检查 {endpoint}/health；strategy="auto" 检查失败时记录警告，并保留本地解析优先的回退行为。

  • Memory V3 成为唯一抽取链路：memory.version 已废弃并被忽略，配置值不会再选择 V2；memory.v2_lock_retry_interval_seconds 和 memory.v2_lock_max_retries 不再受支持。SessionCommit worker 默认并发从 4 调整为 8。

体验与可靠性改进

  • 语义向量化任务改为流式调度，并延迟加载完整 embedding 内容；父目录语义刷新保持异步，降低大批量入库时的内存和队列压力。
  • PathLock 在高竞争时退避重试，并增强 lease handoff、保活和 adopt capability 轮换，减少长任务误失锁。
  • Session 后续归档不再占用 worker 等待前序归档；记忆 patch 移出事件循环，V3 link 更新扩大锁覆盖并报告真实失败的 patch block。
  • MCP Streamable HTTP 改为无状态模式，避免多实例、负载均衡部署中出现间歇性 Session not found。
  • VikingBot compile 在运行超时或迭代上限时尽量保留工作区中的部分产物，并增加运行时 deadline 与输出限制保护。

修复

  • Markdown YAML frontmatter 默认不再从最终正文中静默丢失；强制拆分的 Markdown chunk 保持在 token 预算内，标题锚点与 GitHub 标点处理一致。
  • 超大图片在送入 VLM 或多模态 Embedding 前临时缩放，AGFS 中保存的原始图片不变。
  • L1 overview 现在能进入 Rerank 输入；首次 Session 检索会被正确记录，空检索不再被健康检查误判为故障。
  • OVPack 账号恢复不再删除目标端独有数据；目录移动会完整枚举条目，LocalFS 的 ENOENT 会正确映射为 NotFound，零字节文件不会被误判为缺失索引。
  • Session JSONL 只按换行符拆分，不再把 Unicode 行分隔符当作记录边界；assistant-only event range 会保留正确 owner。
  • Stats、Debug 和 Session 的错误响应现在返回与错误码一致的 HTTP 状态；VikingDB 日期范围会统一规范化，非法写入标签会被丢弃。

文档、测试与安全

  • 新增 Agent Plugins、DSH、DeerFlow、OpenViking Assets、MCP 写入工具、Session 标签和 Agent Evolution 日期过滤文档，并同步中英文 API/配置示例。
  • Agent Plugins 包加入规范一致性测试；DSH 插件覆盖注册结构、捕获、离线队列与可选真实服务召回测试。
  • 私有 Git token 仅允许用于 HTTPS，并与仓库 URL 绑定保存在 Watch 私有状态中，不进入普通队列或 Watch API 输出。未启用 VikingFS 加密时，该服务端控制文件仍包含明文 token 状态。
  • Watch 刷新补齐鉴权校验，服务端 API key 只读副本可通过 store watcher 刷新；过期持久化任务会被清理。

English

Overview

v0.4.14 makes viking:// a more complete agent workspace. MCP can now browse trees, write text, and apply exact edits; resource ingestion supports pinned Git commits, private repositories, and Feishu Drive folders and files; Sessions gain event tags and mutable auto-commit policies.

The release also consolidates the client and memory architecture. Python consumers move to the HTTP SDK, memory extraction always uses V3, and the Qdrant and openGauss vector backends have been removed. Review the upgrade notes before deploying.

Highlights

  • Agent-writable viking:// workspace: MCP adds tree, write, and edit. Writes support create, replace, and append; exact edits leave the file unchanged when the match is missing or ambiguous. wait=true waits for semantic and vector index refreshes, and viking://user/... addresses the authenticated user's workspace.
  • Portable Agent Plugins 1.0 package: the new agent-plugins/ package contains a standard manifest, a zero-runtime-dependency stdio-to-HTTP MCP proxy, and the openviking-memory Skill. It targets conforming clients without a dedicated hooks integration; the specification does not provide automatic session capture or pre-prompt recall.
  • New DeepSeek Harness plugin: @openviking/dsh-memory-plugin adds automatic recall, Session capture, retryable-write replay, viking:// path protection, and model-callable memory tools. It uses native DSH tool/message constructors and is pinned to @deepseek-ai/dsh 0.1.0-rc.6.
  • DeerFlow and TRAE integrations: DeerFlow gains both MemoryManager and MCP setup guides. MemoryManager provides automatic write, recall, and injection, while MCP provides agent-invoked search and management; using both is recommended. The TRAE/TRAE CN Hooks + MCP integration covers automatic recall, per-turn capture, and short-session commits, with commit trace_id values preserved in v0.4.14 logs. OpenCode also gains a hooks-only mode.
  • Resource ingestion and synchronization: OpenViking Assets supports full pinned Git commit SHAs, explicit to targets, and private HTTPS Git credentials. Regular add_resource and Watch flows support private Git authentication as well. Feishu/Lark ingestion now accepts Drive files and recursive folders. Web Studio adds richer remote import options and complete Watch management flows.
  • Unified Session and Memory behavior: memory extraction now has one V3 path. Sessions can define default event-memory tags, update them later, and override or clear them for one commit; auto-commit policies can also be updated or disabled. Selecting experiences enables cases and trajectories, and Agent Evolution derivatives run only when extraction actually produces a case.
  • Search tags and Agent Evolution queries: reindex can replace or append tags on successfully rebuilt records. Experience trajectory and outcome endpoints accept inclusive UTC date ranges.
  • Studio and administration: Web Studio adds account deletion, scope-grouped Skills, improved resource imports, and scheduled synchronization management. Removing a user now revokes identity immediately and delegates data cleanup to a durable queue.

New Feature Usage

DeepSeek Harness (DSH) memory plugin

Requirements: exact @deepseek-ai/dsh version 0.1.0-rc.6, Node.js ^22.19.0 or >=24, and a reachable OpenViking Server.

export OPENVIKING_URL=http://127.0.0.1:1933
export OPENVIKING_API_KEY=your-api-key

dsh plugin --profile default add @openviking/dsh-memory-plugin
dsh --profile default --dump-config

Important behavior:

  • The plugin injects source-attributed user messages at agent/pre-step instead of changing the system prompt, so presets with persona.complete: true do not silently discard recalled context.
  • session/event captures messages and turn/end commits after the threshold. Retryable failures enter a pending queue and replay on the next Session start.
  • Set OPENVIKING_WORKSPACE_PEER=1 to derive actor peers by workspace and OPENVIKING_RECALL_PEER_SCOPE=actor to restrict recall to the current workspace.
  • Tools include viking_search, viking_read, viking_browse, viking_remember, and viking_add_resource. viking_forget permanently deletes data and should only run on an explicit user request.

DeerFlow: MemoryManager + MCP

The two DeerFlow entry points have different responsibilities and should normally be enabled together:

  • MemoryManager automatically writes conversations, recalls memories before model calls, and injects them into context.
  • MCP lets the agent invoke tools such as search, read, write, and edit. MCP alone is not an automatic memory backend.

Set the USER API key in the DeerFlow project .env:

OPENVIKING_API_KEY=your-api-key

Switch the memory section in config.yaml to OpenViking:

memory:
  enabled: true
  injection_enabled: true
  shutdown_flush_timeout_seconds: 30
  manager_class: openviking
  mode: middleware
  backend_config:
    base_url: https://openviking.example.com
    owner_user_id: default
    api_key_env: OPENVIKING_API_KEY
    startup_policy: fail_fast
    failure_policy:
      read: fail_open
      write: log_and_drop

Copy and edit extensions_config.json to enable OpenViking MCP:

cp extensions_config.example.json extensions_config.json
{
  "mcpServers": {
    "openviking": {
      "enabled": true,
      "type": "http",
      "url": "https://openviking.example.com/mcp",
      "headers": {"X-API-Key": "$OPENVIKING_API_KEY"}
    }
  }
}

Restart DeerFlow with make dev. With read: fail_open, the main agent continues when recall fails. With write: log_and_drop, failed writes are logged but not replayed. OpenViking summary and memory extraction are asynchronous, so long-term memories do not appear immediately after message writes.

TRAE / TRAE CN memory integration

Requirements: macOS or Linux, Node.js 18+, and a TRAE/TRAE CN release supporting the SessionStart, UserPromptSubmit, PreToolUse, and Stop Hooks.

# Install both TRAE and TRAE CN
bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh) \
  --harness trae,trae-cn

When prompted, Volcengine Cloud users should select Volcengine OpenViking Cloud. Select Self-hosted / local only when an OpenViking Server is already running locally. Quit and restart TRAE/TRAE CN completely after installation, then create a new Agent Session.

SessionStart loads profile and project memory, UserPromptSubmit recalls context, and Stop captures and immediately commits the completed turn so short Sessions are persisted as well. MCP supplies explicit search and management tools. v0.4.14 includes trace_id in commit logs; set OPENVIKING_DEBUG=1 and inspect:

  • TRAE: ~/.openviking/logs/trae-hooks.log
  • TRAE CN: ~/.openviking/logs/trae-cn-hooks.log

Use the TOS mirror when GitHub is unavailable:

bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh) \
  --harness trae,trae-cn --dist tos

Agent Plugins 1.0 clients without Hooks

Point a conforming client at the repository's agent-plugins/ directory to load the OpenViking MCP server and openviking-memory Skill. This package relies on the model to invoke recall and persistence. Prefer a dedicated integration when the client supports Hooks, because it provides automatic capture and pre-prompt recall.

Upgrade Notes

  • Python embedded clients were removed: OpenViking, SyncOpenViking, AsyncOpenViking, LocalClient, and their embedded implementations are no longer exported. Install and run openviking as the server; applications that only connect to an existing server can install the standalone openviking-sdk:

    pip install openviking
openviking-server init
openviking-server

# HTTP client only
pip install openviking-sdk
    from openviking_sdk import SyncHTTPClient

client = SyncHTTPClient(url="http://127.0.0.1:1933", api_key="your-key")
client.initialize()

  • Qdrant and openGauss backends were removed: built-in storage.vectordb.backend values are now local, cuvs, http, volcengine, and vikingdb. Deployments using qdrant or opengauss must migrate their data and configuration before upgrading.

  • MinerU now uses the official API contract: mineru_endpoint is a base URL and OpenViking calls POST {endpoint}/file_parse; mineru_params becomes mineru_bodys, and mineru_api_key has been removed. strategy="mineru" requires {endpoint}/health to pass during service initialization. strategy="auto" logs a warning on preflight failure and retains local-first fallback behavior.

  • Memory V3 is the only extraction path: memory.version is deprecated and ignored, so it no longer selects V2. memory.v2_lock_retry_interval_seconds and memory.v2_lock_max_retries are no longer supported. The default SessionCommit worker concurrency increases from 4 to 8.

Improvements

  • Semantic vectorization is streamed and full embedding content is materialized later; parent semantic refresh stays asynchronous, reducing queue and memory pressure during large ingestions.
  • PathLock adds contention backoff, lease handoff keepalive, and adopt-capability rotation for safer long-running work.
  • Later Session archives no longer occupy workers while waiting for earlier archives. Memory patch work moves off the event loop, while V3 link updates use broader lock coverage and report the actual failing patch block.
  • MCP Streamable HTTP is stateless, preventing intermittent Session not found failures behind load balancers and multi-instance deployments.
  • VikingBot compile salvages partial workspace output when runtime timeouts or iteration limits are reached, with stronger deadline and output-limit enforcement.

Fixes

  • Markdown YAML frontmatter is no longer silently removed from stored content by default. Forced Markdown chunks stay within the token budget, and heading anchors match GitHub punctuation behavior.
  • Oversized images are temporarily downsampled for VLM and multimodal embedding requests while the original AGFS bytes remain unchanged.
  • L1 overviews now reach Rerank input. First-turn Session recalls are recorded correctly, and empty retrievals are no longer treated as health failures.
  • Account-level OVPack restore preserves target-only data. Directory moves enumerate every entry, LocalFS ENOENT maps to NotFound, and zero-byte files are excluded from index expectations.
  • Session JSONL splits only on newline characters rather than Unicode line boundaries, and assistant-only event ranges retain the correct owner.
  • Stats, Debug, and Session error envelopes now return the matching HTTP status. VikingDB date ranges are normalized consistently, and invalid write-time tags are discarded.

Docs, Tests, and Security

  • Added or refreshed bilingual documentation for Agent Plugins, DSH, DeerFlow, OpenViking Assets, MCP write tools, Session tags, and Agent Evolution date filters.
  • The Agent Plugins package includes specification-conformance tests. The DSH plugin covers registration shape, capture, offline queues, and an optional live-server recall gate.
  • Private Git tokens are restricted to HTTPS and stored in repository-bound private Watch state rather than normal queues or Watch API output. Without VikingFS encryption, that server-side control file still contains plaintext token state.
  • Watch refresh authorization is enforced, read-replica API-key indexes refresh through a store watcher, and expired persisted task records are deleted.
Assets 2
Loading