Develop

.clang-tidy

@@ -0,0 +1,86 @@
+# .clang-tidy — naming & style checks for clangd / manual clang-tidy.
+#
+# Status: CONFIG-ONLY. Not run in pre-commit or CI (see AGENT.md "Code Quality
+# Discipline"). clangd reads this automatically for in-editor hints; to silence
+# naming noise temporarily, comment out `readability-identifier-naming` in Checks.
+# Naming rules mirror AGENT.md "Code Style": PascalCase types, camelCase methods,
+# snake_case files/variables, UPPER_CASE constants, lower_case namespaces.
+---
+Checks: >
+  -*,
+  readability-identifier-naming,
+  bugprone-assert-side-effect,
+  bugprone-bool-pointer-implicit-conversion,
+  bugprone-copy-constructor-init,
+  bugprone-dangling-handle,
+  bugprone-fold-init-type,
+  bugprone-forwarding-reference-overload,
+  bugprone-inaccurate-cast,
+  bugprone-incorrect-roundings,
+  bugprone-infinite-loop,
+  bugprone-integer-division,
+  bugprone-misplaced-widening-cast,
+  bugprone-move-forwarding-reference,
+  bugprone-multiple-statement-macro,
+  bugprone-string-constructor,
+  bugprone-suspicious-enum-usage,
+  bugprone-suspicious-memset-usage,
+  bugprone-undefined-memory-manipulation,
+  bugprone-use-after-move,
+  bugprone-virtual-near-miss,
+  modernize-deprecated-headers,
+  modernize-loop-convert,
+  modernize-make-shared,
+  modernize-make-unique,
+  modernize-pass-by-value,
+  modernize-redundant-void-arg,
+  modernize-replace-auto-ptr,
+  modernize-replace-random-shuffle,
+  modernize-return-braced-init-list,
+  modernize-shrink-to-fit,
+  modernize-unary-static-assert,
+  modernize-use-bool-literals,
+  modernize-use-default-member-init,
+  modernize-use-emplace,
+  modernize-use-equals-default,
+  modernize-use-equals-delete,
+  modernize-use-noexcept,
+  modernize-use-nullptr,
+  modernize-use-override,
+  modernize-use-transparent-functors,
+  modernize-use-using,
+  readability-braces-around-statements,
+  readability-container-size-empty,
+  readability-delete-null-pointer,
+  readability-else-after-return,
+  readability-function-size,
+  readability-non-const-parameter,
+  readability-qualified-auto,
+  readability-redundant-control-flow,
+  readability-redundant-string-cstr,
+  readability-redundant-string-init,
+  readability-simplify-boolean-expr,
+  readability-static-definition-in-anonymous-namespace,
+  readability-string-compare,
+  readability-uniqueptr-delete-release,
+  readability-uppercase-literal-suffix,
+WarningsAsErrors: ''
+HeaderFilterRegex: '.*'
+CheckOptions:
+  - { key: readability-identifier-naming.ClassCase,            value: CamelCase  }
+  - { key: readability-identifier-naming.StructCase,           value: CamelCase  }
+  - { key: readability-identifier-naming.UnionCase,            value: CamelCase  }
+  - { key: readability-identifier-naming.EnumCase,             value: CamelCase  }
+  - { key: readability-identifier-naming.EnumConstantCase,     value: UPPER_CASE }
+  - { key: readability-identifier-naming.TypedefCase,          value: CamelCase  }
+  - { key: readability-identifier-naming.TypeAliasCase,        value: CamelCase  }
+  - { key: readability-identifier-naming.FunctionCase,         value: camelBack }
+  - { key: readability-identifier-naming.MethodCase,           value: camelBack }
+  - { key: readability-identifier-naming.ParameterCase,        value: camelBack }
+  - { key: readability-identifier-naming.VariableCase,         value: camelBack }
+  - { key: readability-identifier-naming.PrivateMemberPrefix,  value: m_         }
+  - { key: readability-identifier-naming.PrivateMemberCase,    value: camelBack }
+  - { key: readability-identifier-naming.ConstantCase,          value: UPPER_CASE }
+  - { key: readability-identifier-naming.GlobalConstantCase,    value: UPPER_CASE }
+  - { key: readability-identifier-naming.NamespaceCase,        value: lower_case }
+  - { key: readability-identifier-naming.FileIgnoringCase,      value: lower_case }

