Pi

Pi Coding Agent：从一次真实任务开始

Pi 把自己定义为一个 minimal agent harness。这里的“minimal”不是功能简陋，而是尽量把稳定内核与工作流偏好分开：模型调用、Agent Loop、工具和 Session 由运行时负责；Skill、Extension 与 Package 负责按需定制。

学习 Pi 最容易走偏的方式，是先收集插件和配置，再试图从功能列表反推架构。本模块采用相反顺序：先跑通一条可观察的工具闭环，再沿 Provider、扩展、MCP、安全、生态和 Session 逐层拆解。

事实基线：2026-08-24，官方仓库 badlogic/pi-mono commit a470b121。Pi 迭代很快，安装命令和 API 以 官方 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=[email protected] \
  commit -m "baseline"
pi

第一次启动时使用 /login 选择 Provider，然后给 Pi 一个边界清楚的任务：

读取 README.md，增加一句项目说明。修改后检查 git diff，
不要提交，不要访问仓库外的文件，也不要执行任何发布操作。

退出后不要只看 Pi 的最终回答，要检查环境事实：

git diff --check
git diff
git status --short

这次练习至少应让你看到四件事：模型提出工具调用，运行时执行工具，工具结果回到下一轮模型请求，最终文件状态由 Git 而不是模型自述证明。

模块主线

本模块保留旧版“轻内核的收益与代价”主线，并加入《动手学 Pi》的实践方法。每篇文章都回答四个问题：

1. 这个部件在完整运行链中负责什么？
2. 输入、输出和失败终态是什么？
3. 当前官方实现把职责放在哪个包或源码目录？
4. 读者怎样用一个小实验验证，而不是只相信文字？

阅读顺序

1. Pi 是什么：定位、架构与 Agent Loop
2. pi-ai：统一多 Provider 的适配层设计
3. 扩展体系：Skill、Extension 与 Package
4. Pi 为什么不内置 MCP：Adapter 与 Token 取舍
5. 安全模型：Project Trust、权限门禁与系统隔离
6. 生态使用：发现、审计与退出策略
7. Pi vs Claude Code vs DSH：按约束选择 Harness
8. Session Runtime：树形历史、恢复与 Compaction

每篇文章的学习产物

只保留这些入口

官方事实源

• Pi 官网：安装、更新、核心定位和文档入口。
• Skills：SKILL.md、发现目录、渐进披露和显式调用。
• Extensions：工具、命令、事件拦截、UI 和运行时状态。
• Pi Packages：pi install、包结构、作用域和更新。
• Package 市场：发现候选包，不能替代源码审计。
• 官方源码：类型、示例、安全边界和行为的最终依据。

学习与辅助入口

• 《动手学 Pi》：沿 15 个 checkpoint 手写 Pi-style Agent，适合补 Agent Loop、Session 和 Eval 的实践理解。
• Pi 中文文档：用于快速阅读；与官方 latest 冲突时以后者为准。
• awesome-pi-agent：历史社区目录。该仓库已于 2026-06-03 归档，只用于发现旧项目，不用于判断当前兼容性。

四条选择规则

• 团队流程、检查清单和领域知识：先写 Skill。
• 新增工具、命令、事件拦截或 UI：写 Extension。
• 分发 Extension、Skill、Prompt Template 或 Theme：做 Package。
• 已有 MCP Server 需要跨宿主复用：再引入 MCP Adapter。

收藏本身不会提升 Agent 工程能力。完成一次 diff、一次失败实验、一次 Session 恢复和一次安全拦截，才算把资料变成可复用经验。