By Unbug 
如果你正在构建一个基于 LLM 的代码修复 Agent，你可能已经注意到一个反直觉的现象：给模型”看”代码仓库的结构图，反而让它变得更笨了。这不是你的错觉——慕尼黑工业大学和达姆施塔特大学的研究团队在 SWE-bench Verified 上做了系统实验，发现纯视觉模式让所有模型的修复准确率显著下降，GPT-5-mini 从 55.0% 跌至 41.4%，Doubao 更是暴跌至 16.9%。但混合文本加视觉的模式却实现了双赢：Token 成本降低最高达 26%，同时修复准确率持平或微升。这篇文章将解析 SeeRepo 的核心发现，并带你理解多模态表示在编码 Agent 中的正确打开方式。
为什么传统编码 Agent 的输入接口存在根本缺陷
当前几乎所有编码 Agent（包括 Claude Code、Cursor Copilot、OpenAI Codex 等）都采用纯文本接口与代码仓库交互：通过 cat、grep、tree 等命令获取文件内容和目录结构，然后将这些文本片段作为上下文喂给模型。这种设计有一个隐含假设——LLM 对文本的理解能力足以覆盖代码仓库的结构化信息。
但人类开发者从来不是这样工作的。当你面对一个大型项目时，你的第一反应是打开 IDE 的文件树、查看依赖关系图、浏览类继承结构——这些都是视觉化的空间认知方式。纯文本接口剥夺了这种最自然的认知通道。
SeeRepo 团队在 SWE-bench Verified（500 个 Python 项目实例）上做了系统性实验，对比了三种输入模式：
- 纯文本基线：传统方式，通过文件树和文件内容交互
- 纯视觉模式：将仓库结构渲染为图像直接展示给 Agent
- 混合模式：文本定位目标 + 可视化理解整体架构
这个实验设计的关键在于它不是简单地”加一张图”，而是系统性地探索了多模态表示作为编码 Agent 输入维度的完整设计空间。
SeeRepo 框架：从 AST 到可视化的完整管线
SeeRepo 的核心贡献在于提出了一套完整的仓库结构可视化管线，将代码仓库的抽象语法树（AST）转换为多关系依赖图。具体流程如下：
第一步：静态分析构建依赖图。 通过解析每个文件的 AST，提取四种核心关系——包含关系（文件在目录中的层级）、导入关系（import/require 语句）、调用关系（函数调用链）和继承关系（类继承树）。这些关系构成了仓库的拓扑骨架。
第二步：Graphviz 子图渲染。 将依赖图转换为 Graphviz DOT 格式，支持三种布局策略——图布局（力导向算法）、嵌套布局（层级缩进）和表格布局（结构化排列）。每种布局对应不同的信息密度和认知负荷。
第三步：多模态注入。 生成的 PNG 图像作为辅助输入与文本上下文一起提供给 Agent，形成”文本定位 + 视觉理解”的互补模式。
# SeeRepo 核心管线示意
def build_repo_graph(repo_path):
# 1. AST 解析 → 提取四种关系
relations = extract_relations(repo_path) # contains, imports, calls, inherits
# 2. 构建多关系依赖图
graph = MultiRelationGraph(relations)
# 3. 选择布局策略并渲染
if layout == "graph":
image = render_force_directed(graph)
elif layout == "nested":
image = render_hierarchical(graph)
else:
image = render_table(graph)
return image
这个管线的精妙之处在于它只做静态分析——不需要运行时信息，不依赖代码执行，因此可以安全地集成到任何编码 Agent 的预处理阶段。
纯视觉模式的陷阱：为什么”看图”反而更差
这是整篇论文最反直觉的发现：给 Agent 看仓库结构图，所有模型的修复准确率都下降了。
具体数据如下（SWE-bench Verified Pass@1）：
| 模型 | 纯文本基线 | 纯视觉模式 | 变化幅度 |
|---|---|---|---|
| GPT-5-mini | 55.0% | 41.4% | -24.7% |
| Kimi K2.5 | 70.3% | 55.0% | -21.8% |
| Doubao-Seed-2.0-Lite | 51.0% | 16.9% | -66.9% |
这个结果揭示了一个关键事实：当前多模态模型在”从图像中读取代码结构信息”这一任务上存在系统性能力缺口。原因有三：
第一，分辨率瓶颈。 仓库依赖图通常包含数百个节点和边，渲染为 PNG 后每个节点的文本标签变得极小。即使是最先进的视觉编码器也无法可靠地解析这些微小文字。
第二，空间推理局限。 多模态模型的视觉理解能力主要集中在自然图像（照片、截图）上，对结构化图表的解析能力远未成熟。力导向布局产生的节点位置是算法生成的，没有语义意义，模型很难从中提取有意义的拓扑信息。
第三，Token 效率低下。 纯视觉模式要求模型”阅读”整张图来理解仓库结构，这比直接读取文本文件树消耗更多 Token——GPT-5-mini 的 Token 成本上升 42%，Doubao 飙升 268%。
这个发现对 Agent 设计有深远影响：多模态不是银弹。简单地把视觉信息塞给模型不会自动提升性能，必须理解模型的视觉能力边界在哪里。
混合模式：文本与视觉的互补之道
SeeRepo 的真正贡献不在于证明”纯视觉不行”，而在于展示了如何正确地结合多模态表示。
在混合模式下，Agent 的工作流程变为两步：
- 文本定位阶段：通过文件树和 grep 结果快速定位目标文件和相关上下文
- 视觉理解阶段：当需要理解模块间关系或整体架构时，查看对应的可视化子图
这种分工利用了两种模态各自的优势——文本擅长精确信息检索（文件名、函数签名、代码片段），视觉擅长空间关系表达（依赖拓扑、层级结构、调用链）。
实验结果验证了这一设计的有效性：
| 模型 | 纯文本基线 | 混合模式 | Token 变化 |
|---|---|---|---|
| GPT-5-mini | 55.0% | 55.4% (+0.4%) | -26% |
| Kimi K2.5 | 68.8% | 70.6% (+1.8%) | -3% |
| Doubao | 51.0% | 52.0% (+1.0%) | -6% |
关键洞察是：混合模式在几乎所有模型上都实现了准确率提升或持平，同时 Token 成本显著降低。GPT-5-mini 的 Token 节省率高达 26%，这意味着同样的预算可以处理更大规模的仓库。
故障定位阶段（bug localization）是收益最大的环节——此时 Agent 需要理解”这个 bug 可能影响哪些模块”，可视化子图提供了精确的依赖拓扑信息，而文本上下文提供了具体的代码片段。混合模式在此阶段的 Pass@1 达到 55.4%，同时 Token 成本降低约 25%。
三种布局策略的取舍分析
SeeRepo 测试了三种可视化布局，每种对应不同的设计权衡：
图布局（力导向）：节点位置由算法自动生成，适合展示全局拓扑关系。优势是信息密度高、Token 效率高——输入 Token 减少约 25%。劣势是节点位置无语义意义，模型难以建立稳定的空间记忆。
嵌套布局（层级缩进）：按照目录层级排列节点，保留了文件系统的自然结构。优势是与人类开发者的认知习惯一致，劣势是深度嵌套时图像宽度急剧膨胀，超出视觉编码器的有效分辨率范围。
表格布局：以结构化表格形式展示关系矩阵。优势是每个单元格的内容清晰可读，劣势是信息密度最低、Token 开销最大。
论文的实验结果表明，图布局在 Token 效率和准确率之间取得了最佳平衡。对于实际工程部署，建议优先采用图布局作为默认策略，并根据仓库规模动态调整可视化粒度——大型仓库只渲染局部子图而非全局拓扑。
与现有编码 Agent 架构的集成路径
SeeRepo 的发现对当前主流编码 Agent 的设计有直接指导意义：
Claude Code / Cursor Copilot：这些工具目前完全依赖文本接口。引入 SeeRepo 的混合模式后，可以在用户请求”理解这个模块”或”分析依赖关系”时自动触发可视化生成，而不改变现有的文件读取流程。
OpenAI Codex / Devin：这些 Agent 已经具备一定的仓库感知能力（如文件搜索、符号跳转），但缺乏结构化的全局视图。SeeRepo 的 AST 依赖图可以作为增强层叠加在现有工具链之上。
自建编码 Agent：如果你正在构建自己的编码 Agent，SeeRepo 提供了一个开箱即用的参考实现。核心集成步骤包括：安装 AST 解析库（如 tree-sitter）、配置 Graphviz 渲染管线、设计文本-视觉切换的触发逻辑。
# 混合模式集成示意
def agent_with_seerepo(task, repo_path):
# 1. 文本定位阶段
relevant_files = text_search(repo_path, task)
# 2. 判断是否需要可视化
if needs_structural_understanding(relevant_files):
subgraph = build_subgraph(repo_path, relevant_files)
visual_context = render_graph(subgraph, layout="force")
prompt = combine_text_and_visual(task, relevant_files, visual_context)
else:
prompt = format_text_only(task, relevant_files)
return llm_agent(prompt)
实际案例：从故障定位到修复的完整流程
让我们用一个具体场景来演示 SeeRepo 的实际效果。假设你需要修复一个 Python 项目中的依赖冲突 bug：
纯文本模式下的 Agent 行为：Agent 通过 grep 搜索相关代码，找到 15 个涉及该模块的文件，逐个读取内容。由于缺乏全局视图，它可能遗漏了间接依赖关系（A 导入 B，B 导入 C，但 A 没有直接导入 C），导致修复不完整。
混合模式下的 Agent 行为：Agent 先通过文本搜索定位到核心文件，然后通过 SeeRepo 生成的子图发现了一个隐藏的传递依赖链——C 模块的 API 变更影响了三个间接下游模块。Agent 据此生成了更完整的修复方案。
在这个案例中，SeeRepo 的价值不在于”让 Agent 看到更多代码”，而在于揭示了文本接口无法表达的关系信息。这种关系信息在大型项目中尤为关键——随着仓库规模增长，文件间的依赖关系呈指数级复杂化，纯文本接口越来越难以有效传达这种复杂性。
边界条件与反方观点
在看到 SeeRepo 的积极结果时，也需要清醒地认识其局限性：
第一，静态分析的覆盖范围有限。 AST 解析只能捕捉编译期可见的关系，动态导入（如 importlib.import_module）、反射调用、插件机制等运行时行为无法被捕获。对于高度动态化的项目（如 Django、Flask），依赖图的完整性会打折扣。
第二，可视化生成的计算开销。 虽然 SeeRepo 的管线本身不重，但对于超大型仓库（数千文件），构建完整依赖图和渲染图像仍然需要可观的计算资源。论文中测试的是 SWE-bench 中的中等规模项目，实际生产环境的规模可能大一个数量级。
第三，多模态模型的演进方向。 当前多模态模型在结构化图表解析上的能力缺口是暂时的还是根本性的？随着视觉编码器分辨率的提升和训练数据的丰富，纯视觉模式是否有可能在未来某个时刻超越文本基线？这是一个值得持续观察的问题。
第四，Token 节省的边际效应。 SeeRepo 报告的 Token 节省主要来自减少冗余的文件树遍历。但对于已经高度优化的 Agent（如使用增量文件读取、智能缓存等），SeeRepo 带来的额外收益可能有限。
未来雷达观察点
基于 SeeRepo 的发现，我们提出以下三个未来 1-2 个周期的观察方向：
观察点一：动态依赖图的实时构建。 当前 SeeRepo 只做静态分析，未来的研究方向是将运行时调用追踪（如 Python 的 sys.settrace）与 AST 解析结合，生成包含动态关系的增强型依赖图。这将显著提升对动态语言项目的适用性。
观察点二：多模态编码 Agent 的标准输入接口。 SeeRepo 证明了仓库结构可视化对编码 Agent 的价值，但目前的集成方式高度定制化。未来可能出现标准化的”仓库感知 API”——类似文件系统 API 的抽象层，让不同 Agent 可以统一地获取结构化仓库信息。
观察点三：视觉表示的自适应粒度。 当前 SeeRepo 使用固定粒度的可视化（要么全局图、要么子图）。未来的研究方向是根据任务复杂度动态调整可视化粒度——简单 bug 修复只需文件级视图，复杂重构需要模块级拓扑。这种自适应策略有望在 Token 效率和信息完整性之间实现更优平衡。
总结与行动清单
SeeRepo 揭示了一个被长期忽视的 Agent 设计维度：代码仓库的多模态表示。纯视觉模式虽然反直觉地降低了性能，但混合文本加视觉的模式实现了准确率提升和 Token 成本降低的双重收益——这为编码 Agent 的输入接口设计提供了实证依据。
你现在可以做的：
- 在你的编码 Agent 中引入轻量级仓库结构可视化工具（SeeRepo 开源实现可用
pip install seerepo安装） - 将现有的纯文本文件读取流程改造为”文本定位 + 视觉理解”的两阶段模式
- 在故障定位任务上对比混合模式与纯文本模式的性能差异，量化 SeeRepo 的实际收益
- 关注多模态模型在结构化图表解析上的能力演进——这可能是下一个 Agent 输入表示的突破点
AI 范式雷达：《HarnessFix——从失败轨迹到可靠 Agent 的自动修复》