Loading

AIGC标识 PhotoCraft CLI 调用说明_20261011

PhotoCraft CLI 调用说明_20261011

由于此软件更新迭代非常快，所以请查看最新版本文章
本文面向任何想用命令行脚本化「排版 / 出图 / 出分层 PSD」的人。
一句话：PhotoCraft 是「命令驱动」的类 Photoshop 编辑器，一张图 = 一条 run 命令链，每个图层、文字、形状都是命令参数，最终可直接输出 PNG / JPG / PSD。
https://github.com/storytold/photocraft

一、PhotoCraft 是什么

  • 纯 Rust 开源的类 Photoshop 图像编辑器（仓库：github.com/storytold/photocraft），离线、免费、可商用（MIT / Apache-2.0）。
  • 两个可执行文件：
    • photocraft.exe —— 桌面 GUI（手动操作，类似 PS）
    • photocraft-cli.exe —— 命令行（脚本化 / AI 驱动做图的核心）
  • 核心设计：所有操作都来自同一套 500+ 命令注册表，UI 里能点的，命令行就能跑，因此可被脚本或 AI 精确、批量地驱动。

二、安装与获取

从 GitHub Releases 下载对应平台安装包：https://github.com/storytold/photocraft/releases

平台 说明
Windows .msi 安装包，或 -portable.zip 便携版（解压即用，含 photocraft-cli.exe）
macOS .dmg 应用 + photocraft-cli-<ver>-macos-universal.zip（单独的命令行工具）
Linux AppImage / Flatpak / .deb / .rpm / tarball

安装后找到 CLI 可执行文件（Windows 通常在 C:/Program Files/PhotoCraft/photocraft-cli.exe）。首次运行建议先 photocraft-cli commands 确认可用。

三、核心用法：一条命令链完成整张图

photocraft-cli run <输入文件 | --new 画布JSON> \
  --cmd 命令1 --params '参数JSON' \
  --cmd 命令2 --params '参数JSON' \
  ... \
  --out 输出文件
  • --new '{"width":1080,"height":1440,"background":"#FFFFFF","name":"xxx"}' 新建画布（单位 px，background 支持 white/black/transparent/#hex）。
  • 也可以用现有图片 / PSD 文件作为起点（run 输入.psd ...）。
  • 每个 --cmd 后紧跟一个 --params（JSON），作用于前一个命令。
  • 输出格式由 --out 的扩展名决定：.png / .jpg / .webp / .psd（分层工程）/ .tif 等。
  • 命令按顺序执行，后放置的图层在上层。

其它子命令：

photocraft-cli commands [--filter 关键词]   # 列出全部命令（500+）
photocraft-cli convert <in> <out> --format   # 格式互转
photocraft-cli info <文件> --compact         # 读文档/图层树（JSON）
photocraft-cli batch --actions x.json --in d --out d   # 批量套动作
photocraft-cli mcp                            # 以 MCP server 方式供 AI 驱动

每个子命令都能 photocraft-cli <子命令> --help 看完整参数说明。

四、常用命令速查

命令 作用 关键参数
file.new 新建文档 width, height, background, name, mode, depth
file.placeEmbedded 放置图片（底图/素材） path, fit:true(铺满), center:[x,y], scale
type.create 新建文字层 x,y(基线), text, font, size(pt), color, weight(100-900), align, tracking, box:[x,y,w,h](段落自动换行), name
type.setStyle 改已有文字样式 layer, font, size, color, weight, tracking, leading…
type.fonts 列出可用字体 {}
shape.create 画矢量形状（矩形/圆角/椭圆/线/星…） kind, rect:[x,y,w,h], fill, radii, stroke, name
layer.newFillLayer.solidColor 纯色填充层 color
layer.newFillLayer.gradient 渐变填充层 from, to, angle, style
layer.layerStyle.dropShadow 投影 color, opacity, distance, size
layer.layerStyle.stroke 描边 size, position, color, opacity
layer.layerStyle.gradientOverlay 渐变叠加 from, to, angle, opacity
layer.rasterize.type 栅格化文字层 layer
file.export.quickExport 快速导出 path
layer.exportAs 按图层导出 layer, path, scale

type.create 的 x,y 是文字基线锚点；align:"center" 时 x 为水平中心。加粗 / 拉字距直接传 weight / tracking，无需额外命令。

五、实战示例：做一张竖版海报

photocraft-cli run --new '{"width":1080,"height":1440,"background":"#1B4F9C","name":"海报"}' \
  --cmd file.placeEmbedded --params '{"path":"背景图.png","fit":true}' \
  --cmd type.create --params '{"x":540,"y":300,"text":"标题文字","align":"center","font":"Source Han Sans CN","size":96,"color":"#FFFFFF","weight":700,"tracking":120,"name":"主标题"}' \
  --cmd layer.layerStyle.dropShadow --params '{"color":"#000000","opacity":80,"distance":0,"size":20}' \
  --cmd type.create --params '{"x":120,"y":600,"text":"这是一段会按宽度自动换行的正文说明。","font":"Source Han Serif CN","size":40,"color":"#EAF2FF","box":[120,600,840,400],"name":"正文"}' \
  --cmd shape.create --params '{"kind":"rect","rect":[120,540,840,4],"fill":"#FFD166","name":"分隔线"}' \
  --cmd file.placeEmbedded --params '{"path":"二维码.png","center":[540,1200]}' \
  --out 成品.psd

要点：

  • 分隔线 = 一个细长矩形 shape.create kind:rect（高 4px 的色条）。
  • 正文用 box 参数即成段落文字，按给定宽度自动换行。
  • 想输出高清 PNG，把 --out 成品.psd 改成 --out 成品.png 即可（或先出 PSD 再 convert 成图）。

六、通用技巧与注意事项

  1. 新层自动选中：type.create 之后紧跟 layer.layerStyle.*（不传 layer），样式会自动作用到刚建的文字层——这是给文字批量加投影 / 描边的捷径。
  2. 中文字体：Windows 系统通常已注册 Source Han Sans CN（黑体）、Source Han Serif CN（宋体）、Noto Sans SC、微软雅黑 等，font 直接填 family 名；用 type.fonts 可列出全部可用字体。
  3. 输出格式靠扩展名推断：--out 写 /dev/null 这类无扩展名路径会报「cannot tell the format」，务必带 .png / .psd 等后缀。
  4. PSD 是真分层工程：文字是 Type 层（保留字体 / 字号 / 内容，可改字）、形状是 Shape 层、贴图是 Smart Object。用 info 文件.psd --compact 可读图层树核对。
  5. 透明底 / 反色图片：若素材是「白色内容 + 透明底」，放在白底上会「隐形」，需垫深色底；必要时先用图像库合成到底色再 placeEmbedded。
  6. reg.exe 拦截提示无害：Windows 上 CLI 每次启动可能调 reg.exe 枚举字体，被安全策略拦截后会打印 PROGRAM BLOCKED…reg.exe，不影响任何功能（文字照常渲染），可忽略。
  7. 验证渲染：convert 文件.psd 预览.png --format png 转图后，用脚本采样像素颜色即可核对（标题色 / 正文色 / 位置是否对）。

七、进一步参考

  • photocraft-cli <子命令> --help —— 每个子命令的完整参数
  • photocraft-cli commands --json —— 全部命令及参数定义
  • 官方仓库 AGENTS.md 与 docs/control-protocol.md —— 面向 AI/脚本的高级用法（MCP、headless server、控制通道）
posted @ 2026-10-11 18:58  离者悲名  阅读(56)  评论(0)    收藏  举报