oh-my-pi

一个内置 IDE 的编程 agent。 omp.sh

Fork of Pi by @mariozechner

功能最强大的开箱即用 agent 界面。经实际使用持续调优——开箱即用，完全开放。

40+ 提供商 · 32 内置工具 · 13 个 LSP 操作 · 27 个 DAP 操作 · ~27k 行 Rust 核心代码。

安装

macOS · Linux

curl -fsSL https://omp.sh/install | sh

Bun（推荐）

bun install -g @oh-my-pi/pi-coding-agent

Windows（PowerShell）

irm https://omp.sh/install.ps1 | iex

固定版本（mise）

mise use -g github:can1357/oh-my-pi

macOS · Linux · Windows · bun ≥ 1.3.14

每个工具，极致优化。

首次尝试即成功的编辑。概括文件而非倾倒内容的读取。瞬间返回的搜索。选择任意模型——omp 都能做到。

model	metric	what
Grok Code Fast 1	6.7% → 68.3%	编辑格式不再吞噬模型后，性能提升十倍。
Gemini 3 Flash	+5 pp	超越 str_replace——击败 Google 自身对该格式的最佳尝试。
Grok 4 Fast	−61% tokens	当糟糕 diff 的重试循环消失后，输出大幅缩减。
MiniMax	2.1×	通过率翻倍多。相同权重，相同提示词。

• read：摘要片段 · 理想默认值 · 选择器命中率
• search：西方最快
• lsp：IDE 所知的一切，agent 都知道
• prompts：为每个模型持续调整

阅读完整博文 ↗

你喜爱的 Pi，功能齐全。

基于 Mario Zechner 出色的 Pi 构建，omp 增添了你所缺失的一切。

01 · 带工具调用的代码执行

多数 harness 给 agent 一个 Python 沙箱就完事了。我们的方案运行持久化 Python 和 Bun worker，并且两个内核都可以通过回环桥调用 agent 自身的工具——read、search、task。agent 在 Python 内部使用 tool.read 加载 CSV，用 JavaScript 绘制图表，全程不离开所在 cell。

02 · LSP 集成至每次写入

请求重命名，就能得到重命名。调用通过 workspace/willRenameFiles 进行，因此在文件移动之前，重新导出、barrel 文件和别名导入都已更新。IDE 所知的一切，agent 同样知晓。

03 · 驱动真实调试器

C 程序段错误：agent 附加 lldb，逐步定位到坏指针，读取栈帧。Go 服务挂起：它附加 dlv 并遍历 goroutine。Python 进程僵住：debugpy、暂停、检查、求值。多数 agent 仍在使用打印语句。

观看演示 ↗

04 · 时间回溯流规则

你的规则平时休眠，直到模型偏离脚本时才激活。正则匹配在 token 中间中止流，将规则以系统提醒形式注入，并从同一点重试。你获得方向修正，无需在每个轮次支付上下文开销。注入在压缩后仍然保留，因此修正得以持久。

观看演示 ↗

05 · 头等公民子 agent

将任务拆分给多个 worker，并获得类型化结果返回。task 分发到隔离的工作树，每个 worker 运行自己的工具界面，最终产出是一个 schema 验证的对象，父 agent 可以直接读取。无需解析文本，兄弟 worker 间没有合并冲突，没有遗弃的编辑。

观看演示 ↗

06 · 读取 arxiv 上的 PDF，有何不可？

web_search 链接十四家排名提供商，并将找到的 URL 直接交给 read。arXiv 的 PDF、GitHub 页面、Stack Overflow 线程以结构化 markdown 返回，锚点保持完整——与你处理本地文件时使用的同一工具界面。引用、跟踪、引用，永远不会丢失来源。

观看演示 ↗

07 · 毫不掩饰的原生实现。即使在 Windows 上。

其他 agent 通过 shell 调用 rg、grep、find 和 bash。很多机器上这些二进制文件并不存在，而在存在的机器上，每次调用都产生一次 fork-exec 往返。omp 将真实实现链接到进程中。ripgrep、glob、find：都在进程中。brush 是 bash，会话跨调用保持。同一个 omp 二进制在 macOS、Linux 和 Windows 上运行——无需 WSL 桥接。

08 · 带优先级和判决的代码审查

