终端中的 AI 编码代理

分支自 badlogic/pi-mono, 由 @mariozechner 创建

目录

• 亮点
• 安装
• 快速入门
  • 终端设置
  • API 密钥与 OAuth
  • 推荐的前 15 分钟
• 使用方法
  • 斜杠命令
  • 编辑器功能
  • 快捷键
  • Bash 模式
  • 图像支持
• 会话
  • 会话管理
  • 上下文压缩
  • 分支
  • 自主记忆
• 配置
  • 项目上下文文件
  • 自定义系统提示
  • 自定义模型和提供商
  • 设置文件
• 扩展
  • 主题
  • 自定义斜杠命令
  • 技能
  • 钩子
  • 自定义工具
• CLI 参考
• 工具
• 程序化使用
  • SDK
  • RPC 模式
  • HTML 导出
• 理念
• 开发
• 单仓库包
• 许可证

---

亮点

+ 提交工具（AI 驱动的 Git 提交）

基于 AI 的规范提交生成，结合智能变更分析：

• 代理模式：通过 git-overview、git-file-diff、git-hunk 等工具进行基于工具的 Git 检查，实现细粒度分析
• 拆分提交：自动将不相关的更改分离为原子提交，并按依赖关系排序
• 块级暂存：当更改涉及多个关注点时，可单独暂存各个代码块
• 变更日志生成：为 CHANGELOG.md 文件提出并应用变更日志条目
• 提交验证：检测填充词、元短语，并强制执行规范提交格式
• 传统模式：提供 --legacy 标志，在偏好时使用确定性流程
• 通过 omp commit 运行，支持选项：--push、--dry-run、--no-changelog、--context

+ Python 工具（IPython 内核）

使用持久化的 IPython 内核和丰富的辅助预置来执行 Python 代码：

• 流式输出：实时 stdout/stderr，支持图像和 JSON 渲染
• 预置助手：内核中内置了文件 I/O、搜索、查找/替换、行操作、Shell 和文本实用工具
• 行操作：lines()、insert_at()、delete_lines()、delete_matching() 等助手可用于精确编辑
• 共享网关：通过 python.sharedGateway 设置，在不同会话中高效复用资源
• 自定义模块：可从 .omp/modules/ 和 ~/.omp/agent/modules/ 加载扩展
• 丰富输出：支持 display() 方法，用于 HTML、Markdown、图片以及交互式 JSON 树
• Markdown 渲染：包含 Markdown 内容的 Python 单元格输出会内联渲染
• Mermaid 图表：在 iTerm2/Kitty 终端中将 Mermaid 代码块渲染为内联图形
• 使用 omp setup python 安装依赖项

+ LSP 集成（语言服务器协议）

具备自动格式化和诊断功能的完整 IDE 式代码智能：

• 11 种 LSP 操作：diagnostics、definition、type_definition、implementation、references、hover、symbols、rename、code_actions、status、reload
• 写入时格式化：使用语言服务器的格式化工具（rustfmt、gofmt、prettier 等）自动格式化代码
• 写入/编辑时诊断：每次文件更改后立即反馈语法错误和类型问题
• 工作区诊断：无需指定文件即可通过 lsp 操作 diagnostics 检查整个项目中的错误
• 40 多种语言配置：开箱即用支持 Rust、Go、Python、TypeScript、Java、Kotlin、Scala、Haskell、OCaml、Elixir、Ruby、PHP、C#、Lua、Nix 等多种语言
• 本地二进制解析：自动发现项目中的本地 LSP 服务器，如 node_modules/.bin/、.venv/bin/ 等
• 符号消歧义：通过 occurrence 参数解决同一行上重复出现的符号问题

+ 时光旅行式流式规则 (TTSR)

零上下文占用的规则，仅在需要时才会注入自身：

• 模式触发注入：规则定义正则表达式触发器，监控模型的输出流
• 即时激活：当模式匹配时，流会中断，规则作为系统提醒注入，并重新发起请求
• 零前置成本：TTSR 规则在真正相关之前不会消耗任何上下文
• 每会话一次触发：每个规则只触发一次，防止循环
• 通过规则文件中的 ttsrTrigger 字段（正则模式）进行定义

示例：一条“禁止使用已弃用 API”的规则，只有当模型开始编写已弃用代码时才会激活，从而为从未涉及该 API 的会话节省上下文。

+ 交互式代码审查

基于优先级的结构化代码审查：

• /review 命令：交互式模式选择（分支对比、未提交更改、提交审查）
• 结构化发现：report_finding 工具，带有优先级等级（P0-P3：严重 → 细节）
• 评审结果呈现：将发现汇总为批准/请求更改/评论
• 结合结果树显示评审结论和所有发现

+ 任务工具（子代理系统）

具有专业代理和实时流式的并行执行框架：

• 6 个内置代理：探索、计划、设计、审查、任务、快速任务
• 并行探索：审查代理可为大型代码库分析启动探索代理
• 实时工件流：任务输出在生成时即开始流式传输，而非仅在完成时
• 完整输出访问：可通过 agent://<id> 资源读取完整的子代理输出，即使预览被截断
• 隔离后端：isolated: true 可在 Git 工作树、Unix FUSE 叠加文件系统或 Windows ProjFS（fuse-projfs）中运行任务，并支持补丁或分支合并策略
• 异步后台作业：可配置并发度的后台执行（最多 100 个作业），并使用 await 工具阻塞等待结果
• 代理控制中心：/agents 仪表板用于管理和创建自定义代理
• AI 驱动的代理创建：利用架构师模型生成自定义代理定义
• 针对单个代理的模型覆盖：通过 swarm 扩展为各个代理分配特定模型
• 用户级（~/.omp/agent/agents/）和项目级（.omp/agents/）自定义代理

+ 模型角色

通过自动发现功能为不同用途配置不同模型：

• 基于角色的路由：default、smol、slow、plan 和 commit 角色
• 可配置的自动发现：角色默认值会自动解析，也可按角色覆盖
• 基于角色的选择：任务工具代理可使用 model: pi/smol 进行经济高效的探索
• CLI 参数（--smol、--slow、--plan）和环境变量（PI_SMOL_MODEL、PI_SLOW_MODEL、PI_PLAN_MODEL）
• 通过 /model 选择器交互式配置角色，并将分配持久化到设置中

+ 待办事项工具（任务跟踪）

带有阶段性进度跟踪的结构化任务管理：

• 分阶段任务列表：将工作组织成命名阶段，包含有序任务
• 5 种操作：replace（设置）、add_phase、add_task、update（状态变更）、remove_task
• 4 种任务状态：pending、in_progress、completed、abandoned
• 自动规范化：确保任何时候都恰好有一项任务处于“进行中”状态
• 持久化面板：待办事项列表显示在编辑器上方，实时更新进度
• 完成提醒：当代理在未完成待办事项的情况下停止时会收到警告（todo.reminders 设置）
• 切换可见性：Ctrl+T 可展开/收起待办事项面板

