AGENTS.md@.github/apps/bazi-infinite-demo git:20261025.3c17b73A

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

# AGENTS.md — 全字段算法时间矩阵

独立本地研究体验壳；不修改其他 timeline/math/3d 产品，不承担生产路由。

## 边界

- 严格复用 frontend-design Native Workbench v0.1：顶层开关、覆盖控制面、全屏数据面。CSS 模板不变，不引入装饰或 React UI。
- 35 组字段、119 行与初始 574165 个采样保留在同一场景。X 为独立分类词表，Y 为字段与柱位，Z 为实际采样时间；算法可继续向两侧生成，没有业务年份终点。整盘字段单行，不复制成四份命盘。
- “聚焦字段”更新标注；显式更换时还可调低其余字段的窗口概览亮度，不移动或删除其余字段，不替换全量纹理、裁剪初始历史或重新下载资产。35 组 Y 轴字段名放在矩阵内部左侧行表头列，不再在平面外重复显示；按 14 CSS px 屏幕空间尺寸显示，投影避让按实际字形墨迹边界而非纹理透明边距计算，聚焦字段优先，省略计数必须可见，完整字段名保留在语义侧栏。行表头不得移动分类单元或改变拾取坐标。禁止出生查询、分页或把缓存块宣称为逻辑时间域；分块只用于算法生产、缓存、预取与有限显存。
- 新增字段必须进入真实 GPU 表达、切片文字、图中字段标签和 JSON 导出；侧栏文字不算 3D 交付。当前切片的激活格必须在原 XY 坐标显示分类真值，字形按投影后的行高与类目槽宽自适应缩放，不得恢复方块占位；空集合不生成假文字。
- 全历史原始记录不变。相邻同值集合无损压缩为区间，GPU 用整数纹理解码；区间是采样显示槽，不声称帧内状态恒定。默认不绘制历史线段或中心点，只保留当前 XY 切片与独立四角导线；完整纹理和拾取层不删。显式打开采样状态带时，按 2—4096 个真实采样构建窗口；算法数据跨所需相邻 256 帧块读取，4096 层对齐窗口为 16 块，双并发装配，核对模型身份、块边界与逐块摘要；历史重叠区使用初始原始记录。按真实采样时刻分箱，仅在真实 X 分类槽绘制每行原始集合的样本众数概览；高度/透明度只表示箱内样本占比，混合箱不冒充全箱真值，全箱同值且相邻才合并。没有侧面统计幕布；无损同值段另画在真实 X 槽内，变化处断开，不插值、不宣称帧内恒定。带片只占据同分类采样显示槽，不是跨类别连续面、帧内证明或数学流形；颜色按行柱位冗余标记，不表达命理价值。局部视图 Z 轴按窗口采样时刻归一化，仅表达顺序和相对间隔，不代表绝对时距；窗口不是时间域边界。四角边线必须保留。
- 复用 Three.js DataTexture、BufferGeometry、RenderTarget。WebGL 保持透明并叠加在本应用 `#graph-root` 深色中性画布上；只有状态带按柱位使用青/紫/琥珀/珊瑚/绿，字段文字和控制面仍为语义文本/原生控件，不用颜色单独表达状态。此例外仅限本 Demo 绘图区，不扩展到其他页面或控制面。显式聚焦窗口时按完整 XY 与局部 Z 窗口拟合；恢复初始全景回到初始历史视角。局部聚焦改变的是可视 Z 比例，不改时间索引和源记录。侧栏开关不改变画布尺寸、不重建 renderer、不上传 GPU。
- 十神/十二长生以当层日干为准；各柱自坐以各自天干为准。合冲只查盘内不同柱位的既有配对表，不推断合化或吉凶。
- 浏览器只校验 producer 的物化记录并连接 canonical 字段表，不重算历法、五行或个人真太阳时，不导入其他 app 业务代码。时间输入的年、月、日、时直接按已换算好的真太阳时解释，由本地 producer 复用同一 provider 映射为时辰索引；不得声称完成地点/时区驱动的民用时间换算。producer 复用锁定的 lunar-python 公共接口，不复制天文算法。
- 初始资产仍严格校验其 Profile/支持域/摘要；外推块有独立模型及完整载荷摘要，不假称获得生产 Profile 域外精度认证。无业务年份终点不等于 provider 数值能力无限；失败明确报错，不补零、不复制历史。初始已物化资产没有断点记录，浏览器对此明确说明；断点只描述相邻采样状态在交接时刻改变，不把采样槽声明为帧内恒定。
- 全局索引/时间用 BigInt；块内小序号送入整数纹理。浮动原点改变坐标表示，不改变四柱或时间。最多 8 个外推记录块/显存块、128 MiB 数据纹理预算，过期请求不能夺回选择。没有远景统计 LOD 时明确保留未物化区域，不画伪汇总。
- 卸载释放几何、纹理、材质、渲染目标、实例、controls、observer、监听器和 WebGL context。

## 文件职责

