pi-distill 1.2.0 → 1.3.0

package/README.md

@@ -189,6 +189,12 @@ 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. |
 
+## Session statistics
+
+Use `/distill:stats` to view distillation statistics for the current Pi session. Statistics are kept in memory, reset when the session starts, and never store raw tool output.
+
+The report includes tool-result counts, success/failure/fallback counts, model attempts, original and summary character totals, compression ratio, `chars/4` estimated original/summary tokens, estimated tokens saved, and model-reported input/output/cache/total tokens and cost. Counts use compact `k` and `m` units at 1,000 and 1,000,000; durations use `ms`, `s`, or `min` based on their value. Estimated context tokens are labeled as estimates; usage and cost fields are shown as unavailable when the provider does not return usage data.
+
 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

@@ -192,6 +192,12 @@ Agent 消费更适合当前决策的结果，并获得可审计的处理诊断
 `/pi-distill` 仍作为兼容别名保留。
 | `render.*` | 控制审计卡片、prompt 预览和结果预览。 |
 
+## Session 统计
+
+使用 `/distill:stats` 查看当前 Pi 会话的提炼统计。统计只保存在内存中，在会话开始时重置，不保存原始工具输出。
+
+统计包括工具结果数量、成功/失败/回退次数、模型尝试次数、原始与摘要字符数、压缩比、按 `chars/4` 估算的原文/摘要 Token、预计节省 Token、提炼实际消耗的 input/output/cache/total Token 和成本。数量达到 1,000 或 1,000,000 时分别使用 `k` 或 `m` 紧凑显示；耗时会根据数值显示为 `ms`、`s` 或 `min`。原文/摘要 Token 是估算值；provider 未返回 usage 时，提炼消耗 Token 或成本字段显示为不可用。
+
 主要环境变量包括 `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/locales/fallback-renderer.json

@@ -43,6 +43,22 @@
     "zh-CN": "字符",
     "en-US": "chars"
   },
+  "tokens": {
+    "zh-CN": "Token",
+    "en-US": "tokens"
+  },
+  "compressionTokens": {
+    "zh-CN": "压缩消耗",
+    "en-US": "compression"
+  },
+  "tokensSaved": {
+    "zh-CN": "节省",
+    "en-US": "saved"
+  },
+  "savedPercent": {
+    "zh-CN": "节省",
+    "en-US": "saved"
+  },
   "tool": {
     "zh-CN": "工具",
     "en-US": "Tool"

package/locales/index.json

@@ -163,6 +163,14 @@
     "zh-CN": "非超时异常",
     "en-US": "a non-timeout error"
   },
+  "outputRequestUnavailable": {
+    "zh-CN": "无法扩展工具 {tool} 的参数结构；outputRequest 不可用。",
+    "en-US": "Could not extend the {tool} parameter schema; outputRequest is unavailable."
+  },
+  "extendOutputRequestFailed": {
+    "zh-CN": "扩展 outputRequest 参数失败：{error}",
+    "en-US": "Failed to extend the outputRequest parameter: {error}"
+  },
   "thresholdTitle": {
     "zh-CN": "长输出阈值",
     "en-US": "Long-output threshold"
@@ -171,6 +179,18 @@
     "zh-CN": "交互式配置工具输出提炼",
     "en-US": "Configure tool-output distillation interactively"
   },
+  "statsCommandDescription": {
+    "zh-CN": "查看本次会话的工具输出提炼统计",
+    "en-US": "Show tool-output distillation statistics for this session"
+  },
+  "statsUnavailable": {
+    "zh-CN": "不可用",
+    "en-US": "n/a"
+  },
+  "statsReport": {
+    "zh-CN": "Distill 会话统计\n工具结果 {toolResults}｜成功 {summarizedResults}｜回退 {fallbackResults}｜失败 {failedResults}\nRAW {rawResults}｜跳过 {skippedResults}｜非文本 {nonTextResults}\n尝试 {summaryAttempts}｜重试 {retryCount}｜耗时 {summaryDuration}（平均 {summaryAverageDuration}）\n字符：{originalOutputChars} → {summaryChars}（{compressionRatio}x）\nToken（估算）：{estimatedOriginalOutputTokens} → {estimatedSummaryTokens}（节省 {estimatedTokensSaved}）\n模型总 Token：{summaryTotalTokens}（输入 {summaryInputTokens}｜输出 {summaryOutputTokens}｜推理 {summaryReasoningTokens}）\n缓存 Token：读 {summaryCacheReadTokens}｜写 {summaryCacheWriteTokens}\n模型成本：{summaryCost}",
+    "en-US": "Distill session statistics\nTool results {toolResults} | summarized {summarizedResults} | fallback {fallbackResults} | failed {failedResults}\nRAW {rawResults} | skipped {skippedResults} | non-text {nonTextResults}\nAttempts {summaryAttempts} | retries {retryCount} | time {summaryDuration} (avg {summaryAverageDuration})\nChars: {originalOutputChars} → {summaryChars} ({compressionRatio}x)\nTokens (estimated): {estimatedOriginalOutputTokens} → {estimatedSummaryTokens} (saved {estimatedTokensSaved})\nModel total tokens: {summaryTotalTokens} (input {summaryInputTokens} | output {summaryOutputTokens} | reasoning {summaryReasoningTokens})\nCache tokens: read {summaryCacheReadTokens} | write {summaryCacheWriteTokens}\nModel cost: {summaryCost}"
+  },
   "outputRequest": {
     "zh-CN": "outputRequest",
     "en-US": "outputRequest"

package/package.json

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

package/src/fallback-renderer.ts

@@ -56,6 +56,13 @@ function formatCount(value: number): string {
   return Math.round(value).toLocaleString("en-US");
 }
 
+function formatCompactCount(value: number): string {
+  const rounded = Math.round(value);
+  if (rounded >= 1_000_000) return `${(rounded / 1_000_000).toFixed(1).replace(/\.0$/, "")}m`;
+  if (rounded >= 1_000) return `${(rounded / 1_000).toFixed(1).replace(/\.0$/, "")}k`;
+  return String(rounded);
+}
+
 function renderDistillAuditLine(audit: DistillAuditView, line: string, index: number, theme: RenderTheme): string {
   if (index === 0) {
     const title = theme.fg("accent", theme.bold("◇ Distill"));
@@ -191,6 +198,10 @@ export function buildDistillAuditLines(
   const error = getString(details.outputSummaryError);
   const originalChars = getFiniteNumber(details.originalOutputChars);
   const summaryChars = getFiniteNumber(details.summaryChars);
+  const estimatedOriginalTokens = getFiniteNumber(details.estimatedOriginalOutputTokens);
+  const estimatedSummaryTokens = getFiniteNumber(details.estimatedSummaryTokens);
+  const estimatedTokensSaved = getFiniteNumber(details.estimatedTokensSaved);
+  const summaryTotalTokens = getFiniteNumber(details.summaryTotalTokens);
   const compressionRatio = getFiniteNumber(details.compressionRatio);
   const compressionSavedPercent = getFiniteNumber(details.compressionSavedPercent);
   const toolExecutionMs = getFiniteNumber(details.toolExecutionMs);
@@ -201,14 +212,23 @@ export function buildDistillAuditLines(
   const statusView = statusViews[status] ?? { label: status, tone: "muted" as const };
   const metrics: string[] = [];
 
-  if (originalChars !== undefined && summaryChars !== undefined) {
+  if (estimatedOriginalTokens !== undefined && estimatedSummaryTokens !== undefined) {
+    const tokenMetric = `≈${formatCompactCount(estimatedOriginalTokens)} → ${formatCompactCount(estimatedSummaryTokens)} ${i18n.t("tokens")}`;
+    const savedMetric = estimatedTokensSaved !== undefined && estimatedTokensSaved > 0
+      ? `（${i18n.t("tokensSaved")} ≈${formatCompactCount(estimatedTokensSaved)}${compressionSavedPercent !== undefined ? `，${compressionSavedPercent.toFixed(1)}%` : ""}）`
+      : "";
+    metrics.push(`${tokenMetric}${savedMetric}`);
+  } else if (originalChars !== undefined && summaryChars !== undefined) {
     metrics.push(`${formatCount(originalChars)} → ${formatCount(summaryChars)} ${i18n.t("chars")}`);
+    if (compressionRatio !== undefined) metrics.push(`${compressionRatio.toFixed(2)}×`);
+    if (compressionSavedPercent !== undefined) {
+      metrics.push(`${compressionSavedPercent.toFixed(1)}% ${i18n.t("savedPercent")}`);
+    }
   } else if (originalChars !== undefined) {
     metrics.push(`${formatCount(originalChars)} ${i18n.t("chars")}`);
   }
-  if (compressionRatio !== undefined) metrics.push(`${compressionRatio.toFixed(2)}×`);
-  if (compressionSavedPercent !== undefined) {
-    metrics.push(`${compressionSavedPercent.toFixed(1)}% saved`);
+  if (summaryTotalTokens !== undefined && summaryTotalTokens > 0) {
+    metrics.push(`${i18n.t("compressionTokens")} ${formatCompactCount(summaryTotalTokens)} ${i18n.t("tokens")}`);
   }
   if (toolExecutionMs !== undefined && toolExecutionMs >= 50) {
     metrics.push(`${i18n.t("tool")} ${formatDuration(toolExecutionMs)}`);

package/src/index.ts

@@ -123,19 +123,69 @@ type SummaryDecision = {
   reason: string;
 };
 
+type SummaryUsage = {
+  input?: number;
+  output?: number;
+  reasoning?: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+  totalTokens?: number;
+  cost?: {
+    input?: number;
+    output?: number;
+    reasoning?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    total?: number;
+  };
+};
+
 type SummaryResult = {
   text: string;
   summaryChars: number;
   summaryFilePath?: string;
   summaryModel: string;
   decision: SummaryDecision;
+  usage?: SummaryUsage;
+  attempts?: number;
 };
 
 type SummaryCompletion = (...args: Parameters<typeof complete>) => ReturnType<typeof complete>;
+type DistillWarningReporter = (message: string) => void;
+
+class SummaryAttemptError extends Error {
+  constructor(message: string, readonly usage?: SummaryUsage) {
+    super(message);
+    this.name = "SummaryAttemptError";
+  }
+}
+
+class SummaryRetryError extends Error {
+  constructor(
+    message: string,
+    readonly attempts: number,
+    readonly usage?: SummaryUsage,
+  ) {
+    super(message);
+    this.name = "SummaryRetryError";
+  }
+}
 
 type SummaryDiagnostics = {
   toolExecutionMs?: number;
   summaryDurationMs?: number;
+  summaryAttempts?: number;
+  summaryInputTokens?: number;
+  summaryOutputTokens?: number;
+  summaryReasoningTokens?: number;
+  summaryCacheReadTokens?: number;
+  summaryCacheWriteTokens?: number;
+  summaryTotalTokens?: number;
+  summaryCost?: number;
+  /** 原始输出与最终摘要的 Token 数是按 Pi 的 chars/4 规则估算的。 */
+  estimatedOriginalOutputTokens?: number;
+  estimatedSummaryTokens?: number;
+  estimatedTokensSaved?: number;
   outputSummaryIntent?: string;
   outputSummaryPrompt?: string;
   outputSummaryRender?: DistillRenderConfig;
@@ -158,6 +208,278 @@ type SummaryDiagnostics = {
   missedCompressionRatio?: number;
 };
 
+function toFiniteNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function normalizeSummaryUsage(value: unknown): SummaryUsage | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const record = value as Record<string, unknown>;
+  const usage: SummaryUsage = {
+    input: toFiniteNumber(record.input),
+    output: toFiniteNumber(record.output),
+    reasoning: toFiniteNumber(record.reasoning),
+    cacheRead: toFiniteNumber(record.cacheRead),
+    cacheWrite: toFiniteNumber(record.cacheWrite),
+    totalTokens: toFiniteNumber(record.totalTokens),
+  };
+  if (record.cost && typeof record.cost === "object" && !Array.isArray(record.cost)) {
+    const cost = record.cost as Record<string, unknown>;
+    usage.cost = {
+      input: toFiniteNumber(cost.input),
+      output: toFiniteNumber(cost.output),
+      reasoning: toFiniteNumber(cost.reasoning),
+      cacheRead: toFiniteNumber(cost.cacheRead),
+      cacheWrite: toFiniteNumber(cost.cacheWrite),
+      total: toFiniteNumber(cost.total),
+    };
+  }
+  return Object.values(usage).some((entry) => typeof entry === "number") || usage.cost !== undefined
+    ? usage
+    : undefined;
+}
+
+function mergeSummaryUsage(first: SummaryUsage | undefined, second: SummaryUsage | undefined): SummaryUsage | undefined {
+  if (!first && !second) return undefined;
+  const merged: SummaryUsage = {};
+  for (const key of ["input", "output", "reasoning", "cacheRead", "cacheWrite", "totalTokens"] as const) {
+    const value = (first?.[key] ?? 0) + (second?.[key] ?? 0);
+    if ((first?.[key] !== undefined || second?.[key] !== undefined) && Number.isFinite(value)) {
+      merged[key] = value;
+    }
+  }
+  if (first?.cost || second?.cost) {
+    merged.cost = {};
+    for (const key of ["input", "output", "reasoning", "cacheRead", "cacheWrite", "total"] as const) {
+      const value = (first?.cost?.[key] ?? 0) + (second?.cost?.[key] ?? 0);
+      if ((first?.cost?.[key] !== undefined || second?.cost?.[key] !== undefined) && Number.isFinite(value)) {
+        merged.cost[key] = value;
+      }
+    }
+  }
+  return merged;
+}
+
+function getSummaryUsageDiagnostics(usage: SummaryUsage | undefined): Pick<
+  SummaryDiagnostics,
+  "summaryInputTokens" | "summaryOutputTokens" | "summaryReasoningTokens" | "summaryCacheReadTokens" | "summaryCacheWriteTokens" | "summaryTotalTokens" | "summaryCost"
+> {
+  return {
+    summaryInputTokens: usage?.input,
+    summaryOutputTokens: usage?.output,
+    summaryReasoningTokens: usage?.reasoning,
+    summaryCacheReadTokens: usage?.cacheRead,
+    summaryCacheWriteTokens: usage?.cacheWrite,
+    summaryTotalTokens: usage?.totalTokens,
+    summaryCost: usage?.cost?.total,
+  };
+}
+
+const ESTIMATED_CHARS_PER_TOKEN = 4;
+
+function estimateTextTokens(text: string): number {
+  return Math.ceil(text.length / ESTIMATED_CHARS_PER_TOKEN);
+}
+
+function getTokenCompressionDiagnostics(
+  originalOutput: string,
+  finalOutput: string,
+): Pick<SummaryDiagnostics, "estimatedOriginalOutputTokens" | "estimatedSummaryTokens" | "estimatedTokensSaved"> {
+  const estimatedOriginalOutputTokens = estimateTextTokens(originalOutput);
+  const estimatedSummaryTokens = estimateTextTokens(finalOutput);
+  return {
+    estimatedOriginalOutputTokens,
+    estimatedSummaryTokens,
+    estimatedTokensSaved: Math.max(0, estimatedOriginalOutputTokens - estimatedSummaryTokens),
+  };
+}
+
+type DistillSessionStats = {
+  startedAt: number;
+  toolResults: number;
+  summarizedResults: number;
+  fallbackResults: number;
+  failedResults: number;
+  rawResults: number;
+  skippedResults: number;
+  nonTextResults: number;
+  summaryAttempts: number;
+  retryCount: number;
+  originalOutputChars: number;
+  summaryChars: number;
+  summaryDurationMs: number;
+  summaryInputTokens: number;
+  summaryOutputTokens: number;
+  summaryReasoningTokens: number;
+  summaryCacheReadTokens: number;
+  summaryCacheWriteTokens: number;
+  summaryTotalTokens: number;
+  hasSummaryTokenUsage: boolean;
+  estimatedOriginalOutputTokens: number;
+  estimatedSummaryTokens: number;
+  estimatedTokensSaved: number;
+  summaryCost: number;
+  hasSummaryCost: boolean;
+};
+
+function createDistillSessionStats(): DistillSessionStats {
+  return {
+    startedAt: Date.now(),
+    toolResults: 0,
+    summarizedResults: 0,
+    fallbackResults: 0,
+    failedResults: 0,
+    rawResults: 0,
+    skippedResults: 0,
+    nonTextResults: 0,
+    summaryAttempts: 0,
+    retryCount: 0,
+    originalOutputChars: 0,
+    summaryChars: 0,
+    summaryDurationMs: 0,
+    summaryInputTokens: 0,
+    summaryOutputTokens: 0,
+    summaryReasoningTokens: 0,
+    summaryCacheReadTokens: 0,
+    summaryCacheWriteTokens: 0,
+    summaryTotalTokens: 0,
+    hasSummaryTokenUsage: false,
+    estimatedOriginalOutputTokens: 0,
+    estimatedSummaryTokens: 0,
+    estimatedTokensSaved: 0,
+    summaryCost: 0,
+    hasSummaryCost: false,
+  };
+}
+
+function getDetailNumber(details: Record<string, unknown> | undefined, key: string): number | undefined {
+  return toFiniteNumber(details?.[key]);
+}
+
+function recordDistillSessionResult(
+  stats: DistillSessionStats,
+  details: Record<string, unknown> | undefined,
+): void {
+  stats.toolResults += 1;
+  const status = typeof details?.outputSummaryStatus === "string"
+    ? details.outputSummaryStatus
+    : undefined;
+  if (status === "summarized") stats.summarizedResults += 1;
+  else if (status === "summary-fallback") stats.fallbackResults += 1;
+  else if (status === "summary-failed") stats.failedResults += 1;
+  else if (status === "full-output") stats.rawResults += 1;
+  else if (status === "non-text-output") stats.nonTextResults += 1;
+  else stats.skippedResults += 1;
+
+  stats.summaryAttempts += getDetailNumber(details, "summaryAttempts") ?? 0;
+  const attempts = getDetailNumber(details, "summaryAttempts");
+  if (attempts !== undefined) stats.retryCount += Math.max(0, attempts - 1);
+  stats.originalOutputChars += getDetailNumber(details, "originalOutputChars") ?? 0;
+  stats.summaryChars += getDetailNumber(details, "summaryChars") ?? 0;
+  stats.summaryDurationMs += getDetailNumber(details, "summaryDurationMs") ?? 0;
+  stats.summaryInputTokens += getDetailNumber(details, "summaryInputTokens") ?? 0;
+  stats.summaryOutputTokens += getDetailNumber(details, "summaryOutputTokens") ?? 0;
+  stats.summaryReasoningTokens += getDetailNumber(details, "summaryReasoningTokens") ?? 0;
+  stats.summaryCacheReadTokens += getDetailNumber(details, "summaryCacheReadTokens") ?? 0;
+  stats.summaryCacheWriteTokens += getDetailNumber(details, "summaryCacheWriteTokens") ?? 0;
+  const summaryTotalTokens = getDetailNumber(details, "summaryTotalTokens");
+  if (summaryTotalTokens !== undefined) {
+    stats.summaryTotalTokens += summaryTotalTokens;
+  }
+  if (
+    getDetailNumber(details, "summaryInputTokens") !== undefined
+    || getDetailNumber(details, "summaryOutputTokens") !== undefined
+    || getDetailNumber(details, "summaryTotalTokens") !== undefined
+  ) {
+    stats.hasSummaryTokenUsage = true;
+  }
+  stats.estimatedOriginalOutputTokens += getDetailNumber(details, "estimatedOriginalOutputTokens") ?? 0;
+  stats.estimatedSummaryTokens += getDetailNumber(details, "estimatedSummaryTokens") ?? 0;
+  stats.estimatedTokensSaved += getDetailNumber(details, "estimatedTokensSaved") ?? 0;
+  const cost = getDetailNumber(details, "summaryCost");
+  if (cost !== undefined) {
+    stats.summaryCost += cost;
+    stats.hasSummaryCost = true;
+  }
+}
+
+export function formatCompactCount(value: number): string {
+  const absolute = Math.abs(value);
+  const sign = value < 0 ? "-" : "";
+  const formatScaled = (scaled: number): string => {
+    const rounded = Math.round(scaled * 10) / 10;
+    return Number.isInteger(rounded) ? String(rounded) : rounded.toFixed(1);
+  };
+  if (absolute >= 1_000_000) return `${sign}${formatScaled(absolute / 1_000_000)}m`;
+  if (absolute >= 1_000) return `${sign}${formatScaled(absolute / 1_000)}k`;
+  return String(Math.round(value));
+}
+
+export function formatSessionDuration(milliseconds: number): string {
+  if (milliseconds < 1_000) return `${Math.max(0, Math.round(milliseconds))}ms`;
+  const seconds = milliseconds / 1_000;
+  if (seconds < 60) return `${seconds.toFixed(1).replace(/\.0$/, "")}s`;
+  const minutes = seconds / 60;
+  return `${minutes.toFixed(1).replace(/\.0$/, "")}min`;
+}
+
+function formatDistillSessionStats(stats: DistillSessionStats): string {
+  const compressionRatio = stats.summaryChars > 0
+    ? (stats.originalOutputChars / stats.summaryChars).toFixed(2)
+    : "-";
+  const cost = stats.hasSummaryCost ? stats.summaryCost.toFixed(6) : i18n.t("statsUnavailable");
+  const summaryOperations = stats.summarizedResults
+    + stats.fallbackResults
+    + stats.failedResults
+    + stats.rawResults;
+  const averageDurationMs = summaryOperations > 0
+    ? Math.round(stats.summaryDurationMs / summaryOperations)
+    : 0;
+  const tokenUsage = stats.hasSummaryTokenUsage
+    ? {
+        input: formatCompactCount(stats.summaryInputTokens),
+        output: formatCompactCount(stats.summaryOutputTokens),
+        reasoning: formatCompactCount(stats.summaryReasoningTokens),
+        cacheRead: formatCompactCount(stats.summaryCacheReadTokens),
+        cacheWrite: formatCompactCount(stats.summaryCacheWriteTokens),
+        total: formatCompactCount(stats.summaryTotalTokens),
+      }
+    : {
+        input: i18n.t("statsUnavailable"),
+        output: i18n.t("statsUnavailable"),
+        reasoning: i18n.t("statsUnavailable"),
+        cacheRead: i18n.t("statsUnavailable"),
+        cacheWrite: i18n.t("statsUnavailable"),
+        total: i18n.t("statsUnavailable"),
+      };
+  return i18n.t("statsReport", {
+    toolResults: formatCompactCount(stats.toolResults),
+    summarizedResults: formatCompactCount(stats.summarizedResults),
+    fallbackResults: formatCompactCount(stats.fallbackResults),
+    failedResults: formatCompactCount(stats.failedResults),
+    rawResults: formatCompactCount(stats.rawResults),
+    skippedResults: formatCompactCount(stats.skippedResults),
+    nonTextResults: formatCompactCount(stats.nonTextResults),
+    summaryAttempts: formatCompactCount(stats.summaryAttempts),
+    retryCount: formatCompactCount(stats.retryCount),
+    originalOutputChars: formatCompactCount(stats.originalOutputChars),
+    summaryChars: formatCompactCount(stats.summaryChars),
+    compressionRatio,
+    estimatedOriginalOutputTokens: formatCompactCount(stats.estimatedOriginalOutputTokens),
+    estimatedSummaryTokens: formatCompactCount(stats.estimatedSummaryTokens),
+    estimatedTokensSaved: formatCompactCount(stats.estimatedTokensSaved),
+    summaryDuration: formatSessionDuration(stats.summaryDurationMs),
+    summaryAverageDuration: formatSessionDuration(averageDurationMs),
+    summaryInputTokens: tokenUsage.input,
+    summaryOutputTokens: tokenUsage.output,
+    summaryReasoningTokens: tokenUsage.reasoning,
+    summaryCacheReadTokens: tokenUsage.cacheRead,
+    summaryCacheWriteTokens: tokenUsage.cacheWrite,
+    summaryTotalTokens: tokenUsage.total,
+    summaryCost: cost,
+  });
+}
+
 function attachDiagnostics(result: ToolResult, diagnostics: SummaryDiagnostics): ToolResult {
   return {
     ...result,
@@ -394,8 +716,12 @@ async function summarizeOutput(
     },
   );
 
+  const usage = normalizeSummaryUsage(response.usage);
   if (response.stopReason === "error" || response.stopReason === "aborted") {
-    throw new Error(response.errorMessage ?? `Summarizer stopped with reason: ${response.stopReason}`);
+    throw new SummaryAttemptError(
+      response.errorMessage ?? `Summarizer stopped with reason: ${response.stopReason}`,
+      usage,
+    );
   }
 
   const rawResponse = response.content
@@ -404,17 +730,23 @@ async function summarizeOutput(
     .join("\n")
     .trim();
 
-  if (!rawResponse) throw new Error("Summarizer returned no text");
+  if (!rawResponse) throw new SummaryAttemptError("Summarizer returned no text", usage);
   const summaryModel = `${model.provider}/${model.id}`;
-  const parsed = parseSummaryResponse(rawResponse, summaryModel);
-  if (parsed.decision.mode === "RAW") return parsed;
-  if (parsed.summaryChars <= config.maxChars) return parsed;
+  let parsed: SummaryResult;
+  try {
+    parsed = parseSummaryResponse(rawResponse, summaryModel);
+  } catch (error) {
+    throw new SummaryAttemptError(error instanceof Error ? error.message : String(error), usage);
+  }
+  if (parsed.decision.mode === "RAW") return { ...parsed, usage };
+  if (parsed.summaryChars <= config.maxChars) return { ...parsed, usage };
 
   const summaryFilePath = await writeSummaryFile(parsed.text);
   return {
     ...parsed,
     text: `Summary exceeded ${config.maxChars} chars and was written to: ${summaryFilePath}`,
     summaryFilePath,
+    usage,
   };
 }
 
@@ -427,10 +759,12 @@ async function summarizeOutputWithRetries(
 ): Promise<SummaryResult> {
   let timeoutRetries = 0;
   let errorRetries = 0;
+  let attempts = 0;
+  let totalUsage: SummaryUsage | undefined;
 
   while (true) {
     if (context.signal?.aborted) {
-      throw new Error("Summarization aborted");
+      throw new SummaryRetryError("Summarization aborted", attempts, totalUsage);
     }
 
     const attemptController = new AbortController();
@@ -445,9 +779,10 @@ async function summarizeOutputWithRetries(
       },
       config.timeoutSeconds * 1000,
     );
+    attempts += 1;
 
     try {
-      return await summarizeOutput(
+      const result = await summarizeOutput(
         prompt,
         output,
         config,
@@ -455,19 +790,39 @@ async function summarizeOutputWithRetries(
         attemptController.signal,
         completion,
       );
+      totalUsage = mergeSummaryUsage(totalUsage, result.usage);
+      return {
+        ...result,
+        usage: totalUsage,
+        attempts,
+      };
     } catch (error) {
-      if (context.signal?.aborted) throw error;
+      totalUsage = mergeSummaryUsage(
+        totalUsage,
+        error instanceof SummaryAttemptError || error instanceof SummaryRetryError
+          ? error.usage
+          : undefined,
+      );
+      if (context.signal?.aborted) {
+        throw new SummaryRetryError("Summarization aborted", attempts, totalUsage);
+      }
       const retryLimit = timedOut ? config.timeoutRetryCount : config.errorRetryCount;
       const retriesUsed = timedOut ? timeoutRetries : errorRetries;
-      if (retriesUsed >= retryLimit) throw error;
+      if (retriesUsed >= retryLimit) {
+        throw new SummaryRetryError(
+          error instanceof Error ? error.message : String(error),
+          attempts,
+          totalUsage,
+        );
+      }
       if (timedOut) timeoutRetries += 1;
       else errorRetries += 1;
-      console.warn(i18n.t("retryingSummary", {
+      context.ctx.ui.notify(i18n.t("retryingSummary", {
         kind: i18n.t(timedOut ? "retryKindTimeout" : "retryKindError"),
         retry: retriesUsed + 1,
         limit: retryLimit,
         error: error instanceof Error ? error.message : String(error),
-      }));
+      }), "warning");
     } finally {
       clearTimeout(timeout);
       context.signal?.removeEventListener("abort", abortFromParent);
@@ -496,7 +851,9 @@ export async function processToolResult(
   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(" | ")}`);
