Theory of Code Space: Do Code Agents Understand Software Architecture?

该论文提出了“代码空间理论”（ToCS）基准，通过让 AI 代理在部分可观测条件下探索程序化生成的代码库并维护结构化信念状态，揭示了不同大模型在主动探索能力、信念自我支撑机制以及信念稳定性方面存在显著差异，表明当前代理在构建和维护软件架构理解方面仍面临挑战。

要点

这篇论文就像是在给现在的 AI 编程助手做一场"深度体检"，看看它们到底是不是真的“懂”代码，还是只是在“背”代码。

作者发现了一个有趣的现象：现在的 AI 写代码很厉害，但一旦面对一个由几十个文件组成的复杂项目，它们就容易“迷路”或者“精神分裂”。

为了解决这个问题，作者发明了一个叫 TOCS（代码空间理论）的测试工具。下面我用几个生活中的比喻来解释这篇论文的核心内容：

1. 核心问题：AI 是“导游”还是“游客”？

想象一下，你要去一个陌生的城市旅游。

• 以前的测试：就像给 AI 一张完整的地图，然后问它：“从 A 到 B 怎么走？”AI 答对了，我们就觉得它很聪明。
• 现实情况：在真实的软件开发中，没有现成的地图。你需要自己一个个打开文件（就像在城市里一个个街区探索），去搞清楚这个模块是干嘛的，那个模块和谁有联系。
• TOCS 的测试：它把 AI 扔进一个没有地图的迷宫（代码库）。AI 手里只有有限的“步数”（预算），它必须决定先打开哪个文件，再打开哪个。每走几步，AI 就必须停下来，画一张草图（JSON 格式），告诉考官：“我现在觉得这个迷宫的结构是这样的……"

2. 三个惊人的发现（就像体检报告）

作者测试了 6 种最先进的 AI 模型，结果发现了三个非常反直觉的现象：

发现一：有的 AI 喜欢“瞎逛”，有的喜欢“看全景”

• 现象：有些 AI（比如 GPT-5.3）在自己一步步探索时，画出的地图反而比直接给它看所有文件还要好。这就像有些侦探，必须亲自去现场勘查线索，才能理清思路；如果直接把卷宗全堆在它面前，它反而晕了。
• 反例：但有些 AI（比如 Gemini 2.5 Flash）完全相反。让它自己一步步找，它反而画不好图；给它看所有文件，它反而画得更好。这说明“主动探索”这个能力，并不是所有 AI 都天生具备的。

发现二：有的 AI 会“自我强化”，有的会“自我干扰”

• 比喻：测试中，AI 每走几步就要画一张草图。
  • GPT-5.3 把之前的草图留在手边（作为“草稿纸”），这就像给它一个脚手架。它看着自己之前画的图，能更好地理解接下来的路，越画越清晰。
  • Gemini 2.5 Pro 却不一样。它把之前的草图留在手边，反而让它更糊涂了。它看着之前的图，好像把新信息给忘了，甚至把之前画对的部分给擦掉了。
• 结论：让 AI“记住”自己之前的思考，对有的模型是神助攻，对有的模型却是毒药。

发现三：越大的模型，越容易“失忆”

• 最惊人的对比：
  • 小模型（Gemini 2.5 Flash）：虽然它个头小，但它非常稳。每走一步，它画的图都稳稳当当，从不忘记之前发现的东西。
  • 大模型（Gemini 2.5 Pro）：它个头大，能力看似更强，但在测试中却出现了灾难性的“失忆”。它可能前 9 步画得很好，第 10 步突然把之前画对的所有关系都忘了，甚至把图给毁了。
• 启示：模型越大，并不代表它越能“记住”复杂的结构。有时候，小模型反而更专注、更稳定。

3. 这个测试发现了什么“硬伤”？

作者发现，很多 AI 其实看懂了代码，但在汇报的时候出了问题。

• 比喻：就像你让一个学生去图书馆找书。学生其实把书都找到了（探索行为是对的），但让他写读书笔记（外部化信念）时，他要么写错了书名，要么把两本书的关系搞混了。
• 原因：很多时候不是 AI“不懂”，而是它不会把脑子里的想法准确地翻译成结构化的语言（比如 JSON 格式）。

4. 这对未来意味着什么？

这篇论文告诉我们，未来的 AI 编程助手不能只靠“猜”或者“背代码”。我们需要：

