Pi：一个极简可扩展的终端编程 Agent 开源项目

1 阅读

Pi 是什么

Pi（全称 Agent Harness）是一个极简风格的开源终端编程 Agent，由 Mario Zechner 开发，也是 OpenClaw 项目的底层 Coding Agent。它的核心理念很直接：不给模型塞一堆预设功能，而是只提供四个基础操作——read（读文件）、write（写文件）、edit（编辑代码）、bash（执行命令），其余能力全部交给用户通过扩展或模型自身推理来实现。

系统提示词控制在 1000 token 以内，没有冗余描述。搜索？让模型自己用 grep 或 find 解决。计划？建议你写个 PLAN.md。子代理？可以用 bash 启动新进程，或者装个社区扩展。这种“少即是多”的设计，让 Pi 的响应速度更快，上下文更干净，也更容易被用户精确控制。

核心功能详解

极简工具集与上下文控制

Pi 默认只暴露四个工具给模型。这意味着模型不能直接调用“搜索整个代码库”或“分析依赖关系图”这类高级功能。但它可以组合基础命令完成任务，比如用 grep -r 查找关键词，或用 find . -name "*.ts" 列出文件。这种设计迫使模型更贴近真实开发环境的行为逻辑，而不是依赖黑盒工具。

上下文管理方面，Pi 支持多种机制：

  • SYSTEM.md：放在项目根目录，可完全覆盖默认系统提示词。
  • AGENTS.md / CLAUDE.md：自动沿目录树向上查找并加载，用于注入项目规范、架构说明等长期上下文。
  • 动态上下文注入：在对话中临时插入关键代码片段或文档。
  • 自动 Compaction：当上下文接近模型窗口上限时，自动摘要早期内容以腾出空间。

Loomy

这些机制让用户能精细控制哪些信息进入模型视野，避免无关噪声污染上下文。

多模型支持与无缝切换

Pi 内置对接了 15+ 模型提供商，包括 Anthropic、OpenAI、DeepSeek、Kimi、智谱、Qwen、MiniMax、MiMo 等，甚至为国产模型单独配置了中国区节点，降低延迟。

更特别的是，你可以在一次会话中途随时切换模型。输入 /model 或按 Ctrl+L，选择另一个厂商的模型，Pi 会自动将当前对话历史转换为目标模型能理解的格式，并继续对话。这意味着你可以先用 Claude 3.5 Sonnet 快速生成草稿，再切到 DeepSeek-Coder 进行深度优化，全程无需中断。

登录方式也灵活：支持 OAuth 订阅登录（如 GitHub 账号绑定 Anthropic）或直接填入 API Key。

树状会话历史

传统聊天界面是线性历史，一旦走错一步，要么重开对话，要么忍受冗长上下文。Pi 采用树状结构存储会话：每次你从某个历史节点重新提问，就会创建一个新分支。所有分支共存于同一个 .pi/session.json 文件中。

用 /tree 命令可以查看整棵树，点击任意节点即可跳回该状态，继续分叉探索不同方案。这对试错型开发特别有用——比如尝试三种不同的 API 设计，每种都保留完整上下文，互不干扰。

扩展与社区生态

Pi 的扩展机制基于 TypeScript。只需将 .ts 文件放入 ~/.pi/agent/extensions/ 目录，运行 /reload 即可热加载。扩展能：

  • 注册新的工具（如数据库查询、Git 操作）
  • 添加自定义命令（如 /test 自动运行单元测试）
  • 拦截事件（如在每次写文件前做格式校验）

更有趣的是，Pi 能现场给自己写扩展。你只需描述需求，它就能生成符合接口的 TypeScript 代码。

社区还发展出 Pi packages 生态：扩展、Skills、主题等可打包发布到 npm 或 Git 仓库。用户通过 pi install npm:@user/my-skill 或 pi install git+https://... 一键安装。

Skills 与 Prompt 模板

Pi 支持 Agent Skills 标准。你只需写一个 Markdown 文件，定义参数和示例，就能变成一个带参数的 / 命令。例如：

# /refactor

将指定函数重构为更简洁的形式。

## 参数
- file: 文件路径
- function: 函数名

## 示例
/refactor src/utils.ts formatName

