# AGENTS.md — 给 Agent 的建模指南 / How agents add building detail

> 本项目：基于 Overture Maps 真实数据的南京 3D 城市（`https://nanjing.klado.team`）。
> 底图里每栋建筑都只是「挤出的白盒」。Agent 的工作是**给具体建筑发布精细模型**，
> 发布后无需重新部署，刷新页面即可看到，而且会自动适配所有渲染风格（写实 / 赛博朋克 / 水墨 / 白模）。

Machine-readable entry point: `GET https://nanjing.klado.team/api/spec`

---

## 1. 五步流程 (TL;DR)

```bash
BASE=https://nanjing.klado.team
# 1) 找到建筑 ID（Overture GERS id）
curl -s "$BASE/api/lookup?q=鼓楼"                       # 按地名
curl -s "$BASE/api/lookup?lon=118.7787&lat=32.0598"      # 按经纬度
# 2) 读取建模上下文：footprint（已换算到建筑局部坐标）、高度、朝向、邻居、附近 POI
curl -s "$BASE/api/buildings/<ID>" > ctx.json
# 3) 写 detail.json（recipe）或导出 model.glb —— 规范见 docs/BUILDING_DETAIL_SPEC.md
# 4) 先校验（不需要 token）
curl -s -X POST "$BASE/api/validate" -H 'content-type: application/json' --data-binary @detail.json
# 5) 发布（需要 token，存放见第 5 节）
node tools/nj-agent.mjs publish <ID> detail.json [model.glb]
#   或：curl -X PUT "$BASE/api/buildings/<ID>/detail" -H "Authorization: Bearer $NANJING_CITY_AGENT_TOKEN" \
#          -H 'content-type: application/json' --data-binary @detail.json
```

发布后打开 `https://nanjing.klado.team/#b=<ID>` 自动飞到该建筑。

## 2. 坐标系（最容易出错，务必读）

| 用途 | 原点 | 轴 | 单位 |
|---|---|---|---|
| **recipe (JSON)** | 建筑 *anchor*（外轮廓面积加权质心，地面 z=0） | **x = 东，y = 北，z = 上** | 米 |
| **GLB (glTF)** | 同一 anchor | **+X = 东，+Y = 上，+Z = 南**（即 −北） | 米 |

- `GET /api/buildings/<ID>` 返回的 `footprint.outer` 已经是 recipe 坐标（相对 anchor 的 `[x东, y北]`），直接用。
- `footprint.min_rect.angle_deg` = 最小外接矩形长轴方向（自正东逆时针，度）。
  屋顶 / 盒子的 `rotation` 一般就填它，让屋脊顺着建筑长边。
- recipe 点 `(x, y, z)` 对应 glTF 顶点 `(x, z, -y)`。Blender 默认 Z-up 导出 glTF 时会自动转成 Y-up：
  在 Blender 里按「X = 东，Y = 北，Z = 上」建模即可。
- 建筑地面统一是 z = 0（v1 没有地形）。

## 3. 两种模型格式

1. **`recipe`（推荐，LLM 友好）**：用 `extrude / box / cylinder / roof` 四种参数化部件拼建筑，支持 `repeat` 阵列。
   中国传统屋顶有专门参数：`hip`(庑殿)、`hip_gable`(歇山)、`gable`(硬山/悬山)、`pyramid`(攒尖)、`flat`，
   以及 `curve`(屋面举折凹曲)、`corner_lift`(飞檐翘角)。完整参数表见 `docs/BUILDING_DETAIL_SPEC.md`。
2. **`glb`**：任何工具（Blender 脚本、trimesh、three.js exporter…）导出的 glTF 2.0 二进制，≤ 25 MB。
   **材质名必须用 `nj:<语义材质>`**（如 `nj:roof_tile_grey`），否则在非写实风格下无法正确换肤。

两种格式都只能使用规范里的**语义材质**（`wall_brick_grey`、`wood_red`、`roof_tile_glazed_yellow`…，完整列表见 `/api/spec`）。
各渲染风格会把语义材质映射成自己的外观——这就是「一次建模，多种风格」的关键。

另外可只发 `overrides`（不带模型）来修正底图：真实高度、立面颜色等。

## 4. 质量要求（检查清单）

- [ ] 模型落在 footprint 内（允许屋檐外挑 ≤ 2 m），不压到 `neighbors` 的轮廓上。
- [ ] 高度与现实一致：查资料，写进 `sources`（URL / 文献）。`ctx.height_source = "estimated"` 的高度不可信。
- [ ] 朝向正确：用 `min_rect.angle_deg` 或 footprint 边方向，不要凭感觉。`angle_deg` 只给出长轴方向（0–180°），
      不区分正反面：有正立面的建筑（如总统府门楼的柱廊朝南）要确认正面朝向，不对就 `rotation` 再加/减 180。
- [ ] 部件数 ≤ 4000（`repeat` 展开后），用 `repeat` 做柱廊/窗格，不要手写上百个部件。
- [ ] 只用语义材质；需要特殊颜色时用 `color` 覆盖（`#rrggbb`）。
- [ ] 先 `POST /api/validate`，再发布；发布后打开 `/#b=<ID>` 截图自检（写实 + 水墨两种风格各看一眼）。
- [ ] 同一栋建筑再次发布会覆盖，旧版本自动存档到服务器 `history/`，不怕改坏。

## 5. Token 与权限

- 写接口（PUT / DELETE）需要 `Authorization: Bearer <token>`。
- Mac mini 上 token 存在 `/Volumes/NewDisk/.agent-secrets/secrets.env` 的 `NANJING_CITY_AGENT_TOKEN`
  （`source` 后使用，**永远不要打印或提交 token**）。其它机器向用户索取。
- 只读接口（lookup / buildings / spec / validate / details）无需 token。

## 6. 什么时候改仓库而不是调 API

- 想让某个模型成为「官方」版本、随代码一起版本化：把 `detail.json`（和 `model.glb`）放到
  `details/<ID>/`，提交并推送 `main` → Harness 流水线自动部署。运行时 API 发布的版本优先级更高。
- 改渲染风格：`web/src/styles/`（见 `docs/STYLES.md`）。
- 扩展地图范围：`regions/*.json` + 数据流水线（见 `docs/DATA_FORMAT.md`、`README.md`）。

## 7. 参考

- `docs/BUILDING_DETAIL_SPEC.md` — detail 文档字段、部件参数、材质表、示例
- `docs/AGENT_API.md` — 全部 HTTP 接口
- `schemas/building-detail.schema.json` — JSON Schema
- `details/_examples/` — 示例（鼓楼）
- `tools/landmarks/build-landmarks.mjs` — 用脚本从 API 上下文批量生成地标模型的示例（中华门、挹江门、阅江楼、大报恩寺塔…）
- `shared/detail-spec.mjs` — 服务端校验与前端渲染共用的规范源码（以它为准）
