OpenViking Assets如何用 Manifest 和 Catalog 聲明并重復構建團隊知識庫資源集【免費下載鏈接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.項目地址: https://gitcode.com/GitHub_Trending/op/OpenVikingOpenViking Assets 用聲明文件描述一個知識庫應該由哪些資源組成讓你把一組 Git 倉庫的接入方式寫進文件里團隊可以 review、共享并反復執行來重建知識庫。這篇文檔面向的場景是你需要把多倉代碼問答庫、團隊文檔集這類需要重復構建、持續更新的資源集合管理起來而不是每次手動敲ov add-resource source。適用前提是openviking-assets/1是實驗性功能協議和命令行行為仍可能在后續版本中調整v1 只支持 Git 資產Manifest 必須平鋪、不支持遞歸include。先分清 Manifest、Catalog 和 StateOpenViking Assets 包含三個對象理解它們的分工能決定你用單文件還是多文件Manifest實際執行的文件。可以在catalog:下直接定義要接入的資產也可以按名稱從單獨的 Catalog 文件中選擇資產。Catalog團隊可接入資源的目錄包含來源、分支、默認更新周期和憑據別名。只有在多個 Manifest 需要共享時才作為單獨文件存在否則直接寫在 Manifest 里。State某個 Manifest 上次執行的結果以及資產到viking://資源的映射。服務端是協議解析的權威實現CLI 會把 Manifest 的原始 YAML使用單獨 Catalog 文件時一并發送 Catalog YAML發送到當前配置的 OpenViking 服務由服務端完成嚴格校驗并返回執行計劃服務端的解析接口本身不會創建資源。前置條件安裝支持 OpenViking Assets 的ovCLI。配置支持/api/v1/openviking-assets/resolve的 OpenViking 服務。確認 CLI 可以連接服務ov health最短路徑單文件 Manifest最簡單的形態下 Manifest 是唯一需要的文件在catalog:下直接定義資產。創建manifest.yamlprotocol: openviking-assets/1 catalog: - name: openviking connector: git params: repo_url: https://github.com/volcengine/OpenViking branch: main字段說明來自協議定義protocol定義catalog時必填當前必須為openviking-assets/1。catalog是資產定義列表定義了catalog的 Manifest 自身就是完整配置。assets用于指定要執行的資產名稱catalog在同一文件中時可省略——省略表示執行上面定義的全部資產。資產名稱必須匹配[A-Za-z0-9][A-Za-z0-9._-]*connectorv1 只支持git。校驗是嚴格的未知字段、重復資產名和不支持的連接器都會使整個解析失敗即使有問題的資產沒有被本次執行選擇。先做 dry-run 驗證不實際提交ov add-resource --manifest manifest.yaml --args dry_run:truedry_run會讀取本地 YAML、調用服務端解析并校驗協議、檢查所有auth_ref能否在本地解析、讓服務端用最終憑據對每個 Git 倉庫執行只讀git ls-remote權限預檢并輸出每個資產將執行的 create 或 sync 操作它不克隆倉庫、不提交資源、不創建任務也不寫入 State。任何倉庫不可讀時dry-run 立即以PERMISSION_DENIED退出不再輸出可執行計劃。確認計劃后去掉dry_run正式應用ov add-resource --manifest manifest.yaml等待每個資源處理完成ov add-resource --manifest manifest.yaml --wait --timeout 600團隊共享一個 Catalog 配多個 Manifest當多個 Manifest 復用同一批資源時把資產定義移到單獨的 Catalog 文件中通常命名為catalog.yaml。倉庫中有一份完整示例位于examples/openviking-assetscatalog.yaml定義資產manifest.yaml按名稱選擇。catalog.yaml示例節選自倉庫憑據不在此文件中auth_ref別名在各消費者機器上解析protocol: openviking-assets/1 defaults: git: watch_interval: 1440 # 分鐘除被覆蓋外每個倉庫每天刷新一次 catalog: - name: openviking connector: git description: OpenViking main repository — server, CLI and SDKs params: repo_url: https://github.com/volcengine/OpenViking branch: main - name: requests connector: git description: python-requests source, for HTTP client QA params: repo_url: https://github.com/psf/requests branch: main - name: flask connector: git description: Flask source, small enough for quick pilot runs watch_interval: 0 # 覆蓋該資產不自動刷新 params: repo_url: gitgithub.com:pallets/flask.git branch: main每個 Manifest 只需按名稱選擇資產例如manifest.yamlassets: - openviking - flask全團隊維護一份 Catalog在 Catalog 中修改資產所有選擇它的 Manifest 都會生效。Catalog 也可以直接執行ov add-resource -m catalog.yaml會導入它定義的全部資產。CLI 按以下規則查找 Catalog 文件傳入--args catalog:file時使用該路徑相對路徑基于當前工作目錄。未傳入時讀取 Manifest 所在目錄下的catalog.yaml。定義了catalog的 Manifest 不使用單獨的 Catalog 文件同時傳入會導致解析失敗。憑據只存別名不存 tokenManifest 和 Catalog 只保存auth_ref別名不應保存 token、密碼或私鑰。CLI 默認從以下文件解析別名~/.openviking/openviking_assets_credentials.yaml示例credentials: team-git: username: oauth2 token: replace-with-your-token可以用環境變量覆蓋文件位置export OPENVIKING_ASSETS_CREDENTIALS_FILE/secure/path/assets-credentials.yaml執行前CLI 先解析所有選中資產的auth_ref然后由服務端在實際執行環境中用git ls-remote校驗每個倉庫的讀取權限。只要有一個別名不存在或倉庫不可讀整個操作都會在提交任何資源之前失敗dry_run也執行相同預檢。如果目標服務已經具備訪問倉庫所需的 SSH key 或其他認證配置可以不設置auth_ref。解析出的 Git 參數會通過當前配置的 OpenViking 服務連接發送因此遠程部署應使用 TLS并限制憑據文件的本地訪問權限。重復構建靠 Statecreate / sync / orphan非 dry-run 執行后CLI 會在 Manifest 旁寫入 State 文件例如manifest.yaml.state.json。State 使用openviking-assets-state/1協議記錄asset_id、名稱、連接器、定位符和 ref、對應的resource_uri和task_id以及最近一次執行狀態、錯誤和時間。重復執行時按以下規則判定條件行為State 中沒有該asset_id的資源 URIcreate創建新資源State 中已有資源 URIsync把 URI 作為to再次調用add_resource資產不再被 Manifest 選擇報告 orphan保留資源和 State不自動刪除asset_id因來源或分支變化創建新資產舊資產成為 orphan服務端根據connector normalized locator ref生成穩定的asset_idGit URL 會去除協議、用戶名前綴、端口、結尾的.git和/并把主機名統一為小寫。資產名稱不參與身份計算——重命名資產但保持來源和分支不變時會繼續關聯原資源修改來源或分支時會產生新資產舊資源被報告為 orphan。State 屬于執行環境不是 Catalog 或 Manifest 協議的一部分。共享 Manifest 倉庫通常應在.gitignore中加入*.state.json。不要并發執行同一個 Manifest當前 State 文件不提供跨進程鎖。更新周期 watch_intervalwatch_interval的優先級從高到低為CLI 的--watch-interval單個資產的watch_intervaldefaults.git.watch_interval0不自動刷新。例如臨時把 Manifest 中全部資產調整為每 60 分鐘刷新ov add-resource --manifest manifest.yaml --watch-interval 60后續內容刷新由 Watch 執行。當最終watch_interval大于0時OpenViking 會把通過auth_ref解析出的 HTTPS Git token 保存到 Watch task 私有且與倉庫 URL 綁定的鑒權狀態中周期為0時token 仍只在本次請求內使用。Git PAT 沒有通用刷新流程token 過期或被撤銷后需要重建 Watch。重新運行 Manifest 仍可用于應用 Catalog/Manifest 構成變化、恢復失敗資產或顯式觸發同步。失敗處理權限預檢先于所有資源提交。任一資產預檢失敗時命令立即以原始錯誤碼退出例如PERMISSION_DENIED不提交任何資產、不創建后臺任務、不寫入 Stateskip_failed不會跳過預檢失敗。只有全部預檢成功后才進入逐資產執行階段。默認采用 fail-fast當前資產失敗、后續資產標記為未嘗試、已成功資產和失敗記錄寫入 State、命令以非零狀態退出。需要某個資產失敗后繼續處理其余資產時ov add-resource --manifest manifest.yaml --args skip_failed:trueskip_failed不會把部分失敗轉換為成功只要有資產失敗命令最終仍以非零狀態退出已經成功的資源不會回滾。全部資產失敗時命令會報告沒有任何資產成功應用。當前限制只支持 Git 資產Manifest 必須平鋪不支持遞歸include。服務端 resolver 只返回計劃不執行批量提交CLI 按順序逐個執行資產。preflight 通過只讀git ls-remote校驗倉庫權限不下載倉庫內容。不自動刪除 orphanState 是本地文件不在多臺機器之間自動同步。不包含ov share指針碼或從現有知識庫導出 Manifest 的能力。CLI 和服務端都必須支持同一協議版本。如果你需要開發自定義客戶端可以直接請求POST /api/v1/openviking-assets/resolve返回標準化資產計劃不克隆倉庫、不創建資源、不啟動同步任務和POST /api/v1/openviking-assets/preflight在服務端實際運行環境執行只讀git ls-remote校驗倉庫與可選 ref 是否可讀詳見 OpenViking Assets API。完整協議與運行指南見 OpenViking Assets 指南?！久赓M下載鏈接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.項目地址: https://gitcode.com/GitHub_Trending/op/OpenViking創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考