minimal-agent 0.11.0 → 0.13.0

package/src/tools/read/read.js

@@ -1,20 +1,52 @@
 import { createReadStream } from 'node:fs';
-import { open, readFile, stat } from 'node:fs/promises';
+import { open, readFile, stat, writeFile } from 'node:fs/promises';
 import { extname } from 'node:path';
 import { createInterface } from 'node:readline';
+import { execFile } from 'node:child_process';
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
 import { toToolParameters } from '../../utils/zodToJson.js';
-import { DEFAULT_MAX_RESULT_SIZE_CHARS, MAX_FILE_SIZE_BYTES, MAX_LINES_TO_READ } from '../types.js';
+import { DEFAULT_MAX_RESULT_SIZE_CHARS, MAX_FILE_SIZE_BYTES, MAX_LINES_TO_READ, } from '../types.js';
 import { fileActivityMetadata } from '../shared/fileActivity.js';
-import { hashFileBytes, recordRead } from '../shared/fileState.js';
+import { hashFileBytes, recordRead, } from '../shared/fileState.js';
 import { hasBinaryExtension, isBlockedDevicePath, readTextFile, resolveToolPath, } from '../shared/fileUtils.js';
 import { filePathField } from '../shared/schemas.js';
+import { pruneRuntimeOutputs, sessionRuntimeDir, } from '../../session/runtimeStore.js';
 const inputSchema = z.object({
     file_path: filePathField('读取'),
-    offset: z.number().int().positive().optional().describe('文本文件为 1-indexed 起始行；Jupyter Notebook 为 1-indexed 起始 cell'),
-    limit: z.number().int().positive().optional().describe(`最多读取的文本行或 Notebook cells；默认 ${MAX_LINES_TO_READ}`),
+    offset: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('文本文件为 1-indexed 起始行；Jupyter Notebook 为 1-indexed 起始 cell'),
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe(`最多读取的文本行或 Notebook cells；默认 ${MAX_LINES_TO_READ}`),
+    pages: z
+        .string()
+        .regex(/^\d+(?:-\d+)?(?:,\d+(?:-\d+)?)*$/)
+        .optional()
+        .describe('PDF 页码，例如 "1-5,8"；每次最多 20 页'),
+    pdf_mode: z
+        .enum(['auto', 'text', 'visual', 'both'])
+        .default('auto')
+        .optional(),
 });
-const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp']);
+const IMAGE_EXTENSIONS = new Set([
+    '.png',
+    '.jpg',
+    '.jpeg',
+    '.gif',
+    '.webp',
+    '.bmp',
+]);
 const MAX_IMAGE_BYTES = 25 * 1024 * 1024;
 const MAX_NOTEBOOK_BYTES = 32 * 1024 * 1024;
 const SMALL_TEXT_BYTES = 16 * 1024 * 1024;
