腾讯与印第安纳大学联手：AI代码助手终于学会"看地图"找代码了

这项由腾讯混元大模型前沿团队联合印第安纳大学、马里兰大学帕克分校、乔治亚大学及新加坡国立大学共同完成的研究，以预印本形式发布于2026年7月14日，论文编号为arXiv:2607.13285，有兴趣深入了解的读者可通过该编号检索完整论文。

**一、故事的起点：AI助手也会"找不到北"**

每一位程序员都有过这样的经历：接手一个运行多年的大型项目，老同事递来一句"代码在那边"，然后你对着几百个文件、几千个函数发呆，不知道从哪里下手。你想改一个功能，但这个功能可能藏在七八个文件的角落里，彼此之间通过复杂的调用关系和共享状态串联在一起。搜索关键词？可能一个都搜不到，因为功能的名字和代码里的变量名完全不同。

现在，越来越多的公司开始把这种"改代码"的工作交给AI编程助手来完成。这些AI助手接到一句自然语言指令，比如"把任务完成的确认流程改成需要三次确认"，就要自己去翻代码库、找到相关位置、制定修改方案。但问题来了：AI助手同样会"找不到北"。它们的记忆是有限的，没办法一次性把所有代码都看完；它们在庞大的代码库里摸索，很容易遗漏那些藏在冷门路径或对称位置的关键代码。

研究团队把这个困难正式命名为"行为定位"——也就是说，给定一个描述"系统应该做什么改变"的指令，如何精准找到所有实现这个行为的代码位置。这不是小问题，这是整个AI辅助编程流程中最先需要解决的一步，因为找不对位置，后续的修改计划从一开始就是错的。

**二、被忽略的那个"中间层"**

要理解这项研究想解决的问题，需要先认识一个稍微陌生的概念：代码驾驭框架，英文叫"harness"。

可以把一个现代AI智能体的工作方式理解为一辆赛车。赛车的发动机是底层的大语言模型，决定着原始的动力和智能。但赛车能不能跑起来、能不能转弯、刹车在哪里——这些都由车身框架和控制系统决定，而不是发动机本身。这个"车身框架和控制系统"就是harness。它负责构造输入给模型的提示词、管理系统的运行状态、调用各种外部工具、控制整个执行流程。一个AI智能体能做什么、怎么做，在很大程度上取决于harness的设计。

随着模型升级、API变化、应用需求演化，harness也必须不断更新和改造。这就是"harness演化"的工程挑战。而在演化过程中，无论是人类开发者还是AI编程助手，都必须先搞清楚"要改的功能到底在代码的哪些地方有实现"，才能动手修改。

现有的代码理解工具——比如代码搜索、代码摘要、仓库索引——确实让代码更容易浏览，但它们的根本组织逻辑是文件、函数和模块。而一个改动请求说的是"行为"，比如"改掉任务完成的确认逻辑"，代码库里却没有一个文件或函数叫做"任务完成确认逻辑"。这个从"行为描述"到"代码位置"的跨越，就是现有工具留下的空白。

**三、Harness Handbook：给代码库绘一张行为地图**

研究团队提出的解决方案叫做Harness Handbook，直译过来就是"驾驭框架手册"。核心思路可以用一个直观的比喻来说明：把整个代码库想象成一座大型博物馆。

传统的代码索引就像博物馆的房间清单，告诉你一号展厅在哪里、二号展厅在哪里，每个展厅里有哪些柜子。但如果你想找"关于宋朝瓷器的所有展品"，房间清单没法直接帮你，你得自己一个展厅一个展厅地翻。Harness Handbook则是另一种导览——它按照"主题"来组织信息，直接告诉你"宋朝瓷器"在几号展厅的哪个柜子、还有一件在五号展厅的角落，以及这两件展品在历史脉络上的关联。

