Skip to content

Commit 4dff245

Browse files
AlexanderDotHAlexanderDotH
committed
docs: Update README files to DevBase.Net, add AGENT.md for AI agents
- Renamed DevBase.Request references to DevBase.Net in all READMEs - Renamed docs/DevBase.Request.md to docs/DevBase.Net.md - Created AGENT.md files for all projects to help AI agents: - Solution-level AGENT.md with overview and patterns - DevBase.Net/AGENT.md - HTTP client guide - DevBase.Api/AGENT.md - API clients guide - DevBase/AGENT.md - Core utilities guide - DevBase.Format/AGENT.md - Format parsers guide - DevBase.Cryptography/AGENT.md - Crypto guide - DevBase.Cryptography.BouncyCastle/AGENT.md - DevBase.Extensions/AGENT.md - DevBase.Logging/AGENT.md - DevBase.Avalonia/AGENT.md
1 parent f2e761d commit 4dff245

File tree

13 files changed

+767
-10
lines changed

13 files changed

+767
-10
lines changed

‎AGENT.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# DevBase Agent Guide
2+
3+
This document helps AI agents work effectively with the DevBase solution.
4+
5+
## Solution Overview
6+
7+
DevBase is a multi-project .NET solution providing utilities, API clients, and helpers. The solution targets **.NET 9.0**.
8+
9+
## Project Structure
10+
11+
```
12+
DevBase/
13+
├── DevBase/ # Core utilities (AList, IO, async tasks)
14+
├── DevBase.Api/ # API clients (Deezer, Tidal, AppleMusic, etc.)
15+
├── DevBase.Avalonia/ # Avalonia UI utilities (color analysis)
16+
├── DevBase.Cryptography/ # Basic cryptography (Blowfish, MD5)
17+
├── DevBase.Cryptography.BouncyCastle/ # BouncyCastle crypto wrappers
18+
├── DevBase.Extensions/ # .NET type extensions
19+
├── DevBase.Format/ # File format parsers (LRC, SRT, ENV)
20+
├── DevBase.Logging/ # Lightweight logging
21+
├── DevBase.Net/ # HTTP client library (main networking)
22+
├── DevBase.Test/ # Unit tests (NUnit)
23+
├── DevBaseLive/ # Console app for testing
24+
└── docs/ # Documentation
25+
```
26+
27+
## Key Dependencies Between Projects
28+
29+
```
30+
DevBase.Api → DevBase.Net → DevBase → DevBase.Cryptography
31+
DevBase.Format → DevBase
32+
DevBase.Test → All projects
33+
```
34+
35+
## Common Patterns
36+
37+
### 1. HTTP Requests (DevBase.Net)
38+
```csharp
39+
using DevBase.Net.Core;
40+
41+
Response response = await new Request("https://api.example.com")
42+
.WithHeader("Authorization", "Bearer token")
43+
.WithTimeout(TimeSpan.FromSeconds(30))
44+
.SendAsync();
45+
46+
var data = await response.ParseJsonAsync<MyType>();
47+
```
48+
49+
### 2. API Client Error Handling (DevBase.Api)
50+
All API clients extend `ApiClient` and use the `Throw<T>()` method:
51+
```csharp
52+
if (response.StatusCode != HttpStatusCode.OK)
53+
return Throw<object>(new MyException(ExceptionType.NotFound));
54+
```
55+
56+
For tuple return types, use `ThrowTuple()`:
57+
```csharp
58+
return ThrowTuple(new MyException(ExceptionType.NotFound));
59+
```
60+
61+
### 3. Generic Collections (DevBase)
62+
Use `AList<T>` instead of `List<T>` for enhanced functionality:
63+
```csharp
64+
AList<string> items = new AList<string>();
65+
items.Add("item");
66+
string first = items.Get(0);
67+
bool isEmpty = items.IsEmpty();
68+
```
69+
70+
## Important Classes
71+
72+
| Project | Key Classes |
73+
|---------|-------------|
74+
| DevBase.Net | `Request`, `Response`, `ProxyInfo`, `RetryPolicy` |
75+
| DevBase.Api | `ApiClient`, `Deezer`, `Tidal`, `AppleMusic`, `NetEase` |
76+
| DevBase | `AList<T>`, `AFile`, `AFileObject` |
77+
| DevBase.Format | `LrcParser`, `SrtParser`, `TimeStampedLyric` |
78+
79+
## Namespaces
80+
81+
- **DevBase.Net.Core** - Request/Response classes
82+
- **DevBase.Net.Proxy** - Proxy support
83+
- **DevBase.Api.Apis.[Service]** - API clients
84+
- **DevBase.Generics** - Generic collections
85+
- **DevBase.Format.Formats** - File parsers
86+
87+
## Testing
88+
89+
Run all tests:
90+
```bash
91+
dotnet test
92+
```
93+
94+
Run specific test class:
95+
```bash
96+
dotnet test --filter "FullyQualifiedName~ClassName"
97+
```
98+
99+
## Building NuGet Packages
100+
101+
Packages are generated on build with `GeneratePackageOnBuild=true`:
102+
```bash
103+
dotnet build -c Release
104+
```
105+
106+
Packages output to: `bin/Release/*.nupkg`
107+
108+
## Tips for AI Agents
109+
110+
1. **Use `DevBase.Net.Core.Request`** for HTTP operations, not `HttpClient` directly
111+
2. **Extend `ApiClient`** when creating new API clients
112+
3. **Use `Throw<T>()`** for error handling in API clients
113+
4. **Use `ThrowTuple()`** for methods returning `ValueTuple` types
114+
5. **Check `StrictErrorHandling`** property for exception behavior
115+
6. **Use `AList<T>`** from DevBase.Generics for collections
116+
7. **External API tests** should handle unavailable services gracefully
117+
8. **README.md files** are included in NuGet packages
118+
119+
## Error Handling Pattern
120+
121+
```csharp
122+
// In API client methods
123+
if (condition_failed)
124+
return Throw<object>(new MyException(ExceptionType.Reason));
125+
126+
// For tuple returns
127+
if (condition_failed)
128+
return ThrowTuple(new MyException(ExceptionType.Reason));
129+
```
130+
131+
When `StrictErrorHandling = true`, exceptions are thrown.
132+
When `StrictErrorHandling = false`, default values are returned.

