CONCEPT
配置优先级
定义
配置优先级是 Hyper-Extract CLI 处理同一配置项的多种来源时采用的覆盖规则。其优先级从高到低依次为：命令行参数、环境变量、配置文件。当多个来源同时指定 API key、模型、连接地址等设置时，较高优先级的值生效。
在本文档中的语境
在 CLI Configuration Reference 摘要 所述的 CLI 配置机制中，he config init 会创建持久化配置文件：Linux/macOS 默认位于 ~/.he/config.toml，Windows 默认位于 %USERPROFILE%\.he\config.toml。该文件适合保存日常使用的默认配置；环境变量和命令行标志则用于在不必修改该默认配置的前提下提供替代值。
覆盖机制
配置解析按以下顺序决定最终值：
- 配置文件提供最低优先级的持久化默认值。
- 环境变量可作为配置文件的回退或覆盖来源；当环境变量与配置文件都提供同一项时，环境变量生效。
- 命令行参数优先级最高；当命令行标志与环境变量或配置文件冲突时，以本次命令传入的标志为准。
因此，环境变量并非不可再覆盖的最终配置：它会覆盖配置文件，但仍会被命令行参数覆盖。
使用场景
- 临时切换 API key，而不改写配置文件中的默认凭据。
- 在 CI/CD 环境中通过环境变量注入密钥，避免将密钥写入仓库、脚本或配置文件。
- 为单次命令传入不同的凭据、模型或连接参数，并让该次运行覆盖环境变量和持久化默认值。
- 保留适合本机长期使用的默认配置，同时允许自动化任务使用独立的密钥与连接参数。
细节与边界
配置优先级只解决“同一设置由多个来源提供”时应采用哪个值的问题，不保证提供的值本身有效。例如，若模型名在目标平台不存在，仍可能出现模型不存在或 404 错误；若 API key 未在最终生效的配置中提供，则仍会导致 API key 缺失。
对包含密钥的配置而言，环境变量适合安全注入和临时替换，但命令行参数具有更高优先级；执行自动化任务时应确认命令行中没有意外传入冲突的标志。需要恢复默认状态时，可使用 he config llm --unset 或 he config embedder --unset 清除相应配置。