PhotoS v2.0.0 — GUI v2.0：拆包 + 活切换 + Library/Develop/Export/Tools 工作区

PhotoS v2.0.0 — GUI v2.0：拆包 + 活切换 + Library/Develop/Export/Tools 工作区

主题：给人用的 GUI 全面现代化——10k 行单文件拆为模块化包，语言/主题切换不再重建界面，Lightroom 式四模块工作区（图库/修图/导出/工具）。agent 面（CLI/REST/MCP/JSON 契约）零改动；from photo_s.gui import … 兼容面不变。

🆕 工作区（模块栏 + Cmd/Ctrl+1..4，活动模块持久化）

• 图库 Library：文件面板全宽（含缩略图 LRU 缓存）
• 修图 Develop：胶片条 + 大图预览（真实管线防抖渲染 ~0.5s、stale 丢弃、原图/效果切换）+ 常驻直方图与曝光/色温读数（analyze_image）+ 右栏调整工具（影调/曲线/调色/矫正/局部——就在预览旁边）
• 导出 Export：导出队列（勾选照片 + 体积合计 + 空态）+ 输出/水印/元数据/选项设置；与修图页共用同一组参数变量
• 工具 Tools：12 张工作流启动卡片（审查/去重/对比/画廊/联系表/筛选/校验/HDR/监视/重命名/预设/分析）

🆕 活切换（不再销毁重建）

• 语言：STRINGS 反向映射遍历器（同文多键多数表决），切换后滚动位置/折叠区状态保留
• 主题：调色板值重映射遍历器 + ttk 样式刷新；系统外观实时跟随（FocusIn + 30s 轮询），手动切换钉住选择直至重启

🆕 架构（photo_s/gui/ 包）

• gui.py（10k 行）拆为 app / theme / strings / widgets / workflows / state / bus 七模块；gui_widgets.py 兼容 shim
• UiBus 事件总线：12 处内联 worker→UI drain 循环统一（排空前查窗口存活，杜绝向已销毁控件派发）
• 13 个 Tk-free seam 函数独立成 workflows.py（无头可测）

🆕 平台与性能

• Linux 深色模式检测补齐（gsettings → kdeglobals）；Windows DPI per-monitor v2 逐级回落
• 缩略图 ThumbCache：256MB 字节上限 LRU（原先无上限 dict，大目录可吃数 GB）、线程安全
• 全部 ImageTk.PhotoImage 显式 master=（修复无窗口管理器/多解释器环境下的 pyimage 崩溃）

🔧 测试

• 新增 47 个测试（theme/state/活切换/工作区/导出队列/UiBus），全量 1202 绿
• GUI 测试 HOME+USERPROFILE 隔离不变量（Windows Path.home() 读 USERPROFILE 的坑）
• CI 新增 Linux xvfb GUI 实验 job（本轮已全绿，稳定后并入主矩阵）

⚠️ 说明

• 升级：pip install -U photo-s-tools；agent 集成（MCP/REST/SKILL）无需任何改动
• 设计方案与后续路线：docs/GUI_UPGRADE_PLAN.md；变更明细：docs/GUI_CHANGES.md §13

auto-tone plugin v0.1.0 — AI 自动调色（CLIP+MLP v7_clean + RAG）

photo-s-plugin-auto-tone 模型权重（资产名与插件 models.py 的 WEIGHTS 一致）。

⚠️ 许可：权重文件采用 CC-BY-NC 4.0（署名-非商用），代码为 MIT。
权重由 1295 张个人 Lightroom 修图记录训练（个人修图风格模型），
详见仓库 plugins/auto-tone/LICENSE-WEIGHTS.txt。

核心（必需，约 4.6MB）:

• auto_tone_v7_clean.pt — CLIP+MLP 主模型 (1295 LR samples, PSNR 29.10 / SSIM 0.9775)
• clip_train_rag.npz — RAG 检索增强训练集 embedding + targets
• hand_features.npz — 异常检测 hand features

可选（Qwen3-VL LoRA，约 400MB，基座 Qwen3-VL-2B 需自备）:

• lora_aesthetic.safetensors / lora_aesthetic_config.json — 美学评分 (Pearson 0.78)
• lora_advisor.safetensors / lora_advisor_config.json — 修图建议

