photoshop-ai-edit/README.md

Photoshop AI Edit

Photoshop CEP 面板插件，用于调用用户自己的图像生成接口，并将生成结果预览后置入当前 Photoshop 文档。插件支持普通生图、选区编辑、参考图上传，以及带图层蒙版的结果置入。

功能

• 配置 API 地址、API Key、模型、尺寸、画质和背景模式
• 输入中文或其他语言的提示词
• 调用 OpenAI 风格的图像生成接口
• 上传一张或多张参考图
• 根据 Photoshop 当前选区自动执行图像编辑
• 生成多张结果并在面板中保留最近 12 张缩略图
• 将结果作为嵌入式智能对象图层置入当前文档
• 有选区时自动创建基于原始选区的图层蒙版
• 将面板配置保存到浏览器本地存储

运行环境

• Windows 或 macOS
• Adobe Photoshop 2020 及以上版本（CEP Host 版本范围为 20.0 至 99.9）
• Node.js，建议使用 LTS 版本
• npm 或 pnpm
• 一个兼容本项目请求格式的图像生成 API

本项目是 CEP 扩展，不是 UXP 插件。运行时需要启用 CEP 的 PlayerDebugMode。

项目结构

路径	说明
src/panels/ImageGenerator.jsx	React 面板界面、设置管理和生图流程
src/cep.js	面板与 Photoshop Host、Node.js 之间的桥接层
src/index.jsx	React 应用入口
src/index.css	Tailwind CSS 入口和全局基础样式
cep/host/host.jsx	Photoshop ExtendScript，包括选区、对话框和图层置入
cep/CSXS/manifest.xml	CEP 扩展清单和 Photoshop 面板声明
cep/index.html	CEP 面板 HTML 外壳
scripts/setup-cep.js	开启调试模式并链接扩展目录
webpack.config.js	Webpack、Babel、CSS 和 CEP 文件复制配置
tailwind.config.js	Tailwind 内容扫描、颜色、字体和窄屏断点配置

安装依赖

使用 npm：

npm install

或使用 pnpm：

pnpm install

构建和安装

先构建扩展：

npm run build

构建结果会输出到 dist/。该目录是可加载的 CEP 扩展目录，包含编译后的 index.js、styles/panel.css 以及从 cep/ 复制的清单、Host 脚本和图标。

然后运行安装脚本：

npm run cep:setup

安装脚本会执行以下操作：

1. 在 Windows 的 HKCU\Software\Adobe\CSXS.9 至 CSXS.12 中启用 PlayerDebugMode；macOS 使用 defaults write 完成相同配置。
2. 创建 Adobe CEP 扩展目录。
3. 将 dist/ 创建为 com.aiedit.panel 的目录链接或符号链接。

脚本执行完成后重启 Photoshop，在菜单 插件 或 Plugins 中打开 AI 生图 面板。

如果尚未构建，安装脚本会提示先运行 npm run build。

配置 API

打开面板右上角的设置按钮，填写：

• API 地址：可以填写 API 根地址，也可以直接填写 /images/generations 或 /images/edits 地址。插件会根据当前操作自动补全路径。
• API Key：请求会通过 Authorization: Bearer <API Key> 发送。
• 模型：可选 gpt-image-2、gpt-image-1、gpt-image-1.5 和 gemini-3.1-flash-lite-image，也可以在代码中扩展模型列表。
• 数量：一次生成 1 至 3 张图片。
• 画质：界面中的 1K、2K、3K 分别对应请求参数 low、medium、high。
• 背景：选择透明背景时发送 background: "transparent"；默认模式不发送该字段。

设置保存于 CEP 面板的 localStorage，键名为 ai-edit.settings.v3。API Key 也会保存在本地，请根据使用环境评估风险，不要在共享电脑上保存生产密钥。

使用流程

1. 在 Photoshop 中打开文档。
2. 打开 AI 生图 面板并配置 API。
3. 输入提示词；需要输入中文时，可以使用提示词区域上方的原生 Photoshop 输入对话框。
4. 可选：上传参考图，或先在 Photoshop 中建立选区。
5. 点击 立即生成。
6. 在结果缩略图中点击目标图片，将其置入当前文档。

