从零构建一个 Mini Claude Code
从手写 40 行 ReAct 循环开始，逐步构建出有工具调用、上下文压缩和安全防护的 Code Agent
Step 01 · 00.ts
这是一个面向初学者的动手教程，目标不是复刻完整的 Claude Code，而是把一个 Code Agent 的关键部件拆开，逐个写出来。
我们会做两个项目：
- agent-loop：一个只有几十行核心代码的 ReAct Agent，用来理解 Agent 为什么能调用工具、持续执行任务。
- mini-claude-code：一个基于 Vercel AI SDK 的本地 Code Agent，支持文件读写、局部编辑、Shell 执行、网页抓取、上下文压缩和危险命令防护。
这两个项目的关系很重要：第一个负责解释原理，第二个负责把原理工程化。很多教程会直接从框架开始讲，结果读者只知道“调用某个 API 就能跑”，但不知道背后的循环、消息、工具结果回填到底发生了什么。我们这里反过来，先手写一个最小闭环，再引入 SDK。
最终你应该能回答这几个问题：
- Agent 和普通 ChatBot 的本质差异是什么？
- ReAct 循环到底在循环什么？
- 工具调用为什么不只是“给模型加几个函数”？
- 为什么 Code Agent 必须考虑上下文、权限和安全？
- Vercel AI SDK 帮我们省掉了哪些重复劳动？
第一章：Agent 和 ChatBot，到底差在哪？
开始写代码之前，先把概念讲清楚。因为如果只是照着代码抄一遍，很容易把 Agent 理解成“会调用 API 的聊天机器人”。这个理解不算错，但太浅。
普通 ChatBot 的基本交互是：
也就是说，控制流在人这边。模型只负责给出一段文本建议，至于要不要执行、怎么执行、执行完之后怎么处理错误，都由用户完成。
Agent 的交互方式不同：
这就是 Agent 的关键：控制流从人转移到了模型和运行时系统组成的闭环里。用户不再需要每一步都手动推进，而是给出目标，让 Agent 自己拆解、执行、观察结果并调整策略。
三个最小要素
一个 LLM-based Agent 至少需要三个要素：
如果只有上下文和系统提示词，它还是一个更聪明的 ChatBot；如果再加上工具调用，并且能把工具结果重新纳入下一轮决策，它才开始具备 Agent 的形态。
为什么工具调用会改变一切？
大模型本身不会真的读文件、改代码、查网页、运行测试。它只能生成文本。所谓“工具调用”，本质上是运行时系统和模型之间的一种约定：
- 模型按约定输出“我要调用某个工具，参数是什么”。
- 你的程序解析这段输出。
- 你的程序在真实环境里执行对应函数。
- 执行结果作为新的消息追加回上下文。
- 模型看到结果后决定下一步。
这个机制让模型从“回答问题”变成“推动任务”。比如你让 Code Agent 修一个 Bug，它不应该直接猜答案，而应该：
- 先读取报错信息；
- 搜索相关文件；
- 阅读上下文；
- 修改最小必要代码；
- 运行测试；
- 如果测试失败，再根据错误继续修。
这就是 Agent 和 ChatBot 的核心差别：ChatBot 给建议，Agent 闭环执行。
第二章：ReAct：让模型边想边做
实现 Agent 有很多范式，入门最适合先理解 ReAct。
ReAct 是 Reasoning + Acting 的缩写。它把一次复杂任务拆成多个循环步骤：
为了直观理解，假设用户问：“上海现在天气怎么样？”
一个 ReAct Agent 的执行过程可能是：
注意这里有两个重点。
第一，模型不是一次性回答，而是在多轮中逐步推进。每一步都依赖上一轮工具返回的 Observation。
第二，工具结果不是给用户看的终点，而是给模型看的输入。Agent 的能力来自这个“执行结果回填上下文”的闭环。
一个最小公式
我们可以把本教程要实现的 Agent 写成一个简单公式：
展开一点：
- LLM：负责理解任务、规划下一步、生成工具调用或最终回答。
- Context：保存系统提示词、用户输入、模型输出、工具结果。
- Tools：真实执行动作，例如读文件、写文件、运行命令。
- UI：用户和 Agent 交互的入口，可以是 CLI、Web、IDE 插件。
- ReAct Loop：把以上部件串起来的循环。
接下来我们先不使用任何 Agent 框架，自己写这个循环。
第三章：手写一个 Agent Loop
这个最小项目叫 agent-loop。它只解决一件事：让你看见 Agent 的核心循环到底长什么样。
我们会使用 Bun + TypeScript。除了调用模型 API，不引入复杂框架。这样每一行代码都和 Agent 的核心机制直接相关。
准备项目
创建项目：
项目结构如下：
这个项目会实现一个天气查询 Agent。它有两个工具：
getTime：返回当前时间。getWeather：根据城市和时间返回模拟天气。
为什么用天气，而不是直接写 Code Agent？因为天气例子足够小，能专注讲清楚工具调用闭环。读文件、改文件、运行命令本质上也是同一套机制，只是工具更复杂、风险更高。
先定义核心数据结构
Agent 的核心状态是消息历史。每条消息至少包含两个字段：谁说的，以及说了什么。
这里有两个类型：
ChatMessage：发送给大模型的消息格式。ParsedAssistant：从模型回复里解析出的结构化意图。
ParsedAssistant 很关键。模型原始输出是字符串，但我们的运行时需要知道它到底是在请求工具，还是已经给出最终答案。所以我们约定：解析结果要么包含 action，要么包含 final。
这也是 Agent 运行时最常见的工作之一：把模型生成的文本转成程序可以执行的结构。
调用大模型
接下来实现 callLLMs。它只做一件事：把消息数组发给模型 API，再返回 assistant 的文本回复。
Step 02 · 01.ts
这里用的是 DeepSeek 的 OpenAI 兼容接口，所以请求体和 OpenAI Chat Completions 类似。
几个细节值得注意：
messages是完整历史，不只是最新问题。模型是否“记得”之前发生了什么，取决于你有没有把历史再次发给它。temperature设置为0.35，比自由写作场景更低。工具调用需要稳定格式，温度太高会增加输出不符合约定的概率。- API 错误必须抛出来。Agent 调试时，沉默失败会非常难查。
到这里，我们只完成了“能和模型说话”。它还不是 Agent，因为还没有解析动作，也没有执行工具。
解析模型回复
为了让模型输出可解析，我们约定两种 XML 标签：
然后用正则解析：
Step 03 · 02.ts
这段代码很朴素，但它揭示了一个事实：所谓 Agent 框架，很大一部分工作就是在处理“模型输出的结构化协议”。
在生产项目里，你不一定会用 XML。也可以用 JSON、OpenAI Function Calling、Vercel AI SDK 的 tool calling、Anthropic tool use。形式不同，本质相同：让模型用机器可读的方式表达“下一步要做什么”。
搭出循环骨架
现在可以写 ReAct 循环的骨架了。
Step 04 · 03.ts
这个版本还没有真正执行工具，但循环结构已经出现了：
- 把当前
history发给模型。 - 记录模型回复。
- 解析模型回复。
- 如果是
<final>，返回最终答案。 - 如果不是最终答案，进入下一轮或退出。
for (let step = 0; step < 10; step++) 是一个非常重要的保护。Agent 必须有最大步数限制，否则模型一旦陷入重复调用工具，就会无限消耗 token 和 API 费用。
定义工具
现在补上工具。工具放在 tools.ts 里：
Step 05 · 04b.ts
这里把工具设计成一个简单的对象：
这不是最类型安全的设计，但足够展示原理。模型输出工具名和输入字符串，运行时根据工具名找到函数并执行，再拿到字符串结果。
天气工具使用模拟数据，而不是接入真实天气 API。这样做有两个好处：
- 教程不依赖第三方天气服务，读者更容易复现。
- 同样的城市和时间会得到稳定结果，方便调试 Agent 循环。
接入工具执行
最后把工具调用接入主循环：
Step 06 · 04.ts
这里沿用前面已经实现的 callLLMs 和 parseAssistant，只展示新增的工具执行分支。完整闭环出现了：
- 模型输出
<action tool="...">...</action>。 parseAssistant解析出工具名和参数。- 运行时从
TOOLKIT查找工具函数。 - 执行工具，得到
observation。 - 把
<observation>...</observation>作为新消息追加到history。 - 下一轮模型看到 observation，继续判断。
这一行尤其关键：
工具结果必须回到上下文，否则模型不知道刚才的动作发生了什么。你可以把它理解成 Agent 的“感官输入”：工具负责接触外部世界，Observation 负责把外部世界的反馈交还给模型。
写系统提示词
代码只能执行协议，协议本身要通过系统提示词告诉模型。
创建 prompt.md：
系统提示词不是“让模型说得更像某个人”的装饰文本，而是 Agent 协议的一部分。它至少要说明四件事：
- 角色：这个 Agent 是干什么的。
- 工具：有哪些工具，每个工具怎么用。
- 输出格式：如何表达 action 和 final。
- 规则：什么时候调用工具，什么时候结束。
运行最小 Agent
设置 API Key 后运行：
你应该会看到类似流程：
这就是一个最小 Agent。它没有复杂框架，本质只是：
手写版的问题
手写版适合理解原理，但不适合直接扩展成生产级 Code Agent。主要有三个问题。
第一，Provider 适配成本高。 如果从 DeepSeek 换到 OpenAI、Anthropic、Gemini，你要改 URL、Header、请求体、响应解析，甚至工具调用协议。
第二，工具调用状态机全靠自己维护。 什么时候继续循环、什么时候停止、工具结果怎么塞回历史、模型输出不合法怎么办，这些都要手写。
第三，工具参数没有类型安全。 所有工具输入都是字符串，解析 JSON、校验字段、处理错误都靠手工写。工具越多，问题越明显。
所以接下来我们引入 Vercel AI SDK。它不会改变 Agent 的本质，但会把这些重复的工程细节标准化。
第四章：为什么使用 Vercel AI SDK？
Vercel AI SDK 在这里主要解决三类问题。
统一模型 Provider
手写 fetch 时，每个模型服务都有自己的细节。SDK 把这些差异封装成统一的 model 对象。
手写版：
SDK 版：
换模型时，业务代码尽量不动，只替换 provider 配置。
内置工具调用循环
手写版需要自己处理：
- 模型是否调用工具；
- 调用哪个工具；
- 工具参数怎么解析；
- 工具结果怎么回填；
- 何时再次请求模型；
- 最多循环多少步。
SDK 的 generateText + maxSteps 会处理这个状态机。你仍然要设计工具和提示词，但不需要重复写循环胶水代码。
Zod 参数校验
手写版工具输入是字符串。SDK 版可以为每个工具定义 Zod schema：
模型生成的参数会被 SDK 解析和校验，execute 函数拿到的是有类型的对象。对 Code Agent 来说，这一点很重要，因为工具参数错误会直接影响文件和命令执行。
第五章：构建 Mini Claude Code
现在开始构建第二个项目：mini-claude-code。
它不是完整 Claude Code 的克隆，而是一个教学版 Code Agent。我们保留最关键的能力：
- 读取文件；
- 写入文件；
- 局部编辑文件；
- 执行 Shell 命令；
- 抓取网页；
- 维护多轮对话历史；
- 在上下文过长时压缩历史；
- 对危险命令做拦截或确认。
项目结构如下：
这个结构背后的原则是：Agent Loop 不直接关心具体工具怎么实现，工具也不直接关心模型怎么调用。 这样后续增加工具、替换模型、调整上下文策略都不会互相污染。
Provider 配置
先配置模型：
Step 07 · 05.ts
这里使用 createOpenAI 创建一个 OpenAI 兼容 Provider。很多第三方模型服务都会提供 OpenAI-compatible API，但兼容不代表完全等价，所以 compatibility: "compatible" 很重要。
它的作用是让 SDK 避免发送某些 OpenAI 官方接口特有但第三方服务未必支持的字段。只要你接的是非 OpenAI 官方的兼容接口，就应该优先考虑这个配置。
Provider 层应该尽量薄，只做这些事：
- 读取 API Key；
- 设置 baseURL；
- 选择模型名；
- 导出统一的
model。
这样 Agent Loop 不需要知道底层到底是七牛、DeepSeek、OpenAI 还是 Anthropic。
工具注册：把能力交给模型
接下来注册工具：
Step 08 · 06.ts
每个工具都包含三部分：
description：给模型看的说明，影响模型什么时候选择这个工具。parameters：Zod schema，定义工具参数。execute：真实执行逻辑。
工具描述不是普通注释，它是模型决策的一部分。比如 edit_file 明确说它只替换唯一匹配的 old_string，模型就更容易先读文件、再做局部修改。一个好的 Code Agent，很多稳定性不是来自“模型更聪明”，而是来自工具描述和系统提示词把边界说清楚。
这里的工具组合也很克制：
read_file负责看上下文；write_file负责创建或全量覆盖；edit_file负责局部修改；bash负责搜索、测试、构建等通用命令；web_fetch负责查文档。
不要一开始就堆很多工具。工具越多，模型选择成本越高，误用概率也越高。教学版保留最小可用集合更合理。
Bash 工具：能力越大，越要加护栏
Code Agent 最危险的工具通常是 Shell。它很强，因为几乎所有本地开发任务都能通过 Shell 完成；它也危险，因为一个错误命令就可能删除文件、泄漏信息或破坏系统。
Step 09 · 07.ts
bash 工具做了几件事：
- 执行前调用危险命令检测。
- 对需要确认的命令暂停并询问用户。
- 对禁止执行的命令直接拒绝。
- 设置超时时间，避免命令挂住。
- 合并 stdout 和 stderr，返回给模型。
- 对长输出做截断。
这不是“锦上添花”，而是 Code Agent 的基本安全要求。只要 Agent 可以执行命令，就必须有最后一道保险。
危险检测逻辑在 utils/safety.ts：
Step 10 · 08.ts
这里把风险分成两类：
block：无论如何都不应该执行，例如格式化磁盘、删除根目录。confirm：有合法用途但风险高，例如rm -rf、sudo、git push --force。
这种设计比简单地全拦或全放更实用。Code Agent 的目标是帮用户做事，不能因为安全而完全失去执行能力；但高风险操作必须让用户明确知情。
同一个文件里还有敏感路径检测。路径安全同样重要，因为文件工具和命令工具都可能被诱导去访问工作目录外的敏感文件。
工具输出截断
Agent 的上下文不是无限的。工具输出是最容易把上下文撑爆的来源之一。
例如模型执行：
如果项目里有 node_modules，输出可能非常长。再比如读取一个几万行日志文件，整个上下文窗口可能瞬间被填满。
所以工具层必须做输出截断：
Step 11 · 09.ts
关键点不是单纯截断，而是告诉模型“这里被截断了”。
如果你只是把输出裁成前 8000 字符，模型会误以为这就是完整结果。更好的做法是追加一个结构化提示：
这样模型知道它看到的不是全量内容，后续可以改用更精确的命令、分页读取文件、增加过滤条件，而不是基于不完整信息做判断。
核心 Loop：让 SDK 接管状态机
现在看 Agent Loop：
Step 12 · 10.ts
和手写版相比，最大的变化是：这里没有手写 for 循环，也没有手动解析 <action>。
generateText 会根据工具调用协议自动执行多步：
- 调用模型。
- 如果模型请求工具，SDK 校验参数。
- 执行对应工具。
- 把工具结果放回模型上下文。
- 再次调用模型。
- 直到模型输出最终文本或达到
maxSteps。
maxSteps: 50 仍然很重要。SDK 能帮你循环，但不能替你决定什么叫“无限循环”。Agent 系统必须始终有边界。
onStepFinish 用来观察中间过程。对 Code Agent 来说，透明度非常重要。用户需要知道 Agent 正在读哪些文件、执行哪些命令、是否卡在某一步。
系统提示词：静态规则 + 动态状态
系统提示词不应该永远只是一个静态 Markdown 文件。真实 Agent 运行时经常需要注入动态信息，例如：
- 当前工作目录；
- 用户偏好；
- 项目级规则；
- 工具输出被截断的提示；
- 压缩后的执行历史；
- 上一次失败的原因。
这个项目用 assembleSystemPrompt 组装提示词：
Step 13 · 11.ts
它把系统提示词分成两段：
- 静态段：从
SYSTEM_PROMPT.md读取，包含 Agent 身份和长期行为规则。 - 动态段：由运行时传入
runtimeHints，包含压缩摘要等当前状态。
这种分段方式比把所有内容硬写在一个字符串里更可维护。后续如果要接入类似 AGENTS.md、用户偏好、项目规则、Skills 索引，也可以继续作为新段落拼进去。
一个 Code Agent 的基础提示词至少应该包含这些规则：
- 修改文件前先读文件；
- 优先做最小改动；
- 能局部替换就不要全量覆盖；
- 工具调用后简要说明发现；
- 不确定需求时询问用户；
- 不要编造不存在的文件或命令结果。
这些规则看起来朴素，但能显著降低 Agent 乱改文件的概率。
上下文压缩
长任务会不断积累上下文。每一轮用户输入、模型输出、工具调用、工具结果都会进入历史。哪怕单次工具输出都被截断，长时间运行后也会逼近模型上下文上限。
解决思路是压缩历史：
Step 14 · 12.ts
这个模块做两件事。
第一，用 shouldCompress 判断是否超过阈值。这里基于 SDK 返回的真实 promptTokens，当超过模型上下文窗口的 80% 时触发压缩。
第二，用 compressHistory 让模型把历史总结成结构化摘要。摘要重点不是“语言优美”，而是保留后续执行需要的信息：
- 已经完成了什么；
- 还剩什么没做；
- 当前修改了哪些文件；
- 有哪些坑和约束；
- 哪些操作不要重复。
压缩完成后，旧 history 可以清空，摘要作为 runtime hint 注入下一轮系统提示词。这样 Agent 不需要携带完整历史，也能继续任务。
这里有一个工程取舍：压缩会损失细节，但不压缩会直接超上下文。实际项目里通常还会结合滑动窗口、重要消息保留、文件级索引等策略。本教程先实现最容易理解的一版。
CLI 入口：让 Agent 可以连续工作
最后把所有模块串成一个 CLI：
Step 15 · 13.ts
入口逻辑做了几件事：
- 读取用户输入；
- 调用
agentLoop； - 打印最终回答；
- 保存本轮
responseMessages到 history； - 根据 token 使用量决定是否压缩；
- 支持
/reset、/exit、/help等基础命令。
history 和 runtimeHints 在多轮之间持久存在，这是它能像一个真正助手一样连续工作的基础。
整个运行链路可以概括为：
第六章：从玩具到 Code Agent，中间多了什么？
现在回头看两个版本的差异。
最重要的结论是：mini-claude-code 并没有改变 Agent 的基本原理。它只是把原理放进了更可靠的工程结构里。
手写版里的这些动作：
在 SDK 版里仍然存在，只是由 SDK 和工具系统接管了大部分细节。
Code Agent 的三个工程重点
如果你继续扩展这个项目，优先关注三个方向。
第一，工具边界。 工具越强，越要定义清楚输入、输出、权限和失败行为。不要让模型靠猜使用工具。
第二，上下文工程。 不要等上下文爆了才处理。文件读取、搜索结果、命令输出都应该有分页、过滤、截断和明确提示。
第三，安全策略。 只要涉及文件和命令执行，就必须考虑路径限制、危险命令、用户确认、超时、资源回收。
这些问题不是模型能力问题，而是软件工程问题。一个 Code Agent 是否可靠，很大程度取决于这些边界是否设计得足够清楚。
收尾
我们从一个天气查询 Agent 开始，手写了最小 ReAct 循环；然后把同样的思想迁移到 Code Agent，使用 Vercel AI SDK 实现了工具注册、自动工具调用、多轮上下文、安全防护和压缩机制。
这条学习路径的重点不是“记住某个框架 API”，而是理解 Agent 的运行骨架：
如果你刚开始学习 Agent 开发，建议先跑通 agent-loop，确认自己理解每一轮消息是如何流动的；再看 mini-claude-code，理解一个能处理真实代码任务的 Agent 需要补哪些工程能力。
核心概念不复杂，几十行代码就能跑起来。但从“能跑”到“能可靠地解决真实问题”，中间每一步都是工程设计。
type ChatMessage = { role: 'system' | 'user' | 'assistant' content: string} type ParsedAssistant = { action?: { tool: string; input: string } final?: string} 这是一个面向初学者的动手教程，目标不是复刻完整的 Claude Code，而是把一个 Code Agent 的关键部件拆开，逐个写出来。
我们会做两个项目：
- agent-loop：一个只有几十行核心代码的 ReAct Agent，用来理解 Agent 为什么能调用工具、持续执行任务。
- mini-claude-code：一个基于 Vercel AI SDK 的本地 Code Agent，支持文件读写、局部编辑、Shell 执行、网页抓取、上下文压缩和危险命令防护。
这两个项目的关系很重要：第一个负责解释原理，第二个负责把原理工程化。很多教程会直接从框架开始讲，结果读者只知道“调用某个 API 就能跑”，但不知道背后的循环、消息、工具结果回填到底发生了什么。我们这里反过来，先手写一个最小闭环，再引入 SDK。
最终你应该能回答这几个问题：
- Agent 和普通 ChatBot 的本质差异是什么？
- ReAct 循环到底在循环什么？
- 工具调用为什么不只是“给模型加几个函数”？
- 为什么 Code Agent 必须考虑上下文、权限和安全？
- Vercel AI SDK 帮我们省掉了哪些重复劳动？
第一章：Agent 和 ChatBot，到底差在哪？
开始写代码之前，先把概念讲清楚。因为如果只是照着代码抄一遍，很容易把 Agent 理解成“会调用 API 的聊天机器人”。这个理解不算错，但太浅。
普通 ChatBot 的基本交互是：
也就是说，控制流在人这边。模型只负责给出一段文本建议，至于要不要执行、怎么执行、执行完之后怎么处理错误，都由用户完成。
Agent 的交互方式不同：
这就是 Agent 的关键：控制流从人转移到了模型和运行时系统组成的闭环里。用户不再需要每一步都手动推进，而是给出目标，让 Agent 自己拆解、执行、观察结果并调整策略。
三个最小要素
一个 LLM-based Agent 至少需要三个要素：
如果只有上下文和系统提示词，它还是一个更聪明的 ChatBot；如果再加上工具调用，并且能把工具结果重新纳入下一轮决策，它才开始具备 Agent 的形态。
为什么工具调用会改变一切？
大模型本身不会真的读文件、改代码、查网页、运行测试。它只能生成文本。所谓“工具调用”，本质上是运行时系统和模型之间的一种约定：
- 模型按约定输出“我要调用某个工具，参数是什么”。
- 你的程序解析这段输出。
- 你的程序在真实环境里执行对应函数。
- 执行结果作为新的消息追加回上下文。
- 模型看到结果后决定下一步。
这个机制让模型从“回答问题”变成“推动任务”。比如你让 Code Agent 修一个 Bug，它不应该直接猜答案，而应该：
- 先读取报错信息；
- 搜索相关文件；
- 阅读上下文；
- 修改最小必要代码；
- 运行测试；
- 如果测试失败，再根据错误继续修。
这就是 Agent 和 ChatBot 的核心差别：ChatBot 给建议，Agent 闭环执行。
第二章：ReAct：让模型边想边做
实现 Agent 有很多范式，入门最适合先理解 ReAct。
ReAct 是 Reasoning + Acting 的缩写。它把一次复杂任务拆成多个循环步骤：
为了直观理解，假设用户问：“上海现在天气怎么样？”
一个 ReAct Agent 的执行过程可能是：
注意这里有两个重点。
第一，模型不是一次性回答，而是在多轮中逐步推进。每一步都依赖上一轮工具返回的 Observation。
第二，工具结果不是给用户看的终点，而是给模型看的输入。Agent 的能力来自这个“执行结果回填上下文”的闭环。
一个最小公式
我们可以把本教程要实现的 Agent 写成一个简单公式：
展开一点：
- LLM：负责理解任务、规划下一步、生成工具调用或最终回答。
- Context：保存系统提示词、用户输入、模型输出、工具结果。
- Tools：真实执行动作，例如读文件、写文件、运行命令。
- UI：用户和 Agent 交互的入口，可以是 CLI、Web、IDE 插件。
- ReAct Loop：把以上部件串起来的循环。
接下来我们先不使用任何 Agent 框架，自己写这个循环。
第三章：手写一个 Agent Loop
这个最小项目叫 agent-loop。它只解决一件事：让你看见 Agent 的核心循环到底长什么样。
我们会使用 Bun + TypeScript。除了调用模型 API，不引入复杂框架。这样每一行代码都和 Agent 的核心机制直接相关。
准备项目
创建项目：
项目结构如下：
这个项目会实现一个天气查询 Agent。它有两个工具：
getTime：返回当前时间。getWeather：根据城市和时间返回模拟天气。
为什么用天气，而不是直接写 Code Agent？因为天气例子足够小，能专注讲清楚工具调用闭环。读文件、改文件、运行命令本质上也是同一套机制，只是工具更复杂、风险更高。
先定义核心数据结构
Agent 的核心状态是消息历史。每条消息至少包含两个字段：谁说的，以及说了什么。
这里有两个类型：
ChatMessage：发送给大模型的消息格式。ParsedAssistant：从模型回复里解析出的结构化意图。
ParsedAssistant 很关键。模型原始输出是字符串，但我们的运行时需要知道它到底是在请求工具，还是已经给出最终答案。所以我们约定：解析结果要么包含 action，要么包含 final。
这也是 Agent 运行时最常见的工作之一：把模型生成的文本转成程序可以执行的结构。
调用大模型
接下来实现 callLLMs。它只做一件事：把消息数组发给模型 API，再返回 assistant 的文本回复。
这里用的是 DeepSeek 的 OpenAI 兼容接口，所以请求体和 OpenAI Chat Completions 类似。
几个细节值得注意：
messages是完整历史，不只是最新问题。模型是否“记得”之前发生了什么，取决于你有没有把历史再次发给它。temperature设置为0.35，比自由写作场景更低。工具调用需要稳定格式，温度太高会增加输出不符合约定的概率。- API 错误必须抛出来。Agent 调试时，沉默失败会非常难查。
到这里，我们只完成了“能和模型说话”。它还不是 Agent，因为还没有解析动作，也没有执行工具。
解析模型回复
为了让模型输出可解析，我们约定两种 XML 标签：
然后用正则解析：
这段代码很朴素，但它揭示了一个事实：所谓 Agent 框架，很大一部分工作就是在处理“模型输出的结构化协议”。
在生产项目里，你不一定会用 XML。也可以用 JSON、OpenAI Function Calling、Vercel AI SDK 的 tool calling、Anthropic tool use。形式不同，本质相同：让模型用机器可读的方式表达“下一步要做什么”。
搭出循环骨架
现在可以写 ReAct 循环的骨架了。
这个版本还没有真正执行工具，但循环结构已经出现了：
- 把当前
history发给模型。 - 记录模型回复。
- 解析模型回复。
- 如果是
<final>，返回最终答案。 - 如果不是最终答案，进入下一轮或退出。
for (let step = 0; step < 10; step++) 是一个非常重要的保护。Agent 必须有最大步数限制，否则模型一旦陷入重复调用工具，就会无限消耗 token 和 API 费用。
定义工具
现在补上工具。工具放在 tools.ts 里：
这里把工具设计成一个简单的对象：
这不是最类型安全的设计，但足够展示原理。模型输出工具名和输入字符串，运行时根据工具名找到函数并执行，再拿到字符串结果。
天气工具使用模拟数据，而不是接入真实天气 API。这样做有两个好处：
- 教程不依赖第三方天气服务，读者更容易复现。
- 同样的城市和时间会得到稳定结果，方便调试 Agent 循环。
接入工具执行
最后把工具调用接入主循环：
这里沿用前面已经实现的 callLLMs 和 parseAssistant，只展示新增的工具执行分支。完整闭环出现了：
- 模型输出
<action tool="...">...</action>。 parseAssistant解析出工具名和参数。- 运行时从
TOOLKIT查找工具函数。 - 执行工具，得到
observation。 - 把
<observation>...</observation>作为新消息追加到history。 - 下一轮模型看到 observation，继续判断。
这一行尤其关键：
工具结果必须回到上下文，否则模型不知道刚才的动作发生了什么。你可以把它理解成 Agent 的“感官输入”：工具负责接触外部世界，Observation 负责把外部世界的反馈交还给模型。
写系统提示词
代码只能执行协议，协议本身要通过系统提示词告诉模型。
创建 prompt.md：
系统提示词不是“让模型说得更像某个人”的装饰文本，而是 Agent 协议的一部分。它至少要说明四件事：
- 角色：这个 Agent 是干什么的。
- 工具：有哪些工具，每个工具怎么用。
- 输出格式：如何表达 action 和 final。
- 规则：什么时候调用工具，什么时候结束。
运行最小 Agent
设置 API Key 后运行：
你应该会看到类似流程：
这就是一个最小 Agent。它没有复杂框架，本质只是：
手写版的问题
手写版适合理解原理，但不适合直接扩展成生产级 Code Agent。主要有三个问题。
第一，Provider 适配成本高。 如果从 DeepSeek 换到 OpenAI、Anthropic、Gemini，你要改 URL、Header、请求体、响应解析，甚至工具调用协议。
第二，工具调用状态机全靠自己维护。 什么时候继续循环、什么时候停止、工具结果怎么塞回历史、模型输出不合法怎么办，这些都要手写。
第三，工具参数没有类型安全。 所有工具输入都是字符串，解析 JSON、校验字段、处理错误都靠手工写。工具越多，问题越明显。
所以接下来我们引入 Vercel AI SDK。它不会改变 Agent 的本质，但会把这些重复的工程细节标准化。
第四章：为什么使用 Vercel AI SDK？
Vercel AI SDK 在这里主要解决三类问题。
统一模型 Provider
手写 fetch 时，每个模型服务都有自己的细节。SDK 把这些差异封装成统一的 model 对象。
手写版：
SDK 版：
换模型时，业务代码尽量不动，只替换 provider 配置。
内置工具调用循环
手写版需要自己处理：
- 模型是否调用工具；
- 调用哪个工具；
- 工具参数怎么解析；
- 工具结果怎么回填；
- 何时再次请求模型；
- 最多循环多少步。
SDK 的 generateText + maxSteps 会处理这个状态机。你仍然要设计工具和提示词，但不需要重复写循环胶水代码。
Zod 参数校验
手写版工具输入是字符串。SDK 版可以为每个工具定义 Zod schema：
模型生成的参数会被 SDK 解析和校验，execute 函数拿到的是有类型的对象。对 Code Agent 来说，这一点很重要，因为工具参数错误会直接影响文件和命令执行。
第五章：构建 Mini Claude Code
现在开始构建第二个项目：mini-claude-code。
它不是完整 Claude Code 的克隆，而是一个教学版 Code Agent。我们保留最关键的能力：
- 读取文件；
- 写入文件；
- 局部编辑文件；
- 执行 Shell 命令；
- 抓取网页；
- 维护多轮对话历史；
- 在上下文过长时压缩历史；
- 对危险命令做拦截或确认。
项目结构如下：
这个结构背后的原则是：Agent Loop 不直接关心具体工具怎么实现，工具也不直接关心模型怎么调用。 这样后续增加工具、替换模型、调整上下文策略都不会互相污染。
Provider 配置
先配置模型：
这里使用 createOpenAI 创建一个 OpenAI 兼容 Provider。很多第三方模型服务都会提供 OpenAI-compatible API，但兼容不代表完全等价，所以 compatibility: "compatible" 很重要。
它的作用是让 SDK 避免发送某些 OpenAI 官方接口特有但第三方服务未必支持的字段。只要你接的是非 OpenAI 官方的兼容接口，就应该优先考虑这个配置。
Provider 层应该尽量薄，只做这些事：
- 读取 API Key；
- 设置 baseURL；
- 选择模型名；
- 导出统一的
model。
这样 Agent Loop 不需要知道底层到底是七牛、DeepSeek、OpenAI 还是 Anthropic。
工具注册：把能力交给模型
接下来注册工具：
每个工具都包含三部分：
description：给模型看的说明，影响模型什么时候选择这个工具。parameters：Zod schema，定义工具参数。execute：真实执行逻辑。
工具描述不是普通注释，它是模型决策的一部分。比如 edit_file 明确说它只替换唯一匹配的 old_string，模型就更容易先读文件、再做局部修改。一个好的 Code Agent，很多稳定性不是来自“模型更聪明”，而是来自工具描述和系统提示词把边界说清楚。
这里的工具组合也很克制：
read_file负责看上下文；write_file负责创建或全量覆盖；edit_file负责局部修改；bash负责搜索、测试、构建等通用命令；web_fetch负责查文档。
不要一开始就堆很多工具。工具越多，模型选择成本越高，误用概率也越高。教学版保留最小可用集合更合理。
Bash 工具：能力越大，越要加护栏
Code Agent 最危险的工具通常是 Shell。它很强，因为几乎所有本地开发任务都能通过 Shell 完成；它也危险，因为一个错误命令就可能删除文件、泄漏信息或破坏系统。
bash 工具做了几件事：
- 执行前调用危险命令检测。
- 对需要确认的命令暂停并询问用户。
- 对禁止执行的命令直接拒绝。
- 设置超时时间，避免命令挂住。
- 合并 stdout 和 stderr，返回给模型。
- 对长输出做截断。
这不是“锦上添花”，而是 Code Agent 的基本安全要求。只要 Agent 可以执行命令，就必须有最后一道保险。
危险检测逻辑在 utils/safety.ts：
这里把风险分成两类：
block：无论如何都不应该执行，例如格式化磁盘、删除根目录。confirm：有合法用途但风险高，例如rm -rf、sudo、git push --force。
这种设计比简单地全拦或全放更实用。Code Agent 的目标是帮用户做事，不能因为安全而完全失去执行能力；但高风险操作必须让用户明确知情。
同一个文件里还有敏感路径检测。路径安全同样重要，因为文件工具和命令工具都可能被诱导去访问工作目录外的敏感文件。
工具输出截断
Agent 的上下文不是无限的。工具输出是最容易把上下文撑爆的来源之一。
例如模型执行：
如果项目里有 node_modules，输出可能非常长。再比如读取一个几万行日志文件，整个上下文窗口可能瞬间被填满。
所以工具层必须做输出截断：
关键点不是单纯截断，而是告诉模型“这里被截断了”。
如果你只是把输出裁成前 8000 字符，模型会误以为这就是完整结果。更好的做法是追加一个结构化提示：
这样模型知道它看到的不是全量内容，后续可以改用更精确的命令、分页读取文件、增加过滤条件，而不是基于不完整信息做判断。
核心 Loop：让 SDK 接管状态机
现在看 Agent Loop：
和手写版相比，最大的变化是：这里没有手写 for 循环，也没有手动解析 <action>。
generateText 会根据工具调用协议自动执行多步：
- 调用模型。
- 如果模型请求工具，SDK 校验参数。
- 执行对应工具。
- 把工具结果放回模型上下文。
- 再次调用模型。
- 直到模型输出最终文本或达到
maxSteps。
maxSteps: 50 仍然很重要。SDK 能帮你循环，但不能替你决定什么叫“无限循环”。Agent 系统必须始终有边界。
onStepFinish 用来观察中间过程。对 Code Agent 来说，透明度非常重要。用户需要知道 Agent 正在读哪些文件、执行哪些命令、是否卡在某一步。
系统提示词：静态规则 + 动态状态
系统提示词不应该永远只是一个静态 Markdown 文件。真实 Agent 运行时经常需要注入动态信息，例如：
- 当前工作目录；
- 用户偏好；
- 项目级规则；
- 工具输出被截断的提示；
- 压缩后的执行历史；
- 上一次失败的原因。
这个项目用 assembleSystemPrompt 组装提示词：
它把系统提示词分成两段：
- 静态段：从
SYSTEM_PROMPT.md读取，包含 Agent 身份和长期行为规则。 - 动态段：由运行时传入
runtimeHints，包含压缩摘要等当前状态。
这种分段方式比把所有内容硬写在一个字符串里更可维护。后续如果要接入类似 AGENTS.md、用户偏好、项目规则、Skills 索引，也可以继续作为新段落拼进去。
一个 Code Agent 的基础提示词至少应该包含这些规则：
- 修改文件前先读文件；
- 优先做最小改动；
- 能局部替换就不要全量覆盖；
- 工具调用后简要说明发现；
- 不确定需求时询问用户；
- 不要编造不存在的文件或命令结果。
这些规则看起来朴素，但能显著降低 Agent 乱改文件的概率。
上下文压缩
长任务会不断积累上下文。每一轮用户输入、模型输出、工具调用、工具结果都会进入历史。哪怕单次工具输出都被截断，长时间运行后也会逼近模型上下文上限。
解决思路是压缩历史：
这个模块做两件事。
第一，用 shouldCompress 判断是否超过阈值。这里基于 SDK 返回的真实 promptTokens，当超过模型上下文窗口的 80% 时触发压缩。
第二，用 compressHistory 让模型把历史总结成结构化摘要。摘要重点不是“语言优美”，而是保留后续执行需要的信息：
- 已经完成了什么；
- 还剩什么没做；
- 当前修改了哪些文件；
- 有哪些坑和约束；
- 哪些操作不要重复。
压缩完成后，旧 history 可以清空，摘要作为 runtime hint 注入下一轮系统提示词。这样 Agent 不需要携带完整历史，也能继续任务。
这里有一个工程取舍：压缩会损失细节，但不压缩会直接超上下文。实际项目里通常还会结合滑动窗口、重要消息保留、文件级索引等策略。本教程先实现最容易理解的一版。
CLI 入口：让 Agent 可以连续工作
最后把所有模块串成一个 CLI：
入口逻辑做了几件事：
- 读取用户输入；
- 调用
agentLoop； - 打印最终回答；
- 保存本轮
responseMessages到 history； - 根据 token 使用量决定是否压缩；
- 支持
/reset、/exit、/help等基础命令。
history 和 runtimeHints 在多轮之间持久存在，这是它能像一个真正助手一样连续工作的基础。
整个运行链路可以概括为：
第六章：从玩具到 Code Agent，中间多了什么？
现在回头看两个版本的差异。
最重要的结论是：mini-claude-code 并没有改变 Agent 的基本原理。它只是把原理放进了更可靠的工程结构里。
手写版里的这些动作：
在 SDK 版里仍然存在，只是由 SDK 和工具系统接管了大部分细节。
Code Agent 的三个工程重点
如果你继续扩展这个项目，优先关注三个方向。
第一，工具边界。 工具越强，越要定义清楚输入、输出、权限和失败行为。不要让模型靠猜使用工具。
第二，上下文工程。 不要等上下文爆了才处理。文件读取、搜索结果、命令输出都应该有分页、过滤、截断和明确提示。
第三，安全策略。 只要涉及文件和命令执行，就必须考虑路径限制、危险命令、用户确认、超时、资源回收。
这些问题不是模型能力问题，而是软件工程问题。一个 Code Agent 是否可靠，很大程度取决于这些边界是否设计得足够清楚。
收尾
我们从一个天气查询 Agent 开始，手写了最小 ReAct 循环；然后把同样的思想迁移到 Code Agent，使用 Vercel AI SDK 实现了工具注册、自动工具调用、多轮上下文、安全防护和压缩机制。
这条学习路径的重点不是“记住某个框架 API”，而是理解 Agent 的运行骨架：
如果你刚开始学习 Agent 开发，建议先跑通 agent-loop，确认自己理解每一轮消息是如何流动的；再看 mini-claude-code，理解一个能处理真实代码任务的 Agent 需要补哪些工程能力。
核心概念不复杂，几十行代码就能跑起来。但从“能跑”到“能可靠地解决真实问题”，中间每一步都是工程设计。