大话 Pi

Appearance

🐣 小a的练习册

每章末尾都有"课后实验"。老z把它们汇总成一本练习册——光读不练假把式,动手才真懂。 按难度分级。

怎么用这本练习册 ​

  • 必做 ⭐:理解本质的核心实验,每章至少做一个
  • 进阶 ⭐⭐:加深理解,需要点探索
  • 挑战 ⭐⭐⭐:综合应用,可能跨多章

Part I 概念篇实验 ​

第 1 章 · LLM 原理 ​

  • ⭐ 数 token:用 tokenizer 工具,数一段代码的 token 数,感受"代码比想的费 token"
  • ⭐ 感受幻觉:问模型一个你编的不存在的 API,看它会不会一本正经编
  • ⭐⭐ 调温度:同 prompt 用 temperature 0 和 1 各跑 3 次,对比稳定性

第 2 章 · 思考强度 ​

  • ⭐ 感受思维链:问一道数学题,先不让展示过程再让展示,对比准确率
  • ⭐⭐ 调思考强度:同题跑 off/medium/high,观察准确率/耗时/token
  • ⭐ 观察 Stop Reason:看一次原始响应的 stop_reason 字段

第 3 章 · 统一 AI 库 ​

  • ⭐ 数厂商:数 pi 的 providers 目录,挑一个没听过的厂商读配置
  • ⭐⭐ System Prompt 威力:同模型加/不加海盗人设,对比回答
  • ⭐ 体验流式:观察文字一个个蹦出,试着中途打断

第 4 章 · System Prompt ​

  • ⭐ 体验人设威力:用同一模型,分别用"编程助手"和"海盗"两种 System Prompt,对比回答
  • ⭐⭐ 写一份:为你的 Agent 写一份 System Prompt,包含角色/能力/规则/边界四块
  • ⭐ 观察工程化:看一个真实 Agent 工具怎么动态拼装人设

第 5 章 · Function Calling ​

  • ⭐ 看真实 ToolCall:定义 get_weather,问天气,观察返回的 ToolCall
  • ⭐⭐ 感受 partial JSON:脚本逐字符喂 JSON,看何时能解析
  • ⭐⭐ 诱导不调工具:给工具但问模型能答的,看它用不用

第 6 章 · Tool 与工具设计 ​

  • ⭐ 评价工具描述:找两个真实工具(read/bash)的描述,评价是否符合"用途/边界/参数"三要点
  • ⭐⭐ 写一个工具:为你的项目写一个 ls 工具,注意描述和 schema 怎么写才好
  • ⭐ 体验失败可读:对比模糊错误 vs 清晰错误,体会模型"自我纠正"的差异
  • ⭐⭐ 判断工具化:一个能力(实时信息/确定性计算/静态知识)该做成工具还是塞 prompt

第 7 章 · Agent 循环 ​

  • ⭐ 画消息流:让 agent 做多步任务("读 X 文件,告诉我有多少行"),还原消息角色流转
  • ⭐ 观察 Stop Reason 作用:看模型何时 toolUse 何时 stop
  • ⭐⭐ 测循环边界:把最大轮数设成 1,看 agent 会不会"没干完就被停"
  • ⭐⭐ 走查真实循环:跑一个 2-3 步任务,抄下每轮 toolCall/toolResult,数数烧了几次调用

第 8 章 · 记忆与上下文 ​

  • ⭐⭐ 感受记忆膨胀:连续做几个任务,观察对话历史越来越长
  • ⭐⭐ 比较三种策略:窗口满了,截断 vs 摘要,哪个让模型更"忘事"?验证一下
  • ⭐⭐ 做持久化:给 Agent 加 JSONL 存盘,关闭重开,问"我们之前聊了啥"
  • ⭐ 设计长期记忆:把用户偏好拼进 system prompt 前缀,对比不拼时 KV 缓存与效果差异

