Oh-My-Pi (omp) 入门指导手册

Dark-Source2026-06-10 10:05

Oh-My-Pi (omp) 入门指导手册

版本：2026-06-09

适用对象：已从 OpenCode 转向 oh-my-pi 的开发者

一、Oh-My-Pi 是什么

Oh-My-Pi （简称 omp）是 pi-mono 的硬分支（hard fork），由 Can Bölük 维护。如果说 pi-mono 是"极简主义"的终端 Agent，那 oh-my-pi 就是"开箱即用"的完整版本------内置了 LSP、DAP 调试器、多 Agent 编排、MCP 支持、AST 工具等，装完就能用，不需要像 pi 那样手动拼装扩展。

一句话定位 ：omp = pi-mono 的完整发行版，类似 LazyVim 之于 Neovim。

二、安装

方式一：npm（推荐）

bash 复制代码 
npm install -g oh-my-pi

方式二：Bun（更快）

bash 复制代码 
bun install -g oh-my-pi

方式三：Cargo（Rust 生态）

bash 复制代码 
cargo install oh-my-pi

验证安装

bash 复制代码 
omp --version
# 预期输出：oh-my-pi v12.x.x

三、目录结构与配置文件

oh-my-pi 的所有配置集中在 ~/.omp/agent/ 目录下：

复制代码 
~/.omp/agent/
├── auth.json              # API Key 凭证（权限 600）
├── models.yml             # 模型提供商配置
├── settings.json          # 全局设置
├── sessions/              # 会话历史
├── skills/                # 技能文件（Markdown / TypeScript）
├── extensions/            # 自定义扩展
│   └── cad-generator/
│       └── index.ts
└── logs/                  # 运行日志

3.1 凭证配置：auth.json

json 复制代码 
{
  "anthropic": {
    "type": "api_key",
    "key": "sk-ant-api03-你的Key"
  },
  "openai": {
    "type": "api_key",
    "key": "sk-你的Key"
  }
}

设置权限：

bash 复制代码 
chmod 600 ~/.omp/agent/auth.json

3.2 模型配置：models.yml

这是 oh-my-pi 的核心配置，支持多供应商、多模型、角色路由。

yaml 复制代码 
providers:
  anthropic:
    baseUrl: https://api.anthropic.com
    api: anthropic-messages
    apiKey: ANTHROPIC_API_KEY
    models:
      - id: claude-sonnet-4
        name: Claude Sonnet 4
        contextWindow: 200000
        maxTokens: 8192
      - id: claude-opus-4
        name: Claude Opus 4
        contextWindow: 200000
        maxTokens: 16000

  openai:
    baseUrl: https://api.openai.com/v1
    api: openai-completions
    apiKey: OPENAI_API_KEY
    models:
      - id: gpt-4o
        name: GPT-4o
        contextWindow: 128000
      - id: o3-mini
        name: o3-mini
        reasoning: true

  local:
    baseUrl: http://localhost:8000/v1
    api: openai-completions
    models:
      - id: Qwen3.5-32B-AWQ
        name: Qwen3.5 32B AWQ
        contextWindow: 32000

  deepseek:
    baseUrl: https://api.deepseek.com
    api: openai-completions
    apiKey: DEEPSEEK_API_KEY
    models:
      - id: deepseek-v4-pro
        name: DeepSeek V4 Pro
        reasoning: true
        contextWindow: 1000000

3.3 全局设置：settings.json

json 复制代码 
{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4",

  "roles": {
    "default": { "model": "claude-sonnet-4" },
    "plan": { "model": "claude-opus-4" },
    "smol": { "model": "claude-haiku-3" },
    "commit": { "model": "claude-sonnet-4" }
  },

  "extensions": [
    "~/.omp/agent/extensions/cad-generator"
  ],

  "skillsDir": "~/.omp/agent/skills",

  "lsp": {
    "autoStart": ["python", "typescript"],
    "autoInjectDiagnostics": ["python", "typescript"]
  },

  "steeringMode": "interactive",
  "interruptMode": "immediate",
  "compaction": {
    "strategy": "auto",
    "threshold": 0.8
  }
}

