Psd Batch Export

SKILL.md

---
name: psd-batch-export
description: 'PSD图层级智能引擎 — 解析PSD每一图层的文本/样式/位置/容量，按需修改、批量替换、AI制图、数据驱动生成。通用于门票、证书、邀请函、工牌、号码牌、海报等任何PSD模板。触发词：PSD、图层、文本替换、批量生成、PSD分析、PSD修改、门票、证书、邀请函、AI制图。'
argument-hint: '[PSD路径] [可选：Excel/数据源] [可选：输出目录]'
---

# PSD 图层级智能引擎 — AI 操作手册 v4.1

> **角色**: 你是 PSD 图层级处理专家。你能：解析 PSD 每个图层的全部信息 → 单层/批量修改文本 → 数据驱动批量生成 → 从零设计模板 → 智能配色推荐 → 自适应排版 → 印刷级渲染 → 像素+OCR 质量验证。

---

## 🎯 触发条件

当用户提及以下任一意图时，自动激活此技能：

| 类别 | 触发词 |
|------|--------|
| **分析/诊断** | PSD分析、图层信息、PSD结构、文字图层、字体检测、查看PSD、解析PSD、样式查看 |
| **单层/局部修改** | 改文字、修改PSD、换字体、改颜色、替换图层文字、调整字号、改样式 |
| **批量/数据驱动** | 批量生成、批量导出、PSD批量、Excel PSD、名单导入、数据驱动 |
| **模板设计** | 做模板、设计门票、生成证书、做海报、设计工牌、AI做图、智能生成 |
| **业务场景** | 门票、证书、邀请函、工牌、号码牌、参会证、奖状、海报、录取通知书、抽签卡 |
| **模糊意图** | "帮我看下这个PSD"、"把名字换成这些"、"生成100张"、"这个模板能放多少字" |

---

## 🧠 核心能力地图

```
┌──────────────────────────────────────────────────────────┐
│                   PSD 图层级智能引擎 v4.0                  │
├────────────────┬────────────────┬────────────────────────┤
│   分析 & 诊断   │   修改 & 操作   │    生成 & 设计          │
├────────────────┼────────────────┼────────────────────────┤
│ • 图层结构解析  │ • 单层文本修改  │ • 数据驱动批量 PSD/PNG  │
│ • 字体/字号检测 │ • 样式覆盖渲染  │ • 从零模板设计(5类型)   │
│ • 颜色提取      │ • JSON配置批量  │ • 印刷级 PNG 渲染      │
│ • bbox/位置     │ • 多图层同时编辑│ • 像素级验证抽查       │
│ • 字符容量分析  │ • 字体选择/降级 │ • 分图层 OCR 校验      │
│ • 列名智能匹配  │ • 颜色推荐      │ • 智能配色推荐         │
│ • 样式详情导出  │ • 自适应排版    │ • 智能分析报告         │
└────────────────┴────────────────┴────────────────────────┘
```

---

## 🎬 场景矩阵

根据用户意图，自动选择最佳工作模式：

### 🔍 分析场景 — "帮我看看这个PSD"
```
用户: 这个PSD里面有哪些文字？什么字体？能放多少字？
→ 执行 --analyze → 输出完整图层分析报告
→ 报告包含: 图层名、文本内容、字体族、字号、颜色、bbox坐标、字符容量
→ 标注容量风险、字体缺失警告
```

### ✏️ 单层修改场景 — "把标题改成XXX"
```
用户: 把名字改成"张三"，学校改成"清华大学"
→ 使用 psd_text_editor 精确定位 Txt TEXT 标记
→ 二进制级替换，保持 PSD 结构完整
→ 支持中英混排、自动截断超长文本
```

### 📊 批量数据驱动场景 — "用这个Excel生成100张"
```
用户: 这个名单.xlsx + 模板.psd → 每人一张
→ 6阶段流水线: 收集→分析→匹配→预览→导出→验证
→ 智能列匹配(精确/语义/位置三级)
→ 双阶段输出: PSD(可再编辑) + PNG(印刷级300DPI)
→ 导出后自动抽查(像素比对+可选分图层OCR)

官方模板快速启动:
  ai_designer.py --use morning --data 日签文案.xlsx --output out/
  ai_designer.py --use tech --data 嘉宾名单.xlsx
  ai_designer.py --use doodle --data 招聘岗位.xlsx
```