+    context.ctx.ui.notify(i18n.t("configWarnings", {
+      warnings: loaded.warnings.join(" "),
+    }), "warning");
   }
 
   if (config && loaded.enabled && !isDistillToolEnabled(config, context.toolName)) return result;
@@ -535,9 +892,7 @@ export async function processToolResult(
   try {
     output = await getCompleteOutput(result);
   } catch (error) {
-    console.warn(
-      `[tool-output-summary] ${context.toolName} could not read the full output; returning the original result: ${error instanceof Error ? error.message : String(error)}`,
-    );
+    const errorMessage = error instanceof Error ? error.message : String(error);
     return finish(attachDiagnostics(result, {
       toolExecutionMs,
       outputSummaryPrompt: prompt || undefined,
@@ -547,6 +902,7 @@ export async function processToolResult(
       summaryTriggerMaxChars: null,
       summaryResultMaxChars: config.maxChars,
       missedCompressionRatio: config.missedCompressionRatio,
+      outputSummaryError: errorMessage,
     }));
   }
 
@@ -564,6 +920,7 @@ export async function processToolResult(
       summaryTriggerMaxChars: null,
       summaryResultMaxChars: config.maxChars,
       missedCompressionRatio: config.missedCompressionRatio,
+      ...getTokenCompressionDiagnostics(output, output),
       ...skippedDiagnostics,
     };
     const candidate = {
@@ -594,6 +951,9 @@ export async function processToolResult(
       const diagnostics: SummaryDiagnostics = {
         originalOutputChars: output.length,
         summaryChars: output.length,
+        summaryAttempts: summarized.attempts,
+        ...getSummaryUsageDiagnostics(summarized.usage),
+        ...getTokenCompressionDiagnostics(output, output),
         compressionRatio: 1,
         compressionSavedPercent: 0,
         ...rawDiagnostics,
@@ -628,6 +988,9 @@ export async function processToolResult(
     const summaryDiagnostics: SummaryDiagnostics = {
       originalOutputChars: output.length,
       summaryChars: summarized.summaryChars,
+      summaryAttempts: summarized.attempts,
+      ...getSummaryUsageDiagnostics(summarized.usage),
+      ...getTokenCompressionDiagnostics(output, summarized.text),
       ...compressionDiagnostics,
     };
     const agentDiagnostic = buildAgentDiagnosticText(summaryDiagnostics);
@@ -650,6 +1013,7 @@ export async function processToolResult(
           outputSummaryReasonCode: summarized.decision.reasonCode,
           outputSummaryReason: summarized.decision.reason,
           ...summaryDiagnostics,
+          ...getTokenCompressionDiagnostics(output, output),
         }),
         content: [{ type: "text", text: output }],
       });
@@ -686,14 +1050,14 @@ export async function processToolResult(
   } catch (error) {
     const summaryDurationMs = Math.round(performance.now() - summaryStartedAt);
     const errorMessage = error instanceof Error ? error.message : String(error);
+    const retryError = error instanceof SummaryRetryError ? error : undefined;
     // 总结链路任何异常都必须保留原始结果，不能把异常文本替换给 AI。
-    console.warn(
-      `[tool-output-summary] ${context.toolName} summarization failed; returning the original result: ${errorMessage}`,
-    );
     const diagnostics: SummaryDiagnostics = {
       toolExecutionMs,
       summaryDurationMs,
       originalOutputChars: output.length,
+      summaryAttempts: retryError?.attempts,
+      ...getSummaryUsageDiagnostics(retryError?.usage),
       outputSummaryIntent: decision.intent,
       outputSummaryPrompt: prompt || undefined,
       outputSummaryRender,
@@ -702,6 +1066,7 @@ export async function processToolResult(
       summaryTriggerMaxChars: null,
       summaryResultMaxChars: config.maxChars,
       missedCompressionRatio: config.missedCompressionRatio,
+      ...getTokenCompressionDiagnostics(output, output),
       outputSummaryAnomalies: ["summary-failed"],
       outputSummaryAdvice: `Summarization failed; the original output was preserved. Check model configuration or authentication. Requests still running after ${config.timeoutSeconds}s are treated as timed out.`,
       outputSummaryError: errorMessage,
@@ -739,17 +1104,21 @@ function restoreOutputRequestParameter(parameters: Record<string, unknown>): boo
   return true;
 }
 
-function extendOutputRequestParameter(tool: ToolInfo, enabled: boolean): boolean {
+function extendOutputRequestParameter(
+  tool: ToolInfo,
+  enabled: boolean,
+  reportWarning: DistillWarningReporter,
+): boolean {
   const parameters = tool.parameters as unknown as Record<string, unknown> | undefined;
   if (!parameters || typeof parameters !== "object" || Array.isArray(parameters)) {
-    console.warn(`[pi-distill] Could not extend the ${tool.name} parameter schema; outputRequest is unavailable.`);
+    reportWarning(i18n.t("outputRequestUnavailable", { tool: tool.name }));
     return false;
   }
 
   if (!enabled) return restoreOutputRequestParameter(parameters);
 
   if (parameters.type !== "object") {
-    console.warn(`[pi-distill] Could not extend the ${tool.name} parameter schema; outputRequest is unavailable.`);
+    reportWarning(i18n.t("outputRequestUnavailable", { tool: tool.name }));
     return false;
   }
 
@@ -758,7 +1127,7 @@ function extendOutputRequestParameter(tool: ToolInfo, enabled: boolean): boolean
   if (properties === undefined) {
     parameters.properties = {};
   } else if (typeof properties !== "object" || properties === null || Array.isArray(properties)) {
-    console.warn(`[pi-distill] Could not extend the ${tool.name} parameter schema; outputRequest is unavailable.`);
+    reportWarning(i18n.t("outputRequestUnavailable", { tool: tool.name }));
     return false;
   }
 
@@ -790,11 +1159,12 @@ function extendOutputRequestParameter(tool: ToolInfo, enabled: boolean): boolean
 export function extendDistillToolParameters(
   pi: Pick<ExtensionAPI, "getAllTools">,
   loaded = loadDistillConfig(),
+  reportWarning: DistillWarningReporter = () => undefined,
 ): number {
   let extended = 0;
   for (const tool of pi.getAllTools()) {
     const enabled = loaded.enabled && Boolean(loaded.config) && isDistillToolEnabled(loaded.config, tool.name);
-    if (extendOutputRequestParameter(tool, enabled) && enabled) extended += 1;
+    if (extendOutputRequestParameter(tool, enabled, reportWarning) && enabled) extended += 1;
   }
   return extended;
 }
@@ -1042,7 +1412,10 @@ async function runDistillConfigUi(
   }
 }
 
-function registerDistillConfigCommand(pi: ExtensionAPI, onSaved: () => void): void {
+function registerDistillConfigCommand(
+  pi: ExtensionAPI,
+  onSaved: (ctx: ExtensionCommandContext) => void,
+): void {
   const command = {
     description: i18n.t("commandDescription"),
     handler: async (_args: string, ctx: ExtensionCommandContext) => {
@@ -1050,7 +1423,7 @@ function registerDistillConfigCommand(pi: ExtensionAPI, onSaved: () => void): vo
         ctx.ui.notify(i18n.t("interactiveOnly"), "warning");
         return;
       }
-      await runDistillConfigUi(ctx, pi, getDistillConfigPath(), onSaved);
+      await runDistillConfigUi(ctx, pi, getDistillConfigPath(), () => onSaved(ctx));
     },
   };
   for (const name of ["config:distill", "pi-distill"] as const) {
@@ -1058,23 +1431,51 @@ function registerDistillConfigCommand(pi: ExtensionAPI, onSaved: () => void): vo
   }
 }
 
+function registerDistillStatsCommand(
+  pi: ExtensionAPI,
+  getStats: () => DistillSessionStats,
+): void {
+  pi.registerCommand("distill:stats", {
+    description: i18n.t("statsCommandDescription"),
+    handler: async (_args: string, ctx: ExtensionCommandContext) => {
+      if (!ctx.hasUI) {
+        ctx.ui.notify(i18n.t("interactiveOnly"), "warning");
+        return;
+      }
+      ctx.ui.notify(formatDistillSessionStats(getStats()), "info");
+    },
+  });
+}
+
 export default function piDistillExtension(pi: ExtensionAPI) {
   const pendingCalls = new Map<string, PendingDistillCall>();
+  const reportedWarnings = new Set<string>();
+  let sessionStats = createDistillSessionStats();
   let originalUserPrompt = "";
   const disposeToolDisplayMiddleware = registerDistillToolDisplayMiddleware();
   registerDistillFallbackRenderer(pi);
-  const extendParameters = () => {
+  const extendParameters = (ctx: ExtensionContext) => {
+    const reportWarning = (message: string) => {
+      if (reportedWarnings.has(message)) return;
+      reportedWarnings.add(message);
+      ctx.ui.notify(message, "warning");
+    };
     try {
-      extendDistillToolParameters(pi, loadDistillConfig());
+      extendDistillToolParameters(pi, loadDistillConfig(), reportWarning);
     } catch (error) {
-      console.warn(`[pi-distill] Failed to extend the outputRequest parameter: ${error instanceof Error ? error.message : String(error)}`);
+      reportWarning(i18n.t("extendOutputRequestFailed", {
+        error: error instanceof Error ? error.message : String(error),
+      }));
     }
   };
 
-  pi.on("session_start", extendParameters);
-  pi.on("before_agent_start", (event) => {
+  pi.on("session_start", (_event, ctx) => {
+    sessionStats = createDistillSessionStats();
+    extendParameters(ctx);
+  });
+  pi.on("before_agent_start", (event, ctx) => {
     originalUserPrompt = typeof event.prompt === "string" ? event.prompt : "";
-    extendParameters();
+    extendParameters(ctx);
     return {
       systemPrompt: [
         typeof event.systemPrompt === "string" ? event.systemPrompt : "",
@@ -1099,11 +1500,15 @@ export default function piDistillExtension(pi: ExtensionAPI) {
   pi.on("tool_result", async (event: ToolResultEvent, ctx) => {
     const pending = pendingCalls.get(event.toolCallId);
     pendingCalls.delete(event.toolCallId);
-    if (pending && !pending.enabled) return toToolResultEventResult({
-      content: event.content,
-      details: event.details as Record<string, unknown> | undefined,
-      isError: event.isError,
-    });
+    if (pending && !pending.enabled) {
+      const untouchedResult: ToolResult = {
+        content: event.content,
+        details: event.details as Record<string, unknown> | undefined,
+        isError: event.isError,
+      };
+      recordDistillSessionResult(sessionStats, untouchedResult.details);
+      return toToolResultEventResult(untouchedResult);
+    }
     const outputRequest = pending?.outputRequest ?? getOutputRequest(event.input);
     const result = await processToolResult(
       {
@@ -1120,6 +1525,7 @@ export default function piDistillExtension(pi: ExtensionAPI) {
       },
       pending ? Math.round(performance.now() - pending.startedAt) : 0,
     );
+    recordDistillSessionResult(sessionStats, result.details);
     if (!isDistillToolDisplayMiddlewareActive(event.toolName)) {
       appendDistillFallbackAudit(pi, event.toolName, result.details, loadDistillConfig().render);
     }
@@ -1127,5 +1533,6 @@ export default function piDistillExtension(pi: ExtensionAPI) {
   });
   pi.on("agent_end", () => pendingCalls.clear());
   pi.on("session_shutdown", () => disposeToolDisplayMiddleware());
+  registerDistillStatsCommand(pi, () => sessionStats);
   registerDistillConfigCommand(pi, extendParameters);
 }

package/src/output-limit.ts

@@ -59,7 +59,6 @@ export async function limitReturnedToolResult(
     };
   } 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) }],

package/src/summary-utils.ts

@@ -160,9 +160,6 @@ export function parseBashSummaryConfig(
     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_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;
   }
 
@@ -181,9 +178,6 @@ export function parseBashSummaryConfig(
 
   const separator = modelRef.indexOf("/");
   if (separator <= 0 || separator === modelRef.length - 1) {
-    console.warn(
-      `[pi-distill] Invalid PI_DISTILL_MODEL; expected provider/model, got: ${modelRef}`,
-    );
     return undefined;
   }