一句话看懂
LightCraft 是一个用 Rust 从零实现的开源 RAW 照片开发与管理工具，对标 Adobe Lightroom，支持桌面原生应用与浏览器 WebAssembly 运行，内置 MCP 服务器可供 AI 代理通过命令直接操控完整后期流程。
它解决什么问题
专业摄影后期依赖 Lightroom 处理 RAW 格式照片，但其为专有软件，依赖闭源技术栈且不可定制。LightCraft 提供开源替代方案，完全用 Rust 重写核心管线，无 C/C++ 依赖，保持高性能与跨平台支持。采用非破坏性编辑（即原始文件不被修改），所有操作可撤销可持久化。内置 MCP 服务器与 91 个引擎命令、48 个 UI 命令，AI 代理可通过 JSON 协议实现端到端自动化后期。
核心概念速览
Scene-referred pipeline：场景参考管线，在线性光照空间处理图像，保持物理世界光照关系。使用 Linear Rec.2020 float 内部色彩空间，白平衡通过 Bradford 适配，避免传统 display-referred（显示参考）流程过早剪裁高光与暗部细节。
Non-destructive editing：非破坏性编辑，所有调整不修改原始文件，可随时撤销或重置。每次参数变更转换为操作日志写入目录，原始 RAW 文件始终不变。
MCP (Machine Control Protocol)：机器控制协议，用于 AI 代理与应用通信。每个菜单项、滑块、画笔、裁剪手柄、键盘快捷键都对应稳定的命令 ID 与 JSON 参数，AI 客户端如 Claude 可通过 MCP 服务器调用实现自动化。
StageCache：按输入键值缓存管线中间结果，避免重复计算。每个处理阶段的缓存键仅由其直接依赖的输入参数决定，用户调整曝光时只有后续色调与显示阶段需要重新计算。
Resolution-independent edits：分辨率无关编辑，所有参数相对于图像长边，不同分辨率输出效果一致。
架构拆解
核心架构分为六层：
lightcraft-raw：RAW 格式解码层，支持 DNG、CR2、NEF、ARW、RAF 等主流格式，从文件头识别容器类型，解压像素数据，返回 CFA（Color Filter Array，色彩滤镜阵列）原始阵列、黑白电平、色彩矩阵等元数据。
lightcraft-pipeline：CPU 参考渲染管线，按五阶段处理图像。几何阶段执行用户方向调整、镜头矫正（畸变、色差、暗角）、透视变换、裁剪拉直、翻转、去边缘色散。曝光阶段在场景线性空间应用白平衡、曝光补偿、去雾、局部色调（高光/阴影）、纹理、清晰度、局部调整遮罩。色调映射阶段对亮度应用对比度/白色/黑色胶片式曲线，高光去饱和。色彩阶段在 OkLCh 色彩空间调整自然饱和度、饱和度、色彩混合器、色彩分级、黑白转换。显示阶段将色域映射到输出空间（默认 sRGB），编码为显示参考格式，应用色调曲线（参数化与点曲线）、晕影、颗粒。
lightcraft-gpu：GPU 加速管线实现，使用 wgpu 计算着色器，后端支持 Metal、Vulkan、DirectX 12，与 CPU 管线在像素级别保持完全等价。
lightcraft-catalog：照片库模型层，提供日志持久化、查询、过滤、相册、关键词、标记管理。每次用户操作转换为 Op（操作）写入日志，目录重建时重放所有操作恢复状态。
lightcraft-engine：引擎门面，统一命令分发接口。Session::execute 接收命令 ID 与 JSON 参数，分发到对应处理器，生成操作日志，管理撤销/重做栈，调度渲染任务。所有状态变更通过 Catalog 完成，保证可撤销性与可持久化。
lightcraft-mcp：MCP 服务器实现，向外暴露 photo.rate、develop.set、album.create、mask.add 等工具，AI 客户端通过标准 MCP 协议调用，服务器转换为引擎命令执行，返回 JSON 结果。
apps/lightcraft：桌面应用主入口，使用 egui 构建 UI，集成原生菜单，启动控制服务器监听 JSON-lines 协议，响应用户交互时调用引擎会话接口。
数据流向：用户在 UI 或通过 MCP 发起操作 → 引擎解析命令并操作目录 → 提交渲染请求到管线 → 管线调用 RAW 解码器获取源图像 → CPU 或 GPU 管线执行五阶段处理 → 返回显示编码的 sRGB 图像与直方图 → UI 更新显示。
关键实现走读
管线模块文档注释（crates/pipeline/src/lib.rs 模块级注释）：
//! The LightCraft develop pipeline (CPU reference implementation).
//!
//! Input: a scene-referred, linear Rec.2020 source image (already EXIF-oriented) at any resolution
//! (full size or a proxy), plus [`DevelopSettings`]. Output: a display-encoded sRGB image at the
//! requested size, and its histogram.
//!
//! Stage order (see `docs/pipeline.md`):
//! 1. geometry — user orientation, lens corrections (distortion, CA, vignetting), perspective, crop +
//! straighten, flips; one resample at output resolution; then defringe
//! 2. scene-linear — white balance, exposure, dehaze, local tone (highlights/shadows), texture,
//! clarity, local adjustments (masks)
//! 3. tone map — contrast / whites / blacks filmic curve on luminance, highlight desaturation
//! 4. colour — vibrance, saturation, colour mixer, colour grading, B&W (OkLCh)
//! 5. display — gamut map to the output space (sRGB unless [`RenderRequest::space`] says otherwise), encode, tone curves (parametric + point), vignette, grain
定义 CPU 参考管线的输入输出契约与五阶段处理顺序。输入为已完成 EXIF 方向校正的场景参考线性 Rec.2020 源图像与 DevelopSettings 参数，输出为指定尺寸的显示编码 sRGB 图像与直方图。五阶段串行执行且顺序固定，每个阶段只依赖其直接输入，方便缓存中间结果。
引擎模块文档注释（crates/engine/src/lib.rs 模块级注释）：
//! The LightCraft engine façade.
//!
//! Every user-visible action is a command with a stable id (`photo.rate`, `develop.set`,
//! `album.create`, `mask.add`…) and JSON parameters. The egui UI, the CLI, the control channel and
//! the MCP server all go through [`Session::execute`].
//!
//! State: a [`Catalog`] (mutated only by ops, so every change is undoable and journaled), the
//! library view (filter/sort/source), the selection, the develop clipboard, presets, and caches
//! of decoded source proxies. Rendering is done by [`RenderJob`]s that are `Send` so frontends can
//! run them off the UI thread.
定义统一命令分发架构，所有用户可见操作都对应稳定命令 ID 与 JSON 参数，通过 Session::execute 执行。状态由 Catalog 管理，仅通过 op 修改，保证所有变更可撤销且可写入日志。渲染任务封装为 Send 的 RenderJob，可在非 UI 线程执行。
动手上手
启动桌面应用并开启控制服务器：
lightcraft --control 7980 ~/Pictures/trip
验证结果：应用窗口打开，加载 ~/Pictures/trip 目录中的照片，同时在 7980 端口监听控制命令。终端显示 Control server listening on 127.0.0.1:7980。
构建 CLI 工具：
cargo build --release -p lightcraft-cli
验证结果：target/release/ 目录下生成 lightcraft-cli 或 lightcraft-cli.exe 可执行文件。
配置 Claude Desktop 使用 MCP 服务器：
claude mcp add lightcraft -- "$PWD/target/release/lightcraft-cli" mcp ~/Pictures/shoot
验证结果：Claude Desktop 配置文件新增 lightcraft 服务器配置，工作目录指向 ~/Pictures/shoot。在 Claude 中输入 "用 lightcraft 导入照片" 能看到相关工具调用。
批量处理 RAW 图像并导出：
验证结果：in.dng 被导入临时目录，应用 +0.7 EV 曝光补偿，导出长边 2048 像素的 out.jpg。
应用场景
专业摄影师 RAW 后期流程：导入拍摄的 DNG 或 CR2 文件，使用 Highlights/Shadows/Clarity 调整曝光层次，通过 Color Grading 工具分离色调实现冷暖对比，添加 Linear 或 Radial 渐变遮罩压暗天空或提亮主体，最终导出 JPEG 或 TIFF 交付客户。
AI 代理批量处理照片：启动带 --control 参数的桌面应用或使用 lightcraft-cli mcp 启动 MCP 服务器，AI 客户端如 Claude 通过 JSON-lines 协议或标准 MCP 接口发送命令序列：photo.flag 标记待处理照片、develop.set 批量应用曝光与色彩调整、mask.add 添加局部遮罩、app.export 导出结果到指定目录。
浏览器端照片预览编辑：运行 cargo xtask web 构建 WebAssembly 版本，在浏览器中打开生成的 HTML 页面，从本地文件系统选择 RAW 文件，应用预设与局部调整，实时预览效果，导出处理后的 JPEG 或 PNG。所有处理在浏览器沙箱内完成，原始文件不离开本地。
独立分析
纯 Rust 重实现相比 C/C++ 提升了安全性与可维护性。README 明确标注 "Pure Rust, no C"，workspace 级别 lints 设置 unsafe_code = deny，整个代码库禁止 unsafe 代码块。这消除了内存安全漏洞、数据竞争、悬垂指针等 C/C++ 常见问题，编译器在编译期捕获大量错误。Rust 的所有权系统与生命周期检查保证资源管理正确性，纯 Rust 生态也简化了跨平台构建。
GPU 加速在 Apple M4 Pro 上 24 MP RAW 单次滑块重渲染约 4 毫秒。README 给出测试数据：M4 Pro 芯片上，滑块更新触发的重渲染耗时约 4 毫秒，冷启动 2.5 MP 放大预览耗时约 30 毫秒，完整尺寸导出耗时约 0.3 秒。这得益于五阶段管线缓存策略与 GPU 并行计算。用户调整曝光时，几何变换结果从 StageCache 复用，只有后续三阶段需要重新计算。wgpu 计算着色器将像素处理分发到数千个工作组并行执行，Metal、Vulkan、DX12 后端充分利用现代 GPU 的并行计算能力。
LightCraft 定位为 Adobe Lightroom 的清洁室重实现，README 明确说明这一点。Lightroom 为专有软件，核心技术封闭且不可定制，LightCraft 从零用 Rust 重写管线，完全开源（Apache-2.0 许可证），代码可审计可修改。但 README 也标注项目 "young & moving fast"，功能覆盖度与成熟度与 Lightroom 存在差距。
局限与风险
项目处于早期阶段，状态标注为 "young & moving fast"，API 与功能快速迭代，向后兼容性可能不保证。生产环境使用需评估当前版本稳定性与功能完整度。
某些 RAW 格式变体尚不支持：Nikon 分割后有损压缩 NEF、Panasonic 量化 RW2、压缩 ORF（Olympus）与 RAF（Fujifilm）、Canon CR3。遇到这些格式会解码失败或输出异常。
完整的 WCAG 无障碍合规性需要手动测试与专家评审。自动化工具可检查部分标准，但键盘导航、屏幕阅读器适配、对比度动态调整等需要实际测试。
GPU 初始化在某些 Windows Vulkan 环境下可能崩溃。Issue #136 记录了此问题，已通过将 Windows 默认后端从 Vulkan 切换到 DirectX 12 修复。
目录日志文件随操作增长，数万张照片与频繁编辑会导致日志文件体积膨胀，影响加载性能。定期压缩或归档历史日志可缓解，但当前版本未提供自动化工具。
结论卡片
适合谁用：
- 专业摄影师与后期师：需要高质量 RAW 开发，支持主流相机格式，接受开源工具的迭代风险。
- Rust 开发者：对图像处理感兴趣，想学习或参与开源项目，代码质量高且架构清晰。
- 需要 AI 自动化后期流程的用户：通过 MCP 服务器与 AI 代理集成，实现批量处理与智能调整。
- 需要跨平台统一工作流的团队：桌面与浏览器共享管线实现，参数与效果一致。
不适合谁用：
- 需要完全稳定生产环境的商业工作室：项目年轻且快速迭代，功能与 API 可能变更。
- 依赖 Lightroom 特定插件生态的用户：LightCraft 为独立实现，不兼容 Lightroom 插件与预设格式。
值得关注的点：关注 ROADMAP 与 issue 跟踪最新进展，评估功能覆盖度是否满足实际需求。参与社区反馈可加速特定格式或功能的支持优先级。
