✨ opfs_read 支持文本内容读取、搜索提取失败提示、正则校验

- opfs_read 自动检测文本/二进制：文本文件直接返回内容（支持 offset/limit 分页），二进制返回 blob URL
- web_search 区分"无结果"和"提取失败"，返回 warning 引导 agent 切换引擎
- tab_tools 对无效正则参数抛出明确错误

Author: CodFrm

src/app/service/agent/system_prompt.ts

@@ -167,18 +167,21 @@ Use task tools **only** when tracking progress genuinely helps the user understa
 
 const SECTION_OPFS = `## OPFS Workspace
 
-OPFS stores files persistently (survives conversation restarts). Designed primarily for **binary data** (images, downloads, attachments).
+OPFS stores files persistently (survives conversation restarts). Supports both **text** and **binary** data.
 
 **When to use OPFS**:
-- Binary files that need to be passed to the page: images, PDFs, downloads → \`opfs_write\` to save, \`opfs_read\` to get blob URL for page use
-- Data that needs to persist across conversations (e.g., user config, style profiles managed by skills)
-- SkillScript intermediate binary output (e.g., generated images saved via \`CAT.agent.opfs.write(blob)\`)
+- Text data that needs to persist across conversations (config, notes, structured data) → \`opfs_write\` to save, \`opfs_read\` to retrieve text content
+- Binary files that need to be passed to the page: images, PDFs, downloads → \`opfs_write\` to save, \`opfs_read\` to get blob URL
+- SkillScript intermediate output (e.g., generated images saved via \`CAT.agent.opfs.write(blob)\`)
 
 **When NOT to use OPFS**:
-- Text content already in conversation context (tool results, extracted data, generated articles) — use it directly, do not write to OPFS for later retrieval
+- Text content already in conversation context (tool results, extracted data) — use it directly
 - Temporary data only needed within the current conversation — keep in context
 
-**Critical rule**: \`opfs_read\` returns a **blob URL only** — never text content. The opfs_write → opfs_read pattern does NOT work for text retrieval. If you need text data later, keep it in conversation context.
+**Text file reading**: \`opfs_read\` detects MIME type automatically.
+- Text files (txt, json, js, html, css, xml, etc.) → returns text content directly with line info
+- If text exceeds 200 lines, you **MUST** use \`offset\` and \`limit\` to read in segments
+- Binary files (images, PDFs, etc.) → returns blob URL
 
 **Binary file workflow**:
 **Save**: screenshot with \`saveTo\` / SkillScript \`fetch()\` → \`CAT.agent.opfs.write(blob)\` → returns path

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

@@ -1,9 +1,10 @@
 import { describe, it, expect, beforeEach, vi } from "vitest";
-import { createOPFSTools, sanitizePath, setCreateBlobUrlFn } from "./opfs_tools";
+import { createOPFSTools, sanitizePath, setCreateBlobUrlFn, guessMimeType } from "./opfs_tools";
+import { isText } from "@App/pkg/utils/istextorbinary";
 
 // ---- In-memory OPFS mock ----
 
-type FSNode = { kind: "file"; content: string } | { kind: "directory"; children: Map<string, FSNode> };
+type FSNode = { kind: "file"; content: string | Uint8Array } | { kind: "directory"; children: Map<string, FSNode> };
 
 function createMockFS() {
   const root: FSNode = { kind: "directory", children: new Map() };
@@ -73,16 +74,22 @@ function createMockFS() {
       kind: "file",
       name,
       async getFile() {
-        return new Blob([node.content], { type: "text/plain" });
+        return new Blob([node.content as BlobPart]);
       },
       async createWritable() {
-        let buffer = "";
+        const chunks: (string | Uint8Array)[] = [];
         return {
-          async write(data: string) {
-            buffer += data;
+          async write(data: string | Uint8Array) {
+            chunks.push(data);
           },
           async close() {
-            node.content = buffer;
+            // 合并所有 chunk，如果全是 string 就存 string，否则存 Uint8Array
+            if (chunks.every((c) => typeof c === "string")) {
+              node.content = chunks.join("");
+            } else {
+              const blob = new Blob(chunks as BlobPart[]);
+              node.content = new Uint8Array(await blob.arrayBuffer());
+            }
           },
         };
       },
@@ -129,6 +136,60 @@ describe("sanitizePath", () => {
   });
 });
 
+describe("guessMimeType", () => {
+  it("常见文本扩展名返回正确 MIME", () => {
+    expect(guessMimeType("readme.md")).toBe("text/markdown");
+    expect(guessMimeType("data.csv")).toBe("text/csv");
+    expect(guessMimeType("config.yaml")).toBe("text/yaml");
+    expect(guessMimeType("config.yml")).toBe("text/yaml");
+    expect(guessMimeType("index.html")).toBe("text/html");
+    expect(guessMimeType("index.htm")).toBe("text/html");
+    expect(guessMimeType("style.css")).toBe("text/css");
+    expect(guessMimeType("data.xml")).toBe("text/xml");
+    expect(guessMimeType("data.json")).toBe("application/json");
+    expect(guessMimeType("app.js")).toBe("application/javascript");
+    expect(guessMimeType("lib.mjs")).toBe("application/javascript");
+  });
+
+  it("常见二进制扩展名返回正确 MIME", () => {
+    expect(guessMimeType("photo.png")).toBe("image/png");
+    expect(guessMimeType("photo.jpg")).toBe("image/jpeg");
+    expect(guessMimeType("song.mp3")).toBe("audio/mpeg");
+    expect(guessMimeType("video.mp4")).toBe("video/mp4");
+    expect(guessMimeType("doc.pdf")).toBe("application/pdf");
+    expect(guessMimeType("archive.zip")).toBe("application/zip");
+  });
+
+  it("未知扩展名返回 octet-stream", () => {
+    expect(guessMimeType("data.xyz")).toBe("application/octet-stream");
+    expect(guessMimeType("Makefile")).toBe("application/octet-stream");
+    expect(guessMimeType("file.rar")).toBe("application/octet-stream");
+  });
+});
+
+describe("isText（内容检测）", () => {
+  it("UTF-8 文本内容被识别为文本", () => {
+    const textContent = new TextEncoder().encode("Hello, world!\nThis is a text file.");
+    expect(isText(textContent)).toBe(true);
+  });
+
+  it("中文 UTF-8 文本被识别为文本", () => {
+    const textContent = new TextEncoder().encode("你好，世界！这是一个文本文件。");
+    expect(isText(textContent)).toBe(true);
+  });
+
+  it("含 null 字节的内容被识别为二进制", () => {
+    // isText 检测 charCode <= 8 为二进制（null byte = 0x00）
+    const binaryContent = new Uint8Array([0x00, 0x01, 0x50, 0x4e, 0x47, 0xff, 0xfe, 0x00]);
+    expect(isText(binaryContent)).toBe(false);
+  });
+
+  it("空内容返回 false", () => {
+    expect(isText(null)).toBe(false);
+    expect(isText(undefined)).toBe(false);
+  });
+});
+
 describe("opfs_tools", () => {
   let mockFS: ReturnType<typeof createMockFS>;
 
@@ -139,7 +200,7 @@ describe("opfs_tools", () => {
         getDirectory: vi.fn().mockResolvedValue(mockFS.rootHandle),
       },
     });
-    // opfs_read 总是返回 blobUrl，需要初始化 createBlobUrlFn
+    // opfs_read 读取二进制文件时需要 createBlobUrlFn 生成 blob URL
     setCreateBlobUrlFn(async () => "blob:mock-url");
   });
 
@@ -155,7 +216,7 @@ describe("opfs_tools", () => {
   });
 
   describe("opfs_write + opfs_read", () => {
-    it("should write and read a file", async () => {
+    it("should write and read a text file", async () => {
       const write = getTool("opfs_write");
       const read = getTool("opfs_read");
 
@@ -167,8 +228,8 @@ describe("opfs_tools", () => {
 
       const readResult = JSON.parse((await read.executor.execute({ path: "hello.txt" })) as string);
       expect(readResult.path).toBe("hello.txt");
-      expect(readResult.blobUrl).toBe("blob:mock-url");
-      expect(readResult.size).toBe(6);
+      expect(readResult.type).toBe("text");
+      expect(readResult.content).toBe("Hello!");
     });
 
     it("should create nested directories automatically", async () => {
@@ -177,7 +238,8 @@ describe("opfs_tools", () => {
 
       await write.executor.execute({ path: "a/b/c.txt", content: "deep" });
       const result = JSON.parse((await read.executor.execute({ path: "a/b/c.txt" })) as string);
-      expect(result.blobUrl).toBe("blob:mock-url");
+      expect(result.type).toBe("text");
+      expect(result.content).toBe("deep");
     });
 
     it("should overwrite existing file", async () => {
@@ -187,7 +249,8 @@ describe("opfs_tools", () => {
       await write.executor.execute({ path: "f.txt", content: "v1" });
       await write.executor.execute({ path: "f.txt", content: "v2" });
       const result = JSON.parse((await read.executor.execute({ path: "f.txt" })) as string);
-      expect(result.blobUrl).toBe("blob:mock-url");
+      expect(result.type).toBe("text");
+      expect(result.content).toBe("v2");
     });
 
     it("should strip leading slashes from path", async () => {
@@ -196,7 +259,8 @@ describe("opfs_tools", () => {
 
       await write.executor.execute({ path: "/leading.txt", content: "ok" });
       const result = JSON.parse((await read.executor.execute({ path: "leading.txt" })) as string);
-      expect(result.blobUrl).toBe("blob:mock-url");
+      expect(result.type).toBe("text");
+      expect(result.content).toBe("ok");
     });
 
     it("should reject .. in path", async () => {
@@ -207,6 +271,148 @@ describe("opfs_tools", () => {
     });
   });
 
+  describe("opfs_read 文本读取", () => {
+    it("should return text content for text files", async () => {
+      const write = getTool("opfs_write");
+      const read = getTool("opfs_read");
+
+      await write.executor.execute({ path: "hello.txt", content: "line1\nline2\nline3" });
+      const result = JSON.parse((await read.executor.execute({ path: "hello.txt" })) as string);
+      expect(result.type).toBe("text");
+      expect(result.content).toBe("line1\nline2\nline3");
+      expect(result.totalLines).toBe(3);
+      expect(result.startLine).toBe(1);
+      expect(result.endLine).toBe(3);
+      expect(result.blobUrl).toBeUndefined();
+    });
+
+    it("should return text content for json files", async () => {
+      const write = getTool("opfs_write");
+      const read = getTool("opfs_read");
+
+      await write.executor.execute({ path: "data.json", content: '{"key":"value"}' });
+      const result = JSON.parse((await read.executor.execute({ path: "data.json" })) as string);
+      expect(result.type).toBe("text");
+      expect(result.content).toBe('{"key":"value"}');
+    });
+
+    it("should return blob URL for binary files (png)", async () => {
+      const write = getTool("opfs_write");
+      const read = getTool("opfs_read");
+
+      // 先通过 write 创建文件（建立 workspace 目录结构），再替换为二进制内容
+      await write.executor.execute({ path: "image.png", content: "placeholder" });
+      const wsDir = mockFS.root.children.get("agents") as FSNode & { kind: "directory" };
+      const workspace = wsDir.children.get("workspace") as FSNode & { kind: "directory" };
+      workspace.children.set("image.png", {
+        kind: "file",
+        content: new Uint8Array([0x89, 0x50, 0x00, 0x47, 0x00, 0x0a, 0x00, 0x0a]),
+      });
+
+      const result = JSON.parse((await read.executor.execute({ path: "image.png" })) as string);
+      expect(result.type).toBe("binary");
+      expect(result.blobUrl).toBe("blob:mock-url");
+      expect(result.content).toBeUndefined();
+    });
+
+    it("mode=blob 时文本文件也返回 blob URL", async () => {
+      const write = getTool("opfs_write");
+      const read = getTool("opfs_read");
+
+      await write.executor.execute({ path: "readme.txt", content: "hello" });
+      const result = JSON.parse(
+        (await read.executor.execute({ path: "readme.txt", mode: "blob" })) as string
+      );
+      expect(result.type).toBe("binary");
+      expect(result.blobUrl).toBe("blob:mock-url");
+      expect(result.content).toBeUndefined();
+    });
+
+    it("mode=text 时二进制内容也强制返回文本", async () => {
+      const write = getTool("opfs_write");
+      const read = getTool("opfs_read");
+
+      // 先创建文件，再替换为二进制内容
+      await write.executor.execute({ path: "data.bin", content: "placeholder" });
+      const wsDir = mockFS.root.children.get("agents") as FSNode & { kind: "directory" };
+      const workspace = wsDir.children.get("workspace") as FSNode & { kind: "directory" };
+      workspace.children.set("data.bin", {
+        kind: "file",
+        content: new Uint8Array([0x48, 0x00, 0x65, 0x00, 0x6c, 0x00]),
+      });
+
+      // auto 模式下内容检测为二进制，返回 blob
+      const blobResult = JSON.parse(
+        (await read.executor.execute({ path: "data.bin" })) as string
+      );
+      expect(blobResult.type).toBe("binary");
+
+      // mode=text 强制文本读取
+      const textResult = JSON.parse(
+        (await read.executor.execute({ path: "data.bin", mode: "text" })) as string
+      );
+      expect(textResult.type).toBe("text");
+    });
+
+    it("should support offset and limit for line-based reading", async () => {
+      const write = getTool("opfs_write");
+      const read = getTool("opfs_read");
+
+      const lines = Array.from({ length: 10 }, (_, i) => `line${i + 1}`).join("\n");
+      await write.executor.execute({ path: "multi.txt", content: lines });
+
+      const result = JSON.parse(
+        (await read.executor.execute({ path: "multi.txt", offset: 3, limit: 4 })) as string
+      );
+      expect(result.content).toBe("line3\nline4\nline5\nline6");
+      expect(result.startLine).toBe(3);
+      expect(result.endLine).toBe(6);
+      expect(result.totalLines).toBe(10);
+    });
+
+    it("should error when text file exceeds max lines without offset/limit", async () => {
+      const write = getTool("opfs_write");
+      const read = getTool("opfs_read");
+
+      // 生成 201 行文本
+      const lines = Array.from({ length: 201 }, (_, i) => `line${i + 1}`).join("\n");
+      await write.executor.execute({ path: "big.txt", content: lines });
+
+      await expect(read.executor.execute({ path: "big.txt" })).rejects.toThrow(/201/);
+      await expect(read.executor.execute({ path: "big.txt" })).rejects.toThrow(/offset/);
+    });
+
+    it("should allow reading large file with offset/limit", async () => {
+      const write = getTool("opfs_write");
+      const read = getTool("opfs_read");
+
+      const lines = Array.from({ length: 300 }, (_, i) => `line${i + 1}`).join("\n");
+      await write.executor.execute({ path: "big.txt", content: lines });
+
+      const result = JSON.parse(
+        (await read.executor.execute({ path: "big.txt", offset: 290, limit: 11 })) as string
+      );
+      expect(result.startLine).toBe(290);
+      expect(result.endLine).toBe(300);
+      expect(result.totalLines).toBe(300);
+    });
+
+    it("should clamp offset to valid range", async () => {
+      const write = getTool("opfs_write");
+      const read = getTool("opfs_read");
+
+      await write.executor.execute({ path: "small.txt", content: "a\nb\nc" });
+
+      // offset 超出范围
+      const result = JSON.parse(
+        (await read.executor.execute({ path: "small.txt", offset: 100, limit: 5 })) as string
+      );
+      expect(result.content).toBe("");
+      expect(result.startLine).toBe(100);
+      expect(result.endLine).toBe(3);
+    });
+  });
+
   describe("opfs_read errors", () => {
     it("should throw for non-existent file", async () => {
       const read = getTool("opfs_read");