+ 询问工具（交互式提问）

带有类型化选项的结构化用户交互：

• 多选题：以描述形式呈现选项供用户选择
• 支持多选：当选项不互斥时允许选择多个答案
• 多部分问题：通过 questions 数组参数依次提出多个相关问题

+ 自定义 TypeScript 斜杠命令

可编程命令，拥有完整的 API 访问权限：

• 在 ~/.omp/agent/commands/[name]/index.ts 或 .omp/commands/[name]/index.ts 创建
• 导出工厂函数，返回 { name, description, execute(args, ctx) }
• 完全访问 HookCommandContext，可用于 UI 对话框、会话控制、Shell 执行
• 返回字符串作为 LLM 提示发送，或返回 void 以执行一次性操作
• 同样可以从 Claude Code 目录加载（~/.claude/commands/、.claude/commands/）

+ 通用配置发现

统一的能力驱动型发现机制，可从 8 种 AI 编程工具中加载配置：

• 多工具支持：Claude Code、Cursor、Windsurf、Gemini、Codex、Cline、GitHub Copilot、VS Code
• 发现一切：MCP 服务器、规则、技能、钩子、工具、斜杠命令、提示词、上下文文件
• 原生格式支持：Cursor MDC 前言、Windsurf 规则、Cline .clinerules、Copilot applyTo 全局模式、Gemini system.md、Codex AGENTS.md
• 来源归属：查看每个配置项由哪个工具提供
• 发现设置：通过 /extensions 交互式仪表板启用或禁用各个提供商
• 优先级排序：跨 .omp、.claude、.codex 和 .gemini 目录进行多路径解析

+ MCP 与插件系统

完整模型上下文协议支持，并可集成外部工具：

• 使用 Stdio 和 HTTP 传输连接到 MCP 服务器
• OAuth 支持：在 MCP 服务器配置中明确指定 clientId 和 callbackPort，并通过斜杠命令手动处理 OAuth 回调
• 浏览器服务器过滤：自动过滤浏览器类型的 MCP 服务器，以避免与内置浏览器工具冲突
• 自动 Exa 过滤：提取 Exa API 密钥，并优先使用原生 Exa 集成
• 配置模式 + 设置指南：docs/mcp-config.md 和 packages/coding-agent/src/config/mcp-schema.json
• 插件 CLI（omp plugin install/enable/configure/doctor）
• 可热加载的插件，位于 ~/.omp/plugins/ 目录下，支持 npm/bun 集成
• disabledServers 设置同时适用于项目级和用户级第三方服务器

+ 网络搜索与抓取

多提供商搜索及全页抓取，并配备专用处理器：

• 多提供商搜索：auto、exa、brave、jina、kimi、zai、anthropic、perplexity、gemini、codex、synthetic
• 专用处理器：针对代码托管平台、包注册表、科研资源、论坛和文档等特定站点进行内容提取
• 包注册表：npm、PyPI、crates.io、Hex、Hackage、NuGet、Maven、RubyGems、Packagist、pub.dev、Go packages
• 安全数据库：NVD、OSV、CISA KEV 漏洞数据
• HTML 转 Markdown 并保留链接

+ SSH 工具

通过持久化连接执行远程命令：

• 项目发现：从项目中的 ssh.json 或 .ssh.json 文件读取 SSH 主机信息
• 主机管理：通过 omp ssh CLI 或 /ssh 斜杠命令添加、删除和列出主机
• 持久化连接：跨命令复用 SSH 连接，以加快执行速度
• 操作系统/Shell 检测：自动检测远程操作系统和 Shell 类型
• SSHFS 挂载：可选地自动挂载远程目录
• 兼容模式：支持 Windows 主机，并自动探测 Shell

+ 浏览器工具（Puppeteer with Stealth）

无头浏览器自动化，配备 14 种隐身脚本以规避机器人检测：

• 自动化操作：导航、点击、输入、填写、滚动、拖拽、截图、执行 JS 代码以及提取可读内容
• 无障碍快照：通过带有数字 ID 的无障碍树观察交互元素，实现可靠的目标定位
• 14 种隐身插件：自定义脚本覆盖 toString 操控、WebGL 指纹识别、音频上下文、屏幕尺寸、字体枚举、插件/MIME 类型模拟、硬件并发数、编解码器可用性、iframe 检测、区域设置欺骗、Worker 检测等
• 用户代理欺骗：移除 HeadlessChrome 标识，生成正确的 Client Hints 品牌列表，并通过 CDP Network 和 Emulation 域进行覆盖
• 选择器灵活性：CSS、aria/、text/、xpath/、pierce/ 查询处理器可用于穿透 Shadow DOM
• 阅读模式：extract_readable 动作使用 Mozilla Readability 清理并提取文章内容
• 无头/可见切换：可通过 /browser 命令或 browser.headless 设置在运行时切换模式
• NixOS 支持：自动检测 NixOS (/etc/NIXOS)，并解析系统 Chromium（PATH 中的 chromium、~/.nix-profile/bin/chromium 或 /run/current-system/sw/bin/chromium），因为 Puppeteer 自带的二进制文件无法在非 FHS 系统上运行

+ Cursor 提供者

利用您的 Cursor Pro 订阅获取 AI 补全功能：

• 基于浏览器的 OAuth：通过 Cursor 的 OAuth 流程进行身份验证
• 工具执行桥接：将 Cursor 的原生工具映射到 omp 对应工具（读取、写入、Shell、诊断）
• 会话缓存：在同一会话中保持请求间的上下文一致性
• Shell 流式输出：命令执行过程中实时显示 stdout/stderr

+ 多凭证支持

在多个 API 密钥之间分配负载：

• 轮询分发：每个会话自动循环使用不同凭证
• 用量感知选择：对于 OpenAI Codex，在选择凭证前会检查账户限额
• 自动回退：当达到速率限制时，会在会话中途切换凭证
• 一致性哈希：使用 FNV-1a 哈希算法确保每个会话的凭证分配稳定

+ 图像生成

直接从代理生成图像：

• Gemini 集成：默认使用 gemini-3-pro-image-preview
• OpenRouter 回退：当设置 OPENROUTER_API_KEY 时，自动使用 OpenRouter
• 内联显示：支持 Kitty/iTerm2 图形的终端可以直接渲染图像
• 保存为临时文件，并报告路径以便进一步操作

+ TUI 全面升级

现代化终端界面，具备智能会话管理：

