装完 omp 只会聊天？那你可能只用了个开头：从一句 Prompt 到可验证交付

先说结论

omp 真正拉开差距的地方，不是“能在终端里回答代码问题”，而是把一次开发任务做成一条可以看、可以打断、可以复核、可以续接的流水线：先说清目标和边界，再调查或进入只读 Plan，必要时把独立工作分给子代理，借 LSP、DAP 和 Hashline 完成修改，最后拿测试、诊断、diff 与剩余风险交差。

本文承接上一篇 pi 与 oh-my-pi 介绍及安装指南，不再重复安装。写作时实测版本为 omp 18.0.8，官方主线已到 18.0.10；项目更新很快，细节最终以你本机的 omp --help、/hotkeys 和官方文档为准。正文与截图不含任何真实密钥、私人地址、机器名或账号信息。

一、问题背景：装好了，却只把 omp 当成“会改代码的聊天框”

很多人的第一次 omp 对话是这样的：

帮我看看这个项目。

这句话不能说错，但它把最重要的决定全丢给了模型：看哪里、为了什么看、能不能改、改到什么程度、用什么证明改对了、什么时候应该停。结果通常有三种：读了一大圈却没有结论；顺手改了不该改的文件；最后说“已完成”，你却不知道它到底验证过什么。

这不是 omp 工具不够多，恰恰是工具太多。它能读文件、跑命令、编辑代码、调用语言服务器、开调试器、派子代理、查网页、操作浏览器、管理会话。就像你把一整间厨房交给一个厨师，却只说“做点吃的”，那最后端上来什么都不奇怪。

问题的根因可以压缩成一句话：我们给了它工作能力，却没有给它验收标准。

官方 Quickstart 的示例很值得抄作业：找一个能在本地验证的小问题，解释发现，做最小安全修复，再跑最相关的检查。这里同时出现了目标、范围、修改原则和验证方式，而不是一句“你自由发挥”。

二、先换一个脑回路：你不是在问答案，而是在发一张“可验收工单”

把 omp 想成一个能看仓库、能动手、也会找同事协作的工程师。给工程师派活时，一张靠谱工单至少有五件事：

1. 目标：最终要发生什么变化。
2. 范围：重点看哪些目录、文件或行为。
3. 禁区：什么不能改，什么动作未经允许不能做。
4. 验证：哪条测试、哪项诊断或哪个可观察结果算通过。
5. 停止条件：遇到什么情况先停下来问，而不是继续猜。

我常用下面这个模板，简单任务不必逐项写标题，但脑子里最好有这些格子：

目标：修复批量导入时重复写入的问题。
范围：只检查导入服务和对应的单元测试。
禁区：不改数据库结构，不改公开接口，不提交、不推送。
验证：先复现，再跑最小相关测试；最后给出 diff 摘要和命令退出状态。
停止条件：如果根因涉及数据迁移，先说明方案和回滚风险，等我确认后再改。

这不是“提示词玄学”。它只是把平时给真人同事说的话写完整。模型越强，完整边界越能让它把能力用在正确方向；模型稍弱，清楚的验收条件更能防止它跑偏。

三、第一次完整使用：从项目根目录开始，盯住状态栏和证据卡片

3.1 从正确目录启动

安装完成后，日常入口其实很简单：

cd my-project
omp

启动目录会影响项目配置、会话归属、上下文文件和工具能看到的工作区。第一眼先看状态栏里的路径、当前模型、思考级别、模式、Git 状态与上下文占用。它不是装饰条，更像汽车仪表盘：方向不对时，继续踩油门只会离目的地更远。

如果只是临时做一次审计，可以从命令行收紧能力：

omp --tools read,grep,glob --approval-mode always-ask \
  "检查当前改动是否存在明显回归，只报告，不修改任何文件。"

3.2 输入区不只接收文字

