Pi Agent Harness：介绍、本地部署与最佳实践

这里的 Pi 不是 Physical Intelligence，也不是聊天机器人 Pi，而是开源的 Pi Agent Harness：面向终端的编码 Agent 框架与 CLI。仓库在 earendil-works/pi。它的核心定位很清楚——极简但高度可扩展，让你用 TypeScript 扩展工具、命令、模型、UI、Skills、Prompt Templates 和主题。

如果你想要「开箱即用的 IDE 体验」，Cursor 更直接；如果你想要「可编程的本地 Agent Harness」，Pi 更有意思。

Pi 是什么

Pi 是 monorepo，主要包包括：

| 包 | 作用 | | --- | --- | | @earendil-works/pi-coding-agent | 终端交互式 Coding Agent CLI（pi） | | @earendil-works/pi-agent-core | Agent runtime：工具调用、状态、会话 | | @earendil-works/pi-ai | 多模型 / 多供应商统一 LLM API | | @earendil-works/pi-tui | 终端 UI 库，支持差分渲染 |

默认给模型的四个主工具：read、write、edit、bash。可选只读工具：grep、find、ls。

这套默认工具面本身就是 harness 哲学：先给模型够用的文件系统与 shell，再靠扩展层接 MCP、权限策略、plan mode 或子 agent。对 工具调用（tool use） 来说，少而清晰往往比堆 40 个工具更稳。

和 Claude Code / Codex / Cursor 的区别

Pi 的取向是 harness-first / extensibility-first，不是大而全：

  1. 极简核心 —— 不把 plan mode、sub-agent、MCP、权限弹窗、todo 直接内置进核心。
  2. 高度可扩展 —— TypeScript extensions 可加自定义工具、slash command、Provider、权限策略、UI、plan mode / sub-agent / MCP。
  3. 终端优先 —— 交互式 TUI 是主体验；也支持 print、JSON、RPC、SDK。
  4. 会话树 / 分支 —— 会话以 JSONL 保存，支持 /tree、/fork、/clone。
  5. 供应链安全意识 —— 官方建议 --ignore-scripts 安装，依赖锁版本，发布包带 shrinkwrap。

本地部署

1
git clone https://github.com/earendil-works/pi pi
2
cd pi
3
npm install --ignore-scripts
4
npm run build

验证：

1
./pi-test.sh --help
2
PI_OFFLINE=1 ./pi-test.sh --version

也可以全局安装 CLI：

1
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

推荐启动方式

交互模式

1
./pi-test.sh
2
# 或已安装的 pi
3
pi

一次性 / 非交互

1
pi -p "Summarize this repository"
2
cat README.md | pi -p "Summarize this"
3
pi @README.md "Summarize this file"

只读审查

降低误改风险时，只开放只读工具：

1
pi --tools read,grep,find,ls -p "Review this codebase and list risks"

离线启动

1
PI_OFFLINE=1 pi
2
# 或
3
pi --offline

模型与认证

两类认证：

  1. 订阅 / OAuth：交互界面里 /login，支持 Claude Pro/Max、ChatGPT Plus/Pro / Codex、GitHub Copilot。凭据落在 ~/.pi/agent/auth.json。
  2. API Key：环境变量或 /login 写入 auth 文件。

常用环境变量：

| Provider | 环境变量 | | --- | --- | | Anthropic | ANTHROPIC_API_KEY | | OpenAI | OPENAI_API_KEY | | Google Gemini | GEMINI_API_KEY | | DeepSeek | DEEPSEEK_API_KEY | | OpenRouter | OPENROUTER_API_KEY | | Moonshot | MOONSHOT_API_KEY |

国内网络可优先 DeepSeek / Moonshot / Kimi / MiniMax / OpenRouter 等可访问供应商。密钥只放环境变量或 auth.json，不要写进仓库。

配置位置

全局：

1
~/.pi/agent/
2
  auth.json
3
  settings.json
4
  sessions/
5
  AGENTS.md
6
  SYSTEM.md
7
  APPEND_SYSTEM.md
8
  extensions/
9
  skills/
10
  prompts/
11
  themes/

项目级：

1
.pi/settings.json
2
.pi/extensions/
3
.pi/skills/
4
.pi/prompts/
5
.pi/themes/
6
AGENTS.md
7
CLAUDE.md

常用 slash command

| 命令 | 用途 | | --- | --- | | /login | 登录 Provider 或保存 API key | | /model | 切换模型 | | /settings | thinking、主题、消息投递等 | | /resume / /new / /session | 会话管理 | | /tree / /fork / /clone | 会话树分支 | | /compact | 手动压缩上下文 | | /export / /share | 导出 / 分享 | | /reload | 重载配置、扩展、skills、prompts | | /quit | 退出 |

最佳实践

