From c42a7d8f2531af021ee8eb4ef9602607d661b453 Mon Sep 17 00:00:00 2001 From: lincube Date: Wed, 4 Mar 2026 13:18:07 +0800 Subject: [PATCH] 0.3.4 --- CICD_EVALUATION.md | 263 --------------------------- MULTIPLATFORM_RELEASE_GUIDE.md | 315 --------------------------------- README.md | 101 ++++------- run.md | 42 +++++ 4 files changed, 77 insertions(+), 644 deletions(-) delete mode 100644 CICD_EVALUATION.md delete mode 100644 MULTIPLATFORM_RELEASE_GUIDE.md create mode 100644 run.md diff --git a/CICD_EVALUATION.md b/CICD_EVALUATION.md deleted file mode 100644 index bee1d31..0000000 --- a/CICD_EVALUATION.md +++ /dev/null @@ -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 -**目标**: 提高代码质量和发布效率 🚀 diff --git a/MULTIPLATFORM_RELEASE_GUIDE.md b/MULTIPLATFORM_RELEASE_GUIDE.md deleted file mode 100644 index 07950ba..0000000 --- a/MULTIPLATFORM_RELEASE_GUIDE.md +++ /dev/null @@ -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 流程！** diff --git a/README.md b/README.md index 70ba971..217509c 100644 --- 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) diff --git a/run.md b/run.md new file mode 100644 index 0000000..1714cd7 --- /dev/null +++ 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` 后重启应用。