Open Design 教學手冊

版本：v0.13.0「Stay in Flow」（對應 Open Design 0.13.0）
最後更新：2026-07-02
適用對象：資深工程師、前後端開發人員、UI/UX 設計師、AI 架構師、平台維運與採購決策者
授權：Apache-2.0（部分內建 Plugin／Skill 沿用原始授權，詳見附錄 A）
文件等級：企業標準技術白皮書

目錄

• 1. 概述與背景
  • 1.1 Open Design 是什麼
  • 1.2 為何需要 Open Design
  • 1.3 市場產品比較全景
  • 1.4 BYOK 與 AMR 雙軌設計理念
  • 1.5 適用場景
  • 1.6 開源基石與技術譜系
• 2. 系統整體架構設計
  • 2.1 高階架構圖
  • 2.2 技術組成
  • 2.3 AI Agent 整合架構
  • 2.4 設計生成流程
  • 2.5 Prompt Stack 組合機制
  • 2.6 專案目錄結構與資料治理
  • 2.7 與企業架構整合
• 3. 安裝與環境建置
  • 3.1 系統需求
  • 3.2 安裝路徑總覽
  • 3.3 首次啟動與驗證
  • 3.4 BYOK 設定
  • 3.5 桌面版安裝
  • 3.6 容器化與雲端部署
  • 3.7 多語系與國際化
• 4. 核心機制解析
  • 4.1 Skill 驅動架構
  • 4.2 HTML PPT Studio 技能體系
  • 4.3 Design System 設計系統
  • 4.4 Visual Directions 視覺方向
  • 4.5 Anti-AI-Slop 防劣質機制
  • 4.6 媒體生成能力
  • 4.7 Craft 設計參考系統
  • 4.8 OD Library 與使用者資產庫
• 5. Plugin 系統與 MCP 整合
  • 5.1 Plugin 市集架構與定位
  • 5.2 官方 Plugin 六大分類
  • 5.3 Plugin CLI 操作
  • 5.4 建立與貢獻 Plugin
  • 5.5 MCP Server 整合
  • 5.6 Open Design AMR 模型路由器
• 6. AI 開發流程（企業級）
  • 6.1 Web Application 開發
  • 6.2 舊系統逆向工程
  • 6.3 Framework 升級
  • 6.4 企業文件與報表生成
• 7. Prompt Engineering
  • 7.1 Prompt 結構設計原則
  • 7.2 高品質 Prompt 範本
  • 7.3 Prompt 最佳化策略
• 8. 設計品質控管機制
  • 8.1 五維度自我審核機制
  • 8.2 P0 / P1 / P2 Checklist
  • 8.3 Artifact Lint API
  • 8.4 Slop 黑名單
• 9. 輸出與整合
  • 9.1 匯出格式
  • 9.2 CI/CD 整合
  • 9.3 Git / PR 開發流程整合
  • 9.4 Claude Design ZIP 匯入
• 10. 系統維護與營運
  • 10.1 日誌與監控
  • 10.2 錯誤處理
  • 10.3 Skill 管理
  • 10.4 Design System 更新策略
  • 10.5 資料備份與復原
• 11. 系統升級策略
  • 11.1 Open Design 升級流程
  • 11.2 相容性管理
  • 11.3 版本控管策略
  • 11.4 回滾機制
• 12. 團隊導入建議
  • 12.1 開發團隊使用方式
  • 12.2 設計師協作模式
  • 12.3 AI Agent 分工策略
  • 12.4 SSDLC 整合方式
• 13. 最佳實踐（Best Practices）
• 14. 常見問題與風險
• 15. 與企業架構深度整合
  • 15.1 微服務架構整合
  • 15.2 Clean Architecture 對應
  • 15.3 前端框架整合（Vue / React）
  • 15.4 後端框架整合（Spring Boot / FastAPI）
• 16. 檢查清單（Checklist）
• 附錄 A：參考來源與技術譜系
• 附錄 B：Roadmap 發展藍圖

1. 概述與背景

1.1 Open Design 是什麼

Open Design（OD）是由 nexu-io 團隊主導開發的開源設計生成平台，定位為 Anthropic Claude Design 的全功能開源替代方案。經過近兩個月的高速迭代，OD 已從單純的「Web app + 本地 daemon」演進為原生桌面應用、MCP 整合、Plugin 市集三翼並進的完整平台，但核心設計原則維持不變：

• Local-first：所有專案資料、對話紀錄、SQLite 資料庫、Agent 執行時資料均保留在本機由 daemon 管理的資料根目錄內，完全不依賴外部雲端儲存；實際路徑規則由官方 AGENTS.md 的「Daemon data directory contract」統一定義，並以環境變數 OD_DATA_DIR 解析，本文件不重複列舉具體路徑，企業導入時請直接以官方文件為準
• BYOK（Bring Your Own Key）：不內建任何 AI 模型或推理引擎。使用者透過已安裝的 Coding Agent CLI、自行提供 OpenAI 相容 API Key，或改用官方代管的 AMR（Agentic Model Router） 服務驅動生成
• Skill / Plugin 雙層驅動：底層仍採用 Claude Code 的 SKILL.md 檔案慣例；v0.8.0 起在其上疊加一層可市集化、可攜式的 Plugin 系統，讓設計能力得以被打包、發布、版本化與跨 Agent 複用
• Agent-agnostic：daemon 啟動時自動掃描 PATH，支援 22 種主流 Coding Agent CLI 自動偵測與切換；也可透過 od mcp install <agent> 讓外部 Agent 以 MCP 協定直接呼叫 OD，不綁定任何特定廠商

專案基本資訊（2026-07-02 查證）：

與 v0.2.0 版本的關鍵差異：規模上，Skill 由 31 個成長至 100+、Design System 由 129 個成長至 150 個、Coding Agent CLI 由 13 種成長至 22 種；產品形態上新增了原生桌面應用、261 個官方 Plugin 市集、MCP Server 整合與官方模型路由服務 AMR。本文件即依此基準全面改版。

1.2 為何需要 Open Design

2026 年 4 月，Anthropic 發布 Claude Design，向業界展示了 LLM 從生成文字轉向直接生成設計產物（artifact）的全新範式——使用者輸入簡報，AI 直接產出可渲染的 HTML 設計稿，一度掀起熱烈討論。然而此產品存在根本性限制：

1. 封閉原始碼：無法檢視、修改或自行託管
2. 付費門檻：需要 Pro / Max / Team 等級訂閱方可使用
3. 廠商鎖定：僅支援 Anthropic 自家模型，無法接入其他 LLM
4. 無法私有部署：無法在企業內網、私有雲、容器平台或自架伺服器部署
5. 技能不可擴充：內建技能為封閉系統，無法新增自定義技能或安裝第三方能力
6. 設計系統不透明：無法匯入企業自有品牌規範

Open Design 提出了「相同的設計迴圈品質，零鎖定」的方案：同一套發現簡報 → 鎖定方向 → 串流產出 artifact → 批評 → 交付的迴圈，開放成一套 Agent 已讀寫得懂的技能／設計系統／Plugin 檔案系統。它不重新發明 Agent——市面上最強的 Coding Agent 早已在使用者的筆電上執行——而是把它們接進這套工作流程；可以在本機執行、以桌面應用形式安裝、透過 MCP 掛進既有 Agent，也能以容器化方式部署到企業內部或雲端環境，並在每一層都保持 BYOK。隨著市場上同時出現了 Figma 這類老牌設計工具、以及 Lovable / v0 / Bolt 等雲端「一句話生網站」工具的競爭，Open Design 的差異化定位也從單純對標 Claude Design，擴展為「開放原始碼、可自架、Agent 原生」三個維度的整體訴求。

1.3 市場產品比較全景

截至 2026-07-02，AI 設計生成賽道上主要有四類代表性產品，定位與能力差異顯著：

與舊版比較表的差異：早期版本的比較基準是 open-codesign（OpenCoworkAI/open-codesign），該專案作為 Open Design UX 設計的「北極星」，其串流 artifact 迴圈、沙箱 iframe 預覽、即時 Agent 面板等體驗仍深刻影響 OD 的產品設計，因此保留在附錄 A 的技術血緣表中；但隨著 Open Design 自身生態擴張，官方現行的比較敘事已改為對標 Claude Design、Figma、Lovable/v0/Bolt 這類更主流的市場玩家。

1.4 BYOK 與 AMR 雙軌設計理念

BYOK（Bring Your Own Key）仍是 Open Design 的核心設計哲學，從根本上實現「零廠商鎖定」；v0.9.0 起官方額外推出 AMR（Agentic Model Router，官方代管模型路由服務），兩者並存，企業可依治理需求擇一或並用：

