OpenViking Agent Plugins 1.0 插件包基于統(tǒng)一規(guī)范的跨客戶端記憶插件接入指南【免費(fèi)下載鏈接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/op/OpenViking導(dǎo)讀Agent Plugins 1.0 插件包 是 OpenViking 面向「與廠商無關(guān)的 AI 編碼 Agent 插件打包規(guī)范」提供的一站式接入方案。本文將圍繞該插件包的目錄結(jié)構(gòu)、stdio 代理原理、憑據(jù)解析順序、能力邊界與規(guī)范一致性校驗(yàn)展開并結(jié)合倉庫中agent-plugins/目錄的真實(shí)源碼與測試講清「如何讓任意符合規(guī)范的客戶端以同一套方式加載 OpenViking 記憶能力」。讀完后你將掌握插件包的安裝與配置方法、ovCLI 同源的憑據(jù)解析機(jī)制、模型驅(qū)動的「召回 沉淀」閉環(huán)用法以及如何用node --test校驗(yàn)插件包的規(guī)范一致性。一、插件包是什么一份規(guī)范多處復(fù)用Agent Plugins 1.0 是一套與廠商無關(guān)的 AI 編碼 Agent 插件打包規(guī)范。一個(gè)插件就是一個(gè)普通目錄包含plugin.json清單、skills/下自動發(fā)現(xiàn)的 Agent Skills以及可選的mcp.jsonMCP 服務(wù)聲明。所有符合規(guī)范的客戶端都以同樣的方式加載它——不再需要為每個(gè)客戶端各寫一套接入。OpenViking 的這個(gè)插件包位于倉庫的agent-plugins/目錄。它的設(shè)計(jì)目標(biāo)很明確讓 Claude Code、Codex、Cursor、TRAE、ZCode、OpenCode、pi 等支持 Agent Plugins 規(guī)范的 harness用同一份包獲得可移植的 OpenViking 長期記憶能力。目錄結(jié)構(gòu)agent-plugins/ ├── plugin.json # Agent Plugins 1.0 清單name: openviking ├── mcp.json # 一個(gè) stdio MCP serveropenviking ├── servers/ │ ├── mcp-proxy.mjs # stdio - streamable-HTTP 代理轉(zhuǎn)發(fā)到服務(wù)端 /mcp │ ├── config.mjs, debug-log.mjs # 憑據(jù) / 配置解析 │ └── shared/ # 由 examples/memory-plugin-shared/lib 生成 ├── skills/openviking-memory/SKILL.md # 教模型完成「召回 沉淀」閉環(huán) └── plugin.test.mjs # node --test 規(guī)范一致性校驗(yàn)零 npm 依賴——代理和測試只用 Node.js 標(biāo)準(zhǔn)庫需要 Node 18 以獲得全局fetch。清單與 MCP 聲明plugin.json嚴(yán)格遵循 Agent Plugins 1.0 schemahttps://agent-plugins.org/schemas/1.0.0/plugin.schema.jsonname為openvikingversion為0.1.0描述中明確了其能力定位為編碼 Agent 提供語義化長期記憶與上下文引擎通過find/search/read等 MCP 工具召回歷史知識通過remember/write持久化重要事實(shí)后端由一個(gè) OpenViking 服務(wù)承載。清單還聲明了author、homepage、licenseAGPL-3.0和keywords等元數(shù)據(jù)字段見 plugin.json。mcp.json聲明了一個(gè)名為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}占位符規(guī)范只在args/env/cwd中展開該占位符command必須是單一可執(zhí)行 token不允許帶空格或 shell 字符串。這一點(diǎn)在 plugin.test.mjs 中有專門的斷言校驗(yàn)。二、安裝三步接入任意客戶端準(zhǔn)備一個(gè)可訪問的 OpenViking 服務(wù)。還沒有的話先按 快速開始 部署本地默認(rèn)端點(diǎn)是http://127.0.0.1:1933。讓你的 Agent Plugins 客戶端指向agent-plugins/目錄。各客戶端的安裝命令或插件目錄不同請查閱其文檔。加載時(shí)客戶端會按mcp.json注冊名為openviking的 MCP server以 stdio 方式運(yùn)行node plugin/servers/mcp-proxy.mjs從skills/發(fā)現(xiàn)openviking-memory技能。配置憑據(jù)見下節(jié)后開始會話。模型即可使用find/search/read/list/grep/glob/remember/add_resource/forget/health較新的服務(wù)端還提供tree/write/edit。如果不想手動下載examples/memory-plugin-shared/install.sh提供了交互式安裝腳本Claude Code、Codex、Cursor、TRAE / TRAE CN、ZCode、OpenCode、pi 共用同一個(gè)安裝腳本。它會依次詢問界面語言、要安裝的 harness、下載源和 OpenViking 憑據(jù)所有步驟冪等重復(fù)運(yùn)行安全。GitHub 訪問受限的地區(qū)可以從火山引擎 TOS 鏡像運(yùn)行同一個(gè)腳本具體 URL 見 memory-plugin-shared 的 README。各客戶端專屬集成對照Harness專屬集成Claude CodeClaude Code 記憶插件CodexCodex 記憶插件OpenCodeOpenCode 插件CursorCursor 記憶集成TRAE / TRAE CNTRAE 記憶集成pipi Coding Agent 擴(kuò)展OpenClawOpenClaw 插件 — 獨(dú)立安裝流程ZCode社區(qū)集成按規(guī)范客戶端專屬的集成后續(xù)也可以放進(jìn)同一個(gè)包里——使用反向域名命名的目錄如com.example.client/或清單的extensions字段——且不會影響其他客戶端。三、為什么用 stdio 代理而不是streamable-httpOpenViking 服務(wù)端本身在/mcp上就是 streamable HTTP但mcp.json里直接寫streamable-http條目無法做到可移植原因有二服務(wù)地址因部署而異有人是 localhost有人是遠(yuǎn)端靜態(tài) URL 寫死在清單里無法復(fù)用規(guī)范禁止把憑據(jù)寫進(jìn)靜態(tài)headersmcp.json屬于可分發(fā)清單不能內(nèi)嵌 API Key。stdio 代理同時(shí)解決這兩點(diǎn)——它在運(yùn)行時(shí)從與ovCLI 相同的本地來源解析 URL 和 API Key逐請求注入再把 JSON-RPC 原樣通過 streamable HTTP 轉(zhuǎn)發(fā)。從源碼看mcp-proxy.mjs 的工作流是通過loadConfig()見 config.mjs解析連接配置交給共享模塊buildMcpProxyConfig()與resolveMcpActorPeerId()見 servers/shared/mcp-proxy-config.mjs整理出代理配置由createOpenVikingMcpProxy()見 servers/shared/mcp-proxy-core.mjs啟動代理處理 stdio 上的 JSON-RPC 請求、維護(hù)會話重試與并發(fā)信號量MAX_CONCURRENT_REQUESTS 16、保持 stdout 協(xié)議純凈。代理核心還實(shí)現(xiàn)了憑據(jù)文件熱加載它會持續(xù)快照被監(jiān)聽的配置文件mtimeMs:size檢測到變化即重新讀取配置見snapshotPaths/snapshotsDiffer因此配置文件改動后無需重啟代理。關(guān)于 actor 范圍的 peer 語義resolveMcpActorPeerId揭示了一個(gè)容易被忽略的細(xì)節(jié)MCP server 可能從插件目錄啟動而非工作區(qū)目錄因此其進(jìn)程 cwd 不能作為可靠的 peer 身份。若開啟 actor 范圍召回recallPeerScope actor代理無法自行推導(dǎo) peer id會回退到跨 peer 的寬召回并輸出警告而不是拒絕啟動——因?yàn)榇沓休d著所有記憶工具因一個(gè)范圍偏好而禁用全部工具代價(jià)遠(yuǎn)大于更寬范圍的搜索。需要精確隔離時(shí)應(yīng)在ovcli.conf中顯式設(shè)置actor_peer_id或在 MCP server 環(huán)境中設(shè)置OPENVIKING_PEER_ID。四、憑據(jù)解析順序與ovCLI 完全一致從高到低與ovCLI 及其他 OpenViking 插件完全一致環(huán)境變量OPENVIKING_URL或OPENVIKING_BASE_URL、OPENVIKING_API_KEY或OPENVIKING_BEARER_TOKEN、OPENVIKING_ACCOUNT、OPENVIKING_USER、OPENVIKING_PEER_ID~/.openviking/ovcli.confurl、api_key、account、user——可用OPENVIKING_CLI_CONFIG_FILE覆蓋路徑~/.openviking/ov.conf的server段url或host/port以及root_api_key——可用OPENVIKING_CONFIG_FILE覆蓋路徑默認(rèn)值http://127.0.0.1:1933不鑒權(quán)本地模式// ~/.openviking/ovcli.conf { url: https://openviking.example.com, api_key: your-api-key }從 config.mjs 的loadConfig()實(shí)現(xiàn)可以逐項(xiàng)印證baseUrl 解析鏈環(huán)境變量OPENVIKING_URL/OPENVIKING_BASE_URL→ovcli.conf的url→ov.confserver.url→ 由host/port拼出http://{host}:{port}其中0.0.0.0會被歸一化為127.0.0.1末尾斜杠統(tǒng)一去除apiKey 解析鏈OPENVIKING_BEARER_TOKEN→OPENVIKING_API_KEY→ovcli.conf的api_key→ov.confserver.root_api_key兩者都作為 Bearer 發(fā)送超時(shí)控制OPENVIKING_TIMEOUT_MS可調(diào)整默認(rèn) 15s 的單請求超時(shí)下限被鉗制為 1000msMath.max(1000, ...)與共享模塊中MIN_PROXY_TIMEOUT_MS 1000、DEFAULT_PROXY_TIMEOUT_MS 15000的常量保持一致~展開配置文件路徑中的~會被正確展開為主目錄見 mcp-proxy-config.mjs 的normalizeConfigPath。配置文件的改動會被運(yùn)行中的代理自動讀取無需重啟。調(diào)試設(shè)置OPENVIKING_DEBUG1日志以 JSON Lines 格式{ ts, hook, stage, data }或{ ts, hook, stage, error }寫入~/.openviking/logs/agent-plugins.log路徑可用OPENVIKING_DEBUG_LOG覆蓋。未開啟時(shí)日志函數(shù)是零開銷的 no-op見 debug-log.mjs。五、能力邊界規(guī)范不含 hooksAgent Plugins 1.0 只覆蓋skills 和 MCP servershooks、commands、agents 被有意排除在本版本之外因?yàn)樗鼈冊诟骺蛻舳酥g語義差異太大。因此這個(gè)包提供的是可移植的召回 寫入能力面由模型驅(qū)動而非生命周期事件驅(qū)動自動會話捕獲和 prompt 前自動召回不在此范圍內(nèi)。作為補(bǔ)償內(nèi)置的openviking-memory技能直接把這套閉環(huán)教給模型見 SKILL.md任務(wù)開始時(shí)用find/searchread召回需要組裝上下文時(shí)使用search的modecontext過程中和結(jié)束后用remember/write/edit沉淀并給出使用召回內(nèi)容時(shí)的優(yōu)先級與安全規(guī)則系統(tǒng)與開發(fā)者指令 當(dāng)前用戶請求 當(dāng)前環(huán)境與工具證據(jù) 記憶內(nèi)容記憶僅作為參考命令、路徑、版本必須以當(dāng)前任務(wù)為準(zhǔn)過往成功從不授權(quán)破壞性操作。如果你的 harness 支持 hooks 機(jī)制推薦使用專屬插件。hook 驅(qū)動的召回與捕獲不需要模型花費(fèi)工具調(diào)用、也不依賴模型「想起來要記」比技能驅(qū)動的閉環(huán)更省 token、也更可靠。本 Agent Plugins 包適用于沒有 hooks 的 harness或你希望用同一個(gè)包覆蓋多個(gè)客戶端的場景。技能中的工具清單與用法約定核心工具所有受支持的部署都提供召回find、search、read、list、grep、glob沉淀remember、add_resource維護(hù)forget、health部分部署還注冊了更多工具——tree、write、edit、list_watches、cancel_watch。這些是可選的具體存在哪些取決于服務(wù)端版本與托管模式托管云服務(wù)會裁剪一部分。使用前先查看會話注冊的工具列表若存在任一可選工具先閱讀references/optional-tools.md再使用。絕不調(diào)用未注冊的工具也不要回退到裸 HTTP如果完全沒有注冊 OpenViking 工具就繼續(xù)無記憶運(yùn)行。實(shí)用的用法約定包括find是快速排名的召回工具返回 URI 摘要 分?jǐn)?shù)limit建議 510search適合需要更深意圖分析的場景或用modecontext讓服務(wù)端組裝一個(gè)受 token 預(yù)算約束的上下文塊list 模式下可用target_uri限定范圍例如viking://~/memories/experiences檢索既往任務(wù)經(jīng)驗(yàn)用read讀取 13 個(gè)最可能改變執(zhí)行方式的精確文件 URI忽略.abstract.md、.overview.md、.relations.json這類 sidecar 文件remember(messages)是默認(rèn)的沉淀方式——把關(guān)鍵對話或簡短事實(shí)摘要以帶角色的消息傳入由服務(wù)端自行抽取并歸檔記憶偏好、實(shí)體、事件、經(jīng)驗(yàn)add_resource用于導(dǎo)入外部文檔或 URL 作為可檢索資源需要精確落盤到已知位置viking://~/用戶根目錄或viking://resources/共享資料時(shí)使用可選的write/edit工具未注冊則回退到remember該記什么穩(wěn)定的偏好與約定、環(huán)境事實(shí)、帶理由的決策、可復(fù)用的流程或修復(fù)方案不該記什么密鑰與憑據(jù)、瞬時(shí)狀態(tài)、猜測、整段 transcript——沉淀結(jié)論而非回放。六、規(guī)范一致性校驗(yàn)與開發(fā)倉庫為插件包提供了零依賴的規(guī)范一致性測試一條命令即可運(yùn)行node --test agent-plugins/plugin.test.mjsplugin.test.mjs 會校驗(yàn)plugin.json的 schema URL 必須是 Agent Plugins 1.0plugin.schema.json且兩個(gè)清單的規(guī)范版本一致插件name規(guī)則1-64 字符小寫字母數(shù)字加連字符/句點(diǎn)不允許連續(xù)分隔符清單根字段閉集plugin.json根只允許$schema、name、version、description、author、homepage、repository、license、keywords、extensions這些規(guī)范字段version必須符合 semver每個(gè)skills/*子目錄都有帶namedescriptionfrontmatter 的SKILL.md且name與目錄同名技能內(nèi)部相對 Markdown 鏈接必須指向真實(shí)存在的文件mcp.json引用的文件存在且不逃逸插件根目錄streamable-http類型的 server 其headers不得攜帶憑據(jù)字段authorization/api_key/token/secret/cookie等包內(nèi)所有.mjs都能通過node --check且mcp-proxy.mjs的 import 鏈完整可解析。共享代碼的同步機(jī)制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等按能力分組的文件清單。請改共享庫后重新執(zhí)行node examples/memory-plugin-shared/sync.mjs一旦漂移examples/memory-plugin-shared/sync.test.mjs會失敗。兩個(gè)測試文件都已接入 CI保證插件包與共享庫不會悄然分叉。七、總結(jié)OpenViking 的 Agent Plugins 1.0 插件包以「一份規(guī)范、多處復(fù)用」為設(shè)計(jì)哲學(xué)用 stdio 代理 技能雙機(jī)制在不依賴 hooks的前提下把模型驅(qū)動的「召回 沉淀」記憶閉環(huán)帶給任意符合規(guī)范的客戶端。其價(jià)值體現(xiàn)在三個(gè)層面可移植性mcp.json只聲明 stdio 代理URL 與憑據(jù)在運(yùn)行時(shí)從ovCLI 同源的本地來源解析同一份包可覆蓋多種 harness可維護(hù)性憑據(jù)熱加載、JSON Lines 調(diào)試日志、node --test規(guī)范一致性校驗(yàn)與共享庫同步機(jī)制讓插件包長期保持健康能力邊界清晰明確區(qū)分「技能驅(qū)動的可移植能力面」與「hook 驅(qū)動的專屬集成」讓用戶按自己的 harness 能力做出恰當(dāng)選擇。對于尚未提供 hooks 機(jī)制的客戶端或者希望以最小成本在多個(gè)客戶端間統(tǒng)一記憶體驗(yàn)的場景這個(gè)插件包是開箱即用的答案。相關(guān)能力的進(jìn)一步對照可參考 集成能力參考?！久赓M(fèi)下載鏈接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/op/OpenViking創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考