pi-explore

Workspace for a Chinese architecture book about pi's packages/agent.

An agent loop, packaged as a library.

The book starts from the code and explains how @earendil-works/pi-agent-core is put together: what it promises, what it refuses, and where the fulcrums are. The whole book tracks pi main at commit cd20a8d2e. Citations use file:line form, each with an inline quotation—so you can verify any claim without opening an editor.

Languages: Chinese is the source of truth under agent/. English and Spanish translations live in agent/en/ and agent/es/. The web reader has a language switcher (中文 / English / Español).

中文说明见下文。

一本中文架构书的工作区。对象是 pi 仓库的 packages/agent。

一个 agent 循环，被做成一个库。

这本书从代码出发，讲清楚 @earendil-works/pi-agent-core 是怎么搭起来的：它承诺什么、拒绝什么、支点在哪里。全书对应 pi 仓库 main 分支的 commit cd20a8d2e。代码引用写成 文件:行号，每个引用就地附上引文——读者不需要打开编辑器，就能核对书里任何一处论断。

多语言： 中文原稿在 agent/（唯一内容源头）。英文与西班牙文译本在 agent/en/ 与 agent/es/。Web 阅读器右上角可切换语言。

阅读方式

读者假设

你会读 TypeScript，知道 LLM API 的基本概念（messages、tool calls、streaming），不需要事先了解 pi 仓库。

组织方式

整体 → 局部 → 横切。

• 第一部分 · 整体（已成稿，review 中）：建立对整个系统的正确认知，不碰实现细节。读完这部分，你应该能凭记忆把这个系统画出来。
• 第二部分 · 局部：逐个部件展开，顺序是依赖顺序——每章只依赖它前面的章。
• 第三部分 · 横切：处理那些不属于任何单一部件的问题。

目录只列已发布的章节，后续章节随写随添。

工作区布局

• agent/ —— 书的原稿（中文），唯一的内容源头。译本在 agent/en/、agent/es/。可见 agent/README.md 与 agent/TRANSLATION.md。

• web/ —— 阅读器（Vite + Vue）。只渲染 agent/ 的原稿，不存放内容。

  cd web && npm install && npm run dev
  

体例

引文规则、三种卡片组件（插叙 / 岔路 / 为什么不去），范围之外，都写在 agent/README.md 的「体例」一节。