01 前言：代理人的模態與狀態治理
在傳統的 AI 輔助軟體開發中，AI 代理人 (Agent) 通常處於兩種極端狀態：要麼完全自主執行 (Autonomous) 導致控制權喪失，要麼純粹被動響應 (Reactive) 使複雜任務難以推進。
Oh My Pi (omp) 引入了成套的模態切換 (Mode Switching) 與狀態調度機制。本文分四大群組深入拆解九種核心模式與操作：執行安全模式（計畫、審批）、模型與推理調度（模型角色、思考等級、服務層級）、上下文與歷史治理（壓縮、會話樹）、以及監督與協作（顧問、即時協作），每組附上實際案例。
計畫模式 (Plan Mode)：工具約束與自動命名
計畫模式是 OMP 在執行複雜多檔案重構時的防禦機制。透過 Alt+Shift+P 開啟後，代理人從「直接修改」降級為「唯讀分析與規劃」：
唯讀工具白名單 (PLAN_MODE_AGENT_TOOL_ALLOWLIST)
Plan Mode 啟用時，子任務啟動器 TaskTool.#runSpawn 動態重組 effectiveAgent：攔截所有寫入/執行工具（edit、write、bash、eval），僅保留 read、search、find、lsp、web_search，並附加計畫模式的子代理人 system prompt。
無超時確認與計畫自動命名
- 確認超時關閉：一般對話中
ask工具會依ask.timeout終止停滯對話，但 Plan Mode 下該超時被強制關閉 (timeout = 0)，給予充足審查時間。 - 核准自動命名：使用者選「批准並執行」後，
InteractiveMode.#approvePlan提取計畫 Title，經humanizePlanTitle轉為人類可讀字串，再以setSessionName()命名（僅當 session 尚未命名），同步更新終端標題與編輯器邊框色。
案例實踐：資料庫路由重構
情境：把單一資料庫連接重構為多租戶動態分庫路由器，涉及 12 個模組。
- 進入計畫模式：按 Alt+Shift+P，狀態列顯示 [PLAN MODE]。
- 唯讀調研：輸入「規劃將資料庫連接改為動態路由」。AI 僅能以
lsp references、grep蒐證，輸出db-router-plan.md。 - 核准與命名：審閱後點「核准並執行」，計畫標題
Refactor DB Router to Tenant Mode被套用為 session 名。 - 自動執行：退出唯讀，AI 取回寫入/執行權限，改寫 12 個檔案並跑測試。
工具審批三模式與安全邊界 (Tool Approval)
每個工具都會宣告一個審批等級：read（讀取）、write（修改狀態但不執行代碼）、exec（執行代碼、shell、瀏覽器、生成子代理）。未宣告的工具一律視為 exec。tools.approvalMode 決定各等級的自動核准策略：
| 模式 (approvalMode) | 自動核准 | 彈出確認 |
|---|---|---|
| always-ask | read | write、exec |
| write | read、write | exec |
| yolo (系統預設) | read、write、exec | 無（全部放行） |
CLI 旗標 --auto-approve 與 --yolo 會將該次 session 強制設為 yolo。
⚠️ 安全警告：YOLO 不會攔截 rm -rf /
不要誤信「即使 YOLO 模式，破壞性指令仍會被系統強制攔截」。在預設的 yolo 模式下，所有安全防護攔截 (Safety Overrides) 都會被自動放行，系統不會因偵測到毀滅性特徵而彈確認。
要防範刪庫，必須在 config.yml 明確設定個別工具策略 (User Policy) 為 prompt 或 deny：
tools:
approvalMode: yolo
approval:
bash: prompt # bash 呼叫強制人工確認
delete: deny # 徹底禁止 delete
案例實踐：自動化部署的高速與防衛平衡
情境：授權 AI 連續執行 20 步打包發佈腳本，既要免手動確認打斷、又要防止誤刪核心資源。
- 設定 Policy：
approvalMode: yolo搭配tools.approval.bash: prompt。 - 自動放行：AI 的
read/write操作全自動通過，快速串接。 - 安全確認：AI 一旦透過
bash執行rm -rf build/，因bash: prompt立即暫停等待人工確認。
模型角色切換 (Model Roles)
OMP 不綁死單一模型，而是以「角色 (Role)」概念分層調度。你可以隨時在會話中切換當前生效的模型。
切換操作
- 前進輪替模型Ctrl+P
- 後退輪替模型Shift+Ctrl+P
- 本次暫時選模Alt+P
- 開啟模型選單/設角色Alt+M
- 命令式切換
/model <name>
支援的模型角色 (modelRoles)
每個角色值可附加思考選擇器（如 :medium、:high），並可用 provider/modelId 釘死特定變體，或用 canonical id（如 gpt-5.3-codex）允許 provider 合併。
modelRoles:
default: anthropic/claude-opus-4:high # 高判斷主力
smol: openai/gpt-5.4 # 命名/初稿等輕任務
task: openai/gpt-5.4 # 子代理人 worker
案例實踐：高低模型混合節流
面對一個需要架構判斷、但過程夾雜大量瑣碎重命名的任務：先以 Ctrl+P 切到高階模型做設計決策，接著切到 smol 快速模型批次跑機械式改名與樣板生成，兼顧品質與成本。子代理人則自動走 task 角色。
思考等級切換 (Thinking Level)
思考等級決定了模型在回答前投入的推理深度（reasoning effort），是速度與縝密度的權衡旋鈕。等級變更會被寫入 session 的 thinking_level_change entry，並在上下文重建時還原。
操作方式
- 輪替思考等級Shift+Tab
- 顯示/隱藏思考塊Ctrl+T
亦可在模型角色值後綴（如 claude-opus-4:high）固定該角色的思考等級。
六個等級 (由低到高)
案例實踐：除錯難題臨時升檔
日常對話維持 low 保持回應速度；碰到一個難纏的並發競態 (race condition) bug 時，用 Shift+Tab 臨時升到 high／xhigh 讓模型深度推理排查，並用 Ctrl+T 展開思考塊觀察其推理鏈，定位後再降回 low。
服務層級切換 (Service Tier)
服務層級控制請求走供應商的哪一條運算通道，影響延遲、吞吐與計費。OMP 以 per-family map 儲存此狀態，分別對 openai / anthropic / google 三家獨立設定，並寫入 service_tier_change entry。
五個可選層級
值為 null 時代表未指定層級。舊版單一字串格式（"flex"、"openai-only"…）在讀取時會自動 normalize 成此 per-family map。
案例實踐：批次任務省錢、互動任務搶速
跑夜間大批量離線分析時，把 OpenAI family 設為 flex 以較低成本換取吞吐；當白天進行需要即時回應的互動 pair-programming 時，切到 priority 確保最低延遲，兩者互不干擾。
上下文壓縮與快照 (Compaction / Snapcompact)
當對話變長逼近上下文上限，Compaction 會把舊歷史改寫成摘要，作為一條 compaction entry。重建上下文時，先注入摘要，再從 firstKeptEntryId 起還原後續完整對話。
六種觸發時機
- 手動壓縮：
/compact [自訂指示]。 - 溢位復原：同模型出現 context overflow 錯誤後。
- 不完整輸出復原：訊息以
stopReason === "length"結尾。 - 門檻維護：一輪成功後 context 超過設定門檻。
- 回合中門檻維護：工具迴圈中跨越門檻（
compaction.midTurnEnabled）。 - 閒置維護：
runIdleCompaction()。
Snapcompact：把歷史畫成點陣圖
對於視覺能力模型，OMP 可將被丟棄的歷史序列化、collapse 空白後，用內建點陣字型印成 PNG 圖框，兩端保留逐字文字、中段影像化並在過大時內部 foveate（HQ/LQ/HQ）。此策略在 200k-token 評測中，比純文字更能在低計費 token 下保住 QA 召回率；且不涉及模型/網路，故溢位復原時同樣安全（非視覺模型會自動退回 context-full 文字摘要）。
案例實踐：長任務中途主動壓縮
在一個跑了數小時、上下文已被大量檔案讀取塞滿的長任務裡，趁邏輯段落結束時輸入 /compact 保留資料庫遷移的決策與尚未完成的 TODO，用自訂指示引導摘要聚焦關鍵決策，釋放上下文空間繼續推進而不失憶。
會話樹與分支導航 (Tree & Branch)
對話樹是解決「AI 對話發散與寫壞程式碼」的終極武器，實作了輕量級版本控制。底層採 Tree & Leaf 模型，跳躍分支只改 leafId 指標，不 mutate 實體日誌。
/tree 與 /branch 的物理邊界差異
- /tree（同檔導航）：在同一個 session 檔案內跳躍。Leaf 回溯到指定 Entry，並在回溯點生成
branch_summary記錄被捨棄的分支。舊分支歷史完好保留，可隨時再/tree跳回。 - /branch（實體分叉）：建立全新 session 檔案。以指定的 user message 為交會點，把其 parent 鏈歷史（排除 label entries）拷貝到新
.jsonl，並切換工作狀態至新檔。
摘要注入與標籤
navigateTree() 會觸發 session_before_tree 事件；若啟用摘要，系統對被捨棄分支做語意摘要並以 branchSummary 注入新上下文，防止 AI 遺忘失敗嘗試的教訓。樹選擇器支援 default/no-tools/user-only/labeled-only/all 過濾，並可 Shift+L 對節點加標籤。
案例實踐：平行 API 實作策略探索
情境：實作高速圖片模糊 API，不確定 Strategy A (純 JS) 或 Strategy B (C++ 擴充) 較優。
- 先在主線讓 AI 實作 Strategy A 並測效能。
- 輸入
/tree，跳回實作 A 之前的 prompt，輸入框自動填回原文。 - 發送「改用 Strategy B 實作」。新 leaf 的上下文乾淨無 A 的雜訊，AI 完整寫出 B 並對比。
- 對比後以
/tree永久停在勝出實作的葉節點，另一側封存。
顧問監督模式與即時協作
顧問監督 (Advisor / Watchdog)
Advisor 是掛在 session 上的第二顆模型，每回合後審查主代理人的 transcript，用自己的工具檢視工作區，再把精簡建議注入主 session。它不是第二執行者——預設工具唯讀（read/grep/glob + advise），無法核准動作或改主 session 狀態。
| /advisor | 切換 advisor.enabled 設定 |
| /advisor on / off | 啟用（需已指派 advisor 模型）/ 停用 |
| /advisor status | 顯示模型、context 使用、token 與成本 |
| /advisor dump | 複製 advisor 精簡 transcript 到剪貼簿 |
啟用需 advisor.enabled: true + modelRoles.advisor。進階可用 WATCHDOG.yml 定義多名各具專長、模型與工具授權的顧問。
即時協作 (Collab)
/collab 把執行中的 session 即時分享給其他 omp instance。訪客在自己的 TUI 原生渲染同一個 session（串流文字、工具卡片、footer 狀態），可下 prompt 與中斷，但所有變更主機狀態的操作皆為 host-only（/model、/compact、/resume、/branch、bash ! 等）。權限由連結上的 16-byte write token 於加入時驗證，無 token 者為唯讀。
案例實踐：高風險重構的雙保險
做一次涉及公開 API 變動的高風險重構時，先 /advisor on 掛上一名「架構顧問」盯跨模組耦合與公開 API 膨脹；同時 /collab 分享 session 給同事，讓資深工程師在自己終端唯讀觀戰並適時下 steer 指令，形成「AI 顧問 + 人類審查」雙保險。
10 結語：靈活切換的工程藝術
Oh My Pi (omp) 的模式體系覆蓋了開發全鏈路：以計畫模式與工具審批治理執行安全，以模型角色、思考等級、服務層級調度推理資源與成本，以壓縮與會話樹治理上下文與歷史，再以顧問與協作疊加監督與人機協同。
熟練在這九種模式間靈活切換，才是把 AI 代理人效能推到極致的關鍵。欲深入源碼，可在 OMP 終端隨時讀取 omp://。