Sigao Li — personal MCP server

sigaoli.com

Sigao Li 的个人网站——AI 产品经理 · 空间数据科学家。 从地图到模型，以及两者之间的产品。

双语网站（英文版位于 /，中文版位于 /zh/），使用 Astro + Tailwind CSS v4 + GSAP 构建， 通过 GitHub Actions 部署到 GitHub Pages。于 2026-06-11 上线，取代此前的 Jekyll（academicpages）网站。

亮点

• 地图主题上的生成式画布效果——交互式粒子场（首页）、等高线地形（工作）、带流场的「河流时间线」（简历）和地理网络弧线地图（摄影）；全部使用原生 canvas/SVG，并经过调校，可达 60fps，同时提供减少动态效果和移动端回退方案
• 点状世界地图——陆地数据采样自 Natural Earth，包含从 6 个国家提取的 88 个 GPS 照片位置；点击标记即可打开该国家的相册
• Zoe，数字门猫——Sigao 的猫（驺虞）以一组 AI 生成、经色度键处理的 VP9-alpha 视频片段形式，出现在每个页面的角落；片段通过共享的锚点姿势固定，并由状态机驱动：被忽视时会打盹、对页面切换做出反应、在你输入时聆听、助手输出内容时会「打字回应」，还藏有一些彩蛋（制作手册位于 docs/）
• 内置 AI 层——每个页面都有一个由 Zoe 出面呈现的浮动聊天助手——随着你的提问，它会推荐最相关的单个页面；回访者还会收到按名字发出的问候（仅存储在其自己的浏览器中，且需主动选择加入）——此外还有一个个人 MCP 服务；两者都使用构建时生成的知识包，知识包与页面来自相同的信息源（见下文）
• 专为机器读取而设计——/llms.txt、/llms-full.txt、/resume.json（JSON Resume）、/knowledge.json、/.well-known/mcp.json、JSON-LD，以及明确欢迎 AI 爬虫的 robots.txt
• 照片自动归档——将全分辨率原始照片放入 _inbox/ 并提交。提交前钩子会根据坐标和 Natural Earth 多边形判断照片所属国家，将原件归档到 git 仓库之外，生成最长边为 4096px 且已移除 EXIF 的母版，调用视觉模型生成双语说明，并将所有内容登记到 photos.json——地图、计数和助手的知识都由此生成
• 编辑一种语言，另一种也会同步跟进——编辑中文或英文内容并提交。钩子会判断哪一侧发生了改动，并询问模型该改动是否真的改变了另一侧需要表达的内容。润色一种语言不会影响另一种；事实发生变化时会进行修订，而非重写，因此精心挑选的措辞得以保留。同一次提交中编辑两种语言，则视为已经手动处理
• Lighthouse（移动端）：所有类别均为 96–100 分；零 Cookie、无付费服务，并在 /privacy 提供通俗易懂的隐私声明

命令

命令	操作
npm run dev	在 localhost:4321 启动开发服务器（Astro 7 会将其作为守护进程运行——使用 npx astro dev stop 停止）
npm run build	将生产版本构建到 dist/
npm run preview	在本地提供生产构建版本
npm test	测试两条钩子流水线的单元测试（node --test，无需额外依赖）
npm run ingest	手动导入照片。通常由 pre-commit 钩子运行；此命令适合用于观察其运行情况
npm run sync	手动同步双语内容。同样，钩子会运行它；此命令用于观察其运行情况
node scripts/check-links.mjs	检查 dist/ 中的内部链接是否完整
node scripts/verify-nav.mjs 等	Playwright 交互测试套件（针对本地服务器运行）
npm run dev（在 worker/ 中）	在 localhost:8787 启动 Chat + MCP Worker（wrangler；机密信息存放在 worker/.dev.vars 中，切勿提交）
node scripts/verify-chat.mjs	Chat 小组件的 E2E 测试（需要同时运行两个开发服务器）
node scripts/verify-zoe.mjs	Zoe 动作状态机的 E2E 测试（在本地追加 ?zoe-fast，可压缩以分钟计的计时器）
node scripts/verify-typeroute.mjs	意图驱动的打字片段和双语 404 页面 E2E 测试

任何等待 Zoe 状态的 Playwright 测试套件都必须固定时钟 （Date.prototype.getHours = () => 14）：在 23:00 到 06:00 之间，她会以睡眠状态开始 会话，因此 state 永远不会变成 idle，运行最终只会超时。