1. 教 AI 学会“画地图”：不仅要会写代码，还要能随时整理出项目的结构图。
2. 给 AI 配个“记事本”：让 AI 学会利用自己之前的思考来辅助现在的思考（就像 GPT 那样）。
3. 别盲目迷信大模型：在处理复杂架构时，有时候小模型反而更靠谱，或者我们需要给大模型换一种“思考方式”。

总结

这篇论文就像给 AI 界敲了一记警钟：现在的 AI 在写代码片段时是天才，但在理解整个软件大厦的结构时，还是个容易迷路、容易失忆的“新手”。

作者把这套测试工具（TOCS）开源了，就像把“迷宫地图”和“评分标准”公开给大家，希望未来的 AI 能真正学会像人类工程师一样，去构建和维护复杂的软件世界。

技术摘要

《代码空间理论 (TOCS)：代码智能体是否理解软件架构？》技术总结

1. 研究背景与问题定义

尽管大型语言模型（LLM）在代码生成基准测试（如 HumanEval）中表现优异，但在处理涉及多文件、相互依赖模块的真实软件工程任务时，往往难以维持连贯的软件架构理解。现有的基准测试（如 SWE-bench）主要关注补丁的正确性，而忽略了智能体在探索过程中如何构建、维护和更新对代码库架构的“信念状态”（Belief State）。

受空间推理领域“空间理论”（Theory of Space, TOS）的启发，本文提出了代码空间理论（Theory of Code Space, TOCS）。该理论将代码库理解视为在部分可观测环境下构建“认知地图”（Cognitive Map）的过程，旨在评估智能体是否能在探索过程中维持连贯的架构信念，并发现潜在的架构约束。

核心问题：

• 代码智能体能否在部分可观测（预算限制下打开文件）的环境中，主动构建并维护结构化的架构信念？
• 智能体能否发现代码中隐含的架构约束（如禁止的依赖、数据流验证链）？
• 智能体的“主动探索”能力与“被动接收”信息的能力之间存在怎样的差异（Active-Passive Gap）？

2. 方法论：TOCS 基准框架

2.1 环境设置

• 生成式代码库：使用过程化生成器创建具有受控架构结构的 Python 代码库（Pipeline 架构模式）。包含 27-30 个模块，分为数据 ETL、日志处理、文本处理等域。
• 部分可观测性：智能体在固定预算（默认 $B=20$ 次操作）下行动。
• 动作空间：
  • LIST: 列出目录文件（无内容）。
  • OPEN: 读取文件内容（消耗 1 预算）。
  • SEARCH: 搜索符号位置（无内容片段）。
  • INSPECT: 查看符号签名和文档字符串（轻量级探索）。
  • DONE: 终止。
• 关键设计：SEARCH 仅返回位置，迫使智能体必须通过 OPEN 决策来理解架构；INSPECT 提供架构线索但不消耗完整文件内容。

2.2 认知地图探测 (Cognitive Map Probing)

• 机制：每执行 $K=3$ 次动作，强制智能体将其当前的架构信念以结构化 JSON 格式外部化。
• 探测内容：
  1. 组件信念：状态（观察/推断/未知）、目的、导出符号及类型签名、带置信度的依赖边。
  2. 不变量信念 (Invariants)：结构化约束（如“模块 A 不得直接导入模块 C"）。
  3. 不确定性追踪：未探索区域列表。
• 目的：生成时间序列数据，不仅评估最终结果，还评估理解是如何随时间演变的。

2.3 评估指标

• 依赖 F1 (Dependency F1)：预测的依赖边与真实依赖图（IMPORTS, CALLS_API, DATA_FLOWS_TO, REGISTRY_WIRES）的匹配度。
• 不变量 F1 (Invariant F1)：智能体发现的架构约束与预设约束的匹配度。
• 主动 - 被动差距 (Active-Passive Gap, APG)：比较主动探索与被动接收（全量文件、Oracle 选择文件、重放轨迹）的表现差异。
• 信念状态稳定性：探测过程中正确边是否丢失（信念崩溃）或更新。

3. 主要实验结果

实验使用了 4 个规则基线（如 BFS 导入、随机探索）和 6 个前沿 LLM（GPT-5.3-Codex, Claude Sonnet 4.6, 以及多个 Gemini 版本）。

3.1 核心发现

