从零手写一个 AI 编程 Agent 之后，我终于理解了 Cursor 的核心原理

本文适合对 AI Agent 感兴趣的 Node.js 开发者。我们不谈虚的——用不到 200 行代码，从零实现一个能自动创建项目、写代码、装依赖、启动服务的编程 Agent，并在这个过程中真正理解"为什么一个 for 循环就能驱动复杂任务"。

文章目录

一、一个被忽视的问题

过去一年，Cursor、Copilot、Devin 这些 AI 编程工具已经渗透了我们的日常工作。敲一行需求，AI 自动创建项目、写代码、装依赖、跑起来——这已经不是什么新鲜事了。

但有一个问题，大多数人用了很久也没有认真想过：这个"自动完成任务的循环"，内部到底是怎么工作的？

我第一次认真思考这个问题，是在用 Cursor 搭建一个全栈项目的时候。AI 先创建了前端项目，又创建了后端项目，然后自动装了依赖，甚至帮我修正了一个配置错误——整个流程大概 20 个步骤，它自己走完了。我当时想：它怎么知道"下一步"该做什么？它的"决策"机制是什么？

后来我读了不少 Agent 相关的论文和源码，发现这件事的核心，其实是一个诞生于 2022 年的老模式：ReAct（Reasoning + Acting）。而且，它的实现骨架简单到让人意外——一个 while 循环，不到 50 行代码。

这篇文章，我想跟你分享一个"从零手写 mini-Cursor"的过程。它只有四个工具、一个 ReAct 循环，但它完整地复现了 AI 编程 Agent 的核心骨架。更重要的是——理解了这个骨架之后，你对市面上所有 AI 编程工具的理解，会从"魔法"变成"工程"。

二、先立一个公式：Agent = LLM + 工具 + 循环

任何 AI Agent，不管多复杂，都可以用这个公式概括：

Agent = LLM（大脑） + 工具（手） + 循环调用（心跳）
  • LLM 负责"思考"——分析当前状态，决定下一步做什么。每次调用就像一次"快照式的判断"，它不记得上一刻发生了什么——除非你把历史告诉它。
  • 工具 负责"行动"——读文件、写代码、执行命令、查数据库。LLM 本身只是一个语言模型，它不能操作文件系统，不能联网，不能执行命令。工具是它伸向外部世界的触手。
  • 循环 负责"持续"——LLM 思考一次就停了，但任务通常需要多步才能完成。循环让这个过程持续运转：思考 → 行动 → 观察结果 → 再思考。

这听起来像是废话——“有大脑、有手、有心跳，当然能干活”。但我想说的是：这个公式里，最不直观、也最关键的一环是"循环"。 因为市面上大部分关于 Agent 的讨论，焦点都放在 LLM 的能力和工具的丰富度上，很少有人去思考：“LLM 为什么能在一个循环里持续做出正确的决策？”

我认为答案是：LLM 并没有"规划"整个任务，它只是在每一步基于"当前上下文 + 上一步的工具结果"做一次推理。 全局的"智能感"，是从局部的、一次次的微观决策中涌现出来的。

所以，要理解 Agent，重点不是"用了什么模型"或"有多少工具"，而是这个循环怎么设计，以及每一步的上下文怎么传递。下面我们通过代码来验证这件事。

三、工具设计的三个关键权衡

在写 ReAct 循环之前，我们需要给 Agent 装上"手"。我们定义了四个工具：read_file、write_file、list_directory、execute_command，分别对应读取、写入、浏览、执行。每个工具用 LangChain 的 tool() 封装，包含三个要素：功能函数、name + description（告诉 LLM 它能干什么）、Zod schema（告诉 LLM 参数类型）。

具体代码我不在这里全部展开（完整版本见文末），我想重点讨论的是工具设计中的三个关键权衡——这些权衡反映了 Agent 开发中普遍存在的取舍。

权衡 1：健壮性 vs 精确性——写文件时要不要自动创建目录？

const writeFileTool = tool(
  async ({ filePath, content }) => {
    const dir = path.dirname(filePath);
    await fs.mkdir(dir, { recursive: true });  // 自动建
    await fs.writeFile(filePath, content, 'utf-8');
    return `成功写入 ${filePath}`;
  },
  { /* name, description, schema */ }
);

