语言：中文 | English
一份关于 Pi Agent Harness 的源码阅读笔记、设计拆解和实验手册。
Pi 是一个小而可组合的 coding agent harness。这个仓库试图回答一个问题：
如果要理解、扩展、二开，甚至参与维护一个现代 coding agent，应该从哪些边界看起？
这不是官方文档，也不是完整教程。它更像一份 field guide：把源码里的设计选择拆出来，整理成可阅读、可回看、可实验的文本。
完整文档地图见：docs/README.md。
先读整体，再读边界：
- 核心思想概览
- 架构视觉地图
- 架构总览
- Agent Core
- Coding Agent
- 扩展系统
- 工具执行与安全边界
- Session / Storage
- SQLite Session Backend
- Compaction
- Model Runtime / Auth
- RPC / SDK
- Telemetry
如果你想先用图建立印象，可以从 架构视觉地图 和 文档视觉地图目录 开始。
如果你关心参与上游，可以直接看：
- 核心思想概览 — Pi 的层级关系、核心抽象和设计取向。
- 架构视觉地图 — 用中心运行时、六个边界和对照表快速建立整体心智模型。
- 架构总览 — monorepo 包结构和模块边界。
- Agent Core — agent loop、事件流、tool call 执行模型。
- AI Package — provider、model、streaming 和多模型抽象。
- Coding Agent — 把 agent-core 放进编程场景的产品层。
- TUI Engine — 终端 UI、组件系统和渲染思路。
- 扩展系统 — extension loader、事件、commands、tools、provider 和 UI hook。
- 工具执行与安全边界 —
read/bash/edit/write、hooks、truncation、mutation queue 和 sandbox 取向。 - Session / Storage — JSONL session、entry tree、branch 和 context projection。
- SQLite Session Backend —
node:sqliteadapter、repository、migrations、writer lease、FTS search 和 backend 拆分逻辑。 - Compaction — context compaction、split turn、branch summary 和 checkpoint 思路。
- Model Runtime / Auth —
models.json、auth.json、OAuth、provider composition 和可用模型快照。 - RPC / SDK —
createAgentSession()、JSONL RPC、CBOR 远程会话协议和外部 UI 集成。 - 进程间通信协议 — JSONL 与 CBOR 的取舍、为什么 agent 用事件流、client/server 拆分逻辑。
- Telemetry — vendor-neutral
TelemetryContext/ span schema、no-op / in-memory adapter，以及 agent runtime 的可观测性边界。
- 工程治理 — CI/CD、依赖管理、供应链安全和维护风格。
- 行为评测 — eval harness、真实 AgentSession 和 LLM 行为回归。
- 贡献路线 — issue、PR、
lgtmi/lgtm、以及适合新参与者的切入方式。 - 双语文档策略 — 中文优先、英文逐步稳定、未来 docs site 的结构设想。
docs/— 稳定的主题笔记和参考文档。journal/— 学习过程、临时判断和阶段性复盘。experiments/— 用小实验验证对源码设计的理解。drafts/— 还没整理成文档的想法。.agents/skills/— 仓库自带的 agent 写作/维护规范。
- Keep notes source-grounded.
- Prefer diagrams and small examples over long narration.
- Separate “what the code does” from “my current interpretation”.
- Turn fuzzy understanding into experiments.
- Remove machine-local details before publishing.