### 🎨 模板设计场景 — "用哪个模板好？"
```
用户: 有什么模板？/ 帮我看看日签模板有哪些字段
→ ai_designer.py --list         列出 3 款官方 PSD 模板
→ ai_designer.py --info morning  查看可编辑字段+容量
→ ai_designer.py --use tech --data 嘉宾.xlsx  一键批量生成

3 款官方模板:
  morning  早安手绘风日签 (720×1280)  — 早安问候/励志日签
  tech     炫彩风科技邀请函 (720×1280) — 科技峰会/产品发布
  doodle   手绘涂鸦招聘海报 (1284×2778) — 创意招聘

→ 8套预设配色 + LLM 无限配色生成
→ LLM 还可: 撰写文案(write_copy) / 评价设计(evaluate_design)
→ 需配置: OPENAI_API_KEY 或 ANTHROPIC_API_KEY 环境变量
```

### 🎨 智能配色场景 — "这个颜色搭配怎么样"
```
用户: 门票用什么配色好？/ 帮我生成一组配色 / 这个文字颜色对比度够吗
→ color_tools.py 场景推荐 + 调色板生成 + WCAG 对比度检查
→ 支持: 互补/三角/类比/单色 4种和谐方案
→ 支持从图片提取主色调
```

### 📐 排版计算场景 — "这个模板能放多大的字"
```
用户: 8个字用多大字号合适？/ 帮我算下这几个文字的排版
→ smart_layout.py 自动计算最优字号和位置
→ 4种预设(门票/证书/工牌/邀请函)
→ 支持任意画布自定义排版
```

### 🔄 复杂混合场景 — "先分析，再改几个试试，最后批量出"
```
用户: 先看看模板结构 → 改几个字预览 → 确认后全部导出
→ --analyze → --dry-run → 完整导出
→ 每阶段输出结果，等待用户确认后进入下一阶段
```

---

## 🧠 系统化工作流（6 阶段）

按以下顺序执行，每阶段完成后汇报发现，等待确认后再进入下一阶段。

### Phase 1: 信息收集 `[GATHER]`

**目标**: 确定输入和用户意图。

```
必需:  PSD 文件路径
可选:  数据源（Excel / CSV / 手动列表 / 无）
可选:  输出目录（默认 output/）
可选:  操作模式（分析 / 修改 / 批量 / 混合）
```

**智能提问策略**:
- 只给了 PSD → 询问意图：分析？修改？批量？
- 给了 PSD + Excel → 默认批量模式，先分析再确认
- 给了 PSD + 文字内容 → 单层/多层修改模式
- 模糊描述（"做个门票"）→ 主动搜索工作区 PSD/Excel 文件，推荐匹配

**文件搜索优先级**:
1. 用户明确指定的路径
2. 工作区 `*.psd` / `*.xlsx` 文件
3. `psd-studio/backend/uploads/` 中的文件

---

### Phase 2: PSD 分析 `[ANALYZE]`

**目标**: 理解 PSD 模板结构，提取所有可编辑元素。

使用 `psd_analyzer.py` 或直接调用 `psd-tools`：

```python
from psd_analyzer import PSDAnalyzer
analyzer = PSDAnalyzer("模板.psd")
analyzer.print_structure()
layers = analyzer.get_text_layers()
```

**必须输出以下分析报告**:

```
📋 PSD 分析报告
═══════════════════════════════════════
文件: 门票.psd
尺寸: 1748×2480 px (300 DPI)
文本图层: N 个

  [1] "姓名"     位置(240,680)  字号48pt  色#FFF  字体:XXX
  [2] "学校"     位置(240,820)  字号36pt  色#CCC  字体:XXX
  ...

智能提示:
  ⚠ "学校"图层最大容纳14个中文字符
  💡 建议使用 XXX 字体或系统黑体作为渲染字体
```

**⚠️ 容量分析**: 检测每个文本图层的字符容量，预判超长风险。

---

### Phase 3: 智能匹配 `[MATCH]`

**目标**: 将 Excel 列自动映射到 PSD 文本图层。

**三级匹配算法**:

```
L1 — 精确匹配 (high):   列名 == 图层名
L2 — 语义匹配 (medium): 同义词库映射
L3 — 位置匹配 (low):    按 PSD 图层顺序对应 Excel 列顺序
```

