@downcity/agent 1.1.338 → 1.1.400

package/src/workspace/file/FilePathPolicy.ts

@@ -1,162 +0,0 @@
-/**
- * 文件工具路径策略。
- *
- * 关键点（中文）
- * - 所有相对路径基于 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

@@ -1,99 +0,0 @@
-/**
- * 文件工具内部错误。
- *
- * 关键点（中文）
- * - 内部流程通过类型化错误中断，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

@@ -1,438 +0,0 @@
-/**
- * 项目搜索 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)}`,
-      };
-  }
-}