nolo-cli 0.1.39 → 0.1.41

package/ai/chat/serverProxyRetry.ts

@@ -0,0 +1,102 @@
+const RETRYABLE_SERVER_PROXY_STATUSES = new Set([502, 503, 504]);
+const DEFAULT_SERVER_PROXY_RETRY_AFTER_MS = 1_500;
+const MAX_SERVER_PROXY_RETRIES = 1;
+
+const normalizeServerProxyRetryAfterMs = (value: unknown) => {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed >= 0
+    ? Math.round(parsed)
+    : DEFAULT_SERVER_PROXY_RETRY_AFTER_MS;
+};
+
+const resolveServerProxyRetryAfterMs = (response: Response) => {
+  const retryAfterHeader = response.headers.get("Retry-After");
+  if (!retryAfterHeader) {
+    return DEFAULT_SERVER_PROXY_RETRY_AFTER_MS;
+  }
+  const seconds = Number(retryAfterHeader);
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    return Math.round(seconds * 1_000);
+  }
+  return DEFAULT_SERVER_PROXY_RETRY_AFTER_MS;
+};
+
+const isRetryableServerProxyFetchError = (error: unknown) => {
+  if (!error || (error as any)?.name === "AbortError") return false;
+  const message =
+    typeof (error as any)?.message === "string"
+      ? (error as any).message
+      : String(error);
+  return /ECONNREFUSED|ECONNRESET|EPIPE|socket hang up|network error|failed to fetch|fetch failed|connection closed|load failed|502|503|504/i.test(
+    message
+  );
+};
+
+const waitForServerProxyRetry = async (
+  retryAfterMs: number,
+  signal?: AbortSignal
+) => {
+  if (retryAfterMs <= 0) return;
+  if (signal?.aborted) {
+    const abortError = new Error("Aborted");
+    abortError.name = "AbortError";
+    throw abortError;
+  }
+  await new Promise<void>((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(timeoutId);
+      signal?.removeEventListener("abort", onAbort);
+      const abortError = new Error("Aborted");
+      abortError.name = "AbortError";
+      reject(abortError);
+    };
+    const timeoutId = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, normalizeServerProxyRetryAfterMs(retryAfterMs));
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+};
+
+export const performServerProxyFetchWithRetry = async ({
+  execute,
+  signal,
+  logPrefix = "[fetchWithServerProxy]",
+}: {
+  execute: () => Promise<Response>;
+  signal?: AbortSignal;
+  logPrefix?: string;
+}): Promise<Response> => {
+  for (let attempt = 0; attempt <= MAX_SERVER_PROXY_RETRIES; attempt += 1) {
+    try {
+      const response = await execute();
+      if (
+        attempt < MAX_SERVER_PROXY_RETRIES &&
+        RETRYABLE_SERVER_PROXY_STATUSES.has(response.status)
+      ) {
+        const retryAfterMs = resolveServerProxyRetryAfterMs(response);
+        console.warn(
+          `${logPrefix} 检测到${response.status}状态，${retryAfterMs}ms后重试一次...`
+        );
+        await waitForServerProxyRetry(retryAfterMs, signal);
+        continue;
+      }
+      return response;
+    } catch (error: any) {
+      if (
+        attempt < MAX_SERVER_PROXY_RETRIES &&
+        isRetryableServerProxyFetchError(error)
+      ) {
+        console.warn(
+          `${logPrefix} 检测到网络瞬断，${DEFAULT_SERVER_PROXY_RETRY_AFTER_MS}ms后重试一次...`,
+          error
+        );
+        await waitForServerProxyRetry(DEFAULT_SERVER_PROXY_RETRY_AFTER_MS, signal);
+        continue;
+      }
+      throw error;
+    }
+  }
+
+  throw new Error("server proxy retry exhausted unexpectedly");
+};

package/ai/chat/shouldUseServerProxy.ts

