排錯手冊

按症狀找。裝不上的在最前面，生成品質的在後面。

裝不上

pnpm install 報 EBADENGINE

Node 大版本不對。OpenDesign 要 Node 24，Node 22 不支援。

nvm install 24 && nvm use 24
node -v   # 確認是 v24.x
corepack enable

Windows 上 better-sqlite3 編譯卡住

Node 24 上的已知情況。先裝 Visual Studio Build Tools（要包含 C++ 桌面開發工作負載），再重跑 pnpm install。

三個替代方案，從簡單到麻煩：

1. 直接用 Windows 安裝包，跳過原始碼。
2. 在 WSL 裡跑原始碼版。
3. 裝完 Build Tools 再來。

pnpm 版本不對

用 Corepack，別全域性裝：

corepack enable
# 之後 pnpm 會按 lockfile 裡鎖定的 10.33.2 走

埠被佔

上一次沒停乾淨：

pnpm tools-dev stop

還不行就換埠：

pnpm tools-dev --daemon-port 27456 --web-port 27573

別在腳本里寫死埠。

不知道缺什麼

pnpm tools-dev check

這條比讀日誌快。它會把環境裡缺的東西直接列出來。

Agent 接不上

介面裡看不到 Agent

按這個順序查：

1. CLI 在 PATH 裡嗎？ 終端裡敲一下它的名字（claude、codex、cursor-agent……），能不能起來。
2. 登入了嗎？ CLI 自己先跑通一次。
3. 用 API key 的話，.od/media-config.json 寫對了嗎？
4. pnpm tools-dev check 看看它怎麼說。

一直彈權限確認

環境沒配全。跑 pnpm tools-dev check，它會指出缺的那一項。

生成卡在「等待」不動

• 檢查那個 Agent 的額度還有沒有。
• 檢查網路能不能到模型廠商。
• 換一個 Agent 試試，能區分是 OpenDesign 的問題還是那個 Agent 的問題。

換了 Agent 之後技能不工作

技能本身跟 Agent 無關，所以這種情況通常是新 Agent 的能力邊界不同——比如它不能聯網、不能生成圖。看那個技能依賴了什麼能力。

生成結果不對

輸出是一堆圖片，文字選不中

有些 Agent 會取巧，把參考圖切片貼進 HTML。補一句：

所有文字必須是真實文本節點，能被選中和編輯。不允許把文字渲染成圖片。

風格完全沒跟上參考圖

兩個可能：

1. 參考圖沒真的傳進去。確認附件在。
2. 描述太籠統。把選中方向的特徵寫具體——具體的配色傾向、字型性格、質感、留白程度。

內容被裁掉了

指出具體頁碼，讓它按骨架補回來。不要說「有些內容丟了」。

第 5 頁現在只剩標題。請按內容方案裡第 5 頁的完整內容補回來，
版式跟第 4、6 頁保持一致。

改一處，壞了另一處

分輪改，每輪聚焦一兩個維度，並且加上：

只改上面說的這些，其餘不要動。

越改越花

明確排優先順序：

優先順序：可讀性 > 資訊層次 > 視覺衝擊。
如果三者衝突，犧牲視覺衝擊。

數字是編的

在提示詞裡寫死：

所有數字如果沒有真實來源，寫佔位符並明確標註為示意，不要估算，
不要編。哪些數字需要我提供，列出來。

已經生成的，讓它逐個標出來源：

把頁面裡所有數字列出來，逐個說明來源。你自己生成的、沒有來源的，
標為待核實。

狀態沒做全

這是 AI 設計最常見的失敗。直接要求：

按 state coverage 補全：空態、載入態、錯誤態、單條資料、大量資料。
錯誤態要說明怎麼恢復，空態要給出下一步動作。

一眼能看出是 AI 做的

跑 反 AI 味自查。常見成分：紫藍漸變、通用圖示、預設三欄、編造的使用者數、均勻的資訊密度。

匯出

PPTX 轉過去很多東西沒了

正常。Three.js 場景、依賴 JS 的互動、CSS 高階特性都過不去。

如果最終交付一定是 PPTX，倒推著做：動效那一步少做，別上 3D，功夫花在排版和圖表上。

PDF 裡圖表糊了

要求向量渲染：

匯出 PDF 時圖表用 SVG 渲染，不要點陣圖。

內聯 HTML 太大發不出去

圖片是 base64 塞進去的。兩個辦法：先壓縮圖片，或者改成外鏈加 ZIP 打包。

深色頁面匯出 PDF 變成大黑塊

列印場景通常要淺色版：

匯出 PDF 之前生成一個列印版本：淺色底、深色字，去掉背景動效和
裝飾性漸變，圖表改成淺色底。

演示現場

投影上掉幀

Three.js 場景在外接投影和螢幕共享時經常撐不住。上臺前必須在真機真投影上測一遍。撐不住就換 CSS 動畫。

投影上字太小

瀏覽器裡合適的字號，投影到大屏、觀眾坐在後排時經常不夠。全屏預覽之後退到房間最後一排的距離看一眼。

遠端共享時動效變糊

影片編碼會毀掉細膩的動效。遠端場合就把動效減到最少，或者乾脆用 PDF。

現場打不開

永遠導一份 PDF 備份。不是因為 OpenDesign 不穩，是因為現場的電腦、轉接頭、網路都不歸你管。

還是不行

• pnpm tools-dev check 的輸出是最快的第一手資訊。
• GitHub Issues 搜一下同樣的症狀。
• Discord 裡問。
• 官方快速開始頁有一份簡短的排錯清單：open-design.ai/quickstart。