┌───────────────────────────────────────────────────┐
│                Open Design (OD)                    │
│                                                     │
│  不內建 AI 模型 · 不綁定特定廠商 · 不強制付費帳號     │
│                                                     │
│  路徑一：BYOK（自帶金鑰 / CLI）                       │
│  ├── 已安裝的 Coding Agent CLI                       │
│  │   （claude / codex / gemini / cursor-agent …）    │
│  │   daemon 自動偵測 PATH，無需設定                   │
│  └── 或 OpenAI 相容 / Anthropic / Azure / Google     │
│      / Ollama 等 API Key                             │
│      POST /api/proxy/{provider}/stream               │
│      SSE 串流直通 + 逐端點 SSRF 防護                  │
│                                                     │
│  路徑二：Open Design AMR（官方代管，選用）             │
│  └── 一次儲值即可使用 20+ 旗艦模型，依實際 token       │
│      用量計費，零額外設定                             │
└───────────────────────────────────────────────────┘

BYOK 的兩條子路徑：

安全機制：

• API Key 僅存於本機環境變數或應用內加密設定，不會回傳至第三方伺服器
• BYOK Proxy 對每個供應商端點皆內建 SSRF 防護：拒絕 loopback（127.0.0.0/8、::1）、link-local（169.254.0.0/16）、RFC1918 私有位址與 CGNAT 網段
• 特定模型（如 MiMo）自動調整工具呼叫參數，避免工具 schema 在自由生成時異常
• 本機／daemon 執行時資料一律排除在版本控制之外，實際路徑規則請以官方 AGENTS.md 為準，不建議在企業內部文件中硬編路徑
• 生產環境使用環境變數注入，不硬編碼 Key；透過 MCP 對外開放時，連線憑證與即時預覽路由一律維持僅限本機（loopback-only）

1.5 適用場景

1.6 開源基石與技術譜系

Open Design 站在多個開源專案的肩膀上，各自貢獻了不同的核心能力：

其他技術來源：

2. 系統整體架構設計

2.1 高階架構圖

graph TB
    subgraph Client ["用戶端形態"]
        DesktopApp["Electron 桌面殼層（macOS / Windows / Linux）"]
        Browser["瀏覽器（Next.js 16 Web）"]
        ExtAgent["外部 Coding Agent（透過 MCP）"]
    end

    subgraph Daemon ["本地 Daemon（Express + SQLite，唯一特權行程）"]
        API["/api/* 路由"]
        SkillLoader["Skill 載入器"]
        DSLoader["Design System 載入器"]
        PluginRuntime["Plugin Runtime（市集 / 安裝 / 套用）"]
        AgentDetector["Agent PATH 偵測器"]
        BYOKProxy["BYOK Proxy（逐端點 SSRF Guard）"]
        MCPServer["MCP stdio Server"]
        DB["daemon 資料根目錄：projects / messages / templates / plugin state / automation state"]
        MediaPipeline["媒體生成管線"]
    end

    subgraph Agents ["Coding Agent CLIs（22 種）"]
        Claude["Claude Code"]
        Codex["Codex CLI"]
        Cursor["Cursor Agent"]
        Copilot["GitHub Copilot CLI"]
        OpenClaw["OpenClaw / Antigravity"]
        Others["Gemini / OpenCode / Qwen / Hermes / Kimi / Pi / Kiro / Vibe / Cline / Trae ..."]
    end

    subgraph External ["外部服務"]
        AMR["Open Design AMR（官方模型路由）"]
        Providers["Anthropic / OpenAI / Azure / Google / Ollama 等"]
    end

    DesktopApp --> Daemon
    Browser -->|"/api/*"| Daemon
    ExtAgent -->|"MCP stdio"| MCPServer
    API -->|"spawn(cli, args, {cwd})／ACP"| Agents
    BYOKProxy -->|"/api/proxy/{provider}/stream"| Providers
    BYOKProxy -.->|"零設定代管"| AMR
    Agents -->|"讀寫 daemon 管理的專案資料"| DB

資料根目錄的實際路徑規則由官方 AGENTS.md 的「Daemon data directory contract」唯一定義（以環境變數 OD_DATA_DIR 解析），本文件不重複列舉具體路徑，企業導入時請以官方文件為準。

2.2 技術組成

2.3 AI Agent 整合架構

Open Design 支援兩種整合模式：① daemon 啟動時掃描 PATH，自動偵測並以 spawn / ACP 驅動已安裝的 Coding Agent CLI；② 反向透過 od mcp install <agent> 把 OD 安裝成該 Agent 的 MCP Server，讓外部 Agent 主動呼叫 OD 的工具。截至 v0.13.0，官方支援的 CLI／平台已達 22 種，以下列出代表性項目：

兩種整合模式的差異：

新增 CLI 適配器：只需在 apps/daemon/src/agents.ts 中增加一個適配器條目與對應的串流解析器，詳細合約見官方 docs/agent-adapters.md。

2.4 設計生成流程

