iF.ai：一個 AI agent 平台的四代架構演進
iF.ai 是一個讓非技術用戶用聊天就能做出軟體的多 tier AI agent 平台。除了核心引擎 OpenCode（開源），整套系統——前端聊天介面、後台、控制層、瀏覽器代理，以及我自己的開發流程——由我一個人從零做到上線。
這篇想記的不是「我串了一個 LLM」，而是它的 agent 編排層走過的四代架構：從直通、加上雙會話編排器、減重成內嵌的編排器，最後又收斂回單一 AI。主線甚至走了一個完整的圈：直通 → 加編排 → 減重 → 砍掉回到直通，但更成熟。另外有一條未上線的異質模型實驗，技術上最能代表我做這套系統的核心信念：
生產級 AI 系統是「人設計的限制 + 客觀、可驗證的關卡」，不是讓模型自由發揮。
時間軸（以後端 main 的 commit 為準）：直通 2026-02-02 → 雙會話編排器 03-06 → 輕量編排器 03-17 → 單一 AI 03-18。異質模型路由是平行支線，從未併入 main。
為什麼要做這套系統
第一：把「只有工程師會走的開發流程」自動化給看不懂的一般用戶。
我自己的開發流程建立在 superpowers skills 上，但中間會針對 design.md、plan.md 跑一道自動審查（用 subagent 加上一組規則）。這條流程原本的每個審查關卡，很多是只有工程師看得懂、也只有工程師答得出的問題。為了讓一般用戶也能理解、確認，我自己開發了 ui-prototype 與其它相關的 skills——因為對一般用戶來說，用畫面是最容易理解、也最好調整需求的方式。
iF.ai 的目標是把它變成：用戶只丟一句需求，AI 就一路自動往下走完整條流程；只有碰到「用戶端的非技術問題」才回頭問用戶。需求由用戶透過畫面調整，不必去答那些技術性的審查問題。
這就是編排器（下面的 oAI，第二代引入）存在的根本理由：它是用戶的代理人，代替用戶在每個審查關卡上回答、決定何時進下一步。
第二：用異質模型壓成本。
當時 MiniMax 2.6 出來，號稱品質與 Claude 相差無幾、但便宜許多。於是我想：不是每個階段都需要最貴的模型——發想、判斷類的環節用便宜模型，需要高能力的環節才用 Claude。這就是異質模型路由（下面那條平行實驗）的由來。
系統現況架構（第四代）
核心引擎是 OpenCode（開源的 AI coding agent），我刻意不改原版，以便持續跟上游同步；所有「產品化」邏輯都做在它外圍。
┌─────────────┐ ┌─────────────┐
│ 聊天介面 │ │ 後台管理 │ ← 用戶端
│ (手機 / Web) │ │ (React SPA) │
└──────┬──────┘ └──────┬──────┘
│ 對話請求 │ 管理 API
▼ ▼
┌────────────────────────────────────────┐
│ 後端（Go + Echo） │ ← 控制層
│ · 認證 / 多租戶 / tier 路由 │
│ · 持久 SSE ←→ OpenCode │
│ · 編排（各代差異都在這層） │
└───────┬───────────────────────┬──────────┘
│ HTTP + SSE │ 管理
▼ ▼
┌───────────────┐ ┌─────────────┐
│ OpenCode │ │ PostgreSQL │
│ (AI 引擎,原版)│ │ │
└──────┬─────────┘ └─────────────┘
│ stdio
▼
┌───────────────┐ wss:// ┌──────────────────────────┐
│ 瀏覽器代理 │◀──────────▶│ 用戶電腦的桌面程式 │
│ │ 中繼 │ └ 用戶自己的瀏覽器 │
└───────────────┘ └──────────────────────────┘最後那一段值得說明，因為它常被誤解：後端的 OpenCode 有時需要在用戶授權後、於用戶自己的電腦本機，透過一個 Tauri 桌面程式加上 chrome-devtools-mcp，操作用戶自己的瀏覽器——用來完成「替用戶把第三方服務的金鑰設定好、自動填一些表單」這類只能在本機做、也不該經過我的伺服器的步驟。金鑰留在用戶端、不上傳，這是刻意的安全邊界。
整套系統的原始碼分佈如下。標 🌐 的已公開，點得進去可直接核對；標 🔒 的未公開（商業 / 客戶相關，僅授權者可見）：
| 元件 | 原始碼 | 職責 |
|---|---|---|
| 控制層（後端，Go / Echo） | 🔒 未公開 | 認證、多租戶、tier 路由、編排、對 OpenCode 的持久 SSE、管理 API、機器健康檢查 |
| 聊天介面（手機 / Web） | 🔒 未公開 | 用戶端對話介面 |
| 後台管理（React SPA） | if-cms 🌐 | 管理用戶 / 組織 / 機器 |
| AI 引擎 | OpenCode 🌐 | 開源 coding agent，刻意保持原版以持續跟上游同步 |
| 瀏覽器代理 | if-browser-agent 🌐 | 桌面程式加 chrome-devtools-mcp，經中繼於用戶本機操作其瀏覽器 |
| 開發流程 | superpowers 🌐 | fork 自 obra/superpowers，本案的開發流程主幹 |
| 產品 skills | if-skills 🌐 | 畫面原型等產品專屬 skills |
除了開源引擎 OpenCode，上表每一項都由我一個人從零做到上線；公開的部分都附了連結，您可以直接點進去核對。
四代架構演進
每一代我固定講同一件事：痛點 → 設計 → 什麼壞了 → 為何演進。
第一代 — 直通 2026-02-02
痛點：先要有一條能用的鏈路，讓用戶訊息進到 AI、把串流結果即時送回。
設計：最簡單的轉發。用戶經由後端到 OpenCode，後端維持一條對 OpenCode 的持久 SSE，把事件即時轉發回前端。純轉發，不介入對話內容。
什麼壞了：對非技術用戶直接攤開——他們看到一堆中間的程式碼輸出、被問到發想與審查計畫的問題，看不懂也答不出。
→ 演進理由：需要一個「用戶代理人」來控流程、代答審查、決定何時進下一步。
第二代 — 雙會話編排器 + tier 2026-03-06
設計：每個專案開兩個 OpenCode 會話——一個負責對話與控流程（oAI，用戶代理人），一個負責實際做事（aAI）。後端在兩者間路由。同時引入 tier（小白 / 技術 / 工程師三級），寫進每專案的設定檔，用 OpenCode 原生的權限機制控制 agent 行為——限制寫在設定檔，不在 prompt，難被模型繞過。
什麼壞了：一、兩個完整會話太重，啟動慢一倍；二、用字串標記在兩者間傳話很不穩，模型偶爾不照格式吐標記，得用一堆正則加備援去補；三、連線斷掉、競態、殭屍訊息一堆要修。
→ 演進理由：角色分離是對的，但「兩個重會話加字串協定」太脆——先把代理人變輕、把字串標記換掉。
第三代 — 輕量編排器（用結構化工具呼叫取代字串標記）2026-03-17
設計：把代理人從一個完整的 OpenCode 會話，改成後端裡的一個模組，直接呼叫 Anthropic 的 API 加上 tool use，用結構化的工具呼叫取代脆弱的字串標記。派工只能走一份允許清單，不在清單上的直接擋掉——清單就是流程的步驟：發想、寫計畫、畫面原型、subagent 實作、系統化除錯。
關鍵機制：工具呼叫取代正則字串，結構化、可驗證、不會解析失敗；做事的那一方完全不知道代理人存在，它以為自己在跟用戶對話——一個乾淨的抽象邊界。體驗像 LINE：背景跑、偶爾收到進度、完成才通知，沒有惱人的串流中間態。
這個階段（前三代）我用的還是原版的 superpowers skills，加上自己疊在上面的；還不敢動 superpowers 本身。
什麼壞了：即使代理人變輕，雙會話的本質沒變——延遲仍會疊加，跨會話傳脈絡仍有損失。我開始懷疑：編排器到底要不要獨立存在？
第四代 — 單一 AI 架構（把限制收進 system prompt）2026-03-18
決策：拿掉編排器，回到最簡。
第三代： 用戶 → 後端 → 代理人（內嵌）⇄ 做事方（OpenCode）
第四代： 用戶 → 後端 → OpenCode（單一會話）
↑ 流程控制 + tier + 溝通風格，全靠 CLAUDE.md做了什麼：刪掉整個編排器模組、輪詢、雙會話建立邏輯。把流程控制、溝通風格、tier 全部用 CLAUDE.md 表達——每個專案自動產出的 CLAUDE.md 會標注用戶等級「小白 / PM / 工程師」，用來調溝通深度與權限。
流程改寫（到第四代才敢動）：前三代一直是「用原版 superpowers 加自己加的」；到第四代，我把整套 superpowers 融會貫通後，才整個 fork 加改寫成自己的流程——關鍵動機是讓各 skill 串起來時脈絡不再互相打架。流程主幹仍是發想 → 畫面原型 → 設計 → 計畫 → 實作，每段中間用一道自動審查：針對規則審設計、計畫與畫面，以 BDD、驗收條件、TDD 為驗收基準；再靠畫面原型加上 CI/CD 把成果部署出來，讓非技術用戶直接用畫面確認「做出來的是不是他要的」。
為什麼退回直通，不是退步：最直接的原因是 LLM 變強了——很多原本得在外部編排的事，現在 AI 在內部就能處理，包括把 Harness（限制與流程）寫進 system prompt 與 CLAUDE.md。編排器之所以被換掉、拿掉，是因為它那一層效果不夠好、又太慢（雙會話的延遲疊加），那就退回最簡的直通。但我留了一條底線：凡是能用外部 script 卡住的，就留在外部當最後一道防線——客觀的把關不該全部交給 AI 自覺。抽象可以加、也可以換或拿掉，判斷依據是效果，不是捨不得。
平行實驗：異質模型路由 + 獨立評審（未上線）2026-02-25 ~ 03-02
這條從未併進 main，設計到一半我刻意暫停了。但它技術上最能代表我說的「客觀關卡」，所以單獨記。
設計：後端依當前階段選模型（高能力環節用 Claude、發想與判斷類用便宜模型），並用一個獨立的評審會話判斷「這個階段完成了沒」，完成才觸發轉場。
最有代表性的一點：階段完成與否，不由做事的那個 AI 自己說了算，而由另一個獨立的會話判定。這正是「不讓 AI 自稱『做完了』」——也是我對「客觀、可驗證的關卡」的具體實作。
為何暫停：階段之間的轉場來源追蹤還沒解乾淨，與其硬上，我先把它擱著。誠實說，它是個還沒做完的實驗，但方向我留著。
一張表，看完整段判斷
| 轉折 | 為什麼改 | 換來什麼 | 代價 |
|---|---|---|---|
| 第一代→二代 加雙會話編排器 | 非技術用戶看不懂、答不出審查 | 用戶只丟需求，代理人代走流程 | 兩個重會話、字串標記脆 |
| 第二代 加 tier（設定檔） | 限制應寫在設定檔不在 prompt | 原生權限強制，難被繞過 | 每專案要生成 / 同步設定檔 |
| 第二代→三代 編排器內嵌 + 工具呼叫 | 會話太重、字串標記太脆 | 啟動快、結構化、不會解析失敗 | 仍是雙會話本質 |
| 第三代→四代 砍掉編排器 | 雙會話延遲疊加 | 最快最穩，編排邏輯整個蒸發 | 流程控制改用 prompt 表達 |
| 異質路由 + 獨立評審（未上線） | 不同階段用不同成本模型加客觀判定 | 省成本、可驗證的階段關卡 | 轉場來源追蹤未解 |
我從這套系統學到的
這四代演進，對我來說是「Harness（駕馭工程）」這件事最直接的證據：
- 限制寫在程式碼與設定檔，不在 prompt——tier 用原生權限強制，難被模型繞過。
- 驗證用客觀、可被機器驗證的關卡——獨立評審判斷階段完成；結構化工具呼叫取代會解析失敗的字串協定。
- 不讓 AI 自稱「做完了」就算數——完成與否由獨立的一方判定。
- 抽象可以加，也可以換或拿掉——判斷依據是效果，不是捨不得。主線一路加，最後因為編排那層太慢、加上 LLM 變強能內化更多，又把它拿掉退回直通；但凡是能用外部 script 守的把關，我留著當最後一道防線。
把 AI 從一個 demo，撐成一個每天有人用、出錯有解、架構撐得住的正式系統——靠的不是更聰明的 prompt，是這些人設計的限制與驗證層。