# G01 列表背景候选与换机重建

> 日期：2026-07-16  
> 状态：三个母版已生成并通过本机确定性构建；尚未由用户选择，不得接入页面或写成已验收。

## 1. 为什么重做

现有 `footer-mountain-bamboo.png` 为 `750×360`，视觉主体集中在底部，上半部留白较大；页面又把它定位到整个内容末尾并使用 `scaleToFill` 拉伸，因此列表变长时山水被推到“添加家谱”下方。用户提出背景应更早出现，并进一步提出 G01 可能只滚动下方列表、上方当前家谱与快捷入口固定。

滚动结构暂不实施。新背景先作为列表滚动窗口候选资产保存，下一轮选择方向并确认滚动边界后再接入。

## 2. 稳定输入

三个母版位于：

- `docs/design/assets/g01-background/masters/g01-list-background-direction-a-chroma-master.png`
- `docs/design/assets/g01-background/masters/g01-list-background-direction-b-chroma-master.png`
- `docs/design/assets/g01-background/masters/g01-list-background-direction-c-paper-master.png`

准确提示词、标题、处理模式、源尺寸和生成输出路径由 `design-pipeline/manifests/g01-background-candidates.json` 单一维护。A/B 使用纯 `#00ff00` 绿幕并提取透明叠加层；C 保留完整暖宣纸底。

## 3. 跨电脑重建

要求：Windows、Node.js 22+、npm、Python 3.12+。本机验证环境为 Node `24.15.0`、npm `11.12.1`、Python `3.14.6`、Pillow `12.3.0`。

在项目根目录执行：

```powershell
python --version
node --version
npm.cmd --version
python -m venv design-pipeline/.venv
design-pipeline/.venv/Scripts/python.exe -m pip install --upgrade pip
design-pipeline/.venv/Scripts/python.exe -m pip install -r design-pipeline/requirements.txt
npm.cmd --prefix design-pipeline run build:g01-background-candidates
design-pipeline/.venv/Scripts/python.exe -m unittest design-pipeline/tests/test_build_g01_backgrounds.py -v
node --test design-pipeline/tests/g01-background-candidates.test.mjs
```

构建输出进入已忽略目录 `design-pipeline/generated/g01-background/`：

- `g01-list-background-direction-a.png`
- `g01-list-background-direction-b.png`
- `g01-list-background-direction-c.png`
- `build-report.json`

Node 入口只使用内置模块做路径与清单编排；图片解码、尺寸检查和像素处理由锁定版本的 Pillow 统一负责，因此 G01 候选构建不依赖已删除的 `node_modules`。项目其他使用 Sharp 的旧流水线仍需执行 `npm.cmd ci --prefix design-pipeline`。

## 4. 当前质量基线

本机输出：

| 候选 | 模式 | 像素 | 字节 | SHA-256 |
| --- | --- | ---: | ---: | --- |
| A | chroma-key | 1024×1536 | 2,280,297 | `7b8a8abecc651b1bc4c589607780c8ff00ea0f13de018ca4b27a479b2a870fe4` |
| B | chroma-key | 1024×1536 | 1,890,556 | `3a0420eaaac9a2821da0f9a2ddbbbd6fb29b463fa6f41be7fa5c23948f782e2a` |
| C | opaque-paper | 1024×1536 | 2,407,477 | `f14aeed81046d2d5e7ae78b1e62f572689c38261a2cc043142bef9f70200dc5b` |

三张输出均满足：可见绿幕残留 0、透明 RGB 0、尺寸错误 0、体积错误 0、sRGB 警告 0。本机连续构建两次的报告与文件 SHA-256 完全一致。若另一台电脑因 Python、Pillow 或压缩实现差异产生不同文件哈希，应先核对锁定依赖，再比较解码后的 RGBA 像素和质量报告，不能只凭压缩字节差异判定视觉失败。

## 5. 可复现边界

- 精确可复现：从仓库内保存的母版执行清单、Python 和 Node 流程，得到相同 RGBA 像素处理结果。
- 方向可复现但非逐像素：在另一台电脑上使用清单中的提示词重新调用图像模型。
- 不可依赖：Codex 本机生成目录、`tmp/`、`node_modules/`、`.venv/`、`generated/` 或未进入仓库的聊天图片。

## 6. 下一步

1. 用户比较 A/B/C 后选择一个方向，或提出组合要求。
2. 选择后只保留一个正式母版合同，创建版本化 `static/assets/` 运行输出。
3. 再讨论并实现：标题栏、当前家谱大卡片和快捷入口固定；从“我创建的”开始独立滚动；背景固定在列表滚动窗口背后。
4. 完成 320×568、360×640、360×800、412×915 H5 截图和 Android/HBuilderX 复核。