《Pi Agent实战》杀青,下一旅程是零基础学习和应用AI

上一套的验收题是刚好 50 块的订单,下一套也备了几道容易翻车的题,住宿报销就是头一道。老规矩,先做最小的一版,看它怎么答、怎么错。手里攥着一组能反复跑的题,下一步该改提示还是补检索,跑一遍就知道,不用坐在那儿冥想。

《Pi Agent实战》杀青,下一旅程是零基础学习和应用AI

起因是个特别小的 bug。系统里满 50 免基础运费,结果有天一单刚好 50 块,运费照扣 5 块。查下来,判断写成了 >,少个等号。改成 >=,两秒。

然后我为这个等号写了 22 章教程。

听着像行为艺术,但真不是。《Pi Agent 实战:从第一次运行到自建 Agent Harness》,22 章,10 个能单独跑的小项目,十月底动工,十一月中写完。等号本身没什么可讲的,值得讲的是它周围那一圈事:Pi 到底动了哪些文件?终端里刷过去一片绿,测的是谁?半夜没人盯着屏幕,程序凭什么认为活儿干完了?等号两秒修完,这三个问题花了我三个礼拜。

代码和正文都在 GitHub:vadxq/pi-agent-practice[1]。基于 Pi 1.4.0,资料基线 2026-10-23。Pi 迭代不慢,要是过俩月你照着跑不通,先别骂我,多半是版本变了,抓个 AI 对着报错问问就好。


01. 改代码之前,先让测试红一次

第一章不改代码,先看。终端连上模型,让 Pi 只读,把运费在哪算、哪组测试管这事找出来。需求提前掰碎了说:国内单 49.99 收 5 块基础运费,50 和 50.01 免;免的只有基础运费,加急费照收,国际规则别碰。

嫌啰嗦?你试试只丢一句"把运费修好"。它真能把运费全改成 0,然后交一份全绿的测试报告。你说它错了吗,运费确实"好"了,一分不收,好得过头了。

练习里放了两份代码,一份埋着 bug,一份是对的。先拿坏的那份跑验收:12 项检查挂 2 项,挂的全是刚好 50 块那单,普通、加急各一,剩下 10 项绿着。这时候反而可以踏实:环境没毛病,坏的就是业务逻辑,位置还跟猜的一样。改完看 diff,同一套检查再跑一遍。对的那份也全绿,不过它生下来就是对的,那个绿不值钱。

这一章还顺手拆了个底。Pi 在终端回你一段话,背后可能已经跑了好几个来回:模型说想看看这个文件,Pi 去磁盘读了递回去,模型看完说再看看那个。它嘴上说完了,手里的工具还在跑;你把聊天窗口关了,测试照样跑。聊天记录顶多算个过程回放,代码最后长什么样,得开文件夹验货。记录不是交付物,这句话到后面写 Harness 还会反复用到。


02. 同样的活干第二遍,哪些话不用再说

第一次干活,手把手交代没问题:哪些文件能动、边界怎么验、交差带什么。第二次换个仓库,把上次的提示词原样贴过去,多半要翻车。任务名改了,验收命令还是上个仓库的;规则改了,某个模板里还留着旧数字。你自己都不记得哪句是抄来的,模型更不会替你记得。

所以教程把这些话分了家:

  • 项目指令:这个仓库长期有效的规矩,写一次。

  • 模板:这次任务查什么范围,每次填。

  • Skill:这类活儿的通用查法,攒着用。

  • 扩展和 MCP:扩展加工具、挂事件,要接外面的能力再走 MCP。

一条规矩只在一个地方住。到处各写一份,过俩月它们自己就打架了,模型夹在中间,听谁的都是错。

最后打包成 Pi Package。验收办法特别土:找个干净配置跑一遍,看工具在不在、命令灵不灵。别拿自己电脑验,你那台机器早就被你喂得饱饱的,缺什么依赖你顺手就装过了。换个干净容器,一跑,缺啥全暴露。


03. 接进自己的程序,谁说了算

到 SDK 这部分,之前靠嘴交代的事得一件件写成代码:什么时候开会话,给哪些工具,模型最多调几次,用户点了取消之后还继不继续。这层在后台管调度的代码,教程里叫 Harness。说白了就是工头:干活的说"我觉得该拆这面墙",工头得拦一下,承重墙,拆不得;测试没跑就想报完工,工头也不签字。

运费题在这又出场了一次,这回练分工。两个只读的子 Agent 分头行动,一个查代码一个查业务要求,父 Agent 收齐情报再动手改,改完跑老规矩的检查,再另请一轮审阅。

这里有个坑。子 Agent 回来汇报,就一句"应该是少了个等号"。应该?我派你出去,就是让你把"应该"变成"确定"的,你带个"应该"回来,我还得亲自再跑一趟,那我要你干嘛。所以汇报有格式:文件在哪、看到了什么、哪些还没核实,一样不能少。

还有钱的事。几个子任务花的是同一份预算,得有人记账。不管账的话,每个子 Agent 花得都不多,月底加起来一看,好家伙。

这章我自己最受用的,是把"停止"和"完成"掰开了。补丁写出来了,验证跑到一半用户点了取消,改动可以留着给人审,但状态不能写"修复通过"。停了就是停了,别给自己脸上贴金。评测同理:一个只读 Agent 和一个能改文件的 Agent,比分析质量可以,比谁修得好就欺负人了——只读那位压根没拿到改代码的权限。它没改,是守规矩,不是菜。真想比手艺,给一样的权限、一样的验收,再上场。


04. 从本机到服务,中间隔着一堆事

