鲸鱼娘图库背后的网站原理:deepseek-whale-girl 的 manifest.json 与 build_gallery.py 静态画廊生成机制

原创2026-11-02 09:06:172,151 阅读
文章标签:媒体生成前端人工智能

鲸鱼娘图库背后的网站原理: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 静态页面,画廊区块由脚本生成

deepseek-whale-girl 鲸鱼娘三视图角色参考图,含正面、侧面、背面与细节特写

这些参考图本身也存放在 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)。

鲸鱼娘社区投稿作品示例:黑底 Q 版鲸鱼娘站姿插画,即 manifest.json 收录的画廊条目

build_gallery.py:24 行脚本如何重写整面图库

有了清单,build_gallery.py 负责把它变成网页。逻辑分四步,非常直白:

  1. 读取两端:载入 site/index.html 全文和 manifest.json;
  2. 逐条生成卡片:跳过 gallery: false 的条目,为每件作品生成一个 <a><img></a> 卡片——带 loading="lazy" 懒加载、data-author / data-handmade 等属性供前端筛选,alt 文本自动拼接"标题(作者:xxx)"保证署名与无障碍访问;
  3. 精准替换区块:用 str.index 定位到首页 gallery-section 到 </section> 之间的画廊区,整段替换,并把作品总数写进"148 张社区作品"的计数;
  4. 写回并汇报:保存 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

登录后查看全文
deepseek-whale-girl