From 346aa09eaaac765d3c8287c69a503fab545b187c Mon Sep 17 00:00:00 2001 From: hanhan Date: Mon, 3 Aug 2026 19:43:31 +0800 Subject: [PATCH] =?UTF-8?q?=E5=AE=8C=E5=96=84=E4=B8=AD=E6=96=87=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 265 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 187 insertions(+), 78 deletions(-) diff --git a/README.md b/README.md index 962e669..5f228c2 100644 --- a/README.md +++ b/README.md @@ -1,107 +1,216 @@ -# AI Edit +# Photoshop AI Edit -Photoshop CEP panel for image generation. It sends text prompts to your own image API, previews the result, and places generated PNGs into the active document as new masked layers. +Photoshop CEP 面板插件，用于调用用户自己的图像生成接口，并将生成结果预览后置入当前 Photoshop 文档。插件支持普通生图、选区编辑、参考图上传，以及带图层蒙版的结果置入。 -## Architecture +## 功能 -| Layer | File | Role | -| --- | --- | --- | -| Panel UI | `src/panels/ImageGenerator.jsx` | React + Tailwind, runs in the CEP CEF panel | -| Bridge | `src/cep.js` | Node file/network access and `evalScript` calls | -| Host | `cep/host/host.jsx` | ExtendScript: masked layer placement, file and prompt dialogs | -| Manifest | `cep/CSXS/manifest.xml` | CEP extension declaration | +- 配置 API 地址、API Key、模型、尺寸、画质和背景模式 +- 输入中文或其他语言的提示词 +- 调用 OpenAI 风格的图像生成接口 +- 上传一张或多张参考图 +- 根据 Photoshop 当前选区自动执行图像编辑 +- 生成多张结果并在面板中保留最近 12 张缩略图 +- 将结果作为嵌入式智能对象图层置入当前文档 +- 有选区时自动创建基于原始选区的图层蒙版 +- 将面板配置保存到浏览器本地存储 -Node runs in the panel (`--enable-nodejs --mixed-context`), so temp files and HTTP -both go through Node rather than UXP storage or `fetch`. +## 运行环境 -## Styling +- Windows 或 macOS +- Adobe Photoshop 2020 及以上版本（CEP Host 版本范围为 `20.0` 至 `99.9`） +- Node.js，建议使用 LTS 版本 +- npm 或 pnpm +- 一个兼容本项目请求格式的图像生成 API -Tailwind CSS 3, compiled by PostCSS into `dist/styles/panel.css`. Utility classes -carry the exact pixel values from the original design, so arbitrary values -(`h-[47px]`, `bg-[#2f2f2f]`) are used throughout rather than the default scale. +本项目是 CEP 扩展，不是 UXP 插件。运行时需要启用 CEP 的 `PlayerDebugMode`。 -- `tailwind.config.js` — accent color, the rounded font stack, and the `narrow` (max 340px) breakpoint -- `src/index.css` — Tailwind entry plus base rules for `html`, `body`, and `#root` +## 项目结构 -`src/styles.css` and `src/panels/ImageGenerator.css` are the pre-Tailwind -originals. Nothing imports them; they are kept as the reference for the -original pixel values. +| 路径 | 说明 | +| --- | --- | +| `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 内容扫描、颜色、字体和窄屏断点配置 | -## Prompt Input +## 安装依赖 -The prompt box is a `contentEditable` div. CEF does not reliably receive IME -composition events, so the button above 词库 opens a native Photoshop -ScriptUI window for typing Chinese. Text crosses `evalScript` as -`escape()`-encoded ASCII in both directions. - -## API Shape - -The default request is compatible with OpenAI-style image endpoints: - -```json -{ - "model": "gpt-image-2", - "prompt": "your prompt", - "n": 1, - "size": "1024x1024", - "response_format": "b64_json" -} -``` - -Accepted response shapes: - -```json -{ "data": [{ "b64_json": "..." }] } -``` - -```json -{ "data": [{ "url": "https://..." }] } -``` - -`output` and `images` arrays are also tolerated for gateway variants. - -## Photoshop Placement - -Generated images first appear only in the panel's thumbnail list. Clicking a -thumbnail places it as an embedded smart-object layer with a new layer mask. -The selection that existed when generation started is saved as a temporary -alpha channel, so the mask still uses the original selection even if the user -changes the selection before clicking. Without a selection, the layer gets a -reveal-all mask. - -When a selection exists, its merged visible pixels are exported as the first -reference image. Uploaded reference files follow it. The panel sends these -images as data URLs in the request body's `images` array. - -The request size is read from Photoshop: the full canvas dimensions are used -without a selection, and the selection bounds are used when a selection exists. - -## Build +使用 npm： ```bash npm install +``` + +或使用 pnpm： + +```bash +pnpm install +``` + +## 构建和安装 + +先构建扩展： + +```bash npm run build ``` -Output goes to `dist`, which is the extension folder itself (`dist/CSXS/manifest.xml`). +构建结果会输出到 `dist/`。该目录是可加载的 CEP 扩展目录，包含编译后的 `index.js`、`styles/panel.css` 以及从 `cep/` 复制的清单、Host 脚本和图标。 -## Install +然后运行安装脚本： ```bash npm run cep:setup ``` -This enables `PlayerDebugMode` for CSXS 9–12 and links `dist` into the Adobe -extensions folder. On Windows it writes to `HKCU\Software\Adobe\CSXS.*` and -creates a directory junction; on macOS it uses `defaults write` and a symlink. +安装脚本会执行以下操作： -Restart Photoshop, then open the panel from `Plugins`. +1. 在 Windows 的 `HKCU\Software\Adobe\CSXS.9` 至 `CSXS.12` 中启用 `PlayerDebugMode`；macOS 使用 `defaults write` 完成相同配置。 +2. 创建 Adobe CEP 扩展目录。 +3. 将 `dist/` 创建为 `com.aiedit.panel` 的目录链接或符号链接。 -## Development +脚本执行完成后重启 Photoshop，在菜单 `插件` 或 `Plugins` 中打开 `AI 生图` 面板。 + +如果尚未构建，安装脚本会提示先运行 `npm run build`。 + +## 配置 API + +打开面板右上角的设置按钮，填写： + +- **API 地址**：可以填写 API 根地址，也可以直接填写 `/images/generations` 或 `/images/edits` 地址。插件会根据当前操作自动补全路径。 +- **API Key**：请求会通过 `Authorization: Bearer ` 发送。 +- **模型**：可选 `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 ``` -Reload the panel from its flyout menu, or open `http://localhost:8088` for -Chrome DevTools (the port comes from `cep/.debug`). +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)。