[RFC] OpenViking Incremental Resource Update

[myysy]

RFC：资源的增量更新（Incremental Resource Update）

概要

OpenViking 当前在执行 add_resource（资源添加/索引）时，往往需要对整个资源进行重新解析、摘要与向量化。对于大型仓库/文档库而言，这会带来显著的成本与等待时间。

本文提出：当用户对同一个目标资源 URI 再次执行 add_resource 时，系统自动切换为“增量更新”模式：通过内容哈希识别变化，复用未变化文件的既有摘要与向量，仅对新增/变更内容重新生成摘要与向量，并以原子方式发布新版本，确保不会出现“部分更新可见”的中间态。

本 RFC 面向社区讨论，重点聚焦行为约束、关键机制、失败语义与开放问题。

动机与价值

• 大仓库重复全量索引成本高：LLM 摘要与向量化的调用次数与输入规模随资源规模线性增长。
• 迭代更新是常态：多数更新只涉及少量文件修改或新增。
• 需要一致性：更新过程中应避免新旧版本混杂、检索命中指向无效文件等问题。

目标

• 当目标 URI 已存在时，add_resource 触发增量更新，而不是全量重建。
• 精准识别新增/修改/删除内容：
  • 基于内容哈希（例如 SHA256）而不是时间戳。
  • 路径变化（移动/重命名）按“删除旧路径 + 新增新路径”处理。
• 复用未变化内容：
  • 未变化文件复用既有摘要，避免重复 LLM 调用。
  • 未变化摘要对应的向量直接复用，不重复向量化。
  • 目录级摘要（overview/abstract）遵循“变更向上冒泡”：任一子孙变化，祖先目录摘要需更新；否则复用。
• 更新发布具备原子性：
  • 新版本在临时位置完成准备与处理后再发布。
  • 失败时保持旧版本可用（除非发生已发布但索引失败的特殊故障场景，见后文）。
• 并发安全：
  • 对同一资源 URI 的所有修改操作（新增/更新/删除）互斥，冲突请求直接拒绝。

非目标（本提案明确不做）

• 不做“重命名/移动检测”的智能匹配（例如基于内容相似度推断 rename）。
• 不提供“一键强制全量重建”的更新参数：需要用户先删除资源再重新添加。
• 不承诺在向量索引更新失败后自动恢复；只提供“标记损坏 + 手动恢复”的机制。
• 不在本轮引入独立的持久化元数据文件（例如 .meta）来存储 hash（可作为后续优化）。

术语

• 资源（Resource）：由一个目标 URI 标识的一组文件/目录集合，例如 viking://resources/my-repo。
• 临时暂存（Staging）：用于准备新版本的临时 URI，例如 viking://temp/my-repo_update_<timestamp>。
• 文件摘要（File Summary）：单文件内容的摘要文本。文件摘要不一定以文件形式落盘，可能仅存于向量库记录字段中。
• 目录摘要：
  • .abstract.md：目录的 L0 摘要（更抽象、更短）。
  • .overview.md：目录的 L1 概览（更结构化、更展开）。
• 变更向上冒泡（Recursive Bubble-Up）：任意深度的子孙发生变化，祖先目录摘要均需重新生成。

用户体验（CLI / API）

CLI 行为（示例）

openviking resource add ./my-repo --target viking://resources/my-repo

• 若目标 URI 不存在：按“新增资源”流程执行。
• 若目标 URI 已存在：自动进入“增量更新”流程。

支持 --wait：

openviking resource add ./my-repo --target viking://resources/my-repo --wait --timeout 60

本 RFC 建议 --wait 的语义为：

• 等待系统完成“差异计算 + 任务入队（或调度成功确认）”，随后返回；
• 不等待“摘要生成/向量化/最终发布”完成（与新增资源时的异步处理策略保持一致，利于脚本化快速确认请求已被接收）。

HTTP API（契约级）

POST /resources/add

请求体（JSON）：

