drshy-org/lightroom-py

lightroom-py

用 Python 和 Claude 驱动 Adobe Lightroom Classic。 首个开放的智能体驱动程序，具备经过验证的程序化蒙版创建能力（已确认 35.4% 像素差异），并记录了其他地方被认为不可能实现的 AI 蒙版计算路径。

Python 3.10+
License: MIT
LR Classic 15.3 verified
Tests

62 个桥接处理器 · 80 个 CLI 动词 · 101 项测试 · 7 次以上真实 LR 验证会话记录于 CHANGELOG.md。 非官方，MIT 许可，与 Adobe 无关联。

安装 — 3 个用户操作

pip install lightroom-py            # 1. 安装
lightroom setup                     # 2. 一条命令：插件 + LaunchAgent + 技能
3. 在 LR 中：Plug-in Manager → 启用
"lightroom-py bridge"（约 10 秒，一次性）

lightroom setup 会将 LR 插件安装到 ~/Library/Application Support/Adobe/Lightroom/Modules/，在 ~/.lightroom/profiles/default/bridge.json 生成桥接令牌，注册一个 macOS LaunchAgent 以在登录时自动启动桥接服务器（无需终端），并安装 Claude 智能体技能。令牌会自动加载到 LR 的插件中——无需手动粘贴。

使用 lightroom doctor 进行验证。

安装变体 + macOS TCC 注意事项 + Windows 说明

变体
| 需求 | 命令 |
|---|---|
| 默认（CLI + Python 库） | pip install lightroom-py |
| 带 Claude Desktop MCP 服务器 | pip install "lightroom-py[mcp]" |
| 带 ExifTool 快速路径用于 XMP | pip install "lightroom-py[exiftool]" |
| 全部（mcp + exiftool + dev） | pip install "lightroom-py[all]" |

macOS TCC 保护的 venv
macOS 上的 LaunchAgent 在没有完全磁盘访问权限的情况下无法读取 ~/Documents、~/Desktop、~/Downloads、~/Pictures、~/Movies、~/Music 下的文件。请将你的 venv 安装在这些目录之外：

python3 -m venv ~/.lightroom/venv
~/.lightroom/venv/bin/pip install lightroom-py
~/.lightroom/venv/bin/lightroom setup

lightroom setup 和 bridge install-service 会检测受保护的路径，并在静默失败之前拒绝执行并提供变通说明。

Windows
手动启动桥接（尚无 LaunchAgent 等效方案）：

pip install lightroom-py
lightroom bridge install
lightroom bridge start         # 保持运行
然后在 LR 中：Plug-in Manager → 启用

你可以做什么

| 界面 | 动词 |
|---|---|
| 目录 | catalog open / info / stats — 照片 / 文件夹 / 关键字 / 收藏集的计数 |
| 照片 | photos list / count / find-by-path — 按评分、相机、镜头、关键词、日期、色标、文件格式、ISO、光圈、焦距、GPS 筛选；SQLite 读取快速路径（50k+ 目录即时返回） |
| 选择 + 导航 | select、select-all/none/inverse/extend、next、previous |
| 旗标 + 评分 | flag-pick/reject/clear、rate-up/rate-down、color-cycle |
| 元数据 | add-keywords（层级式 "People\|Family\|Mom"）、rate、color、set-iptc（caption/title/headline/copyright/creator/city/state/country） |
| XMP | metadata write-xmp / read-xmp + ExifTool 快速路径 |
| 修改照片 — 全局 | apply-preset、apply-settings、paste-settings --subset、get-settings、copy、reset、实时 set |
| 修改照片 — 分类 | crop、hsl、color-grade、transform、lens-correction、calibration、detail、effects |
| 修改照片 — 色调曲线 | curve get/set/preset/linear/s-curve — RGB + 各通道 |
| 修改照片 — 快照 | snapshot create/list — 代理编辑前的安全检查点 |
| 修改照片 — 过程版本 | process-version get/set |
| 修改照片 — 定向重置 | reset-crop / -masking / -spot / -redeye / -transforms |
| 蒙版 — 读取 + 清除 | mask list / clear（统一 MaskGroupBasedCorrections 架构，LR 15.3+） |
| 蒙版 — 创建 ⭐ | mask create-radial（端到端验证）+ create-linear（尽力而为），每个蒙版支持 20+ 个 Local* 调整 |
| AI 蒙版计算 ⭐ | apply-preset --folder "Adaptive: Subject" + library export → LR 的“需要 AI 更新”对话框 → 单击一次 → 蒙版渲染（已验证 20.91% 像素差异） |
| 收藏夹 | list / create / add / remove / delete / get-photos — 普通 + 智能 |
| 图库 | list-folders、export（JPEG/TIFF/PSD/DNG，支持水印、输出锐化、调整大小、DPI、文件名模板、最小化元数据）、make-virtual-copy、stack |
| 编辑方式 | export 到磁盘，run 用于完整往返（导出 → 外部工具 → 作为堆叠重新导入） |
| 开发工具 | bridge reload（无需重启 LR 即可热重载 Lua 处理器）、bridge eval（任意 Lua）、bridge tail-log |
| 服务管理（macOS） | bridge install-service / uninstall-service / service-status |

无法实现的功能（Adobe SDK 缺口，已记录）

| 功能面 | 原因 |
|---|---|
| AI 降噪计算 | LR 未公开 Enhance → Denoise… 的触发接口。设置阶段参数，由用户点击 Enhance。 |
| 画笔蒙版创建 | Mask/Paint 架构（Dabs: 描边数组）尚未探测。v0.6 可使用径向蒙版作为变通方案。 |
| 污点去除创建 | 在 LR 15.3 中未公开。 |
| 照片删除 | cat:trashPhotos 在 15.3 中不存在。 |
| 虚拟副本删除 | 仅支持创建。 |
| Lightroom Cloud（LR CC） | 受 Partner-API 限制；我们面向 LR Classic。 |

