用命令行和 AI Agent 操作 PhotoCraft（CLI + MCP）

PhotoCraft 的每个菜单项、工具和对话框都对应同一套命令（超过 500 个）。这些命令同样可以通过命令行工具和 MCP 服务器 调用，所以你能点的操作，脚本和 AI Agent 也都能做。下面所有内容都用 macOS 上的 photocraft-cli 0.7.0 实测过。

安装 photocraft-cli

在 macOS 上，从 GitHub Release 下载 photocraft-cli-0.7.0-macos-universal.zip，它已签名并经过公证。解压后把程序放进 PATH：

ditto -x -k photocraft-cli-0.7.0-macos-universal.zip .
sudo mv photocraft-cli-0.7.0-macos-universal/photocraft-cli /usr/local/bin/
photocraft-cli --version
# photocraft-cli 0.7.0 (792616159, 2026-10-11)

photocraft-cli --help 会列出所有子命令：convert、info、run、batch、droplet、commands、mcp 和 serve。

不打开软件直接修图

run 会打开文件、按顺序执行命令并保存结果，每个 --params 作用于它前面的 --cmd。下面的命令给一幅画加锐化，再添加一个曲线调整图层：

photocraft-cli run milkmaid.jpg \
  --cmd filter.sharpen.unsharpMask --params '{"amount":120,"radius":2,"threshold":2}' \
  --cmd layer.newAdjustmentLayer.curves --params '{"points":[[0,0],[60,40],[128,128],[196,220],[255,255]]}' \
  --out milkmaid-sharpened-curves.png

它为每个命令输出一行 JSON 结果，处理一张 2675×3000 的图大约用了 0.56 秒：

{"command":"filter.sharpen.unsharpMask","result":{"filter":{"amount":120.0,"filter":"unsharpMask","radius":2.0,"threshold":2.0},"layer":2}}
{"command":"layer.newAdjustmentLayer.curves","result":{"layer":3}}
warning: 2 layer(s) flattened; layers, masks and blend modes are not kept

那条警告是正常的：PNG 不能保存图层。改成 --out result.psd 就会保留曲线图层，用 photocraft-cli info result.psd 可以确认。

查找命令 ID

photocraft-cli commands --filter curves
photocraft-cli commands --json > commands.json

批量处理整个文件夹

在软件里录制一个动作（或者手写一个 JSON 步骤列表），然后应用到文件夹里的每张图：

photocraft-cli batch --actions grade.json --in ./raw --out ./graded --format jpg --quality 90

如果输出文件夹就是输入文件夹，PhotoCraft 会拒绝执行（除非加上 --in-place），避免误覆盖原图。

通过 MCP 接入 AI Agent

photocraft-cli mcp 会在标准输入输出上运行一个 MCP 服务器。在我们的测试中，它报告为 photocraft 0.7.0，提供 21 个工具，包括：

command_list, command_run, command_batch, doc_new, doc_open, doc_inspect, doc_save, doc_export, doc_render_preview, render_preview, session_list, jobs_list, jobs_cancel

另外 5 个工具（ui_inspect、ui_set、ui_pointer、ui_menu_invoke、ui_screenshot）和 control_call 用于 桥接模式，即由 Agent 直接操作正在运行的软件窗口，而不是后台引擎。

把它加入 MCP 客户端的配置，并用 automation root 参数限制 Agent 可读写的目录：

{
  "mcpServers": {
    "photocraft": {
      "command": "/usr/local/bin/photocraft-cli",
      "args": ["mcp", "--automation-read-root", "/Users/you/Pictures", "--automation-write-root", "/Users/you/Pictures/out"]
    }
  }
}

然后对 Agent 说，比如：“打开 portrait.jpg，加一个提亮暗部的曲线调整，导出 1600 像素宽的 JPEG。” 它会用 command_list 查找命令、用 command_run 编辑、用 render_preview 检查效果，最后用 doc_save 保存。

操作正在运行的软件（桥接模式）

带上控制端口和令牌文件启动桌面版，再让 MCP 服务器连接它：

photocraft --control 7878 --control-token-file ~/.photocraft-token
photocraft-cli mcp --bridge 127.0.0.1:7878 --control-token-file ~/.photocraft-token

控制通道只监听本机（127.0.0.1），并且每个连接都要验证令牌。请妥善保管令牌文件。

安全建议

• 把 --automation-write-root 指向专门的输出文件夹，而不是整个用户目录。
• 让 Agent 批量修改时，先在副本上操作。
• 完整协议见 docs/control-protocol.md。