README.md
README.md
项目原理-二次整理版-插图版-Python版(260703)
基于 项目原理-二次整理版-插图版-260702 的 TypeScript 代码示例,改写为 Python 等价代码,让只懂 Python 的读者也能看懂 Pi-Agent 的设计原理。
为什么有这个版本
Pi-Agent 的官方 SDK 是 TypeScript 包(@earendil-works/pi-ai、pi-agent-core、pi-coding-agent),并没有官方 Python 版本。原教程的代码示例全部是 TS——对只懂 Python 的读者不友好。
这个版本是改写版——保留所有非代码文本(讲解、表格、图片引用、ASCII 框图、JSON 数据示例)一字不变,只把 typescript 代码块改写成等价的 python 代码块。
重要澄清:这些 Python 代码不是"用 Python 调 Pi 的指南",而是用 Python 语法帮你看懂每一处 TS 代码在做什么。Pi 的官方 SDK 仍然是 TS——但当你回到 TS 源码时,会发现概念是一一对应的。
改写规则
- 代码块语言标记:
```typescript→```python - 保留所有非代码文本:标题、讲解、表格、列表、引用块、图片引用、ASCII 框图、bash 命令、json 数据格式——全部原样
- 每个改写代码块顶部加注释头:
# ============================================================ # 【Python 改写】<说明> # 原文 TS: # <对应的 TS 代码原文> # ============================================================ - 概念对照:注释里点明 TS → Python 的语法/概念映射(如
Promise<T>→Coroutine,interface→Protocol/dataclass,switch/case→match/case或if/elif) - 命名转换:camelCase → snake_case(
streamSimple→stream_simple、AgentMessage[]→list[AgentMessage]) - 不修复任何"看似 bug"的原代码:保持原 TS 的控制流和结构
改写风格对照
| TS 概念 | Python 等价 | 备注 |
|---|---|---|
Promise<T> |
Awaitable[T] / Coroutine |
异步等价 |
async/await |
async/await |
Python 同样支持 |
interface |
@dataclass 或 Protocol |
看"运行时实例"还是"鸭子协议" |
联合类型 A | B |
Union[A, B] 或 Literal |
|
泛型 T<X> |
Generic[X] |
|
for await...of |
async for...in |
流式迭代 |
Promise.all([p1,p2]) |
asyncio.gather(c1,c2) |
并发 |
array.filter(p) |
[x for x in arr if p(x)] |
|
array.some(p) |
any(p(x) for x in arr) |
|
array.find(p) |
next((x for x in arr if p(x)), None) |
|
array.unshift(x) |
list.insert(0, x) |
|
array.push(x) |
list.append(x) |
|
array.length |
len(list) |
|
Map.has(k) |
k in dict |
|
Map.get(k) |
dict.get(k) |
|
try/catch |
try/except |
|
instanceof Error |
isinstance(e, Exception) |
|
throw new Error(...) |
raise Exception(...) |
|
| TS 声明合并 | 无 Python 等价 | 用专门注释块解释 TS 的编译期魔法 |
章节清单
本版本与 260702 TS 源版完全对应——10 章一一对齐:
| 章节 | 主题 | TS 代码块数 |
|---|---|---|
| 第1章 | 开篇 · Pi-Agent 框架总览 | 3 |
| 第2章 | 三层架构 · Pi-Agent 项目的骨骼 | 10 |
| 第3章 | Agent Loop · 让模型转动起来的引擎 | 21 |
| 第4章 | 模型调用 · 一行代码驾驭多个模型 | 15 |
| 第5章 | 工具系统 · Agent 的手脚是怎么被管住的 | 13 |
| 第6章 | 消息系统 · Agent 的记忆如何组织与传递 | 10 |
| 第7章 | 事件驱动 · Agent 的神经系统 | 9 |
| 第8章 | 上下文工程 · 让有限窗口装下无限对话 | 2 |
| 第9章 | 上下文压缩 · 当对话太长怎么办 | 5 |
| 第10章 | 会话管理 · 对话的存储恢复与分叉 | 7 |
合计 95 个 TS 代码块全部改写为 Python 等价代码。
注:260702 TS 源版只包含这 10 章。旧 Python 版(260702)里额外的"中场总结 / 扩展系统 / 测试模式 / 设计精华"章节,新 TS 源版没有,本版本也没有。
资源文件
assets/— 完整复制自 TS 源版(260702),所有.svg/.html文件与原版一致_chapter-design/— 章节设计文档,也完整复制
与旧版(260702 Python 版)的差异
- 章节范围:旧版有 13 章(含中场+扩展+测试+设计精华),本版严格对齐 TS 源的 10 章
- 章节 8 新增:旧版第 8 章是"上下文压缩",新版第 8 章是"上下文工程"(全新章节),原"上下文压缩"成为新版第 9 章
- 章节 9/10 重写:新版第 9 章(压缩)和第 10 章(会话管理)内容有大幅修订,所有 Python 代码按最新 TS 源重写
- 风格统一:所有代码块都加了"原文 TS + 概念对照"的注释头,旧版没有这个规范
阅读建议
- 第一次读:只看 Python 代码就能理解 Pi 的运行机制
- 想深入 Pi 源码:回到 TS 源版 或
repo/packages/看实际 TS 实现 - 注意 Python 代码里的
pi_agent_core、pi_ai、pi_coding_agent等 import 是示意性的——这些 Python 包并不存在,Pi 的官方 SDK 只有 TS 版