• 输入 @ 后搜索文件，把选中的路径连同本轮请求一起交给模型。
• Ctrl+V 可粘贴图片；长文本会折叠成附件卡片，输入区不会被刷满。
• Ctrl+G 可把长提示词交给外部编辑器写完再送回。
• Ctrl+R 搜索以前输入过的提示词。
• Shift+Enter、Ctrl+J 或 Alt+Enter 插入换行；Windows Terminal 更推荐 Alt+Enter。

路径只是材料，不是意图。不要只丢一个 @src/module.ts，要说明“用它与哪份测试对照、要找什么、允许改哪里”。

3.3 工具卡片是审计记录，不是动画特效

omp 每次读文件、执行命令、修改代码或调用工具，都会在对话里留下一张卡片。Ctrl+O 展开或收起完整输出，Ctrl+Shift+O 隐藏或显示工具活动。

请特别区分两件事：某张卡片显示成功，只代表这个动作执行成功；不代表整个任务正确。 git diff 成功不等于改动合理，测试命令成功也要确认它确实跑到了目标测试。最终至少检查：改了哪些路径、命令退出状态、测试结果、诊断结果、模型承认的剩余风险。

3.4 随时纠偏，不必等它跑到底

omp 工作时你仍可以输入：

• 直接按 Enter 发送当前纠偏，例如“不要改接口，只修实现”。
• Ctrl+Q 或 Ctrl+Enter 把话排到下一轮，例如“做完后再解释风险”。
• Esc 中断正在进行的操作；如果自动补全或选择框开着，第一次 Esc 只会先关掉它。
• 意外中断了正确方向时，发送 . 或 c 可继续上一意图。
• Alt+R 重试上一轮失败的模型响应。

这很像坐副驾驶：看到车走错出口时立刻提醒，比到终点再说“不是这里”便宜得多。

3.5 四个本地逃逸前缀

有时你只是想自己跑一条命令，不需要模型决定：

! git status       # 执行并把输出加入模型上下文
!! git diff --stat # 执行并显示，但不把输出交给模型
$ print(2 + 2)     # 在共享 Python 内核执行，并加入上下文
$$ print(2 + 2)    # 执行并显示，但不加入上下文

注意：!! 和 $$ 只是“不发送给模型”，不是沙箱；命令仍以你的本地权限运行，也可能修改文件。

四、正式干活前先拧紧安全阀：默认 Yolo 不等于适合所有项目

这是本文最值得先改的一项。官方设置文档显示，tools.approvalMode 的默认值是 yolo：普通读、写和执行动作都会自动放行。三种模式分别是：

先查当前生效值：

omp config get tools.approvalMode

临时收紧一轮：

omp --approval-mode always-ask

持久修改全局配置：

omp config set tools.approvalMode write

write 是我更推荐的日常折中：普通文件修改不反复弹窗，但执行命令仍要确认。对陌生仓库、生产环境或带外部系统的任务，用 always-ask 更稳。

一个容易漏掉的细节是：bash.patterns 只约束 Bash 工具，eval 仍可通过子进程启动命令。要真正关住旁路，需同时给 eval 配 prompt 或 deny。另外，子代理是无界面运行的，不能回答 prompt；父级 task 调用才是授权边界。后文的一键脚本已经按这个特性做了平衡配置。

五、配置为什么“改了却没生效”：五层衣服与数组替换陷阱

omp 的配置从低到高是：

内置默认值
  < 全局或 Profile 配置
  < 当前项目配置
  < PI_CONFIG_FILES 与 --config 临时覆盖
  < 本次运行参数和功能专用环境变量

可以把它想成冬天穿五层衣服：里面的衣服没有消失，只是最外层决定你现在看起来是什么样。最常用的路径是：

• 全局：~/.omp/agent/config.yml
• 项目：<repo>/.omp/config.yml
• 单次：omp --config ./temporary.yml

对象会深度合并，但数组整组替换，不会自动追加。例如全局禁用了两个 Provider，项目里又写了一个新的 disabledProviders 数组，项目数组会把全局数组整个替掉，而不是再加一个。这是“全局设置怎么突然没了”的常见根因。

