.cursorrules

# Bit HCI Project - Cursor AI Rules

## 🎯 项目概述

**Bit HCI** 是一个基于 C++20 和 Vulkan 1.3 构建的统一人机交互基础设施，包含：
- **BitUI**: 声明式 UI 框架（类似 SwiftUI）
- **BitUI 编译器**: LLVM 前端编译器
- **Native 运行时**: Vulkan 渲染引擎和窗口管理
- **组件库**: 15+ 个可复用 UI 组件

**技术栈**:
- 语言: C++20, LLVM IR, BitUI DSL
- 渲染: Vulkan 1.3
- 构建: CMake 3.24+, Visual Studio 2022
- 平台: Windows (Win32), 计划支持 Linux

---

## 📁 项目结构

```
Bit HCI/
├── CMakeLists.txt          # 顶层统一构建配置
├── BUILD_GUIDE.md          # 快速构建指南
│
├── compiler/               # BitUI 编译器 (LLVM 前端)
│   ├── include/           # 编译器头文件 (lexer, parser, ast, codegen)
│   ├── src/               # 编译器实现
│   ├── examples/          # BitUI 语法示例
│   └── build/Release/     # bitui.exe + bitui_compiler.lib
│
├── native/                # Native 运行时容器
│   ├── include/          # 公共 API (runtime_api.h)
│   ├── src/              # 实现
│   │   ├── main.cpp      # 主入口
│   │   ├── platform/     # Win32 窗口层
│   │   ├── vk/           # Vulkan 渲染引擎
│   │   └── runtime/      # 运行时实现 (runtime_impl.h, component_loader.h)
│   └── CMakeLists.txt
│
├── examples/              # 示例组件
│   ├── cpp/              # C++ 实现的组件 (15 个)
│   │   └── [component]/  # 每个组件独立目录
│   │       ├── [component].cpp
│   │       ├── CMakeLists.txt
│   │       ├── README.md
│   │       └── assets/shaders/  # GLSL 着色器
│   └── bit/              # BitUI 框架组件 (规划中)
│
├── build/                # 统一构建输出目录
│   ├── bin/             # bitui_native.exe + *.dll (所有组件)
│   └── lib/             # 静态库
│
├── docs/                # 文档中心
│   ├── architecture/    # 架构设计文档
│   ├── guides/          # 开发指南
│   ├── progress/        # 进度追踪
│   └── reports/         # 项目报告 (40+ 个，需要归档)
│
└── scripts/             # 构建脚本
    ├── rebuild.bat      # 完整重建
    ├── configure.bat    # 配置 CMake
    ├── build.bat        # 批量构建
    └── clean.bat        # 清理产物
```

---

## 💻 编码规范

### C++ 代码规范

#### 命名约定
```cpp
// 类名: PascalCase
class TriangleComponent : public BitHCI::IComponent {};
class VkApp {};

// 函数/方法: camelCase
void onUpdate(float deltaTime);
void beginFrame();

// 变量: camelCase
float rotation = 0.0f;
int frameCount = 0;

// 成员变量: camelCase (不使用前缀)
BitHCI::IRenderer* renderer;
float deltaTime;

// 常量: UPPER_CASE
const int MAX_VERTICES = 1024;
const float PI = 3.14159265359f;

// 命名空间: PascalCase
namespace BitHCI {}

// 文件名: snake_case 或 PascalCase
runtime_impl.h    // 推荐
component_loader.h
VkApp.cpp         // 可接受
```

#### 代码风格
```cpp
// 1. 使用 C++20 标准
#include <concepts>
#include <ranges>

// 2. 头文件包含顺序
#include "runtime_api.h"      // 本项目头文件
#include <vulkan/vulkan.h>    // 第三方库
#include <vector>             // 标准库
#include <windows.h>          // 系统头文件

// 3. RAII 原则 - 资源自动管理
class ResourceWrapper {
    VkBuffer buffer;
public:
    ResourceWrapper() { /* 创建资源 */ }
    ~ResourceWrapper() { /* 自动清理 */ }
};

// 4. 智能指针优先
std::unique_ptr<Component> component;
std::shared_ptr<Resource> resource;

// 5. const 正确性
void process(const std::vector<float>& data) const;

// 6. 使用 override 关键字
void onUpdate(float deltaTime) override;

// 7. 初始化列表
TriangleComponent() 
    : rotation(0.0f)
    , scale(1.0f)
    , isPaused(false) {}

// 8. 注释风格
/**
 * 类/函数的详细说明 (Doxygen 风格)
 * @param deltaTime 时间增量
 * @return 是否成功
 */
bool update(float deltaTime);

// 行内注释
float rotation = 0.0f;  // 当前旋转角度（度）
```

