models.toml：模型目录与任务分档¶

真实文件是 config/models.toml。先在厂商配置建立连接，再添加模型。 面板「模型与厂商」维护目录，「功能分配」给任务选择候选。 逐字段说明见模型模板。

模型名、真实 ID 与连接¶

每个 [[models]] 是一条模型目录记录。 name 是本地引用名，model_identifier 是服务商接口接受的真实 ID。 api_provider 指向厂商条目的 name，不是厂商预设标识。 换模型版本通常只改真实 ID；改本地名称才需要更新任务候选。

visual = true 声明该模型可接收图片，是视觉候选的准入条件。 不能通过给纯文本模型勾选视觉能力，让它获得真实图片理解能力。 价格字段只是面板计费参考，不会改变接口计费或自动选出最便宜模型。 embedding_dim 只用于嵌入模型，必须对应接口实际返回的维度。

首装预填的六档¶

六个条目都引用 dashscope 这一条百炼连接。 下表是随本版本代码分发的配置，不是远端实时模型清单。

记忆抽取在后台执行，但错误事实会影响后续召回，模型选择仍需保证判断质量。 语音任务 tts 默认没有候选；语音、视觉、向量功能仍各有独立开关。 新增模型不会自动出现在任务里，要把本地名称加入对应 model_list。 实际模型权限与 ID 是否可调用，需使用实际密钥验证。

任务候选与继承¶

chat 至少保留一个候选。 planner、replyer、scene、proactive、summary、memory、schedule、expression 留空时， 继承 chat 的候选和挑选策略；各自的首字超时与慢阈值仍按各自任务设置。 vision、tts、embedding 不继承 chat；候选列表为空时，对应任务没有可用模型。

因此「清空摘要候选」不等于关闭摘要，而是改用对话模型做摘要。 要关某项能力，检查相应功能开关，而不是随意清空候选。 任务段名写错会被拒绝，不会当作新任务接受。

三种挑选策略¶

只有顺序策略下，拖动候选顺序才决定首选。 只配一个候选时，换策略不会凭空增加备用线路。 熔断按厂商连接归组；同一连接下放多个模型不能隔离厂商整体故障。 要有独立连接的候选，必须先配置另一条真实可用的厂商连接。

首字超时、慢阈值与网络超时¶

first_token_timeout_ms 默认 30000，是当前候选开始输出前的切换窗口。 该窗口包含连接的首字等待与内部重试；超时后尝试下一个候选。 它不是完整一轮对话的总时长，也不是前端打字气泡的等待上限。

slow_threshold_ms 默认 8000，只记录响应偏慢，不会在 8 秒时主动切换。 它必须小于首字超时，设 0 才是关闭慢响应记账。 厂商的 timeout_ms 管网络连接与读取，默认 120000，见厂商配置。 仅增大网络超时，不会延长任务自身配置的首字等待窗口。 已经输出的普通流式内容不会因中途断流而从头自动重试，以免重复输出。

生成参数与思考开关¶

[generation.<任务>] 控制该任务温度与输出上限。 模板当前统一温度为 0.85、max_tokens = 0，0 表示不另设输出上限。 注释中的「稳定」描述不改变实际参数值，任务温度应以配置为准。 模型条目的 temperature、max_tokens 可覆盖任务值，排查时须同时核对两级配置。

思考开关是厂商请求参数，放在模型条目的 extra_body。 本版本五个文本或视觉模型预填：

extra_body = { enable_thinking = false }

嵌入模型的模板实际为 extra_body = {}；嵌入请求不透传此字段。 任务或模型的顶层 thinking 字段已取消，继续使用会导致加载失败。 reasoning_parse_mode 只改变返回思考内容的解析方式，设 none 不会关闭厂商思考。 换厂商时核对它接受的请求体格式，不能保证同一键名适用于所有接口。

嵌入模型的特殊边界¶

同一 embedding 任务的候选必须具有相同正维度。 填 embedding_dim = 1024 是本地声明，不会强制远端输出 1024 维。 当前嵌入请求只发送模型与输入，无法用 extra_body.dimensions 调整输出维度。 更换嵌入模型还会改变向量空间，即使维度相同也不应直接混用旧向量。 先保留数据库与索引，按开发手册：记忆模块核对重建要求。

修改后核对¶

保存并重启后端，检查启动模型路由是否列出预期名称。 再发一轮消息，在会话观察与调用记录中确认实际使用的任务和候选。 连接测试或拉取模型列表成功，不能替代该模型的一轮真实请求。 调用失败时，应依据模型 ID、能力声明及厂商返回信息确定原因，再评估是否调整超时。