具体来说，Harness Handbook把一个代码库的知识组织成三个层次。第一层是系统总览，用来描述整个代码框架的架构、运行模式、主要执行阶段以及全局数据流，让读者先对整个系统有一个宏观的认知。第二层是组件概览，对应系统中的各个执行阶段，详细说明每个阶段的职责、输入输出、依赖关系和本地状态。第三层是单元深挖，把每个阶段进一步拆解到具体的函数或文件，并且用精确的代码位置标注（文件名加行号范围）把描述和源代码直接连接起来。

除了这三层文档树，Handbook还维护着一个跨阶段的"状态寄存器视图"，专门记录那些在多个执行阶段之间传递和共享的数据。这非常重要，因为真实系统里的许多关键状态会在一个地方被写入、在另一个完全不相邻的地方被读取，而这种隐性关联正是人工查找和AI搜索最容易遗漏的陷阱。

**四、地图是怎么自动画出来的**

Harness Handbook不需要人工编写，它由一套自动化流水线从代码仓库直接生成，整个过程分三个阶段。

第一阶段叫"静态事实提取"，完全不依赖AI，是纯粹的确定性程序分析。系统解析代码仓库，提取出所有函数、方法的名称、所在文件、行号范围、调用关系等基础事实，构建出一张"程序图"。这张图的边只连接那些能被明确解析的调用关系；对于无法确认的调用，系统会记录下来而不是猜测，因为猜错比不知道更有害。

第二阶段叫"行为组织"，这里大语言模型开始介入，负责把第一阶段提取出来的函数和文件，按照"这些代码在运行时扮演什么角色"来重新组织。这里有两种工作模式，分别适用于不同规模的代码库。

对于代码规模相对适中、有清晰执行骨架可循的仓库，系统采用"以函数为叶节点"的模式。这时候有一个预先提供的执行阶段骨架作为参照，系统用代码内容和调用图上下文来判断每个函数属于哪个阶段，并且对于那些承担多种职责的大函数，还可以把它切割成若干连续的代码区域，分别归入不同阶段。这个判断过程有提议方和审核方两个角色相互制衡：提议方给出归类方案，审核方检查是否合理，不通过的重新修改，直到方案稳定收敛。

对于代码库规模巨大、事先无法提供清晰骨架的情况，系统采用"以文件为叶节点"的模式。这时候系统先为每个文件生成一张描述卡片，然后根据这些卡片的内容和文件之间的调用关系，自动推断出执行阶段的划分方案，再把文件归入各自的阶段。

第三阶段叫"层次合成与打包"，把前两阶段的成果组装成最终的三层文档树和状态寄存器视图，并且对每一个最底层的条目做验证——检查它指向的代码位置在当前仓库中是否真实存在。如果某个条目指向的代码已经不存在了，这个条目会被冻结标记，在被重新核验之前不会参与定位任务。这个验证机制确保了Handbook始终以代码仓库本身为最终权威。

**五、用Handbook找代码的方式：从粗到细，步步为营**

有了Handbook这张行为地图，AI规划助手在接到改动请求时就有了全新的工作方式，研究团队把这套工作方式称为"行为引导式渐进披露"，英文缩写BGPD。这个名字有点学术，但背后的逻辑其实像警探断案。

接到案子（改动请求）之后，先不要急着去现场翻查证据（源代码）。先看案件档案（Handbook的第一层和第二层），搞清楚这个案子涉及哪几个场景，哪几个执行阶段跟这次改动有关。然后再翻跨阶段关联记录（状态寄存器视图），因为一个状态变量可能在多个阶段都有操作，改了一个地方忘了另一个，案子就没破干净。

确定了相关阶段后，警探深入查看每个阶段的详细档案（第三层），找到最相关的具体函数或文件，拿到它们在代码仓库中的精确地址（文件名加行号）。接着，警探顺着调用关系图顺藤摸瓜，把直接相关的函数调用链上的代码也纳入候选范围。

最后，也是最关键的一步：警探拿着候选地址清单，亲自去现场（源代码）核实。逐一打开每个候选位置，确认它们现在的代码内容确实和这次改动有关，去掉不相关的，保留下确认有效的证据。这些经过核实的源码片段，就构成了后续制定修改方案的可靠基础。

