入门
课程地图
这门课在讲什么
模型提供思考,外面那层程序提供能力边界——这是全书的核心判断。最小闭环只有两样:模型,和它能调用的工具。经典教材里的"规划"由模型自己在循环里完成;"记忆"被拆成三件具体机制:消息数组、会话文件、上下文压缩。工具、拦截、上下文、事件也都属于外面这层程序。
本课程以 Pi 为蓝本,每一章围绕一个机制,讲清"是什么 / 怎么做 / 为什么",并给出一条能跑的命令。
- 固定基线:Pi 1.4.0,任何 API 细节以该版本源码和官方文档(pi.dev)为准。
- 双重对照:每章配有可运行的 Python 教学模型(标准库、离线、确定),以及 Tau(Pi 的 Python 对照实现)的真实代码。
- 工程化验证:159 个单元测试 + 课程契约检查 + 链接检查,全部离线可复现。
三条读法
这本书不必从头读到尾。按你的目标选一条:
| 你的目标 | 建议路线 | 可以暂时跳过 |
|---|---|---|
| 先跑起来、能改能配 | 03 工具 → 08 服务商 → 09 可靠性 → 10 集成 | 05 / 06 / 07 的实现细节 |
| 想读懂内核 | 01 架构 → 02 循环 → 04 消息 → 05 会话 → 06 事件 → 07 压缩 | 08 的配置字段、10 的协议细节 |
| 要做二次开发 | 01 → 03 → 04b 提示词 → 06 事件 → 10 集成 → 11 评测 → 12/13 扩展面 | — |
每条路线都配着可运行的离线实验:读懂一段,就有一条命令能验证。每章末尾的「自测三问」可以当作"要不要继续往前读"的检查点。
章节总览
00-course-map.md01-architecture/README.md02-agent-loop/README.md03-tools/README.md04-messages-and-memory/README.md04b-system-prompt/README.md05-sessions/README.md06-events-and-extensions/README.md07-context-and-compaction/README.md08-providers-and-models/README.md09-reliability/README.md10-protocol-and-integration/README.md11-projects-and-evaluation/README.md12-scripted-tools-and-mcp/README.md13-storage-and-routing/README.md
阶段一 · 架构与核心机制
先建立整体心智模型:谁在循环里,谁在循环外。
架构总览
外壳与核心的分工:模型 + 工具调用这个最小闭环,规划与记忆各由谁承担,模型无关的核心、产品层、界面如何靠事件解耦。
02Agent Loop
循环如何让模型干活:决策权在模型手上;一次运行与一轮的区别;什么决定继续、什么决定停下。
03工具系统
工具怎么装上去:说明书 + 执行器、注册表分发、"劝"与"拦"两类约束、命令类工具的真实防护边界。
04消息与记忆
模型眼里的历史:每条消息标明来源、调用与结果必须成对、对话记忆与跨会话记忆的分工。
04b系统提示词
每轮请求的第一句话:分段的系统提示词、三种改写强度、人设的三级来源、每轮只发变化的那几段。
阶段二 · 状态与边界
状态存在哪一层?出错了边界在哪?
会话管理
对话怎么存下来、怎么分叉:一行一条记录、只追加的树、只记父节点、上下文编辑为什么不改历史。
06事件驱动与扩展
事件即契约:只观察与能介入两种监听、扩展能注册什么、两个"边界时刻"、几个易错的事件名。
07上下文压缩
窗口装不下时怎么办:输入侧截断与历史侧压缩两层防护、切割点不拆一对、token 估算的锚点。
阶段三 · 集成与实践
把前面所有边界接起来,做成能跑、能测的东西。
Provider 与模型
接一家是配置,接十家是架构:模型清单、请求协议、认证三件事分开;认证的四层来源与虚拟模型。
09可靠性
失败怎么处理:先分类再重试、两层重试的区别、退避必封顶、四种问题不要混为一谈。
10协议与集成
让程序也能用它:四种形态、标准输出即协议、按行分帧的四个边界、什么才算真的结束。
11实战与评测
四个离线小项目训练可迁移的工程边界;测试与评测构成同一条质量链,评测要给提升幅度而不是孤立分数。
阶段四 · 新增设计面
前面十二章讲的是"机制本身"。这两章讲近几个版本在机制外围加的两类可替换点——工具的来源,与状态/模型的落点。
工具的第二条通道
脚本化调用把多次往返压成一次;外部工具服务器把第三方能力接进工具池。两条都不改循环,也都不构成权限提升。
13状态与路由
会话存哪、请求给谁:可替换存储与虚拟模型路由。共同要求是可观测、可回退、可归因。
附录
术语表
课程涉及的关键术语:Pi 基线、当前 Pi 行为、Python 教学模型、主章节。
附核心代码导览
十个核心机制的精选片段与逐段解读:循环、拦截、会话树、压缩、事件、分帧、重试、提示词、服务商,以及 1.x 的两条扩展通道。
附Pi 源码映射
固定基线(1.4.0)、源码入口与常见误解对照,每个断言都能回溯到具体位置。
附产品层功能对照
界面组件、快捷键、主题、模板、扩展包、遥测、非聊天模型:各自挂在哪条机制上,为什么不进正文。
学习目标
- 了解课程以哪个 Pi 版本为准,以及如何查找相应的源码说明。
- 区分 Pi 的 TypeScript 实现、Tau 的 Python 实现与本课程的离线 Python 教学模型。
- 使用本仓库的检查脚本验证课程资料。
当前 Pi 行为
Pi 的实际行为以固定版本(1.4.0)的源码为准;课程叙述应链接到 Pi 源码映射,而不是把示例 Python 当作 Pi 的生产实现。
Python 实验
课程实验位于 learn_pi_lab 包中,且只依赖 Python 标准库。可以先运行:
python3 -m learn_pi_lab
配套资料
- Pi 源码映射 —— 固定基线、源码入口、常见误解与基线事实
- 术语表 —— 关键术语定义
- Tau —— Pi 的 Python 对照实现(tau_agent / tau_ai / tau_coding)
验证方式
在仓库根目录运行以下命令:
python3 scripts/check_course_contract.py
python3 scripts/check_markdown_links.py
两条命令成功时都会输出 OK。
边界与安全
- 本课程 Python 教学模型只依赖标准库:不访问网络、不调用模型、不执行学习者提供的 shell 命令。
- 教学模型 ≠ 生产实现:示例中的固定数据和策略不可直接替代生产配置。
- 迁移到 Pi 时用 TypeScript 重新实现,并补齐认证、权限、取消、日志脱敏与端到端测试。