本文為英文版 architecture.md 的翻譯，內容如有出入以英文版為準。

1. 摘要 (Executive Summary)

AOA（Agent-Offloaded Architecture，代理卸載式架構） 是一種針對 AI Agent 時代提出的軟體架構模式：產品把其中的 Agent 工作——LLM 推理、工具操作，以及它們消耗的 token——卸載給使用者既有的 Coding Agent。服務端仍可保留它需要的其他部分，包括後端、資料庫或輕量模型；它不執行的是 Agent。

AOA 在前端的形式，是一個透過本機資料夾與使用者 Agent 協作的靜態網頁應用（這種前端形式有時也稱為 AOFA，Agent-Offloaded Frontend Architecture）。本文多數篇幅描述這種形式，因為它是套用 AOA 最直接的方式；模式 C、D（§5）則說明有後端，以及完全沒有前端時的 AOA。

在傳統生成式 AI 產品（SaaS）模式中，服務商必須在雲端承擔高昂的推論算力、多媒體轉碼與儲存成本，同時使用者必須承擔隱私外洩與資料被雲端綁定的風險。

AOA 提出責任邊界的反轉與重構：

  • 前端（Presentation Layer） 不依賴後端執行推論與運算，簡化為一份純靜態的協議工作台（Protocol Workbench），可零成本託管於 GitHub Pages 等靜態平台。
  • 推論與執行（Execution & Inference Layer） 卸載（Offloaded）給使用者自備的 Coding Agent（如 Claude Code, Cursor, Codex, Gemini CLI, Pi）與本地開源工具鏈（如 FFmpeg, Playwright）。
    • 推論：一般情況下由使用者既有的 Agent 方案在其供應商雲端執行，成本由使用者的 Agent 訂閱 / API 額度承擔，而非本服務；有需要時，也可如 Pi Agent 般改接本機自建模型（如 Ollama / llama.cpp 上的 LLM、Piper / Kokoro 等本機 TTS），達成完全離線。
    • 執行：檔案讀寫、擷取、轉碼、合成等重度運算在使用者本機完成。
  • 通訊與儲存匯流排（Bus & SSOT） 則藉由現代瀏覽器的 File System Access API 搭配結構化規範（JSON Schema），以本機檔案系統作為唯一的真實來源（Single Source of Truth）。

2. 背景與痛點：傳統 AI 系統的困境

2.1 雲端 AI SaaS 的三大代價

  1. 算力稅 (Compute Tax)：每次模型推理、圖像生成、語音合成或影片渲染，都在燃燒服務商的伺服器成本，迫使產品採取昂貴的訂閱制或點數制。
  2. 隱私與安全黑盒 (Privacy Black Box)：使用者的產品原始碼、機密資料、個人聲音與自訂素材必須上傳至服務商雲端處理與保存，企業與個人顧慮重重。
  3. 成品難以微調 (Rigid Outputs)：SaaS 產出的成片或素材無法精準細修，一旦不滿意只能重新花費點數重新生成。

2.2 本地運算與 Coding Agent 的普及

近年來，使用者的本機開發環境發生了劇變：

  • 一般開發機已足以負擔擷取、轉碼、合成等執行層工作；部分高階機器甚至能跑本機 LLM / TTS 模型。
  • 本地開源管線（如 FFmpeg 音視訊合成、Playwright 瀏覽器渲染）極其成熟且完全免費。
  • Coding Agent 普及，具備強大的檔案讀寫、指令調度、邏輯推理與自動修復能力，且使用者多半已為其付費。

核心反思：既然使用者手上已有一具能推理、能操作本機工具的 Agent，前端為何還要在雲端架設後端、重複支付一次推論與運算成本？

3. 核心概念：頭腦與引擎 (Brain & Engine)

AI 產品需要*頭腦（LLM 推論）與引擎（推論所消耗的 token）。傳統 SaaS 兩者都由服務商提供，再以訂閱費回收成本。AOA 把兩者都交給使用者的 Agent；服務只提供介面與規格。*

