@downcity/agent 1.1.287 → 1.1.310

package/src/workspace/file/FilePathPolicy.ts

@@ -0,0 +1,162 @@
+/**
+ * 文件工具路径策略。
+ *
+ * 关键点（中文）
+ * - 所有相对路径基于 Shell 的项目根目录解析。
+ * - 词法路径和真实路径都必须位于项目根目录内。
+ * - 最终目标不允许是符号链接，避免原子替换时产生歧义或逃逸。
+ */
+
+import path from "node:path";
+import { lstat, realpath } from "node:fs/promises";
+import { FileToolRuntimeError } from "@/workspace/file/FileToolError.js";
+import type { ResolvedFileToolPath } from "@/types/workspace/FileTool.js";
+
+/** 判断目标路径是否等于根目录或位于根目录之下。 */
+function is_path_inside_root(root_path: string, target_path: string): boolean {
+  const relative_path = path.relative(root_path, target_path);
+  return (
+    relative_path === "" ||
+    (relative_path !== ".." &&
+      !relative_path.startsWith(`..${path.sep}`) &&
+      !path.isAbsolute(relative_path))
+  );
+}
+
+/** 返回最接近目标且已经存在的祖先目录。 */
+async function resolve_existing_ancestor(target_path: string): Promise<string> {
+  let current_path = path.dirname(target_path);
+  while (true) {
+    try {
+      const metadata = await lstat(current_path);
+      if (metadata.isSymbolicLink()) return current_path;
+      if (!metadata.isDirectory()) {
+        throw new FileToolRuntimeError({
+          error_code: "not_a_file",
+          message: `Parent path is not a directory: ${current_path}`,
+          file_path: target_path,
+        });
+      }
+      return current_path;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+    const parent_path = path.dirname(current_path);
+    if (parent_path === current_path) return current_path;
+    current_path = parent_path;
+  }
+}
+
+/** 解析并校验一个项目内文件或搜索路径。 */
+async function resolve_project_tool_path(params: {
+  /** Shell 当前绑定的项目根目录。 */
+  root_path: string;
+  /** 模型传入的相对路径或绝对路径。 */
+  file_path: string;
+  /** 目标文件不存在时是否仍允许返回路径。 */
+  allow_missing: boolean;
+  /** 是否要求目标为普通文件。 */
+  require_file: boolean;
+}): Promise<ResolvedFileToolPath> {
+  const raw_root_path = String(params.root_path || "").trim();
+  const raw_file_path = String(params.file_path || "").trim();
+  if (!raw_root_path) {
+    throw new FileToolRuntimeError({
+      error_code: "invalid_path",
+      message: "Workspace file tools require a non-empty root_path",
+    });
+  }
+  if (!raw_file_path || raw_file_path.includes("\0")) {
+    throw new FileToolRuntimeError({
+      error_code: "invalid_path",
+      message: "file_path must be a non-empty valid path",
+    });
+  }
+
+  const root_path = path.resolve(raw_root_path);
+  const root_real_path = await realpath(root_path);
+  const file_path = path.resolve(
+    path.isAbsolute(raw_file_path)
+      ? raw_file_path
+      : path.join(root_path, raw_file_path),
+  );
+  if (!is_path_inside_root(root_path, file_path)) {
+    throw new FileToolRuntimeError({
+      error_code: "sandbox_denied",
+      message: `File path escapes project root: ${raw_file_path}`,
+      file_path,
+    });
+  }
+
+  try {
+    const metadata = await lstat(file_path);
+    if (metadata.isSymbolicLink()) {
+      throw new FileToolRuntimeError({
+        error_code: "sandbox_denied",
+        message: `Symbolic link targets are not allowed: ${file_path}`,
+        file_path,
+      });
+    }
+    if (params.require_file && !metadata.isFile()) {
+      throw new FileToolRuntimeError({
+        error_code: "not_a_file",
+        message: `Expected a regular file: ${file_path}`,
+        file_path,
+      });
+    }
+    const file_real_path = await realpath(file_path);
+    if (!is_path_inside_root(root_real_path, file_real_path)) {
+      throw new FileToolRuntimeError({
+        error_code: "sandbox_denied",
+        message: `Resolved file path escapes project root: ${file_path}`,
+        file_path,
+      });
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    if (!params.allow_missing) {
+      throw new FileToolRuntimeError({
+        error_code: "file_not_found",
+        message: `File not found: ${file_path}`,
+        file_path,
+      });
+    }
+    const ancestor_path = await resolve_existing_ancestor(file_path);
+    const ancestor_real_path = await realpath(ancestor_path);
+    if (!is_path_inside_root(root_real_path, ancestor_real_path)) {
+      throw new FileToolRuntimeError({
+        error_code: "sandbox_denied",
+        message: `Resolved parent path escapes project root: ${file_path}`,
+        file_path,
+      });
+    }
+  }
+
+  return { file_path, root_path };
+}
+
+/** 解析并校验一个项目内文件路径。 */
+export async function resolve_file_tool_path(params: {
+  /** Shell 当前绑定的项目根目录。 */
+  root_path: string;
+  /** 模型传入的相对路径或绝对路径。 */
+  file_path: string;
+  /** 目标文件不存在时是否仍允许返回路径。 */
+  allow_missing: boolean;
+}): Promise<ResolvedFileToolPath> {
+  return await resolve_project_tool_path({ ...params, require_file: true });
+}
+
+/** 解析并校验一个项目内搜索路径，允许普通文件或目录。 */
+export async function resolve_search_tool_path(params: {
+  /** Shell 当前绑定的项目根目录。 */
+  root_path: string;
+  /** 模型传入的相对路径或绝对路径。 */
+  file_path: string;
+}): Promise<ResolvedFileToolPath> {
+  return await resolve_project_tool_path({
+    ...params,
+    allow_missing: false,
+    require_file: false,
+  });
+}

package/src/workspace/file/FileToolError.ts

@@ -0,0 +1,99 @@
+/**
+ * 文件工具内部错误。
+ *
+ * 关键点（中文）
+ * - 内部流程通过类型化错误中断，tool 边界再统一转换为结构化失败结果。
+ * - 不把 Node.js 原始错误码直接暴露为公共协议。
+ */
+
+import type {
+  FileEditDetail,
+  FileToolErrorCode,
+  FileToolFailure,
+} from "@/types/workspace/FileTool.js";
+
+/** 文件工具可识别的内部错误。 */
+export class FileToolRuntimeError extends Error {
+  /** 稳定的公共错误码。 */
+  readonly error_code: FileToolErrorCode;
+  /** 已完成解析时的目标绝对路径。 */
+  readonly file_path?: string;
+  /** 编辑失败时的匹配详情。 */
+  readonly details?: FileEditDetail[];
+
+  constructor(params: {
+    /** 稳定的公共错误码。 */
+    error_code: FileToolErrorCode;
+    /** 人类可读错误信息。 */
+    message: string;
+    /** 已完成解析时的目标绝对路径。 */
+    file_path?: string;
+    /** 编辑失败时的匹配详情。 */
+    details?: FileEditDetail[];
+  }) {
+    super(params.message);
+    this.name = "FileToolRuntimeError";
+    this.error_code = params.error_code;
+    this.file_path = params.file_path;
+    this.details = params.details;
+  }
+}
+
+/** 把内部或 Node.js 错误转换为稳定失败结果。 */
+export function to_file_tool_failure(
+  error: unknown,
+  fallback_file_path?: string,
+): FileToolFailure {
+  if (error instanceof FileToolRuntimeError) {
+    return {
+      success: false,
+      error_code: error.error_code,
+      message: error.message,
+      ...(error.file_path || fallback_file_path
+        ? { file_path: error.file_path || fallback_file_path }
+        : {}),
+      ...(error.details ? { details: error.details } : {}),
+    };
+  }
+
+  const node_error = error as NodeJS.ErrnoException;
+  const code = String(node_error?.code || "");
+  if (code === "ENOENT") {
+    return {
+      success: false,
+      error_code: "file_not_found",
+      message: `File not found: ${fallback_file_path || "unknown path"}`,
+      ...(fallback_file_path ? { file_path: fallback_file_path } : {}),
+    };
+  }
+  if (code === "EACCES" || code === "EPERM" || code === "EROFS") {
+    return {
+      success: false,
+      error_code: "permission_denied",
+      message: `Permission denied: ${fallback_file_path || "unknown path"}`,
+      ...(fallback_file_path ? { file_path: fallback_file_path } : {}),
+    };
+  }
+  if (code === "EISDIR") {
+    return {
+      success: false,
+      error_code: "not_a_file",
+      message: `Expected a file: ${fallback_file_path || "unknown path"}`,
+      ...(fallback_file_path ? { file_path: fallback_file_path } : {}),
+    };
+  }
+  if (code === "EEXIST") {
+    return {
+      success: false,
+      error_code: "file_exists",
+      message: `File already exists: ${fallback_file_path || "unknown path"}`,
+      ...(fallback_file_path ? { file_path: fallback_file_path } : {}),
+    };
+  }
+  return {
+    success: false,
+    error_code: "internal_error",
+    message: error instanceof Error ? error.message : String(error),
+    ...(fallback_file_path ? { file_path: fallback_file_path } : {}),
+  };
+}

package/src/workspace/search/SearchActionRuntime.ts

@@ -0,0 +1,438 @@
+/**
+ * 项目搜索 action 运行时。
+ *
+ * 关键点（中文）
+ * - `grep` 通过参数数组执行 `rg --json`，不会把模型输入拼接进 shell 命令。
+ * - `find` 通过 globby 流式发现文件，尊重 `.gitignore` 且不跟随符号链接。
+ * - 两个 action 都复用项目根目录约束，并在结果达到上限后尽快停止扫描。
+ */
+
+import { spawn } from "node:child_process";
+import { lstat } from "node:fs/promises";
+import path from "node:path";
+import readline from "node:readline";
+import type { Readable } from "node:stream";
+import globby from "globby";
+import type {
+  FindToolInput,
+  FindToolResult,
+  GrepToolInput,
+  GrepToolMatch,
+  GrepToolResult,
+  SearchToolActionRequest,
+  SearchToolActionResult,
+} from "@/types/workspace/SearchTool.js";
+import { resolve_search_tool_path } from "@/workspace/file/FilePathPolicy.js";
+import {
+  SearchToolRuntimeError,
+  to_search_tool_failure,
+} from "@/workspace/search/SearchToolError.js";
+
+const DEFAULT_MAX_RESULTS = 200;
+const MAX_RESULTS = 2_000;
+const MAX_LINE_PREVIEW_CHARS = 2_000;
+const MAX_STDERR_CHARS = 16_000;
+
+/** ripgrep JSON 字符串字段。 */
+interface RipgrepJsonText {
+  /** UTF-8 可解码时的原始文本。 */
+  text?: string;
+  /** 无法直接表示为 UTF-8 时的 base64 数据。 */
+  bytes?: string;
+}
+
+/** ripgrep JSON 子匹配。 */
+interface RipgrepJsonSubmatch {
+  /** 当前子匹配文本。 */
+  match?: RipgrepJsonText;
+  /** 当前子匹配在行内的 0-based UTF-8 字节起点。 */
+  start?: number;
+}
+
+/** ripgrep JSON 事件。 */
+interface RipgrepJsonEvent {
+  /** 事件类型。 */
+  type?: string;
+  /** begin / match 事件数据。 */
+  data?: {
+    /** 当前文件路径。 */
+    path?: RipgrepJsonText;
+    /** 当前匹配行文本。 */
+    lines?: RipgrepJsonText;
+    /** 当前匹配的 1-based 行号。 */
+    line_number?: number;
+    /** 当前行内的子匹配列表。 */
+    submatches?: RipgrepJsonSubmatch[];
+  };
+}
+
+/** 把结果上限归一化到公共协议允许范围。 */
+function resolve_max_results(value: number | undefined): number {
+  return Math.min(
+    MAX_RESULTS,
+    Math.max(1, Math.floor(value ?? DEFAULT_MAX_RESULTS)),
+  );
+}
+
+/** 把任意平台路径转换为稳定的 POSIX 路径。 */
+function to_posix_path(file_path: string): string {
+  return file_path.split(path.sep).join(path.posix.sep);
+}
+
+/** 解码 ripgrep JSON 中的 text / bytes 判别字段。 */
+function decode_rg_text(value: RipgrepJsonText | undefined): string {
+  if (typeof value?.text === "string") return value.text;
+  if (typeof value?.bytes === "string") {
+    return Buffer.from(value.bytes, "base64").toString("utf8");
+  }
+  return "";
+}
+
+/** 去除 ripgrep 行文本末尾的单个换行符。 */
+function trim_line_ending(content: string): string {
+  if (content.endsWith("\r\n")) return content.slice(0, -2);
+  if (content.endsWith("\n") || content.endsWith("\r")) {
+    return content.slice(0, -1);
+  }
+  return content;
+}
+
+/** 构造模型可读、长度稳定的行预览。 */
+function create_line_preview(content: string): {
+  /** 截断后的行文本。 */
+  text: string;
+  /** 原始行是否被截断。 */
+  line_truncated: boolean;
+} {
+  const line = trim_line_ending(content);
+  const line_truncated = line.length > MAX_LINE_PREVIEW_CHARS;
+  return {
+    text: line_truncated ? line.slice(0, MAX_LINE_PREVIEW_CHARS) : line,
+    line_truncated,
+  };
+}
+
+/** 校验并归一化 find 使用的 glob 模式。 */
+function resolve_find_pattern(raw_pattern: string): string {
+  const pattern = String(raw_pattern || "").trim();
+  if (
+    !pattern ||
+    pattern.includes("\0") ||
+    pattern.includes("\\") ||
+    path.posix.isAbsolute(pattern) ||
+    /^[a-zA-Z]:\//.test(pattern) ||
+    pattern.startsWith("!")
+  ) {
+    throw new SearchToolRuntimeError({
+      error_code: "invalid_pattern",
+      message: "pattern must be a non-empty positive POSIX glob relative to the search path",
+    });
+  }
+  const has_parent_segment = pattern
+    .split("/")
+    .some((segment) => segment === ".." || /(^|[({,|@+*?!])\.\.($|[)},|])/.test(segment));
+  if (has_parent_segment) {
+    throw new SearchToolRuntimeError({
+      error_code: "invalid_pattern",
+      message: "pattern must not contain parent-directory segments",
+    });
+  }
+  return pattern;
+}
+
+/** 把 ripgrep 输出路径归一化为项目相对路径。 */
+function resolve_rg_file_path(root_path: string, output_path: string): string {
+  const absolute_path = path.isAbsolute(output_path)
+    ? path.resolve(output_path)
+    : path.resolve(root_path, output_path);
+  return to_posix_path(path.relative(root_path, absolute_path));
+}
+
+/** 执行 ripgrep 内容搜索。 */
+async function grep_action(
+  context: { readonly rootPath: string },
+  input: GrepToolInput,
+  abort_signal?: AbortSignal,
+): Promise<GrepToolResult> {
+  let search_path = "";
+  try {
+    const query = String(input.query || "");
+    if (!query || query.includes("\0")) {
+      throw new SearchToolRuntimeError({
+        error_code: "invalid_pattern",
+        message: "query must be a non-empty valid string",
+      });
+    }
+    if (abort_signal?.aborted) {
+      throw new SearchToolRuntimeError({
+        error_code: "aborted",
+        message: "grep search was aborted before it started",
+      });
+    }
+    const resolved = await resolve_search_tool_path({
+      root_path: context.rootPath,
+      file_path: input.path || ".",
+    });
+    search_path = resolved.file_path;
+    const root_path = resolved.root_path;
+    const max_results = resolve_max_results(input.max_results);
+    const target_path = to_posix_path(path.relative(root_path, search_path)) || ".";
+    const args = [
+      "--json",
+      "--hidden",
+      "--no-require-git",
+      "--glob",
+      "!.git/**",
+      ...(input.case_sensitive === true ? [] : ["--ignore-case"]),
+      ...(input.literal === false ? [] : ["--fixed-strings"]),
+      ...((input.glob || []).flatMap((pattern) => ["--glob", pattern])),
+      "--",
+      query,
+      target_path,
+    ];
+    const child = spawn("rg", args, {
+      cwd: root_path,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    const matches: GrepToolMatch[] = [];
+    let files_searched = 0;
+    let truncated = false;
+    let stderr = "";
+    let aborted = false;
+
+    const abort_handler = (): void => {
+      aborted = true;
+      child.kill("SIGTERM");
+    };
+    abort_signal?.addEventListener("abort", abort_handler, { once: true });
+
+    const completion = new Promise<{ code: number | null; signal: NodeJS.Signals | null }>(
+      (resolve, reject) => {
+        child.once("error", reject);
+        child.once("close", (code, signal) => resolve({ code, signal }));
+      },
+    );
+    const stderr_task = (async (): Promise<void> => {
+      child.stderr.setEncoding("utf8");
+      for await (const chunk of child.stderr) {
+        if (stderr.length >= MAX_STDERR_CHARS) continue;
+        stderr += String(chunk).slice(0, MAX_STDERR_CHARS - stderr.length);
+      }
+    })();
+    const stdout_task = (async (): Promise<void> => {
+      const lines = readline.createInterface({ input: child.stdout });
+      for await (const raw_line of lines) {
+        if (!raw_line) continue;
+        let event: RipgrepJsonEvent;
+        try {
+          event = JSON.parse(raw_line) as RipgrepJsonEvent;
+        } catch {
+          child.kill("SIGTERM");
+          throw new SearchToolRuntimeError({
+            error_code: "search_failed",
+            message: "ripgrep returned malformed JSON output",
+            search_path,
+          });
+        }
+        if (event.type === "begin") {
+          files_searched += 1;
+          continue;
+        }
+        if (event.type !== "match" || !event.data) continue;
+        const output_path = decode_rg_text(event.data.path);
+        const line_number = Number(event.data.line_number || 0);
+        const preview = create_line_preview(decode_rg_text(event.data.lines));
+        for (const submatch of event.data.submatches || []) {
+          if (matches.length >= max_results) {
+            truncated = true;
+            child.kill("SIGTERM");
+            return;
+          }
+          matches.push({
+            file_path: resolve_rg_file_path(root_path, output_path),
+            line_number,
+            column: Number(submatch.start || 0) + 1,
+            text: preview.text,
+            match_text: decode_rg_text(submatch.match),
+            line_truncated: preview.line_truncated,
+          });
+        }
+      }
+    })();
+
+    let process_result: { code: number | null; signal: NodeJS.Signals | null };
+    try {
+      [, , process_result] = await Promise.all([
+        stdout_task,
+        stderr_task,
+        completion,
+      ]);
+    } finally {
+      abort_signal?.removeEventListener("abort", abort_handler);
+    }
+    if (aborted) {
+      throw new SearchToolRuntimeError({
+        error_code: "aborted",
+        message: "grep search was aborted",
+        search_path,
+      });
+    }
+    if (!truncated && process_result.code !== 0 && process_result.code !== 1) {
+      const message = stderr.trim() || `ripgrep exited with code ${String(process_result.code)}`;
+      throw new SearchToolRuntimeError({
+        error_code: input.literal === false && /regex parse error|error parsing regex/i.test(message)
+          ? "invalid_pattern"
+          : "search_failed",
+        message,
+        search_path,
+      });
+    }
+    return {
+      success: true,
+      root_path,
+      search_path,
+      query,
+      matches,
+      files_searched,
+      match_count: matches.length,
+      truncated,
+    };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return {
+        success: false,
+        error_code: "rg_unavailable",
+        message: "ripgrep executable 'rg' was not found in PATH",
+        ...(search_path ? { search_path } : {}),
+      };
+    }
+    return to_search_tool_failure(error, search_path || undefined);
+  }
+}
+
+/** 执行 glob 文件发现。 */
+async function find_action(
+  context: { readonly rootPath: string },
+  input: FindToolInput,
+  abort_signal?: AbortSignal,
+): Promise<FindToolResult> {
+  let search_path = "";
+  try {
+    const pattern = resolve_find_pattern(input.pattern);
+    if (abort_signal?.aborted) {
+      throw new SearchToolRuntimeError({
+        error_code: "aborted",
+        message: "find search was aborted before it started",
+      });
+    }
+    const resolved = await resolve_search_tool_path({
+      root_path: context.rootPath,
+      file_path: input.path || ".",
+    });
+    search_path = resolved.file_path;
+    const metadata = await lstat(search_path);
+    if (!metadata.isDirectory()) {
+      throw new SearchToolRuntimeError({
+        error_code: "not_a_directory",
+        message: `find path must be a directory: ${search_path}`,
+        search_path,
+      });
+    }
+    const max_results = resolve_max_results(input.max_results);
+    const search_prefix = to_posix_path(
+      path.relative(resolved.root_path, search_path),
+    );
+    const scoped_pattern = search_prefix
+      ? path.posix.join(search_prefix, pattern)
+      : pattern;
+    const stream = globby.stream(scoped_pattern, {
+      cwd: resolved.root_path,
+      gitignore: true,
+      dot: true,
+      onlyFiles: true,
+      followSymbolicLinks: false,
+      unique: true,
+      expandDirectories: false,
+      ignore: [".git/**"],
+    }) as Readable & AsyncIterable<string | Buffer>;
+    let aborted = false;
+    const abort_handler = (): void => {
+      aborted = true;
+      stream.destroy();
+    };
+    abort_signal?.addEventListener("abort", abort_handler, { once: true });
+    const files: string[] = [];
+    let truncated = false;
+    try {
+      for await (const entry of stream) {
+        if (aborted) break;
+        if (files.length >= max_results) {
+          truncated = true;
+          break;
+        }
+        const relative_to_root_entry = String(entry);
+        const absolute_path = path.resolve(
+          resolved.root_path,
+          relative_to_root_entry,
+        );
+        const relative_to_search = path.relative(search_path, absolute_path);
+        const relative_to_root = path.relative(resolved.root_path, absolute_path);
+        if (
+          relative_to_search === ".." ||
+          relative_to_search.startsWith(`..${path.sep}`) ||
+          path.isAbsolute(relative_to_search) ||
+          relative_to_root === ".." ||
+          relative_to_root.startsWith(`..${path.sep}`) ||
+          path.isAbsolute(relative_to_root)
+        ) {
+          throw new SearchToolRuntimeError({
+            error_code: "sandbox_denied",
+            message: `Glob result escapes search path: ${relative_to_root_entry}`,
+            search_path,
+          });
+        }
+        files.push(to_posix_path(relative_to_root));
+      }
+    } finally {
+      abort_signal?.removeEventListener("abort", abort_handler);
+    }
+    if (aborted) {
+      throw new SearchToolRuntimeError({
+        error_code: "aborted",
+        message: "find search was aborted",
+        search_path,
+      });
+    }
+    files.sort((left, right) => left.localeCompare(right));
+    return {
+      success: true,
+      root_path: resolved.root_path,
+      search_path,
+      pattern,
+      files,
+      match_count: files.length,
+      truncated,
+    };
+  } catch (error) {
+    return to_search_tool_failure(error, search_path || undefined);
+  }
+}
+
+/** 执行一个项目搜索 action。 */
+export async function run_search_action(
+  context: { readonly rootPath: string },
+  request: SearchToolActionRequest,
+): Promise<SearchToolActionResult> {
+  switch (request.action) {
+    case "grep":
+      return await grep_action(context, request.input, request.abort_signal);
+    case "find":
+      return await find_action(context, request.input, request.abort_signal);
+    default:
+      return {
+        success: false,
+        error_code: "internal_error",
+        message: `Unknown search action: ${String((request as { action?: unknown }).action)}`,
+      };
+  }
+}