Doramagic 项目包 · 项目说明书

OpenViking 项目

OpenViking 是专为 AI Agent(如 openclaw)设计的开源上下文数据库,通过文件系统范式统一管理 Agent 所需的上下文(记忆、资源和技能),实现分层上下文交付与自演化。

OpenViking 概览:上下文数据库与五大核心概念

OpenViking 是一个面向 AI Agent 的开源上下文数据库(Context Database),定位为"Agent 时代的文件系统 + 长期记忆 + 语义检索引擎"。它通过统一协议 viking:// 暴露资源(Resources)、会话(Session)、用户(User)三类上下文,配合模块化解析、分层信息模型和语义队列,使 Agent 能够按需加载不同粒度的...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 概念一:三层信息模型(L0 / L1 / L2)

继续阅读本节完整说明和来源证据。

章节 概念二:Viking URI 统一寻址

继续阅读本节完整说明和来源证据。

章节 概念三:三种上下文类型

继续阅读本节完整说明和来源证据。

OpenViking 是一个面向 AI Agent 的开源上下文数据库(Context Database),定位为"Agent 时代的文件系统 + 长期记忆 + 语义检索引擎"。它通过统一协议 viking:// 暴露资源(Resources)、会话(Session)、用户(User)三类上下文,配合模块化解析、分层信息模型和语义队列,使 Agent 能够按需加载不同粒度的信息,而不是一次性将全部上下文塞入提示词窗口。

一、上下文数据库的角色

OpenViking 不是一个传统 RAG 库,也不是单纯的向量数据库,而是一套自包含的上下文引擎

  • 统一寻址:通过 viking:// URI 把本地文件、远程仓库、对话记忆纳入同一棵虚拟文件系统树 openviking/parse/parsers/README.md
  • 多模态解析:支持 Markdown、PDF、HTML、Word、PPT、Excel、EPUB、图像、音视频以及主流编程语言代码 examples/openclaw-plugin/README.md
  • 多客户端接入:提供 Embedded SDK、HTTP Server、CLI(ov 命令)、MCP 端点,以及与 Codex、Claude Code、OpenClaw、OpenCode 等 IDE/Agent 的官方插件 examples/basic-usage/README.md
  • 轻量 HTTP SDK:通过 openviking-sdk 可直接调用远端服务,避免引入本地运行时依赖 sdk/python/README.md

二、五大核心概念

概念一:三层信息模型(L0 / L1 / L2)

OpenViking 把任意上下文拆成三层,让 Agent 按场景读取合适粒度 openviking/parse/parsers/README.md

层级文件体积用途
L0 Abstract.abstract.md<200 token摘要,支撑向量化检索与目录快速浏览
L1 Overview.overview.md<1000 token决策参考,章节导览
L2 Detailcontent.md 或原始文件完整内容仅在遍历到终点时按需读取

代码资源同样遵循这一分层:每层目录都有 .abstract.md.overview.md,但 L2 层直接保存原始源文件而不拆解 openviking/parse/parsers/code/README.md

概念二:Viking URI 统一寻址

所有内容都以 viking:// 开头寻址,常见前缀包括 viking://resources/viking://session/viking://user/。例如把仓库导入后会生成 viking://resources/github/volcengine/OpenViking/... 这样可递归到任意深度的目录树 openviking/parse/parsers/code/README.md。CLI 也以这套 URI 为入口:ov lsov readov abstractov overviewov findcrates/ov_cli/README.md

概念三:三种上下文类型

  • Resources:用户导入的静态知识(文件、目录、仓库、网页)。
  • Session:单次对话或任务产生的临时上下文。
  • User:跨 Session 沉淀的长期记忆(偏好、实体、事件)。

Vikingbot 提供 7 个 OpenViking 专用工具(openviking_read / list / search / add_resource / grep / glob / memory_commit)来操作这三类上下文 bot/README.md

概念四:模块化解析与 SemanticQueue

解析器按文件扩展名自动路由(Markdown、PDF、代码、媒体等),输出统一 ResourceNode 树。每个解析器先在临时目录内构建结构,再由 TreeBuilder 移入 AGFS 并按自底向上顺序入队 SemanticQueue,支持并发解析且不冲突 openviking/parse/parsers/README.md

概念五:分层存储与按需加载

