Pi Coding Agent：从一次真实任务开始
Pi 把自己定义为一个 minimal agent harness。这里的“minimal”不是功能简陋，而是尽量把稳定内核与工作流偏好分开：模型调用、Agent Loop、工具和 Session 由运行时负责；Skill、Extension 与 Package 负责按需定制。
学习 Pi 最容易走偏的方式，是先收集插件和配置，再试图从功能列表反推架构。本模块采用相反顺序：先跑通一条可观察的工具闭环，再沿 Provider、扩展、MCP、安全、生态和 Session 逐层拆解。
事实基线：2026-08-24，官方仓库
badlogic/pi-mono（来源地址：https://github.com/badlogic/pi-mono） commita470b121（来源地址：https://github.com/badlogic/pi-mono/tree/a470b121bf683b4c2b9fc0b3a7c807de7e0cfe9c）。Pi 迭代很快，安装命令和 API 以 官方 latest 文档（来源地址：https://pi.dev/docs/latest/） 为准。
先完成一次最小实操
安装 Pi：
npm install -g --ignore-scripts @earendil-works/pi-coding-agent建立一个不会影响真实项目的临时仓库：
pi_lab_dir=$(mktemp -d)
cd "$pi_lab_dir"
git init
printf '# pi-lab\n' > README.md
git add README.md
git -c user.name=pi-lab -c user.email=pi-lab@example.invalid \
commit -m "baseline"
pi第一次启动时使用 /login 选择 Provider，然后给 Pi 一个边界清楚的任务：
读取 README.md，增加一句项目说明。修改后检查 git diff，
不要提交，不要访问仓库外的文件，也不要执行任何发布操作。退出后不要只看 Pi 的最终回答，要检查环境事实：
git diff --check
git diff
git status --short这次练习至少应让你看到四件事：模型提出工具调用，运行时执行工具，工具结果回到下一轮模型请求，最终文件状态由 Git 而不是模型自述证明。
模块主线
本模块保留旧版“轻内核的收益与代价”主线，并加入《动手学 Pi》的实践方法。每篇文章都回答四个问题：
- 这个部件在完整运行链中负责什么？
- 输入、输出和失败终态是什么？
- 当前官方实现把职责放在哪个包或源码目录？
- 读者怎样用一个小实验验证，而不是只相信文字？
阅读顺序
- Pi 是什么：定位、架构与 Agent Loop
- pi-ai：统一多 Provider 的适配层设计
- 扩展体系：Skill、Extension 与 Package
- Pi 为什么不内置 MCP：Adapter 与 Token 取舍
- 安全模型：Project Trust、权限门禁与系统隔离
- 生态使用：发现、审计与退出策略
- Pi vs Claude Code vs DSH：按约束选择 Harness
- Session Runtime：树形历史、恢复与 Compaction
每篇文章的学习产物
| 文章 | 核心问题 | 建议产物 |
|---|---|---|
| 01 定位与架构 | 一次工具往返怎样穿过 Pi 的职责层 | 一份 JSON 事件轨迹 |
| 02 Provider 适配 | 统一消息和流事件后，哪些差异仍会泄漏 | 一张双模型对照表 |
| 03 扩展体系 | 流程知识、运行时代码和分发分别放哪里 | 一个 Skill + 一个 Extension |
| 04 MCP | 何时需要协议互操作，何时 CLI 或 Skill 更简单 | 一次 direct/proxy 对照实验 |
| 05 安全 | trust、审批、沙箱分别防什么 | 一份威胁模型和隔离配置 |
| 06 生态 | “市场可安装”为什么不等于“可以信任” | 一份安装前审计记录 |
| 07 选型 | 如何用同一任务比较三个 Harness | 一张带证据的决策矩阵 |
| 08 Session | 历史、活动分支和模型上下文如何分离 | 一次 resume/tree/compact 记录 |
只保留这些入口
官方事实源
- Pi 官网（来源地址：
https://pi.dev）：安装、更新、核心定位和文档入口。 - Skills（来源地址：
https://pi.dev/docs/latest/skills）：SKILL.md、发现目录、渐进披露和显式调用。 - Extensions（来源地址：
https://pi.dev/docs/latest/extensions）：工具、命令、事件拦截、UI 和运行时状态。 - Pi Packages（来源地址：
https://pi.dev/docs/latest/packages）：pi install、包结构、作用域和更新。 - Package 市场（来源地址：
https://pi.dev/packages）：发现候选包，不能替代源码审计。 - 官方源码（来源地址：
https://github.com/badlogic/pi-mono）：类型、示例、安全边界和行为的最终依据。
学习与辅助入口
- 《动手学 Pi》（来源地址：
https://chasen-liao.github.io/pi-textbook-page/learn/prologue/）：沿 15 个 checkpoint 手写 Pi-style Agent，适合补 Agent Loop、Session 和 Eval 的实践理解。 - Pi 中文文档（来源地址：
https://pi-doc.com）：用于快速阅读；与官方 latest 冲突时以后者为准。 - awesome-pi-agent（来源地址：
https://github.com/qualisero/awesome-pi-agent）：历史社区目录。该仓库已于 2026-06-03 归档，只用于发现旧项目，不用于判断当前兼容性。
四条选择规则
- 团队流程、检查清单和领域知识：先写 Skill。
- 新增工具、命令、事件拦截或 UI：写 Extension。
- 分发 Extension、Skill、Prompt Template 或 Theme：做 Package。
- 已有 MCP Server 需要跨宿主复用：再引入 MCP Adapter。
收藏本身不会提升 Agent 工程能力。完成一次 diff、一次失败实验、一次 Session 恢复和一次安全拦截，才算把资料变成可复用经验。