Resonance/llm-assist/AGENTS.md

AGENTS.md

Build & Test

dotnet build              # Build all projects
dotnet test               # Run all tests
dotnet test --filter "FullyQualifiedName~ClassName.MethodName"  # Run single test

Architecture

• 3-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
• No Avalonia UI yet — README mentions it but only the Core library exists.
• Target framework: net10.0 (requires .NET 10 SDK — currently 10.0.103).

Known Issues / Gotchas

• Table name mismatch: Database.InitializeDatabase() creates table sounds, but AddEntry() / AddEntries() / EntryExists() reference audio_files. Any call to insert or query will fail at runtime. Database currently has no test coverage.
• 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), OCES.Resonance.Core.Tests (tests).
• Git commit style: WIP: <description> (no conventional commits).

AI 助手工具说明（DeepSeek TUI）

当前工作环境为 DeepSeek TUI，文件操作工具采用延迟加载机制，不在初始工具列表中。首次调用会触发加载并返回 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

使用模式

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