添加 Zoe 片段时，要同时决定由谁预热，以及何时预热。 只有在播放时才获取的片段，在慢速连接上会卡顿，而且 在解码完成之前，舞台上什么都不会显示。预热已经漏掉三次了。 请注意，warm() 接收的是文件名（sit-to-loaf），而不是 ZOE 键（sitToLoaf）。

每次导航时都会重建聊天面板——transition:persist 保留的是 Zoe 的舞台，而不是面板。**任何仅存在于面板 DOM 中的内容，都会在访客点击链接时立刻消失。**流式回复、引导提示和未发送的草稿都必须存入模块状态，并能通过 paint() 恢复；提示丢失了好几个星期才有人发现。因此，在这里添加持久化 UI 时，要先回答两个问题：paint() 如何重建它？是否应该和历史记录一起存入 sessionStorage？仅在面板可见后测量几何尺寸——面板隐藏时 scrollHeight 为 0，这会悄无声息地写入 height: 0px。

Turnstile 会保护 /chat 和 /classify，但绝不能保护 /mcp。 该端点用于让机器读取 Sigao 的个人资料——它已列入 官方注册表——而 Turnstile 的作用正是阻止机器。提供该端点也无需花费任何成本：这些工具只会读取知识包，从不调用模型。 静态出口（llms.txt、knowledge.json、.well-known/mcp.json） 由 Pages 提供服务，根本不会到达 Worker。

在本地，Turnstile 使用 Cloudflare 始终通过的测试密钥——site.ts 中的 sitekey 由 import.meta.env.DEV 控制，secret 存放在 worker/.dev.vars 中。真实密钥会拒绝无头浏览器，这正是它的用途，因此任何驱动真实 Worker 的测试套件都会因此失败。真实 secret 只存在于生产环境中，通过 wrangler secret put 设置。还有一点值得记住： 无法通过脚本验证生产环境中的成功路径——要走通该路径，必须由真人使用真实浏览器。自动化仍可验证防护已启用 （不带凭证的请求必须返回 403）。

src/
├── pages/            # en routes + zh/ mirrors; llms.txt / resume.json / knowledge.json endpoints
├── components/       # Nav, Hero, WorldMap, Lightbox, CommandK, ChatWidget …
│   └── pages/        # shared page bodies rendered by both locales
├── content/          # cases & research (en) + cases-zh & research-zh (generated, reviewed)
├── data/             # cv.json / cv.zh.json / photos.json (GPS + bilingual alts)
│   └── knowledge/    # persona sources for the AI assistant (about / faq / guidelines / boundaries)
├── lib/              # i18n dict, GSAP lifecycle helper, site config
│   └── knowledge/    # knowledge-pack pipeline (same-source layers + build-time privacy guard)
└── assets/           # photo originals (optimized at build; originals never shipped)
worker/               # Cloudflare Worker: /chat (SSE) + /classify (intent) + /mcp (MCP server)
└── src/core/         # runtime-agnostic logic; Cloudflare specifics live only in src/adapter/
public/zoe/           # Zoe's clip library (600p VP9 alpha, lazy-loaded; idle loads first)
docs/                 # zoe-production-handbook.md — clip production specs & prompt cards

AI 层

一个知识层，三个输出端：供被动爬虫使用的 /llms-full.txt、供用户使用的聊天助手（POST /chat，SSE），以及供来访 Agent 使用的 MCP 服务（/mcp，Streamable HTTP，无身份验证——工具：get_profile / list_experience / get_case_study），两者均由 api.sigaoli.com 提供服务（Cloudflare Worker，代码位于 worker/）。知识包（/knowledge.json）在构建时由与页面相同的来源汇编而成——人物设定 Markdown、cv.json、案例研究、照片统计数据——因此，任何内容编辑都会在下次部署时同步到全部三个输出端，无需手动操作。隐私防护机制会在敏感信息模式（电话号码、证件号、坐标）泄漏到知识包时使构建失败。

每次回复时，聊天助手还会运行一个轻量级意图分类器（POST /classify，小型模型），推荐最相关的单个页面，并可记住回访者的姓名——这两项数据都只保存在访问者自己的浏览器中（需选择启用，可通过“忘记我”清除），绝不会保存在服务器上。欧盟／欧洲经济区／英国的访问者，其聊天和分类请求会路由至托管于欧盟的服务提供商，绝不会使用直连中国的 API。网站存储和发送的数据会在 /privacy 中以通俗易懂的语言说明。

编辑内容

