用 CLI 和 MCP 自动化 PhotoCraft
用 photocraft-cli 批量转换 PSD、套用动作；接入 PhotoCraft 开源 MCP 服务器，让 Claude Code、Claude Desktop、Cursor 等 AI 助手修图导出，文件访问限定在指定目录。
PhotoCraft 有两条自动化路线。一是 photocraft-cli：每个桌面版都自带这个命令行工具，不开窗口就能转换格式、查看文档信息、批量处理图片。二是 photocraft-cli mcp：它会启动一个 MCP 服务器，让 Claude Code、Claude Desktop、Cursor 等 AI 助手打开文档、调用 PhotoCraft 的 500 多个引擎命令、查看预览并保存结果。MCP 服务器既可以无界面（headless）运行，也可以桥接到你正在用的 PhotoCraft 窗口。两条路线调用的都是菜单背后的同一套命令。本文按 v0.7.0（2026 年 10 月 11 日）编写。自动化功能变化很快，具体以你手上版本的 photocraft-cli --help 为准。
photocraft-cli 在哪里
Windows 和 Linux 没有单独的 CLI 下载，它就在常规安装包里。只有 macOS 需要另外下载一个文件：
| 安装包 | CLI 位置 |
|---|---|
| Windows MSI | C:\Program Files\PhotoCraft\photocraft-cli.exe（或你自选的安装目录），不会加入 PATH |
| Windows 便携版 zip | 解压后与 photocraft.exe 同目录的 photocraft-cli.exe |
| macOS | 单独的 photocraft-cli-<ver>-macos-universal.zip。DMG 里的 PhotoCraft.app 只有桌面程序 |
Linux .deb / .rpm | /usr/bin/photocraft-cli |
| Linux tar.gz（x86_64、aarch64、riscv64） | 解压目录下的 bin/photocraft-cli |
| Linux Flatpak | 在沙盒内运行：flatpak run --command=photocraft-cli ai.storyteller.photocraft |
| Linux AppImage | 用不了：AppImage 只启动桌面程序 |
| FreeBSD tar.gz | bin/photocraft-cli |
32 位 x86 版 MSI 在 64 位 Windows 上默认装到 Program Files (x86)\PhotoCraft。macOS 的 CLI 是同时支持 Apple 芯片和 Intel 的通用二进制，已签名并经过公证，第一次运行时 macOS 会联网核验公证。各系统的安装步骤见 Windows、macOS 和 Linux，所有文件都在下载页。
先确认能用：
photocraft-cli --version
photocraft-cli --help
命令行工具
子命令一览
| 命令 | 作用 |
|---|---|
convert <in> <out> | 打开一个文件，按扩展名另存为其他格式（.pcraft、.psd、.png、.jpg、.tif、.webp、.exr 等） |
info <file> | 以 JSON 输出文档信息：尺寸、颜色模式、位深、图层树。加 --compact 输出为一行 |
run | 打开文件（或用 --new <json> 新建），依次执行引擎命令，可用 --out 保存 |
batch | 对一个文件夹里的所有图片套用同一个动作 |
droplet | 对文件或文件夹运行 .pcdroplet 快捷批处理 |
commands | 列出命令注册表。--filter <text> 过滤，--json 附带参数说明 |
mcp | 在 stdio 上启动 MCP 服务器 |
serve | 保持一个无界面会话，通过 stdio 或本机回环端口收发 JSON 行 |
convert、run、batch 还支持 --format <ext>、--quality <1-100> 和 --tiff-layers。--quality 作用于 JPEG 和 WebP：指定了质量的 WebP 是有损的，不指定则是无损。TIFF 默认输出拼合图像，加 --tiff-layers 才保留图层。完整用法用 photocraft-cli <子命令> --help 查看。
README 里的示例连续执行两个命令，再导出 PNG：
photocraft-cli run wave.psd \
--cmd filter.sharpen.smartSharpen --params '{"amount":80}' \
--cmd layer.newAdjustmentLayer.curves --params '{"points":[[0,0],[64,48],[192,212],[255,255]]}' \
--out wave-final.png
每个 --params 作用于它前面那个 --cmd，run 每执行完一个命令就输出一行 JSON 结果。命令 ID 和参数可以用 photocraft-cli commands --filter blur 查找（加 --json 可看参数说明），这些命令对应的菜单项可参考快捷键速查。
退出码与拼写错误
成功退出码为 0，执行失败为 1，用法错误为 2。子命令不认识的参数（比如把 --format 敲成 --fromat）按用法错误处理，不会被悄悄忽略。batch 中只要有一个文件失败，整次运行就以 1 退出，但其余文件照常处理。
缺失字体提示
从 v0.6.0 起（#1299），文字图层用到未安装的字体时，CLI 会明确提示，不会把替代字体的渲染结果当成原样输出：
convert和run在导出前向标准错误输出warning: font '<family>' is not installed; text may render using a fallback face。info --compact把同样的内容放进 JSON 的warnings数组，不写到标准错误。run还会在首次发现缺失字体的那条命令的 JSON 结果里加上warnings，同一字体只报一次。
这些提示不会中断导出，也不会改动文件里记录的字体名。要列出或替换缺失字体，请执行引擎命令 type.resolveMissingFonts。
batch：一个动作处理整个文件夹
photocraft-cli batch --actions grade.json --in ./raw --out ./graded
photocraft-cli batch --actions actions.json --in photos/ --out done/ --format jpg
截至 v0.7.0 的行为：
- 动作文件：记录动作的各个步骤，可以写成
[["<id>", {…}], …]、[{"command": "<id>", "params": {…}}, …]或只写命令 ID，直接用列表，或包在{"actions": …}、{"steps": …}里都行。.pcdroplet文件也能直接用。 - 输入：只处理
--in文件夹里直接存放的图片，按文件名顺序处理，不读子文件夹。 - 输出：每张图存为
<out>/<文件名>.<扩展名>。扩展名取--format，没给就沿用原文件的扩展名。--out不存在时会自动创建。 - 同一次运行不会互相覆盖：两个输入会生成同名输出时（例如
a.png和a.jpg都存成 JPEG），后一个记为失败，不会覆盖前一个的结果。 - 保护原图：
--out和--in是同一个文件夹时，batch会拒绝执行，除非加上--in-place。 - 输出信息：每个文件输出
ok <in> -> <out>或FAIL <in>: <error>，最后一行是汇总。
动作和快捷批处理
先在桌面版的 动作（Actions）面板里录制一个动作并选中，然后：
- 文件 › 自动化 › 批处理…（File › Automate › Batch…）：在程序里对一个文件夹运行它。对话框会建议输出到
batch文件夹，格式可选same、png、jpg、psd、tiff。 - 文件 › 自动化 › 创建快捷批处理…（File › Automate › Create Droplet…）：把它存成
.pcdroplet文件，之后交给photocraft-cli运行。在 macOS、Linux 和 FreeBSD 上还会在旁边生成一个.command小脚本。把文件拖到这个脚本上或作为参数传给它，它就会调用photocraft-cli droplet（设置了PHOTOCRAFT_CLI环境变量就用它，否则用PATH里的photocraft-cli）。
photocraft-cli droplet grade.pcdroplet ./raw --out ./graded
不加 --out 时，结果写到快捷批处理里保存的输出目录，没有保存的话就写到第一个输入文件旁边的 droplet-output 文件夹。
v0.7.0 的变化：
- 调用其他动作的动作可以批处理了。 文件 › 自动化 › 批处理 现在会给每个文件一份完整的动作列表，被批处理的动作可以调用另一个动作（“播放动作”步骤，即
actions.play）。被调用的动作里有步骤失败时，这个文件记为失败，而不是报成功（#2783）。用 文件 › 脚本 › 浏览… 运行的脚本也加了同样的检查。 - 录制的保存步骤由目标文件夹取代。 动作现在可以录制 文件 › 保存 和 另存为（#2746）。批处理和创建快捷批处理时会去掉这些步骤，文件存到哪里由输出文件夹决定，相当于 Photoshop 的“覆盖动作中的‘存储为’命令”。
- 跳过缩放和适合屏幕步骤。 动作里录了 放大、适合屏幕 这类视图步骤时，批处理和快捷批处理不再拒绝执行（#2761），含这类步骤的旧快捷批处理文件也能跑了。
还有一个限制（截至 v0.7.0）：photocraft-cli batch 和 photocraft-cli droplet 运行时动作列表是空的，“播放动作”步骤没有可调用的对象。给 CLI 用的动作，请不要调用其他动作。
MCP 服务器
无界面模式和桥接模式
| 无界面（headless） | 桥接（bridge） | |
|---|---|---|
| 启动 | photocraft-cli mcp --automation-read-root <dir> --automation-write-root <dir> | photocraft-cli mcp --bridge 127.0.0.1:<port> --control-token-file <path> |
| 谁在干活 | CLI 进程内的引擎，没有窗口，不用 GPU | 用 --control <port> 启动的桌面程序 |
| 能否看到编辑过程 | 不能，靠预览图 | 能，窗口里实时显示 |
| 文件访问范围 | 传给 CLI 的根目录 | 传给桌面程序的根目录 |
| 额外工具 | doc_select、doc_close | ui_inspect、ui_screenshot、ui_pointer、ui_menu_invoke、ui_set、control_call |
两种模式都通过 stdio 传输 MCP，无界面模式不会开任何网络端口。无人值守的批量任务适合用无界面模式；想看着 AI 改图，或者让它操作真实界面里的工具和对话框，就用桥接模式。
文件根目录：AI 能碰哪些文件
默认不给任何文件访问权限，必须在启动时明确授予：
--automation-read-root <dir>：允许打开<dir>下的文件。--automation-write-root <dir>：允许在<dir>下保存和导出。
读和写是分开授权的。少给一个参数，对应方向就被禁止，请求会报 automation filesystem access is not granted: read authority is absent 之类的错误。README 里不带参数的 photocraft-cli mcp 能在内存里新建和编辑文档，但打不开也存不了任何文件。无界面模式必须用命令行参数指定根目录：PHOTOCRAFT_AUTOMATION_READ_ROOT 和 PHOTOCRAFT_AUTOMATION_WRITE_ROOT 这两个环境变量只对桌面程序有效。根目录请用绝对路径，指向专门准备的文件夹（比如单独建一个 photocraft-work），不要直接给整个用户目录。
工具调用里的路径可以写成：
- 相对根目录的路径，用正斜杠：
in/cat.psd。 - 位于根目录之下的绝对路径：从 v0.7.0 起（#2216，修复 #2176），根目录是
C:\work时，C:/work/in/cat.psd或C:\work\in\cat.psd都能用。之前的版本只接受相对路径。
绝对路径的检查刻意做得很严：PhotoCraft 把请求路径和根目录当作文本逐段比较，只有盘符不区分大小写，从不在磁盘上解析路径。以下情况都会在动文件之前被拒绝：根目录之外的路径、..、根目录本身、CON 这类 Windows 设备名、a.bin:hidden 这类备用数据流、同一位置的其他写法（\\?\C:\…、8.3 短文件名、经符号链接表示的根目录），以及指向根目录外的符号链接。通过检查后，文件仍经由与相对路径相同的目录句柄打开。后续的 #2528 补充了对名字相近的同级目录和 sub/../.. 这类回溯写法的测试。另外，新输出文件所在的文件夹必须事先存在。
自带文件路径参数的引擎命令在自动化中一律被禁用，报错为 automation command `…` uses ambient filesystem paths and is disabled; use capability-scoped document methods。几乎所有 file.* 命令都在此列，包括 file.open、file.save 和 file.automate.batch，layer.exportAs {path} 这类路径参数也一样。打开和保存请改用 doc_open、doc_save、doc_export 工具。少数不涉及路径的 file.* 命令仍可使用，例如 file.new 和 file.automate.fitImage。
在 Claude Code 中注册
从 v0.7.0 起，MCP 文档补上了从正式安装包注册的方法（#2185）。把 <dir> 换成你的工作目录：
# Windows, default install folder
claude mcp add photocraft -- "C:\Program Files\PhotoCraft\photocraft-cli.exe" mcp --automation-read-root <dir> --automation-write-root <dir>
# Linux, or macOS with the CLI unzipped onto PATH
claude mcp add photocraft -- photocraft-cli mcp --automation-read-root <dir> --automation-write-root <dir>
也可以在项目根目录放一个 .mcp.json。下面是官方示例：第一项是无界面模式，第二项是后文介绍的桥接模式。官方示例里的 command 是源码编译后的路径，请换成你安装的 CLI 路径（例如 /usr/bin/photocraft-cli）：
{
"mcpServers": {
"photocraft": {
"command": "/path/to/photocraft/target/release/photocraft-cli",
"args": ["mcp", "--automation-read-root", "/absolute/path/to/trusted/workspace", "--automation-write-root", "/absolute/path/to/trusted/workspace"]
},
"photocraft-live": {
"command": "/path/to/photocraft/target/release/photocraft-cli",
"args": ["mcp", "--bridge", "127.0.0.1:7878", "--control-token-file", "/private/path/photocraft-control.token"]
}
}
}
Claude Desktop
官方文档只写了 Claude Code。Claude Desktop 使用同样的 mcpServers 配置块，写在它自己的 claude_desktop_config.json 里，可以从 Claude Desktop 的设置中打开。command 要写 CLI 的完整路径，改完后重启 Claude Desktop。Windows 路径在 JSON 里要把反斜杠写成两个：
{
"mcpServers": {
"photocraft": {
"command": "C:\\Program Files\\PhotoCraft\\photocraft-cli.exe",
"args": ["mcp", "--automation-read-root", "C:\\Users\\you\\Pictures\\photocraft-work", "--automation-write-root", "C:\\Users\\you\\Pictures\\photocraft-work"]
}
}
}
macOS 上，command 填你放解压后二进制的位置，比如 /usr/local/bin/photocraft-cli。Linux 用 .deb 或 .rpm 安装的话，填 /usr/bin/photocraft-cli。
Cursor 和其他 MCP 客户端
截至 v0.7.0，官方没有针对 Cursor 的说明。只要客户端能用“命令 + 参数列表”的方式启动 stdio MCP 服务器，就可以填上面同样的 command 和 args，配置文件放在哪里请看客户端自己的文档。v0.6.0 起，工具的参数 schema 不再含 $ref、$defs 或布尔 schema（#1845），因为一些校验严格的大模型服务商会因此拒绝整个请求（#1782）。
用 Flatpak 的话，CLI 在沙盒里运行：命令填 flatpak，参数是 run --command=photocraft-cli ai.storyteller.photocraft mcp …。沙盒只能访问“图片”和“文档”文件夹，根目录要设在这两个文件夹里面。
桥接模式：操作正在运行的 PhotoCraft
-
带上控制通道、私有令牌文件和根目录启动 PhotoCraft：
photocraft --control 7878 --control-token-file /private/path/photocraft-control.token \ --automation-read-root /work/project --automation-write-root /work/projectWindows 上程序是
C:\Program Files\PhotoCraft\photocraft.exe，macOS 装到“应用程序”后是/Applications/PhotoCraft.app/Contents/MacOS/PhotoCraft。令牌文件不存在时，PhotoCraft 会生成一个新的 256 位令牌写进去（Unix 上权限为0600；Windows 上请自行设置为仅本人可读）。既没给令牌文件也没给令牌时，PhotoCraft 会为本次启动临时生成一个，并输出到标准错误。 -
让 MCP 客户端连接桥接，使用同一个令牌文件：
photocraft-cli mcp --bridge 127.0.0.1:7878 --control-token-file /private/path/photocraft-control.token
桥接模式下，文件根目录由桌面程序掌管，所以要在 photocraft 上设置，而不是在做桥接的 CLI 上设置。桥接只连接本机回环地址。如果请求在传输中失败（比如超时），桥接会提示操作可能已经执行，但不会自动重发（#1527），重试前请先检查文档状态。桌面程序对每个请求最多等 60 秒。在 Wayland 上，显示器休眠或窗口被完全遮挡时，即使程序本身正常，所有请求也可能超时。
桥接模式下的 doc_save 按程序当前设置保存。从 v0.6.0 起，传入 format、quality、tiffLayers、index 会直接报错，不再悄悄忽略（#1138）。Flatpak 沙盒没有网络权限，控制端口在沙盒外访问不到。Flatpak 清单里的注释说明，可以用 flatpak override --user --share=network ai.storyteller.photocraft 让宿主机上的代理连进来。
工具列表
官方把这五个称为共享核心工具：command_list、command_run、command_batch、doc_inspect、render_preview。截至 v0.7.0 的完整列表（自 #1573 起写入文档）：
| 工具 | 作用 | 模式 |
|---|---|---|
command_list | 引擎命令的 ID、名称、菜单路径、参数说明，以及当前能否执行。参数 filter、enabled_only | 两种 |
command_run | 执行一个命令：id，可选 params 和 wait | 两种 |
command_batch | 按顺序执行最多 256 个 steps，stop_on_error 默认为 true。每个命令占一步历史记录，不是原子事务 | 两种 |
doc_inspect | 以 JSON 返回图层树、历史记录和选区 | 两种 |
render_preview、doc_render_preview | 拼合后的 PNG 预览（index、max_side） | 两种；桥接模式下是窗口截图 |
session_list | 已打开的文档和当前文档 | 两种 |
doc_open | 打开读取根目录下的文件 | 两种 |
doc_new | 新建文档（默认 1920×1080、RGB、8 位、白色背景） | 两种 |
doc_save、doc_export | 保存或导出到写入根目录下，扩展名决定格式，可设 quality、tiffLayers | 两种（选项仅限无界面模式） |
doc_select、doc_close | 切换或关闭文档（关闭不保存） | 仅无界面模式 |
jobs_list、jobs_cancel | 查看和取消后台任务 | 两种 |
ui_inspect、ui_screenshot | 实时界面状态、窗口截图 | 仅桥接模式 |
ui_pointer、ui_menu_invoke、ui_set | 以文档坐标模拟鼠标或数位笔、执行菜单项、设置工具和面板状态 | 仅桥接模式 |
control_call | 调用任意控制协议方法 | 仅桥接模式 |
doc_save 不带 path 时，只会写回原本就是 PSD、PSB 或 .pcraft 的文件，并保持原格式。其他情况都必须给 path，这样拼合或转换后的副本永远不会覆盖你打开的原文件。工具收到不认识的参数时，会在执行前直接报错。资源 photocraft://document 和 photocraft://commands 返回的实时 JSON 与 doc_inspect、command_list 相同。
耗时命令：后台任务和渲染视频
滤镜、内容识别填充和缩放、Photomerge、导入画笔都可能比较慢。command_run 默认等它们完成；传 "wait": false 会立即返回一个任务 ID，之后用 jobs_list 查看进度（0 到 1），用 jobs_cancel 取消。任务被取消或失败时，文档保持原样；任务运行期间，对同一文档的其他编辑会失败，直到任务结束。
从 v0.6.0 起（#1668），无界面模式下用 command_run 执行 file.export.renderVideo 会逐帧报告进度，也可以取消。要先建好文档和时间轴（先 doc_new，再 timeline.create）。官方示例把 PNG 序列写到写入根目录下的 frames 文件夹：
{"jsonrpc":"2.0","id":20,"method":"tools/call","params":{"name":"command_run","arguments":{"id":"file.export.renderVideo","params":{"dir":"frames","format":"png"}},"_meta":{"progressToken":"export-20"}}}
{"jsonrpc":"2.0","method":"notifications/cancelled","params":{"requestId":20}}
只有客户端发送了 progressToken 才会收到进度通知，频率最多每秒十次。取消会在帧与帧之间停下，只删除本次任务创建的文件。目标位置已有同名文件时一开始就会拒绝，所以之前导出的结果不会被覆盖。PNG 序列和 GIF 动画使用同一个渲染器。渲染视频即使传了 wait: false 也是同步执行的。它不能在桥接模式或动作里使用，放在 command_batch 里也不会报告进度，不能单独取消某一步。能否中途取消一次工具调用，取决于你的 MCP 客户端。
预览
render_preview 返回拼合后的 PNG。max_side 默认 1024，最大 2048，传 0 表示在这个上限内输出原尺寸。无界面模式下可以用 index 预览其他已打开的文档，而不切换当前文档。从 v0.6.0 起，index 指向不存在的文档，或在桥接模式下传入任何 index，都会报错，不会返回一张错误的图（#1600）。无界面预览还限制源文档最多 67,108,864 像素，PNG 最大 5 MiB。桥接模式下的预览是程序窗口截图。想确认改动是否到位，doc_inspect 往往比看图更可靠：它会列出图层类型、边界、蒙版、图层样式、智能滤镜、文字内容和调整参数。
其他入口：控制通道、serve 和脚本
-
控制通道：
photocraft --control <port>会在127.0.0.1上接受经过认证的 JSON 行，任何脚本都能用，不限于 MCP。每个连接的第一行必须是{"id": "auth", "method": "auth", "params": {"token": "<64 hexadecimal characters>"}}。桥接工具能做的它都能做，包括ui.pointer、ui.screenshot、engine.execute。README 里的截图就是这样渲染出来的。全部方法见 control-protocol.md。 -
photocraft-cli serve：保持一个无界面会话，在 stdio 上收发 JSON 行（doc.open、engine.execute、batch、doc.save等），加--port和令牌后也可以监听本机端口。脚本需要大量编辑时，它比 MCP 更快，根目录参数也一样：printf '%s\n' \ '{"id":1,"method":"doc.open","params":{"path":"in.jpg"}}' \ '{"id":2,"method":"batch","params":{"steps":[{"command":"image.adjustments.invert"},{"command":"filter.blur.gaussianBlur","params":{"radius":3}}]}}' \ '{"id":3,"method":"doc.save","params":{"path":"out.png"}}' | \ photocraft-cli serve --automation-read-root /work/project --automation-write-root /work/project -
程序内脚本：文件 › 脚本 › 浏览…（File › Scripts › Browse…）运行一个脚本文件，可以是 JSON 动作，也可以是纯文本，每行一条
command.id {json params}，#开头为注释。文件 › 脚本 › 脚本事件管理器…（Script Events Manager…）可以在打开、保存文档等事件发生时运行脚本。通过自动化进行的打开和保存不会触发脚本事件。
网页版（包括本站的在线编辑器）不支持这些自动化方式，因为浏览器无法监听端口。请使用桌面版。
实用示例
把一个文件夹的 PSD 转成 PNG
convert 一次只处理一个文件，用循环遍历文件夹：
mkdir -p png
for f in psd/*.psd; do
photocraft-cli convert "$f" "png/$(basename "${f%.psd}").png"
done
$cli = "C:\Program Files\PhotoCraft\photocraft-cli.exe"
New-Item -ItemType Directory -Force png | Out-Null
Get-ChildItem psd\*.psd | ForEach-Object { & $cli convert $_.FullName "png\$($_.BaseName).png" }
留意标准错误里的 warning: 行，缺失字体和 PNG 存不下的内容都会在这里提示。
批量缩小并导出 JPEG
把下面的内容存为 resize.json。file.automate.fitImage 会把图片等比缩放到框内，加上 dontEnlarge 后，本来就更小的图片保持不变：
[["file.automate.fitImage", {"width": 1600, "height": 1600, "dontEnlarge": true}]]
photocraft-cli batch --actions resize.json --in ./photos --out ./web --format jpg --quality 85
要指定精确宽度，改用 ["image.imageSize", {"width": 1200}]。只给 width 时，高度按原比例计算。
用录好的动作批量处理
-
在 动作 面板里录制动作并选中。
-
用 文件 › 自动化 › 创建快捷批处理… 把它存成
.pcdroplet。 -
在终端、计划任务或其他脚本里运行：
photocraft-cli droplet grade.pcdroplet ./raw --out ./graded # or with the batch options: photocraft-cli batch --actions grade.pcdroplet --in ./raw --out ./graded --format png
如果这个动作会调用其他动作，请改在程序里用 文件 › 自动化 › 批处理… 运行（原因见上文“动作和快捷批处理”一节）。
让 AI 助手缩图并导出
注册好无界面模式的服务器，读写根目录都设为 photocraft-work。把图片放进 photocraft-work/in，再建好 photocraft-work/out，然后这样说：
打开 in/cover.psd，在不放大的前提下缩到 1600×1600 以内，先给我看预览，再以质量 85 导出为 out/cover.jpg。
一个靠谱的助手会依次调用 doc_open、执行 file.automate.fitImage 的 command_run、render_preview，最后调用带 quality: 85 的 doc_export。要一次完成多步编辑，可以用 command_batch：
{"steps": [{"id": "file.automate.fitImage", "params": {"width": 1600, "height": 1600, "dontEnlarge": true}}, {"id": "filter.sharpen.smartSharpen", "params": {"amount": 80}}], "stop_on_error": true}
文件很多时，要么把文件名告诉助手，要么让它用自己的工具列出文件夹内容（Claude Code 可以）。PhotoCraft 的 MCP 服务器没有列目录的工具，file.automate.batch 在自动化中也被禁用，所以助手只能逐个文件地打开、编辑、导出、doc_close。如果是固定流程处理大量文件，photocraft-cli batch 更快，也不依赖模型的发挥。
限制与安全
- CLI 子命令不受根目录限制。
convert、run、batch、droplet接受普通的系统路径，你的账户能读写的地方它都能读写。只有 MCP 服务器和serve受根目录约束。来源不明的动作文件和快捷批处理，请在隔离的账户或机器上运行。 - 令牌不等于权限系统。 拿到控制令牌的人就能使用控制通道里除文件访问以外的全部功能：执行命令、模拟鼠标键盘、退出程序。目前还没有按工具划分的权限，工具上的注解提示也不代表授权。令牌文件要妥善保管，不要提交到代码库，也不要写进日志。在多人共用、能看到他人进程命令行的机器上，不要用
--control-token直接传令牌。 - 只在本机使用。 控制协议没有加密，只监听回环地址。不要把它或 stdio 服务器通过隧道、代理暴露给其他主机或不可信的中转服务。官方也建议不要让控制端口长期开着。
- 把内容当作不可信输入。 文档里的文字、图层名和工具描述都可能夹带写给 AI 的指令。根目录给得越窄越好，输入和输出尽量分开，不要把密钥等敏感信息放进文件名、元数据或命令参数。
- 上限。
command_batch最多 256 步，工具返回结果最大 8 MiB。TCP 单行请求最大 1 MiB（stdio 上的 MCP 不限制请求大小），每个监听端口最多 16 个连接，套接字超时 30 秒。批处理的返回数据超出预算时会停下，已经做过的编辑不会回滚，重试前请先检查文档。 - 输出有上限，耗时没有。 目前没有会话内存预算，也没有通用的命令超时，超大文档或很重的滤镜仍可能跑很久。
- 仍是 alpha 版。 PhotoCraft 处于早期 alpha 阶段，命令参数在版本之间可能变化。让助手先调用
command_list，别依赖它记住的命令 ID。
常见报错
| 报错（节选） | 含义 |
|---|---|
automation filesystem access is not granted: read authority is absent | 启动服务器时没给 --automation-read-root（保存时则是缺 write） |
absolute paths must be inside the automation root | 绝对路径按文本比较不在根目录之下。检查拼写、盘符和符号链接 |
automation command `…` uses ambient filesystem paths and is disabled | 用了 file.* 命令或路径参数，请改用 doc_open、doc_save、doc_export |
… drives the live GUI and needs bridge mode | 在无界面模式下调用了 ui_* 工具或 control_call |
… is still running on this document | 后台任务占着这个文档，等它结束或调用 jobs_cancel |
发现 CLI 或 MCP 服务器的问题，请到 GitHub 提交 issue，写明操作系统、PhotoCraft 版本、完整命令或工具调用以及报错信息。