sequenceDiagram
    participant User as 使用者
    participant Web as Next.js Web
    participant Daemon as Express Daemon
    participant Agent as Coding Agent CLI
    participant FS as 檔案系統

    User->>Web: 輸入設計簡報 + 選擇 Skill + Design System
    Web->>Daemon: POST /api/chat（SSE）
    Daemon->>Daemon: 組合 Prompt Stack
    Note over Daemon: DISCOVERY + identity charter<br/>+ DESIGN.md + SKILL.md<br/>+ project metadata<br/>+ skill side files
    Daemon->>Agent: spawn(cli, args, {cwd: 管理的專案工作目錄})
    Agent->>User: Turn 1: <question-form> 互動表單
    User->>Agent: 填寫表單（surface / audience / tone）
    Agent->>Agent: Turn 2: 品牌資產擷取 / 方向選擇 / URL 或 Figma 匯入
    Agent->>FS: Read template.html, references/*.md，套用已安裝 Plugin 的 inputs
    Agent->>Agent: TodoWrite 計畫 → 串流至 UI
    Agent->>Agent: 5 維度自我批評（≥3/5 才通過）
    Agent->>Web: <artifact> 串流渲染
    Web->>User: iframe 沙箱預覽
    User->>Web: 下載 HTML / PDF / PPTX / MP4 / ZIP

註：MCP 整合模式下，改由外部 Agent 直接呼叫 od get-file／od plugin apply 等指令讀寫同一份專案資料，流程精神相同，僅發起端互換。

2.5 Prompt Stack 組合機制

Open Design 的核心競爭力在於 Prompt Stack——它不是簡單的 “system + user”，而是多層可組合的指令堆疊：

DISCOVERY directives     ← Turn-1 表單、Turn-2 品牌分支（含 URL / Figma / 截圖匯入）、TodoWrite、5 維批評
+ identity charter       ← OFFICIAL_DESIGNER_PROMPT、anti-AI-slop、junior-pass
+ active DESIGN.md       ← 150 個系統可選
+ active SKILL.md        ← 100+ 個技能可選
+ plugin inputs          ← 若透過 `od plugin apply` 呼叫，帶入 od.inputs[] 參數
+ project metadata       ← kind、fidelity、speakerNotes、animations
+ skill side files       ← 自動注入：read assets/template.html + references/*.md
+ DECK_FRAMEWORK_DIRECTIVE  ← （僅 deck 模式：nav / counter / scroll / print）

每一層都是可編輯的檔案。閱讀官方 apps/web/src/prompts/system.ts 與 apps/web/src/prompts/discovery.ts 可查看實際合約。

2.6 專案目錄結構與資料治理

理解 Open Design 的原始碼佈局對企業導入和二次開發至關重要。以下依官方 AGENTS.md 核對後的頂層結構：

open-design/
├── README.md                      ← 主文件（13 種語言切換）
├── QUICKSTART.md                  ← 執行 / 建置 / 部署指南
├── CONTRIBUTING.md                ← 貢獻指南（含多語版本）
├── AGENTS.md                      ← 全репо唯一權威的 Agent 行為與資料路徑約定（含 Daemon data directory contract）
├── MAINTAINERS.md                 ← 維護者規則與 Fellow 計畫
├── TRANSLATIONS.md                ← 多語文件翻譯指引
├── package.json                   ← pnpm workspace 定義
│
├── apps/
│   ├── daemon/                    ← Node + Express，唯一特權伺服器與 `od` CLI／MCP server
│   ├── web/                       ← Next.js 16 App Router + React 客戶端
│   ├── desktop/                   ← Electron 桌面殼層（透過 sidecar IPC 探索 web URL）
│   └── packaged/                  ← 封裝版 Electron 進入點（自動更新、`od://` 協定）
│
├── packages/
│   ├── contracts/                 ← 共用的 web/daemon 應用程式合約
│   ├── sidecar-proto/             ← Open Design sidecar 業務協議
│   ├── sidecar/                   ← 泛用 sidecar 執行時元件
│   └── platform/                  ← 泛用行程／作業系統元件
│
├── skills/                        ← Agent 任務中呼叫的功能型技能（utility／brief／packager 等）
├── design-templates/              ← 渲染型錄：prototype / deck / image / video / audio 模板（100+ Skill 的主體）
├── design-systems/                ← 150 個品牌級 DESIGN.md 系統
├── plugins/
│   ├── _official/                 ← 261 個官方 Plugin（scenarios / image-templates / video-templates / design-systems / atoms / examples）
│   ├── community/                 ← 社群貢獻 Plugin
│   ├── registry/                  ← 發佈流程
│   └── spec/                      ← Plugin 規格書、Agent 開發指南
│
├── craft/                         ← 品牌無關的設計參考，可透過 `od.craft.requires` 選用
├── deploy/                        ← Docker Compose / Sealos 部署範本
├── mocks/                         ← 各 CLI 的錄製回放假 Agent，供測試與自我驗證
├── prompt-templates/              ← 即用媒體 prompt 模板（image / video / audio）
├── scripts/
│   └── sync-design-systems.ts     ← 重新匯入上游 awesome-design-md
│
├── docs/                          ← spec.md / architecture.md / skills-protocol.md / agent-adapters.md / roadmap.md / references.md 等
├── e2e/                           ← Playwright UI + Vitest 整合測試
├── tools/
│   ├── dev/                       ← 本地開發生命週期控制（`pnpm tools-dev`）
│   ├── pack/                      ← 封裝建置／啟停／更新通道控制（`pnpm tools-pack`）
│   └── serve/                     ← 固定測試資料的本地服務（`pnpm tools-serve`）
│
└──（daemon 執行時資料根目錄，由 OD_DATA_DIR 解析，gitignored）
    ← 內容包含 SQLite、專案工作目錄、Artifact、MCP 設定、Automation／Plugin 狀態、連接器憑證等
    ← 具體路徑規則、例外情況與「已知不得沿用的舊路徑」清單，一律以官方 AGENTS.md「Daemon data directory contract」為準

治理提醒：官方 AGENTS.md 明確禁止任何文件（含企業內部 SOP）在說明資料路徑時臆造或沿用具體範例路徑，一律指向 OD_DATA_DIR 這個唯一真實來源。企業撰寫內部維運手冊時，建議直接連結官方 AGENTS.md 而非自行複製路徑範例，以免版本落後後失真。

2.7 與企業架構整合

graph LR
    subgraph Enterprise ["企業系統"]
        FE[前端：Vue / React]
        BE[後端：Spring Boot / FastAPI]
        DB[(DB: Oracle / PostgreSQL)]
        MQ[MQ: Kafka / RabbitMQ]
    end

    subgraph OD ["Open Design"]
        UIGen[UI Prototype 生成]
        DashGen[Dashboard 生成]
        DocGen[文件生成]
        PluginPipe[Plugin 驅動的 CI/CD 管線]
    end

    FE -.->|設計稿交付| UIGen
    BE -.->|API 規格輸入| DashGen
    PluginPipe -.->|od plugin apply / validate| BE
    DB -.->|Schema 參考| DashGen
    DocGen -.->|Runbook / Spec| BE

實務建議：Open Design 產出的是設計原型（HTML artifact），不是生產級前端程式碼。企業應將 OD 定位為「設計階段工具」，產出的 artifact 作為前端開發的視覺規格。

3. 安裝與環境建置

3.1 系統需求

重要更新：官方 AGENTS.md 明訂 macOS、Linux、WSL2 為主要支援路徑，Windows 原生僅為 best-effort（已知摩擦點記錄於歷史 issue #10、#96、#100、#203、#315）。企業若以 Windows 為主要開發環境，建議優先評估「桌面應用（免建置）」或「WSL2 + 原始碼建置」，而非原生 Windows 建置路徑。

Windows 原生建置注意：corepack enable 在 Windows 上可能因權限不足（無法寫入 Program Files 的 shim）而報 EPERM，建議改用 npm install -g pnpm@10.33.2；better-sqlite3 在 win32 + Node 24 無預編譯二進位，pnpm install 會透過 node-gyp 現場編譯（需要 Visual Studio Build Tools 2022+，約需 2 分鐘），這是預期行為而非版本不相容。

3.2 安裝路徑總覽

Open Design 提供四條安裝路徑，企業可依治理需求與團隊技術背景擇一或並用：

以下以「④ 原始碼建置」為例，說明完整流程（其餘三條路徑詳見 3.5、3.6）：

Step 1：安裝 Node.js 24

# 使用 fnm（推薦）
fnm install 24
fnm use 24
node --version  # v24.x.x

# 或使用 nvm
nvm install 24
nvm use 24

Step 2：啟用 corepack 並安裝 pnpm

corepack enable
corepack pnpm --version   # 應印出 10.33.2

# Windows 若 corepack enable 出現 EPERM，改用：
npm install -g pnpm@10.33.2

Step 3：Clone 專案

git clone https://github.com/nexu-io/open-design.git
cd open-design

Step 4：安裝依賴

pnpm install

Step 5：啟動開發環境

pnpm tools-dev run web
# 終端機會印出 web URL，在瀏覽器中開啟

常用 Lifecycle 指令

自訂埠號

pnpm tools-dev run web --daemon-port 4000 --web-port 3001

Namespace 隔離

pnpm tools-dev run web --namespace beta
# 不同 namespace 使用彼此隔離的 daemon 資料根目錄，具體路徑規則見官方 AGENTS.md

tools-dev --namespace <name> 本身只負責 sidecar 執行時／記錄／IPC 的命名隔離；若開發環境需要完全獨立的 daemon 資料根目錄，需額外顯式傳入 OD_DATA_DIR 環境變數給 daemon 行程。

3.3 首次啟動與驗證

首次載入時，系統會自動執行：

1. 偵測 Agent CLI：掃描 PATH，找到已安裝的 Coding Agent 並自動選擇；桌面應用另會偵測可用的 MCP 安裝目標
2. 載入資源：100+ Skills（含 design-templates/ 渲染型錄）＋ 150 個 Design Systems ＋ 261 個官方 Plugin
3. 歡迎對話框：可貼上 API Key（僅 BYOK 路徑需要）或直接以 AMR 一鍵登入
4. 自動建立 daemon 資料根目錄：由 OD_DATA_DIR 解析，內含 SQLite、專案工作目錄、Artifact 等，具體結構請參照官方 AGENTS.md，本文件不重複列舉

驗證步驟：

1. 開啟桌面應用，或在瀏覽器開啟 web URL
2. 選擇一個 Skill（如 web-prototype）
3. 選擇一個 Design System（如 default）
4. 輸入簡單的設計簡報（如「一個咖啡店的首頁」）
5. 觀察互動表單出現 → 填寫 → TodoWrite 串流 → artifact 渲染

3.4 BYOK 設定

方式一：使用已安裝的 Coding Agent CLI（推薦）

如果你已安裝 Claude Code、Gemini CLI 等，daemon 會自動偵測，無需額外設定。

# 確認 CLI 已安裝且在 PATH 中
which claude    # macOS/Linux/WSL2
where claude    # Windows

方式二：使用相容 API（多供應商顯式路由）

在設定面板中依供應商填入對應端點，daemon 依 POST /api/proxy/{provider}/stream 分流：

支援的 Provider／端點：

• Anthropic（原生）
• OpenAI
• Azure OpenAI
• Google Gemini
• Ollama／LM Studio／自建 vLLM（本機或內網推論）
• 任何 OpenAI 相容端點（DeepSeek、Groq、OpenRouter 等）
• MiMo 模型會自動調整工具呼叫參數，避免工具 schema 在自由生成時異常

方式三：Open Design AMR（官方代管，零設定）

不想自行管理多個 API Key 時，可改用官方 AMR（Agentic Model Router）：一次儲值即可使用 20+ 旗艦模型（涵蓋 GPT、Claude、Gemini、DeepSeek 等），依實際 token 用量計費，桌面應用內建一鍵登入，詳見 5.6 節。

安全注意事項：

⚠️ BYOK Proxy 對每個供應商端點皆內建 SSRF 防護：
   - 拒絕 loopback 位址（127.0.0.0/8, ::1）
   - 拒絕 link-local 位址（169.254.0.0/16）
   - 拒絕 RFC1918 私有位址（10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16）
   - 拒絕 CGNAT 位址（100.64.0.0/10）

✅ 企業環境建議：
   - API Key 使用環境變數注入
   - 不要在程式碼中硬編碼 Key
   - 定期輪換 API Key
   - 監控 Token 使用量（無論 BYOK 或 AMR）
   - daemon 預設僅綁定 127.0.0.1；若需區網存取，須明確設定 OD_BIND_HOST 與 OD_ALLOWED_ORIGINS

3.5 桌面版安裝

自 v0.10.0 起，原生桌面應用已是官方建議的預設安裝路徑（而非早期版本中的選用項目）：

• macOS（Apple Silicon／Intel x64）與 Windows（x64）提供正式安裝檔；Linux AppImage 為選用發布通道
• 安裝後自動偵測 PATH 上所有 Coding Agent CLI，載入 100+ Skill 與 150 個 Design System，免任何額外設定
• 沙箱化渲染器 + sidecar IPC，支援 STATUS / EVAL / SCREENSHOT / CONSOLE / CLICK / SHUTDOWN 通道，可用於 E2E 測試自動化
• 封裝版本具備自動更新機制與版本通道模型（詳見 11.1 節）

# 官方安裝檔：open-design.ai 或 GitHub Releases
# 開發模式下以原始碼啟動桌面殼層：
pnpm tools-dev run desktop

3.6 容器化與雲端部署

除了桌面應用與原始碼建置，v0.10.0 起新增了正式的容器化部署路徑，適合企業將 Open Design 部署為團隊共用服務：

Docker Compose

git clone https://github.com/nexu-io/open-design.git
cd open-design/deploy
cp .env.example .env
echo "OD_API_TOKEN=$(openssl rand -hex 32)" >> .env
docker compose up -d
# 開啟 http://localhost:7456

macOS 常見問題：若 Web UI 出現 Authorization: Bearer <OD_API_TOKEN> required，通常是 Docker Desktop 的 bridge networking 所致，修正方式見 deploy/README.md。

Sealos 一鍵部署

Sealos App Store 提供官方發布的 Docker image 範本，內建持久化工作區儲存與公開代理的 Basic Auth；若需自訂反向代理或多團隊共用部署，請參照 deploy/README.md 中的 OPEN_DESIGN_ALLOWED_ORIGINS 設定指引。

Vercel 部署（僅 Web 層）

# 1. Fork 專案到你的 GitHub
# 2. 在 Vercel 匯入專案
# 3. 設定環境變數（如需要）
# 4. 部署（已內建 vercel.json 配置）
vercel deploy

注意：Vercel 部署僅含 Web 前端層，daemon 仍須在本地、企業內網伺服器或前述 Docker／Sealos 路徑中運行；三種部署路徑可依「前端／後端分離治理」的需求並用。

3.7 多語系與國際化

Open Design 目前支援 13 種語言的介面與文件（較早期 7 種大幅擴充）：

已支援語系：

企業導入建議：

• 中文環境的 Design System 可在 DESIGN.md 的 ## 7. Voice 段落指定 Language: 繁體中文
• Prompt 中明確指定語言可確保 artifact 輸出使用正確語系
• 阿拉伯語支援包含完整的 RTL（Right-to-Left）佈局翻轉
• 翻譯貢獻流程與各語系檔案對應規則見官方 TRANSLATIONS.md

4. 核心機制解析

4.1 Skill 驅動架構

Skill 是什麼

Skill 是 Open Design 的核心設計單元，遵循 Claude Code 的 SKILL.md 慣例，每個 Skill 是一個資料夾：

skills/
└── web-prototype/
    ├── SKILL.md              ← 技能定義 + od: 擴展前綴
    ├── assets/
    │   └── template.html     ← 種子模板
    └── references/
        ├── themes.md         ← 主題參考
        ├── layouts.md        ← 佈局參考
        ├── components.md     ← 元件參考
        └── checklist.md      ← P0/P1/P2 檢查清單

od: 擴展前綴

Skill 的 YAML frontmatter 包含 OD 專屬的 od: 欄位，daemon 會原封不動解析這些欄位（見 apps/daemon/src/skills.ts）：

---
name: web-prototype
description: Single-page HTML prototype
od:
  mode: prototype          # prototype | deck
  platform: desktop        # desktop | mobile
  scenario: design         # design | marketing | operation | engineering | ...
  preview:
    type: iframe
  design_system:
    requires: true
  default_for: prototype   # 預設 Skill
  featured: true
  fidelity: high
  speaker_notes: false
  animations: true
  example_prompt: "Create a landing page for a SaaS product"
---

100+ 個內建 Skill

Skill 目錄自 v0.10.0 起分為兩層：skills/（Agent 任務中呼叫的功能型技能，如摘要、封裝、簡報產生器）與 design-templates/（渲染型錄，涵蓋 prototype／deck／image／video／audio 等輸出樣式），兩者合計已超過 100 個可選能力，遠超早期版本的 31 個。以下列出企業最常用的代表性分類（完整清單請以官方 docs/skills-protocol.md 與 design-templates/ 目錄為準）：

Prototype 模式（代表性項目）：

Deck／其他模式（代表性項目）：

Skill 的 mode 欄位涵蓋 prototype / deck / image / video / audio / template / design-system / utility 共 8 種；scenario 欄位則依受眾分為 design／marketing／operation／engineering／product／finance／hr／sale／personal。

自定義 Skill

# 1. 複製現有 Skill 作為模板
cp -r skills/web-prototype skills/my-custom-skill

# 2. 修改 SKILL.md
# 3. 修改 assets/template.html
# 4. 修改 references/*.md
# 5. 重啟 daemon

pnpm tools-dev stop
pnpm tools-dev run web

# 新 Skill 自動出現在選擇器中
# API：GET /api/skills 查看全部，GET /api/skills/:id/example 查看範例

Skill Chaining（技能鏈）

graph LR
    A[wireframe-sketch] -->|初稿| B[critique]
    B -->|評分 + 改進建議| C[web-prototype]
    C -->|完成品| D[tweaks]
    D -->|微調參數| E[最終輸出]

實務範例：

1. 先用 wireframe-sketch 生成草圖，讓使用者確認方向
2. 用 critique 對草圖進行 5 維度評分
3. 用 web-prototype 生成高保真原型
4. 用 tweaks 微調色彩、間距、字型等參數

4.2 HTML PPT Studio 技能體系

Open Design 於早期版本即整合了來自 lewislulu/html-ppt-skill（MIT 授權）的完整 HTML PPT Studio 技能體系，這是 OD 在簡報領域的重大能力擴充，經核對截至 v0.13.0 各項數字仍維持一致：

架構概觀

skills/
├── html-ppt/                      ← 主技能（Master Skill）
│   ├── SKILL.md                   ← 核心 Prompt + 全域設計規則
│   ├── LICENSE                    ← MIT（lewislulu）
│   └── references/
│       ├── layouts.md             ← 31 種單頁佈局
│       ├── themes.md              ← 36 種主題
│       ├── animations.md          ← 27 個 CSS 動畫 + 20 個 Canvas FX
│       └── keyboard-runtime.md    ← 鍵盤導航執行時
│
├── html-ppt-pitch-deck/           ← 投資簡報模板
├── html-ppt-tech-sharing/         ← 技術分享模板
├── html-ppt-presenter-mode/       ← 磁性卡片演示模式
├── html-ppt-xhs-post/             ← 小紅書風格貼文
└── ... （共 15 種模板包裝）

能力規格

與 guizang-ppt 的定位差異

使用範例

# 建立技術分享簡報
請使用 html-ppt-tech-sharing 技能，建立一份 Java 21 新特性介紹簡報：

頁面 1 - 封面：標題「Java 21 新特性完全指南」+ 講者名
頁面 2 - 大綱：4 個主題（Virtual Threads / Pattern Matching / Record / Sealed Classes）
頁面 3-6 - 每個主題一頁，含程式碼範例
頁面 7 - 總結 + Q&A

主題：深色科技風格
動畫：代碼區塊打字機效果

4.3 Design System 設計系統

150 個內建系統

Open Design 內建 150 個品牌級 DESIGN.md 系統（早期版本為 129 個），來源仍是 VoltAgent/awesome-design-md，並依官方最新 README 重新以九大類別組織：

完整清單請以官方 design-systems/README.md 為準；其中 142 個同時以 Plugin 型態包裝於 plugins/_official/design-systems/，可透過 od plugin install 安裝到市集流程（詳見第 5 章）。

每個系統是一個 9 段式 DESIGN.md 檔案：

# Design System: [Brand Name]

## 1. Color
## 2. Typography
## 3. Spacing
## 4. Layout
## 5. Components
## 6. Motion
## 7. Voice
## 8. Brand
## 9. Anti-patterns

選擇設計系統的策略

品牌一致性控制

# 新增企業專屬設計系統
mkdir design-systems/my-company
cat > design-systems/my-company/DESIGN.md << 'EOF'
# Design System: My Company

## 1. Color
- Primary: oklch(0.55 0.15 250)   /* 企業藍 */
- Secondary: oklch(0.65 0.10 150) /* 輔助綠 */
- Neutral-50: oklch(0.97 0 0)
- Neutral-900: oklch(0.15 0 0)

