[RFC] 支持导入代码仓库的方案设计，欢迎讨论

[MaojiaSheng]

代码解析方案 (Code Parser)

OpenViking 通过 Code Parser 模块实现对代码仓库的整体解析与理解。与普通文档的拆解式处理不同，代码解析采用了基于目录结构的整体映射策略，旨在保持代码项目的完整上下文。

概览

特性	策略	说明
解析粒度	文件级	不进行 Chunking 拆分，保持单文件完整性
目录映射	1:1 映射	本地目录结构直接映射为 Viking URI 路径
处理模式	异步处理	Parser 负责搬运，SemanticProcessor 负责理解
元数据	自动提取	提取语言、依赖、符号定义等基础信息

核心设计思考

代码仓库作为一种特殊的资源类型，具有以下显著特征，这些特征直接决定了我们的技术方案：

1. 文件粒度适中：大多数代码文件（KB 级）都在大模型上下文窗口范围内（<10k tokens），无需像长文档那样进行物理切分。
2. 结构即语义：代码的目录结构（Directory Structure）本身就蕴含了模块划分、层级依赖等重要架构信息，必须严格保留。
3. 高频迭代：代码变动频繁，系统需支持增量更新，避免重复索引未变动的文件。
4. 元数据丰富：代码中的注释、DocString、Import 语句等包含了高密度的语义信息。

上下文映射体系

我们将代码仓库映射到 OpenViking 的标准分层描述体系中。

1. Viking URI 映射

假设用户导入了 OpenViking 仓库：

client.add_resource(
    "https://github.com/volcengine/OpenViking",
    target="viking://resources/github/volcengine/OpenViking"
)

系统将生成如下标准化的目录树结构，能够完整体现深层级的文件路径：

viking://resources/github/volcengine/OpenViking/
├── .abstract.md        # L0: 项目级摘要
├── .overview.md        # L1: 项目级概览
├── docs/
│   ├── .abstract.md
│   ├── .overview.md
│   ├── zh/...
│   └── en/...
├── src/
│   ├── .abstract.md
│   ├── .overview.md
│   └── index/          # 深层目录结构
│       ├── .abstract.md
│       ├── .overview.md
│       └── index/      # 更深层的子模块
│           ├── .abstract.md
│           ├── .overview.md
│           ├── index_engine.cpp    # L2: 具体代码文件（C++）
│           └── ...
└── openviking/
    ├── .abstract.md
    ├── .overview.md
    └── ...

在这颗目录树中，每一层目录都会有一个 .abstract.md 文件和 .overview.md 文件：

• .abstract.md：目录的摘要，介绍本目录的功能和在项目中的作用。
• .overview.md：目录的概览，介绍本目录的文件结构、关键实体的位置等。

2. 语义层级 (Context Layers)

• L0 (Abstract)：目录的简短功能描述，用于快速检索。
• L1 (Overview)：目录的详细概览，包含文件结构分析、关键类/函数索引。
• L2 (Detail)：原始代码文件内容。对于代码文件，我们不进行拆分，直接存储完整内容。

数据处理原则

1. 本方案对于任意编程语言的代码仓库均适用，不应该特殊处理任意编程语言的差异性，需要考虑策略足够通用。
2. 对于代码仓库中的文档，除了图片以外，不要让大模型处理文本以外的其他模态内容，如视频、音频等。
3. 可以忽略代码仓库中的隐藏文件，如 .git 文件夹下面的内容，pycache 文件夹下面的内容等。
4. 对于代码仓库中的符号链接，我们应当忽略并记录其目标路径，而不是直接解析符号链接。
5. 对于代码仓库中的子目录，我们应当递归地处理，确保所有包含代码的目录，都被正确映射到 Viking URI 路径。

技术实现方案

1. 仓库识别与拉取

扩展 URLTypeDetector 以支持代码仓库识别：

• 识别逻辑：检测 URL 是否为 GitHub/GitLab 一级仓库地址（如 https://github.com/org/repo 或 *.git）。
• 拉取策略：
  • Git Clone：优先使用 git clone --depth 1 进行浅克隆，速度最快。
  • Zip Download：作为降级方案，下载 main.zip 或 master.zip。
• 过滤机制：内置过滤规则，自动忽略 .git, .idea, __pycache__, node_modules 等非代码资源。

2. 解析流程 (CodeRepositoryParser)

解析器遵循 V5.0 的异步处理架构：

1. 物理搬运 (Parser Phase)：

   • 将拉取到的代码仓库（经过过滤）完整上传到 viking://temp/{uuid}/ 临时目录。
   • 在此阶段不进行任何 LLM 调用，确保 add_resource 接口能快速返回。
   • 仅进行基础的静态分析（如文件类型识别）。

2. 异步理解 (Semantic Phase)：

   • TreeBuilder 将临时目录移入正式路径（如 viking://resources/...）。
   • 系统自动生成 SemanticMsg 并推入 SemanticQueue。
   • 后台 SemanticProcessor 消费消息，遍历目录树，异步生成各级目录的 .abstract.md 和 .overview.md。

3. 使用示例

# 导入代码仓库
await client.add_resource(
    "https://github.com/volcengine/OpenViking",
    target="viking://resources/github/volcengine/OpenViking",
    reason="引入 OpenViking 源码作为参考"
)