‎DevBase.Api/AGENT.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# DevBase.Api Agent Guide
2+
3+
## Overview
4+
DevBase.Api provides ready-to-use API clients for music streaming services, AI platforms, and lyrics providers.
5+
6+
## Key Classes
7+
8+
| Class | Namespace | Purpose |
9+
|-------|-----------|---------|
10+
| `ApiClient` | `DevBase.Api.Apis` | Base class for all API clients |
11+
| `Deezer` | `DevBase.Api.Apis.Deezer` | Deezer music API |
12+
| `Tidal` | `DevBase.Api.Apis.Tidal` | Tidal music API |
13+
| `AppleMusic` | `DevBase.Api.Apis.AppleMusic` | Apple Music API |
14+
| `NetEase` | `DevBase.Api.Apis.NetEase` | NetEase music API |
15+
| `BeautifulLyrics` | `DevBase.Api.Apis.BeautifulLyrics` | Lyrics provider |
16+
17+
## Error Handling Pattern
18+
19+
All API clients extend `ApiClient` which provides error handling:
20+
21+
```csharp
22+
public class MyApiClient : ApiClient
23+
{
24+
public async Task<MyResult> GetData()
25+
{
26+
if (errorCondition)
27+
return Throw<object>(new MyException(ExceptionType.Reason));
28+
29+
// Normal return
30+
return result;
31+
}
32+
33+
// For tuple return types
34+
public async Task<(string Data, bool Flag)> GetTuple()
35+
{
36+
if (errorCondition)
37+
return ThrowTuple(new MyException(ExceptionType.Reason));
38+
39+
return (data, true);
40+
}
41+
}
42+
```
43+
44+
### Error Handling Modes
45+
- `StrictErrorHandling = true` → Exceptions are thrown
46+
- `StrictErrorHandling = false` → Default values returned (null, empty, false)
47+
48+
## Quick Reference
49+
50+
### Deezer
51+
```csharp
52+
var deezer = new Deezer(arlToken: "optional");
53+
var results = await deezer.Search("artist name");
54+
var track = await deezer.GetSong("trackId");
55+
```
56+
57+
### NetEase
58+
```csharp
59+
var netease = new NetEase();
60+
var results = await netease.Search("keyword");
61+
var lyrics = await netease.Lyrics("trackId");
62+
```
63+
64+
### BeautifulLyrics
65+
```csharp
66+
var lyrics = new BeautifulLyrics();
67+
var (rawLyrics, isRichSync) = await lyrics.GetRawLyrics("isrc");
68+
var parsedLyrics = await lyrics.GetLyrics("isrc");
69+
```
70+
71+
### AppleMusic
72+
```csharp
73+
var apple = await AppleMusic.WithAccessToken();
74+
var results = await apple.Search("query");
75+
```
76+
77+
## File Structure
78+
```
79+
DevBase.Api/
80+
├── Apis/
81+
│ ├── ApiClient.cs # Base class with Throw methods
82+
│ ├── Deezer/
83+
│ │ ├── Deezer.cs
84+
│ │ └── Structure/ # JSON response types
85+
│ ├── Tidal/
86+
│ ├── AppleMusic/
87+
│ ├── NetEase/
88+
│ ├── BeautifulLyrics/
89+
│ └── ...
90+
├── Enums/ # Exception type enums
91+
├── Exceptions/ # Custom exceptions
92+
└── Serializer/ # JSON deserializer
93+
```
94+
95+
## Important Notes
96+
97+
1. **Always extend `ApiClient`** for new API clients
98+
2. **Use `Throw<object>()`** for reference type returns
99+
3. **Use `ThrowTuple()`** for `ValueTuple` returns
100+
4. **JSON types are in `Structure/Json/` folders**
101+
5. **Use `JsonDeserializer<T>`** for JSON parsing
102+
6. **External APIs may be unavailable** - handle gracefully in tests
103+
104+
## Dependencies
105+
- **DevBase.Net** for HTTP requests
106+
- **DevBase.Format** for lyrics parsing
107+
- **Newtonsoft.Json** for JSON serialization

