从零 · 不需要编程基础

亲手写一个 Agent

跟着一份干净的源码，把它补出来、让它真跑起来

不讲概念，不搭积木。跟着一份干净的开源实现，一块一块把它补出来、让它在你电脑上真跑起来。学完你手里是一个你看得懂的 agent，不是"我了解了原理"。不需要编程基础——作者本人也不懂代码，是边学边做的。

免费从第一节开始前 10 节不用登录

篇章8

已上线课时39

免费试读10 节

更新节奏每周一章

"我懂 AI 的原理"——可你能自己写一个吗？

市面上讲 agent 的，要么是"三天精通"的空话，要么把它当黑箱只教你调用。这门课反过来：跟着一份干净、能跑的开源实现，一块一块把它补出来、让它在你电脑上真跑起来。而且是同一个项目逐章长大——从空白到能跑，你补的每个零件都留在手里，收官时它们合体成一个完整的 agent，不是学完就散的知识点。学完你手里是一个你看得懂、改得动的 agent，不是"我了解了原理"。不需要编程基础——作者本人也不懂代码，是边学边做的。

一条真实的运行轨迹 · 7 events · 3 model turns · 0 network calls

01 user "帮我看看 login.ts 为什么报错"

02 model toolCall · read({ path: "login.ts" })

03 tool → 〈login.ts 全文 · 200 行〉

04 model toolCall · edit({ path: "login.ts", line: 42 })

05 tool → 已改第 42 行

06 model "改好了，第 42 行少了个 await，你看一下"

07 loop 没有新工具调用 → 跳出循环，回合结束

一次提问，模型和工具你来我往，最后循环判断"没活了"就停——<b>这 7 行，就是一个 agent 活着的全部。看懂它，你就看懂了 agent。</b>

一门课带你搞懂 agent 靠哪六件运转

会

会话Session

搞懂：记忆怎么存、分支怎么回溯

环

循环Loop

搞懂：它凭什么能自己一步步干下去

文

上下文Context

搞懂："三明治"怎么攒、怎么省钱

具

工具ToolUse

搞懂：一次调用要过哪四道关

适

适配Provider

搞懂：换模型为什么不用改代码

设

人设系统提示

搞懂：怎么给它定脾气、挂技能

掌柜 · 阿澄 · 为什么要有这门课

1痛点 · 想搞懂 AI agent，满世界却是"三天精通"的空话和黑箱

2挣扎 · 搭积木、翻文档，还是说不清它到底怎么转起来

3转机 · 不如跟着一份真能跑的代码，一块块把它补出来

4这门课 · 学完手里是一个你看得懂的 agent，不是"我了解了原理"

怎么算学会（不吹，看得见）

不是"看完视频点个懂"。是：给你一段陌生的 agent 报错，你能顺着 trace 指出是哪一层出的问题；合上教程，你能自己说清那六件各自在干嘛、怎么拼起来。做得到，才算学会。

章节路线图

篇章 1

序章 · 开始之前

01 先说清楚：你要造的是什么 我不懂代码。这门课是我边学边做的——先过了自己这关，才敢给你。先花五分钟，看清楚你要造什么、能走多远。免费 02 一个 agent，逃不掉这四件事 别被"agent"这个词唬住。它逃不掉四件事：会说话的模型、替它记账的会话、反复推进的循环、让它动手的工具。这是直觉；课程真正拆的六个模块，是从 Pi 源码来的，本节最后给你对上。免费 03 每个比喻，都焊一个真名 这门课会给你一堆比喻——账本、书签、投影。比喻帮你懂，但有个副作用：用久了，你会忘了这东西在真实世界里叫什么。所以我们立一条规矩，也给你一张随时能翻回来的对照卡。免费 04 最好的教材，是一个你能跑起来的 agent 这门课拆的 pi，不是一份躺在网页上的代码——你现在就能把它装进自己电脑，让它真跑起来。你装上的这个 pi，和我们后面一行行拆的，是同一份源码。学的即用的。免费

篇章 2

Session · 会话是一棵能回溯的树

01 先把 Session 玩坏 别急着看解释。下面这个沙盘里有一份"账本"和一根"书签"，先动手把它弄到一个你觉得不合理的状态——比如让模型看到的内容变少，但账本一条都没减。免费 02 一页账本就是一个 Entry 跟着一个真实案例——修 login.ts 的一个 bug——把账本一页一页写出来。每一页是一个 entry：有的会变成消息，有的只改状态。每往下走，先让你猜三个数字，猜完再揭晓。 🔒 03 压缩不删账本，只加一层书签 context 冲到 48k，该压缩了。但压缩怎么做才能既让模型少看、又不丢历史？先猜账本会不会变短，再看 Pi 那 12 行是怎么办到的。 🔒 04 改历史不改原文，只挪书签 账本会长了，但还不会动。这一课讲三个动作——回退、分叉、复制会话。做完你会发现，它们都不是新机制，只是那两样东西的不同组合。 🔒 05 自己写一遍（TypeScript） 约 50 行 TypeScript，四个函数，一组测试。跑通就说明你真的懂了。给的是分段提示词，不是整段需求——目的是学会，不是做出来。 🔒

