实现Debug EML实时Trace调试链路

2026-07-12 14:59:03 +08:00
parent eee37315a0
commit 8d8fae670a
20 changed files with 1571 additions and 76 deletions
--- a/server/src/main/java/cn/nianxx/thhotel/integrations/ai/superagent/common/result/SuperAgentOpenApiResult.java
+++ b/server/src/main/java/cn/nianxx/thhotel/integrations/ai/superagent/common/result/SuperAgentOpenApiResult.java
@@ -1,5 +1,6 @@
 package cn.nianxx.thhotel.integrations.ai.superagent.common.result;

+import com.fasterxml.jackson.annotation.JsonProperty;
 import java.util.List;

 /**
@@ -15,6 +16,7 @@ import java.util.List;
 * @param outputTokens 输出 token 数
 * @param totalTokens 总 token 数
 * @param eventTypes SSE 事件类型列表
+ * @param traceEvents SuperAgent 公开 Trace 事件列表，只包含可展示摘要字段
 */
 public record SuperAgentOpenApiResult(
        String sessionId,
@@ -26,6 +28,44 @@ public record SuperAgentOpenApiResult(
        Integer inputTokens,
        Integer outputTokens,
        Integer totalTokens,
-        List<String> eventTypes
+        List<String> eventTypes,
+        @JsonProperty("trace_events")
+        List<SuperAgentOpenApiTraceEvent> traceEvents
 ) {
+
+    /**
+     * 兼容未启用 Trace 的历史调用方。
+     */
+    public SuperAgentOpenApiResult(
+            String sessionId,
+            String runId,
+            String profileId,
+            String profileVersionId,
+            String modelName,
+            String rawAnswer,
+            Integer inputTokens,
+            Integer outputTokens,
+            Integer totalTokens,
+            List<String> eventTypes) {
+        this(
+                sessionId,
+                runId,
+                profileId,
+                profileVersionId,
+                modelName,
+                rawAnswer,
+                inputTokens,
+                outputTokens,
+                totalTokens,
+                eventTypes,
+                List.of());
+    }
+
+    /**
+     * 复制集合，避免结果对象被调用方后续修改。
+     */
+    public SuperAgentOpenApiResult {
+        eventTypes = eventTypes == null ? List.of() : List.copyOf(eventTypes);
+        traceEvents = traceEvents == null ? List.of() : List.copyOf(traceEvents);
+    }
 }
--- a/server/src/main/java/cn/nianxx/thhotel/integrations/ai/superagent/common/result/SuperAgentOpenApiTraceEvent.java
+++ b/server/src/main/java/cn/nianxx/thhotel/integrations/ai/superagent/common/result/SuperAgentOpenApiTraceEvent.java
@@ -0,0 +1,37 @@
+package cn.nianxx.thhotel.integrations.ai.superagent.common.result;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/**
+ * SuperAgent Open API 公开 Trace 事件。只保留对外策略允许的摘要字段，不保存原始工具入参、Secret 或 Cookie。
+ *
+ * @param event SuperAgent 公开 trace 事件类型
+ * @param runId SuperAgent run ID
+ * @param messageId AI message ID
+ * @param toolCallId 工具调用 ID
+ * @param toolName 工具名称
+ * @param text 公开推理或进度摘要
+ * @param inputSummary 工具入参摘要
+ * @param outputSummary 工具输出摘要
+ * @param status 运行或任务状态
+ * @param ts SuperAgent 事件时间戳
+ */
+public record SuperAgentOpenApiTraceEvent(
+        String event,
+        @JsonProperty("run_id")
+        String runId,
+        @JsonProperty("message_id")
+        String messageId,
+        @JsonProperty("tool_call_id")
+        String toolCallId,
+        @JsonProperty("tool_name")
+        String toolName,
+        String text,
+        @JsonProperty("input_summary")
+        String inputSummary,
+        @JsonProperty("output_summary")
+        String outputSummary,
+        String status,
+        String ts
+) {
+}
--- a/server/src/main/java/cn/nianxx/thhotel/integrations/ai/superagent/service/SuperAgentOpenApiClient.java
+++ b/server/src/main/java/cn/nianxx/thhotel/integrations/ai/superagent/service/SuperAgentOpenApiClient.java
@@ -2,6 +2,8 @@ package cn.nianxx.thhotel.integrations.ai.superagent.service;

 import cn.nianxx.thhotel.integrations.ai.superagent.common.request.SuperAgentMailDebugRequest;
 import cn.nianxx.thhotel.integrations.ai.superagent.common.result.SuperAgentOpenApiResult;
+import cn.nianxx.thhotel.integrations.ai.superagent.common.result.SuperAgentOpenApiTraceEvent;
+import java.util.function.Consumer;

 /**
 * SuperAgent Open API 客户端端口。业务层只依赖该接口，不直接拼 HTTP 或解析 SSE。
@@ -11,5 +13,15 @@ public interface SuperAgentOpenApiClient {
    /**
     * 创建 SuperAgent session 并发送邮件 Debug 消息，返回最终 AI 回答。
     */
-    SuperAgentOpenApiResult invokeMailDebug(SuperAgentMailDebugRequest request);
+    default SuperAgentOpenApiResult invokeMailDebug(SuperAgentMailDebugRequest request) {
+        return invokeMailDebug(request, traceEvent -> {
+        });
+    }
+
+    /**
+     * 创建 SuperAgent session 并发送邮件 Debug 消息，边解析边回调公开 Trace 事件。
+     */
+    SuperAgentOpenApiResult invokeMailDebug(
+            SuperAgentMailDebugRequest request,
+            Consumer<SuperAgentOpenApiTraceEvent> traceConsumer);
 }
