chatccc 0.2.228 → 0.2.230

package/src/session.ts

@@ -43,6 +43,12 @@ import { resourceMonitor, registerProcess, unregisterProcess } from "./adapters/
 import { buildImSkillsPromptCached, exportSkillSubDocs, clearImSkillsPromptCache } from "./im-skills.ts";
 import type { PlatformAdapter } from "./platform-adapter.ts";
 import { hasResponseStalled, observeResponseProgress } from "./response-stall.ts";
+import {
+  classifyTerminalError,
+  formatTerminalErrorNotice,
+  formatTerminalErrorReason,
+  type TerminalErrorInfo,
+} from "./terminal-error.ts";
 import {
   MAX_PROCESSED,
   clearFeishuMessageLedgerMemory,
@@ -305,13 +311,18 @@ function scheduleFinalResponseCloseGuard(
   runningPrompt.finalResponseCloseTimer = handle;
 }
 
-function formatTerminalHeader(status: "running" | "done" | "stopped" | "error" | "auto_ended"): {
+function formatTerminalHeader(
+  status: "running" | "done" | "stopped" | "error" | "auto_ended",
+  terminalError?: TerminalErrorInfo,
+): {
   title: string;
   template?: string;
 } {
   if (status === "auto_ended") return { title: "已自动结束 · 3分钟无新内容", template: "orange" };
   if (status === "stopped") return { title: "已停止", template: "red" };
-  if (status === "error") return { title: "异常结束", template: "red" };
+  if (status === "error") {
+    return { title: terminalError ? `异常结束 · ${terminalError.title}` : "异常结束", template: "red" };
+  }
   return { title: "完成" };
 }
 
@@ -337,11 +348,42 @@ function monitorsOutputProgress(kind: AgentActivityKind): boolean {
 function formatTerminalReply(
   status: "running" | "done" | "stopped" | "error" | "auto_ended",
   finalReply: string,
+  terminalError?: TerminalErrorInfo,
 ): string | null {
   if (status === "auto_ended") return formatAutoEndedReply(finalReply);
+  if (status === "error") {
+    const error = terminalError ?? {
+      kind: "unknown" as const,
+      title: "原因未记录",
+      message: "当前状态中没有可用的错误详情，请查看运行日志。",
+      occurredAt: Date.now(),
+    };
+    return formatTerminalErrorNotice(error, finalReply);
+  }
   return finalReply || null;
 }
 
+function formatTerminalCardContent(state: {
+  status: "running" | "done" | "stopped" | "error" | "auto_ended";
+  accumulatedContent: string;
+  finalReply: string;
+  terminalError?: TerminalErrorInfo;
+}): string {
+  const content = state.accumulatedContent + state.finalReply;
+  if (state.status !== "error") return content;
+
+  const error = state.terminalError ?? {
+    kind: "unknown" as const,
+    title: "原因未记录",
+    message: "当前状态中没有可用的错误详情，请查看运行日志。",
+    occurredAt: Date.now(),
+  };
+  const reason = formatTerminalErrorReason(error);
+  return content.trim()
+    ? `${content}\n\n${reason}\n以上内容可能不完整。`
+    : reason;
+}
+
 function isCardKitSequenceConflict(err: unknown): boolean {
   return err instanceof Error && err.message.includes("300317");
 }
@@ -1110,7 +1152,7 @@ export async function resumeAndPrompt(
   msgTimestamp: number,
   tool: string,
   traceId?: string,
-): Promise<void> {
+): Promise<SessionRunOutcome> {
   return runAgentSession(sessionId, userText, platform, chatId, msgTimestamp, tool, traceId);
 }
 
@@ -1126,6 +1168,8 @@ interface RunAgentSessionOptions {
   autoRecovery?: boolean;
 }
 
+export type SessionRunOutcome = "busy" | "done" | "stopped" | "error" | "auto_ended";
+
 export async function runAgentSession(
   sessionId: string,
   userText: string,
@@ -1135,7 +1179,7 @@ export async function runAgentSession(
   tool: string,
   traceId?: string,
   options: RunAgentSessionOptions = {},
-): Promise<void> {
+): Promise<SessionRunOutcome> {
   const tid = traceId ?? "";
 
   // runAgentSession 是飞书用户消息、队列消息与内部自动恢复共同使用的唯一
@@ -1162,7 +1206,7 @@ export async function runAgentSession(
       ? "当前正在生成回复中，请等待完成后再发送消息。也可以发送 /stop 结束，已完成的步骤不会丢失。"
       : "该会话正在生成回复中，请等待完成后再发送消息。也可以发送 /stop 结束，已完成的步骤不会丢失。";
     await platform.sendText(_chatId, busyMsg).catch(() => {});
-    return;
+    return "busy";
   }
 
   // 立即标记活跃，确保 /sessions、isSessionRunning 等查询在异步准备阶段就能看到运行状态。
@@ -1290,7 +1334,7 @@ export async function runAgentSession(
   // 再开始缓存问题对应的任务"。
   const prevState = await readStreamState(sessionId);
   if (prevState && prevState.status !== "running") {
-    const prevTerminalReply = formatTerminalReply(prevState.status, prevState.finalReply);
+    const prevTerminalReply = formatTerminalReply(prevState.status, prevState.finalReply, prevState.terminalError);
     const displayChatId = pickDisplayChat(sessionId);
     if (displayChatId) {
       const pp = platformForChat(displayChatId);
@@ -1309,8 +1353,8 @@ export async function runAgentSession(
           setSessionChatAvatar(pp, displayChatId, prevState.tool, "idle", sessionId).catch(() => {});
         } else {
           const nextSeq = display.sequence + 1;
-          const { title: headerTitle, template: headerTemplate } = formatTerminalHeader(prevState.status);
-          const cardContent = truncateContent(prevState.accumulatedContent + prevState.finalReply) || " ";
+          const { title: headerTitle, template: headerTemplate } = formatTerminalHeader(prevState.status, prevState.terminalError);
+          const cardContent = truncateContent(formatTerminalCardContent(prevState)) || " ";
           const doneCard = buildProgressCard(progressView({ text: cardContent, status: "done", showStop: false, headerTitle, headerTemplate }));
           await pp.cardUpdate(display.cardId, doneCard, nextSeq).catch(err => {
             console.error(`[${ts()}] [DISPLAY] prevState final cardUpdate failed: ${(err as Error).message}`);
@@ -1405,6 +1449,8 @@ export async function runAgentSession(
   const FILE_WRITE_INTERVAL_MS = 2000;
   const toolCallMap = new Map<string, { name: string; input: unknown }>();
   let streamErrored = false;
+  let streamTerminalError: TerminalErrorInfo | undefined;
+  let runOutcome: SessionRunOutcome = "error";
 
   const runningPrompt = activePrompts.get(sessionId);
   if (runningPrompt) {
@@ -1580,6 +1626,7 @@ export async function runAgentSession(
     }
   } catch (streamErr) {
     streamErrored = true;
+    streamTerminalError = classifyTerminalError(streamErr);
     console.error(`[${ts()}] [STREAM] Error in stream loop for ${sessionId}: ${(streamErr as Error).message}`);
   } finally {
     // 标记 prompt 结束
@@ -1629,6 +1676,23 @@ export async function runAgentSession(
               ? "stopped"
               : "done";
       const finalReply = pickFinalReply(state).trim();
+      const terminalError = streamTerminalError
+        ?? (wasAbnormalExit
+          ? {
+              kind: "process" as const,
+              title: "Agent 进程意外退出",
+              message: "Agent CLI 进程已退出。若回复不完整，请重新发送上一条指令。",
+              occurredAt: Date.now(),
+            }
+          : wasResourceStuck
+            ? {
+                kind: "resource" as const,
+                title: "Agent 进程失去响应",
+                message: "Agent 进程长时间没有 CPU 或内存变化，已被强制停止。若回复不完整，请重新发送上一条指令。",
+                occurredAt: Date.now(),
+              }
+            : undefined);
+      runOutcome = finalStatus;
 
     // stop-stuck-loop 接口可能在 fire-and-forget 中已写入带 final_reply 的
     // stream state，finally 不应覆盖它。同时保留 stuckAt 标记，防止
@@ -1659,6 +1723,7 @@ export async function runAgentSession(
       tool,
       ...(preserveStuckAt ? { stuckAt: preserveStuckAt } : {}),
       ...(autoEndedAt !== undefined ? { autoEndedAt } : {}),
+      ...(terminalError ? { terminalError } : {}),
     });
 
     // display loop 下一轮会读到最终状态并发送消息
@@ -1749,6 +1814,52 @@ export async function runAgentSession(
       if (activeErr) setSessionChatAvatar(platform, activeErr, tool, "idle", sessionId).catch(() => {});
       console.log(`[${ts()}] Session ${sessionId} process exited unexpectedly (content chunks: ${state.chunkCount})`);
       if (tid) logTrace(tid, "SESSION_END", { sessionId, outcome: "process_missing", chunks: state.chunkCount });
+    } else if (streamErrored || wasResourceStuck) {
+      for (const cid of finalizationChatIds) {
+        const finfo = sessionInfoMap.get(cid);
+        await recordSessionRegistry({
+          chatId: cid,
+          sessionId,
+          tool,
+          turnCount: finfo?.turnCount ?? nextTurnCount,
+          lastContextTokens: finfo?.lastContextTokens ?? nextContextTokens,
+          startTime: finfo?.startTime ?? now,
+          running: false,
+        });
+      }
+      const activeErr = getLastActiveChat(sessionId) ?? finalizationChatIds[0];
+      if (activeErr) {
+        const pp = platformForChat(activeErr) ?? platform;
+        const terminalState = await readStreamState(sessionId);
+        if (
+          terminalError
+          && !displayCards.has(activeErr)
+          && (!terminalState || !isFinalReplySentForTurn(terminalState))
+        ) {
+          await sendFinalReplyTextOnce(
+            pp,
+            activeErr,
+            sessionId,
+            nextTurnCount,
+            formatTerminalErrorNotice(terminalError, finalReplyToWrite),
+          );
+        }
+        setSessionChatAvatar(pp, activeErr, tool, "idle", sessionId).catch(() => {});
+      }
+      const errorOutcome = wasResourceStuck ? "resource_stuck" : "stream_error";
+      console.error(
+        `[${ts()}] Session ${sessionId} ended with ${errorOutcome}` +
+        `${terminalError ? ` (${terminalError.kind}: ${terminalError.title})` : ""} (content chunks: ${state.chunkCount})`,
+      );
+      if (tid) {
+        logTrace(tid, "SESSION_END", {
+          sessionId,
+          outcome: errorOutcome,
+          errorKind: terminalError?.kind,
+          errorTitle: terminalError?.title,
+          chunks: state.chunkCount,
+        });
+      }
     } else {
       for (const cid of finalizationChatIds) {
         const finfo = sessionInfoMap.get(cid);
@@ -1862,6 +1973,7 @@ export async function runAgentSession(
       clearSessionFinalizing(sessionId);
     }
   }
+  return runOutcome;
 }
 
 // ---------------------------------------------------------------------------
@@ -1941,9 +2053,11 @@ export function startUnifiedDisplayLoop(): void {
               const tail = "━━━ 回答结束 ━━━";
               const finalMsg = state.status === "auto_ended"
                 ? formatAutoEndedReply(remaining)
-                : remaining
-                  ? remaining + "\n" + tail
-                  : tail;
+                : state.status === "error"
+                  ? formatTerminalReply(state.status, remaining, state.terminalError) ?? tail
+                  : remaining
+                    ? remaining + "\n" + tail
+                    : tail;
               if (!isFinalReplySentForTurn(state)) {
                 await sendFinalReplyTextOnce(p, chatId, sessionId, state.turnCount, finalMsg);
               }
@@ -1965,8 +2079,8 @@ export function startUnifiedDisplayLoop(): void {
               let terminalCardUpdateAccepted = terminalCardAlreadyUpdated;
               if (!terminalCardAlreadyUpdated) {
                 const nextSeq = display.sequence + 1;
-                const { title: headerTitle, template: headerTemplate } = formatTerminalHeader(state.status);
-                const cardContent = truncateContent(state.accumulatedContent + state.finalReply) || " ";
+                const { title: headerTitle, template: headerTemplate } = formatTerminalHeader(state.status, state.terminalError);
+                const cardContent = truncateContent(formatTerminalCardContent(state)) || " ";
                 const doneCard = buildProgressCard(progressView({ text: cardContent, status: "done", showStop: false, headerTitle, headerTemplate }));
                 await p.cardUpdate(display.cardId, doneCard, nextSeq).then(() => {
                   display.sequence = nextSeq;
@@ -1993,8 +2107,16 @@ export function startUnifiedDisplayLoop(): void {
               }
 
               let terminalTextDelivered = true;
-              const terminalReply = formatTerminalReply(state.status, state.finalReply);
-              if (terminalReply) {
+              const terminalReply = formatTerminalReply(state.status, state.finalReply, state.terminalError);
+              const errorWasDeliveredByCard =
+                state.status === "error"
+                && !state.finalReply.trim()
+                && terminalCardUpdateAccepted;
+              if (errorWasDeliveredByCard) {
+                if (!isFinalReplySentForTurn(state)) {
+                  await markFinalReplySent(sessionId, state.turnCount);
+                }
+              } else if (terminalReply) {
                 if (!isFinalReplySentForTurn(state)) {
                   terminalTextDelivered = await sendFinalReplyTextOnce(p, chatId, sessionId, state.turnCount, terminalReply);
                 }

package/src/stream-state.ts

@@ -1,9 +1,10 @@
 import { readFile, writeFile, mkdir, rename, unlink } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
-import { USER_DATA_DIR, ts } from "./config.ts";
-import { createAgentActivityTracker } from "./agent-activity.ts";
-import type { AgentActivity } from "./agent-activity.ts";
+import { USER_DATA_DIR, ts } from "./config.ts";
+import { createAgentActivityTracker } from "./agent-activity.ts";
+import type { AgentActivity } from "./agent-activity.ts";
+import type { TerminalErrorInfo } from "./terminal-error.ts";
 
 // ---------------------------------------------------------------------------
 // stream-state.json — 每个 session 的流式输出持久化文件
@@ -13,14 +14,14 @@ export const STREAMS_DIR = join(USER_DATA_DIR, "state", "streams");
 
 export interface StreamState {
   sessionId: string;
-  status: "running" | "done" | "stopped" | "error" | "auto_ended";
+  status: "running" | "done" | "stopped" | "error" | "auto_ended";
   accumulatedContent: string;
   /** 本轮会话中 LLM 输出的全部文本内容（所有 text block 的累加）。
    *  命名含 "final" 但实为"全部累积文本"，并非仅"最终一段回复"。
    *  参见 session.ts 的 AccumulatorState 注释。 */
-  finalReply: string;
-  /** Current user-visible work phase for running progress cards. */
-  activity?: AgentActivity;
+  finalReply: string;
+  /** Current user-visible work phase for running progress cards. */
+  activity?: AgentActivity;
   /** The turn whose terminal text reply has already been delivered to IM. */
   finalReplySentTurn?: number;
   finalReplySentAt?: number;
@@ -32,10 +33,12 @@ export interface StreamState {
   tool: string;
   /** Set by stop-stuck-loop to prevent the session from being resumed.
    *  The orchestrator checks this before resuming and creates a new session instead. */
-  stuckAt?: number;
-  /** Set when the shared response watchdog ends a turn after three minutes without new characters. */
-  autoEndedAt?: number;
-}
+  stuckAt?: number;
+  /** Set when the shared response watchdog ends a turn after three minutes without new characters. */
+  autoEndedAt?: number;
+  /** 脱敏后的用户可见根因；完整原始异常只保留在运行日志中。 */
+  terminalError?: TerminalErrorInfo;
+}
 
 function getStreamStatePath(sessionId: string): string {
   return join(STREAMS_DIR, `${sessionId}.json`);
@@ -128,18 +131,18 @@ export async function markFinalReplySent(sessionId: string, turnCount: number, s
   await writeStreamState(state);
 }
 
-export function createEmptyStreamState(sessionId: string, cwd: string, tool: string, turnCount: number): StreamState {
-  const now = Date.now();
-  return {
+export function createEmptyStreamState(sessionId: string, cwd: string, tool: string, turnCount: number): StreamState {
+  const now = Date.now();
+  return {
     sessionId,
     status: "running",
-    accumulatedContent: "",
-    finalReply: "",
-    activity: createAgentActivityTracker(now).activity,
+    accumulatedContent: "",
+    finalReply: "",
+    activity: createAgentActivityTracker(now).activity,
     chunkCount: 0,
     turnCount,
     contextTokens: 0,
-    updatedAt: now,
+    updatedAt: now,
     cwd,
     tool,
   };

package/src/terminal-error.ts

@@ -0,0 +1,129 @@
+/** 用户可见的终态错误。这里只保存脱敏摘要；完整原始异常继续只写运行日志。 */
+export type TerminalErrorKind =
+  | "network_timeout"
+  | "network"
+  | "authentication"
+  | "rate_limit"
+  | "provider"
+  | "process"
+  | "resource"
+  | "unknown";
+
+export interface TerminalErrorInfo {
+  kind: TerminalErrorKind;
+  title: string;
+  message: string;
+  occurredAt: number;
+}
+
+const MAX_UNKNOWN_ERROR_LENGTH = 300;
+
+function errorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  if (typeof error === "string") return error;
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return String(error);
+  }
+}
+
+/**
+ * 未分类错误仍应给出可诊断线索，但不能把常见凭据带进群聊或持久化状态。
+ * 已分类错误使用固定文案，不复述地址、请求体或 provider 原始响应。
+ */
+export function sanitizeTerminalErrorDetail(raw: string): string {
+  return raw
+    .replace(/\bBearer\s+[^\s,;]+/gi, "Bearer [已脱敏]")
+    .replace(/\b(api[_-]?key|access[_-]?token|token|secret)\s*[:=]\s*[^\s,;]+/gi, "$1=[已脱敏]")
+    .replace(/\bsk-[A-Za-z0-9._-]{6,}\b/g, "sk-[已脱敏]")
+    .replace(/([?&](?:api[_-]?key|access[_-]?token|token|secret)=)[^&\s]+/gi, "$1[已脱敏]")
+    .slice(0, MAX_UNKNOWN_ERROR_LENGTH);
+}
+
+function parsePositiveInt(message: string, pattern: RegExp): number | undefined {
+  const value = Number.parseInt(message.match(pattern)?.[1] ?? "", 10);
+  return Number.isFinite(value) && value > 0 ? value : undefined;
+}
+
+function formatSeconds(milliseconds: number): string {
+  if (milliseconds % 1000 === 0) return `${milliseconds / 1000} 秒`;
+  return `${milliseconds} 毫秒`;
+}
+
+export function classifyTerminalError(error: unknown, occurredAt = Date.now()): TerminalErrorInfo {
+  const raw = errorMessage(error);
+  const lower = raw.toLowerCase();
+  const attempts = parsePositiveInt(raw, /\bafter\s+(\d+)\s+attempts?\b/i);
+  const timeoutMs = parsePositiveInt(raw, /\btimeout\s*:\s*(\d+)\s*ms\b/i);
+
+  if (/\b429\b|rate[ _-]?limit|too many requests/.test(lower)) {
+    return {
+      kind: "rate_limit",
+      title: "请求受到限流",
+      message: "模型服务请求受到限流，请稍后重试。",
+      occurredAt,
+    };
+  }
+
+  if (/\b401\b|\b403\b|unauthori[sz]ed|forbidden|invalid api key|authentication/.test(lower)) {
+    return {
+      kind: "authentication",
+      title: "模型服务鉴权失败",
+      message: "模型服务拒绝了当前凭据，请检查 API Key、账号权限或凭据是否过期。",
+      occurredAt,
+    };
+  }
+
+  if (
+    /connect timeout|connection timed out|etimedout|und_err_connect_timeout/.test(lower)
+    || (lower.includes("cannot connect") && lower.includes("timeout"))
+  ) {
+    const retryText = attempts ? `，已重试 ${attempts} 次` : "";
+    const timeoutText = timeoutMs ? `，单次连接等待 ${formatSeconds(timeoutMs)}` : "";
+    return {
+      kind: "network_timeout",
+      title: "网络连接超时",
+      message: `连接模型服务失败${retryText}${timeoutText}。请检查网络、VPN或模型服务状态后重试。`,
+      occurredAt,
+    };
+  }
+
+  if (/econnrefused|econnreset|enotfound|eai_again|socket hang up|network error|cannot connect/.test(lower)) {
+    return {
+      kind: "network",
+      title: "无法连接模型服务",
+      message: "与模型服务的网络连接失败，请检查网络、VPN、DNS或服务状态后重试。",
+      occurredAt,
+    };
+  }
+
+  const httpStatus = raw.match(/\b(?:HTTP\s*)?(5\d\d)\b/i)?.[1];
+  if (httpStatus || /service unavailable|bad gateway|gateway timeout|provider error/.test(lower)) {
+    return {
+      kind: "provider",
+      title: "模型服务暂时不可用",
+      message: `模型服务返回异常${httpStatus ? `（HTTP ${httpStatus}）` : ""}，请稍后重试。`,
+      occurredAt,
+    };
+  }
+
+  const safeDetail = sanitizeTerminalErrorDetail(raw).trim() || "未提供错误详情";
+  return {
+    kind: "unknown",
+    title: "Agent 执行错误",
+    message: `发生未分类错误：${safeDetail}`,
+    occurredAt,
+  };
+}
+
+export function formatTerminalErrorReason(error: TerminalErrorInfo): string {
+  return `⚠️ 异常结束：${error.title}\n${error.message}`;
+}
+
+export function formatTerminalErrorNotice(error: TerminalErrorInfo, finalReply = ""): string {
+  const reason = formatTerminalErrorReason(error);
+  return finalReply.trim()
+    ? `${reason}\n\n以下回复可能不完整：\n\n${finalReply.trim()}`
+    : reason;
+}