• 案例研究／研究：编辑任一语言版本并提交。提交前钩子会判断哪一侧有改动，询问模型此次编辑是否确实改变了另一侧需要表达的内容，只有确认后才会修改另一侧——同时传入现有译文，确保修改事实时只修正相关内容，不改写其余措辞。润色一种语言，另一种语言会保持不变。在同一次提交中编辑两种语言，则视为已手动处理。请参阅 docs/bilingual-sync-design.md。
• 简历：编辑 src/data/cv.json 或 cv.zh.json——钩子会逐条同步另一种语言，因此修改一个职位不会影响其余内容。时间线、/resume.json 和 /llms-full.txt 都由此渲染。请一并替换 public/files/pdf/CV__Sigao_Li.pdf。（skills 特意不参与同步：两个语言版本在此处采用不同结构，渲染器会分别处理。）
• UI 字符串和首页主文案：手写的双语字典位于 src/lib/i18n.ts。
• 照片：将全分辨率原片放入 _inbox/ 并提交。提交前钩子会按 GPS 信息归档照片，将原片存入 _originals/（绝不提交），生成最长边不超过 4096px 的服务用主文件，使用视觉模型撰写双语说明，并将照片登记到 src/data/photos.json。没有 GPS 信息的照片应放入 _inbox/<country-id>/。照片数量、地图和 AI 知识包都会根据 photos.json 自动更新。请参阅 docs/photo-ingest-design.md。
• AI 助手人物设定：编辑 src/data/knowledge/*.md；知识包会在每次部署时重新构建，助手会在约 10 分钟内跟进（Worker 端缓存 TTL）。
• Zoe 的动作：源片段存放在仓库之外；流水线（scripts/zoe-board2.mjs → zoe-qc2.mjs → zoe-prod2.mjs）会为片段添加键、进行 QC、镜像并编码到 public/zoe/。新增动作 = 一个片段 + ChatWidget.astro 中 ZOE 表的一行；规格和提示卡见 docs/zoe-production-handbook.md。

本地设置

有两条链会通过 pre-commit 钩子运行：照片导入和双语同步。克隆后，只需将 Git 指向已跟踪的钩子目录一次：

git config core.hooksPath .githooks

如果不这样做，这两条链都不会运行——放入 _inbox/ 的照片会一直留在那里，两种语言也会停止同步。没有待处理事项时，两者都会立即退出，因此不会影响普通提交。

两者都需要 .env（复制 .env.example）：用于生成说明文字、翻译和检查内容是否过时的模型调用，都会通过该网关进行。

重新生成锁文件。 package-lock.json 必须在 Linux 上生成。npm 只会记录它在运行所在的机器上能解析的可选依赖，因此在 Windows 上生成的锁文件会漏掉 runner 所需的 sharp 依赖，导致 npm ci 拒绝安装。在此修改依赖后，从 Actions 选项卡运行 Relock on Linux 工作流；它会重新生成锁文件、验证 npm ci 可正常运行，并提交结果。普通推送不需要运行它——如果忘了，验证作业会提示。

部署

推送到 master → deploy.yml 会构建并部署到 Pages。推送到 v2 会构建但不会部署（仅验证）。

另外两个工作流负责监控而非阻止发布；失败时都会发送电子邮件，且都不会阻碍发布：

工作流	运行时间	内容
verify.yml	每次推送	构建、检查内部链接，然后运行八个浏览器脚本测试生产构建。失败时会上传截图和 Playwright 跟踪文件——将跟踪文件放入 trace.playwright.dev，即可逐帧回放运行过程
audit.yml	每周一	对网站和 worker 运行 npm audit

审计过去会阻止构建。它读取当天的公告数据库，而不是此代码库，因此即使提交没有任何改动，也可能一夜之间从绿色变成红色——这正是 9 月 13 日导致一批照片无法发布的原因。收到通知很有价值；被阻止则不然。

Worker 单独部署：cd worker && npx wrangler deploy（通过 wrangler secret put 设置密钥；在 Cloudflare 控制面板中绑定自定义域名 api.sigaoli.com）。如果一批更改同时涉及两者，请先部署 Worker——聊天界面会调用它的端点，因此如果先推送网站，短时间内这些调用会返回 404。

部署最多需要一分钟才能到达所有边缘位置。立即检查时读到的仍是旧版本；这曾两次被误认为部署失败，实际并无问题——请稍等片刻再检查。

每日聊天用量见 https://api.sigaoli.com/usage（显示最近七天的数据，以及今天是否已达到上限）。上限由 worker/src/core/quota.ts 中的 DAILY_CAP 设置；达到上限时，会通过 Cloudflare Email Routing 发送一次电子邮件。

⚠️ 切勿点击“Sync fork”。 此代码库最初是 academicpages 的 fork；同步会将 master 重置为上游模板。如果再次发生： git push --force origin <good-commit>:master。