# update-cache 的 arity 语义与入口模式契约

原 `--update-cache` 是独立模式：扫源目录强制重取全部唯一查询后立即退出，从不整理文件；而预期语义是"整理媒体文件时更新对应的缓存"。决定：`--update-cache` 降为修饰标志，行为形状由目录个数推导——只给 1 个目录（位置参数或 `--src-dir`）＝仅刷缓存后退出（保留原 `update_cache()` 行为）；给 2 个目录＝整理流水线内对处理的条目强制重取、不提前退出。

模式契约同步收紧：`list` / `organize` / `cache-only` 三种形状一次调用只取其一，冲突（如 `--update-cache --list-cache`）硬报错并附 usage，废弃原先"看似生效实则静默忽略"的分发顺序。用法错误（未知选项、参数个数、模式冲突）统一 `exit 2`（GNU 惯例），运行期错误保持 `exit 1`。目录只能走一个通道：2 个位置参数或 `--src-dir` + `--dest-dir`，不可混用；每种形状声明所需目录数：`organize`=2、`cache-only`=1、`list`=0，多传少传均报错。

**Considered Options**: 保持独立标志 + main() 内隐式优先级（原状）——冲突静默，用户无法感知标志未生效。混合通道——无真实用例，徒增解析复杂度。