获得关于变更是否可发布的清晰裁决，每个问题按 P0 到 P3 排序并附有信心评分。/review 启动专用的审查员子 agent，并行扫描分支、单个 commit 或未提交的工作。你优先处理阻碍发布的问题；重要信息不会隐藏在一大段文字中。

09 · Hashline：基于内容哈希的编辑

完美编辑，更少 token。模型指向锚点，而不是重新输入它想要更改的行，因此空白符冲突和字符串未找到循环不再发生。编辑过时的文件时，锚点会分歧——我们在补丁破坏任何内容之前就拒绝它。Grok 4 Fast 在相同工作上少花费 61% 的输出 token。

10 · GitHub 只不过是一个文件系统

其他 harness 附加 gh_issue_view、gh_pr_view、gh_search——每个都有自己的参数，agent 需要学习，你需要调试。我们跳过了这一步。read 已经能够处理路径；PR 就是路径。一个接口教会模型，一个表面保持正确。

11 · Hindsight：agent 策划的记忆

agent 在会话之间记住你的代码库。它在运行期间使用 retain 写入事实，使用 recall 拉回，并将每个会话压缩成一种心智模型，在下一个会话的第一轮加载。默认限定项目范围，因此它对此仓库学到的内容留在此仓库。

12 · ACP：编辑器驱动的 agent

在 Zed 内运行 omp，你将获得与在终端中驱动相同的 agent——读取你实际在查看的缓冲区，通过编辑器的保存路径写入，在编辑器的终端中生成 shell。破坏性工具会暂停，弹出一个权限提示，你可以一次性确认后不再打扰。无需桥接、无需插件、无需保持同步的第二个大脑。

13 · 继承你的其他工具已经写入的内容

其他每个 agent 都附带一个导入器，期望你去转换。omp 以原生格式读取磁盘上已有的八种格式——Cursor MDC、Cline .clinerules、Codex AGENTS.md、Copilot applyTo 等。无需迁移脚本、无需 YAML 到 TOML 的移植、没有"支持的子集"脚注。你的团队上个季度编写的配置今晚仍然有效。

14 · omp commit：原子拆分，验证过的提交信息

omp 通过 git-overview、git-file-diff 和 git-hunk 读取工作树，然后将不相关的变更拆分为依赖于它们的原子提交。在写入任何内容之前会拒绝循环。源文件的得分高于测试、文档和配置，因此标题提交是最重要的一项。锁定文件被完全排除在分析之外。

15 · 读取 PR。演练技能。 从子 agent 中提取 JSON。

十个内部方案——pr://、issue://、agent://、skill://、rule:// 等——在 agent 已经调用的每个类 FS 工具中透明地解析。read pr://1428 返回与 read src/foo.ts 相同的形状。search 像遍历目录一样遍历 diff。agent://<id>/findings.0.path 通过路径从子 agent 的输出中提取字段。

16 · 冲突解决，很轻松。

每个合并冲突变成一个 URL。agent 将 @theirs、@ours 或 @base 写入 conflict://N，文件干净地解决。批量形式：conflict://*。

观看演示 ↗

17 · 预览，然后接受。

ast_edit 返回一个 (proposed) 卡片，包含替换数量。变更被暂存。agent 调用 resolve 并附上原因；TUI 将其变成一个 Accept 卡片，然后执行磁盘移动——原子性，全有或全无。

观看演示 ↗

18 · 驱动真正的浏览器。或者你的 Slack？

Stealth 默认开启，因此页面看到的是普通用户而非无头机器人。同样的 API 可以驱动任何 Electron 应用——将其指向 Slack，agent 读取你的 DM 如同读取网页一样。

无论任务需要什么，都已内置在盒子里。

32 个工具与 read 和 bash 处于同一命名空间。使用 --tools read,edit,bash,… 固定激活集，其余工具保持隐藏但可索引——当 tools.discoveryMode 启用时，search_tool_bm25 会在会话中间将它们召回。

文件与搜索

• read —— 文件、目录、归档、SQLite、PDF、notebook、URL 以及内部 :// 方案，通过一个路径。
• write —— 创建或覆盖一个文件、归档条目或 SQLite 行。
• edit —— 基于内容哈希锚点的 hashline 补丁，带过期锚点恢复。
• ast_edit —— 结构重写，应用前可预览，基于 ast-grep。
• ast_grep —— 结构代码查询，支持 50+ 种 tree-sitter 语法。
• search —— 基于正则的文件、glob 和内部 URL 搜索。
• find —— 基于 glob 的路径查找；需要内容匹配时请使用 search。