• 自动会话标题：根据第一条消息自动为会话命名，使用提交模型；若无则使用 smol
• 欢迎界面：包含 logo、提示信息以及最近会话列表供选择
• Powerline 脚注：显示模型、当前工作目录、Git 分支/状态、令牌使用情况和上下文百分比
• LSP 状态：显示哪些语言服务器已激活并就绪
• 快捷键：编辑器为空时按 ? 键可显示快捷方式
• 持久化提示历史：基于 SQLite 存储，并可通过 Ctrl+R 在不同会话中搜索
• 分组工具显示：连续的 Read 调用以紧凑的树状视图呈现
• 流式文本预览：代理输出时实时更新增量内容
• 叠加 UI：自定义钩子可以将组件显示为底部居中的叠加层
• 可配置制表符宽度：通过 display.tabWidth 设置，并与 .editorconfig 集成
• 回滚保留：使用 home+erase-below 而不是 clear-screen
• 紧急终端恢复：崩溃处理程序可防止终端损坏

+ Hashline 编辑

Hashline 为每一行赋予一个简短的内容哈希锚点。模型通过引用这些锚点来操作文本，而非重复复制文本——无需复制空格，不会出现“未找到字符串”的情况，也不会有歧义匹配。如果文件自上次读取以来发生更改，哈希值将不匹配，编辑操作会被拒绝，从而避免任何潜在的数据损坏。

在 16 种模型、180 个任务上进行了三次基准测试：

• Grok Code Fast 1：从 6.7% 提升至 68.3%，这一“十倍”提升隐藏在机械补丁失败的背后
• Gemini 3 Flash：相比 str_replace 提升了 5 个百分点，超越了 Google 自己的最佳尝试
• Grok 4 Fast：输出的 token 数减少了 61%，不再因重试循环而浪费上下文
• MiniMax：成功率提高了一倍以上
• 几乎在所有测试过的模型中，其表现都与 str_replace 相当或更好；其中表现最弱的模型受益最大

+ 原生引擎（Rust N-API）

约7,500行Rust代码被编译为带有平台标签的N-API插件，用于在不调用外部命令的情况下执行性能关键的操作：

模块	行数	功能	依赖组件
grep	~1,300	在文件和内存内容中进行正则表达式搜索，支持并行/串行模式、glob/类型过滤、上下文行显示以及用于自动补全的模糊查找	grep-regex、grep-searcher、grep-matcher（ripgrep内部组件）
shell	~1,025	内嵌bash执行，支持持久化会话、流式输出、超时/中断、自定义内置命令	brush-shell（已打包）
text	~1,280	支持ANSI的颜色编码以正确计算可见宽度、带省略号的截断、列分割、保留SGR代码的文本换行——所有功能均针对UTF-16优化	unicode-width、unicode-segmentation
keys	~1,300	解析Kitty键盘协议，并兼容旧版xterm/VT100协议；支持修饰键及PHF完美哈希查找	phf
highlight	~475	语法高亮，提供11种语义颜色类别及30多种语言别名	syntect
glob	~340	使用glob模式进行文件系统遍历，支持类型过滤、按修改时间排序以及对.gitignore规则的尊重	ignore、globset（ripgrep内部组件）
task	~350	基于libuv线程池的阻塞式任务调度器，支持协作式/外部取消、超时及性能分析钩子	tokio、napi
ps	~290	跨平台进程树杀戮与子进程列表——Linux下使用/proc，macOS下使用libproc，Windows下使用CreateToolhelp32Snapshot	libc
prof	~250	常驻循环缓冲区性能分析器，可折叠堆栈输出，并可选择生成SVG火焰图	inferno
image	~150	解码/编码PNG/JPEG/WebP/GIF格式图像，并支持5种采样滤波器进行缩放	image
clipboard	~95	从系统剪贴板复制文本或读取图像——无需依赖xclip或pbcopy	arboard
html	~50	HTML转Markdown转换，可选内容清理	html-to-markdown-rs

支持的平台：linux-x64、linux-arm64、darwin-x64、darwin-arm64、win32-x64。

…还有更多

• omp config子命令：通过CLI管理配置（列出、获取、设置、重置、查看路径）
• omp setup子命令：安装可选依赖项（例如，omp setup python用于Jupyter内核）
• omp stats子命令：本地AI使用情况观测仪表盘（请求量、成本、缓存率、每秒令牌数）
• xhigh思考级别：为Anthropic模型提供扩展推理能力，增加令牌预算
• 后台模式：/background可分离UI并继续代理执行
• 完成通知：代理完成任务时可触发自定义铃声、OSC99或OSC9提示
• 65+内置主题：Catppuccin、Dracula、Nord、Gruvbox、Tokyo Night、Poimandres以及Material变体
• 自动深色/浅色切换：基于终端检测模式2031，通过CoreFoundation FFI实现原生macOS外观，并提供COLORFGBG回退方案
• 自动环境检测：在系统提示符中显示操作系统、发行版、内核、CPU、GPU、Shell、终端及桌面环境信息
• Git上下文：系统提示符包含分支、状态及最近提交记录
• Bun运行时：原生TypeScript执行，启动更快，所有包均已迁移
• 集中式文件日志：调试日志每日轮转至~/.omp/logs/
• Bash拦截器：可选择性阻止已有专用工具处理的Shell命令
• 每条命令的PTY控制：Bash工具支持pty: true选项，适用于需要真实终端的命令（如sudo、ssh）
• @file自动读取：在提示中输入@path/to/file即可将文件内容直接插入
• AST工具：ast_grep和ast_edit用于基于抽象语法树的代码搜索与代码改写
• 采样控制：topP、topK、minP、presencePenalty、repetitionPenalty等设置可用于精细化调整模型行为

---

安装

通过Bun（推荐）

需安装Bun ≥ 1.3.7：

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

通过安装脚本

Linux / macOS：

curl -fsSL https://raw.githubusercontent.com/can1357/oh-my-pi/main/scripts/install.sh | sh

Windows（PowerShell）：

irm https://raw.githubusercontent.com/can1357/oh-my-pi/main/scripts/install.ps1 | iex

默认情况下，安装程序会在可用且兼容时使用Bun，否则会安装预编译的二进制文件。

选项：

• POSIX（install.sh）：--source、--binary、--ref <ref>、-r <ref>
• PowerShell（install.ps1）：-Source、-Binary、-Ref <ref>
• 使用二进制模式时，--ref/-Ref必须指向发布标签；若使用分支或提交引用，则需采用源码模式

可通过设置PI_INSTALL_DIR来指定自定义安装目录。

示例：

# 源码安装（Bun）
curl -fsSL https://raw.githubusercontent.com/can1357/oh-my-pi/main/scripts/install.sh | sh -s -- --source