角色職責由誰提供
服務介面（網頁工作台或 API）、以 URL 發布的規格、驗證 Agent 的結果服務方，邊際成本趨近於零
頭腦LLM 推論：理解需求、規劃步驟、寫檔、呼叫本機工具使用者的 Agent，以及使用者選擇的模型
引擎推論所消耗的 token使用者的 Agent 方案，或執行自建模型的本機硬體
┌────────────────────────────────────────────────────────┐
│                   Web Browser                          │
│  ┌──────────────────────────────────────────────────┐  │
│  │     AOA Frontend (靜態工作台 / 協議載體)           │  │
│  │     - 零推論 (Zero-Inference)                    │  │
│  │     - 協議驗證器 (Schema Validator)              │  │
│  │     - 狀態視覺化與編輯器 (Visualizer & Editor)    │  │
│  └────────────────────────┬─────────────────────────┘  │
└───────────────────────────┼────────────────────────────┘
                            │ File System Access API
                            │ (Local Directory Handle)
┌───────────────────────────┼────────────────────────────┐
│ User Local Machine        │                            │
│                           ▼                            │
│    ┌──────────────────────────────────────────────┐    │
│    │ Local Filesystem (Shared SSOT)               │    │
│    │ ├── specs / schemas                          │    │
│    │ ├── project.json / scene.json                │    │
│    │ ├── activity.json (進度訊號)                 │    │
│    │ └── assets / output                          │    │
│    └──────────────────────▲───────────────────────┘    │
│                           │                            │
│    ┌──────────────────────┴───────────────────────┐    │
│    │ Local Coding Agent                           │    │
│    │ - 頭腦：LLM 推論                             │    │
│    │ - 引擎：使用者方案的 token                   │    │
│    │   雲端 LLM (預設) / 本機模型 (可選)          │    │
│    │ - 本機工具 (FFmpeg, Playwright, TTS)         │    │
│    │ - 協議遵守者 (Protocol Conformant)           │    │
│    └──────────────────────────────────────────────┘    │
└────────────────────────────────────────────────────────┘

4. AOA 四大核心架構原則 (Core Principles)

原則一：Agent 工作卸載（Offloaded Agent Work）

  • 清楚的 Agent 邊界：需要 Agent 推理與工具操作的工作，以及它消耗的 token，都在使用者的 Agent 上執行。應用層（不論是純靜態前端，或是包含帳號、計費的後端）不執行這部分 Agent 工作，但仍可執行自己的服務，包括輕量模型。
  • 服務商的 Agent 邊際成本趨近於零：服務專注於人機互動（HCI）、工作流程導引、協同中繼資料與協議校驗；Agent 的推論以及它驅動的重度執行，交由使用者端的 Agent 處理（推論可走使用者自己的雲端方案或本機模型）。

原則二：Schema as the Contract（Schema 即合約）

  • 展現/控制層與執行 Agent 之間不以不透明的私有指令或黑盒 API 耦合。
  • 雙方的唯一通訊與狀態轉換合約是一組嚴格定義、開源公開的 JSON Schema / 規格定義。
  • 介面負責將人類意圖結構化為符合 Schema 的規格；Agent 則依照 Schema 規範讀取環境、產出檔案與更新狀態機。

原則三：Filesystem-Centric SSOT & Bus（以檔案系統為核心的真實來源與匯流排）

  • 本地執行真實來源 (Local SSOT)：所有具體的原始碼、中間素材、暫存檔與生成產物，均以本機檔案系統為唯一真實來源。
  • 檔案即通訊訊號：
    • 在純前端場景，前端透過 File System Access API 讀寫檔案，並以中繼資料特徵碼輪詢（Fingerprint Polling）偵測 Agent 的產出；Agent 端則由使用者手動觸發（見模式 A）或由 Companion 推動（見模式 B）。
    • 在具後端協同場景，雲端僅同步脫敏後的專案中繼資料（Metadata Plane），核心資料（Data Plane）永遠扎根本機。
    • 雙方寫入遵守鎖定約定（如 lock 檔、先寫暫存檔再改名的 write-temp-then-rename），以降低並行競態風險。File System Access API 本身不提供跨行程檔案鎖，Agent 是否遵守約定亦需驗證，因此前端讀取時仍應做 Schema 驗證與容錯。