--- a/server/src/main/java/cn/nianxx/thhotel/integrations/ai/superagent/service/impl/SuperAgentOpenApiClientImpl.java
+++ b/server/src/main/java/cn/nianxx/thhotel/integrations/ai/superagent/service/impl/SuperAgentOpenApiClientImpl.java
@@ -2,16 +2,22 @@ package cn.nianxx.thhotel.integrations.ai.superagent.service.impl;

 import cn.nianxx.thhotel.integrations.ai.superagent.common.request.SuperAgentMailDebugRequest;
 import cn.nianxx.thhotel.integrations.ai.superagent.common.result.SuperAgentOpenApiResult;
+import cn.nianxx.thhotel.integrations.ai.superagent.common.result.SuperAgentOpenApiTraceEvent;
 import cn.nianxx.thhotel.integrations.ai.superagent.service.SuperAgentOpenApiClient;
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
+import java.io.InputStreamReader;
+import java.nio.charset.StandardCharsets;
 import java.util.LinkedHashMap;
 import java.util.Map;
 import java.util.UUID;
+import java.util.function.Consumer;
 import org.springframework.http.client.SimpleClientHttpRequestFactory;
 import org.springframework.http.MediaType;
 import org.springframework.stereotype.Service;
+import org.springframework.util.StreamUtils;
 import org.springframework.web.client.RestClient;
+import org.springframework.web.client.RestClientResponseException;

 /**
 * SuperAgent Open API HTTP 客户端实现。负责创建 session、发送 SSE 消息和解析最终回答。
@@ -39,7 +45,9 @@ public class SuperAgentOpenApiClientImpl implements SuperAgentOpenApiClient {
     * 调用 SuperAgent Open API 邮件 Debug 流程；配置缺失时直接失败，避免静默跳过真实调用。
     */
    @Override