@@ -0,0 +1,18 @@
+import type { Agent } from "../../app/types";
+
+export const shouldUseServerProxy = (
+  agentConfig: Pick<Agent, "provider" | "useServerProxy">,
+  requestProvider?: string
+): boolean => {
+  const effectiveProvider = (requestProvider || agentConfig.provider || "").toLowerCase();
+
+  // Google requests are forced through the server proxy for now because the
+  // native Gemini image bridge, provider fallback, and request translation live
+  // on the server. Keep this centralized so we can later add direct/custom-url
+  // opt-out for user-managed keys without having to update web/native twice.
+  if (effectiveProvider === "google") {
+    return true;
+  }
+
+  return !!agentConfig.useServerProxy;
+};

package/ai/chat/streamRetry.ts

@@ -0,0 +1,46 @@
+export const MAX_INITIAL_STREAM_RETRIES = 1;
+export const DEFAULT_INITIAL_STREAM_RETRY_AFTER_MS = 1_500;
+
+const normalizeInitialStreamRetryAfterMs = (value: unknown) => {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed >= 0
+    ? Math.round(parsed)
+    : DEFAULT_INITIAL_STREAM_RETRY_AFTER_MS;
+};
+
+export const isRetryableInitialStreamError = (error: unknown) => {
+  if (!error || (error as any)?.name === "AbortError") return false;
+  const message =
+    typeof (error as any)?.message === "string"
+      ? (error as any).message
+      : String(error);
+  return /ECONNRESET|ECONNREFUSED|EPIPE|socket hang up|network error|failed to fetch|fetch failed|load failed|connection closed|stream ended before first visible delta|response stream ended before first visible delta|模型响应流 .* 秒内没有返回新内容/i.test(
+    message
+  );
+};
+
+export const waitForInitialStreamRetry = async (
+  retryAfterMs: number,
+  signal?: AbortSignal
+) => {
+  if (signal?.aborted) {
+    const abortError = new Error("Aborted");
+    abortError.name = "AbortError";
+    throw abortError;
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(timeoutId);
+      signal?.removeEventListener("abort", onAbort);
+      const abortError = new Error("Aborted");
+      abortError.name = "AbortError";
+      reject(abortError);
+    };
+    const timeoutId = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, normalizeInitialStreamRetryAfterMs(retryAfterMs));
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+};

package/ai/chat/updateTotalUsage.ts

