Oh My Pi 高阶玩家手册

Oh My Pi（omp）不只是一个终端里的 AI 编码助手。用顺手之后，它更像一个可配置、可约束、可编排的本地开发代理：多模型角色路由、子代理编排、Skills/Hooks 扩展体系、MCP 集成、多种 compaction 策略、headless JSON 输出，以及一套跨 Claude Code / Codex / Gemini 配置的兼容发现层。

这篇不是入门教程。安装、登录、第一次提问只保留最低限度；重点放在高强度日常使用时真正影响效率和稳定性的东西：配置分层、上下文文件、权限、模型角色、子代理、压缩策略和排障。

一页速查

会话入口

# 交互式会话
omp

# 带初始 prompt 启动
omp "List all .ts files in src/"

# 附加文件/图片到首条消息
omp @prompt.md @image.png "What color is the sky?"

# 非交互执行，适合脚本或 CI
omp -p "Summarize the changes in the last commit"

# stdin 管道输入
echo "review this diff" | omp -p

# 继续上次会话 / 选择历史会话恢复
omp --continue
omp --resume

# 从已有会话 fork 出一个新会话
omp --fork <session-id>

# 额外授权相邻目录
omp --add-dir ../shared ../infra

# 用独立 profile 启动（隔离 auth、session、settings）
omp --profile work

常用会话命令

命令	用途
`/settings`	交互式设置面板
`/model`	模型选择与角色分配
`/agents`	查看和配置 task 子代理
`/mcp`	管理 MCP 服务器（add/list/test/reload/reauth）
`/memory`	查看、诊断、重建记忆后端
`/compact [说明]`	手动压缩上下文
`/handoff`	生成 handoff 文档作为压缩条目
`/shake`	机械式内容裁剪（不调用模型）
`/tree`	会话树导航，可生成分支摘要
`/fork`	把当前会话 fork 成新会话
`/resume [id]`	切换/恢复会话，`@claude`/`@codex` 可导入外部会话
`/fresh`	重置 provider 流状态，保留对话内容
`/clear`	清空当前对话上下文，保留 session 文件
`/new` / `/drop`	新会话 / 删除当前会话并新开
`/share`	端到端加密分享会话链接
`/export [path]`	导出 HTML
`/dump`	导出文本转录到剪贴板
`/jobs`	查看后台异步任务快照
`/extensions`	查看/开关已发现的扩展与上下文文件
`/skill:<name>`	显式调用某个 Skill
`/hotkeys`	查看当前键位

常用快捷键

键位	用途
`Ctrl+P` / `Shift+Ctrl+P`	按 `cycleOrder` 循环切换模型角色
`Alt+M`	打开模型选择器
`Alt+P`	临时为本次会话选模型
`Alt+Shift+P`	开关 plan 模式
`Shift+Tab`	循环 thinking 等级
`Alt+A`	打开 Agent Hub（子代理看板）
`Ctrl+O`	展开工具输出
`Ctrl+T`	显示/隐藏 thinking 块
`Ctrl+R`	搜索 prompt 历史
`Ctrl+G`	用 `$EDITOR` 编辑草稿
`Alt+R`	重试上一轮失败的请求

常用 CLI 标志

参数	用途
`-p, --print`	非交互执行并退出
`--mode json`	输出结构化 JSON 事件流
`--mode rpc` / `--mode acp`	JSON-RPC / ACP 服务器模式
`--model <id-or-role>`	指定模型或角色（支持模糊匹配与 `:high` 思考后缀）
`--smol / --slow / --plan`	覆盖对应模型角色
`--thinking <level>`	off → max 共 8 档，或 `auto`
`--prewalk`	计划用强模型、首次编辑时切到便宜模型执行
`--plan-yolo`	只读规划 → 自动确认 → 切执行模型实现
`--approval-mode <mode>`	`always-ask` / `write` / `yolo`
`--yolo`	自动批准所有工具调用
`--advisor`	启用 advisor 运行时（第二模型审查每轮输出）
`--config <file>`	加载一次性配置覆盖层（可重复）
`--extension <path>`	加载扩展（可重复）
`--skills <globs>` / `--no-skills`	过滤 / 禁用 Skills
`--no-rules`	禁用规则发现
`--system-prompt` / `--append-system-prompt`	替换 / 追加系统提示
`--max-time <duration>`	限制会话最长运行时间
`--no-session`	不持久化会话