还有一个坑：omp config set 写的是全局配置，不会替你写任意项目配置。项目专属值要直接编辑 .omp/config.yml。并且项目设置按启动工作目录发现，所以应从包含 .omp/config.yml 的目录启动，再用 omp config get <key> 看最终生效值。

六、复杂任务先开 Plan：先看施工图，再决定要不要砸墙

小改动直接做更快；跨文件重构、迁移、陌生代码库或带回滚要求的任务，先用 Plan：

/plan 把内存任务队列替换为持久化队列。保持公开接口不变，列出迁移顺序、兼容窗口和回滚路径。先只调查和给方案，不修改文件。

Plan 模式像装修前的施工图审查。计划阶段可以读项目、查假设、找依赖，但不会先把墙砸了再问你喜欢哪种户型。你可以逐条修改计划、批准后选择实现模型，也可以退出而不执行。

它也有成本：多一次模型回合、占用一部分上下文。修一个拼写错误还开 Plan，就像换灯泡前先开三小时设计评审。判断标准很简单：错误方向的代价是否明显高于多做一次计划的代价？ 是，就开。

七、模型角色：别让总工程师一直去复印资料

/model 或 Alt+M 打开模型中心，/switch 或 Alt+P 临时换本次会话模型，Ctrl+P 在配置好的角色顺序中循环，Shift+Tab 切换思考强度。

omp 不只保存一个“默认模型”，还可为不同工作分角色：

• default：日常实现与综合判断。
• smol：标题、摘要、轻量调查等便宜快速任务。
• slow：复杂推理和疑难问题。
• plan：规划与架构设计。
• vision：图片理解。
• task：通用子代理。
• commit、advisor、designer 等：对应专门流程。

生活里的类比是：让总工程师做关键设计，让助理整理资料，让审计员独立复核。所有活都塞给最贵模型会慢且贵；所有活都给最快模型，又会在关键判断上省错钱。

建议先在 /model 的角色界面配置，而不是照抄别人某个具体模型名。你的账号可用 Provider、模型上下文、价格和工具调用质量都可能不同。配置后，先用小任务分别验证角色真的可用，再谈自动路由。

八、子代理与 Agent Hub：可以开后厨，但别让四个人抢一口锅

子代理适合“互相独立、边界清楚、结果可以合并”的工作，例如：一个 scout 查调用链，一个 librarian 核对上游文档，一个 reviewer 只审当前 diff，一个 task 跑独立实现或测试。具体可用名字会随版本、插件和项目定义变化，以 /agents 为准。

你不必自己写工具调用格式，直接说明希望如何分工：

先不要改代码。请让 scout 梳理登录流程，让 librarian 核对当前依赖的官方升级说明，
让 reviewer 只审现有 diff。三者并行，回来后由主代理合并结论、指出冲突，再问我是否进入实现。

后台任务可在 Agent Hub 查看，官方默认快捷键为 Alt+A，/jobs 可看紧凑状态。你可以读某个 worker 的详细记录、追加指令、继续追问或停止它。

不要为了“看起来高级”而强行并行。下面这些情况更适合单代理：

• 多个任务会同时改同一批文件。
• 后一步必须等前一步的细节结论。
• 每几分钟都要共享一次新决定。
• 任务很小，协调成本比执行成本还高。

还要知道安全边界：子代理无交互界面，普通授权模式会被强制成可无人值守执行；父级 task 是否获准、工具级 deny 规则和隔离工作区才是真正的门。对不熟悉的仓库，优先让子代理只读调查，或使用隔离工作区返回补丁，不要让多个 worker 直接在共享工作树里随意写。

九、LSP、Hashline 与 DAP：不是“多看几行文本”，而是把 IDE 的眼睛接进来

9.1 LSP：知道这个名字“指的是谁”

普通文本搜索看到的是相同字符；语言服务器知道符号定义、引用、类型、导入和诊断。让 omp 做跨项目重命名时，可以明确要求先预览语言服务器提供的改动：

