把 Pi Agent 说成底层引擎、把 Oh My Pi 说成装在上面的插件生态，这个说法很顺，却不准确。Oh My Pi 不是给 Pi 换主题、装插件的配置包，而是从 Pi 分叉出来的另一套 Coding Agent。它保留了 Pi 的骨架，随后在工具、代码理解、并行执行和交互层上走得很远。今天安装 pi 或 omp，得到的是两个可以独立运行的程序。

关系一旦说错，后面的“组合优势”就会变成一套不存在的安装方式。两个项目有意思的地方，其实是它们面对同一个问题，作出了几乎相反的产品选择。

大模型只负责根据输入生成下一段输出。要让它修改一个仓库，还需要有人替它保存会话、挑选上下文、描述工具、执行命令、把结果送回模型，并判断什么时候该停。这一整套运行环境通常叫作 Agent harness。模型决定上限，harness 决定它每天用起来究竟像工具，还是像事故源。

Pi Agent 到底指什么

Pi 最初由 Mario Zechner 开发，现在的正式名称是 Pi Agent Harness。仓库里的代码大致分成三层：

  • pi-ai 统一不同模型供应商的流式接口、消息格式和工具调用。
  • pi-agent-core 实现有状态的 Agent 循环、工具执行和事件流。
  • pi-coding-agent 把前两层装进终端，补上会话、上下文压缩、文件工具、TUI 以及 SDK、RPC 等接入方式。

所以“Pi Agent”有时指底层的 pi-agent-core，更多时候指终端里运行的 pi Coding Agent。讨论功能前最好先问一句说的是哪一层。一个应用可以只引用 core 自己做界面，也可以直接启动完整的 pi。

Pi 的默认工具并不花哨：read、write、edit 和 bash。仓库还提供 grep、find、ls 等工具，并允许用启动参数精确启停。它的赌注是，现代代码模型已经很熟悉文件和 shell，不必为每种动作都创造一套新的抽象。

先跟一遍循环，再谈“自主”

用户输入“找出订单测试偶发失败的原因并修复”之后，Pi 不会先调用一个名为“任务拆解”的神秘模块。Agent core 把系统提示、历史消息、项目说明和工具定义交给模型。模型可能先要求读取测试文件；Pi 执行 read，把结果记成一条 toolResult，随后再次调用模型。只要模型继续提出工具调用，这个循环就继续。

图 1：Pi Agent core 的基本循环。所谓“自主”，主要发生在模型每次看完结果后选择下一步。
输入目标、历史、项目规则
整理上下文裁剪、转换消息
调用模型文字或工具请求
执行工具读文件、编辑、bash
写回结果形成 toolResult
继续或结束由下一次模型输出决定

麻烦都藏在循环的边角。工具参数要校验；并行工具的结果要按可预测的顺序写回；UI 需要在模型流式输出、工具开始和工具结束时收到事件；上下文快满时还要压缩历史。Pi 把这些事收进 core，“Agent”在这里没有额外的任务管理含义。

Pi 的会话可以保存、恢复和分支，长对话也会做 compaction。但会话历史和长期记忆不是一回事。前者解决“这次工作做到哪了”，后者解决“下个月的新会话还应记得什么”。原版 Pi 没有默认附送一套会自动积累用户事实的长期记忆库，也没有一个固定的“自省模块”。你可以用 extension 或 skill 加入这些行为，但不该把扩展能力倒写成核心特性。

轻量是一种产品取舍

Pi 最有辨识度的地方，是它在项目理念里公开列出了一批“不做”的功能：不内置 MCP，不内置 sub-agent，不内置 plan mode，也不弹出统一的权限确认框。需要 MCP 可以装扩展；需要多个 Agent 可以启动多个 Pi 进程或选择社区包；需要强隔离则把整个进程放进容器或沙箱。

Pi 没有否定这些能力，只是不替用户决定实现方式。一个团队习惯用 tmux 观察后台任务，另一个团队要求所有命令经过策略引擎，第三个团队只允许在临时容器里写文件。三套需求硬塞进同一个默认实现，往往谁都不满意。

