Pi Coding Agent：一个可以被你改造的 AI 编程底座

Pi Coding Agent：一个可以被你改造的极简编程 Agent

这两年，编程 Agent 已经不稀奇了。

从 Claude Code、Codex CLI，到各种 IDE 插件，大多数工具的产品逻辑都差不多：给你一个已经包装好的智能体，你在它允许的范围里使用它。

但 Pi Coding Agent 的思路有点不一样。

它不是一个封闭的“AI 编程产品”，而是一个极简 Agent Harness。换句话说，它更像是一个可以运行在终端里的 Agent 操作系统：核心保持很小，把工作流、工具、技能、提示词、扩展、模型供应商都留给用户自己定制。

官方对它的定位很直接：

Change the harness, not your workflow.
改造 Agent 底座，而不是被 Agent 工作流反过来改造。

这正是 Pi 最有意思的地方。

一、Pi 是什么？

Pi Coding Agent 是一个运行在终端里的本地编程 Agent。

它默认提供最基础的能力：

  • 读取文件

  • 写入文件

  • 编辑文件

  • 执行 shell 命令

  • 搜索文件

  • 维护会话历史

  • 切换模型

  • 加载项目上下文

  • 使用 Skills / Extensions / Prompt Templates 扩展能力

但它并不追求把所有功能都内置进去。

官方甚至明确说：Pi 默认不内置 sub-agent、plan mode、MCP、权限弹窗、后台 bash 等功能。

这听起来像缺点，但其实是 Pi 的设计哲学：

Pi 提供原语，而不是提供封死的功能。

如果你需要计划模式，可以自己做一个 plan-mode extension。
如果你需要子代理，可以装 sub-agent extension。
如果你需要权限控制，可以写 permission gate。
如果你需要路径保护，可以加 protected-paths。
如果你需要 SSH 执行、沙箱、状态栏、交互式 UI，也都可以通过扩展完成。

它更像是“给工程师用的 Agent 框架”，不是“给普通用户用的 AI 编程盒子”。

二、安装 Pi

Pi 以 npm 包形式发布。

官方推荐安装方式：

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

其中 --ignore-scripts 是为了禁用 npm 依赖安装时的 lifecycle scripts。Pi 正常安装不依赖这些脚本，安全性更好。

Linux / macOS 也可以使用官方安装脚本：

curl -fsSL https://pi.dev/install.sh | sh

安装完成后，进入项目目录：

cd /path/to/project pi

第一次启动后，可以通过 /login 登录订阅类模型服务，也可以通过环境变量配置 API Key。

例如：

export ANTHROPIC_API_KEY=*** pi

Pi 支持的模型供应商很多，包括 Anthropic、OpenAI、Google、Azure、Bedrock、Mistral、Groq、Cerebras、xAI、Hugging Face、Kimi For Coding、MiniMax、OpenRouter、Ollama、小米 MiMo 等。

三、Pi 的基本使用方法

启动 Pi 后，它会进入一个终端 TUI 界面。

你可以直接输入任务：

Summarize this repository and tell me how to run its checks.

Pi 会读取项目文件，分析仓库结构，然后给出运行方式、检查命令、可能的改动建议。

1. 引用文件

在输入框里输入 @，可以模糊搜索并引用项目文件。

也可以在命令行中直接传入文件：

pi @README.md "Summarize this" pi @src/app.ts @src/app.test.ts "Review these together"

这对代码审查、重构、测试分析很方便。

2. 执行 shell 命令

交互模式里可以用：

!npm run lint

命令输出会进入模型上下文，Agent 可以基于结果继续分析。

如果你想执行命令，但不想把输出喂给模型，可以用：

!!npm run lint

这适合一些输出很长、但只需要你自己看的命令。

3. 切换模型

Pi 支持运行中切换模型：

/model

也可以用快捷键：

  • Ctrl + L：选择模型

  • Ctrl + P：在常用模型之间循环

  • Shift + Tab：切换 thinking level

这点对工程使用很实用：简单任务用便宜模型，复杂重构切高推理模型。

4. 一次性命令模式

Pi 不一定要进入交互界面，也可以当作命令行工具用。

例如：

pi -p "Summarize this codebase"

管道输入：

cat README.md | pi -p "Summarize this text"

指定图片：

pi -p @screenshot.png "What's in this image?"

这意味着 Pi 可以被嵌入 shell 脚本、CI 流水线、代码审查流程中，不只是一个 TUI 聊天工具。

