企业官网建设流程全解析

PhotoCraft CLI完全指南：无头批处理、convert/run/batch/droplet子命令实战手册

【免费下载链接】photocraftAn open-source, clean-room reimplementation of Adobe Photoshop in pure Rust项目地址: https://gitcode.com/gh_mirrors/pho/photocraft

PhotoCraft 是一款用纯 Rust 编写的开源图像编辑器（Photoshop 的 clean-room 重新实现），而PhotoCraft CLI（photocraft-cli）则是它强大的命令行入口：无需打开图形界面，即可无头完成格式转换、参数化修图、整目录批处理和拖放式 droplet 自动化。本文带你掌握convert、run、batch、droplet四大核心子命令的实战用法。

📦 先获取 PhotoCraft CLI

克隆仓库并构建，CLI 与桌面版来自同一套命令引擎：

git clone https://gitcode.com/gh_mirrors/pho/photocraft cd photocraft cargo build -p photocraft-cli

构建完成后，./target/debug/photocraft-cli --help即可查看全部用法。子命令定义见 apps/photocraft-cli/src/lib.rs，官方文档在 book/src/automation/cli.md。

🗂️ 八大子命令速览

核心思想：UI、CLI、JSON 控制通道、MCP 服务器调用的是同一个命令注册表——你能在界面里点的，脚本都能做。

🔄 convert 子命令：一键转换图像格式

支持.pcraft、.psd、.png、.jpg、.tif、.webp、.exr等格式的互转，--quality可控制 JPEG 质量（1–100）：

# PNG 转 PSD photocraft-cli convert cover.png cover.psd # 强制格式 + 质量（输出扩展名不匹配时靠 --format 指定） photocraft-cli convert photo.pcraft out.jpg --format jpg --quality 85

几个实用特性（实现见 apps/photocraft-cli/src/lib.rs）：

• 无损回环：png → pcraft → png像素完全一致，适合做中间存档格式；
• 自动推断格式：默认按输出扩展名决定编码格式；
• 警告不中断：打开/保存中的警告写到 stderr，退出码仍为 0，方便放进 shell 管道。

🎬 run 子命令：无头版 Photoshop

run是威力最大的子命令：打开（或用--new新建）文档后，按顺序执行任意引擎命令，每个命令的 JSON 结果逐行打印，最后可选保存。

# 打开 PSD → 智能锐化 → 加曲线调整图层 → 导出 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 # 不依赖现有文件：直接新建画布并绘制 photocraft-cli run --new '{"width":40,"height":30,"name":"Run"}' \ --cmd layer.new.layer --params '{"name":"Ink"}' --out canvas.pcraft

规则很简单：每个--params作用于它前面的那个--cmd；命令 ID 不确定时，用photocraft-cli commands --filter 曲线搜索即可。

📁 batch 子命令：整个目录批量处理

batch把一份"动作列表"应用到输入目录里的每一张图，是自动化管线的主力。动作文件是 JSON 数组：

[ { "command": "image.adjustments.autoTone", "params": {} }, { "command": "image.resize", "params": { "width": 1920 } } ]

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

行为要点（实现见 apps/photocraft-cli/src/lib.rs）：

• 自动过滤目录中可识别的图片文件，按名称排序处理；
• 输出目录不存在会自动创建，输出文件继承输入文件名（a.png → graded/a.png）；
• 单文件失败不会中断，逐个打印ok/FAIL，最后汇总成功与失败数，有失败时退出码为 1——非常适合 CI 任务。

🖱️ droplet 子命令：拖放即运行

Droplet 是 PhotoCraft 的"动作 + 批处理选项"打包成的.pcdroplet文件（在桌面版中通过 File › Automate › Create Droplet 创建）。CLI 可以直接执行它，甚至可以拖文件到脚本上运行：

# 对文件或整个文件夹执行 droplet photocraft-cli droplet my-action.pcdroplet ./photos/ --out ./result # 在桌面版创建时会自动生成同名 .command 壳脚本， # 把文件拖上去即可触发（见 crates/engine/src/automate_cmds.rs） ./my-action.command ./some-image.png

droplet 默认输出到 droplet 所在目录（或输入文件夹下的droplet-output），可用--out覆盖。解析与执行逻辑在 crates/engine/src/automate_cmds.rs。

🔎 两个辅助命令：info 与 commands

# 查看文档结构：尺寸、色彩模式、位深、完整图层树（JSON） photocraft-cli info big.psd --compact | less # 搜索命令注册表 photocraft-cli commands --filter sharpen photocraft-cli commands --json > registry.json

写脚本前先info摸清图层结构、用commands查参数签名，能少走 90% 的弯路。完整命令回归测试可参考 apps/photocraft-cli/tests/cli.rs。

🛡️ 安全与最佳实践

• 一次性任务优先用run/batch/mcp(stdio)，不要常开 TCP 监听端口；
• 无头服务器（serve、mcp --bridge）走 TCP 时必须携带 256 位 bearer token，且只绑定 127.0.0.1；
• 动作/参数文件请只放入你信任的内容——CLI 本身不做路径白名单，跑不受信的动作文件应在隔离账户中进行；
• 以最小权限的操作系统账户运行自动化。

更多自动化架构与安全边界见 book/src/automation/overview.md 与 book/src/automation/security-model.md。

🎯 总结

PhotoCraft CLI 让"图形界面里的每一步操作"都变成了可脚本化的原子命令：

从零开始：cargo build -p photocraft-cli→--help看用法 →commands --filter查命令 →run打通第一条管线，半小时就能搭起自己的无头图像处理流水线。

【免费下载链接】photocraftAn open-source, clean-room reimplementation of Adobe Photoshop in pure Rust项目地址: https://gitcode.com/gh_mirrors/pho/photocraft