Photo Spread Composer

---
name: photo-spread-composer
description: 当使用者说"把这些照片排成一版"、"做一张照片展示海报"、"仿报纸摄影版那种排版"、"这组照片怎么摆"、"做个 photo essay 的版面"时使用。输入一组照片加署名，分两步：先产出 spread-plan.md（分带、定主次、排序、每带的图注与署名、被舍弃的照片及原因），等确认后再产出单文件 spread.html（照片按需缩放并内联，可打印成 PDF）。这个 skill 不提供固定版式——它给的是带状构图的语法与协议，具体谁大谁小、分几带、怎么排由模型和使用者判断。每张照片必须有署名，分辨率不足会被拦下。只想把自己拍的 3–9 张按原顺序拼成一张长图、网格或一页 PDF，不要分带主次和署名时，用 photo-series-layout。
category: coding-helper/ui-design
version: 0.1.2
status: draft
priority: P2
compatible_agents:
  - claude-code
  - cursor
  - codebuddy
  - generic-llm-agent
display_name: 照片版面
outputs:
  - chat
max_rounds: 30
suggest_hint: 有一组照片要排版？用「照片版面」先定主次分带，再出可打印的单文件海报
---

# 照片版面 / Photo Spread Composer

把一组照片排成报纸摄影版那样的展示版面：分带、定主次、justify 到版心两边齐平。

## 这个 skill 不给版式，给语法

**最重要的一条：不要把位置写死。**

一张好的照片版面，谁占最大格、分几带、哪张打头，取决于这一组照片本身——
哪张有决定性瞬间、哪张的留白能接住图注、哪两张放一起会打架。这些是**每次都不同的判断**，
写成模板就等于把判断替使用者做了，而且做错的概率是百分之百。

所以这里给的是：

- **协议**（Protocol）：数据契约、两个阶段、产出契约。这部分是死的，可被脚本校验
- **语法**（Conventions）：让版面成立的不变量。带怎么构成、图注归谁、层级靠什么建立
- **留给判断的**：分几带、谁是主角、怎么排序、裁不裁、强调色用什么。**这些必须现场决定**

下面第三节专门列了"留给判断的"清单。看到那节里的项目，**不要去别处找标准答案，就地判断**。

## 何时使用 / When to use

- 手上有一组照片（活动记录、专题、日常）要排成一版展示
- 要做摄影墙、社团刊物的摄影版、影展前言页
- 已有一版要调主次或换页面尺寸

**不适用于** / Not for：

- 单张照片：写图注或作品说明 → 用 `photo-caption-writer`；加拍摄参数边框 → 用 `photo-exif-frame`；做成极简几何海报 → 用 `photo-poster-stylist`
- 自己拍的 3–9 张，只想按原顺序拼成一张长图、网格或一页 PDF，不要分带主次、不逐带署名 → 用 `photo-series-layout`。
  反过来，要刊物或展板那样分带、定主次、每带带署名的版面，或者照片超过 9 张，才用这个 skill
- 产品卖点或研究结果收成一张总结图 → 用 `bento-infographic`
- 整套演示 → 用 `keynote-deck-builder`
- 要修图、调色、批量处理 → 这个 skill 只排版，不改动照片内容

## 输入 / Inputs

| 输入 | 必填 | 说明 |
|---|---|---|
| 照片文件 | 是 | 目录或路径清单。先跑 `measure_photos.py` 量一遍 |
| 署名 | **是** | 每张或每组的拍摄者。**没有署名不上版**，见边界 |
| 每带一句说明 | 是 | 这一带拍的是什么。写不出来说明这几张不该在一起 |
| 页面尺寸 | 否 | 默认 A3 纵向 297×420mm。海报可给 A2，刊物给 A4 |
| 刊头信息 | 否 | 栏目名、期号、页码。**不要用真实出版物的报头**，见边界 |
| 强调色 | 否 | 不给就问，或按照片主色定 |

**脚本依赖**：Python 3 和 Pillow（`python3 -m pip install Pillow`）。`scripts/image_io.py` 是和摄影类 skill 共用的读图模块，
要和两个脚本放在同一个目录。

**HEIC**（iPhone 默认格式）要装 pillow-heif 才读得了。没装时先转一份 JPEG：
`sips -s format jpeg IMG_0001.HEIC --out IMG_0001.jpg`（macOS 自带，保留 EXIF），plan 里写转出来的文件名。
两个脚本遇到 HEIC 都会报出这条命令，不会静默跳过。

只有两件事需要问，其余从材料读：

1. **给谁看、挂在哪**（打印张贴 / 刊物内页 / 屏幕浏览）——这决定页面尺寸与最小复制尺寸
2. 有没有必须上版的照片，或必须回避的人物与场景

---

## 协议 / Protocol

这一节是死的。脚本按这个契约工作，不要改结构。

### 阶段一：`spread-plan.md`

用 `templates/spread-plan.md` 起草。**这一步不写任何 HTML，不生成 JSON。**

写完停下等确认。哪张照片当主角是整件事里最需要使用者拍板的判断，
一步做到底等于把它藏进 HTML 里。

