Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

11.9 KB
Raw Blame

安装 OpenViking OpenCode 统一插件

这个插件新增了一个面向 OpenCode 的统一 OpenViking 插件:

  • 面向 memory、resources 和 code context 的 OpenViking MCP 工具
  • 长期记忆、session 同步、生命周期边界 commit、自动 recall

这是仓库中唯一继续维护的 OpenCode 插件示例。这个插件不再安装 skills/openviking/SKILL.md,也不要求 agent 使用 ov 命令。模型工具由 Claude Code 和 Codex 记忆插件同款的 stdio MCP proxy 提供。

前置条件

需要先准备:

  • OpenCode 1.15.7+ 或 OpenCode 2.0.15+
  • OpenViking HTTP Server
  • Node.js 18+
  • 如果服务端启用了认证,需要可用的 OpenViking API Key

建议先启动 OpenViking:

openviking-server --config ~/.openviking/ov.conf

检查服务:

curl http://localhost:1933/health

安装方式一:一键安装(推荐)

OpenCode 与其他记忆插件共用同一个安装器。它会询问要安装的宿主和 OpenViking 凭据:

curl -fsSL https://openviking.ai/install | bash

安装器会把插件作为本地文件插件复制到 ~/.config/opencode/plugins/,把 openviking MCP server 条目写进 ~/.config/opencode/opencode.json,并配置 ~/.openviking/ovcli.conf。

安装方式二:发布包安装

也可以通过 OpenCode 的 package plugin 机制启用:

{
  "plugin": ["@openviking/opencode-plugin"]
}

这份 plugin 配置同时兼容 v1 和 v2;v2 会在加载时规范化为原生的 plugins,无需手工迁移配置。

安装方式三:源码安装

用于开发调试或 PR 测试。OpenCode 推荐插件目录:

~/.config/opencode/plugins

在仓库根目录执行:

node examples/memory-plugin-shared/sync.mjs
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/

sync.mjs 会生成 lib/shared/,插件和 MCP 代理都从这里 import 共享模块。这个目录不在 git 里,所以复制前要先运行;之后每次 git pull 也要重新运行再复制。

安装后结构应类似:

~/.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。 源码安装请使用 .js wrapper;OpenCode 的本地插件扫描器会发现 JavaScript/TypeScript 插件文件。

如果你使用 npm 包方式安装,也可以将 examples/opencode-plugin 作为一个普通 OpenCode 插件包使用。

配置

行为旋钮写在共享的客户端配置文件里:

~/.openviking/ovcli.conf

示例配置:

{
  "url": "http://127.0.0.1:1933",
  "api_key": "your-api-key-here",
  "plugin": {
    "recallLimit": 6,
    "opencode": {
      "enabled": true,
      "mcpEnabled": true,
      "timeoutMs": 30000,
      "repoContext": true,
      "repoContextCacheTtlMs": 60000,
      "autoRecall": true,
      "scoreThreshold": 0.35,
      "recallMaxContentChars": 500,
      "recallPreferAbstract": true,
      "recallTokenBudget": 2000,
      "minQueryLength": 3,
      "commitTokenThreshold": 20000,
      "profileTokenBudget": 10000,
      "skillCatalog": true,
      "skillCatalogTokenBudget": 1200,
      "resumeContextBudget": 32000
    }
  }
}

plugin 里的键对所有 harness 生效;plugin.opencode 里的键只对本插件生效,并覆盖前者。解析顺序是 OPENVIKING_* 环境变量 → 工作区的 .openviking/config.json、.openviking/config.local.json 和本机 registry 条目 → plugin.opencode → plugin → 内置默认值。每个旋钮的类型、默认值、取值范围、环境变量名和兼容的旧拼写都声明在 examples/memory-plugin-shared/lib/config-schema.mjs。

recallLimit 是遗留的配额缩放输入,不是最终结果上限。显式设置为 1 到 5 时,有效总配额仍为 6,因为六个 coding 分类会各保留一个检索槽位。

每个 session 的第一条消息会带上一个隐藏的 <openviking-context source="session-start"> 块,里面有你的 profile.md、preferences/ 和 entities/ 记忆索引,以及 <available-skills> skill 清单:先列你自己的 skill,再列 viking://agent/skills 下账号共享的 skill;共享 skill 与你自己的 skill 同名时不再列出。profileTokenBudget 只管 profile 和记忆索引,skill 清单有独立的预算 skillCatalogTokenBudget(默认 1200,环境变量 OPENVIKING_SKILL_CATALOG_TOKEN_BUDGET)。放不下描述时只列 skill 名,名字也列不全时末尾注明 ... +N more;连一个名字都放不下时,只写一行 skill 总数。设置 skillCatalog: false(OPENVIKING_SKILL_CATALOG=0)或把预算设为 0 即可关闭 skill 清单;没有 skill,或服务端没有 GET /api/v1/skills 接口时,这一块会直接省略。

推荐通过环境变量提供 API Key,而不是写入配置文件:

export OPENVIKING_API_KEY="your-api-key-here"

API key 会从环境变量或 ~/.openviking/ovcli.conf 读取,并由 hooks 和 MCP proxy 作为 Authorization: Bearer ... 发送。account 和 user 是 trusted mode 身份头,会作为 X-OpenViking-Account、X-OpenViking-User 发送;api_key 模式的服务端从 key 里取身份,插件在那里不发这两个头。 peerId 会作为 X-OpenViking-Actor-Peer 用于数据面的 memory/resource 请求;捕获 session message 时仍写入 body peer_id。需要 peer 维度路由时请显式配置。