- `BACKLOG.md`：绑定版本的已确认问题、优化顺序、可扩展字段和接入门槛；不把候选清单冒充已实现能力。
- `index.html`：原生三层 DOM、操作、年/月/日/时真太阳时输入、按需 3D 采样连接体开关与 2—4096 层输入、数据边界、表头缩放/避让状态和未接入清单。
- `src/main.ts`：控制面/数据面初始化、所选层联动、历史/算法时间窗口装配与重叠来源覆盖、完整导出和错误处理。
- `src/shell.js`、`src/workbench.css`：模板副本与生命周期包装，不访问 renderer。
- `src/renderer.css`：仅配置全屏画布挂载及局部深色数据舞台；不改工作台控制面样式。
- `src/model.ts`：历史/算法块的判别联合、资产校验、整数时间、完整四柱解码；旧基础投影仅作回归参考。
- `src/algorithm.ts`：本地算法协议校验、真太阳时输入定位请求、负索引分块、跨块连续窗口装配/双并发约束、BigInt 差分与有界记录缓存。
- `src/fields.ts`：35 组字段登记、有限查表、柱间配对连接、完整 JSON 导出。
- `src/volume.ts`：字段行布局、全量或连续窗口的无损状态段、整数纹理编码与分类坐标；按真实采样统计每行每箱的众数集合/胜出次数及相邻集合跳变，不推断交接时刻；唯一实现算法窗口与历史资产重叠时的原始记录优先覆盖及来源摘要合并，正式页面和候选页共享。
- `src/structural-fields.json`：只读生成物，保存 60/600 条目、配对表、节气词表、psql 文本及来源摘要，禁止手改。
- `scripts/build_fields.py`：复用 canonical 内核和固定 provider 生成字段快照；`--check` 只读验证漂移。
- `src/matrix-scene.ts`：同场多块、浮动原点、相机与窗口聚焦、LRU 显存、切片真值文字、矩阵内左侧行表头及碰撞避让、跨块拾取、采样状态带开关；时间/四柱/聚焦角色详情由语义侧栏承载，不重复悬浮在矩阵外。
- `src/time-tile.ts`：每块 RLE 整数纹理、默认隐藏的历史展示层、真实 X 分类槽内的采样众数实例盒体与断开的无损分类带片、接缝裁剪、精确 GPU 拾取及资源释放；混合箱盒体只是显式有损统计格，不代表整个时间箱的分类。
- `framework-poc.html`、`src/framework-poc.ts`：仅用于开发服务的独立 deck.gl 候选入口；复用校验后的真实历史/算法窗口和现有无损段，不进入正式 Vite 单入口产物。算法窗口与初始历史资产重叠时复用产品的历史优先覆盖流程，不把外推同位置记录冒充初始资产；候选通过真实拾取、像素可读性和资源预算前不切换正式页面。锁定的 `@deck.gl/core`、`@deck.gl/mesh-layers` 与其必需 peer `@luma.gl/webgpu` 仅是 `devDependencies`，由 `package-lock.json` 固定解析版本；glTF/纹理链仍有高风险传递依赖告警，未清零前不得并入正式产物。
- `scripts/time_provider.py`：固定 provider 的时间块 CLI、年/月/日/时到时辰索引映射与帧内交节断点（交接时刻、前后相邻采样状态、受影响字位），拒绝日期非法、数值失真和交节与采样状态不自洽的块（含年份位数变化附近的无解释换柱）；无 datetime 年份上限，不修改生产 Profile。
- `scripts/time-api.ts`：Vite dev/preview 同源本地 API，约束时间定位/分块进程的并发、队列、缓存、超时和响应；不进入浏览器 bundle。
- `scripts/import_history.py`：复制并校验已有历史产物，不计算新历法事实。
- `src/model.test.ts`、`src/volume.test.ts`、`src/algorithm.test.ts`：初始数据、编码、负索引和大整数相对坐标回归。
- `tests/demo.spec.ts`：初始体的真实 GPU、模板、交互、导出、来源和失败路径验收。
- `tests/infinite.spec.ts`：真太阳时年/月/日/时定位、局部连接流形 GPU 绘制与跨算法块切换、真实 producer 对照、远期/过去/10000 年、外推 GPU、取消竞态、损坏与有界缓存验收。
- `tests/oracle_solar_terms.py`：离线比较 `lunar-python` 与 `sxtwl` 的有界节气时刻差异；不进入生产运行链。
- `tests/framework-poc.spec.ts`：隔离页 4096 层、119 行、历史接缝及重叠区原始记录摘要、跨 16 算法块、真实 GPU 实例提交及拾取回查的浏览器证据；不替代正式入口验收。

旧“单字段切换、Y 仅四行、单份 Points 缓冲”的实现约束已由用户的全字段 XY 要求替代。旧版保存在 `bazi-infinite-demo-v0.1.0`；固定完整历史体保存在 `bazi-infinite-demo-v0.2.0`。用户本轮“执行”授权用固定算法外推替代有限年份终点；四柱联合、真实性和来源边界不变。

## 验证

`npm run fields:check`、`npm test`、`npm run build`、`npm run test:e2e`。浏览器工件在 `test-results/`。验证读取真实 GPU 整数纹理与绘制范围，不用 DOM 属性替代几何证据。不得放宽超时掩盖性能问题。