第 9 章 · Hooks ​

  • ⭐⭐ 设计拦截:为 Agent 设计一个 beforeToolCall,拦截 bash 里的危险命令
  • ⭐ 体会 fail loud:对比"被拦截后模型收到错误提示" vs "被静默忽略"的行为差异
  • ⭐ 画 Hook 位置图:在循环图上标出 before/afterToolCall、轮次边界、调 LLM 前
  • ⭐⭐ 区分两种介入:为同一节点分别写"拦截式"(改结果)和"订阅式"(记日志)的 hook

第 10 章 · MCP ​

  • ⭐ 画 MCP 关系图:标出 Server/Client/Agent 三者关系
  • ⭐ 找 MCP Server:搜索流行的 MCP Server(文件/数据库/浏览器),看它们暴露什么工具
  • ⭐⭐ 判断适用性:你的场景该用 MCP 还是自带工具,为什么
  • ⭐⭐ 分辨原语:挑一个 MCP Server,判断它暴露的是 Tools、Resources 还是 Prompts
  • ⭐ 安全审查:浏览一个 MCP Server 的权限声明,评估"敢不敢让它连我的文件系统"

第 11 章 · Skill ​

  • ⭐ 读 pi skill:打开 .pi/skills/,读一个技能文件
  • ⭐⭐ 设计一个 skill:为你的 Agent 设计一个技能(如"代码 review"),列出工具/提示词/步骤
  • ⭐⭐ 对比扩展方式:一个能力该用 prompt/skill/extension 哪个
  • ⭐ 体验触发:抛一个命中技能描述的任务,看它是否主动加载那套流程
  • ⭐⭐ 找软约束边界:试想"发布前先跑全量测试"只写在 skill 里,模型会不会跳过?该用哪种硬约束兜底

第 12 章 · 多 Agent ​

  • ⭐ 判断场景:三个任务该用单/多 agent,说理由
  • ⭐⭐ 体会协调难:列团队协作的常见问题,感受多 Agent 同样面对
  • ⭐ 画协议图:MCP/ACP/A2A 各连接什么

第 13 章 · RAG ​

  • ⭐ 感受幻觉 vs RAG:问模型编造 API,再给真实文档,对比准确率
  • ⭐⭐ 设计切块:拿一篇长文档,想怎么切块检索效果最好
  • ⭐ 判断场景:技术问答/代码修改/客服,哪些该用 RAG

第 14 章 · Workflow vs Graph ​

  • ⭐ 判断范式:三个场景该用 Loop/Workflow/Graph
  • ⭐⭐ 画 Graph:把一个"电商下单"流程画成图(节点+条件分支)
  • ⭐ 对比体验:同一任务用 Workflow 和 Loop 实现,对比可控性和灵活性

第 15 章 · 安全与沙箱 ​

  • ⭐ 认识注入:让模型读一个含"忽略指令"的文件,观察它会不会被骗
  • ⭐⭐ 设计信任模型:为你的 Agent 画一张信任分层表(自由/确认/只读)
  • ⭐ 选沙箱:如果让 Agent 跑不可信 npm 包,你会用哪层沙箱?为什么?

Part II 源码篇实验 ​

第 16 章 · 总览 ​

  • ⭐ 数包:克隆 pi,数 package.json,找第 9 个包
  • ⭐ 画依赖图:根据依赖表画箭头图
  • ⭐ 理解 monorepo:找 workspaces 配置和 tsconfig 的 paths 映射(注意:pi 用 paths,不是 references)

第 17 章 · pi-ai ​

  • ⭐ 读 provider:读一个厂商配置,对照 DeepSeek
  • ⭐ 找责任链:anthropic.ts 的 resolve 试几条路
  • ⭐⭐ 数 Compat:types.ts 里有多少厂商兼容接口

第 18 章 · agent-core ​

  • ⭐⭐ 读 runAgentLoop:顺读到双层 while,画控制流
  • ⭐ 找观察者:agent.ts 的 subscribe/listeners
  • ⭐⭐ 理解 fork:读 fork.ts 注释

