✨ Agent 多项改进：附件路径迁移、LLM 重试机制、系统提示词优化

- 附件存储从 conversations/attachments 迁移到 workspace/uploads，LLM 可通过 OPFS 路径访问
- Provider 非图片附件改用 OPFS 路径引用，减少 context 占用
- LLM API 调用增加重试机制（最多 5 次，递增延迟），UI 显示倒计时
- 系统提示词优化：强化 loop detection、ask early 策略、工具调用预算
- get_tab_content/web_fetch 必须提供 prompt 参数，引导高效使用
- ToolRegistry 错误信息包含可用工具列表，帮助 LLM 自我纠正
- 编辑消息支持附件增删和粘贴，停止生成时正确标记 tool call 状态
- 修复 SenderRuntime null safety、stopGeneration 竞态、base64 编码性能
- 新增 CAT.agent.model.getSummary API、后台模式 tooltip i18n

Author: CodFrm

packages/message/server.ts

@@ -87,6 +87,15 @@ export class SenderRuntime {
 
   getExtMessageSender(): ExtMessageSender {
     const sender = this.sender as RuntimeMessageSender;
+    if (!sender) {
+      // postMessage 通道（如 Offscreen→SW）没有 RuntimeMessageSender
+      return {
+        windowId: -1,
+        tabId: -1,
+        frameId: undefined,
+        documentId: undefined,
+      };
+    }
     return {
       windowId: sender.tab?.windowId || -1, // -1表示后台脚本
       tabId: sender.tab?.id || -1, // -1表示后台脚本

src/app/repo/agent_chat.test.ts

@@ -19,23 +19,18 @@ function createMockOPFS() {
       kind: "file" as const,
       getFile: vi.fn(async () => {
         const content = dir.get(name);
-        if (content instanceof Blob) {
-          return content;
-        }
-        return new Blob([typeof content === "string" ? content : ""], { type: "application/octet-stream" });
+        if (content instanceof Blob) return content;
+        if (content instanceof ArrayBuffer) return new Blob([content]);
+        if (content instanceof Uint8Array) return new Blob([content.buffer as ArrayBuffer]);
+        if (typeof content === "string") return new Blob([content], { type: "application/octet-stream" });
+        return new Blob([""], { type: "application/octet-stream" });
       }),
       createWritable: vi.fn(async () => {
         const writable = createMockWritable();
         const origClose = writable.close;
         writable.close = vi.fn(async () => {
           const written = writable.getData();
-          if (written instanceof Blob) {
-            dir.set(name, written);
-          } else if (typeof written === "string") {
-            dir.set(name, written);
-          } else {
-            dir.set(name, written);
-          }
+          dir.set(name, written);
           await origClose();
         });
         return writable;
@@ -95,11 +90,26 @@ function createMockOPFS() {
   return { rootStore, mockRoot };
 }
 
+// 在 mock store 中按路径导航/创建目录
+function navigateDir(rootStore: Map<string, any>, ...path: string[]): Map<string, any> {
+  let current = rootStore;
+  for (const seg of path) {
+    const key = "__dir__" + seg;
+    if (!current.has(key)) {
+      current.set(key, new Map());
+    }
+    current = current.get(key);
+  }
+  return current;
+}
+
 describe("AgentChatRepo 附件存储", () => {
   let repo: AgentChatRepo;
+  let rootStore: Map<string, any>;
 
   beforeEach(() => {
-    createMockOPFS();
+    const mock = createMockOPFS();
+    rootStore = mock.rootStore;
     repo = new AgentChatRepo();
   });
 
@@ -118,6 +128,14 @@ describe("AgentChatRepo 附件存储", () => {
     expect(size).toBe(blob.size);
   });
 
+  it("saveAttachment 应存储到 workspace/uploads 路径", async () => {
+    await repo.saveAttachment("att-ws", new Blob(["workspace data"]));
+
+    // 验证新路径存在: agents/workspace/uploads/att-ws
+    const uploadsDir = navigateDir(rootStore, "agents", "workspace", "uploads");
+    expect(uploadsDir.has("att-ws")).toBe(true);
+  });
+
   it("getAttachment 应返回已保存的附件", async () => {
     const blob = new Blob(["test data"], { type: "text/plain" });
     await repo.saveAttachment("att-3", blob);
@@ -134,6 +152,19 @@ describe("AgentChatRepo 附件存储", () => {
     expect(result).toBeNull();
   });
 
+  it("getAttachment 应能回退读取旧路径的附件", async () => {
+    // 手动在旧路径写入附件数据: agents/conversations/attachments/{id}
+    const attachDir = navigateDir(rootStore, "agents", "conversations", "attachments");
+    attachDir.set("old-att", new Blob(["old path data"]));
+
+    const result = await repo.getAttachment("old-att");
+
+    expect(result).not.toBeNull();
+    expect(result).toBeInstanceOf(Blob);
+    const text = await result!.text();
+    expect(text).toBe("old path data");
+  });
+
   it("deleteAttachment 应删除已保存的附件", async () => {
     const blob = new Blob(["data"], { type: "text/plain" });
     await repo.saveAttachment("att-4", blob);
@@ -144,6 +175,21 @@ describe("AgentChatRepo 附件存储", () => {
     expect(result).toBeNull();
   });
 
+  it("deleteAttachment 应同时清理新旧路径", async () => {
+    // 在新路径保存
+    await repo.saveAttachment("att-both", new Blob(["new"]));
+    // 在旧路径也放一份
+    const attachDir = navigateDir(rootStore, "agents", "conversations", "attachments");
+    attachDir.set("att-both", new Blob(["old"]));
+
+    await repo.deleteAttachment("att-both");
+
+    // 新旧路径都应被清理
+    const uploadsDir = navigateDir(rootStore, "agents", "workspace", "uploads");
+    expect(uploadsDir.has("att-both")).toBe(false);
+    expect(attachDir.has("att-both")).toBe(false);
+  });
+
   it("deleteAttachments 应批量删除附件", async () => {
     await repo.saveAttachment("att-a", new Blob(["a"]));
     await repo.saveAttachment("att-b", new Blob(["b"]));

src/app/repo/agent_chat.ts

@@ -1,6 +1,7 @@
 import type { Conversation, ChatMessage } from "@App/app/service/agent/types";
 import type { Task } from "@App/app/service/agent/tools/task_tools";
 import { OPFSRepo } from "./opfs_repo";
+import { writeWorkspaceFile, getWorkspaceRoot, getDirectory } from "@App/app/service/agent/opfs_helpers";
 
 const CONVERSATIONS_FILE = "conversations.json";
 const MESSAGES_DIR = "data";
@@ -10,7 +11,8 @@ const TASKS_DIR = "tasks";
 // 目录结构：agents/conversations/
 //            agents/conversations/conversations.json       - 会话列表
 //            agents/conversations/data/{id}.json           - 每个会话的消息
-//            agents/conversations/attachments/{id}         - 附件二进制数据
+//            agents/workspace/uploads/{id}                 - 附件二进制数据（LLM 可通过 opfs_read 访问）
+//            agents/conversations/attachments/{id}         - 旧路径（兼容读取）
 export class AgentChatRepo extends OPFSRepo {
   constructor() {
     super("conversations");
@@ -104,50 +106,57 @@ export class AgentChatRepo extends OPFSRepo {
   }
 
   // ---- 附件存储 ----
+  // 新路径: agents/workspace/uploads/{id}（LLM 可通过 opfs_read 访问）
+  // 旧路径: agents/conversations/attachments/{id}（兼容读取）
 
-  // 保存附件数据（支持 base64/data URL 字符串或 Blob）
+  // 保存附件数据到 workspace/uploads（支持 base64/data URL 字符串或 Blob）
   async saveAttachment(id: string, data: string | Blob): Promise<number> {
-    const dir = await this.getChildDir(ATTACHMENTS_DIR);
-    const fileHandle = await dir.getFileHandle(id, { create: true });
-    const writable = await fileHandle.createWritable();
-
-    let size: number;
-    if (data instanceof Blob) {
-      await writable.write(data);
-      size = data.size;
-    } else {
-      // 字符串数据（base64/data URL），按原始二进制存储
-      const binary = this.dataUrlToBlob(data);
-      await writable.write(binary);
-      size = binary.size;
-    }
-
-    await writable.close();
-    return size;
+    const result = await writeWorkspaceFile(`uploads/${id}`, data);
+    return result.size;
   }
 
-  // 读取附件数据为 Blob
+  // 读取附件数据为 Blob（先查 workspace 新路径，fallback 旧路径）
   async getAttachment(id: string): Promise<Blob | null> {
+    // 新路径: agents/workspace/uploads/{id}
+    try {
+      const workspace = await getWorkspaceRoot();
+      const dir = await getDirectory(workspace, "uploads");
+      return await (await dir.getFileHandle(id)).getFile();
+    } catch {
+      // 新路径不存在，尝试旧路径
+    }
+    // 旧路径回退: agents/conversations/attachments/{id}
     try {
       const dir = await this.getChildDir(ATTACHMENTS_DIR);
-      const fileHandle = await dir.getFileHandle(id);
-      return await fileHandle.getFile();
+      return await (await dir.getFileHandle(id)).getFile();
     } catch {
       return null;
     }
   }
 
-  // 删除单个附件
+  // 删除单个附件（同时清理新旧路径）
   async deleteAttachment(id: string): Promise<void> {
-    const dir = await this.getChildDir(ATTACHMENTS_DIR);
-    await this.deleteFile(id, dir);
+    // 新路径: agents/workspace/uploads/{id}
+    try {
+      const workspace = await getWorkspaceRoot();
+      const dir = await getDirectory(workspace, "uploads");
+      await dir.removeEntry(id);
+    } catch {
+      // 新路径不存在则忽略
+    }
+    // 旧路径: agents/conversations/attachments/{id}
+    try {
+      const dir = await this.getChildDir(ATTACHMENTS_DIR);
+      await dir.removeEntry(id);
+    } catch {
+      // 旧路径不存在则忽略
+    }
   }
 
   // 删除会话关联的所有附件（需传入附件 ID 列表）
   async deleteAttachments(ids: string[]): Promise<void> {
-    const dir = await this.getChildDir(ATTACHMENTS_DIR);
     for (const id of ids) {
-      await this.deleteFile(id, dir);
+      await this.deleteAttachment(id);
     }
   }
 
@@ -171,20 +180,4 @@ export class AgentChatRepo extends OPFSRepo {
     await this.deleteFile(`${conversationId}.json`, tasksDir);
   }
 
-  // 将 data URL 或纯 base64 转换为 Blob
-  private dataUrlToBlob(data: string): Blob {
-    // 匹配 data URL 格式
-    const match = data.match(/^data:([^;]+);base64,(.+)$/s);
-    if (match) {
-      const byteString = atob(match[2]);
-      const ab = new ArrayBuffer(byteString.length);
-      const ia = new Uint8Array(ab);
-      for (let i = 0; i < byteString.length; i++) {
-        ia[i] = byteString.charCodeAt(i);
-      }
-      return new Blob([ab], { type: match[1] });
-    }
-    // 纯文本存储
-    return new Blob([data], { type: "application/octet-stream" });
-  }
 }

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

@@ -25,35 +25,30 @@ function convertContentBlocks(
               source: { type: "base64", media_type: match[1], data: match[2] },
             });
           } else {
-            result.push({ type: "text", text: `[Image: ${block.name || "image"}]` });
-          }
-        } else {
-          result.push({ type: "text", text: `[Image: ${block.name || "image"}]` });
-        }
-        break;
-      }
-      case "file": {
-        const data = attachmentResolver?.(block.attachmentId);
-        if (data) {
-          const match = data.match(/^data:([^;]+);base64,(.+)$/s);
-          if (match) {
             result.push({
-              type: "document",
-              source: { type: "base64", media_type: match[1], data: match[2] },
+              type: "text",
+              text: `[Image: ${block.name || "image"}, OPFS path: uploads/${block.attachmentId}]`,
             });
-          } else {
-            result.push({ type: "text", text: `[File: ${block.name}]` });
           }
         } else {
-          result.push({ type: "text", text: `[File: ${block.name}]` });
+          result.push({
+            type: "text",
+            text: `[Image: ${block.name || "image"}, OPFS path: uploads/${block.attachmentId}]`,
+          });
         }
         break;
       }
+      case "file":
+        result.push({
+          type: "text",
+          text: `[File: ${block.name}${block.size ? ` (${block.size} bytes)` : ""}, OPFS path: uploads/${block.attachmentId}]`,
+        });
+        break;
       case "audio":
         // Anthropic 暂不支持音频，降级为文本描述
         result.push({
           type: "text",
-          text: `[Audio: ${block.name || "audio"}${block.durationMs ? ` (${(block.durationMs / 1000).toFixed(1)}s)` : ""}]`,
+          text: `[Audio: ${block.name || "audio"}${block.durationMs ? ` (${(block.durationMs / 1000).toFixed(1)}s)` : ""}, OPFS path: uploads/${block.attachmentId}]`,
         });
         break;
     }

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

@@ -19,13 +19,18 @@ function convertContentBlocks(
         if (data) {
           result.push({ type: "image_url", image_url: { url: data } });
         } else {
-          result.push({ type: "text", text: `[Image: ${block.name || "image"}]` });
+          result.push({
+            type: "text",
+            text: `[Image: ${block.name || "image"}, OPFS path: uploads/${block.attachmentId}]`,
+          });
         }
         break;
       }
       case "file":
-        // OpenAI 不支持文件上传到 chat，降级为文本引用
-        result.push({ type: "text", text: `[File: ${block.name}]` });
+        result.push({
+          type: "text",
+          text: `[File: ${block.name}${block.size ? ` (${block.size} bytes)` : ""}, OPFS path: uploads/${block.attachmentId}]`,
+        });
         break;
       case "audio": {
         const data = attachmentResolver?.(block.attachmentId);
@@ -36,10 +41,16 @@ function convertContentBlocks(
             const format = block.mimeType.split("/")[1] || "wav";
             result.push({ type: "input_audio", input_audio: { data: match[2], format } });
           } else {
-            result.push({ type: "text", text: `[Audio: ${block.name || "audio"}]` });
+            result.push({
+              type: "text",
+              text: `[Audio: ${block.name || "audio"}, OPFS path: uploads/${block.attachmentId}]`,
+            });
           }
         } else {
-          result.push({ type: "text", text: `[Audio: ${block.name || "audio"}]` });
+          result.push({
+            type: "text",
+            text: `[Audio: ${block.name || "audio"}, OPFS path: uploads/${block.attachmentId}]`,
+          });
         }
         break;
       }

src/app/service/agent/system_prompt.ts

@@ -6,27 +6,39 @@ const BUILTIN_SYSTEM_PROMPT = `You are ScriptCat Agent, an AI assistant built in
 
 - Before interacting with a page, verify its current state — never assume a page is as expected.
 - When a step fails, analyze the cause and change your approach. Never retry the exact same action.
+- Prefer asking the user over guessing. One good question saves many wasted tool calls.
 
 ## Planning
 
 - **Simple tasks** (single step, clear intent): act directly.
-- **Complex tasks** (multi-step, involves navigation across pages, form submissions, or data processing): first propose a numbered step-by-step plan, then wait for user confirmation before executing. The user may adjust, approve, or reject the plan.
-- During execution, if the situation deviates from the plan (unexpected page state, missing element, new information), pause and inform the user with an updated plan rather than silently improvising.
+- **Complex tasks** (multi-step, involves navigation across pages, form submissions, or data processing):
+  1. **Think first** — Before any tool call, analyze the task and design a clear execution plan. Consider: what information do you need? What could go wrong? What's the most efficient sequence of steps?
+  2. **Propose the plan** — Present a numbered step-by-step plan to the user and wait for confirmation. The user may adjust, approve, or reject.
+  3. **Execute methodically** — Follow the approved plan step by step. Use task tools to track progress.
+- During execution, if the situation deviates from the plan (unexpected page state, missing element, new information), **stop and inform the user** with an updated plan rather than silently improvising.
+- **Avoid speculative chains** — Do not chain multiple uncertain actions hoping they will work. If the first step's outcome is uncertain, verify before proceeding.
 
 ## Tool Usage
 
 Your tools come from Skills and MCP servers. Read each tool's description before calling — it defines behavior, parameters, and constraints. When a tool returns an error, read the error message and adapt — do not blindly retry.
 
-### Loop Detection
-Detect when you are stuck and stop early:
-- **Hard loop**: Same tool + same arguments failing 2+ times → change approach immediately.
+**Tool call budget**: You have a limited number of tool calls per conversation (typically 50). Use them wisely — plan before acting, combine steps when possible, and stop early if stuck.
+
+### Loop Detection — Stop Early, Ask Early
+Continuing to error wastes tokens and never produces good results. Detect when you are stuck and **ask the user before exhausting attempts**:
+- **Hard loop**: Same tool + same arguments failing 2+ times → stop immediately, do NOT retry.
 - **Ping-pong**: Alternating between two actions (A → B → A → B) without progress → stop and rethink.
-- **Persistent failure**: Same error 3+ times despite different approaches → escalate.
+- **Persistent failure**: 2 consecutive errors (even with different approaches) → stop trying and use \`ask_user\` immediately.
+- **Wrong path detection**: If after 3+ tool calls you are not making meaningful progress toward the goal, stop and reassess. Ask yourself: "Am I on the right track?" If unsure, ask the user.
+- **Diminishing returns**: If you're making tiny incremental progress but the goal still seems far, stop and ask the user if the approach is correct.
+
+### Escalation
+When stuck, **prioritize asking the user over repeated attempts**:
+1. **One retry with a different strategy** — try ONE fundamentally different approach.
+2. **Ask the user** — if that also fails, immediately use \`ask_user\` to summarize what you tried and why it failed, then ask for guidance. Do not attempt a third approach without user input.
+3. **Declare blocked** — if the task is clearly impossible given current permissions or page state, say so directly.
 
-### Escalation (in order of preference)
-1. **Switch strategy** — try a fundamentally different approach.
-2. **Ask the user** — summarize what you tried and why it failed, then ask for guidance.
-3. **Declare blocked** — if the task is impossible given current permissions or page state, say so clearly.
+**Default to asking**: When in doubt between trying another approach and asking the user, always ask. The user's time is less expensive than wasting tool calls on wrong approaches.
 
 ## Safety