李婧Amy写这个版本的时候，我正被一个一万多行代码的权限重构项目折腾得头大。之前用 Comate 处理这种多文件、跨模块的任务，它总是一股脑把代码改了，然后我花两小时收拾它改出来的接口兼容性问题。这次 3 月升级重点提到的两个东西——全新 Plan 模式、Explore Subagent 深度检索能力增强，恰好都打在“AI 助手到底怎么参与真实项目”这个痛点上。这篇文章我就从实际使用者的角度，把这俩功能的机制、适用场景、操作步骤和踩坑经验一次性说清楚。
如果你也遇到过以下情况：让 AI 助手改个小函数还好，一让它做“给登录模块加个找回密码功能”这种跨文件任务就开始乱来；或者在几万文件的代码库里查个东西，检索结果前后矛盾、找不全调用方，那这篇内容应该能帮你省下不少时间。
1. 这次升级到底在改什么
1.1 从“问答式助手”到“项目级助手”的转折
以前我们用的 AI 编程助手，本质上是“问答式助手”。你问一句，它答一句，顶多帮你补全当前文件的函数。它的逻辑很直接：根据你的输入和当前代码上下文，预测一段输出。在单文件场景下，这套机制成熟稳定，比如写个工具函数、补充注释、生成单元测试，体验都不错。
但真实项目不是单文件。一个功能可能横跨前端页面、后端接口、数据库表、权限校验等多个模块。老式助手最大的问题在于：它没有“任务目标树”，也没有“全局视野”。你让它实现“按部门汇总导出”，它可能直接在某个工具类里塞一个方法完事，完全不管调用链、权限边界、导出格式兼容性。说白了，它只会“编代码”，不会“做项目”。
Comate 这次的全新 Plan 模式，就是冲着这个问题来的。它把“写代码”这件事拆成了“理解需求 — 拆解计划 — 分步执行 — 验证收敛”四个环节，每个环节都可以人工介入。这已经不是一个简单的代码补全工具，而是一个“项目级编码代理”的工作方式。
1.2 为什么是这两个能力一起升级
光有 Plan 模式还不够。计划做得再漂亮，如果 AI 对现有代码库的理解是片面的，执行起来照样翻车。比如它打算“复用现有的导出工具类”，但那个工具类根本在另一个模块里，或者已经被废弃了，这时候计划就成了一纸空文。这就是 Explore Subagent 深度检索能力要解决的问题。
这两个功能放在一起升级，实际上是在补全一个完整的闭环：先检索摸底，再制定计划，最后按计划执行。没有 Explore Subagent，Plan 就是个空壳，因为计划质量高度依赖对代码库的掌握；没有 Plan 模式，Explore Subagent 收集来的信息也只能用于回答问题，没法真正驱动一次多文件改造。所以这不是两个孤立的新功能，而是同一套“AI 参与复杂开发任务”能力的两根支柱。
我自己的使用体验是，升级之后，最明显的变化不是单次回答变聪明了，而是它不再急着写代码了。你提一个需求，它先给你一份计划书，你确认了它才动手。这一步在真实开发里太重要了，因为它把“改代码的主动权”重新交还给了人。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 全新 Plan 模式：从“自动改”到“先规划、再动手”
2.1 Plan 模式的定位与适用边界
新版本里，Plan 模式不是把原来的对话模式替换掉，而是在旁边多了一条更重的工作流。它和普通对话模式的分工，我是这样理解的：
| 维度 | 普通对话模式 | Plan 模式 |
|---|---|---|
| 任务规模 | 单函数、单文件 | 多文件、模块级改造 |
| 上下文深度 | 当前文件和 用户简单描述 | 跨文件依赖链、项目结构 |
| 执行方式 | 直接输出代码 | 拆解任务 -> 逐步执行 -> 可审批 |
| 适合场景 | 解释代码、写小工具、补测试 | 新增功能、重构、迁移、修复杂 Bug |
| 风险控制 | 低，改错了重来 | 高，每一阶段可中断、回滚 |
我个人的选择标准很简单：如果这个改动涉及的文件数超过 2 个，或者需要同时修改接口和调用方，我就切 Plan 模式。如果只是一个函数内部的逻辑调整，用普通对话模式反而更快，Plan 模式的规划开销会显得有点“杀鸡用牛刀”。
这里要特别提醒一下，Plan 模式不是万能药。它适合那种“任务目标清晰、但步骤需要推演”的场景。如果你的需求本身就很模糊，比如“优化一下这个项目的性能”，Plan 模式生成的第一版计划大概率也是泛泛而谈。所以使用 Plan 模式的第一个技巧就是：先把自己需求里的“完成标准”讲清楚。
2.2 Plan 模式的核心机制：目标树、分步执行与审批
Plan 模式收到需求后，做的第一件事不是写代码，而是输出一份结构化的执行计划。我整理了一下它的核心机制，可以归纳为三个词：
- 目标树（Goal Tree）：把总目标拆成若干层级的子任务。比如“新增按部门汇总导出功能”，顶层是“实现报表导出”，第二层可能是“扩展数据聚合逻辑”、“新增导出入口”、“补充权限校验”，每个子任务还有自己的依赖条件。
- 分步执行（Stepwise Execution）：计划确认后，按顺序执行。每一步可能涉及读取文件、修改代码、运行检查。步骤之间有依赖关系，前一步没完成，后一步不会启动。
- 审批控制（Approval Control）：这是和普通模式最大的区别。你可以选择“一次性批准全部执行”，也可以选择“每执行一步都等人工确认”，甚至可以在某一步执行完成后单独修改这一步的产物再继续。
实际用下来，我强烈建议在涉及接口变更、数据库结构修改的任务里，选“逐步批准”模式。虽然多花一点操作时间，但每个阶段结束后你都能看看它改了什么，是否和预期一致，再决定放行还是回退。这比事后一堆 diff 让你自己 review 要省心太多。
2.3 Plan 模式实操注意事项
讲几个我在实际使用中踩过的坑和总结出的经验：
第一，需求描述里务必写明“范围边界”。 有一次我让它重构一个权限校验模块，忘了写“只改模块内部，不动调用方接口”。结果它“贴心”地把调用该模块的其他三个文件也一并改了，还改了接口签名，导致我在代码评审时被追问了半天。现在我描述需求一定会带上一句“本次改动范围限于 XX，不涉及 XX”。
第二，计划生成后，重点检查的是依赖顺序，不是措辞。 AI 生成的计划文本通常读起来很顺，但你要留意子任务之间的先后关系是否合理。比如“先改数据库表结构，再改数据访问层，最后改前端页面”这个顺序是对的；但如果计划里出现“先改前端页面，再改后端接口”，那后面大概率要对齐字段名返工，需要手动调整计划再执行。
第三，遇到计划与项目实际结构不符时，别急着执行。 有一次它计划里引用了某个工具类的名字，但我印象中这个类已经重命名了。这时候最好的做法是切到 Explore Subagent 确认一下，然后回到 Plan 模式修正计划。直接执行的话，它会在中途自己“发现”类不存在，然后绕道——有时候绕得对，有时候绕出一个四不像。
3. Explore Subagent：深度检索能力增强到底强在哪
3.1 Subagent 架构：为什么检索值得单独一个“代理”
要理解 Explore Subagent 的价值，得先明白一个大模型面对大型代码库时的物理限制。模型上下文窗口再大，也不可能把几十万行代码一次性塞进去等量处理，而且塞进去也没用——信息太多等于没有信息，关键线索会被海量无关代码淹没。这就是为什么需要把“检索”从主对话流程里抽出来，做成一个专门的 Subagent。
在 Comate 的架构里，主 Agent 负责推理、决策、写代码，Explore Subagent 负责“侦察”。主 Agent 遇到需要找证据的场景时，会向 Explore Subagent 派发任务，而不是自己去逐个翻文件。Explore Subagent 带着具体问题去检索，把结果整理成结构化摘要，再回传给主 Agent。这个分工就像项目经理和现场施工员的配合：项目经理不用自己去数钢筋，施工员把数据摸清楚报上来就行。
这次升级里，Explore Subagent 的深度检索能力增强，核心是三件事：混合召回、依赖感知、多粒度上下文压缩。下面分别展开。
3.2 检索能力的三个核心增强点
第一个增强点是“语义检索 + 符号索引”的混合召回策略。之前的检索基本靠关键词匹配，你搜“导出功能”，它只能返回字面命中“导出”这两个字的文件。现在它能理解模糊意图，比如你搜“按部门汇总导出”，它可以返回与“分组统计”“报表生成”“部门维度过滤”相关的实体。这相当于从“索引目录查词”进化到“理解语义联想关联”。
第二个增强点是跨文件依赖感知。这类工具最容易犯的毛病，是搜到的文件东一榔头西一棒槌，却不会告诉你文件之间的调用关系。升级后的 Explore Subagent 会顺着 import 语句、函数调用链、接口实现关系，把直接依赖和间接依赖一起摸出来。举个实际例子，你要确认“修改某个工具函数是否影响线上老接口”，它给出的结果不是一个孤立的函数定义，而是一条从“接口入口 -> 业务层 -> 工具函数”的调用路径，以及影响面清单。
第三个增强点多粒度上下文压缩。检索到一堆代码段之后，不是把原文全量回传，而是按场景生成不同粒度的摘要。如果主 Agent 需要判断是否调用某个接口，摘要会保留“函数签名、入参出参类型、关键注释”，同时丢掉函数体实现细节。这样既省上下文窗口，又不丢失决策所需的关键信息。
3.3 检索增强带来的实际变化
我自己在项目里做了几组对比测试，印象最深的有两个场景。
一个是在一个一万多文件的老项目里查“所有用到旧配置项 APP_DEBUG 的地方”。旧版检索返回了 15 个文件，但没有告诉我调用关系。我用 Explore Subagent 重新查，它输出了一份影响面分析：第一层是 6 个直接读取配置的模块，第二层是 8 个依赖这些模块的间接模块，还标出了其中 2 个在配置变更后可能触发异常的位置。这份清单直接成了我改造方案的基础。
另一个场景是“确认改某个公共数据模型会不会破坏兼容性”。它沿着模型类的引用链一路找到两个线上接口和一个定时任务的入口，并特别提示了其中一个接口的历史请求参数里有一个字段名与新模型定义不一致。这种“交叉验证”能力，比单纯搜出来 20 个文件再让我自己分辨要高效得多。
使用上有两个小建议：一是检索任务尽量用“我要做什么 + 我关心什么”的句式来描述，别只扔几个关键词；二是对大项目，可以先让它“摸清目录结构和模块边界”，再深入具体符号，分两步检索的效率往往更高。
4. 实操：一次完整的多文件功能开发（Plan + Explore Subagent 组合）
4.1 任务定义与初始侦察
为了把这套组合讲透，我模拟了一个常见的真实需求：在一个内部报表系统里，新增“按部门汇总导出”的功能。我全程用 Comate 的 Plan 模式加 Explore Subagent，下面按实际流程走一遍。
一开始，我先用一两句话把需求描述清楚，重点是加了范围边界：只新增报表页面的“按部门汇总”选项，导出格式沿用现有的 Excel 格式，不改动权限模型和数据表结构。
接着我没有急着让 Plan 模式直接生成计划，而是先让 Explore Subagent 做了一次初步侦察：
“这个报表系统里，现有的报表导出入口在哪些文件？导出格式定义在哪里？有没有现成的按时间维度汇总的逻辑可以参考？”
我用这种带明确目的的查询，得到的摘要里包含：报表列表页的前端组件路径、导出网关接口、Excel 生成工具类，以及已有按月汇总的服务类。有了这些信息垫底，再让 Plan 模式生成计划，它的基础设施就扎实多了。
4.2 在 Plan 模式下生成执行计划
我把需求描述和侦察结果一并交给 Plan 模式，它生成的第一版计划大致是这样的（我简化保留了实际格式）：
text复制任务：报表系统新增“按部门汇总导出”功能
├─ 阶段 1：数据聚合扩展
│ ├─ 1.1 读取现有按月汇总实现汇总模式枚举
│ ├─ 1.2 新增按部门维度的聚合查询（复用现有报表数据源）
│ └─ 1.3 为聚合结果补充部门名称字段映射
├─ 阶段 2：导出逻辑适配
│ ├─ 2.1 扩展导出参数 DTO，新增 departmentId 可选字段
│ ├─ 2.2 在导出服务中增加按部门筛选分支
│ └─ 2.3 保持 Excel 模板结构不变
└─ 阶段 3：前端入口与联调
├─ 3.1 报表页面新增“按部门汇总”选项
├─ 3.2 调用导出接口并传递 departmentId
└─ 3.3 补充空数据与异常提示
这个计划本身的分步很合理。但这里有个关键动作：我选择了“逐步骤滚动批准”，而不是“全部自动执行”。原因很简单，阶段 1 会改动数据聚合层，如果它顺手改了查询逻辑的默认行为，后面导出功能就会受影响。逐步骤批准让我可以在每个阶段结束后看 diff。
4.3 用 Explore Subagent 补齐两个关键信息
计划制定期间，我另外让 Explore Subagent 做了两次更深入的检索，主要是确认依赖和边界。
第一次检索：现有导出接口的请求参数结构。结果摘要显示 DTO 里已经有一个 unused 的 orgId 字段，但没有 departmentId。这条信息直接决定了我是否要新增字段，还是可以复用旧字段。实际上，为了兼容性，我决定新增字段，同时保留 orgId 的兼容解析逻辑。
第二次检索：导出工具类对于“数据分组”的支持程度。Explore Subagent 返回了工具类提供的分组聚合方法与 Excel 模板字段的映射关系摘要，并发现在某次历史迭代中模板里的“部门”列曾经被去掉过，导致如果按部门导出却没有该列，生成文件会缺失关键信息。这个风险点如果不做检索大概率会漏掉，执行完才发现就晚了。
这些摘要信息回填到 Plan 模式的上下文后，它后续生成的具体代码和我的预期基本一致，没有再出现凭空臆测接口的情况。
4.4 执行、验证与回滚
执行阶段我批准了阶段 1。Comate 修改了一个数据聚合服务类，新增了按部门维度的分组查询方法，并保留了原有按月汇总的实现。代码 diff 很干净。
阶段 2 执行时遇到了一点问题：它在改造导出服务分支时，把原来按时间过滤的条件也改动了一下，导致查询结果集不再包含“所有月份”的数据语义。我发现了这个偏差，于是走了一次回滚，只撤销阶段 2 当步的改动，重新让它保留原过滤条件、只增加按部门的筛选项。这个操作在 Plan 模式下非常方便，当我选择不批准那一步时，它回到上一步状态并等待新的指示，而不是把整个任务推翻重来。
最后阶段 3 是前端入口的调整。它正确识别了报表页面下拉选项的类型和事件绑定方式，新增了“按部门汇总”选项，并接好了新参数。测试时我先用单测验证了聚合逻辑，再手工触发导出，确认生成文件里部门分组汇总数据与数据库查询结果一致。整个过程跑下来，改动集中在 5 个文件里，没有出现一次“顺手改东改西”的越界行为。
5. 常见问题与排查技巧实录
5.1 Plan 模式相关的典型问题
问题一：Plan 模式生成的计划太长或太短，怎么判断是否合理？
太短的计划（比如只有两个子任务）通常意味着它没理解需求边界，可能漏掉了测试、兼容性处理等环节。太长的计划则可能过度拆解，把无关的优化也塞了进来。我的判断标准是：计划覆盖了“数据层、业务层、展示层、验证”这四个维度中实际涉及的维度，就算合理。如果它把“清理无用代码”“重构历史遗留方法”这种不在需求的子任务也列上，我会手动删掉。
问题二：计划与项目实际结构不符怎么办？
大概率是它没有完整掌握项目结构。先切到 Explore Subagent，把计划的引用点描述给它检索，拿到实际的类名和路径之后，再回来修正计划。直接改计划的文本内容也能行，但确认实际情况更稳妥。
问题三：如何避免 AI 在计划中擅自扩大改动范围？
除了在初始需求里写明“范围边界”，另一个实用技巧是：在计划确认时，主动删除与需求无关的子任务。Plan 模式是允许编辑计划内容的，删掉不合理的步骤再执行，等于提前剥夺了它“临场发挥”的机会。
5.2 Explore Subagent 检索相关的典型问题
问题一：检索结果噪音大，怎么优化查询描述？
我一般会把查询改成“找 XX 的入口 / 调用方 / 数据定义”这种带结构指向的描述。比如搜“导出”，改成“找到报表导出的服务入口，以及它的调用方”效果会好很多。限制返回范围也很重要，比如“只看 /backend 目录下的文件”。
问题二：找不到某类符号，先确认索引状态。
在实际使用中遇到过一次搜索新写的枚举类返回空结果。检查后确认是新文件没有被索引识别。处理方式是触发一次索引刷新再重新检索，通常就能命中了。如果你也和某 IDE 插件配合使用，留意是否插件缓存了旧的项目索引。
问题三：检索回的跨文件结果如何验证可信度？
我会交叉验证两条线索：一是看摘要里有没有给出“调用路径”而不是孤立文件列表；二是对关键结论让它同时在“相反方向”再检索一次。比如它说“A 调用了 B”，我就反向检索“B 被哪些模块调用”，如果两边结果对得上，可信度就比较高。
5.3 双能力协同时的使用建议
组合使用两个功能时，我摸索出来的最优顺序是：先用 Explore Subagent 做初步侦察（搞清楚项目结构和关键入口），再让 Plan 模式基于侦察结果制定详细计划，在计划执行过程中遇到不确定的依赖时，随时再唤起 Explore Subagent 做定向确认。
这里面有一个容易被忽视的原则：检索是给计划喂信息的，计划是给执行定边界的。两者配合的关键不是每次都全套流程，而是按需分配。小任务直接用对话模式；中型任务上 Plan 模式、开逐步骤批准；大型任务才需要先侦察、再规划、再执行的完整组合。如果你只是改一个配置文件，也非要跑一遍完整闭环，那纯粹是给自己添堵。
说实话，这次升级让我重新思考了 AI 编程助手的定位。最有价值的不是它一次性写出多少代码，而是它终于愿意把“规划”和“检索”的主动权交还给开发者。AI 负责执行和整理，人负责方向和边界，这种分工方式对真实项目来说才算健康。最后分享一个小技巧：升级之后，记得去设置里看看 Explore Subagent 的索引策略选项，默认配置适合中小项目，如果你的项目文件数超过一万，建议把索引深度调高一档，检索召回率会有明显提升。