运行时

• bash —— 工作区 shell，可选 PTY 或后台任务调度。
• eval —— 持久化 Python 和 JavaScript 单元，带共享前导和工具重入。
• recipe —— 调用检测到的任务运行器中的目标——bun、just、make、cargo。
• ssh —— 对配置主机执行一条远程命令。

代码智能

• lsp —— 诊断、导航、符号、重命名、代码操作、原始请求。
• debug —— 驱动 DAP 会话——断点、单步、线程、栈、变量。

协调

• task —— 并行分发子 agent，可选工作区隔离。
• irc —— 进程内活跃 agent 之间的简短文本。
• todo_write —— 对会话待办列表的顺序变更，带阶段跟踪。
• job —— 等待或取消后台作业。
• ask —— 交互式运行的结构化后续问题。

外部

• browser —— 通过 headless Chromium 或 CDP 附加应用的 Puppeteer 标签页。
• web_search —— 跨配置提供商的一次查询，返回答案加引用。
• github —— GitHub CLI 操作——仓库、PR、issues、代码搜索、Actions 运行监控。
• generate_image —— 通过 Gemini 图像模型生成或编辑栅格图像。
• inspect_image —— 对本地图像文件的视觉模型分析。
• render_mermaid —— Mermaid 源码转为终端友好的 ASCII 或 PNG。

记忆与状态

• checkpoint —— 标记对话状态，用于后续折叠并报告。
• rewind —— 修剪探索性上下文，保留简洁报告。
• retain —— 将持久性事实入队到活跃的 Hindsight 存储。
• recall —— 在 Hindsight 存储中搜索原始记忆。
• reflect —— 请求 Hindsight 基于存储综合出答案。

杂项

• calc —— 确定性算术——无需模型参与。
• resolve —— 应用或丢弃一个已排队的预览操作。
• search_tool_bm25 —— 对隐藏工具索引进行 BM25 搜索；在会话中间激活最佳匹配。

可通过设置控制，默认关闭：github、calc、inspect_image、render_mermaid、checkpoint、rewind、search_tool_bm25、retain、recall、reflect。每个项目设置一次即可启用。

完整参考 →

四十多家提供商，数百个模型，一个 /model 搞定。

角色按意图路由工作。default 用于常规轮次。smol 用于廉价子 agent 分发。slow 用于深度推理。plan 用于计划模式。commit 用于更新日志。启动时使用 --smol、--slow 或 --plan 覆盖；通过 Ctrl+P 循环当前角色已配置的模型；使用 /model 斜杠命令在会话中间切换活跃模型。

以下认证标签：oauth 通过提供商账户登录，plan 通过编码计划订阅路由，local 针对本地服务器运行，密钥可选。

前沿 API

直接 API 和网关。每个角色可混合提供商。

Anthropic oauth · OpenAI · OpenAI Codex oauth · Google Gemini · Google Antigravity oauth · xAI · Mistral · Groq · Cerebras · Fireworks · Together · Hugging Face · NVIDIA · OpenRouter · Synthetic · Vercel AI Gateway · Cloudflare AI Gateway · Perplexity oauth

编码计划

订阅路由。/login 附加会话。

Cursor oauth · GitHub Copilot oauth · GitLab Duo · Kimi Code plan · Moonshot · MiniMax Coding Plan plan · MiniMax Coding Plan CN plan · Alibaba Coding Plan plan · Qwen Portal · Z.AI / GLM Coding Plan plan · Xiaomi MiMo · Qianfan · NanoGPT · Venice · Kilo · ZenMux · OpenCode Go · OpenCode Zen

自己运行

兼容 OpenAI 的 /v1/models。本地实例可跳过密钥。

Ollama local · Ollama Cloud · LM Studio local · llama.cpp local · vLLM local · LiteLLM

使路由有用的四个旋钮

