{
  "markdown": "# 📷 PhotoS\n\n<!-- mcp-name: io.github.Dongwu259/photo-s -->\n\n[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)\n[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-lightgrey)](https://github.com)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE) [![Weights](https://img.shields.io/badge/auto--tone%20weights-CC--BY--NC%204.0-orange)](docs/COMMERCIAL.md)\n[![PyPI](https://img.shields.io/badge/pypi-photo--s--tools-orange)](https://pypi.org/project/photo-s-tools/)\n\n**CLI 给 AI agent 用，GUI 给人用。** PhotoS 是一个跨平台批量照片处理工具箱：\n给摄影师一套完整的 Tkinter GUI（v2.2 工作区：图库 / 修图（真实管线实时预览 + 直方图 + 旁侧调整工具 + 照片间复制粘贴设置 + 逐照片撤销）/ 导出（照片队列 + 输出设置 + 命名导出配方）/ 工具四大模块，含审查打分灯箱、去重查看器），\n给 AI agent 一套带统一版本化 JSON 契约的 CLI / REST / MCP 接口。\n\n> 🖥 GUI 给人用 — ⌨️ CLI 给 AI agent 用 — `pip install photo-s-tools`\n\n**中文** · [English](docs/README.en.md)\n\n---\n\n## 🤖 为 AI agent 而生\n\nPhotoS 首先是一个 **AI agent 就绪的图像管线**：四条集成通道，全部挂在同一个\n版本化 JSON 契约上（`schema_version`，加性演进——升级永不破坏消费者）。\n\n| 通道 | 接入方式 |\n|---|---|\n| **MCP server** — 30 核心工具 + 插件自动注册（process / suggest / autopilot / index / find / select / hdr / blurfaces / dedup …） | `claude mcp add photo-s -- photo-s mcp` |\n| **现成 SKILL.md** — 支持 skill 的 agent 即取即用，零额外依赖 | `cp -r skills/photo-s ~/.claude/skills/` |\n| **REST API** — 异步任务 + SSE 进度 | `photo-s serve --port 0 --token auto --ready-file x.json` |\n| **Python 库直调** — 无 IPC 开销 | `from photo_s.engine import batch_process` |\n\n所有输出带 `schema_version`；JSON 键永远英文；单文件错误不中断整批；\n破坏性操作必须显式传参。完整契约见 [`docs/AGENT_API.md`](docs/AGENT_API.md)。\n\n---\n\n## ✨ 功能特性\n\n| 功能 | GUI | CLI | 说明 |\n|---|---|---|---|\n| 批量压缩 | ✅ | ✅ | JPEG/WebP/HEIC/AVIF 质量调优、色度子采样（444/422/420） |\n| 目标体积模式 | ✅ | ✅ | 自动调优质量以控制在目标文件体积以内 |\n| 格式转换 | ✅ | ✅ | JPEG / PNG / WebP / TIFF / BMP / HEIC / AVIF |\n| RAW 解码 | ✅ | ✅ | 22+ 种相机 RAW 格式，内置支持（rawpy/libraw）；去马赛克算法可选、色彩空间（sRGB/AdobeRGB/ProPhotoRGB）、16-bit TIFF 输出、自动打 sRGB ICC |\n| 缩放 / 比例 | ✅ | ✅ | 最大尺寸、百分比或最长边上限 |\n| 视觉预览 | ✅ | — | 原图↔处理后实时并排预览（经真实管线渲染，v2.4 含逐照片调整注入） |\n| 影调与色彩 | ✅ | ✅ | 亮度/对比度/饱和度/伽马/锐化，黑白、复古 |\n| 导出锐化 | ✅ | ✅ | LR 式输出级 USM，半径随输出分辨率缩放 |\n| 白平衡 | ✅ | ✅ | 色温 K，或灰卡采样 |\n| WB tint 轴 | ✅ | ✅ | 绿(-)/品红(+) G-M 轴 |\n| 点曲线 / 色阶 | ✅ | ✅ | PCHIP 点曲线，手动黑/白场/伽马 |\n| 三向颜色分级 | ✅ | ✅ | 阴影/中间调/高光 色相 + 饱和分区 |\n| HSL 分色 | ✅ | ✅ | 8 色域，色相/饱和/亮度偏移 |\n| 点颜色 | ✅ | ✅ | 取样色定向色相/饱和/亮度 + 范围容差 |\n| 局部蒙版 | ✅ | ✅ | 命名线性/径向/颜色范围蒙版，蒙版内 11 项局部调整 |\n| 镜头矫正 | ✅ | ✅ | 手动畸变 k1 / 去暗角 / 消色差（纯 numpy）；用户维护的命名镜头档案 |\n| 感知分析 | ✅ | ✅ | 直方图/通道统计/色温倾向/曝光/模糊（`analyze`） |\n| 参数推荐 | — | ✅ | 规则型 `suggest`：分析统计 → 保守修复参数 + 理由（零模型离线） |\n| 自然饱和度 / 清晰度 / 纹理 | ✅ | ✅ | 反向加权饱和，局部对比 |\n| 去雾 / 暗角 / 颗粒 | ✅ | ✅ | 暗通道去雾，径向暗角，胶片颗粒 |\n| 曝光 | ✅ | ✅ | 曝光档位调整，或自动归一化到目标 |\n| 自动色阶 | ✅ | ✅ | 2% 裁切直方图拉伸 |\n| 高光恢复 | ✅ | ✅ | LR 式：压缩硬切高光，恢复出渐变细节 |\n| LOG 还原 | ✅ | ✅ | SLOG3/CLOG3/LOGC3/DLOG/VLOG/HLG（1D LUT，零依赖） |\n| LUT 调色 | ✅ | ✅ | .cube 三线性（插件加四面体 + 5 个电影预设） |\n| 降噪 | ✅ | ✅¹ | NLM（`[enhance]` 可选依赖） |\n| 自动扶正 | ✅ | ✅¹ | 校正地平线，置信度门控（`[enhance]` 可选依赖） |\n| HDR 合并 | ✅ | ✅¹ | 曝光融合，手持对齐（`[enhance]` 可选依赖） |\n| 人脸模糊 | ✅ | ✅¹ | 模糊或马赛克人脸，Haar cascade（`[enhance]` 可选依赖） |\n| 抠图 / 背景移除 | ✅ | ✅ | AI 分割（`subject`/`person`/`object:类别`）或颜色键控（`color:R,G,B[tol,feather,invert]`——白底文字/logo 专用）→ alpha 透明输出，PNG/WebP/TIFF/AVIF/HEIC（JPEG 按文件报错，绝不静默拍平） |\n| 裁剪 / 旋转 / 翻转 / 留边 | ✅ | ✅ | 统一比例裁剪 + 任意几何 |\n| 打印尺寸 | ✅ | ✅ | 中心裁剪 + 指定 DPI 的精确打印像素 |\n| 智能重命名 | ✅ | ✅ | 日期/相机/序号模板 |\n| 自动整理归档 | ✅ | ✅ | 日期/相机子文件夹归类 |\n| 水印 | ✅ | ✅ | 文字 + 图片水印，7 个位置 |\n| 多尺寸输出 | ✅ | ✅ | 一份输入，N 份带标签输出 |\n| 元数据打标 | ✅ | ✅ | 评分/关键词/标题批量打标（UserComment） |\n| 元数据筛选 | ✅ | ✅ | 按评分/关键词筛出照片 |\n| 元数据导入 | — | ✅ | 从表格批量写入 |\n| 选片（筛选） | ✅ | ✅ | 曝光/清晰度筛选（GUI 仅保留符合项，可撤销）；`--score` 质量评分排序 + `--burst` 连拍组留最佳 |\n| 选片归档（评分） | ✅ | ✅ | 按评分分拣——精选/淘汰双阈值（≥4 精选、≤2 淘汰） |\n| 连拍选图 | ✅ | ✅ | 每组保留最清晰 |\n| 校验和清单 | ✅ | ✅ | SHA-256 归档完整性 + 校验 |\n| HTML 画廊 | ✅ | ✅ | 自包含 index.html + 缩略图 |\n| 预设 | ✅ | ✅ | 保存/加载命名配置 + 内置 `lr-look`（LR 风格：S 曲线+自然饱和+导出锐化） |\n| 多配置批量 | — | ✅ | 一份输入，N 份输出配置 |\n| 并行处理 | ✅ | ✅ | 多线程 |\n| JSON 输出 | — | ✅ | 供 AI agent 消费的机器可读输出 |\n| 配置文件 | — | ✅ | TOML 默认值 |\n| EXIF 编辑 | — | ✅ | 批量版权/作者/GPS |\n| 预设一键套用 | — | ✅ | 一键套用已存风格 |\n| EXIF 日期偏移 | — | ✅ | 时区/相机时钟修正 |\n| 隐私清理 | — | ✅ | 移除 EXIF + ICC + GPS |\n| 同步日期 | — | ✅ | 输出 mtime ← EXIF 拍摄时间 |\n| 文件夹监视 | ✅ | ✅ | 自动处理新文件（`[watch]` 可选依赖） |\n| 自动旋转 | ✅ | ✅ | 基于 EXIF Orientation |\n| 图片去重 | ✅ | ✅ | 感知哈希重复检测 |\n| 质量指标 | ✅ | ✅ | SSIM / 模糊分 |\n| CSV 报告 | — | ✅ | 逐文件统计 |\n| 完整性检查 | — | ✅ | 损坏文件扫描 |\n| 联系表 | ✅ | ✅ | 网格拼图 |\n| 色彩管理 | — | ✅ | sRGB / CMYK 展平 |\n| REST API | — | ✅ | 供 agent 使用的 HTTP 服务（异步任务 + SSE 进度） |\n| 插件系统 | — | ✅ | 第三方插件支持 |\n| 官方插件管理 | — | ✅ | list/install/info/fetch + pip 安装 |\n| MCP server | — | ✅ | 向 MCP 客户端（Claude Desktop / Claude Code / 任意客户端）暴露 30 个核心工具（插件自动追加） |\n| 批量基准 | — | ✅ | 并发扩展实测 |\n| AI 识别蒙版 | ✅ | ✅¹ | 主体/人物/物体（80 类）一键生成蒙版，U2Netp/HumanSeg/YOLOv8n-seg（v1.8，onnx 权重自动下载校验） |\n| 笔刷 + 组合蒙版 | ✅ | ✅ | 笔刷涂抹蒙版；A&B / A-B 组合引用已命名蒙版（v1.8） |\n| AI 自动调色 | ✅ | ✅ | auto-tone 官方插件：CLIP+MLP 预测 9 项全局参数 + RAG 检索历史修图（权重 CC-BY-NC 4.0，非商用）；v2.3 引擎槽位接线（`--auto-tone`），装后 MCP/REST 工具自动注册；v2.4 Develop「AI 调色」按钮——参数写入逐照片覆盖层，可微调/可撤销；v2.4 局部调整词汇表（模型预测 subject/person/object 蒙版内调整，经蒙版管线应用） + 美学 verifier（`audit --aesthetic`，SigLIP 头/Qwen 终审）|\n| LR 数据桥 | — | ✅ | `lr-scan` 扫描 Lightroom 目录/XMP → 训练数据；`lr-train`/`lr-predict` 岭回归基调模型；`lr-merge` 合并多机数据包（v1.9） |\n| XMP 写出（LR 双向互通） | — | ✅ | `xmp-export` / `batch --write-xmp`：PhotoS 调整写成 LR 可读 `.xmp` sidecar（crs 字段逐项逆映射 + radial/linear 蒙版 + 评分/关键词），LR 打开原图即续修（v2.5）——「agent 用的 Lightroom」写出侧收口 |\n| 无人值守管线 | ✅ | ✅ | `autopilot`：监视目录 → suggest/auto-tone → audit 闸门 → passed/review 分流 + JSONL 轨迹；`--write-xmp` 让人工在 LR 里修正，回采即残差训练信号（v2.5） |\n| 语义搜索 / 自动打标 | — | ✅ | `index` 建嵌入索引（SigLIP 文本+图像 / 内置 84 维直方图），`find` 中英文文本或以图搜图；`--tags` 自动打标写 EXIF/XMP 关键词（v2.5） |\n| 出片审计 | — | ✅ | `audit` 质量闸门（pass/fail + 原因，agent 终止条件）；`--aesthetic 1-10` 模型美学闸门（v2.4，auto-tone 插件：SigLIP 头/Qwen 终审）；`diff` 前后对比；`preview` base64 快照（v1.9） |\n| GPS 地理标记 | — | ✅ | GPX 轨迹插值写 GPS EXIF（时区偏移自动换算，跨日期变更线正确插值） |\n| SCUNet 强降噪 | — | ✅ | 官方插件（ONNX）：强度感知混合 + 分块推理，大图不 OOM |\n\n> ¹ 降噪 / 自动扶正 / HDR / 人脸模糊需要可选依赖：\n> `pip install photo-s-tools[enhance]`（opencv-python-headless）。\n> 未安装时给出明确安装提示，不影响其余功能。\n\n---\n\n## 📦 安装\n\n```bash\npip install photo-s-tools            # 核心——内置 RAW 解码（rawpy）\npip install \"photo-s-tools[enhance]\" # + opencv：人脸模糊 / HDR / 降噪 / 扶正\npip install \"photo-s-tools[tiff16]\"  # + tifffile：16-bit RAW → TIFF 输出\npip install \"photo-s-tools[mcp]\"     # + MCP server（Python 3.10+）\n```\n\n零安装（uvx）：`uvx --from photo-s-tools photo-s --help` ·\n`uvx --from \"photo-s-tools[mcp]\" photo-s mcp`\n\n## 🚀 快速上手\n\n```bash\nphoto-s batch 'RAW/*.ARW' --format jpeg -o out/ -q 90   # 批量 RAW → JPEG\nphoto-s batch 'RAW/*.ARW' -o out/ -q 95 --jpeg-subsampling 444 \\\n  --raw-demosaic amaze                                # 极致画质 RAW → JPEG\nphoto-s batch 'RAW/*.ARW' -o out/ --preset lr-look      # 内置 LR 风格出片\nphoto-s compress *.jpg --target-size 5MB -j 8           # 自动调优到 ≤5MB\nphoto-s select ~/shoot/ -r --selects-dir 精选 --rejects-dir 淘汰 --dry-run\nphoto-s hash ~/deliver/ -o manifest.csv --verify manifest.csv\n```\n\n`photo-s --help` 列出全部 35 个子命令。语言：`--language en|zh|auto`。\n\n---\n\n## 🧭 文档\n\n| 文档 | 内容 |\n|---|---|\n| [`docs/FEATURES.md`](docs/FEATURES.md) | 完整功能清单——35 个 CLI 命令、引擎管线 |\n| [`docs/AGENT_API.md`](docs/AGENT_API.md) | Agent 契约：JSON 结构、退出码、REST、MCP |\n| [`docs/PLUGINS.md`](docs/PLUGINS.md) | 插件系统：SCUNet 降噪、LUT、自己写插件 |\n| [`docs/GUI_CHANGES.md`](docs/GUI_CHANGES.md) | GUI 行为与接口契约 |\n| [`docs/ROADMAP.md`](docs/ROADMAP.md) | 版本路线（v1.6.0：Lightroom 方向调色） |\n| [`docs/COMMERCIAL.md`](docs/COMMERCIAL.md) | 商用授权：双许可说明、边界判定表与 FAQ |\n\n> 命名：PyPI 发行名 **`photo-s-tools`**（原名 `photo-s` 被 PyPI 拦截）·\n> CLI 命令 `photo-s` · Python 包 `photo_s` · 品牌 **PhotoS**。\n\n---\n\n## ⚠️ 限制与说明\n\nPhotoS 是**批量 / 交付导向管线**，不是交互式编辑器——不做 RAW 域编辑。局部编辑是规格驱动的：命名蒙版（linear/radial/color/AI 分割/笔刷/组合算子）+ 蒙版内局部调整，全部以紧凑字符串建模，经 CLI/REST/MCP/preset 零胶水传递。\n\n- **设备上推理，无云端。** 降噪模型权重（SCUNet）首次使用时下载到本机；不上传任何数据。\n- **许可（双许可）。** 官方代码与多数官方模型权重（含 SCUNet 检查点）为 **MIT**——\n  可自由商用。唯一例外：auto-tone 插件的模型权重为 **CC-BY-NC 4.0**（非商用，\n  训练数据来自个人 Lightroom 修图记录）——个人与非商业用途永久免费，**商业用途\n  需购买授权**：邮箱 <1634103640@qq.com> · [dwphoto.top/message](https://dwphoto.top/message)。\n  边界判定与常见问题见 [`docs/COMMERCIAL.md`](COMMERCIAL.md)。第三方插件与模型\n  各自持有自己的许可；商用再分发前请自行核实。\n\n## 📄 许可证\n\nMIT\n",
  "bytes": 8157,
  "sha": "23d2477aca742e5838fdc9b9f71bd51f621c65ab67a9ed0833d7acb180e23d07",
  "repo_slug": "dongwu259/photo_s",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dongwu259_photo_s_1d16034b/readme"
}