## 2. Typography
- Display: "Noto Sans TC", sans-serif
- Body: "Noto Sans TC", sans-serif
- Mono: "JetBrains Mono", monospace

## 3. Spacing
- Base unit: 4px
- Scale: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64

## 4. Layout
- Max content width: 1200px
- Grid: 12-column, 24px gutter

## 5. Components
- Border radius: 8px (cards), 4px (inputs)
- Shadows: 0 1px 3px oklch(0 0 0 / 0.1)

## 6. Motion
- Duration: 200ms (micro), 400ms (page)
- Easing: cubic-bezier(0.4, 0, 0.2, 1)

## 7. Voice
- Tone: 專業、簡潔、溫暖
- Language: 繁體中文為主

## 8. Brand
- Logo: 水平版，最小寬度 120px
- Safe area: 1x logo height

## 9. Anti-patterns
- 禁止使用漸層按鈕
- 禁止陰影超過 2 層
- 禁止在深色背景使用純白文字
EOF

# 重啟 daemon 即可在選擇器中看到
pnpm tools-dev stop && pnpm tools-dev run web

同步上游設計系統

# 重新匯入 awesome-design-md 最新版
pnpm tsx scripts/sync-design-systems.ts

4.4 Visual Directions 視覺方向

當使用者沒有品牌規範時，OD 會在 Turn 2 提供 5 種預設視覺方向：

