docs: update 1.1 story

.claude/settings.local.json

@@ -0,0 +1,3 @@
+{
+  "outputStyle": "default"
+}

docs/architecture/coding-standards.md

@@ -9,16 +9,12 @@
 以下规则是**强制性**的，违反将导致代码审查不通过：
 
 - **命名空间组织：** 所有控件必须放在 `Penguin.AvaloniaUI.Controls.*` 命名空间下，布局控件在 `Penguin.AvaloniaUI.Layouts`，主题在 `Penguin.AvaloniaUI.Themes`。不得跨命名空间引用内部实现细节。
-
 - **依赖属性定义：** 所有公开的可绑定属性必须定义为 `StyledProperty`，使用 `AvaloniaProperty.Register<>` 注册，不得使用字段或普通属性。
-
 - **XAML 资源引用：** 所有颜色、字体、间距必须从主题资源字典引用，禁止硬编码颜色值（如 `#FFFFFF`）。使用 `{DynamicResource TextPrimary}` 而非 `{StaticResource}`，确保主题切换生效。
-
 - **ReactiveUI 集成：** ViewModel 必须继承 `ReactiveObject`，属性变化使用 `this.RaiseAndSetIfChanged(ref _field, value)`，不得直接触发 `PropertyChanged` 事件。
-
 - **错误处理：** 公开 API 方法必须验证参数（如 `ArgumentNullException`），内部方法可使用 `Debug.Assert`。不得吞没异常（空 catch 块）。
-
 - **XML 文档注释：** 所有 `public` 和 `protected` 成员必须有 XML 注释（`///`），包括 `<summary>`、`<param>`、`<returns>`。示例：
+
   ```csharp
   /// <summary>
   /// 应用指定的主题类型
@@ -26,19 +22,18 @@
   /// <param name="type">主题类型（Light 或 Dark）</param>
   public static void ApplyTheme(ThemeType type)
   ```
-
 - **禁止反射动态创建控件：** PropertyGrid 可以使用反射解析属性，但不得使用 `Activator.CreateInstance` 动态创建编辑器控件。使用工厂模式或字典映射。
-
 - **主题资源命名约定：** 语义化颜色必须使用统一前缀：`TextPrimary`、`TextSecondary`、`BackgroundPrimary`、`SurfaceElevated`。不得使用 `Color1`、`MyBlue` 等非语义化命名。
+- **API查询规则：** 在使用不熟悉的API的时候，优先使用 **mcp-context7** 进行上下文查找。
 
 ---
 
 ### Naming Conventions
 
 | 元素类型  | 命名规则                                       | 示例                                                 |
-|---------|---------|------|
+| --------- | ---------------------------------------------- | ---------------------------------------------------- |
 | 控件类    | PascalCase，功能名称 + 控件类型后缀（可选）    | `PropertyGrid`, `TwoColumnLayout`                |
-| 依赖属性 | PascalCase，属性名 + `Property` 后缀 | `SelectedObjectProperty` |
+| 依赖属性  | PascalCase，属性名 +`Property` 后缀          | `SelectedObjectProperty`                           |
 | 私有字段  | camelCase，下划线前缀                          | `_currentTheme`                                    |
 | 事件      | PascalCase，动词过去式                         | `ThemeChanged`, `PropertyValueChanged`           |
 | 方法      | PascalCase，动词开头                           | `ApplyTheme()`, `RefreshProperties()`            |
@@ -50,16 +45,15 @@
 ### File Organization Rules
 
 - **一个文件一个类**：每个控件类单独一个 `.cs` 文件，不得在同一文件中定义多个公开类（嵌套私有类除外）。
-
 - **XAML 与代码分离**：控件的 XAML 模板放在 `Themes/` 子目录下，与类定义分离：
+
   ```
   Controls/PropertyGrid/PropertyGrid.cs
   Controls/PropertyGrid/Themes/PropertyGrid.axaml
   ```
-
 - **数据模型独立文件**：数据模型类（如 `PropertyItem`, `GuideStep`）与控件类分离，放在同级目录下。
-
 - **文件格式规范**：命名空间单独放在文件顶部，减少缩进层级：
