人物个人主页生成器（单文件 HTML）

把结构化的人物资料（Markdown/Word 汇编）加上一批写真图片，产出一个自包含的 HTML 文件——无 CDN、无外链、双开即用、可离线浏览、可直接拖进浏览器或打包分享。

这个 skill 来自一次真实的完整交付（「杨紫 · 演员主页」，约 121 KB / 8 个版块 / 12 个 JS 交互模块）。下面记录的是当时踩过的坑和算过的账，照着做能省掉一整轮返工。

一、什么时候用

用：
- 用户给了一份人物资料（.md / .docx / 一段文字），要"做成网页/主页/档案页"
- 用户给了一个写真图片文件夹，要"配上这些人物的图做页面"
- 用户要"明星个人主页""艺人资料页""作品集页面"这类长页面、单页滚动、带动画
- 用户要求"单文件、不要依赖外网、离线能开"

不用：
- 只是要个简单介绍页（一屏搞定）→ 直接写 HTML 就行，不必上这一整套
- 需要后端、需要动态数据、需要登录 → 这是纯静态页方案
- 用户明确要 React/Vue 工程 → 走工程化路线

二、输入物清单（先对齐，再动手）

动手前必须确认这 4 项，缺一项就先问用户，不要猜：

资料 → 版块的映射规则

一份好的人物汇编通常已经分好章节。章节直接映射成 section，不要重新编故事：

三、产出规格（硬指标）

<姓名>-个人主页.html      ← 单文件，全部 CSS/JS 内联
图片/                     ← 与 HTML 同级目录，相对路径引用

必须满足：
- ✅ 单文件自包含：CSS 内联在 <style>，JS 内联在 <script>，不允许任何 <link href="http..."> 或 <script src="http...">
- ✅ 图片用相对路径 图片/xxx.jpg，不用 base64（会让文件膨胀到几 MB）
- ✅ 移动端可用：@media (max-width:767px) 全套适配
- ✅ 无 JS 兜底：<html class="js-enabled"> 由内联脚本开启，动画元素在无 JS 时保持可见
- ✅ 尊重 prefers-reduced-motion
- ✅ 文件大小 80–150 KB 属于正常区间

四、执行流程

Step 1 · 侦察输入

# 列压缩包内容（不直接解压到用户目录）
python -c "
import zipfile
z = zipfile.ZipFile(r'D:\xxx.zip')
for n in z.namelist(): print(n)
"

读资料 md，同时统计图片数量与格式——这一步决定后面轮播几张、有没有 heif 要转。

Step 2 · 处理图片（最关键的前置步骤）

# 检查是否有 heif/heic（浏览器不支持，必须转）
python scripts/check_images.py <图片目录>
# 转 heif → jpg
python scripts/convert_heif.py <图片目录>

pillow-heif 安装与坑见 references/pitfalls.md（有独立的 sys.path 技巧）。

给图片起可读的名字：yangzi-05.jpg 比 20210808004054_da82d.jpg 好，方便后续引用和复用。转换时顺手重命名。

Step 3 · 规划版块

按第二节的映射表列出版块顺序，先算清楚每行放几张（见 references/layout-math.md）。这一步不规划，后面必然返工——卡片数量与栅格列数必须同时定。

Step 4 · 写 HTML

分三次写，不要一次性写完：

1. Write 写 <head> + 全部 CSS（:root 变量 → 基础重置 → 组件样式 → 响应式）
2. Write 或追加 写 <body> 结构（导航 → 各 section → 页脚 → 弹层）
3. 追加 写 <script> 交互模块

> ⚠️ 单次写入上限约 8 万字符，超了会被静默截断。HTML 超过这个量必须分段追加。见 references/pitfalls.md。

详细写法见 references/architecture.md（结构）与 references/interactions.md（12 个 JS 模块的完整实现）。

Step 5 · 自检

python scripts/validate_page.py <输出的html>

检查项：外链残留、图片路径是否存在、section id 与导航锚点是否一一对应、data-count 与文案数字是否一致。

Step 6 · 交付

用 present_files 打开预览。同时把 HTML 和 图片/ 一起说清楚——只给 HTML，用户挪动文件后图片会全挂。

五、移植参考模板的铁律

用户常给一个现成模板（如模板王系列）说"照这个效果做"。只抄手法，不抄依赖：

模板的静态资源文件（*_files/ 目录）不要跟着复制进产出，否则文件从 120KB 变成 500KB+ 且依赖本地路径。

六、配色系统

默认紫白主题，用户没指定就照这个用：

--primary:#8b5cf6;  --primary-deep:#6d28d9;  --primary-soft:#a78bfa;
--accent:#c084fc;   --purple-ink:#2e1065;
--bg-primary:#ffffff;  --bg-secondary:#faf7ff;  --bg-tertiary:#f3efff;
--border-color:#ece5f9;
--gradient-text:linear-gradient(120deg,#8b5cf6 0%,#a855f7 45%,#6d28d9 100%);

换色只需改这一组变量，全站跟着变——这是整个方案里最值得保留的设计。具体色板与对比度要求见 references/design-system.md。

七、内容红线（重要）

做人物主页很容易碰到版权与隐私，产出时必须带上：

1. 页脚免责声明：个人学习/资料归档用途，不作商业使用，图片版权归原权利人所有
2. 资料时效声明：奖项与播出信息以官方最终公布为准
3. 若资料含肖像权维权、争议事件：原样呈现事实与工作室声明，不做主观评价、不站队
4. 不臆造资料：汇编里没有的奖项、作品、数据一律不加。宁可版块少一个，也不编

八、参考文档