illustrator-bridge
by groundfic
README.md
# illustrator-bridge
從**需求表單/截圖**批次產生 Illustrator 的**工作區域與名稱**。搭配 Claude Code 使用。
```
Claude Code ──stdio── MCP server ──AppleScript── Illustrator ──ExtendScript── 工作區域
```
不需要安裝任何 Illustrator 外掛,用的是 Illustrator 內建的 `do javascript`,
所以 Illustrator 的 DOM 功能 100% 可用(UXP 面板反而做不到這件事)。
## 安裝
需求:macOS、Adobe Illustrator、Node.js 18 以上、Claude Code。
```
git clone https://github.com/groundfic/illustrator-mcp-bridge.git ~/illustrator-bridge
cd ~/illustrator-bridge
npm install
claude mcp add --scope user illustrator-bridge -- node ~/illustrator-bridge/src/index.js
```
裝好後開一個新的 Claude Code 對話,請它跑 `connection_status`。第一次執行 macOS 會問自動化權限,要允許終端機控制 Adobe Illustrator。
`skill/` 是給 Claude 讀的工作手冊(踩過的坑、印刷判斷)。要用的話複製到 `~/.claude/skills/illustrator/`:
```
mkdir -p ~/.claude/skills/illustrator && cp -R skill/ ~/.claude/skills/illustrator/
```
## 用法
在 Claude Code 裡直接講,例如:
> [貼上報價單截圖] 照這張表建工作區域
Claude 會判讀出「要做哪些格式、各幾件」,先用 `dryRun` 試算給你確認,
確認後才真的建立。也可以直接下指令:
> 建工作區域:名片 90×54 兩面、A4 傳單 2 款、IG 貼文 1080px 3 張,出血 3mm
## 工具
| 工具 | 用途 | 會改文件? |
|---|---|---|
| `connection_status` | 檢查 Illustrator 有沒有開、通道通不通 | 否 |
| `get_document_info` | 文件狀態:存檔路徑、未存修改、色彩模式、尺規單位、工作區域;圖層、色票、特別色、連結圖、字型、文字的摘要或完整清單 | 否 |
| `get_artboard_items` | 某個工作區域上的物件:類型、名稱、圖層、鎖定/隱藏、以工作區域左上角為原點的 mm 座標 | 否 |
| `take_snapshot` | 把工作區域匯出成圖片直接給 Claude 看,可裁切局部 | 否(見下) |
| `check_document` | 一鍵印前檢查:色彩、文字、連結圖、出血、細線、疊印、雜物,回問題清單 | 否 |
| `list_scripts` | 列出登錄的現成 .jsx:用途、能否無介面執行、參數、驗證狀態 | 否 |
| `run_script` | 執行現成的 .jsx(登錄名稱或路徑),有介面的拒絕執行 | 看指令碼(會改的先備份) |
| `create_artboards` | **主力**。依規格批次建立,網格排列、自動命名 | 是(附加時先備份) |
| `rename_artboards` | 依索引改名 | 是(先備份) |
| `card_scan` | 解析卡片欄位,做成 CSV 範本 | 否 |
| `card_build` | 照表格批次複製卡片 | 是(先備份) |
| `execute_jsx` | 逃生門:跑任意 ExtendScript | 可能(預設先備份) |
### 安全機制(1.1.0)
- **對話框鎖死防護**:每次執行期間把 `app.userInteractionLevel` 設成 `DONTDISPLAYALERTS`
(缺字型、連結遺失這類 Illustrator 自己的警告不會跳出來卡住通道),結束後還原原值,腳本丟例外也一樣。
`execute_jsx` 的程式碼若含 `alert(`/`confirm(`/`prompt(`/`new Window(`/`openDialog(` 等,
**送出前就拒絕**(註解裡寫到不算)。
- **改動前自動備份**:`create_artboards`(附加到既有文件時)、`rename_artboards`、`card_build`、`execute_jsx`、
`run_script`(登錄為會改文件的指令碼,1.2.0)執行前,把作用中文件**磁碟上的檔案**複製到
`~/Library/Application Support/illustrator-bridge/backup/<時間>-<原檔名>`,回傳的 `backup` 欄位是路徑。
- ⚠️ 備份的是**上次存檔時的狀態**,Illustrator 裡還沒存檔的修改救不回來。
- 從沒存過檔的新文件不備份、不報錯;超過 500MB 略過並回 warning。
- 同一個檔 10 分鐘內只備份一次(檔案自上次備份後沒變也沿用);啟動時清掉 30 天以上的舊備份。
- 純讀取的 `execute_jsx` 請傳 `backup: false`。
- 時間用本地時間、冒號換成連字號(例 `2026-11-15T14-03-22-客戶檔.ai`),Finder 才不會顯示成斜線。
- 備份位置可用環境變數 `AI_BRIDGE_BACKUP_DIR` 改。
- **截圖不改文件**:`exportFile` 只認作用中的工作區域,切過去後一定切回;
實測 `exportFile` 會把文件標成「已修改」(它把匯出設定記進文件),所以匯出前若是已存檔狀態,匯出後把 `saved` 設回 true。
存檔路徑不變(不用 `saveAs`)。
### get_document_info
預設回**摘要**:固定欄位+每類的數量與前 5 筆。要完整清單給 `sections`(`artboards` `layers` `swatches` `spots`
`links` `fonts` `text`)與 `limit`(預設 200);給了 `sections` 時沒列到的類別只回數量,`fonts` 不掃描。
- `fullName`:存檔路徑,從沒存過檔為 `null`;`hasUnsavedChanges`=`!saved`。
- 連結圖:`effectivePPI` 由置入縮放算出(`boundingBox` 是像素座標、`matrix` 是縮放);
連結檔的色彩空間用 macOS 內建 `sips` 讀;遺失連結 DOM 讀不到路徑,改從 XMP 連結清單比對出 `missingPaths`。
- 字型只從文件裡的文字讀,**絕不碰 `app.textFonts`**。`textRanges` 是逐字的,每字成本隨文字框數增加
(實測 300 框約 15µs/字、1500 框約 145µs/字),所以設探測預算,超過的文字框改等距抽樣,`fonts.scan.complete` 會標示。
- 實測:1500 個文字框的文件摘要約 0.7 秒;`sections:["fonts"]` 約 2.5 秒。
### get_artboard_items
工作區域不是容器,這裡用 `artboardRect` 與物件 `geometricBounds` 幾何比對(兩者 Y 向上為正、`top > bottom`),
輸出換成**工作區域左上角原點、Y 向下、mm** 的 `x,y,w,h`,可直接當 `take_snapshot` 的 `crop`。
- `mode`:`intersect`(預設,重疊才算,只貼齊邊緣不算)/`contain`(完全在內);`partial: true` 表示超出工作區域。
- 只列最上層物件;`expandGroups: true` 展開一層。剪裁群組用遮色片範圍計算(不然被遮掉的部分會讓它看起來很大)。
- `includeLocked`/`includeHidden` 預設 true(列出並標示),鎖定/隱藏包含所在圖層的狀態。
- 每筆附 `uuid`,在 `execute_jsx` 可用 `app.activeDocument.getPageItemFromUuid(uuid)` 抓同一個物件。
- 最多掃 20000 個物件;實測 3000 個物件約 0.3 秒。
### take_snapshot
`artboardIndex`(預設作用中)、`maxSize`(長邊像素上限,預設 1200,最大 4000)、`crop`(mm,工作區域左上角起算)、
`format`(`jpg` 預設/`png`)。裁切時以裁切範圍長邊 = `maxSize` 放大匯出(倍率上限 776%、整張匯出長邊上限 8000px),
再用 `sips` 裁切;暫存檔讀成 base64 後刪掉。實測簡單 A4:jpg 1200px 約 0.45 秒、23KB;2400px 約 0.6 秒、70KB。
Illustrator 會把匯出範圍對齊像素格,長邊可能比 `maxSize` 少 1px。
### check_document(1.2.0)
只讀不改(不碰選取、不切工作區域,回傳 `state.unchanged` 確認),回 `{doc, elapsedMs, summary, report}`。
`report` 每類有 `level`、`count`、前 `limit` 筆 `items`(工作區域名稱、圖層、物件名稱或類型、mm 座標、uuid),依嚴重度排序。
| 檢查 `only` | 類別(level) |
|---|---|
| `color` | `rgbObjects` CMYK 文件裡的 RGB 填色/筆畫(error)、`rgbDocument` RGB 文件(warn)、`spots` 特別色與用量(info)、`unusedSpots`(info) |
| `links` | `missingLinks` 遺失(error)、`rgbImages` CMYK 文件裡的 RGB 點陣圖(error)、`distorted` 非等比縮放(error)、`lowRes` 低於 `minPPI`(warn)、`linkList` 清單(info) |
| `bleed` | `bleed` 最上層物件離裁切線 0.1mm 內卻沒延伸出去(`flushEdges`)(warn)。1.2.1 起超出但不到 `bleed` mm 的(`shortBleed`)要 `bleedStrict: true` 才報;貼邊的點狀文字不報 |
| `stroke` | `thinStroke` 細於 `minStroke` pt 的筆畫(warn) |
| `overprint` | `whiteOverprint` 白色(C0M0Y0K0、灰階 0、白色整體色)設了疊印(error)、`overprint` 其他疊印物件(info;特別色疊印列在這) |
| `text` | `liveText` 未轉外框的文字框,依工作區域計數,只列不判對錯(info) |
| `clutter` | `strayPoints` 孤立錨點、`emptyText` 空文字框(warn)、`offArtboard` 工作區域外、`hiddenLocked` 隱藏/鎖定/不列印圖層的物件(info) |
- 參數:`only`、`limit`(預設 10)、`bleed`(mm,預設 3,`0` 不查)、`bleedStrict`(預設 false;true 時也報出血不足)、`minPPI`(預設 300)、`minStroke`(pt,預設 0.25)。
- 隱藏、不列印圖層的物件不查色彩、筆畫、疊印、出血;遺失連結照報。
- 文字只看整框的字元屬性(不逐字),絕不碰 `app.textFonts`。符號、外掛物件(即時效果)、網格、圖表內部不檢查,`summary.notCheckedTypes` 會列出。
- Illustrator 會把 CMYK 文件裡指定的 RGB 填色、以 RGB 定義的色票自動轉成 CMYK,嵌入 RGB 圖也會轉;實務上 `rgbImages` 來自**連結的 RGB 圖**(`sips` 讀檔頭)。
- 上限:走訪 50000 個物件或 90 秒,超過在 `summary.truncated` 標示。實測 3000 個物件約 0.4 秒(引擎內 0.2 秒)、回傳約 6KB。
### list_scripts/run_script(1.2.0)
> **登錄檔是範例**:`scripts/registry.json` 列的 .jsx(grid-guides、StampTexture、GlyphParts、CardTable、CreateExpandedArtboards、print-prepress)是作者自己的指令碼,**沒有隨這個 repo 附上**。
> 請把登錄檔改成你自己的 .jsx,或直接給 `run_script` 一個 `path`。`tests/scripts.js`、`tests/cardtable*.js` 需要那些指令碼才跑得起來。
登錄檔 `scripts/registry.json`:每支指令碼的路徑(`~` 開頭)、用途、`headless`、判定依據、參數與預設值、作用對象、會不會改文件、驗證狀態。
| 名稱 | 指令碼 | 無介面 |
|---|---|---|
| `grid-guides` | `~/illustrator-scripts/grid-guides.jsx` | ✅ `$.global.GRID_CONFIG`(預設值取自對話框) |
| `stamp-texture` | `~/illustrator-scripts/StampTexture.jsx` | ✅ `$.global.STAMP_CONFIG`(作用在選取) |
| `glyph-parts` | `~/illustrator-scripts/stroke-split/GlyphParts.jsx` | ✅ `GLYPH_PARTS_CONFIG`(作用在選取) |
| `ai-cover-finish`/`ai-cover-assemble` | `print-prepress/scripts/` | ✅ 照 `run_adobe.sh` 組 PARAMS+CONFIG+lib.jsx,需要 print-prepress 的 `config.json` |
| `card-table` | `~/illustrator-scripts/CardTable.jsx` | ❌ 只有 ScriptUI |
| `create-expanded-artboards` | `~/Documents/Illustrator-Scripts/CreateExpandedArtboards.jsx` | ✅ `$.global.EXPAND_AB_CONFIG`(1.2.1;作用在選取,`unit` 必填) |
- `headless:false` 一律拒絕(沒送進 Illustrator),回 `hint` 請使用者從「檔案 → 指令碼 → 其他指令碼…」執行。
- 沒登錄的檔:原始碼有 `alert(`/`new Window(`/檔案對話框/`#targetengine` 就拒絕;確定有無介面模式時帶 `configGlobal`+`assumeHeadless:true`。`#include` 不支援。
- 參數放進約定的全域變數,**跑完一定還原**(grid-guides、GlyphParts 不會自己清,留著的話下次從選單執行會跳過對話框)。
專案 `_tools` 那類「前面補 `var OUT, DOC` 再跑」的指令碼給 `vars`(在同一個函式範圍宣告)。
- **編碼**:不用 `$.evalFile`。檔案讀進 node(處理 BOM、UTF-16,不是 UTF-8 就報錯)送進引擎 eval,有沒有 BOM 中文都正確。
實測 `$.evalFile` 對沒有 BOM 的檔是看開頭猜編碼:開頭就有中文會猜對,前段全是 ASCII 的檔中文會亂碼。
- 指令碼在引擎裡的獨立函式範圍 eval:頂層的 `var`/`function` 不會蓋到引擎,也不會殘留在 `$.global`。`#target` 行改成註解(行號不變);用到 `$.fileName` 的會警告(它指向暫存檔)。
- 同一個行程同時只跑一支;逾時照登錄(60~600 秒,MCP 最長 600)。
### 命令列(不經 MCP)
```
bash scripts/run.sh list
bash scripts/run.sh check [參數.json] [逾時秒] # 也可以 bash scripts/check.sh [參數.json]
bash scripts/run.sh grid-guides grid.json
bash scripts/run.sh ~/某處/工具.jsx params.json 300 # 參數檔可放 "_run": {"configGlobal","vars","assumeHeadless","backup","prepressConfig"}
```
輸出 JSON;`ok:false` 時 exit 1。防護跟 MCP 工具相同,命令列逾時最長 7200 秒。作用對象一樣是**作用中文件**。
### create_artboards 的行為
- **排列**:由左上往右排,滿一列往下。同尺寸自動成一組,換尺寸另起一區(`groupBySize`,預設開)。
- **每列幾個**:`layout.cols`;不給就自動排成接近正方形,上限 8 欄。
- **單位**(⚠️ **1.2.1 行為改變**):有給 `unit` 照給的;**沒給 `unit` 時看目標文件的色彩模式:CMYK → mm、RGB → px**。
附加到既有文件看那份文件的 `documentColorSpace`;新建文件看這次的 `documentColorSpace`(沒給是 CMYK)。
尺寸、`gutter`、`groupGap`、`bleed` 都跟著這個單位;`layout.unit` 有給時間距仍以它為準,單項的 `items[].unit` 只管該項尺寸。
回傳(`dryRun` 也是)一定有 `unitUsed`、`unitSource`(例如 `"文件是 RGB(沒給 unit:RGB 用 px)"`)、`gapUnit`,
有出血時還有 `bleedUnit`,執行前先看單位對不對。
**印刷案在 RGB 文件裡工作時要明確給 `unit: "mm"`**,不然 `90×54` 會變成 90×54px。
`get_document_info`/`get_artboard_items`/`check_document` 的回傳單位不變(mm)。
- **間距**:`layout.gutter` 沒給時 10mm,群組之間 `layout.groupGap` 沒給時 20mm(不論單位)。
有給數值時單位跟著 `layout.unit` > 最外層 `unit` > 上面的預設單位(1.1.0 起;舊版一律 mm)。
例如 `unit: "px"` 時 `gutter: 40` 是 40px。要固定用 mm 設 `layout.unit: "mm"`。
- **接在哪**:已有文件時接在**現有工作區域下方**,不會壓到既有內容;沒有文件則自動新建(預設 CMYK)。
- **命名**:`count > 1` 時自動變 `名稱-01`、`名稱-02`;可用 `nameTemplate` 自訂(`{name}` `{n}` `{nn}`)。
- **重名**:自動加 `(2)` `(3)` 區隔(`dedupeNames`)。
- **名稱原樣保留**:全形括號、全形空白、`/ : \ * ? " < > |`、emoji 都照收(Illustrator 30.8 實測)。
只有換行/tab 換成空白、控制字元移除(NUL 會讓 Illustrator 截斷名稱)。
- **出血**:`bleed: 3` 會在鎖定圖層「出血參考」畫出血框(洋紅細線)。單位跟著最外層 `unit`(沒給就是上面的預設單位)。
- **可用單位**:`mm` `cm` `pt` `px` `in` `q`(級/齒,1Q = 0.25mm);Illustrator 裡 1px=1pt。
### 邊界處理
- 單邊超過 16383pt(約 5779mm)或小於 1pt → 跳過該項並在 `warnings` 說明,其餘照建。
- 一份文件超過 1000 個工作區域 → 整批擋下並說明。
- 名稱長度不截斷(舊版以為上限 100 字,實測 130 字照收)。空名稱在 `rename_artboards` 會被拒絕(Illustrator 會改回預設名)。
## 疑難排解
**「沒有自動化權限」** → 系統設定 → 隱私權與安全性 → 自動化 → 勾選你的終端機底下的「Adobe Illustrator」。
**執行卡住不回應** → Illustrator 有對話框擋著。切過去關掉即可。
1.1.0 起 Illustrator 自己的警告會被關掉、`execute_jsx` 裡的 `alert()` 等會在送出前被擋下;
但 `app.executeMenuCommand()` 開的選單對話框(例如文件設定)仍擋不住,別在腳本裡叫。
**改壞了要救** → `~/Library/Application Support/illustrator-bridge/backup/` 找同名檔(時間在檔名最前面)。
只有上次存檔的內容。
**指到錯的 Illustrator 版本** → 多版本並存時設環境變數:
```
AI_BRIDGE_APP_ID=com.adobe.illustrator node src/index.js
```
**想看實際送進去的 jsx** → `AI_BRIDGE_KEEP_TMP=1`,暫存檔會留在 `$TMPDIR/illustrator-bridge/`。
## 台灣印刷常見尺寸(mm)
名片 90×54|明信片 148×100|A4 210×297|A3 297×420|B5 182×257|菊八開 195×270
## 開發
```
npm install
node tests/unit.js # 不需要 Illustrator:對話框偵測、備份去重與清理、截圖換算、名稱清洗、檢查分類、指令碼登錄與編碼
node tests/smoke.js # 會在 Illustrator 開新文件實測,跑完關掉,不動你正開著的檔
```
需要 Illustrator 的測試(都在自己新建的暫存文件上做,跑完關掉、作用中文件切回原本那份):
| 測試 | 內容 |
|---|---|
| `tests/dialog-guard.js` | userInteractionLevel 設定與還原、alert 擋下 |
| `tests/backup.js` | 備份、去重、`backup:false`、未存檔文件 |
| `tests/snapshot.js` | 截圖尺寸、裁切、PNG、`saved` 前後一致、耗時 |
| `tests/docinfo.js` | 圖層/色票/特別色/連結(含遺失)/字型/文字、大文件耗時 |
| `tests/artboard-items.js` | 幾何比對、座標換算、鎖定/隱藏、群組展開、剪裁群組 |
| `tests/names-units.js` | 全形字元名稱、px 間距(走 MCP 通道) |
| `tests/create-units.js` | 沒給 unit 時的預設單位:既有/新建 × CMYK/RGB × 有沒有給 unit,含間距、出血、回傳的 unitUsed/unitSource |
| `tests/check.js` | 印前檢查:做壞的文件逐項抓、乾淨文件零誤報、RGB 文件、參數、3000 物件耗時 |
| `tests/scripts.js` | run_script:中文編碼(對照 `$.evalFile`)、範圍隔離、拒絕、grid-guides/stamp-texture/glyph-parts/ai-cover-finish 實跑 |
| `tests/mcp-tools.js` | 新工具走 MCP 通道的整合測試 |
| `tests/card.js` | 卡片掃描與生成 |
需要「已存檔的文件」的測試(與測試圖檔、測試用 .jsx)會存到 `AI_TEST_DIR`(預設 `$TMPDIR/illustrator-bridge-test/`)。
`src/jsx/engine.jsx` 是實際跑在 Illustrator 裡的引擎,
`src/runner.js` 負責組檔與 osascript 通道,`src/index.js` 只做 MCP 的殼;
`src/check.js`(印前檢查的連結分類與摘要)、`src/scripts.js`(指令碼登錄與執行)MCP 與命令列共用。
⚠️ 產生的暫存 jsx **必須帶 UTF-8 BOM**,否則 ExtendScript 會把中文讀成亂碼。
回傳值則把非 ASCII 全轉成 `\uXXXX`,避開 AppleScript ↔ stdout 的編碼問題。
## 授權
MIT,見 `LICENSE`。
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues