mirror of
https://github.com/wwiinnddyy/LanMountainDesktop.git
synced 2026-06-20 23:54:26 +08:00
93d6d93815
Upgrade project to the Avalonia 12 baseline and Plugin SDK v5: centralize Avalonia packages, remove legacy WebView.Avalonia usage (use NativeWebView/WebView2 EnvironmentRequested), and update Fluent/Material icon/package usages. Bump multiple package/project versions to 5.0.0 and Avalonia 12.0.1, update plugin template and README/docs to SDK v5, and add PLUGIN_SDK_V5_MIGRATION.md. Also fix runtime/behavior bugs: make DataLocationResolver use a fixed bootstrap launcher data path and avoid recursive ResolveDataRoot; add legacy-state handling and extraction in OobeStateService; and update component settings tests to reflect migrated storage (DB/backup) and reset cache for test reloads. Various csproj, tests, and docs updated to reflect the migration and ensure build/test compatibility.
97 lines
4.1 KiB
Markdown
97 lines
4.1 KiB
Markdown
# 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/<feature>/`
|
||
|
||
## 5. 高频区域注意事项
|
||
|
||
### UI
|
||
|
||
- 主题、资源和视觉语义优先遵守 `docs/VISUAL_SPEC.md` 与 `docs/CORNER_RADIUS_SPEC.md`
|
||
- **圆角规范 (AI 强制建议)**：
|
||
- **桌面组件根容器**：必须且仅能使用 `{DynamicResource DesignCornerRadiusComponent}`。
|
||
- **内部元素**：必须根据嵌套层级使用 `DesignCornerRadiusSm/Md/Lg` 等 Token，严禁硬编码像素值。
|
||
- **禁止修改系数**：严禁在圆角资源上乘以任何 `scale` 变量，圆角现在由全局样式固定控制。
|
||
- 设置页相关改动通常同时落在 `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_V5_MIGRATION.md`
|
||
|
||
### 设置与主题
|
||
|
||
- 设置持久化和 scope 变化优先检查 `LanMountainDesktop.Settings.Core/`
|
||
- 外观、圆角、主题资源优先检查 `LanMountainDesktop.Appearance/` 与专题规范
|
||
- **圆角统一**：桌面组件（Widget）必须统一使用动态资源 `DesignCornerRadiusComponent`。严禁在组件根容器使用硬编码数值或非组件级令牌（如 `Xs`, `Md` 等），以确保全局圆角缩放设置能正确应用到所有组件。
|
||
|
||
## 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 v5 迁移：`docs/PLUGIN_SDK_V5_MIGRATION.md`
|
||
|
||
如果多个文档都提到同一件事，以 `docs/ai/DOC_SOURCES.md` 列出的权威来源为准。
|