FilePickRequest
一次文件选取的配置（链式构造值对象），与 ModContext.openFilePick 配套使用。纯描述性值对象：模组只声明「要选什么」，选取界面长什么样、以何种形态呈现（游戏内对话框 / 系统对话框）由宿主决定，模组不要把呈现假设写进逻辑。各配置项对宿主均为可选提示：未设置的项由宿主取缺省口径。构造任意线程。
方法速览
| 方法 | 用途 |
|---|---|
of() | 创建空配置（唯一入口） |
title(String) | 设置标题栏文本 |
initialDir(Path) | 设置初始目录 |
extensions(String...) | 设置扩展名白名单 |
directoriesOnly() | 切换为只选目录模式 |
hint(String) | 覆盖底部说明文本 |
title() | 读取标题（未设置 null） |
initialDir() | 读取初始目录（未设置 null） |
extensions() | 读取扩展名数组（未设置 null） |
isDirectoriesOnly() | 是否只选目录 |
hint() | 读取底部说明（未设置 null） |
完整签名
public final class FilePickRequest {
public static FilePickRequest of();
public FilePickRequest title(String value);
public FilePickRequest initialDir(Path value);
public FilePickRequest extensions(String... values);
public FilePickRequest directoriesOnly();
public FilePickRequest hint(String value);
public String title();
public Path initialDir();
public String[] extensions();
public boolean isDirectoriesOnly();
public String hint();
}of()
签名：
public static FilePickRequest of();行为：唯一构造入口（构造器私有），返回空配置：各字段取宿主缺省口径。每次调用返回新实例。
示例：
FilePickRequest req = FilePickRequest.of();title(String value)
签名：
public FilePickRequest title(String value);行为：设置标题栏文本；null 表示回到宿主缺省标题。链式返回自身。
示例：
FilePickRequest req = FilePickRequest.of().title("选择谱面");initialDir(Path value)
签名：
public FilePickRequest initialDir(Path value);行为：设置选取对话框的初始目录；null 表示宿主缺省起点。宿主编排时若该目录不存在，按其自身口径回退。
示例：
FilePickRequest req = FilePickRequest.of().initialDir(ctx.getDataDir());extensions(String... values)
签名：
public FilePickRequest extensions(String... values);行为：设置扩展名白名单（小写、可带点，如 "png"、".jpg"）。设置后选取列表 = 目录 + 指定扩展名的文件；不设置 = 宿主缺省过滤口径。数组按引用保存，不做校验或拷贝。
示例：
FilePickRequest req = FilePickRequest.of().extensions("png", "jpg");directoriesOnly()
签名：
public FilePickRequest directoriesOnly();行为：切换为只选目录模式：列表只含目录，确认对象 = 选中目录。无参数、不可关闭。
示例：
FilePickRequest req = FilePickRequest.of().directoriesOnly();hint(String value)
签名：
public FilePickRequest hint(String value);行为：覆盖对话框底部说明文本；null 表示由宿主按口径给缺省文案。
示例：
FilePickRequest req = FilePickRequest.of().hint("仅支持 16:9 PNG");title()
签名：
public String title();行为：读侧访问器，供宿主桥接层映射到宿主选取服务时取用；模组一般不需要。返回 null 表示未设置。注意链式 setter 与同名 getter 参数个数不同，不要混淆。
示例：
String title = req.title();initialDir()
签名：
public Path initialDir();行为：返回已设置的初始目录；未设置返回 null。
示例：
Path dir = req.initialDir();extensions()
签名：
public String[] extensions();行为：返回扩展名数组的内部引用（不拷贝）；未设置返回 null。
示例：
String[] exts = req.extensions();isDirectoriesOnly()
签名：
public boolean isDirectoriesOnly();行为：是否处于只选目录模式；默认 false。
示例：
boolean dirsOnly = req.isDirectoriesOnly();hint()
签名：
public String hint();行为：返回已设置的底部说明文本；未设置返回 null。
示例：
String hint = req.hint();线程：构造与读写访问器任意线程；openFilePick 本身的线程约束见 ModContext（调用与回调都必须在游戏 GL 线程）。
稳定性：2.0 起冻结：2.x 内只增不破（禁止删签名 / 改签名 / 改语义）；破坏性变更只在 major 版本发生且须提供迁移指南与至少一个大版本的弃用期。3.x 内继续只增不破。