PhotoCraft LogoPhotoCraft

PhotoCraft 指南

源自上游 storytold/photocraft 项目的实用文档——安装包、PSD 工作流、面向代理的 CLI，以及从源码构建。PhotoCraft 处于早期 alpha：请预期仍有粗糙之处，并查看您所下载版本对应的发布说明。

PhotoCraft 是什么

PhotoCraft 是用纯 Rust 对 Adobe Photoshop 进行的开源、洁净室式重实现。它在原生应用中提供图层、蒙版、调整图层、图层样式、文字、矢量、画笔以及真实的 PSD/PSB 文件——可离线使用，采用 MIT 或 Apache-2.0 双许可，供您使用与学习。
菜单、快捷键、面板与工具刻意保持熟悉感。基于 wgpu（Metal、Vulkan、DX12、WebGPU）的 GPU 合成器、写时复制分块以及多线程滤镜，让编辑在本地快速完成——桌面应用无需 Electron 外壳。
  • 状态：早期 alpha。Photoshop 的许多功能以某种形式存在，但尚非日常 Photoshop 的全面替代，无法满足所有专业工作流。
  • 当前主要缺口：AI/生成式功能、部分缺失工具、版式与专业工作流深度，以及插件兼容性。
  • 合理预期：每个 Photoshop 菜单项可能已绑定命令，但绑定不等于完整的行为对等。最新情况请以上游路线图与对等说明为准。
  • 商标说明：Adobe 与 Photoshop 为 Adobe Inc. 的商标。PhotoCraft 独立运营，与 Adobe 无关联。

下载与安装

macOS、Windows、Linux、FreeBSD 及 Web 构建的官方安装包随各 GitHub 发布附带。可从本站下载页开始，或打开上游 Releases 页查看全部产物与校验和。

建议通过 photocraftdl.com 上的下载页获取精选链接，或浏览GitHub Releases获取各平台构建。每次发布均附带 SHA256SUMS.txt，便于校验下载内容。

各平台安装包（文件名模式）

平台应获取的内容
Windowsx64、arm64 与 x86 的 MSI 安装程序及便携 ZIP（例如 photocraft-<ver>-windows-x64.msi）。安装程序与可执行文件均经代码签名。
macOSApple 芯片与 Intel 通用 DMG（photocraft-<ver>-macos-universal.dmg），已签名并公证。可选 CLI：photocraft-cli-<ver>-macos-universal.zip。
LinuxAppImage、Flatpak、.deb、.rpm 以及 x86_64 与 aarch64 的 tarball。AppImage 可通过 AppImageUpdate（.zsync）自行更新。
FreeBSDx86_64 tarball，目录布局类似 /usr/local（先用 pkg 安装运行时依赖，再解压）。
Webphotocraft-web-<ver>.zip — 可在现代浏览器中运行的静态站点；可托管于任意静态服务器，或在可用时试用本站其他位置的浏览器内编辑器。

Linux Flatpak 快速入门

  • Flatpak 包需要 Flathub 上的 freedesktop 运行时；flatpak 会提示安装。
  • flatpak install --user photocraft-<version>-linux-x86_64.flatpak（或 aarch64 构建）
  • flatpak run ai.storyteller.photocraft

Linux AppImage 提示

  • 无需安装。首次运行可在 ~/.local/share 下注册启动器图标与菜单项，以便在 Wayland 下 Dock 显示 PhotoCraft 图标。
  • 设置 PHOTOCRAFT_NO_DESKTOP_INTEGRATION=1 可跳过桌面集成。

macOS CLI 公证

CLI zip 与应用使用同一 Developer ID 签名，并经 Apple 公证。裸二进制无法像 DMG 那样携带装订票据，因此首次运行可能在线检查公证。可用以下命令验证：

  • ditto -x -k photocraft-cli-<version>-macos-universal.zip .
  • spctl --assess --type install -vv photocraft-cli-<version>-macos-universal/photocraft-cli
  • 预期类似：accepted, source=Notarized Developer ID。

FreeBSD 14（x86_64）

  • pkg install libxkbcommon wayland libX11 libXcursor libXrandr libXi libxcb mesa-libs vulkan-loader gtk3 fontconfig freetype2 alsa-lib
  • tar -xzf photocraft-<version>-freebsd-x86_64.tar.gz --strip-components 1 -C /usr/local
  • photocraft

首次启动与日常编辑

打开文档、熟悉工具界面，并在深入 PSD 往返或自动化之前了解若干 Linux/Wayland 注意事项。

启动 PhotoCraft，通过「文件 › 打开」打开图像或 PSD，或在终端启动时传入路径（例如源码构建后使用 photocraft image.psd）。编辑留在本机——核心工具无需云账户。

开箱可期待的功能

  • 53 种工具，涵盖选框、套索、对象/快速选择、画笔、修复、文字、钢笔/形状、减淡/加深等。
  • 图层能力完整 — 组、剪贴蒙版、像素与矢量蒙版、填充与调整图层、带智能滤镜的智能对象、混合模式、不透明度/填充与历史记录。
  • 调整图层保持编辑可逆（色阶、曲线、自然饱和度、色相/饱和度等），不破坏原始像素。
  • 图层样式如投影、发光、斜面与浮雕、描边与叠加——文字图层同样可用。
  • 文字、矢量与滤镜，选区内可实时预览滤镜；自由变换支持完整历史记录。
  • 色深 — RGB、灰度、CMYK 与 Lab，每通道 8/16/32 位，纯 Rust 实现 ICC 色彩管理。

