[RFC] OpenViking Assets：把 Resource 的构成写成一份清单

[zihengli-bytedance]

目标：定义一套资产集描述协议（OpenViking Assets），把"一个知识库应该由什么组成"变成一份可声明、可 review、可分享、可重复执行的清单。
OpenViking 已经解决了"怎么存、怎么更新、怎么检索"，需要有个协议补上前面那一步——库的构成本身成为一等工件，对标 Dockerfile 之于运行环境、package.json 之于依赖。

---

1. 背景与动机

在一次多仓库代码问答的实践中，我们把 150 多个业务仓库和依赖仓库提前导入 OpenViking，让 Agent 用语义检索补充上下文。一次覆盖 157 个仓库、10 个问题的评测中，只看本地代码得 4 分，接上 OpenViking 检索后到 8 分。这说明除了模型能力之外，上下文的组织和检索是一个重要瓶颈：Agent 很难在大量仓库里自己找到真正相关的信息。

但建库这一步目前基本靠人：整理仓库列表、写脚本逐个调 add_resource、仓库变了再手工维护更新任务。换一个团队、换一套环境，这些活要重做一遍。由此产生三个长期问题：

1. 构建不可复现：知识库建成后即黑盒终态，没人说得清它由什么构成、怎么重建、哪些内容已过期。
2. 构成无法流转：数据本身受权限和体积限制不能随意复制，但"库由什么组成"这个描述其实是可以分享的——现在它散落在脚本和口头交接里。
3. 静默腐烂：源头的代码和文档天天变，库没有对账基准，偏差无法被发现。

OpenViking Assets 要解决的就是：这套库由什么组成，这件事本身能不能被 review、分享、重新执行。

2. 概念模型

想象你收藏了几百张 CD。管好它们只需要三样东西：

• 一份收藏清单：每张 CD 的专辑名、条码、放在哪个架子。这是 Catalog——你有哪些资产。
• 几张歌单：派对放这十张，写代码放那五张。歌单只引用收藏清单里的条目。这是 Manifest——这一次用哪些。
• 每张 CD 里夹的书签：上次听到第几轨。这是 State——每个资产同步到了哪里。

把歌单发给朋友，他拿到的只是"听什么"的描述，碟得自己去买或去借，版权在各自手里。OpenViking Assets 的分享方式相同：清单可以在合适的协作范围内分享，数据和权限不跟着走。条码用来区分来源和版本不同的唱片—— 每个资产也有一个由"连接器类型 + 归一化定位符"算出的稳定身份，同名不同源不会混。

知识库里的资产比 CD 复杂——是代码仓库、文档、订阅源——但管理逻辑一样。

3. 协议原型

3.1 资产目录（Catalog）

登记团队所有可接入的资源，全团队只维护一份。字段与 OpenViking 数据连接器插件的参数模型对齐，插件已有的参数校验能力可以直接复用。这些描述本身就是上下文，建库时可以一并进库：

# assets.yaml —— 资产目录：团队有哪些资源
protocol: OpenVikingAssets/1

defaults:
  git:
    auth_ref: team-git       # git 类资产的默认凭证别名，可逐条覆盖

assets:
  - name: openviking
    connector: git
    description: OpenViking 主仓库，包含服务端、CLI 与 SDK
    params:
      repo_url: https://github.com/volcengine/OpenViking
      branch: main

  - name: openviking-dev
    connector: git
    description: 同一仓库的开发分支——和上一条是两个不同的资产
    params:
      repo_url: https://github.com/volcengine/OpenViking
      branch: develop

  - name: team-blog
    connector: rss
    description: 团队技术博客订阅源，设计决策和复盘都在这
    params:
      feed_url: https://example.com/blog/feed.xml

关键点：

• 凭证不入清单。连接器插件从设计上就把鉴权配置和连接参数分开，目录里只出现别名 auth_ref，真实凭证留在使用者本地的凭证配置里。这是"清单可分享"能成立的前提。
• 资产身份由 connector + 归一化定位符 + ref 计算，同一仓库的不同分支是两条独立资产，满足对账、增量更新和安全删除的需求。
• description 是协议字段而非注释。它承载"这个资产是什么、为什么在库里"的上下文，建库时可以随内容一并入库。

3.2 建库清单（Manifest）

按名字从目录里挑出这一次要用的，也可以用 include 组合别的清单。这个文件只有资源引用和参数，不保存真实凭证：

# manifests/code-qa.yaml —— 代码问答库用哪些资产
include:
  - base-repos.yaml        # 先引入另一份清单的仓库组合

assets:
  - openviking-dev
  - team-blog

组合规则：

• include 递归展开，限制深度，按资产名去重，先出现者优先（first-wins），冲突时输出告警。
• 清单可以有很多份：代码问答库一份、新人 onboarding 一份，各自引用同一批资产；资产定义变了只改目录一处，所有清单跟着生效。
• 未知字段一律直接报错，不做静默忽略。宁可让一份写错的清单立刻失败，也不让配置静默失效后慢慢腐烂。

3.3 客户端命令