• path：本地路径或 URL
• target：目标资源 URI；若已存在触发更新
• reason：更新原因（可选，便于审计/追踪）
• instruction：处理指令（可选）
• wait：是否等待入队确认（默认 false）
• timeout：等待超时秒数（可选）

响应建议：

• 200：{ status: "success", result: { root_uri, queue_status? } }
• 409：资源锁冲突（同 URI 已有更新进行中）
• 400：参数不合法
• 500：内部错误

核心设计

1）整体流程（高层）

对“更新同一目标 URI”的一次请求，推荐的生命周期如下：

1. 获取资源级互斥锁（覆盖新增/更新/删除的全生命周期）
2. 将新内容上传/复制到临时暂存 URI
3. 计算差异（新增 / 修改 / 删除）
4. 对未变化内容执行复用（摘要与向量复用；目录摘要按需复用/重算）
5. 对新增/变更内容执行摘要与向量化任务编排
6. 所有必要处理完成后，执行发布：
   • 文件系统切换（将新版本替换到目标 URI）
   • 向量索引切换（使检索结果与新版本匹配）
7. 释放锁

2）变更检测（Diff）

检测维度：

• 路径：相同相对路径才可能判定为“未变化”
• 内容：对比内容哈希（推荐 SHA256，也可允许配置）

分类规则：

• 路径相同且哈希相同：未变化
• 路径相同但哈希不同：修改
• 新版本存在但旧版本不存在：新增
• 旧版本存在但新版本不存在：删除
• 路径变化（移动/重命名）：按“删除旧路径 + 新增新路径”处理（即使内容一致也不尝试匹配）

哈希计算建议采用分块读取以适配大文件。

3）摘要与向量复用策略

• 未变化文件：
  • 复用既有文件摘要（从向量库/上下文记录中读取摘要字段）
  • 不重新向量化该文件摘要（复用既有向量）
• 新增/修改文件：
  • 生成新摘要并向量化
• 删除文件：
  • 从向量索引与上下文记录中移除对应 URI（硬删除）

注意：目录级 .abstract.md / .overview.md 是落盘文件；未变化目录可通过从旧版本复制这两个文件到暂存区来复用，避免额外 LLM 调用。

4）目录摘要更新：变更向上冒泡

规则：

• 若目录的任一子孙（文件或子目录）新增/修改/删除，则该目录的 .abstract.md 与 .overview.md 必须重新生成。
• 若目录及其全部子孙均未变化，则复用旧版本的 .abstract.md 与 .overview.md。

实现上更易落地的方式：

• 在暂存区构建“新版本完整树”（包含未变化文件的复制或引用）
• 对“未变化的子树”直接复制旧版目录摘要文件到暂存区
• 对“需要更新的目录”在暂存区执行自底向上的目录摘要生成

5）并发与锁

锁粒度：资源 URI 级别（例如 viking://resources/my-repo）。

锁机制建议：

• 以文件系统锁文件实现（例如在资源根目录放置 .resource.lock）
• 若锁存在且未过期：拒绝并返回冲突错误

锁覆盖范围：

• 从开始上传/复制新内容到暂存区起，直到最终发布成功或失败清理完成为止
• 任何修改资源状态的操作（新增/更新/删除）都必须竞争此锁

6）原子发布与一致性

发布必须尽量保证“对外可见版本”要么是旧版本，要么是新版本，不出现混合。

推荐策略：

1. 新版本的文件内容、目录摘要、（可选）新向量索引先在暂存命名空间完成
2. 执行文件系统切换：先删除旧目标目录，再将暂存目录移动到目标 URI
3. 在确认文件系统切换后，激活新向量索引（例如临时 collection/partition 的原子切换或合并）

该顺序的取舍：

• 先切文件系统：即使索引短暂滞后，检索命中仍更可能落到存在的文件路径（减少“命中但文件不存在”的体验问题）。
• 但若索引更新在文件系统切换后失败，系统可能进入“文件是新版本、索引未对齐”的不一致状态，需要额外故障语义（见下文）。

7）失败语义与恢复

Fail-fast 原则：