把 issueToken 重命名为 mintToken。先确认由哪个语言服务器处理，预览所有引用与导入变化，得到我确认后再应用，并运行最小相关测试。

默认 lsp.enabled: true 且按需启动，但对应语言的服务器仍要在本机可用。遇到“只做文本替换、没有诊断”时，先让 omp 报告当前文件由哪个服务器处理，再检查项目根标记和服务器命令。临时排除 LSP 影响可用 omp --no-lsp。

9.2 Hashline：给每行代码一个临时门牌号

Hashline 是 omp 的默认编辑模式。读文件时，每一行带一个由内容计算出的标识；修改时引用这些标识，能发现“我读完后文件已被别人改过”的冲突，也不用让模型重抄一大段旧文本。就像快递员按门牌送货，而不是凭“红色门旁边那家”猜位置。

检查当前值：

omp config get edit.mode

9.3 DAP：让模型站在断点旁边看现场

DAP 是调试器与编辑器之间的通用协议。适配器可用时，omp 能启动或附加程序、下断点、看局部变量、线程与调用栈。一个好请求不是“帮我 debug”，而是：

用项目现有调试适配器启动导入任务，在转换函数入口停下。
当第三条记录出现异常时，比较当前局部变量和上一层调用参数，解释坏值从哪里进入。先不要修改代码。

如果提示适配器不可用，先按语言安装并验证对应 DAP 适配器；“omp 有调试工具”不等于每种语言的调试器都已预装。

十、会话不是聊天记录，而是一棵可以回到岔路口的树

日常最常用的恢复命令：

omp -c  # 继续当前项目最近一次会话
omp -r  # 打开当前项目的会话选择器

在交互界面里：

• /tree 回到当前会话更早的消息或另一条分支。
• /branch 从较早消息开同一会话里的另一条路线。
• /fork 把当前状态复制成新的会话，适合高风险试验或需要单独分享的路线。
• /rename 给会话起可搜索的名字，/pin 固定重要会话。
• /export 导出本地 HTML 审阅副本。
• /share 可生成加密分享链接；敏感项目更建议本地导出后走你自己的受控渠道。

把它类比成 Git：branch 是同一个仓库里的另一条思路，fork 是复制出一份独立工作档案。这样你不必在一个超长聊天里把所有失败路线混成一锅粥。

十一、Context、Session、Compaction、Memory：四个抽屉不要混用

这四个概念最容易混：

• Context files：会话开始时自动加载的项目说明，例如 .omp/AGENTS.md；适合构建命令、架构、风格和验收要求。
• RULES.md：短而硬的粘性规则，会在长对话里继续靠近当前轮次，例如“未经明确要求不得提交和推送”。
• Session：完整对话和工具记录，可以恢复、分支、导出。
• Compaction：当前对话太长时，把较老内容压成摘要，节省本次会话上下文。
• Memory：跨会话保留长期偏好、决定或项目知识。

记忆默认是 off，这是合理的隐私默认值。官方当前提供 local、mnemopi 与 hindsight 等后端：local 偏向把历史会话提炼为本机项目摘要；mnemopi 提供本机可搜索记忆；hindsight 面向已有的远程或自托管服务。不要因为“有这个功能”就立刻全开，先回答三个问题：存在哪里、按什么范围隔离、如何查看和删除。

需要本地摘要时再开启：

omp config set memory.backend local
omp config get memory.backend

规则和架构真相仍应写进版本控制里的文档，不能把 Memory 当项目文档替代品。否则它像只存在某位老员工脑子里的流程：今天很顺，员工一换就没人说得清。

十二、网页、浏览器与 GitHub：选“能完成任务的最轻工具”

omp 面对网络任务有不同路径：

