From 798124e500e611da06661e1fb1ea9c88e70b6e3a Mon Sep 17 00:00:00 2001 From: lincube Date: Mon, 23 Mar 2026 22:43:54 +0800 Subject: [PATCH] 0.7.6.3 --- AGENTS.md | 91 +++++++++++++ PRODUCT_BRIEF.md | 43 ------- PRODUCT_DOCUMENT.md | 256 ------------------------------------- docs/ARCHITECTURE.md | 76 +++++++++++ docs/CONTRIBUTING.md | 63 +++++++++ docs/DEVELOPMENT.md | 81 ++++++++++++ docs/PRODUCT.md | 62 +++++++++ docs/SPECS.md | 76 +++++++++++ docs/ai/CHANGE_WORKFLOW.md | 60 +++++++++ docs/ai/CODEBASE_MAP.md | 59 +++++++++ docs/ai/DOC_SOURCES.md | 39 ++++++ run.md | 59 --------- 12 files changed, 607 insertions(+), 358 deletions(-) create mode 100644 AGENTS.md delete mode 100644 PRODUCT_BRIEF.md delete mode 100644 PRODUCT_DOCUMENT.md create mode 100644 docs/ARCHITECTURE.md create mode 100644 docs/CONTRIBUTING.md create mode 100644 docs/DEVELOPMENT.md create mode 100644 docs/PRODUCT.md create mode 100644 docs/SPECS.md create mode 100644 docs/ai/CHANGE_WORKFLOW.md create mode 100644 docs/ai/CODEBASE_MAP.md create mode 100644 docs/ai/DOC_SOURCES.md delete mode 100644 run.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..3590dbb --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,91 @@ +# LanMountainDesktop AI Guide + +本文件是 AI 助手进入本仓库时的第一入口。面向 Codex、Cursor、Trae 等工具，目标是减少重复探索，快速定位权威文档、关键目录和执行约束。 + +## 1. 项目目标与仓库边界 + +- 本仓库是阑山桌面桌面宿主、宿主侧插件运行时、Plugin SDK、共享契约与基础外观/设置能力的权威来源。 +- 不要把插件市场元数据、开发者门户或官方示例插件实现当作本仓库内容维护。 +- 市场和生态材料属于兄弟仓库 `LanAirApp`。 +- 官方示例插件属于独立仓库 `LanMountainDesktop.SamplePlugin`。 + +边界详情看： + +- `docs/ECOSYSTEM_BOUNDARIES.md` +- `docs/ARCHITECTURE.md` + +## 2. 关键目录地图 + +- `LanMountainDesktop/`: 主宿主应用，包含 UI、服务、组件系统、主题与插件运行时接入 +- `LanMountainDesktop/ComponentSystem/`: 内置组件定义、注册、扩展加载 +- `LanMountainDesktop/plugins/`: 宿主侧插件运行时、安装与 market 集成 +- `LanMountainDesktop/Views/` and `ViewModels/`: UI 页面、窗口与视图模型 +- `LanMountainDesktop/Services/`: 设置、遥测、启动、持久化、业务服务 +- `LanMountainDesktop.PluginSdk/`: 插件 SDK 公共接口和默认打包行为 +- `LanMountainDesktop.Shared.Contracts/`: 宿主/插件共享契约 +- `LanMountainDesktop.Tests/`: 宿主与 SDK 测试 +- `.trae/specs/`: feature 级规格、任务拆解和验收清单 + +更详细映射看 `docs/ai/CODEBASE_MAP.md`。 + +## 3. 常用命令 + +```bash +dotnet restore +dotnet build LanMountainDesktop.slnx -c Debug +dotnet run --project LanMountainDesktop/LanMountainDesktop.csproj +dotnet test LanMountainDesktop.slnx -c Debug +``` + +插件本地包生成： + +```powershell +./scripts/Pack-PluginPackages.ps1 +``` + +## 4. 改动前后必做检查 + +改动前： + +- 先确认需求是否已经在 `.trae/specs/` 中存在 +- 先确认产品、架构、专题规范分别以哪份文档为准 +- 避免沿用旧根目录产品文档中的过时事实 + +改动后： + +- 至少检查构建和与改动相关的测试 +- 如果行为、流程、边界或命令变化，更新对应文档 +- 如果是新功能或行为调整，补齐或更新 `.trae/specs//` + +## 5. 高频区域注意事项 + +### UI + +- 主题、资源和视觉语义优先遵守 `docs/VISUAL_SPEC.md` 与 `docs/CORNER_RADIUS_SPEC.md` +- 设置页相关改动通常同时落在 `Views/`、`ViewModels/`、`Services/` 和 `.trae/specs/` +- UI 启动与窗口生命周期主线在 `Program.cs` 和 `App.axaml.cs` + +### 插件 + +- SDK 公共 API 以 `LanMountainDesktop.PluginSdk/` 为准 +- 共享契约以 `LanMountainDesktop.Shared.Contracts/` 为准 +- market 数据来源默认是兄弟仓库 `..\\LanAirApp` +- 迁移或 breaking change 优先同步 `docs/PLUGIN_SDK_V4_MIGRATION.md` + +### 设置与主题 + +- 设置持久化和 scope 变化优先检查 `LanMountainDesktop.Settings.Core/` +- 外观、圆角、主题资源优先检查 `LanMountainDesktop.Appearance/` 与专题规范 + +## 6. 权威来源 + +- 产品定位：`docs/PRODUCT.md` +- 架构与模块职责：`docs/ARCHITECTURE.md` +- 运行、构建、测试、打包：`docs/DEVELOPMENT.md` +- feature 规格：`.trae/specs/` +- 视觉规范：`docs/VISUAL_SPEC.md` +- 圆角规范：`docs/CORNER_RADIUS_SPEC.md` +- 生态边界：`docs/ECOSYSTEM_BOUNDARIES.md` +- SDK v4 迁移：`docs/PLUGIN_SDK_V4_MIGRATION.md` + +如果多个文档都提到同一件事，以 `docs/ai/DOC_SOURCES.md` 列出的权威来源为准。 diff --git a/PRODUCT_BRIEF.md b/PRODUCT_BRIEF.md deleted file mode 100644 index 2b67f72..0000000 --- a/PRODUCT_BRIEF.md +++ /dev/null @@ -1,43 +0,0 @@ -# 阑山桌面 产品说明 - -## 1. 目标人群 - -- **学生群体**：大学生、研究生、备考人员 -- **办公用户**：白领、远程工作者 -- **桌面美化爱好者**：追求个性化桌面布局与视觉体验的用户 - -## 2. 使用场景 - -| 场景 | 说明 | -| ---- | ---------------------- | -| 学习辅助 | 查看课程表、记录自习时长、获取每日诗词单词 | -| 办公效率 | 查看日历日程、快速访问最近文档、获取新闻资讯 | -| 信息聚合 | 桌面一站式查看天气、日历、热搜、新闻 | -| 个性美化 | 自由定制桌面组件布局、主题、壁纸 | - -## 3. 解决方案 - -**核心方案**：可编排的桌面组件系统 + 插件扩展生态 - -- **20+ 内置组件**：时钟、天气、日历、新闻、课程表、计时器等 -- **网格化布局**：自由拖拽摆放，支持多页桌面 -- **主题系统**：日夜模式、Monet 取色、玻璃效果 -- **插件市场**：支持第三方插件扩展功能 -- **跨平台**：Windows / Linux / macOS - -## 4. 解决的问题 - -| 痛点 | 解决方案 | -| -------------- | -------------------- | -| 信息分散，需打开多个应用 | 桌面聚合展示天气、日历、新闻等信息 | -| 桌面单调，缺乏个性化 | 丰富的组件和主题自由定制 | -| 学习管理不便 | 课程表、自习监测专为学生设计 | -| 功能单一，需安装多个独立应用 | 一个应用整合考试看板、噪音监测等多种功能 | -| 功能无法满足个性需求 | 插件系统支持无限扩展 | - -## 5. 产品进度 - -- **当前版本**：v0.7.0（插件 API 3.0.0） -- **开发状态**：功能开发中，预计 1\~2 个月内发布 v1.0 正式版 -- **用户统计**：通过 PostHog 收集匿名数据（具体数据需后台查看） - diff --git a/PRODUCT_DOCUMENT.md b/PRODUCT_DOCUMENT.md deleted file mode 100644 index cc2dab5..0000000 --- a/PRODUCT_DOCUMENT.md +++ /dev/null @@ -1,256 +0,0 @@ -# 阑山桌面 (LanMountainDesktop) 产品说明文档 - -**文档版本**: 1.0 -**最后更新**: 2026年3月20日 -**产品版本**: 1.0.0 -**插件 API 基线**: 3.0.0 - ---- - -## 一、产品定位 - -### 1.1 一句话介绍 - -**阑山桌面是一款可编排的桌面信息与交互空间，让用户能够自由定制个性化桌面，整合信息展示与效率工具于一体。** - -### 1.2 核心定位 - -- **产品类型**: 跨平台桌面环境增强工具 -- **技术架构**: 基于 Avalonia UI 的 .NET 跨平台桌面应用 -- **支持平台**: Windows、Linux、macOS -- **开发语言**: C# (.NET 10) - ---- - -## 二、目标用户群体 - -### 2.1 核心用户画像 - -| 用户群体 | 特征描述 | 核心需求 | -|---------|---------|---------| -| **学生群体** | 大学生、研究生、备考人员 | 课程表管理、自习环境监测、学习计时、每日诗词/单词 | -| **办公用户** | 白领、远程工作者、知识工作者 | 日历日程、天气信息、最近文档、资讯获取 | -| **效率爱好者** | 工具控、桌面美化爱好者 | 高度自定义、插件扩展、个性化布局 | -| **中文用户** | 以中文为母语的用户 | 完整的本地化体验、农历/节假日支持 | - -### 2.2 用户场景分析 - -#### 场景一：学生学习桌面 -> 小张是一名大学生，每天需要查看课程表、记录自习时间、查看天气决定穿衣。阑山桌面的课程表组件帮他管理课表，自习监测组件记录学习时长，天气组件提供实时天气信息，让他在学习时无需切换多个应用。 - -#### 场景二：办公效率桌面 -> 李女士是一名产品经理，需要随时查看日程、关注行业资讯、快速访问最近文档。阑山桌面的日历组件展示日程安排，新闻组件聚合央广网/凤凰网资讯，最近文档组件一键打开工作文件，提升工作效率。 - -#### 场景三：个性化展示桌面 -> 小王是一名桌面美化爱好者，喜欢打造独特的桌面环境。阑山桌面提供丰富的组件库和插件系统，支持自定义布局、主题色、壁纸，让他能够打造独一无二的个性化桌面。 - ---- - -## 三、使用场景 - -### 3.1 主要使用场景 - -| 场景 | 描述 | 核心组件 | -|-----|------|---------| -| **学习辅助** | 课程管理、自习监测、学习计时 | 课程表、自习环境监测、计时器、每日诗词/单词 | -| **信息聚合** | 一站式获取天气、新闻、日历信息 | 天气、新闻、日历、热搜 | -| **效率提升** | 快速访问文档、应用启动、工具使用 | 最近文档、应用启动台、汇率换算、浏览器 | -| **桌面美化** | 个性化桌面布局与视觉呈现 | 时钟、天气、每日名画、主题系统 | -| **音乐控制** | 桌面音乐播放控制 | 音乐控制组件 | - -### 3.2 典型使用流程 - -``` -1. 安装阑山桌面 → 2. 选择主题与壁纸 → 3. 添加桌面组件 → 4. 自定义布局 - ↓ - 5. 日常使用（查看信息、使用工具） - ↓ - 6. 按需安装插件扩展功能 -``` - ---- - -## 四、解决方案 - -### 4.1 产品架构 - -``` -┌─────────────────────────────────────────────────────────────┐ -│ 阑山桌面 (LanMountainDesktop) │ -├─────────────────────────────────────────────────────────────┤ -│ 用户界面层 │ 桌面宿主 │ 组件系统 │ 插件系统 │ 设置中心 │ -├─────────────────────────────────────────────────────────────┤ -│ 跨平台运行时 (Avalonia UI + .NET 10) │ -├─────────────────────────────────────────────────────────────┤ -│ Windows │ Linux │ macOS │ -└─────────────────────────────────────────────────────────────┘ -``` - -### 4.2 核心功能模块 - -#### 4.2.1 桌面组件系统 -阑山桌面提供丰富的内置组件，涵盖多个类别： - -| 类别 | 组件列表 | -|-----|---------| -| **时钟类** | 桌面时钟、世界时钟、天气时钟、模拟时钟 | -| **天气类** | 天气组件、小时天气、多日天气、扩展天气 | -| **日历类** | 月历、农历、节假日日历 | -| **信息类** | 每日诗词、每日名画、每日单词、央广网新闻、凤凰网新闻、B站热搜、百度热搜 | -| **学习类** | 课程表、自习环境监测、录音、自习时段控制、历史数据 | -| **工具类** | 计时器、汇率换算、浏览器、最近文档、可移动存储、音乐控制 | -| **白板类** | 竖向小黑板、横向小黑板 | - -#### 4.2.2 插件扩展系统 -- **插件 API 基线**: 3.0.0 -- **插件格式**: `.laapp` 插件包 -- **插件市场**: 官方插件市场 (LanAirApp) -- **开发支持**: 完整的 PluginSdk 和开发文档 - -#### 4.2.3 主题与个性化 -- **主题系统**: 支持日夜模式切换 -- **主题色**: 支持 Monet 取色和自定义主题色 -- **玻璃效果**: 多层级玻璃视觉效果 -- **壁纸系统**: 支持图片壁纸和动态效果 - -#### 4.2.4 布局系统 -- **网格化布局**: 支持多页桌面 -- **自由拖拽**: 组件可自由摆放 -- **尺寸自适应**: 组件支持多种尺寸规格 - -### 4.3 技术亮点 - -| 特性 | 说明 | -|-----|------| -| **跨平台** | 基于 Avalonia UI，支持 Windows/Linux/macOS | -| **现代化 UI** | Fluent Design + Material Design 融合 | -| **插件化架构** | 支持第三方插件扩展，API 基线 3.0.0 | -| **数据安全** | 本地 SQLite 存储，隐私数据不上传 | -| **性能优化** | 组件懒加载、资源按需加载 | -| **无障碍支持** | 对比度优化、语义化界面 | - ---- - -## 五、解决的问题 - -### 5.1 用户痛点 - -| 痛点 | 阑山桌面解决方案 | -|-----|----------------| -| **信息分散** | 整合天气、日历、新闻等信息于桌面 | -| **桌面单调** | 丰富的组件和主题让桌面个性化 | -| **效率低下** | 常用工具和信息一触即达 | -| **学习管理难** | 课程表、自习监测专为学生设计 | -| **功能不足** | 插件系统支持无限扩展 | - -### 5.2 竞品差异化 - -| 对比维度 | 传统桌面工具 | 阑山桌面 | -|---------|-------------|---------| -| **组件丰富度** | 有限组件 | 20+ 内置组件 + 插件扩展 | -| **定制化** | 固定布局 | 自由拖拽、网格化布局 | -| **跨平台** | 单一平台 | Windows/Linux/macOS | -| **插件生态** | 不支持 | 完整插件 SDK 和市场 | -| **本地化** | 一般 | 完整中文本地化 | - ---- - -## 六、用户量与数据统计 - -### 6.1 数据收集说明 - -根据隐私政策，阑山桌面收集以下匿名数据用于统计： - -- ✅ **应用启动事件**: 用于统计日活跃用户 -- ✅ **设备标识符**: 匿名生成，用于区分用户（不含个人信息） -- ✅ **应用版本**: 用于统计版本分布 -- ✅ **崩溃报告**: 用于提升应用稳定性（可选） -- ✅ **使用统计**: 用于功能优化（可选） - -### 6.2 隐私承诺 - -- ❌ 不收集个人身份信息（姓名、邮箱、电话等） -- ❌ 不收集地理位置 -- ❌ 不收集文件内容 -- ❌ 不出售用户数据 -- ❌ 不用于广告目的 - -### 6.3 当前状态 - -**当前版本**: 1.0.0 -**插件 API 基线**: 3.0.0 -**数据收集服务**: PostHog（用户分析）、Sentry（崩溃报告） - -> **注**: 具体用户量数据需从 PostHog 后台获取，此处未展示具体数字。 - ---- - -## 七、产品开发进度 - -### 7.1 当前开发状态 - -| 模块 | 状态 | 说明 | -|-----|------|------| -| **核心桌面功能** | ✅ 已完成 | 网格布局、组件系统、主题系统 | -| **内置组件** | ✅ 已完成 | 20+ 组件已上线 | -| **插件系统** | ✅ 已完成 | API 3.0.0 已稳定 | -| **插件市场** | ✅ 已完成 | 官方市场已运营 | -| **多平台支持** | ✅ 已完成 | Windows/Linux/macOS | -| **自动更新** | ✅ 已完成 | 内置更新系统 | -| **应用启动台** | ✅ 已完成 | Windows 开始菜单集成 | - -### 7.2 版本里程碑 - -| 版本 | 目标 | 状态 | -|-----|------|------| -| v1.0.0 | 核心功能完整、插件系统稳定 | ✅ 已发布 | -| v1.x.x | 组件扩展、性能优化 | 🔄 进行中 | -| v2.0.0 | 重大功能升级（规划中） | 📋 规划中 | - -### 7.3 近期开发计划 - -根据 `.trae/specs` 中的规格文档，近期开发任务包括： - -1. **设置页面 Fluent 重设计** - 提升设置界面体验 -2. **课程表功能增强** - 增加更多课程管理功能 -3. **视频壁纸功能移除** - 优化产品定位 - -### 7.4 生态建设 - -| 项目 | 状态 | 说明 | -|-----|------|------| -| **LanMountainDesktop** | ✅ 主仓库 | 桌面宿主、插件运行时 | -| **LanAirApp** | ✅ 独立仓库 | 插件市场、开发文档 | -| **SamplePlugin** | ✅ 独立仓库 | 权威示例插件 | -| **PluginSdk** | ✅ 已发布 | 插件开发 SDK | - ---- - -## 八、产品优势总结 - -### 8.1 核心价值 - -1. **个性化桌面**: 自由定制组件布局，打造专属桌面空间 -2. **信息聚合**: 一站式获取天气、日历、新闻等实用信息 -3. **效率提升**: 常用工具触手可及，减少应用切换 -4. **学习辅助**: 专为学生群体设计的课程表、自习监测功能 -5. **无限扩展**: 插件系统支持功能无限扩展 - -### 8.2 技术保障 - -- 跨平台架构，一次开发多端运行 -- 现代化 UI 框架，流畅的用户体验 -- 严格的隐私保护，数据安全有保障 -- 完善的插件生态，功能持续扩展 - ---- - -## 九、联系我们 - -- **GitHub**: https://github.com/wwiinnddyy/LanMountainDesktop -- **Issues**: https://github.com/wwiinnddyy/LanMountainDesktop/issues -- **插件市场**: LanAirApp 官方市场 - ---- - -**阑山桌面，让你的桌面更有温度。** diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..4faad7c --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,76 @@ +# 架构文档 / Architecture + +## 中文 + +### 仓库结构 + +| 路径 | 角色 | +| --- | --- | +| `LanMountainDesktop/` | 主桌面宿主应用，包含 UI、服务、组件系统、插件运行时接入 | +| `LanMountainDesktop.PluginSdk/` | 官方插件 SDK，定义插件可依赖的公开接口与打包行为 | +| `LanMountainDesktop.Shared.Contracts/` | 宿主与插件共享的稳定契约类型 | +| `LanMountainDesktop.Appearance/` | 主题、圆角、外观资源相关基础设施 | +| `LanMountainDesktop.Settings.Core/` | 设置域、持久化和设置基础抽象 | +| `LanMountainDesktop.DesktopHost/` | 桌面宿主流程与生命周期相关逻辑 | +| `LanMountainDesktop.DesktopComponents.Runtime/` | 组件运行时支撑能力 | +| `LanMountainDesktop.Host.Abstractions/` | 宿主侧抽象接口 | +| `LanMountainDesktop.PluginsInstallHelper/` | 插件安装辅助程序与发布输出配套 | +| `LanMountainDesktop.PluginTemplate/` | `dotnet new lmd-plugin` 官方模板 | +| `LanMountainDesktop.Tests/` | 宿主与 SDK 的测试项目 | + +### 宿主启动主线 + +启动入口在 `LanMountainDesktop/Program.cs`： + +1. 初始化日志、单实例锁和启动诊断 +2. 初始化遥测身份、崩溃遥测与使用遥测 +3. 构建 Avalonia `AppBuilder` +4. 进入 `LanMountainDesktop/App.axaml.cs` +5. 初始化主题、语言、设置窗口服务、天气定位刷新 +6. 初始化桌面壳层、主窗口、托盘、插件运行时 + +### 运行时主数据流 + +- 设置流：`Settings.Core` 提供基础设置能力，宿主通过 facade 读取和监听设置变化 +- 外观流：`Appearance` 提供主题和圆角资源，宿主在 `App.axaml.cs` 中应用到资源字典 +- 组件流：`LanMountainDesktop/ComponentSystem/` 维护内置组件定义、注册和扩展接入 +- 插件流：宿主侧 `plugins/` 负责 `.laapp` 的发现、安装、替换、激活与共享契约装配 +- 设置页流：插件运行时可把自己的设置页注册进宿主设置窗口 + +### 关键目录落点 + +`LanMountainDesktop/` 内高频目录： + +- `Views/`：窗口、页面、组件视图 +- `ViewModels/`：视图模型 +- `Services/`：业务服务、持久化、启动、遥测等 +- `ComponentSystem/`：组件定义、注册、扩展加载 +- `plugins/`：宿主侧插件运行时 +- `Theme/` 与 `Styles/`：主题资源、样式、外观应用 +- `DesktopEditing/`：桌面布局编辑相关逻辑 +- `Localization/`：本地化资源 + +### 插件边界 + +- 插件 SDK 权威定义在 `LanMountainDesktop.PluginSdk/` +- 宿主与插件共享的稳定通信类型在 `LanMountainDesktop.Shared.Contracts/` +- 插件市场和开发者生态资料不在本仓库维护 +- 本地 market 调试从兄弟仓库 `..\\LanAirApp` 读取数据 + +### 测试边界 + +`LanMountainDesktop.Tests/` 当前主要覆盖： + +- 圆角与外观相关基线 +- 组件放置与编辑数学 +- 组件设置服务 +- UI 异常防护 +- 白板笔记持久化 + +涉及宿主行为、SDK 契约、布局计算或设置持久化的改动，应优先补对应测试。 + +## English + +This repository is organized around a desktop host app plus a host-side plugin ecosystem. `LanMountainDesktop/` contains the application entry points, UI, services, component system, and plugin runtime integration. The surrounding projects provide the public SDK, shared contracts, appearance infrastructure, settings primitives, host abstractions, runtime support, and tests. + +The runtime flow starts in `Program.cs`, proceeds into `App.axaml.cs`, initializes settings/theme/localization services, then boots the desktop shell, tray, windows, and plugin runtime. The most important behavior boundaries are component registration, plugin activation, appearance resources, and settings persistence. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..0ddf3df --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,63 @@ +# 协作文档 / Contributing + +## 中文 + +### 适用范围 + +本文件适用于本仓库内的代码、文档、规格与测试协作。 + +### 基本流程 + +1. 先阅读 `README.md`、`docs/ARCHITECTURE.md` 和 `docs/DEVELOPMENT.md` +2. 如果是新功能、行为变更或跨模块调整，先检查是否需要补 `.trae/specs/` +3. 实现代码改动时，尽量同时补测试和必要文档 +4. 提交 PR 前，至少确认构建、测试和相关文档链接可用 + +### 什么时候必须更新 spec + +以下改动默认要补或更新 `.trae/specs//`： + +- 新增用户可见功能 +- 修改已有功能行为、交互或规则 +- 调整设置页信息架构或主要视觉结构 +- 修改插件宿主集成方式、共享契约或 SDK 使用模式 + +如果只是小范围重构、纯修复拼写、或不改变行为的内部清理，可以不新增 spec，但仍要补必要测试。 + +### 什么时候必须更新文档 + +- 产品定位、版本阶段、生态边界变化：更新 `docs/PRODUCT.md` +- 仓库结构、模块职责、运行时边界变化：更新 `docs/ARCHITECTURE.md` +- 构建、运行、测试、打包步骤变化：更新 `docs/DEVELOPMENT.md` +- AI 协作入口、代码地图、执行约束变化：更新 `AGENTS.md` 或 `docs/ai/` +- 视觉或圆角规则变化：更新对应专题文档 + +### PR 预期 + +PR 说明至少要覆盖： + +- 改了什么 +- 为什么要改 +- 如何验证 +- 是否影响文档、spec 或迁移说明 + +如果改动涉及 UI、插件、设置页、打包或共享契约，建议明确列出受影响区域。 + +### 测试预期 + +默认至少执行与改动相关的验证： + +- `dotnet build LanMountainDesktop.slnx -c Debug` +- `dotnet test LanMountainDesktop.slnx -c Debug` + +无法运行的检查要在 PR 里说明原因。 + +### 文档原则 + +- 每类事实只保留一个权威来源 +- 根目录 `README.md` 面向人类入口，`AGENTS.md` 面向 AI 入口 +- 不要在多个文件里复制同一段说明，只保留索引和跳转 + +## English + +Keep the documentation model simple: `README.md` is the human entry point, `AGENTS.md` is the AI entry point, `docs/` stores durable project docs, and `.trae/specs/` stores feature-level specs. If a change affects behavior, boundaries, or workflows, update the corresponding source-of-truth document in the same PR. diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md new file mode 100644 index 0000000..7686f86 --- /dev/null +++ b/docs/DEVELOPMENT.md @@ -0,0 +1,81 @@ +# 开发文档 / Development + +## 中文 + +### 环境准备 + +- 安装 `.NET SDK 10` +- 桌面端建议优先在 Windows 上开发和验证 +- 仓库主入口解决方案文件为 `LanMountainDesktop.slnx` +- SDK 版本由仓库根目录 `global.json` 锁定 + +### 常用命令 + +#### 还原与构建 + +```bash +dotnet restore +dotnet build LanMountainDesktop.slnx -c Debug +``` + +#### 运行桌面宿主 + +```bash +dotnet run --project LanMountainDesktop/LanMountainDesktop.csproj +``` + +#### 运行测试 + +```bash +dotnet test LanMountainDesktop.slnx -c Debug +``` + +### 常见工作区域 + +- 宿主应用：`LanMountainDesktop/` +- Plugin SDK：`LanMountainDesktop.PluginSdk/` +- 共享契约：`LanMountainDesktop.Shared.Contracts/` +- 测试：`LanMountainDesktop.Tests/` +- 插件打包脚本：`scripts/Pack-PluginPackages.ps1` + +### 调试建议 + +- 启动问题优先看 `LanMountainDesktop/Program.cs` 和 `LanMountainDesktop/App.axaml.cs` +- 设置窗口和设置页问题优先看 `LanMountainDesktop/Views/`、`ViewModels/` 与相关 `Services/` +- 插件加载与安装问题优先看 `LanMountainDesktop/plugins/` +- 组件元数据或可放置规则问题优先看 `LanMountainDesktop/ComponentSystem/` + +### 常见问题 + +- 如果提示 SDK 版本不匹配，先检查 `dotnet --info` +- 如果视频或 WebView 能力异常，优先在 Windows 环境验证 +- 如果需要重置本地配置，可删除 `%LOCALAPPDATA%\\LanMountainDesktop\\settings.json` 后重启 +- 如果需要验证插件打包或本地 feed，使用 `scripts/Pack-PluginPackages.ps1` + +### 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` + +### 打包入口 + +- 桌面宿主打包说明：`LanMountainDesktop/PACKAGING.md` +- 插件相关本地包生成：`scripts/Pack-PluginPackages.ps1` +- CI 和工作流说明：`.github/README.md` 与相关 workflow 文档 + +### 文档协作约定 + +- 产品信息更新到 `docs/PRODUCT.md` +- 架构边界更新到 `docs/ARCHITECTURE.md` +- 需求与实施拆解更新到 `.trae/specs/` +- AI 协作入口和代码地图更新到 `AGENTS.md` 与 `docs/ai/` + +## English + +Use `LanMountainDesktop.slnx` as the workspace entry point. The standard loop is `dotnet restore`, `dotnet build LanMountainDesktop.slnx -c Debug`, `dotnet run --project LanMountainDesktop/LanMountainDesktop.csproj`, and `dotnet test LanMountainDesktop.slnx -c Debug`. + +For packaging, see `LanMountainDesktop/PACKAGING.md`. For plugin package generation or local feed workflows, use `scripts/Pack-PluginPackages.ps1`. diff --git a/docs/PRODUCT.md b/docs/PRODUCT.md new file mode 100644 index 0000000..58828d6 --- /dev/null +++ b/docs/PRODUCT.md @@ -0,0 +1,62 @@ +# 产品文档 / Product + +## 中文 + +### 产品一句话 + +阑山桌面是一个可编排的桌面信息与交互空间，面向需要高频查看信息、追求桌面效率与个性化体验的用户。 + +### 产品定位 + +- 产品类型：跨平台桌面环境增强工具 +- 技术基线：Avalonia UI + .NET 10 +- 支持平台：Windows、Linux、macOS +- 仓库角色：本仓库是桌面宿主、插件运行时、Plugin SDK 与共享契约的权威来源 + +### 目标用户 + +- 学生用户：课程表、自习监测、计时、天气和日常信息聚合 +- 办公用户：日历、资讯、最近文档、常用工具入口 +- 效率和美化爱好者：自由布局、主题切换、插件扩展 +- 中文用户：本地化界面、农历和节假日等本地语境支持 + +### 核心使用场景 + +- 学习辅助：课程表、自习环境监测、计时与知识卡片 +- 信息聚合：天气、新闻、日历、热搜等信息集中展示 +- 效率提升：最近文档、浏览器、工具组件与桌面快捷访问 +- 个性化桌面：自由布局、多页桌面、主题与视觉风格配置 +- 插件扩展：通过 `.laapp` 插件补充新的组件、设置页和集成功能 + +### 核心能力 + +- 桌面组件系统：内置组件与扩展组件统一注册、统一放置约束 +- 插件系统：宿主加载插件、整合设置页、组件与市场安装流 +- 外观系统：主题、玻璃层级、圆角与颜色资源统一管理 +- 设置系统：独立设置窗口、设置页注册与分域持久化 +- 跨平台运行：基于 Avalonia 的桌面宿主运行在 Windows、Linux、macOS + +### 当前阶段 + +- 产品版本：`1.0.0` +- Plugin SDK API 基线：`4.0.0` +- 当前重点：持续完善宿主体验、设置页体验、组件能力与插件生态 +- 近期需求入口：以 `.trae/specs/` 中的 feature spec 为准 + +### 生态边界 + +- 本仓库负责：宿主代码、插件运行时、SDK、共享契约、主题与设置基础设施 +- `LanAirApp` 负责：插件市场元数据、开发者生态材料 +- `LanMountainDesktop.SamplePlugin` 负责：官方示例插件实现 + +### 维护原则 + +- 产品事实只在本文件沉淀，不在多个根目录文档重复维护 +- 代码结构和运行方式分别以 `docs/ARCHITECTURE.md` 与 `docs/DEVELOPMENT.md` 为准 +- 专题规范以 `docs/VISUAL_SPEC.md`、`docs/CORNER_RADIUS_SPEC.md` 等专题文档为准 + +## English + +LanMountainDesktop is a cross-platform desktop enhancement product built with Avalonia UI and .NET 10. It targets students, office users, and customization-focused users who want a programmable desktop surface for information, tools, and plugin-driven extensions. + +This repository is the source of truth for the desktop host, plugin runtime, Plugin SDK, shared contracts, and core appearance/settings infrastructure. The current product version is `1.0.0`, and the active Plugin SDK baseline in this repository is `4.0.0`. diff --git a/docs/SPECS.md b/docs/SPECS.md new file mode 100644 index 0000000..10e2ed0 --- /dev/null +++ b/docs/SPECS.md @@ -0,0 +1,76 @@ +# 规格文档说明 / Specs + +## 中文 + +### 目的 + +`.trae/specs/` 用来存放“一个需求从意图到落地”的协作文档，而不是长期产品说明。它适合记录功能变更、交互改造、重要修复和跨模块调整。 + +### 目录结构 + +每个功能目录建议使用： + +```text +.trae/specs// + spec.md + tasks.md + checklist.md +``` + +### 每个文件的职责 + +#### `spec.md` + +用于描述这次变更的意图和行为要求，建议包含： + +- `Why`：为什么要做 +- `What Changes`：会改什么 +- `Impact`：影响哪些规范或代码区域 +- Requirements / Scenarios：可验证的行为要求 + +#### `tasks.md` + +用于把实现拆成可执行任务，建议包含： + +- 分阶段任务或模块任务 +- 依赖关系 +- 可并行项 +- 完成状态 + +#### `checklist.md` + +用于验收与回归检查，建议包含： + +- 关键 UI 或行为检查点 +- 构建、运行、测试检查点 +- 手工验证项 + +### 什么时候新建 spec + +- 新增功能 +- 已有功能行为发生变化 +- 设置页、主界面、组件系统出现结构性调整 +- 插件系统、共享契约、SDK 接入方式发生变化 + +### 什么时候只更新现有 spec + +- 同一 feature 的后续迭代仍属于原目标范围 +- 原 spec 仍是当前实现的权威描述 +- 只是补充场景、任务拆解或验收项 + +### 什么时候可以不写 spec + +- 纯拼写修复 +- 纯内部重构且不改变行为 +- 只改注释、日志、文档索引等非行为项 + +### 与其他文档的关系 + +- 长期产品说明看 `docs/PRODUCT.md` +- 长期架构说明看 `docs/ARCHITECTURE.md` +- 开发运行方式看 `docs/DEVELOPMENT.md` +- feature 级变更过程看 `.trae/specs/` + +## English + +Use `.trae/specs/` for feature-level change tracking, not for long-lived product or architecture documentation. `spec.md` defines intent and requirements, `tasks.md` breaks implementation into actionable work, and `checklist.md` captures validation and regression checks. diff --git a/docs/ai/CHANGE_WORKFLOW.md b/docs/ai/CHANGE_WORKFLOW.md new file mode 100644 index 0000000..298dac0 --- /dev/null +++ b/docs/ai/CHANGE_WORKFLOW.md @@ -0,0 +1,60 @@ +# Change Workflow + +## 目标 + +给 AI 一个稳定的执行顺序，避免直接跳到编码而漏掉规格、文档和回归验证。 + +## 推荐流程 + +1. 读取 `AGENTS.md` +2. 读取 `docs/ai/DOC_SOURCES.md`，确认这次需求涉及哪些权威文档 +3. 按需读取 `docs/ARCHITECTURE.md`、专题规范和相关目录内 README +4. 检查 `.trae/specs/` 是否已有对应 feature +5. 如果是新功能或行为变化，先补或更新 `spec.md / tasks.md / checklist.md` +6. 再改代码 +7. 补测试或复用已有测试文件 +8. 运行最小必要验证 +9. 回写文档入口和迁移说明 + +## 什么时候必须先更新 `.trae/specs/` + +- 用户可见行为变化 +- 设置页或主界面结构变化 +- 组件系统规则变化 +- 插件宿主集成、共享契约、SDK 使用模式变化 + +## 什么时候可以直接改代码 + +- 纯文档修复 +- 不改变行为的内部重构 +- 小范围 bugfix 且现有 spec 已完整覆盖该功能意图 + +## 最小验证清单 + +默认优先： + +```bash +dotnet build LanMountainDesktop.slnx -c Debug +dotnet test LanMountainDesktop.slnx -c Debug +``` + +按需增加： + +- 运行桌面宿主验证 UI 或启动行为 +- 检查插件打包或 market 调试路径 +- 手工验证设置页、主题切换、组件布局等高风险交互 + +## 回写要求 + +出现以下变化时，AI 应同步回写文档： + +- 命令变化：更新 `docs/DEVELOPMENT.md` +- 模块职责变化：更新 `docs/ARCHITECTURE.md` +- 产品定位或阶段变化：更新 `docs/PRODUCT.md` +- AI 入口或权威来源变化：更新 `AGENTS.md` 或 `docs/ai/DOC_SOURCES.md` + +## 不要做的事 + +- 不要把根目录 `README.md` 写成 feature 详细设计文档 +- 不要在多份文档里重复维护同一条事实 +- 不要把 `LanAirApp` 的资料误写成本仓库权威来源 diff --git a/docs/ai/CODEBASE_MAP.md b/docs/ai/CODEBASE_MAP.md new file mode 100644 index 0000000..8474d07 --- /dev/null +++ b/docs/ai/CODEBASE_MAP.md @@ -0,0 +1,59 @@ +# Codebase Map + +## 目标 + +本文件帮助 AI 在最短时间内定位“需求应该落到哪一层”，减少把改动打到错误项目或错误目录的概率。 + +## 顶层项目地图 + +| 路径 | 主要职责 | 典型改动 | +| --- | --- | --- | +| `LanMountainDesktop/` | 桌面宿主应用 | UI、服务、主流程、组件系统、插件接入 | +| `LanMountainDesktop.PluginSdk/` | 插件 SDK | 公共接口、扩展方法、默认打包行为 | +| `LanMountainDesktop.Shared.Contracts/` | 共享契约 | 宿主与插件共享记录、模型、边界类型 | +| `LanMountainDesktop.Appearance/` | 外观基础设施 | 主题、圆角、外观资源相关逻辑 | +| `LanMountainDesktop.Settings.Core/` | 设置基础设施 | 设置 scope、存储抽象、设置 facade 支撑 | +| `LanMountainDesktop.DesktopHost/` | 桌面宿主流程 | 生命周期、宿主流程支撑 | +| `LanMountainDesktop.DesktopComponents.Runtime/` | 组件运行时 | 组件宿主运行时支撑 | +| `LanMountainDesktop.Host.Abstractions/` | 宿主抽象 | 宿主接口与抽象层 | +| `LanMountainDesktop.PluginsInstallHelper/` | 插件安装辅助 | 发布输出和插件安装辅助程序 | +| `LanMountainDesktop.PluginTemplate/` | 插件模板 | `dotnet new lmd-plugin` 模板内容 | +| `LanMountainDesktop.Tests/` | 测试 | 行为回归、契约验证、基础能力校验 | + +## 主宿主工程内的高频落点 + +| 路径 | 用途 | 常见需求 | +| --- | --- | --- | +| `LanMountainDesktop/Program.cs` | 进程启动主线 | 启动诊断、单实例、启动配置 | +| `LanMountainDesktop/App.axaml.cs` | 应用初始化 | 主题、语言、托盘、插件运行时、主窗口 | +| `LanMountainDesktop/Views/` | 界面视图 | 设置页、主窗口、组件 UI | +| `LanMountainDesktop/ViewModels/` | 视图模型 | 页面状态、命令、交互行为 | +| `LanMountainDesktop/Services/` | 服务层 | 设置、存储、遥测、业务能力 | +| `LanMountainDesktop/ComponentSystem/` | 组件系统 | 组件定义、注册、放置规则、扩展清单 | +| `LanMountainDesktop/plugins/` | 插件运行时 | 插件发现、安装、替换、market 集成 | +| `LanMountainDesktop/Theme/` and `Styles/` | 主题和样式 | 视觉资源、主题行为、样式规则 | +| `LanMountainDesktop/Localization/` | 本地化 | 语言资源、语言切换 | +| `LanMountainDesktop/DesktopEditing/` | 布局编辑 | 组件摆放、数学计算、编辑状态 | + +## 需求到目录的快速映射 + +- 设置页改造：优先看 `Views/`, `ViewModels/`, `Services/`, `.trae/specs/` +- 组件注册或元数据变化：优先看 `ComponentSystem/` +- 插件安装、market、插件加载：优先看 `plugins/` +- 主题、颜色、圆角：优先看 `Theme/`, `Styles/`, `LanMountainDesktop.Appearance/` +- 设置持久化：优先看 `LanMountainDesktop.Settings.Core/` 与宿主设置 facade +- SDK 接口调整：优先看 `LanMountainDesktop.PluginSdk/` 和 `LanMountainDesktop.Shared.Contracts/` +- 桌面壳层或生命周期：优先看 `Program.cs`, `App.axaml.cs`, `LanMountainDesktop.DesktopHost/` + +## 测试对照 + +当前测试工程 `LanMountainDesktop.Tests/` 内的典型覆盖包括： + +- `CornerRadiusScaleTests.cs`: 圆角和外观缩放相关 +- `DesktopPlacementMathTests.cs`: 桌面布局数学 +- `DesktopEditCommitMathTests.cs`: 桌面编辑提交计算 +- `ComponentSettingsServiceTests.cs`: 组件设置服务 +- `UiExceptionGuardTests.cs`: UI 异常保护 +- `WhiteboardNotePersistenceServiceTests.cs`: 白板笔记持久化 + +如果改动落在这些行为附近，优先扩展已有测试而不是新建无关测试入口。 diff --git a/docs/ai/DOC_SOURCES.md b/docs/ai/DOC_SOURCES.md new file mode 100644 index 0000000..46b48d8 --- /dev/null +++ b/docs/ai/DOC_SOURCES.md @@ -0,0 +1,39 @@ +# Documentation Sources + +## 目标 + +当多个文档都提到同一主题时，AI 必须知道“到底信哪一份”。本文件定义权威来源，避免引用旧文档或重复维护的文本。 + +## 权威来源表 + +| 主题 | 权威文档 | 备注 | +| --- | --- | --- | +| 项目总入口 | `README.md` | 面向人类，提供索引而不展开细节 | +| AI 协作入口 | `AGENTS.md` | 面向 AI 的首读文件 | +| 产品定位与阶段 | `docs/PRODUCT.md` | 不再使用旧根目录产品文档 | +| 架构与模块职责 | `docs/ARCHITECTURE.md` | 包含仓库结构和运行时主线 | +| 构建、运行、测试、打包 | `docs/DEVELOPMENT.md` | 命令以这里为准 | +| 贡献和文档更新规则 | `docs/CONTRIBUTING.md` | PR、spec、文档协作规则 | +| feature 级规格 | `.trae/specs//spec.md` | 行为意图和需求场景 | +| feature 任务拆解 | `.trae/specs//tasks.md` | 实施步骤与依赖 | +| feature 验收 | `.trae/specs//checklist.md` | 回归与验收项 | +| 视觉规范 | `docs/VISUAL_SPEC.md` | 颜色、语义资源、玻璃层级 | +| 圆角规范 | `docs/CORNER_RADIUS_SPEC.md` | 圆角层级与动态规则 | +| 插件生态边界 | `docs/ECOSYSTEM_BOUNDARIES.md` | 仓库边界和 market 所属 | +| SDK v4 迁移 | `docs/PLUGIN_SDK_V4_MIGRATION.md` | Plugin SDK breaking changes | + +## 已废弃来源 + +以下文件内容已迁移，不应继续作为权威来源引用： + +- `PRODUCT_BRIEF.md` +- `PRODUCT_DOCUMENT.md` +- `run.md` + +## 冲突处理规则 + +如果发现多个文档内容冲突，按以下优先级处理： + +1. 先看本表中的权威来源 +2. 再看相关项目内源码、`csproj`、目录 README +3. 如果仍有冲突，以当前仓库源码和项目配置为准，并回写文档 diff --git a/run.md b/run.md deleted file mode 100644 index a2c3c3b..0000000 --- a/run.md +++ /dev/null @@ -1,59 +0,0 @@ -# 运行指南 - -## 中文 - -本文档只说明如何在本地运行阑山桌面。 - -### 环境准备 - -- 安装 .NET SDK 10。 -- 桌面端建议在 Windows 上运行。 -- 仓库主入口解决方案文件为 `LanMountainDesktop.slnx`。 -- SDK 版本由仓库根目录 `global.json` 锁定。 - -### 构建 - -```bash -dotnet restore -dotnet build LanMountainDesktop.slnx -c Debug -``` - -### 运行桌面端 - -```bash -dotnet run --project LanMountainDesktop/LanMountainDesktop.csproj -``` - -### 常见问题 - -- 如果提示 SDK 版本不匹配，先检查 `dotnet --info`。 -- 如果视频能力异常，优先在 Windows 环境验证。 -- 如果要重置配置，可删除 `%LOCALAPPDATA%\LanMountainDesktop\settings.json` 后重启。 - -### 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. - -The repository entry solution is `LanMountainDesktop.slnx`, and the SDK version is pinned by the root `global.json`. - -### Build - -```bash -dotnet restore -dotnet build LanMountainDesktop.slnx -c Debug -``` - -### Run - -```bash -dotnet run --project LanMountainDesktop/LanMountainDesktop.csproj -```