LearnPi

入门

课程地图

这门课在讲什么

agent = LLM + tool use（核心循环的最小闭环，不是 Agent 系统的能力全集）。模型提供语言、推理、"下一步调用哪个工具"的决策，并因此在循环内自主承担 Planning；Memory 则由 harness 拆成消息数组、会话与压缩三件机制，与工具、权限、上下文一样，都是包住模型的 harness 的职责。本课程以 Pi 为蓝本，每一章围绕一个大主题，讲清"是什么 / 怎么做 / 为什么"，重点介绍 Pi 的核心设计。

  • 固定基线：Pi 0.85.1 @ d981de1229ef899957bbe968bc8dcda02a21f477，任何 API 细节以该版本源码和官方文档（pi.dev）为准。
  • 双重对照：每章配有可运行的 Python 教学模型（标准库、离线、确定），以及 Tau（Pi 的 Python 对照实现）的真实代码。
  • 工程化验证：131 个单元测试 + 课程契约检查 + 链接检查，全部离线可复现。

章节总览

  • 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

阶段一 · 架构与核心机制

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

01

架构总览

Pi 的分层与核心设计：agent = LLM + tool use 最小闭环，Planning 与 Memory 各由谁承担，模型无关的核心、产品环境、前端如何通过事件契约解耦。

 02

Agent Loop

循环如何驱动模型工作：模型决定、harness 执行；Trace 与 Turn 的区别；stopReason 与终止条件。

 03

工具系统

工具如何被声明、注册与约束：schema + executor、注册表分发、软约束与硬闸门、bash 特权工具。

 04

消息与记忆

对话历史如何组织与传递：role 判别、工具成对回填、两类记忆的分工。

 04b

系统提示词

每轮请求的第一个决定：五段拼装、customPrompt 与默认路径的差别、三级回退链。

阶段二 · 状态与边界

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

05

会话管理

对话如何存储、恢复与分叉：JSONL v3、append-only 的树、认父不认子、分支是回退的自然结果。

 06

事件驱动与扩展

事件即契约：两条监听通道的分水岭、扩展如何按需注入能力、社区扩展生态。

 07

上下文压缩

有限窗口如何装下无限对话：两层防护、压缩不是丢消息而是让模型总结它自己、成对不拆。

阶段三 · 集成与实践

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

08

Provider 与模型

一行代码驾驭多个模型：元数据、协议、认证三者分离，models.json 的结构。

 09

可靠性

失败如何重试与隔离：先分类再重试、指数退避必封顶、错误信息脱敏。

 10

协议与集成

SDK、RPC 与 JSONL 边界：stdout 是协议、增量分帧处理粘包/半包、方法白名单。

 11

实战与评测

四个离线 mini-project 训练可迁移的 Agent 工程边界，测试与评测构成同一条质量链。

附录

附

术语表

课程涉及的关键术语：Pi 基线、当前 Pi 行为、Python 教学模型、主章节。

 附

核心代码导览

九个核心机制的精选片段与逐段解读：循环、权限、会话树、压缩、事件、分帧、重试、提示词、注册表。

 附

Pi 源码映射

固定基线（0.85.1）、源码入口与常见误解对照，每个断言都能回溯到具体位置。

学习目标

  • 了解课程以哪个 Pi 版本为准，以及如何查找相应的源码说明。
  • 区分 Pi 的 TypeScript 实现、Tau 的 Python 实现与本课程的离线 Python 教学模型。
  • 使用本仓库的检查脚本验证课程资料。

当前 Pi 行为

Pi 的实际行为以固定版本（0.85.1）的源码为准；课程叙述应链接到 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 重新实现，并补齐认证、权限、取消、日志脱敏与端到端测试。
下一章架构总览