Pi Agent Harness：一个把控制权交还给开发者的极简编程 Agent
云朵君约 15 分钟这两年我看了不少编程 Agent，Claude Code、Cursor 这类产品已经能帮我们读代码、跑命令、改文件。但看得越多，我越在意另一个问题：这些能力究竟是模型提供的，还是模型外面的程序提供的？
拿修改代码来说，模型可以判断下一步应该读取哪个文件，但真正去读文件、执行 Shell、把结果送回模型，以及决定什么时候停下来的，是外面那套执行框架。
这套围绕模型运行的执行框架，就是 Agent Harness（智能体运行框架）。
Pi[1] 是 Mario Zechner（GitHub 用户名 badlogic，libGDX 创作者）设计的一款极简终端编程 Agent。它的核心主张很直接：Agent 可以有一套好用的默认能力，但不必把所有工作流都写死在产品里。 开发者能够通过 TypeScript 扩展、Skills、提示词模板和可分享的包，按自己的需求改造它。
这也是我想聊 Pi 的原因。它当然能当编程工具用，但更有意思的是，它把很多产品藏起来的 Harness 机制摆到了开发者面前。
不要把“极简”理解为“功能少”。 Pi 保留了能跑通 Agent 的主干，把计划模式、子 Agent 编排、审批策略等能力留给用户自行选择。相应地，开发者获得更大的控制权，也必须承担更多配置、测试与安全责任。
02Agent Harness 到底负责什么？
我习惯把一个 Harness 拆成六个部分来看：
任务定义（Task Definition）：把用户要求变成可执行、可判断是否完成的任务。 上下文与记忆管理（Context / Memory）：控制每轮调用模型时向它提供哪些指令、代码和历史内容。 工具执行层（Tool Execution）：读取与修改文件、执行 Shell 命令、调用 API。 循环控制器（Loop Controller）：根据模型发出的工具调用和结果决定继续执行还是结束。 验证层（Verification）：检查代码是否真的符合要求，而不是仅相信模型说“完成了”。 失败处理（Failure Handler）：在工具失败、超时、偏离目标或验证失败时重试、终止或交给人处理。
Pi 直接提供任务交互、上下文管理、工具调用、循环和基础错误处理；面向业务的完成标准和验收流程，仍然需要用户自己定义。严格地说，Pi 提供底层能力，并不意味着它能自动保证业务可靠性。
用一个最小执行循环理解 Pi
下面是原理示意，不是 Pi 的内部源码：
用户提出修改需求
↓
加载系统指令、项目规则、相关上下文
↓
调用大语言模型
↓
模型决定：直接回答，还是调用工具？
├── 直接回答 → 输出结果
└── 调用工具（read / write / edit / bash）
↓
执行工具
↓
返回工具结果给模型
↓
下一轮推理与工具调用
↓
结束或进入自定义验证流程
例如用户要求“给项目增加一个输入校验，并运行测试”，模型先读取相关源码，随后编辑文件并执行测试命令。Harness 负责执行这些动作，并把标准输出、错误信息等作为下一轮上下文交给模型。模型可以根据失败信息继续修复，但最终是否满足验收标准，需要独立检验。
这就是 Agent Harness Engineering 的关键：模型能力重要，但执行框架同样影响稳定性、成本、可观察性和可控性。
03安装 Pi 并完成第一次运行
想上手的话，可以先用 npm 安装：
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
--ignore-scripts 表示安装时不执行依赖的生命周期脚本。macOS 或 Linux 也可以使用安装脚本：
curl -fsSL https://pi.dev/install.sh | sh
执行远程安装脚本之前，建议先检查脚本内容及其来源；实际安装命令也应以当前官方文档[2]为准，因为 Pi 的包名和仓库组织经历过变化。历史资料中还可能出现 @mariozechner/pi-coding-agent，不要不加区分地混用不同阶段的教程。
进入项目目录后运行：
cd /path/to/your/project
pi
可以在交互界面中使用 /login 登录支持的订阅提供商，或提前设置 API Key，例如：
export ANTHROPIC_API_KEY="your-api-key"
pi
Pi 的多模型支持也是它比较实用的地方，可以接入 Anthropic、OpenAI、Google、Azure、Bedrock、Mistral、Groq、Cerebras、xAI、Hugging Face、Kimi、MiniMax、OpenRouter、Ollama 等。具体支持的模型、认证方式和订阅权益随版本及提供商政策变化，不能把“支持这个提供商”等同于“所有模型都可用”。
在交互模式中，可以使用 /model 选择模型。快捷键方面，还可以用 Ctrl+L 打开模型切换界面，以及 Ctrl+P 在收藏模型之间切换。
第一次使用，我建议先做一件小事
我更建议先找一个有 Git 版本管理的测试仓库，做一件小事，例如：
请先阅读这个项目的 README 和相关代码，说明入口、目录结构和测试命令。
先不要修改文件。如果你发现信息不足，请说明哪些结论还无法确认。
随后再执行一项范围清晰的修改：
只修改输入校验相关代码，为空字符串增加明确的错误提示。
完成后运行对应测试，报告修改文件、测试命令、运行结果和未验证事项。
不要修改无关模块。
这样的开始方式更容易观察 Pi 如何读取文件、使用工具与处理反馈，而不是一上来就把整个项目交给 Agent 自主改造。
04四种运行模式：从终端交互到嵌入产品
Pi 不只是一个终端聊天窗口。按不同的集成需求，可以用四种方式运行：
pi | ||
pi -p "query"--mode json | ||
其中，SDK 和 RPC 是 Pi 作为平台组件的关键价值。如果要开发自己的 AI 工具，不必把模型调用、上下文维护、工具执行和会话管理全部重新实现，可以将 Pi 作为中间执行层，再在上面构建产品界面与业务流程。
OpenClaw 是理解 SDK 集成方式时可以参考的一个案例：消息入口、调度和产品侧 Skills 属于上层应用，Pi 提供其中的底层 Agent 执行能力。这里介绍的是架构分工，而不是断言不同版本的 OpenClaw 始终使用相同集成方案。
四种模式该怎么选？
如果只是尝试 Pi，选交互模式。若需要把结果接入自动化流水线，可以研究 Print/JSON。若自己的宿主程序不是 Node.js，并希望通过进程协议控制 Agent，可以考虑 RPC。如果要在 Node.js 服务里深度控制会话、事件与工具集成，则优先研究 SDK。
在自动化场景中，Agent “会执行”不代表“适合无人值守”。 对删除文件、发布、推送代码、访问外部网络等操作，应在执行层增加明确边界。
05上下文工程：AGENTS.md、SYSTEM.md、压缩与 Skills
Pi 最值得学习的部分之一，是它对上下文管理的开放程度。很多 Agent 工具把“每轮究竟给模型什么内容”隐藏在产品内部；Pi 则让开发者更直接地控制这条链路。
AGENTS.md：项目的长期规则
Pi 可以从全局配置位置、父级目录和当前项目读取 AGENTS.md，用来提供项目约束。它不是长期记忆数据库，而更接近一份每次进入项目都应该参考的工作规程。
例如：
# 项目规则
- 优先读取 README 和已有测试，再修改代码。
- 仅修改当前任务涉及的模块。
- 不得修改生成目录、历史备份或生产密钥。
- 每次完成修改后执行相关测试。
- 如果测试无法运行，必须明确说明原因。
SYSTEM.md：调整系统级指令
Pi 还允许通过 SYSTEM.md 替换或追加默认系统提示词，从而改变 Agent 的角色、工作边界与行为偏好。这是 Harness 层的配置能力，不必为了修改提示词而维护自己的 Pi 分叉。
AGENTS.md 更适合放项目约束；SYSTEM.md 更接近 Agent 的基础行为配置。两者作用不同，具体加载和优先级应以所安装版本的文档为准。
Compaction：上下文压缩
随着对话增长，模型不可能无限读取所有历史消息。Pi 支持压缩较早的对话内容，并允许扩展接管压缩逻辑，例如按照主题摘要、保留关键代码决策、使用较低成本模型处理摘要等。
这里要注意：上下文压缩不等于无损记忆。摘要可能遗漏早期约束，所以关键的测试命令、禁止修改范围、已确认结论等最好写入项目文件，而不是只依赖聊天历史。
Skills 与 Prompt Templates：按需使用的能力
Skills：把一项任务的说明、资料和操作流程组织为可复用能力，通常适合特定任务或技术栈。 Prompt Templates：通过 Markdown 模板定义重复使用的提示词，可使用 /name之类的命令调用。
二者能够避免把所有任务说明都塞进常驻系统提示词。某项能力只有在需要时才展开相关上下文，是一种**渐进式披露（Progressive Disclosure）**策略。
Extensions：在运行时真正改变行为
Pi 的 TypeScript 扩展可以接入事件、命令、键盘快捷键、工具和 TUI，也可以在模型调用前处理上下文。常见用途包括插入动态消息、过滤历史、接入 RAG 或长期记忆等。
这里有一个很容易混淆的地方：Skills 和 Extensions 不是一回事。
简单来说，Skill 更多是任务知识与方法，Extension 更多是执行能力与运行机制。如果只需统一验收步骤，先写 Skill；如果必须新增事件钩子或工具调用行为，再考虑扩展。
06树形会话：一次任务可以有多条探索路径
大多数对话工具让人习惯线性历史，但 Pi 支持树形会话。通过 /tree，可以回到此前某个节点，并从该节点继续新分支，而不必覆盖原来的尝试路径。它还提供消息筛选、书签和导出等能力：
/tree：导航和分支；/export：将会话导出为 HTML；/share：按支持的方式分享会话，例如 GitHub Gist。
例如同一个测试失败，可以沿着两个分支探索不同修复策略：一个从配置入手，另一个从代码逻辑入手。相比不断开启新聊天，这种结构更方便保留决策路径。
需要区分：分支会话历史不等于 Git 代码分支，也不自动回滚磁盘上的文件修改。 若要进行可逆的代码实验，仍应配合 Git commit、工作树或隔离工作目录。
07运行途中调整方向：Steer 与 Follow-up
Pi 还有个我觉得很实用的设计：Agent 正在运行时，也能继续给它发消息。不过，这里要区分两种情况：
Enter（Steer）：将新要求作为中途纠偏信息；在当前工具执行结束后处理，可能中断同批次剩余工具。 Alt+Enter（Follow-up）：把消息排队，等当前轮任务结束后再交给 Agent。
前者适合“你理解错了，现在先不要改数据库”；后者适合“完成后顺便告诉我运行了哪些测试”。
这是一种轻量级的 Human-in-the-loop（人在回路）机制，但不等于对每次危险工具调用都进行权限审批。对于生产项目，仍需独立设计操作授权。
08只提供基础构件：Pi 为什么不预装所有功能？
Pi 的设计哲学在“没有内置什么”这件事上体现得尤其明显：
TODO.md 等文件或扩展维护 | |
Pi 并不是认为这些能力不重要，而是认为不应该强迫所有用户采用同一套工作流。例如，某个团队必须逐步审批文件写入，另一个团队则把整个 Agent 放入容器，并允许它在隔离环境内自动运行，两者适合不同的安全模型。
版本变化：MCP 与 Codemode
这里有个时间点需要留意。Pi 早期确实没有把 MCP 做进核心，不过到 2026 年 9 月底，MCP 和 Codemode 已经进入它的核心能力。因此，现在再说“Pi 不支持 MCP”就不准确了。
MCP（Model Context Protocol）是连接模型应用和外部工具、资源的一套协议；Codemode 强调通过代码化的调用方式组织工具使用。这不意味着所有第三方 MCP Server 都在 Pi 中自动安全可用：连接、授权、工具暴露范围和实际兼容性都应单独验证。
09Pi 可以扩展 Pi：/reload 和可分享的 Packages
我觉得 Pi 特别有意思的一个用法是：如果需要新的命令、工作流或界面交互，可以直接让 Pi 协助编写 TypeScript Extension，修改后使用 /reload 重新加载，而不必一开始就维护自己的程序分支。
扩展、Skills、提示词模板和主题可以打包为 Pi Package，再通过 npm 或 Git 分发。例如：
pi install npm:@foo/pi-tools
pi install git:github.com/badlogic/pi-doom
第一条的 @foo/pi-tools 只是占位包名。第二条的 pi-doom 则很有意思：Pi 的扩展能力甚至能被拿来运行 DOOM，显然不只是给代码编辑器加几个按钮。
不过，自我扩展也意味着风险：模型生成的扩展代码可能改变工具权限、文件操作或上下文注入规则。用于共享或团队生产环境的扩展，应先代码审查、版本固定和隔离测试。
10Pi 与 oh-my-pi、Claude Code、Cursor 和 OpenClaw
oh-my-pi（omp）
oh-my-pi 是 Pi 较知名的 fork，它强化了 hashline 编辑、LSP（语言服务器协议）、DAP（调试适配器协议）、更多模型提供商和子 Agent 编排等功能。
若你希望围绕轻量底座自行组织能力，原版 Pi 更合适；若希望直接拥有更丰富的编辑、诊断和调试工具，则可以评估 omp。两者的具体能力随版本变化。
Claude Code 与 Cursor
这类产品更重视日常开发场景的开箱即用体验。Pi 强调用户对 Harness 的可编程控制。选择并不取决于“谁更高级”，而在于你是否真的需要修改上下文拼装、执行事件和工具控制逻辑。
OpenClaw
从架构上理解 OpenClaw，也可以把它看成一个 SDK 集成案例：上层产品负责消息、调度、技能和用户交互，底层 Harness 承担模型与工具调用等工作。实际集成细节需参考对应版本源码，不能把这种架构描述视为永久不变的依赖关系。
11什么时候应该选择 Pi？
以下场景比较适合 Pi：
希望细粒度控制 AGENTS.md、系统提示词、动态上下文和压缩策略；需要在不同模型提供商之间切换，而不想把执行框架绑定到单一模型； 正在开发自己的 AI 软件，希望通过 SDK 或 RPC 嵌入 Agent； 需要分支会话、实验路径和可观察的执行历史； 愿意自行搭建验证、权限和多 Agent 编排机制。
如果你的目标只是尽快完成日常编码，不愿意维护任何扩展或集成配置，现成功能更完整的产品往往更节省时间。若需要预装 LSP、DAP 和子 Agent 工作流，可以把 oh-my-pi 作为比较对象。
12从零搭建第一个可验证的 Pi 工作流
如果想真正摸清 Pi 的设计，我建议不要一开始就装很多扩展。可以从一条最简单、可验证的工作流开始，再逐步加能力。整个过程分成五步。
第一步：定义边界。 指定允许修改的目录、禁止接触的凭据和资源、允许执行的测试命令。
第二步：定义验收标准。 例如“新增的输入校验必须通过单元测试，且现有测试不回归”。
第三步：只使用 Pi 默认工具完成第一次任务。 Pi 的默认核心工具包括 read、write、edit 和 bash，分别负责读取、写入、局部编辑和执行命令。不要一开始就堆满插件。
第四步：加入独立验证。 让自动化脚本或 CI 根据退出码判断测试是否通过，不仅依赖模型对日志的文字解释。
第五步：记录执行结果。 最少保留修改文件、工具命令、测试结果、失败信息和人工待确认事项。
一个可以直接修改的 AGENTS.md 模板
# Agent 工作约束
## 任务范围
- 只能修改 src/ 与 tests/ 中和当前需求直接相关的文件。
- 不允许修改密钥、依赖锁文件或部署配置，除非用户明确授权。
## 工作顺序
1. 读取相关代码和已有测试。
2. 说明预期修改范围。
3. 修改代码并补齐测试。
4. 运行相关测试，必要时运行全量测试。
5. 总结修改和未完成事项。
## 完成标准
- 关键功能具备自动化测试。
- 所运行测试均通过。
- 未引入无关修改。
- 无法验证的部分必须明确报告，不得宣称已经验证通过。
这只是我用来说明思路的通用模板，并不是 Pi 自动生成的默认规则。真正放进项目时，还要按构建流程、团队要求和风险等级调整。
13安全与沙箱：极简 Harness 的责任边界
安全方面有个不能忽略的前提：Pi 核心没有强制性的逐工具权限弹窗，因此安全策略需要在运行环境、工具层或扩展层实现。可采用 Docker 等容器方案以及官方资料提及的其他隔离工具。
需要关注四类风险：
Shell 执行权限： bash可能删除文件、访问网络或运行安装脚本。建议在独立用户、容器或受限工作目录中使用。第三方包与扩展：它们不只是提示词，还可能执行真实程序。安装之前应审查来源和代码，并固定版本。 提示词注入：仓库中的文档、网页或工具输出可能携带不可信指令，不能因为内容进入上下文就赋予其更高权限。 敏感信息与会话分享：导出或分享会话前，应排查 API Key、私人路径、内部源码及其他保密内容。
还应区分容器隔离和业务授权：即使 Agent 在容器里运行，也不表示它应有权限向生产环境发布内容或使用真实访问令牌。
14近期进展：性能案例、MCP 与 Durable
Pi 在 2026 年下半年还有几次值得留意的更新。不过，产品发布信息、企业个案和可复现的通用结论，最好分开看。
2026 年 8 月 5 日的一组案例： 据 Earendil 引述的 Databricks 内部编码 Agent 基准，称在特定模型与推理配置下，Pi 在所比较的 Harness 中取得较高通过率，同时使用更少上下文、成本更低。该结果是特定测试条件下的报道，不能直接推出 Pi 在所有代码仓库和模型上都最好。另一个案例是 Shopify 使用基于 Pi 扩展的 pi-autoresearch 优化内部任务，并报告部分项目指标显著改善；这些是具体案例的结果，不是对所有项目的普遍保证。
2026 年 9 月末至 10 月 1 日： Pi 引入 MCP 与 Codemode，改变了早期“不内置 MCP”的描述。这也是为什么我们现在讨论 Pi，不能再沿用早期“不支持 MCP”的印象。
2026 年 10 月 2 日： Earendil 发布 Pi 1.0 及实验性的 Pi Durable，探索更长时间运行的会话。由于该功能仍处于实验性描述阶段，实际可用性、状态恢复和失败保证需要核对对应版本文档，不宜直接视为成熟的生产级持久运行系统。
15聊到最后：我为什么觉得 Pi 值得研究
Pi 的核心价值不是替代所有主流编程 Agent，而是把一套常常隐藏在成熟产品内部的机制呈现出来：模型怎么接到任务、如何获得上下文、怎样调用工具、如何处理历史分支，以及在哪里接入自定义行为。
我更愿意把它理解成一个提醒：Agent 的可靠性，不仅取决于模型是否聪明，也取决于 Harness 如何组织上下文、执行工具、验证结果与控制风险。
如果目标是提高个人编码效率，可以先评估现成工具；如果目标是打造自己的 Agent 工作流、面向产品嵌入智能能力，或者深入研究 Agent Harness Engineering，Pi 提供了一个具体而且可以动手修改的起点。