# 通过二进制安装特定版本
curl -fsSL https://raw.githubusercontent.com/can1357/oh-my-pi/main/scripts/install.sh | sh -s -- --binary --ref v3.20.1

# 通过源码安装分支/提交
curl -fsSL https://raw.githubusercontent.com/can1357/oh-my-pi/main/scripts/install.sh | sh -s -- --source --ref main

# 通过二进制安装特定版本
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/can1357/oh-my-pi/main/scripts/install.ps1))) -Binary -Ref v3.20.1

# 通过源代码安装分支/提交
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/can1357/oh-my-pi/main/scripts/install.ps1))) -Source -Ref main

通过 mise

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

手动下载

直接从 GitHub Releases 下载二进制文件。

---

开始使用

终端设置

Pi 使用 Kitty 键盘协议 来可靠地检测修饰键。大多数现代终端都支持该协议，但有些需要进行配置。

Kitty、iTerm2： 无需额外配置即可正常工作。

Ghostty： 在 Ghostty 配置文件（~/.config/ghostty/config）中添加以下内容：

keybind = alt+backspace=text:\x1b\x7f
keybind = shift+enter=text:\n

wezterm： 创建 ~/.wezterm.lua 文件：

local wezterm = require 'wezterm'
local config = wezterm.config_builder()
config.enable_kitty_keyboard = true
return config

Windows Terminal： 不支持 Kitty 键盘协议。Shift+Enter 无法与 Enter 区分。请改用 Ctrl+Enter 进行多行输入。其他所有快捷键均可正常使用。

API 密钥与 OAuth

选项 1：环境变量（常见示例）

提供商	环境变量
Anthropic	ANTHROPIC_API_KEY
OpenAI	OPENAI_API_KEY
Google	GEMINI_API_KEY
Mistral	MISTRAL_API_KEY
Groq	GROQ_API_KEY
Cerebras	CEREBRAS_API_KEY
Hugging Face (huggingface)	HUGGINGFACE_HUB_TOKEN 或 HF_TOKEN
Synthetic	SYNTHETIC_API_KEY
NVIDIA (nvidia)	NVIDIA_API_KEY
NanoGPT (nanogpt)	NANO_GPT_API_KEY
Together (together)	TOGETHER_API_KEY
Ollama (ollama)	OLLAMA_API_KEY (可选)
LiteLLM (litellm)	LITELLM_API_KEY
LM Studio (lm-studio)	LM_STUDIO_API_KEY (可选)
llama.cpp (llama.cpp)	LLAMA_CPP_API_KEY (可选)
Xiaomi MiMo (xiaomi)	XIAOMI_API_KEY
Moonshot (moonshot)	MOONSHOT_API_KEY
Venice (venice)	VENICE_API_KEY
Kilo Gateway (kilo)	KILO_API_KEY
GitLab Duo (gitlab-duo)	仅支持 OAuth
Jina (jina, 网络搜索)	JINA_API_KEY
Perplexity	PERPLEXITY_API_KEY 或 PERPLEXITY_COOKIES
xAI	XAI_API_KEY
OpenRouter	OPENROUTER_API_KEY
Z.AI	ZAI_API_KEY
Qwen Portal (qwen-portal)	QWEN_OAUTH_TOKEN 或 QWEN_PORTAL_API_KEY
vLLM (vllm)	VLLM_API_KEY
Cloudflare AI Gateway (cloudflare-ai-gateway)	CLOUDFLARE_AI_GATEWAY_API_KEY
Vercel AI Gateway (vercel-ai-gateway)	AI_GATEWAY_API_KEY
Qianfan (qianfan)	QIANFAN_API_KEY

完整列表请参阅 环境变量 文档。

选项 2：/login（交互式认证 / API 密钥设置）

使用 /login 功能可与以下支持的提供商进行交互：

• Anthropic（Claude Pro/Max）
• ChatGPT Plus/Pro（Codex）
• GitHub Copilot
• Google Cloud Code Assist（Gemini CLI）
• Antigravity（Gemini 3、Claude、GPT-OSS）
• Cursor
• Kimi Code
• Perplexity
• NVIDIA（nvidia）
• NanoGPT（nanogpt）
• Hugging Face Inference（huggingface）
• OpenCode Zen
• Kilo Gateway（kilo）
• GitLab Duo（gitlab-duo）
• Qianfan（qianfan）
• Ollama（本地 / 自托管，ollama）
• LM Studio（本地 / 自托管，lm-studio）
• llama.cpp（本地 / 自托管，llama.cpp）
• vLLM（本地兼容 OpenAI 的模型，vllm）
• Z.AI（GLM 编码计划）
• Synthetic
• Together（together）
• LiteLLM（litellm）
• Xiaomi MiMo（xiaomi）
• Moonshot（Kimi API，moonshot）
• Venice（venice）
• MiniMax 编码计划（国际版 / 中国版）
• Qwen Portal（qwen-portal）
• Cloudflare AI Gateway（cloudflare-ai-gateway）
• Vercel AI Gateway（vercel-ai-gateway）

对于 ollama，API 密钥是可选的。如果是在本地无认证的实例上使用，可以不设置；若连接到已认证的主机，则需设置 OLLAMA_API_KEY。
对于 llama.cpp，API 密钥也是可选的。在本地无认证的实例上可以不设置；若连接到已认证的主机，则需设置 LLAMA_CPP_API_KEY。
对于 lm-studio，API 密钥同样是可选的。在本地无认证的实例上可以不设置；若连接到已认证的主机，则需设置 LM_STUDIO_API_KEY。
对于 vllm，可在 /login 中粘贴您的密钥（或设置 VLLM_API_KEY）。对于本地无认证的服务器，任何占位符值均可（例如 vllm-local）。
对于 nanogpt，运行 /login nanogpt 将打开 https://nano-gpt.com/api 并提示您输入 sk-... 密钥（或设置 NANO_GPT_API_KEY）。登录过程会通过 NanoGPT 的模型端点验证密钥，而非固定的模型授权。
对于 cloudflare-ai-gateway，请将提供商标记的 URL 设置为： https://gateway.ai.cloudflare.com/v1/<account_id>/<gateway_id>/anthropic （例如，在 ~/.omp/agent/models.yml 中进行设置）。

omp
/login

凭证行为说明：

• /login 会追加当前提供商的凭证信息（不会清除已有记录）。
• /logout 会清除所选提供商的已保存凭证。
• 凭证信息存储在 ~/.omp/agent/agent.db 中。
• 对于同一提供商，系统会优先选择已保存的 API 密钥凭证，而非 OAuth 凭证。

前15分钟（推荐）

这是新用户的实用入门流程。