OPENVIKING_API_KEY、OPENVIKING_ACCOUNT、OPENVIKING_USER、 OPENVIKING_PEER_ID 优先级高于 ovcli.conf 里的同名配置。

高级场景可以用 OPENVIKING_CLI_CONFIG_FILE 指向其他路径的 ovcli.conf。

仅 Hooks 模式

如果其他 MCP server 已经提供 OpenViking,可以关闭本插件附带的 MCP 注册,同时保留生命周期 hooks:

{
  "plugin": {
    "opencode": { "mcpEnabled": false }
  }
}

repository context、自动 recall、消息 capture 和生命周期 commit 会继续工作,也不会添加或覆盖 OpenCode 的 mcp.openviking 配置。

验证

修改插件或 OpenViking 配置后,需要重启 OpenCode。

进入新的 OpenCode session 后,可以让 agent 浏览 OpenViking memory,或搜索一个已索引的资源。插件应暴露 OpenViking MCP server,OpenCode 中的工具名会带 openviking_ 前缀:

  • openviking_search、openviking_find
  • openviking_read、openviking_download、openviking_list、openviking_tree、openviking_grep、openviking_glob
  • openviking_remember、openviking_write、openviking_edit、openviking_add_resource、openviking_add_skill
  • openviking_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 是最终工具清单;当前 OpenViking server 暴露:

  • openviking_search:跨 memories/resources/skills 的深度语义检索;使用 mode="context" 获取面向当前任务、可直接注入的平衡上下文
  • openviking_find:快速语义检索
  • openviking_remember:存储重要事实或决策,供记忆提取
  • openviking_read:读取一个或多个 viking:// 文件
  • openviking_download:获取一次性 URL,用 curl 下载文件原始字节
  • openviking_list:列出 viking:// 目录
  • openviking_tree:展示 viking:// 目录树
  • openviking_grep:精确文本或正则搜索
  • openviking_glob:glob 文件匹配
  • openviking_write:创建、覆盖或追加 viking:// 文件
  • openviking_edit:对 viking:// 文件做精确字符串替换
  • openviking_add_resource:添加 URL、本地文件、sitemap 或 feed
  • openviking_add_skill:用完整的 SKILL.md 文本(data)创建或替换 skill,或从 Git URL、本地 SKILL.md、skill 目录或 .zip(path)安装;传 target_uri="viking://agent/skills" 则共享给整个账号
  • openviking_forget:在用户明确确认后删除 viking:// URI
  • openviking_list_watches / openviking_cancel_watch:查看或取消资源 watch
  • openviking_health:检查 OpenViking server 健康状态

使用建议:

  • 概念性问题用 openviking_search
  • 精确符号、函数名、类名、报错字符串用 openviking_grep
  • 枚举文件用 openviking_glob
  • 读取内容用 openviking_read
  • 探索目录结构用 openviking_list
  • 照 <available-skills> 里的某个 skill 做事之前,先用 openviking_read 读它的 SKILL.md;创建、安装或共享 skill 用 openviking_add_skill
  • 删除前必须先获得用户明确确认,再调用 openviking_forget
  • 如果 agent 误用 OpenCode 本地 read、glob、grep 工具访问 viking:// URI,插件会阻止这次本地文件系统调用,并提示改用 MCP 工具。
  • bash 命令里带 viking:// URI 时照常执行,插件会在输出末尾附一段提示,建议改用 MCP 工具;URI 本来就是命令参数时,agent 可以忽略这段提示。

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(path="https://example.com/spec.md", to="viking://resources/spec")
openviking_add_resource(path="./docs/notes.md", to="viking://resources/notes.md")
openviking_add_resource(path="file:///home/alice/project/notes.md", description="project notes")

当前仍不支持本地目录自动打 zip 上传;传入目录时会返回明确错误。

运行时文件

插件默认会把运行时文件写入:

~/.config/opencode/openviking/

可能包含:

  • openviking-memory.log
  • openviking-session-state.json

可以通过 plugin.opencode 里的 dataDir 修改这个目录。

这些是本地运行时文件,不建议提交到版本库。

故障排查

问题 排查方向
插件没有加载 package 安装检查 ~/.config/opencode/opencode.json 是否包含 @openviking/opencode-plugin;源码安装检查 ~/.config/opencode/plugins/openviking.js 是否存在
加载时报找不到 lib/shared/*.mjs 源码复制前没有运行 sync.mjs。在仓库根目录运行 node examples/memory-plugin-shared/sync.mjs 后重新复制 lib/
MCP tools 连到了错误的 server 检查 ~/.openviking/ovcli.conf,或用 OPENVIKING_* 环境变量 / OPENVIKING_CLI_CONFIG_FILE 指向正确配置
OpenViking 返回 401 / 403 检查 OPENVIKING_API_KEY;trusted-mode 部署还要检查 OPENVIKING_ACCOUNT 和 OPENVIKING_USER
recall 为空 确认 OpenViking 中已有 memories/resources,并且 autoRecall 为 true
本地 openviking_add_resource 失败 传入文件路径而不是目录;目前还不支持自动上传本地目录