智能体的本质与 Pi Agent 笔记

“如果你不能用 300 行代码构建一个 coding agent，说明你最多只是个初级工程师。”

因为，你还没有真正理解智能体的底层原理。

<10%真正理解本质的人

300 行极简 agent 代码量

3 层Pi 的核心包结构

01Pi 的三种用法

当成 coding agent 用可作为 Claude Code 的替代品，社区很受欢迎，能自己拓展功能，玩法很多。

当成学习样本开源的生产级 agent，比知名项目更容易入门，学它怎么写。

当成开发基座基于它构建你自己的智能体，例如数据 Agent，非常好上手。

02上手：安装与配置

01到官网，按你的平台执行对应的安装命令。

02进入用户目录下的点 Pi 文件夹 → agent → 新建 models.json，写入你的模型配置。

03注意：使用 coding plan 前先确认是否支持 Pi。

04在项目文件夹命令行输入 Pi 回车启动，用 /model 切换模型。

03极简哲学与扩展生态

默认什么都不给

崇尚极简，常见的多智能体、计划模式统统没有。Pi 认为这些都是非必要的——需要什么，自己用扩展接入。

skill 提示词模板主题 extension

其中 extension 是代码扩展，可以定制 coding agent 的各种功能，官方收录已有数千个。安装方式：复制命令，直接在命令行运行。

别人是把觉得好的功能塞给你，Pi 是鼓励你按自己的习惯，构建自己的 coding agent。所以它更适合喜欢折腾的人。

04源码三层架构

ai 包 · 管模型调用

市面上模型服务太多，输入输出各不相同，所以做一层统一封装，用一致的方式调用不同模型。

agent 包 · 管循环

只负责维护一个智能体的循环。循环太基础，所以值得单独写一个包。

coding agent 包 · 管业务

编程场景的具体实现：定义工具、定义系统提示词等。三层递进，架构清晰。

05模型的三种使用方式

单轮调用

输入提示词，模型给一段答复，结束。回答你的是模型，不是智能体。

工作流

流程预先定好，何时开始、几步、何时结束都是人设计的。

严格意义上的智能体

不断循环调用模型：模型决定是否调用工具 → 程序执行工具 → 把结果送回模型 → 模型再决定下一步，直到它不再需要工具，给出最终答复。

两个特点：一是多轮调用而非单轮；二是中间经历什么流程、什么时候结束，由模型决定，而不是人预设。

06一个极简 coding agent 的骨架

A定义要使用的模型（主流模型基本都能填）。

B定义三个工具：读取文件、列出目录、编辑文件，都是标准库函数即可实现。

C编写工具的 schema 说明——没有它，模型不知道有什么工具、怎么用。

D写一段简洁的系统提示词：人设、有哪些工具、基本做事方法。

E核心：维护一个循环。有工具调用就执行并把结果拼回去，进入下一轮；没有就直接结束。

智能体 = 模型 + 工具 + 循环高大上的智能体背后，就这么朴实无华。

07为什么循环能停下来

这是人类在代码里定义的规则

为什么模型不调用工具，就认为任务完成了？答案在对齐训练阶段：模型学会了要么调用工具，要么给出最终答复。两者都不做，这一轮训练就会得低分。

久而久之，模型学会先调用工具获取充分信息，直到任务完成、可以给出最终答复，才停止调用工具。

知之为知之，不知为不知，是知也。这里的“完成任务”，不一定是解决用户问题——准确回答“不知道”也算。

08可以干预循环的十个节点

TRACE 开始记录时间起点

TRACE 结束算出响应时长

TURN 开始判断已跑多少轮

TURN 结束轮次收尾处理

模型调用前组装上下文

模型调用时流式与重试

模型调用后敏感词检测

工具执行前危险操作拦截

工具执行时进度与终止

工具执行后结果脱敏处理

你输入一个问题到模型给出答复，这是一次 trace；其中每一次模型调用是一个 turn。在这十个节点插入代码，做任何你想做的事——比如超过 100 轮就强制停下，比如在执行前按住 delete、drop 这类危险指令。

