✨ 附件扩展名、readAttachment API、缓存用量追踪与 UI 优化

- 附件 ID 统一追加文件扩展名，便于类型识别
- 新增 CAT.agent.opfs.readAttachment API 读取内部附件存储
- usage 增加 cacheCreationInputTokens/cacheReadInputTokens 追踪
- OPFS 浏览器支持图片预览、文件下载、图标区分
- AskUserBlock 交互卡片 UI 重构（渐变条、pill 选项、内联输入）
- ConversationInstance 收集模型生成的图片/文件 content blocks
- 模型配置自动检测 supportsVision/supportsImageOutput

Author: CodFrm

src/app/service/agent/agent.test.ts

@@ -692,7 +692,7 @@ describe("callLLMWithToolLoop", () => {
 
     const doneEvent = events.find((e) => e.type === "done");
     expect(doneEvent).toBeDefined();
-    expect(doneEvent!.type === "done" && doneEvent!.usage).toEqual({ inputTokens: 10, outputTokens: 5 });
+    expect(doneEvent!.type === "done" && doneEvent!.usage).toEqual({ inputTokens: 10, outputTokens: 5, cacheCreationInputTokens: 0, cacheReadInputTokens: 0 });
   });
 
   it("单轮 tool calling", async () => {
@@ -747,7 +747,7 @@ describe("callLLMWithToolLoop", () => {
     const doneEvent = events.find((e) => e.type === "done");
     expect(doneEvent).toBeDefined();
     if (doneEvent?.type === "done") {
-      expect(doneEvent.usage).toEqual({ inputTokens: 50, outputTokens: 18 });
+      expect(doneEvent.usage).toEqual({ inputTokens: 50, outputTokens: 18, cacheCreationInputTokens: 0, cacheReadInputTokens: 0 });
     }
   });
 

src/app/service/agent/content_utils.ts

@@ -1,5 +1,43 @@
 import type { MessageContent, ContentBlock } from "./types";
 
+// MIME 类型 → 文件扩展名映射
+const MIME_EXT_MAP: Record<string, string> = {
+  "image/png": "png",
+  "image/jpeg": "jpg",
+  "image/gif": "gif",
+  "image/webp": "webp",
+  "image/svg+xml": "svg",
+  "image/bmp": "bmp",
+  "audio/wav": "wav",
+  "audio/mpeg": "mp3",
+  "audio/mp3": "mp3",
+  "audio/ogg": "ogg",
+  "audio/webm": "webm",
+  "application/pdf": "pdf",
+  "application/zip": "zip",
+  "application/json": "json",
+  "text/plain": "txt",
+  "text/html": "html",
+  "text/csv": "csv",
+};
+
+/**
+ * 根据 MIME 类型获取文件扩展名
+ */
+export function getExtFromMime(mimeType: string): string {
+  if (MIME_EXT_MAP[mimeType]) return MIME_EXT_MAP[mimeType];
+  // 从子类型中提取（去掉非字母数字字符）
+  const sub = mimeType.split("/")[1];
+  return sub ? sub.replace(/[^a-z0-9]/gi, "") : "bin";
+}
+
+/**
+ * 判断文件名是否为图片类型（根据扩展名）
+ */
+export function isImageFileName(name: string): boolean {
+  return /\.(png|jpe?g|gif|webp|svg|bmp|ico|avif)$/i.test(name);
+}
+
 /**
  * 从 MessageContent 提取纯文本（用于 copy、搜索、标题生成等）
  * - string: 直接返回

src/app/service/agent/providers/anthropic.ts

@@ -270,7 +270,8 @@ export function parseAnthropicStream(
                 if (imageBlockData) {
                   const fullBase64 = imageBlockData.base64Chunks.join("");
                   const dataUrl = `data:${imageBlockData.mediaType};base64,${fullBase64}`;
-                  const attachmentId = `img_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+                  const ext = imageBlockData.mediaType.split("/")[1] || "png";
+                  const attachmentId = `img_${Date.now()}_${Math.random().toString(36).slice(2, 8)}.${ext}`;
                   onEvent({
                     type: "content_block_complete",
                     block: {

src/app/service/agent/providers/openai.ts

@@ -180,7 +180,8 @@ export function parseOpenAIStream(
                         const dataUrl: string = part.image_url.url;
                         const mimeMatch = dataUrl.match(/^data:([^;]+);/);
                         const mimeType = mimeMatch ? mimeMatch[1] : "image/png";
-                        const blockId = `img_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+                        const ext = mimeType.split("/")[1] || "png";
+                        const blockId = `img_${Date.now()}_${Math.random().toString(36).slice(2, 8)}.${ext}`;
                         onEvent({
                           type: "content_block_complete",
                           block: { type: "image", attachmentId: blockId, mimeType, name: "generated-image" },

src/app/service/agent/tool_registry.ts

@@ -1,6 +1,7 @@
 import type { Attachment, ToolCall, ToolDefinition, ToolResultWithAttachments } from "./types";
 import type { AgentChatRepo } from "@App/app/repo/agent_chat";
 import { uuidv4 } from "@App/pkg/utils/uuid";
+import { getExtFromMime } from "./content_utils";
 
 // 工具执行器接口
 export interface ToolExecutor {
@@ -131,7 +132,8 @@ export class ToolRegistry {
 
     const attachments: Attachment[] = [];
     for (const ad of attachmentDataList) {
-      const id = uuidv4();
+      const ext = getExtFromMime(ad.mimeType);
+      const id = `${uuidv4()}.${ext}`;
       const size = await this.chatRepo.saveAttachment(id, ad.data);
       attachments.push({
         id,

src/app/service/agent/tools/tab_tools.ts

@@ -8,8 +8,9 @@ import { extractHtmlWithSelectors } from "@App/app/service/offscreen/client";
 const GET_TAB_CONTENT_DEFINITION: ToolDefinition = {
   name: "get_tab_content",
   description:
-    "Read the rendered content of a browser tab. Returns cleaned markdown with CSS selector annotations for key elements. " +
-    "Use selector to extract specific sections. Use prompt to have the LLM summarize/extract specific information from the content.",
+    "Read the text content of a browser tab as cleaned markdown. Best for reading articles, extracting text, or summarizing page content. " +
+    "Use selector to extract specific sections. Use prompt to have the LLM summarize/extract specific information. " +
+    "NOTE: If you need to locate interactive elements (buttons, inputs, links) for clicking or form-filling, use the browser_action tool from the browser-automation skill instead — it returns element selectors optimized for DOM operations.",
   parameters: {
     type: "object",
     properties: {

src/app/service/agent/types.ts

@@ -176,7 +176,7 @@ export type ChatReply = {
   content: MessageContent;
   thinking?: string;
   toolCalls?: ToolCall[];
-  usage?: { inputTokens: number; outputTokens: number };
+  usage?: { inputTokens: number; outputTokens: number; cacheCreationInputTokens?: number; cacheReadInputTokens?: number };
   command?: boolean; // 标识该回复来自命令处理
 };
 
@@ -186,7 +186,7 @@ export type StreamChunk = {
   content?: string;
   block?: ContentBlock;
   toolCall?: ToolCall;
-  usage?: { inputTokens: number; outputTokens: number };
+  usage?: { inputTokens: number; outputTokens: number; cacheCreationInputTokens?: number; cacheReadInputTokens?: number };
   error?: string;
   /** 错误分类码："rate_limit" | "auth" | "tool_timeout" | "max_iterations" | "api_error" */
   errorCode?: string;
@@ -253,6 +253,7 @@ export type SkillApiRequest =
 export type OPFSApiRequest =
   | { action: "write"; path: string; content: string | Blob; scriptUuid: string }
   | { action: "read"; path: string; format?: "text" | "bloburl"; scriptUuid: string }
+  | { action: "readAttachment"; id: string; format?: "bloburl" | "dataurl"; scriptUuid: string }
   | { action: "list"; path?: string; scriptUuid: string }
   | { action: "delete"; path: string; scriptUuid: string };
 

src/app/service/content/gm_api/cat_agent.ts

@@ -5,6 +5,7 @@ import type {
   ChatReply,
   ChatStreamEvent,
   CommandHandler,
+  ContentBlock,
   Conversation,
   ConversationApiRequest,
   ConversationCreateOptions,
@@ -294,6 +295,7 @@ export class ConversationInstance {
       let content = "";
       let thinking = "";
       const toolCalls: ToolCall[] = [];
+      const contentBlocks: ContentBlock[] = [];
       let currentToolCall: ToolCall | null = null;
       let usage: { inputTokens: number; outputTokens: number } | undefined;
 
@@ -316,26 +318,39 @@ export class ConversationInstance {
           case "thinking_delta":
             thinking += event.delta;
             break;
+          case "content_block_complete":
+            // 收集模型生成的图片/文件/音频 blocks（data 已由 finalize 保存到 attachment 存储）
+            contentBlocks.push(event.block);
+            break;
           case "tool_call_start":
             if (currentToolCall) toolCalls.push(currentToolCall);
             currentToolCall = { ...event.toolCall, arguments: event.toolCall.arguments || "" };
             break;
           case "tool_call_delta":
             if (currentToolCall) currentToolCall.arguments += event.delta;
             break;
-          case "done":
+          case "done": {
             if (currentToolCall) {
               toolCalls.push(currentToolCall);
               currentToolCall = null;
             }
             if (event.usage) usage = event.usage;
+            // 合并文本和 content blocks 到 MessageContent
+            let finalContent: MessageContent = content;
+            if (contentBlocks.length > 0) {
+              const blocks: ContentBlock[] = [];
+              if (content) blocks.push({ type: "text", text: content });
+              blocks.push(...contentBlocks);
+              finalContent = blocks;
+            }
             resolve({
-              content,
+              content: finalContent,
               thinking: thinking || undefined,
               toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
               usage,
             });
             break;
+          }
           case "error":
             reject(Object.assign(new Error(event.message), { errorCode: event.errorCode }));
             break;
@@ -377,6 +392,9 @@ export class ConversationInstance {
         case "thinking_delta":
           chunk = { type: "thinking_delta", content: event.delta };
           break;
+        case "content_block_complete":
+          chunk = { type: "content_block", block: event.block };
+          break;
         case "tool_call_start":
           chunk = { type: "tool_call", toolCall: { ...event.toolCall, arguments: "" } };
           break;

src/app/service/content/gm_api/cat_agent_opfs.ts

@@ -51,6 +51,17 @@ export default class CATAgentOPFSApi {
     ]) as Promise<Array<{ name: string; type: string; size?: number }>>;
   }
 
+  @GMContext.API({ follow: "CAT.agent.opfs" })
+  public "CAT.agent.opfs.readAttachment"(
+    id: string,
+    format?: "bloburl" | "dataurl"
+  ): Promise<{ id: string; blobUrl?: string; content?: string; size: number; mimeType?: string }> {
+    const ctx = this as unknown as GMBaseContext;
+    return ctx.sendMessage("CAT_agentOPFS", [
+      { action: "readAttachment", id, format, scriptUuid: ctx.scriptRes?.uuid || "" } as OPFSApiRequest,
+    ]) as Promise<{ id: string; blobUrl?: string; content?: string; size: number; mimeType?: string }>;
+  }
+
   @GMContext.API({ follow: "CAT.agent.opfs" })
   public "CAT.agent.opfs.delete"(path: string): Promise<{ success: true }> {
     const ctx = this as unknown as GMBaseContext;

src/app/service/service_worker/agent.ts

@@ -27,6 +27,7 @@ import type {
   ContentBlock,
 } from "@App/app/service/agent/types";
 import { getTextContent, isContentBlocks } from "@App/app/service/agent/content_utils";
+import { supportsVision, supportsImageOutput } from "@App/pages/options/routes/AgentChat/model_utils";
 import { buildOpenAIRequest, parseOpenAIStream } from "@App/app/service/agent/providers/openai";
 import { buildAnthropicRequest, parseAnthropicStream } from "@App/app/service/agent/providers/anthropic";
 import { AgentChatRepo } from "@App/app/repo/agent_chat";
@@ -447,6 +448,22 @@ export class AgentService {
         const executor = toolMap.get("opfs_read")!;
         return JSON.parse((await executor.execute({ path: request.path, format: request.format })) as string);
       }
+      case "readAttachment": {
+        const blob = await this.repo.getAttachment(request.id);
+        if (!blob) {
+          throw new Error(`Attachment not found: ${request.id}`);
+        }
+        if (request.format === "dataurl") {
+          // 转为 data URL
+          const buffer = await blob.arrayBuffer();
+          const base64 = btoa(String.fromCharCode(...new Uint8Array(buffer)));
+          const dataUrl = `data:${blob.type || "application/octet-stream"};base64,${base64}`;
+          return { id: request.id, content: dataUrl, size: blob.size, mimeType: blob.type };
+        }
+        // 默认返回 blob URL
+        const blobUrl = URL.createObjectURL(blob);
+        return { id: request.id, blobUrl, size: blob.size, mimeType: blob.type };
+      }
       case "list": {
         const executor = toolMap.get("opfs_list")!;
         return JSON.parse((await executor.execute({ path: request.path || "" })) as string);
@@ -909,8 +926,12 @@ export class AgentService {
   }
 
   // 处理 CAT.agent.model API 请求（只读，隐藏 apiKey），供 GMApi 调用
+  // 同时补充 supportsVision / supportsImageOutput 的自动检测 fallback，
+  // 避免用户未手动勾选时脚本端拿到 undefined
   private stripApiKey(model: AgentModelConfig): AgentModelSafeConfig {
     const { apiKey: _, ...safe } = model;
+    safe.supportsVision = supportsVision(model);
+    safe.supportsImageOutput = supportsImageOutput(model);
     return safe;
   }
 
@@ -1018,7 +1039,7 @@ export class AgentService {
 
     const startTime = Date.now();
     let iterations = 0;
-    const totalUsage = { inputTokens: 0, outputTokens: 0 };
+    const totalUsage = { inputTokens: 0, outputTokens: 0, cacheCreationInputTokens: 0, cacheReadInputTokens: 0 };
 
     while (iterations < maxIterations) {
       iterations++;
@@ -1050,6 +1071,8 @@ export class AgentService {
       if (result.usage) {
         totalUsage.inputTokens += result.usage.inputTokens;
         totalUsage.outputTokens += result.usage.outputTokens;
+        totalUsage.cacheCreationInputTokens += result.usage.cacheCreationInputTokens || 0;
+        totalUsage.cacheReadInputTokens += result.usage.cacheReadInputTokens || 0;
       }
 
       // 自动 compact：当上下文占用超过 80% 时触发
@@ -1159,19 +1182,22 @@ export class AgentService {
       }
 
       // 没有 tool calls，对话结束
+      const durationMs = Date.now() - startTime;
       if (conversationId) {
         await this.repo.appendMessage({
           id: uuidv4(),
           conversationId,
           role: "assistant",
           content: buildMessageContent(),
           thinking: result.thinking ? { content: result.thinking } : undefined,
+          usage: totalUsage,
+          durationMs,
           createtime: Date.now(),
         });
       }
 
       // 发送 done 事件
-      sendEvent({ type: "done", usage: totalUsage, durationMs: Date.now() - startTime });
+      sendEvent({ type: "done", usage: totalUsage, durationMs });
       return;
     }
 
@@ -1748,7 +1774,7 @@ export class AgentService {
     content: string;
     thinking?: string;
     toolCalls?: ToolCall[];
-    usage?: { inputTokens: number; outputTokens: number };
+    usage?: { inputTokens: number; outputTokens: number; cacheCreationInputTokens?: number; cacheReadInputTokens?: number };
     contentBlocks?: ContentBlock[];
   }> {
     const chatRequest: ChatRequest = {
@@ -1793,7 +1819,7 @@ export class AgentService {
     let thinking = "";
     const toolCalls: ToolCall[] = [];
     let currentToolCall: ToolCall | null = null;
-    let usage: { inputTokens: number; outputTokens: number } | undefined;
+    let usage: { inputTokens: number; outputTokens: number; cacheCreationInputTokens?: number; cacheReadInputTokens?: number } | undefined;
     // 收集带 data 的图片 block（模型生成的图片），stream 结束后统一保存到 OPFS
     const pendingImageSaves: Array<{ block: ContentBlock & { type: "image" }; data: string }> = [];
 
@@ -1860,8 +1886,9 @@ export class AgentService {
               let cleanedContent = content;
               while ((match = imgRegex.exec(content)) !== null) {
                 const [fullMatch, alt, dataUrl, subtype] = match;
-                const blockId = `img_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
                 const mimeType = `image/${subtype}`;
+                const ext = subtype || "png";
+                const blockId = `img_${Date.now()}_${Math.random().toString(36).slice(2, 8)}.${ext}`;
                 try {
                   await this.repo.saveAttachment(blockId, dataUrl);
                   const block: ContentBlock = {