可扩展性由四种资源承担：

  • Prompt template 保存可重复调用的提示文本；
  • Skill 保存某类任务的做法和按需加载的说明；
  • Extension 是 TypeScript 模块，可以注册工具、命令、快捷键、事件处理和界面组件；
  • Pi package 把 extension、skill、prompt 和主题打包，通过 npm 或 Git 分发。

这种设计对喜欢自己搭工作台的人很有吸引力，也有明确代价。Pi 官方文档直接提醒：进程默认继承启动用户的文件、网络、进程和凭据权限；第三方 package 也能执行任意代码。扩展性不是安全边界。安装一个看起来无害的主题包之前，仍然要看它实际包含了什么。

当前的安装方式

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

旧的 @mariozechner/pi-coding-agent 包没有被删除，但已经停止在旧命名空间继续发布。新安装应使用上面的 Earendil Works 包名。

先别把 Oh My Pi 当成配置包

Oh My Pi 这个名字自然会让人想到 Oh My Zsh：装完就有一套整理好的默认配置和插件。只看使用感受，这个联想不算离谱；从工程关系看，它会造成误会。

Oh My Pi（命令是 omp）由 Can Bölük 基于 Pi 创建，项目 README 写得很直接：fork of Pi。它从 Pi 的代码基础出发，独立修改并发布自己的包。如今差异已经深入 agent core、coding agent、TUI 和原生运行时，早已超出“挂几项插件”的范围。

图 2：两条代码分支分别演进，运行时没有上下层关系。
共同起点：Pi

模型适配、Agent loop、会话、终端界面和扩展接口构成最初骨架。

↗
Pi

继续保持可塑的最小核心。许多能力由用户选择扩展或外部工具。

／
Oh My Pi

把代码智能、调试、搜索、浏览器、子 Agent 和原生工具做成完整默认工作台。

“先安装 Pi，再安装 Oh My Pi 增强包”走不通。你通常要在 pi 和 omp 之间选一个主程序。二者的扩展思想和部分接口有血缘关系，但包名、内部实现和发布节奏已经分开。某个 Pi package 能否装进 OMP，需要逐项确认。

OMP 的安装入口

# macOS / Linux 安装器
curl -fsSL https://omp.sh/install | sh

# 或使用 Bun
bun install -g @oh-my-pi/pi-coding-agent

omp
/login

Oh My Pi 把精力花在了哪里

Pi 交付一张可靠的工作台，OMP 则把 IDE、调试台和工具车一起推进来。它把主要能力直接放进默认发行版，花力气缩短“模型想做一件事”到“机器可靠地做完”之间的距离。

编辑代码：Hashline 处理的是定位问题

常见的字符串替换工具依赖模型完整复述旧文本。文件稍有变化、缩进少一个空格，替换就失败；模型接着重读、重试，Token 和时间一起浪费。OMP 的 Hashline 编辑格式给文件内容生成锚点，模型引用锚点描述修改。锚点过期时，工具直接拒绝补丁，避免改错位置。

OMP README 给出了不同模型在自家编辑基准上的提升数据。看这些数字要留一点余地：项目方基准可以证明团队在认真测编辑协议，却不能保证每个仓库都得到同样的涨幅。Hashline 更有价值的变化，是把“锚点已失效”变成一种可检测的失败。

可检测不等于没有代价。设想一个改动频繁的 monorepo：Agent 读完文件取得锚点，另一个进程随即运行代码生成器，或者同事的同步任务改写了同一文件。第一次拒绝补丁很正常，重新读取再算一次就好。连续两三次都撞上 stale anchor，继续自动重试通常只会烧掉上下文和 Token。这时该停下来查谁在写文件，而不是把重试次数调到十次。

下面是这条失败路径的终端示意，用来说明机制，并非实际会话录屏：

you  修复 packages/api/src/router.ts 的竞态条件

omp  read router.ts                   # 得到带 hash 的行锚点
omp  edit 84:af31 ...                 # rejected: anchor is stale
omp  read router.ts                   # 文件刚被 codegen 改写
omp  edit 87:922c ...                 # rejected: anchor is stale

