Pi Agent：极简核心与可扩展的编程代理

Sat, 13 Jun 2026 22:05:58 +0800

Pi Agent 是一个运行在终端中的编程代理 harness。官方文档中对它的定义是 minimal terminal coding harness，这个定义基本概括了项目的核心取向：保持最小可用核心，将具体工作流交给扩展层。

它没有预设完整开发流程，也没有把所有常见能力直接打包进核心。Pi 更接近一个本地 agent runtime：负责模型接入、终端交互、工具调用、会话管理和资源加载。计划模式、子代理、权限确认、MCP、任务列表等工作流能力，则通过 extensions、skills、prompt templates、themes 和 pi packages 组合出来。

这种设计的重点在于限制核心职责，避免由核心替用户决定工作方式。

最小核心

默认情况下，Pi 给模型提供的主要工具非常有限：

read
write
edit
bash

这四个工具覆盖了本地代码代理最基础的能力：读取文件、创建或覆盖文件、精确编辑文件、执行 shell 命令。除此之外，Pi 还可以通过工具选项启用额外的只读工具，例如 grep、find、ls。

与很多编程 Agent 不同，Pi 官方 Philosophy 明确列出了一组默认不内置的能力：

No MCP.
No sub-agents.
No permission popups.
No plan mode.
No built-in to-dos.
No background bash.

这些缺省项体现了架构选择。MCP、子代理、计划模式、权限弹窗和任务系统都存在多种实现方式，也对应不同的使用习惯和安全模型。将它们固定在核心里，意味着所有用户都要接受同一套默认行为。

Pi 的选择相反：核心只保留必要运行时，复杂能力由扩展系统提供。

因此，Pi 的默认体验会比许多“大而全”的 Agent 更薄。第一次使用时，它更像一个可以读写项目并执行命令的终端代理。完整的项目管理流程需要在扩展层继续配置。

这也是它的边界。轻量任务可以直接使用默认工具完成；复杂任务需要通过扩展、技能或外部约束补齐流程。

扩展机制

Pi 的扩展体系主要由五类资源构成：

Extensions       TypeScript 模块，用于扩展工具、命令、事件和 UI
Skills           按需加载的能力包，遵循 Agent Skills 标准
Prompt Templates 可复用的提示词模板
Themes           终端界面主题
Pi Packages      通过 npm 或 git 分发的一组扩展资源

Extensions 是能力最强的一层。它们可以注册自定义工具、替换内置工具、添加 slash commands、监听事件、改写 UI、实现权限门禁、接入 MCP、实现 plan mode，甚至将 Pi 改造成另一种交互形态。

Skills 更适合封装任务知识。一个 skill 可以包含某类任务的工作流程、注意事项、辅助脚本和参考资料。与长期膨胀的系统提示词相比，skills 的优势在于按需加载。写 commit message、做 code review、处理 release、生成文档，各自可以有独立规则，不必永久占用主上下文。

Prompt templates 用于复用常见提示词。Themes 负责界面呈现。Pi packages 则是分发机制，可以把 extensions、skills、prompts 和 themes 打包，通过 npm 或 git 安装到全局或项目本地。

这一套机制让 Pi 更接近可组合平台。用户可以只使用默认工具，也可以按自己的工作流逐步增加能力。项目级配置可以放在 .pi/settings.json，用户级配置则位于 ~/.pi/agent/settings.json。

工作流编排

Pi 核心没有内置 plan mode 或 sub-agents，但并不阻止这些能力存在。相反，它鼓励通过扩展或 package 实现不同版本的工作流。

例如子代理可以作为额外 package 提供，由父会话负责协调，再把探索、实现、审查等阶段拆给不同角色：

scout / context-builder   收集项目上下文
worker                    执行明确修改
reviewer                  使用新上下文审查 diff 或方案
researcher                检索外部资料和官方文档
parent session            负责决策、取舍和最终汇总

这种模型解决的是上下文污染和职责混杂的问题。单个 agent 从需求分析、代码阅读、实现到审查一路执行，容易把早期假设带到后续判断中。将探索、执行和审查拆分，可以降低主上下文压力，也能让审查阶段获得更独立的视角。

计划模式也类似。Pi 不预设唯一的 plan mode。计划可以写入普通文件，也可以由 extension 提供交互式计划流程，还可以通过 OpenSpec / SDD 这类阶段化方法沉淀为 proposal、spec、design、tasks、apply、verify 等工件。

工作流因此脱离核心固定功能，成为用户根据项目复杂度选择的编排层。

与常见编程 Agent 的差异

许多编程 Agent 追求开箱即用，倾向于把完整体验集成在产品内部：权限确认、计划模式、MCP、子代理、任务列表、后台命令执行等能力都作为默认流程的一部分。

这种方式降低了初始配置成本，也让用户更容易直接进入自动化开发。但代价是默认行为较重，工作流边界也更难修改。用户通常会进入工具预设的流程，底层组合空间相对更少。

Pi 的差异在于默认取舍：

核心负责运行时，不负责规定流程。
扩展负责能力增长，不污染最小核心。
安全边界交给系统级隔离，避免用内置弹窗伪装成完整沙箱。
项目工作流可以被声明、安装、替换或移除。

这使 Pi 更适合需要自定义 agent 行为的人。比如希望使用特定 review 流程、特定计划格式、特定权限策略、特定子代理编排方式，或者希望把已有团队规范封装成 skills 和 extensions。

相对地，如果只需要一个开箱即用、默认流程完整的 AI 编程工具，Pi 的初始体验可能显得过于朴素。它要求用户理解工具边界，并愿意把工作流作为工程对象来维护。