‎DevBase.Avalonia/AGENT.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# DevBase.Avalonia Agent Guide
2+
3+
## Overview
4+
DevBase.Avalonia provides utilities for the Avalonia UI framework, specifically image color analysis.
5+
6+
## Key Classes
7+
8+
| Class | Namespace | Purpose |
9+
|-------|-----------|---------|
10+
| `ColorCalculator` | `DevBase.Avalonia.Color` | Dominant/accent color extraction |
11+
| `ColorConverter` | `DevBase.Avalonia.Color` | Color space conversions |
12+
13+
## Quick Reference
14+
15+
### Extract Dominant Color
16+
```csharp
17+
using DevBase.Avalonia.Color;
18+
using Avalonia.Media.Imaging;
19+
20+
Bitmap image = new Bitmap("path/to/image.png");
21+
ColorCalculator calculator = new ColorCalculator(image);
22+
23+
Color dominantColor = calculator.GetDominantColor();
24+
Color accentColor = calculator.GetAccentColor();
25+
```
26+
27+
### Color Conversion
28+
```csharp
29+
// RGB to HSL
30+
var hsl = ColorConverter.RgbToHsl(255, 128, 64);
31+
32+
// HSL to RGB
33+
var rgb = ColorConverter.HslToRgb(hsl.H, hsl.S, hsl.L);
34+
```
35+
36+
## File Structure
37+
```
38+
DevBase.Avalonia/
39+
└── Color/
40+
├── ColorCalculator.cs
41+
└── ColorConverter.cs
42+
```
43+
44+
## Important Notes
45+
46+
1. **Requires Avalonia** UI framework
47+
2. **ColorCalculator** analyzes bitmap images
48+
3. **Dominant color** = most prevalent color
49+
4. **Accent color** = complementary/vibrant color
50+
5. **Color space conversions** between RGB, HSL, HSV