1. 模型依赖的“主动 - 被动差距” (Model-Dependent Active-Passive Gap)

   • GPT-5.3-Codex：主动探索表现优于一次性接收所有文件（APG = -0.22）。这表明该模型能更好地处理信息过载，通过逐步聚焦来构建理解。
   • Gemini 2.5 Flash：主动探索表现差于被动接收（APG = +0.23）。该模型在一次性看到所有文件时表现更好，说明其主动探索策略（文件选择）效率较低，或者其推理能力更适合全局上下文而非增量探索。
   • 结论：主动探索本身是一项非平凡的能力，并非所有模型都具备。

2. 信念外部化的自我脚手架效应 (Model-Dependent Self-Scaffolding)

   • GPT-5.3-Codex：将之前的探测结果（JSON 地图）保留在上下文中（Scratchpad 模式），能显著提升性能（F1 提升约 14 点）。模型利用之前的信念作为外部工作记忆来指导后续探索。
   • Gemini 2.5 Flash：保留之前的探测结果对其依赖边发现几乎没有帮助（F1 变化 -0.011），但在不变量发现上有显著提升。
   • 结论：自我脚手架机制的效果高度依赖于模型架构和训练目标。

3. 信念状态维护的巨大差异 (Belief State Instability)

   • 稳定性：较小的模型 Gemini 2.5 Flash 在所有探测中保持了完美的信念稳定性（零正确边丢失）。
   • 崩溃：较大的模型 Gemini 2.5 Pro 表现出灾难性的信念崩溃：在构建出合理地图后，单次探测就丢失了大量已发现的组件。
   • 结论：信念状态的稳定性与模型规模不成正比，可能取决于训练目标（如是否被训练为“从头总结”而非“增量更新”）。

3.2 边缘类型发现能力

• LLM 智能体能够发现所有四种边缘类型（包括需要多跳推理的 DATA_FLOWS_TO 和配置驱动的 REGISTRY_WIRES），而基于规则基线（如 BFS-Import）通常只能发现前两种。
• Claude Sonnet 4.6 表现出极高的精确度（0.983），但召回率较低；GPT-5.3-Codex 则追求更广泛的覆盖（召回率 0.597）。

3.3 架构约束发现

• 通过改进探测提示词（Prompt），LLM 在发现预设架构约束（如禁止依赖、数据流验证链）方面取得了显著进展（Relaxed F1 达到 0.5-0.78），而早期提示词下所有模型得分为 0。这表明提示工程对信念外部化至关重要。

4. 关键贡献

1. TOCS 基准框架：首个针对代码中“主动架构信念构建”的基准测试，引入了部分可观测环境、结构化信念外部化和时间序列评估。
2. 过程化代码生成器：生成了包含四种边缘类型（IMPORTS, CALLS_API, DATA_FLOWS_TO, REGISTRY_WIRES）和 15+ 种预设架构不变量的代码库，模拟了真实世界的复杂性。
3. 实证发现：揭示了模型在主动探索、自我脚手架和信念稳定性方面的显著差异，挑战了“模型越大越好”的简单假设。
4. 开源发布：将 TOCS 作为开源工具发布，包含生成器、评估框架和基线代码。

5. 意义与启示

• 对代码智能体设计的启示：
  • 单纯的工具增强检索不足以解决架构理解问题，需要显式的信念外部化和状态管理。
  • 混合方法（AST 静态分析 + LLM 语义分析）可能是最佳路径。
  • 探索策略（决定打开哪个文件）是当前的关键瓶颈，Oracle 选择文件与智能体自主选择的差距可达 6-17 个百分点。
• 对基准测试设计的启示：
  • 提示词的具体定义（如边缘类型的决策规则）会显著影响结果，甚至掩盖模型能力的真实差异。
  • 探测（Probing）不仅是测量工具，更是一种主动干预，能改变智能体的探索行为（如 GPT 在探测后主动打开了更多模块）。
• 理论价值：证明了在软件工程领域，维持内部认知地图的能力（Belief Maintenance）是区分高级智能体与简单模式匹配者的关键，且这种能力在不同模型间存在巨大差异。

6. 局限性与未来工作

• 当前版本仅支持 Python 和 Pipeline 架构模式。
• 实验基于单次运行，未来需要大规模重复实验以消除随机性。
• 信念外部化是内部状态的代理，模型可能“知道”但未“序列化”出所有信息。
• 未来将扩展至更多语言、架构模式，并引入“信念修正”（Revise）和“利用”（Exploit）阶段的评估。

总结：TOCS 揭示了当前最先进的代码智能体在构建和维护软件架构认知地图方面仍存在显著缺陷，特别是信念状态的稳定性问题。该基准为评估和提升代码智能体的深层理解能力提供了新的维度和工具。