cli-anything-inkscape 是做什麼的？
一個具有狀態追蹤的向量圖形編輯命令列介面，遵循與 GIMP 及 Blender CLI 相同的設計模式。它直接操作 SVG (XML) 文件，並使用 JSON 專案格式來追蹤狀態。
安裝
此命令列工具作為 cli-anything-inkscape 套件的一部分進行安裝：
pip install cli-anything-inkscape
前置需求：
- Python 3.10+
- 系統必須安裝 Inkscape
使用方式
基本指令
# 顯示說明
cli-anything-inkscape --help
# 啟動互動式 REPL 模式
cli-anything-inkscape
# 建立新文件
cli-anything-inkscape document new -o project.json
# 以 JSON 輸出執行（供代理程式使用）
cli-anything-inkscape --json document info -p project.json
REPL 模式
當未指定子指令時，CLI 會進入互動式 REPL 會話：
cli-anything-inkscape
# 以互動方式輸入指令，支援 Tab 補全與指令歷史
你也可以使用不存在的專案路徑來啟動 REPL。CLI 現在會直接建立一個新的記憶體文件，而非立即失敗：
cli-anything-inkscape --project /abs/path/new-title.inkscape-cli.json
指令群組
文件
文件管理指令。
| 指令 | 說明 |
|---|---|
new | 建立新文件 |
open | 開啟現有專案 |
save | 儲存目前專案 |
info | 顯示文件資訊 |
profiles | 列出可用的文件設定檔 |
canvas-size | 設定畫布大小 |
units | 設定文件單位 |
json | 輸出原始專案 JSON |
形狀
形狀管理指令。
| 指令 | 說明 |
|---|---|
add-rect | 新增矩形 |
add-circle | 新增圓形 |
add-ellipse | 新增橢圓形 |
add-line | 新增線條 |
add-polygon | 新增多邊形 |
add-path | 新增路徑 |
add-star | 新增星形 |
remove | 依索引移除形狀 |
duplicate | 複製形狀 |
list | 列出所有形狀/物件 |
get | 取得某個形狀的詳細資訊 |
文字
文字管理指令。
| 指令 | 說明 |
|---|---|
add | 新增文字元素；支援 --box-width、--box-height 與 --line-height 以實現自動換行佈局 |
set | 設定文字屬性（文字內容、字型、字型大小、填色、框寬、框高、行高等） |
list | 列出所有文字物件 |
樣式
樣式管理指令。
| 指令 | 說明 |
|---|---|
set-fill | 設定物件的填滿顏色 |
set-stroke | 設定物件的描邊顏色（及可選的寬度） |
set-opacity | 設定物件的不透明度（0.0-1.0） |
set | 設定物件的任意樣式屬性 |
get | 取得物件的樣式屬性 |
list-properties | 列出所有可用的樣式屬性 |
變形
變形操作（平移、旋轉、縮放、傾斜）。
| 指令 | 說明 |
|---|---|
translate | 平移（移動）物件 |
rotate | 旋轉物件 |
scale | 縮放物件 |
skew-x | 水平傾斜物件 |
skew-y | 垂直傾斜物件 |
get | 取得物件的目前變形 |
clear | 清除物件的所有變形 |
圖層
圖層管理指令。
| 指令 | 說明 |
|---|---|
add | 新增圖層 |
remove | 依索引移除圖層 |
move-object | 將物件移動到不同圖層 |
set | 設定圖層屬性（名稱、可見性、鎖定狀態、不透明度） |
list | 列出所有圖層 |
reorder | 將圖層從某個位置移動到另一個位置 |
get | 取得圖層的詳細資訊 |
路徑群組
路徑布林運算。
| 指令 | 說明 |
|---|---|
union | 兩個物件的聯集 |
intersection | 兩個物件的交集 |
difference | 兩個物件的差集（A 減去 B） |
exclusion | 兩個物件的互斥或（XOR） |
convert | 將形狀轉換為路徑 |
list-operations | 列出可用的路徑布林運算 |
漸層
漸層管理指令。
| 指令 | 說明 |
|---|---|
add-linear | 新增線性漸層 |
add-radial | 新增放射狀漸層 |
apply | 將漸層套用至物件 |
list | 列出所有漸層 |
匯出群組
匯出/渲染指令。
| 指令 | 說明 |
|---|---|
png | 將文件渲染為 PNG |
svg | 將文件匯出為 SVG |
pdf | 將文件匯出為 PDF（需安裝 Inkscape） |
presets | 列出匯出預設集 |
會話
會話管理指令。
| 指令 | 說明 |
|---|---|
status | 顯示會話狀態 |
undo | 復原上一個操作 |
redo | 重做上一個復原的操作 |
history | 顯示復原歷史記錄 |
範例
建立新專案
建立一個新的 Inkscape 專案檔案。
cli-anything-inkscape document new -o myproject.json
# 或使用 JSON 輸出以利程式化使用
cli-anything-inkscape --json document new -o myproject.json
互動式 REPL 會話
啟動一個支援復原/重做的互動式會話。
cli-anything-inkscape
# 以互動方式輸入指令
# 使用 'help' 查看可用指令
# 使用 'undo' 和 'redo' 進行歷史記錄導覽
匯出專案
將專案匯出為最終輸出格式。
cli-anything-inkscape --project myproject.json export pdf output.pdf --overwrite
包圍文字的版面配置
對於標題卡、標籤和直式安全面板，建議使用自動換行的文字框，而不是手動插入換行符號：
cli-anything-inkscape --project title.json text add \
--text "Real capture + Veo cold open + Gemini score + thumbnail plate" \
--x 180 --y 470 --font-size 118 \
--box-width 1180 --box-height 260 --line-height 1.05
cli-anything-inkscape --project title.json text set 0 box-width 980
cli-anything-inkscape --project title.json text set 0 line-height 1.15
注意事項：
box-width會將較長的文字內容自動換行，匯出為多行 SVGtspan。box-height可讓較長的文字安全地失敗，而不是跑出畫布。- 在需要手動換行之前，建議優先使用文字框來處理較長文字的圖形。
狀態管理
CLI 會維護會話狀態，包含：
- 復原/重做：最多 50 層的歷史記錄
- 專案持久化：以 JSON 格式儲存/載入專案狀態
- 會話追蹤：追蹤修改與變更
輸出格式
所有指令皆支援雙重輸出模式：
- 人類可讀（預設）：表格、顏色、格式化文字
- 機器可讀（
--json標記）：結構化 JSON，供代理程式使用
# 人類可讀輸出
cli-anything-inkscape project info -p project.json
# 供代理程式使用的 JSON 輸出
cli-anything-inkscape --json project info -p project.json
給 AI 代理的提示
當以程式化方式使用此 CLI 時：
- 務必使用
--json標記 以取得可解析的輸出 - 檢查回傳碼 - 0 代表成功，非零代表錯誤
- 解析 stderr 以取得失敗時的錯誤訊息
- 對所有檔案操作使用絕對路徑
- 匯出操作後，務必確認輸出檔案存在
- 優先使用文字框 來處理標題和可變長度的文字，以確保版面在編輯過程中保持穩定
更多資訊
- 完整文件：請參閱套件中的 README.md
- 測試涵蓋率：請參閱套件中的 TEST.md
- 方法論：請參閱 cli-anything-plugin 中的 HARNESS.md
版本
1.0.1