chat.nvim v1.11.0 与 v1.11.1：多 API Key 透明故障转移、截断续写与工具参数归一化
内容提要
chat.nvim v1.11.0 发布，重点是提升请求稳定性与工具调用的健壮性。主要改进包括：支持多 API Key 轮换与透明故障转移，并按错误类型区分冷却时长；截断续写自动完成且不伪造用户消息；新增 mastodon、send_email 工具，write_file 支持 chmod；在入口处按 schema 归一化工具参数，修复字符串/数字比较导致的崩溃与死锁；HTTP API 支持消息搜索。测试覆盖率提升至 91%。v1.11.1 为测试稳定性补丁。
延伸解读
透明故障转移的边界：只在首个内容到达前生效
多 Key 轮换的核心不是轮询，而是失败后的处理。文章明确了一条硬约束：只有第一个内容 delta 到达之前失败，才换 Key 静默重发；一旦流式响应已吐出文字或工具调用，再换 Key 会导致屏幕出现重复输出。因此实现上用 streamed 标记区分“静默转移”与“照常报错”。这意味着用户看到的无感切换，实际依赖对可见性时机的精确判断，而非简单的重试逻辑。
错误分类决定冷却时长，顺序判断是关键
文章把错误分成 quota、rate_limit、server 三类，配额耗尽走 1 小时冷却，限流和 5xx 走 30 秒。分类靠文本模式匹配，且顺序很关键：先判限流关键字，再判配额，再判状态码。否则“429 quota exhausted”这类混合信息会被误归为短冷却，白白多打请求。配额模式表还包含中文关键字，因为国内 coding plan 的报错信息就是中文的。这提醒读者，冷却策略的有效性取决于分类是否准确。
截断续写不伪造用户消息，代价是碎片合并
续写有两种路线：追加合成的 user 消息，或原样重发当前消息列表。chat.nvim 选了后者，理由是合成消息会污染真实会话历史，也会改变角色结构，对 Anthropic 的严格交替校验更敏感。代价是多次续写产生的碎片必须合并回同一条 assistant 消息，否则历史里会出现 assistant 相邻而报错。文章还提到，续写链完成、内容完整之后才通知集成一次，避免手机端收到三段重复消息。
参数归一化在入口处统一修，而非逐个工具打补丁
模型经常违反自己的 JSON schema，文章列出两类真实事故：字符串与数字比较导致崩溃，以及“false”在 Lua 中为真值导致语义反转，例如 force="false" 反而触发强推。解法是在 dispatch 之前，用每个工具自己的 schema 归一化参数，统一纠正布尔、数字、数组和 JSON null。文章刻意不做字符串声明的反向强转，因为工具自身的校验能给出清晰错误，悄悄转换反而掩盖模型的理解错误。
Q&A
chat.nvim 的多 API Key 故障转移是怎么工作的？
配置时每个 provider 的 api_key 可以接受字符串数组，请求按 round-robin 轮询使用这些 key。如果在第一个内容 delta 到达之前请求失败（如 429/5xx），系统会静默切换到下一个 key 重发原始请求，不注入 system prompt，也不在会话历史中追加消息。转移最多尝试 #keys - 1 次，且只在内容可见前进行，避免重复输出。
为什么 chat.nvim 要对 API 错误分类并设置不同的冷却时间？
因为限流（如 QPS 超限）和配额耗尽（如账户总额度用完）是不同性质的错误。限流通常 30 秒后恢复，而配额耗尽 30 秒后重试只会浪费请求。v1.11.0 将错误分为 quota、rate_limit、server 三类，配额类使用单独的 quota_cooldown（默认 3600 秒），其他使用 token_cooldown（默认 30 秒）。分类通过文本模式匹配实现，顺序为先判限流关键字，再判配额，再判状态码，最后判服务端错误。
chat.nvim 的截断续写功能是如何避免伪造用户消息的？
当模型返回 finish_reason == "length" 时，chat.nvim 不会追加一条合成的 user 消息（如“请继续”），而是直接将当前消息列表原样重发，让模型顺着截断的 assistant 消息继续写。多次续写产生的碎片会合并回同一条 assistant 消息，以保持 Anthropic 严格的角色交替校验。续写默认开启，最多连续 3 次，可通过 continuation 配置调整。
工具参数归一化解决了哪些实际问题？
它解决了模型违反 JSON schema 导致的两类问题：一是崩溃，如字符串与数字比较抛出异常；二是语义反转，如字符串 "false" 在 Lua 中为真值导致 force="false" 被误判为强推。归一化在工具调度入口处根据每个工具自己的 schema 纠正参数类型：布尔字符串转布尔、数字字符串转数字、裸字符串转数组、丢弃 JSON null 等，避免在每个工具中重复打补丁。
工具回调崩溃导致会话死锁的问题是如何修复的？
修复分三层：1) 登记上下文，为每个 pending jobid 记录 tool_call_id 和 tool_name；2) 检测死 job 并强制收尾，取消时若 job 已退出则不再 kill，而是补一条占位 tool result 并释放 pending 记录，保持 tool_calls 历史合法；3) 回调幂等，在 callback 中先检查历史是否已有该 tool_call_id 的结果，避免重复写入。此外还修复了错误消息不落盘的问题，使重启后仍可查看失败原因。
chat.nvim 的 HTTP API 中 /messages 搜索接口怎么用？
通过 GET /messages?session=<id>&q=<query> 进行搜索，需携带 X-API-Key 头。搜索大小写不敏感、字面量子串匹配，只搜 content 和 reasoning_content 字段，返回结果对象包含 query、total、count 和 matches 数组，每条匹配包含消息序号、角色、命中字段、内容片段（约 160 字符）和创建时间。中文查询也支持。
v1.11.0 新增了哪些工具？各自有什么特点？
新增了 mastodon 和 send_email 工具，并增强了 write_file 和 fetch_web。mastodon 只读，支持 fetch（可拉取 thread）、search 和 timeline，需要 access token 进行搜索；send_email 通过 mail 命令发送邮件，参数以列表传递不经过 shell，收件地址会校验；write_file 新增 chmod 动作，支持设置文件权限；fetch_web 新增 markdown=true 参数，可将 HTML 转换为 Markdown 以减少 token 消耗。
升级到 v1.11.0 后需要注意哪些配置变化？
需要注意三点：1) 废弃模型名（glm-5.2、glm-latest、minimax-m2.7、kimi-k2.6）需替换；2) 多 key 配置是可选的，单 key 字符串配置不受影响；3) 截断续写默认开启，若希望手动控制可设置 continuation = { enable = false }。此外，v1.11.1 是测试稳定性补丁，功能无变化，升级与否不影响使用。