上游依赖：OpenAI CLIP ViT-L-14 (MIT)、Qwen3-VL-2B (Apache-2.0)。
SHA256 固定在 plugins/auto-tone/photo_s_plugin_auto_tone/models.py。

PhotoS v1.8.0 — AI 识别蒙版 + 笔刷 + 组合算子（智能局部调整）

PhotoS v1.8.0 — AI 识别蒙版 + 笔刷 + 组合算子（智能局部调整）

主题：LR 式智能局部调整——AI 分割蒙版、笔刷绘制、组合算子、GUI 画布工作流，全部以紧凑字符串建模，CLI/REST/MCP/preset 零胶水传递。

🆕 AI 分割蒙版（photo_s/segmask.py）

• subject: U2Netp 显著性主体（4.6MB）
• person: PP-HumanSeg 人像（6.2MB）
• object:car YOLOv8n-seg 任意 COCO 80 类（fp16 7MB，含空格类名可达如 object:traffic light）
• 权重经 modelstore 下载 + sha256 校验缓存；OpenCV 5.x 新图引擎 forward 失败自动回退经典引擎
• 缺 cv2/权重抛清晰错误，绝不静默

🆕 笔刷 + 组合算子（v1.8 蒙版类型）

• 笔刷 brush:x,y,r|x,y,r（点间胶囊并集；负点 -x,y,r = 减模式）
• 组合算子 combo:A&B（交集）/ combo:A-B（差集），引用已命名蒙版并替换
• 所有类型支持 ,feather=/,invert（round-trip 保真）

🆕 复杂参数局部化

• mask_adjust 字符串键：curves/hsl/color_grading/vignette/grain（{} 包裹复用 grade.py，蒙版内与全局数值一致）

🆕 GUI LR 式画布蒙版工作流（"GUI for humans"）

• 勾选照片大图画布：多蒙版分色半透明叠加、笔刷/线性/径向/取色/AI 工具
• 拖拽蒙版移动、图层排序、A/B 加减模式、羽化滑杆 live、径向虚线范围圈、undo（50 层跨照片）
• ◀▶ 翻页 + per-photo 蒙版逐文件注入（batch_process(per_file_options=)）
• 调色对话框（曲线/色轮/HSL/点颜色）内嵌照片预览条实时渲染 + RAW 预览

🆕 LR 数据管线补全

• photo-s lr-merge 多机数据包合并（去重 + 图集 + 溯源）
• lr-scan --sanitize 脱敏导出（剥 EXIF，配 --images 直接可训）
• lr-predict 自动识别 CLIP+MLP npz（开箱即用）；输出键对齐 ProcessOptions 字段（REST/CLI 零映射）
• docs/TRAINING.md + tools/train_tone_torch.py 训练管线

🔧 发布前全面扫描修复（2 Critical + 10 Major + 33 Minor）

• mask_adjust 字符串键接线 grade 解析器（hsl/color_grading/vignette/grain 此前必崩）
• lr-predict exposure→ev 消费层别名（REST/MCP 静默丢弃修复）
• combo 循环引用/自引用 → 清晰报错；NaN/Inf 拒绝（静默黑图防护）
• per-photo 蒙版跨文件泄漏、feather/invert round-trip 断裂、GUI combo 保存崩溃等
• 1075 测试全绿

⚠️ 发布须知

• AI 分割权重已附于本 release（u2netp/pphumanseg/yolov8n-seg-fp16 三个 onnx，sha256 与代码 pin 一致）
• 安装：pip install "photo-s-tools[enhance]"（AI 蒙版需 opencv）

PhotoS v1.7.1 - AI 修图基础设施（lr-scan 训练包 + 工具层）

PhotoS v1.7.1 — AI 修图基础设施（阶段 1+2 全落地）

主题：agent 全自动修图的完整地基——感知/循环/验收工具层 + 个人 LR 修图数据训练管线。

🆕 数据层：个人 Lightroom 数据 → 完整训练包（一条命令）

