企业官网建设流程全解析

OpenViking Assets：如何用 Manifest 和 Catalog 声明并重复构建团队知识库资源集

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

OpenViking Assets 用声明文件描述"一个知识库应该由哪些资源组成"，让你把一组 Git 仓库的接入方式写进文件里，团队可以 review、共享并反复执行来重建知识库。这篇文档面向的场景是：你需要把多仓代码问答库、团队文档集这类需要重复构建、持续更新的资源集合管理起来，而不是每次手动敲ov add-resource <source>。适用前提是：openviking-assets/1是实验性功能，协议和命令行行为仍可能在后续版本中调整；v1 只支持 Git 资产，Manifest 必须平铺、不支持递归include。

先分清 Manifest、Catalog 和 State

OpenViking Assets 包含三个对象，理解它们的分工能决定你用单文件还是多文件：

• Manifest：实际执行的文件。可以在catalog:下直接定义要接入的资产，也可以按名称从单独的 Catalog 文件中选择资产。
• Catalog：团队可接入资源的目录，包含来源、分支、默认更新周期和凭据别名。只有在多个 Manifest 需要共享时才作为单独文件存在，否则直接写在 Manifest 里。
• State：某个 Manifest 上次执行的结果，以及资产到viking://资源的映射。

服务端是协议解析的权威实现：CLI 会把 Manifest 的原始 YAML（使用单独 Catalog 文件时一并发送 Catalog YAML）发送到当前配置的 OpenViking 服务，由服务端完成严格校验并返回执行计划；服务端的解析接口本身不会创建资源。

前置条件

1. 安装支持 OpenViking Assets 的ovCLI。
2. 配置支持/api/v1/openviking-assets/resolve的 OpenViking 服务。
3. 确认 CLI 可以连接服务：

ov health

最短路径：单文件 Manifest

最简单的形态下 Manifest 是唯一需要的文件，在catalog:下直接定义资产。创建manifest.yaml：

protocol: 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:true

dry_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-assets：catalog.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 Q&A 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: git@github.com:pallets/flask.git branch: main

每个 Manifest 只需按名称选择资产，例如manifest.yaml：

assets: - openviking - flask

全团队维护一份 Catalog；在 Catalog 中修改资产，所有选择它的 Manifest 都会生效。Catalog 也可以直接执行：ov add-resource -m catalog.yaml会导入它定义的全部资产。

CLI 按以下规则查找 Catalog 文件：

1. 传入--args catalog:<file>时使用该路径，相对路径基于当前工作目录。
2. 未传入时读取 Manifest 所在目录下的catalog.yaml。

定义了catalog的 Manifest 不使用单独的 Catalog 文件；同时传入会导致解析失败。

凭据：只存别名，不存 token

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.yaml

执行前，CLI 先解析所有选中资产的auth_ref，然后由服务端在实际执行环境中用git ls-remote校验每个仓库的读取权限。只要有一个别名不存在或仓库不可读，整个操作都会在提交任何资源之前失败，dry_run也执行相同预检。如果目标服务已经具备访问仓库所需的 SSH key 或其他认证配置，可以不设置auth_ref。解析出的 Git 参数会通过当前配置的 OpenViking 服务连接发送，因此远程部署应使用 TLS，并限制凭据文件的本地访问权限。

重复构建靠 State：create / sync / orphan

非 dry-run 执行后，CLI 会在 Manifest 旁写入 State 文件，例如manifest.yaml.state.json。State 使用openviking-assets-state/1协议，记录asset_id、名称、连接器、定位符和 ref、对应的resource_uri和task_id，以及最近一次执行状态、错误和时间。重复执行时按以下规则判定：

服务端根据connector + normalized locator + ref生成稳定的asset_id；Git URL 会去除协议、用户名前缀、端口、结尾的.git和/，并把主机名统一为小写。资产名称不参与身份计算——重命名资产但保持来源和分支不变时，会继续关联原资源；修改来源或分支时会产生新资产，旧资源被报告为 orphan。

State 属于执行环境，不是 Catalog 或 Manifest 协议的一部分。共享 Manifest 仓库通常应在.gitignore中加入*.state.json。不要并发执行同一个 Manifest；当前 State 文件不提供跨进程锁。

更新周期 watch_interval

watch_interval的优先级从高到低为：

1. CLI 的--watch-interval；
2. 单个资产的watch_interval；
3. defaults.git.watch_interval；
4. 0，不自动刷新。

例如，临时把 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）；不提交任何资产、不创建后台任务、不写入 State；skip_failed不会跳过预检失败。

只有全部预检成功后，才进入逐资产执行阶段。默认采用 fail-fast：当前资产失败、后续资产标记为未尝试、已成功资产和失败记录写入 State、命令以非零状态退出。需要某个资产失败后继续处理其余资产时：

ov add-resource --manifest manifest.yaml --args skip_failed:true

skip_failed不会把部分失败转换为成功：只要有资产失败，命令最终仍以非零状态退出；已经成功的资源不会回滚。全部资产失败时，命令会报告没有任何资产成功应用。

当前限制

• 只支持 Git 资产；Manifest 必须平铺，不支持递归include。
• 服务端 resolver 只返回计划，不执行批量提交；CLI 按顺序逐个执行资产。
• preflight 通过只读git ls-remote校验仓库权限，不下载仓库内容。
• 不自动删除 orphan；State 是本地文件，不在多台机器之间自动同步。
• 不包含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 指南。

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