四、项目上下文：AGENTS.md 是 Pi 的工作说明书

Pi 会自动读取项目里的上下文文件。

包括：

  • ~/.pi/agent/AGENTS.md

  • 当前项目及父目录里的 AGENTS.md

  • 当前项目及父目录里的 CLAUDE.md

你可以在项目根目录写一个 AGENTS.md：

# Project Instructions - Run `npm run check` after code changes. - Do not run production migrations locally. - Keep responses concise. - Use TypeScript strict mode.

这样 Pi 每次进入项目都会自动知道项目约定。

这对长期项目非常重要。否则每次都要重新告诉 Agent：

  • 项目怎么启动

  • 哪些目录不能动

  • 测试命令是什么

  • 数据库迁移能不能跑

  • 代码风格是什么

  • 交付前必须检查什么

Pi 的思路是：把项目规则写进文件，而不是写进临时对话。

这点和 OpenClaw / Claude Code / Codex 的 AGENTS.md 体系是一致的。

五、Pi 最值得注意的能力：会话是树，不是线

很多 Agent 工具的会话是线性的。

你问一句，它答一句。
中间如果走错了，要么撤销，要么新开会话。

Pi 的会话是树结构。

它会把 session 保存到：

~/.pi/agent/sessions/

每个 session 是 JSONL 文件，并且内部是树状结构。

你可以用：

/tree

跳回任意一个历史节点，从那里继续走另一条分支。

这对编程任务特别有用。

比如你让 Pi 重构一个模块：

  • 分支 A：用最小改动方式修

  • 分支 B：顺手重构架构

  • 分支 C：先写测试再改代码

  • 分支 D：完全换一种实现

传统 Agent 对话里，这些尝试很容易混在一起。

Pi 的 /tree 可以把这些探索路径留在同一个 session 文件里，而且可以随时切换、打标签、继续分叉。

这非常适合：

  • 技术方案对比

  • Bug 修复路径探索

  • 重构前后对照

  • Prompt 实验

  • 模型输出对比

  • 复杂任务的决策留痕

我认为这是 Pi 和很多 CLI Agent 相比非常有区分度的功能。

六、Pi 的真正杀手锏：Extensions

Pi 的扩展是 TypeScript 模块，可以直接改变 Pi 的行为。

它可以做很多事：

  • 注册自定义工具

  • 注册自定义 slash command

  • 拦截工具调用

  • 修改模型请求

  • 注入动态上下文

  • 自定义压缩逻辑

  • 加权限确认

  • 加路径保护

  • 加状态栏

  • 加交互式 UI

  • 管理长期状态

  • 接外部系统，比如 CI、Webhook、数据库、SSH

扩展放置位置：

~/.pi/agent/extensions/

或者项目本地：

.pi/extensions/

一个最小扩展示例：

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"; import { Type } from "typebox"; export default function (pi: ExtensionAPI) { pi.on("session_start", async (_event, ctx) => { ctx.ui.notify("Extension loaded!", "info"); }); pi.registerTool({ name: "greet", label: "Greet", description: "Greet someone by name", parameters: Type.Object({ name: Type.String({ description: "Name to greet" }), }), async execute(toolCallId, params) { return { content: [{ type: "text", text: `Hello, ${params.name}!` }], details: {}, }; }, }); pi.registerCommand("hello", { description: "Say hello", handler: async (args, ctx) => { ctx.ui.notify(`Hello ${args || "world"}!`, "info"); }, }); }

启动时加载：

pi -e ./my-extension.ts

如果放在自动发现目录中，运行：

/reload

就可以热重载。

这就是 Pi 的核心价值：它不是只让 Agent 写业务代码，它允许 Agent 改造自己。

你可以对 Pi 说：

帮我写一个 extension：所有 bash 命令里如果出现 rm -rf、sudo、docker prune，就先弹确认框。

Pi 可以直接给自己加一个 permission gate。

或者：

帮我写一个 extension：每次改代码前自动 git diff，改完后自动运行 npm test，并把结果放到底部状态栏。

这就变成了你自己的编程工作流。

七、Skills：让能力按需加载

Pi 支持 Agent Skills 标准。

Skill 是一个自包含能力包，通常结构如下：

my-skill/ ├── SKILL.md ├── scripts/ │ └── process.sh ├── references/ │ └── api-reference.md └── assets/ └── template.json

