AGENTS.md@.github/apps/bazi-3d-web git:20261025.3c17b73A

Immutable. This exact content never changes and is served at /api/v1/blob/c2e8d43f4faa76f1.

# AGENTS.md - 八字全历史三维数学图谱

## 目录用途

`.github/apps/bazi-3d-web/` 是独立 `/bazi-3d/` 产品。它把 CalendarProfile 在 1900 至 2030 闭合支持域内的全部 574165 个原生时辰同时放入一个 Three.js 点云，以 26 种位置投影和 4 种整体或派生着色观察同一历史集合。每个时辰的年柱、月柱、日柱、时柱共同组成一个不可拆分的原子输入；柱位只能作为原子内部坐标展示或计算，不得成为独立样本或独立控制入口。图表切换不得重新请求、裁剪或替换历史；不得导入 `.github/apps/timeline-web/` 或 `.github/apps/bazi-math-web/`。

## 目录结构

```text
bazi-3d-web/
├── AGENTS.md
├── index.html
├── package.json
├── playwright.config.ts
├── public/
│   ├── history-manifest.json
│   └── assets/
│       └── bazi-history-v1-<profile-digest>.bin
├── scripts/
│   └── build_history_dataset.py
├── src/
│   ├── App.tsx
│   ├── WholeHistoryScene.tsx
│   ├── catalog.ts
│   ├── catalog.test.ts
│   ├── history-data.ts
│   ├── history-data.test.ts
│   ├── main.tsx
│   ├── whole-history-projections.ts
│   ├── whole-history-projections.test.ts
│   └── whole-history.css
├── tests/
│   └── product.spec.ts
├── tsconfig.json
└── vite.config.ts
```

## 职责边界

- `scripts/build_history_dataset.py` 是派生资产生成入口；只调用 fate-core canonical CalendarProfile 和 provider，按 ordinal 顺序写五字节记录，不持有第二套历法算法。
- `public/history-manifest.json` 固定 Profile 摘要、支持域、ordinal、词表、记录布局和 binary 摘要；manifest 使用 no-cache，带 Profile 摘要的 binary 使用 immutable cache。
- `history-data.ts` 是浏览器数据边界；30 秒超时且不重试，校验 manifest、长度、SHA-256 和有限值范围后，以 O(n) 构造共享 position 与 color typed arrays。四种着色只能消费完整四柱原子、由完整原子派生的五行或状态变化，以及附着于同一帧的节气。
- `catalog.ts` 是 26 项三维图表的机器目录；ID、分组、三轴语义、输入契约、投影版本、readiness 和投影损失必须唯一且可审计。
- `whole-history-projections.ts` 是纯 O(n) 位置投影内核；每次只原位重写一份 position，每项主坐标必须使用四柱联合相位、联合矩、联合离散度或联合转移；原子身份纤维只解决低维投影碰撞，不得替代主公式。`direct`、`approximate`、`conditional` 必须与实际输入能力一致。
- `App.tsx` 不接受时间、地点、口径或命盘输入，也不请求 timeline Point 或 Window；只加载一次全历史资产并维护图表、着色和所选点。
- `WholeHistoryScene.tsx` 是唯一 WebGL owner；一份全历史 BufferGeometry、一个 Points 对象和一个 canvas 同时承载 574165 个时辰。图表切换原位更新 position，着色切换原位更新 color；P01 可附加一个固定 721 顶点的闭合骨架参考线，但不得复制全历史 geometry。
- 每次位置投影完成后必须按真实 bounding sphere 自动更新相机 target、distance、near、far 和 OrbitControls 范围；禁止用一组固定相机参数裁切或缩小 26 种不同尺度的投影。
- 三轴语义由当前图表目录项定义，不存在所有图表共用的伪时间轴。坐标是可视化嵌入，不宣称吉凶、概率、因果或未计算的完整数学结果。
- 点选才执行 O(n) raycast；pointer move 不做全量命中测试。选中结果从同一五字节记录还原四柱、节气和五行文本。
- WebGL 创建失败或 context lost 时必须保留中文文本；卸载必须释放全历史与参考 geometry、material、纹理、控制器、监听器、renderer 和 WebGL context。
- 任务 0174 的窗口请求和局部 `SceneModel` 实现不属于当前入口。现有 `catalog.ts` 被复用为机器目录，但旧局部算法不得直接扩展到全历史；物理清理仍需删除授权。

## 依赖方向

- `build_history_dataset.py -> CalendarProfile + fate_core.kernel.bazi.calendar_pipeline + fate_core.kernel.bazi.timeline`
- `App.tsx -> catalog.ts + history-data.ts + whole-history-projections.ts + WholeHistoryScene.tsx`
- `WholeHistoryScene.tsx -> catalog.ts + history-data.ts + whole-history-projections.ts + three`
- `whole-history-projections.ts -> catalog.ts + public history record contract`
- `history-data.ts -> public/history-manifest.json + public/assets/*.bin`
- 禁止 `bazi-3d-web -> timeline-web` 和 `bazi-3d-web -> bazi-math-web`

## 验证

- `python3 .github/apps/bazi-3d-web/scripts/build_history_dataset.py --check`
- `npm --prefix .github/apps/bazi-3d-web test`
- `npm --prefix .github/apps/bazi-3d-web run typecheck`
- `npm --prefix .github/apps/bazi-3d-web run build`
- `npm --prefix .github/apps/bazi-3d-web run test:e2e`
- `bash .github/scripts/bazi-3d-web.sh --mode all`