企业官网建设流程全解析

OpenViking Agent Plugins 1.0 插件包：基于统一规范的跨客户端记忆插件接入指南

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

导读

Agent Plugins 1.0 插件包 是 OpenViking 面向「与厂商无关的 AI 编码 Agent 插件打包规范」提供的一站式接入方案。本文将围绕该插件包的目录结构、stdio 代理原理、凭据解析顺序、能力边界与规范一致性校验展开，并结合仓库中agent-plugins/目录的真实源码与测试，讲清「如何让任意符合规范的客户端以同一套方式加载 OpenViking 记忆能力」。读完后，你将掌握插件包的安装与配置方法、ovCLI 同源的凭据解析机制、模型驱动的「召回 + 沉淀」闭环用法，以及如何用node --test校验插件包的规范一致性。

一、插件包是什么：一份规范，多处复用

Agent Plugins 1.0 是一套与厂商无关的 AI 编码 Agent 插件打包规范。一个插件就是一个普通目录：包含plugin.json清单、skills/下自动发现的 Agent Skills，以及可选的mcp.jsonMCP 服务声明。所有符合规范的客户端都以同样的方式加载它——不再需要为每个客户端各写一套接入。

OpenViking 的这个插件包位于仓库的agent-plugins/目录。它的设计目标很明确：让 Claude Code、Codex、Cursor、TRAE、ZCode、OpenCode、pi 等支持 Agent Plugins 规范的 harness，用同一份包获得可移植的 OpenViking 长期记忆能力。

目录结构

agent-plugins/ ├── plugin.json # Agent Plugins 1.0 清单（name: openviking） ├── mcp.json # 一个 stdio MCP server："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 # 教模型完成「召回 + 沉淀」闭环 └── plugin.test.mjs # node --test 规范一致性校验

零 npm 依赖——代理和测试只用 Node.js 标准库（需要 Node 18+ 以获得全局fetch）。

清单与 MCP 声明

plugin.json严格遵循 Agent Plugins 1.0 schema（https://agent-plugins.org/schemas/1.0.0/plugin.schema.json），name为openviking，version为0.1.0，描述中明确了其能力定位：为编码 Agent 提供语义化长期记忆与上下文引擎，通过find/search/read等 MCP 工具召回历史知识，通过remember/write持久化重要事实，后端由一个 OpenViking 服务承载。清单还声明了author、homepage、license（AGPL-3.0）和keywords等元数据字段，见 plugin.json。

mcp.json声明了一个名为openviking的 stdio MCP server：

{ "$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"] } } }

注意args中的${PLUGIN_ROOT}占位符：规范只在args/env/cwd中展开该占位符，command必须是单一可执行 token（不允许带空格或 shell 字符串）。这一点在 plugin.test.mjs 中有专门的断言校验。

二、安装：三步接入任意客户端

1. 准备一个可访问的 OpenViking 服务。还没有的话，先按 快速开始 部署；本地默认端点是http://127.0.0.1:1933。
2. 让你的 Agent Plugins 客户端指向agent-plugins/目录。各客户端的安装命令或插件目录不同，请查阅其文档。加载时客户端会：
   • 按mcp.json注册名为openviking的 MCP server，以 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。

如果不想手动下载，examples/memory-plugin-shared/install.sh提供了交互式安装脚本，Claude Code、Codex、Cursor、TRAE / TRAE CN、ZCode、OpenCode、pi 共用同一个安装脚本。它会依次询问界面语言、要安装的 harness、下载源和 OpenViking 凭据，所有步骤幂等，重复运行安全。GitHub 访问受限的地区，可以从火山引擎 TOS 镜像运行同一个脚本（具体 URL 见 memory-plugin-shared 的 README）。

各客户端专属集成对照

按规范，客户端专属的集成后续也可以放进同一个包里——使用反向域名命名的目录（如com.example.client/）或清单的extensions字段——且不会影响其他客户端。

三、为什么用 stdio 代理，而不是streamable-http

OpenViking 服务端本身在/mcp上就是 streamable HTTP，但mcp.json里直接写streamable-http条目无法做到可移植，原因有二：

• 服务地址因部署而异：有人是 localhost，有人是远端，静态 URL 写死在清单里无法复用；
• 规范禁止把凭据写进静态headers：mcp.json属于可分发清单，不能内嵌 API Key。

stdio 代理同时解决这两点——它在运行时从与ovCLI 相同的本地来源解析 URL 和 API Key，逐请求注入，再把 JSON-RPC 原样通过 streamable HTTP 转发。从源码看，mcp-proxy.mjs 的工作流是：