每個方向都是確定性規格——OKLch 色板 + 字型堆疊 + 佈局姿態，一鍵選擇即綁定，無 AI 即興發揮。

4.5 Anti-AI-Slop 防劣質機制

Open Design 移植了 huashu-design 的完整防劣質策略：

機制一覽

4.6 媒體生成能力

Open Design 不僅生成程式碼/設計，也支援圖片、影片和音訊生成；HyperFrames 自整合以來已是影片能力的一級公民，與傳統 text-to-video 模型並列為主要生成路徑：

圖片生成

43 個即用 prompt 模板位於 prompt-templates/image/。

影片生成

39 個 Seedance prompt 模板 + 11 個 HyperFrames 模板位於 prompt-templates/video/。

音訊生成

音訊模板目錄 prompt-templates/audio/ 已建立，歡迎社群貢獻。

媒體模型支援架構

apps/daemon/src/media-models.ts     ← 模型派發器
apps/web/src/media/models.ts        ← 前端模型定義
prompt-templates/
├── image/                          ← 43 個 gpt-image-2 模板
├── video/                          ← 39 Seedance + 11 HyperFrames
└── audio/                          ← 開放貢獻中

BYOK 注意：媒體模型需要各自的 API Key。圖片使用 OpenAI / Azure 金鑰；影片和音訊多數透過 Fal.ai 統一代理，僅需設定 FAL_KEY；若不想個別管理這些金鑰，也可改用 Open Design AMR 一次性代管計費（詳見 5.6 節）。

4.7 Craft 設計參考系統

craft/ 目錄包含品牌無關的設計參考素材，源自 Refero 等設計靈感庫的衍生連結：

craft/
├── README.md                       ← 使用說明
├── landing-pages/                  ← Landing Page 參考
├── dashboards/                     ← Dashboard 佈局參考
├── mobile/                         ← 行動端參考
└── ...                             ← 按場景持續擴充

用途：

• Agent 在 Turn-1 Discovery 階段可引用 craft/ 中的連結作為視覺參考
• Skill 的 references/ 目錄可透過相對路徑引用 craft/ 的素材
• 企業可在此目錄加入自有品牌的設計參考

4.8 OD Library 與使用者資產庫

早期版本的「使用者儲存模板」功能，已隨 v0.12.0「Brand-backed Design System」擴充為更完整的 OD Library 資產庫機制：

能力範圍

使用流程

1. 在 Chat／Studio 中完成設計 → 預覽滿意
2. 點擊「Save as Template」，或在「Design System」頁面透過 URL／Figma／截圖建立新的品牌系統
3. 填入名稱與描述，系統寫入 daemon 管理的資料庫（實際儲存路徑規則見官方 AGENTS.md，本文件不重複列舉）
4. 模板／設計系統出現在對應的 Picker／Library 面板中
5. 下次新專案可直接從模板或已學習的品牌資產啟動，減少重複輸入

5. Plugin 系統與 MCP 整合

本章為 v0.13.0 版本相對於早期文件全新新增的章節，對應 Open Design 自 v0.8.0（Plugin 市集基礎設施）以來最重大的能力擴充：把「Skill」這種嵌入式設計能力，進一步包裝成可安裝、可版本化、可跨 Agent 分發的「Plugin」，並透過 MCP（Model Context Protocol）讓外部 Coding Agent 直接呼叫 Open Design。

5.1 Plugin 市集架構與定位

Plugin 與 Skill 的關係：Skill 是嵌在 Open Design 內、供其自身 Agent 讀取的設計能力資料夾；Plugin 則是在 Skill 之上疊加一層市集中繼資料的可攜式單元——本質是「一個 SKILL.md（任何支援 Agent Skills 的 Agent 都能讀）＋一個選用的 open-design.json（賦予 Open Design 市集才需要的中繼資料：輸入參數、預覽圖、管線、能力宣告）」。這個設計讓同一份能力既能單獨被其他 Agent 當作 Skill 使用，也能在 Open Design 市集中被安裝、搜尋、套用與升級版本。

my-plugin/
├── SKILL.md            ← 必要：YAML frontmatter（name、description）+ 觸發語句 + 工作流程（建議 < 500 行）
├── open-design.json     ← 若要上架市集才需要：市集中繼資料 + 輸入參數 + 管線 + 能力宣告
├── README.md            ← 選用：使用方式、安裝、登錄檔連結
├── preview/              ← 選用：index.html / poster.png（視覺型 Plugin 強烈建議提供）
└── examples/             ← 選用：具體使用案例

open-design.json 核心欄位：specVersion（目前為 1.0.0）、name（穩定 ID）、version（semver）、compat.agentSkills[].path（指向 ./SKILL.md）、od.kind（skill / scenario / atom / bundle）、od.taskKind（new-generation / figma-migration / code-migration / tune-collab）、od.mode（輸出型態，如 prototype / deck / live-artifact / image / video / hyperframes / audio / design-system / scenario）、od.capabilities[]（最小權限原則——受限安裝預設只授予 prompt:inject）、od.inputs[]（套用時的參數）。

5.2 官方 Plugin 六大分類

官方目前提供 261 個 Plugin，全部位於 plugins/_official/，依用途分為六大類：

另有 plugins/community/ 收錄社群貢獻 Plugin，plugins/registry/ 定義發佈流程。企業導入時，建議先盤點 scenarios/ 中與自身遷移需求相關的項目（如 od-figma-migration、od-code-migration），作為導入 Plugin 生態的第一步。

5.3 Plugin CLI 操作

Plugin 在 Web UI／桌面應用與 od CLI 兩端功能對等，皆呼叫相同的 /api/plugins 端點：

• 圖形介面：開啟「Plugin」頁面瀏覽市集並點擊安裝；在專案 Studio 內，已安裝的 Plugin 會以 composer 上的小工具（chip）形式出現，點擊即可套用並填入宣告的輸入參數
• 命令列（外部自動化管線的主要路徑）：

od plugin list                       # 列出已安裝 Plugin（支援 --task-kind / --mode / --tag 篩選）
od plugin search "landing page"      # 依關鍵字搜尋
od plugin info od-default            # 檢視中繼資料、輸入參數、能力宣告
od plugin install od-figma-migration # 從登錄檔安裝；也接受 ./本地資料夾 或 https://... 連結
od plugin apply od-default --input brief="為我們的種子輪募資做一頁式簡報"
od plugin upgrade od-default         # 升級
od plugin uninstall od-default       # 移除

每個指令皆支援 --json，可透過 jq / xargs 接入企業既有的自動化管線（例如排程批次產出簡報、CI 中驗證設計稿）。

5.4 建立與貢獻 Plugin

最小結構只需一份 SKILL.md；若要上架市集則需補上 open-design.json。官方提供鷹架與驗證工具：

od plugin scaffold --id my-plugin --title "My Plugin"   # 產生骨架
od plugin validate ./my-plugin                          # 檢查 manifest / 檔案結構
pnpm guard && pnpm --filter @open-design/plugin-runtime typecheck

貢獻流程：

1. 第三方 Plugin 放入 plugins/community/；若要隨 Open Design 一併發佈，放入 plugins/_official/ 對應分類
2. 通過驗證：od plugin validate、pnpm guard、pnpm --filter @open-design/plugin-runtime typecheck
3. 依 plugins/spec/CONTRIBUTING.md 範本送出 PR（含 ID、版本、分類、mode、capabilities、觸發語句範例；視覺型 Plugin 附上截圖／預覽）
4. 若要發佈至外部登錄檔（skills.sh、ClawHub 或獨立 GitHub repo），流程見 plugins/spec/PUBLISHING-REGISTRIES.md

企業治理建議：內部貢獻 Plugin 時，od.capabilities[] 應遵循最小權限原則——只宣告該 Plugin 實際需要的能力，避免受限安裝情境下被授予超出需求的權限；社群 Plugin 上線前應比照第三方套件納入既有的程式碼／供應鏈審查流程（詳見 14 章風險表）。

5.5 MCP Server 整合

Open Design 提供一個 stdio MCP server，讓任何支援 MCP 的外部 Agent（不限於 Open Design 自己驅動的 CLI）都能直接讀寫本機 Open Design 專案的檔案——tokens CSS、JSX 元件、entry HTML——如同呼叫一個具名結構化 API，且永遠讀取即時檔案，而非過期的匯出快照。

# 一行安裝進慣用的 Agent（支援 16+ 種 CLI）：
od mcp install <agent>
# <agent> = claude | codex | cursor | copilot | openclaw | antigravity | gemini
#         | pi | vibe | hermes | cline | kimi | trae | opencode

# 或用託管腳本安裝：
curl -fsSL https://open-design.ai/install.sh | sh -s <agent>

