81 lines
5.0 KiB
Markdown
81 lines
5.0 KiB
Markdown
# AGENTS.md
|
||
|
||
## Build & Test
|
||
|
||
```bash
|
||
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).
|
||
|
||
## 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` |
|
||
|
||
### 使用模式
|
||
|
||
- 写入/编辑/打补丁：需**两次调用**（首次触发加载，第二次执行）
|
||
- 读取/搜索：直接可用，单次调用
|
||
|