四、基本使用

4.1 启动

bash 复制代码 
# 默认启动（使用 defaultProvider/defaultModel）
omp

# 指定模型
omp --provider openai --model gpt-4o

# 指定角色（使用 roles 中定义的配置）
omp --role plan

# 加载自定义扩展
omp -e ~/.omp/agent/extensions/cad-generator/index.ts

# 打印模式（非交互，适合脚本）
omp -p "分析当前目录的 package.json"

4.2 内置命令

在 omp 交互界面中可用的命令：

命令 功能
/agents 打开 Agent Control Center，查看所有 Sub-agent
/mcp 管理 MCP 服务器
/models 切换当前会话的模型
/roles 切换角色
/compact 手动压缩上下文
/exit 或 Ctrl+D 退出

4.3 快捷键

快捷键 功能
Ctrl+C 中断当前工具执行
Ctrl+D 退出会话
↑ / ↓ 浏览历史消息
Tab 命令补全

五、核心功能详解

5.1 多 Agent（Sub-agent）--- 内置 Task Tool

oh-my-pi 内置 6 个预设 Agent + 支持自定义 Agent，无需安装额外扩展。

bash 复制代码 
# 在 omp 中直接调用：

# 1. 探索型 Agent（分析代码结构）
/explore "分析 src/ 目录的模块依赖关系"

# 2. 规划型 Agent（生成执行计划）
/plan "设计一个 CAD 图纸批量生成方案，输出到 PLAN.md"

# 3. 设计型 Agent（架构设计）
/designer "为算量软件设计数据流架构"

# 4. 审查型 Agent（Code Review）
/reviewer "审查刚才的 PR 修改"

# 5. 任务型 Agent（执行具体任务）
/task "重构 auth 模块，支持 OAuth 2.0"

# 6. 快速任务（轻量级一次性）
/quick_task "修复第 42 行的类型错误"

隔离机制：每个 Sub-agent 运行在独立的 git worktree 或 overlayfs 中，互不干扰。

自定义 Agent ：在 ~/.omp/agent/agents/ 目录下创建 YAML 定义：

yaml 复制代码 
# ~/.omp/agent/agents/cad-expert.yml
name: cad-expert
description: CAD 图纸生成专家
system_prompt: |
  你是 CAD 图纸生成专家，精通 ezdxf、DXF 格式和建筑制图规范。
  你擅长将需求转换为结构化的 Python 脚本。
tools: [read, write, edit, bash]
model: claude-sonnet-4

5.2 LSP 支持 --- 内置，无需配置

oh-my-pi 原生集成 LSP，支持 40+ 语言服务器。

bash 复制代码 
# 自动识别项目语言并启动对应 LSP
# 例如进入 Python 项目：
cd /project/vllm
omp
# 自动启动 pyright

# 手动触发 LSP 工具（AI 会自动使用）：
# "帮我分析 src/index.py 的类型错误"
# "找到 process() 函数的所有引用"
# "将 User 类重命名为 Account"

支持的 LSP 功能：

  • 诊断（Diagnostics）
  • Hover 类型信息
  • 定义跳转（Go to Definition）
  • 引用查找（Find References）
  • 符号搜索（Workspace Symbols）
  • 重命名（Rename）
  • 代码补全（Completions）

5.3 Skill 支持

oh-my-pi 支持两种 Skill：

A. Markdown 技能（上下文知识）

bash 复制代码 
cat > ~/.omp/agent/skills/vllm-deploy.md << 'EOF'
# VLLM 部署技能

## 环境
- 服务器：8×V100，无 NVLink
- 路径：/project/vllm
- Conda：vllm
- 模型格式：AWQ, GPTQ

## 常用命令
- 启动 Qwen3.5：python -m vllm.entrypoints.openai.api_server --model Qwen/Qwen3.5-32B-AWQ --tensor-parallel-size 8
- 测试 API：curl http://localhost:8000/v1/models
EOF

使用时：

bash 复制代码 
omp -s vllm-deploy
# 或在 omp 中：
# "按照 vllm-deploy 技能中的规范，帮我写一个启动脚本"

