[Feature]: agent_core 模型调用错误分类与弹性重试-agent-core-java-AtomGit

已开启

[Feature]: agent_core 模型调用错误分类与弹性重试 #191

chenxiying创建于 18 天前

chenxiying成员

18 天前创建

Paired: GitHub #363 ↔ GitCode #191

🚀 背景描述

要做什么:为 core 新建模型调用错误的统一分类与分级重试机制。这是一项 core 当前不具备的能力(功能缺失),顺带修复一个既有缺陷(重试配置空转)。

当前现状(各分支均存在,非特定版本问题):

模型调用失败没有分类:任何一次模型调用(非流式/流式)的失败,都以不带类型的裸异常穿透主链。限流(429)、欠费(402)、认证失效(401/403)、服务端临时故障(5xx)、网络抖动、用户取消——这些性质完全不同的失败被一锅烩。
重试配置是空转的:模型客户端存在"最大重试次数"配置字段,但全链路没有消费方,配置了不生效。
后果:网络抖一次,整轮任务直接失败;不可重试的错误(欠费、认证失效)上无法快速失败;上层与运维无法区分"等一下再试"和"重试也没用",错误表面不可程序消费。

工程实践的成熟解法是分类驱动处置:错误先按性质归并类别,再按类别决定退避重试、降温等待还是立即失败。本特性即把这套机制内建于 core。

设计思路

按"痛点 → 机制"设计,所有模型客户端实现(含两条 HTTP 栈)同步接入:

痛点	对应机制	关键点
失败无分类、裸异常穿透	统一错误分类	五类基础分类:限流/欠费/认证永久失效/临时故障/用户取消;另加第六个可判定扩展类别"上下文超限"(提示词过长被拒,不做普通重试,干净浮出)。分类为纯规则映射(HTTP 状态码 + 错误消息关键词组合),不调用模型、不引入外部组件;规则可随服务商差异持续补充,分类集合保持稳定
可重试的错误没人重试	分类驱动自动重试	限流、临时故障按退避策略自动重试(默认至多 2 次,可配置);欠费、认证永久失效、上下文超限、用户取消绝不重试;重试不推进主循环轮次计数,不消耗任务轮次预算
重试配置空转	接线既有配置字段	"最大重试次数"被真实消费,默认值对齐承诺(2 次),配置语义与实际行为一致
流式重试会重复产出	首段判定线	流式调用以"首段数据到达"为重试分界:首段前失败可整次重试;首段后中断不自动重试,按分类浮出处置;HTTP 200 内嵌错误体与流中错误帧(`data: {"error":...}`)必须识别并上浮为带分类异常,不得当空数据段静默吞掉
取消被当故障重试	取消/中断特判	用户取消在任何路径绝不重试、不计入失败统计、干净退出;取消与超时同型异常的区分规则显式定义并文档化;人在环中断类异常是控制流不是故障,必须优先识别并原样放行
错误表面不可程序消费	标准错误码映射	各类别映射统一错误码模型段(181xxx),限流与欠费为新增错误码;控制流按分类类型判定,不按错误码分支;欠费与认证失效产出用户可读说明与修复建议

处置原则:任何模型调用失败离开客户端层前必须携带分类结果;可重试类在重试包装内自动恢复(用户最多感到一次停顿),不可重试类直接形成用户可读的错误表面,裸异常不再穿透主链。

涉及到的对外API

错误分类 SPI:模型客户端层与重试机制之间的统一分类接入点;输入为原始异常/响应事实,输出为分类结果与可恢复性标记;中断类异常不经分类,原样穿透。
重试配置项:最大重试次数(默认 2)、各可重试类别的重试使能;只增量演进,不改既有配置项名称与语义。
错误码:模型段 181xxx,限流与欠费错误码为新增并在错误码规范登记;错误表面携带错误码与可程序化判定的分类信息。
取消识别规则:作为公开行为契约文档化。

测试设计与测试计划

覆盖:五类基础分类与"上下文超限"扩展类别各一条端到端路径;非流式限流/5xx 自动重试与耗尽后失败表面;欠费/认证失效不重试且产出用户可读文案;流式首段前重试、首段后不重试;流中错误帧与 HTTP 200 内嵌错误体上浮;用户取消不重试不计数干净退出;中断类异常放行;重试配置非默认值严格生效;取消与超时同型异常的区分;分类结果、错误码、重试次数在日志与可观测结果中稳定呈现。
计划:分类 SPI 与五类基础分类先行 → 重试机制与既有配置接线 → 流式判定线与错误帧上浮 → 取消/中断特判。