From 4aeefa29125edfdd27d016d953272d11db651cf4 Mon Sep 17 00:00:00 2001
From: pluvium27 <pluvium27@outlook.com>
Date: Fri, 1 May 2026 03:19:19 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=A2=9E=E5=8A=A0=20README.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 143 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 143 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d5bf159
--- /dev/null
+++ b/README.md
@@ -0,0 +1,143 @@
+# 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/) 目录下的许可证全文.