**六、改完代码之后，地图会自动更新**

Harness Handbook还有一个工程上的重要设计：每次代码被修改之后，系统会自动检测改动范围，并且只更新受影响的部分，而不是每次都从头重建整张地图。

在函数级别的模式下，系统通过分析函数体的内容特征来识别"这个函数移动了位置但内容没变"、"这个函数内容改了"、"这个函数被删掉了"等不同情况，从而精确判断哪些Handbook条目需要刷新、哪些可以直接复用。在文件级别的模式下，则通过文件路径差异和内容哈希值来做同样的判断。如果执行阶段的骨架结构没有根本性变化，就只更新涉及改动的那部分文档；如果骨架本身也变了，才重新运行完整的构建流程。整个resync过程中，AI模型只参与分类、归属、组织和描述修订这四类语义判断，其余全部是确定性的计算操作。

**七、真实测试：两个代码仓库，六十个改动任务**

研究团队在两个开源代码库上验证了这套方案的效果。

第一个是Terminus-2，一个Python语言编写的终端智能体，属于Harbor框架的一部分。它通过tmux会话驱动真实终端，在"观察-决策-行动"循环里不断运行，直到任务完成或达到上限。这个仓库虽然只有6个源代码文件，却有丰富的多阶段迭代逻辑和跨迭代状态管理，属于规模小但行为复杂的典型情况，使用函数级别的工作模式。

第二个是Codex，OpenAI Codex编程智能体背后的Rust语言单体仓库。它规模庞大，横跨命令行界面、终端用户界面、应用服务器、配置管理和沙箱机制等多个子系统，包含数千个文件和深度调用图，使用文件级别的工作模式。

每个仓库各提供30个改动请求，按照类型分为三组。"查询型"请求要求修改已有行为，比如改变某个触发条件或控制流决策，难点在于从大量相似代码中找出真正相关的目标。"跨文件型"请求要求添加一个从头到尾贯穿多个文件的新能力，比如添加一个新参数并让它在解析、执行、文档等所有环节都生效，难点在于不遗漏任何一个需要联动改动的位置。"搜索对抗型"请求是专门设计的"刁钻"任务，相关实现藏在镜像代码、备用路径或冷门分支里，单纯靠关键词搜索几乎必然遗漏，这类任务最能考验系统的深度理解能力。此外，每个请求还被标注了"简单"、"中等"或"困难"三个定位难度等级。

规划助手统一使用DeepSeek-V4-Pro大模型，基于NexAU框架构建，只有只读工具权限。两种方案的唯一区别是有没有Handbook可以访问——"基准方案"完全靠自己翻仓库，"Handbook辅助方案"按照BGPD流程先查地图再核实源码。评分由GPT-5.5、Opus 4.8和DeepSeek-V4-Pro三个独立模型担任裁判，从定位准确性、范围控制和推理质量三个维度打分，三者加权之后形成最终评分，定位准确性的权重最高，占50%。

**八、数字说话：效果有多明显**

实验结果在三个维度上都给出了一致的答案。

在整体方案质量上，Handbook辅助方案在Codex上的胜率是38.3%，对比基准方案的28.3%，提升了10个百分点；在Terminus-2上的胜率是45.6%，对比基准方案的26.7%，提升幅度达到将近19个百分点。三个裁判模型的判断方向完全一致，说明结果不是某个裁判的特殊偏好，而是真实的质量差异。

更值得关注的是，这些质量提升不是靠"让AI想更久"换来的，恰恰相反，Handbook辅助方案用的规划token数量反而更少。在Codex上每个请求的token消耗从10.2万降到8.9万，下降了12.7%；在Terminus-2上从5.8万降到5.3万，下降了8.6%。质量更好、成本更低，这个组合是研究团队格外强调的发现，因为它证明了改进来自方向更准确，而不是计算更多。

