psd-to-preview

用途

psd-to-preview 是一个从 PSD 设计文件到预览页面 + React 组件 + Vue 组件的完整转换工作流。它作为工作流入口，串联三个核心技能，把 PSD 设计稿转换为可预览的 HTML 页面以及 React、Vue 组件代码。

主要能力

图层解析：由 psd-layer-reader 解析 PSD 结构，生成 layer-tree.json 图层数据树。
图层切片：由 psd-slicer 导出图层切片图片（PNG）。默认支持导出所有图层（包含中文字符和非常规字符），并会自动在 PSD 目录下寻找 layer-tree.json 等映射文件。
代码生成：由 psd-json-preview 将 JSON 和图片合成为终端代码，可生成 HTML 预览、React 组件和 Vue 组件。
命名规范化：调用 psd-slicer 时可加 --auto-rename 参数将资源转为 layer-xxx 格式；使用 --strict-naming 可强制图层名只能是标准英文加横杠，过滤掉不规范命名的层。
输出真实文本：若用户要求“输出真实文本”或“文案转代码”，在步骤 2 使用 --skip-type，在步骤 3 使用 --include-text，将文字转为 HTML/CSS 而非切图。

使用方式

技能依赖三个核心技能，执行前需确保它们在指定路径存在：psd-layer-reader、psd-slicer、psd-json-preview。

依赖预检查（AI 执行前必须执行）：

# 检查 psd-tools
py -3 -c "import psd_tools" 2>&1
# 如果返回 ImportError，表示未安装

# 检查 scikit-image
py -3 -c "import skimage" 2>&1

如缺少依赖，需询问用户是否安装。用户确认后执行安装：

# 安装必需依赖
py -3 -m pip install psd-tools

# 安装可选依赖（如果用户同意）
py -3 -m pip install scikit-image

版本检查（可选）：

py -3 -c "import psd_tools; print('psd-tools:', psd_tools.__version__)"
py -3 -c "import skimage; print('scikit-image:', skimage.__version__)"

注意事项：如果用户选择不安装 psd-tools，无法继续执行工作流；如果用户选择不安装 scikit-image，可以执行但部分带图层效果的元素会被跳过。安装完成后建议重新检查依赖是否安装成功。

执行命令：

# 步骤 1：图层解析
py -3 .claude/skills/psd-layer-reader/scripts/psd_layers.py \
  <PSD文件路径> --output <输出目录>/layer-tree.json

# 步骤 2：图层切片
py -3 .claude/skills/psd-slicer/scripts/export_slices.py \
  --psd <PSD文件路径> --output <输出目录>/sliced-images
# 注：psd-slicer 现默认允许各种图层导出并在工作目录自动查找映射 JSON。若用户需转命名规范化图形文件，可添加 --auto-rename。

# 步骤 3：代码生成
py -3 .claude/skills/psd-json-preview/scripts/generate_preview.py \
  --json <输出目录>/layer-tree.json --images <输出目录>/sliced-images \
  --out <输出目录> --generate-react --generate-vue \
  --component-name PsdComponent --preserve-names

高级方案：输出真实文本（保留文案可编辑性）。如果用户提到“要输出文案”、“文字转代码”或“文字不要切图”，使用以下组合命令：

# 步骤 2：图层切片（跳过文本图层，避免生成文字图片）
py -3 .claude/skills/psd-slicer/scripts/export_slices.py \
  --psd <PSD文件路径> --output <输出目录>/sliced-images --skip-type

# 步骤 3：代码生成（开启文本渲染，将文字转为 HTML/CSS）
py -3 .claude/skills/psd-json-preview/scripts/generate_preview.py \
  --json <输出目录>/layer-tree.json --images <输出目录>/sliced-images \
  --out <输出目录> --generate-react --generate-vue --include-text

关键提醒：使用 py -3（Windows）或 python3（Linux/Mac）。

执行检查清单：

[ ] <输出目录>/layer-tree.json 有数据
[ ] <输出目录>/sliced-images/ 有 PNG 文件
[ ] <输出目录>/preview/ 有 HTML 文件
[ ] <输出目录>/react-component/ 有 JSX 和 CSS 文件
[ ] <输出目录>/vue-component/ 有 Vue 文件

工作原理

PSD → psd-layer-reader → layer-tree.json → psd-slicer → sliced-images/ → psd-json-preview → preview/ + react-component/ + vue-component/

核心参数

参数	说明	示例
`<PSD路径>`	PSD 文件路径	`assets/design.psd`
`--output`	输出目录	`output/design-preview`

输出目录结构

output/
├── layer-tree.json       # 图层数据
├── sliced-images/        # PNG切片
├── preview/              # HTML 预览
│   ├── index.html
│   ├── styles.css
│   └── images/
├── react-component/      # React组件
│   ├── index.jsx
│   ├── index.module.css
│   └── images/
└── vue-component/        # Vue组件
├── index.vue
└── images/

常见问题

Q: 某些图层没有被导出？ A: 大部分通常是因为图层不可见、不包含内容或者完全透明。如果使用了 --strict-naming 参数，则不合规命名（中文等）也会被跳过。

Q: 导出的图层名字是乱的/中文的？ A: psd-slicer 会默认使用 PSD 中的原始名称进行导出。你可以在生成切片时加入 --auto-rename 将它们转化为统一的标准命名，或者确保 psd-layer-reader 已执行并在它的工作目录下自然匹配映射结构。

故障排查

错误	原因	解决方案
PSD 未找到	路径错误	检查文件路径
权限错误	无写入权限	检查目录权限
预览加载失败	路径错误	确保目录结构完整
JSON 解析错误	文件损坏	重新运行工作流

依赖说明

必需依赖：psd-tools（PSD 文件解析核心库）。

可选依赖：scikit-image（用于导出包含图层效果的元素，如阴影、发光、渐变等）。

手动安装命令（如果预检查阶段的自动安装失败）：

# 安装依赖
py -3 -m pip install psd-tools
py -3 -m pip install scikit-image

注意：虽然 SKILL.md 中包含安装命令，但 AI 执行时不会自动运行。请参考“依赖预检查”小节，让 AI 在执行工作流前检查并安装依赖。

版本：1.6 | 更新：2026年3月12日

适用场景

适用于需要将 PSD 设计稿转换为可预览页面及 React、Vue 组件代码的前端开发与设计交付场景，尤其适合需要保留文案可编辑性（文字转代码）或需要规范化图层命名的项目。

限制

依赖 psd-tools，未安装则无法继续执行工作流。
scikit-image 为可选依赖，未安装时部分带图层效果的元素会被跳过。
部分图层可能因不可见、无内容或完全透明而未被导出。
使用 --strict-naming 时，不合规命名（中文等）的图层会被跳过。
关于收费、价格、平台支持等信息，资料暂未提供。