1. 项目缘起：当AI不只是代码补全

最近在GitHub上闲逛，看到不少项目标题里都带着“Agentic AI”或者“AI Town”之类的词，感觉这股风是越刮越猛了。作为一个常年混迹在开源社区、喜欢折腾各种自动化工具的程序员，我对“AI智能体”（AI Agent）这个概念一直很感兴趣。它早就不是那个只会根据上下文给你补全一行代码的“高级提示词”工具了。现在的趋势是，AI要能自己“想事儿”，能规划一系列动作去完成一个复杂目标，比如从零搭建一个微服务，或者修复一个包含多个文件的Bug。

这让我想起了之前用过的不少AI编程工具。早期的工具，更像是“超级联想输入法”，你写个函数名，它帮你补全函数体。后来有了GitHub Copilot，它能理解更多上下文，甚至能根据注释生成代码块。但这些都还是“反应式”的——你给一个刺激（输入），它给一个反应（输出）。而“智能体”应该是“主动式”的，它内部得有一个“计划”（Plan）。这个计划不是我们人类写的待办清单，而是AI根据一个高层目标（比如“实现用户登录功能”），自己拆解出来的、一系列可执行的、有逻辑顺序的子任务步骤。

所以，当我看到《An Exploratory Study of Agent Plans for Agentic AI Coding Tools in Open-Source Software》这个标题时，立刻就被吸引住了。这研究的正是开源软件场景下，那些能自主编码的AI工具，其内部“计划”是如何生成和演进的。这不再是问“AI生成的代码质量如何”，而是深入到了“AI是如何思考并规划出这些代码的”这个更本质的层面。对于想真正用好这类工具，甚至参与构建这类工具的开发者来说，理解其“计划机制”至关重要。否则，我们只是在用一个黑箱，一旦它出错或者产生“幻觉”（生成看似合理实则错误的代码），我们连调试和干预的入口都找不到。

2. 拆解核心：什么是Agentic AI Coding Tool的“Plan”？

要理解这项研究，我们得先掰扯清楚几个关键概念。不然，很容易把“智能体计划”和普通的“任务列表”或“代码生成提示词”混为一谈。

2.1 从“反应”到“规划”的范式转变

传统的AI编程辅助，无论多强大，其工作模式都可以概括为：用户输入（代码/注释/错误信息） -> 模型推理 -> 代码输出。这是一个单步的、封闭的交互。模型并不关心输出之后的世界，也不负责执行和验证。

而一个真正的Agentic AI Coding Tool（智能体式AI编码工具），其核心在于引入了“感知-思考-行动”的循环。它不仅仅生成代码，它还（或它所在的系统中）能够执行代码、观察执行结果（如测试通过与否、控制台输出）、并根据结果调整后续行为。这里的“思考”环节，很大程度上就依赖于“计划”（Plan）。

2.2 “Plan”的具体内涵与层次

在这个语境下，“Plan”不是一个静态的文档，而是一个动态的、可执行的数据结构或策略。它至少包含以下几个层次：

1. 目标抽象层：将用户模糊的、高层的需求（如“给这个React应用加一个黑暗模式切换按钮”）转化为一个明确的、可评估的AI目标（Goal）。例如，目标可能是：“修改App.jsx，引入一个状态管理黑暗模式的布尔值；创建或修改一个ToggleSwitch组件；确保样式表能响应状态变化。”

2. 任务分解层：将上述目标分解为一系列有序的、原子性的子任务（Sub-tasks）。这些子任务应该是AI能够直接理解并执行的。例如：

   • 子任务1：分析当前项目结构，定位主要的布局或根组件文件（如App.jsx）。
   • 子任务2：在App.jsx中引入useState钩子，添加isDarkMode状态及切换函数。
   • 子任务3：检查是否存在ToggleSwitch组件，若不存在，则生成该组件的基本代码。
   • 子任务4：将ToggleSwitch组件集成到App.jsx中，并绑定状态和函数。
   • 子任务5：检查CSS/样式文件，添加或修改支持黑暗模式的样式类。

