ima2-gen 3.20.0 → 3.21.0

package/docs/README.zh-TW.md

@@ -1,39 +1,98 @@
-# ima2-gen
+<p align="center">
+  <img src="../assets/brand/banner.png" alt="ima2 — 為人與程式設計代理打造的本機影像與影片工作室" width="100%">
+</p>
 
-<!-- runtime-install:generated:start -->
-| Contract | Value |
-|---|---|
-| Node engine | `>=22` |
-| npm toolchain | `npm@11.18.0` |
-| Release Node | `24.17.0` |
-| CLI entry | `bin/ima2.js` |
-| OpenAI SDK | `^7.4.0` |
-| Express | `^5.1.0` |
-<!-- runtime-install:generated:end -->
+<h3 align="center">在自己的電腦上生成、分支並精修影像與影片。</h3>
+<p align="center">一個本機工作室，把 GPT、Grok、Gemini、NovelAI 和 ComfyUI 放在一起。<br>可以在瀏覽器、Mac 應用程式、CLI 中使用，也可以交給你的程式設計代理。</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/ima2-gen"><img src="https://img.shields.io/npm/v/ima2-gen?style=flat-square&labelColor=18181b&color=3f3f46&logo=npm&label=npm" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/ima2-gen"><img src="https://img.shields.io/npm/dm/ima2-gen?style=flat-square&labelColor=18181b&color=3f3f46&label=downloads" alt="npm downloads"></a>
+  <img src="https://img.shields.io/node/v/ima2-gen?style=flat-square&labelColor=18181b&color=3f3f46&logo=node.js&label=node" alt="Node.js version">
+  <a href="https://github.com/lidge-ai/ima2-gen/stargazers"><img src="https://img.shields.io/github/stars/lidge-ai/ima2-gen?style=flat-square&labelColor=18181b&color=3f3f46&logo=github&label=stars" alt="GitHub stars"></a>
+  <a href="../LICENSE"><img src="https://img.shields.io/badge/license-MIT-3f3f46?style=flat-square&labelColor=18181b" alt="MIT license"></a>
+</p>
+
+```bash
+npm install -g ima2-gen
+ima2 serve
+```
+
+<p align="center">
+  <a href="https://github.com/lidge-ai/ima2-gen/releases?q=desktop&expanded=true"><img src="https://img.shields.io/badge/macOS-Apple%20Silicon%20.dmg-18181b?style=for-the-badge&logo=apple&logoColor=white" alt="下載 Mac 應用程式 (.dmg)"></a>
+  <a href="#one-line-installers"><img src="https://img.shields.io/badge/Windows%20%C2%B7%20Linux-one--line%20installer-18181b?style=for-the-badge&logo=gnubash&logoColor=white" alt="Windows 與 Linux 一行安裝"></a>
+</p>
+
+<table>
+<tr>
+<td width="42%" valign="middle">
+
+### 創作
+
+寫下提示詞、附上參考圖，選擇通道和模型就好。每個結果都會保留提示詞、耗時和設定，可以直接複製、接著創作，或做成影片。
+
+</td>
+<td width="58%">
+  <img src="../assets/screenshots/readme-create.webp" alt="深色模式的創作畫面：左側是提示詞輸入框，中間是鍍鉻雕塑結果，右側是 GPT OAuth 設定" width="100%">
+</td>
+</tr>
+<tr>
+<td width="42%" valign="middle">
+
+### 在節點圖中分支
 
-安裝程式從套件中繼資料讀取 Node.js 最低版本，並在啟動伺服器前執行離線安裝檢查。
+保留一張滿意的圖，同時往多個方向推進。每個分支都記得自己的父節點，原圖不會被覆蓋。
+
+</td>
+<td width="58%">
+  <img src="../assets/screenshots/readme-node.webp" alt="節點圖：一件鍍鉻雕塑分出金色、大理石與森林三個版本" width="100%">
+</td>
+</tr>
+<tr>
+<td width="42%" valign="middle">
+
+### 在 Canvas Mode 中精修
+
+標註、擦除、去背，並以真正的 Alpha 通道匯出。一鍵 GPT 透明化會先由伺服器確認實際透明度，再告訴你結果。
+
+</td>
+<td width="58%">
+  <img src="../assets/screenshots/readme-canvas.webp" alt="Canvas Mode：棋盤格背景上的透明相機去背圖與畫布工具列" width="100%">
+</td>
+</tr>
+<tr>
+<td width="42%" valign="middle">
+
+### 從首頁開始
+
+查看哪些通道已就緒，直接輸入提示詞，不必翻資料夾就能接續最近的作品。
+
+</td>
+<td width="58%">
+  <img src="../assets/screenshots/readme-home.webp" alt="首頁：通道就緒狀態、提示詞輸入框與最近作品格狀清單" width="100%">
+</td>
+</tr>
+</table>
 
 <p align="center">
-  <img src="../assets/logo.png" alt="ima2-gen logo" width="240">
+  <a href="../README.md">English</a> · <a href="README.ko.md">한국어</a> · <a href="README.ja.md">日本語</a> · <a href="README.zh-CN.md">简体中文</a> · <b>正體中文</b> · <a href="https://lidge-ai.github.io/ima2-gen/"><b>網站</b></a> · <a href="https://lidge-ai.github.io/ima2-gen/docs"><b>文件 →</b></a>
 </p>
 