保存后，/refactor 就成了可用命令。这种机制让非开发者也能贡献实用功能。

四种运行模式

Pi 不只是交互式工具，还支持多种集成方式：

  • TUI 模式：默认的终端交互界面，支持快捷键、图片粘贴（Ctrl+V）、文件模糊搜索（@）。
  • Print/JSON 模式：适合脚本调用，输出纯文本或结构化 JSON。
  • RPC 协议：通过 stdin/stdout 与外部程序通信，可用于 IDE 插件。
  • Node.js SDK：直接在 JavaScript 项目中嵌入 Pi 的核心逻辑。

这使得 Pi 既能用于日常编码，也能集成到 CI/CD 流水线或企业内部工具链。

实际使用流程

安装很简单：

# 方式一：npm
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# 方式二：官方脚本
curl -fsSL https://pi.dev/install.sh | sh

首次启动需配置模型：

pi
/login  # 选择提供商并登录

进入项目目录后再次运行 pi，它会自动加载 AGENTS.md 等配置文件。之后就可以直接用自然语言提需求，比如：

“帮我把 src/api/user.ts 里的 getUser 函数改成 async/await 风格，并添加错误日志。”

过程中可随时：

  • 按 Ctrl+L 切换模型
  • 输入 /tree 查看会话分支
  • 用 !ls -l 执行 shell 命令
  • 用 @config 模糊搜索文件

退出后，下次用 pi -c 可续接上次会话。也可用 /export 导出 HTML 报告，或 /share 生成 GitHub Gist 链接分享完整过程。

与 Claude Code 的对比

Pi 和 Anthropic 的 Claude Code 定位不同：

  • Claude Code 是“开箱即用”的全功能 Agent，内置大量工具、Plan Mode、Sub-agents、MCP 支持，还有权限弹窗确认机制，适合不想折腾的用户。
  • Pi 是“可组装”的 Agent Harness，功能极简，但扩展性强。它不做 Plan Mode，但你可以写 PLAN.md；不内置 MCP，但社区有 pi-mcp-adapter 包；默认 YOLO（You Only Live Once）模式，不弹窗确认——信任用户知道自己在做什么。

会话结构上，Claude Code 是线性的，Pi 是树状的。模型支持上，Claude Code 仅限 Anthropic，Pi 支持 15+ 厂商且可跨厂商切换。

典型应用场景

快速原型与脚本开发

在终端直接说：“写个 Python 脚本，从 CSV 读取数据，计算平均值，输出到 JSON。” Pi 会生成、保存、甚至运行脚本。如果结果不对，你可以分叉会话尝试另一种实现，而不丢失原始思路。

大型项目重构

在包含数万行代码的项目中，用 Pi 批量修改接口。通过 AGENTS.md 注入团队编码规范，确保生成代码符合风格。切换不同模型验证逻辑一致性——比如用 Claude 生成，用 DeepSeek-Coder 审查。

自定义工作流

团队可开发专属扩展：比如 /lint 自动格式化代码，/doc 生成 JSDoc，/deploy 触发部署流程。这些扩展通过内部 npm 私服分发，统一开发体验。

远程服务器开发

在无图形界面的云服务器或 Docker 容器中运行 Pi，配合 tmux 实现后台持久会话。开发者通过 SSH 连接，享受与本地一致的 AI 辅助编程体验，适合 CI/CD 或边缘计算场景。

开源协作

调试复杂 issue 时，用 /share 生成 Gist 链接，协作者点开就能看到完整上下文、模型推理过程、代码变更记录，比单纯贴代码片段更高效。

开源与社区

Pi 采用 MIT 许可证，代码完全公开。其“极简核心 + 社区扩展”的架构已催生多个移植版本，包括 Go、Rust 和 Python 实现。供应链经过 hardened 处理，依赖透明，适合对安全性要求高的场景。

项目官网为 https://pi.dev/，GitHub 仓库地址是 https://github.com/earendil-works/pi。文档详细，示例丰富，新手也能快速上手。

总的来说，Pi 不是一个“全能助手”，而是一个“可编程的助手框架”。它把控制权交还给开发者，让你决定 Agent 应该有多聪明、多复杂、多贴近你的工作流。