OpenMAIC 教學手冊

文件版本：1.1 研究日期：2026-09-13 OpenMAIC 版本：v1.0.1（發布於 2026-09-06T07:09:09Z，「Security and stability」；已透過官方 Releases API 覆核，其後無任何新版本，含 pre-release） Node.js 需求：>= 22.19.0（engines.node，v1.0.1 起自 20.9 提高）　pnpm：10.28.0（packageManager 以 SHA-512 釘死） 授權：MIT（例外：packages/mathml2omml 為 LGPL-3.0-or-later；packages/pptxgenjs 為第三方 MIT） 官方 Repo：THU-MAIC/OpenMAIC　託管服務：open.maic.chat 學術出處：From MOOC to MAIC: Reimagine Online Teaching through LLM-driven Agents, Journal of Computer Science and Technology (JCST), DOI 10.1007/s11390-025-6000-0 文件狀態：Based on latest verified sources（所有官方能力均對照 2026-09-13 當日之官方 Repo 實際查證，來源包含 README.md、.env.example、CHANGELOG.md、docker-compose.yml、package.json、render-service/README.md、GitHub Releases API，以及 skills/agent-runtime/、lib/server/agent-runtime/ 的實際目錄清單） 篇幅：53 章，分為 11 部；目錄涵蓋全部 53 章與其下所有小節

關於本手冊

這份手冊要回答的問題

本手冊不是 OpenMAIC README 的中文翻譯，也不是「OpenMAIC 是什麼」的簡介。它要回答的是一個工程管理層級的問題：

一個以 Java / Spring Boot / Vue / Angular 為主力技術棧、同時背負大量 Legacy System 的企業軟體工程團隊，能不能、以及該怎麼把 OpenMAIC 用成內部的「知識工程與 AI Agent 賦能平台」，來支援 Web Application 開發、Legacy System 逆向工程與 Framework Upgrade？

一個必須先講清楚的事實

在開始之前，有一件事必須先攤開來說，否則後面所有章節都會被誤讀。

OpenMAIC 官方的定位是「多智能體互動課堂」（Multi-Agent Interactive Classroom），它的核心能力是：把一個主題或一份文件，自動變成一堂有 AI 老師講課、有 AI 同學討論、有測驗、有互動實驗的線上課程。

本手冊查證了 main 分支 skills/agent-runtime/ 目錄下的 23 個內建 Skill，結果如下：

build-personal-skill        curriculum-planner        deep-interactive
deep-research               fact-check                feynman-learning
k12-core-literacy-planning  learning-to-learn         lecture-style
page-clone                  pptx-import               pro-editing
slide-craft                 slide-dsl                 social-emotional-learning
spiral-curriculum           stage-design              stage-dsl
style-clone                 teacher-style-clone       understanding-by-design
vocational                  workshop-style

全部 23 個都是「教學法」與「投影片製作」類的 Skill，沒有任何一個是 reverse-engineering、framework-upgrade、code-review 或 api-design。

這代表什麼？

換句話說：

OpenMAIC 不是 Coding Agent，它是 Coding Agent 的「上游」。 它負責把企業內部散落的架構知識、Legacy 系統知識、升級規範，變成人與 AI 都能反覆消費的結構化教材；真正動手改程式的，還是 Claude Code、GitHub Copilot、Codex。

第 3 章 會完整展開這個評估。如果你只有 10 分鐘，請直接讀第 3 章。

資訊可信度標示制度（非常重要）

為了避免「把企業建議冒充成官方功能」，本手冊全篇使用以下四種標示：

另外，凡官方沒有寫的內容，本手冊一律寫成「官方資料未說明」，不猜測、不補完。

特別提醒兩個高頻誤解：

⚠️ Pro Workbench 與 Agent Runtime 在 v1.0.1 都是 Feature Flag 預設 OFF 的功能。 本手冊凡提到這兩者，一律加註【Experimental】。你在正式環境開啟它們，等於自願承擔上游變動風險。

與本目錄既有手冊的關係

.github/教學/AI開發/ 已有多份相關手冊，分工如下：

本文件自成一冊，不需先讀上述任何一本。

目錄

全書共 53 章、419 個小節，依主題歸為 11 個部。 目錄涵蓋全部章與小節，每一項皆為可點擊的內文錨點連結。

前言與使用說明：

• 關於本手冊（定位、可信度標示制度、與既有手冊的分工）
• 目錄（本節）

依角色的建議閱讀動線：

第一部　認識 OpenMAIC

1. 文件資訊
   • 1.1 文件基本資料
   • 1.2 適用對象與適用範圍
   • 1.3 技術基準與查證方法
   • 1.4 版本對應與有效期
2. OpenMAIC Overview【Official】
   • 2.1 OpenMAIC 是什麼
   • 2.2 核心理念：從 MOOC 到 MAIC
   • 2.3 主要功能總覽
   • 2.4 Provider Neutral 架構
   • 2.5 版本演進史（v0.1.0 → v1.0.1）
   • 2.6 本章實務案例
   • 2.7 本章注意事項
3. 適用性評估：OpenMAIC 能做什麼、不能做什麼
   • 3.1 為什麼需要這一章
   • 3.2 官方能力盤點（確定可以）
   • 3.3 經設計後可以（需自建 Skill / Materials）
   • 3.4 做不到、也不該用它做的事
   • 3.5 三大企業訴求的逐項評分
   • 3.6 決策樹：什麼時候該用 OpenMAIC
   • 3.7 本章實務案例
   • 3.8 本章注意事項
4. OpenMAIC 與其他 AI 工具的比較
   • 4.1 定位總表
   • 4.2 與 ChatGPT / Claude / Gemini 的差異
   • 4.3 與 GitHub Copilot / Claude Code / Codex 的差異
   • 4.4 為什麼不該把 OpenMAIC 當成另一個 Chatbot
   • 4.5 能力矩陣（15 項能力 × 7 個工具）
   • 4.6 本章實務案例
   • 4.7 本章注意事項
5. OpenMAIC 與傳統教育平台的比較
   • 5.1 LMS / 錄影教學 / 文件 / Chatbot / RAG 的侷限
   • 5.2 OpenMAIC 的差異點：內容是「生成」的，不是「錄」的
   • 5.3 企業知識載體的演進路徑
   • 5.4 本章實務案例
   • 5.5 本章注意事項

第二部　架構解析

6. 系統架構總覽【Official】
   • 6.1 五層架構模型
   • 6.2 各層的責任邊界
   • 6.3 執行時的三條主要資料流
   • 6.4 部署形態的三種樣貌
   • 6.5 本章實務案例
   • 6.6 本章注意事項
7. 原始碼架構解析【Official】
   • 7.1 Repository 頂層結構
   • 7.2 app/ —— Next.js App Router
   • 7.3 lib/ —— 核心業務邏輯
   • 7.4 packages/ —— Workspace 套件
   • 7.5 skills/ —— Skill 套件
   • 7.6 render-service/ —— 獨立的影片匯出服務
   • 7.7 從架構推導的企業風險點
   • 7.8 本章實務案例
   • 7.9 本章注意事項
8. 技術棧與版本查證【Official】
   • 8.1 完整技術棧
   • 8.2 版本需求的硬性檢查
   • 8.3 為什麼是這些技術（企業視角的評估）
   • 8.4 依賴的外部服務分類
   • 8.5 技術棧對企業技能的要求
   • 8.6 本章實務案例
   • 8.7 本章注意事項
9. DSL、Renderer 與 Editor【Official】
   • 9.1 為什麼要有 DSL
   • 9.2 DSL 在架構中的位置
   • 9.3 課件的層級結構
   • 9.4 Renderer 與 Editor
   • 9.5 企業整合：OpenMAIC SDK 的可能性【建議】
   • 9.6 本章實務案例
   • 9.7 本章注意事項
10. Persistence 與 PostgreSQL 的角色【Official】

• 10.1 三種儲存模式
• 10.2 @openmaic/storage 的四類 Store
• 10.3 PostgreSQL 的具體角色
• 10.4 Database Schema 的資訊缺口
• 10.5 資產（Asset）的位元組模型
• 10.6 容量規劃【建議】
• 10.7 本章實務案例
• 10.8 本章注意事項

第三部　安裝與部署

11. 安裝前置需求【Official】

• 11.1 硬性需求
• 11.2 Prerequisites Checklist
• 11.3 各作業系統的環境準備
• 11.4 企業網路環境的額外準備
• 11.5 本章實務案例
• 11.6 本章注意事項

12. 安裝方法 A：原始碼安裝【Official】

• 12.1 完整八步驟
• 12.2 啟用 Pro Workbench 與 Agent Runtime【Experimental】
• 12.3 目錄與檔案權限【建議】
• 12.4 本章實務案例
• 12.5 本章注意事項

13. 安裝方法 B：Docker / Docker Compose【Official】

• 13.1 最簡單的啟動方式
• 13.2 Compose 的三個 Service 與兩個 Profile
• 13.3 三種常用啟動組合
• 13.4 企業級 Compose 覆寫檔【建議】
• 13.5 常用維運指令
• 13.6 本章實務案例
• 13.7 本章注意事項

14. 安裝方法 C：開發環境建置【Official】

• 14.1 什麼時候需要開發環境
• 14.2 開發環境設定
• 14.3 常用開發指令
• 14.4 排錯用的開發技巧【建議】
• 14.5 本章實務案例
• 14.6 本章注意事項

15. 環境變數完整說明【Official】

• 15.1 變數分類總覽
• 15.2 ① LLM Providers
• 15.3 ② TTS 語音合成
• 15.4 ③ ASR 語音辨識
• 15.5 ④ PDF 解析
• 15.6 ⑤ 圖片生成
• 15.7 ⑥ 影片生成
• 15.8 ⑦ 網頁搜尋
• 15.9 ⑧ Agent Runtime【Experimental】
• 15.10 ⑨ Feature Flags【Experimental】
• 15.11 ⑩ 伺服端持久化
• 15.12 ⑪ 存取控制與安全
• 15.13 ⑫ 網路與 Proxy
• 15.14 ⑬ Render Service
• 15.15 ⑭ 記錄與效能
• 15.16 企業標準 .env.local 範本【建議】
• 15.17 本章實務案例
• 15.18 本章注意事項

16. Provider 設定實務【Official】

• 16.1 Provider 設定的三種企業策略
• 16.2 策略 A：直連公有 Provider
• 16.3 策略 B：企業 Model Gateway（建議）
• 16.4 策略 C：全內網本地模型
• 16.5 Provider 選型的成本／品質權衡【建議】
• 16.6 本章實務案例
• 16.7 本章注意事項

第四部　核心功能

17. Classic Generator：兩階段課程生成管線【Official】

• 17.1 What：什麼是 Classic Generator
• 17.2 Why：為什麼要分兩階段
• 17.3 How：完整操作流程
• 17.4 Example：一個完整的企業建課範例
• 17.5 Best Practice
• 17.6 Common Mistake
• 17.7 本章實務案例
• 17.8 本章注意事項

18. Multi-Agent Classroom【Official】

• 18.1 What：多智能體課堂是什麼
• 18.2 Why：多個 Agent 有什麼實際價值
• 18.3 課堂的互動型態【Official】
• 18.4 Action Engine：28+ 種動作型別
• 18.5 Classroom State 與 Playback
• 18.6 Example：用圓桌辯論教架構決策
• 18.7 Best Practice
• 18.8 Common Mistake
• 18.9 本章實務案例
• 18.10 本章注意事項

19. Pro Workbench【Experimental】

• 19.1 What：Pro Workbench 是什麼
• 19.2 介面結構【Official】
• 19.3 Agent 的能力【Official】
• 19.4 從對話到課程的完整流程
• 19.5 Session：Chat、Folder、Course 的關係
• 19.6 Steering、Cancel 與 Resume【Experimental】
• 19.7 Example：用 Workbench 規劃完整訓練體系
• 19.8 Best Practice
• 19.9 Common Mistake
• 19.10 本章實務案例
• 19.11 本章注意事項

20. Agent Runtime【Experimental】

• 20.1 What：Agent Runtime 是什麼
• 20.2 啟用條件（缺一不可）【Official】
• 20.3 可調參數與其意義【Official】
• 20.4 執行模型（推導）
• 20.5 官方明文的一致性設計【Official】
• 20.6 Agent 可用的工具【Official，依原始碼檔名歸納】
• 20.7 Event Stream 與 Replay
• 20.8 Best Practice
• 20.9 Common Mistake
• 20.10 本章實務案例
• 20.11 本章注意事項

21. Skills 機制【Official】

• 21.1 What：Skill 是什麼
• 21.2 內建 Skills 完整清單【Official，實際查證】
• 21.3 Skill 的生命週期
• 21.4 Skill 的格式【Official】
• 21.5 v1.0.1 的 Skill 安全強化【Official】
• 21.6 Example：用不同 Skill 產出同一主題的三種課
• 21.7 企業自建 Skills 的設計原則【建議】
• 21.8 Skill 治理【建議】
• 21.9 Best Practice
• 21.10 Common Mistake
• 21.11 本章實務案例
• 21.12 本章注意事項

22. Materials 教材機制【Official】

• 22.1 What：Materials 是什麼
• 22.2 Materials 的處理管線【Official】
• 22.3 Materials ≠ RAG 知識庫
• 22.4 企業該上傳什麼、不該上傳什麼
• 22.5 PDF 解析品質的實務差異
• 22.6 Example：一份文件的完整處理流程
• 22.7 Best Practice
• 22.8 Common Mistake
• 22.9 本章實務案例
• 22.10 本章注意事項

23. Export：PPTX / HTML / ZIP / MP4【Official】

• 23.1 四種匯出格式
• 23.2 離線就緒（Offline-ready）【Official】
• 23.3 MP4 匯出與 render-service【Official】
• 23.4 MP4 匯出的成本與時間預期【建議】
• 23.5 PPTX 匯出與匯入的雙向能力
• 23.6 匯出後的內容治理【建議】
• 23.7 Best Practice
• 23.8 Common Mistake
• 23.9 本章實務案例
• 23.10 本章注意事項

第五部　企業應用【建議】

24. OpenMAIC + AI Agent 軟體開發總體流程【建議】

• 24.1 核心定位：OpenMAIC 在軟體開發中的位置
• 24.2 完整的九步驟流程
• 24.3 步驟五：把 OpenMAIC 產出變成 Agent 脈絡
• 24.4 為什麼「先學再做」對 AI 輔助開發特別重要
• 24.5 本章實務案例
• 24.6 本章注意事項

25. OpenMAIC + Web Application 開發【建議】

• 25.1 目標技術棧
• 25.2 一門完整課程：「企業級 Web Application 開發」
• 25.3 各 SDLC 階段的具體 Prompt 設計
• 25.4 課程與 SDLC 的對應表
• 25.5 本章實務案例
• 25.6 本章注意事項

26. OpenMAIC + Legacy System 逆向工程【建議】

• 26.1 正確的職責劃分
• 26.2 階段一：用 Coding Agent 產出分析報告
• 26.3 階段二：人工覆核的具體做法
• 26.4 階段三：用 OpenMAIC 建立傳承課程
• 26.5 涵蓋 Legacy 技術棧的對應建議
• 26.6 本章實務案例
• 26.7 本章注意事項

27. OpenMAIC + Framework Upgrade【建議】

• 27.1 職責劃分
• 27.2 案例一：Spring Boot 2.x → 3.x → 4.x
• 27.3 案例二：Java 8 → 17 → 21 → 25
• 27.4 案例三：Vue 2 → Vue 3
• 27.5 案例四：Angular Legacy → Latest Angular
• 27.6 案例五：Maven 3 → Maven 4
• 27.7 升級課程的通用結構範本【建議】
• 27.8 本章實務案例
• 27.9 本章注意事項

28. 企業自建 Skills 設計【建議】

• 28.1 設計原則回顧
• 28.2 十三個企業 Skill 的規格
• 28.3 共用的基底規則
• 28.4 六個核心 Skill 的完整規格
• 28.5 Skill 的版控與治理
• 28.6 本章實務案例
• 28.7 本章注意事項

29. OpenMAIC Prompt Engineering 方法論【建議】

• 29.1 為什麼 OpenMAIC 的 Prompt 與一般 AI 不同
• 29.2 五層 Prompt 結構
• 29.3 八種 Prompt 型態
• 29.4 Prompt 品質檢查表【建議】
• 29.5 Prompt 的反模式
• 29.6 本章實務案例
• 29.7 本章注意事項

30. 企業標準 Prompt 模板庫【建議】

• 30.1 模板 1：通用課程生成
• 30.2 模板 2：整套課綱規劃（Pro Workbench 用）
• 30.3 模板 3：Legacy 逆向工程知識傳承
• 30.4 模板 4：Framework 升級實戰
• 30.5 模板 5：Web Application 開發
• 30.6 模板 6：架構教學課程
• 30.7 模板 7：AI Agent 賦能課程
• 30.8 模板使用流程
• 30.9 Prompt 版控【建議】
• 30.10 本章實務案例
• 30.11 本章注意事項

第六部　與 Coding Agent 協作【建議】

31. OpenMAIC + GitHub Copilot【建議】

• 31.1 兩者的關係
• 31.2 能力對照
• 31.3 連接點：copilot-instructions.md
• 31.4 完整協作流程
• 31.5 本章實務案例
• 31.6 本章注意事項

32. OpenMAIC + Claude Code【建議】

• 32.1 Claude Code 在協作中的三個角色
• 32.2 角色 ①：知識生產者（最重要）
• 32.3 角色 ②：知識消費者
• 32.4 角色三：OpenMAIC 的維運助手
• 32.5 完整的四階段協作
• 32.6 本章實務案例
• 32.7 本章注意事項

33. OpenMAIC + Codex【建議】

• 33.1 官方唯一的實質整合點
• 33.2 兩種協作模式
• 33.3 模式 A：Codex 驅動 OpenMAIC
• 33.4 模式 B：知識接力
• 33.5 本章實務案例
• 33.6 本章注意事項

34. OpenMAIC + RAG、MCP 與 Agent Memory【建議】

• 34.1 為什麼需要外部知識層
• 34.2 RAG 與 OpenMAIC 的分工
• 34.3 用 RAG 輔助挑選建課素材
• 34.4 MCP 的角色
• 34.5 完整的企業 AI 知識架構【建議】
• 34.6 本章實務案例
• 34.7 本章注意事項

35. AI Agent 角色編組【建議】

• 35.1 八個角色的職責與工具對應
• 35.2 OpenMAIC 作為「AI Virtual Software Engineering School」
• 35.3 各角色的協作時序
• 35.4 本章實務案例
• 35.5 本章注意事項

第七部　SDLC / SSDLC 整合【建議】

36. Enterprise SDLC 整合【建議】

• 36.1 SDLC 各階段的整合總表
• 36.2 三個 OpenMAIC 價值最高的階段
• 36.3 Quality Gate 的設計
• 36.4 本章實務案例
• 36.5 本章注意事項

37. SSDLC 整合【建議】

• 37.1 SSDLC 各環節與 OpenMAIC
• 37.2 為什麼「安全編碼」與「事故案例」價值最高
• 37.3 AI 開發時代的新安全議題
• 37.4 SSDLC 治理模型
• 37.5 本章實務案例
• 37.6 本章注意事項

38. 企業內部導入架構【建議】

• 38.1 完整的企業導入架構
• 38.2 認證與授權的補強【建議】
• 38.3 Model Gateway 的必要性
• 38.4 知識流的架構
• 38.5 分階段導入的架構演進
• 38.6 本章實務案例
• 38.7 本章注意事項

第八部　安全

39. Security Architecture【Official + 建議】

• 39.1 v1.0.1 的四個安全公告【Official】
• 39.2 v1.0.1 的其他安全強化【Official】
• 39.3 SSRF 與出站流量控制
• 39.4 資料外洩與 Provider 邊界
• 39.5 Prompt Injection 與惡意教材
• 39.6 稽核紀錄的缺口與補強
• 39.7 完整的安全檢查清單
• 39.8 本章實務案例
• 39.9 本章注意事項

40. 開發環境與正式環境的安全基線對照

• 40.1 完整對照表
• 40.2 兩份 .env 範本的關鍵差異
• 40.3 環境升級的檢查腳本
• 40.4 本章注意事項

41. 威脅模型與緩解措施

• 41.1 威脅總覽
• 41.2 XSS 與內容注入
• 41.3 Prompt Injection 與惡意教材
• 41.4 資料外洩
• 41.5 供應鏈安全
• 41.6 威脅緩解總表
• 41.7 本章注意事項

第九部　部署與維運

42. 企業部署架構

• 42.1 四種部署形態
• 42.2 形態 ①②：單機部署
• 42.3 形態 ③：多實例 + HA
• 42.4 Kubernetes 部署【建議】
• 42.5 render-service 的隔離要求
• 42.6 備份策略
• 42.7 本章實務案例
• 42.8 本章注意事項

43. Monitoring 監控

• 43.1 監控指標清單
• 43.2 監控架構
• 43.3 Grafana Dashboard 設計【建議】
• 43.4 關鍵告警規則【建議】
• 43.5 本章實務案例
• 43.6 本章注意事項

44. Cost Management 成本治理

• 44.1 成本從哪裡來
• 44.2 成本熱點排序
• 44.3 十項成本控制手段
• 44.4 預算控管機制
• 44.5 成本效益的量化方法【建議】
• 44.6 本章實務案例
• 44.7 本章注意事項

45. 日常維護