### 阶段二：`plan.json` + `spread.html`

确认之后把计划翻译成 `plan.json`，跑脚本产出 HTML。

**`plan.json` 的数据契约**：

```json
{
  "page":  { "width_mm": 297, "height_mm": 420, "margin_mm": 18,
             "gutter_mm": 3, "dpi": 300 },
  "bands": [
    { "caption": "这一带拍的是什么",
      "credit":  "摄影：某某、某某",
      "items": [
        { "type": "photo", "src": "a.jpg" },
        { "type": "stack", "src": ["b.jpg", "c.jpg"] },
        { "type": "text",  "width_mm": 38, "title": "…", "byline": "…", "body": "…" }
      ] }
  ]
}
```

三种 item，够表达这一类版面的全部结构：

| type | 是什么 | 宽度怎么定 |
|---|---|---|
| `photo` | 一张照片 | 由长宽比与带高解出 |
| `stack` | 竖向叠放的一组，共用一个宽度 | 由组内各图长宽比与带高解出 |
| `text` | 文字栏（作品自述、创作说明） | 固定 `width_mm` |

### 带高是解出来的，不是拍出来的

一带之内所有 item 等高、左右顶到版心边缘。给定版心宽 `W`、天沟 `g`、
`n` 个 item，带高 `h` 由这个方程唯一确定：

```
h · [ Σ aᵢ + Σ 1/Sⱼ ] = W − (n−1)·g − Σ wₖ + Σ (mⱼ−1)·g / Sⱼ

  aᵢ   photo 的长宽比（宽/高）
  Sⱼ   stack 内各图 1/长宽比 之和，mⱼ 为该 stack 的图数
  wₖ   text 栏的固定宽度
```

**这是这套版面唯一的硬约束。** 其余全是判断。
`build_spread.py` 解这个方程，所以**你永远不需要手写任何一个位置或尺寸**。

### 产出契约

- 单文件 HTML，照片按实际显示尺寸缩放后内联为 base64，**离线打开完全一致**
- `@page` 按 `plan.json` 的页面尺寸设置，浏览器打印即得正确开本的 PDF
- 分辨率不足的照片**不会被静默放大**，脚本报错并列出缺多少像素
- 照片先按 EXIF 方向转正再量、再缩放：手机竖拍按竖图算带高，内联后也是竖的
- 每张内联照片保留自己的 ICC 配置文件（iPhone 的 Display P3 仍标 Display P3，浏览器显示和打印成 PDF 都按它解释）；
  没有配置文件的标成 sRGB，灰度与 CMYK 配置文件转成 sRGB；透明区域铺纸色。脚本最后一行"色彩："报告每种处理各几张
- `plan.json` 里写错的键、非数字的尺寸会直接报错，不会被静默忽略

---

## 版面语法 / Conventions

让这类版面成立的不变量。**违反这些，做出来就不是这个东西了**；
在这些之内，怎么排都对。

**G1 带状堆叠。** 版面是若干横带自上而下堆叠；一带之内横向排列、等高、两端顶齐。
不要做成瀑布流或自由拼贴——两端顶齐是这类版面的骨架。

**G2 一带一主角。** 每带里应当有一个 item 面积明显最大。
三张一样大的照片摆一排，这一带就没有主语。（**哪一张当主角是判断**，见下一节。）

**G3 层级只靠面积。** 不加边框、不加阴影、不加圆角、不加白边。
照片之间只有天沟。想强调就给更大的面积，不要靠装饰。

**G4 天沟恒定。** 全页一个天沟值，横竖相同。带与带之间的间距等于天沟，
或等于天沟的整数倍——不要每处都不一样。

**G5 图注归带不归张。** 图注贴在它所描述的那一带**下方、左对齐**，小字号。
一带里若干张照片共用一条图注，说明它们是一组；说不出这组共同讲什么，
就该拆成两带。

**G6 署名必留。** 每带带署名。多人拍摄按出现顺序列。
署名是事实不是装饰，**不能因为版面挤就删掉**。

**G7 一支强调色。** 强调色只给栏目名与大标题，图注与正文用黑。
照片本身已经提供全部色彩，版面再上色就是打架。

**G8 文字栏入列。** 作品自述这类文字栏是带内的一个 item，与照片等高，
按同一套天沟对齐。不要让文字浮在照片上或压边。

**G9 页面家具要轻。** 页码、栏目名、期号排在顶部一条细线上下，小字号。
它们是坐标不是内容。

**G10 顶到版心。** 所有带左右都顶到版心边缘。
不要让某一带比别的窄一截——那看起来像没排完。

---

## 留给判断的 / Left to judgment

**看到这一节里的项目，就地判断，不要去找标准答案。**
这个 skill 故意不给这些的默认值，因为它们由这一组照片决定。