**同义词库**:
```
名字↔姓名↔Name↔名称
学校↔School↔University↔院校
赛区↔Division↔赛↔赛区名称
编号↔ID↔No↔号码↔序号
标题↔Title↔名称
```

**必须输出匹配报告**，标注置信度，让用户确认。

---

### Phase 4: 预览确认 `[PREVIEW]`

**目标**: 用户在批量导出前看到效果。

执行 dry-run:
```bash
python scripts/batch_from_excel.py 名单.xlsx 模板.psd output/ --dry-run
```

展示前 3 行预览、字体匹配结果、预计输出数、预估耗时。

---

### Phase 5: 批量导出 `[EXPORT]`

**目标**: 高效批量生成所有文件。

**两阶段流水线**:
```
Step 1: 批量 PSD（文本替换）
  Excel → [psd_text_editor] → N 个 PSD

Step 2: 批量 PNG（背景缓存优化）
  模板背景(1次) + N 个 PSD 文字 → N 个 PNG
```

**智能参数推荐**:
| 场景 | 推荐参数 |
|------|----------|
| 中文为主 | `--font AlimamaShuHeiTi-Bold.ttf` |
| 中英混排 | `--font NotoSansSC-Regular.ttf` |
| 深色背景 | `--color 255 255 255` |
| 浅色背景 | `--color 0 0 0` |
| 长文本 | `--size` 比原字号小 4pt |
| 打印 | `--dpi 300` |
| 屏幕 | `--dpi 150` |

---

### Phase 6: 结果验证 `[VERIFY]`

**自动检查**:
1. 文件数 = Excel 行数?
2. 有无 0 字节文件?
3. 随机抽查 N 张：**像素比对**（重新渲染 PSD → PNG 后逐像素 diff）
4. 可选 **分图层 OCR 校验**：按 PSD bbox 裁剪 → Tesseract PSM 7 → 5 级模糊打分比对

**抽查参数**:
```bash
--verify-samples 5      # 抽查样本数（默认 3）
--ocr                   # 启用 OCR 文本校验
--ocr-lang chi_sim+eng  # Tesseract 语言（中英混合推荐 chi_sim+eng）
--tesseract-cmd PATH    # tesseract 可执行路径
--tessdata-dir PATH     # tessdata 目录（含 .traineddata 文件）
```

**OCR 模糊打分（5 级）**:
| 级别 | 方法 | 得分 | 说明 |
|------|------|------|------|
| L1 | exact_full | 1.00 | 归一化后完全一致 |
| L2 | substring | 0.95 | 期望文本是 OCR 结果的子串 |
| L3 | tokens | 0.65–0.85 | Token 级重叠率打分 |
| L4 | fuzzy | 0.60–0.99 | difflib 序列相似度 |
| L5 | alnum | 0.60–0.75 | 仅字母数字的模糊匹配 |

通过阈值：单字段 ≥ 0.6 且 平均分 ≥ 0.7。

**输出验证报告**（`output/xxx/verify_report/`）:
- `report.json` / `report.md` — 完整验证结果
- `renders/` — 抽查重新渲染的 PNG
- `diffs/` — 像素差异图（全黑=完全一致）

---

## 🧩 智能决策矩阵

### 字体选择
```
1. PSD 原字体(已安装) → 使用原字体
2. family match → 使用匹配字体
3. 技能包 fonts/ → 使用自带字体
4. 系统中文(微软雅黑/思源) → 降级使用
5. PIL 默认 → ⚠️ 警告用户(不支持中文)
```

### 颜色/字号
```
未指定 → 从 PSD engine_dict 提取原始值
文本长度 > 原容量×0.8 → 建议缩小字号
```

### 性能优化
```
<10行:  直接逐个渲染
<100行: 背景预渲染 + 批量叠加
≥100行: 背景预渲染 + 多进程(可选)
```

---

## 📂 脚本索引

所有脚本位于技能包 `scripts/` 目录下，路径相对于 SKILL.md 所在目录。

