入门

课程地图

这门课在讲什么

模型提供思考,外面那层程序提供能力边界——这是全书的核心判断。最小闭环只有两样:模型,和它能调用的工具。经典教材里的"规划"由模型自己在循环里完成;"记忆"被拆成三件具体机制:消息数组、会话文件、上下文压缩。工具、拦截、上下文、事件也都属于外面这层程序。

本课程以 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.md
  • 01-architecture/README.md
  • 02-agent-loop/README.md
  • 03-tools/README.md
  • 04-messages-and-memory/README.md
  • 04b-system-prompt/README.md
  • 05-sessions/README.md
  • 06-events-and-extensions/README.md
  • 07-context-and-compaction/README.md
  • 08-providers-and-models/README.md
  • 09-reliability/README.md
  • 10-protocol-and-integration/README.md
  • 11-projects-and-evaluation/README.md
  • 12-scripted-tools-and-mcp/README.md
  • 13-storage-and-routing/README.md

阶段一 · 架构与核心机制

先建立整体心智模型:谁在循环里,谁在循环外。

阶段二 · 状态与边界

状态存在哪一层?出错了边界在哪?

阶段三 · 集成与实践

把前面所有边界接起来,做成能跑、能测的东西。

阶段四 · 新增设计面

前面十二章讲的是"机制本身"。这两章讲近几个版本在机制外围加的两类可替换点——工具的来源,与状态/模型的落点。

附录

学习目标

  • 了解课程以哪个 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 重新实现,并补齐认证、权限、取消、日志脱敏与端到端测试。