cli-anything-gimp 是做什麼的？
一個有狀態的命令列介面，用於影像編輯，基於 Pillow 構建。專為 AI 代理程式與進階使用者設計，無需 GUI 即可建立和操作影像。
安裝
此 CLI 作為 cli-anything-gimp 套件的一部分安裝：
pip install cli-anything-gimp
前置需求：
- Python 3.10+
- 建議安裝 GIMP 以進行原生批次渲染，但當 GIMP 不可用或存在延遲
draw操作時，仍可透過內建的 Pillow 路徑渲染圖層合成。
用法
基本指令
# 顯示說明
cli-anything-gimp --help
# 啟動互動式 REPL 模式
cli-anything-gimp
# 建立新專案
cli-anything-gimp project new -o project.json
# 以 JSON 輸出執行（供代理程式使用）
cli-anything-gimp --json project info -p project.json
REPL 模式
當不帶子指令呼叫時，CLI 會進入互動式 REPL 對話：
cli-anything-gimp
# 使用 Tab 補全與歷史記錄功能，互動輸入指令
指令群組
專案 (Project)
專案管理指令。
| 指令 | 說明 |
|---|---|
new | 建立新專案 |
open | 開啟現有專案 |
save | 儲存當前專案 |
info | 顯示專案資訊 |
profiles | 列出可用的畫布設定檔 |
json | 列印原始專案 JSON |
圖層 (Layer)
圖層管理指令。
| 指令 | 說明 |
|---|---|
new | 建立新的空白圖層 |
add-from-file | 從影像檔案新增圖層 |
list | 列出所有圖層 |
remove | 依索引移除圖層 |
duplicate | 複製圖層 |
move | 將圖層移動到新位置 |
set | 設定圖層屬性（名稱、不透明度、可見性、模式、offset_x、offset_y）；負偏移值自然支援 |
flatten | 合併所有可見圖層 |
merge-down | 將圖層與其下方的圖層合併 |
畫布 (Canvas)
畫布操作。
| 指令 | 說明 |
|---|---|
info | 顯示畫布資訊 |
resize | 調整畫布大小（不縮放內容） |
scale | 等比例縮放畫布與所有內容 |
crop | 將畫布裁切為矩形 |
mode | 設定畫布色彩模式 |
dpi | 設定畫布 DPI |
濾鏡群組 (Filter Group)
濾鏡管理指令。
| 指令 | 說明 |
|---|---|
list-available | 列出所有可用的濾鏡 |
info | 顯示濾鏡詳細資訊 |
add | 將濾鏡新增至圖層 |
remove | 依索引移除濾鏡 |
set | 設定濾鏡參數 |
list | 列出圖層上的濾鏡 |
媒體 (Media)
媒體檔案操作。
| 指令 | 說明 |
|---|---|
probe | 分析影像檔案 |
list | 列出專案中引用的媒體檔案 |
check | 檢查所有引用的媒體檔案是否存在 |
histogram | 顯示影像的直方圖分析 |
匯出群組 (Export Group)
匯出/渲染指令。
| 指令 | 說明 |
|---|---|
presets | 列出匯出預設集 |
preset-info | 顯示預設集詳細資訊 |
render | 將專案渲染為影像檔案；延遲繪圖操作在渲染時套用 |
工作階段 (Session)
工作階段管理指令。
| 指令 | 說明 |
|---|---|
status | 顯示工作階段狀態 |
undo | 復原上一次操作 |
redo | 重做上一次復原的操作 |
history | 顯示復原歷史 |
繪圖 (Draw)
繪圖操作（在渲染時套用）。
| 指令 | 說明 |
|---|---|
text | 在圖層上繪製文字（將其轉換為文字圖層） |
rect | 繪製矩形（儲存為繪圖操作） |
範例
建立新專案
建立新的 gimp 專案檔案。
cli-anything-gimp project new -o myproject.json
# 或以 JSON 輸出供程式化使用
cli-anything-gimp --json project new -o myproject.json
互動式 REPL 工作階段
啟動支援復原/重做的互動式工作階段。
cli-anything-gimp
# 互動輸入指令
# 使用 'help' 查看可用指令
# 使用 'undo' 和 'redo' 瀏覽歷史
匯出專案
將專案匯出為最終輸出格式。
cli-anything-gimp --project myproject.json export render output.png --overwrite
圖層合成工作流程
適用於重疊繁重的合成：
cli-anything-gimp --project poster.gimp-cli.json layer set 0 offset_x -48
cli-anything-gimp --project poster.gimp-cli.json layer set 0 offset_y 24
cli-anything-gimp --project poster.gimp-cli.json draw text --layer 0 --text "Launch Night" --x 96 --y 120 --size 72 --color "#f6f1e8"
cli-anything-gimp --project poster.gimp-cli.json export render output.png --overwrite
備註：
layer set現在支援指令模式與 REPL 模式中的負數offset_x和offset_y值。draw text和draw rect是渲染時的操作。請將匯出的影像（而不只是專案 JSON）視為需要審查的內容。- 對於包含延遲繪圖操作的專案，即使已安裝 GIMP，也應預設使用 Pillow 渲染路徑作為穩定預設路徑。
狀態管理
CLI 透過以下方式維護工作階段狀態：
- 復原/重做：最多 50 層歷史記錄
- 專案持久化：將專案狀態儲存/載入為 JSON
- 工作階段追蹤：追蹤修改與變更
輸出格式
所有指令都支援雙輸出模式：
- 人類可讀（預設）：表格、顏色、格式化文字
- 機器可讀（
--json旗標）：結構化 JSON，供代理程式使用
# 人類輸出
cli-anything-gimp project info -p project.json
# 代理程式使用的 JSON 輸出
cli-anything-gimp --json project info -p project.json
給 AI 代理程式的提示
以程式化方式使用此 CLI 時：
- 始終使用
--json旗標 以取得可解析的輸出 - 檢查回傳碼 - 0 代表成功，非零代表錯誤
- 解析 stderr 以取得失敗時的錯誤訊息
- 使用絕對路徑 進行所有檔案操作
- 確認輸出存在 在匯出操作後
- 檢查渲染輸出 在偏移、繪圖、混合模式或濾鏡變更後，不要僅信任已儲存的專案狀態
更多資訊
- 完整文件：請參閱套件中的 README.md
- 測試覆蓋率：請參閱套件中的 TEST.md
- 方法論：請參閱 cli-anything-plugin 中的 HARNESS.md
版本
1.0.0