AIDC JSON to PSD Converter

---

🌟 核心优势

🎯 完美适配 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

---

💡 使用建议

1. 批量转换：可以编写脚本批量处理 AIDC 导出的多个 JSON 文件
2. 自定义字体：根据实际需求调整字体映射表
3. 样式微调：转换后在 Photoshop 中进行细节调整
4. 版本控制：建议将生成的 PSD 文件纳入版本管理

---