篇章 3

Loop · 一次调用不是 agent，循环才是

01 先把 agent 卡在半路 别急着看"主循环"三个字。这一课不讲机制，先让你亲手把一个 agent 弄"死"——看它怎么在任务做到一半时停住、干等。你先撞上这个坑，下一课那个循环才有意义。免费 02 一次调用不是 agent，循环才是 上一课你把 agent 卡在半路——它说"我要读 login.ts"，然后就没下文了。这一课补上那半步：把"调一次模型"换成"一个循环"。补完，agent 就活了。而且你会发现，决定它什么时候停的，根本不是你。 🔒 03 一轮多个工具，能并排就别排队 上一课那句 executeTools(toolCalls) 是个黑盒。拆开看：模型一轮可能同时要好几个工具，怎么跑？默认并排跑更快，但有的必须排队。还有个反直觉的"全票"规则，决定这批跑完循环停不停。 🔒 04 主循环一大半，是在接住三种意外 正常流程十行就够了。可 Pi 真实的主循环有 792 行——多出来的一大半，不在处理"正常"，而在接住三种意外：话被截断、用户喊停、用户插话。这三种，才是玩具 agent 和真 agent 的分水岭。 🔒 05 自己写一遍主循环（TypeScript） 约 40 行 TypeScript，把 while 循环 + stop_reason 分支 + 工具执行 + 一种意外处理拼出来，跑通一组测试。给的是分段约束，不是整段需求——目的是学会，不是让 AI 替你糊一个。 🔒

篇章 4

Context · 每次现攒一份，攒得稳才省钱、攒不下才压缩

01 每一轮，都把前面全部重发一遍 按下回车，你以为发给模型的是刚打的那句话。其实不是。这一课先让你看清：每一轮，agent 都把之前说过的全部、加上一整套规矩和工具，重新打包发一遍——而且越滚越大。免费 02 Context 是每次现攒的一份三明治 上一章你反复听到"context 是投影出来的，不是存的"。这一课把那份现攒的 context 摊开看：它不是"你最后一句话"，是系统提示 + 全部历史 + 工具，三层，每次调用整个重发一遍。 🔒 03 不变的放前面，是为了缓存、不重复收费 L0 里那个"系统提示被传了 8000 token"的浪费，真实 agent 几乎不为它多花钱。靠的是 prompt caching。这一课讲它怎么做到，以及一个直接关系钱包的结论：三明治的顺序，一步都不能乱。 🔒 04 窗口有上限，历史只增——迟早得压 缓存救了钱，救不了容量。窗口是硬上限，历史只增不减，迟早撑爆。Session 章教了压缩"怎么存"，这一课回答它故意留下的三个问题：什么时候压？从哪切？怎么摘要才不丢关键信息？ 🔒 05 自己攒一次 context + 一个压缩判断（TypeScript） 约 40 行 TypeScript：把三明治攒出来、读模型账单量大小、判断该不该压、决定从哪切。跑通测试，你手里就是一个会自己管理记忆的 agent 内核。给的还是分段约束。 🔒

篇章 5

ToolUse · 工具让模型能动手，但每一下都要过四道关

01 先给模型装一只手 前三章的模型只会"说"。这一章给它装上手——能读文件、能跑命令。但先看清一件事：模型开口要的那个动作，参数是它现编的，你敢闭着眼睛替它执行吗？免费 02 一个工具，就四样东西 "工具"听着玄，拆开就四样：名字、说明、参数格式、怎么执行。而其中前三样，正是上一章"三明治"里那层工具清单——模型看到的，只有它们。 🔒 03 模型说要调，不等于马上跑——四道关 上一章 Loop 里"执行工具"被一句 executeTools 带过。真相是：从"模型说要调"到"结果回到账本"，每个工具调用都要过四道关——准备、执行、收尾、回填。这一课把这条流水线铺开。 🔒 04 "准备"这道关：校验参数 + 拦住危险 四道关里，"准备"是 agent 敢在你真实电脑上动手的全部底气。它在执行之前做三件事：找到工具、按 schema 校验参数、过一道权限拦截——任何一步不过，立即变错误、绝不执行。 🔒 05 "收尾"关：报错和长输出，都得收得住 execute 跑完了，拿到一坨原始结果——它可能是个异常，也可能是几万行输出。这坨东西不能直接塞进账本。收尾与回填这两关，负责把它收拾成模型读得懂、又不撑爆上下文的一条干净消息。 🔒 06 认识 pi 自带的这几件家伙 前面拿 read 当范例，把工具的机制讲透了。这一课换个角度：pi 到底自带哪几件工具？它们少，但每一件都有一个聪明的设计——而且每个设计，都是你前几课学过的主线的实例。 🔒 07 自己写一个工具 + 四阶段执行器（TypeScript） 约 45 行：定义一个工具，写一套跑通"准备→执行→收尾→回填"的执行器。测试要覆盖两个关键场景——参数不合法被拦在执行前、execute 抛异常被接住不崩。 🔒