| 脚本 | 相对路径 | 职责 |
|------|----------|------|
| `batch_from_excel.py` | `scripts/batch_from_excel.py` | 一键全流程（分析→匹配→预览→导出→验证→OCR） |
| `ai_designer.py` | `scripts/ai_designer.py` | 从零模板设计（门票/证书/工牌/邀请函/号码牌） |
| `color_tools.py` | `scripts/color_tools.py` | 配色提取/推荐/对比度检查/调色板生成 |
| `smart_layout.py` | `scripts/smart_layout.py` | 自适应排版计算（字号/位置/换行） |
| `psd_style_editor.py` | `scripts/psd_style_editor.py` | 样式编辑（查看/修改/JSON批量） |
| `psd_text_editor.py` | `scripts/psd_text_editor.py` | PSD 二进制文本修改 |
| `render_psd_batch.py` | `scripts/render_psd_batch.py` | PSD→PNG 渲染引擎 |
| `random_check.py` | `scripts/random_check.py` | 独立抽查工具（像素比对+OCR） |

> 💡 运行方式：`python scripts/batch_from_excel.py 名单.xlsx 模板.psd output/`

---

## 🎬 常见场景

### A. 门票/入场券
```
→ 搜索 *.psd → 分析 → 匹配 Excel → 预览 → 导出
```

### B. 邀请函
```
→ 邀请函.psd + 邀请函名单.xlsx → invite_batch.py（长名字支持）
```

### C. 号码牌
```
→ 纯编号(无需Excel) → generate_batch.py 或 number_card_tool.py
```

### D. 证书/奖状
```
→ ai_designer.py --type certificate 生成模板
→ 或 证书.psd + 学员名单.xlsx → 标准 6 阶段流程
```

### F. 从零开始（无 PSD 模板）
```
→ ai_designer.py 生成设计稿 → 可选：导入PSD继续编辑 → 或直接批量填充
```

### G. 仅配色/排版咨询
```
→ color_tools.py --recommend ticket → 获取场景推荐配色
→ smart_layout.py --preset certificate → 查看预设排版方案
```

---

## ⚠️ 故障排除

| 症状 | 原因 | 解决方案 |
|------|------|----------|
| 中文方框 | 字体不支持中文 | 安装中文字体或 `--font` 指定 |
| 位置偏移 | bbox 计算偏差 | `--align center` 居中 |
| 文字截断 | 超 PSD 文本容量 | 减小字号或缩短文本 |
| PNG 模糊 | DPI 低 | `--dpi 300` |
| psd-tools 报错 | PSD 版本不兼容 | PS 重新保存为"最大兼容" |
| 原文残留 | topil() 含文字层 | 用 prerender_background() 跳过 type 层 |

---

## 🔧 依赖

```
psd-tools>=1.9.0    # PSD 读写
Pillow>=9.0.0       # 图片渲染
pandas>=1.0.0       # Excel 读取
openpyxl>=3.0.0     # Excel 写入
pytesseract>=0.3.10 # 可选：OCR 文本校验
```

**系统依赖（OCR 功能）**:

1. 安装 Tesseract 引擎：[UB-Mannheim/tesseract](https://github.com/UB-Mannheim/tesseract/releases)
2. 下载中文语言包 `chi_sim.traineddata` → 放入 tessdata 目录
3. 运行时指定 `--ocr --ocr-lang chi_sim+eng --tesseract-cmd <path>`

---

## 📝 版本

| 版本 | 日期 | 变更 |
|------|------|------|
| 4.3 | 2026-05-31 | 重构模板系统：3款官方PSD模板(日签/邀请函/招聘)+template_loader；ai_designer 改为模板工作台；移除合成模板代码 |
| 4.1 | 2026-05-31 | 新增 design_llm.py（LLM设计适配层）+ ai_designer.py 重构支持 --ai/--prompt/--evaluate |
| 3.2 | 2026-05-31 | 重新定位：从"批量导出工具"升级为"PSD图层级智能引擎"；新增核心能力地图、5类场景矩阵 |
| 3.1.1 | 2026-05-31 | 修复：脚本索引改为相对路径，去除硬编码绝对路径 |
| 3.1 | 2026-05-31 | 分图层 OCR（PSD bbox 裁剪+PSM 7）、5 级模糊打分、像素比对抽查、`--verify-samples/--ocr/--ocr-lang/--tesseract-cmd/--tessdata-dir` CLI 参数、独立 `random_check.py` 工具 |
| 3.0 | 2026-05-31 | 重构为 AI 操作手册：6 阶段系统化工作流、智能决策矩阵、场景模板、故障排除 |
| 2.3 | 2026-05 | 背景预渲染缓存、跨平台字体、dry-run |
| 2.0 | 2026-04 | 自动列匹配、语义匹配 |
| 1.0 | 2026-03 | 初始版本 |