• photo-s lr-scan：自动发现 .lrcat/.xmp（缺省扫 ~/Pictures+~/Desktop，零配置）→ 覆盖报告（参数使用频率/蒙版类型/工具轨迹/未映射缺口）+ --export-dir 训练 JSONL（每行 = path + PhotoS 参数）+ --render-dir rawpy 默认渲染 before 图（幂等）——其他电脑安装即产训练包
• photo-s lr-train / lr-predict：自动基调回归（岭回归，纯 numpy 零 torch，任何机器可训），9 项全局参数（曝光/对比/饱和/自然饱和/WB/清晰度/纹理/去雾），R² 报告
• photo-s lr-recipes：KMeans 编辑配方聚类 → 个人风格配方库（簇中心即 PhotoS options）
• photo-s lr-similar：84 维内容特征 kNN 相似修图检索（CLIP 升级路径文档化）
• photo-s lr-eval：教师评测集准备（before/after 渲染对，PhotoS 自渲染 after + 打分模板）
• photo-s batch --trace DIR：轨迹日志（before-analyze → params → after-analyze，训练数据格式）
• photo_s/lrxmp.py：LR 18 catalog 明文快照解析（s = { key = value }）+ XMP sidecar → ProcessOptions 映射（覆盖率 ~90%：WB/曝光/HSL/曲线/3路分级/几何蒙版+局部调整/点颜色）

🆕 工具层：agent 感知 + 循环 + 验收

• photo-s preview：视觉快照（缩放 JPEG base64 + 直方图 PNG）——多模态 agent 直接看图
• photo-s analyze --grid 4|8：区域反馈（逐格亮度/色偏 + 天空/肤色启发式分区 + 过曝/欠曝区域框）
• photo-s diff：版本数值对比（PSNR/SSIM/MAD）——before/after 判定
• photo-s audit：出片质量闸门（过曝/欠曝/模糊/亮度/对比/色温逐项 pass/fail + 原因）——agent 的终止条件
• MCP 异步批量：batch_start / batch_status / batch_cancel（目录级任务 + 轮询 + 取消）

🔌 契约

• MCP 工具 19 → 25（+preview/diff/audit/batch×3）；REST +/preview /diff /audit，/analyze 加 grid
• 全部新参数/输出 additive（schema_version 不变，=1）
• CLI 命令 23 → 32

测试

1022 tests green（+~35 新增：lrxmp 数据层/audit/grid/compare/snapshot/MCP 25 工具）

数据验证（本机实测）

• 6 个会话 catalog 5007 张解析 100% 通过；133 张已编辑 → 177 训练样本 → R²=0.184 线性基线
• 配方聚类直接给出摄影师风格签名：47% 轻手（-0.14EV）/ 35% 提亮（+0.34EV）/ 12% 压暗（-0.97EV）
• XMP 自动写入已开 → 8-3 新拍 46 张 sidecar 自动产出

PhotoS v1.7.0 - Local masks + lens correction + perceptual feedback

PhotoS v1.7.0 — Local adjustments (masks) + lens correction + perceptual feedback

主题：可序列化的局部调整 + 镜头矫正 + 多模态感知反馈闭环。

🆕 新功能

局部蒙版（photo_s/mask.py）

• 命名蒙版紧凑字符串：masks="sky:linear:0.5,0,0.5,1,feather=0.3; face:color:255,200,180,tol=0.15"
• 三类蒙版：线性渐变 / 径向椭圆（可反相）/ 颜色范围，相对坐标 0-1 → 同一 spec 批量适用全部文件
• 蒙版内局部调整：mask_adjust="sky:exposure=-0.7,vibrance=0.2"，11 项标量（曝光/亮度/对比度/饱和度/自然饱和度/清晰度/纹理/锐化/色温/tint/模糊）
• v1.8 语法预留：subject: / person: / object: / brush:（解析即报清晰错误，不静默）

点颜色（--point-color）

• 取样色中心软掩码："200,120,80:30,0.2,-0.1,0.2"，与 HSL 固定 8 色域互补

镜头矫正（photo_s/lens.py，纯 numpy 双线性）

• --lens-distort k1（桶形/枕形畸变）、--lens-vignette "0.3,0.4"（去暗角）、--lens-ca "0.999,1.001"（消色差）
• 管线几何先行：auto_rotate 后、一切像素调色前

感知分析 photo-s analyze（CLI / REST /analyze / MCP 第 19 个工具 analyze）

