# PSD Editor

[中文文档](#中文文档) | [English](#english)

![Node](https://img.shields.io/badge/Node.js-%3E%3D20.11-339933)
![License](https://img.shields.io/badge/License-MIT-blue)
![MCP](https://img.shields.io/badge/MCP-Streamable%20HTTP-6f42c1)

![PSD Editor 编辑器欢迎界面](assets/editor-cover-welcome.jpg)

PSD Editor 是一个面向 PSD / PSB 文件的浏览器编辑器，同时提供 REST API、MCP 服务和本地 CLI。项目采用前后端同构的 PSD 内核：浏览器负责可视化编辑，Node 服务端负责文件处理、渲染、自动化接口与 AI 能力。

> 在线体验：<https://fullpsd.zaopod.com>  
> GitHub 仓库：<https://github.com/hmwl/psdeditor>

> 本项目仅供学习、研究与技术参考。请遵守当地法律法规、Adobe 软件许可协议及知识产权规定；严禁用于任何非法用途。详见文末免责声明。

---

## 中文文档

### 项目简介

PSD Editor 可以在浏览器中打开、编辑并导出 PSD / PSB 文档，也可以作为无头服务被脚本、自动化平台或 AI Agent 调用。

- **编辑器**：图层、组、蒙版、混合模式、图层样式、文字、矢量路径、调整图层、滤镜、画板、色彩管理、选区、画笔、修饰、液化、消失点等。
- **智能对象导入**：读取 Photoshop 保存的缓存像素，作为普通像素图层使用；不编辑内嵌源内容、放置网格或智能滤镜参数。
- **导出**：PSD / PSB、PNG、JPEG、WebP、TIFF，以及 PDF、GIF、BMP、TGA、HDR、EXR 等格式。
- **API**：基于 Express 的 REST 接口，覆盖解析、编辑、渲染、导出、字体、档位与权限。
- **MCP**：标准 Model Context Protocol Streamable HTTP 端点，方便 Claude、Cursor、VS Code 等客户端接入。
- **CLI**：不启动浏览器即可执行 inspect、render、batch、convert 等操作，也可作为 stdio MCP 使用。
- **本地 AI**：可选的“重新打光”功能，模型在浏览器本地推理，不上传图片。

本项目只保留 **编辑器、MCP 服务、API 服务** 三项核心能力，不包含官网、文档站、在线调试台或示例 PSD 下载入口。

### 0.14.0 更新了什么

- **大文件更好保存了**：超大 PSD 的压缩和保存更多交给后台处理，减少卡顿和内存占用，保存后的预览图也会更新。
- **颜色更接近 Photoshop**：改进渐变、调整图层，以及 CMYK、Lab、灰度和 16/32 位文档的显示与导出，减少打开后偏色的情况。
- **文字保存更完整**：改进文字变形、路径文字和英文断字，保存后的排版和参数兼容性更好。
- **图层外观按缓存保留**：智能对象按 Photoshop 已保存的像素导入，保留文档中的独立图层；合并大图层时如果读不到原图像素，会停止操作并保留原内容。
- **接口权限更严格**：API Key 创建的会话沿用该 Key 原有的权限和额度。

升级后请重新安装依赖并运行 `npm run build`，再运行 `npm start`。默认启动现在使用生产模式；本机调试请用 `npm run dev`。

完整记录和已知限制见 [更新日志](CHANGELOG.md)。

### 智能对象与兼容性限制

导入智能对象后保留 Photoshop 保存的图层像素，不重新计算其内部源文档或变形。文档中的其他图层、文字和蒙版继续独立存在。导出的 PSD 不再包含这些智能对象的可编辑源内容；需要保留原始智能对象结构时，请保留原文件并另存编辑结果。

缓存缺失或通道数据不完整的文件可能无法正确显示或导入，应先在 Photoshop 中重新保存。溶解混合模式为近似效果；部分 HDR 调整、路径文字翻转及其他高级组合仍有限制。

### 技术栈

- **运行时**：Node.js 20.11+
- **服务端**：Express 5、Sharp、Multer
- **PSD 内核**：JavaScript 与可选 WASM 加速，浏览器与 Node 共用
- **前端**：原生 ES Modules、Canvas、WebGL / WebGPU、Web Worker
- **接口**：REST、OpenAPI 3.1、MCP Streamable HTTP
- **测试**：Node 内置测试脚本、Playwright（可选浏览器测试）
- **本地 AI**：ONNX Runtime Web、MediaPipe Tasks Vision

### 目录结构

```text
.
├── bin/                 CLI 与 stdio MCP
├── core/                PSD 解析、像素编辑、合成、滤镜、文字、格式编解码
├── server/              REST API、MCP、鉴权、档位、渲染服务
│   └── profiles/        ICC 色彩配置
├── web/
│   ├── editor/          浏览器编辑器
│   ├── assets/          图标、画笔/样式/图案等预设
│   └── vendor/          第三方解码库与本地 AI 模型
├── tools/               构建辅助、测试、图标与资源生成
├── deploy/              systemd 部署示例
├── .env.example         环境变量模板
└── package.json
```

### 环境要求

- Node.js **>= 20.11.0**
- npm
- 可选：Playwright + Chromium（运行浏览器测试）
- 可选：ImageMagick、Python 3 等（部分测试会使用）

### 安装

```bash
cd "PSD Editor"
npm install
npm --prefix server install
```

### 启动

```bash
npm run build
npm start
```

默认以生产模式启动，只提供构建产物。编辑器默认无需登录。`PSD_EDITOR_KEY=1` 是可选的服务端访问限制；启用时需由调用方或受控网关提供 API Key，页面不提供登录表单。

默认地址：

```text
http://localhost:8787/
```

编辑器入口为 `/` 或 `/editor`。

开发模式（监听源码改动）：

```bash
npm run dev
```

本地调试时可以关闭 API 鉴权：

```bash
PSD_EDITOR_AUTH=off npm start
```

> `PSD_EDITOR_AUTH=off` 只允许在本机或可信内网使用。部署到公网前必须配置 API Key、HTTPS 与反向代理。

### 配置

环境变量通过 shell、systemd、Docker 或进程管理器注入，`.env.example` 是完整变量清单模板。常用变量：

| 变量 | 说明 | 默认 |
| --- | --- | --- |
| `PORT` | 服务端口 | `8787` |
| `MAX_UPLOAD_MB` | 单文件上传上限（MB） | `200` |
| `PSD_EDITOR_AUTH` | `off` 关闭鉴权，仅限本机调试 | 空 |
| `PSD_EDITOR_DEV` | `1` 启用源码开发模式；生产保持 `0` | `0` |
| `PSD_EDITOR_KEY` | 可选：`1` 要求会话请求携带 API Key，需调用方或网关提供 | 空（无需登录） |
| `PSD_EDITOR_API_KEYS_FILE` | API Key 配置文件 | `server/api-keys.json` |
| `PSD_EDITOR_PLANS_FILE` | 档位/权限配置文件 | `server/plans.json` |
| `PSD_EDITOR_STATE_DIR` | 运行状态落盘目录 | `server/data/state` |
| `PSD_EDITOR_PUBLIC_URL` | 对外访问地址，用于生成 MCP 下载链接 | 空 |
| `PSD_EDITOR_CORS_ORIGINS` | 允许跨域的来源，逗号分隔 | 同源 |
| `PSD_EDITOR_MAX_CONCURRENT` | 重接口并发上限 | `2` |

创建 API Key：

```bash
cp server/api-keys.example.json server/api-keys.json
# 编辑 server/api-keys.json，填入随机 key
npm start
```

创建档位配置：

```bash
cp server/plans.example.json server/plans.json
```

请求时通过请求头传入 Key：

```text
X-Api-Key: your-key
```

或：

```text
Authorization: Bearer your-key
```

### REST API

常用端点：

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/health` | 健康检查与服务能力 |
| `GET` | `/api/catalog` | 能力目录、op 参数、滤镜、调整、预设 |
| `GET` | `/openapi.json` | OpenAPI 3.1 描述 |
| `POST` | `/api/doc/inspect` | 上传 PSD，返回图层树与文档摘要 |
| `POST` | `/api/doc/edit` | 统一编辑：属性、文字、像素、滤镜、画布等 |
| `POST` | `/api/doc/edit/plan` | 编辑 dry-run，不产出文件 |
| `POST` | `/api/doc/render` | 按图层重新合成位图 |
| `POST` | `/api/doc/export-artboards` | 导出全部画板为 zip |
| `POST` | `/mcp` | MCP Streamable HTTP 端点 |

示例：

```bash
curl http://localhost:8787/health

curl -X POST http://localhost:8787/api/doc/inspect \
  -H "X-Api-Key: your-key" \
  -F "psd=@example.psd"

curl -X POST http://localhost:8787/api/doc/edit \
  -H "X-Api-Key: your-key" \
  -F "psd=@example.psd" \
  -F 'ops=[{"op":"setLayerProps","index":1,"name":"新名称"}]'
```

完整参数请读取 `/api/catalog` 或 `/openapi.json`。智能对象在导入时转为缓存像素图层；不提供源图替换、网格编辑或智能对象片段写回接口。

### MCP

MCP 端点为：

```text
POST /mcp
```

客户端配置示例：

```json
{
  "mcpServers": {
    "psd-editor": {
      "type": "http",
      "url": "http://localhost:8787/mcp",
      "headers": {
        "X-Api-Key": "your-key"
      }
    }
  }
}
```

本地 stdio MCP：

```bash
node bin/psd_editor.js mcp
```

### CLI

```bash
node bin/psd_editor.js capabilities
node bin/psd_editor.js describe setLayerProps
node bin/psd_editor.js inspect example.psd
node bin/psd_editor.js render example.psd --out preview.png
node bin/psd_editor.js batch example.psd --input ops.json --out edited.psd
node bin/psd_editor.js convert example.psd example.png
```

### 本地 AI 模型

“重新打光”等功能使用本地 ONNX / MediaPipe 模型。仓库默认不提交大体积 `.onnx` 模型；如缺失可执行：

```bash
npm run vendor
```

该命令会下载并校验固定版本资源。所有推理均在本地完成，不上传图片。

### 测试

```bash
npm test
```

浏览器测试（需要 Playwright 与 Chromium）：

```bash
npm run test:browser
```

### 许可证

本项目自有代码采用 **MIT License**，详见 [LICENSE](LICENSE)。

以下内容 **不属于** MIT 授权范围，分别遵循其上游许可证：

- `web/vendor/` 下的第三方库、模型与运行库，详见 `web/vendor/LICENSES.txt`
- `web/assets/ps-presets/` 中的 Photoshop 预设资源，权利归各自所有者
- 其他文件中明确标注的第三方组件

使用、分发或商用前请自行核对所有第三方许可证。

### 免责声明

本项目仅供学习、研究和技术参考，不隶属于 Adobe，也不代表 Adobe 官方。Photoshop、PSD 及相关名称、商标、文件格式归 Adobe 或其各自权利人所有。

使用者必须遵守所在国家或地区的法律法规、Adobe 软件许可协议以及知识产权规定。**严禁**将本项目用于任何非法用途，包括但不限于侵犯知识产权、破解或绕过商业授权、未经授权处理他人文件、传播恶意内容或其他违法活动。

本项目按“现状”提供，不附带任何明示或暗示担保。使用者自行承担使用本项目产生的全部风险与责任；作者不对任何直接或间接损失负责。

---

## English

### Overview

PSD Editor is a browser-based editor for PSD / PSB documents, with a REST API, an MCP server, and a local CLI. The PSD kernel is shared between the browser editor and the Node.js server.

> Live demo: <https://fullpsd.zaopod.com>  
> GitHub repository: <https://github.com/hmwl/psdeditor>

> This project is provided for learning, research, and technical reference only. You must comply with applicable laws, Adobe's license terms, and intellectual-property rules. Any illegal use is strictly prohibited. See the disclaimer below.

### Features

- Open, edit, and export PSD / PSB documents.
- Layers, groups, masks, blend modes, layer styles, text, vector paths, adjustment layers, filters, artboards, selections, brushes, retouching, liquify, and vanishing point.
- Import smart objects as ordinary pixel layers using the cached appearance saved by Photoshop. Embedded source content, placement meshes, and smart-filter parameters are not editable.
- Export to PSD / PSB, PNG, JPEG, WebP, TIFF, PDF, GIF, BMP, TGA, HDR, EXR, and more.
- ICC color management and CMYK workflows.
- REST API for parsing, editing, rendering, export, fonts, plans, and permissions.
- MCP Streamable HTTP endpoint for Claude, Cursor, VS Code, and other clients.
- CLI for inspect, render, batch, convert, and stdio MCP.
- Optional local AI relighting. Inference runs locally; images are not uploaded.

The project ships only the **editor**, **MCP service**, and **API service**. It does not include the former marketing site, documentation site, online API console, or sample-PSD download endpoint.


### What changed in 0.14.0

- Large files use improved background compression, streaming saves, and refreshed composite previews.
- Gradients, adjustment layers, and CMYK, Lab, grayscale, and 16/32-bit documents have better rendering compatibility.
- Text warping, path text, and English hyphenation preserve more layout information when saved.
- Smart objects import as cached pixel layers. The document keeps its separate layers; large-layer merges stop if the original pixels cannot be read.
- API-key sessions inherit the key's permissions and quotas.

Reinstall dependencies and run `npm run build` before `npm start`. See [the changelog](CHANGELOG.md) for details.

### Smart objects and compatibility limits

Smart-object imports retain the layer pixels saved by Photoshop without recalculating embedded content or deformation. Other layers, text, and masks remain separate. Exported PSDs no longer contain editable smart-object sources; keep the original file and save your result separately if you need the original structure.

Files with missing caches or incomplete channel data may fail to display or import correctly; resave them in Photoshop first. Dissolve blending is approximate. Some HDR adjustments, flipped path text, and other advanced combinations still have limitations.

### Tech Stack

- Node.js 20.11+
- Express 5, Sharp, Multer
- JavaScript PSD kernel with optional WASM acceleration, shared by browser and server
- Native ES Modules, Canvas, WebGL / WebGPU, Web Workers
- REST, OpenAPI 3.1, MCP Streamable HTTP
- Playwright for optional browser tests
- ONNX Runtime Web and MediaPipe Tasks Vision for local AI

### Requirements

- Node.js **>= 20.11.0**
- npm
- Optional: Playwright + Chromium for browser tests
- Optional: ImageMagick, Python 3, and other tools used by some tests

### Install

```bash
cd "PSD Editor"
npm install
npm --prefix server install
```

### Run

```bash
npm run build
npm start
```

The server defaults to production mode and serves built assets. The editor opens without login by default. `PSD_EDITOR_KEY=1` optionally restricts session creation at the server; the caller or a controlled gateway must provide the API key. The page has no login form.

Open:

```text
http://localhost:8787/
```

Development mode:

```bash
npm run dev
```

For local testing without API authentication:

```bash
PSD_EDITOR_AUTH=off npm start
```

> Never expose `PSD_EDITOR_AUTH=off` to the public internet. Use API keys, HTTPS, and a reverse proxy in production.

### Configuration

Environment variables are injected by your shell, systemd, Docker, or process manager. `.env.example` lists the available variables.

| Variable | Description | Default |
| --- | --- | --- |
| `PORT` | HTTP port | `8787` |
| `MAX_UPLOAD_MB` | Upload limit per file (MB) | `200` |
| `PSD_EDITOR_AUTH` | `off` disables authentication; local use only | empty |
| `PSD_EDITOR_DEV` | `1` enables source development mode; keep `0` in production | `0` |
| `PSD_EDITOR_KEY` | Optional: `1` requires an API key on session requests, supplied by the caller or gateway | empty (no login) |
| `PSD_EDITOR_API_KEYS_FILE` | API-key file | `server/api-keys.json` |
| `PSD_EDITOR_PLANS_FILE` | Plan/permission file | `server/plans.json` |
| `PSD_EDITOR_STATE_DIR` | Runtime state directory | `server/data/state` |
| `PSD_EDITOR_PUBLIC_URL` | Public base URL used for MCP links | empty |
| `PSD_EDITOR_CORS_ORIGINS` | Comma-separated allowed origins | same origin |
| `PSD_EDITOR_MAX_CONCURRENT` | Concurrency limit for heavy endpoints | `2` |

Create an API key file:

```bash
cp server/api-keys.example.json server/api-keys.json
```

Create a plan file:

```bash
cp server/plans.example.json server/plans.json
```

Send the key with either header:

```text
X-Api-Key: your-key
```

```text
Authorization: Bearer your-key
```

### REST API

| Method | Path | Description |
| --- | --- | --- |
| `GET` | `/health` | Health and capabilities |
| `GET` | `/api/catalog` | Capability catalog, op schemas, filters, adjustments |
| `GET` | `/openapi.json` | OpenAPI 3.1 document |
| `POST` | `/api/doc/inspect` | Upload a PSD and inspect its layer tree |
| `POST` | `/api/doc/edit` | Unified edit endpoint |
| `POST` | `/api/doc/edit/plan` | Dry-run edit planning |
| `POST` | `/api/doc/render` | Recomposite layers to a bitmap |
| `POST` | `/api/doc/export-artboards` | Export all artboards as a zip |
| `POST` | `/mcp` | MCP Streamable HTTP endpoint |

Examples:

```bash
curl http://localhost:8787/health

curl -X POST http://localhost:8787/api/doc/inspect \
  -H "X-Api-Key: your-key" \
  -F "psd=@example.psd"
```

Read `/api/catalog` or `/openapi.json` for the full schemas. Smart objects become cached pixel layers on import. Source replacement, mesh editing, and smart-object fragment writeback are not available.

### MCP

```text
POST /mcp
```

Client configuration:

```json
{
  "mcpServers": {
    "psd-editor": {
      "type": "http",
      "url": "http://localhost:8787/mcp",
      "headers": {
        "X-Api-Key": "your-key"
      }
    }
  }
}
```

Local stdio MCP:

```bash
node bin/psd_editor.js mcp
```

### CLI

```bash
node bin/psd_editor.js capabilities
node bin/psd_editor.js describe setLayerProps
node bin/psd_editor.js inspect example.psd
node bin/psd_editor.js render example.psd --out preview.png
node bin/psd_editor.js batch example.psd --input ops.json --out edited.psd
node bin/psd_editor.js convert example.psd example.png
```

### Local AI Models

Optional AI features use local ONNX / MediaPipe models. Large `.onnx` files are not committed by default. Download and verify them with:

```bash
npm run vendor
```

All inference runs locally. Images are not uploaded.

### Tests

```bash
npm test
```

Browser tests (requires Playwright and Chromium):

```bash
npm run test:browser
```

### License

The project's own source code is released under the **MIT License**. See [LICENSE](LICENSE).

The MIT license does **not** cover:

- Third-party libraries and models under `web/vendor/`; see `web/vendor/LICENSES.txt`
- Photoshop preset assets under `web/assets/ps-presets/`, which belong to their respective owners
- Other third-party components explicitly marked in their files

Check all upstream licenses before redistribution or commercial use.

### Disclaimer

This project is for learning, research, and technical reference only. It is not affiliated with Adobe and does not represent Adobe. Photoshop, PSD, and related names, trademarks, and file formats belong to Adobe or their respective owners.

You must comply with all applicable laws and regulations, Adobe's software license terms, and intellectual-property rules. **Any illegal use is strictly prohibited**, including but not limited to intellectual-property infringement, cracking or bypassing commercial licenses, unauthorized processing of other people's files, distributing malicious content, or any other unlawful activity.

The software is provided "as is", without warranty of any kind, express or implied. You use it entirely at your own risk. The authors are not liable for any direct or indirect damages.