.claude/commands/architecture.md

@@ -0,0 +1,97 @@
+# /architecture — 架构一致性守护
+
+检查代码是否符合 CFDesktop 三层架构规则。
+
+## 层级定义
+
+### Layer 1: base/ (基础层)
+- **路径**: `base/`
+- **CMake targets**: `cfbase`, `cfbase_headers`, `cfbase_cpu`, `cfbase_memory`, `cfbase_gpu`, `cfbase_network`, `cfbase_console`
+- **允许依赖**: Qt6::Core, OS APIs (POSIX, Win32)
+- **职责**: 硬件探测、工具库、平台抽象
+- **禁止**: 不可感知 UI 或桌面环境概念
+
+### Layer 2: ui/ (UI 框架层)
+- **路径**: `ui/`
+- **CMake targets**: `cfui`, `cf_ui_base`, `cf_ui_core`, `cf_ui_widget_material`, `cf_ui_components_material`
+- **允许依赖**: Qt6::Core, Qt6::Gui, CFDesktop::base
+- **职责**: Material Design 3 组件、主题引擎、动画框架
+- **禁止**: 不可感知桌面环境或窗口管理概念
+
+### Layer 3: desktop/ (桌面环境层)
+- **路径**: `desktop/`
+- **CMake targets**: `CFDesktop_shared`, `CFDesktopMain`, `CFDesktopUi`, `cffilesystem`, `cfconfig`, `cflogger`
+- **允许依赖**: Qt6::Core, Qt6::Gui, Qt6::Widgets, cfbase, cflogger, cfui
+- **职责**: 桌面环境实现、窗口管理、显示后端、配置管理
+
+## 依赖规则 (STRICT)
+
+```
+base/  →  禁止 include ui/ 或 desktop/ 的任何头文件
+ui/    →  禁止 include desktop/ 的任何头文件
+desktop/ → 可以 include ui/ 和 base/ 的头文件
+```
+
+## 检查流程
+
+### Step 1: 确定审查范围
+
+根据用户指定的模块/文件/目录，确定需要检查的文件列表。
+
+### Step 2: 检查 #include 指令
+
+对每个源文件和头文件：
+1. 提取所有 `#include` 行
+2. 将每个 include 映射到其所属层级 (base/ui/desktop/外部)
+3. 标记任何向上依赖（低层级 include 高层级）
+
+**检测模式**：
+- base 层违规: `#include` 匹配 `ui/` 或 `desktop/` 或 `cfui` 或 `CFDesktop`
+- ui 层违规: `#include` 匹配 `desktop/` 或 `CFDesktop_shared`
+
+### Step 3: 检查 CMake 依赖
+
+对每个 `CMakeLists.txt`：
+1. 检查 `target_link_libraries` 只引用同层或更低层
+2. base: 只允许 Qt 和系统库
+3. ui: Qt + CFDesktop::base
+4. desktop: Qt + cfbase + cfui + 自身静态库
+
+### Step 4: 检查接口驱动设计
+
+- 抽象接口应在 `components/` 或 `include/` 目录
+- 具体实现在 `platform/` 或 `private/` 目录
+- 运行时平台选择使用工厂模式
+- 行为变化使用策略模式
+
+### Step 5: 检查平台抽象隔离
+
+平台特定代码必须隔离在 `private/<platform>_impl/` 目录中：
+- `base/system/*/private/linux_impl/` — Linux 实现
+- `base/system/*/private/win_impl/` — Windows 实现
+- `desktop/ui/platform/windows/` — Windows 桌面后端
+- `desktop/ui/platform/linux_wsl/` — Linux/WSL 后端
+
+共享代码（ui/core, ui/widget, base/include）中不得出现平台特定代码。
+
+## 输出格式 (中文)
+
+```markdown
+# 架构一致性报告: <scope>
+
+## 依赖关系图
+(ASCII 图示实际依赖关系)
+
+## 违规项
+| 文件 | 行号 | 违规类型 | 说明 |
+|------|------|----------|------|
+
+## 符合项
+(确认观察到的正确模式)
+
+## 建议修改
+(针对每个违规的具体修复方案)
+```
+
+如果无违规：
+> 架构一致性检查通过，未发现层级依赖违规。

