AGENTS.md

AI 行为准则

称呼规范：始终称呼用户为「思谦」或「王思谦」。
信息缺失处理：遇到任何不确定、拿不准或信息缺失的情况，不要自行推测。先收集整理好问题，停下来向思谦确认后再继续。

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.
需要一个UI设计。现在的界面属实有点丑陋了。

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.1 KiB Raw Permalink Blame History Unescape Escape