1. 不知道来源、要对照多份资料：网页搜索。
2. 已知公开 URL、只需读内容：直接读取页面或文档。
3. 必须渲染 JavaScript、点击或填写表单：托管浏览器。
4. 必须使用你已经登录的 Chrome 状态：Browser Relay，并明确指定目标标签页。
5. GitHub Issue、PR、Actions：优先用结构化 GitHub 集成，而不是刮网页。

这里的原则和生活中一样：能打电话问清楚，就别先派人撬门进去。浏览器自动化权限更广、状态更复杂，只有需要真实交互时才用。涉及发送、提交、购买、发布、删除、改权限等外部动作，请在 Prompt 里写清“停在最终确认前”，并把浏览器工具设为 prompt。

十三、非交互与自动化：把 omp 放进脚本，也要给它围栏

一次性问答或 CI 可用打印模式：

omp -p "解释当前改动的风险，不修改文件。"

机器读取事件流时：

omp -p --mode json --no-session --max-time 10m \
  --tools read,grep,glob \
  "检查生成文件是否与源文件一致，只输出证据。" > omp-events.jsonl

自动化最常见的错误，是因为“没有人在旁边点确认”就直接上 Yolo。更稳的做法是反过来：缩小工具列表、限制时间、使用临时配置、只给必要目录，把写入和外部动作变成流水线里的显式下一步。

十四、三平台一键项目配置：不重装 omp，不写 Key，不依赖第三方服务

下面三套脚本假设 omp 已经安装好，只在当前项目创建：

• .omp/config.yml：write 授权模式、Hashline、LSP、压缩、秘密信息遮蔽和关键工具策略。
• .omp/AGENTS.md：通用工作约定；如果根目录已有 AGENTS.md，会通过 @../AGENTS.md 导入，而不是丢掉原规则。
• .omp/RULES.md：未经明确要求不得提交、推送、发布或做不可逆外部动作等粘性安全规则。

脚本不会安装软件、不会读取或配置 API Key、不会连接第三方服务。已有非托管文件默认保留，并生成 .recommended 候选；只有显式传 -Force 或 --force 才会先备份再替换。三套脚本都在末尾用 omp config get 验证关键配置确实被当前版本接受。

14.1 Windows 11（PowerShell）

下载：omp-bootstrap-windows11.ps1

# 在项目目录中执行；先阅读脚本，再运行
powershell -NoProfile -ExecutionPolicy Bypass `
  -File .\omp-bootstrap-windows11.ps1 `
  -ProjectRoot .

若确认要替换已有自定义文件：

powershell -NoProfile -ExecutionPolicy Bypass `
  -File .\omp-bootstrap-windows11.ps1 `
  -ProjectRoot . -Force

14.2 Ubuntu 26.04（Bash）

下载：omp-bootstrap-ubuntu2604.sh

# 在项目目录中执行；脚本无需 sudo
bash ./omp-bootstrap-ubuntu2604.sh .

确认备份并替换已有文件：

bash ./omp-bootstrap-ubuntu2604.sh --force .

14.3 macOS 26（zsh）

下载：omp-bootstrap-macos26.zsh

# 在项目目录中执行；脚本无需管理员权限
zsh ./omp-bootstrap-macos26.zsh .

确认备份并替换已有文件：

zsh ./omp-bootstrap-macos26.zsh --force .

14.4 人工自动执行与 Agent 自动配置，两种方法怎么选

上面的方式是人工自动执行：你先审脚本，再让固定逻辑一次完成，结果可重复，也容易在团队里评审。

如果项目已有复杂 .omp、多层 AGENTS.md 或公司规则，更适合让 Agent 先调查再配置。把下面这段原样交给你已有的编码 Agent：

请为当前项目配置已经安装好的 omp，不要安装或升级任何软件。

要求：
1. 先确认当前目录是真正的项目根目录，检查现有 .omp、AGENTS.md、CLAUDE.md、
   .github/instructions 等规则来源，并报告可能的遮蔽或冲突；