fs.mkdir(dir, { recursive: true }) 这行代码我犹豫过要不要加。理由是：加了，Agent 可能在不该建目录的地方建了目录；不加，Agent 在写嵌套路径时会反复失败。

最终我选择了"加"。因为这个 Agent 的场景是"自动化编程"，LLM 大概率会写出 src/components/Header.tsx 这样的路径——如果 src/components 不存在就报错，Agent 会在创建目录和写文件之间反复试错，浪费多轮调用。

这个取舍背后的原则是：工具应该容忍 LLM 的"粗放"——LLM 擅长生成意图，不擅长精准操作。 你在设计 Agent 工具时，需要主动判断哪些操作可以"容错"，哪些必须"严格"。这和传统 API 设计的思路完全不同——传统 API 强调"契约"，Agent 工具强调"鲁棒性"。

权衡 2：实时反馈 vs 结果收集——执行命令时用 spawn 还是 exec？

const child = spawn(cmd, args, {
  cwd,
  stdio: 'inherit',  // 子进程的输出直接透传到终端
  shell: true,
});

spawn + stdio: 'inherit' 是一个刻意为之的选择。如果用 exec，子进程的输出会被缓冲，等命令执行完才返回。对于 pnpm install 这种带进度条的命令，用户会在终端前干等好几分钟，啥也看不到——这体验太差了。

但 stdio: 'inherit' 也有代价：子进程的输出不经过 Node.js，所以你"拿不到"它的 stdout，无法在事后分析输出内容来辅助决策。 如果 Agent 需要根据命令输出来判断下一步该做什么，spawn 就不是好选择。

取舍的原则是：如果命令的输出是给用户看的（安装进度、构建日志），优先保证体验，用 spawn；如果命令的输出需要被 Agent 解析和推理，用 exec 收集完整结果。 在这个 mini-Cursor 中，四个工具里有三个都需要 Agent 拿到返回结果做下一步决策，唯独 execute_command 是个例外——因为它的主要场景是安装和启动，用户更关心"看到它跑起来了"而非"Agent 分析输出"。

权衡 3：描述详细度 vs 上下文消耗——怎么给工具写 description？

每个工具都需要一个 description 字段，告诉 LLM 它是干什么的。我一开始写得很简略：

description: '读取文件',

后来发现这样写，LLM 会在"看代码"和"查目录"之间选错工具——它分不清什么时候该用 read_file，什么时候该用 list_directory。于是我把 description 改成了更详细的版本：

description: '用此工具来读取文件内容，当用户要求读取文件、查看代码、分析文件内容时，调用此工具。输入文件路径（可以是相对路径或绝对路径）',

但问题又来了——description 太长会消耗上下文窗口。四个工具，每个 100 字的 description，加上 System Prompt，已经占了几百个 token。对于简单任务，这完全是浪费。

原则是：description 的长度应该和"调用歧义度"成正比。 两个容易混淆的工具（如 read_file 和 list_directory），description 要写得足够有区分度；不太可能混淆的工具（如 execute_command），description 可以简略。

这三个权衡做下来，你会发现一个更底层的规律：工具设计不是在写 API，而是在和 LLM “对话”。 你要预判 LLM 可能在什么场景下犹豫，主动给它铺好路。这种"产品思维"比纯工程思维重要得多——这也是我觉得 Agent 开发中最有意思的部分。

四、ReAct 循环的优雅——一个 for 循环为什么能驱动复杂任务

工具定义好了，现在到最有意思的部分：把这个 for 循环跑起来，看 LLM 怎么在每一步做决策。

4.1 模型绑定——为什么 bindTools 是桥梁而非黑魔法

const model = new ChatOpenAI({
  modelName: 'deepseek-v4-pro',
  temperature: 0,  // 代码生成不需要创意，要确定性
});

const tools = [readFileTool, writeFileTool, listDirectoryTool, executeCommandTool];
const modelWithTools = model.bindTools(tools);