Wayland 拖放（Linux）

在 Wayland 会话中，拖放到窗口的文件可能尚无法打开——这是 egui 下层窗口栈的限制。变通办法：

  • 使用「文件 › 打开」，或在文件管理器中复制图像后用 Ctrl+V 粘贴。
  • 要恢复拖放，可在 XWayland 下启动：WAYLAND_DISPLAY= photocraft，或对 AppImage / Flatpak 按上游文档使用带 X11 套接字的相同方式。

导出与主题

  • 使用「导出为」设置格式、质量、透明度与缩放，并预览与估算大小；快速导出可一键写入 PNG。
  • 在应用偏好中可在深色 Pro、明亮 Studio 与 Classic 外观间切换。

PSD、格式与往返

PhotoCraft 的 PSD 支持是依据 Adobe 公开规范编写、并对真实语料测试的独立 crate——并非对专有代码的薄封装。

可打开、编辑并保存分层 Photoshop 文档。上游报告：重新保存时，309 个 psd-tools 测试文件中有 307 个渲染保持一致（混合语料上结果同样出色）。重新保存的文件与源文件并非字节级相同：图像资源、图层记录与合成会被重写。尽可能保留不支持的原始块与描述符，而非丢弃。

PSD 之外的格式

  • PSD / PSB — 含大文档、16/32 位、CMYK 与 Lab。
  • 分层 TIFF — TIFF 中的 Photoshop 图层数据，任一字节序。
  • OpenRaster — 读写图层、组与混合模式（Krita、MyPaint、GIMP）。
  • Paint.NET PDN3 — 可读可编辑图层；SVG 可打开为形状或作为矢量智能对象置入。
  • 平面格式 — PNG、JPEG、TIFF、WebP、GIF、BMP、TGA、ICO、QOI、PNM、OpenEXR、Radiance HDR，以及原生 .pcraft。
  • 可选 / 有限：官方构建中 HEIC 只读；AVIF 写入需可选功能；Affinity 文档只读打开，不支持部分会警告。

可靠处理 PSD 的提示

  • 在评估早期 alpha 行为时，大量往返前请保留重要源 PSD 副本。
  • 若重新保存后出现问题，向上游提交 issue 时请注明操作系统、文档尺寸、图层数量并附截图。
  • 各格式编解码细节见仓库文档中的上游 codecs 能力矩阵。

CLI、批处理与代理

每个菜单项、工具与对话框均通过同一套 500+ 命令注册表运行。UI、CLI、JSON 控制通道与 MCP 服务器调用同一引擎——因此脚本能点的，代理也能驱动。

无头编辑示例（命令名与参数以您安装版本的上游 CLI 帮助为准）：
  • 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 batch --actions grade.json --in ./raw --out ./graded
  • photocraft-cli batch --help — 各子命令均有说明。
  • photocraft-cli mcp — 通过 MCP 让代理驱动 PhotoCraft（无头，或桥接到运行中的应用）。

桌面控制通道

桌面应用可暴露经认证、仅环回的 control channel（photocraft --control），用于检查 UI 状态、用指针事件驱动工具以及截取离屏截图。上游在 docs/control-protocol.md 中记录协议。

从源码构建

克隆上游仓库，以 release 模式运行桌面应用，并可选择指向 craft-fonts 以捆绑 CJK 界面/字体。

需要较新的 Rust 工具链。新贡献者与 AI 代理应先从上游 AGENTS.md 入手，再阅读 docs/ 树与文档书。

最小桌面运行

  • git clone https://github.com/storytold/photocraft
  • cd photocraft
  • cargo run --release -p photocraft -- image.psd
  • cargo test --workspace — 修改代码后运行测试套件。

可选日文 / CJK 字体（craft-fonts）

界面与文字工具的日文字体来自 craft-fonts，为可选构建输入（桌面 release 构建始终包含）。无此项时 PhotoCraft 使用系统 CJK 字体：

  • git clone https://github.com/storytold/craft-fonts ../craft-fonts
  • CRAFT_FONTS_DIR="$PWD/../craft-fonts" cargo run --release -p photocraft

测试语料

  • PhotoCraft 针对真实文件测试（oracle PSD、psd-tools、ag-psd、PngSuite），固定版本并校验和验证。
  • 使用 cargo xtask corpus --all 获取，cargo xtask test-corpus 运行（细节见上游 docs/development.md）。

与上游保持同步

标志、包名与对等状态随每次发布变化。请以您检出的 commit 或 tag 对应的 README、Release 说明与文档为准，而非较旧的社区快照。上游仓库：github.com/storytold/photocraft。

获取帮助

出现问题时，请提交 issue 并注明操作系统、文档尺寸、图层数量与截图。也可在上游项目页所链接的 ArtCraft Discord 提问。