-[![npm 版本](https://img.shields.io/npm/v/ima2-gen)](https://www.npmjs.com/package/ima2-gen)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org/)
-[![授權條款：MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../LICENSE)
+`ima2-gen` 是本機優先的視覺生成執行環境與工作室，讓人和程式設計代理在多個供應商之間執行可重現的影像與影片工作流程。它在你的電腦上執行一個小型伺服器，把所有作品存放在 `~/.ima2/generated`，只和你連線的供應商通訊：OpenAI OAuth/API、Grok OAuth/API、Antigravity CLI、Gemini API、AtlasCloud、MiniMax、NovelAI，以及已註冊的 ComfyUI 工作流程。Runway 與 Higgsfield 是獨立的 MCP 整合。提示詞與參考圖只會送往你為每個工作選擇的供應商。
 
-> 🌐 **線上網站**：[lidge-jun.github.io/ima2-gen](https://lidge-jun.github.io/ima2-gen/) · [한국어](https://lidge-jun.github.io/ima2-gen/ko/)
->
-> 📖 **開發者文件**：[文件網站](https://lidge-jun.github.io/ima2-gen/docs) · [한국어](https://lidge-jun.github.io/ima2-gen/ko/docs)
->
-> **閱讀其他語言版本**：[English](../README.md) · [한국어](README.ko.md) · [日本語](README.ja.md) · [正體中文](README.zh-TW.md) · [简体中文](README.zh-CN.md)
+## 快速開始
 
-`ima2-gen` 是面向使用者與程式設計代理的本機優先視覺生成執行環境與工作室，支援跨多個供應商的可重現圖片與影片工作流程。
+### Mac 應用程式（Apple Silicon）
 
-全域安裝後，可在 OpenAI OAuth/API、Grok OAuth/API、Antigravity CLI、Gemini API、AtlasCloud 與 MiniMax 組成的 8 個 core lane 中生成圖片與影片。Runway 與 Higgsfield 屬於獨立的 MCP integration。
+桌面應用程式以 Mac 視窗和選單列圖示執行同一個本機伺服器與工作室。它以 Developer ID 簽署並通過 Apple 公證，內建執行環境，不需要另外安裝 Node.js。
 
-![ima2-gen 播放影片時的畫面，右側圖庫顯示產生的圖片與影片。](../assets/screenshots/classic-generate-light.png)
+1. 從最新的 [ima2 Desktop 版本](https://github.com/lidge-ai/ima2-gen/releases?q=desktop&expanded=true) 下載 `ima2-<version>-mac-arm64.dmg`。
+2. 打開 DMG，把 **ima2** 拖進 **應用程式** 資料夾。
+3. 啟動 ima2，在歡迎畫面選擇一個供應商。
 
-## 快速入門
+檢查碼、更新與設定請見 [Mac 應用程式指南](https://lidge-ai.github.io/ima2-gen/docs/desktop)。在 Intel Mac、Windows 或 Linux 上，請使用 npm 或一行安裝。
+
+### npm
 
 ```bash
 npm install -g ima2-gen
@@ -41,377 +100,424 @@ ima2 setup
 ima2 serve
 ```
 
-接著在瀏覽器開啟 `http://localhost:3333`。
-
-### Docker
-
-```bash
-docker build -t ima2-gen .
-docker run -d -p 3333:3333 -e IMA2_LAN_TOKEN=change-me -v ima2-data:/data ima2-gen
-```
+接著打開 `http://localhost:3333`。如果 `3333` 已被佔用，`ima2-gen` 會改用下一個可用連接埠，並把實際網址寫入 `~/.ima2/server.json`，`ima2 open` 一定會開啟正確的網址。
 
-請參閱 [DOCKER.md](DOCKER.md)，了解 Compose 用法、必要環境變數與限制。
+### 用 CLI 生成第一張圖
 
-若要從 CLI 產生內容，可以先查看目前可用的模型清單，並設定圖片／影片的預設模型：
+先設定一次影像與影片的預設目標，再開始生成：
 
 ```bash
 ima2 models
-ima2 defaults set image oauth/gpt-5.6-luna
+ima2 defaults set image oauth/gpt-6-luna
 ima2 defaults set video grok/grok-imagine-video-1.5
 ima2 gen "a clean product photo of a red guitar pedal"
 ima2 video "a cat playing piano" --duration 5 --resolution 720p
-ima2 video "animate this scene" --ref photo.png --duration 10
 ```
 
-在設定 CLI 目標前，`ima2 gen` 與生成模式的 `ima2 video` 會以 `NO_DEFAULT_MODEL` 安全失敗；除非該次呼叫指定 `--model <lane>/<model>` 或明確指定 `--provider <lane>`。這能避免升級後不知情地切換提供者或計費路徑。
+在設定 CLI 目標之前，`ima2 gen` 和生成模式的 `ima2 video` 會以 `NO_DEFAULT_MODEL` 停止，除非呼叫時明確傳入 `--model <lane>/<model>` 或 `--provider <lane>`。升級絕不會悄悄切換供應商或計費通道。
 
-如果 `3333` 已被其他程式使用，`ima2-gen` 會改用下一個可用的連接埠，並把實際網址寫入 `~/.ima2/server.json`。請使用 `ima2 open`，或開啟終端機列出的網址，不要假設連接埠一定是 `3333`。
+<a id="one-line-installers"></a>
 
-> **想使用 npx？**請參閱 [NPX_QUICKSTART.md](NPX_QUICKSTART.md) 的 `npx ima2-gen serve` 使用方式。
+### 一行安裝（不需要 npm）
 
-### 一鍵安裝（不需要 npm）
+每個指令碼都會檢查套件宣告的 Node.js 最低版本，必要時安裝 Node LTS，安裝一次 ima2-gen，並在啟動 `ima2 serve` 之前執行離線安裝檢查。它不會停止無關的程序，也不會清除全域鎖定。
 
-如果沒有 Node.js 或 npm，可以使用對應平台的安裝腳本。腳本會偵測環境、視需要安裝 Node LTS，最後安裝 ima2-gen。
+**macOS**
 
-**macOS：**
 ```bash
-curl -fsSL https://lidge-jun.github.io/ima2-gen/install-mac.sh | bash
+curl -fsSL https://lidge-ai.github.io/ima2-gen/install-mac.sh | bash
 ```
 
-**Windows（PowerShell）：**
+**Windows (PowerShell)**
+
 ```powershell
-irm https://lidge-jun.github.io/ima2-gen/install-windows.ps1 | iex
+irm https://lidge-ai.github.io/ima2-gen/install-windows.ps1 | iex
 ```
 
-**Linux/WSL：**
+**Linux / WSL**
+
 ```bash
-curl -fsSL https://lidge-jun.github.io/ima2-gen/install-linux.sh | bash
+curl -fsSL https://lidge-ai.github.io/ima2-gen/install-linux.sh | bash
 ```
 
-每個腳本都會檢查支援的 Node 版本，必要時使用 nvm、fnm、Homebrew 或 winget 安裝 Node LTS。npm 安裝只嘗試一次，通過 `ima2 doctor --installation --json` 後才啟動伺服器。腳本不會終止其他程序或刪除全域鎖定檔案。
+<details>
+<summary><b>Docker</b></summary>
 
-### 設定
+```bash
+docker build -t ima2-gen .
+docker run -d -p 3333:3333 -e IMA2_LAN_TOKEN=change-me -v ima2-data:/data ima2-gen
+```
 
-`ima2 setup` 提供四種驗證方式：
+compose 用法、必要的環境變數與限制請見 [Docker 文件](DOCKER.zh-TW.md)。
 
-1. **GPT OAuth** — 使用 ChatGPT 帳戶登入（免費，僅支援圖片）
-2. **Grok OAuth** — 使用 xAI／Grok 帳戶登入（支援圖片與影片）
-3. **兩者皆用** — 同時使用 GPT OAuth 與 Grok OAuth（完整功能）
-4. **Web 設定** — 在 Web UI 中設定所有選項
+</details>
 
-影片生成需要 Grok OAuth（選項 2 或 3）。如果已經設定 GPT OAuth、想再加入影片支援，請另外執行 `ima2 grok login`；預設會使用手動貼上驗證資訊的流程。
+<details>
+<summary><b>設定、更新與 npx</b></summary>
 
-### 更新中
+`ima2 setup` 提供四種驗證方式：
+
+1. **GPT OAuth** — 以 ChatGPT 帳號登入（影像）
+2. **Grok OAuth** — 以 xAI/Grok 帳號登入（影像與影片）
+3. **Both** — 同時使用 GPT OAuth 與 Grok OAuth
+4. **Web setup** — 在網頁介面完成所有設定
 
-使用 Ctrl+C 停止執行中的伺服器，然後執行：
+影片生成需要 Grok OAuth（選項 2 或 3）。如果已在使用 GPT OAuth，可以執行 `ima2 grok login` 加入影片功能，預設採用手動貼上流程。
+
+更新時，先用 Ctrl+C 停止伺服器（或在另一個終端機執行 `ima2 stop`），再執行：
 
 ```bash
 npm install -g ima2-gen@latest
 ```
 
-按下 Ctrl+C 會關閉資料庫、停止子程序並釋放檔案鎖定。如果 Windows 顯示 `EBUSY`，請先手動停止對應的 ima2 服務，再重新安裝。安裝器不會自動終止程序或提高權限。
+Ctrl+C 會乾淨地結束：關閉資料庫、停止子程序並釋放檔案鎖定。若安裝失敗，請查看 npm 的權限訊息，或自行停止對應的 `ima2` 程序；安裝程式不會大範圍清理程序。
+
+想用 npx？請參考 [npx 快速開始](NPX_QUICKSTART.zh-TW.md)。
 
-## 功能總覽
+</details>
 
-- **經典模式**：產生、編輯、重複使用目前圖片、貼上參考圖，或從歷史記錄繼續工作。
-- **節點模式**：從一張好圖片分支出多個方向，同時保留原始結果。
-- **多階段批次**：從一個提示詞啟動多個經典模式結果，逐一查看進度，再從最佳結果繼續。
-- **影片生成**：使用文字、單張圖片或多張參考圖，透過 Grok 影片模型建立短片。SSE 串流會顯示「規劃 → 已提交 → 進度百分比 → 完成」；影片影格按鈕（第一格／中間格／最後一格）可擷取並複製關鍵影格。
-- **分鏡模式**：在編輯器中開啟分鏡模式，維持連續影格中的角色與場景一致性。圖片與影片生成都支援此模式；圖片關鍵影格可用於影片製作，影片片段則會沿用角色／環境鎖定規則。
-- **畫布模式**：縮放、平移、加註解、擦除、清理背景、預覽透明圖片，並匯出透明度或指定底色的版本。
-- **本機圖庫**：將產生的資產保存在電腦上，並以工作階段管理歷史記錄。圖庫預設顯示目前工作階段；切換「所有圖片」即可查看完整歷史記錄，而且範圍設定會跨工作階段保留。每張圖片的產生時間與推理強度都會記錄在結果中繼資料裡，重新載入後仍可查看。
-- **參考圖片**：拖放、貼上並附加最多 5 張圖片參考，或最多 7 張影片參考；大型圖片會在上傳前自動壓縮。
-- **提示詞庫匯入**：將本機提示詞包、GitHub 資料夾、精選來源與 GPT 圖片提示詞提示包匯入內建提示詞庫。
-- **行動版介面**：在小螢幕上使用應用程式列、撰寫面板與精簡設定切換。
-- **可觀測的工作**：透過安全日誌與請求 ID 追蹤目前及最近的工作。
+## 能做什麼
 
-### 代理技巧
+- **創作**：生成、編輯、重複使用目前的影像、貼上參考圖、從歷史紀錄接續。開啟多模式後，一個提示詞就能同時送出多個候選，看著它們一格一格完成。所有控制項、多模式配方、Direct 模式與 reasoning effort 都寫在 [Prompt Studio 手冊](PROMPT_STUDIO.zh-TW.md) 中。 參考圖在影像生成中最多 5 張、影片中最多 14 張，大型影像會在上傳前壓縮。
+- **節點圖**：把一張好圖分支到多個方向。根節點使用本機參考圖，子節點以父節點影像為來源。完成的工作會依請求 ID 回填到節點，所以重新整理頁面或圖版本衝突後，結果仍能復原。
+- **Canvas Mode**：縮放、平移、懸停高亮的標註、橡皮擦、群組、復原、便利貼、背景清理，以及保留 Alpha 或指定底色匯出。需要自足的畫布文件就選 **SVG (embedded raster)**，需要真正的向量路徑就選 **Trace to SVG (vector)**。**GPT transparency** 按鈕透過 OAuth i2i 通道去背，並依解碼後的位元組回報 `alphaVerified`。 儲存的畫布版本不會出現在圖庫與歷史列中，但可以在 Canvas Mode 重新開啟，或作為下一次的參考圖。
+- **影片**：透過 Grok 影片模型進行文字轉影片、影像轉影片與參考轉影片，提供進度顯示與 First/Mid/Last 影格複製按鈕。**Storyboard mode** 讓連續畫面中的人物與場景保持一致。 進度透過 SSE 依 planning → submitted → 進度百分比 → done 顯示。分鏡模式下，影像關鍵影格會依影片製作來構圖，影片片段會沿用人物與環境的鎖定規則。
+- **點陣轉向量**：透過 `ima2 vectorize`、AssetGen/Assets 或 Canvas 匯出，把扁平點陣圖描成真正的 SVG 路徑。
+- **NovelAI 雙提示詞**：選擇 NovelAI 後，創作、首頁與行動版輸入面板會並排顯示 **Positive prompt** 與 **Undesired content**。 輸入區域窄於 719px 時兩欄會上下堆疊。
+- **提示詞庫**：匯入本機提示詞包、GitHub 資料夾與精選的 GPT-image 提示，並在本機建立索引搜尋。
+- **Prompt Builder**：以文字後端琢磨意圖。可在 Settings > Providers 維持 Auto，或固定後端與模型，**via &lt;backend&gt;** 徽章會顯示實際回應的後端。 選擇 GPT 後端時，預設模型是 `gpt-6-luna`。
+- **本機圖庫**：所有影像與影片都留在本機，附有依工作階段區分的歷史紀錄、生成時間與 reasoning effort 中繼資料。 預設只顯示目前的工作階段，All Images 切換可以展開全部歷史，所選的預設範圍在工作階段之間維持不變。
+- **淺色與深色主題**：以 token 為基礎、符合 AA 對比度的配色，可在淺色、深色與跟隨系統之間無閃爍切換。
+- **行動版外殼**與**工作可觀測性**：小螢幕上的應用程式列、輸入面板與精簡的設定切換，以及附安全日誌和請求 ID 的進行中、最近工作清單。
 
-ima2-gen 內建三套提供給 AI 程式碼代理使用的技能。這些 Markdown 指令檔案可協助代理建立圖片／影片的結構化工作流程、製作前端資產，以及探索設計方向。
+Card News 是僅供開發的實驗功能，在發佈版本中預設隱藏。
 
-|技能|命令|它涵蓋什麼|
-|-------|---------|----------------|
-| **核** | `ima2 skill` | CLI參考、提示協定、提供者路由、韓文文字、影片工作流程|
-| **前端** | `ima2 skill front` | 資產流程（平行產生、變體選擇、提供者路由）、Web 動態／影片、響應式設計、無障礙、防止 AI 味設計，以及 30 多份參考文件 |
-| **UI／UX 設計** | `ima2 skill uiux` | 以圖片為核心的設計方向探索、UX 狀態、設計語彙、產品個性、DESIGN.md 工作流程，以及 18 份參考文件 |
+### 代理技能
+
+ima2-gen 內建三個 Markdown 技能，供程式設計代理載入，為影像與影片生成、前端素材與設計方向探索提供結構化流程。
+
+| 技能 | 指令 | 內容 |
+|------|------|------|
+| **Core** | `ima2 skill` | CLI 參考、提示詞寫法、供應商路由、韓文文字、影片工作流程 |
+| **Frontend** | `ima2 skill front` | 素材管線（平行生成、候選挑選、供應商路由）、網頁動態與影片、響應式、無障礙、anti-slop，30 多個參考檔案 |
+| **UI/UX Design** | `ima2 skill uiux` | 以影像為起點的設計方向探索、UX 狀態、design-ism、產品個性、DESIGN.md 工作流程，21 個參考檔案 |
 
 ```bash
-ima2 skill ls            # list available skills
-ima2 skill front         # print the frontend skill
-ima2 skill uiux          # print the design skill
-ima2 skill front path    # print file path (for agents)
-ima2 skill front --json  # JSON wrapper (for agents)
-ima2 skill front refs    # list reference modules (35 files)
-ima2 skill front ref motion        # load one reference module
-ima2 skill install --dir <path>     # install skills to agent's skill dir
-ima2 skill install --tmp            # install to temp dir (fallback)
+ima2 skill ls                   # 列出技能
+ima2 skill front path          # 輸出檔案路徑（供代理使用）
+ima2 skill front --json        # JSON 包裝（供代理使用）
+ima2 skill front refs           # 列出參考模組
+ima2 skill front ref motion     # 載入一個參考模組
+ima2 skill install --dir <path> # 安裝到代理的技能資料夾
+ima2 skill install --tmp        # 安裝到暫存資料夾（備案）
 ```
 
-前端與 UI／UX 技能是針對 ima2 工作流程整理的正式產品設計工程指南，涵蓋字體、色彩系統、版面配置、韓文 UX 模式、動態編排與視覺驗證；每個資產產生步驟都對應到 `ima2 gen`、`ima2 video` 與 `ima2 multimode` 指令。
+## 供應商與模型
 
-### SSE多路復用
+| 通道 | 驗證 | 影像 | 影片 | 說明 |
+|---|---|:-:|:-:|---|
+| `oauth` | ChatGPT 登入，由 ima2 直接呼叫 ChatGPT | ✓ | | 預設通道；GPT-6 規劃，`gpt-image-2` 出圖，`gpt-6-luna` |
+| `api` | `OPENAI_API_KEY` | ✓ | | Responses API `image_generation` 工具，支援遮罩、多模式、節點 |
+| `grok` | xAI OAuth（`ima2 grok login`） | ✓ | ✓ | 呼叫 Images API 前先做網頁搜尋與規劃 |
+| `grok-api` | `XAI_API_KEY` | ✓ | ✓ | 直接呼叫 xAI Images API |
+| `gemini-api` | `GEMINI_API_KEY` 或 Vertex 服務帳戶 | ✓ | | `nano-banana-2`、`nano-banana-pro`，512px 到 4K |
+| `agy` | Antigravity CLI | ✓ | | 透過 `agy -p` 使用 Gemini `nano-banana-2` / `nano-banana-pro` |
+| `nai` | NovelAI API 權杖 | ✓ | | 四個 NAI Diffusion 模型，文字轉影像 |
+| `comfy` | 本機 ComfyUI | ✓ | ✓ | 已註冊的影像與影片工作流程 |
+| `atlascloud` | AtlasCloud API 金鑰 | ✓ | | `openai/gpt-image-2` 生成與編輯 |
+| `minimax` | MiniMax API 金鑰 | ✓ | | `image-01`、`image-01-live` |
+| `runway`、`higgsfield` | MCP 連線 | ✓ | ✓ | 獨立的 MCP 整合 |
 
-Web UI 使用單一 `GET /api/events` 伺服器發送事件（SSE）連線，接收所有生成進度。多階段、節點與影片請求會以非同步 POST（`202 { requestId }`）提交，進度事件則透過共用事件匯流排多工傳送。這避免了瀏覽器最多 6 條連線的限制，不再因同時生成而讓圖庫卡住。未傳送 `async: true` 的 CLI 用戶端仍會收到每個請求各自的 SSE 串流，以維持向下相容性。
+GPT OAuth 通道使用三個 GPT-6 模型：預設 **`gpt-6-luna`**，另有 `gpt-6-sol`，以及推理時間最長、速度最慢的 `gpt-6-astra`。所選模型負責規劃畫面，`gpt-image-2` 負責出圖。`gpt-5.6-luna` 等舊的 OAuth 模型 ID 在已儲存的設定與腳本中仍可使用，會對應到相應的 GPT-6 模型。API key 通道保留自己的清單：`gpt-5.6-luna`（預設）、`gpt-6-astra`、`gpt-5.6-terra`、`gpt-5.6-sol`、`gpt-5.5`、`gpt-5.4`、`gpt-5.4-mini`。應用程式也提供品質（`low`、`medium`、`high`）與審核等級（`auto`、`low`）控制。
 
-## 提供者路徑
+<details>
+<summary><b>供應商詳情（English）</b></summary>
 
-圖片生成可以使用本機 Codex／ChatGPT OAuth、已設定的 OpenAI API 金鑰、內建 Grok 提供者，或透過 Antigravity CLI 使用 Gemini 提供者。
+- `provider: "oauth"` signs in with your ChatGPT session and calls ChatGPT's Codex backend from the ima2 server process, with no separate proxy. A GPT-6 model plans the prompt and `gpt-image-2` renders it; Direct mode skips the planner. Transparent backgrounds and image edits run on the same lane.
+- `provider: "api"` calls the OpenAI Responses API with the hosted `image_generation` tool.
+- `provider: "grok"` calls `https://api.x.ai` directly with the xAI OAuth session stored in `~/.progrok/auth.json`, running mandatory xAI Web Search plus a planner pass (default: `grok-4.3`, configurable in settings or via `--planner-model`) before the xAI Images API call. `grok-4.5` and `grok-4.6` are also selectable. Log in once with `ima2 grok login` or the Settings **Switch Account** button; the session refreshes itself two minutes before expiry.
+- `provider: "grok-api"` calls the xAI Images API directly with `XAI_API_KEY` (no OAuth session involved).
+- `provider: "nai"` calls the NovelAI image API with a persistent API token (saved in Settings > API Keys or `NOVELAI_API_KEY`; no fixed token prefix is required). Four models: `nai-diffusion-5-full`, `nai-diffusion-5-curated`, `nai-diffusion-4-5-full`, `nai-diffusion-4-5-curated`. Responses arrive as a ZIP archive that ima2 decodes to PNG. Text-to-image only — reference images, edits, and masks are refused rather than silently dropped. Browser and CLI surfaces expose negative prompt, sampler/schedule, steps/guidance/CFG rescale, seed, presets, Auto SMEA, Decrisper, Variety+, and V5 alpha.
+- `provider: "agy"` spawns the Antigravity CLI (`agy -p`) to generate images via Google Gemini's `default_api:generate_image` tool (models: `nano-banana-2` and `nano-banana-pro`). Output is fixed at 1024×1024 JPEG, max 3 reference images. No web search, quality, or size controls.
+- `provider: "gemini-api"` calls the Google Generative Language API directly. Supports two models: `nano-banana-2` (Gemini 3.1 Flash Image) and `nano-banana-pro` (Gemini 3 Pro Image). Auth is via `GEMINI_API_KEY` env var, web UI key management, or a Vertex AI service account JSON (`VERTEX_SERVICE_ACCOUNT_JSON`). When both an API key and Vertex credentials are configured, Vertex takes priority. Supports variable aspect ratios (1:1 through 21:9) and four resolution tiers (512px, 1K, 2K, 4K); these controls are only honored on the direct API path — the Vertex AI endpoint ignores aspect/size because it does not accept the `response_format` field. Per-model cost differs: `nano-banana-2` (Flash): 512=$0.001, 1K=$0.003, 2K=$0.004, 4K=$0.006; `nano-banana-pro`: 1K=$0.007, 2K=$0.007, 4K=$0.013. No web search or mask controls.
+- API-key generation supports classic generate, edit, mask-guided edit, multimode, and node generation.
+- Grok generation supports Classic, Node, and Agent flows. If a Classic reference, Node parent image, or Agent current image is present, ima2 switches the final Grok call to xAI image edit so image-to-image context is preserved.
 
-- `provider: "oauth"` 使用本機 Codex OAuth 代理程式。
-- `provider: "api"` 使用 OpenAI Responses API 的 `image_generation` 工具。
-- `provider: "grok"`使用`~/.progrok/auth.json`中的xAI OAuth工作階段直接呼叫`https://api.x.ai`, 強制運行xAI網路搜尋加上規劃者通行證（預設：`grok-4.5`，可在設定中配置或透過`--planner-model`），然後調用xAI圖片API。`grok-4.3`仍然可以作為顯式相容性覆蓋使用。用`ima2 grok login`或網頁UI登入一次；權杖在過期前 2 分鐘自動更新。
-- `provider: "grok-api"`稱為xAI圖片API直接與`XAI_API_KEY`（使用API金鑰而不是OAuth工作階段）。
-- `provider: "agy"` 啟動 Antigravity CLI（`agy -p`），透過 Google Gemini 的 `default_api:generate_image` 工具產生圖片（模型：`nano-banana-2`）。輸出固定為 1024×1024 JPEG，最多 3 張參考圖，不提供網路搜尋、品質或尺寸控制。
-- `provider: "gemini-api"` 直接呼叫 Google Generative Language API。支援 `nano-banana-2`（Gemini 3.1 Flash Image）與 `nano-banana-pro`（Gemini 3 Pro Image）；驗證方式包括 `GEMINI_API_KEY` 環境變數、Web UI 金鑰管理，或 Vertex AI 服務帳戶 JSON（`VERTEX_SERVICE_ACCOUNT_JSON`）。同時設定 API 金鑰與 Vertex 憑證時，優先使用 Vertex。支援 1:1 至 21:9 的長寬比與 512px、1K、2K、4K 四種解析度；這些控制只有直接 API 路徑有效，Vertex AI 端點不接受 `response_format` 欄位，因此會忽略長寬比與尺寸設定。
-- API 金鑰產生支援經典模式的產生、編輯、遮罩導向編輯、多階段與節點產生。
-- Grok 產生支援經典、節點與代理模式。如果有經典參考圖、節點父圖片或代理模式目前圖片，ima2 會將最後一次 Grok 呼叫切換為 xAI 圖片編輯，以保留圖片轉圖片的上下文。
+If no provider is specified, the app keeps the current GPT OAuth/default behavior. GPT OAuth defaults to `gpt-6-luna` and API-key generation to `gpt-5.6-luna`; the API-key path also defaults to `low` reasoning and `1024x1024` unless the request passes validated options. Grok image generation defaults to `grok-imagine-image-2.0`.
 
-如果未指定提供者，應用程式將保留目前的GPT OAuth/預設行為。GPT OAuth和API-金鑰產生預設為`gpt-5.6-luna`;這API-key路徑也預設為`low`推理和`1024x1024`除非請求通過了經過驗證的選項。Grok影像生成預設為`grok-imagine-image-quality`.
+One caveat on the OAuth Grok lane: xAI documents only `/v1/me` as accepting an OAuth token, so image and video calls to `api.x.ai` with that token ride an undocumented path. It works today — progrok relied on the same path — but it carries no compatibility promise. If xAI closes it, `provider: "grok-api"` with `XAI_API_KEY` is the documented route and stays unaffected.
 
-關於OAuth Grok通道有一點需要說明：xAI只把`/v1/me`記錄為接受OAuth權杖的端點，所以用該權杖呼叫`api.x.ai`的影像與影片介面走的是未文件化的路徑。它目前可用——progrok一直依賴同一條路徑——但沒有任何相容性承諾。如果xAI關閉這條路徑，用`XAI_API_KEY`的`provider: "grok-api"`是有文件的方案，且不受影響。
+Grok image generation exposes a Fast/Best model picker (`grok-imagine-image` / `grok-imagine-image-quality`; new sessions start on `grok-imagine-image-2.0`) and a size picker (aspect ratio + 1k/2k resolution). The Settings page prefers the Grok Build weekly credits percentage and reset time from `GET /v1/billing?format=credits`; if that source is unavailable, it falls back to the legacy monthly billing window and `$used/$limit`. A **Switch Account** button starts a device-code OAuth flow (`POST /api/auth/switch`) for re-authenticating without leaving the app.
 
-Grok圖像生成公開了模型選擇器（`grok-imagine-image` / `grok-imagine-image-quality`）和尺寸選擇器（長寬比 + 1k/2k 解析度）。設定頁面更喜歡Grok建立每週積分百分比並重置時間`GET /v1/billing?format=credits`;如果該來源不可用，則會退回到傳統的每月計費窗口，並且`$used/$limit`. A **切換帳戶**按鈕啟動設備代碼OAuth流動 （`POST /api/auth/switch`）無需離開應用程式即可重新進行身份驗證。
+Grok video generation defaults to canonical `grok-imagine-video-1.5`; `grok-imagine-video` remains available for base-model-only Ref2V, V2V edit, and extension paths, and the legacy `grok-imagine-video-1.5-preview` string is accepted as an alias. Three modes are auto-detected from reference count: text-to-video (0 refs), image-to-video (1 ref), and reference-to-video (2-14 refs; up to 15s on grok-imagine-video-1.5, 10s on grok-imagine-video). 1080p is available for `grok-imagine-video-1.5` prompt-only text-to-video and single image/frame image-to-video; prompt-only 1.5 uses the internal white-canvas I2V shim before the upstream request. Video controls include duration (1-15s), resolution (480p, 720p, 1080p when supported), and aspect ratio (1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, auto).
 
-Grok影片產生預設為規範`grok-imagine-video-1.5`; `grok-imagine-video`仍可用於僅限基本型號的 Ref2V、V2V 編輯和擴展路徑，以及舊版本`grok-imagine-video-1.5-preview`字串被接受作為別名。根據引用計數自動偵測三種模式：文字到影片（0 引用）、圖像到影片（1 引用）和引用到影片（2-14 引用；grok-imagine-video-1.5 最長 15 秒，grok-imagine-video 最長 10 秒）。 1080p 可用於`grok-imagine-video-1.5`僅提示文字到影片和單圖像/幀圖像到影片；僅提示 1.5 在上游請求之前使用內部白色畫布 I2V 填充程式。視訊控制包括持續時間（1-15秒）、解析度（480p、720p、1080p（如果支援））和寬高比（1:1、16:9、9:16、4:3、3:4、3:2、2:3、自動）。
+</details>
 
-![設定工作區顯示GPT OAuth活躍和API可用的密鑰提供者。](../assets/screenshots/settings-oauth-generation.png)
+## CLI
 
-## 型號指導
+<details>
+<summary><b>伺服器指令（English）</b></summary>
 
-該應用程式預設為**`gpt-5.6-luna`**用於影像生成和 Prompt Builder 規劃。較舊的受支援型號仍保留明確的兼容性選擇。
+| Command | Description |
+|---|---|
+| `ima2 serve [--dev]` | Start the local web server; `--dev` enables verbose server diagnostics |
+| `ima2 stop [--force]` | Stop the running server safely — graceful admin-API stop first, then SIGTERM/SIGKILL; verifies the advertised pid against `/api/health` so a recycled pid is never killed |
+| `ima2 service <sub>` | Background service: `install`/`uninstall`/`start`/`stop`/`restart`/`status`/`logs`/`repair` — launchd on macOS, systemd user unit on Linux, auto-start on login with crash restart |
+| `ima2 setup` | Reconfigure saved auth |
+| `ima2 status` | Show config and OAuth status |
+| `ima2 doctor` | Diagnose Node, package, config, and auth |
+| `ima2 doctor image-probe [--json]` | Run sanitized image probes for no-image diagnostics |
+| `ima2 open` | Open the web UI |
+| `ima2 reset` | Remove saved config |
 
-- `gpt-5.6-luna`— 目前影像和提示產生器預設值。
-- `gpt-6-astra`— 最新的 GPT 影像模型；可選，但不是預設值。
-- `gpt-5.6-terra` / `gpt-5.6-sol`- 目前的GPT-5.6當您的帳戶暴露它們時的替代方案。
-- `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`- 支援的相容性選擇。
+</details>
 
-應用程式也提供品質（`low`、`medium`、`high`）與內容審查（`auto`、`low`）控制。
+<details>
+<summary><b>用戶端指令（English）</b></summary>
 
-## 工作流程
+These require a running `ima2 serve`. The CLI covers every server route. The most common ones are below — the [full CLI reference](CLI.zh-TW.md) lists everything (generation, history, sessions, prompt library, annotations, Card News, observability, config).
 
-### 經典模式
+| Command | Description |
+|---|---|
+| `ima2 models [--kind image\|video] [--lane <lane>] [--json]` | List live lanes, status, model IDs, and capabilities |
+| `ima2 defaults set image\|video <lane>/<model>` | Persist the fail-closed CLI target for image or video generation |
+| `ima2 defaults reset image\|video` | Remove a persisted CLI generation target |
+| `ima2 gen <prompt> [--model <lane>/<model>]` | Generate from the CLI; requires an explicit target or saved image default |
+| `ima2 edit <file> --prompt <text>` | Edit an existing image |
+| `ima2 vectorize <input.png> [-o output.svg]` | Trace PNG/JPEG/WebP into a real SVG locally; no server or provider required |
+| `ima2 prompt build --message <text> [--backend <backend>] [--model <model>]` | Refine prompt intent through the configured or explicitly selected Prompt Builder backend; requires the local server |
+| `ima2 multimode <prompt>` | Multi-image SSE generation |
+| `ima2 video <prompt> [--model <lane>/<model>]` | Generate video through a Grok or MCP lane; requires an explicit target or saved video default |
+| `ima2 ls [--session <id>] [--favorites]` | List recent history |
+| `ima2 show <name> [--metadata]` | Reveal a generated asset |
+| `ima2 prompt ls -q <search>` | Search the prompt library |
+| `ima2 inflight ls [--terminal]` | List active and recent jobs (alias of `ps`) |
+| `ima2 config set <key> <value>` | Write to `~/.ima2/config.json` |
+| `ima2 ping` | Health-check the running server |
+
+The server advertises its actual port at `~/.ima2/server.json`. If `3333` is busy, the backend falls back to `3334+` and CLI commands follow the advertised URL. Override discovery with `--server <url>` or `IMA2_SERVER=http://localhost:3333`.
 
-如果想快速取得一個完整結果，請使用經典模式。
+```bash
+ima2 models --kind image
+ima2 gen "poster" --model oauth/gpt-6-luna --reasoning-effort high
+ima2 gen "1girl, blue hair" --model nai/nai-diffusion-5-full --nai-negative-prompt "lowres, watermark"
+ima2 vectorize logo.png -o logo.svg --json
+ima2 prompt build --message "Make this prompt production-ready" --backend auto --model auto
+ima2 edit input.png --prompt "make it rainy" --web-search
+ima2 multimode "two cats playing" -n 2
+ima2 video "a cat playing piano" --model grok/grok-imagine-video-1.5 --duration 5 --resolution 720p
+ima2 video "animate this" --model grok/grok-imagine-video-1.5 --ref photo.png --aspect-ratio 16:9
+ima2 inflight ls --terminal
+ima2 config set imageModels.reasoningEffort high
+```
 
-1. 輸入提示詞。
-2. 視需要附加或貼上參考圖。
-3. 選擇模型、品質、尺寸、格式與內容審查模式。
-4. 產生一張圖片，或開啟多階段模式，從同一個提示詞產生多個候選結果。
-5. 複製、下載、從結果繼續，或將結果送到畫布模式。
+Full reference: [docs/CLI.md](CLI.md).
 
-有關 Prompt Studio、多模式配方、直接模式的逐一控制指南，
-推理努力和畫廊最喜歡的行為，請參閱
-[提示工作室手冊](PROMPT_STUDIO.md).
+</details>
 
-![多模式序列，具有四個候選槽位，由側邊欄中的一個提示和活動作業歷史記錄產生。](../assets/screenshots/multimode-sequence.png)
+## 設定
 
-### 節點模式
+設定的優先順序是 `環境變數 > ~/.ima2/config.json > 內建預設值`。Prompt Builder 的設定會存成 `promptBuilder.backend`（`auto`、`oauth`、`grok`、`api` 或 `grok-api`）與 `promptBuilder.model`。在 Auto 模式下，Prompt Builder 依序嘗試 GPT OAuth、Grok、OpenAI API、Grok API，並使用第一個就緒的通道；明確選擇的後端會被固定，無法使用時回傳具型別的錯誤。
 
-當您想要探索分支時，請使用節點模式。
+<details>
+<summary><b>環境變數（English）</b></summary>
 
-![具有連接的生成卡和緊湊的每個節點元資料的節點模式。](../assets/screenshots/node-graph-branching.png)
+| Variable | Default | Description |
+|---|---:|---|
+| `IMA2_PORT` / `PORT` | `3333` | Web server port |
+| `IMA2_HOST` | `127.0.0.1` | Web server bind host |
+| `IMA2_OAUTH_PROXY_PORT` / `OAUTH_PORT` | `10531` | Port of the external GPT OAuth endpoint used with `IMA2_NO_OAUTH_PROXY=1` |
+| `IMA2_SERVER` | — | CLI target override |
+| `IMA2_CONFIG_DIR` | `~/.ima2` | Config and SQLite location |
+| `IMA2_ADVERTISE_FILE` | `~/.ima2/server.json` | Runtime discovery file |
+| `IMA2_GENERATED_DIR` | `~/.ima2/generated` | Generated image directory |
+| `IMA2_IMAGE_MODEL_DEFAULT` | `gpt-6-luna` | Server fallback image model |
+| `IMA2_PROMPT_BUILDER_BACKEND` | `auto` | Prompt Builder text backend (`auto`, `oauth`, `grok`, `api`, or `grok-api`); Settings persists the same value as `promptBuilder.backend` |
+| `IMA2_PROMPT_BUILDER_MODEL` | `auto` with Auto backend | Backend-scoped Builder model; Settings persists the same value as `promptBuilder.model` |
+| `IMA2_REASONING_EFFORT` | `medium` | Default reasoning effort for the default (GPT OAuth) path; one of `none`, `low`, `medium`, `high`, `xhigh`, `max` |
+| `IMA2_NO_OAUTH_PROXY` | — | Set `1` to send GPT OAuth calls to an OpenAI-compatible endpoint on `127.0.0.1:IMA2_OAUTH_PROXY_PORT` instead of ChatGPT directly |
+| `IMA2_CODEX_CLIENT_VERSION` | latest `@openai/codex` | Codex client version sent to ChatGPT; the automatic value is never lower than `0.157.0` |
+| `IMA2_LOG_LEVEL` | `info` | Normal serve defaults to `info`; dev mode defaults to `debug`; supports `debug`, `info`, `warn`, `error`, or `silent` |
+| `IMA2_INFLIGHT_TERMINAL_TTL_MS` | `300000` | Recent terminal job retention for debug views |
+| `OPENAI_API_KEY` | — | API key for the `provider: "api"` Responses API image path and auxiliary API-key features |
+| `XAI_API_KEY` | — | API key for `provider: "grok-api"` direct xAI Images API path |
+| `NOVELAI_API_KEY` | — | NovelAI persistent API token for `provider: "nai"` |
+| `IMA2_NAI_IMAGE_MODEL_DEFAULT` | `nai-diffusion-5-full` | Default NovelAI image model |
+| `IMA2_NAI_DEFAULT_AUTO_SMEA` | `false` | Default NovelAI Auto SMEA state |
+| `IMA2_NAI_DEFAULT_DECRISPER` | `false` | Default NovelAI Decrisper (`dynamic_thresholding`) state |
+| `IMA2_API_IMAGE_MODEL_DEFAULT` | `gpt-5.6-luna` | Default image model for `provider: "api"` |
+| `IMA2_API_REASONING_EFFORT` | `low` | Default reasoning effort for `provider: "api"` |
+| `IMA2_API_IMAGE_SIZE` | `1024x1024` | Default size for `provider: "api"` |
+| `IMA2_API_ALLOW_WEB_SEARCH` | `true` | Toggle web search for `provider: "api"` |
+| `IMA2_GROK_PLANNER_MODEL` | `grok-4.3` | Grok search/planner model; `grok-4.5`, `grok-4.6` and GPT planners are selectable (settings UI or `--planner-model`) |
+| `IMA2_GROK_PLANNER_TIMEOUT_MS` | `900000` | Timeout for the Grok planner call |
+| `IMA2_GROK_SEARCH_TIMEOUT_MS` | `300000` | Timeout for the Grok web-search brief (degrades instead of failing) |
+| `IMA2_GROK_VIDEO_PLAN_TOTAL_TIMEOUT_MS` | `1500000` | Ceiling on the whole video planning phase (clamped above search + planner) |
+| `IMA2_GROK_IMAGE_MODEL_DEFAULT` | `grok-imagine-image-2.0` | Default final Grok image model |
+| `IMA2_GROK_VIDEO_MODEL_DEFAULT` | `grok-imagine-video-1.5` | Default Grok video model |
+| `IMA2_GROK_GENERATION_TIMEOUT_MS` | `300000` | Timeout for the final Grok Images API call |
+| `IMA2_OAUTH_MASKED_EDIT_ENABLED` | `false` | Opt-in feature flag for masked-edit requests on the OAuth path (#31, groundwork only) |
+| `GEMINI_API_KEY` | — | API key for `provider: "gemini-api"` direct Generative Language API path |
+| `VERTEX_SERVICE_ACCOUNT_JSON` | — | Google service account JSON for Vertex AI auth with `provider: "gemini-api"`; takes priority over `GEMINI_API_KEY` when both are set |
+| `IMA2_AGY_BIN` | `agy` on PATH | Explicit path to the Antigravity CLI binary for `provider: "agy"` |
+| `IMA2_MAX_PARALLEL` | `24` | Server-wide parallel generation cap |
 
-每個節點都有自己的提示和結果。根節點可以附加本地引用；子節點使用父圖像作為其來源。已完成的作業透過請求 ID 與節點匹配，因此重新載入和圖形版本衝突可以恢復完成的結果。
+`IMA2_GROK_PROXY_HOST`, `IMA2_GROK_PROXY_PORT`, `IMA2_NO_GROK_PROXY`, and `IMA2_GROK_RESTART_*` were removed in 3.16 together with the local Grok proxy; they are no longer read, and setting them is harmless.
 
-### 畫布模式
+</details>
 
-當產生的影像已接近但需要在下一個提示之前進行有針對性的清理時，請使用畫布模式。
+<details>
+<summary><b>日誌模式（English）</b></summary>
 
-- 將視窗平移與選擇分開，以便您可以在縮放影像中移動而不會意外變更註釋。
-- 使用註釋、橡皮擦、多選、分組、撤消/重做和便簽，同時保持原始圖庫圖像可用。
-- 選擇背景清理種子，預覽蒙版，並將清理儲存為畫布版本。
-- 偵測透明影像並顯示棋盤預覽；使用保留的 alpha 或選擇的霧面顏色匯出。
-- 儲存的畫布版本對 Gallery 和 HistoryStrip 保持隱藏狀態，但 Canvas 模式可以重複使用它們並附加畫布版本作為下一個參考。
+`ima2 serve` keeps terminal output intentionally quiet: startup URLs, warnings, and errors stay visible, while request/node/OAuth structured logs are hidden by default.
 
-![帶有縮放控制項、註解標記、便籤和畫布工具列的畫布模式。](../assets/screenshots/canvas-mode-cleanup.png)
+Use `ima2 serve --dev`, `npm run dev`, or `IMA2_LOG_LEVEL=debug ima2 serve` when you need request IDs, node generation phases, OAuth stream diagnostics, or inflight state transitions. Explicit `IMA2_LOG_LEVEL` and `~/.ima2/config.json` values still override the built-in defaults.
 
-### 提示詞庫與匯入
+</details>
 
-現在可以從本機檔案、GitHub 資料夾、精選來源與 GPT 圖片提示詞包填入提示詞庫。匯入的提示詞會在本機建立索引，因此搜尋與排序不必在每個工作階段重新匯入相同來源。
+## 疑難排解
 
-![用於將提示導入庫的提示導入對話框，顯示GitHub匯入前的資料夾控制項、精選來源和搜尋提示候選者。](../assets/screenshots/prompt-import-dialog.png)
+<details>
+<summary><b><code>ima2 ping</code> 顯示無法連線到伺服器</b></summary>
 
-### 實驗卡新聞模式
+先執行 `ima2 serve`，再檢查 `~/.ima2/server.json`。也可以用 `ima2 ping --server http://localhost:3333` 直接指定網址。
 
-Card News 仍處於開發階段且處於實驗階段。預設是隱藏的
-除非明確啟用開發，否則發布運行時，且不應該
-尚未被視為穩定的公共功能。
+</details>
 
-### 設定
+<details>
+<summary><b>GPT OAuth 無法登入</b></summary>
 
-設定工作區將帳戶、模型、外觀與語言選項集中管理，讓生成側欄保持精簡。
+重新執行 `ima2 setup`（選項 1），確認 `ima2 status`，然後重新啟動 `ima2 serve`。
 
-![具有帳戶導航和產生模型控制項的設定工作區。](../assets/screenshots/settings-workspace.png)
+</details>
 
-## CLI命令
+<details>
+<summary><b>在代理/VPN 網路中反覆出現 <code>fetch failed</code></b></summary>
 
-### 伺服器
+GPT OAuth 請求由 `ima2 serve` 行程直接送往 `chatgpt.com`。需要代理的網路請開啟代理用戶端的 TUN/TURN 類模式。若無法這麼做，請在啟動伺服器的終端機同時設定 `HTTPS_PROXY` 與 `NODE_USE_ENV_PROXY=1`；Node.js 22.21+ 與 24+ 只有在設定第二個變數時才會讀取 `HTTPS_PROXY`；更早的 Node.js 兩者都會忽略，請改用 TUN 模式。在 Windows 上，也請檢查開機自動啟動的網路攔截工具，包括 SecretDNS 這類 DNS/封包分割繞過工具，即使瀏覽器看起來正常，它們也可能破壞 OAuth 或影像回應。
 
-|命令|描述|
-|---|---|
-| `ima2 serve [--dev]` |啟動本地網路伺服器；`--dev`啟用詳細的伺服器診斷|
-| `ima2 setup` |重新配置已儲存的身份驗證|
-| `ima2 status` | 顯示設定與 OAuth 狀態 |
-| `ima2 doctor` |診斷節點、套件、配置和身份驗證|
-| `ima2 doctor image-probe [--json]` |運行經過淨化的影像探針進行無影像診斷|
-| `ima2 open` |開啟網路UI |
-| `ima2 reset` |刪除已儲存的配置|
+</details>
 
-### 客戶
+<details>
+<summary><b>影像生成出現 <code>API_KEY_REQUIRED</code></b></summary>
 
-以下指令都需要先執行 `ima2 serve`。CLI 覆蓋伺服器提供的各項功能；下面列出最常用的指令，完整清單請參閱 [CLI 參考](CLI.md)（包含產生、歷史記錄、工作階段、提示詞庫、註解、Card News、可觀測性與設定）。
+使用 `provider: "api"` 前，請設定 `OPENAI_API_KEY` 或設定 API key。預設的 GPT OAuth 路徑不需要 API 金鑰。
 
-|命令|描述|
-|---|---|
-| `ima2 models [--kind image\|video] [--lane <lane>] [--json]` |列出即時車道、狀態、型號 ID 和功能|
-| `ima2 defaults set image\|video <lane>/<model>` |堅持失敗關閉CLI影像或影片生成目標|
-| `ima2 defaults reset image\|video` |刪除一個持久化的CLI世代目標|
-| `ima2 gen <prompt> [--model <lane>/<model>]` |生成自CLI;需要明確的目標或已儲存的影像預設值|
-| `ima2 edit <file> --prompt <text>` |編輯現有影像|
-| `ima2 multimode <prompt>` |多影像SSE世代|
-| `ima2 video <prompt> [--model <lane>/<model>]` |透過生成視頻Grok或者MCP車道;需要明確的目標或已儲存的視訊預設值|
-| `ima2 ls [--session <id>] [--favorites]` |列出最近的歷史記錄|
-| `ima2 show <name> [--metadata]` |顯示產生的資產|
-| `ima2 prompt ls -q <search>` |搜尋提示庫|
-| `ima2 inflight ls [--terminal]` |列出目前和最近的工作（別名`ps`) |
-| `ima2 config set <key> <value>` | 寫入 `~/.ima2/config.json` |
-| `ima2 ping` |健康檢查正在運行的伺服器|
-
-伺服器會將實際連接埠寫入 `~/.ima2/server.json`。如果 `3333` 忙碌，後端會改用 `3334` 以上的連接埠，CLI 指令也會遵循公告網址。你可以用 `--server <url>` 或 `IMA2_SERVER=http://localhost:3333` 覆寫自動偵測結果。
+</details>
 
-```bash
-ima2 models --kind image
-ima2 gen "poster" --model oauth/gpt-5.6-luna --reasoning-effort high
-ima2 edit input.png --prompt "make it rainy" --web-search
-ima2 multimode "two cats playing" -n 2
-ima2 video "a cat playing piano" --model grok/grok-imagine-video-1.5 --duration 5 --resolution 720p
-ima2 video "animate this" --model grok/grok-imagine-video-1.5 --ref photo.png --aspect-ratio 16:9
-ima2 inflight ls --terminal
-ima2 config set imageModels.reasoningEffort high
-```
+<details>
+<summary><b>回傳 <code>EMPTY_RESPONSE</code> 或沒有影像資料</b></summary>
 
-完整參考：[docs/CLI.md](CLI.md).
+執行 `ima2 doctor image-probe --json > ima2-image-probe.json`，並把去識別化後的 JSON 附在 Issue 中。若是 GPT OAuth 問題，請在 `ima2 serve` 執行時一併記錄 `ima2 gen "고양이" --model oauth/gpt-6-luna --no-web-search --json` 與 `ima2 gen "고양이" --model oauth/gpt-6-luna --json` 的結果。請勿分享 ChatGPT Cookie、OAuth token 檔案、API 金鑰、原始上游回應、提示詞歷史或生成的 base64。
 
-## 配置
+</details>
 
-配置優先權：
+<details>
+<summary><b>大尺寸參考圖失敗</b></summary>
 
-```text
-environment variables > ~/.ima2/config.json > built-in defaults
-```
+大型 JPEG/PNG 會在上傳前自動壓縮。若仍失敗，請轉成解析度較低的 JPEG 或 PNG 再試。瀏覽器路徑不支援 HEIC/HEIF。
 
-| 環境變數 | 預設值 | 說明 |
-|---|---:|---|
-| `IMA2_PORT` / `PORT` | `3333` | Web 伺服器連接埠 |
-| `IMA2_HOST` | `127.0.0.1` |Web伺服器綁定主機|
-| `IMA2_OAUTH_PROXY_PORT` / `OAUTH_PORT` | `10531` | OAuth代理端口|
-| `IMA2_SERVER` | — | CLI目標覆蓋|
-| `IMA2_CONFIG_DIR` | `~/.ima2` |配置和 SQLite 位置|
-| `IMA2_ADVERTISE_FILE` | `~/.ima2/server.json` |運行時發現文件|
-| `IMA2_GENERATED_DIR` | `~/.ima2/generated` |產生的圖片目錄|
-| `IMA2_IMAGE_MODEL_DEFAULT` | `gpt-5.6-luna` |伺服器後備映像模型|
-| `IMA2_REASONING_EFFORT` | `medium` |默認的默認推理工作（GPT OAuth） 小路;之一`none`, `low`, `medium`, `high`, `xhigh` |
-| `IMA2_NO_OAUTH_PROXY` | — |放`1`停用自動啟動OAuth代理人|
-| `IMA2_LOG_LEVEL` | `info` |正常服務預設為`info`;開發模式預設為`debug`;支持`debug`, `info`, `warn`, `error`， 或者`silent` |
-| `IMA2_INFLIGHT_TERMINAL_TTL_MS` | `300000` |調試視圖的最近終端作業保留|
-| `OPENAI_API_KEY` | — | API的關鍵`provider: "api"`回應API影像路徑和輔助API- 主要特點|
-| `XAI_API_KEY` | — | API關鍵是`provider: "grok-api"`直接的xAI圖片API小路|
-| `IMA2_API_IMAGE_MODEL_DEFAULT` | `gpt-5.6-luna` |預設影像模型`provider: "api"` |
-| `IMA2_API_REASONING_EFFORT` | `low` |默認推理工作`provider: "api"` |
-| `IMA2_API_IMAGE_SIZE` | `1024x1024` |預設尺寸為`provider: "api"` |
-| `IMA2_API_ALLOW_WEB_SEARCH` | `true` |切換網路搜尋`provider: "api"` |
-| `IMA2_GROK_PLANNER_MODEL` | `grok-4.5` | Grok搜尋/規劃器模型（也可透過設定進行配置UI或者`--planner-model` CLI旗幟）|
-| `IMA2_GROK_PLANNER_TIMEOUT_MS` | `60000` |超時時間為Grok搜尋和規劃呼叫|
-| `IMA2_GROK_IMAGE_MODEL_DEFAULT` | `grok-imagine-image-quality` |預設最終Grok影像模型|
-| `IMA2_GROK_VIDEO_MODEL_DEFAULT` | `grok-imagine-video-1.5` |預設Grok視訊模型|
-| `IMA2_GROK_GENERATION_TIMEOUT_MS` | `120000` |決賽暫停Grok圖片API稱呼|
-| `IMA2_OAUTH_MASKED_EDIT_ENABLED` | `false` |針對屏蔽編輯請求的選擇加入功能標誌OAuth路徑（#31，僅基礎）|
-| `GEMINI_API_KEY` | — | API關鍵是`provider: "gemini-api"`直接生成語言API小路|
-| `VERTEX_SERVICE_ACCOUNT_JSON` | — |谷歌服務帳戶JSON為了Vertex AI授權與`provider: "gemini-api"`;優先於`GEMINI_API_KEY`當兩者都設定時|
-| `IMA2_AGY_BIN` | `agy`在路徑上|顯式路徑Antigravity CLI二進制為`provider: "agy"` |
-| `IMA2_MAX_PARALLEL` | `24` |伺服器範圍的平行產生上限|
+</details>
 
-`IMA2_GROK_PROXY_HOST`、`IMA2_GROK_PROXY_PORT`、`IMA2_NO_GROK_PROXY`和`IMA2_GROK_RESTART_*`已隨本機Grok代理在 3.16 中移除，不再被讀取；即使保留這些值也不會有任何影響。
+<details>
+<summary><b>更新後看不到以前的圖庫影像</b></summary>
 
-### 記錄模式
+新版本把生成的影像從安裝套件資料夾移到了 `~/.ima2/generated`。請執行 `ima2 doctor`，並參考 [找回舊影像](RECOVER_OLD_IMAGES.zh-TW.md)。
 
-`ima2 serve`故意保持終端輸出安靜：啟動 URL、警告和錯誤保持可見，而 request/node/OAuth結構化日誌預設隱藏。
+</details>
 
-使用`ima2 serve --dev`, `npm run dev`， 或者`IMA2_LOG_LEVEL=debug ima2 serve`當您需要請求 ID、節點產生階段時，OAuth流診斷或飛行狀態轉換。顯式的`IMA2_LOG_LEVEL`和`~/.ima2/config.json`值仍然會覆蓋內建預設值。
+<details>
+<summary><b>GPT OAuth 通道找不到或拒絕 GPT-6 模型</b></summary>
 
-## API參考
+GPT OAuth 通道使用你的 ChatGPT 方案開放的 GPT-6 模型。請更新 ima2-gen，以 `ima2 gpt login` 重新登入，再用 `ima2 models --kind image` 檢查。若只有某個模型持續失敗，請切換到預設的 `gpt-6-luna`。
 
-端點清單移至[docs/API.md](API.md)因此本自述文件可以集中於首次運作使用。
+</details>
 
-有用的參考：
+<details>
+<summary><b>應用程式在另一個連接埠開啟</b></summary>
 
-- [開發者文件網站](https://lidge-jun.github.io/ima2-gen/docs)— 概述、快速入門、架構、模式、提供者、CLI、設定和伺服器API
-- [CLI參考](CLI.md)
-- [API參考](API.md)
-- [提示工作室手冊](PROMPT_STUDIO.md)
-- [常問問題](FAQ.md)
-- [恢復舊影像](RECOVER_OLD_IMAGES.md)
-- [韓文自述文件](README.ko.md)
-- [日文自述文件](README.ja.md)
-- [中文自述文件](README.zh-CN.md)
+如果要求的連接埠已被佔用，`ima2-gen` 會改用下一個可用連接埠，並記錄在 `~/.ima2/server.json`。若連接埠意外變成 `3457`，可能是你的 shell 從其他本機工具繼承了 `PORT=3457`。請執行 `unset PORT`，或用 `IMA2_PORT=3333 ima2 serve` 啟動。
 
-## 故障排除
+</details>
 
-**`ima2 ping`說伺服器無法存取**
-開始`ima2 serve`，然後檢查`~/.ima2/server.json`。你也可以運行`ima2 ping --server http://localhost:3333`.
+更多解答請見 [FAQ](FAQ.zh-TW.md)。
 
-**GPT OAuth登入不起作用**
-重新運行`ima2 setup`（選項1），確認`ima2 status`，然後重新啟動`ima2 serve`.
+## 文件
 
-**`fetch failed`在代理/VPN 網路上重複**
-檢查本地OAuth代理可達。在需要代理的網路上，啟用代理客戶端的 TUN/TURN 式模式，然後重試`openai-oauth --port 10531`。如果仍然失敗，請設定`HTTP_PROXY`和`HTTPS_PROXY`在運作的同一個終端中`ima2 serve`或者`openai-oauth`。在 Windows 上，也要檢查自動啟動的網路攔截工具，包括 SecretDNS 等 DNS/碎片繞過工具，因為它們可能會破壞OAuth或串流圖像回應，即使瀏覽器顯示為已連線。
+- [開發者文件網站](https://lidge-ai.github.io/ima2-gen/docs) — 概覽、快速開始、架構、模式、供應商、CLI、設定與伺服器 API
+- [CLI 參考](CLI.zh-TW.md) · [API 參考](API.zh-TW.md) · [Prompt Studio 手冊](PROMPT_STUDIO.zh-TW.md) · [FAQ](FAQ.zh-TW.md) · [找回舊影像](RECOVER_OLD_IMAGES.zh-TW.md)
 
-**影像失敗`API_KEY_REQUIRED`**
-放`OPENAI_API_KEY`或配置一個API使用前按鍵`provider: "api"`。預設GPT OAuth路徑仍然有效，無需API鑰匙。
+## 開發
 
-**圖像生成返回`EMPTY_RESPONSE`或沒有影像數據**
-跑步`ima2 doctor image-probe --json > ima2-image-probe.json`並附上保險箱JSON打開問題時。為了GPT OAuth案例，也捕獲`ima2 gen "고양이" --model oauth/gpt-5.6-luna --no-web-search --json`和`ima2 gen "고양이" --model oauth/gpt-5.6-luna --json`儘管`ima2 serve`正在運行。請勿分享ChatGPT餅乾,OAuth令牌文件，API鍵、原始上游回應、提示歷史記錄或產生的 base64。請參閱[常見問題支援包](FAQ.md#what-should-i-share-when-oauth-image-generation-returns-no-image).
+```bash
+git clone https://github.com/lidge-ai/ima2-gen.git
+cd ima2-gen
+npm install
+npm run dev
+npm run typecheck
+npm test
+npm run build
+```
 
-**大參考影像失敗**
-該應用程式壓縮較大JPEG/PNG上傳前參考。如果文件仍然失敗，請將其轉換為JPEG或者PNG降低解析度並重試。瀏覽器路徑不支援 HEIC/HEIF 檔案。
+`npm run dev` 會建置 UI，並以 `--watch` 與詳細診斷日誌啟動 TypeScript 伺服器。`npm run typecheck`、`npm run build:server` 與 `npm run build:cli` 用來驗證 TypeScript 的建置路徑。 節點模式與 Canvas Mode 預設包含在封裝後的 UI 中。
 
-**更新後舊圖庫影像遺失**
-最新版本將產生的映像從已安裝的套件資料夾移至`~/.ima2/generated`。跑步`ima2 doctor`並看到[恢復舊影像](RECOVER_OLD_IMAGES.md).
+網頁介面透過單一 `GET /api/events` Server-Sent Events 連線接收所有進度。多模式、節點與影片請求以非同步 POST（`202 { requestId }`）送出，並經由共用事件匯流排多工傳送，因此同時進行的工作不會撞上瀏覽器 6 條連線的上限。沒有送出 `async: true` 的 CLI 用戶端仍會收到依請求區分的 SSE 串流。
 
-**`gpt-5.5`失敗但其他模型可以工作**
-更新Codex CLI首先，然後重試。如果仍然失敗，您的帳戶或後端路由可能無法公開相同的映像能力或配額`gpt-5.5`然而;使用`gpt-5.4`作為穩定的後備。
+### 執行需求
 
-**該應用程式在不同的連接埠上打開**
-如果請求的伺服器連接埠繁忙，`ima2-gen`回退到下一個可用連接埠並將其記錄在`~/.ima2/server.json`。如果連接埠意外`3457`，你的shell也可能繼承了`PORT=3457`來自另一個本地工具。跑步`unset PORT`或開始於`IMA2_PORT=3333 ima2 serve`.
+<!-- runtime-install:generated:start -->
+| Contract | Value |
+|---|---|
+| Node engine | `>=22` |
+| npm toolchain | `npm@11.18.0` |
+| Release Node | `24.17.0` |
+| CLI entry | `bin/ima2.js` |
+| OpenAI SDK | `^7.4.0` |
+| Express | `^5.1.0` |
+<!-- runtime-install:generated:end -->
 
-**港口`10531`已經在 Windows 上使用**
-一些 Windows 安全性工具，包括`AnySign4PC.exe`，可以佔用預設值OAuth代理端口。當前版本追蹤實際的回退OAuth港口。如果您仍然需要手動超控，請從`IMA2_OAUTH_PROXY_PORT=11531 ima2 serve`並檢查`ima2 doctor`.
+安裝程式會從套件的中繼資料讀取 Node.js 最低版本，並在啟動伺服器前執行離線安裝檢查。
 
-有關更多適合初學者的答案，請參閱[常問問題](FAQ.md).
+<details>
+<summary><b>桌面應用程式建置（Electron，English）</b></summary>
 
-## 發展
+`desktop/` wraps the same local server and UI in a menubar/tray app for macOS, Windows, and Linux. It supervises `server.js` as a child process (attaching to an already-running server on the configured port instead of starting a second one) and adds a native settings window: port, open at login, start hidden, menubar-only (macOS), keep-server-on-close, log level, config directory.
 
 ```bash
-git clone https://github.com/lidge-jun/ima2-gen.git
-cd ima2-gen
+cd desktop
 npm install
-npm run dev
-npm run typecheck
-npm test
-npm run build
+npm run prepare:app     # builds server + CLI + UI at the repo root
+npm start               # run unpackaged
+npm run dist:mac        # dmg + zip (Apple Silicon / arm64)
+npm run dist:win        # nsis + zip
+npm run dist:linux      # AppImage + deb
 ```
 
-`npm run dev`建立UI並開始TypeScript伺服器條目與`--watch`和詳細的伺服器診斷。`npm run typecheck`, `npm run build:server`， 和`npm run build:cli`驗證TypeScript遷移和包發出路徑。 Node模式和Canvas模式是打包的一部分UI預設情況下。
+Only the macOS app is distributed today, for Apple Silicon. `.github/workflows/desktop.yml` runs in three ways: a push to `dev` builds an unsigned macOS validation build, a manual dispatch builds signed and notarized installers without publishing anything, and a `desktop-v*` tag push builds, verifies, and publishes the desktop release. Trusted macOS builds require `MAC_CSC_LINK`, `MAC_CSC_KEY_PASSWORD`, `APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD`, and `APPLE_TEAM_ID`; missing or invalid authentication fails the build instead of producing an unsigned success.
+
+For a signed macOS verification build without publishing, run:
+
+```bash
+gh workflow run desktop.yml --ref <reviewed-branch> -f platform=mac
+```
+
+The workflow verifies Developer ID, team, architecture (arm64), hardened runtime, secure timestamp, nested signatures, Gatekeeper and stapled notarization tickets. It checks the apps recovered from the final ZIP and DMG against the original signed content, then exports `ima2-macos-signature-proof` reports and installer SHA-256 hashes. Failed verification blocks installer upload. Only a `desktop-v*` tag push creates and publishes a release.
+
+Signing credential imports run on disposable GitHub-hosted macOS. The builder cleans successfully imported keychains; if import/setup fails before its cleanup registration, runner destruction is the final cleanup boundary. Local recovery should reuse an existing login-keychain identity in the same unlocked session, rather than importing credential packages into a persistent machine. This does not require changing automatic locking or key access rules.
+
+Windows Authenticode remains separate and uses `WIN_CSC_LINK` / `WIN_CSC_KEY_PASSWORD`; Windows builds without them are unsigned.
+
+</details>
 
 ## 貢獻者
 
-- [@lidge-jun](https://github.com/lidge-jun)— 維護者
-- [@ree9622](https://github.com/ree9622)— 審核控制、Windows 修復、結構化日誌記錄
-- [@Charley-Peng](https://github.com/Charley-Peng) — API快取修復（#74）
-- [@philiptaron](https://github.com/philiptaron)— 尼克斯薄片 (#81)
-- [@傲英](https://github.com/aorying)— 上游驗證錯誤浮出水面（告知 TS 遷移方向）
-- [@樸正民](https://github.com/PARKJONGMlN)— 批次比較矩陣設計 (#80)
+- [@lidge-jun](https://github.com/lidge-jun) — maintainer
+- [@ree9622](https://github.com/ree9622) — moderation controls, Windows fixes, structured logging
+- [@Charley-Peng](https://github.com/Charley-Peng) — API cache fix (#74)
+- [@philiptaron](https://github.com/philiptaron) — Nix flake (#81)
+- [@aorying](https://github.com/aorying) — upstream validation error surfacing (informed TS migration direction)
+- [@PARKJONGMlN](https://github.com/PARKJONGMlN) — batch comparison matrix design (#80)
 
-## 執照
+## 授權
 
-麻省理工學院
+MIT