配置作用域

omp 的配置分层，不要把所有东西塞进一个文件：

作用域	位置	适合放什么	是否应提交
Global	`~/.omp/agent/config.yml`	个人偏好、模型角色、全局工具策略	否
Project	`<repo>/.omp/config.yml`	项目级模型角色、工具策略覆盖	看内容
CLI overlay	`--config <file>`	一次性实验配置	否
Profile	`~/.omp/profiles/<name>/agent/`	隔离的整套 auth/session/settings	否
Models	`~/.omp/agent/models.yml`	自定义 provider、模型元数据覆盖	否

优先级从低到高：

1	`内置默认值 <- 全局 config <- 项目 config <- --config 覆盖层 <- CLI 标志/环境变量`

最重要的合并规则：对象深合并，数组整体替换。项目配置里的 disabledProviders: [groq] 不会追加到全局列表，而是整个替换它。这是最常见的踩坑点。

日常管理用 omp config：

omp config list                    # 查看全部生效配置
omp config get theme.dark          # 查看单个值
omp config set compaction.thresholdPercent 80
omp config reset steeringMode      # 恢复默认值
omp config path                    # 打印当前 agent 目录

Profile：多套身份隔离

--profile <name> 把 auth、session、settings、MCP 用户配置全部隔离到 ~/.omp/profiles/<name>/agent/：

1 2	`omp --profile client-a omp --profile client-a --alias oca # 创建 shell 快捷方式`

适合：工作/个人账号分离、给客户项目用独立凭据、打开不可信仓库时用无凭据 profile。

上下文文件：AGENTS.md 与 RULES.md

AGENTS.md 放背景，RULES.md 放硬约束

omp 原生格式（推荐新项目使用）：

文件	作用域	行为
`~/.omp/agent/AGENTS.md`	用户级	每个会话都加载
`<repo>/.omp/AGENTS.md`	项目级	从最近的非空 `.omp/` 目录读取
`~/.omp/agent/RULES.md`	用户级	sticky 规则，每轮重新附加
`<repo>/.omp/RULES.md`	项目级	同上

关键区别：AGENTS.md 是会话开头注入一次的背景；RULES.md 是 always-apply 规则，会在长对话中持续贴靠当前轮次。长对话把开场上下文顶上去之后，普通 context file 的影响力会衰减，RULES.md 不会。

AGENTS.md 适合写：

# Project Notes

- 包管理用 pnpm，不要生成 package-lock.json。
- 测试命令：`pnpm test`，改动后跑最窄的相关测试。
- `src/generated/` 是生成产物，不要手改。
- API handler 在 `apps/api/src/routes/`。
- 优先复用现有模式，不要引入新抽象。

RULES.md 只放几条必须始终生效的硬约束，保持短：

1 2	`Never commit or push unless the user explicitly asks. Do not edit generated files.`

兼容发现：不用迁移存量配置

omp 会自动发现其他 agent 工具的上下文文件：CLAUDE.md、GEMINI.md、.github/copilot-instructions.md、裸 AGENTS.md 等。提供者优先级：native(100) > claude(80) > agents/codex(70) > gemini(60) > opencode(55) > github(30) > agents-md(10)。

同一作用域/同一目录深度，高优先级遮蔽低优先级；不同深度的文件可以共存（monorepo 里根目录和包目录的 AGENTS.md 都会加载）。

注意几个行为差异：

原生项目配置只读最近的非空 .omp/ 目录，找到就停，不继续向上走。
.claude/CLAUDE.md、.gemini/GEMINI.md 只读当前工作目录，不做祖先遍历。
裸 AGENTS.md（agents-md 提供者）会从 cwd 一路走到仓库根。

