# AGENTS.md

本文件适用于整个仓库。

## 开始工作前

1. 阅读 `README.md` 和 `docs/AI-HANDOFF.md`。
2. 运行 `powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify-production.ps1`。
3. 检查工作区已有改动，不要覆盖不属于当前任务的修改。

## 必须保持的行为

- Sakura 保持 1,600 粒子、五次花瓣绘制、四次 Bloom 和 120 FPS 上限，除非用户明确批准降低效果。
- 动画使用 `requestAnimationFrame`，页面隐藏时暂停，页面恢复时只能存在一个动画循环。
- 保留 cold-start、`pagehide/pageshow`、WebGL context recovery 和 Render Target fallback 测试。
- Blog 和 Tools 默认在新标签页打开。
- `site/assets/js/site-config.json` 失败时必须保留 HTML 后备链接。
- reduced-motion 当前会让 WebGL 使用静态帧；改变该策略前先与用户确认。
- `site/404.html` 使用根绝对资源路径，避免嵌套 URL 下资源失效。

## 修改规则

- 网站源文件位于 `site/`，不要创建第二份重复的运行副本。
- 修改 CSS 或 JavaScript 后同步更新 `site/index.html` 和 `site/404.html` 的资源查询版本。
- 修改字体文件后更改字体 URL 版本或文件名，因为生产环境使用长期缓存。
- 不要将密钥、证书私钥、访问令牌、主机 IP、私有代理路径或服务器备份写入仓库。
- `nginx/midctrl.com.example.conf` 只能保持为脱敏示例；部署时合并现有主机私有 location，不要在公开仓库记录它们。
- 不要将测试工具、备份或发布 ZIP 放进 `site/`。

## 完成标准

- 生产检查全部通过。
- 首页和 404 页面控制台无错误。
- 桌面端和移动端无横向溢出或元素重叠。
- 连续画面采样确认 Sakura 在非 reduced-motion 的前台页面持续更新。
- 若生成发布包，ZIP 只能包含 `site/` 文件，并生成 SHA-256。
- 未经用户明确授权，不连接生产服务器、不上传文件、不 reload Nginx。