2026-03-23 22:43:54 +08:00
|
|
|
|
# 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`
|
2026-04-08 00:55:10 +08:00
|
|
|
|
- **圆角规范 (AI 强制建议)**：
|
|
|
|
|
|
- **桌面组件根容器**：必须且仅能使用 `{DynamicResource DesignCornerRadiusComponent}`。
|
|
|
|
|
|
- **内部元素**：必须根据嵌套层级使用 `DesignCornerRadiusSm/Md/Lg` 等 Token，严禁硬编码像素值。
|
|
|
|
|
|
- **禁止修改系数**：严禁在圆角资源上乘以任何 `scale` 变量，圆角现在由全局样式固定控制。
|
2026-03-23 22:43:54 +08:00
|
|
|
|
- 设置页相关改动通常同时落在 `Views/`、`ViewModels/`、`Services/` 和 `.trae/specs/`
|
|
|
|
|
|
- UI 启动与窗口生命周期主线在 `Program.cs` 和 `App.axaml.cs`
|
|
|
|
|
|
|
|
|
|
|
|
### 插件
|
|
|
|
|
|
|
|
|
|
|
|
- SDK 公共 API 以 `LanMountainDesktop.PluginSdk/` 为准
|
|
|
|
|
|
- 共享契约以 `LanMountainDesktop.Shared.Contracts/` 为准
|
|
|
|
|
|
- market 数据来源默认是兄弟仓库 `..\\LanAirApp`
|
Avalonia12 (#7)
* ava12升级
* Enable centralized package versioning
Add <Project> and <PropertyGroup> with <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally> to Directory.Packages.props to enable centralized package version management across the repository. This allows package versions to be controlled from this single file instead of individual project files.
* Migrate codebase to Avalonia 12 APIs
Apply Avalonia 12 migration changes: replace SystemDecorations with WindowDecorations and remove ExtendClientAreaChromeHints/ExtendClientAreaTitleBarHeightHint usages; update BindingPlugins removal logic (no-op); switch clipboard usage to ClipboardExtensions.SetTextAsync; update Bitmap.CopyPixels calls to the new signature. Replace TextBox.Watermark with PlaceholderText, convert NumberBox styles to FANumberBox and adjust templates, change Checked/Unchecked handlers to IsCheckedChanged, and adapt FluentIcons usages (SymbolIconSource -> FASymbol/FAFont/FluentIcon equivalents). Fix MainWindow partial classes to inherit Window and correct missing variables/fields/usings. Add migration docs/specs/tasks under .trae and include a small TestFluentIcons project for icon testing.
* Migrate to Avalonia 12 and Plugin SDK v5
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.
* Update icon glyphs and symbol mappings
Replace and refine icon sources across settings pages and controls: many FAFontIconSource glyphs were updated to specific Seagull Fluent Icons codepoints, some FASymbolIconSource usages were replaced with FAFontIconSource, and a number of symbol-to-Symbol enum mappings were adjusted (e.g. "Bell" -> AlertOn, "Shield" -> ShieldLock). Also clarified a comment in SettingsWindow and fixed a trailing newline in StudySettingsPage. Changes standardize icon visuals and bridge FluentIcons glyphs into FluentAvalonia icon sources.
* fix.修复合并产生的问题。
2026-04-29 12:14:29 +08:00
|
|
|
|
- 迁移或 breaking change 优先同步 `docs/PLUGIN_SDK_V5_MIGRATION.md`
|
2026-03-23 22:43:54 +08:00
|
|
|
|
|
|
|
|
|
|
### 设置与主题
|
|
|
|
|
|
|
|
|
|
|
|
- 设置持久化和 scope 变化优先检查 `LanMountainDesktop.Settings.Core/`
|
|
|
|
|
|
- 外观、圆角、主题资源优先检查 `LanMountainDesktop.Appearance/` 与专题规范
|
2026-03-30 15:28:51 +08:00
|
|
|
|
- **圆角统一**：桌面组件（Widget）必须统一使用动态资源 `DesignCornerRadiusComponent`。严禁在组件根容器使用硬编码数值或非组件级令牌（如 `Xs`, `Md` 等），以确保全局圆角缩放设置能正确应用到所有组件。
|
2026-03-23 22:43:54 +08:00
|
|
|
|
|
|
|
|
|
|
## 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`
|
Avalonia12 (#7)
* ava12升级
* Enable centralized package versioning
Add <Project> and <PropertyGroup> with <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally> to Directory.Packages.props to enable centralized package version management across the repository. This allows package versions to be controlled from this single file instead of individual project files.
* Migrate codebase to Avalonia 12 APIs
Apply Avalonia 12 migration changes: replace SystemDecorations with WindowDecorations and remove ExtendClientAreaChromeHints/ExtendClientAreaTitleBarHeightHint usages; update BindingPlugins removal logic (no-op); switch clipboard usage to ClipboardExtensions.SetTextAsync; update Bitmap.CopyPixels calls to the new signature. Replace TextBox.Watermark with PlaceholderText, convert NumberBox styles to FANumberBox and adjust templates, change Checked/Unchecked handlers to IsCheckedChanged, and adapt FluentIcons usages (SymbolIconSource -> FASymbol/FAFont/FluentIcon equivalents). Fix MainWindow partial classes to inherit Window and correct missing variables/fields/usings. Add migration docs/specs/tasks under .trae and include a small TestFluentIcons project for icon testing.
* Migrate to Avalonia 12 and Plugin SDK v5
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.
* Update icon glyphs and symbol mappings
Replace and refine icon sources across settings pages and controls: many FAFontIconSource glyphs were updated to specific Seagull Fluent Icons codepoints, some FASymbolIconSource usages were replaced with FAFontIconSource, and a number of symbol-to-Symbol enum mappings were adjusted (e.g. "Bell" -> AlertOn, "Shield" -> ShieldLock). Also clarified a comment in SettingsWindow and fixed a trailing newline in StudySettingsPage. Changes standardize icon visuals and bridge FluentIcons glyphs into FluentAvalonia icon sources.
* fix.修复合并产生的问题。
2026-04-29 12:14:29 +08:00
|
|
|
|
- SDK v5 迁移：`docs/PLUGIN_SDK_V5_MIGRATION.md`
|
2026-03-23 22:43:54 +08:00
|
|
|
|
|
|
|
|
|
|
如果多个文档都提到同一件事，以 `docs/ai/DOC_SOURCES.md` 列出的权威来源为准。
|