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 提問。