@downcity/agent 1.1.287 → 1.1.310

package/src/workspace/file/FileActionRuntime.ts

@@ -0,0 +1,433 @@
+/**
+ * 文件 action 运行时。
+ *
+ * 关键点（中文）
+ * - 三个 action 共用项目根目录校验、编码识别和结构化错误协议。
+ * - write/edit 都通过同目录临时文件实现原子替换。
+ * - edit 的全部匹配基于原始文件，并从后向前一次应用。
+ */
+
+import { lstat, mkdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import type {
+  EditFileToolInput,
+  EditFileToolResult,
+  FileEditDetail,
+  FileToolActionRequest,
+  FileToolActionResult,
+  ReadFileToolInput,
+  ReadFileToolResult,
+  WriteFileToolInput,
+  WriteFileToolResult,
+} from "@/types/workspace/FileTool.js";
+import { resolve_file_tool_path } from "@/workspace/file/FilePathPolicy.js";
+import { FileToolRuntimeError, to_file_tool_failure } from "@/workspace/file/FileToolError.js";
+import {
+  count_text_lines,
+  create_file_sha256,
+  decode_text_file,
+  detect_file_mime_type,
+  detect_image_file_mime_type,
+  encode_text_file,
+  is_binary_file,
+  normalize_text_to_lf,
+} from "@/workspace/file/FileEncoding.js";
+import { write_file_atomically } from "@/workspace/file/FileAtomicWriter.js";
+
+const DEFAULT_READ_LINES = 500;
+const MAX_READ_LINES = 2_000;
+const MAX_READ_OUTPUT_BYTES = 256 * 1024;
+const MAX_FILE_BYTES = 64 * 1024 * 1024;
+const MAX_WRITE_BYTES = 1024 * 1024;
+const MAX_EDITS = 10;
+const MAX_OLD_TEXT_CHARS = 10_000;
+const MAX_NEW_TEXT_CHARS = 50_000;
+
+/** 判断文件是否存在。 */
+async function file_exists(file_path: string): Promise<boolean> {
+  try {
+    await lstat(file_path);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+/** 在内存读取前限制单文件大小。 */
+async function read_limited_file(file_path: string): Promise<Buffer> {
+  const metadata = await lstat(file_path);
+  if (metadata.size > MAX_FILE_BYTES) {
+    throw new FileToolRuntimeError({
+      error_code: "file_too_large",
+      message: `File exceeds ${MAX_FILE_BYTES} byte processing limit: ${file_path}`,
+      file_path,
+    });
+  }
+  return await readFile(file_path);
+}
+
+/** 把文本拆为稳定的逻辑行。 */
+function split_text_lines(content: string): string[] {
+  if (content.length === 0) return [];
+  const normalized = normalize_text_to_lf(content);
+  const lines = normalized.split("\n");
+  if (normalized.endsWith("\n")) lines.pop();
+  return lines;
+}
+
+/** 执行文件读取。 */
+async function read_file_action(
+  context: { readonly rootPath: string },
+  input: ReadFileToolInput,
+): Promise<ReadFileToolResult> {
+  let file_path = "";
+  try {
+    const resolved = await resolve_file_tool_path({
+      root_path: context.rootPath,
+      file_path: input.file_path,
+      allow_missing: false,
+    });
+    file_path = resolved.file_path;
+    const buffer = await read_limited_file(file_path);
+    const total_bytes = buffer.byteLength;
+    const sha256 = create_file_sha256(buffer);
+    const image_mime_type = detect_image_file_mime_type(buffer);
+    if (image_mime_type) {
+      return {
+        success: true,
+        file_path,
+        total_bytes,
+        total_lines: 0,
+        start_line: 0,
+        end_line: -1,
+        content: "",
+        truncated: false,
+        type: "image",
+        mime_type: image_mime_type,
+        sha256,
+      };
+    }
+    const mime_type = detect_file_mime_type(file_path);
+    if (is_binary_file(buffer)) {
+      return {
+        success: true,
+        file_path,
+        total_bytes,
+        total_lines: 0,
+        start_line: 0,
+        end_line: -1,
+        content: "",
+        truncated: false,
+        type: "binary",
+        ...(mime_type ? { mime_type } : {}),
+        sha256,
+      };
+    }
+
+    const decoded = decode_text_file(buffer);
+    const lines = split_text_lines(decoded.content);
+    const total_lines = lines.length;
+    const offset = Math.max(0, Math.floor(input.offset ?? 0));
+    const limit = Math.min(
+      MAX_READ_LINES,
+      Math.max(1, Math.floor(input.limit ?? DEFAULT_READ_LINES)),
+    );
+    const selected_lines: string[] = [];
+    let output_bytes = 0;
+    const requested_end = Math.min(total_lines, offset + limit);
+    for (let index = offset; index < requested_end; index += 1) {
+      const line = lines[index] ?? "";
+      const separator_bytes = selected_lines.length > 0 ? 1 : 0;
+      const line_bytes = Buffer.byteLength(line, "utf8") + separator_bytes;
+      if (selected_lines.length === 0 && line_bytes > MAX_READ_OUTPUT_BYTES) {
+        throw new FileToolRuntimeError({
+          error_code: "line_too_large",
+          message: `Line ${index} exceeds the ${MAX_READ_OUTPUT_BYTES} byte read limit`,
+          file_path,
+        });
+      }
+      if (output_bytes + line_bytes > MAX_READ_OUTPUT_BYTES) break;
+      selected_lines.push(line);
+      output_bytes += line_bytes;
+    }
+
+    const start_line = offset;
+    const end_line = selected_lines.length > 0
+      ? offset + selected_lines.length - 1
+      : offset - 1;
+    const truncated = end_line + 1 < total_lines;
+    return {
+      success: true,
+      file_path,
+      total_bytes,
+      total_lines,
+      start_line,
+      end_line,
+      content: selected_lines.join("\n"),
+      truncated,
+      ...(truncated ? { next_offset: end_line + 1 } : {}),
+      type: "text",
+      ...(mime_type ? { mime_type } : {}),
+      encoding: decoded.encoding,
+      sha256,
+    };
+  } catch (error) {
+    return to_file_tool_failure(error, file_path || undefined);
+  }
+}
+
+/** 执行文件写入。 */
+async function write_file_action(
+  context: { readonly rootPath: string },
+  input: WriteFileToolInput,
+): Promise<WriteFileToolResult> {
+  let file_path = "";
+  try {
+    const resolved = await resolve_file_tool_path({
+      root_path: context.rootPath,
+      file_path: input.file_path,
+      allow_missing: true,
+    });
+    file_path = resolved.file_path;
+    const normalized_content = normalize_text_to_lf(input.content);
+    const content = Buffer.from(normalized_content, "utf8");
+    if (content.byteLength > MAX_WRITE_BYTES) {
+      throw new FileToolRuntimeError({
+        error_code: "content_too_large",
+        message: `Write content exceeds ${MAX_WRITE_BYTES} bytes`,
+        file_path,
+      });
+    }
+    const existed = await file_exists(file_path);
+    if (existed && input.overwrite !== true) {
+      throw new FileToolRuntimeError({
+        error_code: "file_exists",
+        message: `File already exists; pass overwrite=true to replace it: ${file_path}`,
+        file_path,
+      });
+    }
+    const mode = existed ? (await lstat(file_path)).mode & 0o7777 : undefined;
+    await mkdir(path.dirname(file_path), { recursive: true });
+    await write_file_atomically({
+      file_path,
+      content,
+      overwrite: existed,
+      ...(typeof mode === "number" ? { mode } : {}),
+    });
+    return {
+      success: true,
+      file_path,
+      bytes_written: content.byteLength,
+      lines_written: count_text_lines(normalized_content),
+      overwritten: existed,
+      timestamp: new Date().toISOString(),
+      sha256: create_file_sha256(content),
+    };
+  } catch (error) {
+    return to_file_tool_failure(error, file_path || undefined);
+  }
+}
+
+/** 返回字面量在文本中的全部起始位置，包含潜在重叠匹配。 */
+function find_literal_matches(content: string, target: string): number[] {
+  const matches: number[] = [];
+  let cursor = 0;
+  while (cursor <= content.length - target.length) {
+    const position = content.indexOf(target, cursor);
+    if (position < 0) break;
+    matches.push(position);
+    cursor = position + 1;
+  }
+  return matches;
+}
+
+/** 识别原文件使用的主要换行符。 */
+function detect_text_eol(content: string): "\n" | "\r\n" | "\r" {
+  if (content.includes("\r\n")) return "\r\n";
+  if (content.includes("\r")) return "\r";
+  return "\n";
+}
+
+/** 把编辑文本适配为原文件的主要换行符。 */
+function normalize_edit_eol(content: string, eol: "\n" | "\r\n" | "\r"): string {
+  return normalize_text_to_lf(content).replace(/\n/g, eol);
+}
+
+/** 计算字符位置对应的 0-based 行号。 */
+function resolve_line_number(content: string, position: number): number {
+  return count_text_lines(content.slice(0, position));
+}
+
+/** 执行文件精确编辑。 */
+async function edit_file_action(
+  context: { readonly rootPath: string },
+  input: EditFileToolInput,
+): Promise<EditFileToolResult> {
+  let file_path = "";
+  try {
+    const resolved = await resolve_file_tool_path({
+      root_path: context.rootPath,
+      file_path: input.file_path,
+      allow_missing: false,
+    });
+    file_path = resolved.file_path;
+    if (!Array.isArray(input.edits) || input.edits.length === 0) {
+      throw new FileToolRuntimeError({
+        error_code: "no_edits",
+        message: "edits must contain at least one operation",
+        file_path,
+      });
+    }
+    if (input.edits.length > MAX_EDITS) {
+      throw new FileToolRuntimeError({
+        error_code: "too_many_edits",
+        message: `A single edit call supports at most ${MAX_EDITS} operations`,
+        file_path,
+      });
+    }
+    for (const edit of input.edits) {
+      if (
+        edit.old_text.length === 0 ||
+        edit.old_text.length > MAX_OLD_TEXT_CHARS ||
+        edit.new_text.length > MAX_NEW_TEXT_CHARS
+      ) {
+        throw new FileToolRuntimeError({
+          error_code: "edit_too_large",
+          message: `Each old_text must contain 1-${MAX_OLD_TEXT_CHARS} characters and new_text at most ${MAX_NEW_TEXT_CHARS} characters`,
+          file_path,
+        });
+      }
+    }
+
+    const buffer = await read_limited_file(file_path);
+    if (is_binary_file(buffer)) {
+      throw new FileToolRuntimeError({
+        error_code: "binary_file",
+        message: `Cannot edit a binary file: ${file_path}`,
+        file_path,
+      });
+    }
+    const previous_sha256 = create_file_sha256(buffer);
+    const expected_sha256 = String(input.expected_sha256 || "").trim().toLowerCase();
+    if (expected_sha256 && expected_sha256 !== previous_sha256) {
+      throw new FileToolRuntimeError({
+        error_code: "file_changed",
+        message: `File changed since it was read: ${file_path}`,
+        file_path,
+      });
+    }
+
+    const decoded = decode_text_file(buffer);
+    const original_content = decoded.content;
+    const eol = detect_text_eol(original_content);
+    const matches = input.edits.map((edit, index) => {
+      const old_text = normalize_edit_eol(edit.old_text, eol);
+      const new_text = normalize_edit_eol(edit.new_text, eol);
+      const positions = find_literal_matches(original_content, old_text);
+      const detail: FileEditDetail = {
+        index,
+        status:
+          positions.length === 0
+            ? "not_found"
+            : positions.length > 1
+              ? "duplicate"
+              : "applied",
+        match_count: positions.length,
+        ...(positions.length === 1
+          ? { line_start: resolve_line_number(original_content, positions[0]) }
+          : {}),
+      };
+      return {
+        index,
+        old_text,
+        new_text,
+        start: positions[0] ?? -1,
+        end: positions.length === 1 ? positions[0] + old_text.length : -1,
+        detail,
+      };
+    });
+    const invalid_match = matches.find((item) => item.detail.status !== "applied");
+    if (invalid_match) {
+      throw new FileToolRuntimeError({
+        error_code:
+          invalid_match.detail.status === "duplicate"
+            ? "duplicate_match"
+            : "not_found",
+        message:
+          invalid_match.detail.status === "duplicate"
+            ? `edits[${invalid_match.index}].old_text matched ${invalid_match.detail.match_count} times`
+            : `edits[${invalid_match.index}].old_text was not found`,
+        file_path,
+        details: matches.map((item) => item.detail),
+      });
+    }
+
+    const sorted_matches = [...matches].sort((left, right) => left.start - right.start);
+    for (let index = 0; index < sorted_matches.length - 1; index += 1) {
+      if (sorted_matches[index].end > sorted_matches[index + 1].start) {
+        throw new FileToolRuntimeError({
+          error_code: "overlapping_edits",
+          message: "Edit regions overlap; merge nearby changes into one edit",
+          file_path,
+          details: matches.map((item) => item.detail),
+        });
+      }
+    }
+
+    let next_content = original_content;
+    for (const match of [...sorted_matches].reverse()) {
+      next_content =
+        next_content.slice(0, match.start) +
+        match.new_text +
+        next_content.slice(match.end);
+    }
+    const next_buffer = encode_text_file(next_content, decoded.encoding);
+    if (next_buffer.byteLength > MAX_FILE_BYTES) {
+      throw new FileToolRuntimeError({
+        error_code: "content_too_large",
+        message: `Edited file exceeds ${MAX_FILE_BYTES} bytes`,
+        file_path,
+      });
+    }
+    const mode = (await lstat(file_path)).mode & 0o7777;
+    await write_file_atomically({
+      file_path,
+      content: next_buffer,
+      overwrite: true,
+      mode,
+    });
+    return {
+      success: true,
+      file_path,
+      applied: matches.length,
+      details: matches.map((item) => item.detail),
+      new_total_lines: count_text_lines(next_content),
+      previous_sha256,
+      sha256: create_file_sha256(next_buffer),
+    };
+  } catch (error) {
+    return to_file_tool_failure(error, file_path || undefined);
+  }
+}
+
+/** 执行一个文件 action。 */
+export async function run_file_action(
+  context: { readonly rootPath: string },
+  request: FileToolActionRequest,
+): Promise<FileToolActionResult> {
+  switch (request.action) {
+    case "read":
+      return await read_file_action(context, request.input);
+    case "write":
+      return await write_file_action(context, request.input);
+    case "edit":
+      return await edit_file_action(context, request.input);
+    default:
+      return {
+        success: false,
+        error_code: "internal_error",
+        message: `Unknown file action: ${String((request as { action?: unknown }).action)}`,
+      };
+  }
+}

package/src/workspace/file/FileAtomicWriter.ts

@@ -0,0 +1,61 @@
+/**
+ * 文件工具原子写入器。
+ *
+ * 关键点（中文）
+ * - 新文件使用 `wx` 保证不会覆盖并发创建的文件。
+ * - 覆盖文件时在同目录写临时文件，再通过 rename 原子替换。
+ * - 临时文件写入后执行 fsync，并尽力清理失败残留。
+ */
+
+import path from "node:path";
+import crypto from "node:crypto";
+import { chmod, open, rename, unlink } from "node:fs/promises";
+
+/** 将字节内容安全写入目标文件。 */
+export async function write_file_atomically(params: {
+  /** 已通过路径策略校验的目标绝对路径。 */
+  file_path: string;
+  /** 要写入的完整字节内容。 */
+  content: Buffer;
+  /** 是否允许替换已有文件。 */
+  overwrite: boolean;
+  /** 覆盖时需要保留的原文件权限位。 */
+  mode?: number;
+}): Promise<void> {
+  if (!params.overwrite) {
+    const file_handle = await open(params.file_path, "wx", params.mode ?? 0o666);
+    try {
+      await file_handle.writeFile(params.content);
+      await file_handle.sync();
+    } finally {
+      await file_handle.close();
+    }
+    return;
+  }
+
+  const directory_path = path.dirname(params.file_path);
+  const temporary_path = path.join(
+    directory_path,
+    `.${path.basename(params.file_path)}.${process.pid}.${crypto.randomUUID()}.tmp`,
+  );
+  let temporary_exists = false;
+  try {
+    const file_handle = await open(temporary_path, "wx", params.mode ?? 0o666);
+    temporary_exists = true;
+    try {
+      await file_handle.writeFile(params.content);
+      await file_handle.sync();
+    } finally {
+      await file_handle.close();
+    }
+    if (typeof params.mode === "number") {
+      await chmod(temporary_path, params.mode);
+    }
+    await rename(temporary_path, params.file_path);
+    temporary_exists = false;
+  } finally {
+    if (temporary_exists) {
+      await unlink(temporary_path).catch(() => undefined);
+    }
+  }
+}

package/src/workspace/file/FileEncoding.ts

@@ -0,0 +1,175 @@
+/**
+ * 文件内容检测与编码辅助。
+ *
+ * 关键点（中文）
+ * - 二进制检测只把 NUL 和低位控制字符视为高风险，避免误判 UTF-8 中文。
+ * - 文本解码使用 fatal 模式，禁止静默插入替换字符。
+ * - 第一版仅接受 UTF-8 和带 BOM 的 UTF-16 文本。
+ */
+
+import crypto from "node:crypto";
+import path from "node:path";
+import { FileToolRuntimeError } from "@/workspace/file/FileToolError.js";
+
+const BINARY_SAMPLE_BYTES = 512;
+
+/** 支持的文本编码。 */
+export type SupportedFileEncoding = "utf-8" | "utf-16le" | "utf-16be";
+
+/** 计算文件内容的 SHA-256。 */
+export function create_file_sha256(content: Uint8Array | string): string {
+  return crypto.createHash("sha256").update(content).digest("hex");
+}
+
+/** 根据 BOM 判断文本编码。 */
+export function detect_text_encoding(buffer: Buffer): SupportedFileEncoding {
+  if (buffer.length >= 2 && buffer[0] === 0xff && buffer[1] === 0xfe) {
+    return "utf-16le";
+  }
+  if (buffer.length >= 2 && buffer[0] === 0xfe && buffer[1] === 0xff) {
+    return "utf-16be";
+  }
+  return "utf-8";
+}
+
+/** 保守判断一个文件是否为二进制。 */
+export function is_binary_file(buffer: Buffer): boolean {
+  const encoding = detect_text_encoding(buffer);
+  if (encoding !== "utf-8") return false;
+  const sample = buffer.subarray(0, Math.min(buffer.length, BINARY_SAMPLE_BYTES));
+  if (sample.includes(0)) return true;
+  if (sample.length === 0) return false;
+  let control_bytes = 0;
+  for (const byte of sample) {
+    if ((byte < 7 || (byte > 13 && byte < 32)) && byte !== 0) {
+      control_bytes += 1;
+    }
+  }
+  return control_bytes / sample.length > 0.3;
+}
+
+/** 根据文件签名识别模型可直接读取的静态图片 MIME。 */
+export function detect_image_file_mime_type(buffer: Buffer): string | undefined {
+  if (
+    buffer.length >= 8 &&
+    buffer.subarray(0, 8).equals(
+      Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    )
+  ) {
+    return "image/png";
+  }
+  if (
+    buffer.length >= 3 &&
+    buffer[0] === 0xff &&
+    buffer[1] === 0xd8 &&
+    buffer[2] === 0xff
+  ) {
+    return "image/jpeg";
+  }
+  const header = buffer.subarray(0, 6).toString("ascii");
+  if (header === "GIF87a" || header === "GIF89a") return "image/gif";
+  if (
+    buffer.length >= 12 &&
+    buffer.subarray(0, 4).toString("ascii") === "RIFF" &&
+    buffer.subarray(8, 12).toString("ascii") === "WEBP"
+  ) {
+    return "image/webp";
+  }
+  if (
+    buffer.length >= 2 &&
+    buffer[0] === 0x42 &&
+    buffer[1] === 0x4d
+  ) {
+    return "image/bmp";
+  }
+  return undefined;
+}
+
+/** 严格解码文本文件。 */
+export function decode_text_file(buffer: Buffer): {
+  /** 解码后的文本。 */
+  content: string;
+  /** 实际采用的文本编码。 */
+  encoding: SupportedFileEncoding;
+} {
+  const encoding = detect_text_encoding(buffer);
+  try {
+    const decoder = new TextDecoder(encoding, { fatal: true });
+    return {
+      content: decoder.decode(buffer),
+      encoding,
+    };
+  } catch {
+    throw new FileToolRuntimeError({
+      error_code: "encoding_error",
+      message: `File is not valid ${encoding} text`,
+    });
+  }
+}
+
+/** 按原文本编码重新编码内容，并保留 UTF-16 BOM。 */
+export function encode_text_file(
+  content: string,
+  encoding: SupportedFileEncoding,
+): Buffer {
+  if (encoding === "utf-8") return Buffer.from(content, "utf8");
+  const utf16le_content = Buffer.from(content, "utf16le");
+  if (encoding === "utf-16le") {
+    return Buffer.concat([Buffer.from([0xff, 0xfe]), utf16le_content]);
+  }
+  const utf16be_content = Buffer.from(utf16le_content);
+  for (let index = 0; index + 1 < utf16be_content.length; index += 2) {
+    const first_byte = utf16be_content[index];
+    utf16be_content[index] = utf16be_content[index + 1];
+    utf16be_content[index + 1] = first_byte;
+  }
+  return Buffer.concat([Buffer.from([0xfe, 0xff]), utf16be_content]);
+}
+
+/** 把调用方文本统一为 LF 换行。 */
+export function normalize_text_to_lf(content: string): string {
+  return content.replace(/\r\n|\r/g, "\n");
+}
+
+/** 统计可见文本行数，不把尾随换行后的空位置计为新行。 */
+export function count_text_lines(content: string): number {
+  if (content.length === 0) return 0;
+  const normalized = normalize_text_to_lf(content);
+  const lines = normalized.split("\n");
+  if (normalized.endsWith("\n")) lines.pop();
+  return lines.length;
+}
+
+/** 根据扩展名识别常见 MIME 类型。 */
+export function detect_file_mime_type(file_path: string): string | undefined {
+  const extension = path.extname(file_path).toLowerCase();
+  const by_extension: Record<string, string> = {
+    ".txt": "text/plain",
+    ".md": "text/markdown",
+    ".mdx": "text/mdx",
+    ".json": "application/json",
+    ".jsonl": "application/x-ndjson",
+    ".js": "text/javascript",
+    ".mjs": "text/javascript",
+    ".cjs": "text/javascript",
+    ".ts": "text/typescript",
+    ".tsx": "text/tsx",
+    ".jsx": "text/jsx",
+    ".css": "text/css",
+    ".html": "text/html",
+    ".xml": "application/xml",
+    ".yaml": "application/yaml",
+    ".yml": "application/yaml",
+    ".csv": "text/csv",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".bmp": "image/bmp",
+    ".pdf": "application/pdf",
+    ".zip": "application/zip",
+  };
+  return by_extension[extension];
+}