手搓Claude Code（1）：一个极简Agent的诞生
2026-04-08
前言
一直以来，我都在使用各种“Vibe Coding”（氛围感编程）工具。但我的内心始终藏着一个问题：同样是以 AI 为驱动，为什么有些工具如丝般顺滑，有些却总是人工智障？
业界最好用工具可能是 Claude Code，虽然最近一不小心开源了，但是几十万行的代码也不是我这种小白就能分析明白的。
找了找市面上其他讲 Claude Code 的文章，但大部分不是教你怎么使用 Claude Code，就是分析 Claude Code 各种架构，非常硬核，显然也不是我一口吃的下的。
所幸，在 GitHub 游荡的时候发现一个非常有意思的项目，叫做《learn-claude-code》，教你从 0 到 1 自制一个 Nano Claude Code。最让我惊喜的是它的视角：它摒弃了那种“先看总架构、再看子模块”的传统授课方式。
相反，它采用了一种演化的方法：
- 从一个最简单的、只会复读的 AI 开始。
- 告诉你这个 AI 遇到了什么现实困难（比如：它没手没脚、它记性不好）。
- 为了解决困难，我们需要亲手给它加上什么模块。
这种从创造者视角出发、抽丝剥茧的过程，真的让人有种拨开云雾见青天的快感。
或许有人会问：“我学会怎么用 Claude Code 不就好了吗？为什么要关心它是怎么造出来的呢？”
我想换个角度回答：一个优秀的赛车手，必然对赛车的机械原理了如指掌。 只有知道它如何换挡、如何进气，你才能在弯道时人车合一。理解 AI Agent（智能体）的底层逻辑，能帮助你更好地驾驭 AI，而不是被它牵着鼻子走。
《learn-claude-code》的作者应该是一位极其硬核的程序员，视角还是比较极客，这对于编程基础一般的朋友来说，读起来可能还是有些吃力。我也算是一个“技术半瓶水选手”，好在有 AI 的帮助，咬咬牙也是去啃了下源码，通过源码也是更透彻的理解了这个教程。
啃完之后，我觉得如果能把这些精妙的架构逻辑，用更通俗易懂的方式分享出来，那将非常有意义。
这个项目其实讲解的内容非常多，所以我准备写一系列文章分解，今天先稍微讲讲一个最简单的Agent是怎么做成的。
有编程基础的，更建议读原项目，《learn-claude-code》项目地址：https://github.com/shareAI-lab/learn-claude-code
为什么需要Agent
让我们把时间倒回 ChatGPT 刚问世的那阵子。那时候，OpenAI 仅仅丢出一个极简的网页聊天框。大家惊喜地发现，屏幕对面坐着一个上知天文、下知地理的"万事通"，于是全网都陷入了跟它聊天的狂热。
没过多久，OpenAI 开放了 API 供开发者调用。市面上随即涌现出大批"套壳" Chatbot，乃至各种主打"角色扮演"的虚拟伴侣、行业专家 AI。
其实，这些五花八门的 Chatbot 背后，并没有什么深不可测的黑科技。它们最基础、也最普遍的那层秘密，全靠一个叫做 「System Prompt」（系统提示词） 的东西。
当你以为自己只是单纯地对 AI 说了一句"你好"时，厂商其实早已在暗地里帮你塞了一点东西，AI 真正接收到的完整信息，长这样：
[系统提示词 / System Prompt]：你是一个善解人意的聊天机器人，你能做 XXX，你绝对不能做 XXX。
[用户消息 / User Message]：你好。
在收到了带有身份限制的消息以后，AI就自然而然的开始了角色扮演。
看懂了这点，你也就摸清了市面上绝大多数套壳 AI 最底层的运作逻辑。当然，这仅仅是构造一个 Chatbot 的第一步。
既然已经有了五花八门的 Chatbot，大家聊得不亦乐乎，为什么还要搞出一个 Agent（智能体） 呢？
原因很简单：光靠"聊天"，是干不了重活的。
举个例子。你让 Chatbot 帮你写个小游戏，它确实给你写了几百行代码。但接下来，你得自己新建文件、粘贴代码、打开命令行运行。报错了，再把错误信息复制回来，等它修改，再粘贴、再运行……
AI 负责动脑，你负责动手。说好的"帮我干活"，结果你成了它的"人肉复制粘贴机"。
我们真正想要的，是一个能把事情从头做到尾的 AI。
Agent Loop：让 AI 自己转起来
普通 Chatbot 的工作方式是"你一句我一句"，你不问话，它就不回复。
你 → AI → 你 → AI → 你 → AI ……
（每一步都要你推着走）
Agent 的不同之处在于，它内部跑着一个持续循环的程序（Agent loop）。每轮思考结束后，它会判断：任务完成了吗？
如果没完成，它会发出一个"使用工具"的信号（在 Claude 的 API 里叫做 tool_use，OpenAI 那边则叫 function calling，叫法不同，原理一致），意思是"我需要做点什么"。程序收到信号，在后台把事情办好，把结果反馈给它，它拿到结果继续思考，继续判断，继续发信号……直到它认为任务完成，才停下来把结果告诉你。
这也正是为什么现阶段大部分 Agent 都相当烧 tokens——每一次循环，都要把前面所有的对话历史重新带入上下文，相当于在 Chatbot 里重新发起了一次会话，只是这次换成 Agent 代替你发问而已。循环越多次，消耗的 tokens 就越多。
你 → AI 思考
↓ 没完成
工具执行
↓ 结果反馈
AI 思考
↓ 没完成
工具执行
↓ 结果反馈
AI 思考
↓ 完成了
你 ← 最终结果
整个中间的过程，不需要你介入任何一步。
给它一双手：Bash
有了自动循环的机制，就需要给 Agent 配上真正能操作电脑的工具了（tool_use）。
我们先只给它装了一个工具，叫做 Bash——也就是大部分电脑自带的那个黑框命令行。
命令行是操作电脑最直接、功能最全面的方式之一，你用鼠标能做的绝大多数事情——读写文件、安装软件、运行程序——它都能做到。把这一个工具交给 Agent，它就能写文件、运行代码、查看报错，什么都能干。
于是，当你说"帮我写个贪吃蛇并运行"：
你说：帮我写个贪吃蛇并运行
第一圈循环：
AI 思考 → 给出贪吃蛇代码
↓ 调用 Bash 工具，把代码写入文件
写好了 ✓
第二圈循环：
AI 思考 → 决定运行刚才写好的文件
↓ 调用 Bash 工具，执行运行命令
游戏弹出来了 ✓
你收到：一个跑起来的贪吃蛇
游戏直接弹出来了，你全程没有碰过键盘，更不需要复制粘贴。
这就是 Chatbot 和 Agent 最根本的区别：一个等你动手，一个自己把事情做完。
好了，现在我们已经拥有了一个能自己思考、自己动手的 Agent，但是它还很弱小，只能做一些简单的事情。
为什么只有一个 Bash 是不够的
我们把 Bash 交给了 Agent，让它有了真正动手操作电脑的能力。理论上，只要有 Bash，AI 就能做到人类在命令行里能做的一切——读文件、写代码、运行程序。
既然 Bash 这么全能，我们为什么还要多此一举，专门再开发其他工具呢？
原因同样很简单：全能的工具，往往意味着粗糙和失控。
就好比你有一把瑞士军刀，开瓶盖、锯木头、剪指甲，样样都能来。但如果你要做一台精密手术，你绝不会拿它上场——精度不够，风险太高。
在真实的 Agent 运行环境里，只给 Bash 会面临两个非常现实的问题。
问题一：执行极其容易出错
假设你想让 AI 帮你读取或者修改一个代码文件。
如果只有 Bash，AI 就只能靠敲命令行来完成这件事。读文件要用到一种读取命令（cat），但这个命令会把文件内容一股脑全部输出——文件太大时，AI 的脑容量（上下文窗口）装不下，信息就会被悄悄裁掉；要修改文件，AI 只能依靠一种"查找并替换"的命令（sed）——非常原始，一旦文件里出现了一些特殊符号（转义字符），整个命令当场就会报错崩掉。
【只有 Bash 时】
读大文件：
AI → 调用 cat 命令
↓ 输出一万行内容
AI 脑容量不够，信息被裁掉 ✗
改代码：
AI → 调用 sed 命令
↓ 遇到特殊符号
命令崩溃报错 ✗
每次操作都是这样"硬凑"命令，成功与否全看运气，整个过程走钢丝一样不稳定。
问题二：安全边界完全失控
这是更严重的问题。Bash 的权限实在太高了。
你可以把 Bash 想象成一把电脑的"万能钥匙"，它能打开电脑里几乎所有的门。当你把这把钥匙，原封不动地交给一个偶尔会有"幻觉"的 AI 时，后果是难以预料的。它可能因为一个错误判断，把你不该删的文件夹一口气删干净（rm -rf）；也可能被恶意的提示词诱导，悄悄去翻你个人文件夹（主目录）里的隐私文件，你完全不知情（这也是为什么说不建议在自己工作电脑上装小龙虾的原因）。
专用工具：给每件事配一把合适的钥匙
看懂了这两个问题，你也就明白了为什么要引入专用工具（Tools）。
思路很直接：把那些高频的、需要精确控制的操作，从 Bash 里单独拿出来，做成一个个专门的小工具（函数）。比如，直接给 AI 提供 "读取文件"（read_file） 和 "写入文件"（write_file） 这样的专用功能，而不是让它自己去拼凑那些脆弱的命令行。
这样做带来了两个好处：
- 更稳定：读文件就是读文件，改文件就是改文件，专用工具只做一件事，不会被乱七八糟的符号搞到崩溃。
- 划定活动范围（Path Sandboxing）：我们可以在这些专用工具里，悄悄加一把"锁"。比如明确规定 AI 只能在当前的项目文件夹（工作目录）里活动，一旦它试图读取项目之外的文件，工具就会立刻拒绝并报错："越界了，不行。"
Bash 给了 AI 动手的能力，而各种专用工具则为它划定了行动边界。有了这套多工具调度机制，我们的 Agent 才从一个容易乱来的莽撞选手，变成了一个精准、安全、可扩展的得力助手。
现在我们的Agent已经升级到了以下水平，你终于拥有了一个极简可控的Agent：
你 → AI 思考
↓ 没完成
工具调度表 → 执行对应工具
↓ 结果反馈
↓ 没完成
工具调度表 → 执行对应工具
↓ 结果反馈
...
AI 思考
↓ 完成了
你 ← 最终结果