pi-distill 1.1.2 → 1.2.0

package/README.md

@@ -110,7 +110,7 @@ Agent consumes a result suited to the current decision, with auditable diagnosti
 2. The `tool_call` handler captures the parameter and removes it before forwarding the call, so the underlying tool never receives the extension-only field.
 3. The `tool_result` handler sees the actual output and decides what to do; it does not rely on the agent predicting the output size.
 4. Every tool call must include a non-empty `outputRequest`. A prompt containing only `RAW` explicitly requests the original. Any other non-empty prompt permits distillation once the configured threshold is reached.
-5. If distillation fails, no model is available, or compression is ineffective, the original facts are retained and the status is exposed through details and the audit card.
+5. A timed-out attempt is retried according to `timeoutRetryCount`, while other failures use `errorRetryCount` (both default to one retry). If all attempts fail, no model is available, or compression is ineffective, the original facts are retained and the status is exposed through details and the audit card. JSON responses wrapped in Markdown fences such as `````json … ````` are also accepted.
 
 ## Output contract
 
@@ -118,7 +118,7 @@ Agent consumes a result suited to the current decision, with auditable diagnosti
 | --- | --- | --- |
 | Omitted | Invalid tool call; Pi rejects the call before the underlying tool runs | Never omit it; use `RAW` when no compression is explicitly requested |
 | Exactly `RAW` (case-insensitive) | Skip the distillation model and keep the complete original text; oversized text is handled by Pi's own output-limiting mechanism | You need to inspect, copy, or verify exact output |
-| Any non-empty value other than `RAW` | Call the model once the output reaches the threshold; the prompt defines what to retain | “Keep errors, warnings, and final status” workflows |
+| Any non-empty value other than `RAW` | Call the model when the output reaches the threshold; timed-out and other failed attempts use separate retry budgets, and the prompt defines what to retain | “Keep errors, warnings, and final status” workflows |
 | Any non-text content such as images or audio | Preserve the result as-is; do not send it to the distillation model or apply text truncation | Image reads, binary results, and mixed text/media results |
 
 `RAW` is the deterministic completeness signal. The distillation prompt tells the summarizer to return exactly `RAW` when the request clearly asks for complete extraction without omissions, especially for syntax, parameters, SQL, API calls, or other text that must be copied. Passing `RAW` directly remains the preferred option when the tool caller can control the parameter.
@@ -157,7 +157,10 @@ Start from [`config.example.json`](./config.example.json):
   "model": "",
   "minChars": 200,
   "maxChars": 100000,
+  "maxOutputChars": 10000,
   "timeoutSeconds": 10,