### 组件开发规范

#### 组件模板
```cpp
#include "runtime_api.h"
#include <cmath>

class MyComponent : public BitHCI::IComponent {
private:
    // 运行时接口（必需）
    BitHCI::IWindow* window = nullptr;
    BitHCI::IRenderer* renderer = nullptr;
    BitHCI::IInput* input = nullptr;
    BitHCI::IResourceManager* resources = nullptr;
    
    // 组件状态
    float rotation = 0.0f;
    bool isPaused = false;
    
public:
    // 初始化（必需）
    void onInit(BitHCI::IWindow* window, 
                BitHCI::IRenderer* renderer, 
                BitHCI::IInput* input,
                BitHCI::IResourceManager* resources) override {
        this->window = window;
        this->renderer = renderer;
        this->input = input;
        this->resources = resources;
        
        // 初始化代码
    }
    
    // 更新（必需）
    void onUpdate(float deltaTime) override {
        // 处理输入
        if (input->isKeyJustPressed(VK_SPACE)) {
            isPaused = !isPaused;
        }
        
        // 更新状态
        if (!isPaused) {
            rotation += deltaTime * 45.0f;  // 45度/秒
        }
    }
    
    // 渲染（必需）
    void onRender() override {
        // 绘制图形
        renderer->beginFrame();
        // ... 绘制调用
        renderer->endFrame();
    }
    
    // 清理（必需）
    void onDestroy() override {
        // 清理资源
    }
};

// 导出组件（必需）
BITHCI_COMPONENT(MyComponent)
```

#### 组件坐标系统
```cpp
// 组件使用像素坐标系统（不是 NDC）
// 原点在窗口左上角，X 向右，Y 向下

// 示例：在窗口中心绘制矩形
int centerX = window->getWidth() / 2;
int centerY = window->getHeight() / 2;
renderer->drawRectangle(centerX - 50, centerY - 50, 100, 100, color);

// 颜色格式：RGB (0.0 - 1.0)
float red[3] = {1.0f, 0.0f, 0.0f};
float green[3] = {0.0f, 1.0f, 0.0f};
float blue[3] = {0.0f, 0.0f, 1.0f};
```

#### Runtime API 使用规范
```cpp
// 1. IRenderer 接口
renderer->beginFrame();                                    // 每帧开始
renderer->drawTriangle(vertices, colors);                  // 三角形
renderer->drawRectangle(x, y, w, h, color);               // 矩形
renderer->drawLine(x1, y1, x2, y2, color, width);         // 线段
renderer->drawCircle(x, y, radius, color);                // 圆形
renderer->drawText("Hello", x, y, color, size);           // 文本
renderer->endFrame();                                      // 每帧结束

// 2. IInput 接口
bool pressed = input->isKeyPressed(VK_SPACE);             // 按键持续按下
bool justPressed = input->isKeyJustPressed(VK_SPACE);     // 按键刚按下
float mouseX, mouseY;
input->getMousePosition(mouseX, mouseY);                  // 鼠标位置（组件坐标）
bool leftClick = input->isMouseButtonPressed(0);          // 鼠标左键
float scrollDelta = input->getMouseScrollDelta();         // 滚轮增量

// 3. IWindow 接口
int width = window->getWidth();                            // 窗口宽度
int height = window->getHeight();                          // 窗口高度
window->setTitle("New Title");                             // 设置标题
```

---

## 🏗️ CMake 规范

