运行时配置

状态：运行中 (Running)。运行时配置合约 (K-CFG-001..K-CFG-011) 规定了规范配置路径、源优先级、模式版本控制、密钥策略和重新加载边界。

运行时从一个具有明确源优先级的规范路径读取配置。配置验证失败时关闭；重新加载边界是明确的。没有隐式的热重载。

规范配置路径

规则	值
规范路径	`~/.nimi/config.json`
旧路径	不读取

运行时不参考旧的配置位置。迁移的机器必须将其配置移动到规范路径。

源优先级

源按固定优先级顺序解析：

环境变量 > 配置文件 > 内置默认值

环境变量覆盖配置文件中的值。配置文件中的值覆盖内置默认值。

模式版本

规则	值
必需字段	`schemaVersion`
当前版本	`1`
未知字段	向前兼容忽略

没有 schemaVersion 的配置不会加载。向前兼容的姿态允许旧的运行时忽略新字段而不崩溃。

提供商名称规范化

配置中的提供商名称必须使用 provider-catalog.yaml 中的规范值。别名和旧名称将被拒绝。这防止了两个配置以不同方式拼写同一个提供商并静默路由到不同路径的情况。

密钥策略

规则	值
每个提供商选择一个	`apiKey` 或 `apiKeyEnv`
两者都设置	拒绝
推荐	环境变量或系统安全存储
`apiKey` 内联	仅作为规范配置文件的回退允许

面向用户的工具应优先使用环境变量或安全存储。内联 apiKey 在规范配置文件中作为回退保留，因为某些引导流程需要该值在守护进程重启后仍然存在，但推荐使用 apiKeyEnv 和安全存储。

原子写入

配置写入使用 临时文件 + 重命名 原子写入。崩溃的写入不会留下半写入的配置；要么新的配置原子性地写入成功，要么旧的配置仍然在位。

运行时命令界面

config init / validate / get / set 行为必须符合此合约。错误会发出统一的原因代码；部分成功返回不被接受。

验证失败关闭

规则	值
验证失败	失败关闭 —— 运行时不会启动核心路径
部分成功	不被接受

一个包含无效字段的配置不会部分工作。运行时拒绝启动核心执行路径，直到配置验证通过。

提供商环境绑定

从提供商到其 baseUrl / apiKey 环境变量名称的映射位于 provider-probe-targets.yaml 中。配置合约不内联此映射。

热重载边界 (K-CFG-010)

本页最重要的规则：

在运行时生效与仅在重启时生效的配置更改必须明确声明。隐式热重载不被接受。

配置字段要么被文档化为可热重载，要么不是。依赖于某事物是否“有时”热重载的行为是此规则要防止的错误模式。

凭据平面边界 (K-CFG-011)

配置层接受凭据引用，并在规范配置文件中接受内联密钥回退。更高级别的安装和配置入口点必须优先使用环境变量/安全存储路径。

对于公共 CLI 首次运行，如果发生交互式凭据捕获，则用户粘贴的提供商密钥必须立即写入规范的机器配置。相同的引导 run 不能仅使用“仅本次调用的内联内存凭据”成功。路径必须：

警告内联密钥风险
继续推荐 apiKeyEnv / 安全存储
如果写入失败则关闭失败 —— 无继续生成云

当前调用可以继续使用内联元数据到已经运行的守护进程（避免假设守护进程已热重载），但持久化的真相是规范配置。

读者场景：初始配置

用户运行 config init。 运行时写入一个新的 ~/.nimi/config.json，其中包含 schemaVersion: 1 和内置默认值。
用户设置提供商。 config set 使用 provider-catalog.yaml 中的规范名称写入提供商条目。
用户添加 API 密钥。 工具首先提示 apiKeyEnv；如果用户坚持内联，则值存储在 apiKey 下，并建议切换到环境变量。
用户启动守护进程。 进行验证；通过；守护进程进入服务。

读者场景：启动时验证失败

守护进程启动。 读取 ~/.nimi/config.json。
验证失败。 提供商名称是旧别名。
失败关闭。 守护进程拒绝进入服务。原因代码精确定位问题。
用户修复。 将提供商名称更新为规范名称；重新运行 config validate；重启守护进程。

守护进程不会“禁用坏的提供商部分启动”。

读者场景：热重载问题

用户更改了一个配置字段并询问：这个更改现在生效吗？

检查字段的文档化重新加载边界。 如果文档化为可热重载，运行时应用它；订阅的子系统重新读取。
如果文档化为仅重启生效， 用户必须重启守护进程才能使更改生效。
如果没有明确声明， 字段不假定为可热重载 —— 合约要求明确声明。

此规则使配置行为在升级过程中可预测。