1) 设置提供商

• API密钥（最快）：导出 ANTHROPIC_API_KEY、OPENAI_API_KEY、GEMINI_API_KEY 等。
• OAuth 订阅：运行 /login 并使用您的提供商账户进行认证。

2) 通过 /model 配置模型角色

在 TUI 中使用 /model 分配角色模型：

• default → 普通的实现工作
• smol → 快速/廉价的探索和轻量级任务
• slow → 用于复杂调试/重构的深度推理
• plan → 在计划模式激活时使用的模型（/plan）
• commit → 用于提交/变更日志工作流的模型

此设置是交互式的，并会为您持久化保存。

3) 在进行重大更改前使用 /plan

/plan 可切换计划模式。当您希望在编辑之前规划架构和执行顺序时，请使用它。

典型流程：

1. 运行 /plan
2. 请求具体的实现计划
3. 优化计划
4. 批准并执行

4) 通过 /extensions 查看上下文

如果上下文使用量意外偏高，可以检查已发现的外部提供商资源（规则/提示/上下文/钩子/扩展）。

运行 /extensions 并：

• 浏览提供商选项卡（Tab / Shift+Tab）
• 检查每个条目的来源（via <provider> + 文件路径）
• 禁用整个提供商或您不希望使用的特定条目（Space）

---

使用方法

斜杠命令

这些是聊天中的斜杠命令（而非 CLI 子命令）。

命令	描述
/settings	打开设置菜单
/plan	切换计划模式
/model (/models)	打开模型选择器
/export [path]	将会话导出为 HTML
/dump	将会话记录复制到剪贴板
/share	将会话上传为私密 gist
/session	显示会话信息及使用情况
/usage	显示提供商使用情况及限额
/hotkeys	显示键盘快捷键
/extensions (/status)	打开扩展控制中心
/changelog	显示变更日志条目
/tree	导航会话树
/branch	打开分支选择器（根据设置为树形或消息选择器）
/fork	从先前的消息分叉
/resume	打开会话选择器
/new	开始新的会话
/compact [focus]	手动压缩上下文
/handoff [focus]	将上下文移交至新会话
/browser [headless|visible]	切换浏览器模式
/mcp ...	管理 MCP 服务器
/memory ...	检查/清除/重建内存状态
/move <path>	将当前会话移动到不同的工作目录
/background (/bg)	分离 UI 并在后台继续
/debug	打开调试工具
/copy	复制最后一条代理消息
/login / /logout	OAuth 登录/登出
/exit (/quit)	退出交互模式

内置的自定义斜杠命令包括 /review（交互式代码审查启动器）。

编辑器功能

文件引用（@）： 输入 @ 可模糊搜索项目文件。尊重 .gitignore。

路径补全（Tab）： 补全相对路径、../、~/ 等。

拖放： 可将文件从文件管理器拖放到终端中。

多行粘贴： 粘贴的内容会在预览中折叠，但实际发送时会完整显示。

消息队列： 当代理正在工作时仍可提交消息；队列行为可在 /settings 中配置。

键盘快捷键

导航：

键	动作
方向键	移动光标 / 浏览历史记录（空时向上）
Option+左/右	按单词移动
Ctrl+A / Home / Cmd+Left	行首
Ctrl+E / End / Cmd+Right	行尾

编辑：

键	动作
Enter	发送消息
Shift+Enter / Alt+Enter	新行
Ctrl+W / Option+Backspace	向后删除一个单词
Ctrl+U	删除到行首
Ctrl+K	删除到行尾

其他：

键	动作
Tab	路径补全 / 接受自动补全
Escape	取消自动补全 / 中断流式输出
Ctrl+C	清除编辑器内容（第一次） / 退出（第二次）
Ctrl+D	退出（当编辑器为空时）
Ctrl+Z	暂停至后台（使用 shell 中的 fg 恢复）
Shift+Tab	循环切换思考层级
Ctrl+P / Shift+Ctrl+P	循环切换角色模型（slow/default/smol），临时轮换
Alt+P	临时选择模型
Ctrl+L	打开模型选择器
Alt+Shift+P	切换计划模式
Ctrl+R	搜索提示历史
Ctrl+O	切换工具输出展开
Ctrl+T	切换待办事项列表展开
Ctrl+G	在外部编辑器中编辑消息（$VISUAL 或 $EDITOR）
Alt+H	切换语音转文字录音

Bash 模式

在命令前加上 ! 可以执行该命令，并将输出纳入上下文中：

!git status
!ls -la

使用 !! 可以执行命令，但不将输出纳入 LLM 上下文：

!!git status

输出会实时显示。按 Escape 可取消。

图像支持

通过引用附加图像：

@/path/to/image.png 里有什么？

或者直接粘贴/拖放图像（Ctrl+V 或拖放）。

支持的格式：.jpg、.jpeg、.png、.gif、.webp

可通过 /settings 切换内联图像，或设置 terminal.showImages: false。

---

会话

会话以 JSONL 格式存储，并具有树状结构，便于分支和回放。

文件格式和 API 请参阅 docs/session.md。

会话管理

会话会自动保存到 ~/.omp/agent/sessions/（按工作目录分组）。

omp --continue             # 继续最近的会话
omp -c

omp --resume               # 打开会话选择器
omp -r

omp --resume <id-prefix>   # 按会话 ID 前缀恢复
omp --resume <path>        # 按明确的 .jsonl 路径恢复
omp --session <value>      # --resume 的别名
omp --no-session    # 临时模式（不保存）

会话 ID 是 Snowflake 风格的十六进制 ID（不是 UUID）。

上下文压缩

长时间的会话可能会耗尽上下文窗口。压缩功能会总结较旧的消息，同时保留最近的上下文。

手动操作： /compact 或 /compact 关注 API 变更

自动操作： 通过 /settings 启用。

• 溢出恢复： 当模型返回上下文溢出时，进行压缩并重试。
• 阈值维护： 在一次成功的对话回合后，上下文会超过配置的预留空间。

配置 (~/.omp/agent/config.yml)：

compaction:
  enabled: true
  reserveTokens: 16384
  keepRecentTokens: 20000
  autoContinue: true

有关内部机制和钩子集成，请参阅 docs/compaction.md。

分支

就地导航 (/tree)： 在不创建新文件的情况下浏览会话树。

• 通过输入搜索，使用 ←/→ 键翻页
• 过滤模式（Ctrl+O）：默认 → 无工具 → 仅用户 → 仅标记 → 全部
• 按 Shift+L 可将条目标记为书签

创建新会话 (/branch / /fork)： 从选定的前一条消息分支到一个新的会话文件。

自主记忆

