从 Chat 到 Agent：AI coding 智能体的 4 个关键零件（系列 01）

本文探讨了如何将AI编程工具从简单的聊天模式升级为高效的智能体（Agent）模式，提出了四个关键设计要素：命令系统（/命令）、路径展开（@路径）、工具调用闭环（MCP）和规约资产化。通过建立预处理、推理、工具执行和结果回填的完整流水线，智能体能够更准确地理解需求并生成可验证的代码方案。文章提供了实用操作清单，包括如何设计命令、优化路径引用、管理工具权限以及建立验收标准，并针对常见问题给出排错建议。

AI老炮儿

396人浏览 · 2025-12-29 23:39:16

AI老炮儿 · 2025-12-29 23:39:16 发布

声明：本文为学习笔记与工程化延伸，核心脉络来自阿里云开发者技术号发布的《AI coding 智能体设计》，在此基础上按“可落地教程”的方式重组，并补充了个人实践中的检查清单与排错思路；如有出入，以原文与官方文档为准。原文链接见文末参考。

如果你正在用各类 AI coding 工具（CLI/IDE/插件），你大概率见过两种体验：

像聊天：你提需求，它不断追问环境、文件、入口；你贴一点，它猜一截；最后输出一份“看起来像对的”方案。
像干活：你提需求，它先把相关文件找出来、跑一遍命令、给出可验证的步骤或补丁。

这两者的差异，通常不在“模型聪不聪明”，而在智能体设计是否补齐了关键零件：让模型能“看到代码、用上工具、控制上下文、按规约推进”。

本文目标很明确：用一篇文章讲清楚 AI coding 智能体从 Chat 升级到 Agent 的 4 个关键零件，并给你一套今天就能照着用的操作清单。

你会得到什么（阅读指南）

一个最小闭环心智模型：为什么有的工具“会做事”，有的只是“会说”
四个关键零件：/命令、@路径、工具调用闭环（MCP）、规约资产化
一套可直接复用的提示词模板：减少来回追问、提高一次性命中率
排错清单：为什么它没读到文件？为什么它不调用工具？为什么输出越来越飘？

01｜先理解“最小闭环”：智能体不是聊天，是流水线

把 AI coding 智能体当成一条流水线，会比把它当成“更会写代码的聊天机器人”更准确：

用户输入
  │
  ├─（A）预处理：识别 /命令；展开 @路径，把文件内容拼进上下文
  │
  ├─（B）模型推理：决定下一步 —— 直接回答？还是调用工具？
  │
  ├─（C）执行工具：读文件 / 搜索 / 运行命令 / 调用 MCP 工具...
  │
  ├─（D）回填结果：把工具输出再喂回模型
  │
  └─（E）产出：最终回答/补丁/任务清单；必要时继续循环

Chat 往往只做（B）（E）；
Agent 则把（A）（C）（D）补齐，并且对上下文、流程有更强的治理。

最小伪代码（帮助你“看见闭环”）

// 伪代码：把自然语言输入先“工程化”
function preprocess(input: string) {
  const isCommand = input.startsWith("/");
  const expanded = expandAtPaths(input); // 扫描 @path，读文件/目录并拼接到上下文
  return { isCommand, prompt: expanded };
}

// 伪代码：工具调用闭环（tool-calling loop）
async function agentLoop(userInput: string) {
  let ctx = preprocess(userInput);
  while (true) {
    const resp = await llm(ctx); // 可能返回 toolCall 或 finalText
    if (resp.toolCall) {
      const out = await runTool(resp.toolCall); // 执行：读文件/搜索/命令/MCP...
      ctx = appendToolOutput(ctx, out);         // 回填：把 out 加入上下文
      continue;
    }
    return resp.finalText;
  }
}

你只要记住一句话：智能体不是“更强的聊天”，而是“更完整的闭环”。

02｜关键零件一：/命令（把高频动作从自然语言里抽出来）

在《AI coding 智能体设计》对 Gemini-CLI 的分析中，输入若以 / 开头，会被当成命令：执行特定操作，或替换为预置提示词再和模型交互（例如清空、初始化、压缩上下文等）。

为什么这很重要？因为它让“可确定动作”变得可复用、可发现、可审计，避免你每次都在自然语言里重新组织指令。

你可以怎么用（通用方法，不依赖某个工具）

把“状态类操作”改成命令：清空上下文、切换配置、压缩历史、列出项目文件
把“重复提示词”封装成命令：例如“生成变更清单”“安全审查”“生成测试用例”

教程化建议：命令设计三条原则

命令只做一件事：不要把清空上下文和重写代码绑在一起
命令输出要可被下一步消费：最好是结构化输出（列表/路径/JSON）
命令要遵守最小权限：能不写文件就不写，能不执行命令就不执行

