先说结论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 想成一个能看仓库、能动手、也会找同事协作的工程师。给工程师派活时一张靠谱工单至少有五件事目标最终要发生什么变化。范围重点看哪些目录、文件或行为。禁区什么不能改什么动作未经允许不能做。验证哪条测试、哪项诊断或哪个可观察结果算通过。停止条件遇到什么情况先停下来问而不是继续猜。我常用下面这个模板简单任务不必逐项写标题但脑子里最好有这些格子目标修复批量导入时重复写入的问题。 范围只检查导入服务和对应的单元测试。 禁区不改数据库结构不改公开接口不提交、不推送。 验证先复现再跑最小相关测试最后给出 diff 摘要和命令退出状态。 停止条件如果根因涉及数据迁移先说明方案和回滚风险等我确认后再改。这不是“提示词玄学”。它只是把平时给真人同事说的话写完整。模型越强完整边界越能让它把能力用在正确方向模型稍弱清楚的验收条件更能防止它跑偏。三、第一次完整使用从项目根目录开始盯住状态栏和证据卡片3.1 从正确目录启动安装完成后日常入口其实很简单cdmy-project omp启动目录会影响项目配置、会话归属、上下文文件和工具能看到的工作区。第一眼先看状态栏里的路径、当前模型、思考级别、模式、Git 状态与上下文占用。它不是装饰条更像汽车仪表盘方向不对时继续踩油门只会离目的地更远。如果只是临时做一次审计可以从命令行收紧能力omp--toolsread,grep,glob --approval-mode always-ask\检查当前改动是否存在明显回归只报告不修改任何文件。3.2 输入区不只接收文字输入后搜索文件把选中的路径连同本轮请求一起交给模型。CtrlV可粘贴图片长文本会折叠成附件卡片输入区不会被刷满。CtrlG可把长提示词交给外部编辑器写完再送回。CtrlR搜索以前输入过的提示词。ShiftEnter、CtrlJ或AltEnter插入换行Windows Terminal 更推荐AltEnter。路径只是材料不是意图。不要只丢一个src/module.ts要说明“用它与哪份测试对照、要找什么、允许改哪里”。3.3 工具卡片是审计记录不是动画特效omp 每次读文件、执行命令、修改代码或调用工具都会在对话里留下一张卡片。CtrlO展开或收起完整输出CtrlShiftO隐藏或显示工具活动。请特别区分两件事某张卡片显示成功只代表这个动作执行成功不代表整个任务正确。git diff成功不等于改动合理测试命令成功也要确认它确实跑到了目标测试。最终至少检查改了哪些路径、命令退出状态、测试结果、诊断结果、模型承认的剩余风险。3.4 随时纠偏不必等它跑到底omp 工作时你仍可以输入直接按Enter发送当前纠偏例如“不要改接口只修实现”。CtrlQ或CtrlEnter把话排到下一轮例如“做完后再解释风险”。Esc中断正在进行的操作如果自动补全或选择框开着第一次Esc只会先关掉它。意外中断了正确方向时发送.或c可继续上一意图。AltR重试上一轮失败的模型响应。这很像坐副驾驶看到车走错出口时立刻提醒比到终点再说“不是这里”便宜得多。3.5 四个本地逃逸前缀有时你只是想自己跑一条命令不需要模型决定! git status # 执行并把输出加入模型上下文 !! git diff --stat # 执行并显示但不把输出交给模型 $ print(2 2) # 在共享 Python 内核执行并加入上下文 $$ print(2 2) # 执行并显示但不加入上下文注意!!和$$只是“不发送给模型”不是沙箱命令仍以你的本地权限运行也可能修改文件。四、正式干活前先拧紧安全阀默认 Yolo 不等于适合所有项目这是本文最值得先改的一项。官方设置文档显示tools.approvalMode的默认值是yolo普通读、写和执行动作都会自动放行。三种模式分别是模式自动允许会询问always-ask只读动作写入与执行write读取、工作区写入命令执行等高权限动作yolo读取、写入、执行默认不问先查当前生效值omp config get tools.approvalMode临时收紧一轮omp --approval-mode always-ask持久修改全局配置omp configsettools.approvalModewritewrite是我更推荐的日常折中普通文件修改不反复弹窗但执行命令仍要确认。对陌生仓库、生产环境或带外部系统的任务用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或AltM打开模型中心/switch或AltP临时换本次会话模型CtrlP在配置好的角色顺序中循环ShiftTab切换思考强度。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 查看官方默认快捷键为AltA/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.mode9.3 DAP让模型站在断点旁边看现场DAP 是调试器与编辑器之间的通用协议。适配器可用时omp 能启动或附加程序、下断点、看局部变量、线程与调用栈。一个好请求不是“帮我 debug”而是用项目现有调试适配器启动导入任务在转换函数入口停下。 当第三条记录出现异常时比较当前局部变量和上一层调用参数解释坏值从哪里进入。先不要修改代码。如果提示适配器不可用先按语言安装并验证对应 DAP 适配器“omp 有调试工具”不等于每种语言的调试器都已预装。十、会话不是聊天记录而是一棵可以回到岔路口的树日常最常用的恢复命令omp-c# 继续当前项目最近一次会话omp-r# 打开当前项目的会话选择器在交互界面里/tree回到当前会话更早的消息或另一条分支。/branch从较早消息开同一会话里的另一条路线。/fork把当前状态复制成新的会话适合高风险试验或需要单独分享的路线。/rename给会话起可搜索的名字/pin固定重要会话。/export导出本地 HTML 审阅副本。/share可生成加密分享链接敏感项目更建议本地导出后走你自己的受控渠道。把它类比成 Gitbranch是同一个仓库里的另一条思路fork是复制出一份独立工作档案。这样你不必在一个超长聊天里把所有失败路线混成一锅粥。十一、Context、Session、Compaction、Memory四个抽屉不要混用这四个概念最容易混Context files会话开始时自动加载的项目说明例如.omp/AGENTS.md适合构建命令、架构、风格和验收要求。RULES.md短而硬的粘性规则会在长对话里继续靠近当前轮次例如“未经明确要求不得提交和推送”。Session完整对话和工具记录可以恢复、分支、导出。Compaction当前对话太长时把较老内容压成摘要节省本次会话上下文。Memory跨会话保留长期偏好、决定或项目知识。记忆默认是off这是合理的隐私默认值。官方当前提供local、mnemopi与hindsight等后端local偏向把历史会话提炼为本机项目摘要mnemopi提供本机可搜索记忆hindsight面向已有的远程或自托管服务。不要因为“有这个功能”就立刻全开先回答三个问题存在哪里、按什么范围隔离、如何查看和删除。需要本地摘要时再开启omp configsetmemory.backendlocalomp config get memory.backend规则和架构真相仍应写进版本控制里的文档不能把 Memory 当项目文档替代品。否则它像只存在某位老员工脑子里的流程今天很顺员工一换就没人说得清。十二、网页、浏览器与 GitHub选“能完成任务的最轻工具”omp 面对网络任务有不同路径不知道来源、要对照多份资料网页搜索。已知公开 URL、只需读内容直接读取页面或文档。必须渲染 JavaScript、点击或填写表单托管浏览器。必须使用你已经登录的 Chrome 状态Browser Relay并明确指定目标标签页。GitHub Issue、PR、Actions优先用结构化 GitHub 集成而不是刮网页。这里的原则和生活中一样能打电话问清楚就别先派人撬门进去。浏览器自动化权限更广、状态更复杂只有需要真实交互时才用。涉及发送、提交、购买、发布、删除、改权限等外部动作请在 Prompt 里写清“停在最终确认前”并把浏览器工具设为prompt。十三、非交互与自动化把 omp 放进脚本也要给它围栏一次性问答或 CI 可用打印模式omp-p解释当前改动的风险不修改文件。机器读取事件流时omp-p--modejson --no-session --max-time 10m\--toolsread,grep,glob\检查生成文件是否与源文件一致只输出证据。omp-events.jsonl自动化最常见的错误是因为“没有人在旁边点确认”就直接上 Yolo。更稳的做法是反过来缩小工具列表、限制时间、使用临时配置、只给必要目录把写入和外部动作变成流水线里的显式下一步。十四、三平台一键项目配置不重装 omp不写 Key不依赖第三方服务下面三套脚本假设 omp 已经安装好只在当前项目创建.omp/config.ymlwrite授权模式、Hashline、LSP、压缩、秘密信息遮蔽和关键工具策略。.omp/AGENTS.md通用工作约定如果根目录已有AGENTS.md会通过../AGENTS.md导入而不是丢掉原规则。.omp/RULES.md未经明确要求不得提交、推送、发布或做不可逆外部动作等粘性安全规则。脚本不会安装软件、不会读取或配置 API Key、不会连接第三方服务。已有非托管文件默认保留并生成.recommended候选只有显式传-Force或--force才会先备份再替换。三套脚本都在末尾用omp config get验证关键配置确实被当前版本接受。14.1 Windows 11PowerShell下载omp-bootstrap-windows11.ps1# 在项目目录中执行先阅读脚本再运行powershell-NoProfile-ExecutionPolicy Bypass -File.\omp-bootstrap-windows11.ps1 -ProjectRoot.若确认要替换已有自定义文件powershell-NoProfile-ExecutionPolicy Bypass -File.\omp-bootstrap-windows11.ps1 -ProjectRoot.-Force14.2 Ubuntu 26.04Bash下载omp-bootstrap-ubuntu2604.sh# 在项目目录中执行脚本无需 sudobash./omp-bootstrap-ubuntu2604.sh.确认备份并替换已有文件bash./omp-bootstrap-ubuntu2604.sh--force.14.3 macOS 26zsh下载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.ymltools.approvalMode 设为 writecomputer 设为 deny browser、eval、task 设为 prompt保留 Hashline、LSP 写后诊断和自动压缩 4. memory.backend 保持 offsecrets.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脚本方法更可预测但不会替你理解复杂仓库。两者不是谁更高级而是“标准化模板”和“现场工程师”的区别。十五、常见问题与故障排查QAQ1为什么我从没见过授权提示先跑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 掩盖策略问题。Q6Memory 和/compact有什么区别/compact缩短当前会话的活跃上下文Memory 把信息带到以后会话。前者像本节课摘要后者像跨学期档案。Q7越多子代理是不是越快不是。互相独立的调查可以并行共同修改同一文件时四个代理就像四个人同时抢一块白板协调和冲突可能比单人更慢。Q8怎样确认 omp 真的完成了而不是“口头完成”要求它给出改动路径、实际执行命令、退出状态、测试或诊断结果、未覆盖范围和剩余风险。然后自己看 diff。没有证据的“完成”只是一句话。十六、写在最后把“会不会用”改成“能不能验收”omp 功能很多但主线并不复杂说清结果和边界先调查复杂任务先规划工作中随时纠偏用合适角色分工最后只认验证证据。真正熟练以后你不会背下所有斜杠命令你会知道什么时候只读、什么时候 Plan、什么时候分叉会话、什么时候值得派子代理以及什么时候必须把手放回刹车上。如果只记一条就记这句不要问“你做完了吗”要问“你用什么证据证明做完了”。从这一刻开始omp 才从聊天框变成工程工具。参考资料omp 官方文档首页、Quickstart、Using ompSettings、Tool approvals、Context filesPlan mode、Subagents、Code intelligence、DebuggingSessions、Memory、Web browser、CLI referenceoh-my-pi GitHub 仓库与 README、oh-my-pi/pi-coding-agent npm 页面本文功能、默认值与截图核对时间为 2026-08-29。omp 迭代频繁若网页与本机行为不同以本机版本的帮助、配置 Schema 和对应版本源码为准。