CLI-Anything Photoshop
透過 Windows COM 自動化介面操控 Adobe Photoshop 的命令列工具。
前置條件
- Windows 10/11
- Adobe Photoshop 2023+（需註冊 COM 介面）
- Python 3.10+ 及
pywin32 套件
安裝
cd photoshop-harness/agent-harness
pip install -e .
安裝後可使用 cli-anything-photoshop 命令。
命令結構
cli-anything-photoshop [--json] [--project <path>] [--dry-run] <command-group> <command> [options]
全域選項
| 選項 | 描述 |
|---|
--json | 以 JSON 格式輸出（供 AI Agent 解析） |
--project <path> | 自動開啟或建立 PSD 專案檔案 |
--dry-run | 執行命令但不儲存到磁碟 |
命令組
project — 專案管理
| 命令 | 選項 | 描述 |
|---|
new <path> | -w width, -h height, -r resolution, -m mode, -b bg-color | 建立新 PSD |
open <path> | | 開啟 PSD 檔案 |
save [path] | | 儲存文件 |
close | --no-save | 關閉文件 |
document — 文件操作
| 命令 | 選項 | 描述 |
|---|
info | | 文件資訊 |
resize | -w width, -h height, -r resolution | 調整尺寸 |
canvas | -w width, -h height, -a anchor | 調整畫布 |
crop | --left --top --right --bottom | 裁切 |
rotate | -a angle | 旋轉畫布 |
flip | -d direction | 翻轉畫布 |
mode | -m mode | 更改色彩模式 |
trim | -t type | 裁切邊緣 |
layer — 圖層操作
| 命令 | 選項 | 描述 |
|---|
add | -n name, -t type, -o opacity, -b blend | 新增圖層 |
delete | -n name | 刪除圖層 |
duplicate | -n name, --new-name name | 複製圖層 |
rename | --old name, --new name | 重新命名 |
show / hide | -n name | 顯示/隱藏 |
opacity | -n name, -o opacity | 設定透明度 |
blend | -n name, -m mode | 設定混合模式 |
list | | 列出所有圖層 |
reorder | -n name, -p position | 調整順序 |
merge | -n name, --with-layer name | 合併圖層 |
selection — 選區操作
| 命令 | 選項 | 描述 |
|---|
all | | 全選 |
none | | 取消選取 |
invert | | 反轉選取 |
feather | -r radius | 羽化 |
expand | -p pixels | 擴張 |
contract | -p pixels | 收縮 |
border | -w width | 邊框選取 |
rect | --left --top --right --bottom | 矩形選取 |
fill | -c color, -o opacity | 填充選取 |
text — 文字操作
| 命令 | 選項 | 描述 |
|---|
add | -t text, -f font, -s size, -c color | 新增文字 |
edit | -n name, -t text, -f font, -s size, -c color | 編輯文字 |
info | -n name | 文字資訊 |
export — 匯出
| 命令 | 選項 | 描述 |
|---|
save <path> | -f format, -q quality, -w width, -h height | 匯出檔案 |
repl
使用範例
AI Agent 用法（--json 模式）
cli-anything-photoshop --json project new -w 800 -h 600 poster.psd
cli-anything-photoshop --json --project poster.psd text add -t "Hello World" -f Arial -s 48 -c "#FF0000"
cli-anything-photoshop --json --project poster.psd layer list
cli-anything-photoshop --json --project poster.psd export save -f png output.png
cli-anything-photoshop --dry-run --project poster.psd layer add -n "draft" --type text
人工使用
cli-anything-photoshop --project work.psd layer list
cli-anything-photoshop repl
Agent 使用指南
- 始終使用
--json 標誌 取得結構化輸出
- 使用
--dry-run 預覽，確認後再正式儲存
- 錯誤處理：退出碼非零時檢查
stderr 中的 JSON 錯誤物件
- 專案狀態：使用
--project 自動管理檔案開啟/儲存
- REPL 模式：適合多步驟互動式操作，減少 Photoshop 程序啟動開銷
Photoshop COM 架構
CLI 命令 → Click CLI → Core 模組 → ComBridge (單例) → Photoshop.Application COM → Photoshop 引擎
Photoshop 透過 Windows COM 介面暴露全部編輯能力。本 harness 封裝了最常用的操作。如需擴充，參考 Adobe Photoshop COM 文件新增方法到 utils/com_bridge.py。