homepage/docs/AI-HANDOFF.md

AI 交接说明

更新日期：2026-08-18

当前状态

项目是 midctrl.com 的纯静态首页，无数据库、API 或构建步骤。网站运行文件位于 site/。当前版本已完成代码复审、冷启动修复、移动端检查和公开文件白名单验证，但本仓库版本尚未上传生产服务器。

最近完成的修复

• WebGL 从等待 window.load 改为 DOM 就绪后初始化，字体或图片请求不会阻塞 Sakura。
• 初始化函数幂等，避免重复创建场景。
• 初始化时重新读取页面可见性和 reduced-motion 状态。
• pagehide 取消待执行帧，pageshow 重新同步并恢复。
• generation guard 隔离浏览器队列中未及时移除的旧 rAF 回调。
• site-config.json 请求超时为三秒，失败时使用 HTML 中的链接。
• 资源查询版本为 20260818-3。

渲染约束

• 粒子数：1,600。
• 花瓣 draw call：五次。
• Bloom directional blur draw：四次。
• 帧率上限：120 FPS，跟随显示器 requestAnimationFrame。
• 内部像素预算：普通设备 1,000 万像素，浏览器报告内存不高于 4 GB 时为 600 万像素。
• resize 稳定窗口：140 ms。
• reduced-motion：WebGL 静态帧，头像框使用静态图片。

不要在没有用户明确批准的情况下通过降低粒子、Bloom 或绘制次数解决性能问题。

关键文件

• site/assets/js/main.js：链接配置、Shader、Sakura、Render Target 和生命周期。
• site/assets/css/main.css：布局、字体、文字和头像效果。
• site/assets/js/site-config.json：站点名称、描述、规范 URL、外链名称和 URL。
• tests/test-render-target-resize.js：无第三方依赖的 VM 测试。
• scripts/verify-production.ps1：生产检查和公开目录白名单。
• nginx/midctrl.com.example.conf：脱敏示例，不是生产服务器完整配置。

推荐工作流程

python -m http.server 9010 --bind 127.0.0.1 --directory site
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify-production.ps1

修改后先运行自动检查，再用真实浏览器检查首页、移动端和 /404.html。检查控制台并对纯 Sakura 区域间隔采样，确认画面确实变化。

生产边界

• Cloudflare SSL/TLS 使用 Full (strict)。
• 源站为 AlmaLinux 9 和 Nginx。
• 生产主机还有不属于本仓库的私有 location，部署时必须从现有服务器配置中保留。
• 证书私钥、服务器地址、私有 location、备份和上传凭据不得进入仓库。
• 用户授权部署前，只能在本地修改和验证。

新会话启动提示

可以在新 AI 会话中直接说明：“请先阅读 AGENTS.md 和 docs/AI-HANDOFF.md，运行生产检查，再继续处理我的需求。”

域名配置边界

运行时站点身份从 site/assets/js/site-config.json 读取，首页的标题、canonical 和 Open Graph 元数据不会再分别写死域名。site/robots.txt 与 site/sitemap.xml 是需要绝对 URL 的静态 SEO 文件；更换站点域名时必须一并更新它们，并运行生产检查。