AI 项目编码规范

为了统一项目编码风格，提高代码的可读性、可维护性和团队协作效率，特制定本规范。所有项目参与者均需严格遵守。

1. 终端命令

在本项目中，所有终端操作，包括但不限于编译、运行、脚本执行等，均需使用 PowerShell 命令。

• 目的: 确保在 Windows 主开发环境下命令的一致性。
• 要求: 请确保你的开发环境已正确配置 PowerShell，并使用 PowerShell Core (7.x+) 以获得最佳的跨平台兼容性体验。

2. 跨平台宏定义

项目中所有的跨平台宏定义和操作系统判断逻辑，请统一参考和使用根目录 cmake/detect_os.cmake 文件中提供的宏。

• 目的: 集中管理平台相关逻辑，避免在业务代码中出现分散的、重复的平台判断代码。
• 示例: 在 CMakeLists.txt 中需要根据操作系统执行不同操作时，应使用 detect_os.cmake 中定义的 IS_WINDOWS, IS_LINUX 等变量。

3. 目录结构与头文件管理

本项目不设立顶层的 include 文件夹用于存放公共头文件。每个模块所需的头文件（.h, .hpp）和源文件（.cpp）应全部放置在该模块自身的文件夹下。

• 目的: 提高模块的内聚性，使得模块可以被轻松地移植或复用。
• 正确结构示例:

  project/
  ├── src/
  │   ├── moduleA/
  │   │   ├── a.h
  │   │   └── a.cpp
  │   ├── moduleB/
  │   │   ├── b.h
  │   │   └── b.cpp
  │   └── common/
  │       ├── logger.h
  │       └── error.h
  └── cmake/
      ├── detect_os.cmake
      └── retrieve_files.cmake
  

4. 跨平台文件包含

当需要根据不同操作系统包含不同的源文件时，应遵循 cmake/retrieve_files.cmake 文件中定义的规范和函数。

• 目的: 将文件包含的平台差异性逻辑收敛到 CMake 构建系统中，保持 CMakeLists.txt 的整洁。
• 要求: 请勿在业务模块的 CMakeLists.txt 中自行编写 if(WIN32) 等逻辑来添加源文件，应调用 retrieve_files.cmake 中提供的函数来获取平台相关的文件列表。

5. 错误码与异常处理

项目中所有的错误码定义和异常抛出机制，均已在 common 模块的 error.h 文件中统一规定。

• 目的: 统一全项目的错误处理方式，便于问题的定位和跟踪。
• 要求:
  • 在进行错误处理或抛出异常时，必须查阅并使用此文件中已有的定义。
  • 如需新增错误类型，也应在此文件中进行统一扩展，并附上清晰的注释说明。

6. 日志打印

严禁使用 printf、std::cout 等标准输出函数进行调试和日志打印。所有日志信息必须通过 common 模块下的 logger.h 提供的日志接口进行输出。

• 目的: 便于统一管理日志级别（如 DEBUG, INFO, WARNING, ERROR）、输出格式和输出目标（如控制台、文件），方便在不同环境下进行调试和部署。
• 示例:

  // 错误示范
  // std::cout << "加载模型失败" << std::endl;
  
  // 正确示范
  #include "logger.h"
  ...
  log_err("模型加载失败，文件路径：%s", model_path.c_str());
  

7. 注释与日志语言

为了方便团队所有成员的阅读和理解，项目所有的代码注释、日志信息以及代码提交信息（Commit Message） 必须全部使用中文。

• 目的: 消除语言障碍，降低沟通成本，确保信息的准确传达。
• 要求:
  • 代码注释: 对复杂的函数、算法或业务逻辑，必须添加清晰的中文注释。
  • 日志内容: logger.h 输出的日志消息必须为中文。
  • Git Commit: 每次提交的说明信息都应使用中文描述本次变更的内容。