• 自定义提供商 —— 在 ~/.omp/agent/models.yml 中声明任何支持 openai-completions、openai-responses、openai-codex-responses、azure-openai-responses、anthropic-messages、google-generative-ai 或 google-vertex 协议的服务。
• 回退链 —— 每个角色在 retry.fallbackChains 下设置回退链。当主提供商返回 429 或达到配额限制时，下一个条目接管当前轮次——冷却后恢复。
• 路径作用域角色 —— 在 modelRoles 下嵌套 paths:，可将更重的 default 模型绑定到一个仓库而无需修改全局配置。最近的路径获胜。
• 轮询凭据 —— 按提供商堆叠 API 密钥，运行时在会话亲和性和每个凭据的退避机制下轮转。当单个密钥在午前就会耗尽配额时非常有用。

完整提供商及路由参考请访问 omp.sh/docs/providers。

十四个后端。一个 agent 已经知晓的工具。

web_search 是内置的，不是附加的。auto 遍历十四个提供商的链；如果你已经为哪家付费，可以按名称固定它。每次命中背后，站点感知提取将 GitHub、注册表、arXiv、Stack Overflow 和文档转化为结构化 markdown——锚点和链接目标完整保留。

搜索提供商

十四个后端。固定一个，或让 auto 依次遍历链。

provider	auth
auto	chain
exa	EXA_API_KEY (或 mcp)
brave	BRAVE_API_KEY
jina	JINA_API_KEY
kimi	MOONSHOT_API_KEY
zai	ZAI_API_KEY
anthropic	oauth
perplexity	PERPLEXITY_API_KEY
gemini	oauth
codex	oauth
tavily	TAVILY_API_KEY
parallel	PARALLEL_API_KEY
kagi	KAGI_API_KEY
synthetic	SYNTHETIC_API_KEY
searxng	自托管

专用处理器

agent 获得结构化内容，而非剥离的 HTML。

• 代码托管 —— github, gitlab
• 包注册表 —— npm, PyPI, crates.io, Hex, Hackage, NuGet, Maven, RubyGems, Packagist, pub.dev, Go packages
• 研究来源 —— arxiv, semantic scholar
• 论坛 —— stack overflow, reddit, hn
• 文档 —— mdn, readthedocs, docs.rs

页面转换为 markdown，链接结构完整。agent 可以引用、追踪和引用，而不会丢失锚点。

安全数据库

漏洞查询返回供应商数据，而非博客摘要。

• NVD —— 国家漏洞数据库
• OSV —— 开源漏洞馈送
• CISA KEV —— 已知被利用的漏洞

web_search 参考 ↗

大约 ~27,000 行 Rust，完成其他 harness 通过 shell 调用完成的工作。

三个 crate，一个平台标记的 N-API addon。搜索、shell、AST、高亮、PTY、图像解码、BPE 计数——全部在 libuv 池中完成进程内操作。热路径上没有 fork/exec。

• Crates: pi-natives, pi-shell, pi-ast
• 平台：linux-x64、linux-arm64、darwin-x64、darwin-arm64、win32-x64

下表是每个模块的分解，有意省略了胶水和测试。

模块	功能	驱动者	~LoC
shell	嵌入式 bash · 持久会话 · 超时/中止 · 自定义内置命令	brush-shell (vendored)	3,700
grep	正则搜索 · 并行/顺序 · glob 和类型过滤器 · 模糊查找	grep-regex · grep-searcher	1,900
keys	Kitty 键盘协议 + xterm 回退 · PHF 完美哈希查找	phf	1,490
text	感知 ANSI 的宽度 · 截断 · 列切片 · 保留 SGR 的换行	unicode-width · segmentation	1,450
summarize	基于 tree-sitter 的结构化源码摘要，带省略控制	tree-sitter · ast-grep-core	1,040
ast	ast-grep 模式匹配及结构重写	ast-grep-core	1,000
fs_cache	基于 mtime 的文件缓存，由 read · grep · lsp 共享	内建	840
highlight	语法高亮 · 11 个语义类别 · 30+ 别名	syntect	470
pty	原生 PTY 分配，用于 sudo · ssh 交互提示	portable-pty	455
glob	基于 glob 的发现 · 类型过滤器 · mtime 排序 · 尊重 gitignore	ignore · globset	410
workspace	工作区遍历器，一次通过中同时处理 gitignore + AGENTS.md 发现	ignore · git2	385
appearance	Mode 2031 + 原生 macOS 暗/浅色主题，通过 CoreFoundation FFI	core-foundation	270
power	macOS 电源断言 API，用于空闲/系统/显示休眠阻止	IOKit FFI	270
task	基于 libuv 线程池的阻塞工作 · 取消 · 超时 · 性能分析	tokio · napi	260
fd	文件系统遍历器，作为 find-tool 的替代	ignore	250
iso	工作区隔离中间层 · apfs · btrfs · zfs · reflink · overlayfs · projfs · rcopy	pi-iso (PAL)	245
prof	循环缓冲区性能分析器，输出折叠栈及 SVG 火焰图	inferno	240
ps	跨平台进程树终止及后代列举	libc · libproc · CreateToolhelp32Snapshot	195
image	解码/编码 PNG · JPEG · WebP · GIF · 5 种滤镜缩放	image	190
clipboard	文本复制和图片从系统剪贴板读取 · 无需 xclip/pbcopy	arboard	80
tokens	O200k / Cl100k BPE token 计数 · 两个表内置	tiktoken-rs	65
html	HTML 转 Markdown，可选内容清理	html-to-markdown-rs	50

