@ericxyuan: 编码代理能理解代码，但无法记住它。我们发布了ShadowFrog，一套开源技能，用于构建……

编码智能体能理解代码，但记不住代码。我们发布了 ShadowFrog，一套开源技能，用于构建持久化的影子知识库，使得智能体的理解能力能在会话间持续累积。https://microsoft.github.io/debug-gym/blog/2026/06/shadow-frog/… https://github.com/microsoft/ShadowFrog… ↓ (1/10) — # Shadow-Frog：会做梦和发现问题的编码智能体 来源：https://microsoft.github.io/debug-gym/blog/2026/06/shadow-frog/ 图0 — 一次野外的梦境探索。 一个仓库的完整演化太阳burst图（pydata/xarray，n = 115次梦境）。每个切片代表一次自主梦境；环向外延伸表示后续梦境从早期梦境分支而来；颜色表示梦境探索的工作类型（后面我们会再次用到这个分类体系）。我们将在后续章节详细解释“梦境”和“累积”的含义。## TL;DR Shadow-Frog 是一种智能体发现系统，通过主动探索而非被动记录，为编码智能体构建代码库记忆。Shadow-Frog 将编码智能体的空闲时间转化为自主的发现循环。在发现会话中，智能体对代码库中尚未充分探索的部分运行实验，并将学习成果捕获到影子知识库中。我们发现，与基线相比，Shadow-Frog 智能体在知识检索、缺陷检测和新功能构思方面表现更优。与其它离线记忆系统不同，Shadow-Frog 不会被动地 Consolidate 过去任务的记忆。智能体通过实践主动学习：获取人类程序员只有亲身处理代码库才能获得的隐性知识。当你启动一次发现会话（通常在离开 IDE 之前），智能体会等待一个任务：它会针对你的代码库设想实验，在独立的 Git 分支上运行这些实验，并将其学到的东西提炼到影子知识库中：一个\.shadow/目录，镜像了源代码树。每个文件都有一个对应的 Markdown 文件——影子文件——它记录了智能体关于相应文件中的代码实际行为所学到的内容。这种影子文件结构使得智能体在未来的会话中，相比于筛选一个扁平文件，能更快、更容易地找到相关的发现。后续的每次交互都能受益于影子已有的知识。我们在五项研究（检索、对合成缺陷和真实缺陷的盲缺陷狩猎、功能构思、缺陷修复）中对系统进行了评估，每项研究都针对一个匹配的基线（相同模型、相同仓库访问权限、无影子）。三个主要结果： - 1 影子召回。 结构化的影子是否真的比扁平文件更容易让智能体导航？Shadow-Frog 的按文件布局（每个源文件对应一个影子文件）在仅允许 8 次工具调用（智能体允许执行的读文件或搜索）的情况下，在 django 和 fastapi 上进行了 69,342 次运行，达到了 97.6% 的检索准确率。结构至关重要：扁平影子（所有内容在一个文件中）在相同预算下仅得分 36.2%。 - 2 盲缺陷狩猎。 空闲时间的探索能否发现代码中的真实问题？在没有问题描述和任何提示的情况下，智能体仅通过空闲时间探索就发现了缺陷。在 20 个仓库 × 100 个合成缺陷（SWE-Smith）上，Shadow-Frog 比基线高出 +25.4 个百分点（71.5% vs 46.0%），在 20 个仓库中赢了 15 个。在 SWE-Bench Verified 的 50 个真实缺陷上，它在 88% 的情况下标出了正确的模块，在 22% 的情况下标出了确切的缺陷函数。 - 3 功能构思。 累积的知识能否帮助智能体预测要构建什么？在 8 个开源仓库（固定在 2023 年 1 月）上的梦境探索，智能体预见到了维护者后来实际发布的功能：比无影子基线高出 +10.4 个百分点的对齐度，并且一个盲评判断器对 Shadow-Frog 创意的洞察力评分高了 +0.40（1–5 分制，所有 8 个仓库）。完整数字、每个任务的亮点以及消融实验见下面的评估部分。 ## 为什么我们要构建它 现代智能体记忆主要保留智能体在交互过程中已经看到的内容。但成熟的代码库包含另一类知识：只有通过运行代码才会显现的隐性知识。哪个重构会静默破坏下游调用者？文档在哪些地方悄悄地与实现不一致？测试套件从未实际测试哪些不变量？这种洞察很难在文档中找到，也同样难以通过被动记忆系统浮现。我们想要一个系统，能够在智能体的空闲时间里自主收集这类知识：在用户提问之前就预判他们可能需要什么。在空闲时间（喝咖啡、午餐、过夜、周末），Shadow-Frog 可以对仓库的候选任务进行做梦（一个新功能、重构、安全审计、性能优化），并认真执行这些任务，一批接一批。通过分析自己的尝试，智能体学到了仅通过阅读代码无法推导出的关于代码库的知识。总结来说，首先，我们模仿工程师自身了解代码库的方式：通过编写和运行代码，而不是再读一遍源代码。其次，我们将知识库视为需要通过主动发现而非被动记录的东西：智能体会去查找它不知道的东西，而不是等待材料飘过。第三，影子是仅通过阅读源代码难以浮现的知识的归宿：那些只有某人实际尝试某件事（实现新功能、模糊测试输入、利用代码路径）时才会显现的行为事实。 ## 影子记忆载体 影子是一个\.shadow/文件夹，镜像了源代码树。每个代码文件都有一个对应的 Markdown 文件，其中包含智能体了解到的关于该文件的信息；跨越多个文件的洞察存放在\.shadow/\_cross/中，并在符号级别（file::function）从两侧引用。索引就是仓库本身：没有向量存储、没有嵌入数据库、没有独立的检索服务。任何能够导航代码库的智能体都已经知道给定文件的影子在哪里：如果你正在编辑src/parser\.py，你检查\.shadow/src/parser\.py\.md。发现带有其来源标记：exploration（智能体运行了实验）、user（人类在对话中陈述的）、或interaction（在协作调试中出现的）。用户来源的知识是最高信任级别的，并且以与梦境发现相同的保真度捕获。可操作的发现还可以额外携带一个或多个标签（bug、security、performance、feature-gap、tech-debt），并且一个preToolUse钩子（在智能体编辑文件之前触发的自动触发器）会在智能体即将修改周围代码时内联bug和security标签。这种设计带来了两个后果。首先，任何能运行cat和grep的智能体都可以即开即用地使用影子：不需要嵌入管道、不需要特殊客户端、不需要模式迁移。其次，更新是稀疏的：当源文件发生变化时，/shadow-frog-update会针对最后一个已知提交进行差异比较，并只遍历受影响的路径，刷新结构部分并重新检查锚定在那里的发现。影子随着仓库的增长和老化，粒度与 git diff 一致。 图1 — 影子镜像了源代码树。 每个源文件与\.shadow/中的一个对应 Markdown 配对；跨领域的发现存放在\.shadow/\_cross/中，并锚定在两侧的特定file::symbol位置。任何一个文件的读者仍然可以找到关于该文件如何与代码库其余部分交互的所学内容。## 梦境：发现循环 每次梦境都是一次实验：智能体选择一个它认为有用的任务，打开一个平行的 Git 分支，真正实现它，并运行所需的脚本和测试。无论代码是否被合并都几乎无关紧要（按设计，大多数不会被合并）。真正的输出是智能体在此过程中了解到的关于代码库的内容：只有当你实际运行代码时才会浮现的具体行为事实。 ### 想象 智能体想象针对代码库中尚未充分探索部分的候选任务：新功能、重构、安全审计、缺陷狩猎、性能优化。候选任务分布在六个调查类别中，并偏向于影子极少触及的文件，这样智能体就不会一直戳它已经理解的代码。智能体不是等着被提问，而是提出关于代码库接下来需要什么的假设，并将每个假设作为探测它以前没有探测过的地方的借口。 ### 在真实分支上执行 每次梦境都会生成一个工作线程，它会打开一个平行的 Git 分支，拾取任务，并逐步完成：读写文件、运行脚本、调用测试。每次提交都落在专用的dream//分支上。梦境结果是在真实分支上的实时、可运行的代码，而不是存放在文件中的补丁。审核者可以签出一个分支，运行它，并准确看到智能体是如何得出结论的。 ### 累积的梦境，在梦境之上构建 今天的编码智能体会话通常在智能体宣布成功的那一刻结束（任务完成、测试通过、PR 草稿），这使得每个会话都很短暂且自包含。另一方面是浅层开发：每个新会话从main重新开始，没有对上一次会话的走向的记忆，需要多个会话才能完成的调查很少发生。累积的梦境旨在打破这个天花板。由于梦境分支持久存在，后续梦境可以从之前的梦境分支分支出来，而不是从main分支，例如，一个原型化重试层的梦境变成了添加超时处理的梦境的起点，而这又变成了加固整个 HTTP 层的梦境的起点。每个梦境都会在\.shadow/\_dreams//下存档一个简短的结构化报告，包含基础提交、分支名称、父分支、类别以及一个useful/dead_end裁决，以及一个发现清单，供协调脚本合并到main上的影子中。未来的梦境会话会首先读取过去的报告，避免死胡同，并继续部分有用工作。知识在跨会话间累积，而不仅仅是在一个会话内。 发现循环。四个步骤：想象一个任务，在梦境分支上运行它，提炼出一个发现，将其合并到影子中，然后返回想象。插图显示三个梦境分支相互分叉以累积知识。图2 — 发现循环。 每个空闲时刻都从左侧的循环开始：智能体想象一个候选任务，在专用的梦境分支上运行它，将结果提炼成一行发现，然后将该发现合并回影子中。右侧的插图显示了累积机制：后续梦境从早期的梦境分支（而不是main）分出来，因此每个梦境都继承了其父分支的代码和影子。帖子顶部梦境探索图中的环正是从上方看到的这种分支结构。 ### 提炼发现 梦境的实验代码可能永远不会合并到主仓库中（大多数不会，这是设计使然）。然而，这些梦境所做的发现是重要的部分：每个发现都是一个单句的行为事实，锚定在正确的符号上，标有其来源，并带有verified（通过实际运行代码确认）、uncertain（合理但未确认）或refuted（已探索并发现错误）标签。所有三种状态都会连同其标签合并到main上的影子中，以便未来的会话对verified声明采取行动，将uncertain声明作为线索，并避免重新走refuted的路。梦境存档的报告、清单和补丁差异存放在\.shadow/\_dreams//中，是持久的证据，以防我们后来想知道如何知道。 ## 评估 除非另有说明，所有实验都使用Claude Opus 4.6作为后端 LLM，在Copilot CLI智能体框架内运行。在我们衡量跨 LLM 泛化能力（第4节中的鲁棒性重新评分）的地方，我们还使用 Opus 4.7 和 GPT-5.5 作为独立的判断器。 ### 1 · 在影子干草堆中找针 在衡量影子的能力之前，我们验证智能体能够读回它。我们在仓库内的影子文件中植入一句合成事实（“针”），然后问智能体一个问题，答案需要这些针。以下是来自 django 评估的一个真实例子： 针：.shadow/django/db/models/query_utils\.py\.md → Q 关键字在作为子节点存储之前经过排序，因此 Q(a=1, b=2) 和 Q(b=2, a=1) 产生相同的对象。 提示给出：django/db/models/query_utils\.py::Q 您将要对 Q 进行更改。枚举所有与此处安全更改相关的先验项目知识项。 我们测试了三个系统在此类任务上的表现：Shadow-Frog（我们的镜像布局，每个源文件一个影子文件）、扁平影子（所有发现转储到一个巨型文件中）和无影子（相同模型，无知识库）。每个系统都获得相同的文件路径提示和 8 次工具调用的预算。在69,342 次运行中，涵盖了 django + fastapi、5 种影子大小（50 → 35k 针）、7 种工具调用预算（1 → 无限制）和 2 种任务框架，Shadow-Frog 在现实配置（django，约 2,500 针的影子，给出文件路径，预算为 8 次工具调用）下达到了 97.6% 的召回率，而扁平影子的召回率为 36.2%，无影子为 12.4%。在上面的例子中，对比更加明显： **Shadow-Frog：**glob → 查看 20 行文件 → 回答。4 次调用，召回率 100%。 **扁平影子：**在 9,301 行的庞然大物内进行了 7 次定位调用，在第 8 次调用时找到了针，但在回答前预算耗尽。召回率 0%。 无影子：在源码中 grep 了class Q，找到了定义，但植入的事实只存在于影子中。召回率 0%。 “给出文件路径”是现实姿态，而不是人为的便利。正如我们在上面所说，索引就是仓库本身，所以每当智能体正在读取一个源文件时，它已经知道匹配的影子在哪里，中间没有检索查找。按文件布局使得这在机械上可推导（query_utils\.py→\.shadow/\.\.\./query_utils\.py\.md），所以智能体一次 glob 就到达了正确的 20 行文件。扁平转储迫使搜索数百个符号标题，将预算消耗在定位而不是检索上。在无限预算下，扁平影子会赶上，但在现实预算下，影子的结构与它的内容同样重要。在“必须搜索”行也出现了类似情况：每个具有真实影子大小和现实预算的单元格都显示了相同的形状。 图3 — django 上的召回率：Shadow-Frog vs 扁平 vs 无影子。 *行：*智能体是否收到了文件路径，还是必须搜索？*列：*影子大小（50 → 35k 针）。*x 轴：*工具调用预算（1 → ∞）。标题中的单元格（高亮）是现实情况：给出了文件路径，2,500 针影子。在仅 8 次工具调用的预算下，Shadow-Frog 已经达到了 97.6%，而扁平影子为 36.2%，无影子为 12.4%。扁平→Shadow-Frog 的差距只有在更高的预算下才会消失。悬停在任意点上可查看精确召回率；切换置信区间复选框。 ### 2 · 对合成缺陷的盲缺陷狩猎 梦境知识库的构建不依赖于任何已知存在的缺陷。一旦影子构建完成，我们将智能体指向仓库并询问“有什么问题？”，没有问题描述，也没有提示。当 LLM 判断器裁定智能体的报告足以让开发者仅根据报告修复缺陷时（“严格层级”），我们称缺陷被“发现”。在 20 个仓库 × 每个 100 个合成缺陷（SWE-Smith 同时将无冲突的缺陷注入单个仓库，并移除所有测试）上，与匹配的无影子基线（在 10 个预算级别上扫描，即每个任务分配的独立子智能体数量，从 12 到 120）相比，Shadow-Frog 比基线高出 +25.4 个百分点（71.5% vs 4