you  先停。检查 watch/codegen 进程，不要继续重试。

代码理解：把 IDE 已知的信息交给模型

只靠文本搜索可以找到变量名，却不知道它究竟引用哪个符号。OMP 把 LSP 接到工具层，模型可以请求定义、引用、诊断、重命名和 code action。写入文件后，语言服务器的错误可以立刻回到 Agent 循环。碰到运行时问题，还可以通过 DAP 查看线程、堆栈和变量，少做几轮靠日志猜原因的尝试。

LSP 也有自己的脾气。索引尚未完成时，查引用可能漏结果；生成代码、宏和高度动态的调用，语言服务器本来就未必看得全；刚写完文件立刻取 diagnostics，有时读到的还是上一版。Agent 需要识别“没有诊断”和“代码正确”之间的差距，最终判断仍应落到编译和测试上。

执行环境：shell 之外还有可回调工具的代码单元

eval 提供持久的 Python 和 JavaScript 运行环境。单元格里的程序还能重新调用 Agent 已有的 read、search、task 等工具。一段分析代码可以自行读取文件、清洗表格、生成图表，大块中间数据不用反复塞回模型上下文。

子 Agent 怎么落地

OMP 把 sub-agent 做成一等工具。主 Agent 可以把互不依赖的调查任务并发交给多个工作单元，为它们分配隔离工作区，并用结构化结果收回结论。Agent Hub 用来观察、干预、终止或恢复这些任务。另一个 advisor 角色则可以用独立模型旁观主 Agent 的每一步，在发现问题时插入意见。

多 Agent 会放大吞吐，也会放大费用和冲突。一个问题本来只需读三个文件，拆成四个 Agent 往往更慢；只有搜索空间能真正分开，或者需要独立复核时，并发才有意义。

工作区隔离只能避免几个进程同时踩同一份文件，不能替你解决语义冲突。两个 sub-agent 分别修改数据库 schema 和调用方，单看各自测试都可能通过，合起来却缺一段迁移。主 Agent 收回结果后还得重新跑集成验证。把“并发完成”直接当成“可以合并”，是多 Agent 流程里最危险的省略。

浏览器、搜索、记忆与外部协议

OMP 内置网页搜索、浏览器和桌面控制，也能发现已有配置中的 MCP Server。它的本地 SQLite 记忆引擎提供 retain、recall、reflect 和 memory edit 等操作，不过记忆工具默认关闭，需要明确配置后才会出现。这样的默认值是合理的：长期记忆牵涉保留范围、错误修正和隐私，不适合悄悄开启。

OMP 的主要交互面仍是终端 TUI。它可以通过 SDK 嵌入 Node/Bun 程序，通过 RPC 给其他进程调用，也能用 ACP 接入编辑器；/collab 还可以把实时会话分享给别人。Browser 工具负责操作网页，协作页负责旁观或共同控制会话；项目没有附送通用 Web 管理后台。

图 3：一次较完整的 OMP 修复链路。并非每次任务都会走满这些步骤。
1理解现场读取失败日志和相关文件，用 grep、AST 摘要或 LSP 缩小范围。
2验证猜测运行最小测试；必要时启动 DAP，检查实际堆栈和变量。
3修改用 Hashline 锚点提交编辑；锚点过期就停止并重新读取。
4静态反馈LSP 返回诊断、引用变化和重命名影响。
5运行验证执行针对性测试，再跑约定的 lint、类型检查或完整测试。
6复核复杂改动可以交给 reviewer sub-agent；最终是否提交、发布仍由工作流和权限决定。

共同血缘能带来什么

所谓“化学反应”发生在项目演化上。Pi 先做出一个小而开放的 Agent harness，让用户自己定义工作流；OMP 接过这副骨架，继续试验代码编辑、LSP、调试、搜索和多 Agent 能否被调成一套顺手的默认配置。

它们会互相影响，社区扩展也可能在两边移植。用户还能把相同的 AGENTS.md、skills、模型供应商和外部 CLI 带到不同工具中。两个有共同祖先的操作系统发行版，也常会共享理念和文件格式；用这个类比理解二者更接近现状。