@@ -23,13 +55,15 @@ const description = `Reads local text files, images, and Jupyter notebooks.
 Usage:
 - Relative paths resolve against the current working directory.
 - Text results use 1-based line numbers. Use offset/limit for targeted ranges.
-- PNG, JPEG, WebP, GIF, BMP, and TIFF files are attached for visual inspection.
+- PNG, JPEG, WebP, GIF, and BMP files are attached for visual inspection.
 - For .ipynb files, offset/limit select cells; results include cell id, type, source, and bounded outputs.
-- PDF and office files are not decoded by this tool. Use the matching project Skill for those formats.
+- PDF supports page-selected text extraction and optional visual page rendering; office files use the matching project Skill.
 - This tool reads files, not directories; use Glob for directory discovery.`;
 function notebookSource(value) {
     if (Array.isArray(value))
-        return value.filter((item) => typeof item === 'string').join('');
+        return value
+            .filter((item) => typeof item === 'string')
+            .join('');
     return typeof value === 'string' ? value : '';
 }
 function renderNotebook(raw, offset, limit) {
@@ -39,17 +73,24 @@ function renderNotebook(raw, offset, limit) {
     const start = offset - 1;
     const cells = parsed.cells.slice(start, start + limit);
     const parts = cells.map((value, index) => {
-        const cell = value && typeof value === 'object' ? value : {};
+        const cell = value && typeof value === 'object'
+            ? value
+            : {};
         const outputs = Array.isArray(cell.outputs) ? cell.outputs : [];
-        const renderedOutputs = outputs.slice(0, 8).map((output) => {
+        const renderedOutputs = outputs
+            .slice(0, 8)
+            .map((output) => {
             if (!output || typeof output !== 'object')
                 return String(output ?? '');
             const item = output;
-            const text = item.text ?? (item.data && typeof item.data === 'object'
-                ? item.data['text/plain']
-                : undefined);
+            const text = item.text ??
+                (item.data && typeof item.data === 'object'
+                    ? item.data['text/plain']
+                    : undefined);
             return notebookSource(text).slice(0, 2_000);
-        }).filter(Boolean).join('\n');
+        })
+            .filter(Boolean)
+            .join('\n');
         return [
             `## Cell ${start + index + 1} [selector=cell-${start + index + 1}${typeof cell.id === 'string' ? `; id=${cell.id}` : ''}; type=${String(cell.cell_type ?? 'unknown')}]`,
             notebookSource(cell.source),
@@ -59,7 +100,11 @@ function renderNotebook(raw, offset, limit) {
     const end = start + cells.length;
     if (end < parsed.cells.length)
         parts.push(`... (${parsed.cells.length - end} cells remain; continue with offset=${end + 1})`);
-    return { content: parts.join('\n\n'), total: parsed.cells.length, partial: start > 0 || end < parsed.cells.length };
+    return {
+        content: parts.join('\n\n'),
+        total: parsed.cells.length,
+        partial: start > 0 || end < parsed.cells.length,
+    };
 }
 async function readStreamedText(filePath, offset, limit) {
     const handle = await open(filePath, 'r');
@@ -69,7 +114,14 @@ async function readStreamedText(filePath, offset, limit) {
     const utf16 = bytesRead >= 2 && prefix[0] === 0xff && prefix[1] === 0xfe;
     const stream = createReadStream(filePath, {
         encoding: utf16 ? 'utf16le' : 'utf8',
-        start: utf16 ? 2 : bytesRead >= 3 && prefix[0] === 0xef && prefix[1] === 0xbb && prefix[2] === 0xbf ? 3 : 0,
+        start: utf16
+            ? 2
+            : bytesRead >= 3 &&
+                prefix[0] === 0xef &&
+                prefix[1] === 0xbb &&
+                prefix[2] === 0xbf
+                ? 3
+                : 0,
     });
     const rl = createInterface({ input: stream, crlfDelay: Infinity });
     const lines = [];
@@ -88,7 +140,7 @@ async function readStreamedText(filePath, offset, limit) {
     }
     return { numbered: lines.join('\n'), totalKnown: line, hasMore };
 }
-async function call(input, state, cwd) {
+async function call(input, state, cwd, runtimeIdentity) {
     const offset = input.offset ?? 1;
     const limit = input.limit ?? MAX_LINES_TO_READ;
     const resolved = resolveToolPath(input.file_path, cwd);
@@ -99,10 +151,80 @@ async function call(input, state, cwd) {
         return { ok: false, error: `不允许读取设备文件：${filePath}` };
     const info = await stat(filePath).catch((error) => ({ error }));
     if ('error' in info)
-        return { ok: false, error: `文件不存在或无法读取：${filePath}（${info.error.message}）` };
+        return {
+            ok: false,
+            error: `文件不存在或无法读取：${filePath}（${info.error.message}）`,
+        };
     if (!info.isFile())
         return { ok: false, error: `${filePath} 不是文件；目录请用 Glob。` };
     const ext = extname(filePath).toLowerCase();
+    if (ext === '.pdf') {
+        try {
+            const bytes = await readFile(filePath);
+            if (bytes.subarray(0, 5).toString() !== '%PDF-') {
+                return {
+                    ok: false,
+                    error: '文件扩展名是 PDF，但缺少有效 %PDF- 文件头',
+                };
+            }
+            const pdfjs = await import('pdfjs-dist/legacy/build/pdf.mjs');
+            // ⚠️ 释放要调**加载任务**的 destroy，不是文档代理的：pdfjs v6 的
+            // PDFDocumentProxy 上没有 destroy（只有 cleanup），写成 document.destroy()
+            // 会在 finally 里抛 TypeError，被外层 catch 成「PDF 解析失败」——
+            // 于是每一次 PDF 读取都失败，且错误文案完全指不向真因。
+            const loadingTask = pdfjs.getDocument({
+                data: new Uint8Array(bytes),
+                useSystemFonts: true,
+            });
+            const document = await loadingTask.promise;
+            try {
+                const requested = parsePdfPages(input.pages, document.numPages);
+                if (requested.length > 20)
+                    return { ok: false, error: '一次最多读取 20 个 PDF 页面' };
+                const chunks = [];
+                for (const pageNumber of requested) {
+                    const page = await document.getPage(pageNumber);
+                    const text = await page.getTextContent();
+                    chunks.push(`## Page ${pageNumber}\n${text.items
+                        .map((item) => 'str' in item && typeof item.str === 'string' ? item.str : '')
+                        .filter(Boolean)
+                        .join(' ')}`);
+                }
+                const mode = input.pdf_mode ?? 'auto';
+                const sparse = chunks.join('').replace(/\s/g, '').length < requested.length * 80;
+                const wantVisual = mode === 'visual' || mode === 'both' || (mode === 'auto' && sparse);
+                const images = wantVisual
+                    ? await renderPdfPages(document, filePath, requested.slice(0, 10), runtimeIdentity)
+                    : [];
+                recordRead(filePath, { contentHash: hashFileBytes(bytes) }, state);
+                const rawText = mode === 'visual' ? '[visual-only mode]' : chunks.join('\n\n');
+                const text = rawText.length > DEFAULT_MAX_RESULT_SIZE_CHARS
+                    ? `${rawText.slice(0, DEFAULT_MAX_RESULT_SIZE_CHARS)}\n... (PDF 文本输出已截断；请缩小 pages 范围继续读取)`
+                    : rawText;
+                return {
+                    ok: true,
+                    content: `PDF ${document.numPages} pages; selected ${requested.join(', ')}.\n\n${text}${wantVisual && !images.length ? '\n\n视觉渲染不可用（Canvas 与 pdftoppm 均不可用）；文本提取结果仍可用。' : ''}`,
+                    metadata: await fileActivityMetadata(filePath, 'read', 'not_run', 'source', cwd),
+                    ...(images.length
+                        ? {
+                            visionImages: images.map((source) => ({ source })),
+                            visionNote: '这是所选 PDF 页面的视觉渲染，请检查版式、图表和扫描内容。',
+                        }
+                        : {}),
+                };
+            }
+            finally {
+                await loadingTask.destroy().catch(() => undefined);
+            }
+        }
+        catch (error) {
+            const message = error.message;
+            return {
+                ok: false,
+                error: `PDF 解析失败${/password/i.test(message) ? '（文件可能已加密）' : ''}：${message}`,
+            };
+        }
+    }
     if (IMAGE_EXTENSIONS.has(ext)) {
         if (info.size > MAX_IMAGE_BYTES)
             return { ok: false, error: `图片超过 ${MAX_IMAGE_BYTES} 字节上限` };
@@ -118,7 +240,10 @@ async function call(input, state, cwd) {
     }
     if (ext === '.ipynb') {
         if (info.size > MAX_NOTEBOOK_BYTES)
-            return { ok: false, error: `Notebook 超过 ${MAX_NOTEBOOK_BYTES} 字节上限` };
+            return {
+                ok: false,
+                error: `Notebook 超过 ${MAX_NOTEBOOK_BYTES} 字节上限`,
+            };
         try {
             const snapshot = await readTextFile(filePath);
             const rendered = renderNotebook(snapshot.content, offset, Math.min(limit, 200));
@@ -133,19 +258,34 @@ async function call(input, state, cwd) {
                 limit,
                 partial: rendered.partial,
                 truncated,
-                ...(!rendered.partial && !truncated ? { contentHash: hashFileBytes(snapshot.bytes) } : {}),
+                ...(!rendered.partial && !truncated
+                    ? { contentHash: hashFileBytes(snapshot.bytes) }
+                    : {}),
             }, state);
-            return { ok: true, content, metadata: await fileActivityMetadata(filePath, 'read', 'not_run', 'source', cwd) };
+            return {
+                ok: true,
+                content,
+                metadata: await fileActivityMetadata(filePath, 'read', 'not_run', 'source', cwd),
+            };
         }
         catch (error) {
-            return { ok: false, error: `Notebook 解析失败：${error.message}` };
+            return {
+                ok: false,
+                error: `Notebook 解析失败：${error.message}`,
+            };
         }
     }
     if (hasBinaryExtension(filePath)) {
-        return { ok: false, error: `不支持直接读取 ${ext || '该二进制格式'}；PDF/Office 文件请使用对应 Skill。` };
+        return {
+            ok: false,
+            error: `不支持直接读取 ${ext || '该二进制格式'}；PDF/Office 文件请使用对应 Skill。`,
+        };
     }
     if (info.size > MAX_FILE_SIZE_BYTES) {
-        return { ok: false, error: `文件超过 ${MAX_FILE_SIZE_BYTES} 字节硬上限。请用 Grep 定位，或用 Bash 做流式处理。` };
+        return {
+            ok: false,
+            error: `文件超过 ${MAX_FILE_SIZE_BYTES} 字节硬上限。请用 Grep 定位，或用 Bash 做流式处理。`,
+        };
     }
     try {
         let content;
@@ -158,7 +298,9 @@ async function call(input, state, cwd) {
             const all = snapshot.content.length === 0 ? [] : snapshot.content.split('\n');
             const start = offset - 1;
             const selected = all.slice(start, start + limit);
-            content = selected.map((line, index) => `${start + index + 1}\t${line}`).join('\n');
+            content = selected
+                .map((line, index) => `${start + index + 1}\t${line}`)
+                .join('\n');
             totalLines = all.length;
             hasMore = start + selected.length < all.length;
         }
@@ -183,19 +325,97 @@ async function call(input, state, cwd) {
             limit,
             partial,
             truncated,
-            ...(!partial && !truncated && completeBytes ? { contentHash: hashFileBytes(completeBytes) } : {}),
+            ...(!partial && !truncated && completeBytes
+                ? { contentHash: hashFileBytes(completeBytes) }
+                : {}),
         }, state);
         if (info.size > 100 * 1024 && offset === 1) {
             content = `⚠️ 大文件：结果受行数和输出字符上限约束，请按需分段读取。\n\n${content}`;
         }
         if (reads >= 2)
             content = `⚠️ 重复读取空转：该区间未变化，前一次 Read 结果仍然有效。\n\n${content}`;
-        return { ok: true, content, metadata: await fileActivityMetadata(filePath, 'read', 'not_run', 'source', cwd) };
+        return {
+            ok: true,
+            content,
+            metadata: await fileActivityMetadata(filePath, 'read', 'not_run', 'source', cwd),
+        };
     }
     catch (error) {
         return { ok: false, error: `读取失败：${error.message}` };
     }
 }
+async function renderPdfPages(document, filePath, pages, identity) {
+    const outputDir = join(sessionRuntimeDir(identity ?? {}), 'outputs');
+    const outputPrefix = `pdf_${randomUUID()}`;
+    await mkdir(outputDir, { recursive: true, mode: 0o700 });
+    const images = [];
+    const dynamicImport = new Function('specifier', 'return import(specifier)');
+    let createCanvas;
+    try {
+        ({ createCanvas } = await dynamicImport('@napi-rs/canvas'));
+    }
+    catch {
+        /* optional adapter */
+    }
+    if (createCanvas) {
+        try {
+            for (const pageNumber of pages) {
+                const page = await document.getPage(pageNumber);
+                const viewport = page.getViewport({ scale: 2 });
+                const canvas = createCanvas(Math.ceil(viewport.width), Math.ceil(viewport.height));
+                await page.render({
+                    canvas: canvas.getContext('2d'),
+                    viewport,
+                }).promise;
+                const target = join(outputDir, `${outputPrefix}-page-${pageNumber}.png`);
+                await writeFile(target, canvas.toBuffer('image/png'), { mode: 0o600 });
+                images.push(target);
+            }
+            void pruneRuntimeOutputs();
+            return images;
+        }
+        catch {
+            images.length = 0;
+        }
+    }
+    for (const pageNumber of pages) {
+        const prefix = join(outputDir, `${outputPrefix}-page-${pageNumber}`);
+        try {
+            await promisify(execFile)('pdftoppm', [
+                '-f',
+                String(pageNumber),
+                '-l',
+                String(pageNumber),
+                '-singlefile',
+                '-png',
+                '-r',
+                '144',
+                filePath,
+                prefix,
+            ], { maxBuffer: 1024 * 1024 });
+            images.push(`${prefix}.png`);
+        }
+        catch {
+            break;
+        }
+    }
+    void pruneRuntimeOutputs();
+    return images;
+}
+function parsePdfPages(spec, total) {
+    if (!spec)
+        return Array.from({ length: Math.min(total, 20) }, (_, index) => index + 1);
+    const pages = new Set();
+    for (const part of spec.split(',')) {
+        const [first, last] = part.split('-').map(Number);
+        for (let page = first; page <= (last ?? first); page += 1) {
+            if (page < 1 || page > total)
+                throw new Error(`PDF 页码超出范围：${page}（共 ${total} 页）`);
+            pages.add(page);
+        }
+    }
+    return [...pages].sort((left, right) => left - right);
+}
 export const readTool = {
     name: 'Read',
     description,
@@ -206,5 +426,5 @@ export const readTool = {
     maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
     interruptBehavior: () => 'cancel',
     call: (input) => call(input),
-    callWithContext: (input, _signal, context) => call(input, context.sessionState?.fileReads, context.cwd),
+    callWithContext: (input, _signal, context) => call(input, context.sessionState?.fileReads, context.cwd, context),
 };