启用后，代理会从过去的会话中提取持久知识，并在启动时注入这些知识。该流程在后台运行，不会阻塞当前会话。

记忆按项目（工作目录）隔离，存储在 ~/.omp/agent/memories/ 下。在会话开始时，系统提示中会注入一份精简摘要。代理可以通过 memory://root/MEMORY.md 和 memory://root/skills/<name>/SKILL.md 读取更深入的上下文。

可通过 /memory 斜杠命令管理：

• /memory view — 显示当前注入的内容
• /memory clear — 删除所有记忆数据和产物
• /memory enqueue — 强制在下次启动时进行整合

请参阅 记忆文档。

---

配置

项目上下文文件

omp 会从支持的配置目录中发现项目上下文（例如 .omp, .claude, .codex, .gemini）。

常见文件：

• AGENTS.md
• CLAUDE.md

用于以下用途：

• 项目说明和约束条件
• 常用命令和工作流程
• 架构文档
• 编码/测试规范

自定义系统提示

通过创建 SYSTEM.md 替换默认系统提示：

1. 项目本地： .omp/SYSTEM.md（优先级更高）
2. 全局： ~/.omp/agent/SYSTEM.md（备用） 使用 --system-prompt 可覆盖上述两个文件。若需追加额外说明，可使用 --append-system-prompt。

自定义模型和提供商

通过 ~/.omp/agent/models.yml 添加自定义提供商/模型。

models.json 仍可用于旧版配置，但 models.yml 是现代格式。

有关模式和合并行为，请参阅 models.yml 提供商集成指南。

providers:
  ollama:
    baseUrl: http://localhost:11434/v1
    apiKey: OLLAMA_API_KEY
    api: openai-completions
    models:
      - id: llama-3.1-8b
        name: Llama 3.1 8B (本地)
        reasoning: false
        input: [text]
        cost:
          input: 0
          output: 0
          cacheRead: 0
          cacheWrite: 0
        contextWindow: 128000
        maxTokens: 32000

  llama.cpp:
    baseUrl: http://127.0.0.1:8080
    api: openai-responses
    auth: none
    discovery:
      type: llama.cpp

支持的 API： openai-completions, openai-responses, openai-codex-responses, azure-openai-responses, anthropic-messages, google-generative-ai, google-vertex

设置文件

全局设置存储于：

• ~/.omp/agent/config.yml

项目覆盖设置则从发现的项目设置文件中加载（通常为 .omp/settings.json）。

全局 config.yml 示例：

theme:
  dark: titanium
  light: light

enabledModels:
  - "anthropic/*"
  - "*gpt*"
  - "gemini-2.5-pro:high"

modelRoles:
  default: anthropic/claude-sonnet-4-20250514
  plan: anthropic/claude-opus-4-1:high
  smol: anthropic/claude-sonnet-4-20250514
defaultThinkingLevel: high

retry:
  enabled: true
  # 在放弃速率限制/服务器错误之前的最大重试次数
  maxRetries: 3
  # 默认等待时间（指数退避），除非 API 提供 retry-after-ms
  baseDelayMs: 2000
  # 配置角色特定的模型回退链
  fallbackChains:
    default:
      - "openai/gpt-4o-mini"
      - "openai/gpt-4o"
    plan:
      - "anthropic/claude-sonnet-4-6:high"
      - "openai/o3:high"
  # 回退模型冷却期结束后是否恢复到主模型
  fallbackRevertPolicy: cooldown-expiry
steeringMode: one-at-a-time
followUpMode: one-at-a-time
interruptMode: immediate

shellPath: C:\\path\\to\\bash.exe
hideThinkingBlock: false
collapseChangelog: false

disabledProviders: []
disabledExtensions: []

compaction:
  enabled: true
  reserveTokens: 16384
  keepRecentTokens: 20000

skills:
  enabled: true


terminal:
  showImages: true

topP: -1 # 核采样 (0-1, -1 = 提供商默认值)
topK: -1 # Top-K 令牌 (-1 = 提供商默认值)
minP: -1 # 最小概率 (0-1, -1 = 提供商默认值)

display:
  tabWidth: 4 # Tab 渲染宽度 (.editorconfig 集成)

async:
  enabled: false
  maxJobs: 100

task:
  eager: false
  isolation:
    mode: none # none | worktree | fuse-overlay | fuse-projfs
    merge: patch # patch | branch

旧版迁移注意事项：

• settings.json → config.yml
• queueMode → steeringMode
• 平面的 theme: "..." → theme.dark / theme.light

---

扩展

主题

内置主题包括 dark、light 以及许多捆绑变体。

自动深色/浅色切换： omp 通过 Mode 2031、原生 macOS CoreFoundation FFI 或 COLORFGBG 备用方案检测终端外观，并自动在 theme.dark 和 theme.light 之间切换。

可通过 /settings 选择主题，或在 ~/.omp/agent/config.yml 中设置：

theme:
  dark: titanium
  light: light