# 搜索代码逻辑
results = await client.find(
    "VikingFS 是如何实现文件挂载的？",
    target_uri="viking://resources/github/volcengine/OpenViking/"
)

相关文档

• 上下文类型
• Viking URI
• 上下文层级

[ZaynJarvis]

1. 过滤机制 是否参考或直接使用 .gitignore
2. 这套体系依赖代码库有很好的模块化设计，否则只有顶层 1～2 层目录的 abstract overview 比较有价值
3. [不确定] 参考 coding agent 设计，没有逐层 抽“abstract” embedding 而是直接用 keyword search 的原因是什么。深层 abstract embedding 有没有可能是弯路；直觉认为代码库中仅少数文件夹有必要执行 abstract/overview 抽取，由 vlm 决策。
4. 极大极小文件暂不特殊处理？
5. 需要本地仓库识别？高频代码变更和实时 context 索引应该在本地

现版本尝试过代码分析，看起来基本不可用，导入时间超长切片零散。这个方案看起来会有挺大提升

[kkkwjx07]

关于这个第三点，实测下来对于文件数比较多的情况，导入还是非常慢。用户恐怕很难接受几个小时的等待。我也准备研究一下coding agent的方案。

[Mijamind719]

1、认同1:1映射和文件不切分。
2、目前opencode主要是各种grep的方式来进行检索，ast-grep/exploring/glob，看你目前的实现是每个目录进行摘要，和exploring的方式有点像？但好像差别也蛮大的。。核心目录/代码文件的abstract和overview感觉得区分？
glob我看你们应该已经有了，ast-grep也得做吧。
3、看了cursor的文章好像会用到向量，这块准备再研究下对比差异。
4、增量更新这块目前实现到啥状态了？
5、多代码仓协同这块，现在有考虑么，例如多work-tree的设计？
anyway，感觉得先把benchmark搞起来？

[MaojiaSheng]

目前提交了第一版，多仓库协同好做，但多 worktree 还需要再研究，欢迎提出建议。benchmark 会研究下，核心是处理速度

[kkkwjx07]

昨天尝试了一下导入linux源码，跑了四个多小时还没跑完，纯工程角度优化也很难再低于小时级别。
我感觉现在逐文件理解的方案成本有点过高了。让AI想了几个方案，感觉这个方案一或三可以试试。

方案一：基于静态分析的符号索引 (推荐)

核心思路：用无需 LLM 的静态分析（AST）替代 LLM 摘要。
原理：对于代码文件，提取其“骨架”（类名、函数签名、Docstring），将这些结构化信息作为“摘要”进行向量化。
优点：

• 成本极低：无需调用 LLM，本地计算即可完成。
• 检索精准：保留了真实的函数名和参数，便于精确匹配。
实施路径：

1. 修改 SemanticProcessor._generate_single_file_summary。
2. 引入 tree-sitter 或语言自带解析库（如 Python ast）。
3. 对代码文件：提取 class/function 定义 + docstring -> 拼接成摘要 -> 存入向量库。

方案二：原始内容分块向量化 (RAG 标准做法)

核心思路：放弃“先摘要后向量化”，直接对代码进行分块（Chunking）向量化。
原理：将代码文件视为文本，按函数或固定窗口切分，直接计算 Embedding。
优点：保留代码原貌，适合“Copy-Paste”级别的代码搜索。
实施路径：

1. 修改 SemanticProcessor.get_resource_content_type，将代码文件标记为 TEXT 类型（目前被排除在外）。
2. 在 _vectorize_single_file 中引入 CodeSplitter（按语义或字符切分）。
3. 直接对切分后的 Chunks 进行向量化，跳过 LLM 摘要步骤。

方案三：按需/分层处理 (Tiered Processing)

核心思路：只对“重要”文件用 LLM，其他文件用廉价方案。
原理：

• Tier 1 (Core)：README、入口文件 (main.py)、核心逻辑 -> 全量 LLM 摘要。
• Tier 2 (Regular)：普通业务代码 -> 方案一 (AST 提取)。
• Tier 3 (Utils/Auto-gen)：工具类、自动生成代码 -> 方案二 (纯文本向量化) 或 仅文件名索引。
实施路径：

1. 定义启发式规则（Heuristics），例如：
   • 文件深度（根目录文件更重要）。
   • 引用入度（被引用多的文件更重要）。
   • 文件名特征（README, GUIDE vs test_, mock_）。

[lzj8]

有一些问题:

1. 解析和理解代码库的主要目的应该是给到CodingAgent去生成代码？
2. 如果是给CodingAgent去应用，是不是可以把代码库的解析和理解这些事情交给CodingAgent来做？毕竟这一块儿逻辑非常非常重，各个CodingAgent也非常不一样
3. OpenViking只是处理好CodingAgent在沙盒中执行时的代码文件的分布式存储、统一资源/知识定位、甚至加上知识版本管理(这个是CodingAgent的强需求)是不是就可以了？

[MaojiaSheng]

codeagent 的选型太多了，目前我们团队就有三四种，但上下文希望在团队内共享，因此我们考虑统一到服务端做