篇章 6

Provider · 一套代码接多家模型，差异都被一层适配吸收

01 同一句话，Anthropic 和 OpenAI 发出去完全不同 你的 agent 到现在只跟一个模型说过话。可市面上有 Anthropic、OpenAI、Google……换一家，请求的形状差得像两种语言。这一章讲：怎么让 agent 一套代码接所有家，换引擎不改代码。免费 02 一层适配器，把"哪家"和主循环隔开 主循环不该知道自己在对接哪一家。Pi 的做法是让它只对着一个统一接口说话——一份 Context、一个 StreamFn。每家配一个 adapter 负责翻译。而这个 StreamFn，你在 Loop 章其实早就见过。 🔒 03 翻译是双向的：请求出去、响应回来 adapter 当翻译官，两个方向都要翻。请求：把统一格式改写成某家方言。响应：把某家的流式输出翻回同一串标准事件。回来这半程尤其难——各家的流长得完全不一样，却都得归一成"文字来了/工具来了/结束了"。 🔒 04 抹平的不只是格式，还有"会不会" 各家不只长得不同，能耐也不同——有的支持工具缓存，有的不支持；有的能调温度，有的不能。adapter 要抹平的第二层差异是"能力"。它靠一张每个模型自带的"能力清单"来兜：不支持的功能，要么关掉、要么降级，绝不硬发。 🔒 05 自己写一个 mini adapter（TypeScript） 约 40 行：把一份统一 Context 翻成某家的请求形状（出去）、把它的响应流翻回统一事件（回来）、还要按能力清单决定某个功能加不加。跑通测试，你就亲手证明了"换家只需换 adapter"。 🔒

篇章 7

人设 · 系统提示是岗前培训，技能是随手翻的手册

01 同一个模型，给不给"人设"判若两人 前五章你造好了一台机器：会存、会转、会装、会动手、能换引擎。但它还没有"人设"。这一章给它岗前培训——系统提示告诉它是谁、该怎么做事。先看一眼：同一个模型，加不加这段培训，判若两人。免费 02 系统提示写什么：身份 + 工具 + 规矩 系统提示不玄，就三块：你是谁（身份）、你有哪些工具（能力清单）、该怎么做事（规矩）。而它待的位置，正是上一章三明治的最底层——整场不变、每轮都在、最该被缓存的那一层。 🔒 03 别把什么都塞进系统提示 系统提示每轮都在、还是缓存地基，很容易让人想"把所有专业知识都塞进去，一劳永逸"。这恰恰是个坏主意——不只烧钱，还会稀释模型的注意力。这一课讲为什么，以及 Pi 用什么办法破局。 🔒 04 技能：平时只挂个目录，用到才翻全文 技能妙在加载方式。系统提示里平时只挂一张"技能目录"——每个技能就一行：叫什么、干嘛用、在哪。只有模型真要用某个技能时，才把那一整本手册拉进上下文。这套"目录常驻、正文按需"的手法，有个名字叫渐进式披露。 🔒 05 自己拼一段系统提示 + 挂一个技能（TypeScript） 约 35 行：拼一段系统提示（身份+工具+规矩），把技能做成"目录常驻、正文按需"。测试要证明两件事——平时系统提示里只有技能目录、没有正文；被调用时正文才拉进来。这是拼成真 agent 的最后一块。 🔒

篇章 8

收官 · 你写的那些零件，合体就活了

01 六块拼图，接上线 前六章你一块一块写下了 agent 的六个零件。这一课把它们接上线，喂一个真实任务，亲眼看它们合在一起把事做完。用的是脚本化的假模型——不花一分钱、人人能跑，且每一步都是你写过的东西在动。 🔒 02 回到真 pi，认出你写的每一块 上一课你拼的是玩具（假模型、略过压缩）。这一课回到序章你装好的那个真 pi，跑一件真的事——然后逐帧对照：这就是你写的循环、这是四道关、这里压缩真的触发了。序章那句"你装的就是你拆的"，当着你的面兑现。 🔒 03 你现在能拿它做什么 课到这儿就上完了。最后一课不讲代码，只说两件事：你现在手里到底有了什么，以及——一句送别。从"我了解了原理"，到"我能上手、能改、能看懂"，这中间隔着的，正是你走完的这一路。 🔒