• 任一阶段出现永久性错误（重试后仍失败）即终止更新
• 清理暂存目录与锁文件
• 目标 URI 保持旧版本不变且可用

特殊故障：文件系统切换成功后，索引更新失败

• 建议行为：将资源标记为“损坏/不可用于检索”，避免返回可能错误或不一致的搜索结果
• 标记方式：在资源根目录创建 .corrupted 标记文件
• 恢复方式（本提案范围内）：用户删除资源并重新添加，触发全量重建

8）可观测性（建议）

为了让社区能更容易定位问题、衡量收益，建议最少提供：

• 更新过程阶段日志：锁、暂存、diff 统计、入队、发布、清理
• diff 统计：新增/修改/删除文件数量、目录数量
• 复用命中率：复用摘要/向量的数量与比例
• 失败原因与阶段：明确是锁冲突、读取/上传失败、摘要失败、向量失败、发布失败等

数据与存储布局（概念）

资源目录（示例）：

viking://resources/my-repo/
  .resource.lock
  .corrupted
  .abstract.md
  .overview.md
  src/
    .abstract.md
    .overview.md
    main.py

上下文/向量记录（概念）：

• 以文件/目录 URI 为主键
• abstract 字段可用于存储文件摘要（便于复用）
• parent_uri 用于重建层级
• content_hash 可作为未来优化字段（本轮可先“现算现比”）

兼容性与迁移

• 对外接口保持不变：同一个 add_resource 入口同时支持新增与增量更新。
• 老资源无需迁移：增量更新可在缺少 hash 元数据时通过读取内容现算 hash 完成对比。
• 重命名/移动不会被智能识别：会按删除+新增产生额外摘要与向量成本（已在非目标声明）。

安全与权限（讨论点）

• 读取/扫描文件应遵循既有权限模型；遇到权限错误时建议明确失败阶段与提示。
• 需要明确符号链接、设备文件等特殊文件的处理策略（跳过/拒绝/按文件处理）。

开放问题（需要社区讨论）

1. --wait 的最终语义是否需要扩展？
   • 仅等待“入队确认”（本 RFC 建议）
   • 还是支持额外模式：等待“发布完成”（例如 --wait=complete）
2. 内容哈希算法是否固定为 SHA256，还是允许配置（MD5/SHA256）？
3. 锁文件的“超时/过期”判定规则与恢复策略：
   • 多实例部署下，如何处理进程崩溃导致的锁遗留
4. 删除/更新对“正在运行的会话上下文”的影响如何定义？
   • 会话中引用旧文件 URI 的上下文是否需要失效/重建/保留
5. 向量索引的原子切换方案：
   • 临时 collection/partition 的原子 swap
   • 或直接 delete+upsert（实现更简单，但故障窗口更大）
6. 资源规模/单文件大小的限制策略是否需要明确（避免极端输入导致超时或内存压力）？
7. 特殊文件处理：符号链接、循环链接、二进制大文件、空文件、空目录等是否需要显式规则？

讨论引导（希望社区反馈）

• 你希望增量更新带来哪些“最关键”的体验提升（速度、成本、稳定性）？
• 你更偏好“强一致但更复杂”的索引切换，还是“实现简单但需要故障标记”的策略？
• 你是否需要对 rename/move 做更智能的处理，还是当前的“删除+新增”足够？

---

English Version

---

RFC: Incremental Resource Update

Summary

Today, running add_resource in OpenViking often implies re-processing an entire resource: parsing, summarization, and embedding. For large repositories or document trees, this is expensive and slow.

This RFC proposes that when a user calls add_resource again for an already-existing target resource URI, the system switches to an incremental update mode: detect changes via content hashing, reuse existing summaries and vectors for unchanged files, re-summarize and re-embed only new/changed content, and publish the new version atomically to avoid partially-visible updates.

This document is written for community discussion and includes the key behaviors, constraints, failure semantics, and open questions directly in the RFC.

Motivation

• Full re-indexing is costly for large resources (LLM calls + embedding scale with size).
• Most updates are small deltas (a few files changed).
• Consistency matters: avoid mixing old/new versions or returning search hits that point to missing files.