命令速查表

完整参考：docs/cli-reference.md。以下是最常见的 20 种模式：

=== 设置 + 健康检查 ===
lightroom setup                                              # 一次性：插件 + 服务 + 技能
lightroom doctor                                             # 诊断安装 + 桥接状态
lightroom bridge ping                                        # 往返测试

=== 目录 + 筛选 ===
lightroom catalog open ~/Pictures/Lightroom/MyCatalog.lrcat
lightroom photos list --rating ">=4" --iso ">=400" --since 2026-01-01 --json
lightroom photos count --keyword wedding
lightroom photos select-all
lightroom photos flag-pick --selection
lightroom photos rate-up --selection                         # 循环 +1 星

=== 元数据 ===
lightroom metadata add-keywords "wedding,bride,People|Family|Mom" --selection
lightroom metadata rate 5 --selection
lightroom metadata set-iptc -f caption="Sunset" -f city="Paris" --selection

=== 全局显影 ===
lightroom develop list-presets
lightroom develop apply-preset "Pop" --folder "Adaptive: Subject" --selection
lightroom develop apply-settings '{"Exposure2012":0.5,"Contrast2012":20}' --selection
lightroom develop hsl --saturation orange=10 --luminance blue=15 --selection
lightroom develop color-grade --shadow-hue 215 --shadow-sat 20 \
--highlight-hue 30 --highlight-sat 25 --selection
lightroom develop curve preset "Medium Contrast" --selection

=== ⭐ 几何蒙版创建（v0.6，已验证） ===
lightroom develop mask create-radial --left 0.05 --right 0.5 \
--top 0.4 --bottom 0.95 --exposure 1.0 \
--name "subject-brighten" --selection
lightroom develop mask create-radial --top 0.15 --bottom 0.85 \
--left 0.15 --right 0.85 --invert --exposure -1.0 --feather 70 --selection
↑ 暗角式压暗（invert = 效果作用于椭圆外部）

=== 安全 + 实验 ===
lightroom develop snapshot create "Pre-agent-edit" --selection
lightroom develop mask list --selection                      # 查看照片上有哪些蒙版
lightroom develop mask clear --kind all --selection          # 清除所有蒙版
lightroom develop reset --selection                          # 完全重置

=== 生产导出 ===
lightroom library export ~/Desktop/finals --selection --format JPEG \
--quality 88 --resize-long-edge 1920 --sharpening standard --dpi 96

=== 外部工具往返 ===
lightroom edit-in run "magick {input} -auto-level {output}" --selection

三种使用方式

1. CLI

lightroom photos list --rating ">=4" --iso ">=400" --json
lightroom develop apply-preset "Pop" --folder "Adaptive: Subject" --selection
lightroom develop mask create-radial --left 0.05 --right 0.5 --top 0.4 --bottom 0.95 \
--exposure 1.0 --selection                          # ⭐ 已验证渲染
lightroom library export ~/finals --selection --format JPEG \
--resize-long-edge 1920 --sharpening standard --dpi 96

2. Python API

import asyncio
from lightroom import LightroomClient

async def main():
async with LightroomClient.connect() as lr:
await lr.catalog.open("~/Pictures/Lightroom/MyCatalog.lrcat")
keepers = await lr.photos.list(rating_gte=4, iso_gte=400, since="2026-01-01")
for p in keepers:
await lr.develop.apply_preset("Pop", folder="Adaptive: Subject", photo_uuids=[p.uuid])
await lr.develop.mask_create_radial(
left=0.05, right=0.5, top=0.4, bottom=0.95,
exposure=1.0, photo_uuids=[p.uuid],
)

asyncio.run(main())

完整的异步子客户端参考：docs/python-api.md。

3. Claude / agent 技能

该软件包附带一个规范的 SKILL.md，可通过 lightroom skill install 安装（lightroom setup 也会自动完成安装）。它会在 /lightroom 或类似“筛选这些照片”、“将我的暖色预设应用到所选内容”、“将五星照片导出为 JPEG”这样的意图时激活。

对于 Claude Desktop 的 MCP 集成：pip install "lightroom-py[mcp]" + 将 Claude Desktop 的配置指向捆绑的 lightroom-mcp 二进制文件。参见 docs/mcp.md。

4. DeepSeek Harness (dsh)

本仓库同时也是一个 DeepSeek Harness 插件包（根目录下的 package.json + cordis.patch.yml —— 纯配置，无需构建步骤）：

pip install "lightroom-py[mcp]"                        # the MCP server (0.6.1+; on 0.6.0 add "mcp drshy. (2026). lightroom-py: A Python and Claude agent driver for Adobe Lightroom Classic (v0.6.0) [Software]. Retrieved from https://github.com/drshy-org/lightroom-py — http://www.drshy.xyz

BibTeX：
bibtex
@software{drshy_lightroom_py_2026,
author       = {drshy},
title        = {{lightroom-py}: {A} {Python} and {Claude} agent driver for {Adobe} {Lightroom} {Classic}},
url          = {https://github.com/drshy-org/lightroom-py},
version      = {0.6.0},
date         = {2026-05-10},
note         = {作者主页：\url{http://www.drshy.xyz}}
}

如果您的作品使用了本项目中的某项具体实证结果（已验证的几何蒙版创建像素差异、AI 蒙版计算路径、LR Classic 15.3 沙盒陷阱目录），请链接到相关的 CHANGELOG.md 版本条目，以便读者找到原始证据。

许可证

MIT — 参见 LICENSE。可自由使用；不提供担保；与 Adobe 无关联。