# AGENTS.md

## 基本要求

- 开发沟通、审查结论和任务说明使用简体中文；代码默认缩进为 4 个半角空格。
- 部署上线的默认语言、SEO 语义、manifest 和结构化数据以 `en-US` 为主要基准。
- 修改前先阅读相关代码、配置和文档；更深层级规范优先。
- 未经用户明确许可，不得修改本文件。

## 技术栈与文档

- 项目技术栈：Astro + Beer CSS。
- Astro 文档：<https://docs.astro.build/>；仓库：<https://github.com/withastro/astro>。
- Beer CSS 文档：<https://www.beercss.com/>；仓库：<https://github.com/beercss/beercss>。
- Astro 相关问题优先使用 Astro MCP 或官方文档。
- Beer CSS 组件和交互优先照官方文档、GitHub 源码与示例实现；官网不便阅读时查仓库。
- Beer CSS 目标是无需自定义 CSS 构建现代界面；优先使用其语义元素、组件类和工具类。仅在必要需求无法表达、项目级主题变量或明确兼容性修复时添加少量自定义 CSS，并说明原因。
- 优先使用 Noto Sans 字体及其多语言变体，等宽字体使用 Noto Sans Mono。

## 开发原则

- 聚焦当前任务，避免无关重构、格式化或元数据变更。
- 不删除或覆盖用户已有改动；不确定时先确认或绕开。
- 引入框架、依赖、部署配置或公开路径前，明确长期用途与维护成本。
- 新增抽象应有明确收益；公开行为、路径、接口和内容语义变化应显式说明。

## 数据与资源

- 站点级常量统一维护在 `src/data/site.config.mjs`；多语言文案维护在 `src/data/site.ts`，避免网址、资源路径、主题色等多处硬编码。
- 依赖站点配置的公开文件优先用 Astro 路由生成；仅纯静态且无需配置的数据放入 `public/`。
- `src/generated/` 下文件视为脚本产物，不手工编辑；Beer CSS 主题生成逻辑放在 `scripts/generate-beer-theme.mjs`。

## 样式规则

- 项目新增的自定义样式放在 `src/styles/` 独立文件中引用，不写入 `src/generated/` 生成文件。
- 覆盖 Beer CSS 或其他第三方样式时，优先在构建或生成脚本中完成替换并写入生成产物；仅针对明确需要调整的选择器和属性，避免扩大为通用项目样式。

## 验证与沟通

- 完成站点代码改动后按影响范围运行 `npm.cmd run check`、`npm.cmd run build` 或更聚焦的验证；无法验证时说明原因和风险。
- 前端改动需关注桌面与移动端布局、可访问性、焦点态、溢出、加载与错误状态。
- 临时方案和一次性迁移细节不写入本文件；回复简洁说明改动、验证结果和注意事项。