Goals

• If the target URI already exists, add_resource performs an incremental update instead of a full rebuild.
• Correctly classify changes (added / modified / deleted):
  • Use content hash (e.g., SHA256), not timestamps.
  • Treat moves/renames as “delete old path + add new path”.
• Reuse unchanged work:
  • Reuse existing file summaries for unchanged files (avoid LLM calls).
  • Reuse vectors for unchanged summaries (avoid re-embedding).
  • For directory-level summaries (overview/abstract), apply “recursive bubble-up”: if any descendant changes, regenerate the directory summaries; otherwise reuse.
• Atomic publish:
  • Build and process the new version in a temporary staging area.
  • On failure, keep the previous version intact and usable (except for a specific post-swap indexing failure case described below).
• Concurrency safety:
  • All modifications for the same resource URI (add/update/delete) are mutually exclusive; concurrent requests are rejected.

Non-goals

• No “smart rename/move detection” (e.g., similarity matching across paths).
• No “force full re-index” flag in update: users delete + re-add to rebuild.
• No automatic recovery after an indexing failure post-publish; only “mark corrupted + manual recovery”.
• No new persistent per-resource metadata file (e.g., .meta) in this iteration (can be a follow-up optimization).

Terminology

• Resource: a file/directory tree identified by a target URI, e.g. viking://resources/my-repo.
• Staging: a temporary URI to prepare the new version, e.g. viking://temp/my-repo_update_<timestamp>.
• File Summary: a single-file summary text. It may not be persisted as a file and can live in the vector/context store record.
• Directory Summaries:
  • .abstract.md: L0 directory summary (shorter, more abstract)
  • .overview.md: L1 directory overview (more structured/expanded)
• Recursive Bubble-Up: if any descendant (at any depth) changes, ancestor directory summaries must be regenerated.

UX (CLI / API)

CLI behavior (example)

openviking resource add ./my-repo --target viking://resources/my-repo

• If the target URI does not exist: create a new resource (existing behavior).
• If the target URI exists: trigger an incremental update.

--wait support:

openviking resource add ./my-repo --target viking://resources/my-repo --wait --timeout 60

This RFC recommends --wait semantics as:

• Wait until the system completes “diff calculation + task enqueue/dispatch confirmation”, then return.
• Do not wait for summarization/embedding/final publish to finish (keep it consistent with asynchronous new-resource processing and friendly to scripting).

HTTP API (contract-level)

POST /resources/add

Request body (JSON):

• path: local path or URL
• target: target resource URI; if it exists, triggers update
• reason: optional reason for add/update (audit/traceability)
• instruction: optional processing instructions
• wait: boolean, default false
• timeout: optional seconds for the wait operation

Recommended responses:

• 200: { status: "success", result: { root_uri, queue_status? } }
• 409: resource lock conflict (an update is already in progress)
• 400: invalid request
• 500: internal error

Proposed Design

1) End-to-end lifecycle (high level)

For an update request targeting an existing resource URI:

1. Acquire a resource-level exclusive lock (covers add/update/delete)
2. Upload/copy the new content into a staging URI
3. Compute a diff (added / modified / deleted)
4. Reuse unchanged work (summaries/vectors; directory summaries reuse/regenerate as needed)
5. Enqueue/execute summarization and embedding for new/changed content
6. Publish:
   • filesystem swap (make the new version the target)
   • vector index activation (make search match the new version)
7. Release lock

2) Diff calculation

Dimensions:

• Path: only identical relative paths are eligible to be “unchanged”
• Content: compare content hash (recommended: SHA256, potentially configurable)

Classification:

• Same path + same hash: unchanged
• Same path + different hash: modified
• Present in new version only: added
• Present in old version only: deleted
• Renamed/moved path: delete old + add new (even if content is identical)

Hashing should be streaming/chunked for large files.

3) Summary and vector reuse

• Unchanged files:
  • Reuse existing file summaries (read from the vector/context store record fields)
  • Reuse existing vectors (no re-embedding)