SKILL.md 里写清楚技能名称、描述、使用场景、操作步骤。

Pi 启动时只把 skill 的名称和描述放进上下文；当任务匹配时，再读取完整 SKILL.md。

这叫 progressive disclosure：能力很多，但上下文不爆炸。

你也可以手动调用：

/skill:brave-search /skill:pdf-tools extract

这套机制很适合把高频流程沉淀下来，例如：

  • PDF 处理

  • API 文档查询

  • 项目发布流程

  • 数据库巡检

  • 模型部署流程

  • Docker 故障排查

  • 周报生成

  • 公众号排版

  • 视频脚本生成

对工程团队来说，Skills 的意义不是“让 AI 更聪明”，而是把团队里的操作经验变成可复用资产。

八、Prompt Templates：把常用提示词变成命令

Pi 支持 prompt templates。

你可以把常用提示词写成 Markdown 文件，然后在 Pi 里通过 slash command 展开。

例如你可以做一个：

/review

用于代码审查。

一个：

/release-check

用于发布前检查。

一个：

/refactor-plan

用于生成重构计划。

这比每次复制粘贴长 Prompt 更稳定，也更容易团队共享。

九、Pi Packages：把扩展、技能、提示词打包分享

Pi 还支持 package 机制。

一个 Pi package 可以包含：

  • extensions

  • skills

  • prompt templates

  • themes

可以通过 npm 或 git 安装：

pi install npm:@foo/pi-tools pi install git:github.com/user/repo@v1

也可以项目级安装：

pi install -l git:github.com/team/project-pi-tools

项目级 package 会写入 .pi/settings.json，团队成员进入项目后，Pi 可以加载同一套工作流。

这意味着你可以为一个项目定制完整的 Agent 工作环境：

.pi/ ├── settings.json ├── extensions/ ├── skills/ ├── prompts/ └── themes/

这对团队工程化很有价值。

不是每个人各自调 Prompt，而是把 Agent 能力版本化、仓库化、可审查化。

十、Pi 的几个妙用场景

1. 把 Pi 当成“可改造的 Claude Code”

如果只是日常写代码，可以这样用：

cd your-project pi

然后让它：

阅读这个项目，告诉我如何启动、如何测试、主要模块是什么。

再让它：

帮我修复这个 failing test，改动前先说明原因，改动后运行测试。

这种用法和其他 coding agent 类似。

但 Pi 更进一步：当你发现默认行为不顺手时，可以直接让它改自己。

比如：

以后每次修改代码前，先自动创建 git checkpoint。帮我写一个 extension。

这就是 Pi 的强项。

2. 做“项目级 AI 工程规范”

在项目根目录写：

AGENTS.md .pi/settings.json .pi/prompts/ .pi/skills/

把项目的启动方式、测试方式、发布规则、安全限制、代码规范都沉淀进去。

这样任何人进入项目后运行：

pi

拿到的是同一套 Agent 行为。

这比口头约定强得多。

3. 做代码审查机器人

用只读工具启动：

pi --tools read,grep,find,ls -p "Review this repository and identify risky code paths."

这样 Pi 只能读，不能写，也不能跑命令。

适合：

  • PR 审查

  • 安全审查

  • 依赖风险分析

  • 老项目摸底

  • 接手新项目

4. 做 CI 辅助分析器

Pi 的 print 模式适合脚本化。

例如：

npm test 2>&1 | pi -p "Analyze this test failure and suggest the likely fix."

或者：

cat build.log | pi -p "Summarize this build failure in Chinese."

这可以接到 CI 里，自动生成失败原因说明。

5. 做“可分叉的技术方案实验台”

复杂重构时，最怕 Agent 一条路走到黑。

Pi 的 /tree 很适合探索多个方案。

例如：

方案 A：最小改动修复。 方案 B：重构 service 层。 方案 C：引入状态机。

每个方案可以在同一个 session 树里保留。最后你可以比较差异，再决定采用哪条路径。

这对架构设计、重构试验、Prompt 评估都很有用。

6. 做团队内部 Agent 平台的原型底座

Pi 支持四种模式：

  • Interactive：终端交互

  • Print / JSON：命令行一次性调用或事件流

  • RPC：stdin/stdout JSON 协议

  • SDK：嵌入 Node.js 应用

这说明 Pi 不只是一个终端工具，也可以作为上层系统的 Agent runtime。