-    public SuperAgentOpenApiResult invokeMailDebug(SuperAgentMailDebugRequest request) {
+    public SuperAgentOpenApiResult invokeMailDebug(
+            SuperAgentMailDebugRequest request,
+            Consumer<SuperAgentOpenApiTraceEvent> traceConsumer) {
        validateProperties();
        try {
            RestClient restClient = RestClient.builder()
@@ -47,8 +55,7 @@ public class SuperAgentOpenApiClientImpl implements SuperAgentOpenApiClient {
                    .requestFactory(requestFactory())
                    .build();
            String sessionId = createSession(restClient, request);
-            String sseBody = sendMessage(restClient, sessionId, request);
-            return sseParser.parse(sessionId, sseBody);
+            return sendMessage(restClient, sessionId, request, traceConsumer);
        } catch (SuperAgentOpenApiException exception) {
            throw exception;
        } catch (Exception exception) {
@@ -86,24 +93,46 @@ public class SuperAgentOpenApiClientImpl implements SuperAgentOpenApiClient {
    }

    /**
-     * 发送 Debug 邮件消息并读取 SSE 文本响应。
+     * 发送 Debug 邮件消息并流式解析 SSE 文本响应。
     */
-    private String sendMessage(RestClient restClient, String sessionId, SuperAgentMailDebugRequest request) {
+    private SuperAgentOpenApiResult sendMessage(
+            RestClient restClient,
+            String sessionId,
+            SuperAgentMailDebugRequest request,
+            Consumer<SuperAgentOpenApiTraceEvent> traceConsumer) {
        String csrfToken = UUID.randomUUID().toString();
        Map<String, Object> body = new LinkedHashMap<>();
        body.put("message", request.message());
        body.put("idempotency_key", request.idempotencyKey() + "-message");
        body.put("metadata", request.metadata());
        return restClient.post()
-                .uri("/api/open/agent-sessions/{sessionId}/messages/stream", sessionId)
+                .uri(uriBuilder -> uriBuilder
+                        .path("/api/open/agent-sessions/{sessionId}/messages/stream")
+                        .queryParam("include_trace", "true")
+                        .build(sessionId))
                .contentType(MediaType.APPLICATION_JSON)
                .accept(MediaType.TEXT_EVENT_STREAM)
                .header("Authorization", "Bearer " + properties.getApiKey())
                .header("X-CSRF-Token", csrfToken)
                .header("Cookie", "csrf_token=" + csrfToken)
                .body(body)
-                .retrieve()
-                .body(String.class);
+                .exchange((clientRequest, clientResponse) -> {
+                    if (!clientResponse.getStatusCode().is2xxSuccessful()) {
+                        byte[] responseBody = StreamUtils.copyToByteArray(clientResponse.getBody());
+                        throw new RestClientResponseException(
+                                "SuperAgent Open API HTTP 调用失败。",
+                                clientResponse.getStatusCode(),
+                                clientResponse.getStatusText(),
+                                clientResponse.getHeaders(),
+                                responseBody,
+                                StandardCharsets.UTF_8);
+                    }
+                    try (InputStreamReader reader = new InputStreamReader(
+                            clientResponse.getBody(),
+                            StandardCharsets.UTF_8)) {
+                        return sseParser.parse(sessionId, reader, traceConsumer);
+                    }
+                });
    }

    /**
--- a/server/src/main/java/cn/nianxx/thhotel/integrations/ai/superagent/service/impl/SuperAgentOpenApiSseParser.java
+++ b/server/src/main/java/cn/nianxx/thhotel/integrations/ai/superagent/service/impl/SuperAgentOpenApiSseParser.java
@@ -1,12 +1,19 @@
 package cn.nianxx.thhotel.integrations.ai.superagent.service.impl;

 import cn.nianxx.thhotel.integrations.ai.superagent.common.result.SuperAgentOpenApiResult;
+import cn.nianxx.thhotel.integrations.ai.superagent.common.result.SuperAgentOpenApiTraceEvent;
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
+import java.io.BufferedReader;
+import java.io.IOException;
+import java.io.Reader;
+import java.io.StringReader;
 import java.util.ArrayList;
 import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Set;
+import java.util.function.Consumer;
+import java.util.regex.Pattern;
 import org.springframework.stereotype.Component;

 /**
@@ -15,6 +22,13 @@ import org.springframework.stereotype.Component;
@Component
 public class SuperAgentOpenApiSseParser {

+    private static final Pattern JSON_SECRET_PATTERN = Pattern.compile(
+            "(?i)(\"(?:api[_-]?key|token|secret|password|cookie|authorization)\"\\s*:\\s*\")[^\"]*(\")");
+    private static final Pattern HEADER_SECRET_PATTERN = Pattern.compile(
+            "(?i)((?:authorization|cookie)\\s*:\\s*)[^\\s,;]+");
+    private static final Pattern TEXT_SECRET_PATTERN = Pattern.compile(
+            "(?i)((?:api[_-]?key|token|secret|password)\\s*[=:]\\s*)[^\\s,;}]+");
+
    private final ObjectMapper objectMapper;

    /**
@@ -35,18 +49,50 @@ public class SuperAgentOpenApiSseParser {
     * 解析 SSE 文本，返回最终 AI 回答和调用元数据。
     */
    public SuperAgentOpenApiResult parse(String sessionId, String sseBody) {
+        return parse(sessionId, sseBody, traceEvent -> {
+        });
+    }
+
+    /**
+     * 解析 SSE 文本，边解析边回调 SuperAgent 公开 Trace 事件。
+     */
+    public SuperAgentOpenApiResult parse(
+            String sessionId,
+            String sseBody,
+            Consumer<SuperAgentOpenApiTraceEvent> traceConsumer) {
        if (sseBody == null || sseBody.isBlank()) {
            throw new SuperAgentOpenApiException("SuperAgent SSE 响应为空。");
        }
+        return parse(sessionId, new StringReader(sseBody), traceConsumer);
+    }
+
+    /**
+     * 从 Reader 流式解析 SSE，适用于 Open API 长连接响应。
+     */
+    public SuperAgentOpenApiResult parse(
+            String sessionId,
+            Reader reader,
+            Consumer<SuperAgentOpenApiTraceEvent> traceConsumer) {
+        if (reader == null) {
+            throw new SuperAgentOpenApiException("SuperAgent SSE 响应为空。");
+        }
        Set<String> eventTypes = new LinkedHashSet<>();
        ParsedState state = new ParsedState();
-        for (SseEvent event : splitEvents(sseBody)) {
-            eventTypes.add(event.eventType());
-            consumeEvent(event, state);
-            if (state.endSeen) {
-                break;
-            }
+        try {
+            parseLines(reader, event -> {
+                eventTypes.add(event.eventType());
+                consumeEvent(event, state, safeTraceConsumer(traceConsumer));
+            }, state);
+        } catch (IOException exception) {
+            throw new SuperAgentOpenApiException("SuperAgent SSE 读取失败。", exception);
        }
+        return buildResult(sessionId, eventTypes, state);
+    }
+
+    /**
+     * 汇总解析状态并生成结果对象。
+     */
+    private SuperAgentOpenApiResult buildResult(String sessionId, Set<String> eventTypes, ParsedState state) {
        if (!state.endSeen) {
            throw new SuperAgentOpenApiException("SuperAgent SSE 未收到结束事件。");
        }
@@ -70,13 +116,17 @@ public class SuperAgentOpenApiSseParser {
                state.inputTokens,
                state.outputTokens,
                state.totalTokens,
-                List.copyOf(eventTypes));
+                List.copyOf(eventTypes),
+                List.copyOf(state.traceEvents));
    }

    /**
     * 消费单个 SSE 事件。
     */
-    private void consumeEvent(SseEvent event, ParsedState state) {
+    private void consumeEvent(
+            SseEvent event,
+            ParsedState state,
+            Consumer<SuperAgentOpenApiTraceEvent> traceConsumer) {
        try {
            if ("end".equals(event.eventType())) {
                state.endSeen = true;
@@ -94,6 +144,9 @@ public class SuperAgentOpenApiSseParser {
            if ("values".equals(event.eventType())) {
                consumeValuesEvent(data, state);
            }
+            if ("trace".equals(event.eventType())) {
+                consumeTraceEvent(data, state, traceConsumer);
+            }
        } catch (Exception exception) {
            throw new SuperAgentOpenApiException("SuperAgent SSE JSON 解析失败。", exception);
        }
@@ -159,31 +212,96 @@ public class SuperAgentOpenApiSseParser {
    }

    /**
-     * 拆分 SSE 事件块，支持多行 data。
+     * 消费公开 Trace 事件，只提取可展示摘要字段。
     */
-    private List<SseEvent> splitEvents(String sseBody) {
-        String[] blocks = sseBody.split("\\R\\s*\\R");
-        List<SseEvent> events = new ArrayList<>();
-        for (String block : blocks) {
-            String eventType = "message";
-            StringBuilder data = new StringBuilder();
-            for (String line : block.split("\\R")) {
-                if (line.startsWith("event:")) {
-                    eventType = line.substring("event:".length()).trim();
-                    continue;
-                }
-                if (line.startsWith("data:")) {
-                    if (!data.isEmpty()) {
-                        data.append('\n');
-                    }
-                    data.append(line.substring("data:".length()).trim());
-                }
+    private void consumeTraceEvent(
+            JsonNode data,
+            ParsedState state,
+            Consumer<SuperAgentOpenApiTraceEvent> traceConsumer) {
+        JsonNode trace = data.path("data").isObject() && data.path("event").isMissingNode()
+                ? data.path("data")
+                : data;
+        JsonNode toolCalls = trace.path("tool_calls");
+        if (toolCalls.isArray() && !toolCalls.isEmpty()) {
+            for (JsonNode toolCall : toolCalls) {
+                emitTraceEvent(traceEvent(trace, toolCall), state, traceConsumer);
            }
-            if (!data.isEmpty() || "end".equals(eventType)) {
-                events.add(new SseEvent(eventType, data.toString()));
+            return;
+        }
+        emitTraceEvent(traceEvent(trace, trace), state, traceConsumer);
+    }
+
+    /**
+     * 构造公开 Trace 事件对象。
+     */
+    private SuperAgentOpenApiTraceEvent traceEvent(JsonNode trace, JsonNode detail) {
+        return new SuperAgentOpenApiTraceEvent(
+                safeTraceText(text(trace, "event", null)),
+                safeTraceText(text(trace, "run_id", null)),
+                safeTraceText(text(trace, "message_id", null)),
+                safeTraceText(text(detail, "tool_call_id", text(trace, "tool_call_id", null))),
+                safeTraceText(text(detail, "name", text(trace, "name", null))),
+                safeTraceText(text(trace, "text", null)),
+                safeTraceText(summary(detail.path("input"), summary(trace.path("input"), null))),
+                safeTraceText(summary(detail.path("output"), summary(trace.path("output"), null))),
+                safeTraceText(text(trace, "status", null)),
+                safeTraceText(text(trace, "ts", null)));
+    }
+
+    /**
+     * 保存并回调 Trace 事件。
+     */
+    private void emitTraceEvent(
+            SuperAgentOpenApiTraceEvent traceEvent,
+            ParsedState state,
+            Consumer<SuperAgentOpenApiTraceEvent> traceConsumer) {
+        if (traceEvent.event() == null || traceEvent.event().isBlank()) {
+            return;
+        }
+        state.traceEvents.add(traceEvent);
+        traceConsumer.accept(traceEvent);
+    }
+
+    /**
+     * 流式拆分 SSE 事件块，支持多行 data。
+     */
+    private void parseLines(Reader reader, Consumer<SseEvent> consumer, ParsedState state) throws IOException {
+        BufferedReader bufferedReader = reader instanceof BufferedReader existingReader
+                ? existingReader
+                : new BufferedReader(reader);
+        SseEventBuilder builder = new SseEventBuilder();
+        String line;
+        while ((line = bufferedReader.readLine()) != null) {
+            if (line.isBlank()) {
+                flushEvent(builder, consumer);
+                if (state.endSeen) {
+                    return;
+                }
+                continue;
+            }
+            if (line.startsWith(":")) {
+                continue;
+            }
+            if (line.startsWith("event:")) {
+                builder.eventType(line.substring("event:".length()).trim());
+                continue;
+            }
+            if (line.startsWith("data:")) {
+                builder.appendData(line.substring("data:".length()).trim());
            }
        }
-        return events;
+        flushEvent(builder, consumer);
+    }
+
+    /**
+     * 输出当前累积事件并重置 builder。
+     */
+    private void flushEvent(SseEventBuilder builder, Consumer<SseEvent> consumer) {
+        SseEvent event = builder.build();
+        if (event != null) {
+            consumer.accept(event);
+        }
+        builder.reset();
    }

    /**
@@ -205,6 +323,42 @@ public class SuperAgentOpenApiSseParser {
        return value.asInt();
    }

+    /**
+     * 读取公开 summary 字段。
+     */
+    private String summary(JsonNode node, String fallback) {
+        if (node == null || node.isMissingNode() || node.isNull()) {
+            return fallback;
+        }
+        String value = text(node, "summary", null);
+        if (value != null) {
+            return value;
+        }
+        return node.isTextual() ? node.asText() : fallback;
+    }
+
+    /**
+     * Trace 展示字段做短文本脱敏与截断。
+     */
+    private String safeTraceText(String value) {
+        if (value == null || value.isBlank()) {
+            return null;
+        }
+        String sanitized = JSON_SECRET_PATTERN.matcher(value).replaceAll("$1***$2");
+        sanitized = HEADER_SECRET_PATTERN.matcher(sanitized).replaceAll("$1***");
+        sanitized = TEXT_SECRET_PATTERN.matcher(sanitized).replaceAll("$1***");
+        return sanitized.length() > 2048 ? sanitized.substring(0, 2048) : sanitized;
+    }
+
+    /**
+     * Trace 消费者为空时使用 no-op。
+     */
+    private Consumer<SuperAgentOpenApiTraceEvent> safeTraceConsumer(
+            Consumer<SuperAgentOpenApiTraceEvent> traceConsumer) {
+        return traceConsumer == null ? traceEvent -> {
+        } : traceConsumer;
+    }
+
    /**
     * 读取 AI content，兼容字符串、文本片段数组和简单文本对象。
     */
@@ -252,6 +406,37 @@ public class SuperAgentOpenApiSseParser {
    private record SseEvent(String eventType, String data) {
    }

+    /**
+     * SSE 事件累积器。
+     */
+    private static final class SseEventBuilder {
+        private String eventType = "message";
+        private final StringBuilder data = new StringBuilder();
+
+        private void eventType(String eventType) {
+            this.eventType = eventType == null || eventType.isBlank() ? "message" : eventType;
+        }
+
+        private void appendData(String value) {
+            if (!data.isEmpty()) {
+                data.append('\n');
+            }
+            data.append(value);
+        }
+
+        private SseEvent build() {
+            if (data.isEmpty() && !"end".equals(eventType)) {
+                return null;
+            }
+            return new SseEvent(eventType, data.toString());
+        }
+
+        private void reset() {
+            eventType = "message";
+            data.setLength(0);
+        }
+    }
+
    /**
     * SSE 解析过程中的可变状态。
     */
@@ -270,5 +455,6 @@ public class SuperAgentOpenApiSseParser {
        private Integer fallbackInputTokens;
        private Integer fallbackOutputTokens;
        private Integer fallbackTotalTokens;
+        private final List<SuperAgentOpenApiTraceEvent> traceEvents = new ArrayList<>();
    }
 }
--- a/server/src/main/java/cn/nianxx/thhotel/platform/debug/common/result/DebugEmlSuperAgentRunResult.java
+++ b/server/src/main/java/cn/nianxx/thhotel/platform/debug/common/result/DebugEmlSuperAgentRunResult.java
@@ -1,5 +1,6 @@
 package cn.nianxx.thhotel.platform.debug.common.result;

+import cn.nianxx.thhotel.integrations.ai.superagent.common.result.SuperAgentOpenApiTraceEvent;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.fasterxml.jackson.databind.JsonNode;
 import java.util.List;
@@ -25,6 +26,7 @@ import java.util.Map;
 * @param superagentRunId SuperAgent run ID
 * @param superagentRawAnswer SuperAgent 原始最终回答
 * @param superagentParsedJson 后端解析出的 JSON
+ * @param superagentTraceEvents SuperAgent 公开 Trace 事件列表
 * @param warnings 可展示的安全警告
 * @param status Debug 运行状态
 */
@@ -63,6 +65,8 @@ public record DebugEmlSuperAgentRunResult(
        String superagentRawAnswer,
        @JsonProperty("superagent_parsed_json")
        JsonNode superagentParsedJson,
+        @JsonProperty("superagent_trace_events")
+        List<SuperAgentOpenApiTraceEvent> superagentTraceEvents,
        List<String> warnings,
        String status
 ) {
--- a/server/src/main/java/cn/nianxx/thhotel/platform/debug/control/DebugEmlSuperAgentController.java
+++ b/server/src/main/java/cn/nianxx/thhotel/platform/debug/control/DebugEmlSuperAgentController.java
@@ -3,6 +3,7 @@ package cn.nianxx.thhotel.platform.debug.control;
 import cn.nianxx.thhotel.platform.debug.common.result.DebugEmlSuperAgentRunResult;
 import cn.nianxx.thhotel.platform.debug.service.DebugEmlSuperAgentRunService;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.http.HttpHeaders;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
@@ -12,6 +13,7 @@ import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
+import org.springframework.web.servlet.mvc.method.annotation.StreamingResponseBody;

 /**
 * Debug EML 上传 Controller。该入口只用于受控调试，不创建业务订单或任务。
@@ -41,4 +43,23 @@ public class DebugEmlSuperAgentController {
            @RequestParam(name = "run_label", required = false) String runLabel) {
        return ResponseEntity.status(HttpStatus.CREATED).body(runService.uploadAndRun(accessKey, file, hotelId, runLabel));
    }
+
+    /**
+     * 上传单封 .eml 邮件并以 SSE 实时返回本系统阶段、SuperAgent 公开 Trace 和最终回答。
+     */
+    @PostMapping(path = "/stream", consumes = MediaType.MULTIPART_FORM_DATA_VALUE, produces = MediaType.TEXT_EVENT_STREAM_VALUE)
+    public ResponseEntity<StreamingResponseBody> uploadStream(
+            @RequestHeader(name = "X-TH-Hotel-Debug-Upload-Key", required = false) String accessKey,
+            @RequestParam("file") MultipartFile file,
+            @RequestParam(name = "hotel_id", required = false) String hotelId,
+            @RequestParam(name = "run_label", required = false) String runLabel) {
+        runService.validateUploadAccessKey(accessKey);
+        StreamingResponseBody responseBody = outputStream ->
+                runService.uploadAndRunStream(accessKey, file, hotelId, runLabel, outputStream);
+        return ResponseEntity.ok()
+                .header(HttpHeaders.CACHE_CONTROL, "no-cache")
+                .header("X-Accel-Buffering", "no")
+                .contentType(MediaType.TEXT_EVENT_STREAM)
+                .body(responseBody);
+    }
 }
--- a/server/src/main/java/cn/nianxx/thhotel/platform/debug/service/DebugEmlSuperAgentRunService.java
+++ b/server/src/main/java/cn/nianxx/thhotel/platform/debug/service/DebugEmlSuperAgentRunService.java
@@ -1,6 +1,7 @@
 package cn.nianxx.thhotel.platform.debug.service;

 import cn.nianxx.thhotel.platform.debug.common.result.DebugEmlSuperAgentRunResult;
+import java.io.OutputStream;
 import org.springframework.web.multipart.MultipartFile;

 /**
@@ -8,6 +9,11 @@ import org.springframework.web.multipart.MultipartFile;
 */
 public interface DebugEmlSuperAgentRunService {

+    /**
+     * 校验 Debug EML 上传访问口令。流式入口需要在响应开始前完成校验，才能保留标准 HTTP 401。
+     */
+    void validateUploadAccessKey(String accessKey);
+
    /**
     * 上传并处理单封 EML，写入 SourceMessage 后调用 SuperAgent Open API。
     */
@@ -16,4 +22,14 @@ public interface DebugEmlSuperAgentRunService {
            MultipartFile file,
            String hotelId,
            String runLabel);
+
+    /**
+     * 上传并处理单封 EML，按 text/event-stream 实时写出内部阶段、SuperAgent Trace 和最终结果。
+     */
+    void uploadAndRunStream(
+            String accessKey,
+            MultipartFile file,
+            String hotelId,
+            String runLabel,
+            OutputStream outputStream);
 }
--- a/server/src/main/java/cn/nianxx/thhotel/platform/debug/service/impl/DebugEmlSuperAgentRunServiceImpl.java
+++ b/server/src/main/java/cn/nianxx/thhotel/platform/debug/service/impl/DebugEmlSuperAgentRunServiceImpl.java
@@ -2,6 +2,7 @@ package cn.nianxx.thhotel.platform.debug.service.impl;

 import cn.nianxx.thhotel.integrations.ai.superagent.common.request.SuperAgentMailDebugRequest;
 import cn.nianxx.thhotel.integrations.ai.superagent.common.result.SuperAgentOpenApiResult;
+import cn.nianxx.thhotel.integrations.ai.superagent.common.result.SuperAgentOpenApiTraceEvent;
 import cn.nianxx.thhotel.integrations.ai.superagent.service.SuperAgentOpenApiClient;
 import cn.nianxx.thhotel.integrations.ai.superagent.service.impl.SuperAgentOpenApiException;
 import cn.nianxx.thhotel.integrations.storage.aliyunoss.common.request.ObjectStoragePutRequest;
@@ -34,6 +35,8 @@ import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.node.ObjectNode;
+import java.io.IOException;
+import java.io.OutputStream;
 import java.net.SocketTimeoutException;
 import java.net.URLDecoder;
 import java.nio.charset.StandardCharsets;
@@ -48,6 +51,7 @@ import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Locale;
 import java.util.Map;
+import java.util.function.Consumer;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 import org.springframework.http.HttpStatus;
@@ -106,6 +110,14 @@ public class DebugEmlSuperAgentRunServiceImpl implements DebugEmlSuperAgentRunSe
        this.hotelContextService = hotelContextService;
    }

+    /**
+     * 校验 Debug EML 上传访问口令。供 Controller 在流式响应开始前复用，避免错误被写成 SSE 事件后丢失 HTTP 状态。
+     */
+    @Override
+    public void validateUploadAccessKey(String accessKey) {
+        validateAccessKey(accessKey);
+    }
+
    /**
     * 处理单封 Debug EML 上传；第一版只展示 SuperAgent 结果，不创建订单或任务。
     */
@@ -131,7 +143,7 @@ public class DebugEmlSuperAgentRunServiceImpl implements DebugEmlSuperAgentRunSe
                DebugEmlSuperAgentRunStatus.CREATED.name(),
                now));
        try {
-            return doUploadAndRun(runId, normalizedHotelId, trimToNull(runLabel), safeFileName, emlBytes, now);
+            return doUploadAndRun(runId, normalizedHotelId, trimToNull(runLabel), safeFileName, emlBytes, now, null);
        } catch (DebugEmlSuperAgentException exception) {
            markFailed(runId, exception.getMessage(), statusForException(exception), nowUtc());
            throw exception;
@@ -166,6 +178,80 @@ public class DebugEmlSuperAgentRunServiceImpl implements DebugEmlSuperAgentRunSe
        }
    }

+    /**
+     * 处理单封 Debug EML 上传，并实时输出安全的调试 SSE 事件。
+     */
+    @Override
+    public void uploadAndRunStream(
+            String accessKey,
+            MultipartFile file,
+            String hotelId,
+            String runLabel,
+            OutputStream outputStream) {
+        OutputStreamDebugEmlStreamSink streamSink = new OutputStreamDebugEmlStreamSink(outputStream, objectMapper);
+        Long runId = null;
+        try {
+            validateAccessKey(accessKey);
+            String normalizedHotelId = normalizeHotelId(hotelId);
+            validateFile(file);
+            byte[] emlBytes = readFileBytes(file);
+            String safeFileName = safeFileName(file.getOriginalFilename(), "debug-email.eml");
+            if (!safeFileName.toLowerCase(Locale.ROOT).endsWith(".eml")) {
+                throw new DebugEmlSuperAgentException(HttpStatus.BAD_REQUEST, "INVALID_FILE_TYPE", "只支持上传 .eml 邮件文件。");
+            }
+
+            LocalDateTime now = nowUtc();
+            runId = runRepository.insert(new DebugEmlSuperAgentRunDraft(
+                    normalizedHotelId,
+                    trimToNull(runLabel),
+                    DebugEmlSuperAgentRunStatus.CREATED.name(),
+                    now));
+            DebugEmlSuperAgentRunResult result = doUploadAndRun(
+                    runId,
+                    normalizedHotelId,
+                    trimToNull(runLabel),
+                    safeFileName,
+                    emlBytes,
+                    now,
+                    streamSink);
+            streamSink.result(result);
+            streamSink.done();
+        } catch (DebugEmlSuperAgentException exception) {
+            if (runId != null) {
+                markFailed(runId, exception.getMessage(), statusForException(exception), nowUtc());
+            }
+            streamSink.error(runId, exception.getErrorCode(), exception.getMessage(), statusForException(exception).name());
+        } catch (EmlMessageParseException exception) {
+            if (runId != null) {
+                markFailed(runId, "EML 邮件解析失败。", DebugEmlSuperAgentRunStatus.FAILED, nowUtc());
+            }
+            streamSink.error(runId, "EML_PARSE_FAILED", "EML 邮件解析失败。", DebugEmlSuperAgentRunStatus.FAILED.name());
+        } catch (ObjectStorageException exception) {
+            if (runId != null) {
+                markFailed(runId, "OSS 上传失败。", DebugEmlSuperAgentRunStatus.FAILED, nowUtc());
+            }
+            streamSink.error(runId, "OSS_UPLOAD_FAILED", "OSS 上传失败。", DebugEmlSuperAgentRunStatus.FAILED.name());
+        } catch (SuperAgentOpenApiException exception) {
+            if (runId != null) {
+                markFailed(runId, superAgentFailureSummary(exception), DebugEmlSuperAgentRunStatus.SUPERAGENT_FAILED, nowUtc());
+            }
+            streamSink.error(
+                    runId,
+                    "SUPERAGENT_OPEN_API_FAILED",
+                    "SuperAgent 调用失败。",
+                    DebugEmlSuperAgentRunStatus.SUPERAGENT_FAILED.name());
+        } catch (Exception exception) {
+            if (runId != null) {
+                markFailed(runId, "Debug EML 上传处理失败。", DebugEmlSuperAgentRunStatus.FAILED, nowUtc());
+            }
+            streamSink.error(
+                    runId,
+                    "DEBUG_EML_RUN_FAILED",
+                    "Debug EML 上传处理失败。",
+                    DebugEmlSuperAgentRunStatus.FAILED.name());
+        }
+    }
+
    /**
     * 解析 Debug 上传酒店上下文。第一版可不传 hotel_id，由单酒店系统上下文兜底。
     */
@@ -250,12 +336,14 @@ public class DebugEmlSuperAgentRunServiceImpl implements DebugEmlSuperAgentRunSe
            String runLabel,
            String safeFileName,
            byte[] emlBytes,
-            LocalDateTime createdAt) throws Exception {
+            LocalDateTime createdAt,
+            DebugEmlSuperAgentStreamSink streamSink) throws Exception {
        String sha256 = sha256(emlBytes);
        markStage(
                runId,
                DebugEmlSuperAgentRunStatus.PARSING_EML,
-                "阶段：解析 EML 邮件，文件名：" + safeFileName + "，大小：" + emlBytes.length + " bytes。");
+                "阶段：解析 EML 邮件，文件名：" + safeFileName + "，大小：" + emlBytes.length + " bytes。",
+                streamSink);
        ParsedEmlMessage parsed = parseService.parse(emlBytes, safeFileName);
        String originalMessageId = parsed.messageId();
        String originalConversationId = parsed.conversationId();
@@ -267,7 +355,8 @@ public class DebugEmlSuperAgentRunServiceImpl implements DebugEmlSuperAgentRunSe
        markStage(
                runId,
                DebugEmlSuperAgentRunStatus.UPLOADING_ORIGINAL_EML,
-                "阶段：上传原始 EML 到 OSS，文件名：" + safeFileName + "，大小：" + emlBytes.length + " bytes。");
+                "阶段：上传原始 EML 到 OSS，文件名：" + safeFileName + "，大小：" + emlBytes.length + " bytes。",
+                streamSink);
        uploadedMedia.add(uploadOriginalEml(runId, safeFileName, emlBytes, createdAt));
        int inlineIndex = 1;
        int attachmentIndex = 1;
@@ -276,13 +365,15 @@ public class DebugEmlSuperAgentRunServiceImpl implements DebugEmlSuperAgentRunSe
                markStage(
                        runId,
                        DebugEmlSuperAgentRunStatus.UPLOADING_MEDIA,
-                        mediaUploadStageSummary(mediaItem, "inline", inlineIndex));
+                        mediaUploadStageSummary(mediaItem, "inline", inlineIndex),
+                        streamSink);
                uploadedMedia.add(uploadParsedMedia(runId, createdAt, mediaItem, "inline", inlineIndex++));
            } else {
                markStage(
                        runId,
                        DebugEmlSuperAgentRunStatus.UPLOADING_MEDIA,
-                        mediaUploadStageSummary(mediaItem, "attachments", attachmentIndex));
+                        mediaUploadStageSummary(mediaItem, "attachments", attachmentIndex),
+                        streamSink);
                uploadedMedia.add(uploadParsedMedia(runId, createdAt, mediaItem, "attachments", attachmentIndex++));
            }
        }
@@ -290,7 +381,8 @@ public class DebugEmlSuperAgentRunServiceImpl implements DebugEmlSuperAgentRunSe
        markStage(
                runId,
                DebugEmlSuperAgentRunStatus.BUILDING_SOURCE_MESSAGE,
-                "阶段：构造 SourceMessage payload。");
+                "阶段：构造 SourceMessage payload。",
+                streamSink);
        String htmlWithOssUrls = replaceCidReferences(parsed.htmlBody(), uploadedMedia, warnings);
        String htmlBodySanitized = htmlSanitizerService.sanitizeHtml(htmlWithOssUrls);
        String htmlRenderMode = htmlSanitizerService.htmlRenderMode(htmlWithOssUrls);
@@ -308,7 +400,8 @@ public class DebugEmlSuperAgentRunServiceImpl implements DebugEmlSuperAgentRunSe
        markStage(
                runId,
                DebugEmlSuperAgentRunStatus.CAPTURING_SOURCE_MESSAGE,
-                "阶段：写入 SourceMessage Inbox。");
+                "阶段：写入 SourceMessage Inbox。",
+                streamSink);
        SourceMessageCaptureResult captureResult = sourceMessageCaptureService.capture(new CaptureSourceMessageCommand(
                hotelId,
                SOURCE_PROVIDER,
@@ -338,15 +431,29 @@ public class DebugEmlSuperAgentRunServiceImpl implements DebugEmlSuperAgentRunSe
        markStage(
                runId,
                DebugEmlSuperAgentRunStatus.CALLING_SUPERAGENT,
-                "阶段：调用 SuperAgent Open API，source_message_id=" + captureResult.inboxId() + "。");
-        SuperAgentOpenApiResult superAgentResult = superAgentOpenApiClient.invokeMailDebug(new SuperAgentMailDebugRequest(
+                "阶段：调用 SuperAgent Open API，source_message_id=" + captureResult.inboxId() + "。",
+                streamSink);
+        SuperAgentMailDebugRequest superAgentRequest = new SuperAgentMailDebugRequest(
                buildSuperAgentMessage(payloadJson),
                "debug-eml-" + runId,
                Map.of(
                        "source", "th-hotel-debug-eml-upload",
                        "debug_run_id", runId.toString(),
                        "source_message_id", captureResult.inboxId().toString(),
-                        "hotel_id", hotelId)));
+                        "hotel_id", hotelId));
+        List<SuperAgentOpenApiTraceEvent> streamedTraceEvents = new ArrayList<>();
+        Consumer<SuperAgentOpenApiTraceEvent> traceConsumer = traceEvent -> {
+            streamedTraceEvents.add(traceEvent);
+            if (streamSink != null) {
+                streamSink.trace(traceEvent);
+            }
+        };
+        SuperAgentOpenApiResult superAgentResult = streamSink == null
+                ? superAgentOpenApiClient.invokeMailDebug(superAgentRequest)
+                : superAgentOpenApiClient.invokeMailDebug(superAgentRequest, traceConsumer);
+        List<SuperAgentOpenApiTraceEvent> traceEvents = streamedTraceEvents.isEmpty()
+                ? superAgentResult.traceEvents()
+                : List.copyOf(streamedTraceEvents);
        JsonNode parsedJson = parseSuperAgentJson(superAgentResult.rawAnswer(), warnings);
        String parsedJsonText = parsedJson == null ? null : objectMapper.writeValueAsString(parsedJson);
        DebugEmlSuperAgentRunStatus status = DebugEmlSuperAgentRunStatus.SUPERAGENT_SUCCEEDED;
@@ -391,6 +498,7 @@ public class DebugEmlSuperAgentRunServiceImpl implements DebugEmlSuperAgentRunSe
                superAgentResult.runId(),
                superAgentResult.rawAnswer(),
                parsedJson,
+                traceEvents,
                List.copyOf(warnings),
                status.name());
    }
