hanhan
217 lines
7.7 KiB
Markdown
217 lines
7.7 KiB
Markdown
# 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：
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
或使用 pnpm：
|
||
|
||
```bash
|
||
pnpm install
|
||
```
|
||
|
||
## 构建和安装
|
||
|
||
先构建扩展：
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
构建结果会输出到 `dist/`。该目录是可加载的 CEP 扩展目录，包含编译后的 `index.js`、`styles/panel.css` 以及从 `cep/` 复制的清单、Host 脚本和图标。
|
||
|
||
然后运行安装脚本：
|
||
|
||
```bash
|
||
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 字段：
|
||
|
||
```json
|
||
{
|
||
"model": "gpt-image-2",
|
||
"prompt": "一只坐在窗边的猫",
|
||
"n": 1,
|
||
"size": "1024x1024",
|
||
"quality": "low",
|
||
"response_format": "b64_json"
|
||
}
|
||
```
|
||
|
||
当背景设置为透明时，额外发送：
|
||
|
||
```json
|
||
{
|
||
"background": "transparent"
|
||
}
|
||
```
|
||
|
||
接口响应支持以下形式：
|
||
|
||
```json
|
||
{
|
||
"data": [{ "b64_json": "..." }]
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"data": [{ "url": "https://example.com/image.png" }]
|
||
}
|
||
```
|
||
|
||
为兼容不同网关，插件也会读取 `output` 或 `images` 数组；数组元素可以是 `b64_json`、`image`、`url` 字段，或者直接是字符串。
|
||
|
||
选区编辑请求使用 multipart/form-data：文本字段与普通请求字段相同，图片字段名为单图时的 `image`，多图时的 `image[]`。
|
||
|
||
## 开发模式
|
||
|
||
执行以下命令后，源码变更会自动重新构建：
|
||
|
||
```bash
|
||
npm run watch
|
||
```
|
||
|
||
CEP 面板可以通过面板飞出菜单重新加载。调试地址使用 `cep/.debug` 中配置的端口，默认可尝试访问：
|
||
|
||
```text
|
||
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](LICENSE)。
|