+  "timeoutRetryCount": 1,
+  "errorRetryCount": 1,
   "missedCompressionRatio": 10,
   "summarizeErrors": true,
   "render": {
@@ -174,8 +177,11 @@ Configuration-file fields take precedence over environment variables. Unspecifie
 | --- | --- |
 | `model` | Optional `provider/model`; empty uses the current Pi session model. |
 | `minChars` | Minimum output size before a summary is requested. |
-| `maxChars` | Maximum output budget for the distillation model (about `maxChars / 2` tokens) and a diagnostic reference; no longer used to write files. |
-| `timeoutSeconds` | Maximum time allowed for the distillation model call. |
+| `maxChars` | Distilled text is written to a temporary file when it exceeds this length. |
+| `maxOutputChars` | Maximum text returned to the Agent. Oversized text is written to a temporary file and replaced with a file pointer. |
+| `timeoutSeconds` | Maximum time allowed for each distillation model attempt. |
+| `timeoutRetryCount` | Number of additional attempts after a timeout. Defaults to `1`; set to `0` to disable timeout retries. |
+| `errorRetryCount` | Number of additional attempts after any non-timeout error. Defaults to `1`; set to `0` to disable other error retries. |
 | `missedCompressionRatio` | Long-output threshold for a diagnostic when no summary prompt was supplied. |
 | `summarizeErrors` | Whether error results that meet `minChars` should still be sent to the distillation model. |
 | `tools.<name>.enabled` | Enables or disables `outputRequest` injection and result distillation for one tool. `edit` and `write` default to disabled; other unconfigured tools default to enabled. It can also be changed from `/config:distill`. |
@@ -183,7 +189,7 @@ Configuration-file fields take precedence over environment variables. Unspecifie
 `/pi-distill` remains available as a compatibility alias.
 | `render.*` | Controls the audit card, prompt preview, and result preview. |
 
-The main environment variables are `PI_DISTILL_MODEL`, `PI_DISTILL_MIN_CHARS`, `PI_DISTILL_MAX_CHARS`, `PI_DISTILL_TIMEOUT_SECONDS`, `PI_DISTILL_MISSED_COMPRESSION_RATIO`, and `PI_DISTILL_SUMMARIZE_ERRORS`. The legacy `maxOutputChars` / `PI_DISTILL_MAX_OUTPUT_CHARS` option is still parsed for backward compatibility but no longer has any effect.
+The main environment variables are `PI_DISTILL_MODEL`, `PI_DISTILL_MIN_CHARS`, `PI_DISTILL_MAX_CHARS`, `PI_DISTILL_MAX_OUTPUT_CHARS`, `PI_DISTILL_TIMEOUT_SECONDS`, `PI_DISTILL_TIMEOUT_RETRY_COUNT`, `PI_DISTILL_ERROR_RETRY_COUNT`, `PI_DISTILL_MISSED_COMPRESSION_RATIO`, and `PI_DISTILL_SUMMARIZE_ERRORS`.
 
 ## Requirements
 

package/README.zh-CN.md

@@ -112,7 +112,7 @@ Agent 消费更适合当前决策的结果，并获得可审计的处理诊断
 2. `tool_call` 事件捕获这个参数，并在交给底层工具前移除它，因此原工具不会收到扩展专用字段。
 3. `tool_result` 事件拿到真实输出后再做判断，不依赖 Agent 对输出长度的预测。
 4. 每次工具调用都必须包含非空的 `outputRequest`；严格的 `RAW` 表示明确要求原文；其他非空 prompt 才允许进入提炼流程。
-5. 提炼失败、没有可用模型或结果收益过低时，扩展保留原始事实，并通过 details 和审计卡片暴露状态。
+5. 单次提炼超时后按照 `timeoutRetryCount` 重试，其他异常按照 `errorRetryCount` 重试（两者默认都重试 1 次）；全部尝试失败、没有可用模型或结果收益过低时，扩展保留原始事实，并通过 details 和审计卡片暴露状态；模型用 Markdown 的 JSON 代码围栏（如 `````json … `````）包裹响应时也会兼容解析。
 
 ## 输出处理契约
 
@@ -120,7 +120,7 @@ Agent 消费更适合当前决策的结果，并获得可审计的处理诊断
 | --- | --- | --- |
 | 未提供 | 工具调用无效；Pi 会在底层工具执行前拒绝该调用 | 不要省略；未明确要求压缩时使用 `RAW` |
 | 严格为 `RAW`（大小写不敏感） | 不调用提炼模型，保留完整原始文本；超长时由 Pi 自身的输出限制机制处理 | 逐字核对、复制内容、需要完整日志时 |
-| 任意非空且非 `RAW` | 输出达到阈值后调用模型，具体保留内容由 prompt 决定 | “只保留错误、警告和最终状态”等场景 |
+| 任意非空且非 `RAW` | 输出达到阈值后调用模型，超时与其他异常分别使用独立重试次数，具体保留内容由 prompt 决定 | “只保留错误、警告和最终状态”等场景 |
 | 包含图片、音频或其他非文本内容 | 原样保留，不发送给提炼模型，不做文本长度截断 | 图片读取、二进制结果、混合文本与图片结果 |
 
 `RAW` 是确定性的完整输出信号。提炼 prompt 会要求总结模型在用户明确要求“不遗漏地完整提取”时直接返回 `RAW`，尤其适用于语法、参数、SQL、API 调用或其他需要复制的精确文本。工具调用方可以控制参数时，直接传 `RAW` 仍然是首选方式。
@@ -159,7 +159,10 @@ Agent 消费更适合当前决策的结果，并获得可审计的处理诊断
   "model": "",
   "minChars": 200,
   "maxChars": 100000,
+  "maxOutputChars": 10000,
   "timeoutSeconds": 10,
+  "timeoutRetryCount": 1,
+  "errorRetryCount": 1,
   "missedCompressionRatio": 10,
   "summarizeErrors": true,
   "tools": {},
@@ -177,8 +180,11 @@ Agent 消费更适合当前决策的结果，并获得可审计的处理诊断
 | --- | --- |
 | `model` | 可选的 `provider/model`；为空时使用当前 Pi 会话模型。 |
 | `minChars` | 达到此输出长度后才请求提炼。 |
-| `maxChars` | 提炼模型的最大输出预算（约 `maxChars / 2` tokens），同时作为诊断参考；不再用于写文件。 |
-| `timeoutSeconds` | 提炼模型调用的最长等待时间。 |
+| `maxChars` | 提炼结果超过此字符数时写入临时文件。 |
+| `maxOutputChars` | 最终返回给 Agent 的文本上限。超出后写入临时文件，只返回文件指针。 |
+| `timeoutSeconds` | 每次提炼模型尝试的最长等待时间。 |
+| `timeoutRetryCount` | 超时后的额外重试次数。默认 `1`；设为 `0` 时不重试超时。 |
+| `errorRetryCount` | 非超时异常后的额外重试次数。默认 `1`；设为 `0` 时不重试其他异常。 |
 | `missedCompressionRatio` | 没有提供摘要 prompt 时，用于长输出诊断的倍数阈值。 |
 | `summarizeErrors` | 工具返回错误且达到 `minChars` 时，是否仍发送给提炼模型。 |
 | `tools.<name>.enabled` | 按工具开启或关闭 `outputRequest` 注入和结果提炼。`edit` 和 `write` 默认关闭，其他未配置工具默认开启，也可以通过 `/config:distill` 修改。 |
@@ -186,7 +192,7 @@ Agent 消费更适合当前决策的结果，并获得可审计的处理诊断
 `/pi-distill` 仍作为兼容别名保留。
 | `render.*` | 控制审计卡片、prompt 预览和结果预览。 |
 
-主要环境变量包括 `PI_DISTILL_MODEL`、`PI_DISTILL_MIN_CHARS`、`PI_DISTILL_MAX_CHARS`、`PI_DISTILL_TIMEOUT_SECONDS`、`PI_DISTILL_MISSED_COMPRESSION_RATIO` 和 `PI_DISTILL_SUMMARIZE_ERRORS`。旧配置中的 `maxOutputChars` / `PI_DISTILL_MAX_OUTPUT_CHARS` 仍会被解析以兼容旧文件，但不再生效。
+主要环境变量包括 `PI_DISTILL_MODEL`、`PI_DISTILL_MIN_CHARS`、`PI_DISTILL_MAX_CHARS`、`PI_DISTILL_MAX_OUTPUT_CHARS`、`PI_DISTILL_TIMEOUT_SECONDS`、`PI_DISTILL_TIMEOUT_RETRY_COUNT`、`PI_DISTILL_ERROR_RETRY_COUNT`、`PI_DISTILL_MISSED_COMPRESSION_RATIO` 和 `PI_DISTILL_SUMMARIZE_ERRORS`。
 
 ## 要求
 

package/config.example.json

@@ -3,7 +3,10 @@
   "model": "",
   "minChars": 200,
   "maxChars": 100000,
+  "maxOutputChars": 10000,
   "timeoutSeconds": 10,
+  "timeoutRetryCount": 1,
+  "errorRetryCount": 1,
   "missedCompressionRatio": 10,
   "summarizeErrors": true,
   "tools": {},

package/locales/index.json

@@ -11,6 +11,10 @@
     "zh-CN": "请输入大于 0 的整数。",
     "en-US": "Enter a positive integer."
   },