03｜关键零件二：@路径展开（让模型“读代码”，而不是“猜代码”）

Gemini-CLI 的另一个关键设计是：当输入里出现 @路径，在发送给模型之前会提前读取相关文件（如果是目录，可能读取目录下多个文件）作为上下文。

它解决的是一个很现实的问题：你不给文件，模型只能猜；你贴太多，模型又读不完。

一套可直接复制的“工单式提示词”

把指令写成“范围 + 关注点 + 输出格式”，会比单纯一句“帮我改改”好用得多：

请阅读 @src/auth/ 目录下与 token 校验相关的代码。
关注点：校验逻辑、过期时间、错误码映射。
输出：用 1) 现状 2) 问题 3) 修复建议 4) 风险 5) 验证步骤 的结构回答。

@路径常见踩坑（以及怎么避免）

坑 1：一把梭读整个仓库
- 解决：先给最小范围（1～3 个文件或一个小目录），必要时再扩展
坑 2：只给范围，不给关注点
- 解决：明确你要它找什么（函数/错误码/配置项/边界条件）
坑 3：路径写错/相对路径不一致
- 解决：用工具的文件浏览/搜索先确认路径；优先用项目根目录相对路径

04｜关键零件三：工具调用闭环（MCP 让“会说”变成“会做”）

AI coding 智能体真正拉开差距的地方，是它能不能稳定跑完这个闭环：

把工具列表作为上下文提供给模型
模型决定是否调用哪个工具
工具侧执行（读文件/搜索/运行命令/访问外部服务）
把输出回填给模型
模型基于真实输出继续推理，直到完成任务

MCP（Model Context Protocol）提供了一个标准化的“外接能力”接口：MCP server 可以提供工具，也可以提供提示词命令，让 CLI/IDE 以插件化方式扩展。

教程化建议：把工具闭环当成“可观测系统”

可追踪：记录每次工具调用的输入/输出/耗时/错误码
可控权：默认最小权限；项目级配置允许/禁止哪些工具
可恢复：失败要有重试/降级/人工确认点，避免模型硬编

05｜关键零件四：规约资产化（spec-driven，让交付可复现）

很多人用 AI coding 最大的痛点不是“写不出来”，而是：

同一句需求，每次跑出来都不一样
改动越来越大，影响面不清楚
需求对齐靠聊天记录，过几天谁也说不清当时的约束

《AI coding 智能体设计》提到 OpenSpec 的思路，我建议你至少把“规约与任务清单”沉淀到仓库：让 AI 的产出变成可复现、可审计、可迭代的资产。

最小可落地目录（建议从这一套开始）

changes/<id>/
  proposal.md   # 背景/范围/验收标准
  design.md     # 关键决策与取舍（可选）
  tasks.md      # 可勾选的执行清单（必须）

tasks.md 建议写“可验证”的验收项，而不是抽象口号：

新增单元测试覆盖：成功/失败/过期三条路径
不修改现有 public API（如需修改，必须提供迁移说明）
README 增补使用说明与错误码对照表

06｜把本文变成“今天就能用”的操作清单

如果你希望从“聊天式输出”切到“工程式交付”，可以按下面顺序训练你的输入：

先用 /命令把状态准备好
- 清空旧上下文（避免串台）
- 设定输出结构（例如必须给验证步骤）
再用 @路径把材料一次性备齐
- 最小范围优先（1～3 个文件）
- 明确关注点（函数、配置、边界）
让它进入工具闭环
- 明确允许做哪些工具动作（读/搜/跑命令）
- 要求引用工具输出作为证据（避免“凭空断言”）
最后用规约锁住验收标准
- 把“完成定义”写进 tasks.md
- 让它逐项勾选并说明验证方式

07｜排错清单：为什么它“没有变成 Agent”？

你在使用 AI coding 工具时，如果发现它没有进入“会做事”的模式，通常是下面几类原因：

没有读取到正确的上下文
- 现象：回答泛泛、像在猜；反复追问你贴代码
- 处理：缩小/校准 @路径；补上“关注点”；让它先复述它读到的文件名/关键函数
工具权限/工具注册不可用
- 现象：它说“我建议你运行某命令”，但不主动调用工具
- 处理：检查工具是否启用；明确告诉它“允许调用哪些工具”；要求输出中引用工具结果
上下文超载导致信息丢失
- 现象：前面说过的约束后面忘了；只针对后半段代码给建议
- 处理：减少一次性读入；用压缩/摘要命令；让它先生成任务清单再逐项执行
缺少可验证的验收标准
- 现象：它写了很多，但你不知道是否“真的完成”
- 处理：补 tasks.md；每项任务要求“如何验证/在哪里验证”