完善中文项目文档
This commit is contained in:
hanhan
@@ -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 <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
|
||||
```
|
||||
|
||||
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)。
|
||||
|
||||
Reference in New Issue
Block a user