‎DevBase.Cryptography.BouncyCastle/AGENT.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# DevBase.Cryptography.BouncyCastle Agent Guide
2+
3+
## Overview
4+
DevBase.Cryptography.BouncyCastle provides modern cryptographic implementations using the BouncyCastle library.
5+
6+
## Key Classes
7+
8+
| Class | Namespace | Purpose |
9+
|-------|-----------|---------|
10+
| `AesGcm` | `DevBase.Cryptography.BouncyCastle.AesGcm` | AES-GCM authenticated encryption |
11+
| `Blowfish` | `DevBase.Cryptography.BouncyCastle.Blowfish` | Enhanced Blowfish |
12+
13+
## Quick Reference
14+
15+
### AES-GCM Encryption
16+
```csharp
17+
using DevBase.Cryptography.BouncyCastle.AesGcm;
18+
19+
byte[] key = new byte[32]; // 256-bit key
20+
byte[] nonce = new byte[12]; // 96-bit nonce
21+
byte[] plaintext = Encoding.UTF8.GetBytes("secret data");
22+
23+
AesGcm aes = new AesGcm(key);
24+
byte[] ciphertext = aes.Encrypt(nonce, plaintext);
25+
byte[] decrypted = aes.Decrypt(nonce, ciphertext);
26+
```
27+
28+
## File Structure
29+
```
30+
DevBase.Cryptography.BouncyCastle/
31+
├── AesGcm/
32+
│ └── AesGcm.cs
33+
└── Blowfish/
34+
└── Blowfish.cs
35+
```
36+
37+
## Important Notes
38+
39+
1. **Requires BouncyCastle.NetCore** NuGet package
40+
2. **Use unique nonces** for each encryption
41+
3. **AES-GCM provides authenticated encryption** (integrity + confidentiality)
42+
4. **Prefer this over DevBase.Cryptography** for security

‎DevBase.Cryptography/AGENT.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# DevBase.Cryptography Agent Guide
2+
3+
## Overview
4+
DevBase.Cryptography provides basic cryptographic implementations including Blowfish and MD5.
5+
6+
## Key Classes
7+
8+
| Class | Namespace | Purpose |
9+
|-------|-----------|---------|
10+
| `Blowfish` | `DevBase.Cryptography.Blowfish` | Blowfish encryption/decryption |
11+
| `MD5` | `DevBase.Cryptography.Hash` | MD5 hashing |
12+
13+
## Quick Reference
14+
15+
### Blowfish Encryption
16+
```csharp
17+
using DevBase.Cryptography.Blowfish;
18+
19+
byte[] key = Encoding.UTF8.GetBytes("secret-key");
20+
byte[] data = Encoding.UTF8.GetBytes("data to encrypt");
21+
22+
Blowfish blowfish = new Blowfish(key);
23+
byte[] encrypted = blowfish.Encrypt(data);
24+
byte[] decrypted = blowfish.Decrypt(encrypted);
25+
```
26+
27+
### MD5 Hashing
28+
```csharp
29+
using DevBase.Cryptography.Hash;
30+
31+
string hash = MD5.ComputeHash("input string");
32+
```
33+
34+
## File Structure
35+
```
36+
DevBase.Cryptography/
37+
├── Blowfish/
38+
│ └── Blowfish.cs
39+
└── Hash/
40+
└── MD5.cs
41+
```
42+
43+
## Important Notes
44+
45+
1. **MD5 is not cryptographically secure** - use only for checksums
46+
2. **Blowfish requires key setup** before encryption
47+
3. **For modern crypto, use DevBase.Cryptography.BouncyCastle**

0 commit comments

Comments
 (0)