`@` 导入

上下文文件里可以用 @path 内联导入其他文件：

1 2	`架构说明见 @docs/architecture.md。发布流程见 @../RELEASE.md。`

相对路径从导入文件自己的目录解析，不是会话 cwd。最多递归五层，循环引用自动跳过，目标缺失时保留原文不报错。导入要克制——上下文文件太长时，agent 更容易漏掉具体规则。

精确关闭某个来源

整个提供者太重时，可以只关一个文件：

# config.yml
disabledExtensions:
  - context-file:user:CLAUDE.md      # 只关用户级 CLAUDE.md，Claude 的 MCP/Skills 照常加载
  - context-file:project:AGENTS.md   # 关掉所有深度的项目级 AGENTS.md

典型用途：headless 运行时（-p）关掉写给交互会话的个人指令，避免和调用方 prompt 冲突。交互式管理用 /extensions。

权限设计

权限是安全边界；AGENTS.md 只是行为指导，不是安全机制。

三档审批模式

模式	自动批准	需要审批
`always-ask`	只读工具	write、exec
`write`	只读 + 写文件	exec（bash/eval/browser/task…）
`yolo`（默认）	全部	无

工具按声明分三档：read（读数据）、write（改工作区）、exec（执行代码/起 shell/驱动浏览器/派生子代理）。未声明的工具按 exec 处理。

推荐配置：write 模式 + 命令规则

# ~/.omp/agent/config.yml 或 <repo>/.omp/config.yml
tools:
  approvalMode: write
  approval:
    bash: allow
    read: allow

bash:
  patterns:
    - match: "rm -rf *"
      approval: deny
    - match: "git push*"
      approval: prompt
    - match: "npm publish*"
      approval: deny
    - match: "kubectl apply*"
      approval: deny
    - match: "*"
      approval: allow

bash.patterns 的匹配是非对称的，设计意图是让规则读起来是什么就是什么：

deny/prompt 规则：命中整条命令或复合命令的任意一段即生效。rm -rf * 能拦住 cd /tmp && rm -rf build。
allow 规则：必须匹配整条命令，对复合命令永不生效。git * 不能给 git status && rm -rf / 背书。

另外两层保险：

内建关键命令守卫：rm -rf /、fork bomb、写 /etc/passwd、关机命令等，即使 match: "*" allow 也仍需确认。
在 yolo 模式下，裸的关键命令覆盖会被忽略，但显式的 prompt/deny 策略依然强制生效。

一个必须知道的绕过路径

bash.patterns 只管 bash 工具。eval 工具（持久 Python/JS 内核）可以通过子进程起 shell，同样的命令走 eval 就不受 bash.patterns 的 deny 约束。要堵上这条路，加一条：

1
2
3

tools:
  approval:
    eval: prompt   # 或 deny

模型与推理强度

角色系统：omp 的核心抽象

不要只想"用哪个模型"，要想"哪个角色用哪个模型"：

# ~/.omp/agent/config.yml
modelRoles:
  default: anthropic/claude-sonnet-4-5
  smol: openai/gpt-4.1-mini
  slow: anthropic/claude-opus-4-5:high
  vision: google/gemini-3.1-pro-preview
  plan: anthropic/claude-opus-4-5
  advisor: anthropic/claude-sonnet-4-5:medium

cycleOrder:
  - smol
  - default
  - slow

内置角色：

角色	用途
`default`	主会话
`smol`	轻量任务、子代理默认降级目标
`slow`	深度推理
`vision`	图像任务
`plan`	架构规划
`commit`	生成 commit message（`omp commit`）
`tiny`	后台杂务（会话标题、记忆、自动 thinking 分级），未设置时回落到 `@smol`
`task`	子代理默认模型
`advisor`	advisor 运行时

角色值可以带思考后缀（:high），也可以用 @slow 这样的角色别名互相引用。Ctrl+P 按 cycleOrder 循环切换。

建议按任务分层：

