# AGENTS.md — 魔芋の松果 工作区规则

> **本文件是入口。** 详细规则按任务拆在 `docs/rules/` 里，**按需读取**，不用一次全看。
> 冲突时优先级：**本文件 > `docs/rules/` > 各游戏 README > 个人偏好**。

---

## 1. 这是什么

`little-games` 是一个**纯静态、零构建、离线可用**的小游戏合集。
站名 **魔芋の松果**（英文 Pinecone），logo 是一颗点阵松果。

- 根目录首页 = **导航页**（`index.html`），展示 / 搜索 / 筛选所有游戏
- 每个**一级子目录** = **一个完整的独立小游戏**
- **成绩在服务器上**：本地只存设备 ID 和昵称，成绩不落盘
- 想要跨设备榜单时，部署 `server/`，见 [rating-guide](./docs/rating-guide.md)

**设计目标**：新增一个游戏 = 新建一个文件夹 + 跑一条命令，导航页自动收录。

---

## 2. 八条铁律

**这八条永远有效，不用读别的文档也必须遵守。**

1. **根目录只允许一个 `.html`：`index.html`（导航页）。** 其他 HTML 一律进子目录。
2. **一个游戏 = 一个目录，目录名 = `game.json` 里的 `id`，二者必须完全一致。**
3. **禁止手改 `games.js`。** 它是生成物，改完会被覆盖。要改就改 `game.json` 然后跑 `node tools/scan-games.mjs`。
4. **禁止跨游戏互相引用。** 游戏 A 不得 import 游戏 B 的文件。
   共享资源只有三处：`design/`（设计系统）、`sdk/`（计分等运行时）、`assets/`（只给导航页用）。
5. **禁止引入构建步骤、框架、CDN 外链。** 纯 HTML + CSS + 原生 JS，离线可用。
6. **禁止在根目录堆散落文件。** 图片、音频、脚本都必须归位到所属目录。
7. **禁止另起配色。** 颜色 / 字号 / 间距 / 圆角 / 阴影一律用 `design/tokens.css` 的变量。
8. **禁止用不可验证的维度计分。** 用时、设备性能、网络延迟这类外部量一律不许当分数——
   计分必须能从重放算出来，见 [replay.md](./docs/rules/replay.md)。

---

## 3. 按任务查文档

| 你要做什么 | 读哪个 |
|---|---|
| **新建一个游戏** | [docs/new-game-guide.md](./docs/new-game-guide.md) |
| 写 / 改 `game.json` | [docs/rules/structure.md](./docs/rules/structure.md) |
| 写游戏代码（技术约束） | [docs/rules/tech.md](./docs/rules/tech.md) |
| **让分数可验证（防改分）** | [docs/rules/replay.md](./docs/rules/replay.md) |
| 接计分 / 定 rating | [docs/rating-guide.md](./docs/rating-guide.md) |
| 改导航页 | [docs/rules/nav.md](./docs/rules/nav.md) |
| **部署到服务器** | [docs/deploy-1panel.md](./docs/deploy-1panel.md) |
| **提交前自检** | [docs/rules/ship.md](./docs/rules/ship.md) |
| 改配色 / 组件 / 图标 | [DESIGN.md](./DESIGN.md) |

**最常用的两条命令：**

```bash
node tools/new-game.mjs snake --title "贪吃蛇" --tags "街机,休闲" --emoji "🐍"
node tools/scan-games.mjs --check     # 提交前必跑
```

---

## 4. 给 AI 代理的约定

- **动手前**：先跑 `node tools/scan-games.mjs --check` 看现状，再读目标游戏的 `README.md`。
- **改完**：必须跑 `--check`，并在回复里报告结果。
- **不要**为了「让页面好看」重写整个导航页——增量修改 `assets/nav.css`。
- **不要**擅自删除已有游戏目录。要删先确认，或改成 `"hidden": true`。
- **不要**擅自新增游戏目录。这个仓库交付的是**框架**；
  没有明确要求时，只改 `tools/` `assets/` `_template/` `sdk/` `docs/` 这些框架文件。
- **不要**擅自 `git add` 或提交**游戏目录**的改动——那是作者的事。
- **不要**在 `_template/` 里写具体游戏逻辑，它必须保持通用。
- 拿不准目录归属时，**新建子目录**，不要往根目录塞文件。

---

## 5. 文档地图

```
AGENTS.md                  ← 你在读的：入口、铁律、索引
DESIGN.md                  设计规范（配色 / 字体 / 组件 / 图标 / 动效）
docs/
├── new-game-guide.md      新建游戏：从一条命令到能玩
├── rating-guide.md        计分：0–1 的 rating 怎么算、怎么防改分
├── deploy-1panel.md       部署到 1Panel（一个 Node 进程跑静态 + API）
└── rules/
    ├── structure.md       目录结构、保留名、命名规范、game.json 契约
    ├── tech.md            技术规范：必须 / 建议 / 禁止 / 性能预算
    ├── replay.md          重放验证：让分数可验证，防改分
    ├── nav.md             导航页维护
    └── ship.md            验收清单、提交规范、常见坑
```