# AGENTS.md - 八字数学图谱

## 目录用途

`.github/apps/bazi-math-web/` 是独立的八字数学可视化产品壳。它消费 canonical timeline API，把离散时辰投影为 42 项可审计数学视图；不得导入或修改 `.github/apps/timeline-web/`。

## 目录结构

```text
bazi-math-web/
├── AGENTS.md
├── index.html
├── package.json
├── playwright.config.ts
├── src/
│   ├── App.tsx
│   ├── ChartView.tsx
│   ├── CartesianChartView.tsx
│   ├── NetworkChartView.tsx
│   ├── StructureChartView.tsx
│   ├── VisualizationWorkspace.tsx
│   ├── advanced-projections.ts
│   ├── api.ts
│   ├── main.tsx
│   ├── math-projection.ts
│   ├── math-visualizations.ts
│   ├── styles.css
│   ├── types.ts
│   ├── visualization-catalog.ts
│   └── visualization-model.ts
├── tests/
├── tsconfig.json
└── vite.config.ts
```

## 职责边界

- `visualization-catalog.ts` 是 42 项目录的单一真相源，固定 S 级 12、A 级 18、经典辅助 12，并为每项登记理论、数学对象、编码、版本和数据契约。
- `advanced-projections.ts` 只从 typed timeline DTO 构建共享特征张量、过滤图、二维边界秩、Euler、Betti、Laplacian、Hodge、W1、矩阵 Profile、Diffusion、Haar 与秩一张量等无 I/O 原语。
- `visualization-model.ts` 为每个目录 ID 构建独立 ECharts option、文本等价物、指标和覆盖缺口；不得把近似算法、相似度、布局或证据分描述为概率、因果、吉凶或科学证明。
- `ChartView.tsx` 只拥有 ECharts 公共生命周期、resize、事件和 dispose。
- `CartesianChartView.tsx`、`NetworkChartView.tsx`、`StructureChartView.tsx` 按图型拆分 ECharts 注册，避免首个活动图加载全部 42 项图型。
- `VisualizationWorkspace.tsx` 组织分组目录、单活动图实例、共享选中时辰、当前帧遥测、时辰扫描轨和文本等价物，不请求 API。
- `math-projection.ts` 负责 timeline 文本读取和既有固定时距辅助，不计算命理规则。
- `math-visualizations.ts` 保留 0171 的基础有限代数、ILR、递归、关系、Belnap 与 Evidence DAG 原语，供高级投影复用。
- `styles.css` 只服务于数学画布、目录控制面、信息层级、可读性和响应式退化；不得用装饰动画替代数据反馈。
- `api.ts` 只调用 `/api/v1/timeline/point` 与 `/api/v1/timeline/window`，15 秒超时且不自动重试。
- `App.tsx` 负责输入、候选显式选择、固定 25 帧窗口和产品错误边界。
- ECharts 是文本结果的增强视图，不得成为唯一信息来源。
- 禁止 WebGL 和伪 3D 事实声明；环面结与高维对象只允许使用声明过投影损失的二维正交或重心投影。
- 任一投影最多处理 129 帧；DOM 同时只挂载一个主图实例；当前时辰关系力导向最多 32 节点且关闭布局动画。

## 依赖方向

- `App.tsx -> api.ts + VisualizationWorkspace.tsx + math-projection.ts + types.ts`
- `VisualizationWorkspace.tsx -> advanced-projections.ts + visualization-catalog.ts + visualization-model.ts + lazy chart family views`
- `visualization-model.ts -> advanced-projections.ts + math-visualizations.ts + typed timeline DTO`
- `advanced-projections.ts -> math-visualizations.ts + math-projection.ts`
- `api.ts -> delivery timeline API`
- 禁止 `bazi-math-web -> timeline-web`

## 验证

- `npm --prefix .github/apps/bazi-math-web test`
- `npm --prefix .github/apps/bazi-math-web run typecheck`
- `npm --prefix .github/apps/bazi-math-web run build`
- `npm --prefix .github/apps/bazi-math-web run test:e2e`
- `bash .github/scripts/bazi-math-web.sh --mode all`