用 Agent Plugins 1.0 统一打包 OpenViking 记忆能力：一份插件包接入所有 AI 编码 Agent

用 Agent Plugins 1.0 统一打包 OpenViking 记忆能力：一份插件包接入所有 AI 编码 Agent

【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking

OpenViking 在仓库的agent-plugins/目录中提供了一份符合 Agent Plugins 1.0 规范的便携插件包：以plugin.json声明清单、skills/自动发现技能、mcp.json声明 MCP 服务器，让任何遵循该规范的客户端（Cursor、VS Code、Amazon/OpenAI 侧客户端等）以完全一致的方式加载同一份"语义长期记忆 + 上下文引擎"能力。读完本文，你将掌握该插件包的目录结构与真实清单内容、stdio 代理的传输原理与凭据解析链、模型驱动的记忆"召回—持久化"循环，以及如何运行一致性测试与参与开发。

Agent Plugins 1.0 是什么，为什么 OpenViking 需要它

Agent Plugins 1.0 是一种与厂商无关的打包格式，用于扩展 AI 编码 Agent。一个插件就是一个普通目录，包含三部分：

• plugin.json—— 清单（manifest），声明插件的名称、版本、作者、许可与关键字；
• skills/—— Agent Skills 目录，客户端自动发现其中的技能（Skill）；
• mcp.json—— 可选的 MCP 服务器声明。

对 OpenViking 而言，这意味着"一套包、多处复用"：不再为每个客户端各写一套集成代码，而是一份符合规范的包被所有客户端以相同方式加载。agent-plugins/就是这个包的实现。

包内结构：一个零 npm 依赖的目录

agent-plugins/ ├── plugin.json # Agent Plugins 1.0 清单（name: openviking） ├── mcp.json # 一个 stdio MCP 服务器："openviking" ├── servers/ │ ├── mcp-proxy.mjs # stdio -> streamable-HTTP 代理，转发到服务器的 /mcp │ ├── config.mjs, debug-log.mjs # 凭据 / 配置解析 │ └── shared/ # 由 examples/memory-plugin-shared/lib 生成 ├── skills/openviking-memory/SKILL.md # 教模型执行 recall + persist 循环 └── plugin.test.mjs # node --test 一致性检查

整个包零 npm 依赖：代理与测试只依赖 Node.js 标准库（全局fetch需要 Node 18+）。

清单plugin.json的真实内容

agent-plugins/plugin.json声明了插件身份与用途：