@@ -693,14 +801,29 @@ public class DebugEmlSuperAgentRunServiceImpl implements DebugEmlSuperAgentRunSe
            Long runId,
            DebugEmlSuperAgentRunStatus status,
            String safeSummary) {
+        markStage(runId, status, safeSummary, null);
+    }
+
+    /**
+     * 标记 Debug 运行中的当前阶段，并在流式调试入口实时输出阶段事件。
+     */
+    private void markStage(
+            Long runId,
+            DebugEmlSuperAgentRunStatus status,
+            String safeSummary,
+            DebugEmlSuperAgentStreamSink streamSink) {
        if (runId == null) {
            return;
        }
+        String truncatedSummary = truncate(safeSummary, 512);
        runRepository.updateStatus(new DebugEmlSuperAgentRunStatusUpdate(
                runId,
                status.name(),
-                truncate(safeSummary, 512),
+                truncatedSummary,
                nowUtc()));
+        if (streamSink != null) {
+            streamSink.stage(runId, status, truncatedSummary);
+        }
    }

    /**
@@ -912,6 +1035,106 @@ public class DebugEmlSuperAgentRunServiceImpl implements DebugEmlSuperAgentRunSe
        return LocalDateTime.now(ZoneOffset.UTC);
    }

+    /**
+     * Debug EML 流式事件输出端口，避免主流程依赖 HTTP 细节。
+     */
+    private interface DebugEmlSuperAgentStreamSink {
+
+        /**
+         * 输出本系统处理阶段。
+         */
+        void stage(Long runId, DebugEmlSuperAgentRunStatus status, String safeSummary);
+
+        /**
+         * 输出 SuperAgent 公开 Trace 事件。
+         */
+        void trace(SuperAgentOpenApiTraceEvent traceEvent);
+
+        /**
+         * 输出最终 Debug 结果。
+         */
+        void result(DebugEmlSuperAgentRunResult result);
+
+        /**
+         * 输出安全错误事件。
+         */
+        void error(Long runId, String errorCode, String message, String status);
+
+        /**
+         * 输出流结束事件。
+         */
+        void done();
+    }
+
+    /**
+     * 将 Debug EML 事件写成 text/event-stream。
+     */
+    private static final class OutputStreamDebugEmlStreamSink implements DebugEmlSuperAgentStreamSink {
+
+        private final OutputStream outputStream;
+        private final ObjectMapper objectMapper;
+        private boolean active = true;
+
+        private OutputStreamDebugEmlStreamSink(OutputStream outputStream, ObjectMapper objectMapper) {
+            this.outputStream = outputStream;
+            this.objectMapper = objectMapper;
+        }
+
+        @Override
+        public void stage(Long runId, DebugEmlSuperAgentRunStatus status, String safeSummary) {
+            Map<String, Object> data = new LinkedHashMap<>();
+            data.put("debug_run_id", runId == null ? null : runId.toString());
+            data.put("status", status.name());
+            data.put("safe_summary", safeSummary);
+            send("debug_stage", data);
+        }
+
+        @Override
+        public void trace(SuperAgentOpenApiTraceEvent traceEvent) {
+            send("superagent_trace", traceEvent);
+        }
+
+        @Override
+        public void result(DebugEmlSuperAgentRunResult result) {
+            send("superagent_result", result);
+        }
+
+        @Override
+        public void error(Long runId, String errorCode, String message, String status) {
+            Map<String, Object> data = new LinkedHashMap<>();
+            data.put("debug_run_id", runId == null ? null : runId.toString());
+            data.put("error_code", errorCode);
+            data.put("message", message);
+            data.put("status", status);
+            send("debug_error", data);
+            done();
+        }
+
+        @Override
+        public void done() {
+            send("done", Map.of("status", "done"));
+        }
+
+        /**
+         * 写出一个 SSE 事件块并立即 flush。写失败通常表示客户端断开，只关闭流输出，不影响后续业务落库。
+         */
+        private void send(String eventName, Object data) {
+            if (!active) {
+                return;
+            }
+            try {
+                String eventBlock = "event: " + eventName
+                        + "\n"
+                        + "data: " + objectMapper.writeValueAsString(data)
+                        + "\n\n";
+                outputStream.write(eventBlock.getBytes(StandardCharsets.UTF_8));
+                outputStream.flush();
+            } catch (IOException exception) {
+                active = false;
+            }
+        }
+    }
+
    /**
     * 上传媒体内部组合对象。
     */