OpenViking Assets 指南用 Manifest 声明式管理 AI Agent 知识库资源【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking本指南依据仓库中 docs/zh/guides/18-openviking-assets.md 展开并结合服务端解析器 openviking/server/openviking_assets.py、CLI 实现 crates/ov_cli/src/openviking_assets.rs 与仓库内完整示例 examples/openviking-assets/ 进行纵深说明。OpenViking Assets 是 OpenViking 提供的一套声明式知识库构建方案用一份 Manifest 文件描述一个知识库应该由哪些资源组成再交给 OpenViking 逐项创建或更新资源。本文面向需要重复构建、持续更新资源集合的团队如多仓代码问答库、团队文档集完整覆盖openviking-assets/1协议的 Manifest/Catalog/State 概念模型、完整配置示例、凭据与权限预检、dry-run 验证、ov add-resource -m命令行操作及失败处理策略。读完本文你将能独立编写并验证自己的 Manifest把资源集合变成可 review、可共享、可重复执行的工程资产。实验性功能提示openviking-assets/1协议和命令行行为仍可能在后续版本中调整请以当前仓库实现为准。OpenViking Assets 在资源体系中的定位在 OpenViking 中接入外部内容有三种途径它们解决的层次完全不同能力描述ov add-resource source添加或更新一个资源描述的是一次资源操作。OpenViking Assets声明一组资源的预期构成可以 review、共享并重复执行。OVPack导出或导入已经生成的数据快照搬运的是内容和可选索引数据。OpenViking Assets不替代现有资源处理流程。Git 拉取、内容解析、语义提取、向量化和 Watch 更新仍由add_resource及服务端连接器完成Assets 只增加声明、解析和逐项编排这一层。也就是说Assets 是编排层add_resource是执行层两者各司其职。概念模型Manifest、Catalog 与 StateOpenViking Assets 由三个主要对象构成Manifest实际执行的文件。可以在catalog:下直接定义要接入的资产也可以按名称从单独的 Catalog 文件中选择资产。Catalog团队可接入资源的目录包含来源、分支、默认更新周期和凭据别名。只有在多个 Manifest 需要共享时才作为单独文件存在否则直接写在 Manifest 里。State某个 Manifest 上次执行的结果以及资产到viking://资源的映射。三者协作的完整流程如下manifest.yaml使用共享 Catalog 时再加 catalog.yaml | v 服务端解析和校验 openviking-assets/1 | v Resolved Assets | v CLI 解析本地凭据和 State | v 逐个调用 add_resource - viking:// resources这里有一个重要的职责划分服务端是协议解析的权威实现。CLI 会把 Manifest 的原始 YAML使用单独 Catalog 文件时一并发送 Catalog YAML发送到当前配置的 OpenViking 服务由服务端完成严格校验并返回执行计划服务端的解析接口本身不会创建资源。这一点在源码中得到印证HTTP 路由 openviking/server/routers/openviking_assets.py 中的/api/v1/openviking-assets/resolve端点只调用resolve_openviking_assets完成解析与校验并返回结果注释明确写着Parse and validate configuration without submitting resources而 CLI 端Rust 实现 crates/ov_cli/src/openviking_assets.rs同样注明服务端拥有 openviking-assets 语法解析与语义校验的权威实现CLI 只接收已解析的执行计划。协议详解ManifestManifest 描述一次知识库构建。最简单的形态下它是唯一需要的文件——在catalog:下直接定义资产protocol: openviking-assets/1 defaults: git: auth_ref: team-git watch_interval: 60 catalog: - name: openviking connector: git description: OpenViking 主仓库 params: repo_url: https://github.com/volcengine/OpenViking branch: main - name: requests connector: git description: Requests HTTP 客户端源码 watch_interval: 0 params: repo_url: https://github.com/psf/requests branch: main assets: [openviking] # 可选省略 执行上面定义的全部资产Manifest 顶层字段字段必填说明protocol定义catalog时必填当前必须为openviking-assets/1只按名称选择资产的 Manifest 可省略但设置时同样会校验。defaults否为本文件定义的资产设置连接器级默认值只能与catalog一起使用。catalog否资产定义列表字段见下。定义了catalog的 Manifest 自身就是完整配置。assets见说明要执行的资产名称。catalog在同一文件中时可省略——省略表示执行全部定义的资产资产定义在单独 Catalog 文件中时必填。include否v1 不支持组合其他 Manifest非空时解析失败。重复的资产名称会按首次出现的位置去重。选择不存在的资产时整个解析失败。defaults.git与 Git 资产字段defaults.git支持字段说明auth_ref本地凭据文件中的默认别名。watch_interval默认 Watch 周期单位为分钟0表示不自动刷新。Git 资产catalog下的每个条目支持字段必填说明name是唯一资产名称必须匹配[A-Za-z0-9][A-Za-z0-9._-]*。connector是v1 只支持git。description否资产用途说明。params.repo_url是Git clone URL。params.branch否要接入的分支设置时不能为空。auth_ref否覆盖defaults.git.auth_ref。watch_interval否覆盖defaults.git.watch_interval。严格校验宁可失败不可静默降级校验是严格的未知字段、重复资产名和不支持的连接器都会使整个解析失败即使有问题的资产没有被本次执行选择。params内容和 clone URL 安全性针对被选中的资产校验。这些规则与资产定义所在的位置无关——写在 Manifest 的catalog里和写在单独的 Catalog 文件里完全相同。服务端源码以 pydantic 模型落实了这套规则所有模型都基于_StrictModel配置extraforbid, strictTrue见 openviking/server/openviking_assets.py任何未知字段都会触发InvalidArgumentError资产名校验使用正则^[A-Za-z0-9][A-Za-z0-9._-]*$openviking/server/openviking_assets.pywatch_interval必须是有限且不小于 0 的数值openviking/server/openviking_assets.pyinclude非空时服务端解析器直接抛出InvalidArgumentErroropenviking/server/openviking_assets.py。仓库中的服务端测试 tests/server/test_openviking_assets.py 覆盖了未知字段导致解析失败重复资产身份include被拒绝等典型场景可以作为校验行为的可执行规格参考。资产身份稳定且与名称解耦服务端根据以下信息生成稳定的asset_idconnector normalized locator ref具体实现位于 openviking/server/openviking_assets.py对connector\nlocator\ngit_ref三元组计算 SHA-1 并截取前 12 位十六进制作为标识源码注释明确说明这是stable identity, not security。Git URL 的归一化规则normalize_repo_urlopenviking/server/openviking_assets.py会去除协议、用户名前缀、端口、结尾的.git和/并把主机名统一为小写。因此同一仓库的 HTTPS、SSH 和 SCP 风格地址如https://github.com/org/repo.git与gitgithub.com:org/repo通常会得到相同定位符不同分支会得到不同资产因为git_ref参与身份计算。两个重要推论资产名称不参与身份计算。重命名资产但保持来源和分支不变时会继续关联原资源修改来源或分支时会产生新资产旧资源被报告为 orphan孤儿保留但不自动删除。出于安全原因clone URL 不能对应实现见 openviking/server/openviking_assets.py为空或包含控制字符以-开头会被 Git 当作命令行参数使用ext::、fd::等 Git remote-helper 传输格式。多个 Manifest 共享一个 Catalog当多个 Manifest 复用同一批资源时把资产定义移到单独的 Catalog 文件中通常命名为catalog.yaml。Catalog 包含protocol、可选的defaults以及同样的catalog块——一份 Catalog 文件就是一个不做选择的 Manifestprotocol: openviking-assets/1 defaults: git: auth_ref: team-git watch_interval: 60 catalog: - name: openviking connector: git description: OpenViking 主仓库 params: repo_url: https://github.com/volcengine/OpenViking branch: main - name: requests connector: git description: Requests HTTP 客户端源码 watch_interval: 0 params: repo_url: https://github.com/psf/requests branch: main每个 Manifest 只需按名称选择assets: - openviking - requests全团队维护一份 Catalog在 Catalog 中修改资产所有选择它的 Manifest 都会生效。因为两种文档同构Catalog 也可以直接执行ov add-resource -m catalog.yaml会导入它定义的全部资产。CLI 按以下规则查找 Catalog 文件传入--args catalog:file时使用该路径相对路径基于当前工作目录。未传入时读取 Manifest 所在目录下的catalog.yaml。定义了catalog的 Manifest 不使用单独的 Catalog 文件同时传入会导致解析失败服务端解析器会显式抛出InvalidArgumentError见 openviking/server/openviking_assets.py。仓库自带一份可直接运行的共享 Catalog 示例位于 examples/openviking-assets/catalog.yaml它定义了三个资产OpenViking 主仓库、requests、flask通过defaults.git.watch_interval: 1440设置每日刷新并用flask条目演示了watch_interval: 0的逐资产覆盖以及 SSH 地址gitgithub.com:pallets/flask.git与 HTTPS 地址混用的情况对应的按名选择 Manifest 在 examples/openviking-assets/manifest.yaml。快速开始前置条件安装支持 OpenViking Assets 的ovCLI。配置支持/api/v1/openviking-assets/resolve的 OpenViking 服务。确认 CLI 可以连接服务ov health编写并验证 Manifest创建manifest.yamlprotocol: openviking-assets/1 catalog: - name: openviking connector: git params: repo_url: https://github.com/volcengine/OpenViking branch: main先验证ov add-resource --manifest manifest.yaml --args dry_run:truedry_run会完成以下操作读取本地 YAML 文件使用单独 Catalog 文件时一并读取调用当前 OpenViking 服务解析并校验协议检查所有auth_ref是否能在本地解析让服务端使用最终凭据对每个 Git 仓库执行只读git ls-remote权限预检输出每个资产将执行的 create 或 sync 操作不克隆仓库、不提交资源、不创建任务也不写入 State。任何仓库不可读时dry-run 立即以PERMISSION_DENIED退出不再输出可执行计划。应用 Manifest确认计划后去掉dry_runov add-resource --manifest manifest.yaml等待每个资源处理完成ov add-resource --manifest manifest.yaml --wait --timeout 600从源码理解 dry-run 的预检链路dry-run 的权限预检并非本地模拟而是真实地走到服务端执行。HTTP 端点定义在 openviking/server/routers/openviking_assets.pyPOST /api/v1/openviking-assets/preflight接收单个已解析资产的repo_url、branch/commit与一次性auth_config然后调用preflight_git_repository。服务端预检的实现openviking/server/openviking_assets.py有几个值得注意的工程细节通过子进程执行git ls-remote --exit-code repo_url并设置GIT_TERMINAL_PROMPT0、GCM_INTERACTIVENever、GIT_SSH_COMMANDssh -o BatchModeyes确保任何情况下都不会弹出交互式凭据提示传入 token 时通过进程级GIT_CONFIG_*环境变量注入 HTTP Basic 认证token 不会出现在 Git 命令行参数中指定了 branch 时同时校验refs/heads/branch与refs/tags/branch固定 commit 时由于ls-remote无法证明历史 commit 可达只对远端HEAD做仓库级可达性校验精确 SHA 由后续导入流水线在 fetch/checkout 时验证预检默认超时15 秒GIT_PREFLIGHT_TIMEOUT_SECONDS 15.0openviking/server/openviking_assets.py超时抛DEADLINE_EXCEEDED错误被精细分类网络类错误DNS、连接拒绝、超时等见_NETWORK_FAILURE_PATTERNS映射为UNAVAILABLEbranch 不存在映射为NOT_FOUND其余权限问题统一映射为PERMISSION_DENIED对应 API 文档 docs/zh/api/22-openviking-assets.md 中的错误表。凭据管理只存别名不存密钥Manifest 和 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.yamlCLI 端的凭据解析实现在 crates/ov_cli/src/openviking_assets.rs默认路径为$HOME/.openviking/openviking_assets_credentials.yaml环境变量OPENVIKING_ASSETS_CREDENTIALS_FILE优先文件不存在时视为空映射。原生 Git 凭据别名只支持username和token并保持扁平结构deny_unknown_fields。执行前CLI 会先解析所有选中资产的auth_ref然后由服务端在实际执行环境中用git ls-remote校验每个仓库的读取权限。只要有一个别名不存在或仓库不可读整个操作都会在提交任何资源之前失败dry_run也执行相同预检。使用默认的原生 Git 链路时CLI 会在调用add_resource时把解析出的凭据放入args.auth_config而branch或commit仍留在args顶层。解析出的 Git 参数会通过当前配置的 OpenViking 服务连接发送因此远程部署应使用 TLS并限制凭据文件的本地访问权限。关于 token 的生命周期协议还有几条明确约定当最终watch_interval大于0时OpenViking 会把通过auth_ref解析出的 HTTPS Git token 保存到 Watch task 私有且与仓库 URL 绑定的鉴权状态中。token不会写入 Manifest State、普通入库队列或 Watch API/MCP/CLI 返回周期为0时token 只在本次请求内使用Git PAT 没有通用刷新流程token 过期或被撤销后需要重建 WatchWatch 私有状态保存在viking://resources/.watch_tasks.json。启用 VikingFS 文件加密时会静态加密否则服务端控制文件及其备份包含明文 token 状态生产环境应限制服务端存储访问并启用加密即使没有指定--wait原生凭据导入也需要等 clone 和 parse 完成后服务端才会返回 task因此 CLI 对这类资产默认使用 300 秒请求超时源码常量NATIVE_AUTH_REQUEST_TIMEOUT_SECONDS 300.0见 crates/ov_cli/src/openviking_assets.rs大仓库可通过--timeout 秒调大token 会放在 HTTPS 请求体中传输生产环境应保持诊断请求体 dump 关闭。如果目标服务已经具备访问仓库所需的 SSH key 或其他认证配置可以不设置auth_ref——示例 examples/openviking-assets/catalog.yaml 中的 flask 资产SSH 地址就是这种形态。Create、Sync 与 State非 dry-run 执行后CLI 在 Manifest 旁写入manifest-file.state.json例如manifest.yaml.state.jsonState 使用openviking-assets-state/1协议常量定义于 crates/ov_cli/src/openviking_assets.rs记录asset_id、名称、连接器、定位符和 ref对应的resource_uri和task_id最近一次执行状态、错误和时间。执行规则条件行为State 中没有该asset_id的资源 URIcreate创建新资源。State 中已有资源 URIsync把 URI 作为to再次调用add_resource。资产不再被 Manifest 选择报告 orphan保留资源和 State不自动删除。asset_id因来源或分支变化创建新资产旧资产成为 orphan。CLI 端对 orphan 的处理crates/ov_cli/src/openviking_assets.rs会输出事件日志并保留资源与 State 条目——v1 策略是永不自动删除。State 属于执行环境不是 Catalog 或 Manifest 协议的一部分。共享 Manifest 仓库通常应在.gitignore中加入*.state.json注意不要并发执行同一个 Manifest当前 State 文件不提供跨进程锁。内容级同步进度不保存在 Manifest State 中持续刷新由 OpenViking Watch 和连接器负责。更新周期watch_interval 的优先级watch_interval的优先级从高到低为CLI 的--watch-interval单个资产的watch_intervaldefaults.git.watch_interval0不自动刷新。例如临时把 Manifest 中全部资产调整为每 60 分钟刷新ov add-resource --manifest manifest.yaml --watch-interval 60后续内容刷新由 Watch 执行。原生 HTTPS Git 资产使用auth_ref时服务端会在每次刷新时从 Watch 私有状态恢复与仓库绑定的 token。重新运行 Manifest 仍可用于应用 Catalog/Manifest 构成变化、恢复失败资产或显式触发同步。失败处理预检优先fail-fast 可选权限预检阶段权限预检先于所有资源提交。任一资产预检失败时命令立即以原始错误码退出例如PERMISSION_DENIED不提交任何资产不创建后台任务不写入 Stateskip_failed不会跳过预检失败。这一点在 CLI 源码中有显式注释crates/ov_cli/src/openviking_assets.rs权限预检失败会立即中止即使设置了skip_failed也一样。逐资产执行阶段只有全部预检成功后才进入逐资产执行阶段。默认采用 fail-fast当前资产失败后续资产标记为未尝试已成功资产和失败记录写入 State命令以非零状态退出。使用skip_failed可以继续处理其余资产ov add-resource --manifest manifest.yaml --args skip_failed:trueskip_failed不会把部分失败转换为成功只要有资产失败命令最终仍以非零状态退出已经成功的资源不会回滚。全部资产失败时命令会报告没有任何资产成功应用。命令行选项速查与--manifest搭配使用的参数参数说明-m, --manifest fileManifest 文件。--args key:value,...Manifest 运行选项多个选项用逗号分隔支持的键见下表。--wait等待每个资源处理完成。--timeout secondsHTTP 请求超时。原生私有 Git 即使没有--wait也会使用该值默认 300 秒。--watch-interval minutes覆盖全部资产的更新周期。--args支持的运行选项键说明catalog:file按名称选择资产的 Manifest 使用的单独 Catalog 文件省略时使用 Manifest 同目录的catalog.yaml。Manifest 自身定义了catalog时不使用。dry_run:true解析协议并校验所有仓库的读取权限不提交资源、不创建任务、不写 State。skip_failed:true一个资产失败后继续处理其他资产。--args既支持key:value,...逗号分隔形式也支持整段 JSON 对象例如ov add-resource -m manifest.yaml --args {dry_run: true, catalog: shared/catalog.yaml}运行选项由 CLI 在本地消费不会作为资源参数发送给服务端未知的键会直接报错。当前限制openviking-assets/1当前具有以下边界只支持 Git 资产Manifest 必须平铺不支持递归include服务端 resolver 只返回计划不执行批量提交服务端 preflight 通过只读git ls-remote校验仓库权限不下载仓库内容CLI 按顺序逐个执行资产不自动删除 orphan不包含ov share指针码或从现有知识库导出 Manifest 的能力State 是本地文件不在多台机器之间自动同步CLI 和服务端都必须支持同一协议版本。相关文档OpenViking Assets API资源管理 API资源 Watch APIOVPack 导入导出OpenViking Assets 示例catalog.yamlOpenViking Assets 示例manifest.yaml【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenViking Assets 指南：用 Manifest 声明式管理 AI Agent 知识库资源
OpenViking Assets 指南用 Manifest 声明式管理 AI Agent 知识库资源【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking本指南依据仓库中 docs/zh/guides/18-openviking-assets.md 展开并结合服务端解析器 openviking/server/openviking_assets.py、CLI 实现 crates/ov_cli/src/openviking_assets.rs 与仓库内完整示例 examples/openviking-assets/ 进行纵深说明。OpenViking Assets 是 OpenViking 提供的一套声明式知识库构建方案用一份 Manifest 文件描述一个知识库应该由哪些资源组成再交给 OpenViking 逐项创建或更新资源。本文面向需要重复构建、持续更新资源集合的团队如多仓代码问答库、团队文档集完整覆盖openviking-assets/1协议的 Manifest/Catalog/State 概念模型、完整配置示例、凭据与权限预检、dry-run 验证、ov add-resource -m命令行操作及失败处理策略。读完本文你将能独立编写并验证自己的 Manifest把资源集合变成可 review、可共享、可重复执行的工程资产。实验性功能提示openviking-assets/1协议和命令行行为仍可能在后续版本中调整请以当前仓库实现为准。OpenViking Assets 在资源体系中的定位在 OpenViking 中接入外部内容有三种途径它们解决的层次完全不同能力描述ov add-resource source添加或更新一个资源描述的是一次资源操作。OpenViking Assets声明一组资源的预期构成可以 review、共享并重复执行。OVPack导出或导入已经生成的数据快照搬运的是内容和可选索引数据。OpenViking Assets不替代现有资源处理流程。Git 拉取、内容解析、语义提取、向量化和 Watch 更新仍由add_resource及服务端连接器完成Assets 只增加声明、解析和逐项编排这一层。也就是说Assets 是编排层add_resource是执行层两者各司其职。概念模型Manifest、Catalog 与 StateOpenViking Assets 由三个主要对象构成Manifest实际执行的文件。可以在catalog:下直接定义要接入的资产也可以按名称从单独的 Catalog 文件中选择资产。Catalog团队可接入资源的目录包含来源、分支、默认更新周期和凭据别名。只有在多个 Manifest 需要共享时才作为单独文件存在否则直接写在 Manifest 里。State某个 Manifest 上次执行的结果以及资产到viking://资源的映射。三者协作的完整流程如下manifest.yaml使用共享 Catalog 时再加 catalog.yaml | v 服务端解析和校验 openviking-assets/1 | v Resolved Assets | v CLI 解析本地凭据和 State | v 逐个调用 add_resource - viking:// resources这里有一个重要的职责划分服务端是协议解析的权威实现。CLI 会把 Manifest 的原始 YAML使用单独 Catalog 文件时一并发送 Catalog YAML发送到当前配置的 OpenViking 服务由服务端完成严格校验并返回执行计划服务端的解析接口本身不会创建资源。这一点在源码中得到印证HTTP 路由 openviking/server/routers/openviking_assets.py 中的/api/v1/openviking-assets/resolve端点只调用resolve_openviking_assets完成解析与校验并返回结果注释明确写着Parse and validate configuration without submitting resources而 CLI 端Rust 实现 crates/ov_cli/src/openviking_assets.rs同样注明服务端拥有 openviking-assets 语法解析与语义校验的权威实现CLI 只接收已解析的执行计划。协议详解ManifestManifest 描述一次知识库构建。最简单的形态下它是唯一需要的文件——在catalog:下直接定义资产protocol: openviking-assets/1 defaults: git: auth_ref: team-git watch_interval: 60 catalog: - name: openviking connector: git description: OpenViking 主仓库 params: repo_url: https://github.com/volcengine/OpenViking branch: main - name: requests connector: git description: Requests HTTP 客户端源码 watch_interval: 0 params: repo_url: https://github.com/psf/requests branch: main assets: [openviking] # 可选省略 执行上面定义的全部资产Manifest 顶层字段字段必填说明protocol定义catalog时必填当前必须为openviking-assets/1只按名称选择资产的 Manifest 可省略但设置时同样会校验。defaults否为本文件定义的资产设置连接器级默认值只能与catalog一起使用。catalog否资产定义列表字段见下。定义了catalog的 Manifest 自身就是完整配置。assets见说明要执行的资产名称。catalog在同一文件中时可省略——省略表示执行全部定义的资产资产定义在单独 Catalog 文件中时必填。include否v1 不支持组合其他 Manifest非空时解析失败。重复的资产名称会按首次出现的位置去重。选择不存在的资产时整个解析失败。defaults.git与 Git 资产字段defaults.git支持字段说明auth_ref本地凭据文件中的默认别名。watch_interval默认 Watch 周期单位为分钟0表示不自动刷新。Git 资产catalog下的每个条目支持字段必填说明name是唯一资产名称必须匹配[A-Za-z0-9][A-Za-z0-9._-]*。connector是v1 只支持git。description否资产用途说明。params.repo_url是Git clone URL。params.branch否要接入的分支设置时不能为空。auth_ref否覆盖defaults.git.auth_ref。watch_interval否覆盖defaults.git.watch_interval。严格校验宁可失败不可静默降级校验是严格的未知字段、重复资产名和不支持的连接器都会使整个解析失败即使有问题的资产没有被本次执行选择。params内容和 clone URL 安全性针对被选中的资产校验。这些规则与资产定义所在的位置无关——写在 Manifest 的catalog里和写在单独的 Catalog 文件里完全相同。服务端源码以 pydantic 模型落实了这套规则所有模型都基于_StrictModel配置extraforbid, strictTrue见 openviking/server/openviking_assets.py任何未知字段都会触发InvalidArgumentError资产名校验使用正则^[A-Za-z0-9][A-Za-z0-9._-]*$openviking/server/openviking_assets.pywatch_interval必须是有限且不小于 0 的数值openviking/server/openviking_assets.pyinclude非空时服务端解析器直接抛出InvalidArgumentErroropenviking/server/openviking_assets.py。仓库中的服务端测试 tests/server/test_openviking_assets.py 覆盖了未知字段导致解析失败重复资产身份include被拒绝等典型场景可以作为校验行为的可执行规格参考。资产身份稳定且与名称解耦服务端根据以下信息生成稳定的asset_idconnector normalized locator ref具体实现位于 openviking/server/openviking_assets.py对connector\nlocator\ngit_ref三元组计算 SHA-1 并截取前 12 位十六进制作为标识源码注释明确说明这是stable identity, not security。Git URL 的归一化规则normalize_repo_urlopenviking/server/openviking_assets.py会去除协议、用户名前缀、端口、结尾的.git和/并把主机名统一为小写。因此同一仓库的 HTTPS、SSH 和 SCP 风格地址如https://github.com/org/repo.git与gitgithub.com:org/repo通常会得到相同定位符不同分支会得到不同资产因为git_ref参与身份计算。两个重要推论资产名称不参与身份计算。重命名资产但保持来源和分支不变时会继续关联原资源修改来源或分支时会产生新资产旧资源被报告为 orphan孤儿保留但不自动删除。出于安全原因clone URL 不能对应实现见 openviking/server/openviking_assets.py为空或包含控制字符以-开头会被 Git 当作命令行参数使用ext::、fd::等 Git remote-helper 传输格式。多个 Manifest 共享一个 Catalog当多个 Manifest 复用同一批资源时把资产定义移到单独的 Catalog 文件中通常命名为catalog.yaml。Catalog 包含protocol、可选的defaults以及同样的catalog块——一份 Catalog 文件就是一个不做选择的 Manifestprotocol: openviking-assets/1 defaults: git: auth_ref: team-git watch_interval: 60 catalog: - name: openviking connector: git description: OpenViking 主仓库 params: repo_url: https://github.com/volcengine/OpenViking branch: main - name: requests connector: git description: Requests HTTP 客户端源码 watch_interval: 0 params: repo_url: https://github.com/psf/requests branch: main每个 Manifest 只需按名称选择assets: - openviking - requests全团队维护一份 Catalog在 Catalog 中修改资产所有选择它的 Manifest 都会生效。因为两种文档同构Catalog 也可以直接执行ov add-resource -m catalog.yaml会导入它定义的全部资产。CLI 按以下规则查找 Catalog 文件传入--args catalog:file时使用该路径相对路径基于当前工作目录。未传入时读取 Manifest 所在目录下的catalog.yaml。定义了catalog的 Manifest 不使用单独的 Catalog 文件同时传入会导致解析失败服务端解析器会显式抛出InvalidArgumentError见 openviking/server/openviking_assets.py。仓库自带一份可直接运行的共享 Catalog 示例位于 examples/openviking-assets/catalog.yaml它定义了三个资产OpenViking 主仓库、requests、flask通过defaults.git.watch_interval: 1440设置每日刷新并用flask条目演示了watch_interval: 0的逐资产覆盖以及 SSH 地址gitgithub.com:pallets/flask.git与 HTTPS 地址混用的情况对应的按名选择 Manifest 在 examples/openviking-assets/manifest.yaml。快速开始前置条件安装支持 OpenViking Assets 的ovCLI。配置支持/api/v1/openviking-assets/resolve的 OpenViking 服务。确认 CLI 可以连接服务ov health编写并验证 Manifest创建manifest.yamlprotocol: openviking-assets/1 catalog: - name: openviking connector: git params: repo_url: https://github.com/volcengine/OpenViking branch: main先验证ov add-resource --manifest manifest.yaml --args dry_run:truedry_run会完成以下操作读取本地 YAML 文件使用单独 Catalog 文件时一并读取调用当前 OpenViking 服务解析并校验协议检查所有auth_ref是否能在本地解析让服务端使用最终凭据对每个 Git 仓库执行只读git ls-remote权限预检输出每个资产将执行的 create 或 sync 操作不克隆仓库、不提交资源、不创建任务也不写入 State。任何仓库不可读时dry-run 立即以PERMISSION_DENIED退出不再输出可执行计划。应用 Manifest确认计划后去掉dry_runov add-resource --manifest manifest.yaml等待每个资源处理完成ov add-resource --manifest manifest.yaml --wait --timeout 600从源码理解 dry-run 的预检链路dry-run 的权限预检并非本地模拟而是真实地走到服务端执行。HTTP 端点定义在 openviking/server/routers/openviking_assets.pyPOST /api/v1/openviking-assets/preflight接收单个已解析资产的repo_url、branch/commit与一次性auth_config然后调用preflight_git_repository。服务端预检的实现openviking/server/openviking_assets.py有几个值得注意的工程细节通过子进程执行git ls-remote --exit-code repo_url并设置GIT_TERMINAL_PROMPT0、GCM_INTERACTIVENever、GIT_SSH_COMMANDssh -o BatchModeyes确保任何情况下都不会弹出交互式凭据提示传入 token 时通过进程级GIT_CONFIG_*环境变量注入 HTTP Basic 认证token 不会出现在 Git 命令行参数中指定了 branch 时同时校验refs/heads/branch与refs/tags/branch固定 commit 时由于ls-remote无法证明历史 commit 可达只对远端HEAD做仓库级可达性校验精确 SHA 由后续导入流水线在 fetch/checkout 时验证预检默认超时15 秒GIT_PREFLIGHT_TIMEOUT_SECONDS 15.0openviking/server/openviking_assets.py超时抛DEADLINE_EXCEEDED错误被精细分类网络类错误DNS、连接拒绝、超时等见_NETWORK_FAILURE_PATTERNS映射为UNAVAILABLEbranch 不存在映射为NOT_FOUND其余权限问题统一映射为PERMISSION_DENIED对应 API 文档 docs/zh/api/22-openviking-assets.md 中的错误表。凭据管理只存别名不存密钥Manifest 和 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.yamlCLI 端的凭据解析实现在 crates/ov_cli/src/openviking_assets.rs默认路径为$HOME/.openviking/openviking_assets_credentials.yaml环境变量OPENVIKING_ASSETS_CREDENTIALS_FILE优先文件不存在时视为空映射。原生 Git 凭据别名只支持username和token并保持扁平结构deny_unknown_fields。执行前CLI 会先解析所有选中资产的auth_ref然后由服务端在实际执行环境中用git ls-remote校验每个仓库的读取权限。只要有一个别名不存在或仓库不可读整个操作都会在提交任何资源之前失败dry_run也执行相同预检。使用默认的原生 Git 链路时CLI 会在调用add_resource时把解析出的凭据放入args.auth_config而branch或commit仍留在args顶层。解析出的 Git 参数会通过当前配置的 OpenViking 服务连接发送因此远程部署应使用 TLS并限制凭据文件的本地访问权限。关于 token 的生命周期协议还有几条明确约定当最终watch_interval大于0时OpenViking 会把通过auth_ref解析出的 HTTPS Git token 保存到 Watch task 私有且与仓库 URL 绑定的鉴权状态中。token不会写入 Manifest State、普通入库队列或 Watch API/MCP/CLI 返回周期为0时token 只在本次请求内使用Git PAT 没有通用刷新流程token 过期或被撤销后需要重建 WatchWatch 私有状态保存在viking://resources/.watch_tasks.json。启用 VikingFS 文件加密时会静态加密否则服务端控制文件及其备份包含明文 token 状态生产环境应限制服务端存储访问并启用加密即使没有指定--wait原生凭据导入也需要等 clone 和 parse 完成后服务端才会返回 task因此 CLI 对这类资产默认使用 300 秒请求超时源码常量NATIVE_AUTH_REQUEST_TIMEOUT_SECONDS 300.0见 crates/ov_cli/src/openviking_assets.rs大仓库可通过--timeout 秒调大token 会放在 HTTPS 请求体中传输生产环境应保持诊断请求体 dump 关闭。如果目标服务已经具备访问仓库所需的 SSH key 或其他认证配置可以不设置auth_ref——示例 examples/openviking-assets/catalog.yaml 中的 flask 资产SSH 地址就是这种形态。Create、Sync 与 State非 dry-run 执行后CLI 在 Manifest 旁写入manifest-file.state.json例如manifest.yaml.state.jsonState 使用openviking-assets-state/1协议常量定义于 crates/ov_cli/src/openviking_assets.rs记录asset_id、名称、连接器、定位符和 ref对应的resource_uri和task_id最近一次执行状态、错误和时间。执行规则条件行为State 中没有该asset_id的资源 URIcreate创建新资源。State 中已有资源 URIsync把 URI 作为to再次调用add_resource。资产不再被 Manifest 选择报告 orphan保留资源和 State不自动删除。asset_id因来源或分支变化创建新资产旧资产成为 orphan。CLI 端对 orphan 的处理crates/ov_cli/src/openviking_assets.rs会输出事件日志并保留资源与 State 条目——v1 策略是永不自动删除。State 属于执行环境不是 Catalog 或 Manifest 协议的一部分。共享 Manifest 仓库通常应在.gitignore中加入*.state.json注意不要并发执行同一个 Manifest当前 State 文件不提供跨进程锁。内容级同步进度不保存在 Manifest State 中持续刷新由 OpenViking Watch 和连接器负责。更新周期watch_interval 的优先级watch_interval的优先级从高到低为CLI 的--watch-interval单个资产的watch_intervaldefaults.git.watch_interval0不自动刷新。例如临时把 Manifest 中全部资产调整为每 60 分钟刷新ov add-resource --manifest manifest.yaml --watch-interval 60后续内容刷新由 Watch 执行。原生 HTTPS Git 资产使用auth_ref时服务端会在每次刷新时从 Watch 私有状态恢复与仓库绑定的 token。重新运行 Manifest 仍可用于应用 Catalog/Manifest 构成变化、恢复失败资产或显式触发同步。失败处理预检优先fail-fast 可选权限预检阶段权限预检先于所有资源提交。任一资产预检失败时命令立即以原始错误码退出例如PERMISSION_DENIED不提交任何资产不创建后台任务不写入 Stateskip_failed不会跳过预检失败。这一点在 CLI 源码中有显式注释crates/ov_cli/src/openviking_assets.rs权限预检失败会立即中止即使设置了skip_failed也一样。逐资产执行阶段只有全部预检成功后才进入逐资产执行阶段。默认采用 fail-fast当前资产失败后续资产标记为未尝试已成功资产和失败记录写入 State命令以非零状态退出。使用skip_failed可以继续处理其余资产ov add-resource --manifest manifest.yaml --args skip_failed:trueskip_failed不会把部分失败转换为成功只要有资产失败命令最终仍以非零状态退出已经成功的资源不会回滚。全部资产失败时命令会报告没有任何资产成功应用。命令行选项速查与--manifest搭配使用的参数参数说明-m, --manifest fileManifest 文件。--args key:value,...Manifest 运行选项多个选项用逗号分隔支持的键见下表。--wait等待每个资源处理完成。--timeout secondsHTTP 请求超时。原生私有 Git 即使没有--wait也会使用该值默认 300 秒。--watch-interval minutes覆盖全部资产的更新周期。--args支持的运行选项键说明catalog:file按名称选择资产的 Manifest 使用的单独 Catalog 文件省略时使用 Manifest 同目录的catalog.yaml。Manifest 自身定义了catalog时不使用。dry_run:true解析协议并校验所有仓库的读取权限不提交资源、不创建任务、不写 State。skip_failed:true一个资产失败后继续处理其他资产。--args既支持key:value,...逗号分隔形式也支持整段 JSON 对象例如ov add-resource -m manifest.yaml --args {dry_run: true, catalog: shared/catalog.yaml}运行选项由 CLI 在本地消费不会作为资源参数发送给服务端未知的键会直接报错。当前限制openviking-assets/1当前具有以下边界只支持 Git 资产Manifest 必须平铺不支持递归include服务端 resolver 只返回计划不执行批量提交服务端 preflight 通过只读git ls-remote校验仓库权限不下载仓库内容CLI 按顺序逐个执行资产不自动删除 orphan不包含ov share指针码或从现有知识库导出 Manifest 的能力State 是本地文件不在多台机器之间自动同步CLI 和服务端都必须支持同一协议版本。相关文档OpenViking Assets API资源管理 API资源 Watch APIOVPack 导入导出OpenViking Assets 示例catalog.yamlOpenViking Assets 示例manifest.yaml【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考