pi-learn Agent 教程目录 —— 从 0 到 9 手写你的 Agent

怎么用这份目录

这份教程从 0 开始，每步一个可运行项目，讲透一个概念后再往前。

使用建议 ① 按 0 → 9 顺序学，每步先跑通再读讲解；② 每个 HTML 页面的顶部和底部都有这排导航，随时跳转；③ 代码块可点击按钮展开、也可在浏览器新标签页打开原文；④ Step 4 起的页面有"升级前 / 升级后"对比面板；⑤ Step 8、9 的讲解文档也已就位（task8.html、task9.html），至此 0~9 全部打通。

为什么用简化版学，而不是直接读 pi 源码？ pi 是生产级 monorepo（7 个包、几千个 TS 文件）。先在这里用几十行代码亲手实现每个概念，再对照 pi 的真实模块，你会看到"原来我写的简化版就是它的骨架"——这样啃源码才不劝退。

Step 0 ~ 9 · 目录

0 从这里开始学习路径总览、目录导航、与 pi 的对应关系。 index.html 1 最小 LLM 调用环境搭建、协议字段，一句提问 → 一段回复。 agent-tutorial0123.html 2 Agent 主循环 LLM 自己循环思考：多轮消息 + 退出条件。 agent-tutorial0123.html 3 工具调用 tools / tool_calls：让 Agent 能调用你的函数。 agent-tutorial0123.html 4 多 Provider 抽象先写死、后抽象：换配置不换代码。 task4.html 5 交互模式 REPL readline 事件驱动，命令行对话循环。 task5.html 6 对话历史 history 管理 + 截断，/clear 清空。 task6.html 7 技能系统 skills 按需加载，select_skill 动态选工具。 task7.html 8 健壮化错误分层 + 重试退避 + 超时 + 日志（llm.ts 核心改造）。 task8.html 9 流式与发布流式输出（打字机效果）+ 终端颜色 + npm link 全局命令。 task9.html

每步对应 pi 的哪一块

学完一步，可以按这张表去 f:\piagent 里找对应模块精读。

你的步骤	概念	pi 对应模块
1~3	最小调用 / 主循环 / 工具	`packages/ai`（模型抽象）、`packages/agent/src/agent-loop.ts`（主循环）
4	多 Provider 抽象	`packages/ai`（provider / models 抽象）
5	交互模式 REPL	`packages/tui`（终端 UI：input / editor / keybindings）
6	对话历史 + 截断	`packages/agent/src/agent-loop.ts`（消息循环 + compaction）
7	技能按需加载	`packages/agent/src/harness/skills.ts`（skill 机制）
8	健壮化（重试 / 超时 / 错误分层）	`packages/ai`（fetchWithRetry / 错误分层）
9	TUI 与发布（流式 / 颜色 / bin）	`packages/tui`（tui-render / streams）