3. 动作规划层：为每个子任务规划具体的“动作”（Actions）。在编码上下文中，动作通常是针对代码库的原子操作，例如：

   • READ_FILE：读取指定文件内容。
   • SEARCH_CODE：在代码库中搜索特定模式或组件。
   • EDIT_FILE：在文件的特定位置插入、删除或修改代码块。
   • CREATE_FILE：创建新文件并写入初始内容。
   • RUN_TEST：运行特定的测试命令。
   • EXECUTE_COMMAND：执行Shell命令（如安装依赖npm install）。

4. 状态评估与循环层：计划必须包含“检查点”（Checkpoints）。在每个或几个动作执行后，智能体需要评估当前状态是否与预期相符。例如，在执行EDIT_FILE后，可以自动运行一次语法检查（npm run lint）或相关单元测试。如果失败，则触发“重新规划”（Re-planning），可能回溯到上一步，或者尝试另一种解决方案。

2.3 与“提示词工程”的本质区别

很多人可能会觉得，我写一个非常详细的、步骤化的提示词（Prompt），不就是在给AI做计划吗？比如：“第一步，请打开App.jsx；第二步，在第10行添加以下代码...”。这确实是一种初级的、外部的计划。

但研究中所指的“Agent Plan”，是智能体内部自主生成的。它的输入可能只是一个简单的目标描述，然后由智能体自身的规划模块（可能基于大语言模型的思维链CoT、树搜索Tree of Thoughts，或专门的规划器）来产生上述多层次计划。这个过程的优势在于：

• 适应性：能处理未预见的错误。如果第一步创建文件失败（因为文件已存在），外部提示词工程可能就卡住了，而内部规划器可以调整计划，改为编辑现有文件。
• 可扩展性：计划可以很复杂，包含条件分支（if-else）和循环（while），以应对不同的代码库状态。
• 学习与进化：智能体可以从多次执行中学习，优化其规划策略，比如发现某种代码修改模式更容易通过测试。

所以，这项探索性研究，就是要打开这个“计划生成”的黑箱，看看在真实开源项目的复杂环境中，这些计划是如何被构建、执行、成功或失败的。

3. 研究方法论：如何“探索”AI智能体的计划？

既然是要做探索性研究，肯定不能只是纸上谈兵，或者拿几个玩具项目（Toy Project）做演示。它需要一套系统的方法，在接近真实世界的环境中，观察和记录智能体的行为。结合当前AI编码智能体的常见实现方式，我推测这项研究可能会采用以下一种或几种混合的方法论。

3.1 构建一个可观测的测试沙箱

研究的第一步，很可能是搭建或利用一个现有的、支持智能体编码的框架，比如基于OpenAI的Assistant API、LangChain的Agent模块，或者直接使用像Cursor、Claude Desktop（如果其具备智能体特性）以及一些开源框架如Open Interpreter、Aider的修改版。关键是要对这些框架进行“插桩”（Instrumentation），使其能完整记录下内部状态。

需要记录的数据包括：

• 原始用户请求：例如“为项目添加README文件”。
• 智能体的内部“思考”过程：如果模型支持输出思维链，这部分至关重要。它记录了模型是如何一步步推理出计划的。
• 生成的计划（Plan）：以结构化的格式（如JSON、YAML或自定义DSL）记录下被正式采纳的执行计划。
• 执行轨迹（Execution Trace）：按时间顺序记录每一个执行的动作（Action）、动作的输入参数、执行后的输出结果（成功、失败、返回内容）。
• 代码库的增量变化（Git Diff）：在每个计划步骤或整个计划执行前后，记录代码仓库的精确变化。
• 外部反馈：如测试运行结果、构建日志、静态分析报告等。

3.2 选取多样化的开源项目作为试验场

研究的可信度取决于测试场景的多样性。研究者可能会从GitHub上选取一系列具有代表性的开源项目，涵盖：

