mirror of
https://github.com/wwiinnddyy/LanMountainDesktop.git
synced 2026-06-20 15:44:25 +08:00
0.5.9
中文与插件市场
This commit is contained in:
lincube
@@ -1,27 +1,21 @@
|
|||||||
# LanAirApp
|
# LanAirApp
|
||||||
|
|
||||||
`LanAirApp` 是阑山桌面插件生态的对外发布工作区。
|
## 中文
|
||||||
|
|
||||||
这里集中放置：
|
`LanAirApp` 是阑山桌面插件生态的对外工作区。这个目录是宿主仓库中的镜像副本，权威版本以独立 `LanAirApp` 仓库为准。
|
||||||
- 插件开发标准
|
|
||||||
- 插件打包与构建工具
|
|
||||||
- 插件开发与打包文档
|
|
||||||
- 示例插件
|
|
||||||
|
|
||||||
目录结构：
|
### 目录说明
|
||||||
- `docs/`：插件开发文档、打包文档
|
|
||||||
- `plugins/`：第一方插件项目，例如插件市场插件
|
|
||||||
- `releases/`：已经打包完成、可直接分享与安装的 `.laapp` 插件包
|
|
||||||
- `samples/`：示例插件，其中 `LanMountainDesktop.SamplePlugin` 是示例开发插件
|
|
||||||
- `standards/`：插件标准文件与模板
|
|
||||||
- `tools/`：插件打包与构建工具
|
|
||||||
|
|
||||||
面向用户的安装流程：
|
- `docs/`：插件开发与打包文档。
|
||||||
1. 将插件构建或打包为 `.laapp` 文件。
|
- `samples/`：示例插件与参考项目。
|
||||||
2. 打开 `设置 -> 插件`。
|
- `standards/`：插件清单和目录结构约定。
|
||||||
3. 点击 `打开 .laapp 插件包`。
|
- `tools/`：插件打包与辅助工具。
|
||||||
4. 选择插件包完成安装。
|
|
||||||
|
|
||||||
宿主侧的插件加载、安装、发现、解析与设置页接入逻辑，保留在 `LanMountainDesktop/plugins/`。
|
### 与宿主的关系
|
||||||
|
|
||||||
`LanMountainDesktop.PluginSdk` 仅作为插件开发 SDK 使用，提供 `IPlugin`、`IPluginContext`、清单模型与扩展注册接口。
|
- 宿主程序只连接独立 `LanAirApp` 仓库中的官方市场索引。
|
||||||
|
- 每个插件项目应在仓库根目录提供 `.laapp` 和 `README.md`。
|
||||||
|
|
||||||
|
## English
|
||||||
|
|
||||||
|
`LanAirApp` is the external-facing workspace for the LanMountainDesktop plugin ecosystem. This copy is only a mirror inside the host repository; the standalone `LanAirApp` repository remains the source of truth.
|
||||||
|
|||||||
@@ -1,41 +1,16 @@
|
|||||||
# 插件开发文档
|
# 插件开发指南
|
||||||
|
|
||||||
LanMountainDesktop 插件基于 `LanMountainDesktop.PluginSdk` 开发。
|
## 中文
|
||||||
|
|
||||||
`LanAirApp/` 负责对外发布插件开发标准、示例插件和打包工具；宿主应用内部的插件加载与解析逻辑位于 `LanMountainDesktop/plugins/`。
|
使用 `LanMountainDesktop.PluginSdk` 开发插件时，至少需要准备：
|
||||||
`LanMountainDesktop.PluginSdk` 只提供插件作者需要依赖的开发契约，不再承载宿主侧运行时加载实现。
|
|
||||||
|
|
||||||
## 必需文件
|
|
||||||
- `plugin.json`
|
- `plugin.json`
|
||||||
- `plugin.json` 中声明的入口程序集
|
- 插件入口程序集
|
||||||
- 使用插件入口特性标记的入口类型
|
- 入口类
|
||||||
|
- 本地化资源
|
||||||
|
|
||||||
## 推荐开发流程
|
推荐从示例插件开始，先完成清单、入口、设置页和桌面组件，再逐步扩展业务逻辑。
|
||||||
1. 以 `LanAirApp/samples/LanMountainDesktop.SamplePlugin` 为起点。
|
|
||||||
2. 修改 `plugin.json`，填写你自己的插件 `id`、名称、作者、版本和入口程序集。
|
|
||||||
3. 实现 `IPlugin` 或继承 `PluginBase`。
|
|
||||||
4. 通过 `IPluginContext` 注册服务、设置页和桌面组件。
|
|
||||||
5. 将输出内容打包为 `.laapp` 文件。
|
|
||||||
|
|
||||||
## 运行时能力
|
## English
|
||||||
- 插件可以注册自己的设置页。
|
|
||||||
- 插件可以注册自己的桌面组件。
|
|
||||||
- 插件可以注册自己的服务，并通过插件消息总线进行通信。
|
|
||||||
- 宿主优先加载 `.laapp` 包，其次才是散装清单。
|
|
||||||
|
|
||||||
## 多语言建议
|
To build a plugin with `LanMountainDesktop.PluginSdk`, prepare the manifest, plugin assembly, entrance class, and localization resources first.
|
||||||
- 插件应当内置 `Localization/zh-CN.json` 与 `Localization/en-US.json`。
|
|
||||||
- 插件界面文案、组件文案、状态文案建议统一通过插件本地化层读取。
|
|
||||||
- 建议优先读取宿主传入的语言代码，再回退到插件默认语言。
|
|
||||||
|
|
||||||
## 目录建议
|
|
||||||
一个标准插件项目建议至少包含：
|
|
||||||
- `plugin.json`
|
|
||||||
- `Localization/zh-CN.json`
|
|
||||||
- `Localization/en-US.json`
|
|
||||||
- 插件程序集与依赖文件
|
|
||||||
|
|
||||||
## 示例项目与工具
|
|
||||||
- 示例插件：`LanAirApp/samples/LanMountainDesktop.SamplePlugin`
|
|
||||||
- 打包工具：`LanAirApp/tools/LanMountainDesktop.PluginPackager`
|
|
||||||
- 标准模板：`LanAirApp/standards/plugin.template.json`
|
|
||||||
|
|||||||
@@ -1,34 +1,14 @@
|
|||||||
# 插件打包文档
|
# 插件打包指南
|
||||||
|
|
||||||
LanMountainDesktop 插件的安装包格式固定为 `.laapp`。
|
## 中文
|
||||||
|
|
||||||
`LanAirApp/` 负责提供打包标准与打包工具；`.laapp` 的安装、发现和运行时加载由 `LanMountainDesktop/plugins/` 负责。
|
阑山桌面插件的标准安装格式为 `.laapp`。插件项目应在仓库根目录提供：
|
||||||
|
|
||||||
## `.laapp` 格式说明
|
- `.laapp` 安装包
|
||||||
- 本质上是一个标准 zip 压缩包
|
- `README.md`
|
||||||
- 包根目录必须包含 `plugin.json`
|
|
||||||
- 包根目录还必须包含入口程序集及其依赖
|
|
||||||
|
|
||||||
## 建议打包内容
|
官方市场索引只负责记录链接和校验信息。
|
||||||
- `plugin.json`
|
|
||||||
- `YourPlugin.dll`
|
|
||||||
- 依赖程序集
|
|
||||||
- `Localization/zh-CN.json`
|
|
||||||
- `Localization/en-US.json`
|
|
||||||
- 插件运行所需的其他资源文件
|
|
||||||
|
|
||||||
## 使用打包工具
|
## English
|
||||||
```powershell
|
|
||||||
dotnet run --project .\LanAirApp\tools\LanMountainDesktop.PluginPackager -- --input .\path\to\plugin-output --output .\artifacts\YourPlugin.laapp --overwrite
|
|
||||||
```
|
|
||||||
|
|
||||||
## 应用内安装流程
|
The standard package format is `.laapp`. Plugin repositories should keep the package and `README.md` in the repository root, while the official market index stores metadata and validation data.
|
||||||
1. 打开 `设置 -> 插件`
|
|
||||||
2. 点击 `打开 .laapp 插件包`
|
|
||||||
3. 选择要安装的插件包
|
|
||||||
4. 如果插件注册了设置页或组件，安装后重启应用
|
|
||||||
|
|
||||||
## 注意事项
|
|
||||||
- `plugin.json` 中的 `entranceAssembly` 必须能在包内找到。
|
|
||||||
- 包内应尽量避免无关开发产物。
|
|
||||||
- `.laapp` 是标准安装格式，建议不要对外分发散装目录。
|
|
||||||
|
|||||||
@@ -1,16 +1,9 @@
|
|||||||
# LanMountainDesktop.SamplePlugin
|
# LanMountainDesktop.SamplePlugin
|
||||||
|
|
||||||
这是阑山桌面的**示例开发插件**。
|
## 中文
|
||||||
|
|
||||||
它用于演示以下能力：
|
这是阑山桌面的标准示例插件，用于演示插件清单、设置页、桌面组件、服务注册、本地化和 `.laapp` 打包流程。
|
||||||
- 插件入口与 `plugin.json` 清单
|
|
||||||
- 插件服务注册
|
|
||||||
- 插件设置页注册
|
|
||||||
- 插件桌面组件注册
|
|
||||||
- 插件内通信与状态更新
|
|
||||||
- `.laapp` 打包与安装流程
|
|
||||||
- 插件多语言资源组织方式
|
|
||||||
|
|
||||||
如果你要开发自己的插件，建议以这个目录为模板开始。
|
## English
|
||||||
|
|
||||||
这个目录仅用于示例开发与打包发布，不承载宿主应用内部的插件加载逻辑。
|
This is the standard sample plugin used to demonstrate manifests, settings pages, desktop components, service registration, localization, and `.laapp` packaging.
|
||||||
|
|||||||
@@ -1,11 +1,11 @@
|
|||||||
# 示例插件
|
# 示例插件目录
|
||||||
|
|
||||||
本目录用于存放阑山桌面的示例开发插件。
|
## 中文
|
||||||
|
|
||||||
当前示例：
|
本目录用于存放阑山桌面的示例插件和参考实现。
|
||||||
- `LanMountainDesktop.SamplePlugin`
|
|
||||||
|
|
||||||
说明：
|
当前标准示例为 `LanMountainDesktop.SamplePlugin`。
|
||||||
- 这个插件是**示例开发插件**，用于演示插件项目结构、服务注册、设置页注册、桌面组件注册、`.laapp` 打包与安装流程。
|
|
||||||
- 开发新插件时，建议直接从这个示例插件复制一份再修改。
|
## English
|
||||||
- 示例插件属于 `LanAirApp/` 对外开发工作区；宿主应用里的插件运行时与解析实现位于 `LanMountainDesktop/plugins/`。
|
|
||||||
|
This directory stores sample plugins and reference implementations. The current standard sample is `LanMountainDesktop.SamplePlugin`.
|
||||||
|
|||||||
@@ -1,11 +1,9 @@
|
|||||||
# 插件标准文件
|
# 插件标准说明
|
||||||
|
|
||||||
这里存放 LanMountainDesktop 插件开发所使用的标准模板与约定文件。
|
## 中文
|
||||||
|
|
||||||
当前标准：
|
本目录存放插件开发需要遵循的基础约定，包括 `.laapp`、`plugin.json`、`Localization/` 以及仓库根目录 README 和安装包等要求。
|
||||||
- 安装包扩展名：`.laapp`
|
|
||||||
- 插件清单文件名：`plugin.json`
|
|
||||||
- 多语言资源目录：`Localization/`
|
|
||||||
- 建议内置语言文件：`zh-CN.json`、`en-US.json`
|
|
||||||
|
|
||||||
创建新插件时，建议优先参考本目录中的模板文件。
|
## English
|
||||||
|
|
||||||
|
This directory stores the baseline conventions for plugin development, including `.laapp`, `plugin.json`, `Localization/`, and repository-root deliverables.
|
||||||
|
|||||||
@@ -1,22 +1,35 @@
|
|||||||
# MiSans Font Notice
|
# MiSans 字体说明
|
||||||
|
|
||||||
This app bundles MiSans fonts for consistent cross-device rendering.
|
## 中文
|
||||||
|
|
||||||
## Included files
|
本项目内置 MiSans 字体，用于在不同设备上保持相对一致的文字渲染效果。
|
||||||
|
|
||||||
|
### 包含文件
|
||||||
|
|
||||||
- `MiSans-Regular.ttf`
|
- `MiSans-Regular.ttf`
|
||||||
- `MiSans-Semibold.ttf`
|
- `MiSans-Semibold.ttf`
|
||||||
- `MiSans-Bold.ttf`
|
- `MiSans-Bold.ttf`
|
||||||
|
|
||||||
## Source
|
### 来源
|
||||||
|
|
||||||
|
- 上游仓库：https://github.com/dsrkafuu/misans
|
||||||
|
- 上游所引用的小米字体页面：https://hyperos.mi.com/font/zh/
|
||||||
|
|
||||||
|
### 许可与使用说明
|
||||||
|
|
||||||
|
- 上游脚本或打包仓库使用 Apache-2.0 许可。
|
||||||
|
- MiSans 字体本身的版权和补充使用条款以小米官方说明为准：
|
||||||
|
- https://hyperos.mi.com/font-download/MiSans%E5%AD%97%E4%BD%93%E7%9F%A5%E8%AF%86%E4%BA%A7%E6%9D%83%E8%AE%B8%E5%8F%AF%E5%8D%8F%E8%AE%AE.pdf
|
||||||
|
|
||||||
|
在重新分发本项目时，请自行确认并遵守 MiSans 字体的相关条款。
|
||||||
|
|
||||||
|
## English
|
||||||
|
|
||||||
|
This project bundles MiSans fonts for more consistent cross-device rendering.
|
||||||
|
|
||||||
|
### Sources
|
||||||
|
|
||||||
- Upstream package repository: https://github.com/dsrkafuu/misans
|
- Upstream package repository: https://github.com/dsrkafuu/misans
|
||||||
- Original font source referenced by upstream: https://hyperos.mi.com/font/zh/
|
- Xiaomi font source page: https://hyperos.mi.com/font/zh/
|
||||||
|
|
||||||
## License and usage notes
|
Please review and comply with the MiSans font terms before redistributing this application.
|
||||||
|
|
||||||
- Script/package license in upstream repository: Apache-2.0
|
|
||||||
- MiSans font copyright and additional usage terms:
|
|
||||||
https://hyperos.mi.com/font-download/MiSans%E5%AD%97%E4%BD%93%E7%9F%A5%E8%AF%86%E4%BA%A7%E6%9D%83%E8%AE%B8%E5%8F%AF%E5%8D%8F%E8%AE%AE.pdf
|
|
||||||
|
|
||||||
Please review and comply with the MiSans font terms when distributing this app.
|
|
||||||
|
|||||||
@@ -1,9 +1,12 @@
|
|||||||
# Weather Background Assets
|
# 天气背景资源署名
|
||||||
|
|
||||||
Weather card background images are sourced from **Pexels** and used under the Pexels license:
|
## 中文
|
||||||
https://www.pexels.com/license/
|
|
||||||
|
|
||||||
## Sources
|
本目录中的天气背景图像主要来自 **Pexels**，并按 Pexels License 使用：
|
||||||
|
|
||||||
|
- License: https://www.pexels.com/license/
|
||||||
|
|
||||||
|
### 原始来源
|
||||||
|
|
||||||
- `clear_sky.jpg`
|
- `clear_sky.jpg`
|
||||||
- https://www.pexels.com/photo/a-clear-blue-sky-with-few-clouds-on-a-sunny-day-29390199/
|
- https://www.pexels.com/photo/a-clear-blue-sky-with-few-clouds-on-a-sunny-day-29390199/
|
||||||
@@ -14,16 +17,24 @@ https://www.pexels.com/license/
|
|||||||
- `storm.jpg`
|
- `storm.jpg`
|
||||||
- https://www.pexels.com/photo/sea-under-a-stormy-sky-4609228/
|
- https://www.pexels.com/photo/sea-under-a-stormy-sky-4609228/
|
||||||
|
|
||||||
## Derived Variants (for widget scene mapping)
|
### 派生资源
|
||||||
|
|
||||||
The following files are generated from the above base assets by color grading/brightness adjustments to match the ColorOS-like weather card style:
|
以下文件由上述基础图片经过色彩、亮度或风格调整后生成，用于适配阑山桌面的天气组件视觉：
|
||||||
|
|
||||||
- `clear_day.jpg` (from `clear_sky.jpg`)
|
- `clear_day.jpg`
|
||||||
- `clear_night.jpg` (from `clear_sky.jpg`)
|
- `clear_night.jpg`
|
||||||
- `cloudy_day.jpg` (from `clear_sky.jpg`)
|
- `cloudy_day.jpg`
|
||||||
- `cloudy_night.jpg` (from `clear_sky.jpg`)
|
- `cloudy_night.jpg`
|
||||||
- `rain_light.jpg` (from `rain.jpg`)
|
- `rain_light.jpg`
|
||||||
- `rain_heavy.jpg` (from `rain.jpg`)
|
- `rain_heavy.jpg`
|
||||||
- `storm_dark.jpg` (from `storm.jpg`)
|
- `storm_dark.jpg`
|
||||||
- `fog_haze.jpg` (from `storm.jpg`)
|
- `fog_haze.jpg`
|
||||||
- `snow_soft.jpg` (from `snow.jpg`)
|
- `snow_soft.jpg`
|
||||||
|
|
||||||
|
## English
|
||||||
|
|
||||||
|
The weather background images in this directory are primarily sourced from **Pexels** and used under the Pexels License:
|
||||||
|
|
||||||
|
- License: https://www.pexels.com/license/
|
||||||
|
|
||||||
|
Derived variants in this repository are adjusted from the listed base assets for widget presentation.
|
||||||
|
|||||||
@@ -1,45 +1,23 @@
|
|||||||
# HyperOS3 Weather Assets (Official Xiaomi Package)
|
# HyperOS3 天气资源署名
|
||||||
|
|
||||||
|
## 中文
|
||||||
|
|
||||||
|
本目录中的 HyperOS3 风格天气资源来自用户提供的 Xiaomi Weather 安装包提取内容，以及基于该视觉方向制作的项目内派生资源。
|
||||||
|
|
||||||
|
### 提取来源
|
||||||
|
|
||||||
These assets were extracted from the official Xiaomi Weather APK provided by the user:
|
|
||||||
- Source APK: `c:\Program Files\Netease\GameViewer\Download\MI SKY 12.apk`
|
- Source APK: `c:\Program Files\Netease\GameViewer\Download\MI SKY 12.apk`
|
||||||
- Package: `com.miui.weather2` (Mi Weather)
|
- Package: `com.miui.weather2`
|
||||||
- Extraction date: 2026-03-03
|
- Extraction date: `2026-03-03`
|
||||||
|
|
||||||
Extracted source paths inside APK:
|
### 用途说明
|
||||||
- `assets/map_custom/particle/sun_0.png` -> `hyper_sun_core.png`
|
|
||||||
- `assets/map_custom/particle/sun_1.png` -> `hyper_sun_ring.png`
|
|
||||||
- `assets/map_custom/particle/fog.png` -> `hyper_fog.png`
|
|
||||||
- `assets/map_custom/particle/haze.png` -> `hyper_haze.png`
|
|
||||||
- `assets/map_custom/particle/rain.png` -> `hyper_rain_drop.png`
|
|
||||||
- `assets/map_custom/particle/snow.png` -> `hyper_snow_flake.png`
|
|
||||||
- `assets/map_custom/skybox/top.png` -> `hyper_sky_top.png`
|
|
||||||
- `assets/map_custom/skybox/back.png` -> `hyper_sky_back.png`
|
|
||||||
- `assets/map_custom/skybox/front.png` -> `hyper_sky_front.png`
|
|
||||||
- `assets/map_custom/skybox/left.png` -> `hyper_sky_left.png`
|
|
||||||
- `assets/map_custom/skybox/right.png` -> `hyper_sky_right.png`
|
|
||||||
- `assets/map_custom/skybox/bottom.png` -> `hyper_sky_bottom.png`
|
|
||||||
- `assets/map_assets/VM3DRes/cross_sky_day.png` -> `hyper_cross_sky_day.png`
|
|
||||||
- `assets/map_assets/VM3DRes/cross_sky_night.png` -> `hyper_cross_sky_night.png`
|
|
||||||
|
|
||||||
Extracted weather icon paths inside APK (`res/*.webp`):
|
- 这些资源仅用于项目内部视觉研究、原型还原和界面适配。
|
||||||
- `res/aO.webp` -> `Icons/icon_sunny_day.webp`
|
- 使用时应遵守小米相关许可与使用条款。
|
||||||
- `res/k2.webp` -> `Icons/icon_moon_clear.webp`
|
|
||||||
- `res/Ip.webp` -> `Icons/icon_partly_cloudy_day.webp`
|
|
||||||
- `res/HI.webp` -> `Icons/icon_partly_cloudy_night.webp`
|
|
||||||
- `res/E4.webp` -> `Icons/icon_cloudy.webp`
|
|
||||||
- `res/5f.webp` -> `Icons/icon_rain_light.webp`
|
|
||||||
- `res/fO.webp` -> `Icons/icon_rain_heavy.webp`
|
|
||||||
- `res/lV1.webp` -> `Icons/icon_thunder.webp`
|
|
||||||
- `res/mH1.webp` -> `Icons/icon_snow.webp`
|
|
||||||
- `res/jB.webp` -> `Icons/icon_sleet.webp`
|
|
||||||
- `res/Wl.webp` -> `Icons/icon_haze.webp`
|
|
||||||
- `res/Mg.webp` -> `Icons/icon_windy.webp`
|
|
||||||
|
|
||||||
Use only according to Xiaomi's applicable license and usage terms.
|
### 额外派生资源
|
||||||
|
|
||||||
## Soft Widget Icon Set (2026-03-05)
|
以下文件为项目内基于上述视觉方向制作的派生素材：
|
||||||
|
|
||||||
To better match the Xiaomi weather time-card visual hierarchy, an additional local icon set was generated for this project:
|
|
||||||
|
|
||||||
- `Icons/icon_hero_sun_soft.png`
|
- `Icons/icon_hero_sun_soft.png`
|
||||||
- `Icons/icon_hero_moon_soft.png`
|
- `Icons/icon_hero_moon_soft.png`
|
||||||
@@ -52,4 +30,8 @@ To better match the Xiaomi weather time-card visual hierarchy, an additional loc
|
|||||||
- `Icons/icon_mini_snow_soft.png`
|
- `Icons/icon_mini_snow_soft.png`
|
||||||
- `Icons/icon_mini_fog_soft.png`
|
- `Icons/icon_mini_fog_soft.png`
|
||||||
|
|
||||||
These files are original derivative assets generated in-repo with local tooling, using the extracted Xiaomi package visual direction as reference (soft glow hero icon + lightweight forecast icons).
|
## English
|
||||||
|
|
||||||
|
The HyperOS3-style weather assets in this directory were extracted from a Xiaomi Weather APK provided by the user, together with additional derivative assets created in-repo to match the same visual direction.
|
||||||
|
|
||||||
|
Use these resources only in accordance with Xiaomi's applicable license and usage terms.
|
||||||
|
|||||||
@@ -1,77 +1,38 @@
|
|||||||
# 组件系统模块（Component System Module）
|
# 组件系统说明
|
||||||
|
|
||||||
本目录提供组件系统的模块化基础，用于支持内置组件管理与第三方扩展接入。
|
## 中文
|
||||||
This directory provides the modular foundation for built-in component management and third-party extension integration.
|
|
||||||
|
|
||||||
## 核心文件职责（Core Files）
|
`ComponentSystem/` 提供阑山桌面组件定义、注册和扩展的基础能力。
|
||||||
- `BuiltInComponentIds.cs`：内置组件 ID 常量（例如 `Clock`）。
|
|
||||||
Built-in component ID constants (for example `Clock`).
|
|
||||||
- `DesktopComponentDefinition.cs`：组件元数据定义（名称、类别、最小尺寸、可放置区域等）。
|
|
||||||
Component metadata model (name, category, minimum size, placement permissions).
|
|
||||||
- `ComponentPlacementRules.cs`：组件放置规则（最小尺寸、状态栏高度限制、网格边界约束）。
|
|
||||||
Placement rules (minimum size, status-bar height rule, grid clamping).
|
|
||||||
- `ComponentRegistry.cs`：组件注册中心，负责内置组件与扩展组件合并。
|
|
||||||
Registry that merges built-in and extension components.
|
|
||||||
- `Extensions/IComponentExtensionProvider.cs`：扩展提供者接口契约。
|
|
||||||
Extension provider interface contract.
|
|
||||||
- `Extensions/JsonComponentExtensionProvider.cs`：基于 JSON 的扩展加载器。
|
|
||||||
JSON-based extension loader.
|
|
||||||
|
|
||||||
## 第三方扩展契约（Extension Contract）
|
### 主要职责
|
||||||
- 第三方可通过实现 `IComponentExtensionProvider` 提供组件定义。
|
|
||||||
Third parties can provide component definitions via `IComponentExtensionProvider`.
|
|
||||||
- 当前内置了 JSON 提供者，运行时扫描目录：
|
|
||||||
Built-in JSON provider scans at runtime:
|
|
||||||
- `Extensions/Components/*.json`（相对应用输出目录）
|
|
||||||
`Extensions/Components/*.json` (relative to app output directory)
|
|
||||||
|
|
||||||
## 加载流程（Load Flow）
|
- 管理内置组件 ID 和元数据
|
||||||
1. `ComponentRegistry.CreateDefault()` 先注册内置组件。
|
- 约束组件最小尺寸与可放置区域
|
||||||
Register built-in components first via `ComponentRegistry.CreateDefault()`.
|
- 合并内置组件与扩展组件
|
||||||
2. 调用 `.RegisterExtensions(...)` 合并扩展组件。
|
- 通过 JSON 或扩展提供者接入第三方组件
|
||||||
Merge extension components via `.RegisterExtensions(...)`.
|
|
||||||
3. 主窗口通过注册中心校验组件合法性与放置权限。
|
|
||||||
Main window validates component identity and placement permission through the registry.
|
|
||||||
|
|
||||||
## JSON 清单格式（Manifest Schema）
|
### 关键文件
|
||||||
JSON 文件为数组，每一项代表一个组件定义。
|
|
||||||
The JSON file is an array, where each item represents one component definition.
|
|
||||||
|
|
||||||
```json
|
- `BuiltInComponentIds.cs`：内置组件 ID 常量
|
||||||
[
|
- `DesktopComponentDefinition.cs`：组件元数据模型
|
||||||
{
|
- `ComponentPlacementRules.cs`：放置规则
|
||||||
"id": "Weather",
|
- `ComponentRegistry.cs`：组件注册中心
|
||||||
"displayName": "Weather",
|
- `Extensions/IComponentExtensionProvider.cs`：扩展提供者接口
|
||||||
"iconKey": "WeatherSunny",
|
- `Extensions/JsonComponentExtensionProvider.cs`：JSON 扩展加载器
|
||||||
"category": "Status",
|
|
||||||
"minWidthCells": 1,
|
|
||||||
"minHeightCells": 1,
|
|
||||||
"allowStatusBarPlacement": true,
|
|
||||||
"allowDesktopPlacement": true
|
|
||||||
}
|
|
||||||
]
|
|
||||||
```
|
|
||||||
|
|
||||||
字段说明（Field notes）：
|
### 扩展方式
|
||||||
- `id`：组件唯一 ID（建议英文、稳定不变）。
|
|
||||||
Unique component ID (prefer stable English key).
|
|
||||||
- `displayName`：显示名。
|
|
||||||
Display name.
|
|
||||||
- `iconKey`：图标键（由上层 UI 解释）。
|
|
||||||
Icon key resolved by UI layer.
|
|
||||||
- `category`：组件分类。
|
|
||||||
Component category.
|
|
||||||
- `minWidthCells` / `minHeightCells`：最小占格，必须满足 `>= 1`。
|
|
||||||
Minimum cell size, must satisfy `>= 1`.
|
|
||||||
- `allowStatusBarPlacement`：是否允许放到顶部状态栏。
|
|
||||||
Whether placing in top status bar is allowed.
|
|
||||||
- `allowDesktopPlacement`：是否允许放到桌面区域。
|
|
||||||
Whether placing in desktop area is allowed.
|
|
||||||
|
|
||||||
## 放置规则摘要（Placement Rules Summary）
|
- 当前默认扫描 `Extensions/Components/*.json`
|
||||||
- 最小尺寸约束：`minWidthCells >= 1` 且 `minHeightCells >= 1`。
|
- 组件清单定义显示名、分类、最小尺寸和可放置区域
|
||||||
Minimum size constraint: `minWidthCells >= 1` and `minHeightCells >= 1`.
|
- 主程序通过注册中心统一验证组件是否合法
|
||||||
- 状态栏约束：状态栏组件高度必须为 `1` 格。
|
|
||||||
Status bar constraint: component height must be exactly `1` cell.
|
## English
|
||||||
- 越界约束：所有组件坐标会被网格边界钳制（clamp）。
|
|
||||||
Out-of-bounds constraint: component coordinates are clamped to grid bounds.
|
`ComponentSystem/` contains the foundation for component definition, registration, and extension in LanMountainDesktop.
|
||||||
|
|
||||||
|
### Responsibilities
|
||||||
|
|
||||||
|
- manage built-in component IDs and metadata
|
||||||
|
- enforce placement rules
|
||||||
|
- merge built-in and extension components
|
||||||
|
- support third-party registration through JSON or provider contracts
|
||||||
|
|||||||
@@ -1,75 +1,51 @@
|
|||||||
# Desktop Packaging Guide
|
# 桌面端打包指南
|
||||||
|
|
||||||
## Prerequisites
|
## 中文
|
||||||
- Install `.NET SDK 10`
|
|
||||||
- Windows installer build only:
|
|
||||||
- Install `Inno Setup 6` (`ISCC.exe`)
|
|
||||||
|
|
||||||
## Local packaging commands
|
本指南说明阑山桌面的本地打包和 CI 打包流程。
|
||||||
|
|
||||||
|
### 前置条件
|
||||||
|
|
||||||
|
- 安装 .NET SDK 10
|
||||||
|
- Windows 安装包需要 Inno Setup 6（`ISCC.exe`）
|
||||||
|
|
||||||
|
### 本地打包命令
|
||||||
|
|
||||||
|
#### Windows 安装包
|
||||||
|
|
||||||
### Windows installer (`win-x64`)
|
|
||||||
```powershell
|
```powershell
|
||||||
.\scripts\package.ps1 -RuntimeIdentifier win-x64 -Version 1.0.1
|
.\scripts\package.ps1 -RuntimeIdentifier win-x64 -Version 1.0.1
|
||||||
```
|
```
|
||||||
|
|
||||||
Output:
|
#### Linux 包
|
||||||
- Published files: `artifacts/publish/win-x64`
|
|
||||||
- Installer: `artifacts/installer`
|
|
||||||
|
|
||||||
### Linux package (`linux-x64`)
|
|
||||||
```powershell
|
```powershell
|
||||||
pwsh ./scripts/package.ps1 -RuntimeIdentifier linux-x64 -Version 1.0.1
|
pwsh ./scripts/package.ps1 -RuntimeIdentifier linux-x64 -Version 1.0.1
|
||||||
```
|
```
|
||||||
|
|
||||||
Output:
|
#### macOS 包
|
||||||
- Published files: `artifacts/publish/linux-x64`
|
|
||||||
- Zip package: `artifacts/packages/LanMountainDesktop-1.0.1-linux-x64.zip`
|
|
||||||
|
|
||||||
### macOS package (`osx-x64`)
|
|
||||||
```powershell
|
```powershell
|
||||||
pwsh ./scripts/package.ps1 -RuntimeIdentifier osx-x64 -Version 1.0.1
|
pwsh ./scripts/package.ps1 -RuntimeIdentifier osx-x64 -Version 1.0.1
|
||||||
```
|
```
|
||||||
|
|
||||||
Output:
|
### 产物位置
|
||||||
- Published files: `artifacts/publish/osx-x64`
|
|
||||||
- Zip package: `artifacts/packages/LanMountainDesktop-1.0.1-osx-x64.zip`
|
|
||||||
|
|
||||||
## Optional script flags
|
- 发布目录：`artifacts/publish/<rid>`
|
||||||
```powershell
|
- 安装包或压缩包：`artifacts/installer` 或 `artifacts/packages`
|
||||||
# Publish only (skip Windows installer step)
|
|
||||||
.\scripts\package.ps1 -RuntimeIdentifier win-x64 -SkipInstaller
|
|
||||||
|
|
||||||
# Publish only (skip Linux/macOS zip package step)
|
### CI 流程
|
||||||
pwsh ./scripts/package.ps1 -RuntimeIdentifier linux-x64 -SkipArchive
|
|
||||||
```
|
|
||||||
|
|
||||||
## Runtime dependency notes
|
- 工作流文件：`.github/workflows/windows-ci.yml`
|
||||||
- Linux build does not bundle a native `libvlc` package from NuGet.
|
- 日常构建会验证桌面端可编译
|
||||||
- Install VLC runtime on target machine, for example:
|
- 手动触发或 `v*` 标签可生成正式包并上传到 Release
|
||||||
- Ubuntu/Debian: `sudo apt install vlc libvlc-dev`
|
|
||||||
- macOS packaging target in CI is currently `osx-x64`.
|
|
||||||
|
|
||||||
## CI workflow
|
## English
|
||||||
- Workflow file: `.github/workflows/windows-ci.yml`
|
|
||||||
- Workflow name: `Desktop CI`
|
|
||||||
|
|
||||||
Jobs:
|
This guide covers local packaging and CI packaging for LanMountainDesktop.
|
||||||
- `Validate Build (Windows)` runs on every push and pull request.
|
|
||||||
- Package flow runs on manual trigger or `v*` tag push:
|
|
||||||
- `Resolve Package Version` (single shared version source)
|
|
||||||
- `Package (Windows)` (`win-x64` installer)
|
|
||||||
- `Package (Linux)` (`linux-x64` zip)
|
|
||||||
- `Package (macOS)` (`osx-x64` zip)
|
|
||||||
- On `v*` tags, `Attach Artifacts to GitHub Release` uploads Windows/Linux/macOS packages to the release.
|
|
||||||
|
|
||||||
### Trigger manual packaging
|
### Key points
|
||||||
1. Open GitHub Actions.
|
|
||||||
2. Choose `Desktop CI`.
|
|
||||||
3. Click `Run workflow`.
|
|
||||||
4. Optional: set `version` input, for example `1.0.1`.
|
|
||||||
|
|
||||||
### Trigger by tag
|
- use `scripts/package.ps1` with the target runtime identifier
|
||||||
```powershell
|
- Windows installer requires Inno Setup
|
||||||
git tag v1.0.1
|
- CI can publish artifacts and attach them to GitHub Releases
|
||||||
git push origin v1.0.1
|
|
||||||
```
|
|
||||||
|
|||||||
@@ -242,6 +242,23 @@ public sealed class GitHubReleaseUpdateService : IDisposable
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
public async Task<GitHubReleaseInfo?> GetReleaseByTagAsync(
|
||||||
|
string tagName,
|
||||||
|
CancellationToken cancellationToken = default)
|
||||||
|
{
|
||||||
|
if (string.IsNullOrWhiteSpace(tagName))
|
||||||
|
{
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
|
||||||
|
var url =
|
||||||
|
$"https://api.github.com/repos/{_owner}/{_repo}/releases/tags/{Uri.EscapeDataString(tagName.Trim())}";
|
||||||
|
var responseText = await GetResponseTextAsync(url, cancellationToken);
|
||||||
|
|
||||||
|
using var document = JsonDocument.Parse(responseText);
|
||||||
|
return ParseRelease(document.RootElement);
|
||||||
|
}
|
||||||
|
|
||||||
private async Task<GitHubReleaseInfo?> GetLatestStableReleaseAsync(CancellationToken cancellationToken)
|
private async Task<GitHubReleaseInfo?> GetLatestStableReleaseAsync(CancellationToken cancellationToken)
|
||||||
{
|
{
|
||||||
var url = $"https://api.github.com/repos/{_owner}/{_repo}/releases/latest";
|
var url = $"https://api.github.com/repos/{_owner}/{_repo}/releases/latest";
|
||||||
|
|||||||
@@ -27,6 +27,7 @@ internal sealed class PluginMarketEmbeddedView : UserControl, IDisposable
|
|||||||
private readonly PluginRuntimeService _runtime;
|
private readonly PluginRuntimeService _runtime;
|
||||||
private readonly AirAppMarketIndexService _indexService;
|
private readonly AirAppMarketIndexService _indexService;
|
||||||
private readonly AirAppMarketInstallService _installService;
|
private readonly AirAppMarketInstallService _installService;
|
||||||
|
private readonly AirAppMarketReadmeService _readmeService;
|
||||||
private readonly Version? _hostVersion;
|
private readonly Version? _hostVersion;
|
||||||
|
|
||||||
private readonly TextBox _searchTextBox;
|
private readonly TextBox _searchTextBox;
|
||||||
@@ -38,7 +39,10 @@ internal sealed class PluginMarketEmbeddedView : UserControl, IDisposable
|
|||||||
private AirAppMarketIndexDocument? _document;
|
private AirAppMarketIndexDocument? _document;
|
||||||
private AirAppMarketPluginEntry? _selectedPlugin;
|
private AirAppMarketPluginEntry? _selectedPlugin;
|
||||||
private Dictionary<string, PluginCatalogEntry> _installedPlugins = new(StringComparer.OrdinalIgnoreCase);
|
private Dictionary<string, PluginCatalogEntry> _installedPlugins = new(StringComparer.OrdinalIgnoreCase);
|
||||||
|
private readonly Dictionary<string, string> _readmeContents = new(StringComparer.OrdinalIgnoreCase);
|
||||||
|
private readonly Dictionary<string, string> _readmeErrors = new(StringComparer.OrdinalIgnoreCase);
|
||||||
private string _marketSourceDisplay = AirAppMarketDefaults.DefaultIndexUrl;
|
private string _marketSourceDisplay = AirAppMarketDefaults.DefaultIndexUrl;
|
||||||
|
private string? _loadingReadmePluginId;
|
||||||
private bool _isRefreshing;
|
private bool _isRefreshing;
|
||||||
private bool _isInstalling;
|
private bool _isInstalling;
|
||||||
private bool _hasLoadedOnce;
|
private bool _hasLoadedOnce;
|
||||||
@@ -49,6 +53,7 @@ internal sealed class PluginMarketEmbeddedView : UserControl, IDisposable
|
|||||||
var dataDirectory = Path.Combine(AppContext.BaseDirectory, "Data", "AirAppMarket");
|
var dataDirectory = Path.Combine(AppContext.BaseDirectory, "Data", "AirAppMarket");
|
||||||
_indexService = new AirAppMarketIndexService(new AirAppMarketCacheService(dataDirectory));
|
_indexService = new AirAppMarketIndexService(new AirAppMarketCacheService(dataDirectory));
|
||||||
_installService = new AirAppMarketInstallService(runtime, dataDirectory);
|
_installService = new AirAppMarketInstallService(runtime, dataDirectory);
|
||||||
|
_readmeService = new AirAppMarketReadmeService();
|
||||||
_hostVersion = typeof(App).Assembly.GetName().Version;
|
_hostVersion = typeof(App).Assembly.GetName().Version;
|
||||||
|
|
||||||
_searchTextBox = new TextBox
|
_searchTextBox = new TextBox
|
||||||
@@ -114,6 +119,7 @@ internal sealed class PluginMarketEmbeddedView : UserControl, IDisposable
|
|||||||
|
|
||||||
public void Dispose()
|
public void Dispose()
|
||||||
{
|
{
|
||||||
|
_readmeService.Dispose();
|
||||||
_installService.Dispose();
|
_installService.Dispose();
|
||||||
_indexService.Dispose();
|
_indexService.Dispose();
|
||||||
}
|
}
|
||||||
@@ -223,6 +229,7 @@ internal sealed class PluginMarketEmbeddedView : UserControl, IDisposable
|
|||||||
|
|
||||||
SetStatus(statusMessage, result.Source == AirAppMarketLoadSource.Cache ? WarningBrush : SuccessBrush);
|
SetStatus(statusMessage, result.Source == AirAppMarketLoadSource.Cache ? WarningBrush : SuccessBrush);
|
||||||
RebuildSurface();
|
RebuildSurface();
|
||||||
|
await EnsureReadmeLoadedAsync(_selectedPlugin);
|
||||||
}
|
}
|
||||||
finally
|
finally
|
||||||
{
|
{
|
||||||
@@ -245,6 +252,7 @@ internal sealed class PluginMarketEmbeddedView : UserControl, IDisposable
|
|||||||
|
|
||||||
BuildPluginList(filteredPlugins);
|
BuildPluginList(filteredPlugins);
|
||||||
BuildDetailPanel();
|
BuildDetailPanel();
|
||||||
|
_ = EnsureReadmeLoadedAsync(_selectedPlugin);
|
||||||
}
|
}
|
||||||
|
|
||||||
private List<AirAppMarketPluginEntry> GetFilteredPlugins()
|
private List<AirAppMarketPluginEntry> GetFilteredPlugins()
|
||||||
@@ -372,10 +380,11 @@ internal sealed class PluginMarketEmbeddedView : UserControl, IDisposable
|
|||||||
}
|
}
|
||||||
};
|
};
|
||||||
|
|
||||||
button.Click += (_, _) =>
|
button.Click += async (_, _) =>
|
||||||
{
|
{
|
||||||
_selectedPlugin = plugin;
|
_selectedPlugin = plugin;
|
||||||
RebuildSurface();
|
RebuildSurface();
|
||||||
|
await EnsureReadmeLoadedAsync(plugin);
|
||||||
};
|
};
|
||||||
|
|
||||||
return button;
|
return button;
|
||||||
@@ -454,11 +463,12 @@ internal sealed class PluginMarketEmbeddedView : UserControl, IDisposable
|
|||||||
CreateInfoRow(T("market.detail.min_host_version", "最低宿主版本"), plugin.MinHostVersion),
|
CreateInfoRow(T("market.detail.min_host_version", "最低宿主版本"), plugin.MinHostVersion),
|
||||||
CreateInfoRow(T("market.detail.installed_version", "当前已安装版本"), installedPlugin?.Manifest.Version ?? T("market.detail.not_installed", "未安装")),
|
CreateInfoRow(T("market.detail.installed_version", "当前已安装版本"), installedPlugin?.Manifest.Version ?? T("market.detail.not_installed", "未安装")),
|
||||||
CreateInfoRow(T("market.detail.market_source", "市场源"), _marketSourceDisplay),
|
CreateInfoRow(T("market.detail.market_source", "市场源"), _marketSourceDisplay),
|
||||||
|
CreateInfoRow(T("market.detail.project", "Project"), plugin.ProjectUrl),
|
||||||
CreateInfoRow(T("market.detail.homepage", "主页"), plugin.HomepageUrl),
|
CreateInfoRow(T("market.detail.homepage", "主页"), plugin.HomepageUrl),
|
||||||
CreateInfoRow(T("market.detail.repository", "仓库"), plugin.RepositoryUrl),
|
CreateInfoRow(T("market.detail.repository", "仓库"), plugin.RepositoryUrl),
|
||||||
new TextBlock
|
new TextBlock
|
||||||
{
|
{
|
||||||
Text = T("market.detail.release_notes", "发布说明"),
|
Text = T("market.detail.readme", "README"),
|
||||||
FontSize = 18,
|
FontSize = 18,
|
||||||
FontWeight = FontWeight.SemiBold
|
FontWeight = FontWeight.SemiBold
|
||||||
},
|
},
|
||||||
@@ -469,7 +479,7 @@ internal sealed class PluginMarketEmbeddedView : UserControl, IDisposable
|
|||||||
Padding = new Thickness(14),
|
Padding = new Thickness(14),
|
||||||
Child = new TextBlock
|
Child = new TextBlock
|
||||||
{
|
{
|
||||||
Text = plugin.ReleaseNotes,
|
Text = GetReadmeContent(plugin),
|
||||||
TextWrapping = TextWrapping.Wrap
|
TextWrapping = TextWrapping.Wrap
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@@ -540,6 +550,63 @@ internal sealed class PluginMarketEmbeddedView : UserControl, IDisposable
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
private async Task EnsureReadmeLoadedAsync(AirAppMarketPluginEntry? plugin)
|
||||||
|
{
|
||||||
|
if (plugin is null ||
|
||||||
|
_readmeContents.ContainsKey(plugin.Id) ||
|
||||||
|
string.Equals(_loadingReadmePluginId, plugin.Id, StringComparison.OrdinalIgnoreCase))
|
||||||
|
{
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
_loadingReadmePluginId = plugin.Id;
|
||||||
|
_readmeErrors.Remove(plugin.Id);
|
||||||
|
BuildDetailPanel();
|
||||||
|
|
||||||
|
try
|
||||||
|
{
|
||||||
|
var readme = await _readmeService.LoadAsync(plugin);
|
||||||
|
_readmeContents[plugin.Id] = string.IsNullOrWhiteSpace(readme)
|
||||||
|
? T("market.detail.readme_empty", "README is empty.")
|
||||||
|
: readme.Trim();
|
||||||
|
}
|
||||||
|
catch (Exception ex)
|
||||||
|
{
|
||||||
|
_readmeErrors[plugin.Id] = ex.Message;
|
||||||
|
}
|
||||||
|
finally
|
||||||
|
{
|
||||||
|
_loadingReadmePluginId = null;
|
||||||
|
if (string.Equals(_selectedPlugin?.Id, plugin.Id, StringComparison.OrdinalIgnoreCase))
|
||||||
|
{
|
||||||
|
BuildDetailPanel();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
private string GetReadmeContent(AirAppMarketPluginEntry plugin)
|
||||||
|
{
|
||||||
|
if (_readmeContents.TryGetValue(plugin.Id, out var readme))
|
||||||
|
{
|
||||||
|
return readme;
|
||||||
|
}
|
||||||
|
|
||||||
|
if (_readmeErrors.TryGetValue(plugin.Id, out var error))
|
||||||
|
{
|
||||||
|
return F(
|
||||||
|
"market.detail.readme_error_format",
|
||||||
|
"README could not be loaded: {0}",
|
||||||
|
error);
|
||||||
|
}
|
||||||
|
|
||||||
|
if (string.Equals(_loadingReadmePluginId, plugin.Id, StringComparison.OrdinalIgnoreCase))
|
||||||
|
{
|
||||||
|
return T("market.detail.readme_loading", "Loading README...");
|
||||||
|
}
|
||||||
|
|
||||||
|
return plugin.ReleaseNotes;
|
||||||
|
}
|
||||||
|
|
||||||
private AirAppMarketPluginEntry? ResolveSelectedPlugin(
|
private AirAppMarketPluginEntry? ResolveSelectedPlugin(
|
||||||
string? selectedPluginId,
|
string? selectedPluginId,
|
||||||
IReadOnlyList<AirAppMarketPluginEntry> plugins)
|
IReadOnlyList<AirAppMarketPluginEntry> plugins)
|
||||||
|
|||||||
@@ -14,6 +14,7 @@ internal sealed class AirAppMarketInstallService : IDisposable
|
|||||||
{
|
{
|
||||||
private readonly PluginRuntimeService _runtime;
|
private readonly PluginRuntimeService _runtime;
|
||||||
private readonly HttpClient _httpClient;
|
private readonly HttpClient _httpClient;
|
||||||
|
private readonly AirAppMarketReleaseResolverService _releaseResolverService;
|
||||||
private readonly string _downloadsDirectory;
|
private readonly string _downloadsDirectory;
|
||||||
|
|
||||||
public AirAppMarketInstallService(PluginRuntimeService runtime, string dataDirectory)
|
public AirAppMarketInstallService(PluginRuntimeService runtime, string dataDirectory)
|
||||||
@@ -25,6 +26,7 @@ internal sealed class AirAppMarketInstallService : IDisposable
|
|||||||
Timeout = TimeSpan.FromMinutes(2)
|
Timeout = TimeSpan.FromMinutes(2)
|
||||||
};
|
};
|
||||||
_httpClient.DefaultRequestHeaders.UserAgent.ParseAdd("LanMountainDesktop-PluginMarketplace/1.0");
|
_httpClient.DefaultRequestHeaders.UserAgent.ParseAdd("LanMountainDesktop-PluginMarketplace/1.0");
|
||||||
|
_releaseResolverService = new AirAppMarketReleaseResolverService(_httpClient);
|
||||||
}
|
}
|
||||||
|
|
||||||
public async Task<AirAppMarketInstallResult> InstallAsync(
|
public async Task<AirAppMarketInstallResult> InstallAsync(
|
||||||
@@ -40,7 +42,9 @@ internal sealed class AirAppMarketInstallService : IDisposable
|
|||||||
|
|
||||||
try
|
try
|
||||||
{
|
{
|
||||||
if (AirAppMarketDefaults.TryResolveWorkspaceFile(plugin.DownloadUrl, out var localPackagePath))
|
var resolvedDownloadUrl = await _releaseResolverService.ResolveDownloadUrlAsync(plugin, cancellationToken);
|
||||||
|
|
||||||
|
if (AirAppMarketDefaults.TryResolveWorkspaceFile(resolvedDownloadUrl, out var localPackagePath))
|
||||||
{
|
{
|
||||||
await using var sourceStream = File.OpenRead(localPackagePath);
|
await using var sourceStream = File.OpenRead(localPackagePath);
|
||||||
await using var destinationStream = File.Create(downloadPath);
|
await using var destinationStream = File.Create(downloadPath);
|
||||||
@@ -49,7 +53,7 @@ internal sealed class AirAppMarketInstallService : IDisposable
|
|||||||
else
|
else
|
||||||
{
|
{
|
||||||
using var response = await _httpClient.GetAsync(
|
using var response = await _httpClient.GetAsync(
|
||||||
plugin.DownloadUrl,
|
resolvedDownloadUrl,
|
||||||
HttpCompletionOption.ResponseHeadersRead,
|
HttpCompletionOption.ResponseHeadersRead,
|
||||||
cancellationToken);
|
cancellationToken);
|
||||||
response.EnsureSuccessStatusCode();
|
response.EnsureSuccessStatusCode();
|
||||||
|
|||||||
@@ -13,11 +13,25 @@ internal static class AirAppMarketDefaults
|
|||||||
public const string DefaultIndexUrl =
|
public const string DefaultIndexUrl =
|
||||||
"https://raw.githubusercontent.com/wwiinnddyy/LanAirApp/main/airappmarket/index.json";
|
"https://raw.githubusercontent.com/wwiinnddyy/LanAirApp/main/airappmarket/index.json";
|
||||||
|
|
||||||
private const string RawGitHubLanAirAppPathPrefix = "/wwiinnddyy/LanAirApp/main/";
|
public static string BuildGitHubReleaseDownloadUrl(
|
||||||
|
string owner,
|
||||||
|
string repositoryName,
|
||||||
|
string releaseTag,
|
||||||
|
string assetName)
|
||||||
|
{
|
||||||
|
ArgumentException.ThrowIfNullOrWhiteSpace(owner);
|
||||||
|
ArgumentException.ThrowIfNullOrWhiteSpace(repositoryName);
|
||||||
|
ArgumentException.ThrowIfNullOrWhiteSpace(releaseTag);
|
||||||
|
ArgumentException.ThrowIfNullOrWhiteSpace(assetName);
|
||||||
|
|
||||||
|
return string.Create(
|
||||||
|
CultureInfo.InvariantCulture,
|
||||||
|
$"https://github.com/{owner.Trim()}/{repositoryName.Trim()}/releases/download/{Uri.EscapeDataString(releaseTag.Trim())}/{Uri.EscapeDataString(assetName.Trim())}");
|
||||||
|
}
|
||||||
|
|
||||||
public static string? TryGetWorkspaceIndexPath()
|
public static string? TryGetWorkspaceIndexPath()
|
||||||
{
|
{
|
||||||
var repositoryRoot = TryGetWorkspaceLanAirAppRepositoryRoot();
|
var repositoryRoot = TryGetWorkspaceRepositoryRoot("LanAirApp");
|
||||||
if (repositoryRoot is null)
|
if (repositoryRoot is null)
|
||||||
{
|
{
|
||||||
return null;
|
return null;
|
||||||
@@ -31,17 +45,24 @@ internal static class AirAppMarketDefaults
|
|||||||
{
|
{
|
||||||
localPath = string.Empty;
|
localPath = string.Empty;
|
||||||
|
|
||||||
var repositoryRoot = TryGetWorkspaceLanAirAppRepositoryRoot();
|
string repositoryName;
|
||||||
if (repositoryRoot is null ||
|
string relativePath;
|
||||||
!Uri.TryCreate(url, UriKind.Absolute, out var uri) ||
|
|
||||||
!string.Equals(uri.Host, "raw.githubusercontent.com", StringComparison.OrdinalIgnoreCase) ||
|
if (TryParseGitHubReleaseDownloadUrl(url, out repositoryName, out var releaseAssetName))
|
||||||
!uri.AbsolutePath.StartsWith(RawGitHubLanAirAppPathPrefix, StringComparison.OrdinalIgnoreCase))
|
{
|
||||||
|
relativePath = releaseAssetName;
|
||||||
|
}
|
||||||
|
else if (!TryParseRawGitHubUrl(url, out repositoryName, out relativePath))
|
||||||
|
{
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
|
||||||
|
var repositoryRoot = TryGetWorkspaceRepositoryRoot(repositoryName);
|
||||||
|
if (repositoryRoot is null)
|
||||||
{
|
{
|
||||||
return false;
|
return false;
|
||||||
}
|
}
|
||||||
|
|
||||||
var relativePath = Uri.UnescapeDataString(uri.AbsolutePath[RawGitHubLanAirAppPathPrefix.Length..])
|
|
||||||
.Replace('/', Path.DirectorySeparatorChar);
|
|
||||||
var candidatePath = Path.GetFullPath(Path.Combine(repositoryRoot, relativePath));
|
var candidatePath = Path.GetFullPath(Path.Combine(repositoryRoot, relativePath));
|
||||||
if (!File.Exists(candidatePath))
|
if (!File.Exists(candidatePath))
|
||||||
{
|
{
|
||||||
@@ -52,13 +73,39 @@ internal static class AirAppMarketDefaults
|
|||||||
return true;
|
return true;
|
||||||
}
|
}
|
||||||
|
|
||||||
private static string? TryGetWorkspaceLanAirAppRepositoryRoot()
|
public static bool TryParseGitHubRepositoryUrl(
|
||||||
|
string? url,
|
||||||
|
out string owner,
|
||||||
|
out string repositoryName)
|
||||||
|
{
|
||||||
|
owner = string.Empty;
|
||||||
|
repositoryName = string.Empty;
|
||||||
|
|
||||||
|
if (!Uri.TryCreate(url, UriKind.Absolute, out var uri) ||
|
||||||
|
!string.Equals(uri.Host, "github.com", StringComparison.OrdinalIgnoreCase))
|
||||||
|
{
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
|
||||||
|
var segments = uri.AbsolutePath
|
||||||
|
.Split('/', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
|
||||||
|
if (segments.Length != 2)
|
||||||
|
{
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
|
||||||
|
owner = segments[0];
|
||||||
|
repositoryName = segments[1];
|
||||||
|
return !string.IsNullOrWhiteSpace(owner) && !string.IsNullOrWhiteSpace(repositoryName);
|
||||||
|
}
|
||||||
|
|
||||||
|
private static string? TryGetWorkspaceRepositoryRoot(string repositoryName)
|
||||||
{
|
{
|
||||||
var current = new DirectoryInfo(AppContext.BaseDirectory);
|
var current = new DirectoryInfo(AppContext.BaseDirectory);
|
||||||
while (current is not null)
|
while (current is not null)
|
||||||
{
|
{
|
||||||
var candidate = Path.Combine(current.FullName, "LanAirApp");
|
var candidate = Path.Combine(current.FullName, repositoryName);
|
||||||
if (File.Exists(Path.Combine(candidate, "airappmarket", "index.json")))
|
if (Directory.Exists(candidate))
|
||||||
{
|
{
|
||||||
return candidate;
|
return candidate;
|
||||||
}
|
}
|
||||||
@@ -68,6 +115,60 @@ internal static class AirAppMarketDefaults
|
|||||||
|
|
||||||
return null;
|
return null;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
private static bool TryParseRawGitHubUrl(
|
||||||
|
string url,
|
||||||
|
out string repositoryName,
|
||||||
|
out string relativePath)
|
||||||
|
{
|
||||||
|
repositoryName = string.Empty;
|
||||||
|
relativePath = string.Empty;
|
||||||
|
|
||||||
|
if (!Uri.TryCreate(url, UriKind.Absolute, out var uri) ||
|
||||||
|
!string.Equals(uri.Host, "raw.githubusercontent.com", StringComparison.OrdinalIgnoreCase))
|
||||||
|
{
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
|
||||||
|
var segments = uri.AbsolutePath
|
||||||
|
.Split('/', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
|
||||||
|
if (segments.Length < 4)
|
||||||
|
{
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
|
||||||
|
repositoryName = segments[1];
|
||||||
|
relativePath = Path.Combine(segments[3..]).Replace(Path.AltDirectorySeparatorChar, Path.DirectorySeparatorChar);
|
||||||
|
return !string.IsNullOrWhiteSpace(repositoryName) && !string.IsNullOrWhiteSpace(relativePath);
|
||||||
|
}
|
||||||
|
|
||||||
|
private static bool TryParseGitHubReleaseDownloadUrl(
|
||||||
|
string url,
|
||||||
|
out string repositoryName,
|
||||||
|
out string assetName)
|
||||||
|
{
|
||||||
|
repositoryName = string.Empty;
|
||||||
|
assetName = string.Empty;
|
||||||
|
|
||||||
|
if (!Uri.TryCreate(url, UriKind.Absolute, out var uri) ||
|
||||||
|
!string.Equals(uri.Host, "github.com", StringComparison.OrdinalIgnoreCase))
|
||||||
|
{
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
|
||||||
|
var segments = uri.AbsolutePath
|
||||||
|
.Split('/', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
|
||||||
|
if (segments.Length != 6 ||
|
||||||
|
!string.Equals(segments[2], "releases", StringComparison.OrdinalIgnoreCase) ||
|
||||||
|
!string.Equals(segments[3], "download", StringComparison.OrdinalIgnoreCase))
|
||||||
|
{
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
|
||||||
|
repositoryName = segments[1];
|
||||||
|
assetName = Uri.UnescapeDataString(segments[5]);
|
||||||
|
return !string.IsNullOrWhiteSpace(repositoryName) && !string.IsNullOrWhiteSpace(assetName);
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
internal enum AirAppMarketLoadSource
|
internal enum AirAppMarketLoadSource
|
||||||
@@ -193,6 +294,24 @@ internal sealed class AirAppMarketIndexDocument
|
|||||||
return normalized;
|
return normalized;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
internal static string NormalizeReleaseTag(string? value, string propertyName, string sourceName)
|
||||||
|
{
|
||||||
|
var normalized = RequireValue(value, propertyName, sourceName);
|
||||||
|
if (!normalized.StartsWith("v", StringComparison.OrdinalIgnoreCase))
|
||||||
|
{
|
||||||
|
throw new InvalidOperationException(
|
||||||
|
$"Market index '{sourceName}' declares invalid release tag '{normalized}' for '{propertyName}'. Expected format 'v1.2.3'.");
|
||||||
|
}
|
||||||
|
|
||||||
|
if (!TryParseVersion(normalized[1..], out _))
|
||||||
|
{
|
||||||
|
throw new InvalidOperationException(
|
||||||
|
$"Market index '{sourceName}' declares invalid release tag '{normalized}' for '{propertyName}'.");
|
||||||
|
}
|
||||||
|
|
||||||
|
return normalized;
|
||||||
|
}
|
||||||
|
|
||||||
internal static void EnsureUrl(string url, string propertyName, string sourceName)
|
internal static void EnsureUrl(string url, string propertyName, string sourceName)
|
||||||
{
|
{
|
||||||
if (!Uri.TryCreate(url, UriKind.Absolute, out var uri) ||
|
if (!Uri.TryCreate(url, UriKind.Absolute, out var uri) ||
|
||||||
@@ -203,6 +322,24 @@ internal sealed class AirAppMarketIndexDocument
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
internal static string NormalizeGitHubRepositoryUrl(
|
||||||
|
string url,
|
||||||
|
string propertyName,
|
||||||
|
string sourceName)
|
||||||
|
{
|
||||||
|
EnsureUrl(url, propertyName, sourceName);
|
||||||
|
|
||||||
|
if (!AirAppMarketDefaults.TryParseGitHubRepositoryUrl(url, out var owner, out var repositoryName))
|
||||||
|
{
|
||||||
|
throw new InvalidOperationException(
|
||||||
|
$"Market index '{sourceName}' declares invalid GitHub repository url '{url}' for '{propertyName}'.");
|
||||||
|
}
|
||||||
|
|
||||||
|
return string.Create(
|
||||||
|
CultureInfo.InvariantCulture,
|
||||||
|
$"https://github.com/{owner}/{repositoryName}");
|
||||||
|
}
|
||||||
|
|
||||||
internal static bool TryParseVersion(string? value, out Version? version)
|
internal static bool TryParseVersion(string? value, out Version? version)
|
||||||
{
|
{
|
||||||
version = null;
|
version = null;
|
||||||
@@ -260,6 +397,14 @@ internal sealed class AirAppMarketPluginEntry
|
|||||||
|
|
||||||
public string IconUrl { get; init; } = string.Empty;
|
public string IconUrl { get; init; } = string.Empty;
|
||||||
|
|
||||||
|
public string ReleaseTag { get; init; } = string.Empty;
|
||||||
|
|
||||||
|
public string ReleaseAssetName { get; init; } = string.Empty;
|
||||||
|
|
||||||
|
public string ProjectUrl { get; init; } = string.Empty;
|
||||||
|
|
||||||
|
public string ReadmeUrl { get; init; } = string.Empty;
|
||||||
|
|
||||||
public string HomepageUrl { get; init; } = string.Empty;
|
public string HomepageUrl { get; init; } = string.Empty;
|
||||||
|
|
||||||
public string RepositoryUrl { get; init; } = string.Empty;
|
public string RepositoryUrl { get; init; } = string.Empty;
|
||||||
@@ -272,6 +417,10 @@ internal sealed class AirAppMarketPluginEntry
|
|||||||
|
|
||||||
public string ReleaseNotes { get; init; } = string.Empty;
|
public string ReleaseNotes { get; init; } = string.Empty;
|
||||||
|
|
||||||
|
public bool HasReleaseDownloadMetadata =>
|
||||||
|
!string.IsNullOrWhiteSpace(ReleaseTag) &&
|
||||||
|
!string.IsNullOrWhiteSpace(ReleaseAssetName);
|
||||||
|
|
||||||
public AirAppMarketPluginEntry ValidateAndNormalize(string sourceName)
|
public AirAppMarketPluginEntry ValidateAndNormalize(string sourceName)
|
||||||
{
|
{
|
||||||
var normalizedTags = (Tags ?? [])
|
var normalizedTags = (Tags ?? [])
|
||||||
@@ -298,6 +447,14 @@ internal sealed class AirAppMarketPluginEntry
|
|||||||
var normalizedIconUrl = AirAppMarketIndexDocument.NormalizeValue(IconUrl)
|
var normalizedIconUrl = AirAppMarketIndexDocument.NormalizeValue(IconUrl)
|
||||||
?? throw new InvalidOperationException(
|
?? throw new InvalidOperationException(
|
||||||
$"Market index '{sourceName}' is missing required property '{nameof(IconUrl)}'.");
|
$"Market index '{sourceName}' is missing required property '{nameof(IconUrl)}'.");
|
||||||
|
var normalizedReleaseTag = AirAppMarketIndexDocument.NormalizeValue(ReleaseTag);
|
||||||
|
var normalizedReleaseAssetName = AirAppMarketIndexDocument.NormalizeValue(ReleaseAssetName);
|
||||||
|
var normalizedProjectUrl = AirAppMarketIndexDocument.NormalizeValue(ProjectUrl)
|
||||||
|
?? throw new InvalidOperationException(
|
||||||
|
$"Market index '{sourceName}' is missing required property '{nameof(ProjectUrl)}'.");
|
||||||
|
var normalizedReadmeUrl = AirAppMarketIndexDocument.NormalizeValue(ReadmeUrl)
|
||||||
|
?? throw new InvalidOperationException(
|
||||||
|
$"Market index '{sourceName}' is missing required property '{nameof(ReadmeUrl)}'.");
|
||||||
var normalizedHomepageUrl = AirAppMarketIndexDocument.NormalizeValue(HomepageUrl)
|
var normalizedHomepageUrl = AirAppMarketIndexDocument.NormalizeValue(HomepageUrl)
|
||||||
?? throw new InvalidOperationException(
|
?? throw new InvalidOperationException(
|
||||||
$"Market index '{sourceName}' is missing required property '{nameof(HomepageUrl)}'.");
|
$"Market index '{sourceName}' is missing required property '{nameof(HomepageUrl)}'.");
|
||||||
@@ -307,8 +464,30 @@ internal sealed class AirAppMarketPluginEntry
|
|||||||
|
|
||||||
AirAppMarketIndexDocument.EnsureUrl(normalizedDownloadUrl, nameof(DownloadUrl), sourceName);
|
AirAppMarketIndexDocument.EnsureUrl(normalizedDownloadUrl, nameof(DownloadUrl), sourceName);
|
||||||
AirAppMarketIndexDocument.EnsureUrl(normalizedIconUrl, nameof(IconUrl), sourceName);
|
AirAppMarketIndexDocument.EnsureUrl(normalizedIconUrl, nameof(IconUrl), sourceName);
|
||||||
|
normalizedProjectUrl = AirAppMarketIndexDocument.NormalizeGitHubRepositoryUrl(
|
||||||
|
normalizedProjectUrl,
|
||||||
|
nameof(ProjectUrl),
|
||||||
|
sourceName);
|
||||||
|
normalizedRepositoryUrl = AirAppMarketIndexDocument.NormalizeGitHubRepositoryUrl(
|
||||||
|
normalizedRepositoryUrl,
|
||||||
|
nameof(RepositoryUrl),
|
||||||
|
sourceName);
|
||||||
|
AirAppMarketIndexDocument.EnsureUrl(normalizedReadmeUrl, nameof(ReadmeUrl), sourceName);
|
||||||
AirAppMarketIndexDocument.EnsureUrl(normalizedHomepageUrl, nameof(HomepageUrl), sourceName);
|
AirAppMarketIndexDocument.EnsureUrl(normalizedHomepageUrl, nameof(HomepageUrl), sourceName);
|
||||||
AirAppMarketIndexDocument.EnsureUrl(normalizedRepositoryUrl, nameof(RepositoryUrl), sourceName);
|
|
||||||
|
if (string.IsNullOrWhiteSpace(normalizedReleaseTag) != string.IsNullOrWhiteSpace(normalizedReleaseAssetName))
|
||||||
|
{
|
||||||
|
throw new InvalidOperationException(
|
||||||
|
$"Market index '{sourceName}' must declare both '{nameof(ReleaseTag)}' and '{nameof(ReleaseAssetName)}' together for plugin '{Id}'.");
|
||||||
|
}
|
||||||
|
|
||||||
|
if (!string.IsNullOrWhiteSpace(normalizedReleaseTag))
|
||||||
|
{
|
||||||
|
normalizedReleaseTag = AirAppMarketIndexDocument.NormalizeReleaseTag(
|
||||||
|
normalizedReleaseTag,
|
||||||
|
nameof(ReleaseTag),
|
||||||
|
sourceName);
|
||||||
|
}
|
||||||
|
|
||||||
if (PackageSizeBytes <= 0)
|
if (PackageSizeBytes <= 0)
|
||||||
{
|
{
|
||||||
@@ -339,6 +518,10 @@ internal sealed class AirAppMarketPluginEntry
|
|||||||
Sha256 = normalizedSha,
|
Sha256 = normalizedSha,
|
||||||
PackageSizeBytes = PackageSizeBytes,
|
PackageSizeBytes = PackageSizeBytes,
|
||||||
IconUrl = normalizedIconUrl,
|
IconUrl = normalizedIconUrl,
|
||||||
|
ReleaseTag = normalizedReleaseTag ?? string.Empty,
|
||||||
|
ReleaseAssetName = normalizedReleaseAssetName ?? string.Empty,
|
||||||
|
ProjectUrl = normalizedProjectUrl,
|
||||||
|
ReadmeUrl = normalizedReadmeUrl,
|
||||||
HomepageUrl = normalizedHomepageUrl,
|
HomepageUrl = normalizedHomepageUrl,
|
||||||
RepositoryUrl = normalizedRepositoryUrl,
|
RepositoryUrl = normalizedRepositoryUrl,
|
||||||
Tags = normalizedTags,
|
Tags = normalizedTags,
|
||||||
|
|||||||
42
LanMountainDesktop/plugins/PluginMarketReadmeService.cs
Normal file
42
LanMountainDesktop/plugins/PluginMarketReadmeService.cs
Normal file
@@ -0,0 +1,42 @@
|
|||||||
|
using System;
|
||||||
|
using System.IO;
|
||||||
|
using System.Net.Http;
|
||||||
|
using System.Threading;
|
||||||
|
using System.Threading.Tasks;
|
||||||
|
|
||||||
|
namespace LanMountainDesktop.Views.SettingsPages;
|
||||||
|
|
||||||
|
internal sealed class AirAppMarketReadmeService : IDisposable
|
||||||
|
{
|
||||||
|
private readonly HttpClient _httpClient;
|
||||||
|
|
||||||
|
public AirAppMarketReadmeService()
|
||||||
|
{
|
||||||
|
_httpClient = new HttpClient
|
||||||
|
{
|
||||||
|
Timeout = TimeSpan.FromSeconds(20)
|
||||||
|
};
|
||||||
|
_httpClient.DefaultRequestHeaders.UserAgent.ParseAdd("LanMountainDesktop-PluginMarketplace/1.0");
|
||||||
|
}
|
||||||
|
|
||||||
|
public async Task<string> LoadAsync(
|
||||||
|
AirAppMarketPluginEntry plugin,
|
||||||
|
CancellationToken cancellationToken = default)
|
||||||
|
{
|
||||||
|
ArgumentNullException.ThrowIfNull(plugin);
|
||||||
|
|
||||||
|
if (AirAppMarketDefaults.TryResolveWorkspaceFile(plugin.ReadmeUrl, out var localReadmePath))
|
||||||
|
{
|
||||||
|
return await File.ReadAllTextAsync(localReadmePath, cancellationToken);
|
||||||
|
}
|
||||||
|
|
||||||
|
using var response = await _httpClient.GetAsync(plugin.ReadmeUrl, cancellationToken);
|
||||||
|
response.EnsureSuccessStatusCode();
|
||||||
|
return await response.Content.ReadAsStringAsync(cancellationToken);
|
||||||
|
}
|
||||||
|
|
||||||
|
public void Dispose()
|
||||||
|
{
|
||||||
|
_httpClient.Dispose();
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,72 @@
|
|||||||
|
using System;
|
||||||
|
using System.Linq;
|
||||||
|
using System.Net.Http;
|
||||||
|
using System.Threading;
|
||||||
|
using System.Threading.Tasks;
|
||||||
|
using LanMountainDesktop.Services;
|
||||||
|
|
||||||
|
namespace LanMountainDesktop.Views.SettingsPages;
|
||||||
|
|
||||||
|
internal sealed class AirAppMarketReleaseResolverService
|
||||||
|
{
|
||||||
|
private readonly HttpClient _httpClient;
|
||||||
|
|
||||||
|
public AirAppMarketReleaseResolverService(HttpClient httpClient)
|
||||||
|
{
|
||||||
|
_httpClient = httpClient ?? throw new ArgumentNullException(nameof(httpClient));
|
||||||
|
}
|
||||||
|
|
||||||
|
public async Task<string> ResolveDownloadUrlAsync(
|
||||||
|
AirAppMarketPluginEntry plugin,
|
||||||
|
CancellationToken cancellationToken = default)
|
||||||
|
{
|
||||||
|
ArgumentNullException.ThrowIfNull(plugin);
|
||||||
|
|
||||||
|
if (!plugin.HasReleaseDownloadMetadata)
|
||||||
|
{
|
||||||
|
return plugin.DownloadUrl;
|
||||||
|
}
|
||||||
|
|
||||||
|
if (!TryGetRepositoryIdentity(plugin, out var owner, out var repositoryName))
|
||||||
|
{
|
||||||
|
return plugin.DownloadUrl;
|
||||||
|
}
|
||||||
|
|
||||||
|
var releaseDownloadUrl = AirAppMarketDefaults.BuildGitHubReleaseDownloadUrl(
|
||||||
|
owner,
|
||||||
|
repositoryName,
|
||||||
|
plugin.ReleaseTag,
|
||||||
|
plugin.ReleaseAssetName);
|
||||||
|
|
||||||
|
if (AirAppMarketDefaults.TryResolveWorkspaceFile(releaseDownloadUrl, out _))
|
||||||
|
{
|
||||||
|
return releaseDownloadUrl;
|
||||||
|
}
|
||||||
|
|
||||||
|
try
|
||||||
|
{
|
||||||
|
using var updateService = new GitHubReleaseUpdateService(owner, repositoryName, _httpClient);
|
||||||
|
var release = await updateService.GetReleaseByTagAsync(plugin.ReleaseTag, cancellationToken);
|
||||||
|
var asset = release?.Assets.FirstOrDefault(candidate =>
|
||||||
|
string.Equals(candidate.Name, plugin.ReleaseAssetName, StringComparison.OrdinalIgnoreCase));
|
||||||
|
|
||||||
|
return asset?.BrowserDownloadUrl ?? plugin.DownloadUrl;
|
||||||
|
}
|
||||||
|
catch
|
||||||
|
{
|
||||||
|
return plugin.DownloadUrl;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
private static bool TryGetRepositoryIdentity(
|
||||||
|
AirAppMarketPluginEntry plugin,
|
||||||
|
out string owner,
|
||||||
|
out string repositoryName)
|
||||||
|
{
|
||||||
|
owner = string.Empty;
|
||||||
|
repositoryName = string.Empty;
|
||||||
|
|
||||||
|
return AirAppMarketDefaults.TryParseGitHubRepositoryUrl(plugin.RepositoryUrl, out owner, out repositoryName) ||
|
||||||
|
AirAppMarketDefaults.TryParseGitHubRepositoryUrl(plugin.ProjectUrl, out owner, out repositoryName);
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -1,33 +1,57 @@
|
|||||||
# 宿主侧插件运行时
|
# 宿主侧插件运行时
|
||||||
|
|
||||||
这个目录用于归档阑山桌面宿主侧的插件相关实现。
|
## 中文
|
||||||
|
|
||||||
职责范围：
|
本目录保存阑山桌面宿主程序中的插件运行时实现。
|
||||||
- 已安装插件的发现
|
|
||||||
- `.laapp` 安装包安装与替换
|
### 主要职责
|
||||||
- 插件运行时加载
|
|
||||||
- 插件贡献的设置页与桌面组件接入
|
- 发现已安装插件
|
||||||
- 宿主侧插件设置页的安装、显示与刷新
|
- 安装和替换 `.laapp` 插件包
|
||||||
|
- 加载插件程序集
|
||||||
|
- 接入插件贡献的设置页和桌面组件
|
||||||
|
- 在宿主设置界面中展示插件与市场信息
|
||||||
|
|
||||||
|
### 市场安装优先级
|
||||||
|
|
||||||
|
1. 宿主先连接 `LanAirApp/airappmarket/index.json`。
|
||||||
|
2. 当条目同时提供 `releaseTag` 和 `releaseAssetName` 时，宿主优先按精确标签读取插件仓库的 GitHub Release 资产。
|
||||||
|
3. 如果 Release 不存在、资产缺失、GitHub API 失败，或当前是本地工作区测试但找不到远程资产，宿主会退回 `downloadUrl` 指向的仓库根目录 `.laapp`。
|
||||||
|
4. 插件介绍始终读取仓库根目录 `README.md`。
|
||||||
|
5. 安装完成后只做暂存，重启后生效，不在运行时热重载市场安装插件。
|
||||||
|
|
||||||
|
### 核心文件
|
||||||
|
|
||||||
当前宿主侧核心文件：
|
|
||||||
- `PluginLoader.cs`
|
- `PluginLoader.cs`
|
||||||
- `PluginLoadContext.cs`
|
- `PluginLoadContext.cs`
|
||||||
- `PluginLoaderOptions.cs`
|
|
||||||
- `PluginLoadResult.cs`
|
|
||||||
- `LoadedPlugin.cs`
|
|
||||||
- `PluginRuntimeService.cs`
|
- `PluginRuntimeService.cs`
|
||||||
- `PluginContributions.cs`
|
|
||||||
- `PluginCatalogEntry.cs`
|
- `PluginCatalogEntry.cs`
|
||||||
- `PluginSettingsPage.axaml`
|
- `PluginSettingsPage.axaml`
|
||||||
- `PluginSettingsPage.Host.cs`
|
- `PluginSettingsPage.Host.cs`
|
||||||
- `MainWindow.PluginSettingsHost.cs`
|
- `PluginMarketIndexService.cs`
|
||||||
- `SettingsWindow.PluginSettingsHost.cs`
|
- `PluginMarketInstallService.cs`
|
||||||
- `MainWindow.PluginSettingsLocalization.cs`
|
|
||||||
- `SettingsWindow.PluginSettingsLocalization.cs`
|
|
||||||
- `MainWindow.PluginSettingsControls.cs`
|
|
||||||
- `SettingsWindow.PluginSettingsControls.cs`
|
|
||||||
|
|
||||||
说明：
|
### 与 `LanAirApp` 的分工
|
||||||
- 插件开发标准、插件打包工具、示例插件与开发文档统一放在仓库根目录下的 `LanAirApp/`
|
|
||||||
- 宿主本体的插件加载、解析、安装与插件设置页接入逻辑统一放在 `LanMountainDesktop/plugins/`
|
- `LanAirApp` 负责插件开发文档、示例、市场索引和校验工具。
|
||||||
- `LanMountainDesktop.PluginSdk` 只保留插件作者需要引用的契约、清单模型和扩展注册接口
|
- 宿主目录负责运行时发现、安装、加载和界面接入。
|
||||||
|
|
||||||
|
## English
|
||||||
|
|
||||||
|
This directory contains the host-side plugin runtime for LanMountainDesktop.
|
||||||
|
|
||||||
|
### Responsibilities
|
||||||
|
|
||||||
|
- discover installed plugins
|
||||||
|
- install and replace `.laapp` packages
|
||||||
|
- load plugin assemblies
|
||||||
|
- integrate plugin settings pages and desktop components
|
||||||
|
- expose market and plugin management in the host UI
|
||||||
|
|
||||||
|
### Market install order
|
||||||
|
|
||||||
|
1. The host reads `LanAirApp/airappmarket/index.json`.
|
||||||
|
2. If an entry declares both `releaseTag` and `releaseAssetName`, the host first resolves the exact GitHub Release asset.
|
||||||
|
3. If Release resolution fails, the host falls back to the repository root `.laapp` from `downloadUrl`.
|
||||||
|
4. Plugin details always come from the repository root `README.md`.
|
||||||
|
5. Market installs are staged and take effect after restart.
|
||||||
|
|||||||
77
README.md
77
README.md
@@ -1,47 +1,48 @@
|
|||||||
# LanMountainDesktop
|
# 阑山桌面（LanMountainDesktop）
|
||||||
|
|
||||||
> 你的桌面，不止一面。
|
## 中文
|
||||||
|
|
||||||
`LanMountainDesktop` 是一个基于 Avalonia 的桌面壳层项目，目标不是“做一个启动器”，而是把桌面变成可编排的信息与交互空间。
|
阑山桌面是一个基于 Avalonia 的桌面壳层项目。它不是单纯的启动器，而是一个可编排、可扩展、可长期演进的桌面信息空间。
|
||||||
|
|
||||||
> ⚠️ **注意**：该项目使用 Vibe Coding，介意勿用。
|
### 核心目标
|
||||||
## 项目定位
|
|
||||||
- 以网格化布局组织桌面组件，支持多页桌面与组件自由摆放。
|
|
||||||
- 提供顶部状态栏 + 底部任务栏的桌面框架，强调信息密度与可读性平衡。
|
|
||||||
- 通过主题色、日夜模式、玻璃视觉与动画系统，形成统一的视觉语言。
|
|
||||||
- 通过组件注册机制与 JSON 扩展入口，让桌面能力可持续扩展。
|
|
||||||
|
|
||||||
## 核心能力
|
- 通过网格化布局管理桌面组件。
|
||||||
- 桌面组件系统：天气、时钟、计时器、课程表、日历、白板、音乐控制、学习环境等组件可组合使用。
|
- 提供状态栏、任务栏和多页桌面的统一外壳。
|
||||||
- 壁纸系统：支持图片与视频壁纸，并可在设置中实时预览。
|
- 通过主题、玻璃效果和动效塑造统一体验。
|
||||||
- 主题系统：支持日夜模式、主题色与调色联动（Monet 风格色板）。
|
- 通过组件系统和插件系统持续扩展能力。
|
||||||
- 个性化设置：网格密度、状态栏间距、任务栏布局、语言与时区等可持久化配置。
|
|
||||||
- 本地化：内置 `zh-CN` 与 `en-US` 资源。
|
|
||||||
|
|
||||||
## 工程结构
|
### 当前工程结构
|
||||||
- `LanMountainDesktop/`：桌面端主程序（Avalonia）。
|
|
||||||
- `LanMountainDesktop.RecommendationBackend/`：推荐内容后端服务（ASP.NET Core Minimal API）。
|
|
||||||
- `docs/`：视觉与圆角等规范文档。
|
|
||||||
- `LanMountainDesktop/ComponentSystem/`：组件定义、注册、放置规则与扩展入口。
|
|
||||||
|
|
||||||
## 技术栈
|
- `LanMountainDesktop/`：桌面主程序。
|
||||||
- .NET 10（`net10.0`）
|
- `LanMountainDesktop.RecommendationBackend/`：推荐内容后端。
|
||||||
- Avalonia 11
|
- `LanMountainDesktop/ComponentSystem/`：组件定义与注册系统。
|
||||||
- FluentAvalonia + FluentIcons.Avalonia
|
- `LanMountainDesktop/plugins/`：宿主侧插件加载、安装和设置集成。
|
||||||
- LibVLCSharp（用于视频相关能力）
|
- `docs/`：视觉与设计规范。
|
||||||
- WebView.Avalonia（嵌入式网页组件能力）
|
- `LanAirApp/`：插件开发资料镜像，权威版本以独立 `LanAirApp` 仓库为准。
|
||||||
|
|
||||||
## 扩展机制（摘要）
|
### 生态关系
|
||||||
- 组件系统通过 `ComponentRegistry` 合并内置组件与扩展组件。
|
|
||||||
- 运行时会扫描 `Extensions/Components/*.json`（相对应用输出目录）加载第三方组件清单。
|
|
||||||
- 扩展契约与字段说明见组件系统文档：`LanMountainDesktop/ComponentSystem/README.md`。
|
|
||||||
|
|
||||||
## 当前状态
|
- 宿主程序只连接 `LanAirApp` 仓库中的官方市场索引。
|
||||||
- 项目包含桌面端与推荐后端两个子项目，并在同一 solution 中维护。
|
- 官方市场索引返回插件列表以及各插件项目根目录链接。
|
||||||
- 通用应用配置默认写入本地：`%LOCALAPPDATA%\LanMountainDesktop\settings.json`。
|
- 插件项目根目录提供 `.laapp` 安装包和 `README.md`。
|
||||||
- 启动台与桌面布局已拆分到独立文件：`%LOCALAPPDATA%\LanMountainDesktop\launcher-settings.json`、`%LOCALAPPDATA%\LanMountainDesktop\desktop-layout-settings.json`。
|
|
||||||
- 组件配置统一写入：`%LOCALAPPDATA%\LanMountainDesktop\component-settings.json`；同类组件按实例 `componentId::placementId` 隔离存储，同时预留插件专属配置区。
|
|
||||||
- 当前体验以 Windows 为主要目标平台。
|
|
||||||
|
|
||||||
## 运行说明
|
### 当前状态
|
||||||
运行与环境准备已拆分到独立文档：[`run.md`](./run.md)
|
|
||||||
|
- Windows 是当前主要目标平台。
|
||||||
|
- 已提供组件系统、插件系统、主题系统和设置系统。
|
||||||
|
- 中文为主语言，英文为附加扩展语言。
|
||||||
|
|
||||||
|
### 运行说明
|
||||||
|
|
||||||
|
运行方法见 [run.md](./run.md)。
|
||||||
|
|
||||||
|
## English
|
||||||
|
|
||||||
|
LanMountainDesktop is an Avalonia-based desktop shell. It is designed as a composable and extensible desktop environment rather than a simple launcher.
|
||||||
|
|
||||||
|
### Main goals
|
||||||
|
|
||||||
|
- manage desktop widgets with a grid-based layout
|
||||||
|
- provide a unified shell with status bar, taskbar, and multi-page desktop support
|
||||||
|
- build a consistent experience through themes, glass effects, and motion
|
||||||
|
- extend capabilities through the component and plugin systems
|
||||||
|
|||||||
@@ -1,23 +1,17 @@
|
|||||||
# AirAppMarket
|
# AirApp Market 目录说明
|
||||||
|
|
||||||
`airappmarket/` 是阑山桌面的官方插件市场源目录。
|
## 中文
|
||||||
|
|
||||||
当前阶段职责：
|
这个目录是阑山桌面仓库里遗留的市场原型目录，只用于历史参考，不再作为官方权威市场源。
|
||||||
- 提供官方插件市场索引 `index.json`
|
|
||||||
- 提供索引 schema
|
|
||||||
- 提供静态图标资产
|
|
||||||
- 提供本地与 CI 使用的索引校验工具
|
|
||||||
|
|
||||||
Bootstrap 方式：
|
### 当前结论
|
||||||
1. 用户先通过阑山桌面内置的 `设置 -> 插件 -> 打开 .laapp 插件包` 手动安装 `LanMountainDesktop.PluginMarketplace`。
|
|
||||||
2. 市场插件启动后，会从这里的官方索引拉取插件列表。
|
|
||||||
3. 后续插件安装与更新都通过市场插件完成。
|
|
||||||
|
|
||||||
官方索引地址：
|
- 官方市场源以独立 `LanAirApp` 仓库中的 `airappmarket/index.json` 为准
|
||||||
|
- 阑山桌面程序应连接 `LanAirApp` 仓库，而不是以本目录为权威数据源
|
||||||
|
- 如无特殊需要，不应继续向这里添加正式市场数据
|
||||||
|
|
||||||
`https://raw.githubusercontent.com/wwiinnddyy/LanMountainDesktop/main/airappmarket/index.json`
|
## English
|
||||||
|
|
||||||
约束：
|
This directory is a legacy market prototype kept in the LanMountainDesktop repository for historical reference only.
|
||||||
- 这里只维护官方市场源，不做多源聚合。
|
|
||||||
- 第一阶段不提供独立 GitHub Pages 页面。
|
The authoritative market source now lives in the standalone `LanAirApp` repository.
|
||||||
- 索引中的下载链接默认指向本仓库已提交的 `.laapp` 发布包。
|
|
||||||
|
|||||||
@@ -1,177 +1,38 @@
|
|||||||
# 圆角设计规范 (Corner Radius Design System)
|
# 圆角设计规范
|
||||||
|
|
||||||
> 基于小米澎湃OS 3 (HyperOS) 设计语言
|
## 中文
|
||||||
|
|
||||||
## 设计理念
|
本规范用于统一阑山桌面不同层级容器和控件的圆角尺度。
|
||||||
|
|
||||||
澎湃OS 3 采用**"生命感美学"**设计语言，强调：
|
### 基础层级
|
||||||
- **全局圆角设计** - 所有界面元素均采用圆角
|
|
||||||
- **视觉舒适统一** - 柔和、现代、细腻
|
|
||||||
- **多级渲染** - 配合模糊混色与阴影
|
|
||||||
- **层级分明** - 大容器使用大圆角，小元素使用小圆角
|
|
||||||
|
|
||||||
## 圆角数值体系
|
- Level 1：12px，小元素和图标容器
|
||||||
|
- Level 2：16px，小型色块和紧凑控件
|
||||||
|
- Level 3：20px，普通按钮
|
||||||
|
- Level 4：24px，输入面板和小型容器
|
||||||
|
- Level 5：28px，普通玻璃面板
|
||||||
|
- Level 6：32px，强化容器
|
||||||
|
- Level 7：36px，大容器、窗口、任务栏
|
||||||
|
|
||||||
### 核心数值
|
### 使用建议
|
||||||
|
|
||||||
| 级别 | 圆角值 (px) | 用途 |
|
- 同层级元素保持相同圆角。
|
||||||
|------|-------------|------|
|
- 大容器的圆角大于内部子面板。
|
||||||
| **Level 0** | 0 | 特殊场景（无圆角需求） |
|
- 动态尺寸组件可按 `cellSize` 计算圆角，但仍要落在统一范围内。
|
||||||
| **Level 1** | 12 | 小元素、图标内边角、ListBoxItem |
|
|
||||||
| **Level 2** | 16 | 色块按钮、小组件 |
|
|
||||||
| **Level 3** | 20 | 普通按钮、组件预览 |
|
|
||||||
| **Level 4** | 24 | 输入框、小型面板 |
|
|
||||||
| **Level 5** | 28 | 面板/卡片 (glass-panel) |
|
|
||||||
| **Level 6** | 32 | Mica 风格面板 (mica-strong) |
|
|
||||||
| **Level 7** | 36 | 大容器 (glass-strong)、任务栏、窗口 |
|
|
||||||
|
|
||||||
### 动态圆角
|
### 动态圆角建议
|
||||||
|
|
||||||
动态圆角根据格子大小（cellSize）动态计算：
|
|
||||||
|
|
||||||
```csharp
|
```csharp
|
||||||
// 小元素
|
|
||||||
CornerRadius = Math.Clamp(cellSize * 0.35, 16, 28);
|
|
||||||
|
|
||||||
// 小组件
|
|
||||||
CornerRadius = Math.Clamp(cellSize * 0.45, 24, 44);
|
|
||||||
|
|
||||||
// 大容器（任务栏/窗口）
|
|
||||||
CornerRadius = Math.Clamp(cellSize * 0.45, 24, 44);
|
|
||||||
```
|
|
||||||
|
|
||||||
**系数参考**：
|
|
||||||
- 系数范围：`0.35 - 0.45`
|
|
||||||
- 最小值限制：`12 - 24 px`
|
|
||||||
- 最大值限制：`28 - 44 px`
|
|
||||||
|
|
||||||
## 组件圆角速查表
|
|
||||||
|
|
||||||
### 基础控件
|
|
||||||
|
|
||||||
| 控件 | 圆角值 | 代码位置 |
|
|
||||||
|------|--------|---------|
|
|
||||||
| Button | 20px | GlassModule.axaml |
|
|
||||||
| ToggleSwitch | 继承系统 | - |
|
|
||||||
| TextBox | 20px | glass-panel |
|
|
||||||
| ComboBox | 20px | glass-panel |
|
|
||||||
| NumberBox | 20px | glass-panel |
|
|
||||||
|
|
||||||
### 容器样式类
|
|
||||||
|
|
||||||
| 样式类 | 圆角值 | 说明 |
|
|
||||||
|--------|--------|------|
|
|
||||||
| `.glass-panel` | 28px | 普通玻璃面板 |
|
|
||||||
| `.glass-strong` | 36px | 加强玻璃面板（任务栏） |
|
|
||||||
| `.mica-strong` | 36px | Mica 风格面板（设置页） |
|
|
||||||
| `.glass-overlay` | 0px | 覆盖层（无圆角） |
|
|
||||||
|
|
||||||
### 特殊场景
|
|
||||||
|
|
||||||
| 场景 | 圆角值 | 说明 |
|
|
||||||
|------|--------|------|
|
|
||||||
| 窗口整体 | 36px | 组件库/设置窗口 |
|
|
||||||
| 窗口标题栏 | 36px | 仅顶部圆角 (`36,36,0,0`) |
|
|
||||||
| 颜色选择器色块 | 12px | Monet 颜色/推荐色 |
|
|
||||||
| 设置页 ListBoxItem | 12px | 导航项 |
|
|
||||||
| 预览视口 | 12-16px | 壁纸/网格预览 |
|
|
||||||
|
|
||||||
## 圆角层级视觉示例
|
|
||||||
|
|
||||||
```
|
|
||||||
┌─────────────────────────────────────────────────────────────────┐
|
|
||||||
│ │
|
|
||||||
│ Level 7: 大容器 (36px) │
|
|
||||||
│ ┌───────────────────────────────────────────────────────────┐ │
|
|
||||||
│ │ │ │
|
|
||||||
│ │ Level 6: Mica 面板 (36px) │ │
|
|
||||||
│ │ ┌─────────────────────────────────────────────────────┐ │ │
|
|
||||||
│ │ │ │ │ │
|
|
||||||
│ │ │ Level 5: 玻璃面板 (28px) │ │ │
|
|
||||||
│ │ │ ┌─────────────────────────────────────────────┐ │ │ │
|
|
||||||
│ │ │ │ │ │ │ │
|
|
||||||
│ │ │ │ Level 4: 输入面板 (24px) │ │ │ │
|
|
||||||
│ │ │ │ ┌─────────────────────────────────────┐ │ │ │ │
|
|
||||||
│ │ │ │ │ │ │ │ │ │
|
|
||||||
│ │ │ │ │ Level 3: 按钮 (20px) │ │ │ │ │
|
|
||||||
│ │ │ │ │ ┌─────────────────────────────┐ │ │ │ │ │
|
|
||||||
│ │ │ │ │ │ Level 2: 色块 (16px) │ │ │ │ │ │
|
|
||||||
│ │ │ │ │ │ ┌─────────────────────┐ │ │ │ │ │ │
|
|
||||||
│ │ │ │ │ │ │ Level 1: 小元素 │ │ │ │ │ │ │
|
|
||||||
│ │ │ │ │ │ │ (12px) │ │ │ │ │ │ │
|
|
||||||
│ │ │ │ │ │ └─────────────────────┘ │ │ │ │ │ │
|
|
||||||
│ │ │ │ │ └─────────────────────────────┘ │ │ │ │ │
|
|
||||||
│ │ │ │ └─────────────────────────────────────┘ │ │ │ │
|
|
||||||
│ │ │ └─────────────────────────────────────────────┘ │ │ │
|
|
||||||
│ │ └─────────────────────────────────────────────────────┘ │ │
|
|
||||||
│ └───────────────────────────────────────────────────────────┘ │
|
|
||||||
│ │
|
|
||||||
└─────────────────────────────────────────────────────────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
## 在 XAML 中使用
|
|
||||||
|
|
||||||
### 直接使用固定值
|
|
||||||
|
|
||||||
```xml
|
|
||||||
<Border Classes="glass-strong" CornerRadius="36">
|
|
||||||
<!-- 内容 -->
|
|
||||||
</Border>
|
|
||||||
|
|
||||||
<Button CornerRadius="20">点击</Button>
|
|
||||||
```
|
|
||||||
|
|
||||||
### 使用样式类
|
|
||||||
|
|
||||||
```xml
|
|
||||||
<!-- 使用预定义的 glass-panel 样式 -->
|
|
||||||
<Border Classes="glass-panel">
|
|
||||||
<TextBlock Text="面板内容" />
|
|
||||||
</Border>
|
|
||||||
|
|
||||||
<!-- 组合多个样式类 -->
|
|
||||||
<Border Classes="glass-strong mica-strong">
|
|
||||||
<!-- 内容 -->
|
|
||||||
</Border>
|
|
||||||
```
|
|
||||||
|
|
||||||
### 动态圆角（Code-Behind）
|
|
||||||
|
|
||||||
```csharp
|
|
||||||
// 根据格子大小动态计算圆角
|
|
||||||
var cellSize = 100; // 假设格子大小
|
|
||||||
var cornerRadius = Math.Clamp(cellSize * 0.45, 24, 44);
|
var cornerRadius = Math.Clamp(cellSize * 0.45, 24, 44);
|
||||||
|
|
||||||
BottomTaskbarContainer.CornerRadius = new CornerRadius(cornerRadius);
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## 新增控件时的圆角规范
|
## English
|
||||||
|
|
||||||
1. **确定元素层级** - 根据容器大小选择合适的级别
|
This specification keeps corner radius usage consistent across containers and controls.
|
||||||
2. **遵循视觉一致性** - 同层级的元素使用相同圆角
|
|
||||||
3. **考虑内容安全区** - 圆角不应遮挡重要内容
|
|
||||||
4. **响应式适配** - 大屏幕使用较大圆角，小屏幕使用较小圆角
|
|
||||||
|
|
||||||
### 快速参考
|
### Reference levels
|
||||||
|
|
||||||
```
|
- 12px for small elements
|
||||||
新控件圆角选择流程：
|
- 20px for common buttons
|
||||||
|
- 28px for normal glass panels
|
||||||
1. 是窗口/大容器？ → Level 7 (36px)
|
- 36px for large containers and windows
|
||||||
2. 是面板/卡片？ → Level 5-6 (28-36px)
|
|
||||||
3. 是按钮/输入框？ → Level 3-4 (20-24px)
|
|
||||||
4. 是小组件/色块？ → Level 2 (16px)
|
|
||||||
5. 是图标/小元素？ → Level 1 (12px)
|
|
||||||
```
|
|
||||||
|
|
||||||
## 附录：修改历史
|
|
||||||
|
|
||||||
| 日期 | 修改人 | 说明 |
|
|
||||||
|------|--------|------|
|
|
||||||
| 2026-03-02 | AI Assistant | 初始规范，基于澎湃OS 3 设计语言 |
|
|
||||||
|
|
||||||
## 参考资料
|
|
||||||
|
|
||||||
- 澎湃OS 生命感美学设计
|
|
||||||
- Xiaomi HyperOS Design Guidelines
|
|
||||||
- 小米小部件审核规范 (dev.mi.com)
|
|
||||||
|
|||||||
@@ -1,126 +1,42 @@
|
|||||||
# LanMountainDesktop 视觉规范（主题色 + 毛玻璃）
|
# 视觉规范
|
||||||
|
|
||||||
## 1. 主题色应用规范
|
## 中文
|
||||||
|
|
||||||
### 1.1 颜色角色定义
|
本规范用于统一阑山桌面的主题色、玻璃效果和基础视觉语义。
|
||||||
|
|
||||||
- `Primary`（主色）：品牌主导色，用于主要操作、关键状态提示。
|
### 颜色角色
|
||||||
- `Secondary`（辅助色）：主色的低权重变体，用于次级强调、辅助信息。
|
|
||||||
- `Accent`（强调色）：可被用户替换的动态主题色，用于选中态、激活态、聚焦态。
|
|
||||||
- `OnAccent`：放在强调色背景上的文本/图标颜色。
|
|
||||||
- `SurfaceBase` / `SurfaceRaised` / `SurfaceOverlay`：基础背景、抬升层、遮罩层。
|
|
||||||
- `TextPrimary` / `TextSecondary` / `TextMuted` / `TextAccent`：文字语义层级。
|
|
||||||
|
|
||||||
### 1.2 UI 元素映射规则
|
- `Primary`：品牌主色
|
||||||
|
- `Secondary`：辅助色
|
||||||
|
- `Accent`：强调色与选中态主色
|
||||||
|
- `OnAccent`：强调色背景上的文字或图标
|
||||||
|
- `SurfaceBase` / `SurfaceRaised` / `SurfaceOverlay`：背景层级
|
||||||
|
- `TextPrimary` / `TextSecondary` / `TextMuted` / `TextAccent`：文本层级
|
||||||
|
|
||||||
- 主按钮、主导航选中态：`Accent` + `OnAccent`
|
### 使用规则
|
||||||
- 次级按钮/输入控件：`AdaptiveButtonBackgroundBrush` + `TextPrimary`
|
|
||||||
- 页头标题：`TextPrimary`
|
|
||||||
- 说明/辅助文本：`TextSecondary` / `TextMuted`
|
|
||||||
- 设置页导航激活项：`AdaptiveNavItemSelectedBackgroundBrush` + `AdaptiveNavSelectedTextBrush`
|
|
||||||
|
|
||||||
### 1.3 统一资源键（单一真相源）
|
- 主按钮和主要导航选中态使用 `Accent + OnAccent`
|
||||||
|
- 次级操作和输入控件优先使用语义背景色，不直接写死颜色
|
||||||
|
- 页面层只使用资源键和语义类名，不写业务颜色常量
|
||||||
|
|
||||||
- 主题核心：
|
### 玻璃效果层级
|
||||||
- `AdaptivePrimaryBrush`
|
|
||||||
- `AdaptiveSecondaryBrush`
|
|
||||||
- `AdaptiveAccentBrush`
|
|
||||||
- `AdaptiveOnAccentBrush`
|
|
||||||
- 文本：
|
|
||||||
- `AdaptiveTextPrimaryBrush`
|
|
||||||
- `AdaptiveTextSecondaryBrush`
|
|
||||||
- `AdaptiveTextMutedBrush`
|
|
||||||
- `AdaptiveTextAccentBrush`
|
|
||||||
- 表面：
|
|
||||||
- `AdaptiveSurfaceBaseBrush`
|
|
||||||
- `AdaptiveSurfaceRaisedBrush`
|
|
||||||
- `AdaptiveSurfaceOverlayBrush`
|
|
||||||
|
|
||||||
## 2. 毛玻璃（Glassmorphism）统一实现方案
|
- `glass-overlay`：最外层遮罩
|
||||||
|
- `glass-strong`：主要大容器
|
||||||
|
- `glass-panel`：子区域、小面板、卡片
|
||||||
|
|
||||||
### 2.1 分层标准
|
### 可访问性
|
||||||
|
|
||||||
- `glass-overlay`：最高层遮罩（设置页背板）
|
- 正文对比度目标不低于 `4.5:1`
|
||||||
- `glass-strong`：主内容容器（设置页主体）
|
- 大号文字和重点文字不低于 `3.0:1`
|
||||||
- `glass-panel`：子功能区、组件容器（网格卡片、按钮容器）
|
- 主题服务负责对前景色做自动对比度修正
|
||||||
|
|
||||||
### 2.2 参数标准（模拟毛玻璃，跨平台稳定）
|
## English
|
||||||
|
|
||||||
- 描边：统一去除（`BorderThickness = 0`）
|
This specification defines the visual language of LanMountainDesktop, including theme roles, glass layers, and semantic color usage.
|
||||||
- 模糊半径资源（供样式/扩展复用）：
|
|
||||||
- `AdaptiveGlassPanelBlurRadius`（日 18 / 夜 22）
|
|
||||||
- `AdaptiveGlassStrongBlurRadius`（日 24 / 夜 28）
|
|
||||||
- 透明度资源：
|
|
||||||
- `AdaptiveGlassPanelOpacity`（日 0.88 / 夜 0.92）
|
|
||||||
- `AdaptiveGlassStrongOpacity`（日 0.92 / 夜 0.95）
|
|
||||||
- 背景色：由 `GlassEffectService` 基于主题色动态混合，统一下发到：
|
|
||||||
- `AdaptiveGlassPanelBackgroundBrush`
|
|
||||||
- `AdaptiveGlassStrongBackgroundBrush`
|
|
||||||
- `AdaptiveGlassOverlayBackgroundBrush`
|
|
||||||
|
|
||||||
## 3. 视觉一致性策略
|
### Key rules
|
||||||
|
|
||||||
- 全局样式入口：`Styles/GlassModule.axaml`
|
|
||||||
- 全局主题入口：`ThemeColorSystemService` + `GlassEffectService`
|
|
||||||
- 页面侧仅使用语义资源键和 `glass-*` 类，不写硬编码颜色
|
|
||||||
- `MainWindow` 只负责编排：切换模式、选择主题色、触发资源重算
|
|
||||||
|
|
||||||
## 4. 可访问性（WCAG）
|
|
||||||
|
|
||||||
### 4.1 对比度目标
|
|
||||||
|
|
||||||
- 正文文本：`>= 4.5:1`
|
|
||||||
- 大号文本 / 强调文本：`>= 3.0:1`
|
|
||||||
|
|
||||||
### 4.2 实现方式
|
|
||||||
|
|
||||||
- `Theme/ColorMath.cs` 提供：
|
|
||||||
- 相对亮度计算
|
|
||||||
- 对比度计算
|
|
||||||
- `EnsureContrast(...)` 自动修正文本前景色
|
|
||||||
- `ThemeColorSystemService` 在生成 `TextPrimary/TextSecondary/TextMuted/NavText` 时强制走对比度校正
|
|
||||||
|
|
||||||
## 5. 跨尺寸与分辨率一致性
|
|
||||||
|
|
||||||
- 启用像素对齐：`UseLayoutRounding="True"` + `SnapsToDevicePixels="True"`
|
|
||||||
- 桌面网格布局通过统一计算函数输出 `row/col/cell`，主视图与预览共用算法
|
|
||||||
- 预览区域按窗口实际宽高比缩放，保持 Win11 风格比例一致性
|
|
||||||
- 关键尺寸自适应（字体、内边距、圆角）随 `cellSize` 动态计算
|
|
||||||
|
|
||||||
## 6. 实现代码示例
|
|
||||||
|
|
||||||
### 6.1 主题系统应用（C#）
|
|
||||||
|
|
||||||
```csharp
|
|
||||||
var context = new ThemeColorContext(
|
|
||||||
selectedAccent,
|
|
||||||
isLightBackground,
|
|
||||||
isLightNavBackground,
|
|
||||||
isNightMode);
|
|
||||||
|
|
||||||
ThemeColorSystemService.ApplyThemeResources(Resources, context);
|
|
||||||
GlassEffectService.ApplyGlassResources(Resources, context);
|
|
||||||
```
|
|
||||||
|
|
||||||
### 6.2 页面层使用语义资源（AXAML）
|
|
||||||
|
|
||||||
```xml
|
|
||||||
<Border Classes="glass-overlay" />
|
|
||||||
|
|
||||||
<Border Classes="glass-strong" CornerRadius="16">
|
|
||||||
<Border Classes="glass-panel" CornerRadius="10" Padding="14">
|
|
||||||
<TextBlock Foreground="{DynamicResource AdaptiveTextPrimaryBrush}" />
|
|
||||||
<Button Background="{DynamicResource AdaptiveButtonBackgroundBrush}" />
|
|
||||||
</Border>
|
|
||||||
</Border>
|
|
||||||
```
|
|
||||||
|
|
||||||
### 6.3 无描边层级区分原则（AXAML）
|
|
||||||
|
|
||||||
```xml
|
|
||||||
<Style Selector="Border.glass-panel">
|
|
||||||
<Setter Property="BorderThickness" Value="0" />
|
|
||||||
<Setter Property="Opacity" Value="{DynamicResource AdaptiveGlassPanelOpacity}" />
|
|
||||||
</Style>
|
|
||||||
```
|
|
||||||
|
|
||||||
|
- use semantic resource keys instead of hard-coded colors
|
||||||
|
- keep glass layers visually distinct
|
||||||
|
- maintain contrast targets for readability
|
||||||
|
|||||||
796
noise.md
796
noise.md
@@ -1,771 +1,67 @@
|
|||||||
# 噪音计算与评分技术文档
|
# 噪音监测与评分说明
|
||||||
|
|
||||||
噪音监测系统不仅仅是一个简单的分贝计，它内置了一个基于心理声学与专注力理论的评分引擎。该引擎旨在客观、多维度地量化环境噪音对学习心流的干扰程度。
|
## 中文
|
||||||
|
|
||||||
本文档详细解析了该系统的计算原理、核心指标定义、评分算法及完整的技术架构。
|
本文档描述阑山桌面中噪音监测能力的基本设计目标、核心指标和实现边界。
|
||||||
|
|
||||||
## 目录
|
### 设计目标
|
||||||
|
|
||||||
1. [核心理念](#1-核心理念)
|
- 用尽量稳定的方式度量环境噪音。
|
||||||
2. [系统架构](#2-系统架构)
|
- 区分持续噪音、超阈值时长和高频打断。
|
||||||
3. [数据采集层](#3-数据采集层)
|
- 将结果反馈到实时界面、历史报表和专注场景中。
|
||||||
4. [数据聚合层](#4-数据聚合层)
|
|
||||||
5. [评分算法核心](#5-评分算法核心)
|
|
||||||
6. [数据存储层](#6-数据存储层)
|
|
||||||
7. [历史报告生成](#7-历史报告生成)
|
|
||||||
8. [流服务整合](#8-流服务整合)
|
|
||||||
9. [配置参数体系](#9-配置参数体系)
|
|
||||||
10. [类型定义](#10-类型定义)
|
|
||||||
|
|
||||||
---
|
### 核心指标
|
||||||
|
|
||||||
## 1. 核心理念
|
- `p50Dbfs`：持续噪音水平，反映环境底噪。
|
||||||
|
- `overRatioDbfs`：超阈值时间占比，反映噪音覆盖时长。
|
||||||
|
- `segmentCount`：独立噪音事件数，反映被打断频率。
|
||||||
|
|
||||||
### 1.1 设计原则
|
### 评分思路
|
||||||
|
|
||||||
系统认为，并非所有"响声"都是一样的。对于专注力而言：
|
评分从 100 分开始，依据三类惩罚项扣分：
|
||||||
|
|
||||||
- **持续的嗡嗡声**（如嘈杂的人群）比**偶尔的掉笔声**更具破坏性
|
- 持续噪音惩罚
|
||||||
- **频繁的打断**（如每分钟都有人说话）比**单次的大声喧哗**更让人烦躁
|
- 超阈值时长惩罚
|
||||||
- **评分与校准分离**：评分使用原始 DBFS 数据，校准仅影响显示分贝
|
- 打断频率惩罚
|
||||||
|
|
||||||
因此，评分系统采用了 **多维度加权扣分制**，满分 100 分，根据环境表现进行扣分。
|
常见固定参数：
|
||||||
|
|
||||||
### 1.2 评分与校准分离
|
- 帧间隔：50ms
|
||||||
|
- 切片时长：30s
|
||||||
|
- 评分阈值：`-50 dBFS`
|
||||||
|
- 事件合并窗口：500ms
|
||||||
|
- 每分钟最大容忍事件数：6
|
||||||
|
|
||||||
项目通过"原始数据（用于评分）"与"显示数据（用于展示）"的**严格分层**，杜绝了校准值导致的评分偏差：
|
### 数据流
|
||||||
|
|
||||||
1. **评分只依赖原始 DBFS（设备输出的相对电平）**
|
1. 麦克风采集音频。
|
||||||
- 评分的三项核心指标（`p50Dbfs`、`overRatioDbfs`、`segmentCount`）都来自原始 `dbfs` 统计
|
2. 计算 RMS 与 dBFS。
|
||||||
- "超阈时长占比"判定条件固定为：`dbfs > scoreThresholdDbfs`（阈值默认 `-50 dBFS`），与校准无关
|
3. 聚合为时间切片。
|
||||||
- 这意味着即使用户把"显示分贝基准"调高/调低，评分侧的 `dbfs` 不会变化，因此得分与超阈时长也不会被"调参刷分"
|
4. 为每个切片计算统计值和评分。
|
||||||
|
5. 写入本地历史数据。
|
||||||
|
6. 在 UI 中展示实时状态与历史报告。
|
||||||
|
|
||||||
2. **校准仅影响 Display dB（UI 展示口径），不进入评分链路**
|
### 设计边界
|
||||||
- 校准（`baselineRms` / `baselineDb`）只用于将 `rms` 映射为 `displayDb`，用于实时显示与报告中的"噪音等级分布"等图表展示
|
|
||||||
- 这些展示口径变化不会反向影响评分输入，也不会改变切片摘要中的 `raw.*` 字段
|
|
||||||
|
|
||||||
3. **统计报告中"超阈时长"取自 raw.overRatioDbfs**
|
- 评分使用原始统计口径，不应被显示层校准参数反向影响。
|
||||||
- 报告里展示的"超阈时长"是对每个切片 `raw.overRatioDbfs` 按有效采样时长加权汇总得到，仍然完全基于 DBFS
|
- 历史数据只存统计值，不存原始音频。
|
||||||
- 相比之下，"噪音等级分布"使用的是 `display.avgDb`（校准后的显示分贝），因此它会随校准变化——这是为了更贴近用户直觉的 dB 区间划分
|
- 该系统用于环境质量评估，不作为专业声学测量工具。
|
||||||
|
|
||||||
---
|
## English
|
||||||
|
|
||||||
## 2. 系统架构
|
This document summarizes the noise monitoring and scoring model used by LanMountainDesktop.
|
||||||
|
|
||||||
### 2.1 整体架构图
|
### Main metrics
|
||||||
|
|
||||||
```
|
- `p50Dbfs`: sustained noise level
|
||||||
┌─────────────────────────────────────────────────────────────────┐
|
- `overRatioDbfs`: ratio of time above threshold
|
||||||
│ 用户界面层 │
|
- `segmentCount`: number of distinct interruption events
|
||||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
||||||
│ │ 实时监控组件 │ │ 噪音报告弹窗 │ │ 噪音历史列表 │ │
|
|
||||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
||||||
└─────────────────────────────────────────────────────────────────┘
|
|
||||||
↑
|
|
||||||
│ 订阅/发布
|
|
||||||
↓
|
|
||||||
┌─────────────────────────────────────────────────────────────────┐
|
|
||||||
│ 流服务层 │
|
|
||||||
│ ┌──────────────────────────────────────────────────────────┐ │
|
|
||||||
│ │ 噪音流服务 - 订阅管理、生命周期控制、设置热更新 │ │
|
|
||||||
│ └──────────────────────────────────────────────────────────┘ │
|
|
||||||
└─────────────────────────────────────────────────────────────────┘
|
|
||||||
↑
|
|
||||||
│ 帧数据流
|
|
||||||
↓
|
|
||||||
┌─────────────────────────────────────────────────────────────────┐
|
|
||||||
│ 数据聚合层 │
|
|
||||||
│ ┌──────────────────┐ ┌────────────────────────────────────┐ │
|
|
||||||
│ │ 噪音帧处理器 │ │ 噪音切片聚合器 │ │
|
|
||||||
│ │ - RMS/dBFS 计算 │ │ - 切片聚合、统计指标、评分计算 │ │
|
|
||||||
│ │ - 50ms/帧 │ │ - 30秒/切片 │ │
|
|
||||||
│ └──────────────────┘ └────────────────────────────────────┘ │
|
|
||||||
│ ┌──────────────────────────────────────────────────────────┐ │
|
|
||||||
│ │ 实时环形缓冲区 - 保留固定时长的实时数据 │ │
|
|
||||||
│ └──────────────────────────────────────────────────────────┘ │
|
|
||||||
└─────────────────────────────────────────────────────────────────┘
|
|
||||||
↑
|
|
||||||
│ 音频流
|
|
||||||
↓
|
|
||||||
┌─────────────────────────────────────────────────────────────────┐
|
|
||||||
│ 数据采集层 │
|
|
||||||
│ ┌──────────────────────────────────────────────────────────┐ │
|
|
||||||
│ │ 麦克风采集 - Web Audio API、滤波器、AnalyserNode │ │
|
|
||||||
│ └──────────────────────────────────────────────────────────┘ │
|
|
||||||
└─────────────────────────────────────────────────────────────────┘
|
|
||||||
↑
|
|
||||||
│ 物理音频
|
|
||||||
↓
|
|
||||||
┌─────────────────────────────────────────────────────────────────┐
|
|
||||||
│ 数据存储层 │
|
|
||||||
│ ┌──────────────────────────────────────────────────────────┐ │
|
|
||||||
│ │ 切片存储 - localStorage、时间清理、容量限制 │ │
|
|
||||||
│ └──────────────────────────────────────────────────────────┘ │
|
|
||||||
└─────────────────────────────────────────────────────────────────┘
|
|
||||||
↑
|
|
||||||
│ 历史数据
|
|
||||||
↓
|
|
||||||
┌─────────────────────────────────────────────────────────────────┐
|
|
||||||
│ 历史报告层 │
|
|
||||||
│ ┌──────────────────────────────────────────────────────────┐ │
|
|
||||||
│ │ 历史构建 - 课表关联、加权平均评分、覆盖率计算 │ │
|
|
||||||
│ └──────────────────────────────────────────────────────────┘ │
|
|
||||||
└─────────────────────────────────────────────────────────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2.2 模块说明
|
### Pipeline
|
||||||
|
|
||||||
| 模块 | 功能 |
|
|
||||||
|------|------|
|
|
||||||
| 类型定义 | 核心类型定义 |
|
|
||||||
| 常量定义 | 分析参数常量、报告参数常量 |
|
|
||||||
| 麦克风采集 | 音频采集 |
|
|
||||||
| 帧处理器 | 帧处理 |
|
|
||||||
| 切片聚合器 | 切片聚合 |
|
|
||||||
| 环形缓冲区 | 实时数据 |
|
|
||||||
| 流服务 | 流管理 |
|
|
||||||
| 评分引擎 | 评分算法 |
|
|
||||||
| 切片服务 | 存储服务 |
|
|
||||||
| 历史构建 | 历史报告 |
|
|
||||||
| 设置管理 | 设置管理 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. 数据采集层
|
|
||||||
|
|
||||||
### 3.1 麦克风采集
|
|
||||||
|
|
||||||
#### 3.1.1 Web Audio API 使用
|
|
||||||
|
|
||||||
系统使用 Web Audio API 获取麦克风输入，构建完整的音频处理链路：
|
|
||||||
|
|
||||||
```
|
|
||||||
麦克风 → MediaStream → MediaStreamAudioSourceNode
|
|
||||||
→ 高通滤波器 (80Hz) → 低通滤波器 (8000Hz)
|
|
||||||
→ AnalyserNode (FFT Size 2048)
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 3.1.2 音频滤波器配置
|
|
||||||
|
|
||||||
| 滤波器类型 | 截止频率 | 作用 |
|
|
||||||
|-----------|---------|------|
|
|
||||||
| 高通滤波器 | 80 Hz | 过滤低频噪音（如空调嗡嗡声） |
|
|
||||||
| 低通滤波器 | 8000 Hz | 过滤高频噪音（如电子设备啸叫） |
|
|
||||||
|
|
||||||
#### 3.1.3 AnalyserNode 配置
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
analyser.fftSize = 2048; // FFT 窗口大小
|
|
||||||
analyser.smoothingTimeConstant = 0; // 无平滑，实时响应
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 3.1.4 权限处理与错误处理
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
// 麦克风权限请求配置
|
|
||||||
{
|
|
||||||
audio: {
|
|
||||||
echoCancellation: false, // 禁用回声消除
|
|
||||||
noiseSuppression: false, // 禁用降噪
|
|
||||||
autoGainControl: false, // 禁用自动增益
|
|
||||||
},
|
|
||||||
video: false
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**浏览器兼容性说明：**
|
|
||||||
- 部分浏览器/设备可能忽略上述约束设置
|
|
||||||
- 建议在 UI 中提示用户实际生效的约束
|
|
||||||
- 需要测试矩阵验证：Chrome/Firefox/Safari/Edge/iOS Safari/Android WebView
|
|
||||||
|
|
||||||
**错误处理：**
|
|
||||||
- `NotAllowedError` / `SecurityError` → 权限拒绝
|
|
||||||
- `AudioContext not supported` → 浏览器不支持
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 3.2 帧处理器
|
|
||||||
|
|
||||||
#### 3.2.1 采样频率
|
|
||||||
|
|
||||||
- **帧间隔**：50ms（约 20 fps）
|
|
||||||
- **数据来源**：AnalyserNode.getFloatTimeDomainData()
|
|
||||||
|
|
||||||
#### 3.2.2 RMS（均方根）计算
|
|
||||||
|
|
||||||
RMS 是衡量音频信号强度的标准方法：
|
|
||||||
|
|
||||||
**公式：**
|
|
||||||
$$ \text{RMS} = \sqrt{\frac{1}{N} \sum_{i=1}^{N} x_i^2} $$
|
|
||||||
|
|
||||||
#### 3.2.3 dBFS（分贝满刻度）转换
|
|
||||||
|
|
||||||
dBFS 是数字音频的标准分贝单位，范围 -100 到 0 dB：
|
|
||||||
|
|
||||||
**公式：**
|
|
||||||
$$ \text{dBFS} = 20 \times \log_{10}(\text{RMS}) $$
|
|
||||||
|
|
||||||
**范围限制：**
|
|
||||||
- 最小值：-100 dBFS（静音）
|
|
||||||
- 最大值：0 dBFS（满刻度）
|
|
||||||
|
|
||||||
#### 3.2.4 峰值检测
|
|
||||||
|
|
||||||
峰值用于检测突发噪音，在 RMS 计算过程中同时记录峰值。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. 数据聚合层
|
|
||||||
|
|
||||||
### 4.1 切片聚合器
|
|
||||||
|
|
||||||
#### 4.1.1 切片时长
|
|
||||||
|
|
||||||
- **默认切片时长**：30 秒
|
|
||||||
- **可配置范围**：≥ 1 秒
|
|
||||||
|
|
||||||
#### 4.1.2 统计指标计算
|
|
||||||
|
|
||||||
切片聚合器为每个切片计算以下统计指标：
|
|
||||||
|
|
||||||
| 指标 | 说明 | 计算方法 |
|
|
||||||
|------|------|---------|
|
|
||||||
| avgDbfs | 平均分贝 | 能量平均（线性域 RMS 平均后转回 dBFS） |
|
|
||||||
| maxDbfs | 最大分贝 | 所有帧 dBFS 的最大值 |
|
|
||||||
| p50Dbfs | 中位数分贝 | 线性域分位数（RMS 域计算后转回 dBFS） |
|
|
||||||
| p95Dbfs | 95分位数分贝 | 线性域分位数（RMS 域计算后转回 dBFS） |
|
|
||||||
| overRatioDbfs | 超阈值比例 | 超阈值时长 / 采样时长 |
|
|
||||||
| segmentCount | 事件段数量 | 独立噪音事件次数 |
|
|
||||||
| sampledDurationMs | 采样时长 | 有效采样时间（排除缺口） |
|
|
||||||
| gapCount | 缺口数量 | 数据缺口次数 |
|
|
||||||
| maxGapMs | 最大缺口时长 | 最长数据缺口时长 |
|
|
||||||
|
|
||||||
#### 4.1.3 能量平均计算（avgDbfs）
|
|
||||||
|
|
||||||
**公式：**
|
|
||||||
$$ \text{avgDbfs} = 20 \times \log_{10}\left(\sqrt{\frac{1}{N} \sum_{i=1}^{N} 10^{\text{dBFS}_i / 10}}\right) $$
|
|
||||||
|
|
||||||
**物理意义：** 在线性域（RMS）上做平均，符合能量守恒定律
|
|
||||||
|
|
||||||
#### 4.1.4 线性域分位数计算
|
|
||||||
|
|
||||||
**公式：**
|
|
||||||
$$ \text{quantileDbfs} = 20 \times \log_{10}(Q_{\text{RMS}}(p)) $$
|
|
||||||
|
|
||||||
其中 $Q_{\text{RMS}}(p)$ 是 RMS 域的分位数，使用线性插值计算：
|
|
||||||
$$ Q_{\text{RMS}}(p) = x_{\lfloor i \rfloor} \times (1 - w) + x_{\lceil i \rceil} \times w $$
|
|
||||||
|
|
||||||
- $i = (n-1) \times p$
|
|
||||||
- $w = i - \lfloor i \rfloor$
|
|
||||||
|
|
||||||
**物理意义：** 在线性域（RMS）上计算分位数，符合能量统计的严谨性
|
|
||||||
|
|
||||||
#### 4.1.5 超阈值比例计算（时间加权）
|
|
||||||
|
|
||||||
**公式：**
|
|
||||||
$$ \text{overRatioDbfs} = \frac{\text{超阈值时长}}{\text{采样时长}} $$
|
|
||||||
|
|
||||||
**物理意义：** 使用实际时长而非帧数计算比例，更精确
|
|
||||||
|
|
||||||
#### 4.1.6 事件段检测与合并算法
|
|
||||||
|
|
||||||
事件段检测用于识别独立的噪音事件：
|
|
||||||
|
|
||||||
**合并规则：**
|
|
||||||
- **合并窗口**：500ms（默认）
|
|
||||||
- 如果两次超阈值事件间隔 ≤ 500ms，合并为同一事件段
|
|
||||||
- 否则计为新的独立事件段
|
|
||||||
|
|
||||||
**示例：**
|
|
||||||
```
|
|
||||||
时间轴： 0ms 200ms 400ms 600ms 800ms 1000ms
|
|
||||||
状态： [噪音] [噪音] [安静] [噪音] [噪音] [安静]
|
|
||||||
合并后： └─────── 事件段1 ───────┘ └── 事件段2 ──┘
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 4.1.7 显示分贝映射（校准机制）
|
|
||||||
|
|
||||||
显示分贝用于用户界面展示，支持校准：
|
|
||||||
|
|
||||||
**公式（有校准）：**
|
|
||||||
$$ \text{displayDb} = \text{baselineDb} + 20 \times \log_{10}\left(\frac{\text{rms}}{\text{baselineRms}}\right) $$
|
|
||||||
|
|
||||||
**公式（无校准）：**
|
|
||||||
$$ \text{displayDb} = 20 \times \log_{10}\left(\frac{\text{rms}}{10^{-3}}\right) + 60 $$
|
|
||||||
|
|
||||||
**范围限制：** 20 dB ~ 100 dB
|
|
||||||
|
|
||||||
**校准流程说明：**
|
|
||||||
1. 使用标准声源（如 60 dB 的白噪音）
|
|
||||||
2. 测量对应的 RMS 值
|
|
||||||
3. 设置为 baselineRms
|
|
||||||
4. 设置对应的显示分贝为 baselineDb
|
|
||||||
|
|
||||||
#### 4.1.8 缺口检测与采样时长统计
|
|
||||||
|
|
||||||
**缺口阈值：** `max(1000ms, frameMs × 5)` = **1000ms**（默认）
|
|
||||||
|
|
||||||
当检测到数据缺口时，会触发切片完成并记录缺口信息。
|
|
||||||
|
|
||||||
#### 4.1.9 无效帧过滤
|
|
||||||
|
|
||||||
低于 -90 dBFS 的帧被视为静音/无效信号，不参与统计。
|
|
||||||
|
|
||||||
**常量说明：**
|
|
||||||
- `INVALID_DBFS_THRESHOLD = -90`：统计意义上的"静音"阈值
|
|
||||||
- `DBFS_MIN_POSSIBLE = -100`：物理最小可表示值（用于 clamp）
|
|
||||||
- `DBFS_MAX_POSSIBLE = 0`：物理最大可表示值（用于 clamp）
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 4.2 实时环形缓冲区
|
|
||||||
|
|
||||||
#### 4.2.1 数据结构设计
|
|
||||||
|
|
||||||
环形缓冲区使用固定容量数组实现，通过起始索引和当前长度管理数据。
|
|
||||||
|
|
||||||
#### 4.2.2 时间窗口裁剪策略
|
|
||||||
|
|
||||||
**裁剪规则：** 移除时间戳早于 `当前时间 - retentionMs` 的数据点
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. 评分算法核心
|
|
||||||
|
|
||||||
### 5.1 三大核心指标
|
|
||||||
|
|
||||||
评分引擎从以下三个维度对噪音数据进行分析：
|
|
||||||
|
|
||||||
#### A. 持续噪音水平 (Sustained Level)
|
|
||||||
|
|
||||||
- **定义**：剔除突发噪音后的环境"底噪"水平
|
|
||||||
- **算法**：使用时段内所有帧的中位数电平 (`p50Dbfs`)
|
|
||||||
- **意义**：反映环境本身是否安静。如果环境中有持续的风扇声或交谈声，该指标会升高
|
|
||||||
|
|
||||||
#### B. 超阈值时长占比 (Over Threshold Ratio)
|
|
||||||
|
|
||||||
- **定义**：原始 `DBFS` 超过评分阈值（`scoreThresholdDbfs`）的时间比例
|
|
||||||
- **算法**：`超阈值时长 / 采样时长`（超标判定：`dbfs > scoreThresholdDbfs`）
|
|
||||||
- **意义**：反映环境的"纯净度"。即使是 0.1 秒的尖叫也会被精确计入，无法被平均值掩盖
|
|
||||||
|
|
||||||
> **提示**：评分阈值（`scoreThresholdDbfs`，单位 dBFS）与"界面报警/提示音"使用的显示分贝阈值（`maxLevelDb`，单位 dB）不是同一个概念；前者只用于评分，后者用于判定 noisy/quiet 与提示音触发。
|
|
||||||
|
|
||||||
#### C. 打断次数密度 (Interruption Density)
|
|
||||||
|
|
||||||
- **定义**：单位时间内（每分钟）发生的独立噪音事件次数
|
|
||||||
- **智能合并算法**：
|
|
||||||
- 系统设有 **500ms** (默认) 的合并窗口
|
|
||||||
- 如果两次响声间隔小于该窗口（如拉椅子的一连串声音），会被合并为 **1 次打断**
|
|
||||||
- 只有间隔较长的响声才会被计为新的打断
|
|
||||||
- **意义**：反映环境的干扰频率。频繁的打断（如断断续续的说话声）比连续的噪音更易打断心流
|
|
||||||
|
|
||||||
### 5.2 评分引擎
|
|
||||||
|
|
||||||
#### 5.2.1 三维度评分模型
|
|
||||||
|
|
||||||
评分系统从三个维度对噪音进行评估：
|
|
||||||
|
|
||||||
| 维度 | 权重 | 指标 | 满扣分条件 |
|
|
||||||
|------|------|------|-----------|
|
|
||||||
| **持续噪音** | 40% | p50Dbfs | 中位数超过阈值 6 dBFS |
|
|
||||||
| **超阈时长** | 30% | overRatioDbfs | 超阈时间占比 30% |
|
|
||||||
| **打断频次** | 30% | segmentCount | 6 次/分钟 |
|
|
||||||
|
|
||||||
#### 5.2.2 评分公式
|
|
||||||
|
|
||||||
**总惩罚系数：**
|
|
||||||
$$ \text{TotalPenalty} = 0.40 \times P_{\text{sustained}} + 0.30 \times P_{\text{time}} + 0.30 \times P_{\text{segment}} $$
|
|
||||||
|
|
||||||
**最终得分：**
|
|
||||||
$$ \text{Score} = 100 \times (1 - \text{TotalPenalty}) $$
|
|
||||||
|
|
||||||
#### 5.2.3 惩罚系数计算
|
|
||||||
|
|
||||||
##### A. 持续噪音惩罚
|
|
||||||
|
|
||||||
**公式：**
|
|
||||||
$$ P_{\text{sustained}} = \text{clamp}_{[0,1]}\left(\frac{\text{p50Dbfs} - \text{threshold}}{6}\right) $$
|
|
||||||
|
|
||||||
**满扣分条件：** `p50Dbfs - threshold ≥ 6 dBFS`
|
|
||||||
|
|
||||||
##### B. 超阈时长惩罚
|
|
||||||
|
|
||||||
**公式：**
|
|
||||||
$$ P_{\text{time}} = \text{clamp}_{[0,1]}\left(\frac{\text{overRatioDbfs}}{0.3}\right) $$
|
|
||||||
|
|
||||||
**满扣分条件：** `overRatioDbfs ≥ 30%`
|
|
||||||
|
|
||||||
##### C. 打断频次惩罚
|
|
||||||
|
|
||||||
**公式：**
|
|
||||||
$$ P_{\text{segment}} = \text{clamp}_{[0,1]}\left(\frac{\text{segmentCount} / \text{minutes}}{\text{maxSegmentsPerMin}}\right) $$
|
|
||||||
|
|
||||||
**满扣分条件：** `segmentsPerMin ≥ 6 次/分钟`
|
|
||||||
|
|
||||||
#### 5.2.4 权重解读
|
|
||||||
|
|
||||||
- **持续噪音 (40%)**：持续底噪仍会明显拉低分数
|
|
||||||
- **超阈时长 (30%)**：只要大部分时间安静，偶尔的噪音仍可被容忍
|
|
||||||
- **打断频次 (30%)**：强调"被频繁打断"对心流的破坏，提升对碎片化干扰的惩罚力度
|
|
||||||
|
|
||||||
#### 5.2.5 边界条件处理
|
|
||||||
|
|
||||||
- DBFS 范围限制：-100 到 0 dB
|
|
||||||
- 惩罚系数范围限制：0 到 1
|
|
||||||
- 评分范围限制：0 到 100 分
|
|
||||||
|
|
||||||
#### 5.2.6 有效时长处理
|
|
||||||
|
|
||||||
优先使用采样有效时长，不存在时回退到物理时长。
|
|
||||||
|
|
||||||
#### 5.2.7 评分示例
|
|
||||||
|
|
||||||
**场景 1：安静环境**
|
|
||||||
- p50Dbfs = -60 dBFS, threshold = -50 dBFS
|
|
||||||
- overRatioDbfs = 0.05 (5%)
|
|
||||||
- segmentCount = 1, duration = 30s
|
|
||||||
|
|
||||||
```
|
|
||||||
sustainedPenalty = clamp01((-60 - (-50)) / 6) = clamp01(-10/6) = 0
|
|
||||||
timePenalty = clamp01(0.05 / 0.3) = 0.167
|
|
||||||
segmentPenalty = clamp01((1/0.5) / 6) = clamp01(2/6) = 0.333
|
|
||||||
|
|
||||||
TotalPenalty = 0.4×0 + 0.3×0.167 + 0.3×0.333 = 0.15
|
|
||||||
Score = 100 × (1 - 0.15) = 85 分
|
|
||||||
```
|
|
||||||
|
|
||||||
**场景 2：嘈杂环境**
|
|
||||||
- p50Dbfs = -45 dBFS, threshold = -50 dBFS
|
|
||||||
- overRatioDbfs = 0.40 (40%)
|
|
||||||
- segmentCount = 8, duration = 30s
|
|
||||||
|
|
||||||
```
|
|
||||||
sustainedPenalty = clamp01((-45 - (-50)) / 6) = clamp01(5/6) = 0.833
|
|
||||||
timePenalty = clamp01(0.40 / 0.3) = 1.0
|
|
||||||
segmentPenalty = clamp01((8/0.5) / 6) = clamp01(16/6) = 1.0
|
|
||||||
|
|
||||||
TotalPenalty = 0.4×0.833 + 0.3×1.0 + 0.3×1.0 = 0.933
|
|
||||||
Score = 100 × (1 - 0.933) = 6.7 分
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. 数据存储层
|
|
||||||
|
|
||||||
### 6.1 切片服务
|
|
||||||
|
|
||||||
#### 6.1.1 localStorage 存储策略
|
|
||||||
|
|
||||||
存储键：`noise-slices`
|
|
||||||
|
|
||||||
**隐私说明：**
|
|
||||||
- 存储内容：时间戳、噪音统计（不包含音频数据）
|
|
||||||
- 风险：可能泄露位置/日程信息
|
|
||||||
- 建议：在 UI 中提供"清除历史"功能
|
|
||||||
|
|
||||||
#### 6.1.2 时间窗口清理
|
|
||||||
|
|
||||||
**默认保留时长：** 14 天
|
|
||||||
**可配置范围：** 1 ~ 365 天
|
|
||||||
|
|
||||||
使用新切片的结束时间作为基准计算 cutoff，确保新切片不会被清理。
|
|
||||||
|
|
||||||
#### 6.1.3 容量限制
|
|
||||||
|
|
||||||
**容量上限：** 本地存储配额的 90%
|
|
||||||
|
|
||||||
#### 6.1.4 数据规范化与校验
|
|
||||||
|
|
||||||
**精度控制：**
|
|
||||||
- dBFS：3 位小数
|
|
||||||
- overRatioDbfs：4 位小数
|
|
||||||
- 显示分贝：2 位小数
|
|
||||||
- 评分：1 位小数
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 7. 历史报告生成
|
|
||||||
|
|
||||||
### 7.1 历史构建器
|
|
||||||
|
|
||||||
#### 7.1.1 与课表关联逻辑
|
|
||||||
|
|
||||||
**关联规则：**
|
|
||||||
1. 按日期分组切片
|
|
||||||
2. 对每个日期的每个课时，查找重叠的切片
|
|
||||||
3. 计算该课时的平均评分
|
|
||||||
|
|
||||||
#### 7.1.2 时段平均评分计算（加权平均）
|
|
||||||
|
|
||||||
**公式：**
|
|
||||||
$$ \text{avgScore} = \frac{\sum_{i} \text{score}_i \times \text{effectiveMs}_i}{\sum_{i} \text{effectiveMs}_i} $$
|
|
||||||
|
|
||||||
其中：
|
|
||||||
$$ \text{effectiveMs}_i = \text{sampledDurationMs}_i \times \frac{\text{overlapMs}_i}{\text{sliceMs}_i} $$
|
|
||||||
|
|
||||||
#### 7.1.3 覆盖率计算
|
|
||||||
|
|
||||||
**公式：**
|
|
||||||
$$ \text{coverageRatio} = \frac{\text{totalMs}}{\text{periodMs}} $$
|
|
||||||
|
|
||||||
**含义：** 课时内有效采样时长占课时总时长的比例
|
|
||||||
|
|
||||||
#### 7.1.4 日期时间处理
|
|
||||||
|
|
||||||
**时区说明：**
|
|
||||||
- 使用本地时区
|
|
||||||
- 内部存储使用 UTC 时间戳
|
|
||||||
- 对外展示使用本地时间
|
|
||||||
|
|
||||||
**日期格式：** `YYYY-MM-DD`
|
|
||||||
**时间格式：** `HH:MM`
|
|
||||||
|
|
||||||
#### 7.1.5 跨天课时处理
|
|
||||||
|
|
||||||
如果结束时间 ≤ 开始时间，则课时跨越到次日。
|
|
||||||
|
|
||||||
#### 7.1.6 报告中的图表
|
|
||||||
|
|
||||||
在噪音统计报告中，您可以直观地看到这些数据：
|
|
||||||
|
|
||||||
- **评分走势图**：展示了 `Score` 随时间的变化，帮助您回顾专注状态
|
|
||||||
- **噪音等级分布**：将每一帧归类为安静/正常/吵闹/极吵，直观展示时间占比
|
|
||||||
- **扣分归因**：直接显示上述三个维度的扣分比例，告诉您为什么分低（是因为一直吵，还是因为总被打断）
|
|
||||||
- **打断次数密度**：展示每分钟被干扰的次数
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 8. 流服务整合
|
|
||||||
|
|
||||||
### 8.1 噪音流服务
|
|
||||||
|
|
||||||
#### 8.1.1 订阅/发布模式
|
|
||||||
|
|
||||||
**模式：** 观察者模式
|
|
||||||
- 多个组件可同时订阅
|
|
||||||
- 最后一个订阅者取消时自动停止采集
|
|
||||||
|
|
||||||
#### 8.1.2 生命周期管理
|
|
||||||
|
|
||||||
流服务支持启动、停止和重启操作，自动管理采集资源的生命周期。
|
|
||||||
|
|
||||||
#### 8.1.3 预热帧处理
|
|
||||||
|
|
||||||
**目的：** 丢弃麦克风启动后的不稳定数据（约 500ms）
|
|
||||||
|
|
||||||
#### 8.1.4 设置热更新响应
|
|
||||||
|
|
||||||
**需要重启的参数：**
|
|
||||||
- frameMs
|
|
||||||
- sliceSec
|
|
||||||
- scoreThresholdDbfs
|
|
||||||
- segmentMergeGapMs
|
|
||||||
- maxSegmentsPerMin
|
|
||||||
|
|
||||||
**无需重启的参数：**
|
|
||||||
- maxLevelDb
|
|
||||||
- showRealtimeDb
|
|
||||||
- alertSoundEnabled
|
|
||||||
- avgWindowSec
|
|
||||||
- baselineDb
|
|
||||||
|
|
||||||
#### 8.1.5 时间加权平均
|
|
||||||
|
|
||||||
**公式：**
|
|
||||||
$$ \text{avg} = \frac{\sum_{i} v_i \times (t_{i+1} - t_i)}{\sum_{i} (t_{i+1} - t_i)} $$
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 9. 配置参数体系
|
|
||||||
|
|
||||||
### 9.1 常量定义
|
|
||||||
|
|
||||||
#### 9.1.1 分析参数
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
NOISE_ANALYSIS_SLICE_SEC = 30; // 切片时长 30 秒
|
|
||||||
NOISE_ANALYSIS_FRAME_MS = 50; // 帧间隔 50ms
|
|
||||||
NOISE_SCORE_THRESHOLD_DBFS = -50; // 评分阈值 -50dBFS
|
|
||||||
NOISE_SCORE_SEGMENT_MERGE_GAP_MS = 500; // 事件段合并间隔 500ms
|
|
||||||
NOISE_SCORE_MAX_SEGMENTS_PER_MIN = 6; // 每分钟最大事件段数 6
|
|
||||||
NOISE_REALTIME_CHART_SLICE_COUNT = 1; // 实时图表切片数 1
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 9.1.2 报告参数
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
DEFAULT_NOISE_REPORT_RETENTION_DAYS = 14; // 默认保留 14 天
|
|
||||||
MIN_NOISE_REPORT_RETENTION_DAYS = 1; // 最小保留 1 天
|
|
||||||
MAX_NOISE_REPORT_RETENTION_DAYS_FALLBACK = 365; // 最大保留 365 天
|
|
||||||
```
|
|
||||||
|
|
||||||
### 9.2 设置管理
|
|
||||||
|
|
||||||
#### 9.2.1 固定参数
|
|
||||||
|
|
||||||
为保证评分口径稳定，避免用户通过调整参数"刷分"，以下参数固定为程序内常量：
|
|
||||||
- sliceSec
|
|
||||||
- frameMs
|
|
||||||
- scoreThresholdDbfs
|
|
||||||
- segmentMergeGapMs
|
|
||||||
- maxSegmentsPerMin
|
|
||||||
|
|
||||||
#### 9.2.2 可配置参数
|
|
||||||
|
|
||||||
| 参数 | 类型 | 默认值 | 说明 |
|
|
||||||
|------|------|--------|------|
|
|
||||||
| maxLevelDb | number | 55 | 最大允许噪音级别（显示分贝） |
|
|
||||||
| baselineDb | number | 40 | 手动基准显示分贝 |
|
|
||||||
| showRealtimeDb | boolean | true | 是否显示实时分贝 |
|
|
||||||
| avgWindowSec | number | 1 | 噪音平均时间窗（秒） |
|
|
||||||
| alertSoundEnabled | boolean | false | 超阈值提示音开关 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 10. 类型定义
|
|
||||||
|
|
||||||
### 10.1 核心类型
|
|
||||||
|
|
||||||
#### 10.1.1 噪音帧采样
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
interface NoiseFrameSample {
|
|
||||||
t: number; // 时间戳
|
|
||||||
rms: number; // 均方根值
|
|
||||||
dbfs: number; // 分贝值 (dBFS)
|
|
||||||
peak?: number; // 峰值
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 10.1.2 噪音切片原始统计
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
interface NoiseSliceRawStats {
|
|
||||||
avgDbfs: number; // 平均分贝
|
|
||||||
maxDbfs: number; // 最大分贝
|
|
||||||
p50Dbfs: number; // 中位数分贝
|
|
||||||
p95Dbfs: number; // 95分位数分贝
|
|
||||||
overRatioDbfs: number; // 超阈值比例
|
|
||||||
segmentCount: number; // 事件段数量
|
|
||||||
sampledDurationMs?: number; // 采样时长
|
|
||||||
gapCount?: number; // 缺口数量
|
|
||||||
maxGapMs?: number; // 最大缺口时长
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 10.1.3 噪音切片显示统计
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
interface NoiseSliceDisplayStats {
|
|
||||||
avgDb: number; // 平均显示分贝
|
|
||||||
p95Db: number; // 95分位数显示分贝
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 10.1.4 噪音评分明细
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
interface NoiseScoreBreakdown {
|
|
||||||
sustainedPenalty: number; // 持续噪音惩罚
|
|
||||||
timePenalty: number; // 时间惩罚
|
|
||||||
segmentPenalty: number; // 事件段惩罚
|
|
||||||
thresholdsUsed: {
|
|
||||||
scoreThresholdDbfs: number; // 使用的评分阈值
|
|
||||||
segmentMergeGapMs: number; // 使用的合并间隔
|
|
||||||
maxSegmentsPerMin: number; // 使用的最大事件段数
|
|
||||||
};
|
|
||||||
sustainedLevelDbfs: number; // 持续电平
|
|
||||||
overRatioDbfs: number; // 超阈值比例
|
|
||||||
segmentCount: number; // 事件段数量
|
|
||||||
minutes: number; // 时长（分钟）
|
|
||||||
durationMs?: number; // 物理时长
|
|
||||||
sampledDurationMs?: number; // 采样时长
|
|
||||||
coverageRatio?: number; // 覆盖率
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 10.1.5 噪音切片摘要
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
interface NoiseSliceSummary {
|
|
||||||
start: number; // 开始时间戳
|
|
||||||
end: number; // 结束时间戳
|
|
||||||
frames: number; // 帧数
|
|
||||||
raw: NoiseSliceRawStats; // 原始统计
|
|
||||||
display: NoiseSliceDisplayStats; // 显示统计
|
|
||||||
score: number; // 评分
|
|
||||||
scoreDetail: NoiseScoreBreakdown; // 评分明细
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 10.1.6 实时数据点
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
interface NoiseRealtimePoint {
|
|
||||||
t: number; // 时间戳
|
|
||||||
dbfs: number; // 分贝值 (dBFS)
|
|
||||||
displayDb: number; // 显示分贝
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 10.1.7 噪音流快照
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
interface NoiseStreamSnapshot {
|
|
||||||
status: NoiseStreamStatus; // 流状态
|
|
||||||
realtimeDisplayDb: number; // 实时显示分贝
|
|
||||||
realtimeDbfs: number; // 实时分贝 (dBFS)
|
|
||||||
maxLevelDb: number; // 最大允许级别
|
|
||||||
showRealtimeDb: boolean; // 是否显示实时分贝
|
|
||||||
alertSoundEnabled: boolean; // 提示音开关
|
|
||||||
ringBuffer: NoiseRealtimePoint[]; // 环形缓冲区快照
|
|
||||||
latestSlice: NoiseSliceSummary | null; // 最新切片
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 10.1.8 噪音流状态
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
type NoiseStreamStatus =
|
|
||||||
| "initializing" // 初始化中
|
|
||||||
| "quiet" // 安静
|
|
||||||
| "noisy" // 嘈杂
|
|
||||||
| "permission-denied" // 权限拒绝
|
|
||||||
| "error"; // 错误
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 附录
|
|
||||||
|
|
||||||
### A. 术语表
|
|
||||||
|
|
||||||
| 术语 | 英文 | 说明 |
|
|
||||||
|------|------|------|
|
|
||||||
| 均方根 | RMS (Root Mean Square) | 衡量音频信号强度的标准方法 |
|
|
||||||
| 分贝满刻度 | dBFS (Decibels relative to Full Scale) | 数字音频的标准分贝单位，范围 -100 到 0 dB |
|
|
||||||
| 显示分贝 | Display dB | 用于用户界面展示的分贝值，范围 20 到 100 dB |
|
|
||||||
| 切片 | Slice | 固定时间窗口（默认 30 秒）内的噪音数据聚合 |
|
|
||||||
| 帧 | Frame | 单次音频采样（默认 50ms） |
|
|
||||||
| 事件段 | Segment | 独立的噪音事件，通过合并窗口（500ms）合并 |
|
|
||||||
|
|
||||||
### B. 参数固定策略
|
|
||||||
|
|
||||||
为保证统计口径稳定，当前版本将"分析与评分"的高级参数固定为程序内常量：
|
|
||||||
|
|
||||||
| 参数 | 值 | 说明 |
|
|
||||||
|------|-----|------|
|
|
||||||
| frameMs | 50ms | 约 20fps |
|
|
||||||
| sliceSec | 30s | 切片时长 |
|
|
||||||
| scoreThresholdDbfs | -50 dBFS | 评分阈值 |
|
|
||||||
| segmentMergeGapMs | 500ms | 事件段合并间隔 |
|
|
||||||
| maxSegmentsPerMin | 6 | 每分钟最大事件段数 |
|
|
||||||
|
|
||||||
### C. 技术栈
|
|
||||||
|
|
||||||
- **音频处理**：Web Audio API
|
|
||||||
- **数据存储**：localStorage
|
|
||||||
- **前端框架**：React 18
|
|
||||||
- **构建工具**：Vite 5
|
|
||||||
- **类型系统**：TypeScript 5.4
|
|
||||||
|
|
||||||
|
1. capture microphone input
|
||||||
|
2. compute RMS and dBFS
|
||||||
|
3. aggregate frames into slices
|
||||||
|
4. score each slice
|
||||||
|
5. persist historical statistics
|
||||||
|
6. present realtime and historical views
|
||||||
|
|||||||
63
run.md
63
run.md
@@ -1,54 +1,55 @@
|
|||||||
# LanMountainDesktop 运行指南
|
# 运行指南
|
||||||
|
|
||||||
本文档只负责“怎么跑起来”。项目介绍请看 [README.md](./README.md)。
|
## 中文
|
||||||
|
|
||||||
## 1. 环境准备
|
本文档只说明如何在本地运行阑山桌面。
|
||||||
- 安装 .NET SDK 10（`net10.0`）。
|
|
||||||
- 建议使用 Windows 运行桌面端（当前桌面体验以 Windows 为主）。
|
|
||||||
|
|
||||||
## 2. 拉取依赖并构建
|
### 环境准备
|
||||||
在仓库根目录执行：
|
|
||||||
|
- 安装 .NET SDK 10。
|
||||||
|
- 桌面端建议在 Windows 上运行。
|
||||||
|
|
||||||
|
### 构建
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
dotnet restore
|
dotnet restore
|
||||||
dotnet build LanMountainDesktop.sln -c Debug
|
dotnet build LanMountainDesktop.sln -c Debug
|
||||||
```
|
```
|
||||||
|
|
||||||
## 3. 运行桌面端
|
### 运行桌面端
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
dotnet run --project LanMountainDesktop/LanMountainDesktop.csproj
|
dotnet run --project LanMountainDesktop/LanMountainDesktop.csproj
|
||||||
```
|
```
|
||||||
|
|
||||||
## 4. 推荐能力说明
|
### 常见问题
|
||||||
桌面端已内置推荐数据服务（每日诗词 / 每日名画），默认无需额外启动本地推荐后端。
|
|
||||||
|
|
||||||
## 5. 常见问题
|
- 如果提示 SDK 版本不匹配，先检查 `dotnet --info`。
|
||||||
- 启动失败提示 SDK 版本不匹配：确认 `dotnet --info` 中已安装 .NET 10 SDK。
|
- 如果视频能力异常，优先在 Windows 环境验证。
|
||||||
- 桌面端视频相关能力异常：优先在 Windows 环境下验证。
|
- 如果要重置配置，可删除 `%LOCALAPPDATA%\LanMountainDesktop\settings.json` 后重启。
|
||||||
- 配置重置：删除 `%LOCALAPPDATA%\LanMountainDesktop\settings.json` 后重启应用。
|
|
||||||
|
|
||||||
## 6. Linux 音频功能依赖
|
### Linux 录音依赖
|
||||||
|
|
||||||
如果在 Linux 上使用录音机组件或自习监测组件，需要安装以下音频库：
|
如果在 Linux 上使用录音机或自习监测相关能力，需要安装音频库：
|
||||||
|
|
||||||
|
- Debian/Ubuntu：`sudo apt install libportaudio2 libasound2`
|
||||||
|
- Fedora/RHEL：`sudo dnf install portaudio-libs alsa-lib`
|
||||||
|
- Arch Linux：`sudo pacman -S portaudio alsa-lib`
|
||||||
|
- Alpine Linux：`sudo apk add portaudio alsa-lib`
|
||||||
|
|
||||||
|
## English
|
||||||
|
|
||||||
|
This guide explains how to run LanMountainDesktop locally.
|
||||||
|
|
||||||
|
### Build
|
||||||
|
|
||||||
### Debian/Ubuntu
|
|
||||||
```bash
|
```bash
|
||||||
sudo apt install libportaudio2 libasound2
|
dotnet restore
|
||||||
|
dotnet build LanMountainDesktop.sln -c Debug
|
||||||
```
|
```
|
||||||
|
|
||||||
### Fedora/RHEL
|
### Run
|
||||||
```bash
|
|
||||||
sudo dnf install portaudio-libs alsa-lib
|
|
||||||
```
|
|
||||||
|
|
||||||
### Arch Linux
|
|
||||||
```bash
|
```bash
|
||||||
sudo pacman -S portaudio alsa-lib
|
dotnet run --project LanMountainDesktop/LanMountainDesktop.csproj
|
||||||
```
|
```
|
||||||
|
|
||||||
### Alpine Linux
|
|
||||||
```bash
|
|
||||||
sudo apk add portaudio alsa-lib
|
|
||||||
```
|
|
||||||
|
|
||||||
> 注：如果未安装这些依赖，录音和自习监测功能将不可用，但应用其他功能可以正常运行。
|
|
||||||
|
|||||||
Reference in New Issue
Block a user