# 安裝後，Agent 內即可呼叫：
od search-files "primary button"      # 跨專案搜尋檔案
od get-file design-systems/linear-app/DESIGN.md
od get-artifact <slug>                # 取得最新渲染的 artifact
od plugin run web-prototype --brief "..."
od skill list --scenario marketing

od mcp install <agent> --print 可預覽安裝內容而不實際寫入，--uninstall 可移除。

安全模型：daemon 預設唯讀、僅綁定 127.0.0.1；區網存取需要明確設定 OD_BIND_HOST 與 OD_ALLOWED_ORIGINS；連接器憑證與即時預覽路由無論如何都維持僅限本機（loopback-only），不因區網開放而暴露。

WSL2 使用者注意：若 Coding Agent CLI 是在 WSL2 內執行，Linux 內建的 /usr/bin/od（octal dump 指令）可能與 Open Design 的 od 指令衝突，請先參照官方 docs/wsl-setup.md 排除路徑衝突。

5.6 Open Design AMR 模型路由器

AMR（Agentic Model Router） 是官方自 v0.9.0 起推出的代管模型服務，作為 BYOK 之外的第三條模型供應路徑：

與 BYOK 的取捨：BYOK 給予企業對供應商、資料落地、合約條款的完全掌控，適合有明確供應商治理政策的組織；AMR 則以「單一帳務窗口＋零設定」換取管理便利性，適合中小型團隊或希望快速跨模型實驗的場景。兩者可以並存——例如日常原型設計使用 AMR，正式合規敏感的專案改走企業已簽約供應商的 BYOK 路徑。

6. AI 開發流程（企業級）

6.1 Web Application 開發

graph TD
    A[需求分析] --> B[選擇 Skill + Design System]
    B --> C[撰寫設計簡報]
    C --> D[OD 互動表單]
    D --> E[方向選擇]
    E --> F[AI 生成原型]
    F --> G[5 維度品質審核]
    G -->|通過| H[artifact 預覽]
    G -->|未通過| F
    H --> I[團隊審查]
    I -->|OK| J[匯出 HTML/PDF]
    I -->|修改| K[chat 追加指示]
    K --> F
    J --> L[前端開發參考實作]

實際操作步驟

Step 1：選擇適當的 Skill

Step 2：撰寫高品質設計簡報

為我們的企業內部人事管理系統設計一個 Dashboard。

系統背景：
- 使用者：HR 部門，約 50 人
- 功能：員工管理、請假審核、薪資查詢
- 資料量：約 5000 名員工

設計需求：
- 左側導航列
- 頂部搜尋列 + 通知
- 主區域顯示 KPI 卡片（在職人數、本月新進、離職率、平均年資）
- 下方顯示請假審核待辦清單
- 右側顯示快速操作面板

Step 3：互動表單填寫

OD 會自動彈出表單，詢問：

• Surface type: Desktop
• Target audience: HR 專員
• Visual tone: Professional / Clean
• Brand context: 企業內部系統
• Scale: Medium complexity

Step 4：審查與迭代

# 追加修改指示
- 請將 KPI 卡片改為 2x2 格局
- 顏色調整為企業藍（#1B4F72）
- 新增「本月壽星」小元件到右側面板

6.2 舊系統逆向工程

流程

graph LR
    A[截圖舊畫面] --> B[上傳至 OD Chat]
    B --> C[OD 品牌資產擷取]
    C --> D[分析色彩/佈局/元件]
    D --> E[生成現代化 UI]
    E --> F[新舊對照審查]
    F --> G[匯出設計稿]

實際操作

輸入：

這是我們 10 年前的員工管理系統截圖。
請分析此畫面的：
1. 資訊架構（IA）
2. 資料欄位
3. 操作流程

然後使用 dashboard skill + Linear design system，
重新設計一個現代化的版本，保留所有功能但改善 UX。

約束條件：
- 必須保留所有現有欄位
- 操作流程不可增加步驟
- 支援繁體中文

輸出：

• 現代化 UI 原型（HTML artifact）
• 資訊架構分析
• 新舊功能對照表

6.3 Framework 升級

場景：jQuery → Vue / React

我們正在將一個基於 jQuery + Bootstrap 3 的管理後台
升級為 Vue 3 + Element Plus。

請根據以下舊畫面截圖，使用 dashboard skill，
設計新版本的 UI，需要：

1. 保留現有功能佈局
2. 使用 Element Plus 的設計語言
3. 響應式設計
4. 暗色模式支援
5. 產出元件拆分建議

場景：舊版 Spring MVC 畫面 → 新版 SPA

這是我們 Spring MVC + JSP 的訂單管理頁面。
請分析畫面元素，並使用 web-prototype skill，
重新設計為現代 SPA 風格：

- 左側：訂單篩選器
- 中間：訂單清單（可排序/篩選）
- 右側：訂單詳情面板
- 底部：分頁控制

6.4 企業文件與報表生成

CLI／自動化路徑：以上場景皆可改用第 5 章介紹的 Plugin CLI 執行，例如 od plugin apply od-default --input brief="為 Q3 研發團隊建立 OKR 記分卡"，適合排入排程或接進企業既有的文件產出管線，不需手動開啟介面逐一輸入。

7. Prompt Engineering

7.1 Prompt 結構設計原則

Open Design 的 Prompt 設計遵循以下原則：

1. 具體優於抽象：描述具體的使用者、場景、數據
2. 約束優於自由：明確列出限制條件，減少 AI 即興
3. 結構優於散文：使用列表、表格、分區
4. 品牌優於預設：附上品牌規範或選擇 Design System
5. 迭代優於一次：先粗後細，分步精修

7.2 高品質 Prompt 範本

範本 1：企業 Dashboard

設計一個企業級 IT 資產管理 Dashboard。

使用者角色：IT 管理員
使用頻率：每日
關鍵指標：
- 設備總數 / 在用 / 閒置 / 報修
- 軟體授權使用率
- 本月資安事件數
- 設備到期預警（30/60/90天）

佈局要求：
- 頂部：全域搜尋 + 通知鈴 + 使用者頭像
- 左側：收合式導航（Dashboard / 設備 / 軟體 / 報表 / 設定）
- 主區域上方：4 個 KPI 卡片
- 主區域中間：設備狀態折線圖（近 12 個月）
- 主區域下方：待處理事項表格

色彩偏好：藍灰色系，專業穩重
字型：Noto Sans TC
語言：繁體中文

範本 2：行動 App Onboarding

設計一個銀行行動 App 的 Onboarding 流程，共 4 個畫面：

畫面 1 - Splash：
- 銀行 Logo + Tagline
- 「開始體驗」按鈕

畫面 2 - 功能介紹：
- 圖示 + 標題 + 說明
- 功能：轉帳、繳費、投資

畫面 3 - 安全承諾：
- 生物辨識圖示
- 端對端加密說明
- 金管會核准字樣

畫面 4 - 登入/註冊：
- 手機號碼輸入
- OTP 驗證按鈕
- 隱私政策連結

裝置：iPhone 15 Pro
風格：Modern Minimal
語言：繁體中文

範本 3：SaaS Landing Page

為一個 AI 程式碼審查工具設計 Landing Page。

產品名稱：CodeGuard AI
Tagline：「讓每一行程式碼都經得起考驗」

頁面區塊：
1. Hero：大標題 + 副標題 + CTA「免費試用」+ 產品截圖
2. 痛點：3 欄式，開發者常見困擾
3. 功能：4 個核心功能卡片（自動審查、安全掃描、效能建議、CI/CD 整合）
4. 數據：「已審查 1000 萬行程式碼」等社會證明
5. 定價：Free / Pro / Enterprise 三欄
6. 客戶評價：3 則推薦
7. CTA：重複呼籲行動
8. Footer：連結、社群、法律

Design System：Vercel
動態效果：微妙的滾動進場動畫

範本 4：週報簡報

為研發團隊產生本週工作週報簡報（deck 模式）。

日期：2026-W18（5/4 - 5/8）

頁面 1 - 封面：團隊名稱 + 週次

頁面 2 - 本週亮點：
- 完成 API Gateway v2 上線
- 修復 12 個 P1 bugs
- 新增 3 位團隊成員

頁面 3 - 進度追蹤：
- Sprint Burndown（剩餘 15 story points）
- 完成率 78%

頁面 4 - 阻礙與風險：
- DB 連線池不足
- 第三方 API 不穩定

頁面 5 - 下週計畫：
- 壓測目標 1000 TPS
- 開始 SSO 整合

風格：簡潔專業

範本 5：逆向工程 — 舊系統重設計

[附上舊系統截圖]

這是我們 2012 年開發的客戶關係管理系統（CRM）。
技術棧：Struts 2 + JSP + Oracle

請分析此畫面並重新設計：

保留功能：
- 客戶搜尋（姓名/統編/電話）
- 客戶清單（表格，含分頁）
- 客戶詳情（側邊面板）
- 新增/編輯客戶表單

改善方向：
- 現代化視覺風格
- 響應式佈局
- 搜尋改為即時篩選
- 表格支援排序、固定表頭
- 表單改為分步驟

Design System: Linear

7.3 Prompt 最佳化策略

