# easy-ps

**Repository Path**: chaunceyzero/easy-ps

## Basic Information

- **Project Name**: easy-ps
- **Description**: easy-ps
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-15
- **Last Updated**: 2026-07-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Easy PS

Easy PS 是一款面向 Windows 的本地 AI 修图工具，提供常用 Canvas 编辑能力，并通过 OpenAI 兼容 API 网关完成 AI 图片生成、图片编辑和修图提示词优化。

应用内置写真、婚纱、婚礼跟拍、儿童摄影、孕妇照、全家福、毕业照、证件照等修图场景，并支持叠加质感肌或奶油肌肤质风格。

## 主要功能

- Windows 桌面应用，同时保留浏览器运行模式
- 打开本地图片或新建画布
- 画笔、橡皮擦、文字、裁剪、旋转、翻转
- 亮度、对比度、饱和度、灰度、模糊调整
- 撤销、重做、缩放、画布尺寸调整和 PNG 导出
- 基于场景预设生成专业修图提示词
- 使用文本模型进一步优化“补充要求”
- 使用图像模型生成新图片或编辑当前画布
- 自动检测网关支持的模型并禁用不可用项

## 支持的 AI 模型

### 图片生成与编辑

应用按网关实际返回结果检测以下图像模型：

- `gpt-image-2`
- `gpt-image-1.5`
- `gpt-image-1`

`2048x2048` 尺寸仅对支持该尺寸的模型开放，其他情况下请选择界面提供的可用尺寸或 `auto`。

### 提示词优化

点击“AI 优化”时，应用会按以下优先级选择网关中可用的文本模型：

1. `gpt-5.4-mini`
2. `gpt-5.6-luna`
3. `gpt-5.4`

提示词优化会结合当前任务、修图场景、肤质风格和补充要求，整理出适合图像模型执行的专业指令。

音频和 Realtime 模型不属于当前修图工作流，因此不会用于图片测试或编辑。

## 环境要求

- Windows 10/11 x64
- Node.js 18 或更高版本
- npm
- 一个 OpenAI 兼容 API 网关及有效 API Key

网关需要按实际使用能力提供以下接口：

- `GET /v1/models`
- `POST /v1/chat/completions`
- `POST /v1/images/generations`
- `POST /v1/images/edits`

## 快速开始

首次使用先安装依赖：

```powershell
cd easy-ps
npm install
```

### Windows 桌面版

首次运行前生成应用图标，然后启动桌面应用：

```powershell
npm run icon
npm run desktop
```

桌面应用会在随机本地端口启动内置服务，不占用固定的 `4190` 端口。

### 浏览器版

```powershell
npm start
```

打开 `http://127.0.0.1:4190`。

如需指定端口，可在启动前设置 `PORT`：

```powershell
$env:PORT=4200
npm start
```

## 连接 AI 网关

1. 在连接区域填写 API Base URL，例如 `https://api.example.com/v1`。
2. 填写网关 API Key。
3. 点击连接，应用会读取模型列表并标记当前可用模型。
4. 连接成功后，选择图片模型、画质和输出尺寸。

Base URL 可以填写到域名或 `/v1` 层级，应用会自动规范接口路径。请不要填写到具体的 `/images/generations` 接口。

## 基本工作流

### AI 编辑

1. 打开一张本地图片，或先新建画布。
2. 选择“编辑当前图片”。
3. 选择写真、婚纱、证件照等场景，并按需选择质感肌或奶油肌。
4. 填写补充要求；需要时点击“AI 优化”。
5. 选择图像模型、画质和尺寸，然后开始 AI 修图。
6. 对返回结果继续使用本地工具调整，最后导出 PNG。

### AI 生成

1. 选择“生成新图片”。
2. 选择场景和肤质预设，填写画面要求。
3. 可先使用“AI 优化”完善提示词。
4. 选择模型、画质和尺寸，然后生成图片。

AI 请求超时时间为 **240 秒**。大型图片生成或编辑可能需要较长时间，请等待任务完成后再重复提交。

## 构建 Windows 安装包

生成图标并构建 Windows x64 NSIS 安装包：

```powershell
npm install
npm run icon
npm run dist:win
```

构建产物输出到 `dist` 目录，安装包名称格式为：

```text
Easy-PS-Setup-1.0.0-x64.exe
```

## 常用命令

| 命令 | 用途 |
| --- | --- |
| `npm start` | 启动浏览器版服务 |
| `npm run desktop` | 启动 Windows 桌面版 |
| `npm run icon` | 生成桌面应用图标 |
| `npm run mock` | 启动手动调试用的本地模拟网关 |
| `npm test` | 运行自动化测试 |
| `npm run check` | 检查主要 JavaScript 文件语法 |
| `npm run dist:win` | 构建 Windows x64 安装包 |

## 本地接口

内置服务向前端提供以下本地接口：

| 接口 | 用途 |
| --- | --- |
| `GET /api/models` | 获取并分类网关模型 |
| `POST /api/ai/optimize-prompt` | 使用文本模型优化修图提示词 |
| `POST /api/ai/generate` | 调用图像生成接口 |
| `POST /api/ai/edit` | 调用图像编辑接口 |

这些接口只负责本机前端与用户指定网关之间的转发，不提供公网服务。

## 测试

```powershell
npm run check
npm test
```

自动化测试会启动本地模拟网关，不访问真实 API，也不会消耗 API Key。

需要手动联调界面时，可另开一个终端运行：

```powershell
npm run mock
```

模拟网关默认地址为 `http://127.0.0.1:4191/v1`，仅用于本地开发测试。

## 项目结构

```text
easy-ps/
|- server.mjs             本地静态服务与 AI 网关代理
|- public/
|  |- index.html          应用界面
|  |- app.js              前端编辑器和 AI 交互逻辑
|  |- presets.js          修图场景和肤质预设
|  `- style.css           界面样式
|- electron/
|  `- main.mjs            Electron 主进程
|- scripts/
|  `- generate-icon.ps1   Windows 图标生成脚本
|- test/                   自动化测试
`- work/
   `- mock-gateway.mjs    本地模拟 AI 网关
```

## 数据安全

- 桌面版会使用操作系统提供的安全存储能力加密 API Base URL 和 API Key，并保存到当前用户的应用数据目录，以便下次启动时自动恢复连接。
- 浏览器版的 API Key 只保存在当前页面内存中，不会写入文件、日志、Cookie、`localStorage` 或 `sessionStorage`。
- AI 请求仅由本地服务转发到用户填写的网关。
- 带鉴权的请求不会跟随重定向，避免 API Key 被转发到其他地址。
- 桌面版和浏览器版服务均只监听本机地址 `127.0.0.1`。

在桌面版中点击“断开连接”会删除已保存的 API 凭据。