# Capture One AI for Mac

让视觉 AI 在 Mac 上读取和调整 Capture One，通过本机 **MCP stdio / JSON CLI** 完成调色，并查看 Capture One 实际渲染的画面。

**macOS 实验版 · Capture One 16.8.6.25 · Apple Silicon · Session**。当前版本为 0.3.0a3，依赖原生 Apple Events / JXA；其他宿主版本、Intel Mac、Catalog 和批量任务尚未完成兼容验证。项目非 Capture One 官方产品。

[下载预发布](https://github.com/iscca/capture-one-ai-macos/releases) · [安装说明](docs/INSTALL.md) · [Skill 使用](docs/SKILL.md)

## 1. AI 可以调整 Capture One 的哪些参数？

你可以直接描述希望照片发生的变化，例如“人物亮一点，背景保持暗调”“绿色柔和一些”“高光暖一点、阴影冷一点”。AI 会结合当前照片，选择 Capture One 中受支持的工具进行调整。

| 调整工具 | 可以控制的参数 | 可以用来改善什么 |
|---|---|---|
| 基础调整 | 曝光、对比度、亮度、饱和度 | 调整照片整体明暗、反差和颜色浓淡 |
| 白平衡 | 色温、色调 | 调整整体冷暖，以及偏绿或偏品红的倾向，同时保留需要的现场光色 |
| 高动态范围（HDR） | 高光、阴影、白色、黑色 | 调整亮部和暗部层次，让高光过渡、阴影密度更符合画面目标 |
| 曲线 | RGB、红、绿、蓝、Luma 五个通道的曲线点 | 塑造反差、黑位和高光过渡；通过通道曲线调整不同明度区域的颜色关系 |
| 色阶 | RGB、红、绿、蓝通道的输入黑白点、输出黑白点和中间调 | 调整黑白端点、中间调明暗及通道关系，控制照片的厚重或通透感 |
| 颜色编辑器 | Basic / Advanced 支持色区的色相、饱和度、明度，以及高级色区的范围和平滑度 | 单独处理某类颜色，例如让鲜绿更克制、蓝色更偏青，或修正局部颜色倾向 |
| 色彩平衡 | 主色轮，以及阴影、中间调、高光色轮；分影调色轮还支持明度调整 | 建立整体色调，或分别处理暗部、主体中间调和亮部的冷暖与偏色 |
| 胶片颗粒 | 六种颗粒类型、强度、大小 | 增加适合照片的颗粒质感；目前仅支持背景层 |

当问题只出现在主体或背景时，AI 可以使用 **AI 主体／背景蒙版和调整图层**，对受支持的参数做局部调整。图层支持创建、选择、不透明度和开关；蒙版支持复制、反相、清除、受限填充、羽化和亮度范围。实际覆盖与边缘效果需要结合预览检查。

新方案会先创建一个新的调整版本，保留原图和原有版本；同一方案的后续微调继续使用这个版本。你可以查看前后对比，再提出“保留现在的肤色，背景继续调整”等要求。

具体参数和局部能力以当前 Capture One 版本的支持范围为准。颜色编辑器的“所有颜色”总色区不提供明度调整；Skin 专用参数目前尚未接通。[完整参数说明](docs/COLOR_API.md)

## 2. 参考照片追色：分析样图，再调整当前照片

接入支持看图的 AI 客户端后，你可以提供一张参考照片，让 AI **自动分析参考图的明暗、灰度偏色和主要颜色关系，再调用 Capture One 的原生参数，对当前照片进行追色**。你负责说明喜欢什么、哪些内容需要保留，无需自己逐项填写调色参数。

### 分析参考图的明暗和灰度偏色

AI 会先看参考照片的黑位有多深、暗部是否通透、中间调是否柔和，以及高光怎样过渡，再分析暗部、中间调和亮部各自的偏色。

例如，一张照片可能是“暗部偏青灰、中间调保留自然肤色、高光略带暖黄”。这些关系共同构成它的色调。追色时需要保留这种关系，而不是把所有灰色和白色都校成中性。

### 建立参考图与当前照片的颜色对应

颜色映射指的是：比较两张照片中可对应的颜色，判断当前照片应怎样调整，才能接近参考图中的表现。

例如，参考图中的绿色可能更偏橄榄绿、饱和度较低；蓝色可能更偏青；肤色可能更柔和，白色物体仍保留暖光。AI 会分别判断这些颜色在**色相、浓淡和明暗**上的差异，再选择颜色编辑器、色轮、曲线或其他合适工具进行调整。

同一场景可以更直接地比较细节；不同场景则需要考虑光线、肤色和材质差异，借鉴参考图的色彩关系，避免把另一张照片的参数直接套用过来。

### 选取固定细节，检查每轮变化

AI 会从两张照片中选取可对应、具有代表性的细节，例如灰白墙面、面颊、叶片、天空或产品包装，作为反复比较的依据。

这些细节会帮助判断：“暗部还需要偏冷多少”“绿色是否过于鲜艳”“高光变暖后，肤色有没有一起偏黄”。取样尽量避开反光、过曝高光、纯黑阴影和混色边缘。参考文件可读取且色彩空间可确认时，还可以测量这些区域的明度与颜色差异；只有可见附件而没有可读文件时，会明确采用目测分析，不虚构数值。

### 调整 C1 参数，查看真实效果，再继续微调

AI 根据分析结果选择有实际作用的参数：先处理整体明暗和反差，再调整分影调偏色与具体颜色，必要时增加主体或背景的局部调整。

每轮调整后会读取实际参数，并查看 **Capture One 当前调整后渲染的预览**，对照参考图和同一批固定细节，检查效果是否更接近目标，以及已经满意的部分有没有受到影响。测量结果用来辅助判断，不会直接当作色温或滑块数值使用。

你可以继续用自然语言提出修改，例如：

> 参考这张照片追色：保留它柔和的高光、偏冷的暗部和低饱和绿色。人物肤色保持自然，不要跟着背景一起变绿。先给我一个版本，再展示与调整前的对比。

> 这一版的肤色和亮度可以保留，背景绿色再克制一点，阴影不要继续加深。

参考追色会受原片曝光、布光、相机色彩和材质影响，不能仅靠调色重建另一张照片的光线与内容，也不承诺每张照片都能完全一致。当前重点是单张照片的参考调色，批量处理暂不纳入。

本版本包含任务记录、版本比较和固定细节测量；更新旧版时，需要同时更新本机程序和配套 skill。参数恢复目前只覆盖快照所在层的调色参数，不包含完整图层和蒙版历史。

[修图与版本流程](docs/EDITING_TASKS.md) · [参考目标与反馈](docs/P1_EDITING.md) · [灰度偏色与细节测量](docs/REFERENCE_MATCHING.md)

## 安装

需要 Python 3.11+、已安装并有效授权的 Capture One。在 Mac 上解压源码到固定目录，打开终端执行：

```sh
./Install.command
./Run.command context --compact
```

如果系统 `python3` 版本不足，使用 `C1AI_PYTHON=/path/to/python3 ./Install.command` 指定已安装的 Python。授权 macOS 正常弹出的自动化权限。

在 Capture One 打开一个 Session 并选中照片。确认开启该 Session 的实验调整后运行：

```sh
.venv/bin/python scripts/configure_macos.py \
  --enable-current-session --enable-experimental-modules
```

实际预览需要用户明确允许临时低分辨率 JPEG 导出，再加 `--allow-preview-export`。预览是 C1 当前调整后的实际输出，最长边 1600px；不是相机内嵌缩略图。默认不导出正式成片。

安装器生成本机 `config/mcp-server.local.json`。将它接入支持本地 MCP 和图片块的视觉 AI 客户端，六个工具为 `context`、`images`、`read`、`adjust`、`preview`、`operations`。无需为不同模型另建服务。

## 配套 skill

将 `skills/capture-one-edit` 复制到客户端的技能目录；Codex 通常使用 `~/.codex/skills/capture-one-edit`。刷新后使用：

> 使用 $capture-one-edit，为当前选中照片制作一个电影胶片候选版本，先说明方向，再调整并查看实际预览。

skill 提供调色流程，执行依赖已安装的本机 MCP/CLI。安装 skill 不会自动开启照片写入或临时导出。[详细说明](docs/SKILL.md)

## 当前限制

Skin 逐项参数、图层排序／复制、渐变／组合／子蒙版选择、直接蒙版像素、预览与 RAW 坐标映射和无导出渲染暂不可用。AI 蒙版的实际覆盖需要看图判断；AI 层填充可能保留生成蒙版约束。参数成功回读不等于视觉效果合格。

[验证范围](docs/SUPPORT.md) · [实机报告](docs/MAC_VALIDATION.md) · [接口](docs/API.md) · [开发说明](docs/DEVELOPMENT.md)

照片、预览、Session、配置、候选资格、令牌和操作记录保留在本机，不进入公开分发包。运行状态位于 `~/Library/Application Support/CaptureOneAI/`。

[MIT License](LICENSE) · [来源与第三方声明](THIRD_PARTY_NOTICES.md)