安全边界

Pi 是本地编程代理，以启动它的用户权限运行。内置工具可以读写文件和执行 shell 命令，extensions 也是具有同等权限的 TypeScript 模块。

官方安全文档明确指出：project trust 不具备 sandbox 语义。它只控制项目本地配置、资源、packages 和 extensions 是否加载，不限制模型在已启动会话中请求工具执行什么操作。

因此，不可信仓库、不希望密切监督的生成代码、无人值守自动化任务，都不应该只依赖 Pi 自身的 trust 机制。更强的边界需要来自操作系统或虚拟化层，例如容器、VM、micro-VM、远程 sandbox 或带策略控制的执行环境。

这一点和 Pi 的整体设计一致。它不在进程内部提供容易被误解的半沙箱，真实隔离交给外部环境。

我的工具配置列表

在默认 Pi 之上，我目前主要增加了几个 package。它们位于 Pi 核心之外，建立在 Pi 扩展机制之上，组成个人工作流层。

gentle-pi        SDD / OpenSpec / review guardrails
gentle-engram    persistent memory
pi-subagents     subagent orchestration
pi-web-access    web search / fetch / GitHub clone / media extraction
pi-mcp-adapter   MCP adapter
pi-zentui        terminal UI / statusline

gentle-pi 是我配置里的主干。它把 Pi 调整成偏工程纪律的开发 harness，提供 el Gentleman persona、SDD/OpenSpec 流程、严格 TDD 证据约束、review workload guard、skill registry 以及 PR / issue / release 等协作技能。

我使用它的目的在于给复杂开发任务增加阶段边界。这里的重点不在“人格”本身，而在 proposal / spec / design、tasks、verify 这些阶段化约束。需求不清楚时先沉淀规格，进入实现前拆任务，实现后再验证。这样可以避免所有需求、假设和决策都留在聊天上下文里。

gentle-engram 提供持久记忆能力。Pi 本身有 session，但 session 更偏向会话记录。项目长期知识库需要保存跨会话仍然有价值的信息，例如项目约定、用户偏好、非显然发现、修复过的问题和配置决策。Engram 用来承担这部分职责。

我使用它的目的在于降低重复解释成本。每次进入项目时，不必重新告诉 agent 文章目录、脚本位置、测试能力或偏好的工作方式。但 memory 需要保持可验证和可维护，过期信息不能当成事实直接使用。

pi-subagents 为 Pi 增加子代理、chain、parallel、async、forked context 等编排能力。Pi 官方默认不内置 sub-agents，这个 package 相当于在扩展层实现了一套可组合的代理工作流。

我使用它的目的主要是分离职责。探索阶段交给 scout 或 context-builder，执行阶段交给 worker，审查阶段交给 fresh-context reviewer，外部资料检索交给 researcher。主会话只保留决策、取舍和最终汇总，避免一个上下文承担所有角色。

pi-web-access 提供外部资料访问能力，包括 web search、URL 内容抽取、GitHub 仓库克隆、PDF 提取、YouTube 视频理解和本地视频分析。对需要核查官方文档、库源码或网页资料的任务，它补齐了 Pi 默认工具无法直接覆盖的外部信息来源。

我使用它的目的在于减少凭印象写作和实现。涉及第三方项目、公开仓库、API 行为或文档解释时，需要优先读取 primary source，降低对模型已有知识的依赖。

pi-mcp-adapter 用于接入 MCP。Pi 官方核心不内置 MCP，原因仍然是保持核心小，并避免把某一种工具接入协议强制变成默认路径。需要 MCP 时，通过 adapter 扩展即可。

我使用它的目的在于保留 MCP server 的兼容性。MCP 在这套配置里只是可选接入层，不进入 Pi 核心依赖，也不承担所有工具能力的入口。

pi-zentui 负责终端界面和状态展示，提供类似 Starship 的 statusline 和另一套 TUI 风格。它不改变 agent 的能力边界，但会影响长会话中的可观察性。

我使用它的目的主要是改善交互体验。模型、上下文、工作目录、状态提示、token 使用等信息更容易在终端里被看到，长时间使用时成本更低。

这些工具组合后的实际形态更接近一个个人开发 harness：Pi 提供极简运行时，package 提供工作流能力，项目配置保存本地约束，memory 保存跨会话事实，subagents 负责拆分复杂任务，web access 负责事实核查。

我的使用场景

我的使用场景主要集中在本地项目开发和技术资料整理。默认 Pi 可以完成轻量读写和命令执行；在此基础上，额外配置用于补齐长期使用中更容易出问题的部分：需求沉淀、上下文管理、事实核查、审查和交互可观察性。

目前更适合用 Pi 处理的任务包括：

在终端中直接阅读和修改本地项目；
根据项目约定生成或调整文档、脚本、配置文件；
通过 web access 核查官方文档、公开仓库和 API 行为；
通过 SDD / OpenSpec 管理边界不清楚的复杂需求；
通过 subagents 拆分探索、实现和审查；
通过 memory 保存跨会话仍然有效的项目事实。

这套配置不追求“一键自动开发”。更准确的定位是把 AI 编程变成一个可编排、可审查、可回溯的本地工作流。

轻量任务仍然可以直接交给默认工具。复杂任务则需要先确定范围，再决定是否使用 SDD、是否委托子代理、是否需要外部资料核查、是否需要 fresh review。

工具本身不替人决定这些问题。真正需要维护的是流程、上下文、权限、审查和项目规范。Pi 提供底座，我的配置负责把这些边界补上。

Pi Agent on 永恒的四月博客