# 写入、回读与环境状态

| 输入或阶段 | 行为 |
| --- | --- |
| model_ids省略/null/[]/仅空白 | 规范化后为空；默认模型也为空才清空配置。 |
| 空配置写入 | extra_json最终清空；但提供的非空JSON文本仍先校验。 |
| 只提供models | handler可解析但不作为写命令，可能因model_ids为空而清空。 |
| extra_json | 字段类型是string，内容需合法JSON；不要求一定为JSON对象。 |
| 空body/null或未知字段 | 普通decoder不构成严格拒绝合同，可能得到空配置；不能当探测请求。 |

请求是PUT完整替换，没有expected_version或专用回滚字段。写前须由部署配置负责人核对配置源并保存完整备份，包括查询响应中不可见的 endpoint。当前 codec 仅允许 agent_chat 配置该独占端点，包含地址、凭据和超时；API 查询和写入 DTO 均不暴露它。不要把密钥写入证据或文档。

非空模型更新也可能移除该端点，使 agent_chat 转回目录池路径。普通列表响应和操作日志不足以恢复完整路由，重新 PUT 原 model_ids/extra_json 也不能补回 endpoint。

写入后回读同一slot_id，比较当前模型顺序、默认值和额外配置，并由配置负责人确认持久化值与相关实例快照；不要只以HTTP200或日志存在判断实际使用效果。

配置owner先持久化，再重载当前进程快照，service随后另开系统事务写日志。旧注释称“同事务”不符合当前调用顺序。重载失败或后续日志失败可在持久化之后返回错误，不能承诺回滚或日志与配置一体成功。重载失败时列表可能仍来自旧快照，回读结果未变化也不能证明持久化未发生；需要配置负责人核对配置源，不自动重试。其他实例生效时机及全局并发需要实际部署验证。

操作日志不返回完整前后值。恢复须依赖配置源的完整备份和相应负责人，不能仅用本 API 响应恢复。没有本次请求的幂等或预期版本合同，恢复前还须确认没有其他管理员变更；不要覆盖未知并发写入。清空真实agent_chat等功能槽位会影响使用，不能临时发明未注册 slot_id 来隔离试验。

已请求用户更新本地凭据；

累计10认证401加一次前次公开版本200；前次自报提交与源码不同，当前部署未重核。