任务	建议
小改动、解释、脚本	`@smol` 或低 thinking
日常编码、测试、重构	`@default`
复杂架构、疑难 bug	`@slow` 或 `--thinking xhigh`
一次性深度推理	prompt 里写 `ultrathink`

Thinking 等级

八档：off、minimal、low、medium、high、xhigh、max，外加 auto（本地分类器按任务难度选档）。默认 high。

1 2	`omp --thinking medium "explain this function" omp config set defaultThinkingLevel auto`

auto 的上限由 providers.autoThinkingMaxEffort 控制（默认 xhigh），只有 ultrathink 能到 max。

重试与 fallback 链

模型不可用时自动降级，而不是直接失败：

retry:
  enabled: true
  modelFallback: true
  fallbackRevertPolicy: cooldown-expiry   # 冷却结束后切回主模型
  fallbackChains:
    default:
      - anthropic/claude-opus-4-5
      - openai/gpt-5.5
      - google/gemini-3-pro
    smol:
      - openai/gpt-5.5-mini
      - anthropic/claude-haiku-4-5
    # 也可以按模型或整个 provider 配：
    google-antigravity/*:
      - google/*
      - google-vertex/*

上下文溢出时的模型提升

小上下文模型（如 *-spark）打满上下文时，omp 会优先尝试 contextPromotionTarget 指定的更大模型重试，不做压缩。这是模型元数据驱动的，自定义模型可以在 models.yml 的 modelOverrides 里配。

上下文控制

五种压缩方法

omp 的压缩不是单一的"总结一下"，而是按 compaction.methodOrder 依次尝试的方法链：

1
2
3

compaction:
  methodOrder: [remote, snapcompact, handoff, shake, soft]
  thresholdPercent: 80

方法	机制	特点
`remote`	provider 原生压缩（OpenAI Responses 等）	最快，看 provider 支持
`snapcompact`	把历史渲染成位图 PNG，走视觉 token	本地确定性，无额外模型调用，成本极低，需要视觉模型
`handoff`	生成结构化 handoff 文档	保活 prefix cache，适合跨阶段交接
`shake`	机械裁剪：大段工具输出替换成 `artifact://` 引用	不调用模型，即时完成
`soft`	经典 LLM 摘要	兜底

前一个方法不可用或失败时自动落到下一个。snapcompact 是其中最特别的：它把被丢弃的历史序列化后用像素字体打印成模型可读的位图帧，按模型的视觉计费方式选帧尺寸——实测 200k token 规模下 QA 召回率和原文相当，但计费 token 低得多。

手动控制：

1
2
3

/compact 保留所有和鉴权相关的决策细节
/handoff
/shake

压缩前的辅助机制

到达阈值之前还有两层减重：

工具输出剪枝：旧的超大工具结果被替换成 [Output truncated - N tokens]，最近 40k token 受保护。
无用结果消除：零结果的搜索、超时的等待这类结果直接折叠成 [Uneventful result elided]。

所以看到上下文占用下降不一定是压缩了，可能只是剪枝。

/fresh、/clear、/new、/drop 的区别

命令	对话内容	session 文件	适用
`/fresh`	保留	保留	provider 流状态卡住（prompt cache 过期、服务端会话漂移）
`/clear`	清空	保留（追加 reset 边界）	同一会话里开新任务
`/new`	全新	新建	全新任务
`/drop`	删除后新建	尝试删除	彻底丢弃当前会话

/fresh 是最容易误用成 /clear 的：它解决的是"provider 那边状态坏了"，不是"我想重来"。

/tree：会话分支导航

omp 的会话是树形的。/tree 可以在分支间跳转；开启 branchSummary.enabled 后，离开一个分支时会自动生成该分支的摘要并附加到目标分支，被放弃的探索不会白做。

Magic Keywords

prompt 里的独立小写单词会触发隐藏的单轮指令：

关键词	效果
`ultrathink`	多步推理指令；auto thinking 下本轮拉到模型最高 effort
`orchestrate`	多代理编排契约：拆分任务、并行委派、逐阶段验证
`workflowz`	基于 eval 内核的确定性工作流契约（`agent()`/`parallel()`/`pipeline()`），适合大规模评审/迁移

1
2
3

ultrathink about the failure modes before changing this API
orchestrate the migration described in docs/plan.md
workflowz an adversarial review of the authentication changes

匹配是刻意的：必须小写、独立成词，代码块、行内代码、XML 标签里的不算；orchestrate()、orchestrate.ts 不会触发。作用范围只有当前这一轮。开关在 /settings → Interaction → Magic Keywords，或 omp config set magicKeywords.enabled false。

子代理与 Agent Hub

内置子代理

代理	定位
`scout`	只读探索，快速压缩上下文回报（默认禁用 read 摘要，返回原文）
`task`	通用执行代理（默认）
`sonic`	低推理、纯机械任务
`designer`	UI/UX
`reviewer`	代码审查
`security-reviewer`	安全审查
`librarian`	读第三方库源码给出源验证结论

探索大仓库时把探索交给 scout，主上下文只收压缩后的结论：

Use a scout to investigate how token refresh works. Return only:
1. relevant files
2. call flow
3. edge cases
4. tests that cover it

自定义子代理

~/.omp/agent/agents/security-audit.md 或项目级 .omp/agents/：

---
name: security-audit
description: Review code for auth, injection, and secret leakage
model: "@slow"
tools: read, grep, bash
---

You are a security-focused code reviewer.

Focus on:
- authentication and authorization bypass
- injection risks
- secret handling

Return findings with severity, file path, and concrete fix guidance.
Do not modify files.

frontmatter 关键点：

model 支持 @role 别名和优先级列表，改角色映射不用改代理定义。
tools 限制工具面；给了 tools 会自动加 yield。
spawns 控制它能再派生哪些代理（* 或名单）；递归深度上限 task.maxRecursionDepth 默认 2。
prewalk: true：用自己的模型起步，首次编辑时切到 smol 执行——强模型规划、便宜模型干活。
advisor: true：给这个代理的子会话配一个 advisor 模型旁路审查。
read-summarize: false：让它的 read 返回原文而非结构摘要（scout/librarian 内置如此）。

发现优先级：项目 .omp/agents > 用户 ~/.omp/agent/agents > 扩展包 > Claude marketplace 插件 > 内置。同名 first-wins，所以项目级可以覆盖内置代理。

Agent Hub：子代理看板

派发后按 Alt+A 打开 Hub：

实时名册：状态、模型、当前活动、成本、token 数。
Enter 进入某个子代理的会话，直接读转录、发消息 steer。
r 唤醒 parked 代理，x 杀掉，t 切换平铺/树状视图。
恢复旧会话时，Hub 会从持久化产物里重建历史子代理行。

权限边界

子代理以 headless yolo 模式运行——父会话的 task 工具审批就是授权边界。你的 tools.approval.<tool> 设置仍然有效：deny 会拦住子代理的工具调用；prompt 在 headless 里无法满足，会直接拒绝该调用。

Advisor 与 WATCHDOG

advisor 是第二个模型，每轮结束后旁路审查主代理的输出，发现问题时注入意见甚至打断：

1
2
3

omp --advisor
# 或
omp config set advisor.enabled true

模型来自 modelRoles.advisor。它适合长无人值守任务：主代理干活，advisor 盯着。项目里可以放 WATCHDOG.md 给 advisor 提供项目特定的审查要点。

相关参数：advisor.immuneTurns（被打断后几轮内降级为非打断提示，默认 3）、advisor.syncBacklog（允许主代理等 advisor 追上进度的上限）。也可以在 /agents 里给单个子代理配 advisor。

Skills

Skills 是文件化的能力包：元数据进系统提示，正文按需通过 skill:// 读取，也可以 /skill:<name> 显式调用。

目录布局

.omp/skills/                    # 或 ~/.omp/agent/skills/，或其他兼容来源
  migration-review/
    SKILL.md
    references/
      checklist.md

注意：发现是非递归的，只扫 skills/ 下面一层。skills/team/internal/SKILL.md 不会被发现。

示例

---
name: migration-review
description: Review database migrations for safety, rollback, and production impact
---

Review the migration with this checklist:

1. Identify every schema and data change.
2. Check backward compatibility.
3. Check for long locks or full table scans.
4. Verify rollback strategy.
5. Report findings as P0/P1/P2 with file references.

Do not edit files unless explicitly asked.

使用：

1	`/skill:migration-review review the current diff`

agent 也可以自己通过 read 工具读 skill://migration-review 和 skill://migration-review/references/checklist.md。Skill 目录内的资源用 skill://<name>/<path> 访问，路径逃逸（..、绝对路径）会被拒绝。

Skills 和其他机制的边界

机制	放什么
`AGENTS.md`	稳定事实、仓库约定
`RULES.md`	必须始终生效的硬约束
Skill	可复用流程、checklist、按需加载的知识
Hook/Extension	事件驱动的确定性动作
MCP	外部系统和数据源
权限配置	安全边界

omp 还会发现 Claude/Codex 等工具目录下的 skills，并在同名时按提供者优先级去重；自动学习生成的 skills（autolearn.enabled）放在 ~/.omp/agent/managed-skills，优先级最低，同名手写的永远赢。

MCP

omp 原生配置位置：

项目：.omp/mcp.json（可提交，团队共享）
用户：~/.omp/agent/mcp.json（profile 下为 ~/.omp/profiles/<name>/agent/mcp.json）

同时自动翻译 Claude Code、Codex、Gemini CLI、Cursor、Windsurf、VS Code 的存量 MCP 配置，基本零迁移。

文件示例

{
  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/alice/projects"]
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

最常见的坑：远程服务器忘了写 "type": "http"，omp 会按 stdio 处理然后报"requires command field"。

密钥处理

三种方式，按安全性排序：

{
  "headers": {
    "Authorization": "Bearer ${GITHUB_TOKEN}"
  },
  "env": {
    "API_KEY": "!op read op://dev/mcp/api-key"
  }
}

${VAR}：发现时从环境展开。
"VAR_NAME"：整个值是环境变量名时，连接前取值。
"!command"：执行命令取 stdout（10s 超时，进程内缓存）。适合接 1Password/Bitwarden。

OAuth 服务器授权一次后，凭据按 profile + URL 绑定存储，项目 mcp.json 只提交定义不提交凭据；每个 profile 用 /mcp reauth <name> 授权自己的账号。

管理命令

/mcp add        # 向导式添加
/mcp list       # 看每个服务器来自哪个配置文件
/mcp test <name>
/mcp reload     # 改完配置后重连
/mcp reauth <name>

不想要的服务器用用户级 disabledServers 隐藏，比改每个来源的配置干净。

Hooks 与 Extensions

Hooks 是事件驱动的拦截器，TS/JS 模块，默认导出工厂函数。放在 .omp/hooks/ 下自动发现，或 --hook <path> 显式加载。

示例：拦截危险命令

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

export default function (pi: HookAPI): void {
  pi.on("tool_call", async (event, ctx) => {
    if (event.toolName !== "bash") return;
    const cmd = String(event.input.command ?? "");
    if (!/rm\s+-rf/.test(cmd)) return;

    if (!ctx.hasUI) return { block: true, reason: "rm -rf blocked (no UI)" };
    const ok = await ctx.ui.confirm("Dangerous command", `Allow: ${cmd}`);
    if (!ok) return { block: true, reason: "user denied command" };
  });
}

能拦什么

tool_call（执行前）：{ block: true, reason } 阻止；返回 input 可改写参数。处理器抛异常时失败关闭（直接阻止）。
tool_result（执行后）：可改写返回内容，比如给输出脱敏。
context：每次 LLM 调用前过滤/改写消息链。
session_before_compact / session.compacting：取消压缩或注入自定义上下文。
before_agent_start：每轮开始前注入消息。
session_before_switch 等生命周期事件：可取消。

Hooks 还能注册 slash 命令（pi.registerCommand）、自定义 UI（ctx.ui.custom）、状态栏文本（ctx.ui.setStatus）。更完整的能力（自定义工具、provider 注册、主题）走 Extensions，参见 extensions 文档和 omp plugin / omp install。

Headless 与脚本化

-p 是把 omp 变成 Unix pipeline 一环的分水岭：

# 普通管道
git diff main...HEAD | omp -p "Review this diff. Return only correctness bugs and missing tests."

# JSON 事件流
omp -p --mode json "List every TODO in src/" > todos.json

# 限制运行时长，防止 CI 挂死
omp -p --max-time 10m "Fix the failing lint"

# 不持久化会话
omp -p --no-session "one-off question"

# 覆盖配置做一次性实验
omp -p --config ./ci-settings.yml "check this failure"

CI 里的建议：

输入走 stdin 或 @file，减少 agent 自由探索。
用 --mode json 消费输出，不要解析自然语言。
显式 --approval-mode 和 --tools 收紧工具面；只读审查任务禁掉写工具。
非交互运行时用 --config 覆盖层关掉写给交互会话的用户级上下文文件（disabledExtensions），避免和 CI 自己的 prompt 冲突。

两个进阶传输模式：--mode rpc 是 stdio 上的 JSON-RPC 服务器，适合自己写客户端；--mode acp（或 omp acp）是 Agent Client Protocol，Zed 等编辑器直接接。ACP 要无人值守执行，记得显式配 tools.approvalMode: yolo 或 omp acp --yolo。

Prewalk 与 Plan-yolo：让贵模型只做值钱的事

两个省钱又保质的启动模式：

# 用当前模型做规划和 todo 拆分，首次编辑时切到 smol 执行
omp --prewalk --model opus "refactor the auth module"

# 只读规划 → 自动确认计划 → 切 smol 实现
omp --plan-yolo "add partial refund support"
omp --plan-yolo --plan-yolo-into anthropic/claude-sonnet-4-5 "..."

--prewalk 的逻辑：计划阶段的 todo 列表就绪后，agent 第一次 edit/write 时切换到 --prewalk-into 指定的模型（默认 @smol）。强模型的推理用在"想清楚"上，机械执行交给便宜模型。子代理 frontmatter 里的 prewalk: true 是同一机制的代理级版本。

组合工作流模板

PR 守护

orchestrate: keep this branch's PR green.

完成条件：
- CI 全绿
- 所有可执行的 review 意见已处理
- pnpm test 退出码 0
约束：不改公共 API，不 rebase 已推送的提交

大迁移

workflowz migrate all packages from LegacyLogger to StructuredLogger.

Plan:
- split work by package
- each worker updates usages and local tests
- verifier agents sample migrated packages
- aggregate failures into a fix list
- stop before committing

机械但范围大的迁移交给多代理编排，比在单会话里塞满上下文稳。

调试模式

This test fails. Do not edit code yet.

Please:
1. run the smallest failing test
2. read the failure output
3. identify the first wrong assumption
4. inspect only the relevant code path
5. propose a fix with verification command

间歇性问题让 agent 建假设表，先跑最便宜的证伪命令。

大仓库工作流

从子目录启动：monorepo 里 cd apps/payments && omp，跨包再 --add-dir ../../packages/db。
分层上下文文件：根目录 .omp/AGENTS.md 写全局，包目录写局部；不同深度的文件会都加载。
worktree 隔离：子代理可以在隔离的 git worktree 里干活，不污染主工作区；omp worktree 管理这些 agent 托管的 worktree（~/.omp/wt）。
先画地图再动手：

1 2	`Do not edit files yet. Find the minimal set of packages involved in adding OAuth refresh rotation. Return: package list, relevant entrypoints, likely tests, files you would not touch.`

常见故障排查

上下文文件没加载

按顺序查：

原生项目配置只读最近的非空 .omp/——中间有个不含 AGENTS.md 的 .omp/ 会挡住更上层的。
.claude/CLAUDE.md 只读 cwd，不做祖先遍历；裸 AGENTS.md 才走 walk-up。
空文件不贡献内容。
disabledProviders 把发现源整个关了；disabledExtensions 关了单个文件。/extensions 能看到每个文件的状态。
数组替换陷阱：项目配置里的 disabledProviders 是替换全局列表，不是追加。

加载了错误的文件

同深度高优先级提供者遮蔽低优先级（native > claude > gemini > github > agents-md）。要确定性行为：把规则挪进 .omp/AGENTS.md（native 永远赢），或关掉竞争来源。

RULES.md 不生效

只有 native 位置的 RULES.md 是 sticky 的：用户 agent 目录 + 最近非空项目 .omp/。放在别的地方不识别。另外规则按名字去重，用户级 RULES.md 会遮蔽项目级的。

MCP 连不上

1
2
3

/mcp list          # 服务器在不在、来自哪个文件
/mcp test <name>   # 单测
/mcp reload        # 改完配置重连

requires "command" field：远程服务器忘了 "type": "http"。
both "command" and "url"：二选一。
stdio 首次 npx 下载慢导致超时：加大 OMP_MCP_TIMEOUT_MS。
配置是在会话启动时发现的，改完用 /mcp reload，不用重启。

会话越来越笨

/compact 或检查自动压缩阈值（compaction.thresholdPercent）。
大探索交给 scout，主上下文只收结论。
稳定规则沉淀到 AGENTS.md，硬约束挪到 RULES.md（sticky，长对话不衰减）。
检查 compaction.methodOrder 里 snapcompact 是否在视觉模型上生效。

provider 流状态异常

响应卡住、prompt cache 异常、服务端会话漂移：先 /fresh（保留对话，重置 provider 状态），不要急着 /clear。

模型总是落到 fallback

omp models 看可用模型和凭据状态。
启动时的 config warning 会列出 fallback 链里的未知模型。
retry.fallbackRevertPolicy: never 会停在 fallback 上不切回——检查是不是设错了。

我的推荐默认配置

`~/.omp/agent/config.yml`

modelRoles:
  default: anthropic/claude-sonnet-4-5
  smol: openai/gpt-4.1-mini
  slow: anthropic/claude-opus-4-5:high

defaultThinkingLevel: high

tools:
  approvalMode: write
  approval:
    bash: allow
    read: allow
    eval: prompt

bash:
  patterns:
    - match: "rm -rf *"
      approval: deny
    - match: "git push*"
      approval: prompt
    - match: "npm publish*"
      approval: deny
    - match: "*"
      approval: allow

compaction:
  methodOrder: [remote, snapcompact, handoff, shake, soft]
  thresholdPercent: 80

retry:
  modelFallback: true
  fallbackRevertPolicy: cooldown-expiry

项目 `.omp/AGENTS.md`

# Project Notes

- Prefer minimal, behavior-preserving changes.
- Read existing patterns before adding abstractions.
- Do not edit generated files under src/generated/.
- Run the narrowest relevant test after each meaningful change.
- When uncertain, state the uncertainty and gather evidence before editing.

项目 `.omp/RULES.md`

1 2	`Never commit or push unless the user explicitly asks. Do not modify database schema without an approved migration plan.`

日常节奏

1. 先让 agent 读局部代码，不改文件。
2. 要求最小改动计划（复杂任务用 --prewalk 或 plan 模式）。
3. 计划确认后执行，每个阶段跑窄测试。
4. Alt+A 看子代理进展，必要时进去 steer。
5. 收尾前 /compact 或交给自动阈值。
6. 新学到的稳定规则写回 AGENTS.md / RULES.md / Skill。

参考资料

Oh My Pi GitHub 仓库（docs/ 目录含完整内部文档）
omp --help / omp <command> --help：运行时帮助
omp config list：完整配置 schema 的权威来源
会话内 /hotkeys：当前构建的实际键位