# HeurAMS-K: HeurAMS 的 Kirigami 现代前端

## 概述

"潜进K型" (HeurAMS-K) 是 [潜进 (HeurAMS)](https://git.pluv27.top/pluv/HeurAMS) 的现代跨平台图形用户界面前端,  
基于 KDE 用户界面框架 **Kirigami** 与 **Qt6** / **KDE Framework6** 构建, 旨在为潜进核心调度器提供遵循 KDE 设计风格的现代原生体验.

> [!NOTE]
> HeurAMS-K 目前处于早期开发阶段, 已建立完整的 CMake 构建框架、QML 模块结构和 Flatpak/Android 打包基础设施.
> 当前图形界面仅包含功能演示级别内容, 尚未与潜进 Python 核心程序库实现对接.

HeurAMS-K 将通过 **PyOtherSide** 直接复用 HeurAMS Python 内核,  
实现"现代化 UI + 成熟核心"的架构, 同时支持 Windows、Linux、macOS、Android 和 Plasma Mobile 平台.

## 特性

### 技术栈

- **Qt6** (≥ 6.8.0) + **KF6** (≥ 6.12.0) + **Kirigami Addons** (≥ 1.10.0)
- **Kirigami** 自适应 UI 框架 — 一套代码适配桌面与移动端
- **QML** 声明式界面 — 组件化、可扩展
- **KConfig** 配置框架 — 类型安全的设置管理
- **ECM QML Module** — 模块化 QML 扩展
- **Flatpak** 打包 — 沙箱化 Linux 分发
- **Android** 原生支持 — 通过 `androiddeployqt` 构建 APK/AAB

### 项目架构

```
HeurAMS-K/
├── CMakeLists.txt              # 顶层 CMake 构建配置
├── src/
│   ├── CMakeLists.txt          # 静态库与可执行文件构建
│   ├── main.cpp                # 入口点 (KirigamiApp)
│   ├── heuramsapplication.h/cpp  # 应用类 (AbstractKirigamiApplication)
│   ├── heuramsconfig.kcfg      # KConfig 设置定义
│   ├── heuramsconfig.kcfgc     # KConfig 代码生成配置
│   ├── qml/
│   │   └── Main.qml            # 主窗口 (StatefulWindow)
│   └── settings/
│       ├── CMakeLists.txt
│       ├── HeurAMSConfigurationView.qml  # 配置视图
│       └── GeneralPage.qml               # 通用设置页
├── android/
│   ├── AndroidManifest.xml
│   ├── build.gradle
│   └── res/                    # Android 资源
├── .flatpak-manifest.json      # Flatpak 构建清单
├── top.pluv27.heurams.kiri.desktop     # .desktop 文件
├── top.pluv27.heurams.kiri.metainfo.xml  # AppStream 元数据
├── .clang-format               # 代码格式化配置
└── LICENSES/                   # REUSE 规范的许可证文件
```

### QML 模块

- `top.pluv27.heurams.kiri` — 主模块 (Main.qml, HeurAMSApplication)
- `top.pluv27.heurams.kiri.settings` — 设置模块 (ConfigurationView, GeneralPage)

### 构建依赖

| 依赖 | 最低版本 |
|------|----------|
| CMake | ≥ 3.24 |
| Qt6 (Qml, Widgets) | ≥ 6.8.0 |
| KF6 (Kirigami, CoreAddons, Config, I18n) | ≥ 6.12.0 |
| Kirigami Addons | ≥ 1.10.0 |

## 快速开始

### 从源码构建

```bash
# 1. 安装依赖 (以 Debian/Ubuntu 为例)
sudo apt install cmake extra-cmake-modules qt6-base-dev qt6-declarative-dev \
    libkf6kirigami-dev libkf6coreaddons-dev libkf6config-dev libkf6i18n-dev \
    kirigami-addons-dev

# 2. 配置与构建
cd HeurAMS-K
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

# 3. 运行
./build/src/heurams
```

### Flatpak 构建

```bash
flatpak-builder --user --install flatpak-build .flatpak-manifest.json
flatpak run top.pluv27.heurams.kiri
```

### Android 构建

需安装 Qt Android 工具链与 Android SDK/NDK, 然后:

```bash
cmake -B build-android \
    -DCMAKE_TOOLCHAIN_FILE=/path/to/android-toolchain.cmake \
    -DQT_HOST_PATH=/path/to/qt-host \
    -DANDROID_SDK_ROOT=$ANDROID_SDK_ROOT \
    -DANDROID_NDK=$ANDROID_NDK
cmake --build build-android
```

## 项目状态

```
构建框架      ████████████████░░░░  80%  ✅  CMake、QML 模块、静态库
设置系统      ████████████░░░░░░░░  60%  ✅  KConfig + 设置页面
桌面整合      ████████████░░░░░░░░  60%  ✅  .desktop、metainfo、Flatpak
Android 支持  ██████████░░░░░░░░░░  50%  ✅  AndroidManifest、Gradle
界面功能      ██░░░░░░░░░░░░░░░░░░  10%  ⏳  仅功能演示(scaffold)
Python 内核桥  ░░░░░░░░░░░░░░░░░░░   0%  ⏳  待 PyOtherSide 集成
```

## 参与项目

HeurAMS-K 项目需要以下方面的贡献者:

- **C++ / Qt / KDE 框架开发** — 扩展应用层与核心逻辑
- **QML 界面开发** — 设计美观、自适应的学习界面
- **Python 桥接** — PyOtherSide 或类似技术的集成
- **Android / Plasma Mobile** — 移动端适配与测试

请参阅 [潜进主项目贡献指南](https://git.pluv27.top/pluv/HeurAMS/src/branch/main/CONTRIBUTING.md) 了解整体贡献流程.

## 许可证

本项目遵循 REUSE 规范, 各文件头部标注了对应的 SPDX 标识.

| 组件 | 许可证 |
|------|--------|
| 源代码 (C++/QML) | **GPL-2.0-or-later** (大多数文件) |
| CMake 构建文件 | **BSD-2-Clause** / **BSD-3-Clause** |
| KConfig 定义 | **LGPL-2.0-or-later** |
| 元数据 (.desktop, metainfo) | **CC0-1.0** |
| Flatpak 清单 | **FSFAP** |
| Android 构建文件 | **BSD-3-Clause** |

详见 [LICENSES/](LICENSES/) 目录下的许可证全文.