• Added/modified files:
  • Generate new summaries and embed them
• Deleted files:
  • Hard delete corresponding URIs from the index and context records

Directory summaries are persisted as files (.abstract.md, .overview.md). For unchanged directories, copying these files from the previous version into staging enables reuse without LLM calls.

4) Directory summary regeneration: recursive bubble-up

Rules:

• If any descendant (file or subdirectory) is added/modified/deleted, regenerate the directory’s .abstract.md and .overview.md.
• If the directory and all descendants are unchanged, reuse the prior .abstract.md and .overview.md.

Practical approach:

• Build a complete “new version tree” in staging (including unchanged content via copy/reference)
• Copy directory summary files for unchanged subtrees into staging
• Run bottom-up directory summarization only where regeneration is needed

5) Concurrency and locking

Lock scope: per resource URI (e.g., viking://resources/my-repo).

Recommended lock mechanism:

• A filesystem lock file (e.g., .resource.lock) at the resource root
• If present and not considered stale: reject the request with a conflict error

Lock duration:

• From the start of staging upload/copy until publish completes or failure cleanup finishes
• All state-changing operations (add/update/delete) must contend for the same lock

6) Atomic publish and consistency

Publish should make the externally visible state either “old version” or “new version”, not a mix.

Recommended strategy:

1. Prepare new files, directory summaries, and (optionally) a new vector index in staging
2. Filesystem swap: remove the old target directory, then move staging into the target URI
3. After filesystem swap is confirmed, activate the new vector index (e.g., atomic swap/merge of a temporary collection/partition)

Trade-offs:

• FS-first reduces the risk that search hits point to missing files.
• But if indexing fails after FS swap, the system can enter an inconsistent state unless failure semantics are explicit (see below).

7) Failure semantics and recovery

Fail-fast principle:

• Any permanent error (after retries) aborts the update
• Cleanup staging and lock
• Keep the previous target version intact and usable

Special failure: filesystem swap succeeds, then vector index activation fails

• Recommended behavior: mark the resource as “corrupted / search-unavailable” to avoid returning inconsistent results
• Marking mechanism: create a .corrupted marker file at the resource root
• Recovery (in-scope): user deletes the resource and re-adds it to rebuild

8) Observability (recommended)

Minimum recommended signals:

• Stage-level logs: lock, staging, diff stats, enqueue, publish, cleanup
• Diff stats: counts of added/modified/deleted files and affected directories
• Reuse metrics: how many summaries/vectors were reused (ratio)
• Failure stage and reason: lock conflict, read/upload failure, summarization failure, embedding failure, publish failure

Data and storage layout (conceptual)

Resource directory:

viking://resources/my-repo/
  .resource.lock
  .corrupted
  .abstract.md
  .overview.md
  src/
    .abstract.md
    .overview.md
    main.py

Context/vector records (conceptual):

• Keyed by file/directory URI
• abstract can store file summaries for reuse
• parent_uri reconstructs hierarchy
• content_hash is a potential future optimization field (this iteration can hash on the fly)

Compatibility

• No new public entrypoints: the same add_resource handles both create and update.
• No migration required: updates can compute hashes on the fly even if no hash metadata exists.
• Rename/move costs extra (delete+add) by design (explicitly a non-goal to optimize in this RFC).

Security and permissions (discussion points)

• File scanning/reading should respect the existing permission model and report permission errors clearly.
• Handling of symlinks, device files, and other special entries should be explicitly defined (skip/reject/treat-as-file).

Open questions for the community

1. Should --wait support additional modes beyond “enqueued” (e.g., --wait=complete)?
2. Should the hashing algorithm be fixed to SHA256, or configurable (MD5/SHA256)?
3. Lock staleness detection and cleanup:
   • In multi-process or multi-instance deployments, how do we recover from orphaned locks?
4. Session impact:
   • What happens to active session contexts referencing the resource when it updates?
5. Vector index atomicity:
   • Temporary collection/partition swap for strong consistency
   • Versus direct delete+upsert for simplicity (with a larger failure window)