1. 通过loadConfig()（见 config.mjs）解析连接配置；
2. 交给共享模块buildMcpProxyConfig()与resolveMcpActorPeerId()（见 servers/shared/mcp-proxy-config.mjs）整理出代理配置；
3. 由createOpenVikingMcpProxy()（见 servers/shared/mcp-proxy-core.mjs）启动代理：处理 stdio 上的 JSON-RPC 请求、维护会话重试与并发信号量（MAX_CONCURRENT_REQUESTS = 16）、保持 stdout 协议纯净。

代理核心还实现了凭据文件热加载：它会持续快照被监听的配置文件（mtimeMs:size），检测到变化即重新读取配置（见snapshotPaths/snapshotsDiffer），因此配置文件改动后无需重启代理。

关于 actor 范围的 peer 语义

resolveMcpActorPeerId揭示了一个容易被忽略的细节：MCP server 可能从插件目录启动而非工作区目录，因此其进程 cwd 不能作为可靠的 peer 身份。若开启 actor 范围召回（recallPeerScope = "actor"），代理无法自行推导 peer id，会回退到跨 peer 的宽召回并输出警告，而不是拒绝启动——因为代理承载着所有记忆工具，因一个范围偏好而禁用全部工具，代价远大于更宽范围的搜索。需要精确隔离时，应在ovcli.conf中显式设置actor_peer_id，或在 MCP server 环境中设置OPENVIKING_PEER_ID。

四、凭据解析顺序：与ovCLI 完全一致

从高到低，与ovCLI 及其他 OpenViking 插件完全一致：

1. 环境变量：OPENVIKING_URL（或OPENVIKING_BASE_URL）、OPENVIKING_API_KEY（或OPENVIKING_BEARER_TOKEN）、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" }

从 config.mjs 的loadConfig()实现可以逐项印证：

• baseUrl 解析链：环境变量OPENVIKING_URL/OPENVIKING_BASE_URL→ovcli.conf的url→ov.confserver.url→ 由host/port拼出http://{host}:{port}，其中0.0.0.0会被归一化为127.0.0.1，末尾斜杠统一去除；
• apiKey 解析链：OPENVIKING_BEARER_TOKEN→OPENVIKING_API_KEY→ovcli.conf的api_key→ov.confserver.root_api_key（两者都作为 Bearer 发送）；
• 超时控制：OPENVIKING_TIMEOUT_MS可调整默认 15s 的单请求超时，下限被钳制为 1000ms（Math.max(1000, ...)），与共享模块中MIN_PROXY_TIMEOUT_MS = 1000、DEFAULT_PROXY_TIMEOUT_MS = 15000的常量保持一致；
• ~展开：配置文件路径中的~会被正确展开为主目录（见 mcp-proxy-config.mjs 的normalizeConfigPath）。

配置文件的改动会被运行中的代理自动读取，无需重启。

调试：设置OPENVIKING_DEBUG=1，日志以 JSON Lines 格式（{ ts, hook, stage, data }或{ ts, hook, stage, error }）写入~/.openviking/logs/agent-plugins.log（路径可用OPENVIKING_DEBUG_LOG覆盖）。未开启时，日志函数是零开销的 no-op（见 debug-log.mjs）。

五、能力边界：规范不含 hooks

Agent Plugins 1.0 只覆盖skills 和 MCP servers；hooks、commands、agents 被有意排除在本版本之外，因为它们在各客户端之间语义差异太大。因此这个包提供的是可移植的召回 + 写入能力面，由模型驱动而非生命周期事件驱动：自动会话捕获和 prompt 前自动召回不在此范围内。

作为补偿，内置的openviking-memory技能直接把这套闭环教给模型（见 SKILL.md）：

• 任务开始时用find/search+read召回（需要组装上下文时使用search的mode="context"）；
• 过程中和结束后用remember/write/edit沉淀；
• 并给出使用召回内容时的优先级与安全规则：系统与开发者指令 > 当前用户请求 > 当前环境与工具证据 > 记忆内容；记忆仅作为参考，命令、路径、版本必须以当前任务为准，过往成功从不授权破坏性操作。

如果你的 harness 支持 hooks 机制，推荐使用专属插件。hook 驱动的召回与捕获不需要模型花费工具调用、也不依赖模型「想起来要记」，比技能驱动的闭环更省 token、也更可靠。本 Agent Plugins 包适用于没有 hooks 的 harness，或你希望用同一个包覆盖多个客户端的场景。