• 直方图（RGB+luma 32 桶）/ 通道均值/中位/σ / 对比度 / 饱和度 / 色温估计 / 曝光 / 模糊分
• 调色反馈闭环：analyze → 调参 → process → analyze（详见 AGENT_API §7）

GUI

• 调整 Tab 新增镜头矫正折叠区；点颜色对话框（取样色 + H/S/L/范围滑杆 + 多目标列表）；蒙版编辑器（三类蒙版表单 + 羽化/反相 + 11 项局部调整滑杆 + 红色叠加实时预览）

🔌 契约（Agent/LLM 相关）

• MCP 工具 18 → 19（analyze）；process 增 6 参数（masks/mask_adjust/point_color/lens_*）
• 全部新参数经紧凑字符串/标量建模 → REST/preset/MCP 零胶水继承
• analyze 统计输出即未来专有调色模型的训练数据基座

测试

991 tests green（+~67 新增：test_mask / test_lens / analyze / MCP/服务端/GUI roundtrip）

感谢

PhotoS 是开源项目（MIT），欢迎 issue / PR / star！

PhotoS v1.6.1 — Lightroom-style grading GUI + layout overhaul

PhotoS v1.6.1 — GUI 大增强（Lightroom 式调色编辑器 + 布局重构）

Patch 版：把 GUI 从"数字输入"升级为 Lightroom 式交互控件，并重排整体布局。

✨ Lightroom 式调色编辑器（GUI）

• 可拖拽点曲线：RGB 主曲线 + R/G/B 分通道 tab；单击曲线加点并立即拖动、右键删点、固定端点、"复位"按钮
• 真色轮（3 轮）：阴影 / 中间调 / 高光 各一个 HSV 色轮（点击/拖拽选色相+强度）+ 每轮亮度条
• HSL 分色编辑器：8 色域色块 + 色相/饱和/明度滑块
• 引擎配套：color_grading 支持每区亮度 zone:hue,sat,lum；全部写回同一 StringVar，REST/preset/MCP 往返不变

🎨 GUI 布局重构

• 设置面板分类 Tab：输出 / 调整 / 效果 / 元数据 / 选项 5 页，每页独立滚动 + 区块可折叠（▾/▸）
• 工具栏分组：文件管理 │ 工作流 │ 撤销/更多 组间分隔线；分析/清空移入"更多工具"菜单；破坏性操作红色描边

📊 其它 GUI 优化

• 文件列表缩略图（缓存 + 异步懒加载 + 小/中/大切换，RAW 半尺寸解码）
• 布局记忆：窗口大小 + 缩略图尺寸持久化（~/.photos/gui_state.json）
• 文件过滤框：按文件名/扩展名筛选
• 处理进度 ETA：剩余时间估算
• 重做（⌘⇧Z / Ctrl+Shift+Z）+ 撤销扩展

🐛 修复

• LUT 后 EXIF 丢失 / 3D LUT 丢 alpha / MCP process 缺调色参数（v1.6.0 起）
• Windows CI：缩略图异步化（渲染轮询不再被拖垮）、测试 display/pyimage 健壮性

依赖：不变（Pillow ≥10.4 · rawpy ≥0.18 · numpy）。测试 924 全绿（CI 7 job 含 Windows 真 Tk）。

pip install photo-s-tools
photo-s   # 打开 GUI 体验 Lightroom 式调色

PhotoS v1.6.0 — Lightroom-direction grading

PhotoS v1.6.0 — Lightroom 方向调色（专业调色）

Minor 版：给批量/交付管线补上 Lightroom 方向的核心调色能力（源自 LensPilot 商业软件
的功能摸底），全部为纯 numpy/PIL 单图全局算法，零新依赖。

✨ 新增：LR 方向调色（photo_s/grade.py，11 个算法）

P0 核心旋钮（CLI 11 个新 flag，GUI/MCP/REST 同步接入）：