自定义主题： 创建 ~/.omp/agent/themes/*.json。

请参阅 主题文档。

自定义斜杠命令

将可重复使用的提示命令定义为 Markdown 文件：

• 全局：~/.omp/agent/commands/*.md
• 项目：.omp/commands/*.md

---
description: 审查暂存的 Git 更改
---

审查暂存的更改（`git diff --cached`）。重点关注：

- Bug 和逻辑错误
- 安全问题
- 错误处理的不足

文件名（不带 .md）即为命令名称。

参数占位符：

• $1, $2, ... 位置参数
• $@ 和 $ARGUMENTS 表示所有参数的拼接

也支持 TypeScript 自定义命令：

• ~/.omp/agent/commands/<name>/index.ts
• .omp/commands/<name>/index.ts

捆绑的 TypeScript 命令：/review。

技能

技能是按需加载的能力包。

常见位置：

• ~/.omp/agent/skills/*/SKILL.md
• .omp/skills/*/SKILL.md
• ~/.claude/skills/*/SKILL.md, .claude/skills/*/SKILL.md
• ~/.codex/skills/*/SKILL.md, .codex/skills/*/SKILL.md

---
name: brave-search
description: 通过 Brave Search API 进行网页搜索。
---

# 勇敢搜索

description 驱动匹配；name 在省略时默认为文件夹名称。

使用 omp --no-skills 或 skills.enabled: false 来禁用技能。

请参阅 技能文档。

钩子

钩子是订阅生命周期事件的 TypeScript 模块。

钩子位置：

• 全局：~/.omp/agent/hooks/pre/*.ts, ~/.omp/agent/hooks/post/*.ts
• 项目：.omp/hooks/pre/*.ts, .omp/hooks/post/*.ts
• CLI：--hook <path>

import type { HookAPI } from "@oh-my-pi/pi-coding-agent/hooks";

export default function (omp: HookAPI) {
	omp.on("tool_call", async (event, ctx) => {
		if (event.toolName === "bash" && /sudo/.test(event.input.command as string)) {
			const ok = await ctx.ui.confirm("允许使用 sudo 吗？", event.input.command as string);
			if (!ok) return { block: true, reason: "被用户阻止" };
		}
		return undefined;
	});
}

通过以下方式从钩子注入消息：

omp.sendMessage(message, { triggerTurn: true });

请参阅 钩子文档 和 示例钩子。

自定义工具

自定义工具扩展了内置工具集，可供模型调用。

自动发现的位置：

• 全局：~/.omp/agent/tools/*/index.ts
• 项目：.omp/tools/*/index.ts

import { Type } from "@sinclair/typebox";
import type { CustomToolFactory } from "@oh-my-pi/pi-coding-agent";
const factory: CustomToolFactory = () => ({
	name: "greet",
	label: "问候",
	description: "生成问候语",
	parameters: Type.Object({
		name: Type.String({ description: "要问候的名字" }),
	}),
	async execute(_toolCallId, params) {
		const { name } = params as { name: string };
		return { content: [{ type: "text", text: `你好，${name}！` }] };
	},
});
export default factory;

请参阅 自定义工具文档 和 自定义工具示例。

---

CLI 参考

omp [选项] [@文件...] [消息...]
omp <命令> [参数] [标志]

选项

选项	描述
--provider <name>	提供商提示（旧版；建议使用 --model）
--model <id>	模型 ID（支持模糊匹配）
--smol <id>	覆盖本次运行的 smol 角色模型
--slow <id>	覆盖本次运行的 slow 角色模型
--plan <id>	覆盖本次运行的 plan 角色模型
--models <patterns>	用于角色轮换的逗号分隔的模型模式
--list-models [pattern]	列出可用模型（可选模糊筛选）
--thinking <level>	思考级别：off, minimal, low, medium, high, xhigh
--api-key <key>	API 密钥（覆盖环境/提供商查找）
--system-prompt <text|file>	替换系统提示
--append-system-prompt <text|file>	追加到系统提示
--mode <mode>	输出模式：text, json, rpc
--print, -p	非交互式：处理提示并退出
--continue, -c	继续最近一次会话
--resume, -r [id|path]	根据 ID 前缀或路径恢复会话（若未指定则打开选择器）
--session <value>	--resume 的别名
--session-dir <dir>	用于会话存储和查找的目录
--no-session	不保存会话
--tools <tools>	限制为逗号分隔的内置工具名称
--no-tools	禁用所有内置工具
--no-lsp	禁用 LSP 集成
--no-pty	禁用基于 PTY 的交互式 bash 执行
--extension <path>, -e	加载扩展文件（可重复）
--hook <path>	加载钩子/扩展文件（可重复）
--no-extensions	禁用扩展发现（-e 路径仍会加载）
--no-skills	禁用技能发现和加载
--skills <patterns>	用于筛选技能的逗号分隔的 glob 模式
--no-rules	禁用规则发现和加载
--allow-home	允许从主目录启动而不自动切换目录
--no-title	禁用自动会话标题生成
--export <file> [output]	将会话导出为 HTML
--help, -h	显示帮助
--version, -v	显示版本

子命令

omp 还提供专用子命令：

• commit
• config
• grep
• jupyter
• plugin
• search（别名：q）
• setup
• shell
• ssh
• stats
• update

文件参数

使用 @ 前缀包含文件：

omp @prompt.md "回答这个问题"
omp @screenshot.png "这张图片里有什么？"
omp @requirements.md @design.png "实现这个"

文本文件会被包裹在 <file ...> 块中。图像会被附加。

示例

# 交互模式
omp
# 非交互模式
omp -p "列出 src 目录下的所有 .ts 文件"
omp -c "我们刚才讨论了什么？"
# 根据 ID 前缀恢复会话
omp -r abc123

# 使用模式进行模型轮换
omp --models "sonnet:high,haiku:low"

# 限制工具集以进行只读审查
omp --tools read,grep,find -p "审查架构"
# 导出会话
omp --export session.jsonl output.html

环境变量

变量	描述
ANTHROPIC_API_KEY、OPENAI_API_KEY 等	提供商凭据
PI_CODING_AGENT_DIR	覆盖代理数据目录（默认：~/.omp/agent）
PI_PACKAGE_DIR	覆盖包目录解析
PI_SMOL_MODEL、PI_SLOW_MODEL、PI_PLAN_MODEL	角色模型覆盖
PI_NO_PTY	禁用基于 PTY 的 Bash 执行
VISUAL、EDITOR	Ctrl+G 的外部编辑器

完整参考请参阅 环境变量。

---

工具

使用 --tools <列表> 来限制可用的内置工具。

内置工具名称 (--tools)

工具	描述
ask	向用户提出结构化的后续问题（交互模式）
bash	执行 Shell 命令
python	在 IPython 内核中执行 Python 代码
calc	确定性计算器/求值器
ssh	在已配置的 SSH 主机上执行命令
edit	使用 LINE#ID 锚点进行原地文件编辑
find	按照 glob 模式查找文件
grep	搜索文件内容
ast_grep	使用 AST 匹配进行结构化代码搜索（ast-grep）
ast_edit	基于 AST 的结构化代码重写（ast-grep）
lsp	语言服务器操作（11 种操作）
notebook	编辑 Jupyter 笔记本
read	读取文件/目录（默认文本上限：3000 行）
browser	浏览器自动化工具（面向模型的名称：puppeteer）
task	启动子代理以并行执行
await	阻塞等待异步后台任务
todo_write	分阶段任务跟踪与进度管理
fetch	获取并提取 URL 内容
web_search	多提供商网络搜索
write	创建或覆盖文件
generate_image	使用 Gemini 图像模型生成或编辑图像

注：

• 部分工具受设置限制（如 calc、browser 等）
• ask 需要交互式 UI
• ssh 需要配置好的 SSH 主机

示例：

omp --tools read,grep,find -p "Review this codebase"

如需添加新工具，请参阅 自定义工具。

---

编程式使用

SDK

若需将 omp 嵌入到 Node.js/TypeScript 应用程序中，可使用 SDK：

import { ModelRegistry, SessionManager, createAgentSession, discoverAuthStorage } from "@oh-my-pi/pi-coding-agent";
const authStorage = await discoverAuthStorage();
const modelRegistry = new ModelRegistry(authStorage);
await modelRegistry.refresh();
const { session } = await createAgentSession({
	sessionManager: SessionManager.inMemory(),
	authStorage,
	modelRegistry,
});
session.subscribe((event) => {
	if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
		process.stdout.write(event.assistantMessageEvent.delta);
	}
});
await session.prompt("What files are in the current directory?");

SDK 提供以下控制功能：

• 模型选择和思考层级
• 系统提示（替换或追加）
• 内置/自定义工具
• 钩子、技能、上下文文件、斜杠命令
• 会话持久化（SessionManager）
• 设置（Settings）
• API 密钥和 OAuth 解析

请参阅 SDK 文档 和 examples/sdk/。

RPC 模式

若需从其他语言嵌入或实现进程隔离：

omp --mode rpc --no-session

在标准输入上发送 JSON 命令：

{"id":"req-1","type":"prompt","message":"List all .ts files"}
{"id":"req-2","type":"abort"}

响应以 type: "response" 的形式发出；会话事件则实时流式输出到标准输出。

完整协议请参阅 RPC 文档。

HTML 导出

omp --export session.jsonl              # 自动生成文件名
omp --export session.jsonl output.html  # 自定义文件名

适用于会话文件以及 --mode json 生成的 JSON 事件日志。

---

哲学

omp 是 pi-mono 的一个分支，由 Mario Zechner 开发，并扩展为包含电池式的编码工作流。

核心理念：

• 保持交互式终端优先的用户体验，以适应实际编码工作
• 包含实用的内置功能（工具、会话、分支、子代理、可扩展性）
• 将高级行为设计为可配置，而非隐藏起来

---

开发

调试命令

/debug 打开用于调试、报告和性能分析的工具。

有关架构和贡献指南，请参阅 packages/coding-agent/DEVELOPMENT.md。

---

单仓库包

包	描述
@oh-my-pi/pi-ai	支持流式传输和模型/提供商集成的多提供商 LLM 客户端
@oh-my-pi/pi-agent-core	带工具调用和状态管理的代理运行时
@oh-my-pi/pi-coding-agent	交互式编码代理 CLI 和 SDK
@oh-my-pi/pi-tui	带差异渲染的终端 UI 库
@oh-my-pi/pi-natives	用于 grep、shell、图像、文本、语法高亮等功能的 N-API 绑定
@oh-my-pi/omp-stats	用于 AI 使用统计信息的本地可观测性仪表板
@oh-my-pi/pi-utils	共享工具（日志记录、流、目录/环境/进程助手）
@oh-my-pi/swarm-extension	Swarm 编排扩展包

Rust 库

库	描述
pi-natives	@oh-my-pi/pi-natives 使用的核心 Rust 原生插件
brush-core-vendored	为嵌入式 Bash 执行而分叉并 vendored 的 brush-shell
brush-builtins-vendored	Vendored 的 Bash 内置命令（cd、echo、test、printf、read、export 等）

---

许可证

MIT。参见 LICENSE。

版权所有 © 2025 马里奥·泽克纳
版权所有 © 2025–2026 坎·博吕克

oh-my-pi 快速上手指南

oh-my-pi 是一款运行在终端中的 AI 编程助手（Coding Agent）。它基于 Rust 和 TypeScript 构建，使用 Bun 运行时，提供类似 IDE 的代码智能、多代理协作系统以及强大的 Git 提交辅助功能。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (WSL2 推荐)。
• 运行时：必须安装 Bun (oh-my-pi 的核心运行时)。
  • 安装命令 (macOS/Linux): curl -fsSL https://bun.sh/install | bash
  • 安装命令 (Windows): powershell -c "irm bun.sh/install.ps1 | iex"
• Node.js (可选)：部分插件或项目依赖可能需要，但核心功能由 Bun 处理。
• Git：用于版本控制及 omp commit 等功能。
• Python (可选)：如需使用内置的 IPython 内核执行 Python 代码，需安装 Python 3.8+。

提示：国内用户若下载 Bun 速度慢，可尝试使用镜像源或代理配置。

安装步骤

oh-my-pi 通过 npm 发布，但由于其底层使用 Bun 运行，建议直接使用 bun 命令进行全局安装以获得最佳性能。

1. 全局安装

打开终端，运行以下命令：

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

如果习惯使用 npm，也可以使用：

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

2. 验证安装

安装完成后，检查版本号以确认安装成功：

omp --version

3. 初始化配置 (可选)

首次运行时，工具会自动创建配置文件目录 (~/.omp)。如需手动设置 Python 环境或其他依赖，可运行：

omp setup python

基本使用

1. 启动助手

进入任意项目目录，直接输入以下命令启动交互界面：

omp

启动后，您将进入一个类似聊天室的终端界面，可以在此输入自然语言指令让 AI 协助编写代码、解释逻辑或重构文件。

2. 常用斜杠命令 (Slash Commands)

在交互界面中，可以使用 / 开头的命令调用特定功能：

• 代码审查：

  /review
  

  交互式选择审查模式（如对比分支、未提交变更等），AI 将生成结构化报告。

• 任务管理：

  /todo
  

  创建和管理分阶段的任务列表，实时追踪进度。

• 模型切换：

  /model
  

  根据不同任务需求（如规划、快速回答、复杂编码）切换不同的 AI 模型角色。

• 自定义命令： 支持加载 TypeScript 编写的自定义命令，放置在 ~/.omp/agent/commands/ 或 .omp/commands/ 目录下即可自动识别。

3. 核心功能示例

智能 Git 提交

无需手动编写 Commit Message，oh-my-pi 可以分析代码变更并生成符合规范的提交信息：

omp commit

• 支持 --dry-run 预览，--push 直接推送。
• 自动检测不相关的变更并建议拆分为原子提交。

内置 Python 执行

在对话中直接请求运行 Python 代码，oh-my-pi 会启动持久的 IPython 内核：

请帮我分析当前目录下的 data.csv 文件，并绘制销售趋势图。

• 支持流式输出结果、渲染图片及 Markdown。
• 内置文件操作、Shell 调用等辅助函数。

多代理协作 (Task Tool)

处理复杂任务时，可以调用子代理系统并行工作：

/task 请分析整个项目的架构，找出潜在的循环依赖，并由评审员代理给出优化建议。

• 系统会自动调度 explore (探索), plan (规划), reviewer (评审) 等专用代理。
• 支持后台异步执行和实时流式查看结果。

4. 键盘快捷键

在交互界面中，常用的快捷键包括：

• Ctrl + T：展开/折叠待办事项 (Todo) 面板。
• Ctrl + C：中断当前生成的回复或取消操作。
• Esc：清除输入行或退出当前模态框。

---

现在您已经完成了 oh-my-pi 的安装并掌握了基础用法。您可以尝试在项目中输入第一个指令，例如：“帮我重构这个文件夹下的所有 TypeScript 文件，使其符合最新的 ESLint 规范”。