### 组件 CMakeLists.txt 模板
```cmake
cmake_minimum_required(VERSION 3.24)
project(my_component)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 包含 Native API
include_directories(${CMAKE_SOURCE_DIR}/../../../native/include)

# 创建组件 DLL
add_library(my_component SHARED
    my_component.cpp
)

# Windows 平台配置
if(WIN32)
    target_compile_definitions(my_component PRIVATE BITUI_PLATFORM_WIN32=1)
    if(MSVC)
        target_compile_options(my_component PRIVATE /utf-8)
    endif()
endif()
```

### 着色器编译
```bash
# 每个组件的 assets/shaders/ 目录必须包含：
assets/shaders/
├── triangle.vert           # 顶点着色器
├── triangle.frag           # 片段着色器
├── compile_shaders.bat     # 编译脚本
└── spv/                    # SPIR-V 输出目录
    ├── triangle_vert.spv
    └── triangle_frag.spv

# compile_shaders.bat 内容：
@echo off
glslc triangle.vert -o spv/triangle_vert.spv
glslc triangle.frag -o spv/triangle_frag.spv
```

---

## 📚 文档规范

### 文档分类

```yaml
docs/
├── architecture/      # 永久性文档（核心设计）
├── guides/           # 参考文档（开发指南）
├── api/              # API 文档
├── progress/         # 进度文档（动态更新）
└── archive/          # 历史归档（按年月）
```

### 文档命名
```bash
# 使用 kebab-case
✅ system-overview.md
✅ getting-started.md
✅ component-development-guide.md

# 避免
❌ System_Overview.md       # 不用下划线
❌ SystemOverview.md        # 不用 PascalCase
❌ doc-2025-10-12.md        # 活跃文档不带日期

# 语言标记
api-reference.md            # 默认英文
api-reference.zh-CN.md      # 中文版本
```

### 文档元数据
```markdown
---
title: 文档标题
status: active | stable | draft | deprecated | archived
type: architecture | guide | api | progress | report
author: 作者名
created: 2025-10-12
last_updated: 2025-10-12
version: 1.0
---

# 文档标题

内容...
```

### README 规范
```markdown
# 模块名称

> **简短描述**  
> **版本**: v0.0.1  
> **最后更新**: 2025-10-12

## 🎯 功能概述
简要说明模块功能...

## 🚀 快速开始
快速上手步骤...

## 📖 详细文档
链接到详细文档...

## 🔗 相关资源
- [相关文档1](link)
- [相关文档2](link)
```

---

## 🔄 Git 工作流

### Commit 消息规范
```bash
# 格式: <type>(<scope>): <subject>

# Type:
feat:     新功能
fix:      修复 bug
docs:     文档更新
style:    代码格式（不影响功能）
refactor: 重构
perf:     性能优化
test:     测试
chore:    构建/工具变更

# 示例:
feat(compiler): add support for conditional rendering
fix(native): correct shader path resolution
docs: update build guide
refactor(examples): simplify component structure
chore(build): update CMake to 3.24
```

### 分支策略
```bash
main          # 主分支，稳定版本
develop       # 开发分支
feature/*     # 功能分支
bugfix/*      # 修复分支
docs/*        # 文档分支
```

---

## 🛠️ 构建和运行

### 标准构建流程
```bash
# 1. 完整构建（推荐）
scripts\rebuild.bat

# 2. 分步构建
scripts\configure.bat    # 配置 CMake
scripts\build.bat        # 构建所有组件
scripts\clean.bat        # 清理产物

# 3. 运行组件
cd build\bin
.\bitui_native.exe .\triangle.dll
.\bitui_native.exe .\button.dll
```

### 编译器使用
```bash
cd compiler/build/Release

# 编译为 LLVM IR
.\bitui.exe -o output.ll -f ir input.bitui

# 编译为目标文件
.\bitui.exe -o output.o -f obj input.bitui
```

---

## ⚠️ 常见问题和最佳实践

### 路径问题
```cpp
// ❌ 错误：绝对路径
#include "D:/_Bit_OS/Bit HCI/native/include/runtime_api.h"

// ✅ 正确：相对路径或 CMake 配置的包含路径
#include "runtime_api.h"

// 着色器路径（从 build/bin/ 运行）
std::string shaderPath = "../../examples/cpp/" + componentName + "/assets/shaders/spv/";
```