@@ -0,0 +1,89 @@
+// 文件路径: ai/chat/updateTotalUsage.ts
+
+import { CompletionUsage } from "../../chat/messages/types";
+
+/**
+ * ✨ 新增辅助函数 ✨
+ * 根据新的数据块更新累积的 token 使用量。
+ * @param currentUsage - 当前的累积 usage 对象，可能为 null。
+ * @param newUsageChunk - 从流中收到的新 usage 数据块。
+ * @returns 更新后的 usage 对象。
+ */
+export function updateTotalUsage(
+  currentUsage: CompletionUsage | null,
+  newUsageChunk: Partial<CompletionUsage>
+): CompletionUsage | null {
+  if (!newUsageChunk) {
+    return currentUsage;
+  }
+
+  // 如果是第一次接收，直接克隆新数据块
+  if (!currentUsage) {
+    return {
+      completion_tokens: 0,
+      prompt_tokens: 0,
+      total_tokens: 0,
+      ...newUsageChunk,
+    } as CompletionUsage;
+  }
+
+  // 否则，在现有基础上进行累加或更新
+  const updatedUsage: CompletionUsage = { ...currentUsage };
+
+  // === token 相关 ===
+  // 这里假设 usage 是累积的还是单次的？
+  // 如果是 OpenAI 流式 output，usage 通常只在最后一次 chunk 发送完整的统计值 (除了 Azure 等可能变体)。
+  // 如果是这种情况，我们直接覆盖即可。
+  // 但如果服务端分片发送增量（比较少见但有可能），则需要累加。
+  // 原代码逻辑是：
+  // updatedUsage.completion_tokens = newUsageChunk.completion_tokens ?? updatedUsage.completion_tokens;
+  // 这意味着如果有新值就覆盖，没新值保持原样。这适合 "最后一次发送完整值" 的场景。
+
+  // 保持原逻辑：覆盖
+  if (newUsageChunk.completion_tokens !== undefined) updatedUsage.completion_tokens = newUsageChunk.completion_tokens;
+  if (newUsageChunk.prompt_tokens !== undefined) updatedUsage.prompt_tokens = newUsageChunk.prompt_tokens;
+  if (newUsageChunk.total_tokens !== undefined) updatedUsage.total_tokens = newUsageChunk.total_tokens;
+
+
+  if (newUsageChunk.prompt_tokens_details) {
+    updatedUsage.prompt_tokens_details = {
+      ...(updatedUsage.prompt_tokens_details || {}),
+      ...newUsageChunk.prompt_tokens_details,
+    };
+  }
+  if (newUsageChunk.completion_tokens_details) {
+    updatedUsage.completion_tokens_details = {
+      ...(updatedUsage.completion_tokens_details || {}),
+      ...newUsageChunk.completion_tokens_details,
+    };
+  }
+
+  // === OpenRouter usage.cost 相关 ===
+  if (typeof newUsageChunk.cost === "number") {
+    // 对于 OpenRouter，通常只有最后一条 chunk 带 cost，这里直接覆盖即可
+    updatedUsage.cost = newUsageChunk.cost;
+  }
+
+  if (newUsageChunk.cost_details) {
+    updatedUsage.cost_details = {
+      ...(updatedUsage.cost_details || {}),
+      ...newUsageChunk.cost_details,
+    };
+  }
+
+  if (
+    typeof newUsageChunk.billing_provider === "string" &&
+    newUsageChunk.billing_provider.trim()
+  ) {
+    updatedUsage.billing_provider = newUsageChunk.billing_provider.trim();
+  }
+
+  if (
+    typeof newUsageChunk.billing_model === "string" &&
+    newUsageChunk.billing_model.trim()
+  ) {
+    updatedUsage.billing_model = newUsageChunk.billing_model.trim();
+  }
+
+  return updatedUsage;
+}

package/ai/context/buildReferenceContext.ts