在定位精度上，研究团队把DeepSeek-V4-Pro规划助手的预测位置，与Opus 4.8和GPT-5.5独立给出的参考答案做比较，计算文件级别和函数级别的召回率、精确率和F1分数。结果是：在两个仓库、两个参考答案、两个粒度上，全部24组比较都是Handbook辅助方案更高。F1分数的提升幅度从5个百分点到将近19个百分点不等。尤其在Terminus-2上，Handbook辅助方案对比GPT-5.5参考答案，文件级别和函数级别的F1分别达到89.3%，精确率达到93.3%。"完全定位失败"的比例——也就是一个相关位置都没找对的情况——在所有设置下都没有增加，最高下降了将近26个百分点。

按照请求类型细分来看，六个"仓库×类型"的组合全部是Handbook辅助方案领先，提升幅度在16到33个百分点之间。Codex在"查询型"请求上提升最显著，Terminus-2在"搜索对抗型"请求上提升最显著，后者的提升幅度高达33个百分点——这恰恰是那些最依赖深度理解而非关键词搜索的任务。按照定位难度分层来看，六个"仓库×难度"的组合同样全部是Handbook辅助方案领先，提升幅度在4到33个百分点之间，而且提升幅度不是简单地随难度升高而增大，这说明Handbook的帮助不只是对"难题"有效，在各种情境下都能带来实质性改善。

**九、这张地图还能用在哪里**

研究团队在论文中指出，Harness Handbook的用途并不局限于辅助代码改动的规划。因为它是一份始终与代码同步更新的行为中心式仓库表示，它天然适合用来做行为审计——检查某个设计决策是否在所有相关位置都得到了一致的实现——以及回归影响分析——当某处代码发生变化时，哪些其他行为可能受到影响。

更长远的方向，研究团队把Harness Handbook视为一种"共享行为记忆"，让智能体可以在这个记忆的支撑下，自主完成定位、规划、执行、同步这一整个循环，让代码框架朝着自我演化的方向发展。换句话说，不只是AI帮人改代码，而是AI自己维护自己运行所依赖的基础设施。

归根结底，这项研究揭示的核心道理并不复杂：找对地方，才能做对事情。无论是人类开发者还是AI编程助手，在面对大型复杂系统时，最大的瓶颈往往不是"怎么改"，而是"改哪里"。Harness Handbook把这个隐性的、费力的认知过程变成了一个有迹可循的系统性工作，而且这个过程可以自动化、可以持续维护、可以在每次代码变动后自动跟上。

这对于那些日常需要维护大型AI系统的工程团队来说意味着什么？新人不再需要花几周时间才能搞清楚一个功能在哪里；AI助手不再因为遗漏了某个镜像实现而提交一个"改了一半"的方案；代码审查也多了一个可靠的参照，让人知道一个改动是否真的覆盖了所有相关位置。

如果你对这套方案的细节感兴趣，想进一步了解Harness Handbook的构建算法、BGPD的完整工作流程，或者研究中使用的提示词模板和评测设计，可以通过arXiv编号2607.13285查阅完整论文。

---

Q&A

Q1：Harness Handbook是什么？

A：Harness Handbook是一种自动从代码仓库生成的"行为地图"，它把代码按照运行时的行为逻辑而非文件结构重新组织，并把每个行为描述直接连接到对应的源代码位置。当你想改某个功能时，可以先查这张地图定位相关代码，再去核实源码，而不是在几百个文件里盲目摸索。

Q2：BGPD定位方式和普通代码搜索有什么区别？

A：普通代码搜索是用关键词去匹配文件内容，找到的是包含特定词语的位置。BGPD则是先理解"这个改动涉及系统的哪个运行阶段"，再追踪跨阶段的共享状态，最后才去源码核实，能找到那些变量名和功能名完全不同、关键词搜索必然遗漏的实现位置，尤其擅长处理分散在多个文件角落的情况。

Q3：Harness Handbook构建出来之后需要手动维护吗？

A：不需要手动维护。每次代码被修改，系统会自动检测改动范围，只更新受影响的部分文档，未改动的内容直接复用缓存。如果某个文档条目指向的代码已不存在，系统会自动冻结标记，防止过期信息被用于定位任务。整个维护过程对用户来说是透明的。