### 内存管理
```cpp
// ❌ 错误：手动管理
float* vertices = new float[9];
// ... 可能忘记 delete

// ✅ 正确：使用智能指针或 RAII
std::vector<float> vertices(9);
std::unique_ptr<float[]> vertices(new float[9]);
```

### 渲染坐标
```cpp
// ❌ 错误：使用 NDC 坐标 (-1.0 到 1.0)
renderer->drawRectangle(-0.5f, -0.5f, 1.0f, 1.0f, color);

// ✅ 正确：使用像素坐标
int width = window->getWidth();
int height = window->getHeight();
renderer->drawRectangle(width/2 - 50, height/2 - 50, 100, 100, color);
```

### 输入检测
```cpp
// ❌ 错误：在 onRender() 中处理输入
void onRender() override {
    if (input->isKeyPressed(VK_SPACE)) { /* ... */ }
    renderer->drawTriangle(vertices, colors);
}

// ✅ 正确：在 onUpdate() 中处理输入
void onUpdate(float deltaTime) override {
    if (input->isKeyPressed(VK_SPACE)) {
        // 处理输入
    }
}

void onRender() override {
    // 只做渲染
    renderer->drawTriangle(vertices, colors);
}
```

### 组件生命周期
```cpp
// 正确的调用顺序：
// 1. onInit()     - 初始化资源
// 2. onUpdate()   - 每帧更新（持续）
// 3. onRender()   - 每帧渲染（持续）
// 4. onDestroy()  - 清理资源

// ❌ 错误：在 onUpdate() 中初始化
void onUpdate(float deltaTime) override {
    if (firstFrame) {
        // 应该在 onInit() 中做
    }
}

// ✅ 正确：在正确的阶段做正确的事
void onInit(...) override {
    // 一次性初始化
}

void onUpdate(float deltaTime) override {
    // 每帧更新状态
}
```

---

## 🎓 术语表

| 术语 | 定义 | 使用场景 |
|------|------|---------|
| **Bit HCI** | 整体人机交互基础设施项目 | 项目整体描述 |
| **Bit** | 未来的系统级编程语言（规划中）| 长期规划讨论 |
| **BitUI** | 声明式 UI 框架 | 框架和编译器相关 |
| **LLVM 前端** | BitUI 编译器的定位 | 编译器技术描述 |
| **Vulkan 后端** | Bit HCI 的渲染引擎 | 渲染和图形相关 |
| **Native 运行时** | 原生测试窗口和运行容器 | 运行时环境 |
| **组件 (Component)** | 独立的 UI 组件（DLL）| 示例开发 |
| **Runtime API** | Native 提供给组件的接口 | API 设计 |

---

## 🚫 避免的做法

### 代码
```cpp
// ❌ 不要使用原始指针（除非必要）
float* data = new float[100];

// ❌ 不要忘记虚析构函数
class Base {
    // 缺少 virtual ~Base() = default;
};

// ❌ 不要在头文件中使用 using namespace
using namespace std;  // 在 .h 文件中

// ❌ 不要硬编码魔数
if (count > 256) { /* ... */ }

// ✅ 应该定义常量
const int MAX_COUNT = 256;
if (count > MAX_COUNT) { /* ... */ }
```

### 文档
```markdown
❌ 不要创建无日期的临时报告
report.md

❌ 不要在活跃文档中使用日期后缀
api-reference-2025-10-12.md

❌ 不要创建重复内容的文档
component-guide-v1.md
component-guide-v2.md
component-guide-final.md

✅ 应该更新现有文档或归档旧版本
component-guide.md (活跃)
docs/archive/2025/10-october/component-guide-v1.md (归档)
```

### Git
```bash
❌ 不要提交构建产物
git add build/

❌ 不要使用不清晰的提交消息
git commit -m "fix"
git commit -m "update"

❌ 不要强制推送主分支
git push --force origin main

✅ 遵循规范
git commit -m "fix(native): resolve shader loading path issue"
git push origin feature/new-component
```

---

## 🎯 开发优先级

