架构概览

本项目刻意保持小架构：一个可执行文件、一条清晰的渲染流水线、显式的数据归属，以及仓库内不再保留任何 AI 工作流或行为控制框架。

设计原则

1. 一个程序，只做一件事 - ray_tracer 负责构建场景、启动 Kernel、输出 PPM 图像。
2. CPU 负责编排，GPU 负责执行 - 场景构建、BVH 构建、CLI 解析在主机侧；求交与着色在设备侧。
3. 按职责分模块 - 按渲染问题拆分代码，而不是按抽象模式或框架层次拆分。
4. 优先删除，而不是加开关 - 对死分支和重复路径直接收敛，不保留低频开关。
5. 显式数据流 - 场景数据上传一次，渲染一次，帧缓冲下载一次。

系统流程

模块边界

模块	职责	边界
include/core/	数学基础与 CUDA 辅助	vec3、ray、常量、CUDA 错误处理、随机工具
include/geometry/	空间查询与命中数据	AABB、BVH、图元求交、命中记录
include/rendering/	渲染算法	camera、material、light、shading、kernel、validation
include/scene/	场景装配	场景容器与内置场景工厂
include/image/	输出格式	色调映射与 PPM 写入
src/	程序入口	仅保留 CLI 解析和顶层编排
tests/	行为验证	单元测试与属性测试

保留的核心能力

• Blinn-Phong 着色
• 蒙特卡洛路径追踪
• BVH 加速
• 面向受支持的 Phong 单采样路径的光线排序
• demo、Cornell、random 内置场景
• PPM 输出与色调映射

明确废弃的方向

• AI 工作流框架或仓库内的 Agent 控制层
• 对同一渲染步骤的重复架构实现
• 根目录 CHANGELOG.md 之外的变更历史系统
• 没有测试、没有文档、半接入状态的功能
• 不能提升性能或可维护性的重配置抽象

重构规则

1. 新逻辑优先放入现有模块，除非确实出现新的职责边界。
2. 优先使用简单结构体和自由函数，避免过度间接层。
3. 新增类型前先复用现有 scene、material、geometry 结构。
4. CUDA 错误必须通过 CUDA_CHECK() / CUDA_CHECK_LAST() 显式处理。
5. 死代码直接删除，不通过未使用开关隐藏。
6. 行为变化必须同步更新测试和文档。
7. 项目变更历史只记录在根目录 CHANGELOG.md。

数据归属

• 主机侧负责 CLI 解析、场景构建、BVH 构建和文件输出。
• 设备侧负责热点渲染路径。
• 场景缓冲区在渲染前拷贝到 GPU。
• 帧缓冲区在渲染结束后一次性回传。

实用准则

• 不能提升图像质量、性能或可维护性的功能，不要加。
• 两条代码路径解决同一个问题时，收敛成一条。
• 文档描述的系统如果已经不存在，就删除或重写。