PhotoCraft 故障排查与报错代码库 — 解决启动、黑屏、PSD 解析与崩溃问题

在 Early Alpha 阶段遇到异常？以下内容依据 PhotoCraft v0.2.0 ~ v0.3.0 最新已知问题整理。 如需在 GitHub Issues 提交反馈，请务必附带：操作系统 + 画布尺寸 + 图层数量 + 错误截图。

---

1. 安装与启动类故障#

ERR-INST-001 — Windows 安装包卡死在配置界面#

• 症状： 运行 Windows 安装包，弹出 UAC 提权并提示 "Please wait while Windows configures PhotoCraft"，进度条走完后程序无任何响应。
• 原因： 上游安装包打包打包脚本在部分 64位 Windows 机器上的偶发 Bug（GitHub Issue #866）。
• 避坑解法：
  1. 无需重复安装。
  2. 前往 官方 Releases 发布页 下载 Portable（绿色便携版）ZIP 压缩包（如 photocraft-v0.3.0-windows-x86_64-portable.zip）。
  3. 解压到任意非中文路径，直接双击 photocraft.exe 即可秒开。

ERR-INST-002 — Linux 双击无反应 / 报错缺失动态运行库#

• 症状： 终端提示 cannot open shared object file: libxkbcommon.so 或闪退。
• 解法：
  • 最省心解法： 改用 Flatpak（flatpak run ai.storyteller.photocraft）或 AppImage，这两个版本自带完整的沙箱运行时库。
  • 补充系统依赖： 若使用 tarball 或 deb/rpm，在 Debian/Ubuntu 下执行：

    sudo apt install libxkbcommon-x11-0 libwayland-client0 libwayland-cursor0 libxcursor1 libxrandr2 libxi6
    

  • 说明： v0.3.0 起已内置运行库自检机制（#201），缺库时会在终端明确打印缺失的具体库名。

macOS：提示“无法打开，因为 Apple 无法检查其是否包含恶意软件”#

• 症状： macOS Gatekeeper 安全网关拦截首次运行。
• 解法： 在访达中右键点击 PhotoCraft.app → 按住 Option/Alt 键点击 “打开” → 在弹窗中确认点击 “打开”。程序本身已包含 Apple 官方公证签名，仅因未入驻 Mac App Store 需首次人工放行。

macOS：命令行 CLI 首次运行卡住#

• 症状： 在终端运行 photocraft 命令时停顿十几秒无输出。
• 原因： 系统正在进行联网公证哈希比对。请保持网络连接等待验证完成，可通过以下命令验证签名状态：

  spctl --assess --type install -vv /Applications/PhotoCraft.app
  

---

2. 显示、GPU 与画布异常#

ERR-GPU-001 — 画布纯黑 / 画面闪烁 / GPU 设备丢失 (DeviceLost)#

• 症状： 界面正常但中央画布区域呈黑块，或日志打印 wgpu::DeviceLost 显卡重置。
• 解法：
  1. 升级显卡驱动： PhotoCraft 强依赖底层 Vulkan/DirectX12/Metal，老旧驱动极易导致 wgpu 崩溃。请前往 NVIDIA/AMD/Intel 官网更新最新版驱动。
  2. 升级到 v0.3.0+： 最新版引入了启动防崩安全回退与设备丢失自恢复机制（#4、#243、#252）。
  3. 双显卡笔记本： 请在 Windows “图形设置” 中将 PhotoCraft 指定为“高性能独立显卡”运行。

ERR-GPU-002 — 16位 / 32位 浮点色彩文档渲染偏色或花屏#

• 原因： 部分显卡硬件不支持 Rgba32Float 纹理直接渲染。
• 解法： 升级至 v0.2.0 或更高版本，内部已支持平滑降级至 Rgba16Float。

界面与文字工具出现方块（中日韩字符“豆腐块”乱码）#

• 原因： 宿主操作系统未安装 CJK 字体，或字体未正确映射。
• 解法： Linux 用户请安装中文字体包（如 sudo apt install fonts-noto-cjk）；官方正式 Release 包自带常用的备用字体。

---

3. PSD 文档读取与文件异常#

某个 PSD 文件打不开或打开后图层错位#

• 原因： 命中未被 clean-room 引擎完全建模的专有图层样式或高级矢量特性。
• 解法：
  • 在 Photoshop 中另存时勾选 “最大兼容性 (Maximize Compatibility)”。
  • 如确认属于 Bug，请按照标准模板前往 GitHub Issues 提交样本复现。
  • 提醒： PhotoCraft 重新保存 PSD 时不会丢弃未知数据块，但输出并非二进制字节完全一致，请勿直接覆盖原始商业工程母文件。

尼康相机压缩 NEF 打开仅显示小尺寸缩略图#

• 说明： 受限于无逆向工程的 Clean-Room 法律合规要求，尼康专有压缩算法尚未完成自研解码，目前会自动提取内嵌全尺寸高清预览图。建议先用 Adobe DNG Converter 批量转为 DNG 再行编辑。

---

4. MCP 与自动化调用报错#

automation command 'image.applyDataSet' uses ambient filesystem paths and is disabled#

• 原因： v0.2.0+ 引入的强安全防护机制（Issue #806），严禁 AI Agent 或外部脚本任意读写宿主机全盘路径。
• 解法： 启动程序时必须显式授权工作根目录：

  photocraft --automation-read-root /path/to/workdir --automation-write-root /path/to/output
  

  或者设置环境变量：

  export PHOTOCRAFT_AUTOMATION_READ_ROOT="/path/to/workdir"
  export PHOTOCRAFT_AUTOMATION_WRITE_ROOT="/path/to/output"
  

控制通道连接被拒绝 (Connection Refused)#

• 原因： 缺少启动动态 Token。
• 解法： 每次启动 PhotoCraft 时，终端会打印当次唯一的安全认证令牌，外部自动化程序必须携带该 Token 方可握手成功。