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 模式）
# 创建新项目并获取 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"
# 列出所有图层（JSON 格式）
cli-anything-photoshop --json --project poster.psd layer list
# 导出为 PNG
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
人工使用
# 打开 PSD，交互编辑
cli-anything-photoshop --project work.psd layer list
# 启动 REPL
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。
1---2name: cli-anything-photoshop3description: 通过 COM 自动化操控 Adobe Photoshop 的 CLI harness。支持项目管理、图层操作、选区控制、文字编辑、图像调整和多格式导出。4---56# CLI-Anything Photoshop78通过 Windows COM 自动化接口操控 Adobe Photoshop 的命令行工具。910## 前置条件1112- **Windows 10/11**13- **Adobe Photoshop 2023+** (需注册 COM 接口)14- **Python 3.10+** 及 `pywin32` 包1516## 安装1718```bash19cd photoshop-harness/agent-harness20pip install -e .21```2223安装后可使用 `cli-anything-photoshop` 命令。2425## 命令结构2627```28cli-anything-photoshop [--json] [--project <path>] [--dry-run] <command-group> <command> [options]29```3031### 全局选项3233| 选项 | 描述 |34|------|------|35| `--json` | 以 JSON 格式输出（供 AI Agent 解析） |36| `--project <path>` | 自动打开或创建 PSD 项目文件 |37| `--dry-run` | 执行命令但不保存到磁盘 |3839## 命令组4041### project — 项目管理42| 命令 | 选项 | 描述 |43|------|------|------|44| `new <path>` | `-w` width, `-h` height, `-r` resolution, `-m` mode, `-b` bg-color | 创建新 PSD |45| `open <path>` | | 打开 PSD 文件 |46| `save [path]` | | 保存文档 |47| `close` | `--no-save` | 关闭文档 |4849### document — 文档操作50| 命令 | 选项 | 描述 |51|------|------|------|52| `info` | | 文档信息 |53| `resize` | `-w` width, `-h` height, `-r` resolution | 调整尺寸 |54| `canvas` | `-w` width, `-h` height, `-a` anchor | 调整画布 |55| `crop` | `--left --top --right --bottom` | 裁切 |56| `rotate` | `-a` angle | 旋转画布 |57| `flip` | `-d` direction | 翻转画布 |58| `mode` | `-m` mode | 更改色彩模式 |59| `trim` | `-t` type | 裁切边缘 |6061### layer — 图层操作62| 命令 | 选项 | 描述 |63|------|------|------|64| `add` | `-n` name, `-t` type, `-o` opacity, `-b` blend | 添加图层 |65| `delete` | `-n` name | 删除图层 |66| `duplicate` | `-n` name, `--new-name` name | 复制图层 |67| `rename` | `--old` name, `--new` name | 重命名 |68| `show` / `hide` | `-n` name | 显示/隐藏 |69| `opacity` | `-n` name, `-o` opacity | 设置透明度 |70| `blend` | `-n` name, `-m` mode | 设置混合模式 |71| `list` | | 列出所有图层 |72| `reorder` | `-n` name, `-p` position | 调整顺序 |73| `merge` | `-n` name, `--with-layer` name | 合并图层 |7475### selection — 选区操作76| 命令 | 选项 | 描述 |77|------|------|------|78| `all` | | 全选 |79| `none` | | 取消选区 |80| `invert` | | 反转选区 |81| `feather` | `-r` radius | 羽化 |82| `expand` | `-p` pixels | 扩展 |83| `contract` | `-p` pixels | 收缩 |84| `border` | `-w` width | 边框选区 |85| `rect` | `--left --top --right --bottom` | 矩形选区 |86| `fill` | `-c` color, `-o` opacity | 填充选区 |8788### text — 文字操作89| 命令 | 选项 | 描述 |90|------|------|------|91| `add` | `-t` text, `-f` font, `-s` size, `-c` color | 添加文字 |92| `edit` | `-n` name, `-t` text, `-f` font, `-s` size, `-c` color | 编辑文字 |93| `info` | `-n` name | 文字信息 |9495### export — 导出96| 命令 | 选项 | 描述 |97|------|------|------|98| `save <path>` | `-f` format, `-q` quality, `-w` width, `-h` height | 导出文件 |99100### repl101| 命令 | 描述 |102|------|------|103| `repl` | 启动交互式 REPL 模式 |104105## 使用示例106107### AI Agent 用法（--json 模式）108109```bash110# 创建新项目并获取 JSON 输出111cli-anything-photoshop --json project new -w 800 -h 600 poster.psd112113# 添加文字图层114cli-anything-photoshop --json --project poster.psd text add -t "Hello World" -f Arial -s 48 -c "#FF0000"115116# 列出所有图层（JSON 格式）117cli-anything-photoshop --json --project poster.psd layer list118119# 导出为 PNG120cli-anything-photoshop --json --project poster.psd export save -f png output.png121122# 预览（不保存）123cli-anything-photoshop --dry-run --project poster.psd layer add -n "draft" --type text124```125126### 人工使用127128```bash129# 打开 PSD，交互编辑130cli-anything-photoshop --project work.psd layer list131132# 启动 REPL133cli-anything-photoshop repl134```135136## Agent 使用指南1371381. **始终使用 `--json` 标志** 获取结构化输出1392. **使用 `--dry-run` 预览**，确认后再正式保存1403. **错误处理**：退出码非零时检查 `stderr` 中的 JSON 错误对象1414. **项目状态**：使用 `--project` 自动管理文件打开/保存1425. **REPL 模式**：适合多步骤交互式操作，减少 Photoshop 进程启动开销143144## Photoshop COM 架构145146```147CLI 命令 → Click CLI → Core 模块 → ComBridge (单例) → Photoshop.Application COM → Photoshop 引擎148```149150Photoshop 通过 Windows COM 接口暴露全部编辑能力。本 harness 封装了最常用的操作。如需扩展，参考 Adobe Photoshop COM 文档添加新方法到 `utils/com_bridge.py`。
yb2460