原則四：Local-First & Data Sovereignty（本地優先與資料主權）

  • 資產不經過本服務：專利代碼、私有素材、內部網站登入憑證與創作原稿保存在使用者受控環境，本服務的伺服器（若有）不經手這些資料。
  • 隱私邊界由使用者選擇：Agent 推論時，必要的上下文會送往使用者所選的 LLM 供應商，隱私邊界等同該供應商的資料政策；若需完全不出本機，可改用本機 LLM / TTS。
  • 自給自足（Self-Sustaining）：即便雲端後端斷線或服務停止營運，本機專案與產出資產依然完整可讀、可透過本地工具鏈獨立編譯與運行。

5. 協作模式 (Collaboration Modes)

AOA 支援漸進式的四種模式：模式 A、B 是搭配本機資料夾的前端；模式 C 加上輕量後端；模式 D 則完全沒有前端。

模式 A：純工作台模式（Pure Workbench / File-Driven）

最簡單的前端形式，無需本機安裝任何額外伺服器。

  1. 前端透過 File System Access API 取得 Handle。
  2. 前端每 N 秒比對關鍵檔案中繼資料（lastModified 與檔案大小計算的 Fingerprint）。
  3. 當 Agent 完成分鏡或生成音訊時，特徵碼變更，前端無感自動更新。
  4. 前端需要 Agent 介入時（例如修改了文案），在狀態檔標註 stale，並提供標準指令（如 /video-sync），使用者在終端機貼上執行。

模式 B：伴侶增強模式（Companion-Enhanced / Push-Driven）

當環境允許時，啟用極致的無感體驗。

  1. 本機隨專案啟動微型 WebSocket Companion（僅綁定 127.0.0.1，不對外暴露）。
  2. 安全配對機制：WebSocket 不受 CORS 保護，Companion 必須驗證連線的 Origin header 並搭配一次性配對 Token，以防範跨站連線劫持。
  3. Companion 提供即時事件推播（Push），取代輪詢。
  4. 前端可直接點擊「立即重新渲染」，由 Companion 執行白名單內的本機確定性指令。

注意：從公開 HTTPS 網站（如 GitHub Pages）連線至 127.0.0.1，新版 Chromium 的 Local Network Access 機制會要求使用者授權，前端需處理授權被拒時退回模式 A 的流程。

模式 C：具後端混合架構（Backend-Enabled / Hybrid AOA）

適用於需要團隊協作、帳號權限或企業級管理的多租戶系統。

重要觀念：AOA 並不排斥後端伺服器！在具後端的系統中，AOA 實現了**「控制平面（Control Plane）與算力平面（Compute Plane）的徹底解耦」**：

[ Cloud Backend (控制平面) ]
  ├── 帳號認證 (Auth) & 訂閱計費 (Billing)
  ├── 團隊協同 (Team Sync) & 專案中繼資料 (Metadata)
  └── 共享範本庫 (Shared Protocol / Prompt Registry)
         ▲
         │ (輕量 JSON / Schema Sync)
         ▼
[ Web UI / Native App ] <──(本地協議匯流排)──> [ Local SSOT ] <──> [ Local Agent ]
                                                 └── 私有代碼、素材與重度執行算力
  1. 雲端後端只做薄控制層：
    • 後端專注於用戶權限、協同通知、計費與方案管理，以及發布標準化 Schema 與 Prompt 模組。
    • 後端完全不跑高耗能的模型推論與多媒體渲染，服務商的邊際算力成本趨近於零（Near-Zero Marginal Compute Cost）。
  2. 算力與資料留存使用者端 (BYOA - Bring Your Own Agent)：
    • 企業用戶的專利原始碼、商業機密與龐大影音素材，留在員工本地由 Agent 運算與渲染，不經過本服務後端。
    • 推論則走企業自選的 LLM 供應商（可為已簽署資料協議的企業方案）或內部自建模型。
    • 只有經過脫敏、通過 Schema 驗證的「最終專案中繼資料」或使用者明確同意發布的成片，才會上傳同步至雲端後端，大幅簡化企業的隱私合規範圍。

模式 D：純後端（Backend-Only / Agent-Operated API）