四个入口点：交互式、一次性、RPC 和 ACP。

同一引擎，四个包装器。omp 运行 TUI。omp -p 回答一个提示后退出。Node SDK 将会话嵌入你的进程。omp --mode rpc 和 omp acp 通过 stdio 将控制权交给另一个程序。

交互式——若有疑问，agent 会询问

TUI 是默认界面。工具调用渲染为卡片，编辑在落地前预览，歧义通过 ask 工具处理——agent 可以在运行中间调用的结构化选项选择器。键盘处理其余部分。

同样的提示卡片通过 ACP 显示，因此编辑器无需编写选择器即可获得。

SDK——嵌入 Node

@oh-my-pi/pi-coding-agent

Node 和 TypeScript 主机直接引入引擎。包暴露了 ModelRegistry、SessionManager、createAgentSession 和 discoverAuthStorage；会话发出类型化事件，你可以订阅。

import { ModelRegistry, SessionManager, createAgentSession, discoverAuthStorage } from "@oh-my-pi/pi-coding-agent";

const auth = await discoverAuthStorage();
const models = new ModelRegistry(auth);
await models.refresh();

const { session } = await createAgentSession({
	sessionManager: SessionManager.inMemory(),
	authStorage: auth,
	modelRegistry: models,
});
await session.prompt("list .ts files");

RPC——通过 stdio 驱动

omp --mode rpc

适用于非 Node 嵌入器，或当你想要进程隔离时。NDJSON 命令输入，响应和事件帧输出。--mode rpc-ui 添加工具卡片、选择器和对话框，作为主机必须回答的 extension_ui_request 帧。

$ omp --mode rpc --no-session
> {"id":"r1","type":"prompt","message":"list .ts files"}
< {"id":"r1","type":"response", ...}
> {"id":"r2","type":"set_model","provider":"anthropic","modelId":"sonnet-4.5"}
> {"id":"r3","type":"abort"}

ACP——与编辑器通信

omp acp

Agent Client Protocol 基于 JSON-RPC。当编辑器通告能力时，工具 I/O 经由它路由，写入通过 session/request_permission 门控。

omp 工具	ACP 路由
bash	terminal/create + terminal/output
read	fs/read_text_file
write	fs/write_text_file
edit, ast_edit, write, bash	session/request_permission

完整参考：omp.sh/docs/sdk.

一个值得保留的 harness，是你_不会_用一阵就嫌小的。

在 omp.sh 获取它。

omp 是 Pi（由 Mario Zechner 开发）的一个 fork，重写为以编码优先的界面：会话、子 agent、斜杠命令、扩展——全部 TypeScript、全部 MIT、全部在 GitHub 上。通过配置塑造它，从外部钩住它，或在需要时阅读源码。

原语

扩展是一个 TypeScript 模块。相同的工具 API、相同的斜杠命令注册表、相同的热键表、内置组件使用的相同 TUI 原语。没有保留名称。

发现

首次运行时，omp 继承磁盘上已有的内容：来自 .claude、.cursor、.windsurf、.gemini、.codex、.cline、.github/copilot 和 .vscode 的规则、技能和 MCP 服务器。无需迁移脚本。

可扩展性

让 omp 编写你缺少的部分，然后 /reload-plugins。