# 边界、异常与恢复 [English](en/boundaries.md) · [README](../README.md) · [功能介绍](features.zh-CN.md) ## 没有建议,先看什么 没有显示不一定是故障。先看当前线程状态,再确认输入框为空、助手已正常结束、线程开关开启且不在黑名单。预测可能正在排队、已主动放弃,或被价格、用量、额度、上下文校验拦截。 | 情况 | 插件如何处理 | 用户可以怎么做 | | --- | --- | --- | | 助手报错、取消、中断、未完成 | 不启动自动预测 | 重试或继续主会话,等一次正常结束 | | 输入框已有文字、附件、IME、菜单或排队发送 | 隐藏或禁止接受,不覆盖输入 | 完成当前操作;来源仍有效时复用结果 | | 模型返回 `suggestion:false` | 本轮主动放弃,不展示 | 正常继续聊天;无需把放弃当作网络故障 | | 正在排队或生成 | 相同来源复用在途任务 | 等待结果;切换窗口不会要求重复生成 | | 用户发送下一轮 | 隐藏旧建议,等待新轮正常结束 | 无需操作 | | 切换线程、迟到响应 | 校验线程与修订,拒绝过时结果 | 查看目标线程自己的状态 | | 线程关闭或工作区/线程黑名单 | 不自动预测 | 需要时调整对应开关或黑名单 | | 无法安全读取本线程历史 | 不发送不明归属的上下文 | 检查宿主版本、会话是否加载完整;仍失败时保留状态并报告 | | 保存配置或切换思考策略 | 使有关身份重新校验,不自动重算当前轮 | 确认保存;确需新结果时主动重试 | 重新显示不等于重新生成。已经保存的建议没有按时间失效的 TTL,但不保证在来源变化后继续有效。 ## 上下文变化与日志 事件记录按**从早到晚**排列,1 是保留列表中最早的一条;只保留最近 32 条,所以编号不是全会话的永久事件 ID。当前状态描述最新状态,不代表整个过程只有一种状态。 一次普通流程通常包含:用户已发送 → 助手生成 → 正常结束 → 生成预测 → 保存结果。首次获取快照、缓存复用和队列调度可能增加记录;不能只凭日志条数判断模型调用次数。 | 事件 | 含义与边界 | | --- | --- | | 对话上下文已更新 | 有效来源变化,可能是正常工具步骤或新消息;不表示发了预测请求 | | 已记录主请求上下文快照 / 已校验映射 | 保存或核对父请求证据;不等于又调用预测模型 | | 主线程上下文已压缩 | 使用新的有效上下文重新校验;不是插件另发一次摘要请求 | | 旧预测已失效 | 原来源不再匹配;不能继续显示旧建议 | | 正在排队 | 准备调度,不是已发出请求的凭证 | | 正在生成 | 进入生成流程;实际物理尝试以账本为准 | | 已保存,可直接复用 | 结果可复用;接受前仍需校验来源与输入框 | 同一轮没有真实压缩却反复显示“已压缩”,或已保存后无来源变化仍反复生成,属于需要排查的异常,不应解释成正常省钱策略。提交问题时附前后事件、线程操作步骤和账本中的请求数量;不要只截最后一条状态。 外部插件修改早期消息时,先使旧来源失效,再重新映射。保留前缀估计低于 50% 时暂停该线程的被动预测,避免未经评估反复买冷输入。实际服务商缓存命中低与本地前缀损失是不同信号,不能混用阈值。 上下文超限时按完整消息与工具单元选择窗口。不能在限制内安全表示,或协议不能保真转换图片、工具、推理等历史时,拒绝发送。可选用兼容的后端/配置或等主线程完成有效压缩;不要为消除报错静默删除未知内容。 ## 本地检查失败 检查的是建议正文。JSON 外壳错误、语言/字形不一致、过长、控制字符、内部标记、解释性答案、明显助手视角、照抄助手,以及没有证据的价格数字,均可能导致拒绝。 默认允许一次校验修复。修复再次不合格,本轮不显示,等待用户决定是否主动重试。 - **超长**:提示前一次长度与需要减少的量;开启截断后,在上限内截断,不因长度本身再修复。截断后其他门仍要通过。 - **语言不符**:修复提示明确目标语言与字形,保留文件名、路径等标识。代码与日志不应主导用户语言判断。 - **价格/授权依据不足**:不得借修复创造证据;无法保留有依据的意图时应放弃。 - **修复输入太大**:受本地输入大小和输出预算约束,不无限把大草稿送回模型。 自动选择器比较草稿修复与父上下文方案的预计总费用。草稿修复可能减少输入,也可能失去父请求缓存;不要只比较 token 数量。关闭自动重试后,本次失败不显示建议,需用手动触发按钮处理。 这些是局部启发式检查,不是完整的语义证明、安全审查或服务端限制替代品。最终发送前仍需用户审阅。 ## 网络、协议与凭据 | 异常 | 自动行为 | 恢复方式 | | --- | --- | --- | | 超时、连接中断、408、429、5xx 等暂时错误 | 自动重试开启时,整个生成任务最多额外 3 次网络重试 | 先看用量是否结算;恢复后主动重试 | | 服务商要求等待 | 尊重 Retry-After;超过配置等待预算则停止 | 稍后手动重试 | | 400/401/403/404/413/422、凭据缺失、未知模型、上下文超限 | 不作为临时网络错误反复重试 | 修正端点、凭据引用、模型或上下文配置 | | 证书验证失败 | 不关闭证书验证绕过 | 修复证书或网络配置 | | 协议能力不支持、历史无法转换 | 不静默切换协议或删减信息重发 | 声明正确能力或使用兼容协议 | | 请求已发出但最终 usage 不全 | 标为未结算,停止后续自动请求 | 保留账本,核对服务商用量与诊断 | 网络重试上限是**整个任务共用**的,不是每次校验修复都重新获得 3 次。在用量可结算且其他门都通过的前提下,初次请求 + 一次修复 + 最多 3 次网络重试,最多 5 次物理尝试;失败不保证免费。默认退避从 400ms 开始,最多 10 秒,且可取消。 第三方支持模型调用,不代表支持余额查询、缓存控制、缓存细项或官方价表。按已声明能力发送参数;不猜余额地址,不付费探测可选能力。未知模型的思考参数需按协议声明;不能把“最低”写成“一定无推理”。 ## 额度不足与恢复 只有主会话或 Prediction **明确收到额度不足拒绝**,才开启该账户路由的恢复监测;不是看到一般网络错误就查余额。 1. 暂停该账户的被动预测,保存仍可能恢复的等待来源。 2. 有支持的余额接口时,在逻辑检查点合并查询;不按秒轮询,也不通过付费生成探测余额。 3. 确认额度恢复,或一次模型请求成功后,结束此次监测;仅恢复仍满足来源、开关等条件的等待项。 余额接口不支持或查询失败表示**未知**,不等于余额为零。主动重试在额度这一层一直允许,便于充值后继续;但不能绕过黑名单、来源校验、价格和未结算用量等限制。重复点击不应被当作自动恢复方案。 “已识别的余额不足拒绝请求(未生成)”用于区分明确拒绝与可能已消费但未结算的失败;它不是永久禁用标记。只有有证据的未生成拒绝才按该类别统计。 ## 费用与占比排查 **Prediction /(主会话 + Prediction)**,必须使用同一币种、同一覆盖范围。所有实际预测尝试分别计入,包括手动重试和修复。 | 现象 | 原因与处理 | | --- | --- | | 有金额但占比是“—” | 已知小计不等于完整合计;检查历史缺价、缺用量及覆盖提示 | | 未定价请求 | 不补零。旧记录缺价与新请求发送前缺价要分开;新预测应在发送前拦截 | | 未结算请求 | 可能已有消费;阻止自动重复调用,保留证据 | | 只缺缓存细项 | 缓存命中保持未知;按已有总量与价表给出上界/区间 | | CNY、USD 等多币种 | 分别计算,不隐含汇率合并 | | 换价或峰谷时段变化 | 按各请求开始时保存的价表和时段核对,不用最新价重写所有历史 | | 安装前历史不完整 | 查看与其分开的安装后完整覆盖统计;不能声称完整会话占比 | 例如已知主会话 1.549872 元、Prediction 0.029572 元,已知小计的比值约 **1.8723%**。若另有 91 个未定价请求,这只是已知部分的比值,不能称为全会话的准确占比。 账本是根据服务商 usage 与价表计算的估算,不是服务商结算单。不要删账本、把未知设为零或忽略修复费用来“修好”占比。 ## 排查与报告 记录插件/DSH 版本、所用协议、模型、脱敏后的端点类型、当前状态、操作顺序、对应请求数量和错误码。比较“事件数”与“物理请求数”,后者才用于核对是否重复消费。不要公开 API key、完整请求、聊天快照或整个插件数据目录。 [架构](architecture.zh-CN.md) 说明映射、选择器与账本分层;[验证范围](verification.zh-CN.md) 区分回归、组件截图与实时服务商实测。CI 使用模拟模型/网络,不证明实时余额、缓存存续或建议质量;展示截图中的演示金额不是省钱实测结果。