# cg

**Repository Path**: huxiqing/cg

## Basic Information

- **Project Name**: cg
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-28
- **Last Updated**: 2026-07-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 计算机图形学知识平台

Vue 3、Vite 和本地静态资源构建的计算机图形学学习站。当前内容快照包含 139 个知识入口、101 个课程/概念可视化和 12 个离线 Three.js Demo。生产站点使用 Hash 路由，可部署到普通静态文件服务器，不需要后端或运行时外网连接。

## 环境要求

- Node.js `22.18+` 或 `24.12+`
- npm 10+
- 首次执行 E2E 前安装 Playwright Chromium：`npx playwright install chromium`

Windows PowerShell 中可使用 `npm.cmd`、`npx.cmd` 替代 `npm`、`npx`。

## 安装与开发

```powershell
npm install
npm run sync-content
npm run dev
```

默认开发地址由 Vite 输出。应用的全部课程、可视化和 Demo 都从该地址访问，不依赖 Vault 中其他临时服务器。

## 验证与构建

```powershell
npm run validate
npm run test:e2e
npm run build
npm run preview -- --host 127.0.0.1
```

`validate` 依次检查内容契约、运行 Vitest 并生成生产构建。`test:e2e` 使用 Playwright 遍历知识页面、引擎、Demo 和响应式布局。若本机未安装 Playwright Chromium，可临时指定兼容的 Chromium 可执行文件：

```powershell
$env:PLAYWRIGHT_EXECUTABLE_PATH='C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe'
npm run test:e2e
```

## 内容来源

课程源文件位于本项目上级 Obsidian Vault。同步器只读取课程、概念、复习、资源和 Demo 元数据，并将可公开运行的快照写入：

- `src/content/generated/manifest.json`
- `src/content/generated/pages/*.json`
- `src/content/generated/search-index.json`
- `src/content/generated/demos.json`
- `public/demos/00..11`

这些文件是生成物，不应直接编辑。修改 Vault 内容或 Demo 源后运行 `npm run sync-content`，再运行 `npm run check-content`。同步不会修改 `.obsidian/**`、Canvas 或用户工作区状态。

## 可视化覆盖规则

每个 `lesson` 和 `concept` 必须在 `src/visualizations/manifest.js` 中拥有有效配置。当前门禁为 101/101；新增课程或概念但未提供引擎、具名 preset、控件、观察任务和静态降级时，内容检查与覆盖测试会失败。

十二个引擎族分别覆盖渲染循环、数学空间、图形管线、场景图、几何表示、光照、纹理、Shader、阴影后处理、交互动画、性能和现代渲染。引擎按模块动态加载，必须实现 `update`、`resize` 和 `dispose` 生命周期。

## Demo 同步规则

Demo 源位于 Vault 的 `30-Demo实验室/src`。每个实验都必须使用 Three.js 主画布、OrbitControls 和独立主题场景，并公开 `window.__demo3D` 诊断契约。在 Vault 根目录执行 `npm run build:demos` 会将同一份离线 bundle 同时写入 `30-Demo实验室/site/00..11` 与 `cg/public/demos/00..11`。应用通过同源 sandbox iframe 加载 Demo，并提供加载、超时、重新载入和全屏状态。

不要直接修改两处构建输出：下一次构建会覆盖这些文件。需要修正实验时先改 `30-Demo实验室/src`，在 Vault 根目录运行 `npm run build:demos` 与 `npm run test:demos`，再回到 `cg` 运行 `npm run validate` 与 `npm run test:e2e`。

## 目录概览

```text
src/content/          内容编译与运行时仓库
src/features/         阅读、搜索、进度、图谱和实验室
src/visualizations/   12 个模块引擎、规格与生命周期宿主
src/styles/           响应式视觉系统
tests/                Vitest、内容契约与 Playwright E2E
public/demos/         同步生成的 12 个离线 Demo
```