• 不同规模：从小型工具库（几千行代码）到中型应用（数万行）。
• 不同语言和栈：JavaScript/TypeScript (React, Node.js)、Python (Django, FastAPI)、Java (Spring)、Go等。
• 不同成熟度：新项目（结构清晰）和老项目（结构复杂，有历史债务）。
• 不同任务类型：
  • 功能添加：如“添加一个API端点”。
  • Bug修复：给定一个Issue描述，让智能体修复。
  • 代码重构：如“将这两个重复的函数抽取成公共工具函数”。
  • 文档生成：基于代码生成或更新文档。
  • 依赖升级：解决版本冲突。

3.3 设计具体的分析维度

有了大量的执行轨迹数据后，研究就可以从多个维度对“计划”进行定性或定量分析：

1. 计划生成的成功率：给定一个任务，智能体是否能生成一个看似合理的初始计划？有多少比例的任务在计划阶段就失败了（例如，无法理解任务或分解出可行步骤）？

2. 计划的质量评估：

   • 正确性：计划中的步骤序列在逻辑上是否正确？是否遗漏了关键前置条件（如未安装依赖就先导入模块）？
   • 效率：计划是否迂回？例如，是否反复读取同一个文件，而不是在内存中缓存内容？
   • 稳健性：计划是否包含了错误处理或回退机制？比如，当EDIT_FILE失败时，是否有备选方案？

3. 计划与执行的偏差分析：这是最有趣的部分。比较初始计划和实际执行轨迹。

   • 计划膨胀：实际执行的动作数量是否远多于计划？这可能意味着初始计划过于乐观，低估了复杂度。
   • 计划修正：智能体在遇到错误时，是如何修改后续计划的？是局部微调，还是推倒重来？修正策略的有效性如何？
   • “幻觉”在计划中的体现：智能体是否计划去操作一个不存在的文件或调用一个不存在的API？这种“计划层面的幻觉”比生成错误代码更隐蔽，危害也更大。

4. 上下文学习能力：在同一个项目上执行多个任务后，智能体生成的计划是否会有所改进？例如，它是否学会了这个项目的特定目录结构或编码规范，从而在后续任务中生成更精准的计划？

通过这套方法，研究就能超越“这个AI工具好不好用”的笼统评价，深入到“它在哪种情况下、因为何种原因、以何种方式成功或失败”的微观机制层面。

4. 实战推演：一个模拟案例的深度剖析

为了让大家更直观地感受“计划”的重要性以及可能遇到的问题，我们不妨模拟一个研究可能涉及的场景，并一步步推演一个AI编码智能体可能的行为。假设我们有一个简单的Python Flask开源项目，任务是：“为现有的/usersGET API 添加分页查询功能。”

4.1 理想中的“完美计划”

一个经验丰富的开发者可能会这样规划：

1. 分析现状：查看app.py中/users路由的处理函数，了解当前如何获取和返回用户数据（比如是从数据库直接User.query.all()）。
2. 设计接口：决定分页参数，比如page(页码) 和per_page(每页条数)，并考虑默认值。
3. 修改数据层：将数据库查询从获取全部改为使用offset()和limit()，并计算总数。
4. 修改业务逻辑层：在路由处理函数中接收参数，调用新的数据层方法。
5. 修改返回结构：将返回格式从用户列表改为一个包含data(用户列表)、page、per_page、total等字段的JSON对象。
6. 更新文档：修改相关的API文档（如Swagger/OpenAPI spec）。
7. 编写测试：为新的分页功能添加单元测试和集成测试。

4.2 AI智能体可能生成的初始计划

一个基于LLM的智能体，在接收到任务后，其规划模块可能会生成如下结构的计划（此处用伪代码表示）：

