polish

Author: linyuan.yang

packages/scorpio.ai/src/Saver/ConversationCompactor.ts

@@ -72,7 +72,7 @@ export class ConversationCompactor {
         const summary = !result ? '' :
             typeof result.content === 'string'
                 ? result.content
-                : result.content.map(p => p.text ?? '').join('');
+                : result.content.map(p => (p.type === 'text' ? (p.text ?? '') : '')).join('');
 
         this.logger?.info(`Compact complete, summary length: ${summary.length}`);
 

packages/scorpio.ai/src/Saver/IAgentSaverService.ts

@@ -22,6 +22,66 @@ export interface ChatToolCall {
     type?: string;
 }
 
+// ─── Content parts (discriminated union by `type`) ───────────────────────────
+
+/**
+ * 多模态消息内容 part 的判别符
+ *
+ * 该集合由本仓库内部 + 直连 LLM/Channel 时实际出现的取值聚合而来。
+ * 透传给 SDK 时还可能出现 provider 专属取值，由 `ContentPart` 末尾的兜底分支兼容。
+ */
+export const ContentPartType = {
+    Text:     'text',
+    /** Anthropic / ACP 风格：data + mimeType */
+    Image:    'image',
+    /** OpenAI 兼容风格：image_url.url */
+    ImageUrl: 'image_url',
+    Audio:    'audio',
+} as const;
+export type ContentPartType = typeof ContentPartType[keyof typeof ContentPartType];
+
+/** 文本 part，可选携带 Anthropic 的 cache 标记 */
+interface TextPart {
+    type: 'text';
+    text: string;
+    cache_control?: any;
+}
+
+/** Anthropic / ACP 风格的图像 part（base64 + mimeType） */
+interface ImagePart {
+    type: 'image';
+    data: string;
+    mimeType?: string;
+}
+
+/** OpenAI 兼容风格的图像 part（dataUrl 或外链） */
+interface ImageUrlPart {
+    type: 'image_url';
+    image_url: { url: string };
+    mimeType?: string;
+}
+
+/** 音频 part（base64 + mimeType） */
+interface AudioPart {
+    type: 'audio';
+    data: string;
+    mimeType?: string;
+}
+
+/**
+ * 多模态消息 part 的判别联合类型。
+ *
+ * - 已知形状：`TextPart` / `ImagePart` / `ImageUrlPart` / `AudioPart`
+ * - 末尾的开放分支用于透传 provider 专属 part（如 `tool_use` / `tool_result` / `thinking` 等），
+ *   避免类型阻塞迭代；仍保留 `type: string` 以维持运行时一致性。
+ */
+export type ContentPart =
+    | TextPart
+    | ImagePart
+    | ImageUrlPart
+    | AudioPart
+    | { type: string; [key: string]: any };
+
 /**
  * 中性化的消息结构，不依赖任何 LLM 框架
  *
@@ -32,7 +92,7 @@ export interface ChatToolCall {
  */
 export interface ChatMessage {
     role: MessageRole;
-    content: string | Array<{ type: string; text?: string; [key: string]: any }>;
+    content: string | ContentPart[];
     /** AI 消息发起的工具调用列表 */
     tool_calls?: ChatToolCall[];
     /** Tool 消息关联的 tool_call_id */

packages/scorpio.ai/src/Saver/index.ts

@@ -4,7 +4,18 @@
  */
 
 // ===== 接口 + Symbol Token + 中性类型 =====
-export { IAgentSaverService, MessageRole, type StoredMessage, type ChatMessage, type ChatToolCall, type ChatMessageOptions, type MessageContent, type TokenUsage } from "./IAgentSaverService";
+export {
+    IAgentSaverService,
+    MessageRole,
+    ContentPartType,
+    type StoredMessage,
+    type ChatMessage,
+    type ChatToolCall,
+    type ChatMessageOptions,
+    type MessageContent,
+    type ContentPart,
+    type TokenUsage,
+} from "./IAgentSaverService";
 
 // ===== LangChain 转换（仅在 Agent 执行层需要） =====
 export { toChatMessage, toBaseMessage, toBaseMessages } from "./messageConverter";

packages/scorpio.ai/src/Utils/contentUtils.ts

@@ -1,19 +1,23 @@
-import type { MessageContent } from "../Saver/IAgentSaverService";
+import type { ContentPart, MessageContent } from "../Saver/IAgentSaverService";
+
+type TextPart = Extract<ContentPart, { type: 'text' }>;
+const isTextPart = (p: ContentPart): p is TextPart => p.type === 'text';
 
 /** Extract a plain-text representation from MessageContent. */
 export function contentToString(content: MessageContent): string {
     if (typeof content === 'string') return content;
     if (!Array.isArray(content)) return '';
     return content
-        .filter(c => c.type === 'text' && c.text)
-        .map(c => c.text!)
+        .filter(isTextPart)
+        .map(p => p.text)
+        .filter((t): t is string => !!t)
         .join('\n');
 }
 
 /** Remove empty/whitespace-only text parts from MessageContent. */
 export function trimContent(content: MessageContent): MessageContent {
     if (typeof content === 'string') return content.trim();
-    return content.filter(p => p.type !== 'text' || p.text?.trim());
+    return content.filter(p => !isTextPart(p) || !!p.text?.trim());
 }
 
 /** Check if MessageContent is empty. */
@@ -62,8 +66,6 @@ export function detectMediaType(filePath: string): { mimeType: string; category:
     return { mimeType, category };
 }
 
-export type ContentPart = { type: string; text?: string; [key: string]: any };
-
 export let maxImageSize: number | undefined;
 
 export function setMaxImageSize(size: number | undefined) {

packages/scorpio.ai/src/index.ts

@@ -166,6 +166,10 @@ export {
   type MessageContent,
   type TokenUsage,
 
+  // ContentPart 判别联合
+  ContentPartType,
+  type ContentPart,
+
   // 实现类
   AgentMemorySaver,
   AgentFileSaver,
@@ -343,6 +347,6 @@ export { MessageDispatcher, MessageType, summarizeMultimodal } from "./User";
 // Utils - 工具函数
 // ========================================
 export { contentToString, trimContent, isEmptyContent, readImageAsDataUrl, readMediaAsContentPart, detectMediaType, setMaxImageSize, resizeImageIfNeeded } from "./Utils/contentUtils";
-export type { MediaCategory, ContentPart } from "./Utils/contentUtils";
+export type { MediaCategory } from "./Utils/contentUtils";
 export { withRetry } from "./Utils/withRetry";
 export { UsageTracker, type UsageData } from "./Utils/UsageTracker";