自己电脑上跑一个任务,挺省心的,目录选对就能干活。一上服务,麻烦全是组团来的。两个任务同时往一个工作区里写,打起来了;进程半夜退了,早上重启,上轮干到哪了,没人知道;升级之后行为不对,是模型换的、扩展换的,还是哪个验收命令被人顺手改了?慢慢查吧。

后面几章就在收拾这些:任务记录、工作区隔离、并发限制、故障恢复、部署验收。有能上手的 SQLite 和隔离实验,也有一些只放在正文里聊的方案。

丑话照旧说在前头:跑通一个小实验,离手搓一个高并发高可用的生产服务,中间还隔着十万八千里。看完别急着上线,真的。

剩下几个方向可以单拎出来玩:按任务挑模型、把 Agent 循环拆开看、长任务存进度、从 Python 调 Pi、去源码里逛一圈。10 个项目互相独立就是为这个,想尝口 Python 客户端,不用先把整套环境供起来。

Pi 这套写到这,算是从"怎么用一个 Coding Agent"走到了"怎么把它塞进自己的程序"。下一套我想把起点再往前挪挪:先不急着挑 Agent 工具,先写自己的 AI 应用。等真撞上"一个循环搞不定"的活儿,再谈 Agent 也不迟。


05. 下一本:《AI 应用与 Agent 工程》

新课从一个 Python 小程序起步:几份材料,问模型一个问题,结果存下来。材料用的是虚构的业务资料。

里面埋了这么一道题。差旅制度白纸黑字写着,北京住宿每晚报销上限 600。AI 助手读完,结论是"每次出差最多报 600"。

住三晚的朋友按制度能报 1800,按它的说法只能报 600。差的 1200 找谁要?找它吗,它连工资都没有。

这种错最阴的地方在于,出处引得一页不差,语气斩钉截铁,你不逐字对原文根本发现不了。所以第一版评测就冲它去的。

报告不能是一坨读着挺顺的文字,得能拆开看:结论是哪句,凭的原文是哪句,哪些地方是它自己脑补的。写代码核对出处位置只是第一关,还得看那段原文撑不撑得住这个结论。页码引对了、结论照样跑偏,这种事太常见了。

材料里没写的,就让它说"没查到",三个字,不丢人。接口超时报错,就老老实实报"请求失败"。最怕它把这几种情况混着说,一律"资料中未提及",搞得你都不知道该去补文档还是该去修网络。

材料就几页的时候,别折腾,全塞给模型完事。攒到几百页塞不下了,再上检索,关键词一路,向量一路,同一道题,看两边各自捞回来什么。这么分路有个好处,答错了能破案:捞回来的材料里压根没有那份制度?检索的锅。制度明明在材料里,它还答错?阅读的锅。锅分清了,修起来才不抓瞎。

再往题里加点坏的。制度出了新版,旧版还躺在资料库里,问它现行标准,它引用旧文件答得那叫一个自信。所以更新资料、下架旧版这些不起眼的杂活,本身就是问答质量的一部分。


06. 什么时候才真的需要 Agent

说实话,Agent 这个词现在有点通货膨胀,什么活都想套一个。

比如"北京住宿一晚最多报多少",搜一下,600,白纸黑字,完事。这种题配个 Agent,属于查字典之前先开项目启动会。

换成"我去北京住三晚,一共能报多少",味道就不一样了。得先找到差旅制度,翻到住宿那节,盯住"每晚"俩字,再乘三。哪步没走对,就是上面那个 1200 的惨案。这种要边查边定下一步的活儿,交给助手自己拿主意就合理多了。工具先只给只读的,能翻哪些资料,程序圈死。

后面把查资料的工具做成可复用的 MCP 服务,再用 Skill 写清楚查法和整理格式。这俩得分开验,别问我怎么知道的:工具连得通,跟宿主真按你写的方法干活,完全是两码事。

长任务那块有个挺损的实验:报告已经生成、文件还没落盘,就在这个节骨眼上把进程杀了。重启,从检查点把报告捞回来,接着存。为什么不让模型重写一遍?重写就是再烧一遍钱。断点续传这道理,网盘十年前就教会我们了。

多 Agent 那块,单 Agent 版本留着不删,两个版本拿同一份预算跑同一批题,跑完对着看:分工到底多查到了什么,汇总时又弄丢了什么。要是新加的那位只是把别人查过的资料又查了一遍,恭喜,你雇了个复读机。删了,一点不可惜,Token 是真金白银。

最后把助手做成服务,验几件扫兴但必须的事:不同身份进来各能看到什么;重启一回、从备份恢复一回,之前跑一半的任务还接不接得上。

主线 32 章,分入门、应用技术、项目实战三个阶段,不要求先学完 Pi,两套是独立的:

  • 刚学编程:从虚构的"海棠工作室"的来信和活动记录写起,做一个能读文件、调模型、存结果的命令行小程序。

  • 已经会写脚本:直接进检索、工具调用、运行状态这些实验。

  • 做过 AI 应用:从带出处的研究报告开工。

  • 熟 TypeScript、Go 或 Rust:有对应的实践路线。


上一套的验收题是刚好 50 块的订单,下一套也备了几道容易翻车的题,住宿报销就是头一道。老规矩,先做最小的一版,看它怎么答、怎么错。手里攥着一组能反复跑的题,下一步该改提示还是补检索,跑一遍就知道,不用坐在那儿冥想。

Pi 那套链接在开头,练习跑不起来,issue 区见。

soon 回见!👋

参考资料与相关链接

[1] vadxq/pi-agent-practice:https://github.com/vadxq/pi-agent-practice