.claude/commands/cross-platform.md

@@ -0,0 +1,116 @@
+# /cross-platform — 跨平台兼容性检查
+
+检查代码的跨平台兼容性，确保正确的平台抽象和隔离。
+
+## 触发方式
+
+- `/cross-platform <模块路径>` — 检查跨平台兼容性
+- Review 流程内部调用
+
+## 支持平台
+
+| 平台 | API | 编译器 |
+|------|-----|--------|
+| Windows 10/11 | Win32, DWM | MSVC, MinGW |
+| Linux/WSL | POSIX, X11, Wayland | GCC, Clang |
+| Embedded ARM | EGLFS, LinuxFB (规划中) | GCC交叉编译 |
+
+## 检查流程
+
+### Step 1: 条件编译检查
+
+#### 合法的平台宏 (优先使用)
+- `Q_OS_WIN` — Windows 平台 (Qt 宏，**首选**)
+- `Q_OS_LINUX` — Linux 平台 (Qt 宏，**首选**)
+- `Q_OS_MAC` — macOS 平台 (Qt 宏)
+- `_WIN32` / `_MSC_VER` — Windows 特定低层代码（可接受）
+- `WIN32` — CMake 级别（可接受）
+
+#### 禁止的宏
+- `__linux__` — 应使用 `Q_OS_LINUX`
+- `__APPLE__` — 应使用 `Q_OS_MAC`
+- `#ifdef _WIN64` — 应使用 `Q_OS_WIN`
+
+#### 路径处理
+- 硬编码路径分隔符 (`"\"` 或 `"/"`) — 应使用 `QDir`/`QFileInfo`
+- 硬编码行尾 — 应使用 `QFile` 自动处理
+- 硬编码临时目录 — 应使用 `QStandardPaths`
+
+### Step 2: 平台抽象目录结构检查
+
+验证平台特定代码的隔离模式：
+
+**正确模式** (base/system/)：
+```
+base/system/cpu/
+├── cfcpu.h              ← 公共头文件（平台无关接口）
+├── cfcpu.cpp            ← 公共实现（调用 host.h）
+└── private/
+    ├── cpu_host.h       ← 平台选择器
+    ├── linux_impl/      ← Linux 实现
+    │   └── cpu_linux.cpp
+    └── win_impl/        ← Windows 实现
+        └── cpu_win.cpp
+```
+
+**正确模式** (desktop/ui/platform/)：
+```
+desktop/ui/platform/
+├── interface.h          ← 平台无关接口
+├── windows/             ← Windows 实现
+└── linux_wsl/           ← Linux/WSL 实现
+```
+
+### Step 3: 共享层纯度检查
+
+以下位置**禁止**包含平台特定代码：
+- `ui/core/` — 主题引擎
+- `ui/widget/` — MD3 控件
+- `ui/components/` — 动画框架
+- `base/include/base/` — 工具头文件
+
+平台特定代码**必须**隔离在：
+- `base/system/*/private/`
+- `desktop/ui/platform/windows/`
+- `desktop/ui/platform/linux_wsl/`
+
+### Step 4: DLL 导出宏检查
+
+验证正确的导出宏使用：
+- base: `CF_BASE_EXPORT`
+- ui: `CF_UI_EXPORT`
+- desktop: `CF_DESKTOP_EXPORT`
+
+每个导出宏应处理 Windows `__declspec` 和 Linux `__attribute__((visibility))`。
+
+### Step 5: 输出报告 (中文)
+
+```markdown
+# 跨平台兼容性报告: <scope>
+
+## 条件编译检查
+### 使用的平台宏
+| 文件 | 行号 | 宏 | 合规 |
+|------|------|-----|------|
+
+### 不符合规范的宏
+(需修改的项，含建议替换)
+
+## 平台抽象层检查
+### 正确隔离的代码
+- ...
+
+### 泄漏到共享层的平台代码
+- ...
+
+## 路径处理检查
+- 合规项: ...
+- 违规项: ...
+
+## DLL 导出检查
+- 合规项: ...
+- 缺失导出宏: ...
+
+## 修复建议
+(按优先级排列的具体修改方案)
+```