Initial homepage

2026-08-18 09:57:55 +08:00
commit 1660bb9f65
25 changed files with 3019 additions and 0 deletions
@@ -0,0 +1,78 @@
+# 中枢首页
+
+`midctrl.com` 的纯静态导航首页。页面不需要构建工具、后端运行时或数据库，Nginx 可以直接提供 `site/` 中的文件。
+
+## 功能
+
+- WebGL Sakura 背景，1,600 个粒子、五次花瓣绘制、四次 Bloom，最高 120 FPS。
+- DOM 就绪后立即初始化，不等待字体或图片完成加载。
+- 页面进入后台时暂停，通过 `visibilitychange` 和 `pageshow` 恢复。
+- WebGL context 丢失、Render Target resize 和显存分配失败恢复。
+- 自托管 Noto Serif SC 字体、圆形头像框、标题与文案效果。
+- 外链由 JSON 配置，并在新标签页打开。
+- 响应式首页和 404 页面。
+
+## 本地预览
+
+```powershell
+python -m http.server 9010 --bind 127.0.0.1 --directory site
+```
+
+打开 `http://127.0.0.1:9010/`。
+
+## 修改站点与导航
+
+编辑 `site/assets/js/site-config.json`。站点名称、描述、规范 URL 和导航链接都集中在这里：
+
+```json
+{
+  "site": {
+    "name": "中枢",
+    "description": "你也可以变成光",
+    "url": "https://midctrl.com"
+  },
+  "links": [
+    { "name": "Blog", "url": "https://wp.midctrl.com" },
+    { "name": "Tools", "url": "https://tools.midctrl.com" }
+  ]
+}
+```
+
+HTML 中保留了同样的后备链接，这是 JSON 请求失败、JavaScript 被禁用或网络异常时的故障降级；修改 `links` 后需同步更新 `site/index.html` 中的后备锚点。JSON 请求失败或超过三秒时，后备链接仍可使用，WebGL 初始化不受影响。
+
+页面运行时会从同一份配置更新标题、canonical 和 Open Graph URL，避免在 HTML 与 JavaScript 中重复维护站点域名。`robots.txt` 和 `sitemap.xml` 中的绝对 URL 是搜索引擎协议要求的静态发布文件；更换域名时应同步更新这两个文件。
+
+## 验证
+
+Windows PowerShell：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify-production.ps1
+```
+
+检查内容包括 JavaScript 语法、冷启动、页面恢复、单动画循环、WebGL context 恢复、Render Target resize、渲染质量参数、字体许可、Nginx 示例和公开目录文件白名单。GitHub Actions 会在 push 和 pull request 时运行相同检查。
+
+## 目录
+
+- `site/`：可直接部署的网站文件。
+- `tests/`：WebGL 生命周期和 Render Target 测试。
+- `scripts/`：生产检查脚本。
+- `nginx/`：不包含主机私有 location 的公开配置示例。
+- `docs/`：部署和 AI 交接说明。
+- `AGENTS.md`：后续 AI 会话应遵守的项目约束。
+
+## 部署
+
+参见 [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)。部署时只复制 `site/` 的内容，不要把仓库文档、测试或 Git 元数据放入网站根目录。
+
+## 前端代码与安全
+
+浏览器必须下载前端代码和资源才能渲染，因此无法阻止访问者检查或复制 HTML、CSS、JavaScript、Shader 和图片。混淆只能增加阅读成本，不是安全边界。仓库中不得提交密钥、令牌、源站证书私钥或主机私有代理配置。
+
+## 许可
+
+项目当前没有声明整体开源许可证；公开仓库默认不向第三方授予复制、修改或再发布权利。自托管 Noto Serif SC 子集仍受 `site/assets/fonts/OFL.txt` 中的 SIL Open Font License 约束。若计划把项目作为可复用开源项目发布，应先明确选择项目级许可证。
+
+## AI 继续工作
+
+新的 AI 会话应先阅读 [AGENTS.md](AGENTS.md) 和 [docs/AI-HANDOFF.md](docs/AI-HANDOFF.md)，再运行生产检查，避免丢失渲染质量和部署边界。