第 19 章 · tui ​

  • ⭐ 看同步输出:找 \x1b[?2026h/l 的成对使用
  • ⭐⭐ 感受差分:想自己实现要维护什么状态
  • ⭐ 试终端能力:跑 echo $TERM

第 20 章 · coding-agent ​

  • ⭐ 看 system-prompt:读它怎么构建 pi 人格
  • ⭐ 数配置层:找用户级/项目级配置文件
  • ⭐⭐ 试三种模式:pi / pi -p / 想象 RPC

第 21 章 · protocol ​

  • ⭐⭐ 读 encodeFrame:理解 4 字节大端拆分
  • ⭐ 理解大端序:查资料搞懂大小端
  • ⭐⭐ 体会 snapshot/progress:只有 progress 会怎样

第 22 章 · server/client ​

  • ⭐ 读 PiServer:看两大组件怎么组合
  • ⭐⭐ 理解 attach:读 attach 逻辑
  • ⭐⭐ 画 C/S 时序图

第 23 章 · evals ​

  • ⭐ 读一个 eval:看任务定义和评判
  • ⭐⭐ 理解 LLM-as-judge:想优缺点
  • ⭐ 体会回归守护:改了代码该跑什么

Part III 实现篇实验(造你自己的 Agent) ​

第 24 章 · 开张 ​

  • ⭐ 回答六问:为你的 Agent 写需求文档
  • ⭐ 判断范式:确认用 Loop/Workflow/Graph
  • ⭐ 建项目骨架:npm init,装 TypeScript

第 25 章 · LLM 调用 ​

  • ⭐⭐ 跑通 streamText:写 llm.ts,跑"介绍你自己"
  • ⭐⭐ 看请求 body:console.log 发出的请求
  • ⭐⭐⭐ 换厂商:改成 OpenAI(改 URL/headers/body/事件解析)

第 26 章 · 循环(核心) ​

  • ⭐⭐⭐ 写出 runAgent:照着 26.2 实现
  • ⭐⭐ 测纯对话:不传工具跑通
  • ⭐ 感受 maxTurns:设成 1 看会怎样

第 27 章 · 工具 ​

  • ⭐⭐ 实现三个工具:read/write/bash
  • ⭐⭐ 让 Agent 干活:读 package.json 报依赖
  • ⭐⭐⭐ 加 ls 工具:自己实现列目录

第 28 章 · 上下文会话 ​

  • ⭐⭐ 实现 session.ts:加载/保存
  • ⭐⭐ 测持久化:关了再开能恢复
  • ⭐⭐ 触发裁剪:MAX_MESSAGES=5 聊 10 轮

第 29 章 · 交互 ​

  • ⭐⭐ 写出 cli.ts:跑起来对话
  • ⭐ 体验局限:聊 10 轮感受行输出
  • ⭐ 管道测试:echo | tsx cli.ts

第 30 章 · 安全 ​

  • ⭐⭐ 加安全检查:白/黑名单
  • ⭐⭐ 测注入防御:让它读私钥,看拒绝
  • ⭐⭐ 测危险确认:rm -rf 看问不问

第 31 章 · 长大 ​

  • ⭐ 审视需求:列想长的方向,用三问过滤
  • ⭐⭐⭐ 试加 Provider:改成 Provider 接口
  • ⭐⭐ 体会 pi 克制:对比 pi 没做什么

第 32 章 · 收官 ​

  • ⭐⭐⭐ 完成你的 Agent:拼起来跑通
  • ⭐⭐⭐ 让它干真活:改 bug/写代码
  • ⭐⭐ 回头看 pi:用新眼光读 agent-loop.ts
  • ⭐ 决定下一步:做第一个架构决策

实验统计 ​

  • 必做 ⭐:~30 个
  • 进阶 ⭐⭐:~25 个
  • 挑战 ⭐⭐⭐:~10 个
  • 总计:~65 个实验

建议:至少完成所有 ⭐ 必做(约 30 个),你的理解会从"听过"变成"会做"。

🧙 老z的忠告:"看十遍不如做一遍。 实验里卡住了,正好是学习机会——卡住的地方,就是你不真的懂的地方。"