技能中的工具清单与用法约定

核心工具（所有受支持的部署都提供）：

• 召回：find、search、read、list、grep、glob
• 沉淀：remember、add_resource
• 维护：forget、health

部分部署还注册了更多工具——tree、write、edit、list_watches、cancel_watch。这些是可选的：具体存在哪些取决于服务端版本与托管模式（托管云服务会裁剪一部分）。使用前先查看会话注册的工具列表；若存在任一可选工具，先阅读references/optional-tools.md再使用。绝不调用未注册的工具，也不要回退到裸 HTTP；如果完全没有注册 OpenViking 工具，就继续无记忆运行。

实用的用法约定包括：

• find是快速排名的召回工具（返回 URI + 摘要 + 分数），limit建议 5～10；search适合需要更深意图分析的场景，或用mode="context"让服务端组装一个受 token 预算约束的上下文块；list 模式下可用target_uri限定范围，例如viking://~/memories/experiences检索既往任务经验；
• 用read读取 1～3 个最可能改变执行方式的精确文件 URI；忽略.abstract.md、.overview.md、.relations.json这类 sidecar 文件；
• remember(messages)是默认的沉淀方式——把关键对话或简短事实摘要以带角色的消息传入，由服务端自行抽取并归档记忆（偏好、实体、事件、经验）；add_resource用于导入外部文档或 URL 作为可检索资源；需要精确落盘到已知位置（viking://~/用户根目录或viking://resources/共享资料）时使用可选的write/edit工具，未注册则回退到remember；
• 该记什么：稳定的偏好与约定、环境事实、带理由的决策、可复用的流程或修复方案；不该记什么：密钥与凭据、瞬时状态、猜测、整段 transcript——沉淀结论而非回放。

六、规范一致性校验与开发

仓库为插件包提供了零依赖的规范一致性测试，一条命令即可运行：

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

plugin.test.mjs 会校验：

• plugin.json的 schema URL 必须是 Agent Plugins 1.0（plugin.schema.json），且两个清单的规范版本一致；
• 插件name规则：1-64 字符，小写字母数字加连字符/句点，不允许连续分隔符；
• 清单根字段闭集：plugin.json根只允许$schema、name、version、description、author、homepage、repository、license、keywords、extensions这些规范字段；
• version必须符合 semver；
• 每个skills/*子目录都有带name+descriptionfrontmatter 的SKILL.md，且name与目录同名；技能内部相对 Markdown 链接必须指向真实存在的文件；
• mcp.json引用的文件存在且不逃逸插件根目录；streamable-http类型的 server 其headers不得携带凭据字段（authorization/api_key/token/secret/cookie等）；
• 包内所有.mjs都能通过node --check，且mcp-proxy.mjs的 import 链完整可解析。

共享代码的同步机制

servers/shared/*.mjs是examples/memory-plugin-shared/lib的生成副本——credentials.mjs、mcp-proxy-config.mjs、mcp-proxy-core.mjs、debug-log.mjs等模块由各 harness 插件共享（sync.mjs 中定义了MCP_PROXY_SHARED_FILES等按能力分组的文件清单）。请改共享库后重新执行node examples/memory-plugin-shared/sync.mjs；一旦漂移，examples/memory-plugin-shared/sync.test.mjs会失败。两个测试文件都已接入 CI，保证插件包与共享库不会悄然分叉。

七、总结

OpenViking 的 Agent Plugins 1.0 插件包以「一份规范、多处复用」为设计哲学，用 stdio 代理 + 技能双机制，在不依赖 hooks的前提下把模型驱动的「召回 + 沉淀」记忆闭环带给任意符合规范的客户端。其价值体现在三个层面：

1. 可移植性：mcp.json只声明 stdio 代理，URL 与凭据在运行时从ovCLI 同源的本地来源解析，同一份包可覆盖多种 harness；
2. 可维护性：凭据热加载、JSON Lines 调试日志、node --test规范一致性校验与共享库同步机制，让插件包长期保持健康；
3. 能力边界清晰：明确区分「技能驱动的可移植能力面」与「hook 驱动的专属集成」，让用户按自己的 harness 能力做出恰当选择。

对于尚未提供 hooks 机制的客户端，或者希望以最小成本在多个客户端间统一记忆体验的场景，这个插件包是开箱即用的答案。相关能力的进一步对照，可参考 集成能力参考。

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