| 判断项 | 判断依据 |
|---|---|
| 分几带、每带几张 | 内容能不能归成一句话。一带一个主题 |
| 哪张当主角 | 哪张信息最完整、瞬间最强、或留白最能接住图注 |
| 带的顺序 | 通常强的打头、强的收尾，中间给密度。也可以按时间或叙事排 |
| 裁不裁、裁成什么比例 | 裁掉的必须是真的没用的部分。**裁法要写进 plan** |
| 用不用 stack | 有一张竖构图想占两带高度时用 |
| 要不要文字栏 | 有作品自述或需要展开说明时用 |
| 强调色 | 照片的共同色调、场合、或使用者指定 |
| 字号级差 | 标题与图注拉开三档以上即可，具体值自己定 |
| 页面尺寸 | 由"挂在哪"决定 |

两条判断上的经验，**是提示不是规则**：

- 相邻两张构图方向相同（都往右冲）会互相抵消，错开或换序
- 人脸朝向最好朝向版心内侧，朝外会把视线带出版面

---

## 分辨率与印刷

`build_spread.py` 会按解出的显示尺寸算每张照片需要多少像素：

```
需要的像素宽 = 显示宽度(mm) ÷ 25.4 × dpi
```

- 打印默认 `dpi: 300`。屏幕浏览可降到 `150`
- **不足就报错，不静默放大。** 放大后打印出来是糊的，而使用者在屏幕上看不出来
- 通过的照片会被缩到实际需要的尺寸再内联，所以成品文件不会因为塞了原图而爆掉

---

## 事实与署名 / Credits and captions

1. **每张照片都要有署名。** 查不到作者的照片不上版，不写"佚名"蒙混
2. **图注只写看得见的事。** 时间、地点、事件、人物，都要有出处；
   不确定的写不确定，不要为了句子顺就补细节
3. **不替照片编故事。** "队员们在赛后相拥"可以，"队员们为失利而落泪"不行——
   除非使用者确认当时确实如此
4. **人物可辨识时先问。** 尤其是未成年人、非公开场合、以及会让当事人难堪的画面
5. **裁切要记录。** 改变长宽比会改变内容的含义，plan 里写清楚裁了哪边

---

## 边界 / Boundaries

- **不用没有授权的照片。** 只排使用者自己拍的或明确有权使用的。
  网上找图、截取他人作品一律拒绝
- **不去水印、不抹署名、不裁掉角落的作者标记**
- **不复制任何真实出版物的报头、刊名、商标或版式识别。**
  这类版面的语法（带状构图、图注惯例）是通用做法，可以借鉴；
  但产出物不能让人误以为是某一家刊物的某一期。
  使用者要求"做得跟某某报一模一样"时，做语法不做身份
- **不编造署名、图注、日期或事件**
- **不修改照片内容**：不调色、不合成、不移除画面里的东西。这个 skill 只排版
- **不静默放大**低分辨率照片
- **不在阶段一就生成 HTML 或 JSON**

---

## 输出格式 / Output

阶段一：

```markdown
先按这组照片排了一版分带方案：

<spread-plan.md 全文>

**我拿不准的：**
- <哪张当主角的取舍>
- <被舍弃的照片及原因>

确认之后我生成 spread.html。
```

阶段二：

```markdown
版面已生成：<文件路径>

- 页面：<尺寸>，<n> 带，共 <m> 张
- 主次：<每带的主角是哪张>
- 分辨率：全部通过 / <哪几张不足，缺多少>
- 未用：<没上版的照片及原因>
- 导 PDF：浏览器打开后 Cmd+P，纸张选<尺寸>，边距选无，勾选背景图形
```

## Token 控制 / Token discipline

- 先跑 `measure_photos.py` 拿长宽比与像素，**不要把照片本身读进上下文**
- 阶段二只读 plan 和模板
- 调整某一带就改 `plan.json` 里那一带重跑，不重新规划整版

## 参考资料 / References

- `references/layout-grammar.md` —— 语法逐条的来由，以及带高方程的推导
- `templates/spread-plan.md` —— 阶段一骨架
- `templates/spread.html` —— 版面语法的 CSS 实现（**没有任何写死的位置**）
- `scripts/measure_photos.py` —— 量长宽比、像素、EXIF 署名，标出不可用的
- `scripts/build_spread.py` —— 解带高方程、查分辨率、缩放内联、出 HTML
- `scripts/image_io.py` —— 与摄影类 skill 共用的读图模块（EXIF 方向、ICC、HEIC 提示）。各副本逐字节相同，不要只改这一份

三个脚本都有 `--selftest`，改动后先跑一遍。

## 变更记录 / Changelog

| 版本 | 日期 | 变更 | 类型 |
|---|---|---|---|
| 0.1.2 | 2026-10-10 | 分流改指 `bento-infographic`（`launch-summary-panel` 已废弃） | patch |
| 0.1.1 | 2026-09-26 | 脚本改走共用 image_io：按 EXIF 方向转正（竖拍不再横躺、带高不再按横图算），保留 ICC、透明铺纸色，HEIC 与缺图给出可读提示；修模板注释里的占位字面量导致整版照片注入两次；改用 argparse 并补 --selftest；单张照片改指 photo-caption-writer / photo-exif-frame / photo-poster-stylist，补与 photo-series-layout 的判别句；注明 Pillow 依赖 | patch |
| 0.1.0 | 2026-08-21 | 初始草稿。协议与语法分离，位置全部由带高方程解出，主次与分带留给判断 | minor |