1. 把它当 Harness，不是聊天框

适合：仓库理解、代码审查、小重构、补测试、写文档、脚手架、通过 extensions 接内部工具。

不建议一上来：大范围重写生产代码、未审查地跑迁移、未限权操作重要目录、在没有 git checkpoint 的目录里批量改文件。

2. 先只读，再放权

1
pi --tools read,grep,find,ls   # 探索与计划
2
pi                             # 同意方案后再编辑

3. 每个项目写 AGENTS.md

1
# Project Instructions
2


3
- Package manager: pnpm
4
- Before code changes, explain the plan.
5
- After code changes, run the project check command.
6
- Do not run database migrations locally.
7
- Do not modify generated files directly.
8
- Keep responses concise.

Pi 会加载父目录到当前目录中的 AGENTS.md 或 CLAUDE.md。

4. 对破坏性动作设边界

Pi 默认没有内置权限弹窗，所以要：

  • 在 git worktree 或临时分支中跑
  • 修改前保证 git status 干净
  • 审查任务用只读工具集
  • 在 AGENTS.md 明确禁止生产目录、密钥路径、数据库脚本
  • 必要时容器 / sandbox

若你需要硬性的「按阶段解锁工具」，可把 Pi 与状态机护栏（如 statewright）叠用：Pi 负责扩展与会话，状态机负责每个 phase 的 allowed tools。

5. 用会话树做多方案比较

/tree、/fork、/clone、/compact 适合复杂任务。例如：

  1. 分支 A：最小修复
  2. 分支 B：结构性重构
  3. 分支 C：只写测试验证问题

6. 非交互模式做自动化

1
pi --tools read,grep,find,ls -p "Review this diff for bugs"
2
pi --mode json
3
pi --mode rpc

7. Extensions 先审代码再装

Pi packages / extensions 可执行任意本地代码。装第三方前：看源码、固定版本、优先装到项目本地（pi install <source> -l），不要盲装不可信扩展。

8. Skills 与 Prompt Templates

Pi 的 skills 目录（全局 ~/.pi/agent/skills/ 或项目 .pi/skills/）适合沉淀「可重复的领域流程」，而不是把一长段说明塞进每次会话。写法上可借鉴生产级 Agent Skills 经验：description 写「何时加载」，body 写 gotchas 与目标，重文档放旁路文件。

Prompt templates 则适合固定开场（审查 diff、写 changelog、只读架构导览）。两者都要版本化进仓库，避免每人一份口头习惯。

9. 日常工作流

1
cd /path/to/project
2
git status
3
pi --tools read,grep,find,ls   # 理解项目、找问题、给计划
4
pi                             # 同意后编辑
5
# 跑项目检查命令
6
git diff                       # 人类审查后再提交

Oh My Pi / OMP 补充

oh-my-pi 是 Pi 的 batteries-included fork，命令叫 omp。配置目录通常在 ~/.omp/agent/（如 config.yml、models.yml）。适合作为带主题、角色模型、更多默认能力的日常入口。

配置 OpenAI-compatible 中转时，只写 baseURL、api 形态与兼容字段（如 max tokens 字段名、是否支持 developer role），密钥走环境变量或本地 auth 文件，不要写进笔记或 git。模型角色可拆成 default / plan / smol / vision，让轻任务与重分析走不同档位。

主题可按深浅色切换（如 Tokyo Night、Catppuccin、Nord、GitHub Dark 等）。进入后第一句话建议强制只读：

1
请先阅读 AGENTS.md、package.json 和 README，概括架构、启动入口、主要包，以及本地如何开发和测试。先不要改文件。

准备改代码时：

1
先给我修改计划，等我确认后再改。改完后运行相关测试或 build，并说明改了哪些文件。

何时选 Pi，何时不选

更适合 Pi： 你想掌控 harness 扩展面；需要会话树 / fork 做方案对比；要在终端里接内部工具与自定义 provider；愿意写 AGENTS.md 与本地 skills 来约束行为。

更适合其它产品： 你要强 IDE 集成与默认权限 UX（Cursor 等）；要官方托管的完整 coding agent 体验且不想维护扩展；团队统一策略已锁定在某一 CLI。

无论选谁，原则相同：先只读、再放权；先计划、再改文件；先人类审查 diff，再提交。Pi 只是把这些原则变成可脚本化的默认姿势。

下一步

  1. 选认证：/login 或设置 API key。
  2. 在常用项目加 AGENTS.md。
  3. 先用只读模式做一次代码审查，熟悉 Coding Agent 的行为边界。
  4. 若任务重复出现，抽成 skill 或 prompt template，而不是每次重打提示词。

Liked this note? Share it on Twitter / X, or browse more writing from the home page. Feedback and pointers welcome via @qianyuhe.

Thanks for reading.

– 千羽鹤