### 当前重点 (2025-10)

1. **编译器完善** (⭐⭐⭐)
   - 修复复杂语法解析
   - 完善类型系统
   - 提高测试覆盖率

2. **Native 增强** (⭐⭐⭐)
   - 图形管线实现
   - 输入系统完善
   - 资源管理器

3. **文档整理** (⭐⭐)
   - 归档历史报告
   - 更新核心文档
   - 建立维护机制

### 未来计划

1. **BitUI 集成** - 编译器与运行时集成
2. **跨平台支持** - Linux 平台移植
3. **性能优化** - 渲染性能提升
4. **工具链** - LSP、调试器、Playground

---

## 📖 关键文档索引

### 新人入门
1. [README.md](README.md) - 项目入口
2. [BUILD_GUIDE.md](BUILD_GUIDE.md) - 构建指南
3. [docs/architecture/system-overview.md](docs/architecture/BIT_HCI_ARCHITECTURE.md) - 系统架构
4. [docs/guides/getting-started.md](docs/guides/UNIFIED_BUILD_SYSTEM.md) - 快速开始

### 开发参考
1. [native/include/runtime_api.h](native/include/runtime_api.h) - Runtime API
2. [examples/cpp/README.md](examples/cpp/README.md) - 组件开发指南
3. [compiler/README.md](compiler/README.md) - 编译器使用
4. [docs/progress/PROGRESS.md](docs/progress/PROGRESS.md) - 开发进度

### 架构设计
1. [docs/architecture/BIT_HCI_ARCHITECTURE.md](docs/architecture/BIT_HCI_ARCHITECTURE.md)
2. [docs/architecture/COMPILER_ARCHITECTURE_GUIDE.md](docs/architecture/COMPILER_ARCHITECTURE_GUIDE.md)
3. [native/README.md](native/README.md) - Native 架构

---

## 🤖 AI 助手指引

### 代码生成时
1. **始终遵循项目命名规范**（PascalCase 类名，camelCase 函数/变量）
2. **使用 C++20 特性**（concepts, ranges, 智能指针）
3. **添加详细注释**（类、函数、复杂逻辑）
4. **包含错误处理**（检查空指针，验证参数）
5. **遵循 RAII 原则**（资源自动管理）

### 文档编写时
1. **使用 kebab-case** 文件名
2. **添加文档元数据**（YAML front matter）
3. **包含代码示例**（实际可运行的代码）
4. **链接相关文档**（建立文档网络）
5. **保持简洁清晰**（使用标题、列表、代码块）

### 问题解决时
1. **先查阅现有文档**（README、guides、architecture）
2. **检查相似组件**（examples/cpp/ 中的实现）
3. **参考 Runtime API**（native/include/runtime_api.h）
4. **遵循项目结构**（不创建新的不一致的目录）
5. **更新相关文档**（代码变更后更新文档）

### 文件操作时
1. **不要直接修改 build/ 目录**（自动生成的）
2. **着色器放在 assets/shaders/**（每个组件独立）
3. **DLL 输出到 build/bin/**（统一输出目录）
4. **文档归档到 docs/archive/YYYY/MM-month/**
5. **临时文件放在 docs/internal/**（如果必须保留）

---

## 📌 版本信息

- **项目版本**: v0.0.1
- **C++ 标准**: C++20
- **CMake 版本**: 3.24+
- **Vulkan 版本**: 1.3
- **LLVM 版本**: 21.1.3
- **目标平台**: Windows (Win32), Linux (计划中)

---

**规则文件版本**: 1.0  
**最后更新**: 2025-10-12  
**维护者**: Bit Project Team

---

## 🔗 快速链接

- [项目主页](README.md)
- [构建指南](BUILD_GUIDE.md)
- [文档中心](docs/README.md)
- [组件开发](examples/cpp/README.md)
- [Runtime API](native/include/runtime_api.h)
- [开发进度](docs/progress/PROGRESS.md)
- [文档管理方案](docs/DOCUMENTATION_MANAGEMENT_PLAN.md)

---

**提示**: 此规则文件应该随着项目演进不断更新。如果发现任何不一致或过时的规则，请及时更新。