问题PiOh My Pi
基本取向核心尽量小，把选择权留给 extension、skill 和外部环境把高频的 Coding Agent 能力整合、调优后直接交付
默认工具面文件、编辑、shell 为主文件和 shell 之外，加入 LSP、DAP、浏览器、搜索、代码执行、sub-agent 等
长期记忆不是默认核心能力，可自行扩展提供本地记忆引擎和工具，但默认关闭
MCP官方刻意不内置，通过 extension 接入可以发现和使用 MCP Server 配置
维护感受要自己挑选、理解和维护组合开箱能力多，同时承受更大的配置面和更快的变化
二次开发Extension、Package、SDK、RPCExtension、marketplace/npm、SDK、RPC、ACP

三个场景，差别会更具体

代码修复与运维排障

这是 OMP 最贴近自身定位的场景。一个跨模块重命名可以先查 LSP 引用，再执行 rename，写入后立即读取诊断；一个原生进程崩溃可以接调试器，而不是猜堆栈。若问题可以拆成“定位回归提交”“检查日志”“审查修复”三条独立线索，再让 sub-agent 并行调查。

Pi 也能完成这类工作，而且简单问题未必更慢。团队如果已经有成熟的 CLI、测试脚本和容器环境，Pi 的 bash 加少量 skill 可能已经够用。不要因为 OMP 有三十多种工具，就要求每次修复都把它们走一遍。

个人知识库与资料整理

OMP 可以搜索网页、读取页面和 PDF，再把整理结果写进本地笔记；启用记忆后，还能保留经过筛选的事实。做久了以后，麻烦会集中在资料来源能否追溯、旧结论怎样失效，以及哪些隐私内容不该进入长期记忆。

Pi 的做法更像搭积木：选定抓取 CLI 或 API，写一个 skill 规定引用和落盘格式，需要时再用 extension 增加工具。第一次配置会慢些，之后的行为却更容易按个人习惯收紧。

数据分析与报表

OMP 的持久 Python/JavaScript 单元适合探索数据，尤其是代码可以回调 read、search 等工具时，大文件不必整份进入模型上下文。Pi 则可以直接调用项目已有的 Python、R、DuckDB 或 shell 脚本。两边都能做，但报表一旦进入每天固定运行、必须可追溯的生产流程，就应该把稳定步骤写成普通 Workflow，让 Agent 只处理异常解释和临时调查。

我会怎么选

如果目标是把 Agent 嵌入公司内部平台，我会先看 Pi。理由很实际：需要接进现有 CI、容器、审计和权限系统时，一个边界清楚的 core 比三十个现成工具更省事。团队可以只暴露允许的能力，不必先关闭一堆用不到的默认项。

如果只是想在终端里尽快得到一套能干活的重型工作台，我会先试 OMP。LSP、调试、浏览器、搜索和 sub-agent 都已经接好，省下的是收集扩展和磨合工具的时间。账不会消失，只是晚点结：工具越多，升级时要看的 changelog 越长，某项默认行为变化时排查范围也越大。

还有一条比功能表更实际的判断：团队能否承担它的安全面。Pi 默认继承用户权限；OMP 能调用的系统能力更多，即使加入审批声明和工作区隔离，也不能把提示词当沙箱。生产凭据、发布权限和不可逆操作仍应放在 Agent 进程之外，由容器、操作系统权限、CI 审批和后端授权真正限制。

“Digital Human” 和 “Super Agent” 这类名字还会继续换。几年后仍要维护的，多半是那些不炫目的部件：可替换的模型接口、可观察的循环、稳定的工具协议、受控的执行环境、能迁移的 skills，以及出了错可以重放的会话。Pi 把组装权交给使用者；OMP 选择把工具链做深。它们的分歧比任何“终极助手”口号都更有参考价值。

没有哪条路线天然正确。先知道自己要交给 Agent 哪些权限、哪些决策，再选工具，通常比先被功能列表打动更可靠。

参考资料