6. Resource constraints:
   • Do we need explicit limits for total resource size or single-file size?
7. Edge cases:
   • symlinks and cycles, binary large files, empty files, empty directories

Feedback prompts

• Which outcome matters most to you: speed, cost reduction, or consistency?
• Do you prefer a stricter-but-more-complex index swap, or a simpler approach with “corrupted” marking on failure?
• Is “rename = delete + add” acceptable for your use cases?

[DamonDay]

很有必要。

[fyp711]

Topic：资源文件的变更历史是否需要完整记录？或者近几次的变更记录，这样能给Ai提供一些数据修改的历史信息。

[myysy]

嗯嗯，这个很有必要，本质是资源的版本管理，会在之后考虑方案~

[MaojiaSheng]

“”“
若目标 URI 不存在：按“新增资源”流程执行。
若目标 URI 已存在：自动进入“增量更新”流程。
”“”
我认为这里还需要讨论下目标 URI 是否能有关于资源来源的元信息记录，保护一下。

[myysy]

嗯嗯，安全角度看，衍生出来更像是 client 侧鉴权的问题

[fyp711]

增量更新会考虑通过 Unified Diff 文件直接Patch吗？

[fyp711]

这个好像是比较主流的更新模式

[myysy]

目录级别的变更可能会涉及 L0/L1 缓存和索引的变更，直接 Patch 不太能满足

[r266-tech]

感谢 @myysy 这个高质量的 RFC，设计考虑得很全面。作为一个日常跑 400+ sessions 的重度用户（也是 PR #297 cold/hot lifecycle 和 #322 is_healthy 的贡献者），从实战角度补充几个想法。

1. 关于开放问题 #4：Session-Resource 版本绑定

这是我最关心的点。我的场景中，定时任务会触发资源更新，同时有多个 agent session 正在检索。如果更新发生在 session mid-flight，引用的内容基础可能不一致。

建议引入轻量的版本绑定机制：

• Session 首次检索资源时，记录当前资源 epoch（或 content_hash snapshot）
• 旧版本标记为 superseded，延迟清理
• 当无 active session 引用时触发 GC（引用计数 / TTL 二选一）

这和 PR #297 的 hotness 概念可以复用——被 session 引用的旧版本视为 hot，无引用的降级为 cold → GC 候选。实现上可以先做 TTL 兜底（比如旧版本保留 30min），引用计数作为后续优化。

2. 补充 @fyp711 关于 Unified Diff 的讨论

同意 myysy 的判断，目录级别的 L0/L1 级联依赖让纯 Patch 模式不够用。不过换个角度看，Unified Diff 和 Bubble-Up 其实可以互补——Diff 解决「快速定位变化」，Bubble-Up 解决「摘要级联重算」。

具体来说，可以在 diff 阶段引入 Merkle Tree 式的目录级哈希：自顶向下快速跳过未变化的子树，只对变化部分递归到文件级。这和 Bubble-Up 的自底向上重算方向刚好相反，组合起来能把大仓库的 diff + 摘要更新从 O(n) 压到 O(changed)。

3. 建议 reason 字段结构化

RFC 中 reason 作为可选字段是个好起点，建议进一步结构化：

{
  "type": "content_update | correction | schema_migration",
  "summary": "简要描述",
  "triggered_by": "session_id（可选）"
}

好处：变更可审计（哪个 session 触发了什么类型的更新），也便于后续做变更历史查询——这和 @fyp711 提到的版本管理需求天然衔接。

---

整体非常认可 RFC 的设计取向：内容哈希 > 时间戳、staging + swap 原子发布、.corrupted 标记而非复杂自动恢复。在单机部署场景下这些都是务实的选择。期待后续实现 🙏

[myysy]

感谢 @r266-tech 提供的实战建议，对于 resource diff 的高效处理，确实很有必要结合提到的方式调优，提高性能表现，对于 resource 的事务一致性，提到的类似“双 buffer”的机制也会参考，近期估计还会有一个单独的话题来专门讨论~