bindTools 是 LangChain 提供的一个方法，它做的事情很朴素：把每个工具的 name、description 和 zod schema 转成 OpenAI 兼容的 function-calling 格式，塞到 API 请求里。模型收到后，在连续推理的过程中，可以在任意时刻选择"我要调工具了"——它会输出一个 tool_calls 数组，里面包含工具名和参数。

这里有一个细节值得注意：temperature: 0。Agent 任务不是写诗——每一步都应该稳定、可预测。如果 temperature 设高了，模型可能"突发奇想"调用不存在的工具，或者在参数里填错路径。对于代码生成和工具调用，确定性比创意重要。

4.2 循环体——整个 Agent 的核心，不到 30 行

async function runAgent(query, maxIterations = 30) {
  const messages = [
    new SystemMessage(`你是一个项目管理助手...
      当前工作目录: ${process.cwd()}
      可用工具: read_file, write_file, list_directory, execute_command
      重要规则: workingDirectory 和 cd 不要同时使用...`),
    new HumanMessage(query),
  ];

  for (let i = 0; i < maxIterations; i++) {
    const response = await modelWithTools.invoke(messages);
    messages.push(response);

    // 没有 tool_calls → 任务完成
    if (!response.tool_calls || response.tool_calls.length === 0) {
      return response.content;
    }

    // 有 tool_calls → 执行工具，结果塞回对话历史
    for (const toolCall of response.tool_calls) {
      const tool = tools.find(t => t.name === toolCall.name);
      if (tool) {
        const result = await tool.invoke(toolCall.args);
        messages.push(new ToolMessage({
          content: result,
          tool_call_id: toolCall.id,
        }));
      }
    }
  }
}

这个循环的心跳可以画成这样：

┌──────────┐    response.tool_calls 存在   ┌──────────┐
│ LLM 推理 │ ────────────────────────────► │ 执行工具 │
│ (invoke) │                               │ (invoke) │
└──────────┘                               └──────────┘
      ▲                                           │
      │        ToolMessage 塞回 messages           │
      └───────────────────────────────────────────┘
                          │
                    response.tool_calls 不存在
                          │
                          ▼
                    ┌──────────┐
                    │ 任务完成 │
                    └──────────┘

我真正理解 ReAct 的本质，就是在仔细看了这个循环中的"消息传递"机制之后。有两点是最关键的：

第一，ToolMessage 的"回传"是整个系统的记忆机制。 LLM 自己是无状态的——每一次 invoke，它唯一的信息来源就是 messages 数组。所以，你必须把工具执行结果原封不动地塞回去。如果你忘了这一步，LLM 在下一轮调用中会"失忆"——它不知道上一轮做了什么，更不知道结果是成功还是失败。然后它会怎么做？它大概率会重复调用同一个工具，陷入"loop death"。

第二，LLM 没有"全局规划"，只有"局部推理"。 这是很多人对 Agent 最大的误解。我们回顾一下 Agent 创建 React 项目的真实执行轨迹：

第 1 次推理: "我的任务是创建项目，应该先执行 vite 命令"
  → 调 tool: execute_command("pnpm create vite ...")
  → 结果: "成功执行"

第 2 次推理: "项目建好了，但我还不知道里面有什么文件，先看看"
  → 调 tool: list_directory("react-todo-app/src")
  → 结果: "App.tsx, main.tsx, App.css, ..."

第 3 次推理: "有 App.tsx，我应该重写它实现 TodoList 逻辑"
  → 调 tool: write_file("react-todo-app/src/App.tsx", "完整代码...")
  → 结果: "成功写入"

第 4 次推理: "逻辑写完了，还需要样式文件来加渐变背景和动画"
  → 调 tool: write_file("react-todo-app/src/App.css", "样式代码...")
  → 结果: "成功写入"

第 5 次推理: "代码和样式都写好了，该装依赖了"
  → 调 tool: execute_command("pnpm install", { workingDirectory: "react-todo-app" })
  → 结果: "成功执行"

第 6 次推理: "依赖装好了，启动"
  → 调 tool: execute_command("pnpm run dev", { workingDirectory: "react-todo-app" })
  → 结果: "成功执行"