B. TypeScript 工具技能（可执行工具）

typescript 复制代码 
// ~/.omp/agent/skills/dxf-extract/index.ts
import type { ExtensionAPI } from "@oh-my-pi/omp-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.registerTool({
    name: "dxf_extract_layer",
    description: "提取 DXF 指定图层的实体",
    parameters: {
      type: "object",
      properties: {
        file: { type: "string" },
        layer: { type: "string" }
      }
    },
    handler: async ({ file, layer }) => {
      // 实现...
    }
  });
}

5.4 TUI 界面

oh-my-pi 的 TUI 相比 pi-mono 有显著增强：

  • Powerline 状态栏：底部显示当前模型、git 分支、LSP 状态、Token 用量
  • 分组工具显示：工具调用按类型分组，更易读
  • 流式预览：代码 diff 实时渲染，不闪烁
  • SQLite 持久历史：跨会话保留历史记录
  • 欢迎界面：启动时显示可用命令和最近会话

六、与 OpenCode 的区别

对比维度 Oh-My-Pi OpenCode
定位 终端原生、灵活可定制 产品化、开箱即用
安装体积 轻量（Node.js/Bun） 较重（独立 CLI + 依赖）
系统提示词 约 2-3K tokens（仍比 OpenCode 小） 10K+ tokens
内置工具 极简四件套 + AST + LSP + DAP 丰富工具集（glob, web, todo 等）
Sub-agent 内置 Task Tool（6 种预设 + 自定义） Task/Subagent 工具
LSP ✅ 原生内置，40+ 语言 ✅ 可选配置
DAP 调试器 ✅ 内置（dlv, debugpy, lldb） ❌ 无
MCP ✅ 原生内置（/mcp 管理） ✅ 内置
AST 工具 ✅ ast_grep, ast_edit ❌ 无
Hashline 编辑 ✅ 高 token 效率 ❌ 传统 edit/write
TUI 体验 终端原生，差分渲染 终端 + 可选 GUI
扩展生态 npm 包 + 本地 TS 文件 npm 插件 + MCP
社区规模 较小但活跃 140K+ stars，更大
模型支持 20+ 供应商，本地模型友好 75+ 供应商
配置复杂度 高（models.yml + settings.json + 扩展） 低（ mostly 环境变量 + 简单配置）
Polish 程度 像 NeoVim/LazyVim（功能强但需配置） 像 VS Code（ polished 产品）

关键差异详解

1. Token 效率

oh-my-pi 的系统提示词比 OpenCode 小得多（约 2-3K vs 10K+），同模型下上下文利用率更高，长会话更稳定。

2. 工具策略

  • OpenCode：工具丰富但"保守"，AI 不会过度使用高级工具
  • oh-my-pi：工具更多（AST、LSP、DAP），系统提示词"强迫"AI 使用这些工具，有时会觉得"用力过猛"

3. 编辑方式

  • OpenCode：传统 edit / write / apply_patch
  • oh-my-pi：Hashline 编辑（基于行哈希的锚定替换，token 效率高 61%，避免行号漂移）

4. 调试能力

oh-my-pi 是唯一支持 DAP（Debug Adapter Protocol）的终端 Agent，可以设断点、单步执行、查看变量。OpenCode 没有调试器。

5. 项目类型适配

  • 纯代码项目：两者差距不大，OpenCode 更 polished
  • 混合项目（代码 + SQLite + PDF + 压缩包 + 网页）：oh-my-pi 的 AST 工具和文件类型支持更有优势

七、迁移建议（从 OpenCode 到 oh-my-pi）

如果你...

情况 建议
满意 OpenCode，只是好奇 先别迁移，两边并行试用一周
OpenCode TUI 卡顿 试试 oh-my-pi，它的差分渲染更流畅
需要 DAP 调试 必须迁移，OpenCode 没有调试器
大量本地模型（vLLM/OLLama） oh-my-pi 对本地模型优化更好
喜欢定制和扩展 oh-my-pi 更适合，OpenCode 相对封闭
追求"装完就用" 留在 OpenCode，oh-my-pi 需要配置投入

并行试用方案

