README.md
README.md
Pi Agent Book
基于 Astro 5 + React 19 + MDX 的源码精读电子书,系统性拆解 Pi Agent SDK 的架构与实现。
10 个章节(ch01~ch10)覆盖:开篇总览、三层架构、Agent Loop、模型调用、工具系统、消息系统、事件驱动、上下文工程、上下文压缩、会话管理。TypeScript + Python 双版本齐全(20 个 mdx 文件),顶栏一键切换。为什么有 Python 版:Pi Agent 原作是 TypeScript,转写版方便只熟悉 Python 的读者聚焦设计本身。
快速开始
# 安装依赖(首次)
npm install
# 开发模式(热重载,http://localhost:4321)
npm run dev
# 生产构建(输出到 dist/)
npm run build
# 预览构建产物(http://localhost:4321)
npm run preview
环境要求:Node.js ≥ 18,任意现代浏览器。
读者使用指南
只想看文档不关心开发?两种方式:
方式一:本地起站点(推荐,离线可用)
npm install && npm run dev
# 浏览器打开 http://localhost:4321
方式二:直接读源 md 文件
源文档(Markdown 原稿,无需构建)在仓库的 ../docs/ 目录:
- TS 版原稿:
../docs/typescript/ - Python 版原稿:
../docs/python/
阅读界面操作
| 操作 | 效果 |
|---|---|
| 顶栏 TS / Python 切换器 | 同一章在两种语言间跳转,偏好记到 localStorage,下次自动应用 |
| 顶栏 ☀ / 🌙 按钮 | 浅色/深色/跟随系统三态循环,T 键快捷键 |
顶栏 ◧ 沉浸式阅读 按钮 / F 键 |
进入沉浸模式:右栏大纲淡出、正文加宽到 1080px,留出充分阅读空间。进入/退出都有平滑动画。仅 ≥1280px 可用,偏好记 localStorage |
沉浸模式下 Esc 键 |
退出沉浸模式 |
| 左侧 TOC | 章节层级导航(hover 显示模块号 M01-M10) |
| 右侧 On-This-Page | 当前页面的二级/三级标题大纲,滚动时高亮当前节(沉浸模式下淡出隐藏) |
| 点击 SVG 图内节点 | 自动跳转到对应代码块并高亮(Ch3 Agent Loop 已布好锚点) |
| 点击图片 | 放大查看,Esc 或滚轮缩放退出 |
| 底部 ← 上章 / 下章 → | 按 displayOrder 顺序连续阅读(ch01 → ch10 一条主线) |
章节结构
ch01 开篇总览 → ch02 三层架构 → ch03 Agent Loop → ch04 模型调用 → ch05 工具系统
↓
ch06 消息系统 → ch07 事件驱动 → ch08 上下文工程 → ch09 上下文压缩 → ch10 会话管理
主要功能
| 能力 | 说明 |
|---|---|
| 三栏阅读布局 | 左 TOC(240px)/ 正文(720px)/ 右大纲(240px),1279px 以下隐藏右栏,767px 以下转汉堡菜单 |
| 沉浸式阅读模式 | 顶栏 ◧ 沉浸式阅读 按钮或 F 键切换。沉浸模式下:右栏大纲列宽收到 0 并淡出、正文加宽到 1080px、page-max 放宽到 1280px。进入/退出所有属性都用 CSS transition 同步动画(grid-template-columns / max-width / opacity / transform)。仅 ≥1280px 生效,窗口缩小自动退出。支持 prefers-reduced-motion |
| TS/Python 双版本 | 每章并排两个 mdx:chXX-xxx.mdx(TS 版)+ chXX-xxx.python.mdx(Python 改写版)。URL 各自独立(/modules/ch03-agent-loop vs /modules/ch03-agent-loop.python),顶栏 LanguageSwitcher 一键切换,偏好记到 localStorage |
| 代码块增强 | Shiki 语法高亮 + 语言标签 + 一键复制 + 30 行以上自动折叠 |
| SVG 图表联动 | 点击图内节点自动滚动到对应代码块(S2 双向联动);目前已在 Ch5 工具系统五步管道图 实现,其他章节待扩展(Phase 4-C)。点击图片放大查看(lightbox 支持 Esc/滚轮缩放) |
| 交互式 Islands | 3 个 React 组件按需水合:S3 Partial Message 时间线 / S4 错误防线演示(均挂载在 Ch3 Agent Loop)/ S5 首页知识图谱(10 节点新结构) |
| 章节字数/阅读时长 | 详情页 header 与首页"全部章节"卡片都显示 xxxx字 · 含 N 行代码 · 约 M 分钟。collection.ts:getModuleStats() 在构建时读 mdx 源文件实时计算(CJK 按字 + 英文按词,代码块单独算非空行不计入字数,阅读时长 = 字数/300)。改了 mdx 内容自动跟随,无需维护 |
| 主题切换 | 浅色/深色/跟随系统三态,无 FOUC(anti-FOUC 脚本在 <head> 中同步执行),跨标签页同步 + T 键快捷键 |
| 无障碍 | WAI-ARIA tabs 键盘模式(ArrowLeft/Right/Home/End)、:focus-visible 焦点环、prefers-reduced-motion 双层覆盖(CSS @media + JS matchMedia) |
| 设计令牌 | 颜色/字号/间距/圆角/阴影/动效全部走 tokens.css 的 CSS 变量,深色主题独立精调 |
许可
代码采用 MIT License,文档采用 CC-BY-SA-4.0。