適用於沒有使用者介面的服務：Agent 本身就是客戶端。

  1. 服務提供 HTTP API（或包成 MCP server），並在一個 URL 發布規格：OpenAPI 文件、Guide 或 Skill，以及 JSON Schema。
  2. Agent 讀取規格、規劃步驟，直接呼叫 API。服務端保存資料與狀態，並依 Schema 驗證每一個請求。
  3. 服務端仍然不跑推論：頭腦（LLM 推論）與引擎（token）都留在使用者的 Agent。
  4. API 以使用者範圍的憑證驗證 Agent，並把 Agent 的每個請求都視為不可信的輸入。

規格的入口

不論哪一種模式，Agent 都要先取得規格，而入口通常就是一個 URL：Guide 頁面、/api/index.json 這類索引、OpenAPI 文件或 Skill 套件。好的入口會以絕對網址與雜湊值列出所有 Schema、範本與指令，讓 Agent 能驗證下載的內容。本站的 /api/index.json 就是 Video Studio 的入口。

6. 參考實作 (Reference Implementations)

AOA 網站提供兩個工作台，各自有獨立的靜態介面、協議 Schema、Agent Skill 與專案範本：

  • Slide Studio（模式 A）：Agent 以 Slidev 搭配 HTML、SVG 架構圖與 Three.js 組件製作簡報，在本機匯出 PDF；網頁只讀寫資料夾。
  • Video Studio（模式 B）：Agent 把產品網址或一段故事做成有旁白的影片，細節如下。

Video Studio 的組成：

  • 前端工作台：Vue 3 + Tailwind 靜態網站，託管於 GitHub Pages。提供產品規格填寫、分鏡看板、旁白編輯與成片預覽。
  • 協議庫：apps/video/specs/*.schema.json 定義了 project、scene、workflow 與 activity 格式。
  • 本機 Agent：由 Claude Code 讀取線上 Guide 與本機 Skill，調用本機 Playwright 擷取網頁、Edge-TTS（微軟線上語音服務，可替換為 Piper / Kokoro 等本機 TTS）生成語音、FFmpeg 合成 60fps 影片。
  • 效益：
    • 開發者：0 伺服器月租、0 GPU 帳單、免維護資料庫。
    • 使用者：本服務不收費（推論成本由使用者既有的 Agent 方案負擔）；素材不經過本服務伺服器，原始碼與音訊素材完整可控。

7. 適用場景與限制 (When to Use & Limitations)

適合採用的場景

  • 重度依賴本機工具鏈的生成任務：如程式碼生成、本地測試、音視訊後製、文件編排。
  • 高度隱私敏感型產品：企業內部系統分析、私人故事繪本/動畫、個人隱私資料處理（搭配企業級 LLM 方案或本機模型效果最佳）。
  • 開發者工具與生產力套件：專為已有 Coding Agent 的工程師或專業用戶設計的工具。

局限性與邊界

  • 瀏覽器相容性：依賴 File System Access API（showDirectoryPicker），目前僅桌面版 Chrome、Edge 等 Chromium 瀏覽器支援；Brave 預設停用，Firefox 與 Safari 不支援。
  • 依賴使用者本機環境：使用者環境需具備基本執行環境（如 Node.js、Coding Agent 等），並自行負擔 Agent 的訂閱或 API 費用。
  • Agent 輸出不具確定性：Agent 產出未必完全符合 Schema，前端需驗證並提供重試或修復指引。
  • 模式 A 需人工觸發：無 Companion 時，使用者需手動在終端機執行指令才能推動 Agent。
  • 目錄授權需重新取得：重新整理頁面後，目錄 Handle 的讀寫權限通常需使用者再次授權。

8. 結論 (Conclusion)

AOA（代理卸載式架構）打破了「AI 產品必須等於雲端 SaaS」的固有思維。它將前端還原為純粹的互動介面與協議標準，把推論成本、執行權與資料主權交還給使用者自備的 Agent——推論要走雲端還是本機模型，也由使用者決定。

這是一條兼顧服務商零維護成本、使用者可控的資料隱私與靈活擴展能力的全新架構路徑。