144 lines
5.3 KiB
Markdown
144 lines
5.3 KiB
Markdown
# 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/) 目录下的许可证全文.
|