OpenViking OpenCode 统一插件安装与使用指南MCP 工具、长期记忆与生命周期同步【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenVikingOpenViking 为 AI Agent 提供了自进化的上下文数据库而 OpenCode 用户可以通过仓库中唯一持续维护的 examples/opencode-plugin 示例把 OpenViking 的 memory、resources 与 code context 能力以 stdio MCP proxy 的方式接入 OpenCode。读完本文你将掌握该插件的两种安装方式发布包与源码、完整配置项语义、底层生命周期 hooks 工作原理、全部openviking_*MCP 工具的使用建议以及常见故障的排查路径。插件定位与能力概览这是当前仓库中唯一继续维护的 OpenCode 插件示例它取代了以往索引仓库提示注入 长期记忆分开的两个示例。与旧方案的关键差异在于该插件不再安装skills/openviking/SKILL.md也不要求 agent 使用ov命令——模型工具面完全由与 Claude Code、Codex 记忆插件同款的 stdio MCP proxy 提供。从 README.md 与 index.mjs 的声明可以看到插件提供以下核心能力向 system prompt 注入已索引的viking://resources/仓库上下文暴露与 Claude Code / Codex 记忆插件一致的 OpenViking MCP 工具集将每个 OpenCode session 映射为一个 OpenViking session捕获 user/assistant 文本消息写入 OpenViking在生命周期边界session 删除、压缩、插件退出执行 commit触发记忆提取自动 recall 相关记忆并以隐藏的 synthetic context 注入当前用户消息拦截 agent 误用 OpenCode 本地read/glob/grep访问viking://URI 的行为引导其改用 MCP 工具。值得注意的是插件的工具面来自 OpenViking 的 MCP endpoint目录下有意不提供skills/openviking/SKILL.md见 README.md。前置条件安装前需要准备OpenCode插件目标宿主OpenViking HTTP Server数据面与 MCP 后端Node.js 18如果服务端启用了认证需要可用的OpenViking API Key建议先启动 OpenViking 服务端openviking-server --config ~/.openviking/ov.conf然后检查服务健康状态curl http://localhost:1933/health插件默认连接的 endpoint 为http://127.0.0.1:1933见 lib/config.mjs 的DEFAULT_CONFIG。README 还额外提示该插件要求 OpenViking server 支持viking://~home-aliasrecall 通过viking://~/memories与viking://~/skills定位调用者自身上下文空间新版 server 会拒绝无 uid 的viking://user/memories简写。安装方式一发布包安装普通用户推荐通过 OpenCode 的 package plugin 机制启用。npm 发布包名为openviking/opencode-plugin当前示例仓库内版本为0.2.4见 package.json发布前可通过npm view openviking/opencode-plugin version核对版本。在 OpenCode 的配置~/.config/opencode/opencode.json中声明插件{ plugin: [openviking/opencode-plugin] }npm 包方式安装时插件会通过package.json直接加载index.mjs无需额外 wrapper。安装方式二源码安装用于开发调试或 PR 测试。OpenCode 推荐插件目录为~/.config/opencode/plugins在仓库根目录执行以下复制命令mkdir -p ~/.config/opencode/plugins/openviking cp examples/opencode-plugin/wrappers/openviking.js ~/.config/opencode/plugins/openviking.js cp examples/opencode-plugin/index.mjs examples/opencode-plugin/package.json ~/.config/opencode/plugins/openviking/ cp -r examples/opencode-plugin/lib ~/.config/opencode/plugins/openviking/ cp -r examples/opencode-plugin/servers ~/.config/opencode/plugins/openviking/安装后的目录结构应类似~/.config/opencode/plugins/ ├── openviking.js └── openviking/ ├── index.mjs ├── package.json ├── lib/ └── servers/顶层openviking.js只负责把 OpenCode 能发现的一级.js入口转发到插件目录export { OpenVikingPlugin, default } from ./openviking/index.mjs这个 wrapper 仅用于上述源码安装目录结构。npm 包安装会通过package.json直接加载index.mjs。源码安装请使用.jswrapper因为 OpenCode 的本地插件扫描器会扫描 JavaScript/TypeScript 插件文件。如果你使用 npm 包方式安装也可以把examples/opencode-plugin整体当作一个普通 OpenCode 插件包来使用。配置创建用户级配置文件~/.config/opencode/openviking-config.json示例配置{ enabled: true, mcp: { enabled: true }, timeoutMs: 30000, repoContext: { enabled: true, cacheTtlMs: 60000 }, autoRecall: { enabled: true, limit: 6, scoreThreshold: 0.35, maxContentChars: 500, preferAbstract: true, tokenBudget: 2000, minQueryLength: 3 }, commitTokenThreshold: 20000, commitKeepRecentCount: 10, profileTokenBudget: 10000, resumeContextBudget: 32000 }关键配置项语义与默认值结合 lib/config.mjs 的DEFAULT_CONFIG与normalizeConfig各配置项的真实默认值与取值边界如下配置项默认值归一化范围说明endpointhttp://127.0.0.1:1933—OpenViking 服务地址尾部斜杠会被去除timeoutMs300001000300000HTTP 请求超时毫秒mcp.enabledtrue—是否注册附带的 MCP serverrepoContext.enabledtrue—是否注入已索引仓库提示repoContext.cacheTtlMs6000010003600000仓库列表缓存 TTLautoRecall.enabledtrue—是否自动 recall 并注入上下文autoRecall.limit10150配额缩放输入见下文说明autoRecall.scoreThreshold0.3501召回相似度阈值autoRecall.maxContentChars5001005000每条召回内容最大字符数autoRecall.tokenBudget200020050000recall 注入 token 预算autoRecall.minQueryLength3164触发 recall 的最小查询长度captureModesemanticsemantic/keyword消息捕获模式captureMaxLength24000200100000捕获文本最大长度captureAssistantTurnstrue—是否捕获 assistant 回合commitTokenThreshold20000≥1000pending token 达到该值触发 commitcommitKeepRecentCount10≥0commit 时保留的最近消息数profileTokenBudget10000≥500用户画像注入 token 预算resumeContextBudget32000≥1024session 归档恢复上下文预算runtime.dataDir~/.config/opencode/openviking/—运行时文件目录关于autoRecall.limit有一个重要细节它是遗留的配额缩放输入不是最终结果上限。显式设置为 1 到 5 时有效总配额仍为 6因为六个 coding 分类会各保留一个检索槽位。如需精确的类别配额上限应直接使用服务端 Context 的quotas参数。认证与身份配置推荐通过环境变量提供 API Key而不是写入配置文件export OPENVIKING_API_KEYyour-api-key-hereAPI Key 会从环境变量或~/.openviking/ovcli.conf读取并由 hooks 和 MCP proxy 作为Authorization: Bearer ...头发送。account和user是 trusted mode 身份头会作为X-OpenViking-Account、X-OpenViking-User发送使用 user/admin API key 的 API_KEY mode 时应留空。peerId会作为X-OpenViking-Actor-Peer用于数据面的 memory/resource 请求捕获 session message 时仍写入 bodypeer_id需要 peer 维度路由时请显式配置。OPENVIKING_API_KEY、OPENVIKING_ACCOUNT、OPENVIKING_USER、OPENVIKING_PEER_ID的优先级高于openviking-config.json中的同名配置见 lib/config.mjs 的loadConfig环境变量在文件配置之后应用。高级场景可以用OPENVIKING_PLUGIN_CONFIG指向其他配置文件路径该变量优先级最高。配置查找路径与 peer 推导从 lib/config.mjs 的getConfigPaths可以看出配置文件按以下顺序查找第一个存在的生效OPENVIKING_PLUGIN_CONFIG指向的路径项目目录下的.opencode/openviking-config.json~/.config/opencode/openviking-config.json插件目录下的openviking-config.json。默认情况下插件会从项目目录的 git 身份推导 peer优先使用归一化的originURL否则使用仓库根路径。例如gitgithub.com:volcengine/OpenViking.git会变成github.com-volcengine-openviking路径回退则遵循非字母数字字符替换为-的旧规则。推导直接读取.git目录因此不需要安装 git 二进制。插件不读取工作区的.openviking/config.json其中的peer.id不生效。可通过配置peerId或OPENVIKING_PEER_ID覆盖推导结果或设置workspacePeerfalse/OPENVIKING_WORKSPACE_PEER0完全不发送 peer。仅 Hooks 模式如果其他 MCP server 已经提供 OpenViking可以关闭本插件附带的 MCP 注册同时保留生命周期 hooks{ mcp: { enabled: false } }repository context、自动 recall、消息 capture 和生命周期 commit 会继续工作也不会添加或覆盖 OpenCode 的mcp.openviking配置。从 index.mjs 的confighook 实现可以看到当mcp.enabled为 false 时会跳过injectOpenVikingMcpConfig仅记录 hook-only mode。插件工作原理OpenCode hooks 与 MCP 注册理解插件的底层机制有助于排查问题。插件入口 index.mjs 导出一个OpenVikingPlugin({ client, directory })工厂函数返回一组 OpenCode hooksHook作用config向 OpenCode 配置注入mcp.openviking条目指向本地 stdio MCP proxyevent处理session.created等生命周期事件并刷新仓库上下文缓存tool.execute.beforeviking-uri-guard拦截本地文件系统工具对viking://URI 的访问experimental.chat.system.transform把已索引的 OpenViking 仓库列表追加到 system promptchat.message注入 session 上下文与自动 recall 的 synthetic contextexperimental.session.compactingsession 压缩时 flush 并 commitdispose插件退出时 flush 所有 session 并 commitMCP proxystdio 到 streamable-HTTPOpenCode 将插件视为本地 MCP server通过node servers/mcp-proxy.mjs启动见 lib/mcp-config.mjs 的createOpenVikingMcpConfig默认timeout: 15000。servers/mcp-proxy.mjs 是一个stdio → streamable-HTTP 代理它读取与 hooks 相同的 OpenViking 凭据来源将 JSON-RPC 请求转发到服务端的/mcpendpoint并保持 stdout 协议纯净避免日志污染 MCP 通道。Session 映射与持久化lib/memory-session.mjs 实现 session 生命周期管理每个 OpenCode session 通过deriveHarnessSessionId(oc-, opencodeSessionId)派生出稳定的 OpenViking session id子 agent 会话带__subagent-标记session 状态持久化到openviking-session-state.jsonv2 格式写入采用临时文件 rename 的原子方式并通过 promise 队列串行化避免并发保存竞态消息捕获支持semantic与keyword两种模式捕获前会依据captureMaxLength、captureToolMaxChars、captureAssistantTurns等约束过滤发送失败时消息进入 pending queuelib/shared/pending-queue.mjs服务恢复后自动重放replayPending失败重试遵循retryable判定commit 触发时机包括生命周期边界session 删除/错误/压缩、插件 dispose、pending_tokens超过commitTokenThreshold阈值、显式工具调用。自动 recall 与 session 注入lib/memory-recall.mjs 在chat.message时执行提取当前用户文本过滤 synthetic/ignored 部分若长度低于minQueryLength则跳过先探测/health再通过服务端 context face/api/v1/search/search且modecontext构建 recall 块以synthetic: true的 text part 前置注入输出。recall 请求携带映射后的 OpenViking session id——正是这个映射 session 开启了服务端 query expansion 与跨轮次去重台账。lib/session-inject.mjs 则在 session 开始时注入两类上下文用户画像块受profileTokenBudget约束与最新 session 归档概览/api/v1/sessions/{id}/context?token_budget...受resumeContextBudget约束。两者都以openviking-context标记包裹注入逻辑仅在首个消息执行一次。仓库上下文注入lib/repo-context.mjs 调用/api/v1/fs/ls?uriviking://resources/recursivefalsesimplefalse获取已索引仓库列表按cacheTtlMs缓存并通过experimental.chat.system.transform将格式化的仓库清单含 abstract/overview追加到 system prompt指导 agent 优先使用openviking_*工具回答仓库相关问题。验证修改插件或 OpenViking 配置后需要重启 OpenCode。进入新的 OpenCode session 后可以让 agent 浏览 OpenViking memory或搜索一个已索引的资源。插件应暴露 OpenViking MCP serverOpenCode 中的工具名会带openviking_前缀openviking_search、openviking_findopenviking_read、openviking_list、openviking_tree、openviking_grep、openviking_globopenviking_remember、openviking_write、openviking_edit、openviking_add_resourceopenviking_list_watches、openviking_cancel_watch、openviking_forget、openviking_health如果行为异常先查看运行时文件ls ~/.config/opencode/openviking/ tail -n 100 ~/.config/opencode/openviking/openviking-memory.log如果使用本地 server也确认 OpenViking 可访问curl http://localhost:1933/health可用 MCP 工具插件会通过 OpenCode config 注册 OpenViking stdio MCP proxy。服务端实际返回的tools/list是最终工具清单——proxy 透传服务端真实工具列表插件本身不维护独立的原生工具清单见 README.md。当前 OpenViking server 暴露工具功能openviking_search跨 memories/resources/skills 的深度语义检索使用modecontext获取面向当前任务、可直接注入的平衡上下文openviking_find快速语义检索openviking_remember存储重要事实或决策供记忆提取openviking_read读取一个或多个viking://文件openviking_list列出viking://目录openviking_tree展示viking://目录树openviking_grep精确文本或正则搜索openviking_globglob 文件匹配openviking_write创建、覆盖或追加viking://文件openviking_edit对viking://文件做精确字符串替换openviking_add_resource添加 URL、本地文件、sitemap 或 feedopenviking_forget在用户明确确认后删除viking://URIopenviking_list_watches/openviking_cancel_watch查看或取消资源 watchopenviking_health检查 OpenViking server 健康状态使用建议概念性问题用openviking_search精确符号、函数名、类名、报错字符串用openviking_grep枚举文件用openviking_glob读取内容用openviking_read探索目录结构用openviking_list删除前必须先获得用户明确确认再调用openviking_forget如果 agent 误用 OpenCode 本地read、glob、grep工具访问viking://URI插件会阻止这次本地文件系统调用并提示改用 MCP 工具这就是viking-uri-guard的职责见 lib/viking-uri-guard.mjs。openviking_add_resource本地文件openviking_add_resource支持三类输入远端http(s)URL直接调用/api/v1/resources本地文件路径先调用/api/v1/resources/temp_upload再用返回的temp_file_id添加资源file://URL按本地文件处理。相对路径会按 OpenCode 当前项目目录解析。示例openviking_add_resource(pathhttps://example.com/spec.md, toviking://resources/spec) openviking_add_resource(path./docs/notes.md, toviking://resources/notes.md) openviking_add_resource(pathfile:///home/alice/project/notes.md, descriptionproject notes)当前仍不支持本地目录自动打 zip 上传传入目录时会返回明确错误。运行时文件插件默认会把运行时文件写入~/.config/opencode/openviking/可能包含openviking-memory.log日志文件openviking-session-state.jsonsession 映射与捕获状态v2 格式。可以通过配置里的runtime.dataDir修改这个目录见 lib/config.mjs 的resolveDataDir。这些是本地运行时文件不建议提交到版本库。故障排查问题排查方向插件没有加载package 安装检查~/.config/opencode/opencode.json是否包含openviking/opencode-plugin源码安装检查~/.config/opencode/plugins/openviking.js是否存在MCP tools 连到了错误的 server检查~/.openviking/ovcli.conf或用OPENVIKING_*环境变量 /OPENVIKING_PLUGIN_CONFIG指向正确配置OpenViking 返回 401 / 403检查OPENVIKING_API_KEYtrusted-mode 部署还要检查OPENVIKING_ACCOUNT和OPENVIKING_USERrecall 为空确认 OpenViking 中已有 memories/resources并且autoRecall.enabled为true同时检查查询长度是否低于minQueryLength或 server 的/health是否可达本地openviking_add_resource失败传入文件路径而不是目录目前还不支持自动上传本地目录依赖凭据字段提示 deprecated运行node scripts/setup.mjs迁移到ovcli.conf插件启动时若检测到遗留凭据会通过 toast 提示见 index.mjs测试与进一步阅读插件自带完整的 Node 测试套件tests/ 与 servers/mcp-proxy.test.mjs覆盖配置加载、MCP 配置注入、自动 recall、session 生命周期、日志与viking://URI 拦截等行为可在仓库内通过npm test运行。如需深入源码建议按以下顺序阅读index.mjs插件入口与 hooks 注册lib/config.mjs默认配置、归一化范围与环境变量lib/memory-session.mjssession 映射、捕获、pending 队列与 commit 策略lib/memory-recall.mjs自动 recall 与 synthetic context 注入servers/mcp-proxy.mjsstdio → streamable-HTTP MCP 代理。英文原版文档见 INSTALL.md功能综述见 README.md。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考