• 45.1 維護工作清單
• 45.2 Agent Event 資料歸檔
• 45.3 課程生命週期管理
• 45.4 Materials 與資產維護
• 45.5 API Key 輪替
• 45.6 本章實務案例
• 45.7 本章注意事項

46. 升級策略

• 46.1 升級流程
• 46.2 升級前必檢查的 12 個項目
• 46.3 自動化的升級前檢查腳本
• 46.4 既有課件相容性驗證
• 46.5 Rollback 方案
• 46.6 安全更新的加速流程
• 46.7 本章實務案例
• 46.8 本章注意事項

47. Troubleshooting 與常見錯誤

• 47.1 問題排查總表
• 47.2 十一個最常見的設定錯誤
• 47.3 診斷流程圖
• 47.4 快速診斷指令集
• 47.5 FAQ
• 47.6 本章實務案例
• 47.7 本章注意事項

第十部　治理與導入

48. 企業最佳實務與 Anti-pattern

• 48.1 架構最佳實務
• 48.2 Prompt 最佳實務
• 48.3 Agent 最佳實務
• 48.4 Skill 最佳實務
• 48.5 課程最佳實務
• 48.6 安全最佳實務
• 48.7 治理最佳實務
• 48.8 成本最佳實務
• 48.9 十大 Anti-pattern 總結
• 48.10 本章注意事項

49. OpenMAIC Governance 與 Center of Excellence【建議】

• 49.1 治理組織架構
• 49.2 十一項治理標的
• 49.3 核心政策文件【建議】
• 49.4 AI Software Engineering Academy 六級課程體系【建議】
• 49.5 Center of Excellence 的日常運作
• 49.6 本章實務案例
• 49.7 本章注意事項

50. 導入 Roadmap、KPI 與風險【建議】

• 50.1 七階段 Roadmap
• 50.2 KPI 設計
• 50.3 風險與緩解
• 50.4 各角色的導入建議
• 50.5 本章實務案例
• 50.6 本章注意事項

第十一部　速查

51. 30 分鐘 Quick Start

• 51.1 前置確認（2 分鐘）
• Step 1 — Install（5 分鐘）
• Step 2 — Configure（2 分鐘）
• Step 3 — Start（2 分鐘）
• Step 4 — Enable Workbench（3 分鐘）
• Step 5 — Configure PostgreSQL（4 分鐘）
• Step 6 — Configure Model（3 分鐘）
• Step 7 — Create Course（4 分鐘）
• Step 8 — Upload Material（2 分鐘）
• Step 9 — Ask Agent（2 分鐘）
• Step 10 — Edit Course（3 分鐘）
• Step 11 — Export（2 分鐘）
• Step 12 — Validate（1 分鐘）
• 51.2 30 分鐘後你應該有什麼
• 51.3 接下來該做什麼
• 51.4 本章注意事項

52. OpenMAIC Enterprise Cheat Sheet

• 架構速覽
• 安裝速查
• 版本需求
• 環境變數速查（最常用）
• Agent Runtime 速查
• 23 個內建 Skills
• Materials 速查
• Prompt 五層結構
• Export 速查
• 維護速查
• 升級速查
• 安全速查
• Troubleshooting 速查
• 成本速查
• 十大 Anti-pattern
• 決策速查

53. 檢查清單彙總與資料來源

• 53.1 新進成員上手檢查清單
• 53.2 安裝檢查清單
• 53.3 正式環境上線檢查清單
• 53.4 課程發布檢查清單
• 53.5 升級檢查清單
• 53.6 資料來源與版本查核
• 53.7 資料正確性聲明
• 結語

1. 文件資訊

1.1 文件基本資料

1.2 適用對象與適用範圍

適用對象

適用範圍

在範圍內：

• OpenMAIC v1.0.1 的完整功能說明與操作
• 自架（self-hosted）部署：原始碼、Docker Compose、Kubernetes【建議】
• 企業內部導入的架構、安全、成本、治理設計
• 與 GitHub Copilot / Claude Code / Codex 的協作模式設計【建議】
• Web Application 開發、Legacy 逆向工程、Framework Upgrade 三大情境的應用設計【建議】

不在範圍內：

• OpenMAIC 官方託管服務 open.maic.chat 的商務條款、SLA、資料處理協議 —— 企業使用前務必自行與官方確認，本手冊不代為說明
• OpenMAIC 原始碼的逐行解讀（本手冊只到模組責任層級）
• LLM 模型本身的原理與選型細節（請參考本目錄《AI常用方法論比較教學手冊》）
• K-12 教育場景的應用（OpenMAIC 有 k12-core-literacy-planning 等 Skill，但非企業用途）

1.3 技術基準與查證方法

本手冊所有標示【Official】的內容，都是在 2026-09-13 當天實際查證下列官方來源後撰寫：

查證中發現的三個落差（誠實揭露）

📌 這三個落差本身就是使用 OpenMAIC 的重要資訊：一個沒有 docs/ 站、Skill 數量與 README 對不上、且有未實作旗標的專案，代表它仍在快速演進期。這直接影響第 46 章 的升級策略設計。

1.4 版本對應與有效期

⚠️ 若你手上的 OpenMAIC 是 v0.3.x 或更早：本手冊的第四部（核心功能）與第五部（企業應用）幾乎全部依賴 v1.0.0 才引入的 Agent Workbench，請先升級再讀。

v1.0.1 為查證當日的最新版本：本次已透過官方 Releases API 逐筆列舉所有 release，確認 v1.0.1（2026-09-06T07:09:09Z）之後沒有任何新版本，包含 pre-release 與 draft。完整版本清單：

📌 有效期判準：上游約以 2～6 週的節奏發版。若你閱讀本手冊的時間距查證日（2026-09-13）已超過一季， 請先到 Releases 確認是否已有新版，再依第 46.2 節 覆核差異。

2. OpenMAIC Overview【Official】

2.1 OpenMAIC 是什麼

What —— 一句話定義

OpenMAIC（Open Multi-Agent Interactive Classroom）是清華大學 THU-MAIC 團隊開源的平台，能把「一個主題」或「一份文件」自動轉換成一堂有 AI 老師講課、有 AI 同學互動、有測驗、有可操作實驗的完整線上課堂。

拆開來看，它同時是四樣東西：

┌──────────────────────────────────────────────────────────┐
│                       OpenMAIC                            │
├──────────────────────────────────────────────────────────┤
│ ① 內容生成引擎  主題/文件 → 課綱 → 投影片 + 講稿 + 測驗    │
│ ② 多智能體課堂  AI 老師講課、AI 同學提問、辯論、答疑        │
│ ③ 課件編輯器    投影片可視化編輯、DSL 可程式化修改          │
│ ④ Agent 工作台  對話式規劃整套課綱（v1.0.0 起，實驗性）      │
└──────────────────────────────────────────────────────────┘

Why —— 它想解決什麼問題

傳統線上課程（MOOC）的根本問題是：內容是死的，學習者是被動的。錄好的影片不會回答你的問題，不會因為你這一段沒聽懂而換個講法，更不會有同學跟你討論。

OpenMAIC 的答案是：用 LLM 驅動的多個 Agent 即時演出一堂課。老師 Agent 講課、同學 Agent 提問與辯論、你隨時可以打斷發問，整堂課是「跑出來」的而不是「播出來」的。

When —— 什麼時候該想到它

2.2 核心理念：從 MOOC 到 MAIC

OpenMAIC 背後有一篇正式論文：

From MOOC to MAIC: Reimagine Online Teaching through LLM-driven Agents Journal of Computer Science and Technology (JCST), 2026 DOI: 10.1007/s11390-025-6000-0

論文標題本身就說明了設計理念的轉折：

graph LR
    A["MOOC<br/>Massive Open<br/>Online Course"] -->|"問題：內容固定<br/>互動貧乏<br/>製作成本高"| B{"重新想像"}
    B --> C["MAIC<br/>Multi-Agent<br/>Interactive Classroom"]

    A1["預錄影片"] -.-> A
    A2["固定講義"] -.-> A
    A3["單向傳遞"] -.-> A

    C --> C1["即時生成內容"]
    C --> C2["多 Agent 演出"]
    C --> C3["雙向互動"]
    C --> C4["一鍵產課"]

    style A fill:#e8e8e8,stroke:#666
    style C fill:#d4edda,stroke:#28a745
    style B fill:#fff3cd,stroke:#ffc107

對企業而言，這個轉折的意義是：

🎯 這是本手冊最核心的觀念：把 OpenMAIC 當成「教材編譯器」而不是「教材倉庫」。 你維護的是原始碼（企業知識文件），教材是 build 出來的產物。

2.3 主要功能總覽

以下功能全部為 v1.0.1 官方 README 明列【Official】：

（一）內容生成

（二）課堂呈現

（三）多智能體互動

（四）Agent Workbench（v1.0.0 引入，實驗性）

（五）匯出

📌 離線匯出會把 KaTeX、Three.js、Tailwind、Google Fonts 等外部資產內嵌成 data URI，因此可在完全隔離網路的環境播放。這對金融、政府等內網環境是關鍵能力。

（六）國際化

支援 12 個 locale / 11 種語言。以下為官方 README 明列的完整 locale 代碼【Official】：

📌 對台灣企業的意義：zh-TW 是官方一等公民，不是社群翻譯、也不是簡繁轉換的產物。

這代表三件事：

1. 介面不需自行漢化 —— 導入時不必編列翻譯工時，也不會在升級後被官方覆蓋掉自訂翻譯。
2. fr-FR / es-MX / vi-VN 是 v0.3.2（2026-08-14）才加入的 —— locale 清單會隨版本擴充，跨國集團導入前應以當版 README 為準，不要沿用舊手冊的清單。
3. 介面語言 ≠ 課程語言。locale 只決定 OpenMAIC 自身 UI 的顯示語言；課程內容用什麼語言，由你的 Prompt 與 Skill 決定（見第 29 章）。企業若要求「一律產出繁體中文課程」，必須在 Skill 的用語規範中明寫，不能只靠把 UI 切成 zh-TW。

2.4 Provider Neutral 架構

What

OpenMAIC 不綁定任何一家 AI 供應商。所有能力（文字生成、語音合成、語音辨識、圖片生成、影片生成、網頁搜尋、PDF 解析）都是可插拔的 Provider。

已支援的 LLM Provider【Official，依 .env.example 實際欄位】

OpenAI          Azure OpenAI    AtlasCloud      Anthropic
Google Gemini   DeepSeek        Qwen            Kimi
MiniMax         GLM (Zhipu)     SiliconFlow     Doubao
OpenRouter      Grok            Tencent         Xiaomi
Ollama (本地)    Lemonade (本地)  Amazon Bedrock  OpenAI 相容 API

Why —— 為什麼這對企業特別重要

How —— 最小設定範例

# 只設定一組就能跑
ANTHROPIC_API_KEY=sk-ant-...

# 或走公司內部 Gateway
OPENAI_API_KEY=internal-gateway-token
OPENAI_BASE_URL=https://ai-gateway.corp.example.com/v1
OPENAI_MODELS=gpt-5.5,gpt-5.5-mini

⚠️ v1.0.1 起的重要變更：指向 loopback（127.0.0.1）或私有網段的 model server URL，在非 production build 會被拒絕。若你要接內網 Ollama 或內部 Gateway，必須設定：

ALLOW_LOCAL_NETWORKS=true

這是 GHSA-9m7h-vh2h-rc3w（SSRF 防護）修補的副作用，屬於刻意的安全設計，不是 bug。詳見第 39 章。

2.5 版本演進史（v0.1.0 → v1.0.1）

理解版本演進，才知道哪些功能是「新到還不穩」的。

timeline
    title OpenMAIC 版本演進與企業採用門檻
    section 概念驗證期
        v0.1.0 (2026-03) : 首個 release
        v0.1.1 (2026-04) : 離線匯出 / Ollama
        v0.2.0 (2026-04) : 深度互動模式
        v0.2.1 (2026-04) : 語音克隆
    section 可用期
        v0.2.2 (2026-06) : 投影片可編輯
        v0.3.0 (2026-06) : MIT 授權 / PBL v2
        v0.3.1 (2026-07) : MP4 匯出
        v0.3.2 (2026-08) : 伺服端持久化
    section 企業採用期
        v1.0.0 (2026-08) : Agent Workbench / Skills
        v1.0.1 (2026-09) : 安全修補 ← 建議最低版本

✅ 企業採用建議版本：v1.0.1 或更新 理由：v1.0.0 存在 4 個已公開的安全漏洞（含 Path Traversal 與 XSS），不應部署在正式環境。

2.6 本章實務案例

案例：把一份 60 頁的架構文件變成 3 小時新人課

背景

某金融業核心系統團隊有一份 60 頁的《核心帳務系統架構說明書》（PDF），新人平均要花兩週才讀懂，且讀完常常抓錯重點。資深架構師每季要花 6 小時親自講一遍。

做法

1. 將 PDF 上傳為 Session Material
2. 用 curriculum-planner Skill 請 Agent 規劃 6 堂課的課綱
3. 人工覆核課綱，調整章節順序與深度
4. 逐堂生成內容
5. 用 MAIC Editor 修正 Agent 對業務術語的誤解（約 15 處）
6. 匯出 Classroom ZIP 放到內網

結果對照

關鍵成功因素

這個案例成功的原因不是 OpenMAIC 很聰明，而是那份 60 頁文件寫得夠好。 如果來源文件本身就殘缺、過時、自相矛盾，OpenMAIC 只會把錯誤放大並包裝得很有說服力。

2.7 本章注意事項

⚠️ 注意事項 1：Garbage In, Confident Garbage Out LLM 生成的教材有一個危險特性：它會用非常有自信的口吻講錯誤的內容。學員很難分辨。因此每一份要發布的教材都必須經過領域專家覆核，這是不可省略的步驟（見第 36 章 的 Quality Gate 設計）。

⚠️ 注意事項 2：不要把 OpenMAIC 當 LMS OpenMAIC 沒有學員管理、上課紀錄、考核成績、證書、學習路徑追蹤這些 LMS 功能。官方資料未說明有任何規劃。若企業需要這些，必須另外接既有 LMS，OpenMAIC 只負責產出教材（可匯出 SCORM？官方資料未說明，實測 v1.0.1 匯出格式僅 PPTX / HTML / ZIP / MP4）。

⚠️ 注意事項 3：v1.0.0 及以下不要上正式環境 有 4 個已公開的 GHSA 漏洞。詳見第 39 章。

📌 注意事項 4：授權是 MIT，但有兩個例外 packages/mathml2omml 為 LGPL-3.0-or-later。若貴公司法遵對 LGPL 有限制（例如要求靜態連結時公開原始碼），請先讓法務確認。這個套件用於 MathML → OOXML Math 轉換，若不用 PPTX 匯出的數學公式功能，影響範圍有限。

3. 適用性評估：OpenMAIC 能做什麼、不能做什麼

3.1 為什麼需要這一章

大多數工具手冊不會有這一章，因為它們預設「你已經決定要用了」。

本手冊必須有這一章，原因是：公司對 OpenMAIC 的期待（逆向工程、Framework Upgrade、SDLC 整合）與 OpenMAIC 官方的定位（互動課堂生成）之間，存在明顯落差。

如果不先把這個落差講清楚，會發生兩種災難：

這一章的目的，就是把「確定可以」「設計後可以」「做不到」三條線劃清楚。

3.2 官方能力盤點（確定可以）

以下能力官方明文支援，可以直接規劃進導入計畫【Official】：

3.3 經設計後可以（需自建 Skill / Materials）

以下能力官方沒有內建，但可以透過「自建 Skill + 餵入正確 Materials」達成。本手冊第五部會逐一設計【建議】：

🎯 關鍵洞察：上表每一項的成功關鍵，都是「先有高品質的來源文件」。 也就是說 —— OpenMAIC 不能幫你做逆向工程，但可以把逆向工程的成果變成人人能學的課程。 逆向工程本身，該用 Claude Code / GitHub Copilot 做（見第 26 章 的完整交棒設計）。

3.4 做不到、也不該用它做的事

⚠️ 第 6 點特別容易誤會：很多人第一次看到 Materials 會以為「這就是 RAG，我把公司文件全丟進去就好」。 實際上 Session Materials 是綁在某個 Agent Session 上的教材，不是跨 Session 共享的知識庫。 想要「全公司知識庫」，架構上要在 OpenMAIC 外面做（第 34 章）。

3.5 三大企業訴求的逐項評分

針對公司提出的三大訴求，逐項評估：

訴求一：Web Application Development

總評：★★★☆☆ —— OpenMAIC 在「設計階段的知識對齊」與「維運階段的 SOP 傳承」價值最高；在「實作與測試階段」幾乎沒有直接價值。

訴求二：Legacy System Reverse Engineering

總評：★★☆☆☆（作為逆向工具）／★★★★☆（作為逆向成果的傳承載體）

flowchart LR
    subgraph CA["Coding Agent 負責（Claude Code / Copilot / Codex）"]
        direction TB
        A1["Legacy 原始碼"] --> A2["靜態分析<br/>Call Graph"]
        A2 --> A3["Business Rule<br/>萃取"]
        A3 --> A4["架構重建<br/>資料模型重建"]
        A4 --> A5["逆向工程報告<br/>Markdown / 圖表"]
    end

    subgraph OM["OpenMAIC 負責"]
        direction TB
        B1["匯入報告<br/>為 Materials"] --> B2["生成理解課程"]
        B2 --> B3["多 Agent 討論<br/>設計權衡"]
        B3 --> B4["互動測驗<br/>驗證理解"]
        B4 --> B5["匯出教材<br/>長期傳承"]
    end

    A5 ==>|"交棒<br/>Handoff"| B1

    style CA fill:#e3f2fd,stroke:#1976d2
    style OM fill:#e8f5e9,stroke:#388e3c
    style A5 fill:#fff9c4,stroke:#f9a825
    style B1 fill:#fff9c4,stroke:#f9a825

訴求三：Framework Upgrade / Modernization

總評：★★☆☆☆（作為升級工具）／★★★★☆（作為升級規範的擴散載體）

🎯 這裡有一個容易被低估的價值： 大型 Framework 升級最大的成本往往不是「改第一個模組」，而是「讓 20 個人用同一套手法改剩下 200 個模組」。 資深工程師改完第一個模組後，用 OpenMAIC 把手法做成一堂 40 分鐘的互動課（含「這樣改對不對」的測驗）， 比寫一份沒人看的 Migration Guide 有效得多。

3.6 決策樹：什麼時候該用 OpenMAIC

flowchart TD
    Start{"我有一個<br/>AI 輔助的需求"} --> Q1{"需要修改<br/>程式碼嗎？"}

    Q1 -->|是| NO1["❌ 用 Claude Code /<br/>GitHub Copilot / Codex<br/>不要用 OpenMAIC"]

    Q1 -->|否| Q2{"需要分析<br/>既有原始碼嗎？"}
    Q2 -->|是| NO2["❌ 用 Coding Agent 分析<br/>產出報告後<br/>再交給 OpenMAIC"]

    Q2 -->|否| Q3{"目的是讓「人」<br/>學會某件事嗎？"}
    Q3 -->|否| Q4{"目的是<br/>即時問答嗎？"}
    Q4 -->|是| NO3["❌ 用 ChatGPT / Claude<br/>不需要建課"]
    Q4 -->|否| NO4["❌ 重新界定需求"]

    Q3 -->|是| Q5{"有現成的<br/>來源文件嗎？"}
    Q5 -->|沒有| WARN["⚠️ 先寫文件<br/>或先用 Coding Agent<br/>產出文件"]
    WARN --> Q5

    Q5 -->|有| Q6{"要教超過<br/>3 個人 或<br/>會重複教嗎？"}
    Q6 -->|否| NO5["⚠️ 直接口頭講<br/>可能更快"]
    Q6 -->|是| YES["✅ 適合用 OpenMAIC<br/>投入產出比高"]

    style YES fill:#c8e6c9,stroke:#2e7d32,stroke-width:3px
    style NO1 fill:#ffcdd2,stroke:#c62828
    style NO2 fill:#ffcdd2,stroke:#c62828
    style NO3 fill:#ffcdd2,stroke:#c62828
    style NO4 fill:#ffcdd2,stroke:#c62828
    style NO5 fill:#fff9c4,stroke:#f9a825
    style WARN fill:#fff9c4,stroke:#f9a825

投入產出比的量化參考【建議】

📌 經驗法則：「教超過 3 個人」× 「會重複教」× 「有現成文件」= 值得建課。 三個條件缺一個就要重新評估。

3.7 本章實務案例

案例 A（成功）：eLoan 系統知識傳承

背景：eLoan 系統上線 12 年，Java 8 + Struts + Oracle，主要維護者兩位資深同仁其中一位即將退休。系統有 340 個 JSP、180 個 Action、62 支 Batch、11 個 MQ 介面。

錯誤的做法（差點做的）：把 340 個 JSP 打包上傳到 OpenMAIC，請它「分析這個系統」。

❌ 這會失敗。OpenMAIC 的 Materials 是為「教材」設計的，不是為「原始碼倉庫分析」設計的。就算它讀進去，也只會產出泛泛而談的內容。

正確的做法（實際採用）：

階段 1（Claude Code，3 週）
  → 分析 340 JSP / 180 Action / 62 Batch / 11 MQ 介面
  → 產出 8 份 Markdown 報告：
     系統總覽、模組地圖、Call Graph、業務規則清單、
     資料模型、批次排程、介面規格、已知技術債

階段 2（資深同仁，1 週）
  → 逐份覆核 8 份報告，修正 47 處錯誤與 23 處遺漏
  → 補上「為什麼當初這樣設計」的歷史脈絡（Agent 不可能知道）

