Pi 的 harness 相比于 Claude Code、Codex 这些比较成熟的 AI Coding 工具来说会显得十分小巧但其设计却是十分精妙从 GitHub 的 star 数也可以看出它做的非常优秀。今天我们就回到 Pi 本身看它究竟有什么好的地方。starsPi 是什么按 Pi 官网的定义Pi 的定位是minimal agent harness。它组织模型、工具、上下文、会话和终端交互让 agent 具备在项目中工作的基本能力使用者再根据自己的工作流调整这个 harness。官网用两句话概括这套设计。Primitives, not features强调基础构件优先尽量少预置功能Adapt Pi to your workflows, not the other way around表示工作流应该决定 Pi 的形态。安装也很简单首先去官网首页[1]选择适合自己环境的安装方式安装完成后在终端输入pi启动。Pi下载接下来我们就来简单看看 Pi 的设计思想来看看为什么 Pi 能有这么好的表现。Pi 和其他 coding agent 最大的不同Claude Code、Codex 也有各自的 harness但它们预置的产品能力更多用户可以直接使用权限控制、计划模式等功能。Pi 则把稳定、通用的部分留在核心其余能力放到扩展层。两种路线没有绝对高下差别主要在默认能力和配置成本。最小工具集Pi 有多简单呢在 coding agent 形态下Pi 默认只给模型read、write、edit、bash四个工具。我最开始也很震惊四个工具够用吗Composio 和 Databricks 的评测刚好可以给出问题的答案。图 1Composio 7 月 31 日在 X 发布的 Kimi K3 测试成功率图 2、3 同源。图 2每任务平均成本。图 3每任务中位耗时。图 4Databricks benchmark 的成本与成功率分布。横轴是每任务平均成本纵轴是总体通过率。只看评测结果的话Pi 可谓是相当亮眼它在一些任务上的表现能和 Codex 和 Claude Code 掰掰手腕甚至是超越。grep、find、ls也是内置工具只是不默认开启。工具作用默认给模型read读文件是bash跑命令是edit改文件是write写文件是grep搜文件内容否内置但不默认find按名字找文件否内置但不默认ls列目录否内置但不默认想用这些工具也不用重新配置只需要执行下面这条命令就能启用。pi --tools read,grep,find,ls -p Review the code还能用--exclude-tools禁用单个工具用--no-builtin-tools关掉全部内置工具同时保留 extension 和自定义工具。我没看到官方解释为什么grep、find、ls不默认开。我的猜测是默认的bash已经覆盖了大部分 shell 能力这三个专用工具和它有重叠。这个选择和我最近读到的一本书里对工具设计的讨论很接近。书名是 AI Agents in Depth[2]感兴趣可以读一下书籍-通用工具read、write、edit、bash足够基础与通用模型可以结合自己的代码元能力去编排它们来完成搜索、修改和验证等各种任务。从前面的评测结果也可以看出即使 Pi 只有这些工具也能够成功完成任务。四个工具只是 Pi 的默认起点真正的差异还在于能力如何继续扩展。扩展层四个工具就能解决许多的任务但稳定的工作流光有这些工具还远远不够。当你从功能更完整的 Claude Code、Codex 等 coding agent 切过来时第一眼会觉得 Pi 少了很多东西。我们平时常用的功能比如固定提示、专用工具和权限控制的需求以及 MCP、sub-agent、权限确认、plan mode、内置待办和后台 Bash这些都没有直接放进 Pi 核心而是放在了扩展层。Pi 把这些交给 extension、skill、prompt template 和 package 去解决。Pi 官网用下面这句话表达这套思路Pi isn’t a sealed product. If you need a command, tool, provider, workflow, or UI tweak, just ask Pi to build it.这四种方式处理的事情并不相同。类型解决的问题典型内容extension改变 Pi 的运行时能力工具、命令、事件、快捷键、UI、权限流程skill保存一套按需加载的工作方法、参考等能力说明和执行步骤prompt template减少重复输入可通过/name展开的 Markdown 提示package分发和组合资源extension、skill、prompt、theme扩展层的价值是按需增加能力代价是需要自己维护边界。官方文档允许 extension 实现自定义工具、计划模式、权限控制、会话压缩、沙箱和 MCP 等能力。安装一个 package 之前应该先看源码和维护状态避免下载到有安全隐患的包。Pi 和 DeepSeek Harness 的设计理念有什么不同DeepSeek Harness 是 DeepSeek 官方开源的 agent 框架核心理念是Everything is a plugin一切皆插件。这其实和 Pi 的设计理念很像它们都没有把所有能力固定在核心里但所关注的问题不同。Pi 关注的是一个 coding agent 的默认核心可以缩到什么程度。它先提供一套能够直接工作的最小 harness再把额外工具和工作流能力放到扩展层。使用者从稳定的默认入口开始根据自己的需求逐步增加能力。DSH 关注的是一个 agent runtime 的各个部分能否拆开、替换和重新组合。比如模型接入、会话存储、循环调度和界面这些都可以作为插件被替换或重新组合。它把 runtime 看成一个可编排的系统重点不是提供一套固定的最小入口而是让使用者能够调整 agent 的组成方式。因此Pi 更像是从一个小而完整的 coding agent 出发逐步向外扩展DSH 则是从可组合的 runtime 出发重新组织 agent 的各个部分。这两套设计理念没有绝对高下。已经有明确 coding 工作流、想从小核心开始调整Pi 更直接想研究 agent runtime 的组成方式或希望替换更多底层模块DSH 的思路更适合。具体能力和使用方式可以再分别查看它们的官方文档。Pi 用起来最特别的地方树形会话想象一下如果让 agent 为一个功能准备两种实现方案但是第一种方案已经走了一半我想保留原路径再从早一点的用户消息分出另一条路线去做另一种尝试这个时候在 Pi 中可以怎么做呢首先我们先了解一下 Pi 允许我们怎么控制会话。Pi 把会话写成 JSONL每条记录带id和parentId这些字段让历史形成树。/tree可以在同一个会话文件里跳回历史节点并继续原来的后续记录仍然保留。需要生成独立会话时用/fork它从用户消息创建新的会话文件/clone则复制当前活动分支适合把当前状态完整带到另一份会话里。有了这些命令我们就可以根据需求来灵活的控制会话。命令结果/tree在同一会话文件中跳转历史节点并继续/fork从用户消息创建新的会话文件/clone复制当前活动分支到新的会话文件/export导出 HTML 或 JSONL/share上传为私有 GitHub Gist 并生成分享链接Pi 默认开启自动 compact也支持手动执行/compact。虽然压缩会丢失一部分上下文但完整历史仍保存在 JSONL 文件中。压缩后的会话适合继续当前任务想重新检查被压缩掉的细节时可以用 /tree 回到历史节点查看。图 5/tree打开的 Session Tree。比如在这次示例会话中我选中user你在跑什么这条历史消息然后按回车。Pi 先弹出Summarize branch?让用户在No summary、Summarize和Summarize with custom prompt之间选择。回退前多了一步确认因为选中节点后原节点后面的内容会成为待处理的分支。会话很长时是否摘要会影响接下来能看到的上下文不能顺手跳过。图 6选中历史节点后出现分支摘要选项。接下来输入的新消息会从这里继续原来节点后面的记录仍然保留。图 7导航回历史节点后的会话界面。这样就可以先保留第一种实现再从“你在跑什么”这个节点继续试第二种方案。两条路径都留在同一个会话文件里后面还能通过/tree来回切换。若想彻底分开成新会话再用/fork需要复制当前活动分支时用/clone。树形会话适合 agent 反复试错回退不会让原来的探索记录消失。树形会话解决的是探索路径问题但自由度越高用户承担的边界管理也越多。权限边界能力放进运行时之后问题也跟着变。安装什么、加载什么都会影响 Pi 能碰到的范围。Pi 的官方安全文档对权限边界写得很直接Pi does not include a built-in sandbox. Built-in tools can read files, write files, edit files, and run shell commands with the permissions of the pi process.Pi 默认以启动用户和进程的权限运行没有内置的运行时权限弹窗。不过 Pi 有 Project Trust 机制首次进入含项目资源的目录时会询问是否信任它只控制项目设置、资源、package 和扩展的加载不拦截后续的工具调用。read、write、edit、bash组合起来已经可以读取和修改本地文件、执行命令并通过命令访问外部服务。extension 还可以继续改变工具和运行时行为。使用 Pi 需要用户有一定的风险判断能力和预防意识因为你有可能遇到如下的风险场景风险处理方式安装陌生 packageextension 可以执行任意代码安装前检查源码、来源和维护情况进入陌生仓库项目资源可能改变 agent 能力先检查资源再决定是否进入该项目运行高风险命令启动用户权限可能过大使用低权限账户、容器或 Gondolin 等隔离环境只需要搜索代码暴露写入和执行能力没有必要使用pi --tools read,grep,find,lsPi 官方仓库提供了 Gondolin extension 作为隔离示例。需要更强边界时也可以把 Pi 放进自己管理的容器、虚拟机或低权限账户中运行。具体方案要按项目风险决定容器本身也不等于完整安全保证。如果只做代码搜索可以收窄工具面如果要安装第三方 package 或运行项目脚本就应该把源码审查和执行环境一起考虑。权限问题没有一个只靠配置文件就能解决的答案。权限只是其中一层成本启动时加载哪些规则和工具也会影响维护负担。上下文加载Pi 启动时不会把整个项目目录都读给模型而是先准备一组固定资源再随着任务推进加入会话历史、用户消息和工具结果。可以把这部分内容分成几类。类型加载内容作用系统提示默认 system prompt、.pi/SYSTEM.md、~/.pi/agent/SYSTEM.md、APPEND_SYSTEM.mdSYSTEM.md替换默认 system promptAPPEND_SYSTEM.md追加内容项目规则~/.pi/agent/AGENTS.md父目录和当前目录里的AGENTS.md或CLAUDE.md同目录的AGENTS.override.md加载项目约定AGENTS.override.md会替换同目录中的AGENTS.md或CLAUDE.md工具和扩展默认的read、write、edit、bash以及通过 extension 或 package 加入的工具告诉模型当前可以调用哪些能力会话状态session JSONL、当前活动分支和 compact 生成的摘要恢复已有会话继续当前任务当前交互用户消息、assistant 回复和工具结果推动当前这一轮工作项目规则文件不是只认当前目录。Pi 会先读取全局的~/.pi/agent/AGENTS.md再沿着当前工作目录向上查找父目录最后处理当前目录中的AGENTS.md或CLAUDE.md。某个目录存在AGENTS.override.md时它会替换该目录中的同名上下文文件其他目录的文件仍然会继续合并。这点和 Claude Code 很像只不过 Pi 原生适配的文件数量更多。系统提示文件是另一条入口。项目级.pi/SYSTEM.md和全局~/.pi/agent/SYSTEM.md用来替换默认 system promptAPPEND_SYSTEM.md用来追加内容。只想测试默认上下文时可以使用--no-context-files或-nc禁止加载项目上下文文件。Claude Code 也支持用--system-prompt替换、--append-system-prompt追加但替换内容要每次启动传入Pi 则可以用SYSTEM.md文件做持久替换。Pi 的初始上下文占用少最直观的原因是默认工具面很窄以及默认的系统提示词很小。Pi 也没有把 MCP、sub-agent、权限确认、plan mode 等工作流能力全部预装进核心。需要这些能力时再通过 extension、skill 或 package 加进去。用户需要自己配置和维护启动时则不用先加载暂时用不到的工具说明和工作流规则。Claude Code 则更加“稳重”即使用户还没有开始执行任务它也需要准备默认 system prompt、环境信息、内置工具说明、权限规则、CLAUDE.md、CLAUDE.local.md和 auto memory 等内容。配置了.claude/rules或 MCP 后启动上下文还会继续增加。所以Pi 初始上下文占用更少主要来自默认系统提示词小、默认能力更少、扩展按需加入Claude Code 初始上下文占用更多主要来自内置能力和项目级辅助机制更完整。但这是启动输入组成的差异不代表 Pi 在长会话中一定始终占用更少。这些设计差异最终会回到使用体验里尤其是第一次配置和调整工作流时。一个小实战下面看一次真实的配置和使用过程。开始时我先去 Pi 官方的 packages 安装页面按自己的工作流装了 MCP 适配、网络搜索等基本能力注意 package 里的 extension 会以本机进程权限运行安装前要检查来源、维护状态和源码没必要为了“功能完整”一次装很多装了自己需要的 extension、skill 和 MCP其中包括让 Pi 持续运行的pi-goal。packages下载需要的扩展装好后我让 Pi 配合 DeepSeek V4 Flash 做一个简单的番茄钟。我先用 Matt Pocock 的 grill-me skill 理清需求拿到最终的 goal prompt 后再交给 Pi 直接执行。Pi实战(1)执行过程中可以看到左下角显示的缓存命中率很高有时甚至会到 100%。Pi实战(2)整个过程大约 20 分钟。第一次 goal 得到的前端效果不太理想但功能完成得还不错。Pi实战(3)接下来我让 Pi 用 taste skill 优化前端。Pi实战(4)Pi实战(5)整个流程不需要太复杂和使用 Claude Code 和 Codex 时其实差不多。真正的差异落在配置责任上Pi 需要自己挑选并维护扩展能力。这次体验也反映了一个前置条件。使用者最好理解 harness 的基本构成并且已经形成自己的 AI coding 工作流。否则面对一个很小的默认核心很难判断该加什么、该信任哪些第三方 package。Pi 适合谁如果你想开箱即用、不愿维护工具和权限配置Claude Code、Codex 通常更省心。已经有一套稳定工作流希望从最小 agent 开始逐步增加能力Pi 会更合适之前积累的 MCP server 也可以通过 extension 或 package 接入。看到 Pi 在榜单上的成绩如此之强而且缓存命中率高、省钱可能你就会跟风去用它但我不建议刚接触 AI coding 的朋友直接把 Pi 当成第一入口。先用功能更完整的产品跑过真实项目知道自己常用哪些工具、哪些操作需要审批再来配置 Pi判断会具体很多最终的体验也会更好。就像前面所说的你需要有 AI coding 的使用经验帮助你列出真正需要的能力也需要有对 harness 的理解帮助你决定这些能力放进 extension、skill 还是外部环境。安装别人分享的 package 时这些经验也能帮助你判断权限范围和维护成本。总结如果 Claude Code 或 Codex 已经稳定覆盖你的工作流没有必要单纯为了换工具而迁移。Pi 需要更多配置和维护时间这部分成本是真实存在的。很多朋友喜欢用 Pi原因是四个默认工具让起点足够小extension 又允许按项目调整工具和规则。但是这里的自由度会伴随着权限审查、package 维护和故障回退的问题缺一项都可能把“可定制”变成新的麻烦。Pi 也适合用来学习 agent harness。它把模型接入、工具循环、TUI、会话后端分在几个相对清楚的 package 中扩展系统则内置于 coding-agent 包。想研究这些部分如何配合可以直接从仓库源码和官方文档开始。我也建议去读一下上面分享的AI Agents in Depth这本书它的第 2、4、5 章节和 Pi 的设计思想也有相似的地方。学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】