例如：

  • 接到内部 DevOps 平台

  • 接到代码评审系统

  • 接到企业知识库

  • 接到自研 UI

  • 接到 OpenClaw 这类多 Agent 编排系统

官方首页也提到 OpenClaw 是一个真实集成案例。

对想做内部 AI 工程平台的人来说，Pi 的 RPC / SDK 模式值得重点关注。

十一、安全边界：Pi 没有内置沙箱

这一点必须讲清楚。

Pi 是本地 Agent，它以启动它的用户权限运行。

它可以：

  • 读文件

  • 写文件

  • 改文件

  • 执行 shell 命令

  • 加载 extensions

  • 安装 packages

官方明确说：Pi 没有内置 sandbox。

项目 trust 机制只是控制 Pi 是否加载项目里的 .pi/settings.json、.pi/extensions、.pi/skills 等资源。它不是安全沙箱，也不会限制 Agent 后续工具调用。

所以不要把 Pi 直接扔到不可信仓库里放开跑。

建议：

  • 不可信项目用容器或 VM

  • 最小化挂载目录

  • 不挂载敏感凭据

  • API Key 用短期凭证

  • 高风险任务用只读工具

  • 重要改动前先 git commit 或 checkpoint

  • 安装第三方 package / extension 前审代码

Pi 的安全哲学很工程化：它不假装自己有强沙箱，而是把隔离交给操作系统、容器、虚拟机。

这个判断是对的。

十二、Pi 适合什么人？

Pi 不一定适合所有人。

如果你只想要一个开箱即用、UI 漂亮、什么都不用管的 AI 编程助手，Pi 可能不是第一选择。

但如果你是下面几类用户，Pi 很值得研究：

  • 喜欢终端工作流的工程师

  • 想把 Agent 接入自己工具链的人

  • 想沉淀团队 AI 编程规范的人

  • 需要自定义模型供应商的人

  • 想做内部 Agent 平台的人

  • 需要把 Agent 行为版本化、工程化的人

  • 对 prompt、context、tools、memory 有控制欲的人

Pi 的价值不是“替你写代码”，而是让你拥有一个可以被改造、被扩展、被集成的 Agent 底座。

十三、我的判断

现在很多 AI 编程工具的路线是：产品越做越厚，把用户锁进一套固定工作流。

Pi 走的是相反方向：核心尽量薄，把可编程接口留出来。

这类工具早期看起来会“不够完整”，但对工程师很有吸引力。因为真正复杂的开发流程，从来不是一个通用产品能完全覆盖的。

不同团队有不同的目录结构、发布流程、代码规范、权限边界、模型偏好、安全策略和上下文管理方式。

Pi 的回答是：

不要等产品经理给你加功能。
你可以直接让 Agent 改造 Agent 自己。

这就是 Pi Coding Agent 最妙的地方。

它不是一个封闭的 AI 编程工具，而是一个可以长成你自己工作流形状的 Agent Harness。

附：快速操作清单

安装

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

进入项目

cd /path/to/project pi

登录模型供应商

/login

或使用环境变量：

export ANTHROPIC_API_KEY=*** pi

引用文件

pi @README.md "Summarize this"

一次性任务

pi -p "Summarize this codebase"

管道输入

cat README.md | pi -p "Summarize this text"

只读审查

pi --tools read,grep,find,ls -p "Review this repository."

切换模型

/model

继续最近会话

pi -c

浏览历史会话

pi -r

查看会话树

/tree

导出会话

/export output.html

安装 Pi package

pi install npm:@foo/pi-tools pi install git:github.com/user/repo@v1

资料来源

引用链接

[1]https://pi.dev/

[2]https://pi.dev/docs/latest

[3]https://pi.dev/docs/latest/quickstart

[4]https://pi.dev/docs/latest/usage

[5]https://pi.dev/docs/latest/providers

[6]https://pi.dev/docs/latest/extensions

[7]https://pi.dev/docs/latest/skills

[8]https://pi.dev/docs/latest/sessions

[9]https://pi.dev/docs/latest/security

[10]https://pi.dev/docs/latest/packages

经验分享
Pi Coding Agent：一个可以被你改造的 AI 编程底座
https://maoyu92.github.io/2026/06/17/07 AI笔记/AI写作与发布/a075_Pi Coding Agent：一个可以被你改造的 AI 编程底座/
作者
陈文茂
发布于
2026年6月17日
许可协议