lightcraft

LightCraft

通过其结构化自动化接口操作 LightCraft，并使用用户指定的照片库和会话。

参考资料

在构造桌面调用前，请阅读 references/control-protocol.md 中的相关章节。这是于 2026-10-08 下载的未修改上游快照。

来源：LightCraft control protocol。上游 MIT 许可证包含在 references/LICENSE-MIT 中。

根据需要搜索 Methods、When the library can't be saved、When the library can't be opened 和 Headless rendering。相对链接以 https://github.com/storytold/lightcraft/blob/main/docs/ 为基准解析。

如需了解 MCP 工具架构、导入模式、开发控件、导出选项和一次性 CLI 语法，请按需查阅上游 MCP 文档。如果行为不符，请发现已安装的命令和工具架构；不要复用其他 ArtCraft 应用的参数。

选择会话

发现可用的 LightCraft 工具、已安装的可执行文件和现有会话。优先使用连接到指定会话的可用 MCP 连接。

• 对于用户正在运行的应用，请使用桌面控制或 lightcraft-cli mcp --connect 127.0.0.1:7980。可通过 lightcraft --control 7980 或 LIGHTCRAFT_CONTROL_PORT=7980 启动所需的桌面会话；根据环境调整可执行文件路径和端口。
• 对于独立照片处理，请使用 lightcraft-cli mcp [FILES/FOLDERS…]。默认采用无头模式，并运行单独的进程内会话。
• 对于需要持久保存的无头编辑，请添加 --library /absolute/path/library。一个库一次只能由一个程序打开；如果应用持有其目录锁，请连接到应用，而不是在无头模式下打开该文件夹。不要移除锁来绕过此限制。

未指定 --library 时，不要假定无头目录编辑会在会话之间保留。仅在用户要求演示或独立示例时使用 --demo。复用合适的会话；如果可执行文件或连接不可用，请报告。此技能不会安装 LightCraft 或配置 MCP 服务。

桌面传输

控制通道是原始的回环 TCP，不是 HTTP 或 MCP JSON-RPC，也没有身份验证；仅在需要时启用。发送 UTF-8 JSON 对象，每行一个对象，包含字符串 method、可选的 params 和互不重复的请求 ID。每个请求读取一条回复，匹配 ID，并在执行依赖操作前检查 ok：

{"id":1,"method":"ui.inspect","params":{}}
{"id":2,"method":"engine.commands","params":{}}

通过 engine.commands 发现引擎和 UI 命令 ID、参数文档及启用状态。使用 engine.execute {command, params}（别名 ui.menu.invoke）调用它们。MCP 使用 list_commands 和 run_command {command, params}、辅助工具，或以命令 ID 命名、将点替换为下划线的 cmd_ 工具。

请求会在帧间隔的 UI 线程上执行，超时时间为 60 秒。无效的 JSON 对象、无效的 UTF-8 和超过 4 MiB 的行都会关闭连接；最多服务 16 个连接。收到错误回复后重新连接。发生超时或丢失变更操作的回复后，请检查状态再重试；如果无法安全确认操作结果，请停止并报告不确定性。

检查和编辑照片

编辑前，请检查图库、当前视图／筛选条件、当前照片、所选内容和后台任务。桌面端使用 ui.inspect 以及发现的图库／照片命令；MCP 提供 query_photos、get_develop 等工具，以及 lightcraft://library 和 lightcraft://photo/active 等资源。

通过查询获取真实照片 ID，并使用 select_photos {ids, active?, mode?} 或发现的图库选择命令明确设置选择范围。带有 id 的工具会先将对应照片设为当前照片；不带 id 的工具则作用于当前照片。执行批量操作时，请使用文档中说明的 ids 参数，或明确选择目标照片，并在应用更改前确认操作范围。

使用 list_controls 或已安装的命令注册表，发现显影控件 ID、取值范围、默认值和当前值。使用 set_develop 的 values 参数设置单个控件，或使用 settings 参数进行局部深度合并。先读取当前设置，并保留无关的编辑。查询可用预设，而不要臆造预设 ID。MCP crop 使用归一化的 [x0,y0,x1,y1] 坐标和拉直角度；组合裁切与旋转前，请先读取其架构。

导入时，请保留用户期望的源文件处理方式。选择引用、复制或移动行为前，先读取导入架构。移动模式会移除已核实并已编入目录的源文件及其 XMP 旁车文件；撤销操作不会将它们移回。检查返回的已移动／保留结果和失败项，再报告完成情况。

精确编辑时，优先使用命令和辅助工具。进行桌面交互时，通过 ui.widgets 获取稳定的控件 ID；屏幕矩形以点为单位，而 ui.pointer 手势在细节视图中使用归一化图像坐标。布局更改后，请刷新控件。文本输入取决于焦点。滚动或捏合缩放前，请先移动指针到目标位置。view.navigate 支持适应／填充视图或百分比缩放，以及归一化的图像中心平移；请查阅参考文档了解限制。

持久化、导出与验证

持久化图库会在回复前记录更改日志。错误 saved in memory but not written to disk 表示编辑已完成，并已排队等待持久化。不要把它当作尚未发生更改而重复执行。检查 ui.inspect → unsaved 或 library.info → unsavedOps / unsavedError，在任务范围内解决存储问题，并确认队列已清空。仍有未保存操作时，不要退出，也不要声称编辑已安全保存。

如果图库无法打开，请检查 libraryProblem。临时会话不会写入任何内容；如果任务要求持久化编辑，请勿选择 Continue Without Saving。请重试、选择预期且可访问的图库，或报告阻塞问题，不要丢弃工作。

选择格式、尺寸、色彩空间、质量、位深或原始/DNG 输出之前，请先阅读导出架构。MCP 导出的默认长边为 3000 像素；如果需要裁剪后的原生分辨率，请使用 longEdge: 0。确认明确指定的 ID 和目标位置。渲染预览不等于导出交付物。

桌面端 app.export 使用 background: true 时会确认任务已排队。请轮询 ui.inspect → export，直到相关批次完成；检查其结果，并确认返回的文件存在且可读取。同样，在将异步操作视为完成之前，请检查导入/任务进度。对于状态不确定的导出，请先检查状态和输出，再重试。

验证显影设置和选择范围，然后查看渲染后的照片或屏幕截图，以评估曝光、色彩、裁剪和所需效果。桌面端 ui.render 会渲染照片；ui.screenshot 会等待渲染完成，并支持使用 headless: true 进行 CPU 截图，即使窗口被遮挡也可以。

若要独立获取 UI 快照，lightcraft-cli snapshot --library DIR --script tour.jsonl -o shot.png 可接受控制请求。该命令会开启独立会话，且必须遵守图库锁定规则。脚本请求失败不会阻止后续请求，但会使退出状态为非零；报告成功前，请检查所有回复和退出状态。快照脚本中的 ui.settle {timeoutMs?} 会等待渲染完成。请报告实际导出的路径，以及任何仍未解决的持久化错误或未完成的工作。