photo_s: Instructions file for Claude Code

PhotoS — 项目约定（Claude Code 工作指引）

批量照片处理工具箱：CLI + Tkinter GUI + REST API + 插件系统。定位 "CLI for AI agents, GUI for humans"。

命名约定（禁止"统一"）

同一上下文内不得混用。README 有详细说明。

架构速览

• engine.py — ProcessOptions dataclass + process_image + batch_process（核心，含 per_file_options(path, opts) 钩子——GUI per-photo 蒙版经此逐文件注入，在输出路径预分配前调用）
• cli.py — argparse，子命令：compress/convert/batch/exif/preset/watch/dedup/info/rename/config/serve/mcp/check/contact-sheet/cull/select/hdr/blurfaces/hash/gallery/bench/plugin/lens-profile（含 plugin scaffold）/analyze/lr-scan/lr-train/lr-predict/lr-recipes/lr-similar/lr-eval/lr-merge/diff/audit/preview；--language {en,zh,auto} 全局 flag（_pre_parse_language 两段式解析：先 resolve 语言再建 parser，argparse 构造时定死 help 文本）
• contract.py — JSON 输出契约：SCHEMA_VERSION = 1 + versioned(payload)（加性顶层键 schema_version，非信封）；CLI --json/REST _send_json/MCP 工具三处复用，零项目 import
• i18n.py — 国际化共享模块：detect_system_language()（三平台：env LANG/LC_ALL → macOS defaults read -g AppleLanguages → Windows GetUserDefaultUILanguage LCID → locale.getlocale()，每级 try/except 永不崩，_system_language() 记忆化）；resolve_language() 优先级 flag > PHOTO_S_LANG env > config language > persisted(GUI) > 系统检测 > "en"；CURRENT_LANG 模块变量 + _t(key, lang, **kwargs)（.format 只允许命名占位符）；CLI STRINGS 表（zh/en parity 测试强制）；GUI 持久化 ~/.photos/language。注意：检测层绝不调 locale.setlocale（进程级副作用会污染后续 open() 默认编码）
• gui/（v2.0.0 拆包，原 10k 行单文件 gui.py）：app.py（PhotoSApp 主体 + run_gui；v2.0 工作区：模块栏 Library 图库/Develop 修图/Export 导出/Tools 工具四模块，MODULES 常量 + _show_module 纯 pack 切换（四帧启动时全建、切换不销毁，Cmd/Ctrl+1..4 快捷键，活动模块持久化 gui_state.json module 键）；Library=文件面板全宽、Export=导出队列（_build_export_queue/_refresh_export_queue：勾选照片行 + 体积合计 + 空态，勾选状态在 Library 管理）+ 输出设置 Notebook（输出/水印/元数据/选项 4 Tab，_build_settings_panel(parent, develop_parent) 的 parent 侧；选项 Tab 含 v2.1.0 sec_cutout 抠图区块：cutout_mode 存本地化标签 + _on_cutout_mode_changed 动态显隐 object/color 参数帧，_cutout_spec() 正向/逆解析）、Tools=12 张工作流启动卡片（TOOLS_CARDS 表，仍打开既有对话框——逐工具非模态化是后续批）；Develop 面板（_build_develop_panel + _dev_* 家族：右栏 = 直方图卡 + 调整设置区（_dev_settings_host，_build_settings_panel 的 develop_parent 侧——调整 Tab 独立滚动区、无 Notebook；两页共用同一组 tk.Variable，Develop 拉杆即时驱动预览与导出管线）、胶片条（_dev_refresh_filmstrip 挂在 _refresh_file_list 尾部，files 签名比对去重，缩略图经 _dev_img_cache 64MB LRU + 工作线程解码）+ 大图预览（_dev_tick 160ms 防抖轮询：options 签名稳定 3 tick 后经 workflows.preview_render 真管线渲染，stale 签名丢弃，tempdir 注册进 _preview_tempdirs 统一清理）+ before/after 切换（_dev_show_before BooleanVar）+ 常驻直方图/曝光读数（metrics.analyze_image，luma 柱 + RGB 折线，数据色为字面量不进 palette）；13 个 seam 方法 _cull_scan 等薄委托 workflows 同名无下划线函数，签名不变）、theme.py（调色板/字体/SPACING·RADIUS token + _system_dark_mode 三平台检测（Linux: gsettings color-scheme → kdeglobals，v2.0 补齐）+ apply_dpi_awareness（Windows PMv2→PM→system-aware 逐级回落，__init__ 调用）；零 tkinter import，headless 可测）、strings.py（STRINGS zh/en + DEFAULT_LANG；不叫 gui/i18n.py 是为了避免与 from . import i18n（photo_s.i18n）在包内相对导入歧义）、widgets/（flatbutton=FlatButton / editors=CurveEditor·ColorWheel·HSLPanel（原 gui_widgets.py）/ util=_open_image_safe 等 / zoompan=_ZoomPanState）、workflows.py（Tk-free seam：gallery_build/preview_render/preview_options(opts,tempdir)/contact_sheet_build/cull_scan/hash_generate/hash_verify/hdr_merge/dedup_scan/dedup_trash_path/dedup_move_to_trash/review_scan/select_move）、bus.py（UiBus：worker→UI 事件总线，固化 queue+after-drain 约定；schedule(fn) 任意线程安全调用、start() 挂 80ms drain、窗口销毁自动停、drain_pending() 供 preview 防抖混合轮询——新对话框一律用 UiBus，禁止手写 drain 循环；preview 的 poll+drain 混合循环是唯一文档化例外）、state.py（~/.photos/gui_state.json load_state/save_state + ThumbCache：字节上限 LRU 缩略图缓存（默认 256MB、线程安全、False=失败标记、dict 风格 API））。活切换（v2.0 第二批）：_set_language/_toggle_theme 不再销毁重建——语言走 _translation_remap 反向映射遍历器（旧语言文本→新语言文本，同文多键时多数表决、平票丢弃；动态标签由属主重算：_refresh_file_list/_on_mode_change/_update_count_label/_update_stats），主题走 _recolor_widgets 调色板值重映射遍历器（旧值→新值，palette 外的颜色不动；FlatButton 的 hover_bg/border 一并重映射；ttk 走 _configure_ttk_styles）；两者仍经 WM 协议关闭对话框（测试契约）；系统外观跟随：FocusIn + 30s 轮询 _recheck_system_theme，手动 toggle 置 _theme_user_override=True 钉住选择直至重启。兼容面（不改测试/插件）：photo_s/gui_widgets.py 已是 shim；gui/__init__.py 重导出全部旧名（含 filedialog/messagebox/tempfile/threading——测试 monkeypatch 打在 stdlib 模块属性上，全局共享故拆分后仍生效）；lite spec excludes 显式列出全部 gui 子模块；相对导入注意：包内引用 photo_s 兄弟模块用 ..x（widgets/ 下用 ...x，深度不同！）。工作流对话框（审查灯箱/去重/画廊导出/蒙版画布/预览）与线程约定（worker 只 queue.put，UI 主线程 after-drain）不变，仍在 app.py
• 其他模块：adjust（调色/构图/白平衡/曝光/自动色阶）、grade（v1.6.0 LR 方向调色：点曲线 PCHIP/手动色阶/自然饱和度/三向颜色分级/WB tint/HSL 分色/清晰度·纹理/去雾/暗角/颗粒 + v1.9 apply_export_sharpen 导出锐化（输出级 USM，半径 0.5+max_dim/4000 随分辨率缩放）+ apply_highlight_recovery 高光恢复（200 起阈值幂曲线压缩硬切高光，单调、中间调不动），纯 numpy+PIL 零依赖，紧凑字符串建模 → REST/preset 零胶水）、mask（v1.8.0 命名蒙版：linear/radial/color 相对坐标 0-1 + AI 分割（subject/person/object:label → segmask，cv2.dnn 惰性）+ 笔刷（brush:x,y,r|x,y,r 点间胶囊并集）+ 组合算子（combo:A&B / combo:A-B，引用已命名蒙版并替换，render_mask 需传 refs）+ mask_adjust 蒙版内调整（11 项标量 + curves/hsl/color_grading/vignette/grain 复杂字符串 {} 包裹复用 grade.py），MaskError 清晰报错）、segmask（v1.8.0：U2Netp 4.6MB subject / PP-HumanSeg 6.2MB person / YOLOv8n-seg fp16 7MB object:label COCO 80 类，ONNX 经 modelstore 下载+sha256 校验，纯 numpy YOLO mask 解码+NMS，OpenCV 5.x 新引擎 forward 失败自动回退经典引擎，缺 cv2/权重抛清晰 RuntimeError 不静默；发布时三个 onnx 上传 GitHub release v1.8.0 附件）、lens（v1.7.0 手动镜头矫正：畸变 k1/去暗角/消 CA，纯 numpy 双线性重映射，LensError）、lensprofile（v1.9.0 用户维护的镜头档案库 ~/.photos/lens_profiles.json：save/list/delete + --lens-profile NAME 在 process_image 开头解析进 lens_distort/vignette/ca，显式参数优先、未知档案 per-file 报错；不内置编造镜头数据）、cutout（v2.1.0 抠图/背景移除：cutout 紧凑 spec subject|person|object:label|color:R,G,B[,tol=30][,feather=0][,invert]；AI 三种委托 mask.render_mask（复用 segmask 缓存/线程锁/MaskError 包装），color 为硬阈值 RGB 欧氏距离 + 绝对像素羽化（与 mask.py 颜色高斯语义刻意不同）；apply_cutout 蒙版→alpha（替换源 alpha，info 保留）；管线槽位在 export_sharpen 后、EXIF 提取前；JPEG+cutout per-file 报错（不静默拍平白底）；CutoutError(ValueError) 契约）、lrxmp（v1.7.1 LR 数据桥接（阶段 1/2，v1.9.0 AI 修图的数据底座）：parse_xmp_sidecar / parse_develop_blob（s = { key = value } 明文快照）/ scan_catalog（只读 lrcat，关联链 settings→Adobe_images→AgLibraryFile→folder→root 已验证）/ crs_to_options（→ ProcessOptions）+ coverage（映射分类）/ render_before_images（rawpy 默认显影训练图）/ train_auto_tone·predict_auto_tone（岭回归 9 项全局参数纯 numpy，predict 自动识别 CLIP+MLP npz 分支——torch/open_clip 惰性导入、新旧权重转置兼容、缺依赖清晰 LrError；输出键对齐 ProcessOptions 字段，REST/CLI 零映射）/ cluster_recipes（KMeans 配方库）/ similar_photos（84 维内容特征 kNN）/ prep_eval_set（教师评测集，PhotoS 自渲染 after），纯 stdlib）、audit（出片质量闸门：pass/fail + 原因，agent 终止条件，复用 metrics）、logcurve（LOG 还原 1D LUT，纯 math）、denoise（NLM，可选 opencv）、straighten（扶正，可选 opencv）、hdr（包围曝光合并：opencv MergeMertens 曝光融合，align 用 AlignMTB，可选 opencv）、faceblur（人脸检测 + 模糊/马赛克，opencv Haar cascade，可选 opencv，cascade 缺失抛清晰 RuntimeError 不静默）、metrics（SSIM/PSNR/blur/曝光统计 + v1.7 analyze_image 感知分析：直方图/通道统计/色温估计 + v1.7.1 grid 区域反馈/天空肤色启发式/过曝区域框 + compare_images(diff) + snapshot_image(preview base64)，CLI/REST/MCP 三处共享）、bench（基准：输出写临时目录自动清理、_StageTimer 分段计时、--evaluate PSNR/SSIM）、rename、dedup（含 keep-sharpest）、select（选片工作流：rating≥keep_min 移精选目录、≤reject_max 移淘汰目录、其余原地；双阈值 + move/copy + dry_run 零写入 + basename 平铺防穿越，CLI/GUI/MCP 共享）、watcher（start_watching 支持 stop_event，GUI 可停止）、cull（曝光/清晰度筛选，CLI/GUI/REST 共享）、presets、plugin（插件发现 + find_provider）、plugincmd（plugin 子命令：install/list/info/fetch，shell 到 pip）、registry（官方插件目录）、modelstore（权重下载/校验/缓存，仅 stdlib）、hooks（PhotoSPlugin 接口：过滤器钩子 + operation provider）、config（TOML）、server（stdlib HTTP）、contact（联系表）、check（完整性/校验和清单 + collect_files）、gallery（HTML 画廊）、lut（.cube 3D/1D LUT 解析 + numpy 三线性，LutError）、envinfo（环境探测，info/MCP/GUI 三处共享）、mcp_server（MCP server，26 工具：process/info/exif/dedup/cull/select/hdr/blurfaces/hash/plugin/contact_sheet/gallery/watermark/preset/bench/watch/watch_status/watch_stop/analyze/suggest/batch_start/batch_status/batch_cancel/diff/audit/preview；模块级零 mcp import——mcp SDK 要求 py3.10+，惰性导入 + CLI 版本检查双防护）
• rawpy 是核心依赖（RAW 解码对照片工具是刚需，三平台有 wheel）；其余可选：enhance = opencv-python-headless（denoise + straighten + HDR 合并 + 人脸模糊，可选）。这些模块懒加载 cv2，缺失时抛 "pip install 'photo-s-tools[enhance]'" 的 RuntimeError → process_image 记为 per-file 错误。
• 内置预设：presets.py BUILTIN_PRESETS（v1.9.0 lr-look：S 曲线+微饱和+export_sharpen），load_preset/list_presets 内置兜底，用户同名文件覆盖；delete_preset 对内置是 no-op。_apply_preset_defaults 跳过等于 dataclass 默认值的字段（默认值=无意向，不得覆盖 batch 的 _processed 后缀或 config 值）。
• RAW 解码质量档位（v1.9.0）：raw_demosaic（auto/ahd/vng/ppg/dcb/dht/amaze → rawpy.DemosaicAlgorithm，amaze 质量最高最慢）、jpeg_subsampling（444/422/420 → PIL subsampling 0/1/2，444 全色彩）、raw_color_space（sRGB/AdobeRGB/ProPhotoRGB，宽色域不加 ICC——PIL ImageCms 无对应内置 profile）、raw_16bit（16-bit 解码 → TIFF 输出经 tifffile 写 16-bit，仅纯转换路径有效：img._raw_16bit 动态属性在任一管线变换后被丢弃回退 8-bit；JPEG 无意义；缺 tifffile 抛清晰 per-file 错误）。rawpy 解码输出自动打 sRGB ICC（仅 sRGB 输出；_sRGB_icc_bytes() 缓存；--scrub 仍剥离）。元数据不变量：管线各阶段必须保留 img.info（EXIF/ICC/DPI）——adjust apply_tone_adjustments 已修复 ImageEnhance.Brightness/Contrast 空 .info 的丢元数据 bug，grade.py/mask.py 有同款拷贝约定（grade.py:8 注释）。
• 官方可选插件：独立 PyPI 发行版 photo-s-plugin-<name>（源码在 plugins/<name>/，不进核心 wheel）；模型权重外置（scunet 首次使用经 modelstore.ensure 下载到缓存 + sha256 校验；lut 纯 numpy 无权重）。安装双通道：photo-s plugin install <name> 或 pip install photo-s-plugin-<name>。开发脚手架：photo-s plugin scaffold <name>（生成 pyproject + PhotoSPlugin 桩）。
• Operation provider：PhotoSPlugin.provides = ("denoise"|"lut",) + 同名方法（如 denoise(img, strength, ctx) / lut(img, lut_path, ctx)）。provides 非空的插件被排除在通用 pre/post 钩子之外，只在管线槽位被调用（引擎 find_provider 查找；--denoise 有 provider 时优先否则回退 NLM；--lut 有 provider 时优先否则回退 photo_s.lut 三线性）。provider 异常按 per-file 错误传播，不静默吞。
• 元数据打标：rating/keywords/title 打包进 EXIF UserComment 的 PhotoS: 段（apply_exif_tags/read_exif_metadata），其余字段写标准 EXIF tag