+  "nonNegativeInteger": {
+    "zh-CN": "请输入大于或等于 0 的整数。",
+    "en-US": "Enter a non-negative integer."
+  },
   "modelInput": {
     "zh-CN": "模型（provider/model；留空使用当前会话模型）",
     "en-US": "Model (provider/model; leave empty to use the current session model)"
@@ -71,6 +75,14 @@
     "zh-CN": "超时：{value}s",
     "en-US": "Timeout: {value}s"
   },
+  "timeoutRetryCount": {
+    "zh-CN": "超时重试：{value} 次",
+    "en-US": "Timeout retries: {value}"
+  },
+  "errorRetryCount": {
+    "zh-CN": "异常重试：{value} 次",
+    "en-US": "Error retries: {value}"
+  },
   "threshold": {
     "zh-CN": "长输出阈值：{value}x",
     "en-US": "Long-output threshold: {value}x"
@@ -119,10 +131,38 @@
     "zh-CN": "最终输出字符上限",
     "en-US": "Final output character limit"
   },
+  "outputLimitExceeded": {
+    "zh-CN": "输出超过 {maxChars} 个字符，完整内容已写入：{path}",
+    "en-US": "Output exceeded {maxChars} chars and was written to: {path}"
+  },
+  "outputLimitWriteFailed": {
+    "zh-CN": "无法写入超长输出临时文件，将返回截断内容：{error}",
+    "en-US": "Failed to write oversized output to a temp file; returning truncated content: {error}"
+  },
   "timeoutTitle": {
     "zh-CN": "提炼模型超时（秒）",
     "en-US": "Summarizer timeout (seconds)"
   },