第 7 次推理: "所有步骤都完成了，项目已经在运行"
  → 无 tool_calls，直接返回最终文本

注意看：LLM 并没有在第一步就"想好"所有步骤。它每一步只做一件事，做完后根据新的上下文判断下一步。全局的"智能感"是从一次次局部推理中自然涌现的——就像蚂蚁没有"巢穴设计图"，但成千上万只蚂蚁协作出来的蚁巢结构极其精妙。

这就是 ReAct 模式最优雅的地方：复杂度由环境（messages 历史 + 工具结果）承担，而非由模型承担。 模型不需要"规划"，它只需要在每一步做最好的判断。而环境提供了它做判断所需的全部信息。

4.3 System Prompt——Agent 的"护栏"

这 30 行循环代码是心脏，但 System Prompt 是"基因"。我在 System Prompt 里做了几件关键的事：

  1. 告诉它当前工作目录：${process.cwd()}——不写这句，它可能把文件写到意想不到的地方
  2. 复述一遍工具列表：虽然 bindTools 已经传了工具定义，但 System Prompt 里再列一遍能显著降低模型调用错误工具的几率。这是实践中的经验——双重信息（tool definition + prompt description）比单一信息更可靠
  3. 重点标注易错规则：workingDirectory 和 cd 的冲突。

第三点值得展开说说。execute_command 支持一个 workingDirectory 参数，用来指定命令在哪个目录执行。但 LLM 有一个"思维惯性"——当它想进入某个目录执行命令时，会下意识地在 command 里写 cd react-todo-app && pnpm install。问题是：如果同时传了 workingDirectory: "react-todo-app"，实际路径就变成了 react-todo-app/react-todo-app——直接报错。

我在 System Prompt 里特意写上了正确示例和错误示例：

重要规则 - execute_command：
  - workingDirectory 参数会自动切换到指定目录
  - 当使用 workingDirectory 时，绝对不要在 command 中使用 cd
  - 错误示例: { command: "cd react-todo-app && pnpm install",
                workingDirectory: "react-todo-app" }
    这是错误的！因为 workingDirectory 已经在 react-todo-app 了
  - 正确示例: { command: "pnpm install", workingDirectory: "react-todo-app" }

这看起来像是在"啰嗦"，但在 Agent 开发中，对待已知的、高概率的错误模式，最好的方式就是直接写在 prompt 里。不要指望 LLM 自己"悟"出来——它没有常识，你越把它当"聪明的但不太靠谱的同事"去对待，效果越好。

五、实战验证：让它建一个完整的 React 项目

说了这么多理论，Agent 到底能不能干活？我给它的任务是：

创建一个功能丰富的 React TodoList 应用：
1. 使用 pnpm create vite react-todo-app --template react-ts 创建项目
2. 修改 App.tsx，实现完整功能：增删改查、分类筛选、统计、localStorage 持久化
3. 添加美观样式：蓝紫渐变背景、卡片阴影和圆角、悬停效果、CSS transitions 动画
4. pnpm install 安装依赖
5. pnpm run dev 启动开发服务器

运行 node mini-cursor.mjs，终端开始输出：

正在执行第 1 次 AI 思考
[工具调用] execute_command(pnpm create vite react-todo-app --template react-ts)
工作目录：/Users/xxx/hello-langchain/src
...Vite 脚手架输出...
[工具调用] execute_command(pnpm create vite ...) 成功执行

正在执行第 2 次 AI 思考
[工具调用] list_directory(react-todo-app/src)
成功列出 5 个文件和文件夹

正在执行第 3 次 AI 思考
[工具调用] write_file(react-todo-app/src/App.tsx)
成功写入 4521 字节
...

大概 7 轮之后，Agent 完成了所有步骤。打开浏览器访问 http://localhost:5173，一个完整的 TodoList 就摆在眼前——渐变背景、卡片圆角、hover 效果、添加/删除动画，还有 localStorage 持久化。刷新页面数据不丢失。