bash 复制代码 
# 方案 A：OpenCode（现有工作流）
opencode

# 方案 B：oh-my-pi（新工作流）
omp

# 同一个任务，两边各做一次，对比：
# 1. 响应速度
# 2. Token 消耗
# 3. 工具使用合理性
# 4. 输出质量

八、快速启动清单

bash 复制代码 
# 1. 安装
npm install -g oh-my-pi

# 2. 初始化配置目录
mkdir -p ~/.omp/agent/{skills,extensions,sessions,agents}

# 3. 配置 API Key
cat > ~/.omp/agent/auth.json << 'EOF'
{
  "anthropic": { "type": "api_key", "key": "sk-ant-api03-..." }
}
EOF
chmod 600 ~/.omp/agent/auth.json

# 4. 配置模型
cat > ~/.omp/agent/models.yml << 'EOF'
providers:
  anthropic:
    baseUrl: https://api.anthropic.com
    api: anthropic-messages
    apiKey: ANTHROPIC_API_KEY
    models:
      - id: claude-sonnet-4
        name: Claude Sonnet 4
        contextWindow: 200000
EOF

# 5. 配置全局设置
cat > ~/.omp/agent/settings.json << 'EOF'
{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4",
  "skillsDir": "~/.omp/agent/skills"
}
EOF

# 6. 测试启动
omp
# 输入："你好，请列出当前目录的所有 Python 文件"

九、常见问题

Q: oh-my-pi 和 pi-mono 能共存吗？

A: 可以。pi 和 omp 是不同的 CLI 命令，配置目录也不同（~/.pi/ vs ~/.omp/）。但建议最终选一个主力工具。

Q: 我之前写的 pi 扩展能直接用吗？

A: 代码逻辑基本兼容，只需改导入路径：

typescript 复制代码 
// pi-mono
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
// oh-my-pi
import type { ExtensionAPI } from "@oh-my-pi/omp-coding-agent";

Q: oh-my-pi 支持 Windows 吗？

A: 支持，通过 Node.js/Bun 跨平台。但部分功能（如 DAP 的某些调试器）在 Windows 上可能需要 WSL2。

Q: 如何更新 oh-my-pi？

A: npm update -g oh-my-pi 或 omp update --self。

十、参考资源

相关推荐
咖啡星人k1 小时前
从 Vibe Coding 到专业开发：MonkeyCode 如何重新定义AI编程工作流
人工智能·ai编程·monkeycode
Holman2 小时前
给 Claude Code 装技能包：Skills 实战
人工智能·ai编程
带刺的坐椅2 小时前
SolonCode（编码智能体）支持鸿蒙 PC
java·web·ai编程·harmonyos·soloncode·鸿蒙 pc
南知意-2 小时前
MonkeyCode：长亭开源的企业级AI开发平台，GitHub 3.2k Star！
人工智能·ai·开源·github·ai编程·开源项目
黄金旺铺2 小时前
Super Cursor
ai编程·cursor
大蚂蚁2号3 小时前
提示词工程深度全解：从入门话术到生产级系统构建
ai编程
sunneo3 小时前
第七节：Workspace Trust & Permissions——安全的 AI 协作
ai作画·aigc·ai编程·ai写作·ai-native
脱脱克克3 小时前
使用 TRAE / VS Code + DeepSeek V4 开发微信小程序、网页
微信小程序·ai编程·环境配置
mpr0xy3 小时前
行走编程：把你的 Mac 变成一台随身 AI 开发工作站
人工智能·macos·ai·大语言模型·ai编程·ai写需求
热门推荐
01【AI】2026 年具身智能模型和世界模型总结02GitHub 镜像站点03Codex 下载安装指南：Windows 和 macOS 官方版下载042026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf052026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？06AI科技热点日报 | 2026年6月1日07《置身钉内》原文-可播放阅读08【踩坑记录 | 第一篇】微软商店无法使用时，如何手动安装 OpenAI Codex？附`.msix`文件系统错误解决方法09CC-Switch 下载、安装与使用配置指南【2026.5.29】10Agnes AI 全模态 API 免费实测报告：文生图 + 文生视频完整测试