Просмотр исходного кода

feat(python): 输出超限保留头尾并落盘完整日志

- execute_python 的 stdout/stderr 超过内联上限时保留开头和结尾,中间标注截断,避免丢失末尾报错/汇总
- 完整输出落盘到 py-out/{execId}/stdout.log|stderr.log,结果返回路径、原始字符数与截断标志
- 内联上限默认 30k(可配置,执行时钳到 150k),落盘上限默认 20M,防止死循环打印打满磁盘
- ToolResultLimits 的 Python 结果上限同步放宽到 256k,并补充单测
cc 2 недель назад
Родитель
Сommit
43e41d1f5c

+ 297 - 20
ai-server/src/main/java/com/zsjz/ai/module/agent/python/PythonExecutor.java

@@ -100,6 +100,13 @@ public class PythonExecutor {
     /** Python 输出目录的执行归属文件:第一行 userId,第二行 sessionId */
     private static final String EXEC_OWNER_FILE = ".exec-owner";
 
+    /** 内联输出上限的硬上限(与 ZCode 的 BASH_MAX_OUTPUT_LENGTH 上限一致) */
+    private static final int MAX_INLINE_OUTPUT_CHARS = 150_000;
+
+    /** 截断时完整输出落盘的文件名(放在 py-out/{execId} 下,不参与产物白名单) */
+    private static final String STDOUT_LOG = "stdout.log";
+    private static final String STDERR_LOG = "stderr.log";
+
     /**
      * 关系图辅助模块源码。
      *
@@ -260,6 +267,18 @@ public class PythonExecutor {
         return available;
     }
 
+    /**
+     * 单路输出内联字符上限:配置值钳到 [1, 150000],非法值回退 30000。
+     * 超出后由 {@link OutputCollector} 保留头尾并把完整输出落盘。
+     */
+    private int resolveMaxOutputChars() {
+        int configured = etlProperties.getPython().getMaxOutputChars();
+        if (configured <= 0) {
+            configured = 30_000;
+        }
+        return Math.min(configured, MAX_INLINE_OUTPUT_CHARS);
+    }
+
     /**
      * 执行 Python 代码(子进程沙箱)
      *
@@ -328,10 +347,13 @@ public class PythonExecutor {
             pb.environment().put("MPLCONFIGDIR", mplDir.toAbsolutePath().toString());
 
             Process process = pb.start();
+            int maxInlineChars = resolveMaxOutputChars();
+            long maxFullChars = etlProperties.getPython().getMaxFullOutputChars();
+            Path outDir = storageLayout.pythonOutDir(workspaceId, execId);
             OutputCollector stdout = new OutputCollector(process.getInputStream(),
-                    etlProperties.getPython().getMaxOutputChars());
+                    maxInlineChars, maxFullChars, outDir.resolve(STDOUT_LOG));
             OutputCollector stderr = new OutputCollector(process.getErrorStream(),
-                    etlProperties.getPython().getMaxOutputChars());
+                    maxInlineChars, maxFullChars, outDir.resolve(STDERR_LOG));
             stdout.start();
             stderr.start();
 
@@ -349,12 +371,21 @@ public class PythonExecutor {
             RelationGraphFile relationGraph = readRelationGraph(sandbox);
             List<String> imageUrls = collectGeneratedFiles(
                     workspaceId, execId, sandbox, userId, sessionId);
+            // 只有截断时才落盘输出日志;若本目录没有产物,collectGeneratedFiles 不会触发 LRU 清理
+            if (stdout.isPersisted() || stderr.isPersisted()) {
+                evictOldExecs(storageLayout.pythonOutRoot(workspaceId));
+            }
             long durationMs = System.currentTimeMillis() - start;
-            log.info("Python 执行完成: workspaceId={}, execId={}, exitCode={}, images={}, relationGraph={}, costMs={}",
+            log.info("Python 执行完成: workspaceId={}, execId={}, exitCode={}, images={}, relationGraph={}, "
+                            + "stdoutChars={}, stderrChars={}, stdoutTruncated={}, stderrTruncated={}, costMs={}",
                     workspaceId, execId, process.exitValue(), imageUrls.size(),
-                    relationGraph.json() != null, durationMs);
+                    relationGraph.json() != null, stdout.getTotalChars(), stderr.getTotalChars(),
+                    stdout.isTruncated(), stderr.isTruncated(), durationMs);
             return new PythonResult(process.exitValue(), stdout.getContent(), stderr.getContent(),
-                    imageUrls, durationMs, null, relationGraph.json(), relationGraph.error());
+                    imageUrls, durationMs, null, relationGraph.json(), relationGraph.error(),
+                    stdout.isTruncated(), stderr.isTruncated(),
+                    stdout.getTotalChars(), stderr.getTotalChars(),
+                    stdout.getPersistedPath(), stderr.getPersistedPath());
         } catch (IOException e) {
             return PythonResult.error("Python 进程启动失败: " + e.getMessage());
         } catch (InterruptedException e) {
@@ -398,10 +429,31 @@ public class PythonExecutor {
      * <p>{@code relationGraphJson} / {@code relationGraphError} 对应沙箱里的
      * {@code relation_graph.json}:前者是模型调用 {@code emit_relation_graph} 写出的原文,
      * 后者是读取失败的原因,两者互斥;都为 null 表示本次没有生成关系图。
+     *
+     * <p><b>输出截断</b>:{@code stdout/stderr} 已按内联上限保留头尾(中间有截断说明);
+     * {@code *Truncated} 为真实截断标志,{@code *Chars} 是原始总字符数,
+     * {@code *FullOutputPath} 是完整输出落盘路径(未截断或落盘失败时为 null)。
      */
     public record PythonResult(int exitCode, String stdout, String stderr,
                                List<String> imageUrls, long durationMs, String error,
-                               String relationGraphJson, String relationGraphError) {
+                               String relationGraphJson, String relationGraphError,
+                               boolean stdoutTruncated, boolean stderrTruncated,
+                               long stdoutChars, long stderrChars,
+                               String stdoutFullOutputPath, String stderrFullOutputPath) {
+
+        /**
+         * 兼容旧调用/单测:没有截断元数据时按「未截断」处理。
+         */
+        public PythonResult(int exitCode, String stdout, String stderr,
+                            List<String> imageUrls, long durationMs, String error,
+                            String relationGraphJson, String relationGraphError) {
+            this(exitCode, stdout, stderr, imageUrls, durationMs, error,
+                    relationGraphJson, relationGraphError,
+                    false, false,
+                    stdout == null ? 0L : stdout.length(),
+                    stderr == null ? 0L : stderr.length(),
+                    null, null);
+        }
 
         static PythonResult error(String message) {
             return new PythonResult(-1, "", "", List.of(), 0, message, null, null);
@@ -616,37 +668,262 @@ public class PythonExecutor {
     }
 
     /**
-     * 进程输出流采集线程(截断到 maxChars)
+     * 进程输出流采集线程:内联只保留头尾,超出上限时把完整输出落盘。
+     *
+     * <p>只留前 N 个字符会把错误栈/汇总行(通常在最后)丢掉;这里把内联预算对半分成
+     * 头/尾两段,中间用截断说明代替。第一次超出上限时把已读前缀写盘,后续输出继续追加,
+     * 模型可从结果里的 {@code *_full_output_path} 取全文(用 execute_python 读取)。
+     *
+     * <p>落盘只在截断时发生:短输出既不需要额外文件,也不会改变返回内容。
      */
-    private static class OutputCollector extends Thread {
+    static class OutputCollector extends Thread {
 
         private final java.io.InputStream in;
-        private final int maxChars;
-        private final StringBuilder sb = new StringBuilder();
-
-        OutputCollector(java.io.InputStream in, int maxChars) {
+        private final int maxInlineChars;
+        private final int headChars;
+        private final int tailChars;
+        private final long maxPersistedChars;
+        private final Path outputPath;
+
+        /** 未截断时的全文缓冲 */
+        private final StringBuilder inline = new StringBuilder();
+        /** 截断后的头段 */
+        private final StringBuilder head = new StringBuilder();
+        /** 截断后的尾段(最多 tailChars + 1,保持有界) */
+        private final StringBuilder tail = new StringBuilder();
+
+        private long totalChars;
+        private boolean truncated;
+        private boolean persisted;
+        private boolean persistedTruncated;
+        private boolean persistFailed;
+        private java.io.BufferedWriter writer;
+        private long persistedChars;
+
+        OutputCollector(java.io.InputStream in, int maxInlineChars, long maxPersistedChars,
+                        Path outputPath) {
             this.in = in;
-            this.maxChars = maxChars;
+            this.maxInlineChars = Math.max(1, maxInlineChars);
+            this.headChars = this.maxInlineChars / 2;
+            this.tailChars = this.maxInlineChars - this.headChars;
+            this.maxPersistedChars = maxPersistedChars;
+            this.outputPath = outputPath;
             setDaemon(true);
         }
 
         @Override
         public void run() {
             try (java.io.BufferedReader reader = new java.io.BufferedReader(
-                    new java.io.InputStreamReader(in, java.nio.charset.StandardCharsets.UTF_8))) {
-                int c;
-                while ((c = reader.read()) != -1) {
-                    if (sb.length() < maxChars) {
-                        sb.append((char) c);
-                    }
+                    new java.io.InputStreamReader(in, StandardCharsets.UTF_8))) {
+                char[] buf = new char[8192];
+                int n;
+                while ((n = reader.read(buf)) != -1) {
+                    append(buf, n);
                 }
             } catch (IOException ignored) {
                 // 进程终止导致的流关闭,忽略
+            } finally {
+                closeWriter();
+            }
+        }
+
+        private void append(char[] buf, int len) {
+            if (len <= 0) {
+                return;
+            }
+            totalChars += len;
+            if (!truncated) {
+                int room = maxInlineChars - inline.length();
+                if (len <= room) {
+                    inline.append(buf, 0, len);
+                    return;
+                }
+                if (room > 0) {
+                    inline.append(buf, 0, room);
+                }
+                truncated = true;
+                // 此时 inline 恰好是截断前的完整前缀,先落盘再拆成头/尾
+                startPersistence();
+                splitInline();
+                appendTailAndPersist(buf, room, len - room);
+                return;
+            }
+            appendTailAndPersist(buf, 0, len);
+        }
+
+        /**
+         * 把「前 maxInlineChars 个字符」拆成头段 + 尾段;不拆开代理对(emoji 等)。
+         *
+         * <p>拆分点落在高代理上时(代理对可能完整在 prefix 内,也可能低代理还在下一个 chunk),
+         * 把高代理让给尾段:尾段后续会拼上低代理,头段绝不能留下半个字符。
+         */
+        private void splitInline() {
+            String prefix = inline.toString();
+            inline.setLength(0);
+            int split = Math.min(headChars, prefix.length());
+            if (split > 0 && Character.isHighSurrogate(prefix.charAt(split - 1))) {
+                split--;
+            }
+            head.append(prefix, 0, split);
+            tail.append(prefix, split, prefix.length());
+            trimTail();
+        }
+
+        private void appendTailAndPersist(char[] buf, int off, int len) {
+            if (len <= 0) {
+                return;
+            }
+            if (tailChars > 0) {
+                int take = Math.min(len, tailChars);
+                tail.append(buf, off + len - take, take);
+                trimTail();
+            }
+            persist(buf, off, len);
+        }
+
+        /** 尾段只保留最后 tailChars 个字符;超过两倍再裁剪,均摊 O(1)。 */
+        private void trimTail() {
+            if (tailChars <= 0) {
+                tail.setLength(0);
+                return;
+            }
+            if (tail.length() <= tailChars * 2) {
+                return;
+            }
+            int cut = tail.length() - tailChars;
+            if (cut > 0 && Character.isLowSurrogate(tail.charAt(cut))) {
+                cut--;
+            }
+            tail.delete(0, cut);
+        }
+
+        private String tailText() {
+            if (tail.length() <= tailChars) {
+                return tail.toString();
+            }
+            int start = tail.length() - tailChars;
+            if (start > 0 && Character.isLowSurrogate(tail.charAt(start))) {
+                start--;
+            }
+            return tail.substring(start);
+        }
+
+        private void startPersistence() {
+            if (outputPath == null || persisted || persistFailed) {
+                return;
+            }
+            try {
+                Path parent = outputPath.getParent();
+                if (parent != null) {
+                    Files.createDirectories(parent);
+                }
+                writer = Files.newBufferedWriter(outputPath, StandardCharsets.UTF_8,
+                        java.nio.file.StandardOpenOption.CREATE,
+                        java.nio.file.StandardOpenOption.TRUNCATE_EXISTING,
+                        java.nio.file.StandardOpenOption.WRITE);
+                persisted = true;
+                String prefix = inline.toString();
+                int allow = persistedAllowance(prefix.length());
+                if (allow > 0) {
+                    writer.write(prefix, 0, allow);
+                    persistedChars += allow;
+                }
+                if (allow < prefix.length()) {
+                    persistedTruncated = true;
+                }
+            } catch (IOException e) {
+                persistFailed = true;
+                persistedTruncated = true;
+                log.warn("Python 输出落盘失败(仅返回内联头尾): path={}, err={}",
+                        outputPath, e.getMessage());
+                closeWriter();
             }
         }
 
+        private void persist(char[] buf, int off, int len) {
+            if (writer == null || persistFailed || len <= 0) {
+                return;
+            }
+            int allow = persistedAllowance(len);
+            if (allow <= 0) {
+                persistedTruncated = true;
+                return;
+            }
+            try {
+                writer.write(buf, off, allow);
+                persistedChars += allow;
+                if (allow < len) {
+                    persistedTruncated = true;
+                }
+            } catch (IOException e) {
+                persistFailed = true;
+                persistedTruncated = true;
+                log.warn("Python 输出落盘中断(仅返回内联头尾): path={}, err={}",
+                        outputPath, e.getMessage());
+                closeWriter();
+            }
+        }
+
+        /** 本次允许写入的字符数;{@code maxPersistedChars <= 0} 表示不限。 */
+        private int persistedAllowance(int requested) {
+            if (maxPersistedChars <= 0) {
+                return requested;
+            }
+            long remaining = maxPersistedChars - persistedChars;
+            if (remaining <= 0) {
+                return 0;
+            }
+            return (int) Math.min(requested, remaining);
+        }
+
+        private void closeWriter() {
+            if (writer == null) {
+                return;
+            }
+            try {
+                writer.close();
+            } catch (IOException ignored) {
+                // 关闭失败不影响已写内容
+            }
+            writer = null;
+        }
+
+        /**
+         * 模型可见的输出:未截断返回全文;截断返回「头段 + 截断说明 + 尾段」。
+         */
         String getContent() {
-            return sb.toString();
+            if (!truncated) {
+                return inline.toString();
+            }
+            String tailText = tailText();
+            long truncatedChars = Math.max(0, totalChars - head.length() - tailText.length());
+            StringBuilder out = new StringBuilder(head);
+            out.append("\n\n... [").append(truncatedChars).append(" characters truncated");
+            if (persisted) {
+                out.append("; full output");
+                if (persistedTruncated) {
+                    out.append(" (first ").append(persistedChars).append(" chars)");
+                }
+                out.append(": ").append(outputPath);
+            }
+            out.append("] ...\n\n").append(tailText);
+            return out.toString();
+        }
+
+        long getTotalChars() {
+            return totalChars;
+        }
+
+        boolean isTruncated() {
+            return truncated;
+        }
+
+        boolean isPersisted() {
+            return persisted;
+        }
+
+        String getPersistedPath() {
+            return persisted ? outputPath.toString() : null;
         }
     }
 }

+ 16 - 2
ai-server/src/main/java/com/zsjz/ai/module/agent/python/PythonProperties.java

@@ -25,8 +25,22 @@ public class PythonProperties {
     /** 执行超时秒数(超时强制终止进程) */
     private int timeoutSeconds = 60;
 
-    /** stdout/stderr 截断字符上限 */
-    private int maxOutputChars = 20000;
+    /**
+     * 单路 stdout/stderr 回给模型的内联字符上限。
+     *
+     * <p>超出后不再只丢尾部:保留开头与结尾(错误栈/汇总通常在结尾),
+     * 完整输出同时落盘到 {@code py-out/{execId}/stdout.log|stderr.log},
+     * 结果里带文件路径,模型需要全文时可用 {@code execute_python} 读取。
+     * 默认 30000(与 ZCode 的 Bash 默认内联上限一致);可用
+     * {@code ETL_PYTHON_MAX_OUTPUT_CHARS} 覆盖,执行时再钳到 150000 上限。
+     */
+    private int maxOutputChars = 30000;
+
+    /**
+     * 完整输出落盘上限(字符数),防止脚本死循环打印打满磁盘。
+     * {@code <= 0} = 不限。
+     */
+    private long maxFullOutputChars = 20_000_000L;
 
     /** 单次执行最多捕获图片数 */
     private int maxImages = 4;

+ 27 - 0
ai-server/src/main/java/com/zsjz/ai/module/agent/tools/PythonAnalysisTool.java

@@ -59,6 +59,11 @@ public class PythonAnalysisTool {
             if (result.stderr() != null && !result.stderr().isBlank()) {
                 data.put("stderr", result.stderr());
             }
+            // 输出超限时明确告诉模型:当前只是头尾,完整输出在哪个文件里
+            putOutputMeta(data, "stdout", result.stdoutTruncated(),
+                    result.stdoutChars(), result.stdoutFullOutputPath());
+            putOutputMeta(data, "stderr", result.stderrTruncated(),
+                    result.stderrChars(), result.stderrFullOutputPath());
             if (result.imageUrls() != null && !result.imageUrls().isEmpty()) {
                 data.put("imageUrls", result.imageUrls());
             }
@@ -84,4 +89,26 @@ public class PythonAnalysisTool {
             return ToolResults.error("Python 执行失败: " + e.getMessage());
         }
     }
+
+    /**
+     * 截断元数据:只在内联输出被截断时出现,避免正常结果多带字段。
+     *
+     * <p>{@code stdout/stderr} 已保留头尾;完整输出路径给模型按需读取,
+     * 这样既不把整份长输出塞进上下文,也不会因为只看开头而漏掉末尾的报错/汇总。
+     */
+    private static void putOutputMeta(Map<String, Object> data, String stream, boolean truncated,
+                                      long chars, String fullOutputPath) {
+        if (!truncated) {
+            return;
+        }
+        data.put(stream + "Truncated", true);
+        data.put(stream + "Chars", chars);
+        if (fullOutputPath != null) {
+            data.put(stream + "FullOutputPath", fullOutputPath);
+            data.put(stream + "Hint", "输出超过内联上限,已保留开头和结尾;完整输出见 "
+                    + fullOutputPath + ",需要全文时用 execute_python 读取该文件");
+        } else {
+            data.put(stream + "Hint", "输出超过内联上限,已保留开头和结尾;完整输出落盘失败");
+        }
+    }
 }

+ 5 - 4
ai-server/src/main/java/com/zsjz/ai/module/agent/tools/ToolResultLimits.java

@@ -10,8 +10,9 @@ package com.zsjz.ai.module.agent.tools;
  * <ul>
  *   <li>{@code get_case_graph} 返回 {@code nodeList}/{@code edgeList}(服务端已按 500 条边裁剪,
  *       JSON 仍可能到数百 k),放宽到 {@link #GRAPH_MAX_CHARS};</li>
- *   <li>{@code execute_python} 可能带 {@code relationGraph}(stdout/stderr 各 20k +
- *       关系图最多 60k),放宽到 {@link #PYTHON_MAX_CHARS},避免把关系图结构截断。</li>
+ *   <li>{@code execute_python} 可能带 {@code relationGraph}(stdout/stderr 各 30k +
+ *       关系图最多 60k,换行/引号转义后仍会膨胀),放宽到 {@link #PYTHON_MAX_CHARS},
+ *       避免把关系图结构截断。</li>
  * </ul>
  *
  * <p>截断本身仍是「按字符数硬截断」:超限的结果在 SSE 里只保证前 N 个字符,
@@ -25,8 +26,8 @@ public final class ToolResultLimits {
     /** 关系图谱取数结果的文本上限(字符数,需覆盖 500 条边的 JSON) */
     public static final int GRAPH_MAX_CHARS = 512_000;
 
-    /** Python 分析结果上限:stdout/stderr 上限各 20k + relationGraph 上限 60k,留出 JSON 余量 */
-    public static final int PYTHON_MAX_CHARS = 160_000;
+    /** Python 分析结果上限:stdout/stderr 默认各 30k + relationGraph 上限 60k,留出 JSON 转义余量 */
+    public static final int PYTHON_MAX_CHARS = 256_000;
 
     /** 关系图谱取数工具名 */
     private static final String TOOL_GET_CASE_GRAPH = "get_case_graph";

+ 6 - 0
ai-server/src/main/resources/application.yaml

@@ -255,6 +255,12 @@ etl:
     top-k: "${ETL_RAG_TOP_K:5}"
     # 相似度阈值(cosine 转 score)
     score-threshold: "${ETL_RAG_SCORE_THRESHOLD:0.3}"
+  python:
+    # 单路 stdout/stderr 回给模型的内联字符上限;超出后保留头尾,
+    # 完整输出落盘到 py-out/{execId}/stdout.log|stderr.log(执行时钳到 150000)
+    max-output-chars: "${ETL_PYTHON_MAX_OUTPUT_CHARS:30000}"
+    # 完整输出落盘上限(字符数),防止死循环打印打满磁盘;0 = 不限
+    max-full-output-chars: "${ETL_PYTHON_MAX_FULL_OUTPUT_CHARS:20000000}"
 
 # 按约定不参数化:别名包 / Mapper 位置 / 日志实现都是框架内部装配,随代码发布
 mybatis-plus:

+ 95 - 0
ai-server/src/test/java/com/zsjz/ai/module/agent/python/PythonExecutorTest.java

@@ -4,10 +4,13 @@ import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.io.TempDir;
 
+import java.io.ByteArrayInputStream;
+import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.Path;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertNull;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
@@ -47,4 +50,96 @@ class PythonExecutorTest {
         assertNull(file.json());
         assertTrue(file.error().contains("超过 2MB"));
     }
+
+    @Test
+    @DisplayName("输出未超上限:返回全文,不落盘")
+    void keepsShortOutputInline() throws Exception {
+        Path log = sandbox.resolve("stdout.log");
+        PythonExecutor.OutputCollector collector = collector("hello", 100, 1000, log);
+        collector.start();
+        collector.join();
+
+        assertEquals("hello", collector.getContent());
+        assertFalse(collector.isTruncated());
+        assertFalse(collector.isPersisted());
+        assertEquals(5L, collector.getTotalChars());
+        assertFalse(Files.exists(log), "短输出不需要额外文件");
+    }
+
+    @Test
+    @DisplayName("输出刚好等于上限:仍视为未截断")
+    void exactLimitIsNotTruncated() throws Exception {
+        String full = "x".repeat(100);
+        Path log = sandbox.resolve("stdout.log");
+        PythonExecutor.OutputCollector collector = collector(full, 100, 1000, log);
+        collector.start();
+        collector.join();
+
+        assertEquals(full, collector.getContent());
+        assertFalse(collector.isTruncated());
+        assertFalse(Files.exists(log));
+    }
+
+    @Test
+    @DisplayName("输出超上限:保留头尾、中间截断,完整输出落盘")
+    void truncatesMiddleAndPersistsFullOutput() throws Exception {
+        String full = "HEAD-" + "a".repeat(500) + "MIDDLE" + "b".repeat(500) + "-TAIL";
+        Path log = sandbox.resolve("out").resolve("stdout.log");
+        PythonExecutor.OutputCollector collector = collector(full, 100, 100_000, log);
+        collector.start();
+        collector.join();
+
+        String content = collector.getContent();
+        assertTrue(collector.isTruncated());
+        assertTrue(collector.isPersisted());
+        assertEquals(full.length(), collector.getTotalChars());
+        assertTrue(content.startsWith("HEAD-"), "必须保留开头");
+        assertTrue(content.endsWith("-TAIL"), "必须保留结尾(错误栈/汇总通常在最后)");
+        assertTrue(content.contains("characters truncated"));
+        assertTrue(content.contains(log.toString()), "截断说明要带完整输出路径");
+        assertTrue(Files.isRegularFile(log));
+        assertEquals(full, Files.readString(log), "落盘文件必须是完整原文");
+        assertEquals(log.toString(), collector.getPersistedPath());
+    }
+
+    @Test
+    @DisplayName("落盘上限生效:文件只保留前 N 字符,截断说明标出实际保留量")
+    void capsPersistedOutput() throws Exception {
+        String full = "a".repeat(1000);
+        Path log = sandbox.resolve("stdout.log");
+        PythonExecutor.OutputCollector collector = collector(full, 20, 30, log);
+        collector.start();
+        collector.join();
+
+        String content = collector.getContent();
+        assertTrue(collector.isTruncated());
+        assertTrue(Files.isRegularFile(log));
+        assertEquals(30, Files.readString(log).length());
+        assertTrue(content.contains("first 30 chars"));
+        assertTrue(content.contains(log.toString()));
+    }
+
+    @Test
+    @DisplayName("截断点落在代理对上时不能把 emoji 拆成两个非法字符")
+    void doesNotSplitSurrogatePair() throws Exception {
+        String emoji = "\uD83D\uDE00";
+        // maxInline=4 → head=2/tail=2;拆出尾段时 emoji 的高代理正好落在头段边界,
+        // 后续裁剪尾段又会从低代理开始,两处都必须回退,否则 emoji 会被拆坏
+        String full = "abX" + emoji + "Y";
+        PythonExecutor.OutputCollector collector = collector(full, 4, 10_000,
+                sandbox.resolve("stdout.log"));
+        collector.start();
+        collector.join();
+
+        assertTrue(collector.isTruncated());
+        assertTrue(collector.getContent().contains(emoji), "代理对应完整保留在头段或尾段");
+        assertTrue(collector.getContent().endsWith(emoji + "Y"));
+    }
+
+    private static PythonExecutor.OutputCollector collector(String text, int maxInlineChars,
+                                                            long maxPersistedChars, Path path) {
+        return new PythonExecutor.OutputCollector(
+                new ByteArrayInputStream(text.getBytes(StandardCharsets.UTF_8)),
+                maxInlineChars, maxPersistedChars, path);
+    }
 }

+ 31 - 0
ai-server/src/test/java/com/zsjz/ai/module/agent/tools/PythonAnalysisToolTest.java

@@ -118,6 +118,37 @@ class PythonAnalysisToolTest {
         assertFalse(payload.has("relationGraphError"));
     }
 
+    @Test
+    @DisplayName("输出截断:明确带截断标志、原始字符数与完整输出路径,提示模型按需读取")
+    void reportsTruncatedOutput() {
+        stub(new PythonExecutor.PythonResult(0, "HEAD\n...\nTAIL", "err-tail", List.of(), 12L, null,
+                null, null, true, true, 123_456L, 789L,
+                "/tmp/stdout.log", "/tmp/stderr.log"));
+
+        JsonNode payload = json(text(tool.executePython(null, "print(1)")));
+
+        assertTrue(payload.path("stdoutTruncated").asBoolean());
+        assertEquals(123_456L, payload.path("stdoutChars").asLong());
+        assertEquals("/tmp/stdout.log", payload.path("stdoutFullOutputPath").asText());
+        assertTrue(payload.path("stdoutHint").asText().contains("execute_python"));
+
+        assertTrue(payload.path("stderrTruncated").asBoolean());
+        assertEquals(789L, payload.path("stderrChars").asLong());
+        assertEquals("/tmp/stderr.log", payload.path("stderrFullOutputPath").asText());
+    }
+
+    @Test
+    @DisplayName("输出未截断:不出现截断元字段(正常结果不膨胀)")
+    void noTruncationMetaForNormalOutput() {
+        stub(result(null, null));
+
+        JsonNode payload = json(text(tool.executePython(null, "print(1)")));
+
+        assertFalse(payload.has("stdoutTruncated"));
+        assertFalse(payload.has("stdoutFullOutputPath"));
+        assertFalse(payload.has("stderrTruncated"));
+    }
+
     @Test
     @DisplayName("工具描述保持通用:只讲 Python 能力和关系图输出契约,不点名具体业务工具")
     void descriptionStaysGeneric() throws Exception {

+ 3 - 3
ai-server/src/test/java/com/zsjz/ai/module/agent/tools/ToolResultLimitsTest.java

@@ -11,16 +11,16 @@ import static org.junit.jupiter.api.Assertions.assertTrue;
  *
  * <p>有两类结果比常规工具大一个量级,且前端要拿完整 JSON 才能渲染:
  * {@code get_case_graph} 的 {@code nodeList/edgeList}、{@code execute_python} 的
- * {@code relationGraph}。这里锁住「图谱 512k、Python 160k、其余(含未知工具/null)100k」这条口径。
+ * {@code relationGraph}。这里锁住「图谱 512k、Python 256k、其余(含未知工具/null)100k」这条口径。
  */
 class ToolResultLimitsTest {
 
     @Test
-    @DisplayName("常量口径:默认 100k,关系图谱 512k,Python 160k")
+    @DisplayName("常量口径:默认 100k,关系图谱 512k,Python 256k")
     void constants() {
         assertEquals(100_000, ToolResultLimits.DEFAULT_MAX_CHARS);
         assertEquals(512_000, ToolResultLimits.GRAPH_MAX_CHARS);
-        assertEquals(160_000, ToolResultLimits.PYTHON_MAX_CHARS);
+        assertEquals(256_000, ToolResultLimits.PYTHON_MAX_CHARS);
         assertTrue(ToolResultLimits.GRAPH_MAX_CHARS > ToolResultLimits.DEFAULT_MAX_CHARS);
         assertTrue(ToolResultLimits.PYTHON_MAX_CHARS > ToolResultLimits.DEFAULT_MAX_CHARS);
     }