{ "goal": "Add pagination to /users GET endpoint", "sub_tasks": [ { "id": 1, "description": "Locate and read the current /users endpoint handler", "actions": [ {"type": "SEARCH_CODE", "query": "@app.route('/users')"}, {"type": "READ_FILE", "path": "<file_path_from_search>"} ] }, { "id": 2, "description": "Analyze the current data fetching logic", "actions": [ {"type": "ANALYZE_CODE", "code_snippet": "<content_from_step1>"} ] }, { "id": 3, "description": "Modify the endpoint to accept page and per_page query parameters", "actions": [ {"type": "EDIT_FILE", "path": "<file_path>", "operation": "insert", "location": "function_args", "code": "page=1, per_page=20"} ] }, { "id": 4, "description": "Rewrite the database query to use limit and offset", "actions": [ {"type": "EDIT_FILE", "path": "<file_path>", "operation": "replace", "old_code": "User.query.all()", "new_code": "User.query.paginate(page=page, per_page=per_page)"} ] }, { "id": 5, "description": "Update the return value to include pagination metadata", "actions": [ {"type": "EDIT_FILE", "path": "<file_path>", "operation": "replace", "old_code": "jsonify(users)", "new_code": "jsonify({ 'data': users.items, 'page': page, 'per_page': per_page, 'total': users.total })"} ] } ] }

这个计划看起来有模有样，逻辑也基本通顺。

4.3 计划执行中可能暴露的问题（研究关注点）

现在，让智能体开始执行这个计划。问题会接踵而至，这正是研究要观察的：

• 问题A：搜索失败（计划脆弱性）：SEARCH_CODE动作可能因为代码格式（比如路由装饰器换行）而找不到精确匹配，导致第一步就卡住。一个更健壮的计划应该包含备选搜索模式或允许手动指定文件路径。
• 问题B：知识“幻觉”（计划正确性）：在第4步，计划直接使用了User.query.paginate()。这是一个经典的“幻觉”案例！标准的SQLAlchemy并没有query.paginate()这个方法。这个方法常见于Flask-SQLAlchemy扩展或某些第三方库。如果项目使用的是纯SQLAlchemy，这个计划从根上就是错的。智能体可能混淆了不同框架的API。研究需要观察，智能体是在规划时就产生了这个幻觉，还是在执行EDIT_FILE后运行测试时才暴露出来？
• 问题C：遗漏关键依赖（计划完整性）：计划完全没有考虑分页需要计算总数，这通常需要单独的count()查询，或者使用支持分页的扩展库。它也没有检查项目是否已经引入了类似Flask-SQLAlchemy的库。如果没有，整个计划将无法实现。一个完整的计划应该在早期包含一个CHECK_IMPORTS或INSPECT_REQUIREMENTS的动作。
• 问题D：缺乏错误处理与回滚（计划稳健性）：假设智能体执行到第4步，成功替换了代码，但替换后的语法是错误的（因为幻觉）。当它尝试运行测试（如果计划里有这一步）时，会失败。一个成熟的智能体计划应该能捕获这个错误，分析错误信息（如AttributeError: 'Query' object has no attribute 'paginate'），然后触发“重新规划”。它可能会回溯，搜索项目中的其他查询示例来学习正确的API，或者尝试引入正确的分页库。

通过这个案例，我们可以看到，对“计划”的研究，核心就是审视智能体在理解环境、分解任务、选择工具、预见风险这些关键认知环节上的能力与局限。这项研究的意义，就在于系统地收集这类“失败模式”，为改进智能体的规划能力提供实证依据。

5. 核心挑战与未来方向：从“探索”到“工程化”

通过对智能体计划进行探索性研究，我们不仅能欣赏其潜力，更能清晰地看到当前面临的核心挑战。这些挑战也正是未来工具发展和学术研究需要攻克的方向。

5.1 当前面临的主要挑战

1. 环境理解的局限性：智能体对代码库的“感知”是局部的、基于搜索和读取的。它缺乏人类开发者拥有的“全局图景”和“领域知识”。例如，它可能不知道项目使用的特定设计模式、自研的内部框架约定、或者哪些模块处于“废弃但尚未删除”的状态。这导致其计划可能在不恰当的模块上进行修改，或者使用了被弃用的模式。