命令寄生在现有 ov CLI 中，不引入独立二进制：

• ov add-resource -m manifest.yaml：按清单建库。可重复执行——第一次是创建，之后是同步：清单里新增的资源去创建，移除的按删除保护流程处理。
• ov share -m manifest.yaml（后续阶段）：生成 ov:// 指针链接。链接只含指针不含数据和凭证，对方拿到后用自己的凭证 apply。

与现有 ov import / ov export 的语义区别：后者处理的是数据快照（.ovpack），OpenViking Assets 处理的是资源构成描述——前者搬数据，后者搬"怎么建出这些数据"。

4. 执行层与实现范围

OpenViking 已经有 add_resource、watch-interval 定时更新、viking:// 资源组织和语义检索；数据连接器框架有可扩展插件，覆盖 git、RSS、对象存储等源。底层的抓取、解析、向量化、写入全部复用，协议层只新增四块：

1. 清单解析：目录与清单两层、按名引用、include 组合、严格校验。
2. 多资源编排：执行前检查（权限、参数可达性）、批量创建、失败隔离和结构化进度输出。默认 fail-fast，--skip-failed 时跳过失败项继续，全部失败则整体中止。
3. 运行状态保存：资产到目标库资源的映射和执行结果。只记录清单级事实；内容级的同步水位由连接器的 cursor 机制维护，不重复造调度。
4. 凭证别名解析：auth_ref 到本地凭证配置的解析。

内容的持续同步交给 watch-interval：ov add-resource -m 建资源时自动配置，不做独立的同步调度器。

5. 边界约束

• 分享清单不等于分享权限。对方只能读到自己本来就有权限的源数据，目标库的可见范围也要单独控制。
• 同步水位不等于历史快照。书签能告诉你下次从第几轨继续，但唱片换成再版之后，你听到的就不是原来的版本了。增量同步同理：它保证"持续跟上当前的源"，不承诺"恢复到过去某一天的样子"。
• 删除要保守。一次抓取因为权限或网络只拿到一半内容，不能把没拿到的部分当成"源里已删除"。批量清理至少要有资源隔离、dry-run 和阈值保护。
• 凭证别名挡不住所有泄漏。除了不把 token 写进清单，还要检查普通参数里有没有签名 URL、临时凭证这类敏感信息。

6. 收益

短期：建库过程沉淀为一份长期维护的配置。新人拿到 Manifest 就能开始，不用再问"要导哪些仓库"；仓库增删、换分支走 MR，有记录、能回滚；哪些资源同步失败会被明确报出来。

长期：同一份资产目录可以被不同工具消费。多仓工作区管理工具的清单关心分支和检出路径，OpenViking Assets 的清单关心 connector、索引范围和凭证别名——字段不同，共享目录。一边管"代码可达"，一边管"知识可答"，相互协同。再远一步，当协议公开后，IDE 插件、coding agent、CI 都可以生产或消费清单，"团队上下文"成为像容器镜像一样可寻址、可挂载的标准件。

7. 试点计划

从已经验证过的多仓代码问答场景切入，第一版只支持 Git 仓库：

1. 把现有的仓库收集脚本整理成 assets.yaml，用 Manifest 选全部或子集。
2. 做一个最小的 apply：执行前检查权限和参数；批量创建时报告每个仓库的进度和失败原因；记录清单状态、可重复执行。
3. 内容更新交给 watch-interval。

第一版的分享方式就是直接发送清单文件——它本身是个文本文件，发到另一套环境就能 apply，指针码不是第一版的前置条件。

验收标准（三条硬指标）：

1. 能从清单稳定重建当前 157 个仓库的知识库。
2. 之后新增或删除仓库只改清单，不再碰临时脚本。
3. 第二个团队拿到清单，不找原维护者答疑就能完成接入。

满足这三条之后再扩展：

1. 补 ov share 指针码和从已建库反推清单的能力。
2. 逐个接入 Wiki、云文档、RSS 这些已有插件的源。
3. 第二个团队用同一套格式接进来，协议标准化。

8. 设计原则小结

1. 声明式优先：清单描述"应该有什么"，工具负责把现实收敛到清单，而不是把操作过程记录成脚本。
2. 目录与配方分离：Catalog 管资产全集，Manifest 管单次组合，改一处、处处生效。
3. 凭证永远不出本机：协议只承载凭证别名，鉴权配置与连接参数的结构性分离是分享安全的基础。
4. 身份归一化：资产身份由来源计算而非由名字约定，同名不同源不冲突。
5. 严格校验：未知字段报错不告警，让错误在写清单时暴露，而不是在建库后腐烂。
6. 不重复造执行层：抓取、解析、向量化、增量同步全部复用 OpenViking 与连接器框架，只做声明层和编排层。
7. 删除保守、失败隔离：批量操作默认 fail-fast，清理必须有 dry-run 和阈值保护。
8. 引擎中立的姿态：描述与引擎解耦，任何实现了"创建、同步、检索、删除"语义的引擎都可以执行清单。

---

欢迎讨论：字段命名、include 语义、凭证别名的解析约定、以及试点范围是否合适。