2. 不覆盖未知的现有文件。需要修改时先给出 diff；获准后备份原文件再改；
3. 项目配置使用 .omp/config.yml：tools.approvalMode 设为 write，computer 设为 deny，
   browser、eval、task 设为 prompt；保留 Hashline、LSP 写后诊断和自动压缩；
4. memory.backend 保持 off，secrets.enabled 设为 true；不要读取、打印或配置任何密钥；
5. 创建短小的 .omp/RULES.md：未经我明确要求，不得 commit、push、publish、删除数据
   或改变外部系统；创建 .omp/AGENTS.md 时保留并导入现有项目规则；
6. 不连接第三方服务，不启动浏览器，不修改全局 ~/.omp 配置；
7. 完成后运行 omp config get tools.approvalMode、edit.mode、memory.backend，
   再列出改动文件、验证结果和仍需我决定的事项。没有验证就不要说完成。

Agent 方法更灵活，但也更需要你看 diff；脚本方法更可预测，但不会替你理解复杂仓库。两者不是谁更高级，而是“标准化模板”和“现场工程师”的区别。

十五、常见问题与故障排查（Q&A）

Q1：为什么我从没见过授权提示？

先跑 omp config get tools.approvalMode。默认 yolo 会自动放行常规读写与执行。临时用 --approval-mode always-ask 验证，确认后再决定全局或项目策略。

Q2：为什么 omp 一直调查，就是不改文件？

看状态栏是否处于 Plan 模式，再看是否有待回答的授权框或问题框。Plan 本来就是只读；批准计划、退出 Plan，或回答授权后才会进入实现。

Q3：我用 omp config set，为什么项目文件没变？

它默认写全局 ~/.omp/agent/config.yml。项目专属设置要编辑项目根目录的 .omp/config.yml，然后从该目录启动新会话，用 omp config get 看合并后的有效值。

Q4：为什么项目配置一写 disabledProviders，全局禁用列表就少了？

因为数组是替换，不是追加。项目数组要写完整目标列表。

Q5：子代理为什么不能运行某个工具，主代理却能？

子代理没有界面，无法回答 prompt。如果你把某工具显式设成 prompt，继承到子代理后会拒绝执行。把父级 task 授权当边界：对可信、隔离的子任务可按需 allow；不可信能力直接 deny，不要用 Yolo 掩盖策略问题。

Q6：Memory 和 /compact 有什么区别？

/compact 缩短当前会话的活跃上下文；Memory 把信息带到以后会话。前者像本节课摘要，后者像跨学期档案。

Q7：越多子代理是不是越快？

不是。互相独立的调查可以并行；共同修改同一文件时，四个代理就像四个人同时抢一块白板，协调和冲突可能比单人更慢。

Q8：怎样确认 omp 真的完成了，而不是“口头完成”？

要求它给出改动路径、实际执行命令、退出状态、测试或诊断结果、未覆盖范围和剩余风险。然后自己看 diff。没有证据的“完成”只是一句话。

十六、写在最后：把“会不会用”改成“能不能验收”

omp 功能很多，但主线并不复杂：说清结果和边界，先调查，复杂任务先规划，工作中随时纠偏，用合适角色分工，最后只认验证证据。

真正熟练以后，你不会背下所有斜杠命令；你会知道什么时候只读、什么时候 Plan、什么时候分叉会话、什么时候值得派子代理，以及什么时候必须把手放回刹车上。

如果只记一条，就记这句：不要问“你做完了吗”，要问“你用什么证据证明做完了”。从这一刻开始，omp 才从聊天框变成工程工具。

参考资料

• omp 官方文档首页、Quickstart、Using omp
• Settings、Tool approvals、Context files
• Plan mode、Subagents、Code intelligence、Debugging
• Sessions、Memory、Web & browser、CLI reference
• oh-my-pi GitHub 仓库与 README、@oh-my-pi/pi-coding-agent npm 页面

本文功能、默认值与截图核对时间为 2026-08-29。omp 迭代频繁，若网页与本机行为不同，以本机版本的帮助、配置 Schema 和对应版本源码为准。