09上下文工程

核心就两句话

该给的信息要给够：完成任务所需的信息尽可能提供，不要跟模型打信息差。

不用给的信息不要给：避免占用上下文、分散模型注意力。

Pi 的做法一：截断工具输出

有些工具返回很长，可能一下子把上下文撑爆。于是截断后把文本和本地文件路径给模型，由它自己判断要不要读全文。按字符还是按字节截、保留前段还是后段，都要看具体场景。

Pi 的做法二：上下文压缩

为什么压：上下文有限，多轮调用累积很快，超了会报错；而且上下文越长模型越笨，历史信息密度越低。

何时压：设定 token 阈值，结合模型上下文长度判断剩余可用量，低于阈值就主动压缩。建议在上一轮任务完成后就压，别让用户在下一轮开始时干等。

压成什么样：没有标准答案。可按结构化模板，如用户目标、约束条件、工作流程、关键决策、下一步计划。

怎么用：下次对话时，用压缩结果替换被压缩的那部分上下文，完成重组。

上下文工程的另一个要点：通过合理编排提升缓存命中率。系统提示词怎么分层、什么信息放前放后、如何避免前缀变化——Claude Code 在这块做得很用心。

10工具调用的可靠性

01参数验证：模型把 JSON 序列化成字符串，自动还原；参数类型不符，自动转换。原则是尽量给模型兜底。

02调用前安全检查：是否有危险指令，是否访问了不该访问的文件。

03调用时错误处理：工具执行失败没有结果，就把报错信息当成结果返回给模型。

04调用后结果调整：校验返回结果里有没有敏感信息，要不要脱敏。

工具出错时，基本原则是把错误信息返回给模型，而不是终止循环。给模型继续纠错的机会，agent 才会稳定，也才会看起来更智能。开发时最好针对每个工具预设可能的错误，说清是什么错、怎么处理。

11二次开发：四点必备改动

配置模型设定 url、api key 等参数。企业内网要留意：私有模型接口可能不规范，不支持的参数要单独说明，让 Pi 绕过。

写系统提示词Pi 的系统提示词由五部分组成。开发垂直智能体主要定义基础人设，把默认的 coding agent 人设替换掉，其余路径文件删掉即可。

设计工具先关掉全部内置工具，再用自定义方式配置你自己的工具。用 defineTool 定义名字、描述、参数和具体功能。

覆盖会话存储Pi 默认把会话记录存成文件，想存数据库就接入对应配置，改为自行保存。

关于工具的两个体验细节

工具执行可能要很久：一个参数用来向前端发送进度，避免用户以为程序挂了；另一个参数接收前端停止信号，一层层传入工具，实现调用终止。

12事件订阅：参与者与观察者

可修改行为

可以改变 agent 的行为，比如拦截工具、修改系统提示词。属于“参与者”。

纯观察者

只把数据发给订阅者，不负责后续动作，也不能修改行为。常用于打印信息、记日志。

案例：拦截危险 SQL

订阅工具执行前的事件，收到通知后判断：是不是要执行 SQL？是就做安全校验，不安全就拒绝执行，并把原因反馈给模型。于是“拦截危险语句”这个需求就完成了。

同理，想自定义上下文压缩方式、想在某个位置注入上下文，都可以订阅对应事件。

13行动建议

1先跑起来：选一个靠谱模型，写一段系统提示词，配几个工具，把循环先跑通。

2再根据实际出现的问题，在循环的十个节点上一个个打补丁。

3不要自己闭门造车，摸着已经踩过坑的开源项目过河，效率更高。

4别急着纠结 SDK 用法，在 AI 时代更值得掌握的是机制本身。

开发 agent 有个共识：出 demo 只要一星期，做到上限要一年。

选对模型、写好提示词、配上工具，demo 很容易跑起来；但脱离测试场景真的上线后，各种想到或想不到的坑都会到来。

Pi 以极简著称——它看得上的功能，自然极其重要，非常适合循序渐进地学习。