OpenViking Assets Resolver API 实战指南Manifest 解析与 Git 权限预检【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking本指南以 OpenViking 的 OpenViking Assets 声明式资产体系为背景围绕openviking-assets/1协议的两个核心 HTTP 端点——POST /api/v1/openviking-assets/resolveManifest 解析校验与POST /api/v1/openviking-assets/preflightGit 仓库只读访问预检——讲解其请求/响应契约、错误语义与底层实现原理。读完本文你将掌握如何直接调用 Resolver 端点完成 Manifest 的解析与验证、如何对私有 Git 仓库执行安全的权限预检并理解ov add-resource --manifest命令背后的完整调用链与安全设计。说明正常情况下你不需要直接调用这些端点——运行ov add-resource --manifest file时CLI 会自动调用 Resolver 与权限预检端点。仅当你在实现自定义客户端时才需要以本文契约直接调用它们。一、OpenViking Assets 与 Resolver 的定位OpenViking Assets 用声明式文件描述一个知识库应该包含什么最简形式下一个 Manifest 文件直接定义要摄入的资产assets团队也可以把可摄入源集中维护在一个共享 Catalog 中再由多个 Manifest 按名称挑选资产。应用 Manifest 时CLI 会为每个资产调用add_resource创建或更新对应资源并把资产与viking://资源的映射保存在本地。在这一体系中服务端是权威的协议解析器manifest.yaml ( catalog.yaml 当使用共享 Catalog 时) | v Server 解析并校验 openviking-assets/1 | v Resolved Assets标准化执行计划 | v CLI 解析本地凭据与 State | v 每个资产一次 add_resource 调用 - viking:// 资源Resolver 端点只负责解析与校验——它不会 clone 仓库、不会创建资源、也不会启动同步任务执行计划由客户端负责落地。这正是 docs/en/guides/18-openviking-assets.md 中服务器返回执行计划Resolver 端点本身不创建资源的设计。二、Resolve 端点解析并校验 Manifest2.1 端点与鉴权POST /api/v1/openviking-assets/resolve该端点使用 OpenViking Server 标准鉴权机制。当启用 API Key 鉴权时需携带请求头X-API-Key: your-api-key从源码看端点在 openviking/server/routers/openviking_assets.py 中注册于前缀/api/v1/openviking-assets通过Depends(get_request_context)获取请求上下文再调用openviking.server.openviking_assets.resolve_openviking_assets完成解析最终以标准信封格式{status: ok, result: ...}返回。2.2 请求体字段字段类型必填默认值说明manifest_yamlstring是—完整 Manifest YAML长度 1–4,000,000 字符catalog_yamlstring否—完整 Catalog YAML长度 1–4,000,000 字符。当 Manifest 按名称选择资产时必须提供当 Manifest 在catalog字段下直接定义资产时必须省略manifest_labelstring否manifest.yaml用于错误提示的 Manifest 来源标签1–1,024 字符catalog_labelstring否catalog.yaml用于错误提示的 Catalog 来源标签1–1,024 字符这些约束与 Pydantic 请求模型一一对应ResolveOpenVikingAssetsRequest使用extraforbid拒绝未知字段manifest_yaml与catalog_yaml限制在 1 至 4,000,000 字符两个 label 限制在 1 至 1,024 字符openviking/server/routers/openviking_assets.py。超限、字段类型错误或空值由请求校验层以 HTTP422拒绝。2.3 自包含 Manifest 示例Manifest 直接在其catalog字段下定义资产时请求体只需携带manifest_yamlcurl -X POST ${OPENVIKING_BASE_URL}/api/v1/openviking-assets/resolve \ -H Content-Type: application/json \ -H X-API-Key: ${OPENVIKING_API_KEY} \ --data-binary - JSON { manifest_yaml: protocol: openviking-assets/1\ncatalog:\n - name: openviking\n connector: git\n watch_interval: 1440\n params:\n repo_url: https://github.com/volcengine/OpenViking\n branch: main\n, manifest_label: manifest.yaml } JSON2.4 Manifest 按名称选择资产当 Manifest 只选择名称时例如assets: [openviking, flask]资产定义位于独立的 Catalog 文件中需要把 Catalog YAML 放在catalog_yaml字段、其标签放在catalog_label字段一并提交。仓库中有一个可直接对照的完整示例examples/openviking-assets/catalog.yaml 与 examples/openviking-assets/manifest.yamlcatalog.yaml声明protocol: openviking-assets/1、defaults.git如watch_interval: 1440、以及openviking、requests、flask三个资产定义manifest.yaml只有assets: [openviking, flask]两行按名称从 Catalog 中挑选资产。在 CLI 模式下Catalog 文件的定位顺序为--args catalog:file显式指定相对当前工作目录解析→ 未指定时使用 Manifest 同目录下的catalog.yaml。2.5 成功响应{ status: ok, result: { protocol: openviking-assets/1, manifest: manifest.yaml, catalog: manifest.yaml, assets: [ { name: openviking, connector: git, repo_url: https://github.com/volcengine/OpenViking, branch: main, auth_ref: null, watch_interval: 1440.0, locator: github.com/volcengine/OpenViking, git_ref: main, asset_id: a1b2c3d4e5f6 } ] } }响应字段含义locator标准化后的仓库定位符。Git URL 规范化会移除协议、用户前缀、主机端口、尾部.git与尾部斜杠并将主机名转为小写——因此同一仓库的 HTTPS、SSH、SCP 风格 URL 通常产生相同的 locator而不同分支产生不同的资产。git_ref解析后的 Git 引用分支名或完整 commit SHA。asset_id由 connector、标准化 locator 与 Git 引用派生的稳定 12 位标识符上面示例仅为格式示意。其生成逻辑见 openviking/server/openviking_assets.py对connector\nlocator\ngit_ref做 SHA-1 摘要并取前 12 位十六进制字符。watch_interval以分钟为单位的 Watch 刷新间隔0表示禁用自动刷新。catalog回显catalog_label对自包含 Manifest它等于 Manifest 的 label。测试 tests/server/test_openviking_assets.py 验证了这一逻辑例如gitgithub.com:org/beta.git被规范化为github.com/org/beta而asset_id正是hashlib.sha1(bgit\ngithub.com/org/alpha\nmain).hexdigest()[:12]。2.6 错误响应协议或内容校验失败时返回 HTTP400错误码为INVALID_ARGUMENT。常见原因包括YAML 格式错误或存在未知字段protocol不是openviking-assets/1或 Manifest 定义了catalog却未声明protocolinclude非空v1 不支持 Manifest 组合Manifest 定义了catalog又同时提交了catalog_yamlManifest 按名称选择资产但未提供任何catalog_yamlManifest 引用了 Catalog 中不存在的资产connector、仓库 URL、Git 引用或资产身份无效同一 Manifest 中出现重复的资产身份重复选择名称会被去重并保留首次位置但同一来源解析出相同asset_id的两个资产会报错。空字段、字段类型错误或长度超限则由请求校验以 HTTP422拒绝。从实现看openviking/server/openviking_assets.py解析器通过_StrictModelextraforbid, strictTrue对所有 YAML 结构做严格校验未知字段是错误而非警告未支持的 connector目前仅git即使未被本次选中也会导致整个解析失败params内容与 clone URL 安全性只对选中资产校验。watch_interval必须是非负有限数值params.branch与params.commit互斥commit 必须是完整 40 位十六进制 SHA解析时会统一转为小写。2.7 一个细节to字段与目标 URI 规范化虽然原 API 文档的请求体字段表中未列出但源码中_CatalogAsset还支持可选的to字段精确资源目标 URI。HTTP 调用路径下_normalize_asset_target_uri会复用与add_resource相同的请求边界 URI、命名空间形状与访问检查特别是会把viking://~家目录别名在计划到达 CLI 之前展开。测试 tests/server/test_openviking_assets.py 展示了这一点to: viking://~/resources/repos/private会被规范化为viking://user/alice/resources/repos/private。三、Preflight 端点只读校验 Git 仓库可访问性3.1 端点与职责POST /api/v1/openviking-assets/preflight该端点在 OpenViking Server 执行环境中运行只读的git ls-remote以验证仓库及可选 ref 可读。它不会 clone 仓库、不会创建资源、也不会启动任务。Manifest 模式在 dry-run 与提交前校验两个阶段都会调用它对应apply_manifest_core中先完成所有 preflight再提交第一个资产的顺序见 crates/ov_cli/src/openviking_assets.rs。3.2 请求体字段字段类型必填说明namestring是资产名称connectorstring是当前必须为gitrepo_urlstring是Git clone URLbranchstring否要校验的分支或标签省略时检查远端HEADauth_config.usernamestring否HTTP Basic 用户名默认oauth2auth_config.tokenstring否一次性 Git token绝不持久化Pydantic 模型PreflightOpenVikingAssetRequest还额外支持可选的commit字段完整的 40 位十六进制 SHAopenviking/server/routers/openviking_assets.py。auth_config.token使用SecretStr类型确保 token 不会出现在模型 repr 中。3.3 调用示例私有仓库curl -X POST ${OPENVIKING_BASE_URL}/api/v1/openviking-assets/preflight \ -H Content-Type: application/json \ -H X-API-Key: ${OPENVIKING_API_KEY} \ -d { name: private-repository, connector: git, repo_url: https://github.com/example/private-repository, branch: main, auth_config: { username: oauth2, token: github-token } }当显式提供 token 时preflight不会回退到服务器的 Git 凭据助手。token 通过子进程环境变量传递不会出现在 Git 命令参数或响应中。3.4 成功响应{ status: ok, result: { name: private-repository, connector: git, locator: github.com/example/private-repository, git_ref: main, accessible: true } }3.5 错误响应HTTP 状态码错误码含义403PERMISSION_DENIED仓库不存在、凭据无效或读权限不足404NOT_FOUND仓库可读但请求的分支/标签不存在503UNAVAILABLEDNS、连接或 Git 可执行文件不可用504DEADLINE_EXCEEDED权限预检超过 15 秒3.6 实现原理安全的 git ls-remotepreflight_git_repository的实现非常值得借鉴它是整个资产体系安全性的关键一环URL 安全校验_validate_clone_url拒绝空 URL、含控制字符的 URL、以-开头Git 会把它当参数标志的 URL以及ext::、fd::等 Git remote-helper 传输协议reject_git_http_userinfo拒绝在 URL 内嵌 userinforequire_remote_resource_source拒绝本地路径如file://。token 的强制约束token 认证要求仓库 URL 必须为 HTTPStoken 存在时 username 必须非空。凭据传递设置GIT_TERMINAL_PROMPT0、GCM_INTERACTIVENever、GIT_SSH_COMMANDssh -o BatchModeyes禁用任何交互有 token 时通过build_git_http_auth_env把 HTTP Basic 凭据写入进程级 Git 配置GIT_CONFIG_COUNT机制token 只出现在环境变量中而非命令行参数——测试 tests/server/test_openviking_assets.py 明确断言secret-token不出现在进程参数里而 base64 编码的凭据只存在于GIT_CONFIG_VALUE_*环境变量中。命令构造git ls-remote --exit-code repo_url指定 branch 时追加refs/heads/branch与refs/tags/branch两个引用只给 commit 时则检查HEAD——因为ls-remote无法证明任意历史 commit 可达精确 SHA 由后续导入管道的 fetch/checkout 阶段验证。超时与清理默认 15 秒超时GIT_PREFLIGHT_TIMEOUT_SECONDS 15.0POSIX 下以独立进程组启动start_new_sessionTrue超时或取消时对整个进程组发SIGKILL并限定 1 秒回收时间避免僵尸进程。错误映射根据 stderr 中的网络失败特征串could not resolve host、connection refused等映射为503 UNAVAILABLEgit ls-remote返回码 2 且指定了 branch 时映射为404 NOT_FOUND其余失败一律映射为403 PERMISSION_DENIED。四、CLI 侧的完整调用链ov add-resource --manifest理解端点后再看 CLI 侧的编排会更清晰。ov add-resource --manifest manifest.yaml的完整流程实现于 crates/ov_cli/src/openviking_assets.rs读取本地 Manifest及需要的 Catalog文件内容调用/api/v1/openviking-assets/resolve获得标准化执行计划从本地凭据文件默认~/.openviking/openviking_assets_credentials.yaml可用环境变量OPENVIKING_ASSETS_CREDENTIALS_FILE覆盖解析每个选中资产的auth_ref别名——Manifest 与 Catalog 只携带auth_ref别名绝不能包含 token、密码或私钥对所有资产逐一调用/api/v1/openviking-assets/preflight全部通过后才开始提交按计划为每个资产调用add_resource创建或同步并把结果写入manifest.state.json协议openviking-assets-state/1。关键的行为约束均有对应测试佐证preflight 全量先行任一资产 preflight 失败即整体中止不提交任何资产、不创建任务、不写 Stateskip_failed也无法绕过 preflight 失败crates/ov_cli/src/openviking_assets.rs。失败策略默认 fail-fast——当前资产失败后后续资产标记为 not attempted已成功资产与失败记录写入 State命令以非零码退出--args skip_failed:true可继续处理剩余资产但整体仍以非零码退出且不会回滚已创建的资源crates/ov_cli/src/openviking_assets.rs。dry-run--args dry_run:true会执行解析、凭据解析与完整 preflight并打印每个资产的计划动作create/sync但绝不提交资源、创建任务或写 Statecrates/ov_cli/src/openviking_assets.rs。watch_interval 优先级从高到低CLI--watch-interval 单资产watch_intervaldefaults.git.watch_interval0禁用自动刷新。State 归属State 只属于单一执行环境不属于 Catalog 或 Manifest 协议共享 Manifest 的仓库应把*.state.json加入.gitignore同一 Manifest 不应并发应用State 文件没有跨进程锁。五、端到端验证与快速上手5.1 前置条件安装支持 OpenViking Assets 的ovCLI配置提供/api/v1/openviking-assets/resolve的 OpenViking 服务验证连通性ov health。5.2 编写并校验 Manifest创建manifest.yamlprotocol: openviking-assets/1 catalog: - name: openviking connector: git params: repo_url: https://github.com/volcengine/OpenViking branch: main先校验dry-runov add-resource --manifest manifest.yaml --args dry_run:truedry_run会读取本地 YAML及 Catalog→ 请求服务端解析校验协议 → 检查所有选中auth_ref别名在本地可解析 → 请求服务端对每个仓库用有效凭据执行只读git ls-remote权限预检 → 打印每个资产的 create/sync 计划不会 clone 仓库、提交资源、创建任务或写 State。任一仓库不可读时 dry-run 立即以PERMISSION_DENIED退出不产生可执行计划。5.3 应用 Manifest审查计划后去掉 dry_runov add-resource --manifest manifest.yaml等待每个资源处理完成ov add-resource --manifest manifest.yaml --wait --timeout 6005.4 CLI 选项速查--manifest模式相关选项选项说明-m, --manifest fileManifest 文件--args key:value,...Manifest 运行选项逗号分隔支持键见下--wait等待每个资源处理完成--timeout secondsHTTP 请求超时原生私有 Git 导入即使不加--wait也遵守它默认 300 秒--watch-interval minutes覆盖所有资产的刷新间隔--args支持的运行键在 CLI 本地消费绝不作为资源参数发给服务端未知键报错键说明catalog:file按名称选择资产时的独立 Catalog 文件默认取 Manifest 同目录catalog.yaml。Manifest 自带catalog时不使用dry_run:true只解析协议并校验所有仓库读权限不提交资源、不创建任务、不写 Stateskip_failed:true资产失败后继续处理剩余资产--args既接受key:value,...逗号分隔形式也接受完整 JSON 对象例如--args {dry_run: true, catalog: shared/catalog.yaml}。六、当前协议边界openviking-assets/1目前的限制详见 docs/en/guides/18-openviking-assets.md仅支持 Git 资产Manifest 是扁平的不能递归include其他 Manifest服务端 Resolver 只返回计划不做批量提交服务端 preflight 只做只读git ls-remote检查不下载仓库内容CLI 串行执行资产孤儿资产从 Manifest 移除的资产不会被自动删除暂不包含ov share指针码与从既有知识库导出 ManifestState 是本地文件不跨机器同步CLI 与服务端必须支持同一协议版本。相关文档OpenViking Assets 协议与操作指南资源管理 API资源 Watch APIOVPack 导入与导出服务端实现openviking/server/routers/openviking_assets.py、openviking/server/openviking_assets.pyCLI 实现crates/ov_cli/src/openviking_assets.rs测试用例tests/server/test_openviking_assets.py完整示例examples/openviking-assets/【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考