+  "timeoutRetryCountTitle": {
+    "zh-CN": "提炼超时重试次数",
+    "en-US": "Distillation timeout retry count"
+  },
+  "errorRetryCountTitle": {
+    "zh-CN": "提炼非超时异常重试次数",
+    "en-US": "Distillation non-timeout error retry count"
+  },
+  "retryingSummary": {
+    "zh-CN": "提炼发生{kind}，正在进行第 {retry}/{limit} 次重试：{error}",
+    "en-US": "Distillation hit {kind}; starting retry {retry}/{limit}: {error}"
+  },
+  "retryKindTimeout": {
+    "zh-CN": "超时",
+    "en-US": "a timeout"
+  },
+  "retryKindError": {
+    "zh-CN": "非超时异常",
+    "en-US": "a non-timeout error"
+  },
   "thresholdTitle": {
     "zh-CN": "长输出阈值",
     "en-US": "Long-output threshold"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-distill",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Pi tool-output distillation with file-first configuration",
   "type": "module",
   "main": "./index.ts",

package/src/index.ts

@@ -6,7 +6,8 @@
  *
  * 所有工具统一使用 outputRequest：严格传入 RAW 时返回原始输出；其他非空
  * outputRequest 表示调用提炼模型，具体保留内容由 outputRequest 决定。
- * 提炼结果超过 maxChars 时写入临时文件，只返回文件路径。
+ * 提炼结果超过 maxChars 时写入临时文件，只返回文件路径；最终返回内容
+ * 超过 maxOutputChars 时同样写入临时文件，只把文件指针交给 Agent。
  *
  * 配置文件优先；旧环境变量继续兼容：
  * - ~/.pi/agent/extensions/pi-distill/config.json
@@ -15,6 +16,8 @@
  * - PI_DISTILL_MAX_CHARS=提炼结果超过此字符数时写入文件，默认 100000
  * - PI_DISTILL_MAX_OUTPUT_CHARS=最终返回内容超过此字符数时写入文件，默认 10000
  * - PI_DISTILL_TIMEOUT_SECONDS=模型调用最长等待秒数，默认 10
+ * - PI_DISTILL_TIMEOUT_RETRY_COUNT=提炼超时后的额外重试次数，默认 1；0 表示不重试
+ * - PI_DISTILL_ERROR_RETRY_COUNT=其他异常后的额外重试次数，默认 1；0 表示不重试
  * - PI_DISTILL_MISSED_COMPRESSION_RATIO=长输出提醒倍数，默认 10
  * - 旧 PI_BASH_SUMMARY_* 变量作为兼容回退
  */
@@ -36,7 +39,7 @@ import {
   isDistillToolDisplayMiddlewareActive,
   registerDistillToolDisplayMiddleware,
 } from "./tool-display-bridge.ts";
-import { getTextContent, hasNonTextContent } from "./output-limit.ts";
+import { getTextContent, hasNonTextContent, limitReturnedToolResult } from "./output-limit.ts";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
@@ -279,9 +282,10 @@ async function writeSummaryFile(summary: string): Promise<string> {
 }
 
 function parseSummaryResponse(text: string, summaryModel: string): SummaryResult {
+  const normalizedText = unwrapJsonCodeFence(text);
   let payload: unknown;
   try {
-    payload = JSON.parse(text);
+    payload = JSON.parse(normalizedText);
   } catch (error) {
     throw new Error(`Summarizer returned invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
   }
@@ -336,6 +340,13 @@ function parseSummaryResponse(text: string, summaryModel: string): SummaryResult
   };
 }
 
+/** 兼容模型用 Markdown JSON 代码围栏包裹结构化响应的常见输出格式。 */
+function unwrapJsonCodeFence(text: string): string {
+  const trimmed = text.trim();
+  const match = trimmed.match(/^(`{3,})[ \t]*(?:json)?[ \t]*\r?\n([\s\S]*?)\r?\n\1[ \t]*$/i);
+  return match?.[2]?.trim() ?? trimmed;
+}
+
 async function summarizeOutput(
   prompt: string,
   output: string,
@@ -407,6 +418,63 @@ async function summarizeOutput(
   };
 }
 
+async function summarizeOutputWithRetries(
+  prompt: string,
+  output: string,
+  config: BashSummaryConfig,
+  context: DistillExecutionContext,
+  completion: SummaryCompletion,
+): Promise<SummaryResult> {
+  let timeoutRetries = 0;
+  let errorRetries = 0;
+
+  while (true) {
+    if (context.signal?.aborted) {
+      throw new Error("Summarization aborted");
+    }
+
+    const attemptController = new AbortController();
+    const abortFromParent = () => attemptController.abort();
+    context.signal?.addEventListener("abort", abortFromParent, { once: true });
+    if (context.signal?.aborted) attemptController.abort();
+    let timedOut = false;
+    const timeout = setTimeout(
+      () => {
+        timedOut = true;
+        attemptController.abort();
+      },
+      config.timeoutSeconds * 1000,
+    );
+
+    try {
+      return await summarizeOutput(
+        prompt,
+        output,
+        config,
+        context,
+        attemptController.signal,
+        completion,
+      );
+    } catch (error) {
+      if (context.signal?.aborted) throw error;
+      const retryLimit = timedOut ? config.timeoutRetryCount : config.errorRetryCount;
+      const retriesUsed = timedOut ? timeoutRetries : errorRetries;
+      if (retriesUsed >= retryLimit) throw error;
+      if (timedOut) timeoutRetries += 1;
+      else errorRetries += 1;
+      console.warn(i18n.t("retryingSummary", {
+        kind: i18n.t(timedOut ? "retryKindTimeout" : "retryKindError"),
+        retry: retriesUsed + 1,
+        limit: retryLimit,
+        error: error instanceof Error ? error.message : String(error),
+      }));
+    } finally {
+      clearTimeout(timeout);
+      context.signal?.removeEventListener("abort", abortFromParent);
+    }
+  }
+}
+
 function getOutputRequest(params: Record<string, unknown>): string {
   return typeof params.outputRequest === "string"
     ? params.outputRequest.trim()
@@ -423,8 +491,10 @@ export async function processToolResult(
   const loaded = loadDistillConfig();
   const config = loaded.config;
   const outputSummaryRender = { ...loaded.render };
-  // Merge with Pi's native output limiter; this extension must not truncate tool results itself.
-  const finish = (candidate: ToolResult) => candidate;
+  // Pi may persist raw tool output before this hook runs. This second limit
+  // protects the post-distillation result, including RAW and fallbacks.
+  const maxReturnedChars = config?.maxOutputChars ?? 10_000;
+  const finish = (candidate: ToolResult) => limitReturnedToolResult(candidate, maxReturnedChars);
   if (loaded.warnings.length > 0) {
     console.warn(`[pi-distill] ${loaded.warnings.join(" | ")}`);
   }
@@ -504,17 +574,12 @@ export async function processToolResult(
   }
 
   const summaryStartedAt = performance.now();
-  const timeoutController = new AbortController();
-  const abortFromParent = () => timeoutController.abort();
-  context.signal?.addEventListener("abort", abortFromParent, { once: true });
-  const timeout = setTimeout(() => timeoutController.abort(), config.timeoutSeconds * 1000);
   try {
-    const summarized = await summarizeOutput(
+    const summarized = await summarizeOutputWithRetries(
       prompt,
       output,
       config,
       context,
-      timeoutController.signal,
       completion,
     );
     const summaryDurationMs = Math.round(performance.now() - summaryStartedAt);
@@ -649,9 +714,6 @@ export async function processToolResult(
         : result.content,
     };
     return finish(candidate);
-  } finally {
-    clearTimeout(timeout);
-    context.signal?.removeEventListener("abort", abortFromParent);
   }
 }
 
@@ -745,7 +807,7 @@ function toToolResultEventResult(result: ToolResult): ToolResultEventPatch {
   };
 }
 
-type DistillUiConfig = Required<Pick<DistillConfigFile, "enabled" | "model" | "minChars" | "maxChars" | "maxOutputChars" | "timeoutSeconds" | "missedCompressionRatio" | "summarizeErrors">> & {
+type DistillUiConfig = Required<Pick<DistillConfigFile, "enabled" | "model" | "minChars" | "maxChars" | "maxOutputChars" | "timeoutSeconds" | "timeoutRetryCount" | "errorRetryCount" | "missedCompressionRatio" | "summarizeErrors">> & {
   tools: DistillToolConfig;
   render: DistillRenderConfig;
 };
@@ -762,6 +824,8 @@ function getDistillUiConfig(): DistillUiConfig {
     maxChars: config?.maxChars ?? 100_000,
     maxOutputChars: config?.maxOutputChars ?? 10_000,
     timeoutSeconds: config?.timeoutSeconds ?? 10,
+    timeoutRetryCount: config?.timeoutRetryCount ?? 1,
+    errorRetryCount: config?.errorRetryCount ?? 1,
     missedCompressionRatio: config?.missedCompressionRatio ?? 10,
     summarizeErrors: config?.summarizeErrors ?? true,
     tools: Object.fromEntries(
@@ -785,6 +849,22 @@ async function editDistillNumber(
   return Number(value);
 }
 
+async function editDistillNonNegativeInteger(
+  ctx: ExtensionCommandContext,
+  title: string,
+  current: number,
+): Promise<number | undefined> {
+  const value = await ctx.ui.input(title, String(current));
+  if (value === undefined) return undefined;
+  const normalized = value.trim();
+  const parsed = Number(normalized);
+  if (!/^\d+$/.test(normalized) || !Number.isSafeInteger(parsed)) {
+    ctx.ui.notify(i18n.t("nonNegativeInteger"), "error");
+    return undefined;
+  }
+  return parsed;
+}
+
 async function editDistillModel(
   ctx: ExtensionCommandContext,
   current: string,
@@ -873,6 +953,8 @@ async function runDistillConfigUi(
       i18n.t("summaryLimit", { value: config.maxChars }),
       i18n.t("finalLimit", { value: config.maxOutputChars }),
       i18n.t("timeout", { value: config.timeoutSeconds }),
+      i18n.t("timeoutRetryCount", { value: config.timeoutRetryCount }),
+      i18n.t("errorRetryCount", { value: config.errorRetryCount }),
       i18n.t("threshold", { value: config.missedCompressionRatio }),
       i18n.t("summarizeErrors", { value: config.summarizeErrors ? i18n.t("on") : i18n.t("off") }),
       i18n.t("auditRenderer", { value: config.render.enabled ? i18n.t("on") : i18n.t("off") }),
@@ -917,24 +999,44 @@ async function runDistillConfigUi(
         await saveDistillConfigFile(ctx, config, configPath, onSaved);
       }
     } else if (choice === choices[6]) {
+      const value = await editDistillNonNegativeInteger(
+        ctx,
+        i18n.t("timeoutRetryCountTitle"),
+        config.timeoutRetryCount,
+      );
+      if (value !== undefined) {
+        config.timeoutRetryCount = value;
+        await saveDistillConfigFile(ctx, config, configPath, onSaved);
+      }
+    } else if (choice === choices[7]) {
+      const value = await editDistillNonNegativeInteger(
+        ctx,
+        i18n.t("errorRetryCountTitle"),
+        config.errorRetryCount,
+      );
+      if (value !== undefined) {
+        config.errorRetryCount = value;
+        await saveDistillConfigFile(ctx, config, configPath, onSaved);
+      }
+    } else if (choice === choices[8]) {
       const value = await editDistillNumber(ctx, i18n.t("thresholdTitle"), config.missedCompressionRatio);
       if (value !== undefined) {
         config.missedCompressionRatio = value;
         await saveDistillConfigFile(ctx, config, configPath, onSaved);
       }
-    } else if (choice === choices[7]) {
+    } else if (choice === choices[9]) {
       config.summarizeErrors = !config.summarizeErrors;
       await saveDistillConfigFile(ctx, config, configPath, onSaved);
-    } else if (choice === choices[8]) {
+    } else if (choice === choices[10]) {
       config.render.enabled = !config.render.enabled;
       await saveDistillConfigFile(ctx, config, configPath, onSaved);
-    } else if (choice === choices[9]) {
+    } else if (choice === choices[11]) {
       config.render.showPrompt = !config.render.showPrompt;
       await saveDistillConfigFile(ctx, config, configPath, onSaved);
-    } else if (choice === choices[10]) {
+    } else if (choice === choices[12]) {
       config.render.showResult = !config.render.showResult;
       await saveDistillConfigFile(ctx, config, configPath, onSaved);
-    } else if (choice === choices[11]) {
+    } else if (choice === choices[13]) {
       await runDistillToolConfigUi(ctx, pi, config, configPath, onSaved);
     }
   }

package/src/output-limit.ts

@@ -1,3 +1,10 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createTranslator, loadCatalog } from "pi-extensions-i18n";
+
+const i18n = createTranslator(loadCatalog(new URL("../locales/index.json", import.meta.url)));
+
 export type OutputLimitToolResult = {
   content: Array<{ type?: string; text?: string }>;
   details?: {
@@ -15,3 +22,53 @@ export function getTextContent(result: OutputLimitToolResult): string {
 export function hasNonTextContent(result: OutputLimitToolResult): boolean {
   return result.content.some((content) => content.type !== "text" || typeof content.text !== "string");
 }
+
+async function writeOutputFile(text: string): Promise<string> {
+  const directory = join(tmpdir(), "pi-distill");
+  await mkdir(directory, { recursive: true });
+  const filePath = join(
+    directory,
+    `output-${Date.now()}-${Math.random().toString(16).slice(2)}.txt`,
+  );
+  await writeFile(filePath, text, "utf8");
+  return filePath;
+}
+
+/** Limit text entering the next Agent context; preserve non-text content. */
+export async function limitReturnedToolResult(
+  result: OutputLimitToolResult,
+  maxChars: number,
+): Promise<OutputLimitToolResult> {
+  if (hasNonTextContent(result)) return result;
+
+  const text = getTextContent(result);
+  if (text.length <= maxChars) return result;
+
+  try {
+    const filePath = await writeOutputFile(text);
+    const pointer = i18n.t("outputLimitExceeded", { maxChars, path: filePath });
+    return {
+      ...result,
+      content: [{ type: "text", text: pointer.slice(0, maxChars) }],
+      details: {
+        ...(result.details ?? {}),
+        fullOutputPath: filePath,
+        outputTruncated: true,
+        outputLimitChars: maxChars,
+      },
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(i18n.t("outputLimitWriteFailed", { error: message }));
+    return {
+      ...result,
+      content: [{ type: "text", text: text.slice(0, maxChars) }],
+      details: {
+        ...(result.details ?? {}),
+        outputTruncated: true,
+        outputLimitChars: maxChars,
+        outputFileError: message,
+      },
+    };
+  }
+}

package/src/summary-utils.ts

@@ -9,6 +9,8 @@ const DEFAULT_MIN_CHARS = 200;
 const DEFAULT_MAX_CHARS = 100_000;
 const DEFAULT_MAX_OUTPUT_CHARS = 10_000;
 const DEFAULT_TIMEOUT_SECONDS = 10;
+const DEFAULT_TIMEOUT_RETRY_COUNT = 1;
+const DEFAULT_ERROR_RETRY_COUNT = 1;
 const DEFAULT_MISSED_COMPRESSION_RATIO = 10;
 const DEFAULT_SUMMARIZE_ERRORS = true;
 const DEFAULT_RENDER_ENABLED = true;
@@ -30,6 +32,10 @@ export interface BashSummaryConfig {
   maxOutputChars: number;
   /** 模型调用最长等待时间。 */
   timeoutSeconds: number;
+  /** 单次提炼因超时失败后的额外重试次数。 */
+  timeoutRetryCount: number;
+  /** 单次提炼因非超时异常失败后的额外重试次数。 */
+  errorRetryCount: number;
   /** 无 prompt 的长输出触发 missed-compression 提醒所需的倍数。 */
   missedCompressionRatio: number;
   /** 工具返回错误且达到最小长度时是否仍调用提炼模型。 */
@@ -60,6 +66,8 @@ export interface DistillConfigFile {
   maxChars?: number;
   maxOutputChars?: number;
   timeoutSeconds?: number;
+  timeoutRetryCount?: number;
+  errorRetryCount?: number;
   missedCompressionRatio?: number;
   summarizeErrors?: boolean;
   tools?: DistillToolConfig;
@@ -109,6 +117,8 @@ export function parseBashSummaryConfig(
   const timeoutSecondsValue = (
     env.PI_DISTILL_TIMEOUT_SECONDS ?? env.PI_BASH_SUMMARY_TIMEOUT_SECONDS
   )?.trim();
+  const timeoutRetryCountValue = env.PI_DISTILL_TIMEOUT_RETRY_COUNT?.trim();
+  const errorRetryCountValue = env.PI_DISTILL_ERROR_RETRY_COUNT?.trim();
   const missedCompressionRatioValue = (
     env.PI_DISTILL_MISSED_COMPRESSION_RATIO ?? env.PI_BASH_SUMMARY_MISSED_COMPRESSION_RATIO
   )?.trim();
@@ -127,6 +137,12 @@ export function parseBashSummaryConfig(
   const timeoutSeconds = timeoutSecondsValue
     ? parsePositiveInteger(timeoutSecondsValue)
     : DEFAULT_TIMEOUT_SECONDS;
+  const timeoutRetryCount = timeoutRetryCountValue
+    ? parseNonNegativeInteger(timeoutRetryCountValue)
+    : DEFAULT_TIMEOUT_RETRY_COUNT;
+  const errorRetryCount = errorRetryCountValue
+    ? parseNonNegativeInteger(errorRetryCountValue)
+    : DEFAULT_ERROR_RETRY_COUNT;
   const missedCompressionRatio = missedCompressionRatioValue
     ? parsePositiveNumber(missedCompressionRatioValue)
     : DEFAULT_MISSED_COMPRESSION_RATIO;
@@ -138,12 +154,14 @@ export function parseBashSummaryConfig(
     minChars === undefined ||
     maxChars === undefined ||
     timeoutSeconds === undefined ||
+    timeoutRetryCount === undefined ||
+    errorRetryCount === undefined ||
     maxOutputChars === undefined ||
     missedCompressionRatio === undefined ||
     summarizeErrors === undefined
   ) {
     console.warn(
-      "[pi-distill] Invalid distillation config; distillation disabled. Check PI_DISTILL_MIN_CHARS, PI_DISTILL_MAX_CHARS, PI_DISTILL_MAX_OUTPUT_CHARS, PI_DISTILL_TIMEOUT_SECONDS, PI_DISTILL_MISSED_COMPRESSION_RATIO, and PI_DISTILL_SUMMARIZE_ERRORS (legacy PI_BASH_SUMMARY_* variables remain supported).",
+      "[pi-distill] Invalid distillation config; distillation disabled. Check PI_DISTILL_MIN_CHARS, PI_DISTILL_MAX_CHARS, PI_DISTILL_MAX_OUTPUT_CHARS, PI_DISTILL_TIMEOUT_SECONDS, PI_DISTILL_TIMEOUT_RETRY_COUNT, PI_DISTILL_ERROR_RETRY_COUNT, PI_DISTILL_MISSED_COMPRESSION_RATIO, and PI_DISTILL_SUMMARIZE_ERRORS (legacy PI_BASH_SUMMARY_* variables remain supported).",
     );
     return undefined;
   }
@@ -154,6 +172,8 @@ export function parseBashSummaryConfig(
       maxChars,
       maxOutputChars,
       timeoutSeconds,
+      timeoutRetryCount,
+      errorRetryCount,
       missedCompressionRatio,
       summarizeErrors,
     };
@@ -174,6 +194,8 @@ export function parseBashSummaryConfig(
     maxChars,
     maxOutputChars,
     timeoutSeconds,
+    timeoutRetryCount,
+    errorRetryCount,
     missedCompressionRatio,
     summarizeErrors,
   };
@@ -189,6 +211,12 @@ function parsePositiveInteger(value: string | undefined): number | undefined {
   return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
 }
 
+function parseNonNegativeInteger(value: string | undefined): number | undefined {
+  if (!value || !/^\d+$/.test(value)) return undefined;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : undefined;
+}
+
 function parsePositiveNumber(value: string): number | undefined {
   if (!/^\d+(?:\.\d+)?$/.test(value)) return undefined;
   const parsed = Number(value);
@@ -279,6 +307,19 @@ function appendFileValueToEnv(
     return;
   }
 
+  if (
+    key === "timeoutRetryCount" ||
+    key === "errorRetryCount"
+  ) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+      warnings.push(`Config field ${key} must be a non-negative integer.`);
+      env[envKey] = "__invalid_file_value__";
+      return;
+    }
+    env[envKey] = String(value);
+    return;
+  }
+
   if (typeof value !== "number" || !Number.isFinite(value)) {
     warnings.push(`Config field ${key} must be a positive number.`);
     env[envKey] = "__invalid_file_value__";
@@ -323,6 +364,20 @@ export function loadDistillConfig(
     appendFileValueToEnv(effectiveEnv, file, "maxChars", "PI_DISTILL_MAX_CHARS", warnings);
     appendFileValueToEnv(effectiveEnv, file, "maxOutputChars", "PI_DISTILL_MAX_OUTPUT_CHARS", warnings);
     appendFileValueToEnv(effectiveEnv, file, "timeoutSeconds", "PI_DISTILL_TIMEOUT_SECONDS", warnings);
+    appendFileValueToEnv(
+      effectiveEnv,
+      file,
+      "timeoutRetryCount",
+      "PI_DISTILL_TIMEOUT_RETRY_COUNT",
+      warnings,
+    );
+    appendFileValueToEnv(
+      effectiveEnv,
+      file,
+      "errorRetryCount",
+      "PI_DISTILL_ERROR_RETRY_COUNT",
+      warnings,
+    );
     appendFileValueToEnv(
       effectiveEnv,
       file,
@@ -357,6 +412,8 @@ export function defaultDistillConfigFile(): DistillConfigFile {
     maxChars: DEFAULT_MAX_CHARS,
     maxOutputChars: DEFAULT_MAX_OUTPUT_CHARS,
     timeoutSeconds: DEFAULT_TIMEOUT_SECONDS,
+    timeoutRetryCount: DEFAULT_TIMEOUT_RETRY_COUNT,
+    errorRetryCount: DEFAULT_ERROR_RETRY_COUNT,
     missedCompressionRatio: DEFAULT_MISSED_COMPRESSION_RATIO,
     summarizeErrors: DEFAULT_SUMMARIZE_ERRORS,
     tools: {},