鲸鱼娘图库背后的网站原理:deepseek-whale-girl 的 manifest.json 与 build_gallery.py 静态画廊生成机制
鲸鱼娘图库背后的网站原理:deepseek-whale-girl 的 manifest.json 与 build_gallery.py 静态画廊生成机制
deepseek-whale-girl 是一个由社区共同维护的鲸鱼娘二创资源库,官网的社区画廊没有使用数据库和后端服务器,而是靠一份 manifest.json 作品清单加一个 Python 脚本 build_gallery.py,就把 148 张社区作品"拼装"成了可浏览的静态图库。🐋 这篇文章带你拆解这套静态画廊生成机制,看看它如何让一个纯静态网站也能像动态站点一样持续更新。
先认识一下这个图库:没有后端的鲸鱼娘二创仓库
deepseek-whale-girl 仓库的核心内容分三类:角色参考图(用于二创的设定三视图)、可复制的生成提示词、以及社区投稿作品。其中最"重"的就是首页的社区画廊——每张图都带着作者署名、投稿来源和创作类型(纯人工 or AI 辅助)。
而实现这一切的,只是仓库里的一组静态文件:
| 模块 | 路径 | 作用 |
|---|---|---|
| 作品数据清单 | site/assets/gallery/manifest.json | 画廊的"数据库",记录每件作品的全部信息 |
| 画廊生成器 | tools/build_gallery.py | 读清单,把首页画廊 HTML 整段重写 |
| 投稿导入器 | tools/import_community.py | 从 issue 下载图片、转 WebP、生成候选清单 |
| 站点体检器 | tools/validate_site.py | 一键检查链接、图片尺寸与工作流完整性 |
| 网站首页 | site/index.html | 静态页面,画廊区块由脚本生成 |
这些参考图本身也存放在 characters/ 目录归档,网站则使用 site/assets/ 下的副本——数据、脚本、页面各归其位,是典型的静态站点结构。
manifest.json:一份会"自报家门"的作品清单
整个图库的数据都集中在 manifest.json 里,顶层结构只有 version、updated 和 works 数组。每件作品是一条这样的记录:
{
"id": "issue-54-01",
"issue": 54,
"title": "可爱的鲸鱼娘",
"author": "fxds_AI",
"src": "./assets/gallery/submissions/issue-54-01-preview.webp",
"original": "./assets/gallery/submissions/issue-54-01.webp",
"width": 1736,
"height": 2264,
"handmade": false,
"creationType": "使用了生成式 AI 或 AI 辅助",
"issueUrl": ".../issues/54",
"pixelHash": "461dab26604e49cf..."
}
几个字段的设计尤其值得新手学习:
src与original分离:列表页加载长边不超过 1000 像素的-preview.webp缩略图,点击放大时才加载完整尺寸文件,画廊因此打开飞快;width/height预先写入:图片还没下载时浏览器就知道占位尺寸,瀑布流布局不会抖动;handmade布尔值:标记纯人工创作,前端据此实现"手搓专区"筛选;pixelHash像素指纹:对图片像素做 SHA-256,用于去重和防篡改;gallery: false开关:多格总览图保留在清单和目录里但不占展位,避免与单张重复展示(详见 site/assets/gallery/README.md)。
build_gallery.py:24 行脚本如何重写整面图库
有了清单,build_gallery.py 负责把它变成网页。逻辑分四步,非常直白:
- 读取两端:载入 site/index.html 全文和 manifest.json;
- 逐条生成卡片:跳过
gallery: false的条目,为每件作品生成一个<a><img></a>卡片——带loading="lazy"懒加载、data-author/data-handmade等属性供前端筛选,alt文本自动拼接"标题(作者:xxx)"保证署名与无障碍访问; - 精准替换区块:用
str.index定位到首页gallery-section到</section>之间的画廊区,整段替换,并把作品总数写进"148 张社区作品"的计数; - 写回并汇报:保存
index.html,打印Built N gallery entries。
核心生成逻辑就是 build_gallery.py 这几行模板拼接:
cards.append(f'<a id="{esc(work["id"])}" href="{esc(work["original"])}" ...><img src="{esc(work["src"])}" alt="{esc(caption)}" width="{work["width"]}" height="{work["height"]}" loading="lazy" /></a>')
注意这里全程做了 html.escape 转义——作者名里哪怕出现引号或尖括号也不会破坏页面结构。
这套设计的巧妙之处是:HTML 里写死了图片,JavaScript 只是锦上添花。即使完全禁用 JS,访客依然能看到全部静态图片;而 site/script.js 会在卡片基础上叠加随机排序、手作筛选、复制/下载按钮和放大查看等交互(见 script.js 的画廊初始化逻辑)。
import_community.py:图片如何从投稿变成画廊条目
新作品不是手工填 JSON 的。import_community.py 实现了"机器收集、人工审核"的入库流水线:
- 通过
gh issue list拉取指定编号的投稿 issue 与评论,用正则抽出其中的图片链接; - 每张图经 EXIF 方向修正后存为 WebP:完整尺寸
quality=95一份、长边缩至 1000 像素的预览版一份; - 从投稿表单中提取"作品名称、作者、原始来源、是否纯人工创作"等字段,连同尺寸和
pixelHash写成候选清单imported.json,并生成 6×4 缩略联系表供维护者肉眼复核; - 文件名按
issue-NN-MM规则编号,已存在的同名文件会直接报错而不是覆盖。
维护者审核通过后才把条目并入正式 manifest,再跑生成与校验——这就是"投稿不会即时自动出现"的原因,也是社区图库保持质量的关键环节。
validate_site.py:发布前的自动体检
改完清单、重建页面之后,validate_site.py 是一道质量门,它只依赖标准库,覆盖五类检查:
| 检查项 | 防住的问题 |
|---|---|
清单 id 唯一、尺寸合法、src/original 文件存在 |
数据写错或图片漏提交 |
页面所有本地链接可解析、锚点存在、图片有 alt |
死链与可访问性缺失 |
| 每件上架作品必须在首页有对应卡片 | manifest 与页面不同步 |
| ComfyUI 工作流恰好 6 个、seed 与文件名一致、连线合法 | 工作流包损坏或被改坏 |
| 全文正则扫描疑似密钥 | 意外泄露 API key |
最后输出一行 JSON 摘要(页面数、画廊数、手作数、错误列表),方便接进 CI。
本地预览:两条命令跑起完整图库
想亲手体验这套机制?克隆仓库后只需要 Python 3:
python -m http.server 4173 --directory site
然后访问 http://localhost:4173 即可浏览画廊。若修改了 manifest,接着运行:
python tools/build_gallery.py # 重建首页静态画廊
python tools/validate_site.py # 体检全站
确认无误再推送。仓库通过 .github/workflows/pages.yml 定义的自动化流程,在推送到 main 分支后把 site/ 目录自动部署为线上站点,手动触发同样可用。
总结:小脚本撑起大图库
deepseek-whale-girl 的图库值得每个做静态站的新手参考:
- 数据与呈现分离:
manifest.json是唯一事实来源,页面画廊只是它的投影,重跑build_gallery.py永远能还原; - 静态兜底、JS 增强:无 JavaScript 也能看全部图片,交互层层叠加;
- 缩略图 / 原图分级加载:预览图小、原图大,性能与画质兼得;
- 入库有人审、发布有校验:
import_community.py收集、validate_site.py把关,小社区也能有工程级的质量保障。
关键文件速查:manifest.json · build_gallery.py · import_community.py · validate_site.py · 画廊说明 README