+
   ```csharp
   namespace Penguin.AvaloniaUI.Controls;
 
@@ -97,13 +91,14 @@ indent_size = 2
 ```
 
 **代码风格要点：**
+
 - 使用 `var` 声明局部变量（如 `var count = 100;`）
 - 命名空间单独一行，不使用文件范围命名空间的花括号嵌套
 
 **运行格式化检查：**
+
 ```bash
 dotnet format --verify-no-changes
 ```
 
 ---
-

docs/stories/1.1.story.md

@@ -0,0 +1,420 @@
+# Story 1.1: 项目基础设施搭建并初始化示例应用
+
+## Status
+
+**Draft**
+
+---
+
+## Story
+
+**As a** 控件库开发者，
+**I want** 建立完整的项目结构和依赖配置，并创建一个可运行的示例应用，
+**so that** 我可以在稳定的基础设施上开始控件开发，并有一个测试载体来验证功能。
+
+---
+
+## Acceptance Criteria
+
+1. 创建 Monorepo 目录结构，包含以下项目：
+   - `src/Penguin.AvaloniaUI/`（核心控件库，.NET 8 类库）
+   - `src/Example/`（示例应用，Avalonia 桌面应用）
+   - `src/Penguin.AvaloniaUI.Tests/`（单元测试项目，xUnit）
+
+2. 配置 `Penguin.AvaloniaUI` 项目的核心依赖：
+   - Avalonia 11.x（最新稳定版）
+   - Avalonia.ReactiveUI
+   - Semi.Avalonia（如果评估后可用）
+
+3. 配置 `Example` 项目引用 `Penguin.AvaloniaUI` 项目
+
+4. Example 应用能够成功启动，显示一个基础窗口，包含：
+   - 标题："Penguin.AvaloniaUI Demo"
+   - 一个 TextBlock 显示 "Hello World"
+   - 窗口大小：800x600
+
+5. 项目能够在 Windows 平台成功编译和运行
+
+6. 创建基础的 `.gitignore` 和 `README.md`
+
+7. 快速评估 Semi.Avalonia 的可用性：
+   - 如果 Semi.Avalonia 可用，在 Example 中应用其基础样式
+   - 如果不可用或过于复杂，记录决策并准备自定义样式系统
+
+---
+
+## Tasks / Subtasks
+
+- [ ] **Task 1: 创建项目目录结构和解决方案** (AC: 1)
+  - [ ] 创建 `src/Penguin.AvaloniaUI/` 核心控件库项目（.NET 9.0 类库）
+  - [ ] 创建 `src/Example/` 示例应用项目（Avalonia 桌面应用）
+  - [ ] 创建 `src/Penguin.AvaloniaUI.Tests/` 单元测试项目（xUnit）
+  - [ ] 创建或更新解决方案文件 `Penguin.AvaloniaUI.sln`，包含所有三个项目
+  - [ ] 验证所有项目都能成功加载到解决方案中
+
+- [ ] **Task 2: 配置统一包版本管理** (AC: 2)
+  - [ ] 创建或更新 `Directory.Packages.props` 文件，配置 Central Package Management
+  - [ ] 添加 Avalonia 11.3.7 包版本定义
+  - [ ] 添加 ReactiveUI.Avalonia 11.3.0 包版本定义
+  - [ ] 添加 xUnit 2.6.6 和 xUnit.runner.visualstudio 2.5.6 包版本定义
+  - [ ] 确保所有项目 `.csproj` 文件启用 `ManagePackageVersionsCentrally`
+
+- [ ] **Task 3: 配置 Penguin.AvaloniaUI 核心库项目依赖** (AC: 2)
+  - [ ] 在 `Penguin.AvaloniaUI.csproj` 中添加 Avalonia 包引用（不指定版本号）
+  - [ ] 在 `Penguin.AvaloniaUI.csproj` 中添加 ReactiveUI.Avalonia 包引用
+  - [ ] 创建基本的命名空间结构（Controls/、Layouts/、Themes/、Utils/ 目录）
+  - [ ] 评估 Semi.Avalonia 可用性并记录决策
+  - [ ] 如果 Semi.Avalonia 可用，添加 Semi.Avalonia 包引用
+
+- [ ] **Task 4: 配置 Example 示例应用项目** (AC: 3, 4)
+  - [ ] 在 `Example.csproj` 中添加对 `Penguin.AvaloniaUI` 项目的引用
+  - [ ] 在 `Example.csproj` 中添加 Avalonia 桌面应用必需的包引用
+  - [ ] 创建 `App.axaml` 和 `App.axaml.cs` 应用程序入口点
+  - [ ] 创建 `MainWindow.axaml` 和 `MainWindow.axaml.cs` 主窗口
+  - [ ] 在 MainWindow 中设置标题为 "Penguin.AvaloniaUI Demo"
+  - [ ] 在 MainWindow 中添加 TextBlock 显示 "Hello World"
+  - [ ] 设置窗口默认大小为 800x600
+  - [ ] 创建 `Program.cs` 配置 Avalonia 应用启动
+
+- [ ] **Task 5: 配置测试项目** (AC: 1)
+  - [ ] 在 `Penguin.AvaloniaUI.Tests.csproj` 中添加 xUnit 包引用
+  - [ ] 在测试项目中添加对 `Penguin.AvaloniaUI` 项目的引用
+  - [ ] 创建测试项目的目录结构（Controls/、Layouts/、Themes/、Utils/）
+  - [ ] 创建一个简单的占位测试类验证测试框架工作正常
+
+- [ ] **Task 6: 编译和运行验证** (AC: 5)
+  - [ ] 执行 `dotnet build` 确保所有项目成功编译
+  - [ ] 执行 `dotnet test` 确保测试项目可以运行
+  - [ ] 启动 Example 应用，验证窗口正确显示
+  - [ ] 验证窗口标题、TextBlock 内容和窗口尺寸符合要求
+
+- [ ] **Task 7: 创建项目文档和配置文件** (AC: 6)
+  - [ ] 验证并更新 `.gitignore` 文件（应已存在）
+  - [ ] 更新 `README.md` 添加项目简介、技术栈和快速开始指南
+  - [ ] 验证 `.editorconfig` 文件存在且配置正确
+  - [ ] 在 README 中记录 Semi.Avalonia 评估决策
+
+---
+
+## Dev Notes
+
+本节包含从架构文档中提取的所有相关技术信息，开发者应仔细阅读以确保实现符合项目标准。
+
+### Technology Stack
+
+[Source: docs/architecture/tech-stack.md]
+
+本项目使用以下技术栈，开发时必须严格遵守：
+
+| Technology | Version | Purpose |
+|-----------|---------|---------|
+| .NET | 9.0 | 应用运行时环境（注意：需要从原计划的 .NET 8 更新为 .NET 9） |
+| Avalonia | 11.3.7 | 跨平台桌面 UI 框架 |
+| ReactiveUI.Avalonia | 11.3.0 | 响应式 MVVM 实现 |
+| xUnit | 2.6.6 | 单元测试框架 |
+| xUnit.runner.visualstudio | 2.5.6 | Visual Studio 测试运行器 |
+
+**重要：统一包版本管理**
+
+项目使用 Central Package Management，在 `Directory.Packages.props` 中集中管理所有包版本：
+
+```xml
+<Project>
+  <PropertyGroup>
+    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageVersion Include="Avalonia" Version="11.3.7" />
+    <PackageVersion Include="ReactiveUI.Avalonia" Version="11.3.0" />
+    <PackageVersion Include="xUnit" Version="2.6.6" />
+    <PackageVersion Include="xUnit.runner.visualstudio" Version="2.5.6" />
+  </ItemGroup>
+</Project>
+```
+
+在各项目的 `.csproj` 文件中引用包时**不指定版本号**：
+
+```xml
+<ItemGroup>
+  <PackageReference Include="Avalonia" />
+  <PackageReference Include="ReactiveUI.Avalonia" />
+</ItemGroup>
+```
+
+### Project Structure
+
+[Source: docs/architecture/unified-project-structure.md]
+
+Monorepo 项目结构必须按照以下组织：
+
+```
+D:\32_avalonia.ui/
+├── src/
+│   ├── Penguin.AvaloniaUI/              # 核心控件库项目
+│   │   ├── Controls/                     # 业务场景控件（命名空间: Penguin.AvaloniaUI.Controls.*）
+│   │   ├── Layouts/                      # 布局控件（命名空间: Penguin.AvaloniaUI.Layouts）
+│   │   ├── Themes/                       # 主题系统（命名空间: Penguin.AvaloniaUI.Themes）
+│   │   ├── Utils/                        # 工具类（命名空间: Penguin.AvaloniaUI.Utils.*）
+│   │   ├── Assets/                       # 资源文件
+│   │   ├── Penguin.AvaloniaUI.csproj
+│   │   └── AssemblyInfo.cs
+│   │
+│   ├── Example/                          # 示例应用项目
+│   │   ├── App.axaml
+│   │   ├── App.axaml.cs
+│   │   ├── ViewModels/                   # 视图模型
+│   │   │   └── MainWindowViewModel.cs
+│   │   ├── Views/                        # 视图/页面
+│   │   │   ├── MainWindow.axaml
+│   │   │   ├── MainWindow.axaml.cs
+│   │   │   └── Pages/
+│   │   ├── Models/                       # 测试数据模型
+│   │   ├── Assets/
+│   │   ├── Example.csproj
+│   │   └── Program.cs
+│   │
+│   └── Penguin.AvaloniaUI.Tests/        # 单元测试项目
+│       ├── Controls/
+│       ├── Layouts/
+│       ├── Themes/
+│       ├── Utils/
+│       └── Penguin.AvaloniaUI.Tests.csproj
+├── docs/                                 # 项目文档
+├── .editorconfig
+├── .gitignore
+├── Directory.Packages.props
+├── README.md
+└── Penguin.AvaloniaUI.sln
+```
+
+**关键命名空间映射：**
+- Controls/ → `Penguin.AvaloniaUI.Controls.*`
+- Layouts/ → `Penguin.AvaloniaUI.Layouts`
+- Themes/ → `Penguin.AvaloniaUI.Themes`
+- Utils/ → `Penguin.AvaloniaUI.Utils.*`
+
+### Coding Standards
+
+[Source: docs/architecture/coding-standards.md]
+
+**命名空间组织规则：**
+- 使用文件范围命名空间（File-scoped namespace），减少缩进层级
+- 命名空间单独一行，格式：`namespace Penguin.AvaloniaUI.Controls;`
+
+**命名约定：**
+- 控件类：PascalCase，功能名称 + 控件类型后缀（例：`PropertyGrid`, `TwoColumnLayout`）
+- 私有字段：camelCase，下划线前缀（例：`_currentTheme`）
+- 方法：PascalCase，动词开头（例：`ApplyTheme()`, `RefreshProperties()`）
+
+**代码风格（基于 .editorconfig）：**
+
+```ini
+[*.cs]
+indent_style = space
+indent_size = 4
+end_of_line = crlf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.axaml]
+indent_size = 2
+```
+
+**关键规则：**
+- XML 文档注释：所有 `public` 和 `protected` 成员必须有 XML 注释（`///`）
+- 错误处理：公开 API 方法必须验证参数（如 `ArgumentNullException`）
+- 使用 `var` 声明局部变量
+
+**代码格式化检查：**
+```bash
+dotnet format --verify-no-changes
+```
+
+### Example Application Structure
+
+示例应用必须包含以下核心文件：
+
+**Program.cs** - 应用程序入口点：
+```csharp
+using Avalonia;
+using System;
+
+namespace Example;
+
+class Program
+{
+    [STAThread]
+    public static void Main(string[] args) => BuildAvaloniaApp()
+        .StartWithClassicDesktopLifetime(args);
+
+    public static AppBuilder BuildAvaloniaApp()
+        => AppBuilder.Configure<App>()
+            .UsePlatformDetect()
+            .LogToTrace();
+}
+```
+
+**App.axaml** - 应用程序资源：
+```xml
+<Application xmlns="https://github.com/avaloniaui"
+             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+             x:Class="Example.App">
+  <Application.Styles>
+    <FluentTheme />
+  </Application.Styles>
+</Application>
+```
+
+**MainWindow.axaml** - 主窗口（AC 4 要求）：
+```xml
+<Window xmlns="https://github.com/avaloniaui"
+        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+        x:Class="Example.Views.MainWindow"
+        Title="Penguin.AvaloniaUI Demo"
+        Width="800"
+        Height="600">
+  <TextBlock Text="Hello World"
+             HorizontalAlignment="Center"
+             VerticalAlignment="Center" />
+</Window>
+```
+
+### Semi.Avalonia Evaluation
+
+在配置核心库依赖时，需要快速评估 Semi.Avalonia 的可用性：
+
+**评估步骤：**
+1. 尝试通过 NuGet 查找 `Semi.Avalonia` 包
+2. 检查包的文档和示例
+3. 评估集成复杂度（时间成本 < 1 小时）
+
+**决策标准：**
+- 如果可用且集成简单：添加到 Directory.Packages.props 并在 Example 中引用
+- 如果不可用或过于复杂：记录在 README 中，并注明将使用自定义样式系统（后续故事实现）
+
+**记录格式（README.md）：**
+```markdown
+## Style System Decision
+
+- **Date**: [当前日期]
+- **Decision**: [使用 Semi.Avalonia / 使用自定义样式系统]
+- **Rationale**: [简短说明原因]
+```
+
+### Testing
+
+[Source: docs/architecture/testing-strategy.md]
+
+**测试项目配置：**
+- 测试框架：xUnit 2.6.6
+- 测试项目命名：`Penguin.AvaloniaUI.Tests`
+- 测试文件组织：按照源代码目录结构镜像组织（Controls/、Layouts/、Themes/、Utils/）
+
+**测试命名约定：**
+- 测试类：`{ClassName}Tests`
+- 测试方法：`{MethodName}_{Scenario}_{ExpectedResult}`
+
+**示例占位测试类：**
+```csharp
+namespace Penguin.AvaloniaUI.Tests;
+
+public class PlaceholderTests
+{
+    [Fact]
+    public void SampleTest_WithValidInput_ShouldPass()
+    {
+        // Arrange
+        var expected = true;
+
+        // Act
+        var actual = true;
+
+        // Assert
+        Assert.Equal(expected, actual);
+    }
+}
+```
+
+**运行测试：**
+```bash
+# 运行所有测试
+dotnet test
+
+# 运行特定测试类
+dotnet test --filter "FullyQualifiedName~PlaceholderTests"
+```
+
+### Project Configuration Files
+
+**.editorconfig** - 已存在于项目根目录，确保一致的代码格式
+
+**.gitignore** - 已存在于项目根目录，包含 .NET 和 Avalonia 相关忽略规则
+
+**Directory.Packages.props** - 如果已存在则更新，否则创建新文件
+
+### Build and Run Commands
+
+**编译所有项目：**
+```bash
+dotnet build
+```
+
+**运行测试：**
+```bash
+dotnet test
+```
+
+**运行示例应用：**
+```bash
+dotnet run --project src/Example/Example.csproj
+```
+
+**格式化代码：**
+```bash
+dotnet format
+```
+
+### Important Notes
+
+1. **目标框架版本**：AC 中提到 .NET 8，但 Tech Stack 指定 .NET 9.0，请使用 .NET 9.0
+2. **项目引用**：Example 项目必须通过项目引用（ProjectReference）而非包引用（PackageReference）来引用 Penguin.AvaloniaUI
+3. **初始目录创建**：在创建项目时，必须同时创建 Controls/、Layouts/、Themes/、Utils/ 等子目录，即使它们暂时为空
+4. **Semi.Avalonia**：这是一个可选依赖，评估时间不应超过合理范围，如果遇到困难应选择自定义实现方案
+
+---
+
+## Change Log
+
+| Date | Version | Description | Author |
+|------|---------|-------------|--------|
+| 2025-10-16 | 1.0 | Initial story creation | Scrum Master (Bob) |
+
+---
+
+## Dev Agent Record
+
+*This section will be populated by the development agent during implementation.*
+
+### Agent Model Used
+
+*To be filled by Dev Agent*
+
+### Debug Log References
+
+*To be filled by Dev Agent*
+
+### Completion Notes
+
+*To be filled by Dev Agent*
+
+### File List
+
+*To be filled by Dev Agent*
+
+---
+
+## QA Results
+
+*This section will be populated by QA Agent after implementation.*