8. 設計品質控管機制

8.1 五維度自我審核機制

在 Agent 發射 <artifact> 之前，會靜默進行 5 維度自我評分（1-5 分）：

規則：任何維度低於 3/5 為回歸，必須修復後重新評分。通常需要兩次通過。

8.2 P0 / P1 / P2 Checklist

每個 Skill 在 references/checklist.md 中定義檢查清單：

8.3 Artifact Lint API

POST /api/artifacts/lint
Content-Type: application/json

{
  "html": "<artifact>...</artifact>",
  "skillId": "web-prototype",
  "designSystemId": "linear-app"
}

Response:
{
  "findings": [
    {
      "level": "error",
      "message": "Broken <artifact> framing",
      "line": 1
    },
    {
      "level": "warning",
      "message": "Stale palette token: --color-primary not in DESIGN.md",
      "line": 45
    }
  ]
}

5 維度自我批評使用此 API 的結果來錨定評分，基於真實證據而非感覺。

8.4 Slop 黑名單

以下設計元素在 Prompt Stack 中被明確禁止：

❌ 侵略性紫色漸層
❌ 通用 emoji 圖示作為功能圖示
❌ 左邊框彩色卡片（通用感太重）
❌ 手繪 SVG 人物插圖
❌ Inter 字型作為展示字型（太普通）
❌ 虛構的統計數據（「10× faster」）
❌ 無意義的裝飾性漸層

正確做法：

• 沒有真實數據時，使用 — 或標記灰色區塊
• 使用 Design System 指定的字型，不自行選擇
• 圖示使用 SVG icon set，不用 emoji

9. 輸出與整合

9.1 匯出格式

9.2 CI/CD 整合

# .github/workflows/design-review.yml
name: Design Review
on:
  pull_request:
    paths:
      - 'design-specs/**'
      - 'plugins/community/**'

jobs:
  lint-artifacts:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '24'
      - run: corepack enable && pnpm install
      - run: |
          # 對所有 artifact 執行 lint
          for f in design-specs/*.html; do
            curl -X POST http://localhost:3457/api/artifacts/lint \
              -H "Content-Type: application/json" \
              -d "{\"html\": \"$(cat $f)\"}"
          done
      - run: |
          # 若 PR 涉及自製 Plugin，一併驗證
          if [ -d plugins/community ]; then
            for p in plugins/community/*/; do
              od plugin validate "$p"
            done
          fi
      - run: pnpm guard

9.3 Git / PR 開發流程整合

graph TD
    A[建立 feature branch] --> B[在 OD 中設計 UI]
    B --> C[匯出 artifact 到 design-specs/]
    C --> D[提交 PR]
    D --> E[CI 執行 artifact lint]
    E --> F[團隊 review 設計]
    F -->|Approved| G[Merge]
    F -->|Changes requested| B
    G --> H[前端依據 artifact 實作]

9.4 Claude Design ZIP 匯入

如果團隊之前使用 Claude Design，可以無縫遷移：

1. 從 claude.ai 匯出設計 ZIP
2. 在 OD 歡迎對話框拖放 ZIP 檔案
3. POST /api/import/claude-design 自動解析
4. 自動建立對應的專案工作目錄（由 daemon 資料根目錄管理）
5. 開啟入口檔案為分頁
6. 準備好 continue-where-Anthropic-left-off prompt

10. 系統維護與營運

10.1 日誌與監控

# 查看 daemon 日誌
pnpm tools-dev logs

# 查看行程狀態
pnpm tools-dev status

# 健康檢查
pnpm tools-dev check

# 檢查已偵測的 Agent
curl http://localhost:3457/api/agents

# 檢查已載入的 Skills
curl http://localhost:3457/api/skills

# 檢查已載入的 Design Systems
curl http://localhost:3457/api/design-systems

# 檢查已安裝的 Plugin
curl http://localhost:3457/api/plugins

建議監控項目

10.2 錯誤處理

10.3 Skill 管理

# 列出所有 Skills
curl http://localhost:3457/api/skills | jq '.[] | .id'

# 查看特定 Skill 的範例
curl http://localhost:3457/api/skills/web-prototype/example

# 新增 Skill：放入資料夾 → 重啟 daemon
cp -r skills/web-prototype skills/my-new-skill
# 編輯 SKILL.md...
pnpm tools-dev stop && pnpm tools-dev run web

# 未來：Skill 市場（roadmap）
# od skills install <github-repo>
# od skill add | list | remove | test

10.4 Design System 更新策略

# 同步上游設計系統
pnpm tsx scripts/sync-design-systems.ts

# 手動更新特定系統
# 編輯 design-systems/<brand>/DESIGN.md
# 重啟 daemon

# 版本管理建議：
# - 將自定義 Design System 加入版本控制
# - 上游系統用 sync 腳本管理
# - 記錄每次更新的變更

10.5 資料備份與復原

治理提醒：本節刻意不列出具體資料夾／檔名範例。官方 AGENTS.md 的「Daemon data directory contract」明訂資料路徑僅有 OD_DATA_DIR 這一個真實來源，任何文件（含企業內部 SOP）都不應臆造或沿用具體路徑範例，以免版本更新後失真。企業撰寫備份腳本時，請先讀取當次部署設定的 OD_DATA_DIR 值，再對該目錄整體備份。

# 概念示意：先解析 daemon 實際使用的資料根目錄，再整體備份／還原
# （$OD_DATA_DIR 的實際設定值請以當次部署環境為準，勿寫死路徑）
cp -r "$OD_DATA_DIR" "${OD_DATA_DIR}.bak.$(date +%Y%m%d)"

# 完全重置
pnpm tools-dev stop
rm -rf "$OD_DATA_DIR"
pnpm tools-dev run web
# daemon 會自動重建所有必要結構

# 環境隔離（每個 namespace／租戶使用獨立的 OD_DATA_DIR）
OD_DATA_DIR=/path/to/isolated pnpm tools-dev run web

封裝版桌面應用的資料根目錄由 apps/packaged 依通道與 namespace 自動解析，不建議依應用名稱、Electron userData、埠號或通道名稱自行猜測路徑；備份策略應改為透過應用內建的匯出／診斷功能，或參照官方封裝建置文件操作。

11. 系統升級策略

11.1 Open Design 升級流程

企業導入的部署路徑不同，升級方式也不同，以下分別說明：

桌面應用（封裝版）：自動更新通道

自 v0.10.0 起，封裝版桌面應用具備自動更新機制與版本通道模型（由 tools/pack 的 release channel 定義），一般使用者只需依應用內提示更新即可；企業若需控管更新節奏（如集中測試後才放行），應參照官方封裝建置文件規劃內部發布通道，而非逐台手動更新。

原始碼建置：手動升級流程

# Step 1：備份現有資料（依 10.5 節方式，先備份 $OD_DATA_DIR 指向的資料根目錄）

# Step 2：拉取最新版本
git fetch origin
git log --oneline origin/main..HEAD  # 檢查差異，留意 CHANGELOG／release note 中的破壞性變更

# Step 3：停止服務
pnpm tools-dev stop

# Step 4：合併更新
git pull origin main

# Step 5：更新依賴
pnpm install

# Step 6：啟動新版本
pnpm tools-dev run web

# Step 7：驗證
pnpm tools-dev check
curl http://localhost:3457/api/agents
curl http://localhost:3457/api/skills
curl http://localhost:3457/api/plugins

11.2 相容性管理

11.3 版本控管策略

建議的 Git 策略：

main ─────────────────────── 穩定版本
  │
  ├── feature/custom-skill ── 自定義 Skill 開發
  │
  ├── feature/design-system ─ 企業 Design System
  │
  └── upstream/main ────────── 追蹤上游更新

操作流程：
1. Fork 官方 repo
2. 在 fork 中新增自定義內容
3. 定期 rebase 上游更新
4. 衝突集中在 skills/、design-systems/ 與 plugins/community/

11.4 回滾機制

# 快速回滾到上一個版本
git log --oneline -5
git checkout <previous-commit>
pnpm install
pnpm tools-dev run web

# 資料回滾（$OD_DATA_DIR 為當次部署實際設定的資料根目錄，依 10.5 節備份而來）
pnpm tools-dev stop
rm -rf "$OD_DATA_DIR"
mv "${OD_DATA_DIR}.bak.<備份日期>" "$OD_DATA_DIR"
pnpm tools-dev run web

12. 團隊導入建議

12.1 開發團隊使用方式

graph TD
    subgraph Phase1 ["Phase 1：試點（1-2 週）"]
        A1[選定 1-2 位 champion]
        A2[安裝環境]
        A3[試用 3-5 個 Skill]
        A4[產出內部報告]
    end

    subgraph Phase2 ["Phase 2：擴展（2-4 週）"]
        B1[建立企業 Design System]
        B2[建立 Prompt Template Library]
        B3[培訓核心團隊]
        B4[定義使用規範]
    end

    subgraph Phase3 ["Phase 3：常態化"]
        C1[納入開發流程]
        C2[CI/CD 整合]
        C3[效益衡量]
        C4[持續優化]
    end

    Phase1 --> Phase2 --> Phase3

