2026 年 8 月 5 日提交的 arXiv 论文 “OctoLong: Mid-Training On Cross-Repository Code Contexts Enhances Long-Context Modeling” 把长上下文代码模型的问题讲得很具体：上下文窗口变长了，但训练语料没有同步变得更像真实工程。很多长上下文语料来自书籍、论文、长文档或单个代码仓库。这些材料有长度，却不一定有高质量远距离依赖。
代码不一样。一个函数的含义可能依赖类型定义、接口约定、测试、配置、第三方包、生成代码、README 示例和历史迁移。真实代码 Agent 做任务时，最难的不是把一百万 token 塞进窗口，而是在一百万 token 里找到会改变答案的那几段依赖。OctoLong 的价值就在这里：它不是单纯扩窗，而是用 AST parser、language server backend 和 package manager 递归构造跨仓库代码上下文，让模型在训练阶段见到更接近真实工程的依赖链。
长上下文的错觉
过去讨论长上下文时，很多人默认“窗口越大越好”。这个判断只对了一半。更大的窗口确实能容纳更多代码，但如果上下文是随意拼接的，模型会学到两个坏习惯。
第一，它会把远距离内容当噪声。因为训练样本里很多长文本并没有强依赖，模型不需要真正追踪几万 token 前的细节也能完成目标。第二，它会学到文本相邻性，而不是工程依赖。代码库里真正相关的文件不一定相邻，调用者、实现、类型、测试可能分散在不同目录，甚至不同仓库。
所以长上下文代码模型的关键不是长度，而是依赖密度。OctoLong 试图提高的正是这个密度。
OctoLong 的上下文构造思路
论文摘要描述了一个 context engineering pipeline：使用 AST parser、语言服务器后端和包管理器，递归检索代码引用，构造百万 token 级 dependency-rich code contexts。这个设计很接近资深工程师读代码的方式。
人类不会从仓库第一个文件开始顺序读到最后。我们会先看入口，再跳到定义，再找调用方，再看测试，再追依赖包，再回到错误路径。AST 提供结构，语言服务器提供 definition、reference、type 信息，包管理器提供跨包边界。把这些组合起来，才像真实代码理解。
一个简化流程可以写成：
seed symbol
find definition with language server
collect direct references
parse imported symbols
resolve package boundary
collect tests and examples
expand recursively until budget is filled
order context by dependency path这和普通 embedding 检索不同。embedding 擅长找语义相似片段，但代码理解常常需要语义不相似却依赖紧密的片段。例如一个错误发生在 checkout.ts，真正原因可能在 money.ts 的 rounding policy，或者在第三方 SDK 类型升级。相似度检索未必能稳定找到。
对代码 Agent 的意义
代码 Agent 的短板经常被误归因为“模型不够聪明”。实际上，很多失败来自上下文构造差。Agent 读了业务入口，却没读类型定义；读了实现，却没读测试；读了当前仓库，却没读内部共享包；读了 README，却没读实际调用路径。于是它生成看似合理、但无法合并的 patch。
OctoLong 提醒我们，代码 Agent 的上下文应该由依赖图驱动，而不是由文件大小、最近修改时间或关键词相似度驱动。
一个实用代码 Agent 可以按这五类证据组装上下文：
| 证据 | 作用 |
|---|---|
| 入口文件 | 明确任务发生位置 |
| 定义和引用 | 建立符号级依赖 |
| 类型和接口 | 避免错误调用 |
| 测试和 fixture | 理解预期行为 |
| 包和配置 | 识别环境边界 |
如果上下文预算有限，优先级也应该按依赖强度排序。一个强相关类型定义，比十个语义相似但无调用关系的文件更重要。
对 RAG 的启发
很多团队做代码 RAG 时，仍然把代码切成 chunk，放进向量库，然后按 query 相似度召回。这个方法容易上线，但天花板明显。代码不是普通文档，chunk 边界会切断函数、类型、注释和测试之间的关系。
更好的代码 RAG 应该混合四种索引：
lexical index: 精确匹配符号、错误码、文件名
semantic index: 召回描述相似的代码和文档
graph index: definition、reference、import、call graph
runtime index: trace、test failure、coverage、profileOctoLong 属于 graph-aware context 的训练版本。对普通开发者来说，即使不训练模型，也可以把这个思想用在推理时上下文组装。比如当 Agent 要修一个测试失败，先从失败栈定位符号，再沿 definition 和 reference 展开，再补充相关测试，而不是直接把错误日志 embedding 到向量库里搜索。
中期训练为什么重要
论文提到 OctoLong-Instruct 是从 600M 到 14B 参数的 base models 派生，通过 context-extension mid-training 和 instruction tuning 获得。这里的中期训练很关键。因为模型如果只在指令微调阶段见到长代码上下文，可能只是学会在长提示里回答问题；如果在中期训练阶段就见到依赖丰富的长上下文，它更可能内化跨距离追踪模式。
这对开源模型尤其重要。闭源前沿模型可以靠大规模私有数据和工具链弥补，开源长上下文模型如果训练语料仍然偏普通文档，就很难在代码 Agent 场景稳定追上。
论文摘要还提到，用 OctoLong 代码上下文替换传统 context-extension 语料的一部分，就能改善长距离检索、长期状态追踪、仓库级代码理解和下游 Agent 任务。这个结论如果在更多模型上复现，会对开源代码模型训练配方产生直接影响。
风险和局限
跨仓库语料不是越多越好。第一，依赖解析可能引入版权和许可证问题。训练前必须处理许可证、生成代码、vendored code 和私有包边界。第二，递归展开可能带来噪声。依赖图太宽时，上下文会被低价值引用淹没。第三，不同语言生态差异很大。TypeScript、Python、Rust、Java 的语言服务器和包管理器能力不同，构造质量会影响模型学习。
还有一个实际问题：代码依赖会随版本变化。训练样本如果没有锁定包版本和 commit，模型看到的跨仓库关系可能并不真实。高质量语料需要记录版本、路径、符号、解析工具版本和展开策略。
开发团队可以马上做什么
即使你不训练模型，也可以按 OctoLong 的思路改进代码 Agent：
- 给仓库建立符号索引，不只做 embedding。
- 在 Agent 读文件前，先用语言服务器找 definition 和 references。
- 把测试、类型定义、配置文件纳入默认上下文。
- 对 monorepo 和内部包建立跨包依赖图。
- 记录每次任务实际用到的文件，反向优化检索策略。
尤其是第 5 点。很多团队不知道 Agent 需要什么上下文，因为没有记录。把成功 patch 的上下文路径保存下来，就能逐步训练一个更好的检索器或规则排序器。
结论
OctoLong 把长上下文代码模型的讨论从“窗口多大”推进到“上下文怎么来”。这比单纯扩窗更重要。真实软件工程不是长文本续写，而是依赖追踪、状态理解、接口约束和跨仓库推理。模型要擅长这些能力，训练时就应该看见这样的数据。
对开发者来说，最直接的启发是：不要把代码上下文工程交给纯向量相似度。用 AST、语言服务器、包管理器、测试和 trace 共同构造上下文，才能让代码 Agent 少猜一点，多依据一点。长上下文不会取代 RAG，它会惩罚差 RAG，也会放大好 RAG 的收益。
参考来源：arXiv 论文 OctoLong: Mid-Training On Cross-Repository Code Contexts Enhances Long-Context Modeling，Hugging Face Daily Papers 近期代码模型条目，以及 GitHub Trending、Reddit r/LocalLLaMA 对长上下文开源代码模型的讨论。