0.7.6.3

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` 的资料误写成本仓库权威来源

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`: 白板笔记持久化
+
+如果改动落在这些行为附近，优先扩展已有测试而不是新建无关测试入口。

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/<feature>/spec.md` | 行为意图和需求场景 |
+| feature 任务拆解 | `.trae/specs/<feature>/tasks.md` | 实施步骤与依赖 |
+| feature 验收 | `.trae/specs/<feature>/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. 如果仍有冲突，以当前仓库源码和项目配置为准，并回写文档