AGENTS.md

Build & Test

dotnet build                                            # Build all projects
dotnet test                                             # Run all tests
dotnet test --filter "FullyQualifiedName~ClassName.MethodName"  # Run single test
dotnet run --project src/GUI                            # Launch the Avalonia desktop app

Architecture

4-project solution (src/Resonance.sln):
- Core — class library: audio file scanning, metadata reading (ATL), SQLite persistence (Dapper)
- Core.Tests — xUnit + FluentAssertions + Moq
- AtlFieldExtractor — CLI that dumps ATL metadata fields from WAV files to .atl.txt to test ATL library
- GUI — Avalonia 12 desktop app: audio asset management UI
MVVM architecture (GUI project):
- Based on CommunityToolkit.Mvvm v8.4.1 — source-generator-driven MVVM toolkit.
- Base class: ViewModelBase (abstract, extends ObservableObject). Use [ObservableProperty] for bindable properties, [RelayCommand] for commands, and SetProperty<T>() for manual property change notification.
- View-ViewModel binding: ViewLocator implements IDataTemplate — convention-based resolution by replacing "ViewModel" with "View" in the type name (e.g., MainWindowViewModel → looks for MainWindow in GUI.Views). Uses Activator.CreateInstance(); no DI container is configured.
- Compiled bindings are enabled by default (AvaloniaUseCompiledBindingsByDefault=true in .csproj). Annotate XAML with x:DataType="vm:MyViewModel" for compile-time validation.
- App.axaml applies FluentTheme and registers ViewLocator globally. App.axaml.cs manually instantiates MainWindow → MainWindowViewModel in OnFrameworkInitializationCompleted.
Target framework: net10.0 (requires .NET 10 SDK — currently 10.0.103).

Known Issues / Gotchas

升级 Avalonia 版本时，必须同步更新所有次级包引用。 仅修改主包 Avalonia 的 Version 不会自动更新 Avalonia.Desktop、Avalonia.Themes.Fluent、Avalonia.Fonts.Inter 等次级包。必须手动逐个修改，然后执行 dotnet clean && dotnet restore。否则运行时的原生库（如 libAvaloniaNative.dylib）会混用新旧版本，导致 macOS 上的 StorageProvider 文件/文件夹选择对话框在回调时 SIGSEGV 崩溃。
- 相关 Avalonia issues: #21102, #21150, #21313，修复 PR: #21104。
Tests create temp files/directories under Path.GetTempPath() and clean them up via IDisposable. Don't rely on a real audio directory for tests.
AudioMetadataReader tests use real WAV files from data/source/ (not in git). When files are absent, tests silently return early (if (wavFiles.Length == 0) return;) — they pass without actually running assertions, not Skip.If. Running dotnet test will report 12 passes regardless of whether the fixture files exist.
.atl.txt fixture files are generated by AtlFieldExtractor. If the WAV files or the ATL library version change, re-run the extractor to regenerate them before running metadata tests.

Data / Test Fixtures

data/source/ 包含有版权保护的 WAV 音频文件，不会提交到 git。按厂商分子目录：Boom/、Wow Sound/、The Odessy/、Sound Idea/。
- 每个 WAV 旁有对应的 .atl.txt 文件（由 AtlFieldExtractor 生成），记录了 ATL 库解析出的完整元数据，供测试断言参考。
- Boom 目录下的文件元数据最丰富（标准标签 + iXML 自定义字段 + BWF bext 字段 + 嵌入封面）；Sound Idea 目录下的文件元数据最少（仅基础技术参数，无任何附加字段）。
AudioMetadataReader 测试使用 data/source/Boom/ 和 Sound Idea/ 中的 WAV 文件。文件不在 git 仓库中，测试通过 if (wavFiles.Length == 0) return; 静默返回（测试仍然 pass，但未执行实际断言）。
路径解析：测试运行时从 bin/Debug/net10.0/ 启动，需向上回溯 6 级到达仓库根目录，再拼接 data/source/。

Conventions

Code and comments are in Chinese.
Namespace: OCES.Resonance.Core (Core), OCES.Resonance.AtlFieldExtractor (extractor), Core.Tests (tests), GUI / GUI.Views / GUI.ViewModels (GUI app).

AI 助手工具说明

工具使用优先级

优先使用 Rider MCP 服务器工具（Rider_* 系列）。该类工具直接通过 IDE 执行操作，结果更准确、上下文更丰富。

场景	优先使用	回退方案
读取文件	`Rider_read_file` / `Rider_get_file_text_by_path`	`read_file`
写入/编辑	`Rider_replace_text_in_file` / `Rider_create_new_file`	`write_file` / `edit_file`
搜索文件	`Rider_find_files_by_glob` / `Rider_search_file`	`list_dir` / glob
搜索内容	`Rider_search_text` / `Rider_search_in_files_by_text`	`grep_files`
正则搜索	`Rider_search_regex` / `Rider_search_in_files_by_regex`	`grep_files`
代码重构	`Rider_rename_refactoring` / `Rider_move_type_to_namespace`	`edit_file`（手动）
构建	`Rider_build_solution`	`bash dotnet build`
运行测试	`Rider_execute_run_configuration`	`bash dotnet test`
代码问题	`Rider_get_file_problems`	—（无等效回退）
符号查找	`Rider_search_symbol` / `Rider_get_symbol_info`	`grep_files`（语义降级）

回退规则：仅当 Rider MCP 工具不可用（未在工具列表中、调用报错）时，才使用对应的默认工具。

默认工具说明（DeepSeek TUI / OpenCode 等）

当前工作环境可能为 DeepSeek TUI 或 OpenCode，文件操作工具因平台而异，采用延迟加载机制的工具首次调用会触发加载并返回 schema 提示（不执行），用正确参数重试后正常执行。

可用文件操作工具

工具	用途	参数注意事项
`write_file`	创建/覆盖文件	`path` + `content`
`edit_file`	单次查找替换	`path` + `search` + `replace`（注意不是 `old_string`/`new_string`）
`apply_patch`	结构化 patch（多块变更）	`path` + `patch`（unified diff 格式）
`read_file`	读取文件	`path`，支持 `start_line`/`max_lines` 分页；PDF 自动提取
`list_dir`	列出目录	`path`（可选）
`grep_files`	正则搜索文件内容	`pattern`，支持 `include`/`exclude` glob、`context_lines`

使用模式

写入/编辑/打补丁：需两次调用（首次触发加载，第二次执行）
读取/搜索：直接可用，单次调用

6.7 KiB Raw Blame History Unescape Escape