0.3.4

2026-06-21 16:14:28 +08:00 · 2026-03-04 13:18:07 +08:00
parent 2a41b8c016
commit c42a7d8f25
4 changed files with 77 additions and 644 deletions
--- a/CICD_EVALUATION.md
+++ b/CICD_EVALUATION.md
@@ -1,263 +0,0 @@
-# LanMontainDesktop CI/CD 评估与实现方案
-
-## 📊 项目分析
-
-### 项目特征
-| 特性 | 详情 |
-|------|------|
-| **框架** | Avalonia 11 (.NET 10) |
-| **主平台** | Windows (x64/x86) |
-| **项目数量** | 2个主项目 + 1个测试项目 |
-| **后端** | ASP.NET Core Web API (RecommendationBackend) |
-| **特殊能力** | 视频壁纸支持 (LibVLC) |
-| **发布方式** | PowerShell脚本 (scripts/package.ps1) |
-
-### 与ClassIsland的对比
-
-| 方面 | LanMontainDesktop | ClassIsland |
-|------|-------------------|-------------|
-| 平台覆盖 | 🔷 主要Windows | 🟢 多平台(Win/Linux/macOS) |
-| 构建复杂度 | 🔷 中等 | 🔴 很高(专业级) |
-| 发布周期 | 🔷 按需 | 🔴 频繁release |
-| CI配置 | 🔴 无 | 🟢 完整 |
-| 代码质量检查 | 🔴 无 | 🟢 Qodana集成 |
-
-## 🎯 推荐方案（渐进式）
-
-### **阶段1：基础CI（已完成 ✅）**
-实现核心构建验证，支持每次commit自动检查
-
- ✅ **Build Workflow** - 每次push/PR自动构建
-  - Debug + Release 配置
-  - 两个项目同时构建
-  - 保存build artifacts
-  
- ✅ **Code Quality** - 代码检查
-  - dotnet format检查
-  - 编译警告/错误检测
-  - Qodana集成（可选）
-
- ✅ **PR Template** - 统一pull request规范
-  - 变更类型分类
-  - 测试清单
-  - 截图/视频支持
-
- ✅ **Issue Templates** - GitHub问题规范
-  - 🐛 Bug Report
-  - ✨ Feature Request  
-  - ⚙️ Configuration Issues
-
-### **阶段2：多平台发布自动化（已完成 ✅）**
-完整的跨平台构建与自动化发布
-
- ✅ **多平台Release Workflow** - Git tag触发全平台构建
-  - 🪟 **Windows**: x64 + x86 自包含可执行文件
-  - 🐧 **Linux**: x64 tar.gz包（支持自定义架构）
-  - 🍎 **macOS**: x64 + arm64 (Apple Silicon) tar.gz包
-  - 自动版本号更新
-  - 统一artifact命名
-  - GitHub Release自动创建详细说明
-
- ✅ **构建脚本支持**
-  - PowerShell脚本处理Windows特定依赖
-  - Bash脚本统一处理Linux/macOS
-  - .gitattributes确保行尾兼容
-
- ✅ **灵活的手动触发**
-  - 支持选择性构建（仅Windows/Linux/macOS）
-  - 预发布标记支持
-  - 版本号手动指定
-
- ✅ **Issue Management** - 自动化问题管理
-  - 自动标记过期问题
-  - 自动关闭无活动PR
-  - 可自定义时间阈值
-
-### **阶段3：建议（未来优化）**
- 🔲 **安装程序生成** - MSI/EXE (Windows), .deb (Linux), DMG (macOS)
- 🔲 **代码签名** - macOS notarization, Windows签名
- 🔲 **AppImage/Snap** - Linux现代打包格式
- 🔲 **Docker镜像** - 后端容器化
- 🔲 **测试覆盖报告** - Codecov集成
- 🔲 **性能基准测试** - PR性能对比
- 🔲 **自动更新检查** - 依赖版本检查
-
-## 🔧 创建的GitHub工作流与脚本
-
-### 工作流文件（4个）
-
-1. **[Build & Test](/.github/workflows/build.yml)** - 核心构建验证
-   - 在每个push和PR时自动运行
-   - Debug + Release 两种配置
-   - 支持两个项目同时构建
-   - 保存build artifacts用于检查
-
-2. **[Code Quality](/.github/workflows/code-quality.yml)** - 代码质量检查
-   - 代码格式检查(`dotnet format`)
-   - 编译错误/警告检测
-   - 预留Qodana集成位置（可选）
-
-3. **[Release & Publish (多平台)](/.github/workflows/release.yml)** ⭐ 升级版
-   - **Windows**: x64 + x86
-   - **Linux**: x64
-   - **macOS**: x64 + arm64 (Apple Silicon)
-   - 基于Git标签自动触发
-   - 支持手动选择构建平台
-   - 自动创建GitHub Release
-
-4. **[Issue Management](/.github/workflows/issue-management.yml)** - 自动化问题管理
-   - 每日标记过期问题
-   - 自动关闭无活动PR
-   - 可自定义时间阈值
-
-### 构建脚本
-
-| 脚本 | 平台 | 功能 |
-|------|------|------|
-| `LanMontainDesktop\scripts\package.ps1` | Windows | 现有PowerShell打包脚本 |
-| `scripts\build.sh` | Linux/macOS | 新增跨平台构建脚本 |
-
-### 配置文件
-
-| 文件 | 用途 |
-|------|------|
-| `.gitattributes` | 行尾处理，确保跨平台兼容 |
-| `.github/CODEOWNERS` | 代码所有权定义 |
-| `.github/pull_request_template.md` | PR提交规范 |
-| `.github/ISSUE_TEMPLATE/*.md` | Issue模板 |
-| `.github/WORKFLOWS_GUIDE.md` | 工作流使用指南 |
-| `.github/MULTIPLATFORM_BUILD.md` | 多平台构建详细指南 ⭐ |
-
-## 🚀 快速开始
-
-### 1. 验证工作流正常运行
-```bash
-# Push到main分支
-git add .github/
-git commit -m "feat: Add GitHub CI/CD workflows"
-git push origin main
-
-# 检查GitHub Actions是否自动运行
-# https://github.com/YOUR_ORG/LanMontainDesktop/actions
-```
-
-### 2. 创建第一个Release（可选）
-```bash
-# 本地修改版本号（如果需要）
-# 然后创建tag
-git tag v1.0.0
-git push origin v1.0.0
-
-# GitHub Actions会自动：
-# 1. 更新版本号
-# 2. 构建Release版本
-# 3. 创建可执行文件
-# 4. 生成GitHub Release
-```
-
-### 3. 配置分支保护规则（推荐）
-在 GitHub > Settings > Branches > Branch Protection Rules：
- 要求CI检查通过再merge
- 要求PR审查
- 要求代码最新
-
-## ⚙️ 配置选项
-
-### 可选：启用Qodana代码分析
-
-1. 访问 https://qodana.cloud
-2. 注册并创建organization token
-3. 在GitHub > Settings > Secrets > Actions 中添加：
-   - `QODANA_TOKEN`
-   - `QODANA_ENDPOINT=https://qodana.cloud`
-4. 在 `.github/workflows/code-quality.yml` 中取消Qodana步骤注释
-
-### 自定义构建参数
-
-编辑 `.github/workflows/` 中的yml文件：
- `DOTNET_VERSION` - 改变.NET版本
- 分支列表 - 改变监控的分支
- 矩阵配置 - 添加更多构建配置
-
-## 📊 工作流对比与选择
-
-### Build日语言表
-| 工作流 | 触发条件 | 运行时间 | 成本 |
-|--------|---------|--------|------|
-| Build | 每个push/PR | ~2-3分钟 | 低 |
-| Code Quality | PR/push | ~2-3分钟 | 低 |
-| Release | Tag push | ~5-10分钟 | 中 |
-| Issue Mgmt | 每天1次 | ~1分钟 | 很低 |
-
-### 预计月度GitHub Actions使用
- **小项目**(<5贡献者): 100-200 runner hours
- **中等项目**(5-20贡献者): 300-500 runner hours  
- **大项目**（>20贡献者): 800+ runner hours
-
-> 💡 **免费额度**: 2000 runner hours/月 (对大多数开源项目足够)
-
-## 🔍 故障排查
-
-### 工作流不运行？
- [ ] 检查 `.github/workflows/*.yml` 语法（YAML缩进）
- [ ] 确认分支名称配置正确
- [ ] 查看Actions标签查看错误日志
- [ ] 检查分支保护规则是否冲突
-
-### 构建失败？
-```bash
-# 本地重现CI环境
-dotnet clean
-dotnet restore
-dotnet build LanMontainDesktop/LanMontainDesktop.csproj -c Release
-```
-
-### PR检查无法通过？
-1. 本地运行 `dotnet format`
-2. 确保没有编译警告
-3. 所有测试通过
-
-## 📚 参考资源
-
- [.github/WORKFLOWS_GUIDE.md](.github/WORKFLOWS_GUIDE.md) - 详细使用指南
- [GitHub Actions文档](https://docs.github.com/actions)
- [ClassIsland CI/CD参考](https://github.com/ClassIsland/ClassIsland/.github/workflows)
- [Avalonia发布指南](https://docs.avaloniaui.net/docs/deployment)
-
-## ✅ 完成清单
-
- [x] 构建工作流
- [x] 代码质量检查
- [x] 发布自动化
- [x] Issue管理
- [x] PR模板
- [x] Issue模板
- [x] CODEOWNERS定义
- [x] 完整文档
- [ ] 调试并测试所有工作流
- [ ] 配置Qodana（可选）
- [ ] 配置分支保护规则（推荐）
-
-## 🎓 下一步建议
-
-1. **立即做**
-   - 推送所有文件到GitHub
-   - 验证工作流运行成功
-   - 配置分支保护规则
-
-2. **本周内**
-   - 在贡献指南中记录工作流
-   - 团队成员熟悉PR流程
-   - 测试第一个Release构建
-
-3. **后续优化**
-   - 基于实际运行数据调整参数
-   - 添加额外的检查（危险代码扫描等）
-   - 集成代码覆盖率报告
-   - 准备多平台构建（需要）
-
---
-
-**创建时间**: 2026-03-04  
-**参考项目**: ClassIsland  
-**目标**: 提高代码质量和发布效率 🚀
--- a/MULTIPLATFORM_RELEASE_GUIDE.md
+++ b/MULTIPLATFORM_RELEASE_GUIDE.md
@@ -1,315 +0,0 @@
-# 🚀 LanMontainDesktop 多平台 CI/CD 工作流完整指南
-
-## 📋 概述
-
-已为 LanMontainDesktop 项目配置完整的 **GitHub Actions 多平台 CI/CD 工作流**，支持 Windows、Linux 和 macOS 的自动化构建和发布。
-
-## ✨ 新增功能亮点
-
-### 🪟 Windows 多架构支持
- ✅ **win-x64** (64位) - 主要架构
- ✅ **win-x86** (32位) - 兼容性
- 输出：`.zip` 可执行包
-
-### 🐧 Linux 支持
- ✅ **linux-x64** - 依赖X11
- 输出：`.tar.gz` 压缩包
- 依赖：自动安装 fontconfig、freetype 等库
- 计划：AppImage、Snap、.deb 包
-
-### 🍎 macOS 完整支持
- ✅ **osx-x64** - Intel 芯片（经典Mac）
- ✅ **osx-arm64** - Apple Silicon（M1/M2/M3）
- 输出：`.tar.gz` 压缩包
- 计划：DMG、代码签名、公证
-
-## 📦 发布流程
-
-```
-推送 Git Tag (v1.0.0)
-    ↓
-GitHub Actions 触发
-    ↓
-┌─────────────────────────────────┐
-│  并行构建三个平台                │
-│  ├─ Windows (x64 + x86)         │
-│  ├─ Linux (x64)                 │
-│  └─ macOS (x64 + arm64)         │
-└─────────────────────────────────┘
-    ↓
-创建 GitHub Release
-    ↓
-自动上传所有平台包
-```
-
-## 🎯 使用方式
-
-### 快速发布（所有平台）
-
-```bash
-# 1. 确保所有更改已提交
-git add .
-git commit -m "Release v1.0.0"
-
-# 2. 创建并推送标签
-git tag v1.0.0
-git push origin v1.0.0
-
-# 3. GitHub Actions 自动构建
-# 等待 Actions 完成 → 自动创建 Release
-# 查看：https://github.com/YOUR_ORG/LanMontainDesktop/releases
-```
-
-### 手动触发（选择性平台）
-
-1. 访问 GitHub Actions 标签页
-2. 选择 **Release & Publish** 工作流
-3. 点击 **Run workflow**
-4. 填入版本号（如 `1.0.0`）
-5. ☑️ 选择要构建的平台：
-   - ✅ Build Windows (x64/x86)
-   - ✅ Build Linux (x64)
-   - ✅ Build macOS (x64/arm64)
-6. 可选：☑️ 标记为预发布版本
-7. 点击 **Run workflow**
-
-### 本地测试构建
-
-**Windows:**
-```powershell
-.\LanMontainDesktop\scripts\package.ps1 -RuntimeIdentifier win-x64 -Version 1.0.0
-```
-
-**Linux:**
-```bash
-chmod +x scripts/build.sh
-./scripts/build.sh --rid linux-x64 --version 1.0.0
-```
-
-**macOS:**
-```bash
-chmod +x scripts/build.sh
-./scripts/build.sh --rid osx-x64 --version 1.0.0
-./scripts/build.sh --rid osx-arm64 --version 1.0.0
-```
-
-## 📂 项目结构变更
-
-```
-LanMontainDesktop/
-├── .github/
-│   ├── workflows/
-│   │   ├── build.yml                    # ✅ CI 持续构建
-│   │   ├── code-quality.yml             # ✅ 代码质量检查
-│   │   ├── release.yml                  # ⭐ 多平台 Release（已升级）
-│   │   └── issue-management.yml         # ✅ Issue 自动管理
-│   ├── ISSUE_TEMPLATE/
-│   │   ├── bug_report.md                # Bug 报告模板
-│   │   ├── feature_request.md           # 功能请求模板
-│   │   └── config_issue.md              # 配置问题模板
-│   ├── CODEOWNERS                       # 代码所有权
-│   ├── pull_request_template.md         # PR 模板
-│   ├── WORKFLOWS_GUIDE.md               # 工作流详细指南
-│   └── MULTIPLATFORM_BUILD.md           # ⭐ 多平台构建指南（新增）
-├── scripts/
-│   ├── build.sh                         # ⭐ Linux/macOS 构建脚本（新增）
-│   └── package.ps1                      # Windows 打包脚本（已有）
-├── .gitattributes                       # ⭐ 行尾处理配置（新增）
-└── CICD_EVALUATION.md                   # CI/CD 评估文档（已更新）
-```
-
-## 🔄 工作流详解
-
-### 1. Build & Test (`build.yml`)
-**何时运行:** Push、PR、手动触发  
-**做什么:** 
- 构建 Debug 和 Release 两种配置
- 运行测试
- 检查编译错误
-
-### 2. Code Quality (`code-quality.yml`)
-**何时运行:** PR、Push 到主分支  
-**做什么:**
- 检查代码格式（`dotnet format`）
- 编译警告检测
- 可选：Qodana 分析
-
-### 3. Release & Publish (`release.yml`) ⭐
-**何时运行:** 推送 Git 标签或手动触发  
-**支持平台:**
- Windows: win-x64, win-x86
- Linux: linux-x64
- macOS: osx-x64, osx-arm64
-
-**做什么:**
-1. 检测版本号（从标签或手动输入）
-2. 并行构建所有平台
-3. 创建平台特定的包
-4. 生成 GitHub Release
-5. 上传所有 artifacts
-
-### 4. Issue Management (`issue-management.yml`)
-**何时运行:** 每天 1:30 AM UTC  
-**做什么:**
- 标记 14 天无活动的 Issue 为 "stale"
- 关闭 21 天无活动的 PR
- 自动评论提醒
-
-## 📊 预期构建时间
-
-| 平台 | 架构 | 时间 | 成本 |
-|------|------|------|------|
-| Windows | x64 | ~2-3m | 低 |
-| Windows | x86 | ~2-3m | 低 |
-| Linux | x64 | ~2-3m | 低 |
-| macOS | x64 | ~3-5m | 低 |
-| macOS | arm64 | ~3-5m | 低 |
-| **总计** | 5个 | ~12-20m | 低 |
-
-> 💡 GitHub 免费账户每月 2000 runner-hours，足够大多数项目使用
-
-## 🛠️ 配置与优化
-
-### 必需配置
-✅ 无需额外配置！工作流开箱即用
-
-### 可选配置
-
-**启用 Qodana 代码分析:**
-1. 访问 https://qodana.cloud
-2. 创建 organization token
-3. 在 GitHub Settings > Secrets > Actions 添加：
-   - `QODANA_TOKEN` = your_token
-   - `QODANA_ENDPOINT` = https://qodana.cloud
-4. 编辑 `.github/workflows/code-quality.yml`，取消 Qodana 步骤注释
-
-**配置分支保护规则:** （强烈推荐）
-1. 访问 Settings > Branches > Branch Protection Rules
-2. 要求通过以下检查：
-   - ✅ Build & Test
-   - ✅ Code Quality
-3. 要求代码审查后再合并
-4. 驳回过期分支
-
-## 🐛 故障排查
-
-### Release 工作流不运行？
- 检查标签格式：`v1.0.0` 或 `release-1.0.0`
- 确认 csproj 文件格式正确
- 查看 Actions 日志获取详细错误
-
-### 特定平台构建失败？
- **Windows**: 检查 libvlc 依赖
- **Linux**: 确保依赖库已安装
- **macOS**: 检查 Xcode 命令行工具
-
-### 包大小过大？
- 启用 `PublishTrimmed=true` 缩小 IL 代码
- 考虑关闭符号信息：`DebugType=none`
-
-## 📚 文档导航
-
-| 文档 | 用途 |
-|------|------|
-| [WORKFLOWS_GUIDE.md](.github/WORKFLOWS_GUIDE.md) | 工作流使用指南 |
-| [MULTIPLATFORM_BUILD.md](.github/MULTIPLATFORM_BUILD.md) | 多平台构建详解 |
-| [CICD_EVALUATION.md](CICD_EVALUATION.md) | CI/CD 评估与规划 |
-
-## 🎓 下一步
-
-### 立即做（今天）
- [ ] 推送所有更改到 GitHub
- [ ] 验证 Actions 工作流运行成功
- [ ] 测试创建第一个 Release 标签
-
-### 本周内
- [ ] 配置分支保护规则
- [ ] 团队成员熟悉 PR 流程
- [ ] 收集使用反馈
-
-### 后续优化（计划）
- [ ] 启用 Qodana 代码分析
- [ ] 添加测试覆盖率报告
- [ ] 生成安装程序（.exe/.msi/.deb）
- [ ] 代码签名与公证
- [ ] AppImage/DMG 打包
-
-## 💡 最佳实践
-
-### ✅ 发布时
-```bash
-# 1. 确保代码已通过所有 CI 检查
-# 2. 更新版本号和 CHANGELOG
-# 3. 创建有意义的标签消息
-git tag -a v1.0.0 -m "Release v1.0.0: New features and bug fixes"
-
-# 4. 推送
-git push origin v1.0.0
-
-# 5. 稍等片刻（Actions 运行 12-20 分钟）
-# 6. 在 Releases 页面查看结果
-```
-
-### ✅ 每次提交
-```bash
-# 本地测试
-dotnet build
-dotnet format  # 必须！
-dotnet test
-
-# 然后提交
-git add .
-git commit -m "feat: Add cool feature"
-git push
-```
-
-### ✅ 代码审查
- 检查 CI 检查是否全部通过 ✅
- 检查代码格式 ✅
- 确认目标分支正确 ✅
-
-## 📈 监控与报告
-
-**查看构建状态:**
- GitHub > Actions 标签页
- 或添加状态徽章到 README.md：
-
-```markdown
-![Build Status](https://github.com/YOUR_ORG/LanMontainDesktop/workflows/Build%20&%20Test/badge.svg)
-![Release Status](https://github.com/YOUR_ORG/LanMontainDesktop/workflows/Release%20&%20Publish/badge.svg)
-```
-
-## 🤝 贡献指南集成
-
-建议在 CONTRIBUTING.md 中添加：
-
-```markdown
-## 发布流程
-
-1. 更新版本号
-2. 创建 Release 分支
-3. 提交 PR
-4. 获得审批后 Squash merge
-5. 创建 Git 标签：`git tag v1.0.0`
-6. GitHub Actions 自动构建和发布
-
-详见：[WORKFLOWS_GUIDE.md](.github/WORKFLOWS_GUIDE.md)
-```
-
-## 📞 支持
-
-遇到问题？
-
-1. 查看 [WORKFLOWS_GUIDE.md Troubleshooting](.github/WORKFLOWS_GUIDE.md#troubleshooting)
-2. 查看 [MULTIPLATFORM_BUILD.md Troubleshooting](.github/MULTIPLATFORM_BUILD.md#troubleshooting)
-3. 检查 Actions 日志获取详细错误信息
-4. 提交 Issue 或讨论
-
---
-
-**完成日期**: 2026-03-04  
-**版本**: 2.0 (多平台支持)  
-**参考**: ClassIsland 项目最佳实践  
-**状态**: ✅ 生产就绪
-
-🎉 **恭喜！LanMontainDesktop 现在拥有完整的多平台 CI/CD 流程！**
--- a/README.md
+++ b/README.md
@@ -1,75 +1,44 @@
 # LanMontainDesktop

-## 项目简介 / Project Overview
-`LanMontainDesktop` 是一个基于 Avalonia 的桌面壳层应用原型，聚焦于网格化桌面布局、毛玻璃视觉、主题色系统与可扩展组件体系。  
-`LanMontainDesktop` is an Avalonia-based desktop shell prototype focused on grid layout, glass visuals, theme system, and extensible components.
+> 你的桌面，不止一面。

-## 主要功能 / Key Features
- 网格化桌面：顶部状态栏 + 底部任务栏（Dock 风格容器）。  
-  Grid-based desktop with top status bar and bottom taskbar (dock-like container).
- 设置中心：壁纸、网格、颜色、状态栏、地区（语言）选项。  
-  Settings center with wallpaper, grid, color, status bar, and region (language) tabs.
- 壁纸系统：支持图片与视频壁纸，并提供设置页预览。  
-  Wallpaper system supporting image/video wallpapers with in-settings preview.
- 主题系统：日夜模式、主题色、Monet 调色联动。  
-  Theme system with day/night mode, accent color, and Monet palette integration.
- 组件系统基础：内置组件注册 + 第三方扩展入口（JSON manifest）。  
-  Component system foundation with built-in registry and third-party JSON extension entry.
+`LanMontainDesktop` 是一个基于 Avalonia 的桌面壳层项目，目标不是“做一个启动器”，而是把桌面变成可编排的信息与交互空间。

-## 技术栈 / Tech Stack
- .NET 10 (`net10.0`)
+## 项目定位
+- 以网格化布局组织桌面组件，支持多页桌面与组件自由摆放。
+- 提供顶部状态栏 + 底部任务栏的桌面框架，强调信息密度与可读性平衡。
+- 通过主题色、日夜模式、玻璃视觉与动画系统，形成统一的视觉语言。
+- 通过组件注册机制与 JSON 扩展入口，让桌面能力可持续扩展。
+
+## 核心能力
+- 桌面组件系统：天气、时钟、计时器、课程表、日历、白板、音乐控制、学习环境等组件可组合使用。
+- 壁纸系统：支持图片与视频壁纸，并可在设置中实时预览。
+- 主题系统：支持日夜模式、主题色与调色联动（Monet 风格色板）。
+- 个性化设置：网格密度、状态栏间距、任务栏布局、语言与时区等可持久化配置。
+- 本地化：内置 `zh-CN` 与 `en-US` 资源。
+
+## 工程结构
+- `LanMontainDesktop/`：桌面端主程序（Avalonia）。
+- `LanMontainDesktop.RecommendationBackend/`：推荐内容后端服务（ASP.NET Core Minimal API）。
+- `docs/`：视觉与圆角等规范文档。
+- `LanMontainDesktop/ComponentSystem/`：组件定义、注册、放置规则与扩展入口。
+
+## 技术栈
+- .NET 10（`net10.0`）
 - Avalonia 11
 - FluentAvalonia + FluentIcons.Avalonia
- LibVLCSharp + VideoLAN.LibVLC.Windows（视频壁纸）
+- LibVLCSharp（用于视频相关能力）
+- WebView.Avalonia（嵌入式网页组件能力）

-## 环境要求 / Prerequisites
- .NET SDK `10.0`
- Windows（当前项目引用 `VideoLAN.LibVLC.Windows`，视频能力以 Windows 为主）  
-  Windows is the primary platform for current video capability due to `VideoLAN.LibVLC.Windows`.
+## 扩展机制（摘要）
+- 组件系统通过 `ComponentRegistry` 合并内置组件与扩展组件。
+- 运行时会扫描 `Extensions/Components/*.json`（相对应用输出目录）加载第三方组件清单。
+- 扩展契约与字段说明见组件系统文档：`LanMontainDesktop/ComponentSystem/README.md`。

-## 快速启动 / Quick Start
-```bash
-dotnet restore
-dotnet build LanMontainDesktop/LanMontainDesktop.csproj
-dotnet run --project LanMontainDesktop/LanMontainDesktop.csproj
-```
-
-## 配置与持久化 / Configuration & Persistence
-应用设置通过 `AppSettingsSnapshot` 持久化到本地：  
-App settings are persisted from `AppSettingsSnapshot` to local storage:
-
- 路径 / Path: `%LOCALAPPDATA%\LanMontainDesktop\settings.json`
-
-核心字段（简表）/ Key fields (summary):
- `GridShortSideCells`: 网格短边格子数 / short-side grid cells
- `IsNightMode`: 日夜模式 / day-night mode
- `ThemeColor`: 主题色 / accent color
- `WallpaperPath` + `WallpaperPlacement`: 壁纸路径与显示模式 / wallpaper path and placement
- `SettingsTabIndex`: 设置页当前选项卡 / active settings tab index
- `LanguageCode`: 语言代码（`zh-CN` / `en-US`）
- `TopStatusComponentIds`: 顶部状态栏组件 ID 列表 / status bar component IDs
- `PinnedTaskbarActions`: 任务栏固定动作 / pinned taskbar actions
-
-## 组件扩展入口 / Component Extension Entry
- 运行时会扫描：`Extensions/Components/*.json`（相对应用输出目录）  
-  Runtime scan target: `Extensions/Components/*.json` (relative to app output).
- 扩展加载器：`JsonComponentExtensionProvider`
- 详细契约与 schema 见：`LanMontainDesktop/ComponentSystem/README.md`
-
-## 国际化 / Localization
- 语言资源文件：  
-  Localization files:
-  - `LanMontainDesktop/Localization/zh-CN.json`
-  - `LanMontainDesktop/Localization/en-US.json`
- 当前支持：简体中文、English
-
-## 已知限制（快速版）/ Known Limitations
- 视频壁纸能力当前以 Windows 运行环境为主。  
-  Video wallpaper support is currently Windows-first.
- `docs/VISUAL_SPEC.md` 存在历史编码问题，本次未纳入修复范围。  
-  `docs/VISUAL_SPEC.md` has historical encoding issues and is not updated in this round.
-
-## 许可证与贡献（占位）/ License & Contributing (Placeholder)
- License: TBD
- Contributing guide: TBD
+## 当前状态
+- 项目包含桌面端与推荐后端两个子项目，并在同一 solution 中维护。
+- 配置默认写入本地：`%LOCALAPPDATA%\LanMontainDesktop\settings.json`。
+- 当前体验以 Windows 为主要目标平台。

+## 运行说明
+运行与环境准备已拆分到独立文档：[`run.md`](./run.md)
--- a/run.md
+++ b/run.md
@@ -0,0 +1,42 @@
+# LanMontainDesktop 运行指南
+
+本文档只负责“怎么跑起来”。项目介绍请看 [README.md](./README.md)。
+
+## 1. 环境准备
+- 安装 .NET SDK 10（`net10.0`）。
+- 建议使用 Windows 运行桌面端（当前桌面体验以 Windows 为主）。
+
+## 2. 拉取依赖并构建
+在仓库根目录执行：
+
+```bash
+dotnet restore
+dotnet build LanMontainDesktop.sln -c Debug
+```
+
+## 3. 运行桌面端
+```bash
+dotnet run --project LanMontainDesktop/LanMontainDesktop.csproj
+```
+
+## 4. 可选：运行推荐后端
+如果你需要每日诗词/名画等推荐能力，可单独启动后端：
+
+```bash
+dotnet run --project LanMontainDesktop.RecommendationBackend/LanMontainDesktop.RecommendationBackend.csproj
+```
+
+后端默认会输出监听地址（通常是 `http://localhost:5xxx` 或 `https://localhost:7xxx`）。
+
+可用健康检查：
+
+```bash
+curl http://localhost:5000/health
+```
+
+说明：端口以你本机启动日志为准，`5000` 仅为示例。
+
+## 5. 常见问题
+- 启动失败提示 SDK 版本不匹配：确认 `dotnet --info` 中已安装 .NET 10 SDK。
+- 桌面端视频相关能力异常：优先在 Windows 环境下验证。
+- 配置重置：删除 `%LOCALAPPDATA%\LanMontainDesktop\settings.json` 后重启应用。