2. “计划幻觉”比“代码幻觉”更致命：大语言模型在生成代码时会产生幻觉（Hallucination），生成看似合理但错误的API或逻辑。在智能体场景下，“计划幻觉”问题被放大。一个基于错误知识（如误记API）生成的计划，会导致一系列连贯的错误动作，其调试和修复成本远高于单段错误代码。研究需要区分：幻觉是发生在目标理解阶段、任务分解阶段还是动作选择阶段？

3. 长程规划与上下文管理的矛盾：复杂的编码任务可能需要几十甚至上百个动作步骤。大语言模型的上下文窗口有限，如何让智能体在长序列执行中保持对原始目标、已执行步骤和当前状态的连贯记忆，是一个巨大挑战。计划可能需要被分层、分段，并在执行过程中动态加载和刷新上下文。

4. 反馈循环的延迟与模糊：编程任务的反馈往往是延迟和模糊的。运行一次测试可能需要几分钟，而测试失败只告诉你“没通过”，并不直接指明是计划中哪一步的逻辑出了问题。智能体需要具备从模糊的失败信号（如测试失败日志、构建错误）中精准定位计划缺陷的能力，这需要更强大的诊断和归因机制。

5. 与人类工作流的融合：完全自主的智能体目前风险很高。更现实的路径是“人机协同编程”。那么，智能体的计划应该如何透明地展示给人类开发者？如何允许人类在关键节点进行审批、修改或提供提示？计划的表达方式需要既能让机器高效执行，也能让人快速理解和干预。

5.2 对未来工具设计与研究的启示

基于上述挑战，未来的Agentic AI Coding Tools可能会在以下方向演进，而相关研究也应围绕这些方向展开：

1. 增强的环境感知与建模：工具需要为智能体构建更丰富的代码库“世界模型”。这不仅仅是静态代码分析（如生成AST、调用图），还要集成动态信息，如测试覆盖率、变更历史、文档链接、甚至团队讨论（如GitHub Issues和PR评论）。智能体在规划前，可以先“学习”这个模型。

2. 混合规划架构：纯依赖LLM的“零样本”规划可能不够可靠。未来的系统可能会采用“神经-符号”混合方法。LLM负责高层的、创造性的任务分解和意图理解，而一个经典的、基于规则的符号化规划器（或一个经过微调的小型规划模型）负责将子任务转化为可靠的动作序列。这样可以提高计划的确定性和正确性。

3. 计划验证与模拟执行：在真正修改代码库之前，智能体可以在一个“沙盒”或“模拟环境”中验证其计划。例如，通过静态分析预测代码变更的影响，或在一个临时的代码副本中快速运行核心逻辑的测试。这类似于人类开发者在脑海中“跑一遍”代码逻辑。

4. 可解释的计划界面：工具需要提供一个出色的UI来可视化智能体的计划。不是显示原始的JSON，而是像一个甘特图或流程图，清晰地展示任务分解、动作序列、当前状态、以及每个步骤的“理由”（Why）。当计划需要调整时，开发者可以直接在这个界面上进行拖拽、编辑或添加注释，实现自然的人机交互。

5. 基于学习的计划优化器：智能体可以从历史执行记录中学习。通过收集大量（任务，初始计划，执行轨迹，最终结果）的四元组数据，可以训练一个“计划评估器”或“计划优化器”模型。这个模型可以预测某个计划的成功率、效率，甚至能在规划阶段就提出优化建议，比如“你在这个项目里修改数据库查询时，有80%的情况需要同时更新models/目录下的某个关联文件”。

这项探索性研究，正是迈向这些更高级别能力的第一步。它通过系统性的观察和测量，为我们绘制了一幅当前技术能力边界的详细地图。对于开发者而言，理解这些，能让我们更清醒地使用现有工具，知道何时可以信任智能体的“自动驾驶”，何时必须紧握“方向盘”进行人工干预。对于研究者和工具开发者而言，这些洞察则是照亮前路、指引下一个突破方向的灯塔。