这个 demo 不是为了炫技——它的目的只有一个：验证"LLM + 工具 + 循环"这条公式在实践中是成立的。 一个不到 200 行的程序，配合一个语言模型，确实可以自动完成一个端到端的开发任务。这证明了 Agent 的核心不是"模型有多强"，而是"循环 + 工具传递"的设计是否合理。

六、从 200 行到 Cursor，中间差了什么？

理解了 mini-Cursor 之后，再回去看真正的 Cursor，它的差异不在于"用了什么魔法"，而在于以下这些工程化的增量：

维度 mini-Cursor 真正的 Cursor
工具数量 4 个 可能上百个（文件操作、Git、终端、LSP、浏览器…）
上下文管理 简单的 messages 数组 精巧的上下文压缩、文件相关性排序、RAG 检索
代码编辑 整文件覆写 diff 级别的精确编辑（applyEdit）
人机交互 纯命令行 GUI 中 diff 预览、一键 accept/reject、inline chat
错误恢复 简单的 maxIterations 兜底 自动重试、回退、LSP 诊断反馈
记忆 无 项目级和用户级记忆，跨会话持久化

但骨骼是一样的——ReAct 循环。 所有的增量，都是在"循环"之上做的优化：让工具更丰富、让上下文更精准、让交互更友好。这不是降维打击，而是同一个架构在不同成熟度阶段的表现。

这个认知帮我澄清了一个常见的误解：“Cursor 之所以强，是因为用了最强的模型。” 不是的。Cursor 强在它的工具链设计和上下文管理——这两件事跟模型能力一样重要，甚至更重要。模型只是"思考"的质量，而工具设计和上下文管理决定了"思考的方向"对不对。

七、总结

三个核心观点

  1. AI Agent 的本质就是一个带工具调用的对话循环。 LLM 推理 → 调工具 → 观察结果 → 再推理。一个 30 行的 for 循环就是整个系统的心跳。理解了这一点，任何 Agent 框架（LangChain、AutoGPT、CrewAI）在你眼里都会变得透明。

  2. 工具设计不是在写 API，而是在和 LLM “对话”。 你需要预判 LLM 会在什么场景下犹豫，主动设计容错和引导。描述写多详细、参数怎么定义、是否自动建目录——这些"人机交互"层面的决策，比算法层面的决策更影响最终效果。

  3. Agent 的"智能感"是涌现的，不是规划的。 LLM 每一步只做一次局部的判断，但消息历史把所有判断串起来之后，表现出来的就是"全局的智能"。这意味着你的工作不是教 LLM 做规划，而是确保每一步的上下文（工具结果 + 历史消息）足够清晰、完整。

如果你也想自己试试

完整的代码已经在上文中贴出（all-tools.mjs 和 mini-cursor.mjs），配好 DeepSeek API Key 就能跑。如果你想继续深入，三个值得探索的方向：

  • 记忆系统：给 Agent 加上向量数据库，让它记住之前的对话和项目上下文，跨会话保持状态
  • 多 Agent 协作：一个 Agent 写前端，一个写后端，一个跑测试，通过消息传递协作
  • Human-in-the-loop：关键操作（删文件、推送代码）在执行前让用户确认，安全性和可控性大幅提升

你把 mini-Cursor 跑起来之后，可能会遇到一些"意外行为"——比如 LLM 写了一个语法错误的文件，或者死循环调用同一个工具。这些都不是 bug，而是 Agent 开发中正常的"沟通过程"。每一次调试，都是你在教 LLM 怎么更好地理解你的意图。

在这个过程中，你最大的收获可能不是一个能跑的项目，而是对"AI 编程工具到底在干什么"这件事，建立了一套属于自己的、工程化的理解。

# 人工智能
Logo
亚马逊云科技技术品牌专区

更多推荐

cover

深度分析新时代中企业应该如何利用AI更好提质增效

avatar 亚马逊云科技技术品牌专区
cover

2026年8月：Codex、Plus、Pro进入模型迁移期——为什么Agent系统不能把模型名写死？

avatar 亚马逊云科技技术品牌专区
cover

DeepSeek面试风波之外，李博杰开源了一本23.8k Star的AI Agent实战教程

avatar 亚马逊云科技技术品牌专区