diff --git a/src/main/java/com/guo/learningprogresstracker/service/impl/AiServiceClient.java b/src/main/java/com/guo/learningprogresstracker/service/impl/AiServiceClient.java
index 955b445..8b9e552 100644
--- a/src/main/java/com/guo/learningprogresstracker/service/impl/AiServiceClient.java
+++ b/src/main/java/com/guo/learningprogresstracker/service/impl/AiServiceClient.java
@@ -22,6 +22,10 @@ import java.util.Optional;
/**
* lpt-ai 独立 AI 服务客户端。
*
通过 {@code lpt.ai-service.url} 配置服务地址;未配置或调用失败时返回 empty,由调用方降级。
+ * 唯一例外是 lpt-ai 明确回报任务失败({@code status=failed}):此时抛出
+ * {@link AiServiceTaskFailedException},把服务商给出的真实原因(鉴权、额度等)透传给用户,
+ * 而不是退化成一句无从下手的「AI 没有回应」。有降级形态的调用方(报告草稿、导图、回忆对比)
+ * 仍在各自 catch 里降级,行为不变。
*
* 内部使用异步任务模式:提交任务到 lpt-ai 后轮询等待结果,
* 避免同步等待 LLM 响应时阻塞 HTTP 连接。
@@ -67,6 +71,21 @@ public class AiServiceClient {
return token == null ? "" : token.trim();
}
+ /**
+ * lpt-ai 明确回报任务失败时抛出,{@code message} 是它(通常是 LLM 服务商)给出的真实原因。
+ *
+ *
与「服务不可达 / 超时 / 响应缺字段」区分开:那些属于临时故障,调用方降级或提示重试即可;
+ * 而这里是确定性原因(例如 {@code LLM 请求失败 (402): 账户余额不足}),只有把它透传出去才能定位。
+ *
+ * 继承 {@link AiTaskFailedException},因此从 AI 任务处理器抛出后,
+ * 执行器会按既有逻辑把 message 写进任务表并展示给用户。
+ */
+ public static class AiServiceTaskFailedException extends AiTaskFailedException {
+ public AiServiceTaskFailedException(String message) {
+ super(message);
+ }
+ }
+
// ============ 公开 API(签名不变,内部改为 submit + poll)============
/**
@@ -132,8 +151,9 @@ public class AiServiceClient {
/**
* 调用 lpt-ai 进行学习引导的一轮对话(复习-06)。
*
- * 学习引导允许完全依赖 AI:这条链路没有降级形态,AI 不可用时返回 empty,
- * 由调用方把任务标记为失败,前端据此把入口置为不可用。
+ * 学习引导允许完全依赖 AI:这条链路没有降级形态,拿不到回复即失败。
+ * 若失败原因是 lpt-ai 明确回报的(如额度、鉴权),异常会向上抛出让用户看到真实原因;
+ * 其余情况返回 empty,由调用方以可重试的提示文案标记失败。
*
* @param history 之前的轮次(role/content),作为多轮上下文
*/
@@ -149,6 +169,9 @@ public class AiServiceClient {
);
Optional result = submitAndWait("guidance", params);
return result.map(r -> r.path("reply").asText(null)).filter(s -> s != null && !s.isBlank());
+ } catch (AiServiceTaskFailedException e) {
+ // 服务商给了确定原因:把原因交给用户,不要退化成「AI 没有回应」
+ throw e;
} catch (Exception e) {
log.warn("lpt-ai 学习引导异常: {}", e.getMessage());
return Optional.empty();
@@ -261,7 +284,8 @@ public class AiServiceClient {
case "failed":
String err = json.path("error").asText("未知错误");
log.warn("lpt-ai 任务失败: taskId={}, error={}", taskId, err);
- return Optional.empty();
+ // 带上真实原因向上抛:调用方要么降级,要么把它展示给用户
+ throw new AiServiceTaskFailedException(err);
case "pending":
case "running":
// 还在处理,继续轮询
@@ -270,6 +294,9 @@ public class AiServiceClient {
log.warn("lpt-ai 未知任务状态: taskId={}, status={}", taskId, status);
return Optional.empty();
}
+ } catch (AiServiceTaskFailedException e) {
+ // 明确的失败原因:直接向上抛,不要当成「轮询异常」重试到超时
+ throw e;
} catch (Exception e) {
log.warn("lpt-ai 轮询异常 (第{}次): {}", pollCount, e.getMessage());
}
diff --git a/src/main/java/com/guo/learningprogresstracker/service/impl/GuidanceAiTaskHandler.java b/src/main/java/com/guo/learningprogresstracker/service/impl/GuidanceAiTaskHandler.java
index 74b2241..666d368 100644
--- a/src/main/java/com/guo/learningprogresstracker/service/impl/GuidanceAiTaskHandler.java
+++ b/src/main/java/com/guo/learningprogresstracker/service/impl/GuidanceAiTaskHandler.java
@@ -27,7 +27,9 @@ import java.util.Optional;
* 每一轮对话是一个 AI 任务:提交用户的这一轮,执行器在请求线程之外调用 AI 并把回复写回对话。
* 这样多轮对话不需要前端在请求线程里干等,也不受 AI-01 的事务约束。
*
- * 这条链路没有降级形态:AI 不可用时直接失败,前端把入口置为不可用。
+ * 这条链路没有降级形态:AI 拿不到回复就直接失败。若 lpt-ai 回报了确定原因
+ * (例如 LLM 额度不足、鉴权失败),该原因会原样写进任务表并展示给用户;
+ * 其余临时故障才用可重试的提示文案。
*/
@Slf4j
@Component
@@ -63,7 +65,7 @@ public class GuidanceAiTaskHandler implements AiTaskHandler {
List