• 点曲线 --curves "0,0;128,140;255,255" — PCHIP 单调样条（绝不超调），支持 rgb/r/g/b 分通道
• 手动色阶 --levels "80,200,1.1" — 黑/白场 + 中间调伽马三点重映射
• 自然饱和度 --vibrance 0.5 — 按当前饱和度反向加权，保护肤色/深色
• 三向颜色分级 --color-grading "shadows:120,0.3;highlights:-10,0.2" — 阴影/中间调/高光，平滑亮度掩膜无断层
• WB tint 轴 --wb-tint 20 — 现有 Kelvin 冷暖轴加绿/品红 G-M 轴

P1 风格化：

• HSL 分色 --hsl "green:10,0.2,0.1" — 8 色域 × 色相/饱和/亮度偏移，高斯软过渡
• 清晰度/纹理 --clarity / --texture — 亮度通道 USM 局部对比（大/小半径）
• 去雾 --dehaze — 暗通道先验（批量级，无 opencv 依赖；负数加雾）
• 暗角 --vignette "0.5,0.4,0.4" — 径向渐变掩膜
• 颗粒 --grain "0.15,1.5" — 亮度加权胶片噪点

四层接线：CLI 11 flag（compress/convert/batch/preset 共享）· REST _scalar_groups 自动继承 ·
MCP process 33 参数 · GUI「调色（LR 方向）」设置区块（11 控件）。管线插入 exposure 后 / denoise 前
（LR 参考顺序），现有 tone/LUT 原位保留，向后兼容。

🐛 Bug 修复

• LUT 后 EXIF 丢失：apply_lut 1D/3D 路径统一保留 img.info（此前 --lut 交付图丢版权/拍摄参数）
• 3D LUT 丢 RGBA alpha：3D 路径补 alpha 拆/挂
• MCP process schema 缺调色参数：补 lut_file/brightness/contrast/saturation + 全部新调色字段

📈 其它

• ProcessOptions 64 → 75 字段；测试 834 → 899 全绿（CI 7 job 含 Windows Tk + SCUNet 真推理）
• 所有新算法保留 img.info（EXIF/ICC/DPI）与 alpha，交付图元数据不丢

依赖：不变（Pillow ≥10.4 · rawpy ≥0.18 · numpy）。可选 extras 不变。

pip install photo-s-tools
photo-s batch 'RAW/*.ARW' --curves "0,0;128,140;255,255" --vibrance 0.4 --format jpeg -o out/ -q 90

PhotoS v1.5.1 — Agent 接入便利化（SKILL.md + Claude Code 文档）

PhotoS v1.5.1 — Agent 接入便利化（SKILL.md + Claude Code 文档）

Patch 版：把 PhotoS 打包成现成 skill、补全 Claude Code 的 MCP 连接文档，并修正 README 工具数。

📦 现成 Agent Skill（新）

• 新增 skills/photo-s/SKILL.md：打包好的 Claude Code skill——子命令→任务映射表、--json/schema_version 契约、安全规则（不隐式覆盖输入、dry-run 优先）、4 个典型工作流示例
• 安装即用：mkdir -p ~/.claude/skills && cp -r skills/photo-s ~/.claude/skills/
• 只需核心包（py3.9+），不需要 py3.10+ / [mcp] extra
• 全部命令与 flag 经机器验证与 CLI help 逐一对齐

🔌 Claude Code MCP 连接文档（补全）

• docs/AGENT_API.md §6 新增 claude mcp add 三种接法（用户级 / 项目级 / uvx 零安装变体）+ claude mcp list 验证
• 注明 Cursor / Cline / Windsurf 等客户端填同一 mcpServers 条目即可

🛠 文档修正

• README（en/zh）：MCP 工具数 15 → 18（v1.5.0 发布时的漏网），工具列表补全 select/hdr/blurfaces/bench/watch×3
• 新增「5. Agent skill」安装段；CLAUDE.md 集成方式段同步

依赖：不变（Pillow ≥10.4 · rawpy ≥0.18 · numpy）。可选 extras 不变。

pip install photo-s-tools          # 核心
pip install photo-s-tools[enhance] # + opencv（HDR/人脸模糊/降噪/扶正）
pip install photo-s-tools[mcp]     # + MCP server（py3.10+）

PhotoS v1.5.0 — i18n + Agent contract + photographer workflows

PhotoS v1.5.0 — 国际化 + Agent 契约 + 摄影师批处理工作流