{ "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "openviking", "version": "0.1.0", "description": "Semantic long-term memory and context engine for coding agents. Recall prior knowledge with the find/search/read MCP tools and persist durable facts with remember/write, backed by an OpenViking server.", "author": { "name": "Volcano Engine" }, "license": "AGPL-3.0", "keywords": ["memory", "long-term-memory", "context-engine", "semantic-search", "mcp", "openviking"] }

MCP 服务器声明mcp.json的真实内容

agent-plugins/mcp.json声明了一个 stdio 类型的 MCP 服务器，客户端加载后会执行：

{ "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json", "mcpServers": { "openviking": { "type": "stdio", "command": "node", "args": ["${PLUGIN_ROOT}/servers/mcp-proxy.mjs"] } } }

注意${PLUGIN_ROOT}占位符：规范允许它在args、env、cwd中被客户端展开为插件根目录，而command必须是单个可执行 token（不允许含空格或占位符），这正是plugin.test.mjs会校验的规则之一（见下文"一致性测试"）。

安装：三步接入任意符合规范的客户端

1. 准备一个可达的 OpenViking 服务器。若还没有，参考 Quickstart；本地默认端点为http://127.0.0.1:1933。
2. 把符合 Agent Plugins 规范的客户端指向agent-plugins/目录。每个客户端有自己的安装命令或插件目录，请查阅其文档。加载时客户端会自动：
   • 从mcp.json注册名为openviking的 MCP 服务器，以 stdio 方式运行node <plugin>/servers/mcp-proxy.mjs；
   • 从skills/发现openviking-memory技能。
3. 配置凭据（见下节）并开始会话。模型即可获得find/search/read/list/grep/glob/remember/add_resource/forget/health工具，较新的服务器上还会多出tree/write/edit。

为什么用 stdio 代理而不是streamable-http入口

OpenViking 服务器本身就在/mcp提供 streamable HTTP 能力，但直接在mcp.json里写streamable-http入口无法做到可移植，原因有二：

1. 服务器 URL 因部署而异：对 A 用户是localhost，对 B 用户是远程端点，静态配置无法兼顾；
2. 规范禁止在静态headers中携带凭据：API Key 不能写死在mcp.json的 headers 里。

stdio 代理在运行时解决这两点：它从与ovCLI 相同的本地凭据源读取 URL 与 API Key（见下节），按请求注入，并将 JSON-RPC 原样转发到服务器的 streamable HTTP 端点。

传输层实现要点（源码级）

代理主体在agent-plugins/servers/mcp-proxy.mjs，其核心传输逻辑来自生成文件agent-plugins/servers/shared/mcp-proxy-core.mjs，值得注意的实现细节：

• 协议版本协商：代理始终以自身当前版本（默认2025-06-18）发送MCP-Protocol-Version头，initialize响应中若服务器协商了更低版本则降级——"绝不转发客户端未协商的版本号，否则严格的 upstream 会在协商开始前就以 HTTP 400 拒绝"（源码注释原意）。
• 会话管理与重连：代理跟踪Mcp-Session-Id，收到 400/404（会话失效）或 401/403（认证失败）时自动重新发起initialize并重放请求；认证失败时还会先检查凭据文件是否变化，变化则热重载后重连。
• 并发控制：通过信号量将并发请求限制为 16（MAX_CONCURRENT_REQUESTS），避免打爆上游。
• 错误映射：超时（AbortError）映射为-32004并提示"服务器可能仍在计算（rerank 可能较慢），可检查 /health 或调大OPENVIKING_TIMEOUT_MS"；认证失败映射为-32001并提示检查~/.openviking/ovcli.conf或OPENVIKING_API_KEY——两类错误被刻意区分，避免误诊。
• 协议洁净的 stdout：所有写入 stdout 的消息经串行队列（stdoutChain）输出，调试日志绝不污染协议流。
• 凭据热加载：代理快照被监视配置文件（mtime:size），变化时自动重载——这就是"改配置文件无需重启"的实现基础。

凭据解析链：与ovCLI 完全一致

代理的配置加载在agent-plugins/servers/config.mjs，优先级从高到低，与ovCLI 及其余 OpenViking 插件一致：

1. 环境变量：OPENVIKING_URL（或OPENVIKING_BASE_URL）、OPENVIKING_API_KEY（或OPENVIKING_BEARER_TOKEN，两者均以 Bearer 发送）、OPENVIKING_ACCOUNT、OPENVIKING_USER、OPENVIKING_PEER_ID；
2. ~/.openviking/ovcli.conf（url、api_key、account、user）——可用OPENVIKING_CLI_CONFIG_FILE覆盖路径；
3. ~/.openviking/ov.conf的server段（url，或host/port，以及root_api_key）——可用OPENVIKING_CONFIG_FILE覆盖路径；
4. 默认值：http://127.0.0.1:1933，无认证（本地模式）。

例如~/.openviking/ovcli.conf：

{ "url": "https://openviking.example.com", "api_key": "your-api-key" }

从源码看，baseUrl的推导还有两个细节：其一，0.0.0.0会被替换为127.0.0.1；其二，URL 末尾多余的斜杠会被去除（replace(/\/+$/, "")）。apiKey的解析顺序为OPENVIKING_BEARER_TOKEN→OPENVIKING_API_KEY→cliFile.api_key→server.root_api_key，空串兜底。

运行中的代理会感知配置文件变更而无需重启（通过监听配置文件的 mtime/size 快照）。调试相关环境变量：

• OPENVIKING_DEBUG=1：向~/.openviking/logs/agent-plugins.log写入 JSON Lines 日志（每条形如{ ts, hook, stage, data }或{ ts, hook, stage, error }），可用OPENVIKING_DEBUG_LOG覆盖日志路径；未开启时日志函数是零成本的 no-op；
• OPENVIKING_TIMEOUT_MS：调整默认 15s 的每请求超时（源码中下限被钳制为 1000ms）。

模型驱动的记忆循环：openviking-memory技能

由于 Agent Plugins 1.0 不包含 hooks，本包不做自动捕获与自动召回，而是通过agent-plugins/skills/openviking-memory/SKILL.md教会模型用 MCP 工具自己驱动"召回—持久化"整个循环。技能的核心工具集（所有受支持部署上均可用）：

• 召回：find、search、read、list、grep、glob
• 持久化：remember、add_resource
• 维护：forget、health

部分部署还会注册可选工具tree、write、edit、list_watches、cancel_watch——是否注册取决于服务器版本与托管模式（托管云会裁掉部分工具），使用前应先查看会话中已注册的工具列表，详见 references/optional-tools.md；绝不调用未注册的工具，也不得回退到裸 HTTP。若会话中完全没有 OpenViking 工具，则继续执行、不使用记忆。

任务开始时：召回（Recall）

1. 先判断该请求是否值得检索：可执行或多步工作、涉及可能见过的系统、故障恢复——这些都该检索；闲聊与一次性琐碎问题跳过。
2. 从"任务目标、领域对象、预期操作、约束"构建一条简洁查询；失败恢复时把失败操作与错误信息中稳定的部分一并放入查询。
3. 调用find（快速、带排序的结果：URI + 摘要 + 分数），limit取 5~10；需要更深意图分析时用search，或使用search配合mode="context"让服务器组装受 token 预算约束的上下文块。列表模式下用target_uri限定范围，例如viking://~/memories/experiences检索既往任务经验。
4. 按"任务与环境契合度"而非标题相似度评判结果，read一到三个最可能改变执行方式的精确文件 URI，忽略.abstract.md、.overview.md、.relations.json等 sidecar 文件。
5. 若无相关结果则不带记忆继续；只有当执行因全新原因失败时，才做最多一次聚焦的补充检索。

技能还明确了优先级规则：系统与开发者指令 > 当前用户请求 > 当前环境与工具证据 > 记忆。记忆始终是建议性的——命令、路径、版本必须对照当前任务验证，既往成功绝不授权现在的破坏性操作。

工作期间与之后：持久化（Persist）

由于没有自动捕获，不主动存储就丢失。遇到值得保留的内容要在同一会话内持久化：

• remember(messages)—— 默认方式。传入关键对话或简短事实摘要（带 role 标记的消息），由服务器自行提取并归档记忆（偏好、实体、事件、经验）。适合用户说"记住这个"、陈述长期偏好或决策、出现来之不易的经验教训（根因、可行流程、环境怪癖）时。
• add_resource—— 导入外部文档或 URL 作为可检索资源。
• 需要在已知位置写入精确文档时（自己用户根目录viking://~/下的精修笔记，或viking://resources/下的共享参考资料），可选工具write/edit更合适；若未注册则回退到remember。

该存什么：稳定偏好与约定、环境事实、带理由的决策、可复用的流程或修复。不该存什么：密钥与凭据、瞬时状态、猜测、整段对话转储——存结论，不存滚动记录。

示例：修复一次失败的部署

1. find，查询deployment image pull failure private registry，target_uri: "viking://~/memories/experiences"；
2. read最相关的经验 URI，在应用其步骤前对照当前集群核对其假设；
3. 修复问题并验证线上结果；
4. remember一段根因与可用修复的简短摘要，供下次会话召回。

可选工具速查

references/optional-tools.md 给出了可用性矩阵：

托管云是无状态多实例服务，因此账户级有状态工具（list_watches、cancel_watch）即使底层版本存在也会被裁掉。

• tree(uri, level_limit?)：比list更深一层的目录树，用于在不熟悉的范围内先定位再决定read什么；单个已知目录优先用更廉价的list。
• write(uri, content, mode?)/edit(uri, ...)：在已知 URI 上做精确文档持久化。write覆盖、追加或新建文件（新建要求父目录已存在）；edit对已有文件做定向字符串替换，优先于整文件重写，若本地副本可能过期需先重新read。
• list_watches()/cancel_watch(to_uri)：管理add_resource带 watch 间隔创建的自动刷新订阅（仅私有/自托管）。cancel_watch是破坏性操作，只处理用户明确要求管理的 watch。

边界：hooks 被刻意排除，何时该选专用插件

Agent Plugins 1.0 只覆盖 skills 与 MCP 服务器——hooks、commands、agents 被规范刻意排除在外，因为它们在各个客户端间的语义差异太大。因此本包是可移植的"召回 + 写入"表面，由模型驱动而非生命周期事件驱动：自动对话捕获与自动预置召回不在本包范围内。

如果你的宿主有自己的 hook 体系，优先使用专用插件：hook 驱动的召回与捕获不消耗模型工具调用、不依赖模型"决定去记住"，比技能驱动循环更便宜也更可靠。专用插件一览：

这些专用插件由一个安装器统一覆盖（Claude Code、Codex、Cursor、TRAE / TRAE CN、ZCode、OpenCode、pi），它会询问语言、要安装哪些宿主、下载源与 OpenViking 凭据，且每一步都幂等。本 Agent Plugins 包适用于没有 hook 体系的宿主，或需要一份包在多个客户端间通用的场景。按规范，客户端专属集成将来也可以放入同一包内的反向域名命名目录（如com.example.client/）或清单的extensions字段，而不影响其他客户端。

一致性测试与开发流程

运行一致性检查：

node --test agent-plugins/plugin.test.mjs

plugin.test.mjs是零依赖的node --test套件，逐项校验：

• plugin.json的$schema指向 1.0.0 规范、name 符合 1~64 位小写字母数字加连字符/点号且无连续分隔符的规则、根字段封闭（只允许$schema/name/version/description/author/homepage/repository/license/keywords/extensions）、version 为 semver、author 字段受限；
• mcp.json的$schema与plugin.json的规范版本一致、根字段只允许$schema与mcpServers、至少声明一个服务器；
• 每个 MCP 服务器条目：command是单个 token（无空格、无占位符），streamable-http的 headers 不得携带 authorization/api-key/token/secret/cookie 等凭据，args中的${PLUGIN_ROOT}展开后必须落在插件根目录内且文件真实存在；
• 每个skills/*子目录都带SKILL.md，frontmatter 含与目录名一致的name与description；技能内相对 Markdown 链接必须解析到真实文件；
• 包内所有.mjs通过node --check，且mcp-proxy.mjs的所有相对导入真实存在。

关于servers/shared/*.mjs的生成机制：它们是examples/memory-plugin-shared/lib的生成副本，不要直接编辑。修改共享库后重新运行：

node examples/memory-plugin-shared/sync.mjs

该目录是同步脚本的 target 之一（sync.mjs中AGENT_PLUGINS_SHARED_FILES = ["credentials.mjs", "debug-log.mjs", ...MCP_PROXY_SHARED_FILES]，即只带凭据、调试日志与 MCP 代理所需模块——因为本规范无 hooks，hook 相关模块被整体剔除）；examples/memory-plugin-shared/sync.test.mjs会在副本漂移时失败。而agent-plugins/servers/mcp-proxy.mjs与config.mjs是从 Claude Code 插件的对应文件改编而来（只保留连接字段，丢弃全部 hook 调优旋钮）。两个测试文件都会在 CI 中运行。

小结

这份 Agent Plugins 1.0 包把 OpenViking 的"语义长期记忆 + 上下文引擎"压缩成一个零依赖、可移植、模型驱动的目录：stdio 代理在运行时解析凭据并透明转发 streamable HTTP，openviking-memory技能把完整的召回—持久化循环教给模型，而严格的一致性测试保证它在任何符合规范的客户端上都能被一致加载。没有 hook 体系的宿主、或想要一份包跨多客户端通用的场景，正是它的主场；需要 hook 级自动化的场景，则应转向各宿主的专用插件。更多能力细节可继续阅读 Capability Reference。

【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking