Pi 极简 harness：与 Claude Code 的差异及 DeepSeek 实战

说明：本文关于 Pi 的定位、工具集、扩展层、会话机制、权限边界等内容，主要转述自一篇社区文章（来源类型为 community_signal），未与 Pi 官方原文逐条比对。涉及 DeepSeek Harness 的部分同样来自社区文章，属于社区主张，不代表官方确认。文中评测数据与实战数据均为特定条件下的结果，不构成通用结论。

Pi 是什么

据社区文章转述，Pi 官网将其定位为 minimal agent harness，用于组织模型、工具、上下文、会话和终端交互，让 agent 具备在项目中工作的基本能力，使用者再根据自己的工作流调整这个 harness。

社区文章提到，官网用两句话概括这套设计：Primitives, not features 强调基础构件优先，尽量少预置功能；Adapt Pi to your workflows, not the other way around 表示工作流应该决定 Pi 的形态。

安装方式据称是在官网首页选择适合自己环境的安装方式，完成后在终端输入 pi 启动。

Pi 和其他 coding agent 最大的不同

Claude Code、Codex 也有各自的 harness，但它们预置的产品能力更多，用户可以直接使用权限控制、计划模式等功能。据社区文章描述，Pi 把稳定、通用的部分留在核心，其余能力放到扩展层。两种路线没有绝对高下，差别主要在默认能力和配置成本。

最小工具集

社区文章称，在 coding agent 形态下，Pi 默认只给模型 read、write、edit、bash 四个工具。

grep、find、ls 据称也是内置工具，只是不默认开启。

社区文章给出的启用示例：

pi --tools read,grep,find,ls -p "Review the code"

据称还能用 --exclude-tools 禁用单个工具，用 --no-builtin-tools 关掉全部内置工具，同时保留 extension 和自定义工具。

社区文章作者猜测，默认的 bash 已经覆盖了大部分 shell 能力，这三个专用工具和它有重叠。这属于作者个人推测，并非官方解释。

社区文章还引用了 Composio 和 Databricks 的评测，称 Pi 在一些任务上的表现能和 Codex、Claude Code 接近甚至超越。需要说明的是，这些评测的具体评测对象、任务数量、任务口径和统计方式，社区文章并未完整交代，因此只能理解为特定条件下的结果，不能推广为通用结论。

扩展层

据社区文章描述，从功能更完整的 Claude Code、Codex 等 coding agent 切过来时，第一眼会觉得 Pi 少了很多东西。固定提示、专用工具、权限控制，以及 MCP、sub-agent、权限确认、plan mode、内置待办和后台 Bash，这些都没有直接放进 Pi 核心，而是放在扩展层，由 extension、skill、prompt template 和 package 解决。

社区文章转述官网的一句话：

Pi isn't a sealed product. If you need a command, tool, provider, workflow, or UI tweak, just ask Pi to build it.

这四种方式处理的事情并不相同。

社区文章称，官方文档允许 extension 实现自定义工具、子代理、计划模式、权限控制、会话压缩、沙箱和 MCP 等能力。安装一个 package 之前，应该先看源码和维护状态，避免下载到有安全隐患的包。

与 DeepSeek Harness 的设计理念对比

社区文章提到，DeepSeek 开源了一个名为 DeepSeek Harness 的 agent 框架，其理念是 Everything is a plugin（一切皆插件）。需要强调，这一说法目前仅见于社区文章，尚未与 DeepSeek 官方仓库或官方文档核对，因此只能作为社区主张看待，不能当作已核验的官方事实。

按社区文章的对比，Pi 和 DSH 都没有把所有能力固定在核心里，但所关注的问题不同。

Pi 关注的是一个 coding agent 的默认核心可以缩到什么程度。它先提供一套能够直接工作的最小 harness，再把额外工具和工作流能力放到扩展层。使用者从稳定的默认入口开始，根据自己的需求逐步增加能力。

DSH 关注的是一个 agent runtime 的各个部分能否拆开、替换和重新组合。比如模型接入、会话存储、循环调度和界面，这些都可以作为插件被替换或重新组合。它把 runtime 看成一个可编排的系统，重点不是提供一套固定的最小入口，而是让使用者能够调整 agent 的组成方式。

因此，按社区文章的说法，Pi 更像是从一个小而完整的 coding agent 出发，逐步向外扩展；DSH 则是从可组合的 runtime 出发，重新组织 agent 的各个部分。

这两套设计理念没有绝对高下。已经有明确 coding 工作流、想从小核心开始调整，Pi 更直接；想研究 agent runtime 的组成方式，或希望替换更多底层模块，DSH 的思路更适合。具体能力和使用方式，建议分别查看它们的官方文档。

Pi 用起来最特别的地方

树形会话

据社区文章描述，Pi 把会话写成 JSONL，每条记录带 id 和 parentId，这些字段让历史形成树。/tree 可以在同一个会话文件里跳回历史节点并继续，原来的后续记录仍然保留。需要生成独立会话时用 /fork，它从用户消息创建新的会话文件；/clone 则复制当前活动分支，适合把当前状态完整带到另一份会话里。

社区文章称，Pi 默认开启自动 compact，也支持手动执行 /compact。虽然压缩会丢失一部分上下文，但完整历史仍保存在 JSONL 文件中。压缩后的会话适合继续当前任务，想重新检查被压缩掉的细节时，可以用 /tree 回到历史节点查看。

社区文章描述了一次示例：选中 user：你在跑什么 这条历史消息后按回车，Pi 先弹出 Summarize branch?，让用户在 No summary、Summarize 和 Summarize with custom prompt 之间选择。回退前多了一步确认，因为选中节点后，原节点后面的内容会成为待处理的分支。会话很长时，是否摘要会影响接下来能看到的上下文。

接下来输入的新消息会从这里继续，原来节点后面的记录仍然保留。这样就可以先保留第一种实现，再从同一个节点继续试第二种方案。两条路径都留在同一个会话文件里，后面还能通过 /tree 来回切换。若想彻底分开成新会话，再用 /fork；需要复制当前活动分支时，用 /clone。树形会话适合 agent 反复试错，回退不会让原来的探索记录消失。

树形会话解决的是探索路径问题，但自由度越高，用户承担的边界管理也越多。

权限边界

社区文章转述了 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 官方仓库提供了 Gondolin extension 作为隔离示例。需要更强边界时，也可以把 Pi 放进自己管理的容器、虚拟机或低权限账户中运行。具体方案要按项目风险决定，容器本身也不等于完整安全保证。

如果只做代码搜索，可以收窄工具面；如果要安装第三方 package 或运行项目脚本，就应该把源码审查和执行环境一起考虑。权限问题没有一个只靠配置文件就能解决的答案。

上下文加载

据社区文章描述，Pi 启动时不会把整个项目目录都读给模型，而是先准备一组固定资源，再随着任务推进加入会话历史、用户消息和工具结果。

社区文章称，项目规则文件不是只认当前目录。Pi 会先读取全局的 ~/.pi/agent/AGENTS.md，再沿着当前工作目录向上查找父目录，最后处理当前目录中的 AGENTS.md 或 CLAUDE.md。某个目录存在 AGENTS.override.md 时，它会替换该目录中的同名上下文文件，其他目录的文件仍然会继续合并。

系统提示文件是另一条入口。据社区文章描述，项目级 .pi/SYSTEM.md 和全局 ~/.pi/agent/SYSTEM.md 用来替换默认 system prompt，APPEND_SYSTEM.md 用来追加内容。只想测试默认上下文时，可以使用 --no-context-files 或 -nc 禁止加载项目上下文文件。

社区文章认为，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 或 DeepSeek 的官方评价。

开始时，作者先去 Pi 官方的 packages 安装页面按自己的工作流装了 MCP 适配、网络搜索等基本能力（注意 package 里的 extension 会以本机进程权限运行，安装前要检查来源、维护状态和源码，没必要为了“功能完整”一次装很多），装了自己需要的 extension、skill 和 MCP，其中包括让 Pi 持续运行的 pi-goal。

需要的扩展装好后，作者让 Pi 配合 DeepSeek V4 Flash 做一个简单的番茄钟。先用 Matt Pocock 的 grill-me skill 理清需求，拿到最终的 goal prompt 后再交给 Pi 直接执行。

执行过程中，作者观察到左下角显示的缓存命中率很高，有时甚至会到 100%。整个过程大约 20 分钟。第一次 goal 得到的前端效果不太理想，但功能完成得还不错。接下来作者让 Pi 用 taste skill 优化前端。

需要再次说明，缓存命中率、耗时等均为作者单次实测结果，受任务类型、模型版本、网络环境、缓存状态等多种因素影响，不能作为普遍性能指标。

选型建议

Pi 适合已有明确 coding 工作流、想从小核心开始调整的人，代价是需自己维护扩展边界和权限风险。Claude Code 预置权限控制、计划模式等，开箱即用程度更高，但启动上下文组成更完整、可调整的核心更少。

只做代码搜索可用 pi --tools read,grep,find,ls 收窄工具面；安装第三方 package 或运行项目脚本时，应把源码审查和执行环境一起考虑。想研究 agent runtime 组成或替换更多底层模块，可再查看 DeepSeek Harness 的插件化思路，但需注意其官方资料尚未在本文中核验。

OMP 据社区文章称是 Pi 的一个 fork，此前有文章聊过使用和接 DeepSeek，本文回到 Pi 本身讨论 harness 设计。