合并版本：i18n、JSON 契约版本化、server 安全加固、审计遗留修复 + 6 项摄影师工作流（选片/HDR/人脸模糊/预设套用/批量 GPS/统一比例裁剪）。MCP 工具 11 → 18，CLI 子命令 19 → 22，834 测试全绿。

🌍 国际化（i18n）

• CLI --language {en,zh,auto} 全局 flag，help + 全部运行时消息单一语言
• 三平台系统语言自动检测（macOS AppleLanguages / Windows LCID / Linux LANG）
• GUI 启动自动检测 + 用户选择持久化（~/.photos/language）
• --json 输出键永远英文（agent 契约不受语言影响）

🤖 Agent 契约版本化 + server 加固

• 新 photo_s/contract.py：所有 JSON 输出（CLI --json / REST / MCP）带加性顶层 schema_version 键——消费者可安全忽略未知键，breaking 才递增
• server：ready-file 0600 权限、DNS-rebinding Host 白名单、1MB 请求体上限（413）
• MCP 4 个新工具（上一轮）：bench（实测并发加速比）、watch/watch_status/watch_stop（后台目录监视）、process evaluate（SSIM 质量评估）

📷 摄影师批处理工作流（原 v1.6.0 合并）

• 选片 select：按 EXIF 评分双阈值分拣——≥4 星移精选目录、≤2 星移淘汰目录、3 星/未评分原地；--copy/--dry-run；GUI 评审灯箱一键「移动精选/淘汰」
• HDR hdr：包围曝光曝光融合（opencv MergeMertens，无需 EV 数据），--align AlignMTB 手持对齐消鬼影
• 人脸模糊 blurfaces：Haar cascade 人脸检测 + 高斯模糊/马赛克隐私打码；--blur-faces blur|pixelate 也可进批量管线与其他处理一次完成
• 预设一键套用：preset save 捕获完整选项集；batch/compress/convert --preset NAME（显式 CLI 参数优先）
• 批量 EXIF GPS：exif --gps "lat,lon" --make --model 一键批量写坐标/相机信息
• 统一比例裁剪：--crop-ratio 16:9 居中按比例裁剪（回归测试锁定）

🔧 其他

• rename 撞名修复：photo_1_2.jpg 复后缀 bug → 干净计数 photo_2.jpg
• v1.3.2 审计遗留 3 项：插件安装核心版本检查、真 TLS（PHOTO_S_TLS）、GUI 预览 drain 守卫
• CI 修复：locale 固定的中文文案测试、Windows 真实 Tk 慢 CI 超时放宽、bench 时钟分辨率

依赖：Pillow ≥10.4 · rawpy ≥0.18（核心）· numpy。可选 extras：[enhance]（opencv：降噪/扶正/HDR/人脸模糊）、[mcp]（py3.10+）、[watch]、[exif]、[heic]、[avif]、[gui]。

pip install photo-s-tools          # 核心
pip install photo-s-tools[enhance] # + opencv（HDR/人脸模糊/降噪/扶正）
pip install photo-s-tools[mcp]     # + MCP server（py3.10+）

PhotoS v1.4.2

PhotoS v1.4.2 — MCP 修复 + 文档清扫

修复

• MCP serverInfo 版本号：握手时误报 mcp SDK 版本（如 1.29.0），现正确报告 PhotoS 版本（FastMCP 在 mcp≥1.20 无 version 参数，直接写底层 server）
• py3.9 兼容：photo-s-tools[mcp] extra 增加 python_version >= '3.10' marker，老 Python 上干净跳过而非解析器报错

文档

• README（中/英）+ AGENT_API：MCP 工具数从 v1.3.0 遗留的 "7" 更正为 11，补齐 contact_sheet / gallery / watermark / preset 四个工具的文档与参数表
• 新增 uvx 零安装客户端配置（与官方 MCP Registry 发布的调用一致）：

  { "mcpServers": { "photo-s": { "command": "uvx", "args": ["--from", "photo-s-tools[mcp]", "photo-s", "mcp"] } } }

分发

• 已上架官方 MCP Registry：io.github.Dongwu259/photo-s
• 测试 727 全绿（py3.9-3.12 + Windows 真实 Tk + SCUNet 真推理 CI）

安装：pip install -U photo-s-tools