階段 3（OpenMAIC，2 天）
  → 8 份報告上傳為 Materials
  → 用 curriculum-planner 規劃 5 堂課
  → 生成內容 + 人工修正
  → 加入「圓桌辯論」場景：呈現「該重寫還是該重構」的正反論點

階段 4（交付）
  → 匯出 Classroom ZIP + PPTX 放內網
  → 8 份報告本身也成為 Claude Code 的 CLAUDE.md 參考資料

成果：新接手的 3 位工程師從「完全不敢動」到「能獨立處理一般需求」，時間從預估 3 個月縮短到 5 週。

成功關鍵：沒有要求 OpenMAIC 做它做不到的事。逆向工程給 Coding Agent，知識傳承給 OpenMAIC，人做覆核與補脈絡。

案例 B（失敗）：想用它產出程式碼規範的自動檢查

背景：某團隊想「用 OpenMAIC 建立 Code Review 規範，並讓它自動檢查 PR」。

結果：前半段成功（產出了很好的 Code Review 教學課），後半段完全失敗（OpenMAIC 無法接 GitHub webhook、無法讀 PR、無法留言）。

教訓：需求裡有「自動檢查 PR」這種動作類需求時，就該立刻警覺——OpenMAIC 是內容生成平台，不是流程自動化平台。後半段最終用 GitHub Actions + Claude Code 實作。

3.8 本章注意事項

⚠️ 注意事項 1：「上傳原始碼」是最常見的誤用 Materials 支援上傳檔案，所以很多人第一個念頭就是「把整個 repo 壓縮上傳」。這在技術上做得到，但效果很差，而且有原始碼外洩風險（如果你用的是雲端 LLM Provider）。正確做法見第 26 章。

⚠️ 注意事項 2：原始碼外洩風險必須事前評估 只要你上傳的內容會送到 Provider，就等於把內容交給該 Provider。企業導入前必須先決定：

• 敏感原始碼 → 一律只能走本地模型（Ollama / Lemonade）或公司自建 Gateway
• 或者：只上傳「已經去識別化、抽象化的分析報告」，不上傳原始碼本身（本手冊推薦）

詳見第 39.4 節。

📌 注意事項 3：這一章要定期重讀 OpenMAIC 版本演進很快（半年內從 v0.1.0 到 v1.0.1）。今天「做不到」的事，半年後可能就內建了。建議每次升級後回頭覆核 3.2 – 3.4 節的三張表。

4. OpenMAIC 與其他 AI 工具的比較

4.1 定位總表

一眼看懂的差異：

ChatGPT / Claude / Gemini   →  產出「答案」
GitHub Copilot              →  產出「程式碼片段」
Claude Code / Codex         →  產出「修改後的專案」
OpenMAIC                    →  產出「一堂會講課的課程」

4.2 與 ChatGPT / Claude / Gemini 的差異

何時該用哪一個

「Spring Boot 3 的 @ConfigurationProperties 怎麼用？」
  → ChatGPT / Claude（30 秒得到答案）

「幫我看這個 NullPointerException」
  → Claude / Copilot（貼 stack trace）

「我們公司的訂單系統架構，怎麼讓新人在 3 天內搞懂？」
  → OpenMAIC（值得投入時間建課）

「把這 200 個 Controller 從 javax 改成 jakarta」
  → Claude Code / Codex / OpenRewrite（絕對不是 OpenMAIC）

4.3 與 GitHub Copilot / Claude Code / Codex 的差異

這三個是 Coding Agent，與 OpenMAIC 的關係不是競爭，而是上下游。

flowchart TD
    K["企業知識資產<br/>架構文件 / 規範 / 逆向報告"]

    K --> OM["OpenMAIC<br/>知識工程層"]

    OM --> OUT1["互動課程<br/>（給人學）"]
    OM --> OUT2["結構化教材<br/>（給 Agent 讀）"]

    OUT1 --> H["工程師<br/>建立心智模型"]
    OUT2 --> CTX["Agent Context<br/>CLAUDE.md / instructions"]

    H --> CODE
    CTX --> CODE

    CODE["Coding Agent 層<br/>Claude Code / Copilot / Codex"]

    CODE --> R1["Web App 開發"]
    CODE --> R2["Legacy 重構"]
    CODE --> R3["Framework 升級"]

    R1 --> FB["實作回饋"]
    R2 --> FB
    R3 --> FB
    FB -.->|"更新知識"| K

    style OM fill:#e8f5e9,stroke:#388e3c,stroke-width:3px
    style CODE fill:#e3f2fd,stroke:#1976d2,stroke-width:3px
    style K fill:#fff3e0,stroke:#f57c00
    style FB fill:#fce4ec,stroke:#c2185b

逐項對照

（✅ 支援　△ 部分支援 / 需變通　❌ 不支援　【Exp】實驗性）

4.4 為什麼不該把 OpenMAIC 當成另一個 Chatbot

這是本手冊要對抗的最主要誤解。

症狀：導入後，同仁把它當成「另一個可以問問題的 AI」，用 Pro Workbench 的聊天框問「Spring Boot 怎麼設定連線池」。

為什麼這是浪費：

正確的使用門檻【建議】：

在企業內部推廣時，明確公告以下規則：

✅ 用 OpenMAIC：
   - 產出要給 3 人以上看的教材
   - 需要投影片 / 語音 / 測驗 / 互動的內容
   - 知識要長期保存與重複使用

❌ 不要用 OpenMAIC：
   - 「我想問一個問題」        → 用 ChatGPT / Claude
   - 「幫我寫一段程式」        → 用 Copilot / Claude Code
   - 「幫我改這個檔案」        → 用 Claude Code / Codex
   - 「幫我查一下這個 API」    → 用 IDE / 官方文件

4.5 能力矩陣（15 項能力 × 7 個工具）

（✅✅✅ 核心強項　✅✅ 良好　✅ 可用　△ 勉強 / 需變通　❌ 不支援）

🎯 從矩陣可以看出 OpenMAIC 的三個獨佔強項： 第 8 項（多 Agent 演出）、第 12 項（離線播放）、第 13 項（自架 + 資料不出境）。 這三項對金融、政府、國防等內網環境的企業內訓特別關鍵——這也是它在企業中最不可替代的位置。

4.6 本章實務案例

案例：一個需求，四個工具接力

需求：「我們要把 Payment 模組從 Spring Boot 2.7 升到 3.2，並且讓全隊 15 個人都會這個手法。」

為什麼要四個工具：因為它們的能力邊界不同。硬要用一個工具做完，一定會在某個環節碰壁。

OpenMAIC 在這裡的不可替代性：第 4 階段。如果沒有這一步，第 5 階段的 14 個人會各改各的，產生 14 種風格，最後 code review 成本爆炸。

4.7 本章注意事項

⚠️ 注意事項 1：不要為了「統一工具」而勉強 有些管理者會希望「全公司只用一套 AI 工具」以簡化採購與治理。這在 AI 工具上行不通——它們的能力邊界差異太大。正確的治理方式是明確定義每個工具的使用場景（見第 49 章），而不是強行收斂。

⚠️ 注意事項 2：能力矩陣會過時 上表是 2026-09-13 的狀態。AI 工具的能力邊界移動極快。建議每半年重新評估一次，特別是第 4、5、6、11 項。

📌 注意事項 3：成本結構完全不同 Copilot 是「每人每月訂閱」，Claude Code 是「按 token」，OpenMAIC 自架是「你自己的 Provider token 成本 + 伺服器成本」。做預算時不能用同一套算法。詳見第 44 章。

5. OpenMAIC 與傳統教育平台的比較

5.1 LMS / 錄影教學 / 文件 / Chatbot / RAG 的侷限

企業「知識傳遞」的手段，過去有五種，各有侷限：

共同的根本問題：

文件 / 影片 → 靜態，改不動
Chatbot / RAG → 被動，不知道要問什麼
LMS → 只是殼，內容還是要人做

5.2 OpenMAIC 的差異點：內容是「生成」的，不是「錄」的

graph TB
    subgraph TRAD["傳統做法"]
        T1["企業知識<br/>（在資深同仁腦中）"] -->|"人工，數十小時"| T2["文件 / 投影片"]
        T2 -->|"人工，數十小時"| T3["錄影 / 面授"]
        T3 --> T4["學員"]
        T2 -.->|"知識更新"| X1["❌ 教材過時<br/>重做成本極高"]
    end

    subgraph MAIC["OpenMAIC 做法"]
        M1["企業知識<br/>（結構化文件）"] -->|"上傳為 Materials"| M2["OpenMAIC<br/>生成引擎"]
        M2 -->|"分鐘級"| M3["互動課程"]
        M3 --> M4["學員<br/>（可提問、可測驗）"]
        M1 -.->|"知識更新"| M5["✅ 重新生成<br/>成本 = 一次生成"]
        M5 --> M2
    end

    style TRAD fill:#fafafa,stroke:#999
    style MAIC fill:#e8f5e9,stroke:#388e3c
    style X1 fill:#ffcdd2,stroke:#c62828
    style M5 fill:#c8e6c9,stroke:#2e7d32

七項對照

📌 第 7 項很重要：OpenMAIC 不能取代 LMS。 正確的企業架構是：OpenMAIC 產出教材 → 匯出 → 放進既有 LMS 做學員管理。兩者互補而非取代。

5.3 企業知識載體的演進路徑

flowchart LR
    G1["第一代<br/>紙本 SOP"] --> G2["第二代<br/>Wiki / Confluence"]
    G2 --> G3["第三代<br/>錄影 + LMS"]
    G3 --> G4["第四代<br/>Chatbot / RAG"]
    G4 --> G5["第五代<br/>生成式互動課堂<br/>OpenMAIC"]

    G1 -.- L1["靜態<br/>難更新"]
    G2 -.- L2["易更新<br/>但沒人看"]
    G3 -.- L3["有人看<br/>但改不動"]
    G4 -.- L4["能問答<br/>但無結構"]
    G5 -.- L5["✅ 易更新<br/>✅ 有結構<br/>✅ 能互動"]

    style G5 fill:#c8e6c9,stroke:#2e7d32,stroke-width:3px
    style L5 fill:#e8f5e9,stroke:#388e3c

企業實際上會是「多代並存」【建議】

不要期待用第五代取代前四代。實務上的合理配置是：

graph TB
    SSOT["企業知識<br/>單一真相來源<br/>（Git / Confluence）"]

    SSOT --> A["RAG 索引<br/>→ 即時查詢"]
    SSOT --> B["OpenMAIC<br/>→ 系統性學習"]
    SSOT --> C["Coding Agent Context<br/>→ AI 開發輔助"]
    SSOT --> D["正式文件<br/>→ 稽核與簽核"]

    B --> B1["匯出教材"]
    B1 --> LMS["既有 LMS<br/>學員管理 / 證書"]

    style SSOT fill:#fff3e0,stroke:#f57c00,stroke-width:3px
    style B fill:#e8f5e9,stroke:#388e3c,stroke-width:2px

🎯 這張圖是本手冊建議的企業知識架構總綱。 核心觀念：維護一份 SSOT，衍生出四種消費形式。OpenMAIC 是其中一種消費形式，不是 SSOT 本身。 第 38 章 會展開完整的導入架構。

5.4 本章實務案例

案例：從「三份不同步的教材」到「一個來源、三種輸出」

背景：某團隊的「訂單服務」有三份說明資料：

1. Confluence 上的《訂單服務設計說明》（2024 年寫的，之後改過 2 次）
2. 2025 年新人訓練的錄影（1.5 小時，內容已與現況不符）
3. 資深同仁自己的一份 PPT（最準，但只有他有）

問題：新人不知道該看哪一份；三份說法有衝突；沒人有動力更新。

改造做法：

Step 1  合併三份資料 → 一份權威 Markdown 文件，放進 Git（成為 SSOT）
        由資深同仁 + Claude Code 協作完成，2 天

Step 2  設定同步：
        - Git 文件 → RAG 索引（同仁可即時查詢）
        - Git 文件 → OpenMAIC Materials（生成互動課）
        - Git 文件 → CLAUDE.md 參考（Coding Agent 可讀）

Step 3  淘汰：
        - Confluence 頁面改成「已遷移，請見 Git」+ 連結
        - 錄影下架
        - 個人 PPT 併入 SSOT

成果：

5.5 本章注意事項

⚠️ 注意事項 1：SSOT 沒建立好，導入 OpenMAIC 只會製造更多不同步的教材 如果你現在就有三份互相衝突的文件，直接導入 OpenMAIC 只會變成「四份互相衝突的資料」。先整理 SSOT，再導入。這是第 50 章 Phase 0 的核心工作。

⚠️ 注意事項 2：不要下架所有舊教材 生成式教材有它的弱點（可能出現細微錯誤、風格不穩定）。建議至少保留 6 個月的過渡期，讓兩者並存，收集回饋後再決定是否淘汰舊教材。

📌 注意事項 3：OpenMAIC 不做學員管理，這不是缺陷 有些人會抱怨「連上課紀錄都沒有」。這是設計取捨：OpenMAIC 專注在內容生成，把管理留給既有 LMS。強行要求它做 LMS 的事，只會得到一個兩邊都做不好的系統。

6. 系統架構總覽【Official】

6.1 五層架構模型

What

OpenMAIC 的架構可以拆成五層。以下架構圖是依照官方 Repository 實際的目錄結構與 README 說明重新分析繪製，不是照抄任何現成圖表。

graph TB
    subgraph L1["① 使用者介面層　app/ + components/"]
        UI1["Classic Generator<br/>一鍵生成"]
        UI2["Pro Workbench<br/>【Experimental】"]
        UI3["Classroom<br/>課堂播放"]
        UI4["MAIC Editor<br/>【Experimental】"]
    end

    subgraph L2["② API 層　app/api/"]
        API1["/api/generate<br/>場景生成"]
        API2["/api/stages<br/>課程讀寫"]
        API3["/api/agent<br/>Session/Event/<br/>Material/Skill"]
        API4["/api/persistence<br/>內嵌儲存端點"]
        API5["/api/classroom<br/>課堂持久化"]
    end

    subgraph L3["③ 核心邏輯層　lib/"]
        C1["generation/<br/>兩階段管線"]
        C2["orchestration/<br/>LangGraph 狀態機"]
        C3["playback/<br/>播放狀態機"]
        C4["action/<br/>28+ Action 型別"]
        C5["server/agent-runtime/<br/>持久化 Agent"]
        C6["export/<br/>PPTX / HTML 匯出"]
        C7["ai/<br/>LLM Provider 抽象"]
    end

    subgraph L4["④ 契約與套件層　packages/"]
        P1["@openmaic/dsl<br/>課件資料契約"]
        P2["@openmaic/renderer<br/>React 渲染器"]
        P3["@openmaic/editor<br/>編輯核心"]
        P4["@openmaic/importer<br/>PPTX 匯入"]
        P5["@openmaic/generation<br/>管線契約"]
        P6["@openmaic/storage<br/>持久化原語"]
    end

    subgraph L5["⑤ 外部資源層"]
        E1["Model Providers<br/>OpenAI / Anthropic /<br/>Gemini / Ollama…"]
        E2["PostgreSQL 16<br/>（選用）"]
        E3["Object Storage<br/>S3（選用）"]
        E4["render-service<br/>Chromium + FFmpeg"]
        E5["Media Providers<br/>TTS / ASR / Image /<br/>Video / Search / PDF"]
    end

    L1 --> L2
    L2 --> L3
    L3 --> L4
    L3 --> L5
    L4 -.->|"型別契約"| L1

    style L1 fill:#e3f2fd,stroke:#1976d2
    style L2 fill:#f3e5f5,stroke:#7b1fa2
    style L3 fill:#e8f5e9,stroke:#388e3c
    style L4 fill:#fff3e0,stroke:#f57c00
    style L5 fill:#fce4ec,stroke:#c2185b

6.2 各層的責任邊界

