前言

你是一名对AI炒作持怀疑态度的软件工程师。

你尝试过各种框架——然后眼睁睁地看着自己的LangChain应用胡乱生成指令，把生产数据库给删了。你心想：“一定有更好的办法。”

确实有。本书面向那些想真正理解AI智能体运行原理的开发者。不是营销图表。不是什么“推理引擎“抽象层。而是实际的HTTP请求。实际的while循环。

只要你能读懂Python，并且有过构建 Web 应用或CLI工具的经历，你就已经具备了阅读本书所需的一切。

Nanocode 是一个在终端中运行的编程智能体。读完本书后，它将能够：

• 读写代码库中的文件
• 执行 shell 命令
• 使用纯Python搜索代码
• 跨会话保留上下文
• 通过安全模式将规划与执行分离
• 在网络上搜索文档和答案

你将使用 requests、python-dotenv 和 pytest 从零开始构建它；shell 访问能力来自Python标准库中的 subprocess 模块。没有LangChain，没有向量数据库，没有“编排框架“，只有你可以用 print() 调试的Python代码。

唯一的例外：第11章新增了 ddgs 用于网络搜索——这是本书唯一新增的一个轻量级外部依赖。

本书采用“测试并行“的方式。对于大多数功能：

1. 我们先介绍概念——为什么需要这个功能
2. 先展示测试，让你清楚成功的标准是什么
3. 再编写代码，让测试通过
4. 最后用pytest验证

这种方式传授了测试驱动开发的思维方式，同时省去了书面呈现完整红-绿-重构仪式的繁琐。它还解决了一个关键问题：你无法通过真正调用大语言模型来测试由其驱动的应用。API调用速度慢、成本高，而且结果具有不确定性。

从第3章开始，我们引入 FakeBrain 模式——一种能返回可预测响应的测试替身（test double）。这样你就可以在不发起任何API调用、不花费一分钱的情况下，运行完整的测试套件。

本书遵循“代码优先“的方式。每章在前一章的基础上递进，所有代码示例均从可运行的文件中提取。

获取代码：

• GitHub： 从GitHub克隆或下载。¹
• Leanpub： 完整源代码也包含在购买后可下载的资源包中。

代码按章节组织（ch01/、ch03/、ch04/ 等），另有一个 appendix/ 文件夹。大多数文件夹包含：

• nanocode.py — 该章节完整的、可运行的智能体代码
• test_nanocode.py — 无需API调用即可验证代码正确性的测试

有两个例外：ch02/ 只包含一个独立的 test_api.py 脚本（仅使用一次后即弃用），ch12/ 的智能体快照在功能上与 ch11/ 相同，并附有收官项目成果。

你可以复制任意章节文件夹，从那里继续。运行 pytest 来验证你的代码是否符合预期行为。

全书中，你会看到三种标注框：

代码讲解遵循统一的结构：先是背景（为什么需要这段代码），然后是代码本身，最后逐行解释重要部分。

是时候写代码了。