@@ -0,0 +1,437 @@
+// ai/context/fetchReferenceContents.ts
+
+import { read } from "../../database/dbSlice";
+import { AppDispatch } from "../../app/store";
+import { slateToText } from "../../create/editor/transforms/slateToText";
+import { slateToSimplifiedMarkdown } from "../../create/editor/transforms/slateToSimplifiedMarkdown";
+import { extractCategorizedMentions } from "../../create/editor/utils/slateUtils";
+import { DialogConfig } from "../../app/types";
+import { DataType } from "../../create/types";
+import { extractCustomId } from "../../core/prefix";
+import { getRuntimeServerContext } from "../../database/runtimeServerContext";
+import { fetchAndCacheMessages } from "../../chat/messages/fetchAndCacheMessages";
+import { createSpaceKey } from "../../create/space/spaceKeys";
+import { TableMeta } from "../../render/table/types";
+import { fetchAndSerializeTable } from "../../render/table/utils/tableSerialization";
+import { estimateTokenCount } from "../context/tokenUtils";
+
+interface FetchOptions {
+  format?: "json" | "text" | "simplified_markdown";
+  inlineMentionMeta?: boolean;
+  preloaded?: Map<string, any>;
+}
+
+type MentionMeta = {
+  displayType?: string;
+  title?: string;
+  metaParts: string[] | readonly string[];
+};
+
+const MAX_META_TEXT_LENGTH = 80;
+const DIALOG_REFERENCE_MESSAGE_LIMIT = 20;
+const DIALOG_REFERENCE_SNIPPET_CHARS = 1200;
+const DIALOG_HANDOFF_SNIPPET_CHARS = 360;
+
+const truncateMetaText = (value: string | undefined, max = MAX_META_TEXT_LENGTH) => {
+  if (!value) return "";
+  if (value.length <= max) return value;
+  return `${value.slice(0, max - 3)}...`;
+};
+
+const readSafe = async (dispatch: AppDispatch, dbKey: string) => {
+  try {
+    return await dispatch(read({
+      dbKey: dbKey
+    })).unwrap();
+  } catch {
+    return null;
+  }
+};
+
+const buildMentionMetaMap = async (
+  slateData: any,
+  dispatch: AppDispatch
+): Promise<Map<string, MentionMeta>> => {
+  const metaMap = new Map<string, MentionMeta>();
+  const mentions = extractCategorizedMentions(slateData);
+
+  if (!mentions) return metaMap;
+
+  const pageEntries = await Promise.all(
+    (mentions.pages || []).map(async (pageId: string) => {
+      const pageData = await readSafe(dispatch, pageId);
+      if (!pageData) {
+        return [`page:${pageId}`, { displayType: "page", metaParts: [] }] as const;
+      }
+      if (pageData.type === DataType.DIALOG) {
+        const cybotCount = Array.isArray(pageData.cybots)
+          ? pageData.cybots.length
+          : 0;
+        return [
+          `page:${pageId}`,
+          {
+            displayType: "dialog",
+            title: pageData.title,
+            metaParts: [
+              `cybots=${cybotCount}`,
+              `updated=${pageData.updatedAt || pageData.updated_at || pageData.updated || "Unknown"}`,
+            ],
+          },
+        ] as const;
+      }
+
+      const tags =
+        pageData.tags && pageData.tags.length > 0
+          ? pageData.tags.slice(0, 5).join(", ")
+          : "";
+      return [
+        `page:${pageId}`,
+        {
+          displayType: "page",
+          title: pageData.title,
+          metaParts: [
+            pageData.spaceId ? `space=${pageData.spaceId}` : "",
+            tags ? `tags=${tags}` : "",
+            `updated=${pageData.updatedAt || pageData.updated_at || pageData.updated || "Unknown"}`,
+          ].filter(Boolean),
+        },
+      ] as const;
+    })
+  );
+
+  pageEntries.forEach((entry: any) => metaMap.set(entry[0], entry[1]));
+
+  const agentEntries = await Promise.all(
+    (mentions.agents || []).map(async (agentId: string) => {
+      const agentData = await readSafe(dispatch, agentId);
+      if (!agentData) {
+        return [`agent:${agentId}`, { displayType: "agent", metaParts: [] }] as const;
+      }
+      const desc = truncateMetaText(
+        agentData.description || agentData.introduction || ""
+      );
+      return [
+        `agent:${agentId}`,
+        {
+          displayType: "agent",
+          title: agentData.name,
+          metaParts: [
+            `public=${agentData.isPublic ? "yes" : "no"}`,
+            desc ? `desc=${desc}` : "",
+          ].filter(Boolean),
+        },
+      ] as const;
+    })
+  );
+
+  agentEntries.forEach((entry: any) => metaMap.set(entry[0], entry[1]));
+
+  const spaceEntries = await Promise.all(
+    (mentions.spaces || []).map(async (spaceId: string) => {
+      const spaceKey = createSpaceKey.space(spaceId);
+      const spaceData = await readSafe(dispatch, spaceKey);
+      if (!spaceData) {
+        return [`space:${spaceId}`, { displayType: "space", metaParts: [] }] as const;
+      }
+      const desc = truncateMetaText(spaceData.description || "");
+      const categoriesCount = Object.keys(spaceData.categories || {}).length;
+      const contentsCount = Object.keys(spaceData.contents || {}).length;
+      return [
+        `space:${spaceId}`,
+        {
+          displayType: "space",
+          title: spaceData.name,
+          metaParts: [
+            desc ? `desc=${desc}` : "",
+            `categories=${categoriesCount}`,
+            `contents=${contentsCount}`,
+          ].filter(Boolean),
+        },
+      ] as const;
+    })
+  );
+
+  spaceEntries.forEach((entry: any) => metaMap.set(entry[0], entry[1]));
+
+  return metaMap;
+};
+
+const buildInlineMention = (
+  node: any,
+  metaMap: Map<string, MentionMeta>
+): string => {
+  const resourceType = node.resourceType || "unknown";
+  const resourceId = node.resourceId || "unknown";
+  const key = `${resourceType}:${resourceId}`;
+  const meta = metaMap.get(key);
+  const label = meta?.title || node.label || resourceId || "mention";
+  const displayType = meta?.displayType || resourceType;
+  const metaParts = (meta?.metaParts as string[]) ?? [];
+  const idPart =
+    resourceType === "tool" ? `tool=${resourceId}` : `dbkey=${resourceId}`;
+  const metaSuffix = metaParts.length ? ` | ${metaParts.join(" | ")}` : "";
+  return `@${label}(${displayType} | ${idPart}${metaSuffix})`;
+};
+
+const clipReferenceText = (value: unknown, max: number) => {
+  const raw =
+    typeof value === "string"
+      ? value
+      : value == null
+        ? ""
+        : JSON.stringify(value);
+  const trimmed = raw.trim();
+  if (trimmed.length <= max) return trimmed;
+  return `${trimmed.slice(0, max)}\n...[truncated ${trimmed.length - max} chars]`;
+};
+
+// --- Sub-handlers for specific types ---
+
+const fetchDialogReference = async (
+  dbKey: string,
+  refContent: any,
+  dispatch: AppDispatch
+): Promise<string> => {
+  const dialogConfig = refContent as DialogConfig;
+  const dialogTitle = dialogConfig.title || `Untitled Dialog (${dbKey})`;
+  const dialogId = extractCustomId(dbKey) || dbKey.replace(/^dialog-/, "");
+  const checkpoint = (dialogConfig as any).runtimeCheckpoint || null;
+  const summary = typeof (dialogConfig as any).summary === "string"
+    ? (dialogConfig as any).summary.trim()
+    : "";
+  const proactiveSummary = typeof (dialogConfig as any).proactiveSummary === "string"
+    ? (dialogConfig as any).proactiveSummary.trim()
+    : "";
+
+  const messages = await dispatch(
+    async (_dispatch: any, getState: any, { db }: any) => {
+      const state = getState();
+      const { currentToken: token, remoteServers } =
+        getRuntimeServerContext(state);
+
+      return await fetchAndCacheMessages({
+        db,
+        dialogId,
+        limit: DIALOG_REFERENCE_MESSAGE_LIMIT,
+        token,
+        remoteServers: remoteServers.length > 0 ? remoteServers : undefined,
+      });
+    }
+  );
+
+  const sortedMessages = [...messages].reverse();
+  const formatContent = (content: unknown) =>
+    clipReferenceText(content, DIALOG_REFERENCE_SNIPPET_CHARS);
+  const transcript = sortedMessages
+    .map((msg: any, index) => {
+      const toolLine = msg.toolName ? ` tool=${msg.toolName}` : "";
+      const agentLine = msg.cybotKey ? ` agent=${msg.cybotKey}` : "";
+      const createdLine = msg.createdAt ? ` at=${msg.createdAt}` : "";
+      return [
+        `### Message ${index + 1}: ${msg.role || "unknown"} id=${msg.id || "unknown"}${toolLine}${agentLine}${createdLine}`,
+        formatContent(msg.content) || "[empty]",
+      ].join("\n");
+    })
+    .join("\n\n");
+
+  const checkpointLines: string[] = [];
+  if (checkpoint && typeof checkpoint === "object") {
+    if (checkpoint.status) checkpointLines.push(`- status: ${checkpoint.status}`);
+    if (checkpoint.lastUserInput) checkpointLines.push(`- lastUserInput: ${formatContent(checkpoint.lastUserInput)}`);
+    if (checkpoint.lastAssistantText) checkpointLines.push(`- lastAssistantText: ${formatContent(checkpoint.lastAssistantText)}`);
+    if (Array.isArray(checkpoint.lastToolNames) && checkpoint.lastToolNames.length) {
+      checkpointLines.push(`- lastToolNames: ${checkpoint.lastToolNames.join(", ")}`);
+    }
+    if (Array.isArray(checkpoint.availableToolNames) && checkpoint.availableToolNames.length) {
+      checkpointLines.push(`- availableToolNames: ${checkpoint.availableToolNames.join(", ")}`);
+    }
+  }
+
+  const recentToolEvidence = sortedMessages
+    .filter((msg: any) => msg.role === "tool" || msg.toolName)
+    .slice(-3)
+    .map((msg: any) => {
+      const label = msg.toolName ? `${msg.toolName}` : "tool";
+      return `- ${label} id=${msg.id || "unknown"}: ${clipReferenceText(msg.content, DIALOG_HANDOFF_SNIPPET_CHARS) || "[empty]"}`;
+    });
+
+  const handoffLines = [
+    `- Use this when continuing work, transferring to another Agent, comparing with the current task, or preparing a document/plan from the prior discussion.`,
+    `- Current state source: ${checkpointLines.length ? "Runtime Checkpoint" : "summaries and recent transcript"}.`,
+    summary ? `- Compressed background: passive summary is available below; treat it as lossy, not original wording.` : "",
+    proactiveSummary ? `- Recent work: proactive summary is available below; use it for current direction, not exact evidence.` : "",
+    recentToolEvidence.length
+      ? `- Recent tool evidence:\n${recentToolEvidence.join("\n")}`
+      : `- Recent tool evidence: none loaded in the latest ${DIALOG_REFERENCE_MESSAGE_LIMIT} messages.`,
+    `- For exact claims, old decisions, original wording, files/tools mentioned earlier, or anything not visible in the recent transcript, call searchDialogMessages with DB Key ${dbKey}.`,
+  ].filter(Boolean);
+
+  const referenceBody = [
+    `Conversation Reference:`,
+    `DB Key: ${dbKey}`,
+    `Title: ${dialogTitle}`,
+    `Status: ${(dialogConfig as any).status || "unknown"}`,
+    `Loaded Recent Messages: ${sortedMessages.length}`,
+    `Conversation Handoff:\n${handoffLines.join("\n")}`,
+    checkpointLines.length ? `Runtime Checkpoint:\n${checkpointLines.join("\n")}` : "",
+    summary ? `Passive Summary (compressed history, not original wording):\n${summary}` : "",
+    proactiveSummary ? `Proactive Summary (recent work summary, not original wording):\n${proactiveSummary}` : "",
+    `Recent Transcript (original message excerpts, oldest to newest):\n${transcript || "[no recent messages loaded]"}`,
+    [
+      `Coverage Note: This reference intentionally loads only the latest ${DIALOG_REFERENCE_MESSAGE_LIMIT} messages plus summaries/checkpoint to control token load.`,
+      `Original Message Lookup Policy: If the user asks for an exact old message, original wording, who said what, why a decision was made, early-history detail, file/tool evidence, failed attempts, or a comparison with prior work, use searchDialogMessages({ dialogKey: "${dbKey}", query: "..." }) before making a factual claim from this referenced conversation.`,
+    ].join("\n"),
+  ].filter(Boolean).join("\n\n");
+
+  const tokenEstimate = estimateTokenCount(referenceBody);
+
+  return (
+    `${referenceBody}\n\n` +
+    `Token Load Estimate: ${tokenEstimate} tokens for this conversation reference.\n` +
+    `---\n\n`
+  );
+};
+
+const fetchTableReference = async (
+  dbKey: string,
+  refContent: any,
+  dispatch: AppDispatch
+): Promise<string> => {
+  const tableMeta = refContent as TableMeta;
+  const title = tableMeta.displayName || tableMeta.description || `Untitled Table (${dbKey})`;
+
+  const { markdown: tableMd } = await dispatch(
+    async (_dispatch: any, getState: any, { db }: any) => {
+      const state = getState();
+      const { currentToken: token, remoteServers } =
+        getRuntimeServerContext(state);
+
+      return await fetchAndSerializeTable(tableMeta, db, {
+        token,
+        remoteServers,
+      });
+    }
+  );
+
+  const tags = tableMeta.tags?.length ? tableMeta.tags.join(", ") : "None";
+  const description = tableMeta.description || "No description provided.";
+
+  return (
+    `Reference Item (Table):\n` +
+    `DB Key: ${dbKey}\n` +
+    `Title: ${title}\n` +
+    `Description: ${description}\n` +
+    `Tags: ${tags}\n` +
+    `Content (Markdown Table):\n\n${tableMd}\n` +
+    `---\n\n`
+  );
+};
+
+const fetchSlateReference = async (
+  dbKey: string,
+  refContent: any,
+  dispatch: AppDispatch,
+  options: FetchOptions
+): Promise<string | null> => {
+  if (!refContent?.slateData) return null;
+
+  const title = refContent.title || `Untitled (${dbKey})`;
+  let contentString: string;
+  let contentType: string;
+  const inlineMentionMeta =
+    options.inlineMentionMeta ?? options.format === "simplified_markdown";
+
+  switch (options.format) {
+    case "text":
+      contentType = "Plain Text";
+      contentString = slateToText(refContent.slateData);
+      break;
+    case "simplified_markdown":
+      contentType = "Simplified Markdown";
+      if (inlineMentionMeta) {
+        const metaMap = await buildMentionMetaMap(refContent.slateData, dispatch);
+        contentString = slateToSimplifiedMarkdown(refContent.slateData, {
+          mentionResolver: (node) => buildInlineMention(node, metaMap),
+        });
+      } else {
+        contentString = slateToSimplifiedMarkdown(refContent.slateData);
+      }
+      break;
+    case "json":
+    default:
+      contentType = "Slate JSON";
+      contentString = JSON.stringify(refContent.slateData, null, 2);
+      break;
+  }
+
+  if (
+    !contentString ||
+    (typeof contentString === "string" && !contentString.trim()) ||
+    contentString === "[]"
+  ) {
+    return null;
+  }
+
+  const tags = (refContent.tags || []).length > 0 ? refContent.tags.join(", ") : "None";
+  const createdAt = refContent.created || "Unknown Creation Date";
+  const updatedAt = refContent.updated || "Unknown Update Date";
+
+  return (
+    `Reference Item:\n` +
+    `DB Key: ${dbKey}\n` +
+    `Title: ${title}\n` +
+    `Content (${contentType}):\n${contentString}\n` +
+    `Tags: ${tags}\n` +
+    `Created At: ${createdAt}\n` +
+    `Updated At: ${updatedAt}\n` +
+    `---\n\n`
+  );
+};
+
+/**
+ * 智能地获取并格式化参考内容。
+ */
+export const fetchReferenceContents = async (
+  references: string[],
+  dispatch: AppDispatch,
+  options: FetchOptions = { format: "simplified_markdown" }
+): Promise<Map<string, string>> => {
+  const result = new Map<string, string>();
+  if (!references || references.length === 0) return result;
+
+  const referencePromises = references.map(async (dbKey) => {
+    try {
+      const hasPreloaded = options.preloaded?.has(dbKey);
+      const refContent = hasPreloaded
+        ? options.preloaded?.get(dbKey)
+        : await dispatch(read({
+        dbKey: dbKey
+      })).unwrap();
+
+      if (!refContent) return null;
+
+      let formatted: string | null = null;
+
+      if (refContent.type === DataType.DIALOG) {
+        formatted = await fetchDialogReference(dbKey, refContent, dispatch);
+      } else if (refContent.type === DataType.TABLE) {
+        formatted = await fetchTableReference(dbKey, refContent, dispatch);
+      } else {
+        formatted = await fetchSlateReference(dbKey, refContent, dispatch, options);
+      }
+
+      if (formatted) return [dbKey, formatted] as [string, string];
+      return null;
+    } catch (error: any) {
+      console.error(`Error fetching reference ${dbKey}:`, error);
+      return null;
+    }
+  });
+
+  const resolved = await Promise.all(referencePromises);
+  resolved.forEach((item) => {
+    if (item) result.set(item[0], item[1]);
+  });
+
+  return result;
+};