📌 這個分層的一個重要設計決策：packages/@openmaic/* 是獨立發布的 SDK（v0.3.0 起）。 這代表你可以在不啟動 OpenMAIC 本體的情況下，用 @openmaic/dsl 驗證課件、用 @openmaic/renderer 渲染課件。 這對企業把 OpenMAIC 課件嵌進自家系統很有價值——見第 9.5 節。

6.3 執行時的三條主要資料流

流程 A：Classic Generator（一鍵生成）

sequenceDiagram
    autonumber
    participant U as 使用者
    participant UI as Web UI
    participant API as /api/generate
    participant GEN as lib/generation
    participant AI as lib/ai
    participant M as Model Provider
    participant ST as Storage

    U->>UI: 輸入主題 / 上傳文件
    UI->>API: POST 生成請求
    API->>GEN: 啟動兩階段管線

    rect rgb(232, 245, 233)
    Note over GEN,M: 階段一：Outline
    GEN->>AI: 產生課程大綱
    AI->>M: LLM 呼叫
    M-->>AI: 大綱 JSON
    AI-->>GEN: 大綱
    end

    GEN->>ST: 儲存大綱
    GEN-->>UI: 串流回傳大綱
    UI-->>U: 顯示大綱（可編輯）

    rect rgb(227, 242, 253)
    Note over GEN,M: 階段二：Scene Content
    loop 每個 Scene（可平行，PARALLEL_SCENE_CONCURRENCY）
        GEN->>AI: 產生場景內容
        AI->>M: LLM 呼叫
        M-->>AI: 投影片 + 講稿 + 互動
        AI-->>GEN: Scene DSL
        GEN->>ST: 儲存 Scene
        GEN-->>UI: 串流回傳
    end
    end

    UI-->>U: 課程完成，可進入 Classroom

📌 為什麼要分兩階段：如果一次生成完整課程，一旦大綱方向錯了，全部內容都白做。分兩階段讓使用者可以在大綱階段就介入修正，大幅降低重做成本。這是第 17 章 的核心。

流程 B：Classroom 播放

sequenceDiagram
    autonumber
    participant U as 學員
    participant CR as Classroom UI
    participant PB as lib/playback<br/>狀態機
    participant OR as lib/orchestration<br/>LangGraph
    participant ACT as lib/action<br/>28+ 型別
    participant TTS as TTS Provider
    participant M as Model Provider

    U->>CR: 進入課堂
    CR->>PB: 初始化播放狀態機
    PB->>ACT: 取得下一批 Action

    loop 課堂進行
        ACT->>TTS: 產生語音
        TTS-->>ACT: 音訊
        ACT-->>CR: speak / draw / highlight / effect
        CR-->>U: 播放（投影片 + 語音 + 動畫）
    end

    U->>CR: 舉手提問
    CR->>OR: 觸發互動節點
    OR->>M: 老師 Agent 生成回答
    M-->>OR: 回答內容
    OR->>ACT: 轉為 Action
    ACT-->>CR: 播放回答（含白板繪製）
    CR-->>U: 顯示

    Note over OR: 也可由 Agent 主動發起<br/>討論 / 辯論

流程 C：Pro Workbench + Agent Runtime【Experimental】

sequenceDiagram
    autonumber
    participant U as 使用者
    participant WB as Pro Workbench
    participant API as /api/agent
    participant RT as Agent Runtime<br/>lib/server/agent-runtime
    participant DB as PostgreSQL
    participant TOOL as Agent Tools
    participant M as Model Provider

    U->>WB: 輸入需求（對話）
    WB->>API: 建立 / 續接 Session
    API->>RT: enqueue
    RT->>DB: 建立 session 記錄

    Note over RT,DB: Worker 以 lease 取得任務<br/>並定期 heartbeat

    loop Agent Loop
        RT->>M: 送出對話 + 工具定義
        M-->>RT: 工具呼叫決策
        RT->>TOOL: 執行工具<br/>(course/dsl/material/<br/>generation/skill…)
        TOOL->>DB: 讀寫課件與素材
        TOOL-->>RT: 工具結果
        RT->>DB: 寫入 event
        RT-->>WB: 串流 event
        WB-->>U: 即時顯示進度與課程
    end

    alt 使用者中途導向
        U->>WB: 輸入新指示（steer）
        WB->>API: 送入 steering 訊息
        API->>DB: 寫入待處理訊息
        RT->>DB: 下一輪讀取並納入
    end

    alt 程序重啟 / 崩潰
        Note over RT,DB: lease 逾期後<br/>其他 worker 接手 resume
        RT->>DB: 讀取既有 event 重播狀態
        RT->>M: 從中斷處續作
    end

⚠️ 此流程中的 lease / heartbeat / resume 機制，是本手冊依據 .env.example 中實際存在的設定鍵 （OPENMAIC_AGENT_RUNTIME_LEASE_TTL_MS、_HEARTBEAT_MS、_SCAN_INTERVAL_MS、_MAX_ATTEMPTS） 與 lib/server/agent-runtime/ 目錄中的檔案名稱（runner.ts、store.ts、resume.ts、mutation-fence.ts）推導。 內部實作細節官方資料未說明，第 20 章 會標明哪些是官方明文、哪些是推導。

6.4 部署形態的三種樣貌

同一套程式碼，依環境變數不同，會呈現三種完全不同的架構樣貌：

形態一：純瀏覽器模式（預設）

graph LR
    B["瀏覽器<br/>（課件存 localStorage /<br/>IndexedDB）"] <--> APP["OpenMAIC<br/>Next.js Server"]
    APP <--> M["Model Provider"]

    style B fill:#e3f2fd,stroke:#1976d2
    style APP fill:#e8f5e9,stroke:#388e3c

• 設定：什麼都不用設（除了一組 API Key）
• 特性：課件存在瀏覽器，換裝置就看不到、清快取就消失
• 適用：個人試用、PoC

形態二：伺服端持久化模式

graph LR
    B["瀏覽器"] <--> APP["OpenMAIC<br/>Next.js Server"]
    APP <--> PG[("PostgreSQL 16")]
    APP <--> S3["S3 物件儲存<br/>（選用）"]
    APP <--> M["Model Provider"]

    style PG fill:#fff3e0,stroke:#f57c00
    style APP fill:#e8f5e9,stroke:#388e3c

• 設定：NEXT_PUBLIC_PERSISTENCE=1 + DATABASE_URL
• 特性：課件存 DB，可跨裝置、可多人
• 適用：團隊共用

形態三：完整企業模式【建議】

graph TB
    U["企業員工"] --> SSO["SSO / IdP"]
    SSO --> RP["Reverse Proxy<br/>Nginx / Traefik<br/>（認證、限流、稽核）"]
    RP --> APP1["OpenMAIC 實例 1"]
    RP --> APP2["OpenMAIC 實例 2"]

    APP1 --> PG[("PostgreSQL HA<br/>Primary + Replica")]
    APP2 --> PG
    APP1 --> S3["物件儲存 S3"]
    APP2 --> S3
    APP1 --> RS["render-service<br/>（隔離網段）"]
    APP2 --> RS

    APP1 --> GW["企業 Model Gateway<br/>（金鑰集中、成本歸戶、<br/>內容過濾、稽核）"]
    APP2 --> GW
    GW --> P1["OpenAI"]
    GW --> P2["Anthropic"]
    GW --> P3["內部 Ollama"]

    style RP fill:#f3e5f5,stroke:#7b1fa2
    style GW fill:#fff3e0,stroke:#f57c00,stroke-width:3px
    style PG fill:#e1f5fe,stroke:#0277bd
    style RS fill:#fce4ec,stroke:#c2185b

• 設定：形態二 + Reverse Proxy + SSO + Model Gateway（OpenMAIC 本身不提供 SSO 與 RBAC，必須外掛）
• 適用：正式企業導入 —— 完整說明見第 38 章 與第 42 章

6.5 本章實務案例

案例：一個部署決策的推導過程

背景：某團隊 15 人，要導入 OpenMAIC 給整個部門（約 80 人）使用，資料含 Legacy 系統架構文件（敏感但非個資）。

決策過程：

最終架構：形態三，但 Pro Workbench 走獨立的 URL path 由 Nginx 依群組限制存取。

這個案例的關鍵：先問「資料能不能出境」，再問「幾個人用」，最後才問「要開哪些功能」。順序反了會重做。

6.6 本章注意事項

⚠️ 注意事項 1：ACCESS_CODE 不是身分認證 .env.example 中的 ACCESS_CODE 是單一共用密碼，不是帳號系統。它擋得住路過的人，擋不住內部濫用，也無法做到「誰做了什麼」的稽核。企業導入必須在前面加 Reverse Proxy + SSO。

⚠️ 注意事項 2：架構圖中的 lib/server/agent-runtime 內部行為多屬推導 本章流程 C 的 lease / heartbeat / resume 序列圖，是依據實際存在的環境變數與檔案名稱合理推導。若你要據此做關鍵設計決策，請自行閱讀原始碼確認。

📌 注意事項 3：render-service 需要 NET_ADMIN 權限 官方 docker-compose.yml 中 render-service 需要 NET_ADMIN capability（用於 iptables 出站封鎖）並限制 8GB 記憶體，且放在獨立的 render network。這是刻意的安全隔離設計——它會執行生成的 HTML，等於執行不受信任的程式碼。在 Kubernetes 上部署時必須保留等價的隔離（見第 42.4 節）。

7. 原始碼架構解析【Official】

7.1 Repository 頂層結構

以下為 main 分支實際的頂層目錄與檔案（2026-09-13 查證）：

OpenMAIC/
├── .codegraph/          程式碼圖譜資料
├── .github/             GitHub workflows 與設定
├── app/                 Next.js App Router（頁面 + API）
├── assets/              靜態資產
├── community/           社群相關資源
├── components/          React UI 元件
├── configs/             共用常數設定
├── e2e/                 端對端測試
├── eval/                評測
├── lib/                 核心業務邏輯 ★
├── packages/            Workspace 套件（@openmaic/*）★
├── public/              公開靜態檔
├── render-service/      MP4 匯出服務（獨立容器）
├── scripts/             建置與維運腳本
├── skills/              Skill 套件 ★
├── tests/               測試
├── types/               型別定義
│
├── .env.example         環境變數範本 ★★★
├── .nvmrc               Node 版本鎖定
├── CHANGELOG.md         變更記錄 ★
├── CONTRIBUTING.md      貢獻指引
├── Dockerfile           容器映像定義
├── docker-compose.yml   容器編排 ★
├── LICENSE              MIT
├── README.md            英文說明 ★
├── README-zh.md         中文說明 ★
├── SECURITY.md          安全政策
├── instrumentation.ts   Next.js 儀表化
├── middleware.ts        Next.js 中介層
├── next.config.ts       Next.js 設定
├── package.json         套件定義
├── playwright.config.ts E2E 設定
├── pnpm-workspace.yaml  Monorepo 定義
├── vercel.json          Vercel 部署設定
└── vitest.config.ts     單元測試設定

（★ = 企業導入時最需要關注的檔案）

📌 注意：Repository 沒有 docs/ 目錄（已驗證回傳 404）。 所有官方說明集中在 README.md、README-zh.md 與 .env.example 的行內註解。 這代表很多細節必須讀原始碼，也代表升級時要特別注意 CHANGELOG.md。

7.2 app/ —— Next.js App Router

app/
├── api/                          API 路由
│   ├── agent/                    Agent 控制平面
│   │                             （Session / Event / Material / Skill）
│   ├── stages/                   課程讀寫、Scene 擷取
│   ├── generate/                 場景生成管線
│   ├── persistence/              內嵌儲存 HTTP 端點
│   └── classroom/                課堂持久化
│                                 （v1.0.1 起驗證 DSL、stage id 限 [A-Za-z0-9_-]）
└── classroom/[id]/               課堂播放頁面

7.3 lib/ —— 核心業務邏輯

這是整個專案的重心。

lib/server/agent-runtime/ 的檔案清單（實際查證）

這個目錄是 Pro Workbench 的引擎。以下為 main 分支實際檔案，依責任分組：

⚠️ 上表的「責任」欄位是依檔名推測，官方沒有逐檔說明文件。 對企業有實質意義的觀察是：fetch-url.ts / web-search.ts / session-urls.ts 這組是安全審查的重點——它們是 OpenMAIC 對外發出請求的地方，也是 GHSA-9m7h-vh2h-rc3w（SSRF）與 GHSA-725p-44hx-v52c（redirect）的相關區域。

7.4 packages/ —— Workspace 套件

v0.3.0 起以 @openmaic/* 名義發布為 SDK。

graph TB
    DSL["@openmaic/dsl<br/>課件資料契約<br/>（版本化 + 驗證器）"]

    DSL --> REN["@openmaic/renderer<br/>React 渲染器"]
    DSL --> EDT["@openmaic/editor<br/>可組合的<br/>投影片編輯核心"]
    DSL --> IMP["@openmaic/importer<br/>PPTX → OpenMAIC"]
    DSL --> GEN["@openmaic/generation<br/>管線契約"]

    STO["@openmaic/storage<br/>持久化抽象<br/>（document / runtime /<br/>asset / agent-session）"]

    REN --> APP["OpenMAIC 本體"]
    EDT --> APP
    IMP --> APP
    GEN --> APP
    STO --> APP

    style DSL fill:#fff3e0,stroke:#f57c00,stroke-width:3px
    style STO fill:#e1f5fe,stroke:#0277bd,stroke-width:2px

🎯 @openmaic/storage 的「可插拔」設計對企業非常關鍵： 它定義了 document / runtime / asset / agent-session 四類 store 的抽象與 HTTP 契約。 理論上企業可以實作自己的 store（例如接內部的物件儲存或資料庫），而不必改 OpenMAIC 本體。 但官方沒有提供自訂 store 的教學文件，實作前需自行閱讀套件原始碼。

7.5 skills/ —— Skill 套件

skills/
├── agent-runtime/       ← 23 個內建 Skill（Agent Workbench 使用）
└── openmaic/            ← OpenClaw 標準 SKILL.md 套件

兩者用途完全不同：

skills/openmaic/ 的安裝方式【Official】：

clawhub install openmaic

安裝後可從 Feishu、Slack、Discord、Telegram、WhatsApp 等通訊軟體直接產生與檢視課堂，不用碰終端機。它支援兩種模式：

• Hosted 模式：用 open.maic.chat 的 access code，不用自架
• Self-hosted 模式：引導你 clone、設定、在本機執行

⚠️ 企業使用 Hosted 模式前必須先評估：這代表你的教材內容會送到官方託管服務。 敏感內容請一律使用 Self-hosted 模式。詳見第 39.4 節。

7.6 render-service/ —— 獨立的影片匯出服務

⚠️ 這個服務是整套架構中風險最高的元件：它用 Chromium 執行由 LLM 生成的 HTML。 官方已經做了三層防護（獨立容器、隔離網段、iptables 出站封鎖）。 企業部署時絕對不能為了方便而拿掉這些隔離。

7.7 從架構推導的企業風險點

7.8 本章實務案例

案例：資安部門的原始碼審查清單

某企業資安部門要求「導入任何開源 AI 工具前，須完成原始碼架構審查」。以下是他們針對 OpenMAIC 實際採用的審查路徑：

Step 1  盤點對外連線點（1 天）
        grep -rn "fetch(" lib/ app/ --include=*.ts
        重點檔案：
          lib/server/agent-runtime/fetch-url.ts
          lib/server/agent-runtime/web-search.ts
          lib/server/agent-runtime/session-urls.ts
          lib/ai/（各 Provider client）
        產出：對外連線清單 + 是否經過 URL guard

Step 2  盤點檔案寫入點（0.5 天）
        重點：app/api/classroom（GHSA-p2wh-m28m-c5xw 修補處）
              lib/persistence/
        產出：確認 path traversal 防護是否在 write 端也存在

Step 3  盤點 HTML 渲染點（1 天）
        重點：components/scene-renderers/
              packages/renderer/
        產出：確認 sanitization 邊界（v1.0.1 已移到 persistence boundary）

Step 4  盤點認證機制（0.5 天）
        重點：middleware.ts
              ACCESS_CODE 與 PERSISTENCE_DEV_TOKEN 的使用處
        產出：確認「必須外掛 SSO」的結論

Step 5  依賴套件掃描（0.5 天）
        pnpm audit
        產出：CVE 清單

Step 6  容器隔離驗證（0.5 天）
        審查 docker-compose.yml 的 profiles / networks / cap_add
        產出：K8s 上的等價隔離設計要求

審查結論（該企業的實際結論）：

「條件通過。必要條件：(1) 版本 ≥ v1.0.1；(2) 前置 SSO Reverse Proxy；(3) render-service 網路隔離不得移除；(4) 自建 audit log；(5) 敏感內容僅限內部 Model Gateway。」

7.9 本章注意事項

⚠️ 注意事項 1：lib/ 底下的檔案責任是推測，不是官方文件 本章 7.3 節的表格是依據檔名與目錄結構推導。做關鍵決策前請自行讀原始碼。

⚠️ 注意事項 2：Monorepo 結構代表升級是「整包」的 OpenMAIC 是 pnpm workspace monorepo，packages/@openmaic/* 與本體版本綁定。 你不能只升級某一個 package。升級一律是整個 repo 的事。見第 46 章。

📌 注意事項 3：.codegraph/ 目錄的存在很有意思 Repo 頂層有 .codegraph/ 目錄，暗示官方自己也用程式碼圖譜工具在管理這個專案。 企業做逆向工程時可參考類似做法（本目錄另有《codegraph教學手冊》）。

8. 技術棧與版本查證【Official】

8.1 完整技術棧

以下為 v1.0.1 的實際技術棧（依 README 與 package.json 實際查證）：

packageManager 欄位會釘死 pnpm 版本【Official】

package.json 的 packageManager 不是寫 pnpm@10，而是帶 SHA-512 完整性雜湊的精確版本：

"packageManager": "pnpm@10.28.0+sha512.05df71d1421f21399e053fde567cea34d446fa02c76571441bfc1c7956e98e363088982d940465fd34480d4d90a0668bc12362f8aa88000a64e83d0b0e47be48"

這對企業有三個實際後果：

📌 手冊第 11 章 的前置檢查只驗 pnpm --version >= 10，那是最低門檻； 若要完全重現官方建置結果，應對齊 10.28.0。

8.2 版本需求的硬性檢查

# 執行前務必確認
node --version    # 必須 >= v22.19.0
pnpm --version    # 必須 >= 10.0.0
docker --version  # 若用容器部署
psql --version    # 若用伺服端持久化，建議 16

Repo 有 .nvmrc，建議直接：

nvm use           # 讀取 .nvmrc
# 或
fnm use

⚠️ v1.0.1 最容易踩的坑就是 Node 版本。 從 v1.0.0（Node 20.9）升到 v1.0.1（Node 22.19）時，如果 CI/CD 的 base image 沒同步更新， 會在 pnpm install 階段就失敗。升級檢查清單見第 46.2 節。

8.3 為什麼是這些技術（企業視角的評估）

⚠️ 兩個明顯的企業級缺口：

1. 沒有官方 Helm chart / K8s manifest —— 要上 K8s 得自己寫（第 42.4 節 提供範本）
2. 沒有官方 DB schema 文件與 migration 說明 —— 備份/還原/升級的 DB 處理需自行摸索（第 10 章 說明已知資訊）

8.4 依賴的外部服務分類

OpenMAIC 依賴的外部服務可分成六類，每類都是「可選 + 可替換」：

graph LR
    OM["OpenMAIC"]

    OM --> LLM["① LLM<br/>19+ Providers<br/>【至少要一個】"]
    OM --> TTS["② TTS 語音合成<br/>OpenAI / Azure / GLM /<br/>Qwen / Doubao / MiniMax /<br/>ElevenLabs / VoxCPM / Lemonade"]
    OM --> ASR["③ ASR 語音辨識<br/>OpenAI / Qwen / Azure /<br/>FunASR / Lemonade"]
    OM --> IMG["④ 圖片生成<br/>OpenAI / Seedream /<br/>Qwen / Nano Banana /<br/>MiniMax / Grok / Lemonade"]
    OM --> VID["⑤ 影片生成<br/>Seedance / Kling / Veo /<br/>Sora / MiniMax / Grok /<br/>HappyHorse"]
    OM --> SRCH["⑥ 網頁搜尋<br/>Tavily / Exa / Bocha /<br/>Brave / Baidu / SearXNG /<br/>MiniMax / Doubao / Claude"]
    OM --> PDF["⑦ PDF 解析<br/>unpdf / MinerU /<br/>AliDocMind"]

    style LLM fill:#ffcdd2,stroke:#c62828,stroke-width:3px
    style OM fill:#e8f5e9,stroke:#388e3c,stroke-width:3px

只有第 ① 類（LLM）是必要的，其餘全部可選。這代表你可以：

• 最小啟動：只設一組 ANTHROPIC_API_KEY，其他都不設 → 有課程、無語音、無圖片
• 完全離線：LLM 用 Ollama、TTS 用 VoxCPM、ASR 用 FunASR、圖片用 Lemonade、搜尋用自架 SearXNG → 全部在內網

🎯 「完全離線」這個組合對高度管制產業（金融、國防、醫療）是決定性的。 據本手冊查證，.env.example 中確實同時存在 OLLAMA_BASE_URL、TTS_VOXCPM_BASE_URL、 ASR_FUNASR_BASE_URL、IMAGE_LEMONADE_BASE_URL、SEARXNG_BASE_URL， 理論上可組成完全內網的配置。但官方未提供此組合的完整驗證說明，導入前務必自行 PoC。

8.5 技術棧對企業技能的要求

📌 對以 Java 為主的企業團隊，這是一個真實的成本： OpenMAIC 是純 TypeScript / Node 專案。當它出問題而官方沒有文件時， 你需要有人能讀 TypeScript 原始碼。導入前請確認團隊有這個能力，或接受「遇到問題只能等上游修」。

8.6 本章實務案例

案例：Java 團隊導入時的技能補位

背景：某銀行核心團隊 20 人，18 個 Java、2 個前端（Vue）。要導入 OpenMAIC。

遇到的問題：

1. 第一週：pnpm install 失敗（Node 版本 18）→ 30 分鐘解決
2. 第二週：想改登入頁加公司 Logo → 沒人會 Next.js App Router → 卡兩天
3. 第三週：Agent Session 卡住不動 → 沒人能讀 lib/server/agent-runtime/ → 只能重啟
4. 第五週：想接內部 MinIO → ASSET_S3_BUCKET 設定不明 → 摸索三天

採取的補位措施：

🎯 最後一項值得強調：用 Coding Agent 來讀你不熟悉語言的開源專案原始碼， 是目前最有效的「技能補位」手段。這也呼應本手冊第 32 章 的協作設計。

8.7 本章注意事項

⚠️ 注意事項 1：不要客製 OpenMAIC 本體 一旦你 fork 並修改原始碼，未來每次升級都要處理 merge conflict，而 OpenMAIC 的演進速度很快（半年 10 個版本）。強烈建議：能用環境變數解決的就用環境變數，不要改 code。真的需要客製，優先考慮用 @openmaic/* SDK 在外部組合，而不是改本體。

⚠️ 注意事項 2：Next.js NEXT_PUBLIC_* 是 build-time 變數 所有 NEXT_PUBLIC_ 開頭的變數會在建置時被編譯進前端 bundle。改了之後必須重新 build，只重啟服務沒有用。這是第 47 章 最常見的錯誤之一。

📌 注意事項 3：LangGraph 1.1 的升級連動 lib/orchestration/ 依賴 LangGraph 1.1。若 LangGraph 有重大變更，OpenMAIC 的多 Agent 行為可能改變。升級 OpenMAIC 時建議一併確認 CHANGELOG.md 是否提及 LangGraph 版本異動。

9. DSL、Renderer 與 Editor【Official】

9.1 為什麼要有 DSL

What

@openmaic/dsl 是 OpenMAIC 的版本化課件資料契約（versioned course/slide data contract），也就是「一堂課長什麼樣子」的正式定義。

Why —— 沒有 DSL 會怎樣

沒有 DSL：
  LLM 直接產 HTML → 每次結構都不一樣 → 無法程式化修改
                                      → 無法驗證正確性
                                      → 無法可靠地匯出 PPTX
                                      → 渲染器要應付無限種可能
                                      → 安全性無法收斂（任意 HTML = XSS）

有 DSL：
  LLM 產結構化 DSL → 可驗證（validator）
                   → 可程式化 patch（Agent 的 dsl-tools）
                   → 可可靠匯出（PPTX / HTML / MP4 都從同一份 DSL 出）
                   → 渲染器只需支援有限的元素詞彙
                   → 安全邊界清楚（v1.0.1 就是靠這個修補 XSS）

🎯 v1.0.1 的 XSS 修補（GHSA-7rhf-2798-mvcj）正是這個設計的價值體現： 官方的修法是「把內容限制在渲染器的格式化詞彙內，並在持久化邊界統一淨化」， 而不是在每個渲染點各自處理。 有 DSL 才有「單一淨化邊界」這種乾淨的修法。

9.2 DSL 在架構中的位置

graph TB
    subgraph PRODUCERS["產生者"]
        G["Generation Pipeline<br/>LLM 生成"]
        A["Agent<br/>dsl-tools 逐場景 patch"]
        I["Importer<br/>PPTX 轉換"]
        E["Editor<br/>人工編輯"]
    end

    DSL["@openmaic/dsl<br/>━━━━━━━━━━<br/>版本化資料契約<br/>+ 驗證器<br/>━━━━━━━━━━<br/>單一淨化邊界"]

    subgraph CONSUMERS["消費者"]
        R["@openmaic/renderer<br/>課堂播放"]
        X1["export/pptx"]
        X2["export/html"]
        X3["render-service<br/>→ MP4"]
    end

    G --> DSL
    A --> DSL
    I --> DSL
    E --> DSL

    DSL --> R
    DSL --> X1
    DSL --> X2
    DSL --> X3

    style DSL fill:#fff3e0,stroke:#f57c00,stroke-width:4px
    style PRODUCERS fill:#e3f2fd,stroke:#1976d2
    style CONSUMERS fill:#e8f5e9,stroke:#388e3c

這張圖說明了一個關鍵事實：

四種產生方式（生成、Agent 編輯、PPTX 匯入、人工編輯）產出的都是同一種 DSL； 四種消費方式（播放、PPTX、HTML、MP4）讀的也都是同一種 DSL。

這代表：你用 Agent 生成的課，跟你從 PPTX 匯入的課，在系統中是完全等價的， 都可以用 Editor 編輯、都可以匯出成 MP4。

9.3 課件的層級結構

依據 Pro Workbench 的設計與官方描述，課件的層級如下【Official，層級名稱依官方用語】：

Course（課程）
  └── Lesson（課）
        └── Page / Stage（頁 / 場景單元）
              └── Scene（場景）
                    └── Content（內容元素）
                          ├── Slide（投影片）
                          ├── Narration（講稿 / 語音）
                          ├── Action（動作：speak / draw / highlight…）
                          ├── Quiz（測驗）
                          ├── Interactive（互動：3D / 模擬 / 遊戲 /
                          │                心智圖 / 程式編寫）
                          └── PBL（專題式學習）

graph TD
    C["Course<br/>企業級 Web App 開發"]
    C --> L1["Lesson 1<br/>需求與架構"]
    C --> L2["Lesson 2<br/>後端實作"]
    C --> L3["Lesson 3<br/>測試與部署"]

    L1 --> P1["Page 1-1<br/>需求分析"]
    L1 --> P2["Page 1-2<br/>架構決策"]

    P2 --> S1["Scene: 投影片講解"]
    P2 --> S2["Scene: 圓桌辯論<br/>單體 vs 微服務"]
    P2 --> S3["Scene: 互動測驗"]
    P2 --> S4["Scene: 3D 架構視覺化"]

    style C fill:#e8f5e9,stroke:#388e3c,stroke-width:3px
    style S2 fill:#fff3e0,stroke:#f57c00
    style S4 fill:#f3e5f5,stroke:#7b1fa2

📌 企業建課的實務建議【建議】：

層級	建議粒度
Course	一個主題領域（例：「訂單服務全貌」）
Lesson	一次可上完，30–50 分鐘
Page	一個概念，3–8 分鐘
Scene	一個呈現手法，30 秒–3 分鐘

太大的 Lesson 會導致生成逾時與成本失控；太小則失去脈絡。

9.4 Renderer 與 Editor

Renderer（@openmaic/renderer）

Editor（@openmaic/editor + MAIC Editor UI）

企業為什麼一定要開 Editor【建議】：

LLM 生成的教材，實測平均每 10 張投影片會有 1–2 處需要修正（術語錯誤、公司特有名詞、過時資訊）。 沒有 Editor 就只能「重新生成賭運氣」。 開 Editor 是企業使用的必要條件，不是選配。

9.5 企業整合：OpenMAIC SDK 的可能性【建議】

因為 @openmaic/* 是獨立發布的套件，理論上可以有以下企業整合模式：

graph TB
    subgraph OM["OpenMAIC 本體（內部使用）"]
        GEN["Agent 生成課件"]
        EDT["人工編輯"]
    end

    DSL["課件 DSL<br/>（JSON）"]

    GEN --> DSL
    EDT --> DSL

    DSL --> GIT["存進 Git<br/>版本控管 + Code Review"]

    GIT --> USE1["企業 Portal<br/>用 @openmaic/renderer<br/>直接渲染"]
    GIT --> USE2["CI Pipeline<br/>用 @openmaic/dsl<br/>驗證課件正確性"]
    GIT --> USE3["既有 LMS<br/>嵌入 iframe"]

    style DSL fill:#fff3e0,stroke:#f57c00,stroke-width:3px
    style GIT fill:#e1f5fe,stroke:#0277bd,stroke-width:2px

⚠️ ALLOWED_FRAME_ANCESTORS 很重要： 若要把 OpenMAIC 嵌進公司入口網站的 iframe，必須設定（build-time）：

ALLOWED_FRAME_ANCESTORS=https://portal.corp.example.com

這是 CSP 設定。不設會被瀏覽器擋掉，設成 * 則有 Clickjacking 風險。

9.6 本章實務案例

案例：把課件納入 Git 版控與 Code Review

背景：某團隊發現「教材品質」變成新問題——不同人生成的課程品質落差大，且沒有審查機制。

做法：把課件 DSL 當成程式碼管理。

repo: enterprise-courses/
├── courses/
│   ├── order-service-architecture/
│   │   ├── course.json          ← DSL 匯出
│   │   ├── sources/             ← 生成用的來源文件
│   │   │   └── architecture.md
│   │   └── README.md            ← 課程說明、負責人、更新日期
│   └── spring-boot-3-migration/
│       └── ...
├── .github/workflows/
│   └── validate-courses.yml     ← CI：用 @openmaic/dsl 驗證
└── CODEOWNERS                   ← 每門課指定審查者

CI 驗證腳本範例【建議】：

# .github/workflows/validate-courses.yml
name: Validate Courses

on:
  pull_request:
    paths:
      - 'courses/**/*.json'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22.19'

      - name: Install validator
        run: npm install @openmaic/dsl

      - name: Validate all course DSL
        run: node scripts/validate-courses.mjs

      - name: Check required metadata
        run: |
          for dir in courses/*/; do
            test -f "$dir/README.md" || { echo "缺少 README: $dir"; exit 1; }
            grep -q "負責人:" "$dir/README.md" || { echo "README 缺負責人: $dir"; exit 1; }
            grep -q "最後覆核:" "$dir/README.md" || { echo "README 缺覆核日期: $dir"; exit 1; }
          done

⚠️ 上述 @openmaic/dsl 的具體 validator API 呼叫方式，官方未提供文件。 實作前需先閱讀套件的型別定義或原始碼確認。本範例只示範流程設計。

效果：

9.7 本章注意事項

⚠️ 注意事項 1：DSL 是「版本化」的，代表它會變 官方明說 @openmaic/dsl 是 versioned contract。這代表升級 OpenMAIC 可能改變 DSL 格式。若你把課件存進 Git 長期保存，升級時要確認舊 DSL 是否還能讀。建議：每次升級後抽查最舊的課件是否仍能正常開啟與匯出。

⚠️ 注意事項 2：Editor 相關 Flag 都是 build-time NEXT_PUBLIC_MAIC_EDITOR_ENABLED 等改了要重新 build。Docker 使用者要注意 docker-compose.yml 中這些是build args 不是 runtime env。

📌 注意事項 3：Pro Workbench 會連帶開啟 Editor 依 v1.0.0 CHANGELOG：「The Pro workbench flag now implies the MAIC Editor gate」。所以開了 NEXT_PUBLIC_PRO_WORKBENCH_ENABLED 就等於也開了 Editor。做權限設計時要考慮這個連動。

10. Persistence 與 PostgreSQL 的角色【Official】

10.1 三種儲存模式

OpenMAIC 的儲存是可插拔的，依設定呈現三種模式：

graph TB
    subgraph M1["① 瀏覽器儲存（預設）"]
        B1["瀏覽器<br/>localStorage / IndexedDB"]
    end

    subgraph M2["② 伺服端持久化"]
        A2["OpenMAIC"] --> PG2[("PostgreSQL<br/>課件 + 媒體 bytes")]
    end

    subgraph M3["③ 伺服端 + 物件儲存（建議正式用）"]
        A3["OpenMAIC"] --> PG3[("PostgreSQL<br/>課件結構 + metadata")]
        A3 --> S3[("S3 / MinIO<br/>圖片 / 音訊 / 影片")]
    end

    style M1 fill:#fafafa,stroke:#999
    style M2 fill:#e3f2fd,stroke:#1976d2
    style M3 fill:#e8f5e9,stroke:#388e3c,stroke-width:2px

⚠️ 模式 ① 的資料會消失：清瀏覽器快取、換瀏覽器、換電腦，課件就不見了。 任何超過一人使用的場景，都必須用模式 ② 以上。

模式 ① 的實際實作層【Official，依 package.json 相依查證】

資安審查一定會問「純瀏覽器模式的資料到底存在哪、能不能稽核」，因此把底層講清楚：

這帶出三個對企業的實質結論：

1. 伺服器上沒有任何課件副本。模式 ① 下，OpenMAIC 伺服器只是靜態應用 + LLM 代理；你無法在伺服器端備份、稽核或回收使用者產出的課件。
2. PGlite 的存在解釋了「為什麼模式 ①→② 的遷移是可行的」 —— 瀏覽器端與伺服端用的是同一套 PostgreSQL 語意，而非兩種不同的資料模型。但官方沒有提供自動遷移工具，實際遷移做法與教訓見第 10.7 節。
3. 資料留存責任落在端點。若公司政策要求「所有工作產出必須存放於受控伺服器」，模式 ① 不符合規範，這不是設定問題，是架構問題 —— 必須直接上模式 ②。

📌 IndexedDB 的容量受瀏覽器配額管制（通常依磁碟可用空間的百分比動態計算）。 一旦超出配額，寫入會失敗且錯誤訊息常常不明確。這是模式 ① 在重度使用下的第二個風險，第一個是資料遺失。

10.2 @openmaic/storage 的四類 Store

官方將持久化抽象成四類 store，各有 HTTP 契約【Official】：

📌 「可插拔 + HTTP 契約」的意義：理論上企業可以實作自己的 store 服務， 讓 OpenMAIC 透過 HTTP 存取內部的儲存系統。但官方沒有提供實作教學，需自行讀 @openmaic/storage 原始碼。

10.3 PostgreSQL 的具體角色

當 DATABASE_URL 設定後，PostgreSQL 承擔：

🎯 「database triggers 實現場景版本號」與「serialized 配額預留」這兩點很值得注意： 官方把一致性責任下放到資料庫層，代表多個 worker 同時寫入是被認真設計過的。 這也代表 —— 你不能隨便換掉 PostgreSQL 改用其他 DB，因為邏輯有一部分在 trigger 裡。

10.4 Database Schema 的資訊缺口

⚠️ 這是本手冊必須誠實揭露的最大缺口之一。

企業必須自行應對的做法【建議】：

# 1. 初次啟動後，立刻 dump 出 schema 存檔備查
docker compose exec postgres \
  pg_dump -U openmaic -d openmaic --schema-only > schema-v1.0.1.sql

# 2. 每次升級前後各 dump 一次，比對差異
docker compose exec postgres \
  pg_dump -U openmaic -d openmaic --schema-only > schema-v1.1.0.sql
diff schema-v1.0.1.sql schema-v1.1.0.sql > schema-diff.txt

# 3. 建立完整備份（升級前必做）
docker compose exec postgres \
  pg_dump -U openmaic -d openmaic -Fc > backup-$(date +%Y%m%d).dump

⚠️ 在官方提供 migration 文件之前，「升級前完整備份 + schema diff」是唯一可靠的保護。 詳見第 46 章。

10.5 資產（Asset）的位元組模型

v1.0.0 引入了較完整的資產管理【Official，依 CHANGELOG】：

flowchart LR
    UP["上傳來源<br/>PDF / DOCX / PPTX /<br/>音訊 / 影片"] --> POOL["Asset Pool<br/>資產池"]
    POOL --> EXT["按 ID 萃取<br/>Extraction"]
    EXT --> DER["Derived Assets<br/>衍生資產<br/>（含 lineage 血緣）"]
    DER --> CACHE["Extraction Cache<br/>萃取快取"]
    CACHE --> USE["Agent Context /<br/>Course Content"]

    style POOL fill:#e3f2fd,stroke:#1976d2
    style DER fill:#e8f5e9,stroke:#388e3c
    style CACHE fill:#fff3e0,stroke:#f57c00

關鍵設計【Official】：

相關環境變數：

ASSET_S3_BUCKET=                          # S3 bucket
ASSET_BYTE_EGRESS=redirect                # 位元組出口方式（間接 vs 直接）
ASSET_COLLECTION_ENABLED=true             # DATABASE_URL 設定時預設啟用
ASSET_COLLECTION_INTERVAL_MS=900000       # 回收掃描間隔（15 分鐘）
ASSET_COLLECTION_GRACE_MS=3600000         # 寬限期（1 小時）

📌 ASSET_COLLECTION_* 是垃圾回收機制：定期掃描並回收無人參照的資產。 企業注意：ASSET_COLLECTION_GRACE_MS 預設 1 小時。 如果你有「先刪除課程、後來想救回」的需求，1 小時後資產就沒了。需要更長保留期請自行調大。

10.6 容量規劃【建議】

官方沒有容量規劃指引，以下為本手冊依資料型態的估算方法：

一門 40 分鐘課程的粗估：

DSL          0.3 MB
圖片   25 張 × 0.8 MB  =  20 MB
音訊   40 分鐘 × 1 MB  =  40 MB
─────────────────────────────
小計                    ≈ 60 MB（不含 MP4）
含 MP4 匯出             ≈ 250 MB

企業容量規劃範例：

✅ 建議：媒體一律走 ASSET_S3_BUCKET，不要塞 PostgreSQL。 PG 存 60 MB × 200 門 = 12 GB 的 BLOB，備份與還原都會很痛苦。

10.7 本章實務案例

案例：從瀏覽器模式遷移到伺服端持久化的教訓

背景：某團隊 PoC 階段用預設的瀏覽器模式，做了 12 門課。試行成功後要正式導入，開啟 PostgreSQL。

發生的事：

1. 開了 NEXT_PUBLIC_PERSISTENCE=1 + DATABASE_URL，重新 build
2. 進系統後 —— 12 門課全部不見了
3. 原來瀏覽器儲存的課件不會自動遷移到 DB

補救：

Step 1  把 NEXT_PUBLIC_PERSISTENCE 改回不設定，重新 build
Step 2  逐一開啟 12 門課，用「Classroom ZIP 匯出」存下來
Step 3  重新開啟 PERSISTENCE，重新 build
Step 4  逐一匯入 12 個 ZIP
        （耗時約 4 小時）

教訓：

⚠️ 切換儲存模式前，一定要先把既有課件匯出。 官方沒有提供瀏覽器儲存 → PostgreSQL 的遷移工具（官方資料未說明）。

✅ 更好的做法：PoC 階段就直接用 PostgreSQL。 docker compose --profile server-persistence up 就能起一個 PG，成本很低， 省下後面的遷移痛苦。

案例：Agent Session 資料暴增

背景：某團隊開啟 Agent Runtime 兩個月後，發現 PostgreSQL 從 2 GB 長到 47 GB。

原因排查：

-- 查各 table 大小（實際 table 名稱需依你的環境確認，
-- 官方未提供 schema 文件）
SELECT
  schemaname,
  relname AS table_name,
  pg_size_pretty(pg_total_relation_size(relid)) AS total_size
FROM pg_catalog.pg_statio_user_tables
ORDER BY pg_total_relation_size(relid) DESC
LIMIT 20;

發現 Agent Session 的 event 資料佔了 40 GB —— 因為每次 Agent 執行都會寫入大量 event（工具呼叫、模型回應、串流片段），而官方沒有提供 event 保留期設定。

採取的措施【建議】：

⚠️ 在官方提供資料保留策略之前，Agent Session 資料成長是必須主動監控的項目。 自行刪除 DB 資料有破壞一致性的風險（有 trigger、有配額預留），務必先在測試環境驗證。

10.8 本章注意事項

⚠️ 注意事項 1：NEXT_PUBLIC_PERSISTENCE 是 build-time 改了要重新 build。Docker 使用者注意它在 compose 中是 build arg。

⚠️ 注意事項 2：PERSISTENCE_ALLOW_INSECURE_DEV_AUTH 千萬不要在正式環境開 v1.0.1 起，開發用的 persistence authenticator 在 NODE_ENV=production 下會拒絕運作（fail-closed）。這是刻意的安全設計。若你被迫設 PERSISTENCE_ALLOW_INSECURE_DEV_AUTH=true 才能跑，代表你的認證方案有問題，應該改用前置 Reverse Proxy 認證，而不是打開這個開關。

⚠️ 注意事項 3：官方沒有 DB schema 與 migration 文件 這是導入的實質風險。必要對策：每次升級前完整 pg_dump，並保存 schema 快照做 diff。

📌 注意事項 4：不要嘗試換掉 PostgreSQL 一致性邏輯有一部分在 database triggers 裡（官方 CHANGELOG 明說）。換成 MySQL 或其他 DB 不會work。

11. 安裝前置需求【Official】

11.1 硬性需求

⚠️ v1.0.1 把 Node 需求從 20.9 提高到 22.19。這是最常見的安裝失敗原因。 Repo 有 .nvmrc，用 nvm use / fnm use 最保險。

11.2 Prerequisites Checklist

安裝前逐項打勾：

【基礎環境】
□ Node.js >= 22.19          （node --version）
□ pnpm >= 10                （pnpm --version）
□ Git                       （git --version）
□ 至少 8 GB 可用記憶體
□ 至少 10 GB 可用磁碟空間（含 node_modules 與生成資產）

【網路】
□ 可存取 github.com（clone）
□ 可存取 registry.npmjs.org（或已設定內部 registry）
□ 可存取所選 LLM Provider 的 API 端點
□ 若在公司 Proxy 後：已取得 HTTP_PROXY / HTTPS_PROXY 設定值

【AI Provider（至少一項）】
□ OPENAI_API_KEY            或
□ ANTHROPIC_API_KEY         或
□ GOOGLE_API_KEY            或
□ BEDROCK_REGION + BEDROCK_MODELS  或
□ 內部 Model Gateway 的 base URL + token  或
□ 本地 Ollama 已啟動（http://localhost:11434）

【選用功能（依需求勾選）】
□ PostgreSQL 16             （伺服端持久化）
□ S3 / MinIO bucket         （資產儲存）
□ TTS Provider              （語音講課）
□ ASR Provider              （語音輸入）
□ 圖片生成 Provider          （課件插圖）
□ 網頁搜尋 Provider          （deep-research skill）
□ PDF 解析 Provider          （PDF 教材品質提升）
□ render-service 環境        （MP4 匯出，需 8GB 記憶體 + NET_ADMIN）

【企業環境（正式部署才需要）】
□ Reverse Proxy（Nginx / Traefik）
□ SSO / OIDC Provider
□ 內部 Model Gateway
□ 監控系統（Prometheus / Grafana 等）
□ 備份機制
□ 資安部門審查通過

11.3 各作業系統的環境準備

Windows

建議路徑：WSL2 + Ubuntu（原生 Windows 也可，但踩坑較多）

# 1. 啟用 WSL2（PowerShell 系統管理員）
wsl --install -d Ubuntu

# 2. 進入 WSL 後，安裝 Node（用 nvm）
# 以下在 WSL 的 bash 中執行

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 22.19
nvm use 22.19
node --version    # v22.19.x

# 3. 安裝 pnpm
corepack enable
corepack prepare pnpm@latest --activate
pnpm --version    # 10.x

若堅持用原生 Windows：

# 用 fnm（Windows 上比 nvm-windows 穩定）
winget install Schniz.fnm
fnm install 22.19
fnm use 22.19

corepack enable
corepack prepare pnpm@latest --activate

⚠️ 原生 Windows 的已知風險：

• 路徑長度限制（node_modules 巢狀深）→ 建議把專案放在 C:\dev\OpenMAIC 這種短路徑
• 換行符號（CRLF/LF）→ 設定 git config --global core.autocrlf input
• render-service 需要 Linux 容器 → Docker Desktop 要切到 Linux containers

本手冊建議 Windows 使用者一律用 WSL2 或 Docker。

macOS

# Homebrew
brew install node@22 git
# 或用 nvm（建議，方便切版本）
brew install nvm
nvm install 22.19
nvm use 22.19

corepack enable
corepack prepare pnpm@latest --activate

# Docker（若需要）
brew install --cask docker

Linux（Ubuntu / Debian）

# Node via nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 22.19
nvm use 22.19

# pnpm
corepack enable
corepack prepare pnpm@latest --activate

# Git
sudo apt-get update && sudo apt-get install -y git

# Docker（若需要）
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker "$USER"
newgrp docker

Linux（RHEL / Rocky / Alma）

sudo dnf install -y git
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 22.19 && nvm use 22.19
corepack enable && corepack prepare pnpm@latest --activate

# Podman 使用者（本目錄另有《Podman使用教學》）
sudo dnf install -y podman podman-compose

📌 Podman 使用者注意：官方只測試 Docker Compose。 render-service 需要 NET_ADMIN capability，在 rootless Podman 下需額外設定。 若貴公司標準是 Podman，建議先做 PoC 驗證 video-export profile 是否可用。

11.4 企業網路環境的額外準備

Proxy 設定

若在公司 Proxy 後方，OpenMAIC 支援標準 Proxy 變數【Official】：

HTTP_PROXY=http://proxy.corp.example.com:8080
HTTPS_PROXY=http://proxy.corp.example.com:8080
NO_PROXY=localhost,127.0.0.1,.internal.example.com

同時 npm / pnpm 也要設定：

pnpm config set proxy http://proxy.corp.example.com:8080
pnpm config set https-proxy http://proxy.corp.example.com:8080
# 內部 registry
pnpm config set registry https://npm.corp.example.com/

內部憑證（自簽 CA）

若公司 Proxy 做 TLS 攔截：

export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/corp-ca-bundle.crt

⚠️ 絕對不要用 NODE_TLS_REJECT_UNAUTHORIZED=0。這會關閉所有 TLS 驗證，是嚴重的安全問題。正確做法是設定 NODE_EXTRA_CA_CERTS。

慢速網路 / 中國大陸網路

官方提供 build 加速參數【Official】：

ALPINE_MIRROR=mirrors.tuna.tsinghua.edu.cn \
NPM_REGISTRY=https://registry.npmmirror.com \
docker compose up --build

11.5 本章實務案例

案例：一次典型的安裝前置檢查

某 DevOps 同仁在企業內網要裝 OpenMAIC，實際執行的檢查腳本：

#!/usr/bin/env bash
# openmaic-precheck.sh —— OpenMAIC 安裝前置檢查
set -uo pipefail

PASS=0; FAIL=0
check() {
  local desc="$1"; shift
  if "$@" >/dev/null 2>&1; then
    echo "  ✅ $desc"; PASS=$((PASS+1))
  else
    echo "  ❌ $desc"; FAIL=$((FAIL+1))
  fi
}

echo "=== 基礎環境 ==="
node_ver=$(node --version 2>/dev/null | sed 's/v//')
if [ -n "$node_ver" ]; then
  required="22.19.0"
  if [ "$(printf '%s\n' "$required" "$node_ver" | sort -V | head -1)" = "$required" ]; then
    echo "  ✅ Node.js $node_ver (>= 22.19)"; PASS=$((PASS+1))
  else
    echo "  ❌ Node.js $node_ver 版本過舊，需要 >= 22.19"; FAIL=$((FAIL+1))
  fi
else
  echo "  ❌ Node.js 未安裝"; FAIL=$((FAIL+1))
fi

pnpm_ver=$(pnpm --version 2>/dev/null)
if [ -n "$pnpm_ver" ] && [ "${pnpm_ver%%.*}" -ge 10 ]; then
  echo "  ✅ pnpm $pnpm_ver (>= 10)"; PASS=$((PASS+1))
else
  echo "  ❌ pnpm 缺少或版本過舊（目前：${pnpm_ver:-未安裝}）"; FAIL=$((FAIL+1))
fi

check "Git 已安裝" git --version
check "Docker 已安裝" docker --version

echo ""
echo "=== 資源 ==="
mem_gb=$(free -g 2>/dev/null | awk '/^Mem:/{print $2}')
[ "${mem_gb:-0}" -ge 8 ] \
  && { echo "  ✅ 記憶體 ${mem_gb}GB"; PASS=$((PASS+1)); } \
  || { echo "  ⚠️  記憶體 ${mem_gb:-?}GB（建議 >= 8GB）"; }

disk_gb=$(df -BG . 2>/dev/null | awk 'NR==2{gsub("G","",$4); print $4}')
[ "${disk_gb:-0}" -ge 10 ] \
  && { echo "  ✅ 可用磁碟 ${disk_gb}GB"; PASS=$((PASS+1)); } \
  || { echo "  ⚠️  可用磁碟 ${disk_gb:-?}GB（建議 >= 10GB）"; }

echo ""
echo "=== 網路連線 ==="
check "github.com 可達" curl -sSf -m 10 -o /dev/null https://github.com
check "npm registry 可達" curl -sSf -m 10 -o /dev/null "$(pnpm config get registry)"

echo ""
echo "=== 結果：通過 $PASS 項，失敗 $FAIL 項 ==="
[ "$FAIL" -eq 0 ] || { echo "請先修正失敗項目再安裝"; exit 1; }
echo "前置檢查通過，可以開始安裝"

實際執行後發現的問題：Node 是 20.11（公司標準映像）。這在 v1.0.0 可以跑，但 v1.0.1 不行。最後請 Platform 團隊出一版 Node 22 的標準映像。

🎯 這個案例的價值在於：前置檢查花 10 分鐘，可以省下 2 小時的除錯。 建議把上述腳本納入團隊的安裝 SOP。

11.6 本章注意事項

⚠️ 注意事項 1：公司標準 Node 映像可能不夠新 很多企業的標準 Node base image 停留在 LTS 20。OpenMAIC v1.0.1 需要 22.19+。這需要事先與 Platform 團隊協調，不要等到安裝當天才發現。

⚠️ 注意事項 2：corepack 是安裝 pnpm 的建議方式 npm install -g pnpm 也可以，但 corepack 會依專案的 packageManager 欄位自動選版本，較不易出錯。

📌 注意事項 3：記憶體需求要看你開哪些功能

配置	建議記憶體
只跑 OpenMAIC 本體	4 GB
+ PostgreSQL	6 GB
+ render-service（MP4）	14 GB（render-service 自己限 8GB）
+ 本地 Ollama	依模型而定，通常 +8~32 GB

12. 安裝方法 A：原始碼安裝【Official】

12.1 完整八步驟

以下指令與官方 README 一致【Official】。

Step 1 — Clone

git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC

企業建議：鎖定版本，不要用 main【建議】

# 列出可用的 tag
git tag --list 'v*' --sort=-v:refname | head -10

# 切到已驗證的版本
git checkout v1.0.1

⚠️ 不要在正式環境用 main 分支。main 隨時在變，今天能跑不代表明天能跑。 一律 checkout 特定 tag，並記錄在部署文件中。

Step 2 — Install

pnpm install

預期耗時：首次約 3–10 分鐘（依網路）。

常見失敗：

Step 3 — Configure（複製環境變數範本）

cp .env.example .env.local

📌 注意檔名是 .env.local 不是 .env。這是 Next.js 的慣例。 .env.local 已在 .gitignore 中，不會被 commit。

Step 4 — Database（選用）

若要伺服端持久化：

# 用 Docker 起一個 PostgreSQL 16
docker run -d --name openmaic-pg \
  -e POSTGRES_USER=openmaic \
  -e POSTGRES_PASSWORD=openmaic-dev \
  -e POSTGRES_DB=openmaic \
  -p 5432:5432 \
  -v openmaic-pg-data:/var/lib/postgresql/data \
  postgres:16

# 驗證
docker exec openmaic-pg pg_isready -U openmaic

⚠️ 官方未說明是否需要手動執行 migration。 實務上多數 Next.js 專案會在首次啟動時自動建表。建議：首次啟動後立刻 pg_dump --schema-only 存檔（見第 10.4 節）。

Step 5 — Environment Variables

編輯 .env.local，最小可跑配置：

# ── 最小配置：只要一組 LLM Key ──────────────────
ANTHROPIC_API_KEY=sk-ant-your-key-here

企業建議的起始配置：

# ── LLM ────────────────────────────────────────
# 走公司內部 Model Gateway
OPENAI_API_KEY=corp-gateway-token
OPENAI_BASE_URL=https://ai-gateway.corp.example.com/v1
OPENAI_MODELS=gpt-5.5,gpt-5.5-mini
DEFAULT_MODEL=openai:gpt-5.5

# ── 伺服端持久化 ────────────────────────────────
NEXT_PUBLIC_PERSISTENCE=1
DATABASE_URL=postgres://openmaic:openmaic-dev@localhost:5432/openmaic

# ── 存取控制（開發階段的最低防護）──────────────
ACCESS_CODE=change-me-to-a-strong-secret

# ── 記錄 ───────────────────────────────────────
LOG_LEVEL=info
LOG_FORMAT=json

# ── 效能 ───────────────────────────────────────
PARALLEL_SCENE_CONCURRENCY=3

Step 6 — Build（正式環境）

pnpm build

⚠️ 所有 NEXT_PUBLIC_* 變數在此時被編譯進 bundle。 之後改這些變數必須重新 build，重啟無效。

pnpm build 不是只跑 next build【Official】

package.json 的 build script 實際上是兩段：

"build": "node scripts/assert-vendor-maic-importer.mjs && next build"

也就是說，next build 之前會先跑一支守門腳本 scripts/assert-vendor-maic-importer.mjs，用來斷言 vendored 的 MAIC importer 確實就位。

這對企業有實際意義，因為它是離線／內網環境最常見的第一個 build 失敗點：

📌 排錯要點：這支腳本的錯誤訊息不會提到 Next.js，所以很容易被誤判成「Next.js 設定壞了」而往錯的方向查。 只要失敗發生在編譯輸出之前，先往安裝完整性查，不要往 Next.js 設定查。

Step 7 — Start

開發模式（有 hot reload，適合試用與除錯）：

pnpm dev

正式模式：

pnpm build && pnpm start

服務啟動於 http://localhost:3000。

Step 8 — Verify

驗證清單：

□ 瀏覽器開啟 http://localhost:3000 有畫面
□ 若設了 ACCESS_CODE，會要求輸入
□ 輸入一個簡單主題（例如「什麼是 REST API」）
□ 能看到大綱生成
□ 能看到場景內容生成
□ 能進入 Classroom 播放
□ 若設了 DATABASE_URL：
    重新整理頁面後課程仍在
    docker exec openmaic-pg psql -U openmaic -d openmaic -c "\dt"
    能看到 table
□ 檢查 log 沒有 ERROR

12.2 啟用 Pro Workbench 與 Agent Runtime【Experimental】

這兩個是預設關閉的實驗性功能，需要額外設定。

需要的完整設定

# ── ① Pro Workbench UI（build-time，需重新 build）─────
NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true

# ── ② Agent Runtime（server-only，重啟即可）───────────
OPENMAIC_AGENT_RUNTIME_ENABLED=true

# ── ③ 資料庫（Agent Runtime 必要）─────────────────────
DATABASE_URL=postgres://openmaic:openmaic-dev@localhost:5432/openmaic

# ── ④ Agent 模型路由（必填，否則 Agent 無法運作）───────
MODEL_ROUTES='{"maic-agent-driver":{"model":"openai:gpt-5.5","api":"openai-completions"}}'

⚠️ MODEL_ROUTES 是最容易漏掉、也最容易設錯的一項。 .env.example 明確標示它是 REQUIRED（當 Agent Runtime 啟用時）。 沒設或格式錯誤，Agent 會啟動但無法執行任何工作，而錯誤訊息可能不明顯。

MODEL_ROUTES 的格式說明【Official】

它是一個 JSON 物件，key 是階段名稱，value 指定該階段用哪個模型：

{
  "maic-agent-driver": {
    "model": "openai:gpt-5.5",
    "api": "openai-completions"
  }
}

⚠️ 除了 maic-agent-driver 之外還有哪些階段名稱，官方資料未說明。 .env.example 只給了這一個範例。若要對不同階段做不同路由（成本優化）， 需自行閱讀 lib/ai/ 與 lib/server/agent-runtime/agent-driver-model.ts 原始碼確認。

啟用後的驗證

□ 重新 build（因為改了 NEXT_PUBLIC_ 變數）
    pnpm build && pnpm start
□ 首頁應出現 Pro Workbench 入口
□ 進入 Workbench，左側有導覽列、中間有對話框
□ 輸入「幫我規劃一堂 Spring Boot 入門課的課綱」
□ 觀察是否有 event 串流回來
□ 檢查資料庫是否有 session 記錄
□ 檢查 log 是否有 MODEL_ROUTES 相關錯誤

12.3 目錄與檔案權限【建議】

正式環境部署時：

# 建立專用使用者（不要用 root 跑）
sudo useradd -r -m -s /bin/bash openmaic

# 安裝到專用目錄
sudo mkdir -p /opt/openmaic
sudo chown openmaic:openmaic /opt/openmaic
sudo -u openmaic git clone -b v1.0.1 \
  https://github.com/THU-MAIC/OpenMAIC.git /opt/openmaic

# 環境變數檔案權限（含 API Key，必須嚴格）
sudo -u openmaic chmod 600 /opt/openmaic/.env.local

systemd service 範例【建議】：

# /etc/systemd/system/openmaic.service
[Unit]
Description=OpenMAIC
After=network.target postgresql.service

[Service]
Type=simple
User=openmaic
Group=openmaic
WorkingDirectory=/opt/openmaic
Environment=NODE_ENV=production
EnvironmentFile=/opt/openmaic/.env.local
ExecStart=/usr/local/bin/pnpm start
Restart=on-failure
RestartSec=10

# 安全強化
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/openmaic/.next /opt/openmaic/data

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now openmaic
sudo systemctl status openmaic
sudo journalctl -u openmaic -f

12.4 本章實務案例

案例：第一次安裝的完整時間軸

某團隊實際的首次安裝紀錄（含踩坑）：

總計 65 分鐘，其中 40 分鐘卡在 Pro Workbench 的四個必要設定。

🎯 這個案例是本手冊第 51 章 Quick Start 存在的理由。 把「Pro Workbench 需要四個設定同時到位」講清楚，就能省下這 40 分鐘。

四個設定（缺一不可）：

① NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true   ← build-time，要重 build
② OPENMAIC_AGENT_RUNTIME_ENABLED=true      ← server-only
③ DATABASE_URL=postgres://...              ← 必要
④ MODEL_ROUTES='{"maic-agent-driver":...}' ← 必要，最常漏

12.5 本章注意事項

⚠️ 注意事項 1：正式環境不要用 pnpm dev pnpm dev 是開發模式，效能差、會暴露除錯資訊、且 NODE_ENV 不是 production（這會讓 v1.0.1 的某些安全檢查行為不同）。正式一律 pnpm build && pnpm start。

⚠️ 注意事項 2：.env.local 含 API Key，權限要設 600 而且絕對不能 commit。建議在 CI 加一道 secret scan（本目錄有《GitHub Copilot SSDLC 教學手冊》可參考）。

⚠️ 注意事項 3：checkout 特定 tag，不要用 main 並在部署文件中記錄版本號與 commit hash：

git rev-parse HEAD > /opt/openmaic/DEPLOYED_COMMIT

📌 注意事項 4：pnpm build 可能需要較多記憶體 Next.js 16 的 build 在大型專案上可能吃 4GB+。若在小型 VM 上 build 失敗（OOM），可先在 CI 上 build 好再部署產物，或暫時加 swap。

13. 安裝方法 B：Docker / Docker Compose【Official】

13.1 最簡單的啟動方式

官方提供 Dockerfile 與 docker-compose.yml【Official】：

git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC
git checkout v1.0.1

cp .env.example .env.local
# 編輯 .env.local，至少填一組 API Key

docker compose up --build

服務啟動於 http://localhost:3000。

慢速網路加速【Official】：

ALPINE_MIRROR=mirrors.tuna.tsinghua.edu.cn \
NPM_REGISTRY=https://registry.npmmirror.com \
docker compose up --build

13.2 Compose 的三個 Service 與兩個 Profile

依官方 docker-compose.yml【Official】：

graph TB
    subgraph DEFAULT["預設（無 profile）"]
        APP["openmaic<br/>:3000<br/>env_file: .env.local<br/>volume: openmaic-data"]
    end

    subgraph P1["profile: server-persistence"]
        PG[("postgres:16<br/>DB: openmaic<br/>healthcheck<br/>volume: openmaic-postgres")]
    end

    subgraph P2["profile: video-export"]
        RS["render-service<br/>:9000（僅內部）<br/>cap_add: NET_ADMIN<br/>mem_limit: 8GB"]
    end

    APP -.->|"需 --profile"| PG
    APP -->|"render network<br/>（隔離）"| RS

    NET1["default network<br/>可對外（API 呼叫）"]
    NET2["render network<br/>僅 openmaic ↔ render-service"]

    APP --- NET1
    APP --- NET2
    RS --- NET2

    style APP fill:#e8f5e9,stroke:#388e3c,stroke-width:2px
    style PG fill:#e1f5fe,stroke:#0277bd
    style RS fill:#fce4ec,stroke:#c2185b,stroke-width:2px
    style NET2 fill:#fff3e0,stroke:#f57c00

Volumes：

Networks：

13.3 三種常用啟動組合

組合 A：最小啟動（瀏覽器儲存）

docker compose up --build

適用：個人試用、快速 Demo。

組合 B：含 PostgreSQL（團隊共用）

NEXT_PUBLIC_PERSISTENCE=1 \
docker compose --profile server-persistence up --build

⚠️ 注意 NEXT_PUBLIC_PERSISTENCE=1 放在指令前面。 官方 README 就是這樣寫的——因為它是 build arg，要在 build 時傳入。 光在 .env.local 裡寫是不夠的（除非 compose 有把它接成 build arg， 依官方 compose 的設計，NEXT_PUBLIC_* 是走 build args）。

.env.local 對應設定：

DATABASE_URL=postgres://openmaic:openmaic-dev@postgres:5432/openmaic

📌 注意 host 是 postgres 不是 localhost —— 在 compose 網路中要用 service 名稱。

組合 C：完整（PG + 影片匯出）

NEXT_PUBLIC_PERSISTENCE=1 \
NEXT_PUBLIC_ENABLE_VIDEO_EXPORT=true \
docker compose --profile server-persistence --profile video-export up --build

.env.local：

DATABASE_URL=postgres://openmaic:openmaic-dev@postgres:5432/openmaic
RENDER_SERVICE_URL=http://render-service:9000

13.4 企業級 Compose 覆寫檔【建議】

不要直接改官方的 docker-compose.yml（升級會衝突）。用覆寫檔：

# docker-compose.override.yml —— 企業自訂，不進版控（或進私有版控）
services:
  openmaic:
    # 不對外暴露，由 Reverse Proxy 轉發
    ports: !override
      - "127.0.0.1:3000:3000"
    environment:
      NODE_ENV: production
      LOG_FORMAT: json
      TRUST_PROXY_HEADERS: "true"
    logging:
      driver: json-file
      options:
        max-size: "50m"
        max-file: "5"
    deploy:
      resources:
        limits:
          memory: 4G
        reservations:
          memory: 2G
    healthcheck:
      test: ["CMD", "node", "-e",
             "fetch('http://localhost:3000/').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

  postgres:
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/pg_password
    secrets:
      - pg_password
    # 不對外暴露 5432
    ports: !reset []
    command:
      - postgres
      - -c
      - max_connections=200
      - -c
      - shared_buffers=512MB
      - -c
      - log_min_duration_statement=1000

secrets:
  pg_password:
    file: ./secrets/pg_password.txt

# 啟動時會自動合併 docker-compose.yml + docker-compose.override.yml
docker compose --profile server-persistence up -d

⚠️ !override / !reset 是 Docker Compose 較新的合併語法。 若你的 Compose 版本不支援，改用 -f docker-compose.yml -f docker-compose.prod.yml 明確指定多檔。

13.5 常用維運指令

# 啟動（背景）
docker compose --profile server-persistence up -d

# 查看狀態
docker compose ps

# 看 log（跟隨）
docker compose logs -f openmaic

# 只看錯誤
docker compose logs openmaic 2>&1 | grep -i error

# 進入容器
docker compose exec openmaic sh

# 資料庫指令
docker compose exec postgres psql -U openmaic -d openmaic

# 備份資料庫
docker compose exec -T postgres \
  pg_dump -U openmaic -d openmaic -Fc > backup-$(date +%Y%m%d-%H%M).dump

# 還原
cat backup-20260913-1030.dump | \
  docker compose exec -T postgres pg_restore -U openmaic -d openmaic --clean

# 重啟單一服務
docker compose restart openmaic

# 停止（保留資料）
docker compose down

# 停止並刪除資料（危險！）
docker compose down -v

⚠️ docker compose down -v 會刪掉 volume，所有課件與資料庫都會消失。 建議在團隊 Wiki 上把這個指令標紅，或乾脆別記它。

13.6 本章實務案例

案例：把 render-service 的隔離做對

背景：某團隊為了「方便除錯」，把 render-service 的 port 9000 對外開放，並把它移到 default network。

發生的事：兩週後資安掃描發現該 port 可從辦公網路直接存取，且該服務會執行任意傳入的 HTML。等於在內網開了一個「遠端執行任意前端程式碼」的端點。

官方原本的三層防護（被拿掉的）：

修正：

# 正確做法：保留隔離，除錯時用臨時的 exec 或 port-forward
services:
  render-service:
    # ✅ 不要 publish port
    # ✅ 只掛 render network（官方預設）
    # 除錯時臨時用：
    #   docker compose exec render-service sh
    # 或臨時 port-forward：
    #   docker compose port render-service 9000

🎯 教訓：官方 compose 中每一個看起來「多餘」的設定，通常都有安全理由。 cap_add: NET_ADMIN（為了 iptables 封鎖出站）、獨立 network、不 publish port —— 這三個是一組的。 修改前先問「這是為了什麼」。

案例：Compose 升級時的資料保護流程

#!/usr/bin/env bash
# openmaic-upgrade.sh —— Compose 環境的安全升級流程
set -euo pipefail

TARGET_TAG="${1:?用法: $0 <目標 tag，例如 v1.1.0>}"
BACKUP_DIR="/backup/openmaic/$(date +%Y%m%d-%H%M%S)"

echo "==> 1. 建立備份目錄"
mkdir -p "$BACKUP_DIR"

echo "==> 2. 備份資料庫"
docker compose exec -T postgres \
  pg_dump -U openmaic -d openmaic -Fc > "$BACKUP_DIR/db.dump"

echo "==> 3. 備份 schema 快照（供 diff）"
docker compose exec -T postgres \
  pg_dump -U openmaic -d openmaic --schema-only > "$BACKUP_DIR/schema-before.sql"

echo "==> 4. 備份環境設定"
cp .env.local "$BACKUP_DIR/env.local.bak"
cp docker-compose.override.yml "$BACKUP_DIR/" 2>/dev/null || true

echo "==> 5. 備份 volume（資產）"
docker run --rm \
  -v openmaic-data:/data:ro \
  -v "$BACKUP_DIR:/backup" \
  alpine tar czf /backup/openmaic-data.tar.gz -C /data .

echo "==> 6. 記錄目前版本"
git rev-parse HEAD > "$BACKUP_DIR/commit-before.txt"

echo "==> 7. 停止服務"
docker compose down

echo "==> 8. 切換版本"
git fetch --tags
git checkout "$TARGET_TAG"

echo "==> 9. 比對 .env.example 是否有新變數"
diff <(grep -oE '^[A-Z_]+' "$BACKUP_DIR/env.local.bak" | sort -u) \
     <(grep -oE '^#?\s*[A-Z_]+=' .env.example | tr -d '#= ' | sort -u) \
     > "$BACKUP_DIR/env-diff.txt" || true
echo "    → 請檢視 $BACKUP_DIR/env-diff.txt"

echo "==> 10. 重新建置並啟動"
docker compose --profile server-persistence up -d --build

echo "==> 11. 等待健康檢查"
for _ in $(seq 1 30); do
  if curl -sSf -o /dev/null http://localhost:3000/; then
    echo "    ✅ 服務正常"
    break
  fi
  sleep 5
done

echo "==> 12. 匯出升級後 schema 供 diff"
docker compose exec -T postgres \
  pg_dump -U openmaic -d openmaic --schema-only > "$BACKUP_DIR/schema-after.sql"
diff "$BACKUP_DIR/schema-before.sql" "$BACKUP_DIR/schema-after.sql" \
  > "$BACKUP_DIR/schema-diff.txt" || true

echo ""
echo "升級完成。備份位於 $BACKUP_DIR"
echo "請檢視："
echo "  - $BACKUP_DIR/env-diff.txt     （新增的環境變數）"
echo "  - $BACKUP_DIR/schema-diff.txt  （資料庫結構變更）"

13.7 本章注意事項

⚠️ 注意事項 1：NEXT_PUBLIC_* 在 Compose 中是 build args 官方 compose 把這些 feature flag 設計成 build arguments。改了要 --build 重建，光 restart 沒用。

⚠️ 注意事項 2：不要改官方的 docker-compose.yml 用 docker-compose.override.yml 或 -f 多檔合併。直接改官方檔案會讓每次 git pull 都衝突。

⚠️ 注意事項 3：預設密碼必須改 官方 compose 的 PostgreSQL 用開發用預設密碼。正式環境必須改，並建議用 Docker secrets 而非環境變數。

📌 注意事項 4：restart: always 會掩蓋問題 官方 compose 的 openmaic service 設了 restart: always。這在正式環境是好的，但除錯時會讓你看不到崩潰——服務一直重啟。除錯時建議暫時改成 restart: "no"，並看完整 log。

14. 安裝方法 C：開發環境建置【Official】

14.1 什麼時候需要開發環境

📌 企業建議【建議】：至少要有一位同仁維持一套可執行的開發環境。 因為官方沒有完整文件，遇到問題時「能讀原始碼、能加 log、能 debug」是唯一的自救手段。

14.2 開發環境設定

git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC

# 用 .nvmrc 指定的版本
nvm use     # 或 fnm use

pnpm install
cp .env.example .env.local

.env.local 開發用配置：

# ── 模型（開發用可以用便宜的）────────────────
OPENAI_API_KEY=sk-...
DEFAULT_MODEL=openai:gpt-5.5-mini

# ── 開啟所有實驗性功能以便測試 ────────────────
NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true
NEXT_PUBLIC_MAIC_EDITOR_ENABLED=true
NEXT_PUBLIC_MAIC_EDITOR_RENDERER_ENABLED=true
NEXT_PUBLIC_MAIC_PLAYBACK_RENDERER_ENABLED=true
NEXT_PUBLIC_ENABLE_PPTX_IMPORT=true
OPENMAIC_AGENT_RUNTIME_ENABLED=true

# ── 資料庫 ────────────────────────────────
NEXT_PUBLIC_PERSISTENCE=1
DATABASE_URL=postgres://openmaic:openmaic-dev@localhost:5432/openmaic
MODEL_ROUTES='{"maic-agent-driver":{"model":"openai:gpt-5.5-mini","api":"openai-completions"}}'

# ── 開發用：允許本地網路（接本機 Ollama 等）──
ALLOW_LOCAL_NETWORKS=true

# ── 詳細 log ──────────────────────────────
LOG_LEVEL=debug
LOG_FORMAT=pretty

# ── 開發時降低併發，方便觀察 ──────────────────
PARALLEL_SCENE_CONCURRENCY=1
OPENMAIC_AGENT_RUNTIME_MAX_CONCURRENT=1

# 起 PostgreSQL
docker compose --profile server-persistence up -d postgres

# 開發模式
pnpm dev

14.3 常用開發指令

依 repo 中的設定檔推斷（vitest.config.ts、playwright.config.ts、eslint.config.mjs、.prettierrc）：

pnpm dev            # 開發伺服器（hot reload）
pnpm build          # 正式建置
pnpm start          # 執行已建置版本
pnpm lint           # ESLint
pnpm test           # Vitest 單元測試
pnpm test:e2e       # Playwright E2E（指令名稱需確認 package.json）

⚠️ 上述指令名稱需以 package.json 的 scripts 為準。 執行 cat package.json | grep -A 30 '"scripts"' 確認實際可用的指令。

14.4 排錯用的開發技巧【建議】

技巧 1：用 LOG_LEVEL=debug + LOG_FORMAT=pretty

LOG_LEVEL=debug
LOG_FORMAT=pretty

開發時 pretty 比 json 好讀很多。正式環境反過來（json 方便給 log 系統解析）。

技巧 2：降低併發以便觀察

PARALLEL_SCENE_CONCURRENCY=1
OPENMAIC_AGENT_RUNTIME_MAX_CONCURRENT=1
OPENMAIC_AGENT_RUNTIME_SCAN_INTERVAL_MS=5000

併發為 1 時，log 的順序才有意義。

技巧 3：用 Coding Agent 讀原始碼

對不熟 TypeScript 的團隊，這是最有效的方式【建議】：

# 在 OpenMAIC repo 中
claude

> Agent Session 啟動後就卡住不動，沒有任何 event。
> 請閱讀 lib/server/agent-runtime/runner.ts 與 store.ts，
> 說明 session 從 enqueue 到開始執行的完整流程，
> 並列出可能導致「卡住不動」的所有分支。

🎯 這比自己從頭讀 50 個 TypeScript 檔案快得多，也是第 8.6 節 案例中最有效的一招。

技巧 4：直接查資料庫觀察 Agent 狀態

docker compose exec postgres psql -U openmaic -d openmaic

-- 列出所有 table（官方無 schema 文件，先看有什麼）
\dt

-- 看某個 table 的結構
\d+ <table_name>

-- 找 session 相關的 table
SELECT table_name FROM information_schema.tables
WHERE table_schema = 'public' AND table_name LIKE '%session%';

⚠️ 只讀不寫。直接修改資料庫可能破壞 trigger 維護的一致性。

14.5 本章實務案例

案例：用開發環境驗證升級不會破壞既有課件

背景：某團隊有 45 門課在正式環境，要升級 OpenMAIC。最擔心的是「升級後舊課件打不開」（因為 DSL 是 versioned contract）。

驗證流程：

Step 1  從正式環境匯出 5 門代表性課程
        - 最舊的一門（v0.3.0 時代建的）
        - 用 PPTX 匯入的一門
        - 含 3D 互動的一門
        - 含 PBL 的一門
        - 最複雜的一門（80 張投影片）

Step 2  開發環境切到目標版本
        git checkout v1.1.0 && pnpm install && pnpm build

Step 3  逐一匯入 5 門課，檢查：
        □ 能開啟
        □ 投影片內容正確
        □ 互動元件正常
        □ 能播放（含語音）
        □ 能匯出 PPTX
        □ 能匯出 HTML
        □ 能用 Editor 編輯並儲存

Step 4  記錄結果，任一項失敗就暫緩升級並回報上游

實際發現：某次升級後，用 PPTX 匯入的課程有 3 張投影片的圖片位置跑掉。因為有這道驗證，在正式環境升級前就發現了，避免了 45 門課全部受影響。

✅ 建議把這個流程固化成升級 SOP 的一部分（見第 46 章）。

14.6 本章注意事項

⚠️ 注意事項 1：開發環境的 ALLOW_LOCAL_NETWORKS=true 不要帶到正式環境 這個設定放寬了 SSRF 防護。開發環境為了接本機 Ollama 需要它，正式環境只有在確實要接內網 Provider 時才開，並搭配出站防火牆。

⚠️ 注意事項 2：開發環境不要用正式資料 課件可能含企業敏感資訊。開發環境用測試資料，或用去識別化的副本。

📌 注意事項 3：pnpm dev 的 NODE_ENV 不是 production v1.0.1 有多個安全行為與 NODE_ENV 綁定（例如 persistence dev auth 在 production 會 fail-closed）。開發環境測起來正常，不代表正式環境行為相同。上線前務必用 pnpm build && pnpm start 測一次。

15. 環境變數完整說明【Official】

📌 本章所有變數皆來自官方 .env.example（2026-09-13 查證）。 本手冊不虛構任何環境變數。凡官方註解未說明的行為，一律標示「官方註解未說明」。

15.1 變數分類總覽

graph LR
    ENV[".env.local"]
    ENV --> C1["① LLM Providers<br/>19 組"]
    ENV --> C2["② TTS 語音合成"]
    ENV --> C3["③ ASR 語音辨識"]
    ENV --> C4["④ PDF 解析"]
    ENV --> C5["⑤ 圖片生成"]
    ENV --> C6["⑥ 影片生成"]
    ENV --> C7["⑦ 網頁搜尋"]
    ENV --> C8["⑧ Agent Runtime<br/>【Experimental】"]
    ENV --> C9["⑨ Feature Flags<br/>【Experimental】"]
    ENV --> C10["⑩ 伺服端持久化"]
    ENV --> C11["⑪ 存取控制與安全"]
    ENV --> C12["⑫ 網路與 Proxy"]
    ENV --> C13["⑬ Render Service"]
    ENV --> C14["⑭ 記錄與效能"]

    style C8 fill:#fff3e0,stroke:#f57c00
    style C9 fill:#fff3e0,stroke:#f57c00
    style C11 fill:#ffcdd2,stroke:#c62828

15.2 ① LLM Providers

每個 Provider 的欄位命名一致：{PROVIDER}_API_KEY、{PROVIDER}_BASE_URL、{PROVIDER}_MODELS。

📌 v1.0.1 新註冊的模型：DeepSeek v4 Flash Vision（視覺模型）已在 v1.0.1 納入內建模型註冊表。 這代表你不需自行加 DEEPSEEK_MODELS 條目即可選用；但若你原本已手動列舉過模型清單， 升級後請覆核 DEEPSEEK_MODELS 是否與內建註冊重複或衝突。

Amazon Bedrock（欄位不同）：

BEDROCK_REGION=
BEDROCK_MODELS=
AWS_BEARER_TOKEN_BEDROCK=          # 選用
BEDROCK_API_KEY=                   # 選用
BEDROCK_BASE_URL=                  # 選用
DEFAULT_MODEL=bedrock:us.anthropic.claude-sonnet-5   # 選用

其他 LLM 相關：

企業設定範例（走內部 Gateway）：

OPENAI_API_KEY=corp-gateway-token-xxxx
OPENAI_BASE_URL=https://ai-gateway.corp.example.com/v1
OPENAI_MODELS=gpt-5.5,gpt-5.5-mini,gpt-5.5-nano
DEFAULT_MODEL=openai:gpt-5.5
MODEL_ROUTES='{"maic-agent-driver":{"model":"openai:gpt-5.5","api":"openai-completions"}}'

15.3 ② TTS 語音合成

📌 *_ENABLED=false 這種「強制停用」變數是企業治理的好工具： 即使某人不小心設了 API Key，也可以用 TTS_OPENAI_ENABLED=false 從平台層擋掉。

15.4 ③ ASR 語音辨識

本地 FunASR 啟動範例【Official，README 提供】：

funasr-server --device cuda --model fun-asr-nano

15.5 ④ PDF 解析

⚠️ ALLOW_MINERU_CLOUD_FALLBACK 對企業是安全關鍵開關。 若不小心開啟，你上傳的 PDF 會在本地解析失敗時自動送到 mineru.net 雲端。 企業一律應明確設為不啟用（保持預設）。

15.6 ⑤ 圖片生成

📌 Repo 根目錄有 comfyui-setup-instructions.md，說明 ComfyUI 的設定方式。

15.7 ⑥ 影片生成

⚠️ 影片生成是成本最高的功能。企業導入初期建議全部不設定（等於停用）， 待有明確需求與預算後再開。見第 44 章。

15.8 ⑦ 網頁搜尋

⚠️ 搜尋 Provider 決定了 deep-research Skill 能不能用。 企業若禁止外部搜尋，全部不設定即可（或設 *_ENABLED=false 明確停用）。 若允許但要控管，建議自架 SEARXNG_BASE_URL。

15.9 ⑧ Agent Runtime【Experimental】

⚠️ 整組預設 OFF。官方在 .env.example 中標示為 Experimental。

這組參數怎麼調（企業建議）

graph TB
    Q["調整目標"]
    Q --> A["提高吞吐量"]
    Q --> B["降低資源占用"]
    Q --> C["加快故障接手"]

    A --> A1["MAX_CONCURRENT ↑<br/>（2 → 4~8）"]
    A --> A2["⚠️ 注意：<br/>成本與 DB 壓力同步上升"]

    B --> B1["MAX_CONCURRENT = 1"]
    B --> B2["SCAN_INTERVAL_MS ↑<br/>（1000 → 5000）"]

    C --> C1["LEASE_TTL_MS ↓<br/>（10000 → 5000）"]
    C --> C2["HEARTBEAT_MS ↓<br/>（2000 → 1000）"]
    C --> C3["⚠️ 注意：<br/>心跳太頻繁會增加 DB 負載"]

    style A2 fill:#fff3e0,stroke:#f57c00
    style C3 fill:#fff3e0,stroke:#f57c00

建議配置【建議】：

⚠️ LEASE_TTL_MS 必須明顯大於 HEARTBEAT_MS。 一般建議 LEASE_TTL >= 3 × HEARTBEAT（預設 10000 / 2000 = 5 倍，是合理的）。 設太接近會導致「還活著的 worker 被誤判為死亡」，任務被重複執行。

15.10 ⑨ Feature Flags【Experimental】

⚠️ 全部預設 OFF。NEXT_PUBLIC_* 為 build-time，改了必須重新 build。

企業建議的 Flag 配置【建議】：

15.11 ⑩ 伺服端持久化

⚠️ PERSISTENCE_ALLOW_INSECURE_DEV_AUTH=true 在正式環境是紅線。 詳見第 40 章。

15.12 ⑪ 存取控制與安全

15.13 ⑫ 網路與 Proxy

HTTP_PROXY=
HTTPS_PROXY=
NO_PROXY=localhost,127.0.0.1,.internal.example.com

15.14 ⑬ Render Service

這一組要先分清楚變數設在哪一邊，否則會設了沒有效果：

以下依 render-service/README.md 分為六組【Official】：

① 核心與資源配置

📌 預設併發是 1，這是刻意的。影片轉檔 = Chromium 逐格截圖 + FFmpeg 編碼，是記憶體與 CPU 雙重密集的工作。 盲目調高 RENDER_MAX_CONCURRENCY 的典型後果是 OOM Kill，而不是變快。調整前請先看第 42.5 節 的容量模型。

② 佇列與准入控制

③ 逾時

④ 預覽（POST /preview，v1.0.1 新增）

⑤ 分塊執行（選用）

⑥ 封存上限與程序隔離（安全關鍵）

🔒 這一組是資安審查可以直接引用的官方防護：

• 前四個變數構成 ZIP bomb 防護（檔案數 / 單檔 / 總量 / 壓縮比四重界限）。RENDER_MAX_COMPRESSION_RATIO=200 是其中最關鍵的一道 —— 典型 ZIP bomb 的壓縮比遠高於 200。
• RENDER_EGRESS_LOCKDOWN 預設為 true，代表官方的預設姿態就是「render-service 不該對外連網」。企業不應關閉它；若因自架字型或資產而想關閉，正確做法是把資產內嵌或掛載進容器，而不是開放 egress。詳見第 41.5 節。

15.15 ⑭ 記錄與效能

15.16 企業標準 .env.local 範本【建議】

以下為可直接套用的企業配置範本（請依實際環境調整）：

# ═══════════════════════════════════════════════════════════
#  OpenMAIC v1.0.1 —— 企業正式環境設定範本
#  最後更新：2026-09-13
#  維護者：Platform Team
#  ⚠️ 本檔含機密，權限 600，禁止 commit
# ═══════════════════════════════════════════════════════════

# ── ① LLM：走公司內部 Model Gateway ───────────────────────
OPENAI_API_KEY=__FROM_SECRET_MANAGER__
OPENAI_BASE_URL=https://ai-gateway.corp.example.com/v1
OPENAI_MODELS=gpt-5.5,gpt-5.5-mini
DEFAULT_MODEL=openai:gpt-5.5-mini
MODEL_ROUTES='{"maic-agent-driver":{"model":"openai:gpt-5.5","api":"openai-completions"}}'

# ── ② TTS：僅開內部自架，停用所有外部 ─────────────────────
TTS_VOXCPM_BASE_URL=http://voxcpm.internal.example.com:8000/v1
TTS_OPENAI_ENABLED=false
TTS_BROWSER_NATIVE_ENABLED=false

# ── ③ ASR：停用（本場景用不到）─────────────────────────────
ASR_OPENAI_ENABLED=false
ASR_BROWSER_NATIVE_ENABLED=false

# ── ④ PDF：自架 MinerU，禁止雲端 fallback ──────────────────
PDF_MINERU_BASE_URL=http://mineru.internal.example.com:8080
PDF_MINERU_BACKEND=pipeline
# ALLOW_MINERU_CLOUD_FALLBACK 保持未設定 = 不 fallback

# ── ⑤ 圖片：走內部 Gateway ─────────────────────────────────
IMAGE_OPENAI_API_KEY=__FROM_SECRET_MANAGER__
IMAGE_OPENAI_BASE_URL=https://ai-gateway.corp.example.com/v1

# ── ⑥ 影片生成：全部停用（成本控管）───────────────────────
VIDEO_GROK_ENABLED=false
VIDEO_KLING_ENABLED=false

# ── ⑦ 網頁搜尋：自架 SearXNG ──────────────────────────────
SEARXNG_BASE_URL=http://searxng.internal.example.com:8080
TAVILY_ENABLED=false
EXA_ENABLED=false
WEB_SEARCH_DOUBAO_ENABLED=false

# ── ⑧ Agent Runtime【Experimental】────────────────────────
OPENMAIC_AGENT_RUNTIME_ENABLED=true
OPENMAIC_AGENT_RUNTIME_MAX_CONCURRENT=4
OPENMAIC_AGENT_RUNTIME_SCAN_INTERVAL_MS=1000
OPENMAIC_AGENT_RUNTIME_HEARTBEAT_MS=2000
OPENMAIC_AGENT_RUNTIME_LEASE_TTL_MS=10000
OPENMAIC_AGENT_RUNTIME_MAX_ATTEMPTS=5
OPENMAIC_AGENT_TOOL_TIMEOUT_MS=600000

# ── ⑨ Feature Flags（build-time，改了要重 build）──────────
NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true
NEXT_PUBLIC_MAIC_EDITOR_ENABLED=true
NEXT_PUBLIC_MAIC_EDITOR_RENDERER_ENABLED=true
NEXT_PUBLIC_MAIC_PLAYBACK_RENDERER_ENABLED=true
NEXT_PUBLIC_ENABLE_PPTX_IMPORT=true
NEXT_PUBLIC_ENABLE_VIDEO_EXPORT=false
NEXT_PUBLIC_PI_CHAT_ENABLED=false
NEXT_PUBLIC_COURSEWARE_REFERENCE_ENABLED=false
OPENMAIC_ENABLE_VOCATIONAL=false
NEXT_PUBLIC_SHOW_VOCATIONAL_TEST_UI=false

# ── ⑩ 持久化 ──────────────────────────────────────────────
NEXT_PUBLIC_PERSISTENCE=1
DATABASE_URL=postgres://openmaic:__FROM_SECRET__@pg.internal:5432/openmaic
ASSET_S3_BUCKET=openmaic-assets
ASSET_BYTE_EGRESS=redirect
ASSET_COLLECTION_ENABLED=true
ASSET_COLLECTION_INTERVAL_MS=900000
ASSET_COLLECTION_GRACE_MS=86400000
# ⚠️ 絕不設定 PERSISTENCE_ALLOW_INSECURE_DEV_AUTH

# ── ⑪ 安全 ────────────────────────────────────────────────
# ACCESS_CODE 不設 —— 認證由前置 Reverse Proxy + SSO 負責
ALLOW_LOCAL_NETWORKS=true          # 因為要接內網 Gateway 與 MinerU
TRUST_PROXY_HEADERS=true           # 確實在信任的 Nginx 後方
ALLOWED_FRAME_ANCESTORS=https://portal.corp.example.com

# ── ⑫ Proxy ───────────────────────────────────────────────
NO_PROXY=localhost,127.0.0.1,.internal.example.com

# ── ⑬ Render Service（本例停用影片匯出）──────────────────
# RENDER_SERVICE_URL=http://render-service:9000

# ── ⑭ 記錄與效能 ──────────────────────────────────────────
LOG_LEVEL=info
LOG_FORMAT=json
PARALLEL_SCENE_CONCURRENCY=3
LLM_THINKING_DISABLED=false

⚠️ 範本中的 ALLOW_LOCAL_NETWORKS=true 需要配套： 開了這個等於放寬 SSRF 防護。必須同時在容器/主機層用出站防火牆限制 OpenMAIC 只能連到白名單內的內部服務。 詳見第 39.3 節。

15.17 本章實務案例

案例：環境變數的三層管理

問題：某企業有 dev / staging / prod 三套環境，環境變數各不相同，且含大量機密。用單一 .env.local 管理很快就混亂。

解法【建議】：分層管理。

config/
├── base.env              ← 三環境共通（Feature Flags、效能參數）
├── dev.env               ← 開發環境差異
├── staging.env           ← 測試環境差異
├── prod.env              ← 正式環境差異（不含機密）
└── secrets/              ← 不進版控，由 Secret Manager 注入
    ├── dev.secrets
    ├── staging.secrets
    └── prod.secrets

#!/usr/bin/env bash
# build-env.sh —— 組合環境變數
set -euo pipefail
ENV="${1:?用法: $0 <dev|staging|prod>}"

{
  echo "# 自動產生於 $(date -Iseconds)，請勿手動編輯"
  echo "# 環境：$ENV"
  echo ""
  cat "config/base.env"
  echo ""
  cat "config/${ENV}.env"
  echo ""
  # 機密由 Vault / AWS Secrets Manager 取得
  vault kv get -format=json "secret/openmaic/${ENV}" \
    | jq -r '.data.data | to_entries[] | "\(.key)=\(.value)"'
} > .env.local

chmod 600 .env.local
echo "已產生 .env.local（環境：$ENV）"

加上一道檢查：

#!/usr/bin/env bash
# check-env.sh —— 上線前的環境變數安全檢查
set -uo pipefail
ENV_FILE="${1:-.env.local}"
ERRORS=0

fail() { echo "  ❌ $1"; ERRORS=$((ERRORS+1)); }
ok()   { echo "  ✅ $1"; }

echo "=== 危險設定檢查 ==="
grep -q '^PERSISTENCE_ALLOW_INSECURE_DEV_AUTH=true' "$ENV_FILE" \
  && fail "PERSISTENCE_ALLOW_INSECURE_DEV_AUTH 在正式環境不得為 true" \
  || ok "PERSISTENCE_ALLOW_INSECURE_DEV_AUTH 未開啟"

grep -q '^ALLOW_MINERU_CLOUD_FALLBACK=true' "$ENV_FILE" \
  && fail "ALLOW_MINERU_CLOUD_FALLBACK 會把文件送到外部雲端" \
  || ok "MinerU 雲端 fallback 未開啟"

grep -qE '^ALLOWED_FRAME_ANCESTORS=\*' "$ENV_FILE" \
  && fail "ALLOWED_FRAME_ANCESTORS 設為 * 有 Clickjacking 風險" \
  || ok "ALLOWED_FRAME_ANCESTORS 未設為萬用"

echo ""
echo "=== 必要設定檢查 ==="
grep -q '^DEFAULT_MODEL=' "$ENV_FILE" && ok "DEFAULT_MODEL 已設" || fail "缺少 DEFAULT_MODEL"

if grep -q '^OPENMAIC_AGENT_RUNTIME_ENABLED=true' "$ENV_FILE"; then
  grep -q '^DATABASE_URL=' "$ENV_FILE"  && ok "DATABASE_URL 已設" || fail "Agent Runtime 已啟用但缺 DATABASE_URL"
  grep -q '^MODEL_ROUTES=' "$ENV_FILE"  && ok "MODEL_ROUTES 已設"  || fail "Agent Runtime 已啟用但缺 MODEL_ROUTES"
fi

echo ""
echo "=== 機密外洩檢查 ==="
git check-ignore -q "$ENV_FILE" && ok "$ENV_FILE 已被 gitignore" || fail "$ENV_FILE 未被 gitignore！"
[ "$(stat -c '%a' "$ENV_FILE")" = "600" ] && ok "檔案權限為 600" || fail "檔案權限應為 600"

echo ""
[ "$ERRORS" -eq 0 ] && echo "✅ 全部通過" || { echo "❌ 發現 $ERRORS 個問題"; exit 1; }

15.18 本章注意事項

⚠️ 注意事項 1：NEXT_PUBLIC_* 會進到前端 bundle，任何人都看得到 絕對不要把機密放在 NEXT_PUBLIC_ 開頭的變數裡。NEXT_PUBLIC_PERSISTENCE_TOKEN 這個變數本身就要謹慎——它會被編譯進前端。企業環境建議不使用它，改用前置 Proxy 認證。

⚠️ 注意事項 2：四個「危險開關」

變數	危險在哪
PERSISTENCE_ALLOW_INSECURE_DEV_AUTH=true	繞過 production 的認證保護
ALLOW_MINERU_CLOUD_FALLBACK=true	文件會被送到外部雲端
ALLOWED_FRAME_ANCESTORS=*	Clickjacking
TRUST_PROXY_HEADERS=true（未在 Proxy 後）	IP 偽造

建議把這四項納入上線檢查腳本（如 15.17 節範例）。

📌 注意事項 3：.env.example 是最權威的變數清單 每次升級後，第一件事就是 diff 新舊 .env.example：

git diff v1.0.1 v1.1.0 -- .env.example

這是發現新功能與新設定最快的方式。

16. Provider 設定實務【Official】

16.1 Provider 設定的三種企業策略

graph TB
    Q{"資料敏感度<br/>與法遵要求"}

    Q -->|"可用公有雲"| S1["策略 A<br/>直連公有 Provider"]
    Q -->|"需集中管控"| S2["策略 B<br/>企業 Model Gateway"]
    Q -->|"完全不出境"| S3["策略 C<br/>全內網本地模型"]

    S1 --> S1D["設定：<br/>OPENAI_API_KEY 等<br/>直接填官方 Key"]
    S2 --> S2D["設定：<br/>*_BASE_URL 指向<br/>內部 Gateway"]
    S3 --> S3D["設定：<br/>OLLAMA / VOXCPM /<br/>FUNASR / SEARXNG<br/>+ ALLOW_LOCAL_NETWORKS"]

    S1D --> R1["✅ 最簡單<br/>❌ 難管控成本<br/>❌ 資料出境"]
    S2D --> R2["✅ 成本歸戶<br/>✅ 集中稽核<br/>✅ 金鑰不散落<br/>⚠️ 需自建 Gateway"]
    S3D --> R3["✅ 資料不出境<br/>❌ 品質較低<br/>❌ 需 GPU 資源"]

    style S2 fill:#c8e6c9,stroke:#2e7d32,stroke-width:3px
    style R2 fill:#e8f5e9,stroke:#388e3c

✅ 本手冊建議大多數企業採用策略 B（Model Gateway）。 理由：它同時解決了金鑰散落、成本無法歸戶、無法稽核三個問題，而且未來要換 Provider 只需改 Gateway 設定，OpenMAIC 端不用動。

16.2 策略 A：直連公有 Provider

適用：PoC、非敏感內容、小團隊。

# 最簡：一組 Key
ANTHROPIC_API_KEY=sk-ant-xxxxx
DEFAULT_MODEL=anthropic:claude-sonnet-5

多 Provider 並存（讓不同任務走不同家）：

OPENAI_API_KEY=sk-xxxxx
OPENAI_MODELS=gpt-5.5,gpt-5.5-mini

ANTHROPIC_API_KEY=sk-ant-xxxxx
ANTHROPIC_MODELS=claude-opus-5,claude-sonnet-5

GOOGLE_API_KEY=xxxxx

DEFAULT_MODEL=openai:gpt-5.5-mini
MODEL_ROUTES='{"maic-agent-driver":{"model":"anthropic:claude-opus-5","api":"openai-completions"}}'

⚠️ MODEL_ROUTES 中 api 欄位的可用值，官方只給了 openai-completions 一個範例。 若要用 Anthropic 原生 API 格式，正確值為何官方資料未說明，需自行讀 lib/ai/ 確認。 保守做法：用 OpenAI 相容端點（多數 Provider 都提供）。

16.3 策略 B：企業 Model Gateway（建議）

架構

graph LR
    OM["OpenMAIC"] --> GW["企業 Model Gateway<br/>（LiteLLM / Kong AI /<br/>自建）"]

    GW --> F1["金鑰集中保管"]
    GW --> F2["成本歸戶<br/>（依 header 分部門）"]
    GW --> F3["速率限制"]
    GW --> F4["內容過濾"]
    GW --> F5["請求稽核 log"]
    GW --> F6["模型 fallback"]

    GW --> P1["OpenAI"]
    GW --> P2["Anthropic"]
    GW --> P3["Azure OpenAI"]
    GW --> P4["內部 Ollama"]

    style GW fill:#fff3e0,stroke:#f57c00,stroke-width:3px

OpenMAIC 端設定

# 把 Gateway 偽裝成 OpenAI 相容端點
OPENAI_API_KEY=openmaic-team-token-xxxxx
OPENAI_BASE_URL=https://ai-gateway.corp.example.com/v1
OPENAI_MODELS=gpt-5.5,gpt-5.5-mini,claude-sonnet-5,local-qwen

DEFAULT_MODEL=openai:gpt-5.5-mini
MODEL_ROUTES='{"maic-agent-driver":{"model":"openai:gpt-5.5","api":"openai-completions"}}'

# Gateway 在內網 → 需要這個
ALLOW_LOCAL_NETWORKS=true

關鍵技巧：OPENAI_MODELS 可以列出 Gateway 上的所有模型（包含 Anthropic、本地模型），因為對 OpenMAIC 而言它們都是「OpenAI 相容端點提供的模型」。Gateway 負責把請求轉發到真正的 Provider。

Gateway 端設定範例（以 LiteLLM 為例）【建議】

# litellm-config.yaml
model_list:
  - model_name: gpt-5.5
    litellm_params:
      model: openai/gpt-5.5
      api_key: os.environ/OPENAI_API_KEY

  - model_name: gpt-5.5-mini
    litellm_params:
      model: openai/gpt-5.5-mini
      api_key: os.environ/OPENAI_API_KEY

  - model_name: claude-sonnet-5
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY

  - model_name: local-qwen
    litellm_params:
      model: ollama/qwen3:32b
      api_base: http://ollama.internal:11434

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  database_url: os.environ/LITELLM_DB_URL

litellm_settings:
  success_callback: ["prometheus"]
  # 依 team 記錄成本
  set_verbose: false
  max_budget: 5000            # 每月上限（USD）
  budget_duration: 30d

📌 本目錄有《Kong API Gateway教學手冊》，若貴公司已有 Kong，可考慮用 Kong AI Gateway 插件而非另建 LiteLLM。

16.4 策略 C：全內網本地模型

適用：金融核心、政府、國防等絕對不能出境的場景。

# ── LLM：Ollama ────────────────────────────────
OLLAMA_BASE_URL=http://ollama.internal.example.com:11434/v1
OLLAMA_MODELS=qwen3:32b,deepseek-v3:latest
DEFAULT_MODEL=ollama:qwen3:32b
MODEL_ROUTES='{"maic-agent-driver":{"model":"ollama:qwen3:32b","api":"openai-completions"}}'

# ── TTS：VoxCPM（支援語音克隆）──────────────────
TTS_VOXCPM_BASE_URL=http://voxcpm.internal.example.com:8000/v1

# ── ASR：FunASR（僅 WAV）────────────────────────
ASR_FUNASR_BASE_URL=http://funasr.internal.example.com:8000/v1

# ── 圖片：Lemonade ─────────────────────────────
IMAGE_LEMONADE_BASE_URL=http://lemonade.internal.example.com:13305/v1

# ── 搜尋：自架 SearXNG（若允許）─────────────────
SEARXNG_BASE_URL=http://searxng.internal.example.com:8080

# ── PDF：自架 MinerU ───────────────────────────
PDF_MINERU_BASE_URL=http://mineru.internal.example.com:8080
PDF_MINERU_BACKEND=pipeline

# ── 必要：允許內網位址 ──────────────────────────
ALLOW_LOCAL_NETWORKS=true

# ── 明確停用所有外部 Provider ───────────────────
TTS_OPENAI_ENABLED=false
TTS_BROWSER_NATIVE_ENABLED=false
ASR_OPENAI_ENABLED=false
ASR_BROWSER_NATIVE_ENABLED=false
IMAGE_OPENAI_ENABLED=false
IMAGE_COMFYUI_ENABLED=false
VIDEO_GROK_ENABLED=false
VIDEO_KLING_ENABLED=false
TAVILY_ENABLED=false
EXA_ENABLED=false
WEB_SEARCH_DOUBAO_ENABLED=false

再加一層保險：出站防火牆【建議】

# 只允許 OpenMAIC 連到內部服務
iptables -A OUTPUT -o lo -j ACCEPT
iptables -A OUTPUT -d 10.0.0.0/8 -j ACCEPT       # 內網
iptables -A OUTPUT -p udp --dport 53 -j ACCEPT   # DNS
iptables -A OUTPUT -j REJECT                      # 其餘全擋

⚠️ 策略 C 的品質預期要放低。本地開源模型在「產出結構化課件 DSL」這種需要嚴格格式的任務上， 表現通常明顯遜於前沿的商用模型。導入前務必實測：

1. 生成一堂 5 頁的課，看 DSL 是否合法
2. 看投影片內容是否連貫
3. 看測驗題目品質

若品質不可接受，可考慮混合策略：大綱用本地模型（不含敏感細節）、內容也用本地模型，但接受品質妥協； 或者改變做法：不上傳敏感內容，只上傳已抽象化的描述，改用商用模型。

16.5 Provider 選型的成本／品質權衡【建議】

📌 MODEL_ROUTES 的階段名稱除 maic-agent-driver 外官方未說明， 因此上表的「分階段路由」目前只有 Agent Driver 這一個階段可以確定設定。 其餘階段走 DEFAULT_MODEL。若要更細緻的路由，需自行讀原始碼確認可用的階段名稱。

實務上的變通做法：把 DEFAULT_MODEL 設成便宜的中階模型， 只把 maic-agent-driver 路由到最強模型。這已經能拿到大部分的成本效益。

16.6 本章實務案例

案例：從直連改成 Gateway 的遷移

背景：某公司三個團隊各自導入 OpenMAIC，各用各的 OpenAI Key。三個月後財務發現 AI 支出無法歸戶，資安發現有 5 把 Key 散落在不同伺服器的 .env 中。

遷移步驟：

Week 1  建置 LiteLLM Gateway
        - 集中保管 3 家 Provider 的 Key
        - 為每個團隊發一把 virtual key
        - 設定每團隊月預算上限

Week 2  三個團隊逐一切換
        改動只有兩行：
          OPENAI_API_KEY=<team-virtual-key>
          OPENAI_BASE_URL=https://ai-gateway.corp/v1
        加一行：
          ALLOW_LOCAL_NETWORKS=true

Week 3  撤銷舊 Key
        - 在 Provider 主控台 revoke 所有直連 Key
        - 清除各伺服器 .env 中的殘留
        - 加入 CI secret scan 防止再犯

成果：

🎯 「OpenMAIC 端只改兩行」正是 Provider Neutral 架構的價值。

案例：內網環境的 PoC 結果（品質實測）

某金融業做了策略 C 的 PoC，實測三種配置生成同一堂課（主題：「Spring Security 的認證流程」，5 頁）：

該公司的決定：

「採混合策略。不含客戶資料的一般技術課程（Spring、Java、架構模式）用公有雲模型； 含內部系統細節的課程（核心帳務架構、Legacy 系統）用本地 Qwen3-32B，接受品質妥協並加大人工覆核比重。」

這個決定的關鍵：分級，而不是一刀切。詳見第 39.4 節 的資料分級設計。

16.7 本章注意事項

⚠️ 注意事項 1：*_MODELS 沒設會怎樣？官方資料未說明 多數 Provider 的 *_MODELS 在 .env.example 中預設是空的。空值時是「自動探測」還是「不可用」，官方註解未說明。建議明確列出你要用的模型，避免不確定行為。

⚠️ 注意事項 2：Gateway 在內網就一定要 ALLOW_LOCAL_NETWORKS=true 這是 v1.0.1 最常見的「昨天還能跑今天不行」原因。升級到 v1.0.1 後，所有指向內網的 Provider URL 都會被拒絕，除非明確開啟。

⚠️ 注意事項 3：MODEL_ROUTES 是 JSON 字串，引號很容易搞錯 在 .env 檔中：

MODEL_ROUTES='{"maic-agent-driver":{"model":"openai:gpt-5.5","api":"openai-completions"}}'

外層用單引號、內層用雙引號。在 docker-compose 的 environment 區塊中則要注意 YAML 的跳脫規則。設完後務必檢查 log 有沒有 JSON parse error。

📌 注意事項 4：換 Provider 後要重測課件品質 不同模型產出的 DSL 品質差很多。換 Provider 後，用同一個 Prompt 重新生成一次既有課程，比對差異，再決定是否全面切換。

17. Classic Generator：兩階段課程生成管線【Official】

17.1 What：什麼是 Classic Generator

Classic Generator 是 OpenMAIC 最基本、也不需要任何實驗性 Flag 就能用的功能：

輸入一個主題或一份文件 → 一鍵產出完整互動課堂。

它與 Pro Workbench 的差別：

✅ 企業導入建議：先用 Classic Generator 跑通，再考慮 Pro Workbench。 Classic Generator 沒有實驗性風險，且能驗證「模型品質是否可接受」這個最關鍵的問題。

17.2 Why：為什麼要分兩階段

官方設計【Official】：先產 outline（大綱），再產 scene content（場景內容）。

flowchart LR
    IN["輸入<br/>主題 / 文件"] --> S1

    subgraph S1["階段一：Outline"]
        A1["理解輸入"] --> A2["規劃章節結構"]
        A2 --> A3["決定每章要點"]
    end

    S1 --> CHK{"人工檢視<br/>大綱"}
    CHK -->|"不滿意"| EDIT["編輯大綱"]
    EDIT --> CHK
    CHK -->|"OK"| S2

    subgraph S2["階段二：Scene Content"]
        B1["逐場景生成"] --> B2["投影片內容"]
        B2 --> B3["講稿 / 語音"]
        B3 --> B4["測驗 / 互動元件"]
    end

    S2 --> OUT["完整課程"]

    style CHK fill:#fff3e0,stroke:#f57c00,stroke-width:3px
    style S1 fill:#e3f2fd,stroke:#1976d2
    style S2 fill:#e8f5e9,stroke:#388e3c

為什麼這個「人工檢視大綱」的關卡如此重要：

🎯 這對企業成本控制的意義很大。一堂 40 分鐘的課， 大綱階段的 token 成本可能只佔全部的 3–5%。 在這個階段攔截錯誤，等於用 5% 的成本保護 95%。

企業實務規則【建議】：大綱沒看過就不准往下生成。

17.3 How：完整操作流程

步驟 1 — 選擇輸入方式

✅ 企業場景幾乎一律用「主題 + 文件」。純主題產出的內容是「網路上的通用說法」， 對企業內訓價值有限，甚至可能與公司實際做法衝突。

步驟 2 — 檢視與編輯大綱

生成大綱後，務必逐項檢視：

大綱審查清單
□ 章節順序是否符合認知順序（由淺入深、有前置知識鋪陳）
□ 有沒有遺漏關鍵主題
□ 有沒有加入不該有的主題（模型自行發揮）
□ 章節粒度是否合適（一章 3–8 分鐘）
□ 術語是否使用公司慣用說法
□ 有沒有把「舊做法」當成「現行做法」
□ 總長度是否合理（建議一堂 30–50 分鐘）

常見需要修正的地方（實務經驗）：

步驟 3 — 生成場景內容

確認大綱後，逐場景生成。相關設定：

PARALLEL_SCENE_CONCURRENCY=3    # 平行生成 3 個場景；0 或未設 = 序列

⚠️ PARALLEL_SCENE_CONCURRENCY 調高不會省錢，只會更快。 但太高會撞上 Provider 的 rate limit（429），反而更慢甚至失敗。 建議值：3–5。若用內部 Gateway 且有充足配額，可調到 8。

步驟 4 — 檢視與修正內容

用 MAIC Editor 修正。必檢項目：

內容審查清單
□ 技術細節是否正確（版本號、API 名稱、參數）
□ 程式碼範例是否可執行
□ 公司專有名詞是否正確
□ 有沒有「看起來很對但其實錯」的內容（最危險）
□ 測驗題的正確答案是否真的正確
□ 互動元件是否正常運作
□ 圖片是否恰當（生成圖片有時會出現無意義的文字）

⚠️ 測驗題是最容易出錯的地方。實測經驗： LLM 生成的測驗題，約 10–15% 的「正確答案」是錯的，或選項有多個都對。 每一題都要人工驗證。

17.4 Example：一個完整的企業建課範例

目標：為新進後端工程師建立「訂單服務 API 設計規範」課程。

輸入準備

上傳文件：
  1. order-service-openapi.yaml     （API 規格）
  2. api-design-guideline.md        （公司 API 設計規範）
  3. error-code-catalog.md          （錯誤碼目錄）

主題描述（Prompt）：

為新進後端工程師建立「訂單服務 API 設計規範」教學課程。

【學習對象】
有 1–3 年 Java / Spring Boot 經驗，剛加入訂單服務團隊的工程師。
已具備 REST 基本概念，不需要從頭教 HTTP。

【技術環境】
Java 21 + Spring Boot 3.2 + PostgreSQL 16
API 走 RESTful，文件用 OpenAPI 3.1
認證使用 Keycloak（OAuth2 / OIDC）

【課程目標】
上完後，學員能夠：
1. 說出本團隊 API 設計的 7 條硬性規範，並解釋每條的理由
2. 正確使用錯誤碼目錄，不自行發明錯誤碼
3. 為一個新需求設計出符合規範的 API 端點
4. 在 Code Review 中指出違反規範的地方

【課程限制】
- 全部內容必須依據上傳的三份文件，不要引入文件外的業界做法
- 若文件中沒有規定的部分，明確標示「本團隊未規範」，不要自行補完
- 每個規範都要有「正例」與「反例」的程式碼對照
- 總長度控制在 40 分鐘以內

【互動要求】
- 每講完 2 條規範，加一題測驗
- 最後加一個實作場景：給一個需求，讓學員設計 API（PBL）

大綱審查（實際發生的修正）

生成的大綱有 8 章。人工審查後做了 4 項修正：

📌 第 4 項是最重要的修正。模型很喜歡「補完」它認為應該有的章節。 只要不在來源文件中，就刪掉——否則你會教出「公司根本沒有的規範」。