日常開發流程

1. 需求確認 → PM 撰寫需求規格
2. 設計階段 → 使用 OD 生成 UI 原型
   - 選擇適當 Skill + Design System
   - 填寫互動表單
   - 審查 artifact
3. 開發階段 → 前端依據 artifact 實作
   - 匯出 HTML 作為視覺規格
   - 擷取色彩、間距、字型等 token
4. 審查階段 → 比對實作與設計稿
5. 交付

12.2 設計師協作模式

12.3 AI Agent 分工策略

12.4 SSDLC 整合方式

graph LR
    A[需求分析] --> B[威脅建模]
    B --> C[安全設計]
    C --> D[OD 生成原型]
    D --> E[安全審查]
    E --> F[安全實作]
    F --> G[安全測試]
    G --> H[部署]

安全設計階段使用 OD：

1. 使用 dashboard Skill 設計安全監控面板
2. 使用 eng-runbook 生成安全維運手冊
3. 使用自定義 Skill 生成權限管理 UI
4. 所有 artifact 經過 Artifact Lint API 檢查

13. 最佳實踐（Best Practices）

14. 常見問題與風險

FAQ

風險管理

15. 與企業架構深度整合

15.1 微服務架構整合

graph TB
    subgraph OD ["Open Design"]
        UIDesign[UI 原型生成]
        APIDoc[API 文件生成]
        RunBook[Runbook 生成]
    end

    subgraph Microservices ["微服務架構"]
        Gateway[API Gateway]
        UserSvc[User Service]
        OrderSvc[Order Service]
        NotifySvc[Notification Service]
    end

    UIDesign -->|Dashboard 原型| Gateway
    APIDoc -->|pm-spec| UserSvc
    APIDoc -->|pm-spec| OrderSvc
    RunBook -->|eng-runbook| NotifySvc

使用場景：

1. API Gateway 管理面板：使用 dashboard Skill 設計流量監控 Dashboard
2. 服務狀態頁：使用 web-prototype 設計 Status Page
3. 微服務文件：使用 pm-spec 為每個服務生成規格文件
4. 維運手冊：使用 eng-runbook 為關鍵服務生成 Incident Runbook

15.2 Clean Architecture 對應

Clean Architecture              Open Design 產出
────────────────                ──────────────
Entities                        → pm-spec（Domain 規格）
Use Cases                       → pm-spec（Use Case 文件）
Interface Adapters              → dashboard / web-prototype（UI 層設計）
Frameworks & Drivers            → eng-runbook（部署/維運）

15.3 前端框架整合（Vue / React）

Vue 3 + Element Plus

Prompt 範例：

設計一個員工管理系統的列表頁面。
請使用以下 Element Plus 元件：
- el-table（表格）
- el-pagination（分頁）
- el-input（搜尋框）
- el-button（操作按鈕）
- el-dialog（彈窗）

佈局參考 Element Plus 的 Admin 風格。
色彩使用 Element Plus 預設色系。

產出的 artifact 將作為前端 Vue 元件的視覺規格。

React + Ant Design

Prompt 範例：

設計一個數據分析 Dashboard。
請使用以下 Ant Design 元件風格：
- Card（指標卡片）
- Table（數據表格）
- Chart（圖表，ECharts 風格）
- Breadcrumb（麵包屑）
- Menu（側邊選單）

Design System: 使用 Ant Design 的色彩體系
（主色 #1677ff，成功 #52c41a，警告 #faad14，錯誤 #ff4d4f）

15.4 後端框架整合（Spring Boot / FastAPI）

Spring Boot API 文件生成

Prompt 範例（使用 pm-spec Skill）：

為以下 Spring Boot REST API 生成 PM 規格文件：

Service: Employee Management API
Base Path: /api/v1/employees

Endpoints:
- GET    /           → 查詢員工列表（支援分頁、篩選）
- GET    /{id}       → 查詢單一員工
- POST   /           → 新增員工
- PUT    /{id}       → 更新員工資料
- DELETE /{id}       → 刪除員工（軟刪除）
- GET    /{id}/leave  → 查詢請假記錄

安全性：
- JWT Bearer Token 認證
- RBAC 權限控管（ADMIN / HR / VIEWER）

請包含：
- 每個 endpoint 的 request/response 範例
- 錯誤碼定義
- 分頁格式定義

FastAPI 服務 Dashboard

Prompt 範例（使用 dashboard Skill）：

設計一個 FastAPI 微服務監控 Dashboard。

監控指標：
- 請求數/秒（QPS）
- 平均回應時間（ms）
- 錯誤率（%）
- 活躍連線數

服務清單：
- auth-service（認證）
- user-service（使用者）
- order-service（訂單）
- payment-service（支付）

佈局：
- 頂部：時間範圍選擇器（1h / 6h / 24h / 7d）
- 中間：4 個 KPI 卡片
- 下方左：QPS 折線圖
- 下方右：服務健康狀態表格

16. 檢查清單（Checklist）

環境建置 Checklist

• 已確認部署路徑（桌面應用／MCP 安裝／Docker-Sealos／原始碼建置）
• Node.js 24.x 已安裝（原始碼建置路徑）
• pnpm 10.33.x 已啟用（corepack enable，Windows 若 EPERM 改用 npm install -g pnpm@10.33.2）
• Git 已安裝
• 已 clone open-design repo（原始碼建置路徑）
• pnpm install 成功完成
• pnpm tools-dev run web 可正常啟動，或桌面應用／容器已成功啟動
• 至少一個 Coding Agent CLI 已安裝並在 PATH 中
• 或 BYOK API Key 已設定，或已完成 AMR 一鍵登入
• 瀏覽器／桌面應用可正常開啟主畫面
• 互動表單可正常顯示

首次使用 Checklist

• 選擇適當的 Skill
• 選擇適當的 Design System
• 撰寫包含具體約束的設計簡報
• 完整填寫互動表單
• 確認 5 維度評分 ≥ 3/5
• 審查生成的 artifact
• 測試匯出功能（HTML / PDF / PPTX / MP4 / ZIP）

MCP 安裝 Checklist

• 確認目標 Agent 支援 MCP（見 2.3 節對照表）
• 執行 od mcp install <agent> --print 預覽安裝內容
• 確認實際安裝後的 MCP 設定檔已正確寫入
• 在 Agent 內測試 od search-files／od get-file 可正常取得資料
• WSL2 環境已排除 /usr/bin/od 與 Open Design od 指令的衝突
• 確認 daemon 僅綁定 127.0.0.1，未在無評估情況下開放 OD_BIND_HOST

Plugin 治理 Checklist

• 已盤點需要的官方 Plugin 分類（scenarios／image-templates／video-templates／design-systems／atoms／examples）
• 自製或社群 Plugin 安裝前已執行 od plugin validate
• od.capabilities[] 僅宣告實際需要的最小權限
• 內部貢獻 Plugin 已依 plugins/spec/CONTRIBUTING.md 走完 PR 流程
• 社群 Plugin 已納入既有的供應鏈／安全審查流程

企業導入 Checklist

• 指定 1-2 位 champion 負責試點
• 建立企業專屬 DESIGN.md
• 建立 Prompt Template Library
• 定義 API Key／AMR 帳務管理策略
• 制定使用規範（何時用/何時不用）
• 完成團隊培訓（含 hands-on）
• 納入開發流程（設計階段工具）
• 設定 CI/CD 中的 Artifact Lint 與 Plugin 驗證
• 建立效益衡量指標
• 定期回顧和優化

安全 Checklist

• API Key 不提交版本控制
• 使用環境變數管理敏感資訊
• daemon 資料根目錄已加入 .gitignore（依 OD_DATA_DIR，不硬編路徑）
• BYOK Proxy 不暴露於公網
• 定期輪換 API Key
• 監控 Token／AMR 使用量和費用
• 企業 Design System 標記為「僅限內部使用」
• 生成的 artifact 不包含敏感資訊
• MCP／Plugin 相關風險已納入第 14 章風險表定期複核

維運 Checklist

• 設定定期備份 daemon 資料根目錄（依官方 AGENTS.md 指引，透過 $OD_DATA_DIR 操作）
• 設定磁碟空間監控
• 設定 daemon 健康檢查（pnpm tools-dev check）
• 桌面應用已確認自動更新通道設定符合企業節奏
• 建立升級 SOP
• 建立回滾 SOP
• 記錄已知問題和解決方案

附錄 A：參考來源與技術譜系

上游專案

設計系統來源

媒體模型供應商

官方文件與社群

附錄 B：Roadmap 發展藍圖

以下依官方最新公開資訊（截至 v0.13.0，2026-07-02）重新整理：

已完成項目

進行中／未完成項目

版本歷程（近期）

本文件維護者：開發團隊
下次審查日期：建議每季或於 Open Design 發布重大版本（如 minor version 躍升）時重新核對
參考來源：nexu-io/open-design（Apache-2.0），內容經 GitHub API 與官方 README／AGENTS.md 原始檔查證（查證時間：2026-07-02）