个人网站搭建
引导新用户将作品集部署到 https://<他们的用户名>.github.io。架构固定,但外观、文案和聊天机器人角色都可以根据具体用户进行定制。
他们能得到什么
- 单页静态网站,无需打包工具。GitHub Pages 直接从仓库根目录提供
main分支服务。 - 英雄区 — 包含用户头像 + 姓名 + 一行位置 + 一行标语。
- 项目区域,顶部为纵向时间线(工作经历用扳手图标,教育经历用书本图标,兴趣/副项目用闪光图标;每个节点显示公司、职位、日期和地点),主体为项目卡片网格 — 两者均从用户的简历生成。
- 时间线 ↔ 卡片筛选 — 悬停或键盘聚焦一个时间线节点可隐藏无关的项目卡片;点击可固定筛选结果(再次点击清除)。只有关联了至少一个卡片的节点才会成为可交互状态,其他节点保持静止。
- 折叠卡片 — 每个项目卡片默认只显示其类别 + 标题 + 工具标签;摘要段落和指标行在悬停/聚焦时显示,保持网格的可扫描性。
- 聊天机器人(可选) — 浮动在右下角的启动按钮 + 弹出式面板(非内联页面部分),后端由 DeepSeek 的 OpenAI 兼容 API 驱动,并通过持有 API 密钥的 Cloudflare Worker 托管。用户选择机器人名称;代理程序会提议一个匹配的表情符号头像。机器人回复渲染 Markdown。双层速率限制。
- 联系区域 — 邮箱 + 用户的社交 URL。
前置条件
| 需要用于 | 工具 | 安装方式 |
|---|---|---|
| 所有操作 | git | 通常已安装 |
| 所有操作 | GitHub 账户 + gh 命令行工具 | brew install gh 然后 gh auth login |
| 所有操作 | python3(本地预览) | 通常已安装 |
| 聊天机器人 | Cloudflare 账户(免费套餐) | https://dash.cloudflare.com |
| 聊天机器人 | wrangler 命令行工具 | npm install -g wrangler 然后 wrangler login |
| 聊天机器人 | DeepSeek API 密钥 | https://platform.deepseek.com/ → API keys |
| 头像调整 | Node.js | brew install node |
分步指南
1. 收集用户输入
在接触任何文件之前执行此步骤。 一次性收集所有信息,以便后续步骤进行自动化编辑。对选择题使用 AskUserQuestion,对自由文本使用直接提示。
从用户那里获取以下每一项:
| 输入 | 询问方式 | 示例 |
|---|---|---|
| GitHub 用户名 | 直接提示 | jane(仓库将是 jane.github.io) |
| 显示名称 | 直接提示 | Jane Doe 或 Jane "JD" Doe |
| 位置短语 | 直接提示,简短 | NYC 都会区、远程、东京 |
| 标语 | 直接提示,一句话 | 我构建 ML 系统并热爱交付产品。 |
| 简历 | 粘贴文本或文件路径 | 完整的简历 — 用于填充时间线、项目卡片、聊天机器人知识库 |
| 照片 | 磁盘上的方形图片路径 | /Users/jane/Desktop/headshot.jpg。用户克隆后可将其放在仓库根目录下,命名为 raw.jpg。 |
| 社交 URL | 直接提示,每项可选 | LinkedIn / GitHub 个人主页 / Medium / 个人邮箱 |
| 聊天机器人? | AskUserQuestion | 是 / 否 |
| 聊天机器人名称(如果是) | 直接提示 | Pot、Nova、Echo 等 |
| 视觉风格 | AskUserQuestion | "粘贴一个我喜欢的 URL" 或 "用文字描述" |
收集聊天机器人名称后,提议 2-3 个在主题上匹配的表情符号头像,让用户选择。示例:
| 名称 | 提议的头像 |
|---|---|
| Pot | 🫖(茶壶)· 🍲 · 🎨 |
| Nova | 🌟 · 💫 · 🌠 |
| Echo | 📣 · 🔊 · 🌀 |
| Ember | 🔥 · 🪵 · ✨ |
| Atlas | 🗺️ · 🧭 · 🌍 |
| Bit | 💾 · 🔢 · 🤖 |
| Sage | 🌿 · 📖 · 🦉 |
如果没有明显合适的,提供中性选项:🤖、💬、🪄。保存所选的表情符号 + 名称 — 稍后您需要将它们写入代码中。
2. 创建 GitHub 仓库
gh repo create <用户名>.github.io --public --description "个人网站"
GitHub Pages 用户站点必须在 <用户名>.github.io。
3. 克隆模板
git clone https://github.com/donotdonuts/donotdonuts.github.io my-site
cd my-site
rm -rf .git
git init -b main
git remote add origin https://github.com/<用户名>/<用户名>.github.io.git
4. 选择视觉风格
模板默认为米色 + IBM Plex Mono 美学。根据用户在步骤 1 的答案覆盖它。
4a. 如果用户提供了 URL
拉取页面的 CSS 并提取令牌:
curl -sL "<url>" -o /tmp/ref.html
grep -oE 'href="[^"]+\.css[^"]*"' /tmp/ref.html | sort -u
curl -sL "<来源>/<css-路径>" -o /tmp/ref-1.css
# 实际应用于 `body` 的字体
grep -oE 'body[^{]{0,30}\{[^}]+\}' /tmp/ref-1.css | head -5
# 所有 CSS 自定义属性定义
grep -oE -- '--[a-zA-Z-]+:[^;}]+' /tmp/ref-1.css | sort -u | head -60
查找:背景十六进制色、前景/墨色十六进制色、边框十六进制色、强调色十六进制色、应用于 body 的 font-family、@font-face URLs。
4b. 如果用户提供了文字描述
将描述转换为具体的令牌。启发式方法:
| 词语 | 含义 |
|---|---|
| "极简主义"、"编辑风格"、"纸张" | 米色/灰白色背景,深色墨色,细分割线 |
| "深色"、"终端"、"IDE" | 近黑色背景 (#0f1115),浅色墨色,微妙的灰色边框 |
| "温暖"、"模拟感" | 略带黄色的米色 (#faf5e8),棕黑色墨色 |
| "粗野主义" | 纯白或纯黑,2px+ 实线边框 |
| "科技感"、"数据" | 等宽字体(IBM Plex Mono、JetBrains Mono),冷灰色调 |
| "杂志"、"编辑" | 衬线字体(EB Garamond、Fraunces),宽大的行距 |
| "俏皮" | 一种饱和的强调色,其余部分柔和 |
4c. 提议 + 应用
编译 13 个令牌 + 一个字体栈。在编辑文件之前,以代码块形式展示提议的调色板,并获得用户批准。
:root {
--bg: <十六进制色>; /* 页面背景 */
--bg-soft: <十六进制色>; /* 子面板 — 通常 --bg 与 --ink 混合约 3% */
--bg-hover: <十六进制色>; /* 标签/芯片悬停 */
--card-bg: <十六进制色>; /* 不透明卡片填充(浅色主题下为白色) */
--ink: <十六进制色>; /* 主要文本 */
--ink-soft: <十六进制色>; /* 约为 --ink 的 80% */
--ink-mute: <十六进制色>; /* 约为 --ink 的 60% */
--ink-faint: <十六进制色>; /* 约为 --ink 的 40% */
--border: <十六进制色>; /* 微妙的间隔线 */
--border-strong: <十六进制色>; /* 承重间隔线 */
--up: <十六进制色>; /* 正向指标(默认偏绿) */
--down: <十六进制色>; /* 负向指标(默认偏红) */
--accent-ink: <十六进制色>; /* 链接 */
--font-mono: "<字体族>", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
}
然后:
- 打开
css/styles.css,找到:root块,替换值。 - 打开
index.html,用新的字体族 + 字重更新<head>中的 Google Fonts<link>。
5. 根据简历 + 输入生成内容
使用步骤 1 中的简历和其他输入填充 index.html:
-
<head>—<title>=<显示名称> — <简历中第一个职位>;<meta name="description">来自标语。 -
英雄区:
<h1 class="hero-title">← 显示名称<p class="hero-location">← 位置短语<p class="hero-tagline">← 标语
-
时间线 — 将简历解析为节点。每个职位、每个学历,以及用户想要展示的每个正在进行的个人副项目类别,都对应一个
<li class="tl-stop">。按时间顺序 现在 → 最早(DOM 中从上到下)。 为每个节点选择一个简短的data-experience标识(例如mars、vibe、coach、gatech)— 筛选功能使用它来将节点与卡片关联。仅在有关联至少一个项目卡片的节点上添加tabindex="0"(其他节点保持静止)。<li class="tl-stop tl-stop-work" data-experience="<标识>" tabindex="0"> <!-- tl-stop-work | tl-stop-edu | tl-stop-vibe (选一个) --> <svg class="tl-icon tl-icon-work" aria-hidden="true"> <use href="#icon-wrench"/> <!-- #icon-wrench | #icon-book | #icon-sparkle --> </svg> <div class="tl-info"> <strong>公司 / 学校</strong> <span>职位 / 学位</span> <em>开始 — 结束</em> <i class="tl-loc">城市, 州</i> </div> </li>对于没有关联项目卡片的学历/旧职位节点,删除
tabindex="0"—js/main.js会在加载时自动检测这些节点并使其保持非交互状态。 -
项目 — 约六个
<article class="project-card">块,从简历中显著的项目/成就生成。每个卡片必须携带一个data-experience标识,与其来源节点匹配,否则无法参与筛选:<article class="project-card" data-experience="<标识>"> <header class="project-head"> <span class="project-tag">类别</span> <h3>项目标题</h3> </header> <p>1-2 句摘要,来自简历要点。</p> <dl class="project-metrics"> <div><dt>指标</dt><dd class="up">+值</dd></div> <div><dt>指标</dt><dd>值</dd></div> </dl> <ul class="tag-list small"><li>工具</li><li>工具</li></ul> </article>使用
<dd class="up">/<dd class="down">为指标着色。卡片默认以折叠状态渲染 — 只有标签、标题和工具标签可见,直到悬停/聚焦时显示摘要 + 指标。保持摘要简洁;它们的存在只是为了奖励悬停操作。 -
聊天问候语 — 机器人的开场消息是
index.html中#chat-panel内的内联 HTML(位于面板的<div class="chat-log">内),因此当用户首次打开弹出面板时它会立即渲染。使用选定的机器人名称 + 表情符号头像重写它。格式:<div class="chat-msg chat-msg-bot"> <span class="chat-avatar" aria-label="<机器人名称>">表情符号</span> <div class="chat-bubble"> <p>你好,我是 <strong><机器人名称></strong> — <显示名称> 的 AI 助手,从<他/她>的简历中学习过。</p> <p>你可以问我:</p> <ul> <li>公司 / 职位</li> <li>方法 / 思路</li> <li>项目 / 技能 / 教育背景</li> </ul> <p>你想了解什么?</p> </div> </div> -
联系 — 邮箱 + 每个提供的社交 URL 作为一个
<li>放入.connect-list。删除任何未提供的平台的行。
6. 添加头像
询问照片的位置。将其复制到仓库根目录,命名为 raw.jpg,然后调整大小:
cp <用户照片路径> raw.jpg
mkdir -p assets
sips -Z 720 raw.jpg --out assets/portrait.jpg
如果照片背景与新的 --bg 不匹配,使用捆绑脚本进行颜色替换:
cd /tmp && rm -rf img-fix && mkdir img-fix && cd img-fix
npm init -y > /dev/null
npm install [email protected] --silent
node <此技能目录>/scripts/shift-portrait.js \
/path/to/my-site/raw.jpg \
/path/to/my-site/assets/portrait.jpg \
"#<你的背景十六进制色>"
如果省略第三个参数,默认为 #fbf7eb。raw.jpg 在 .gitignore 中。
7. 配置聊天机器人(如果用户说否则跳过)
7a. Worker
cd worker
wrangler login
wrangler secret put DEEPSEEK_API_KEY
worker/wrangler.toml:
ALLOWED_ORIGIN = "https://<用户名>.github.io,http://localhost:8000,http://127.0.0.1:8000"
MODEL = "deepseek-chat"
worker/worker.js → SYSTEM_PROMPT — 根据用户的简历重写。保持章节结构(关于 / 当前角色 / 过往角色 / 教育经历 / 工具箱)。同时使用机器人名称 + 头像重写开场角色描述:
const SYSTEM_PROMPT = `你是 "<机器人名称>" <表情符号> — 一个友好、简洁的 AI 助手,嵌入在 <显示名称> 的个人网站上。 …`;
部署:
wrangler deploy
7b. 客户端
js/config.js:
window.SITE_CONFIG = {
chatWorkerUrl: "https://<worker>.workers.dev",
};
js/chatbot.js — 更新顶部的常量:
const AVATAR = "<表情符号>";
const AVATAR_LABEL = "<机器人名称>";
8. 预览 + 推送
python3 -m http.server 8000 # http://localhost:8000
点击浏览每个部分。测试聊天功能。调整到移动端宽度进行测试。然后:
git add .
git commit -m "initial: 个人网站"
git push -u origin main
大约 60 秒内即可在 https://<用户名>.github.io/ 上线。
模板架构(不要更改)
区块布局
每个区块都使用 .section-grid: 280px 1fr。280px 列容纳最长时间线标签。如果所有标签都较短,收紧到 240px;如果较长,放宽到 320px。
时间线
- 位于项目
section-head内,标题正下方,opacity: 0.45。悬停、聚焦或激活筛选会将其提升到 0.95。 - DOM 顺序 = 视觉从上到下顺序。 现在 → 最早。不是按时间比例分布 — 通过 flex
gap均匀分布。 - 开箱即用的三种图标类型:
#icon-wrench(工作,.tl-stop-work)、#icon-book(教育,.tl-stop-edu)、#icon-sparkle(兴趣/副项目,.tl-stop-vibe)。所有三个<symbol>定义位于<header>之后的 SVG 精灵中。要添加新的图标类别:- 用你的 SVG 路径添加一个
<symbol id="icon-foo"> - 添加
.tl-icon-foo { color: var(--ink-mute); } - 使用
<svg class="tl-icon tl-icon-foo"><use href="#icon-foo"/></svg>引用
- 用你的 SVG 路径添加一个
- 每个节点携带
data-experience="<标识>";其标识与至少一个项目卡片匹配的节点还会获得tabindex="0",以便js/main.js使其成为可筛选交互式节点。
项目筛选(点击 + 悬停)
完全由 js/main.js 驱动,无需配置 — 它在加载时扫描 DOM 并仅在有适用关系的地方绑定处理程序。
- 加载时,每个其
data-experience标识出现在至少一个.project-card上的节点都会获得.tl-stop-has-projects+role="button"+aria-pressed="false"。没有关联卡片的节点保持静止。 - 悬停 / 聚焦 一个交互式节点 → 临时筛选:不匹配的卡片变为
.is-dim(网格添加.is-filtering,CSS 将其转换为display: none应用于变暗的卡片 — 它们从布局中移除,不仅仅是淡出)。 - 点击(或
Enter/Space)→ 锁定:节点获得.is-locked、完全不透明度、墨水色的图标、带下划线的公司名称。再次点击同一节点清除;点击另一个节点切换。 - 锁定时,悬停不同节点可预览其卡片;鼠标离开时间线面板(或聚焦移出它)会恢复到锁定的筛选状态。
图标
位于 SVG 精灵中(<svg style="display:none">,紧跟在 <header> 后的第一个元素)。添加任何新图标只需在内添加一个 <symbol id="icon-..."> + 路径即可。
英雄区
肖像 (<img>) 会透过 mask-image 放置在 #eee 背景色上。如果更换头像,调整背景色以匹配新的 --bg。如果用户想要深色主题的 #0f1115,将 #eee 更改为 #111(保留可辨别的边缘)。
联系
纯列表。没有表单。mailto: 链接。社交 URL 在新标签页中打开。
Cloudflare Worker
- 在
worker/目录中。 - CORS 配置来自环境变量
ALLOWED_ORIGIN。 - 双层速率限制:每 IP 每 15 分钟 30 次请求 + 全局每分钟 150 次。
- DeepSeek 的 OpenAI 兼容
chat/completions端点。 - API 密钥通过
wrangler secret put DEEPSEEK_API_KEY设置;worker.js通过env.DEEPSEEK_API_KEY读取。
移动端适配
<meta name="viewport">已设置。- 时间线在 600px 以下变为水平单行。
字体托管
- 静态字体无法在 GitHub Pages 上可靠跨域加载。将字体托管在 runbook.sh 上,或通过 Google Fonts 嵌入。
- 模板默认使用通过
@import加载的 Google Fonts。
QA 清单
推送之前检查:
-
raw.jpg已被 git 忽略 — 确认git status没有意外暂存它 - 照片背景颜色匹配,或已使用
shift-portrait.js调整 - 每个
data-experience标识既存在于一个.tl-stop上也存在于至少一个.project-card上(否则筛选将忽略它) - 所有社交 URL 都正确格式化(https://...)
- 聊天机器人提示
SYSTEM_PROMPT没有提及 "donotdonuts"、"模板" 或 "代理程序" — 它只认识 和 -
js/config.js中的chatWorkerUrl是有效的 Cloudflare Workers URL - 当没有聊天机器人时,对话启动器
<div>会收到.hidden类(而不是从 DOM 中删除 — 这样切换逻辑才能正常工作)