普通生图

没有 Photoshop 选区时，插件调用 /images/generations，请求尺寸使用当前文档的完整画布尺寸。上传的参考图会以 Data URL 形式放入 JSON 请求的 images 数组，同时兼容发送第一张图片到 image 字段。

选区编辑

存在选区时，插件会：

1. 保存原始选区到临时 Alpha 通道。
2. 复制并合并可见内容，裁剪到选区边界并导出临时 PNG。
3. 将该 PNG 放在用户上传的参考图之前。
4. 调用 /images/edits，使用 multipart/form-data 上传图片。
5. 点击结果后恢复选区，并按原边界缩放、移动图片，最后创建显示选区的图层蒙版。

如果生成开始后用户修改了选区，置入时仍使用生成开始时保存的原始选区。

没有选区时，置入的图层会创建显示全部内容的图层蒙版。

API 请求格式

普通生图默认发送以下 JSON 字段：

{
  "model": "gpt-image-2",
  "prompt": "一只坐在窗边的猫",
  "n": 1,
  "size": "1024x1024",
  "quality": "low",
  "response_format": "b64_json"
}

当背景设置为透明时，额外发送：

{
  "background": "transparent"
}

接口响应支持以下形式：

{
  "data": [{ "b64_json": "..." }]
}

{
  "data": [{ "url": "https://example.com/image.png" }]
}

为兼容不同网关，插件也会读取 output 或 images 数组；数组元素可以是 b64_json、image、url 字段，或者直接是字符串。

选区编辑请求使用 multipart/form-data：文本字段与普通请求字段相同，图片字段名为单图时的 image，多图时的 image[]。

开发模式

执行以下命令后，源码变更会自动重新构建：

npm run watch

CEP 面板可以通过面板飞出菜单重新加载。调试地址使用 cep/.debug 中配置的端口，默认可尝试访问：

http://localhost:8088

如需调整调试端口，请修改 cep/.debug 后重新加载面板。

样式说明

项目使用 Tailwind CSS 3 和 PostCSS。界面中的许多尺寸直接使用 Tailwind 任意值，以保持既有设计稿的像素尺寸，例如 h-[47px] 和 bg-[#2f2f2f]。

• tailwind.config.js 定义强调色、字体栈和 narrow（最大宽度 340px）断点。
• src/index.css 定义 Tailwind 入口、页面基础尺寸、背景色和滚动条行为。
• 运行时样式编译到 dist/styles/panel.css。

临时文件和网络

CEP 面板启用了 --enable-nodejs 和 --mixed-context，因此：

• 网络请求通过 Node.js 的 http 或 https 模块发送，不依赖浏览器 CORS 配置。
• 参考图通过 Node.js 文件系统读取。
• 生成结果会先写入系统临时目录下的 ai-edit/ 文件夹，再交给 Photoshop 置入。
• 选区参考图会写入系统临时目录，关闭 Photoshop 后不会自动清理历史临时文件。

常见问题

面板没有出现在 Photoshop 中

确认已依次执行 npm run build 和 npm run cep:setup，并完全重启 Photoshop。Windows 下还需要确认当前账户有权限创建 Adobe CEP 扩展目录。

提示 CEP 环境不可用

确认面板是通过 CEP 扩展加载，而不是直接用浏览器打开 cep/index.html。同时检查清单中的 --enable-nodejs 和 --mixed-context 参数是否存在。

接口地址无效或返回非 JSON

确认 API 地址包含正确的协议（http:// 或 https://），API Key 有效，并确认服务端返回 JSON。插件会自动补全 /images/generations 或 /images/edits 路径。

图片无法置入

确认 Photoshop 中有打开的文档，并检查系统临时目录是否可写。选区编辑失败时，可以先取消选区验证普通生图流程是否正常。

许可证

本项目使用 Apache License 2.0，详见 LICENSE。