存储分为对象存储(向量 + 元数据)与文件系统(viking:// 目录树)。Context 对象只保存 URI 与元数据,内容按 get_abstract / get_overview / get_detail 懒加载并在内存中缓存,避免重复 IO openviking/parse/parsers/README.mdOpenVikingMount 还可将 viking:// 映射到本地路径直接以文件系统范式访问 bot/vikingbot/openviking_mount/README.md

三、系统数据流

flowchart LR
  A[原始资源<br/>URL/文件/仓库] --> B[Parser 路由<br/>按扩展名选择]
  B --> C[临时目录构建<br/>ResourceNode 树]
  C --> D[移入 AGFS<br/>viking:// 树]
  D --> E[SemanticQueue<br/>自底向上]
  E --> F[生成 L0/L1/L2<br/>+ 向量索引]
  F --> G[Agent 通过<br/>find/read/abstract 取用]

四、社区共识与延伸阅读

  • 社区在 #744 中集中追踪 Token 消耗与 Embedding 成本 优化,而 L0/L1 分层正是官方推荐的节流手段。
  • #394 讨论 "Zero-Knowledge Context Proofs" 上下文完整性标准,与 Context 对象的元数据/URI 分离设计直接相关。
  • #1082 的维护者地图与 #55 的 Memex 演示,展示了 VikingBot + Resources + Session 的组合用法。

See Also

  • OpenViking 解析系统
  • Vikingbot 架构与 OpenViking 工具
  • Viking URI 与上下文层级详解

来源:https://github.com/volcengine/OpenViking / 项目说明书

系统架构、C++ 索引内核与存储层

OpenViking 采用分层架构,自底向上依次为:C++ 索引内核 → 存储层(AGFS + VikingVectorIndex)→ 解析与语义层 → 服务层与客户端层。整个系统的核心设计哲学是「物理搬运」与「语义理解」分离,确保高吞吐的资源导入和异步的语义处理。

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 2.1 三表存储模型

继续阅读本节完整说明和来源证据。

章节 2.2 关键特性

继续阅读本节完整说明和来源证据。

章节 4.1 服务端运行模式

继续阅读本节完整说明和来源证据。

1. 总体架构概览

OpenViking 采用分层架构,自底向上依次为:C++ 索引内核 → 存储层(AGFS + VikingVectorIndex)→ 解析与语义层 → 服务层与客户端层。整个系统的核心设计哲学是「物理搬运」与「语义理解」分离,确保高吞吐的资源导入和异步的语义处理。

flowchart TB
    A[Client SDK / CLI / Web Studio] --> B[OpenViking Server HTTP API]
    B --> C[Service Layer / 语义队列]
    C --> D[Parser Layer: PDF/HTML/Code/Media]
    D --> E[AGFS 存储层]
    E --> F[VikingVectorIndex C++ 内核]
    F --> G[三表存储 C/D/T]

2. C++ 索引内核:VikingVectorIndex

VikingVectorIndex 是 OpenViking 的向量索引核心,其 C++ 实现通过 Python abi3 扩展绑定,对外暴露 Python API。资料来源:openviking/storage/vectordb/README.md

2.1 三表存储模型

C++ 内核将数据拆分为三张职责分离的表:

表名名称职责
C 表Candidate Table存储最新向量和标量数据,Key 为 label (uint64)
D 表Delta Table记录 PUT/DELETE 变更历史,用于索引增量更新与崩溃恢复
T 表TTL Table按过期时间排序,加速 TTL 清理的后台任务

资料来源:openviking/storage/vectordb/README.md

2.2 关键特性

  • 线程安全:关键数据结构支持并发访问
  • 增量更新:D 表记录变更后重建索引,避免全量重建
  • TTL 清理:T 表使得过期数据可高效回收

社区中关于 #744「Token 消耗与成本优化问题汇总」提到的 Embedding 处理成本,依赖于本内核对增量索引与并发访问的优化。资料来源:openviking/storage/vectordb/README.md

3. 存储层与解析层的协同

OpenViking 使用 AGFS(资源文件系统)作为统一的逻辑文件系统,URI 形如 viking://resources/...。解析层将外部资源(PDF、HTML、代码、媒体等)按 V5.0 架构处理:

  1. 物理搬运阶段(Parser Phase):资源被上传到 viking://temp/{uuid}/ 临时目录,不进行 LLM 调用,保证 add_resource 接口快速返回。资料来源:openviking/parse/parsers/README.md
  2. 语义处理阶段(Semantic Phase)TreeBuilder 将临时目录移入正式路径,生成 SemanticMsg 推入 SemanticQueue,后台异步生成每层目录的 .abstract.md(L0)与 .overview.md(L1)。资料来源:openviking/parse/parsers/code/README.md
  3. 代码仓库特别处理:使用 git clone --depth 1 浅克隆或 zip 下载作为降级方案,自动忽略 .gitnode_modules 等非代码目录。代码文件在 L2 层不进行拆分,直接存储完整内容。资料来源:openviking/parse/parsers/code/README.md

4. 服务层与客户端接入

4.1 服务端运行模式

OpenViking Server 默认监听 http://127.0.0.1:1933,需要通过 openviking-server --with-bot 启动 VikingBot 支持,否则 /bot/v1/* 端点将返回 503。资料来源:web-studio/README.md

4.2 客户端形态

  • 嵌入式模式ov.OpenViking(path="./data") 本地初始化
  • HTTP 客户端模式ov.SyncHTTPClient(url="http://localhost:1933") 远程调用
  • CLI 工具:支持 ls / tree / read / abstract / overview / find / grep 等命令
  • Web Studio:React/Vite 单页应用,纯前端需连接运行中的 OpenViking Server

资料来源:examples/basic-usage/README.mdnpm/cli/README.md

4.3 智能体集成

OpenViking 提供多种 Agent 集成插件,包括 Claude Code、Codex、OpenClaw 等。bot/workspace/skills/ 内置 githubweathersummarizetmux 等技能,遵循 OpenClaw 的 SKILL.md 格式规范。资料来源:bot/workspace/skills/README.md

社区中 #591 报告的 OpenClaw 2026.3.12 兼容性挂起问题,即与该插件生命周期钩子的同步逻辑相关。

See Also

资料来源:openviking/storage/vectordb/README.md

Agent 集成生态:OpenClaw、Claude Code、Codex、OpenCode、LangChain 与 VikingBot

OpenViking 不仅是一个上下文数据库与解析系统,也是一组面向主流 AI Agent 平台的长期记忆 / 上下文引擎适配层。仓库在 examples/ 目录中提供了针对 OpenClaw、Claude Code、Codex 等 CLI Agent 的官方插件,并在 bot/ 中提供名为 VikingBot 的本地代理运行时。Web Studio 与 CLI 则共同构成...

章节 相关页面

继续阅读本节完整说明和来源证据。

OpenViking 不仅是一个上下文数据库与解析系统,也是一组面向主流 AI Agent 平台的长期记忆 / 上下文引擎适配层。仓库在 examples/ 目录中提供了针对 OpenClawClaude CodeCodex 等 CLI Agent 的官方插件,并在 bot/ 中提供名为 VikingBot 的本地代理运行时。Web Studio 与 CLI 则共同构成观测与管理侧。

1. 集成模式总览

OpenViking 暴露 HTTP API(默认 http://127.0.0.1:1933),Agent 插件以"远端客户端"模式连接,所有数据通过 REST 端点交互,本地不再维护存储或索引进程。资料来源:examples/openclaw-plugin/README.md:18-30web-studio/README.md:14-20

Agent 平台集成形式数据通道主要能力
OpenClawclawhub:@openviking/openclaw-pluginHTTP baseUrl + apiKey自动 recall、/compact 提交、记忆注入
Claude Codeclaude-code-memory-plugin 目录远端 HTTP(环境变量配置)UserPromptSubmit 自动 recall、Stop/PreCompact 增量提交
Codexcodex-memory-plugin 目录Streamable HTTP + Bearer决定性 session id cx-<codex_session_id>MCP 工具桥接
VikingBot仓库内 bot/ 子项目本地存储 + 远端模式双模式7 个原生 OpenViking 工具 + 第三方 MCP
社区曾报告 OpenClaw 2026.3.12 升级后 memory-openviking 插件导致对话挂起的问题(issue #591),提示插件需对齐宿主平台版本。

2. OpenClaw 插件

OpenClaw 插件以"context-engine"插槽形式注册,运行模式为纯 HTTP 客户端:

  • 快速安装openclaw plugins install clawhub:@openviking/openclaw-plugin,再通过 openclaw openviking setup --base-url ... --api-key ... 激活。资料来源:examples/openclaw-plugin/README.md:33-44
  • 生命周期钩子:在 afterTurn 阶段把新消息追加到 OpenViking session,commit/extraction 由阈值触发;assemble 在每轮回复前自动注入相关长期记忆;/compact 触发提交并抽取为长期记忆。资料来源:examples/openclaw-plugin/README.md:60-71
  • 协议层抽象:所有本地文件先经 /api/v1/resources/temp_upload 上传,目录通过纯 JS zip 实现压缩,规避明文路径外发。资料来源:examples/openclaw-plugin/README.md:24-28
  • 运行时路由:插件不启动本地子进程,远程服务必须独立部署;baseUrlapiKey 来自插件配置。资料来源:examples/openclaw-plugin/README.md:42-54

3. Claude Code 与 Codex 记忆插件

二者设计思路相近:把 OpenViking 当作 Agent 的"长期记忆后端",在用户提问前自动 recall,在结束/压缩时增量 commit。

  • Claude Code 通过环境变量驱动,例如 OPENVIKING_COMMIT_TOKEN_THRESHOLD=20000 控制提交阈值,OPENVIKING_WRITE_PATH_ASYNC=true 把写入解耦到后台 worker,避免 Stop 钩子超时。资料来源:examples/claude-code-memory-plugin/README.md:53-72
  • Codex 使用决定性 session id cx-<codex_session_id> 增量追加,在 PreCompact 触发抽取,SessionStart 时按活动窗口启发式决定是否提交刚结束的会话。Codex 同时通过原生 /mcp 端点接入 search / store / read / list / grep / glob / forget / add_resource / health 等工具,无需本地 MCP 进程。资料来源:examples/codex-memory-plugin/README.md:8-22
  • 两套插件均强调"recall → inject → commit"三段式流程,与 issue #744 所跟踪的 token 消耗 / embedding 成本问题紧密相关。资料来源:examples/claude-code-memory-plugin/README.md:60-72

4. VikingBot:本地/远端双模式 Agent

VikingBot 基于 Nanobot 构建,是 OpenClaw 风格的开箱即用 Agent,与 OpenViking 深度耦合:

  • 数据模式:默认本地 ~/.openviking/data/,也可切换为远端 Server 模式。资料来源:bot/README.md:18-22
  • 原生工具集:暴露 7 个专用工具——openviking_read / list / search / add_resource / grep / glob / memory_commit,配合 L0/L1/L2 三层内容访问。资料来源:bot/README.md:38-46
  • 扩展能力:通过 tools.mcp_servers 配置第三方 MCP(filesystem、GitHub 等),工具以 mcp_<server>_<tool> 形式注册。资料来源:bot/README.md:50-66
  • 技能与挂载bot/workspace/skills/ 提供 github / summarize / tmux / skill-creator 等内置技能(遵循 OpenClaw 的 SKILL.md 规范);bot/vikingbot/openviking_mount/viking:// 虚拟文件系统挂载到本地路径(实验性)。资料来源:bot/workspace/skills/README.md:18-30bot/vikingbot/openviking_mount/README.md:6-18

5. 观测与命令行侧

  • Web Studio 是 React/Vite 静态 SPA,覆盖资源管理、检索、Bot 会话、运维诊断;其 sessions 页面依赖 VikingBot 端点(/bot/v1/chat 等),启动需 openviking-server --with-bot。资料来源:web-studio/README.md:10-30
  • CLI@openviking/cli)提供 tui / chat / read / find / search / grep / glob / session / export / import 等子命令,并支持多平台 darwin/linux/windows 包。资料来源:npm/cli/README.md:38-72

6. 社区关注点

  • 完整性证明(issue #394):随着 Agent 普遍依赖长期记忆,呼吁制定"Context Proofs"标准以审计返回上下文的真实性。资料来源:examples/openclaw-plugin/README.md:1-4(说明 OpenViking 作为 OpenClaw context-engine 的角色)。
  • 兼容性:issue #591 反映 OpenClaw 2026.3.12 升级导致 memory-openviking 挂起,需要插件与宿主版本协同演进。
  • 成本与 Token(issue #744):CLI 与插件暴露的 OPENVIKING_COMMIT_TOKEN_THRESHOLD / OPENVIKING_RESUME_CONTEXT_BUDGET 等参数正是为控制 embedding 与召回开销而设。

See Also

来源:https://github.com/volcengine/OpenViking / 项目说明书

部署、运维可观测性及社区热点议题

本页面聚焦 OpenViking 在生产与社区场景下的部署拓扑、运行时可观测性入口以及当前社区正在跟踪的高优先级议题。OpenViking 提供嵌入式 SDK、HTTP 服务端与 Web/CLI 客户端等多种部署形态,运维可观测性依赖于服务端健康检查、任务队列、Bot 子系统探针与基于环境的配置契约。

章节 相关页面

继续阅读本节完整说明和来源证据。

部署模式与运行时拓扑

OpenViking 提供三类运行时形态,可按场景组合使用:

  • 嵌入式客户端:使用 ov.OpenViking(path="./data") 直接初始化本地存储与解析管线,适合单进程演示与本地开发(资料来源:examples/basic-usage/README.md:1-60)。
  • HTTP 客户端ov.SyncHTTPClient(url="http://localhost:1933") 将 OpenViking Server 作为远端依赖,便于多端共享同一份向量与资源库;启用鉴权时需传入 user_key资料来源:examples/basic-usage/README.md:1-60)。
  • 独立服务 + Web Studio:通过 openviking-server --with-bot 启动核心 API 与 /bot/v1/* 代理;Web Studio 仅消费 HTTP 接口,不内嵌存储或 VikingBot 运行时(资料来源:web-studio/README.md:1-80)。

部署核心原则是进程职责分离。Web Studio 不直接持有 OpenViking 存储、索引、检索、任务队列或 VikingBot 运行时,必须连接到一个独立运行的 OpenViking Server(资料来源:web-studio/README.md:1-30)。CLI 同理:@openviking/cli 客户端按 darwin-arm64、darwin-x64、linux-x64 等平台分包,不在本机内嵌服务端(资料来源:npm/cli/README.md:1-60)。

flowchart LR
  User[User / Agent] --> Studio[Web Studio / CLI]
  Studio -->|HTTP| Server[OpenViking Server]
  Server --> AGFS[(AGFS Storage)]
  Server --> Queue[SemanticQueue]
  Server --> BotProxy[/bot/v1/*/]
  BotProxy --> VikingBot[VikingBot Runtime]
  VikingBot --> Skills[bot/workspace/skills]

OpenClaw 插件采用纯远程模式baseUrlapiKey 来自插件配置,不在本机拉起子进程;本地文件先经 /api/v1/resources/temp_upload 上传,目录会被纯 JS 实现的 zip 工具打包后再上传(资料来源:examples/openclaw-plugin/README.md:1-40)。Codex 与 Claude Code 的 Memory 插件同样以 HTTP 客户端形态接入,并直接消费 /mcp 流式端点(资料来源:examples/codex-memory-plugin/README.md:1-20)。

可观测性入口与健康契约

OpenViking 的可观测性以轻量探针 + 异步任务追踪为主,关键入口包括:

探针 / 端点用途来源
GET /health核心服务存活检查web-studio/README.md
GET /ready依赖就绪检查web-studio/README.md
GET /bot/v1/healthVikingBot 子系统探针web-studio/README.md
task 子命令(CLI)跟踪异步处理任务npm/cli/README.md
status 子命令查看服务端组件状态npm/cli/README.md

部署 Web Studio 前必须确认 /bot/v1/health 返回健康;即使核心 API 可用,若 Bot 代理异常,Sessions 页面也无法提供真实对话(资料来源:web-studio/README.md:1-80)。Bot 子系统的具体探活路径还包括 vikingbot_url 字段指向的 /bot/v1/health,可在狼人杀 Demo 的故障排查章节中看到(资料来源:bot/demo/werewolf/README.md:1-20)。

异步处理的可观测性集中在 SemanticQueueSemanticProcessor:解析器在 V5.0 架构下将临时目录物理搬运到 AGFS 后才入队语义生成,LLM 调用统一在 SemanticProcessor 中异步消费;这意味着 add_resource 快速返回后,需要通过任务通道观察摘要/概览的生成进度(资料来源:openviking/parse/parsers/README.md:1-80)。Code 仓库解析同样遵循“物理搬运 + 异步理解”的两段式流程(资料来源:openviking/parse/parsers/code/README.md:1-60)。

会话与记忆路径在 Claude Code 插件中可通过环境变量精细化控制,例如 OPENVIKING_TIMEOUT_MSOPENVIKING_CAPTURE_TIMEOUT_MSOPENVIKING_COMMIT_TOKEN_THRESHOLD 等,便于在 StopPreCompactSessionStart 等钩子中观测延迟与提交阈值(资料来源:examples/claude-code-memory-plugin/README.md:1-40)。

社区热点议题跟踪

当前社区围绕完整性、成本与兼容性三类议题集中反馈:

  • Agent 完整性标准(Issue #394):建议在 OpenViking 中引入“零知识上下文证明”(Zero-Knowledge Context Proofs),确保长程记忆中上下文数据库的交付完整性,避免 Agent 在持久化上下文上被静默篡改(社区讨论:#394)。
  • Token 消耗与成本优化(Issue #744):社区汇总了 Embedding、API 调用与解析阶段 Token 消耗相关的多个问题,python-sdk 已发布 v0.1.2 优化版本作为阶段性进展(社区讨论:#744)。
  • OpenClaw 兼容性问题(Issue #591):升级到 OpenClaw 2026.3.12memory-openviking 插件可能导致对话挂起;该问题并非 OpenViking 服务端 Bug,而是插件侧的兼容回归(社区讨论:#591)。
  • 贡献者地图(Issue #1082):项目方建立了模块级维护者与 PR 评审入口索引,便于贡献者按模块定位 reviewer(社区讨论:#1082)。
  • Memex 个人知识助手 Demo(Issue #55):社区提议构建 CLI 形态的端到端示例,覆盖资源导入、检索、会话与记忆全链路(社区讨论:#55)。

故障排查与最佳实践

常见的部署与运行故障集中在三类:

  1. Bot 子系统不可用:Web Studio Sessions 页空白或返回 503 时,应先确认 openviking-server --with-bot 是否启动,并验证 /bot/v1/health 返回正常(资料来源:web-studio/README.md:1-80)。
  2. 异步任务堆积taskstatus 是首要排查命令;若资源长时间停留在临时目录,应检查 SemanticQueue 与 LLM Provider 配额(资料来源:npm/cli/README.md:1-60)。
  3. 插件侧兼容问题:OpenClaw 升级后出现对话挂起,建议先在插件侧降级或绕过(OPENVIKING_BYPASS_SESSION=1),再观察服务端是否仍然异常(资料来源:examples/claude-code-memory-plugin/README.md:1-40社区讨论:#591)。

运维建议:

  • 跨域部署时,在 ov.conf 中配置 server.cors_origins 并设置 server.root_api_key 用于管理面访问(资料来源:web-studio/README.md:1-80)。
  • 通过 VITE_OV_BASE_URL 在构建期注入 API 起源,运行时仍允许用户在连接对话框中覆盖(资料来源:web-studio/README.md:1-80)。
  • 媒体与代码资源的上传建议使用 temp_upload 端点,避免将本地路径直接发送到服务端(资料来源:examples/openclaw-plugin/README.md:1-40)。

See Also

  • OpenViking 整体架构
  • 存储系统设计
  • 上下文提取流程
  • 配置指南
  • CLI 命令参考
  • Web Studio 部署

来源:https://github.com/volcengine/OpenViking / 项目说明书

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险,不把社区讨论只当作装饰信息。

high 来源证据:Bug: openviking-memory.ts autoRecall has three critical bugs (mode:auto, input.parts vs output.parts, config scope)

可能增加新用户试用和生产接入成本。

high 来源证据:[Bug] Semantic queue poison: `_process_memory_directory` raises on a memory file URI and re-enqueues forever

可能增加新用户试用和生产接入成本。

medium 来源证据:[Question]: 请问一下openclaw接入微信渠道,openviking能否支持多个微信用户的记忆隔离和召回

可能增加新用户试用和生产接入成本。

medium 能力判断依赖假设

假设不成立时,用户拿不到承诺的能力。

Pitfall Log / 踩坑日志

项目:volcengine/OpenViking

摘要:发现 10 个潜在踩坑项,其中 2 个为 high/blocking;最高优先级:配置坑 - 来源证据:Bug: openviking-memory.ts autoRecall has three critical bugs (mode:auto, input.parts vs output.parts, config scope)。

1. 配置坑 · 来源证据:Bug: openviking-memory.ts autoRecall has three critical bugs (mode:auto, input.parts vs output.parts, config scope)

  • 严重度:high
  • 证据强度:source_linked
  • 发现:GitHub 社区证据显示该项目存在一个配置相关的待验证问题:Bug: openviking-memory.ts autoRecall has three critical bugs (mode:auto, input.parts vs output.parts, config scope)
  • 对用户的影响:可能增加新用户试用和生产接入成本。
  • 证据:community_evidence:github | https://github.com/volcengine/OpenViking/issues/2757 | 来源类型 github_issue 暴露的待验证使用条件。

2. 配置坑 · 来源证据:[Bug] Semantic queue poison: `_process_memory_directory` raises on a memory file URI and re-enqueues forever

  • 严重度:high
  • 证据强度:source_linked
  • 发现:GitHub 社区证据显示该项目存在一个配置相关的待验证问题:[Bug] Semantic queue poison: _process_memory_directory raises on a memory file URI and re-enqueues forever
  • 对用户的影响:可能增加新用户试用和生产接入成本。
  • 证据:community_evidence:github | https://github.com/volcengine/OpenViking/issues/2734 | 来源讨论提到 python 相关条件,需在安装/试用前复核。

3. 配置坑 · 来源证据:[Question]: 请问一下openclaw接入微信渠道,openviking能否支持多个微信用户的记忆隔离和召回

  • 严重度:medium
  • 证据强度:source_linked
  • 发现:GitHub 社区证据显示该项目存在一个配置相关的待验证问题:[Question]: 请问一下openclaw接入微信渠道,openviking能否支持多个微信用户的记忆隔离和召回
  • 对用户的影响:可能增加新用户试用和生产接入成本。
  • 证据:community_evidence:github | https://github.com/volcengine/OpenViking/issues/2761 | 来源讨论提到 python 相关条件,需在安装/试用前复核。

4. 能力坑 · 能力判断依赖假设

  • 严重度:medium
  • 证据强度:source_linked
  • 发现:README/documentation is current enough for a first validation pass.
  • 对用户的影响:假设不成立时,用户拿不到承诺的能力。
  • 证据:capability.assumptions | https://github.com/volcengine/OpenViking | README/documentation is current enough for a first validation pass.

5. 运行坑 · 运行可能依赖外部服务

  • 严重度:medium
  • 证据强度:source_linked
  • 发现:项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
  • 对用户的影响:本地安装成功不等于能力可用,外部服务不可用会阻断体验。
  • 证据:packet_text.keyword_scan | https://github.com/volcengine/OpenViking | matched external service / cloud / webhook / database keyword

6. 维护坑 · 维护活跃度未知

  • 严重度:medium
  • 证据强度:source_linked
  • 发现:未记录 last_activity_observed。
  • 对用户的影响:新项目、停更项目和活跃项目会被混在一起,推荐信任度下降。
  • 证据:evidence.maintainer_signals | https://github.com/volcengine/OpenViking | last_activity_observed missing
  • 严重度:medium
  • 证据强度:source_linked
  • 发现:no_demo
  • 证据:downstream_validation.risk_items | https://github.com/volcengine/OpenViking | no_demo; severity=medium

8. 安全/权限坑 · 存在评分风险

  • 严重度:medium
  • 证据强度:source_linked
  • 发现:no_demo
  • 对用户的影响:风险会影响是否适合普通用户安装。
  • 证据:risks.scoring_risks | https://github.com/volcengine/OpenViking | no_demo; severity=medium

9. 维护坑 · issue/PR 响应质量未知

  • 严重度:low
  • 证据强度:source_linked
  • 发现:issue_or_pr_quality=unknown。
  • 对用户的影响:用户无法判断遇到问题后是否有人维护。
  • 证据:evidence.maintainer_signals | https://github.com/volcengine/OpenViking | issue_or_pr_quality=unknown

10. 维护坑 · 发布节奏不明确

  • 严重度:low
  • 证据强度:source_linked
  • 发现:release_recency=unknown。
  • 对用户的影响:安装命令和文档可能落后于代码,用户踩坑概率升高。
  • 证据:evidence.maintainer_signals | https://github.com/volcengine/OpenViking | release_recency=unknown

来源:Doramagic 发现、验证与编译记录