minimal-agent 0.10.0 → 0.12.0

package/src/tools/read/read.ts

@@ -0,0 +1,558 @@
+import { createReadStream } from 'node:fs';
+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 type { Tool, ToolCallContext, ToolResult } from '../../types.js';
+import { toToolParameters } from '../../utils/zodToJson.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,
+  type FileReadState,
+} from '../shared/fileState.js';
+import {
+  hasBinaryExtension,
+  isBlockedDevicePath,
+  readTextFile,
+  resolveToolPath,
+} from '../shared/fileUtils.js';
+import { filePathField } from '../shared/schemas.js';
+import {
+  pruneRuntimeOutputs,
+  sessionRuntimeDir,
+  type RuntimeIdentity,
+} 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}`),
+  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(),
+});
+type ReadInput = z.infer<typeof inputSchema>;
+
+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;
+
+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, 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 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: unknown): string {
+  if (Array.isArray(value))
+    return value
+      .filter((item): item is string => typeof item === 'string')
+      .join('');
+  return typeof value === 'string' ? value : '';
+}
+
+function renderNotebook(
+  raw: string,
+  offset: number,
+  limit: number,
+): {
+  content: string;
+  total: number;
+  partial: boolean;
+} {
+  const parsed = JSON.parse(raw) as {
+    cells?: unknown[];
+    metadata?: Record<string, unknown>;
+  };
+  if (!Array.isArray(parsed.cells)) throw new Error('Notebook 缺少 cells 数组');
+  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 as Record<string, unknown>)
+        : {};
+    const outputs = Array.isArray(cell.outputs) ? cell.outputs : [];
+    const renderedOutputs = outputs
+      .slice(0, 8)
+      .map((output) => {
+        if (!output || typeof output !== 'object') return String(output ?? '');
+        const item = output as Record<string, unknown>;
+        const text =
+          item.text ??
+          (item.data && typeof item.data === 'object'
+            ? (item.data as Record<string, unknown>)['text/plain']
+            : undefined);
+        return notebookSource(text).slice(0, 2_000);
+      })
+      .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),
+      ...(renderedOutputs ? [`\nOutput:\n${renderedOutputs}`] : []),
+    ].join('\n');
+  });
+  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,
+  };
+}
+
+async function readStreamedText(
+  filePath: string,
+  offset: number,
+  limit: number,
+): Promise<{ numbered: string; totalKnown: number; hasMore: boolean }> {
+  const handle = await open(filePath, 'r');
+  const prefix = Buffer.alloc(3);
+  const { bytesRead } = await handle.read(prefix, 0, 3, 0);
+  await handle.close();
+  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,
+  });
+  const rl = createInterface({ input: stream, crlfDelay: Infinity });
+  const lines: string[] = [];
+  let line = 0;
+  let hasMore = false;
+  for await (const value of rl) {
+    line += 1;
+    if (line >= offset && lines.length < limit) lines.push(`${line}\t${value}`);
+    else if (line >= offset + limit) {
+      hasMore = true;
+      rl.close();
+      stream.destroy();
+      break;
+    }
+  }
+  return { numbered: lines.join('\n'), totalKnown: line, hasMore };
+}
+
+async function call(
+  input: ReadInput,
+  state?: FileReadState,
+  cwd?: string,
+  runtimeIdentity?: RuntimeIdentity,
+): Promise<ToolResult> {
+  const offset = input.offset ?? 1;
+  const limit = input.limit ?? MAX_LINES_TO_READ;
+  const resolved = resolveToolPath(input.file_path, cwd);
+  if (!resolved.ok) return resolved;
+  const filePath = resolved.resolvedPath;
+  if (isBlockedDevicePath(filePath))
+    return { ok: false, error: `不允许读取设备文件：${filePath}` };
+
+  const info = await stat(filePath).catch((error: Error) => ({ error }));
+  if ('error' in info)
+    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');
+      const document = await pdfjs.getDocument({
+        data: new Uint8Array(bytes),
+        useSystemFonts: true,
+      }).promise;
+      try {
+        const requested = parsePdfPages(input.pages, document.numPages);
+        if (requested.length > 20)
+          return { ok: false, error: '一次最多读取 20 个 PDF 页面' };
+        const chunks: string[] = [];
+        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 document.destroy().catch(() => undefined);
+      }
+    } catch (error) {
+      const message = (error as 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} 字节上限` };
+    const bytes = await readFile(filePath);
+    recordRead(filePath, { contentHash: hashFileBytes(bytes) }, state);
+    return {
+      ok: true,
+      content: `已读取图片：${filePath}（${info.size} 字节）。图像已附加供视觉模型检查；非视觉模型只能确认文件元数据，不能解读像素内容。`,
+      metadata: await fileActivityMetadata(
+        filePath,
+        'read',
+        'not_run',
+        'source',
+        cwd,
+      ),
+      visionImages: [{ source: filePath }],
+      visionNote: '这是 Read 工具读取的本地图片，请直接检查图像内容。',
+    };
+  }
+
+  if (ext === '.ipynb') {
+    if (info.size > 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),
+      );
+      let content = rendered.content;
+      let truncated = false;
+      if (content.length > DEFAULT_MAX_RESULT_SIZE_CHARS) {
+        content = `${content.slice(0, DEFAULT_MAX_RESULT_SIZE_CHARS)}\n\n... (Notebook 输出已截断)`;
+        truncated = true;
+      }
+      recordRead(
+        filePath,
+        {
+          offset,
+          limit,
+          partial: rendered.partial,
+          truncated,
+          ...(!rendered.partial && !truncated
+            ? { contentHash: hashFileBytes(snapshot.bytes) }
+            : {}),
+        },
+        state,
+      );
+      return {
+        ok: true,
+        content,
+        metadata: await fileActivityMetadata(
+          filePath,
+          'read',
+          'not_run',
+          'source',
+          cwd,
+        ),
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        error: `Notebook 解析失败：${(error as Error).message}`,
+      };
+    }
+  }
+
+  if (hasBinaryExtension(filePath)) {
+    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 做流式处理。`,
+    };
+  }
+
+  try {
+    let content: string;
+    let totalLines: number;
+    let hasMore: boolean;
+    let completeBytes: Buffer | undefined;
+    if (info.size <= SMALL_TEXT_BYTES) {
+      const snapshot = await readTextFile(filePath);
+      completeBytes = snapshot.bytes;
+      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');
+      totalLines = all.length;
+      hasMore = start + selected.length < all.length;
+    } else {
+      const streamed = await readStreamedText(filePath, offset, limit);
+      content = streamed.numbered;
+      totalLines = streamed.totalKnown;
+      hasMore = streamed.hasMore;
+    }
+    if (!content) content = '<file is empty>';
+    let truncated = false;
+    if (content.length > DEFAULT_MAX_RESULT_SIZE_CHARS) {
+      content = `${content.slice(0, DEFAULT_MAX_RESULT_SIZE_CHARS)}\n\n⚠️ 重要：Read 输出已截断；截断范围外仍有内容。需要整文件覆盖时必须分段完整读取，精确修改可继续使用 Edit。`;
+      truncated = true;
+    }
+    const partial = offset !== 1 || hasMore;
+    if (hasMore)
+      content += `\n\n... (还有更多内容；继续使用 offset=${offset + limit})`;
+    const reads = recordRead(
+      filePath,
+      {
+        offset,
+        limit,
+        partial,
+        truncated,
+        ...(!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,
+      ),
+    };
+  } catch (error) {
+    return { ok: false, error: `读取失败：${(error as Error).message}` };
+  }
+}
+
+async function renderPdfPages(
+  document: Awaited<
+    ReturnType<
+      (typeof import('pdfjs-dist/legacy/build/pdf.mjs'))['getDocument']
+    >
+  >['promise'] extends Promise<infer T>
+    ? T
+    : never,
+  filePath: string,
+  pages: number[],
+  identity?: RuntimeIdentity,
+): Promise<string[]> {
+  const outputDir = join(sessionRuntimeDir(identity ?? {}), 'outputs');
+  const outputPrefix = `pdf_${randomUUID()}`;
+  await mkdir(outputDir, { recursive: true, mode: 0o700 });
+  const images: string[] = [];
+  const dynamicImport = new Function(
+    'specifier',
+    'return import(specifier)',
+  ) as (specifier: string) => Promise<{
+    createCanvas?: (
+      width: number,
+      height: number,
+    ) => {
+      getContext(type: '2d'): unknown;
+      toBuffer(type: 'image/png'): Buffer;
+    };
+  }>;
+  let createCanvas: Awaited<ReturnType<typeof dynamicImport>>['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({
+          canvasContext: canvas.getContext('2d') as never,
+          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: string | undefined, total: number): number[] {
+  if (!spec)
+    return Array.from({ length: Math.min(total, 20) }, (_, index) => index + 1);
+  const pages = new Set<number>();
+  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: Tool<ReadInput> = {
+  name: 'Read',
+  description,
+  inputSchema,
+  parameters: toToolParameters(inputSchema),
+  isReadOnly: true,
+  isConcurrencySafe: true,
+  maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+  interruptBehavior: () => 'cancel',
+  call: (input) => call(input),
+  callWithContext: (input, _signal, context: ToolCallContext) =>
+    call(input, context.sessionState?.fileReads, context.cwd, context),
+};

package/src/tools/shared/diffSummary.js

@@ -0,0 +1,44 @@
+import { createHash } from 'node:crypto';
+import { createTwoFilesPatch, diffLines } from 'diff';
+const MAX_BYTES = 5 * 1024 * 1024;
+const MAX_LINES = 200_000;
+const MAX_DIFF_CHARS = 16_000;
+function hash(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+export function buildPatchSummary(before, after, label) {
+    const beforeHash = hash(before);
+    const afterHash = hash(after);
+    const totalBytes = Buffer.byteLength(before) + Buffer.byteLength(after);
+    const totalLines = (before.match(/\n/g)?.length ?? 0) + (after.match(/\n/g)?.length ?? 0) + 2;
+    if (totalBytes > MAX_BYTES || totalLines > MAX_LINES) {
+        return {
+            beforeHash,
+            afterHash,
+            additions: 0,
+            deletions: 0,
+            truncated: true,
+            omittedReason: 'too_large',
+        };
+    }
+    const changes = diffLines(before, after);
+    const additions = changes
+        .filter((change) => change.added)
+        .reduce((sum, change) => sum + (change.count ?? 0), 0);
+    const deletions = changes
+        .filter((change) => change.removed)
+        .reduce((sum, change) => sum + (change.count ?? 0), 0);
+    let unifiedDiff = createTwoFilesPatch(`a/${label}`, `b/${label}`, before, after, undefined, undefined, { context: 3 });
+    const truncated = unifiedDiff.length > MAX_DIFF_CHARS;
+    if (truncated) {
+        unifiedDiff = `${unifiedDiff.slice(0, MAX_DIFF_CHARS)}\n... (diff preview truncated)`;
+    }
+    return {
+        unifiedDiff,
+        beforeHash,
+        afterHash,
+        additions,
+        deletions,
+        truncated,
+    };
+}

package/src/tools/shared/diffSummary.ts

@@ -0,0 +1,63 @@
+import { createHash } from 'node:crypto';
+import { createTwoFilesPatch, diffLines } from 'diff';
+
+import type { FilePatchSummary } from '../../types.js';
+
+const MAX_BYTES = 5 * 1024 * 1024;
+const MAX_LINES = 200_000;
+const MAX_DIFF_CHARS = 16_000;
+
+function hash(value: string): string {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+export function buildPatchSummary(
+  before: string,
+  after: string,
+  label: string,
+): FilePatchSummary {
+  const beforeHash = hash(before);
+  const afterHash = hash(after);
+  const totalBytes = Buffer.byteLength(before) + Buffer.byteLength(after);
+  const totalLines =
+    (before.match(/\n/g)?.length ?? 0) + (after.match(/\n/g)?.length ?? 0) + 2;
+  if (totalBytes > MAX_BYTES || totalLines > MAX_LINES) {
+    return {
+      beforeHash,
+      afterHash,
+      additions: 0,
+      deletions: 0,
+      truncated: true,
+      omittedReason: 'too_large',
+    };
+  }
+
+  const changes = diffLines(before, after);
+  const additions = changes
+    .filter((change) => change.added)
+    .reduce((sum, change) => sum + (change.count ?? 0), 0);
+  const deletions = changes
+    .filter((change) => change.removed)
+    .reduce((sum, change) => sum + (change.count ?? 0), 0);
+  let unifiedDiff = createTwoFilesPatch(
+    `a/${label}`,
+    `b/${label}`,
+    before,
+    after,
+    undefined,
+    undefined,
+    { context: 3 },
+  );
+  const truncated = unifiedDiff.length > MAX_DIFF_CHARS;
+  if (truncated) {
+    unifiedDiff = `${unifiedDiff.slice(0, MAX_DIFF_CHARS)}\n... (diff preview truncated)`;
+  }
+  return {
+    unifiedDiff,
+    beforeHash,
+    afterHash,
+    additions,
+    deletions,
+    truncated,
+  };
+}