Aidc Json To Psd
专为[阿里国际图片翻译 (AIDC)](https://www.aidc-ai.com/) 打造的图层数据转换工具,可将 AIDC 翻译结果的多图层 JSON 数据转换为可在 Photoshop 中编辑的 PSD 文件
Installation
npx aidc-json-to-psdAsk AI about Aidc Json To Psd
Powered by Claude · Grounded in docs
I know everything about Aidc Json To Psd. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
AIDC JSON to PSD Converter
🎨 专为阿里国际图片翻译 (AIDC) 打造的图层数据转换工具
将 AIDC 翻译结果的多图层 JSON 数据转换为可在 Photoshop 中编辑的 PSD 文件
🌟 核心优势
🎯 完美适配 AIDC
本项目专为 阿里国际图片翻译 (Alibaba International Design Center) 的图层数据格式优化,支持:
- ✅ 翻译文本层:自动识别
content(译文)和originalContent(原文) - ✅ 原始图像层:通过
refId关联原始图片与翻译文本 - ✅ 图层可见性控制:保留翻译/原图的显示状态
- ✅ 完整变换属性:位置、缩放、旋转、翻转、透明度等
- ✅ 远程图片下载:自动处理阿里云 OSS 图片链接
📖 AIDC 文档参考:图层数据格式说明
🔄 MCP 协议支持
基于 Model Context Protocol (MCP) 实现,可无缝集成到 AI 工作流:
- 通过 MCP 调用转换服务
- 标准化的工具接口
- 完善的错误处理和日志
📋 AIDC 图层数据格式示例
以下是 AIDC 输出的典型图层数据结构:
{
"id": "dfc61e5e-4e4c-11f0-b1cf-00163e0eb98a",
"language": "en",
"type": "template",
"width": 1000,
"height": 1000,
"backgroundColor": "transparent",
"layers": [
{
"id": "615ad318-ea71-4402-b6d2-3b5afd68d0b7",
"type": "text",
"content": "High Elastic Shock-Absorbing Seat Cushion",
"originalContent": "高弹减震坐垫",
"fontSize": 41,
"fontFamily": "AlibabaSans-Regular",
"color": "#00c671",
"textAlign": "left",
"left": 379,
"top": 160,
"width": 650,
"height": 80,
"visible": true,
"opacity": 1,
"rotate": 0,
"scaleX": 1,
"scaleY": 1,
"zIndex": 2,
"refId": "713a407c-5e59-40cb-a0a7-31942f477396"
},
{
"id": "713a407c-5e59-40cb-a0a7-31942f477396",
"type": "image",
"src": "https://piccopilot.oss-accelerate.aliyuncs.com/compose/xxx.png",
"left": 330.5,
"top": 160,
"width": 589,
"height": 132,
"visible": false,
"opacity": 1,
"zIndex": 2,
"refId": "615ad318-ea71-4402-b6d2-3b5afd68d0b7"
},
{
"id": "80270f6e-b8d0-4315-95cc-dd9cfde75555",
"type": "image",
"src": "https://aib-image.oss-ap-southeast-1.aliyuncs.com/xxx.png",
"left": 500,
"top": 500,
"width": 1000,
"height": 1000,
"visible": true,
"opacity": 1,
"zIndex": 1
}
]
}
关键字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
content | string | 翻译后的文本(如:英文) |
originalContent | string | 原始文本(如:中文) |
refId | string | 关联的原始图像层 ID(文本层与图片层互相关联) |
visible | boolean | 图层可见性(true=显示翻译文本,false=显示原始图片) |
fontFamily | string | 字体名称(支持 AlibabaSans 等) |
src | string | 远程图片 URL(支持阿里云 OSS 签名链接) |
🚀 快速开始
1. 安装依赖
npm install
2. 准备数据文件
将 AIDC 或其他兼容格式的 JSON 文件放入 data/ 目录:
data/
├── 1.json # AIDC 翻译结果示例
├── 2.json # AIDC 翻译结果示例
├── 3.json # AIDC 复杂场景示例
├── 4.json # AIDC 混合图层示例
└── 5.json # 通用格式示例(无 AIDC 特有字段)
3. 启动 MCP 服务器
npm start
# 或
node server.js
服务器将在 http://localhost:3000/mcp 上提供 StreamableHTTP 协议服务。
4. 调用转换工具
通过 MCP 客户端(使用 StreamableHTTP 传输)调用 json_to_psd 工具:
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
// 创建客户端并连接到服务器
const client = new Client({
name: "aidc-converter-client",
version: "1.0.0"
}, {
capabilities: {}
});
// 使用 StreamableHTTP 传输连接
const transport = new StreamableHTTPClientTransport(
new URL('http://localhost:3000/mcp')
);
await client.connect(transport);
// 调用转换工具
const result = await client.callTool({
name: "json_to_psd",
arguments: {
jsonData: JSON.parse(fs.readFileSync('data/1.json', 'utf-8')),
outputPath: "result.psd"
}
});
console.log(result);
// 输出示例:
// {
// success: true,
// message: "PSD file created successfully",
// layersProcessed: 6,
// fileSize: 18023,
// resourceUri: "psd://result-20250101120000.psd"
// }
5. 获取转换后的 PSD 文件
⚠️ 重要:工具返回的是 MCP Resource URI,需要通过 resources/read 获取实际文件内容:
// 从工具结果中获取 resourceUri
const resourceUri = result.content[0].text; // 解析 JSON 获取 resourceUri
// 读取资源内容
const resourceResult = await client.readResource({
uri: resourceUri
});
// resourceResult.contents[0] 包含 PSD 文件的 base64 数据
const psdBase64 = resourceResult.contents[0].text;
const psdBuffer = Buffer.from(psdBase64, 'base64');
// 保存到本地
fs.writeFileSync('output/result.psd', psdBuffer);
console.log('✅ PSD 文件已保存到 output/result.psd');
6. 在 Photoshop 中验证
转换完成后,打开 output/result.psd:
- ✅ 文本层可编辑
- ✅ 图层结构完整
- ✅ 变换属性保留
- ✅ 兼容多版本 Photoshop
📖 功能特性
✅ 文本层处理
- 可编辑文本:生成真实的 Photoshop 文本层(非栅格化)
- 字体映射:自动将
AlibabaSans-Regular等字体映射到 Photoshop 兼容字体 - 样式保留:字号、颜色、对齐方式、粗体/斜体等
- 双语支持:同时保留原文和译文信息
✅ 图像层处理
- 远程下载:自动下载阿里云 OSS 等远程图片
- 格式支持:PNG, JPG, GIF, WebP, BMP, TIFF
- 智能缓存:避免重复下载相同图片
- 尺寸限制:最大 8192x8192px,最大 50MB
✅ 图层变换
- 位置:
left,top(坐标定位) - 缩放:
scaleX,scaleY(支持非等比缩放) - 旋转:
rotate(角度值) - 翻转:
flipX,flipY(水平/垂直翻转) - 透明度:
opacity(0-1 范围) - 可见性:
visible(显示/隐藏)
✅ MCP 协议支持
- StreamableHTTP 传输:基于 HTTP 的 MCP 服务器(端口 3000)
- 标准工具定义:符合 MCP 1.21.0 规范
- 输出模式 (outputSchema):定义了结构化返回值
- Resources 机制:转换结果以 MCP Resource 形式返回
- 会话管理:支持多会话并发,自动清理过期资源
- 错误处理:详细的错误信息和日志
🛠️ 技术栈
| 技术 | 版本 | 用途 |
|---|---|---|
| Node.js | ≥18.0.0 | 运行环境 |
| @modelcontextprotocol/sdk | 1.21.0 | MCP 协议实现 |
| ag-psd | ^15.1.0 | PSD 文件读写 |
| axios | ^1.6.2 | HTTP 请求(图片下载) |
| sharp | ^0.33.0 | 图像处理和格式转换 |
| zod | ^3.25.76 | 数据验证和类型安全 |
🏗️ 项目结构
aidc-json-to-psd/
├── server.js # MCP 服务器入口(StreamableHTTP)
├── package.json # 项目配置
├── lib/
│ ├── psd-converter.js # PSD 转换核心逻辑
│ ├── image-downloader.js # 图片下载和缓存
│ ├── text-processor.js # 文本层处理
│ ├── psd-reader.js # PSD 文件读取(验证用)
│ ├── layer-comparison-tool.js # 图层对比工具
│ └── session-resource-store.js# 会话资源存储和管理
├── data/ # 示例数据
│ ├── 1.json # AIDC 示例 1:商品图翻译
│ ├── 2.json # AIDC 示例 2:海报翻译
│ ├── 3.json # AIDC 示例 3:多图层复杂场景
│ ├── 4.json # AIDC 示例 4:混合图层
│ └── 5.json # 通用格式示例:基础图层数据
├── output/ # 输出 PSD 文件目录
└── temp/ # 临时图片缓存目录
📝 使用方法
方法 1:通过 MCP StreamableHTTP 客户端调用(推荐)
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import fs from 'fs';
// 1. 创建并连接客户端
const client = new Client({
name: "aidc-converter-client",
version: "1.0.0"
}, {
capabilities: {}
});
const transport = new StreamableHTTPClientTransport(
new URL('http://localhost:3000/mcp')
);
await client.connect(transport);
// 2. 读取 JSON 数据
const jsonData = JSON.parse(fs.readFileSync('data/1.json', 'utf-8'));
// 3. 调用转换工具
const toolResult = await client.callTool({
name: "json_to_psd",
arguments: {
jsonData: jsonData,
outputPath: "my-design.psd",
useEditableText: true,
strictMode: true
}
});
// 4. 解析工具返回结果
const resultData = JSON.parse(toolResult.content[0].text);
console.log('转换结果:', resultData);
// {
// success: true,
// message: "PSD file created successfully",
// layersProcessed: 6,
// fileSize: 18023,
// resourceUri: "psd://my-design-20250101120000.psd"
// }
// 5. ⚠️ 重要:通过 resources/read 获取 PSD 文件
const resourceResult = await client.readResource({
uri: resultData.resourceUri
});
// 6. 解码并保存 PSD 文件
const psdBase64 = resourceResult.contents[0].text;
const psdBuffer = Buffer.from(psdBase64, 'base64');
fs.writeFileSync('output/my-design.psd', psdBuffer);
console.log('✅ PSD 文件已保存到 output/my-design.psd');
关键点说明:
- 🔌 传输协议:使用
StreamableHTTPClientTransport连接到 HTTP 端点 - 📦 返回格式:工具返回
resourceUri(如:psd://xxx.psd) - 📥 获取文件:必须调用
client.readResource()读取实际文件内容 - 🔐 数据编码:资源内容为 base64 编码,需解码后保存
方法 2:直接调用核心库(无 MCP 协议)
如果不需要 MCP 协议功能,可直接使用核心库:
import { convertJsonToPsd } from './lib/psd-converter.js';
import fs from 'fs';
const jsonData = JSON.parse(fs.readFileSync('data/1.json', 'utf-8'));
// 直接转换并保存到本地文件
await convertJsonToPsd(jsonData, 'output/result.psd', {
useEditableText: true,
strictMode: true
});
console.log('✅ 转换完成: output/result.psd');
🔧 配置选项
图片下载配置
在 lib/image-downloader.js 中可调整:
{
timeout: 30000, // 超时时间:30秒
maxSize: 50 * 1024 * 1024, // 最大文件大小:50MB
maxDimension: 8192, // 最大尺寸:8192x8192px
supportedFormats: ['jpeg', 'png', 'gif', 'webp', 'bmp', 'tiff']
}
字体映射配置
在 lib/text-processor.js 中可自定义:
const FONT_MAPPING = {
'AlibabaSans-Regular': 'ArialMT',
'PingFang SC': 'PingFangSC-Regular',
'Microsoft YaHei': 'MicrosoftYaHei',
// 添加更多字体映射...
};
🐛 故障排除
常见问题
1. 图片下载失败
错误: Failed to download image from [URL]
解决: 检查网络连接,验证 OSS 签名链接是否过期
2. 字体显示问题
问题: Photoshop 提示"缺少字体"
解决: 安装相应字体,或在 FONT_MAPPING 中添加映射
3. 图层位置偏移
问题: 图层坐标不正确
解决: AIDC 坐标系为中心点定位,已自动转换为左上角坐标
4. 文本层无法编辑
问题: 文本显示为像素图
解决: 确保 JSON 中 type 为 "text" 且包含 content 字段
📊 测试结果
以下是使用真实 AIDC 及通用格式数据的测试结果:
| 文件 | 类型 | 画布尺寸 | 图层数 | 文本层 | 图像层 | 输出大小 | 状态 |
|---|---|---|---|---|---|---|---|
| 1.json | AIDC | 1000x1000px | 6 | 2 | 4 | 17.6 KB | ✅ 成功 |
| 2.json | AIDC | 1000x1452px | 6 | 3 | 3 | 17.7 KB | ✅ 成功 |
| 3.json | AIDC | 800x800px | 16 | 8 | 8 | 60.9 KB | ✅ 成功 |
| 4.json | AIDC | 750x1186px | 8 | 4 | 4 | 26.3 KB | ✅ 成功 |
| 5.json | 通用 | 782x1042px | 3 | 0 | 3 | 12.4 KB | ✅ 成功 |
所有生成的 PSD 文件已在 Photoshop CC 2024 / CS6 中测试通过。
🤝 兼容性说明
AIDC 格式支持
本项目完全兼容 AIDC 图层数据格式,包括:
- ✅ 语言标识(
language) - ✅ 模板类型(
type: "template") - ✅ 文本关联(
refId双向关联) - ✅ 原始内容(
originalContent/originalFontSize) - ✅ 图层锁定(
locked) - ✅ 文本方向(
direction: "ltr")
通用格式支持
同时也支持任何符合以下结构的 JSON 数据(参见示例:data/5.json):
{
"width": 782,
"height": 1042,
"backgroundColor": "transparent",
"layers": [
{
"type": "image",
"top": 521,
"left": 391,
"width": 782,
"height": 1042,
"src": "https://example.com/image.png",
"visible": true,
"scaleX": 1,
"scaleY": 1
},
{
"type": "text",
"content": "Hello World",
"fontSize": 24,
"fontFamily": "Arial",
"color": "#000000",
"left": 100,
"top": 100,
"width": 200,
"height": 50,
"visible": true
}
]
}
说明:普通格式无需包含 AIDC 特有字段(如 language、originalContent、refId 等),只需基本的图层属性即可。
📄 许可证
MIT License - 详见 LICENSE 文件
🌐 相关链接
- AIDC 官网: https://www.aidc-ai.com/
- AIDC 文档: https://aidge.yuque.com/org-wiki-aidge-bzb63a/brbggt/ubom6g7nh7byz3on
- MCP 协议: https://modelcontextprotocol.io
- ag-psd 库: https://github.com/Agamnentzar/ag-psd
💡 使用建议
- 批量转换:可以编写脚本批量处理 AIDC 导出的多个 JSON 文件
- 自定义字体:根据实际需求调整字体映射表
- 样式微调:转换后在 Photoshop 中进行细节调整
- 版本控制:建议将生成的 PSD 文件纳入版本管理
