返回提交历史
Added
.github/copilot-instructions.md
+187
-0
XFEstudio/HaloPixelToolBox
Add Copilot instructions for repository
Co-authored-by: XFEstudio <132526994+XFEstudio@users.noreply.github.com>
af1ff47
代码差异
1 个文件
+187
-0
@@ -0,0 +1,187 @@
1
# Copilot Instructions for HaloPixelToolBox
2
3
## Project Overview
4
5
HaloPixelToolBox (花再音响工具箱) is a desktop utility toolbox application designed to provide rich and intuitive information display capabilities for audio/desktop devices. The project is primarily focused on displaying lyrics from various music platforms, starting with NetEase Cloud Music support.
6
7
## Technology Stack
8
9
- **Framework**: .NET 8 with WinUI 3
10
- **Platform**: Windows 10.0.22621.0 (minimum version: 10.0.17763.0)
11
- **UI Framework**: Windows App SDK 1.7.x with WinUI 3
12
- **Architecture**: MVVM pattern using CommunityToolkit.Mvvm
13
- **Dependencies**:
14
- XFEExtension.NetCore libraries (various utilities)
15
- CommunityToolkit.Mvvm for MVVM implementation
16
- CommunityToolkit.WinUI.Controls for UI controls
17
- Microsoft.WindowsAppSDK for Windows App development
18
19
## Project Structure
20
21
```
22
HaloPixelToolBox/
23
├── HaloPixelToolBox/ # Main WinUI application
24
│ ├── Views/ # XAML views and code-behind
25
│ ├── ViewModels/ # View models
26
│ ├── Interface/Services/ # Service interfaces
27
│ ├── Implements/Services/ # Service implementations
28
│ └── Assets/ # Application assets and resources
29
├── HaloPixelToolBox.Core/ # Core business logic
30
│ ├── Models/ # Data models
31
│ └── Utilities/ # Helper utilities
32
├── HaloPixelToolBox.Test/ # Test project (XUnit)
33
├── HaloPixelToolBox.Installer/ # Installer project
34
└── HaloPixelToolBox.Installer.Package/ # Installer packaging
35
```
36
37
## Build and Test
38
39
### Building the Project
40
```bash
41
# Build the entire solution
42
dotnet build HaloPixelToolBox.slnx
43
44
# Build for specific platform
45
dotnet build HaloPixelToolBox.slnx -p:Platform=x64
46
```
47
48
### Running Tests
49
```bash
50
# Run all tests
51
dotnet test HaloPixelToolBox/HaloPixelToolBox.Test/HaloPixelToolBox.Test.csproj
52
```
53
54
### Platform Support
55
The application targets three platforms:
56
- x86 (win-x86)
57
- x64 (win-x64)
58
- ARM64 (win-arm64)
59
60
## Coding Standards and Conventions
61
62
### C# Style Guidelines
63
1. **Naming Conventions**:
64
- Use PascalCase for class names, method names, and properties
65
- Use camelCase for private fields and local variables
66
- Use descriptive names in English for code elements
67
68
2. **MVVM Pattern**:
69
- ViewModels should inherit from `ViewModelBase`
70
- Use `[ObservableProperty]` attribute from CommunityToolkit.Mvvm for bindable properties
71
- Use `[RelayCommand]` attribute for command methods
72
- Services should be registered with `ServiceManager`
73
74
3. **Code Organization**:
75
- Keep views in `Views/` folder with corresponding `.xaml.cs` files
76
- Keep view models in `ViewModels/` folder
77
- Service interfaces go in `Interface/Services/`
78
- Service implementations go in `Implements/Services/`
79
80
4. **Nullable Reference Types**:
81
- The project has nullable reference types enabled
82
- Use `?` suffix for nullable types
83
- Handle null cases appropriately
84
85
5. **Using Directives**:
86
- Global usings are configured in the project for common namespaces
87
- Include necessary usings at the top of each file
88
89
### XAML Guidelines
90
1. Use proper indentation and formatting
91
2. Follow WinUI 3 control naming conventions
92
3. Bind to ViewModel properties using `{x:Bind}` where possible
93
94
## Language and Documentation
95
96
### Bilingual Support
97
The project serves a **bilingual community** (Chinese and English):
98
- **Code**: Write code, comments, and technical documentation in **English**
99
- **User-Facing Content**: Issues, README, and user documentation support **Chinese**
100
- **Issue Translation**: The repository has automatic translation configured for issues
101
102
### Comments
103
- Add comments for complex logic or non-obvious code
104
- Comments can be in English
105
- User-facing strings should support localization where applicable
106
107
## Key Features and Development Focus
108
109
### Current Features
110
- ✅ NetEase Cloud Music lyrics display
111
112
### Planned Features
113
- 🚀 Additional music platform lyrics support
114
- 💬 Social media message notifications
115
- 🎨 More customization options
116
117
## Working with the Repository
118
119
### Issue and PR Guidelines
120
- Issues can be submitted in Chinese (automatic translation is configured)
121
- Read `CONTRIBUTING.md` for detailed contribution guidelines
122
- Use the issue templates provided in `.github/ISSUE_TEMPLATE/`
123
- PRs should:
124
- Have clear descriptions in English
125
- Follow existing code style
126
- Not break existing functionality
127
- Include tests if adding new features
128
129
### Git Workflow
130
- Feature branches should be created from main
131
- Commit messages should be clear and descriptive
132
- Follow conventional commit format when possible
133
134
## Service Architecture
135
136
The application uses a service-based architecture:
137
- Services are defined as interfaces in `Interface/Services/`
138
- Implementations are in `Implements/Services/`
139
- Services are accessed via `ServiceManager` (from XFEExtension.NetCore)
140
- Common services:
141
- `INavigationService`: Page navigation
142
- `IMessageService`: User notifications
143
- `ITrayIconService`: System tray management
144
- `IUpgradeService`: Application updates
145
- `IPageService`: Page lifecycle management
146
147
## Best Practices
148
149
1. **Use Existing Libraries**: Leverage XFEExtension.NetCore utilities where possible
150
2. **Follow MVVM**: Keep business logic in ViewModels, not in code-behind
151
3. **Service Pattern**: Register new services with ServiceManager
152
4. **Error Handling**: Handle exceptions gracefully and provide user feedback
153
5. **Resource Management**: Properly dispose of resources and event handlers
154
6. **UI Threading**: Use proper threading for UI updates in WinUI 3
155
7. **Async/Await**: Use async patterns for I/O operations
156
157
## Testing
158
159
- Test project uses XFEExtension.NetCore.XUnit
160
- Write unit tests for business logic in Core project
161
- Integration tests for services and ViewModels
162
- Keep tests focused and maintainable
163
164
## Special Considerations
165
166
### Windows App SDK Specifics
167
- The app uses self-contained Windows App SDK deployment
168
- MSIX packaging is enabled but WindowsPackageType is set to None
169
- Application uses unsafe blocks for certain operations
170
171
### Installer Project
172
- Separate installer and updater project included
173
- Installer embeds the application as `Source.zip`
174
- See `HaloPixelToolBox.Installer/README.md` for setup instructions
175
176
## Security
177
178
- The project handles user data and music platform integration
179
- Be cautious with API credentials and user privacy
180
- Follow secure coding practices for network operations
181
- Validate all user inputs
182
183
## Additional Resources
184
185
- Main README: `/README.md`
186
- Contributing Guidelines: `/CONTRIBUTING.md`
187
- Installer Documentation: `/HaloPixelToolBox.Installer/README.md`