02 · 搜索工具：rg 与 glob

// src/tools/search.ts

import { exec } from "node:child_process";
import { promisify } from "node:util";
import type { AgentState, Tool } from "../types";

const execAsync = promisify(exec);

export const searchTool: Tool = {
  name: "search",
  description:
    "在项目目录中搜索包含指定关键词的文件。" +
    "返回匹配的文件路径、行号和匹配行的内容。" +
    "适合用来定位某个函数、变量或关键词在哪些文件中出现。",
  parameters: {
    type: "object",
    properties: {
      query: {
        type: "string",
        description: "搜索关键词或正则表达式",
      },
      maxResults: {
        type: "number",
        description: "最多返回多少条结果，默认 20",
      },
    },
    required: ["query"],
  },

  async execute(
    args: Record<string, unknown>,
    state: AgentState,
  ): Promise<string> {
    const query = String(args.query);
    const maxResults = Number(args.maxResults) || 20;

    try {
      /**
       * 使用 ripgrep 而非 Node.js 原生遍历：
       * 1. rg 比纯 JS 实现快一个数量级
       * 2. rg 默认遵守 .gitignore，不会搜索 node_modules 等目录
       * --line-number 输出格式为 "文件路径:行号:匹配内容"
       */
      const { stdout } = await execAsync(
        `rg --line-number --max-count ${maxResults} -- "${escapeShell(query)}" "${state.workingDir}"`,
        { maxBuffer: 1024 * 1024 },
      );

      if (!stdout.trim()) {
        return `未找到包含 "${query}" 的文件。`;
      }

      const lines = stdout.trim().split("\n");
      const results = lines.slice(0, maxResults).map(formatMatchLine);

      /** 搜索结果可能很长，超过 maxResults 时提示模型结果被截断 */
      const truncated =
        lines.length > maxResults
          ? `\n\n... 共 ${lines.length} 条结果，仅显示前 ${maxResults} 条`
          : "";

      return results.join("\n") + truncated;
    } catch (error: unknown) {
      /** rg 在没有匹配时返回 exit code 1，这不是错误，需要特殊处理 */
      if (isExecError(error) && error.code === 1) {
        return `未找到包含 "${query}" 的文件。`;
      }
      return `搜索出错：${String(error)}`;
    }
  },
};

function escapeShell(str: string): string {
  return str.replace(/"/g, '\\"');
}

function formatMatchLine(line: string): string {
  const match = line.match(/^(.+?):(\d+):(.*)$/);
  if (!match) return line;
  const [, filePath, lineNum, content] = match;
  return `${filePath}:${lineNum}: ${content.trim()}`;
}

// src/tools/glob.ts

import { readdir } from "node:fs/promises";
import type { AgentState, Tool } from "../types";

/**
 * glob 工具：按模式列出文件路径
 *
 * 和 search 工具的区别：
 * - search：在文件内容中搜索关键词（rg）
 * - glob：按文件路径/名称模式列出文件
 *
 * 两种搜索互补。例如：
 * - "哪个文件里有 runAgent 函数" -> search
 * - "项目里有哪些 .test.ts 文件" -> glob
 *
 * 使用 Node.js 内置 fs 实现，不依赖外部命令或第三方库，
 * 在 Windows / Linux / macOS 上都能运行。
 */
export const globTool: Tool = {
  name: "glob",
  description:
    "按文件路径模式列出项目中的文件。" +
    "支持 glob 模式，如 **/*.ts、src/**/*.test.ts。" +
    "适合用来查看项目结构、找到特定类型的文件。",
  parameters: {
    type: "object",
    properties: {
      pattern: {
        type: "string",
        description: "glob 模式，如 **/*.ts 或 src/**/*.test.ts",
      },
      maxResults: {
        type: "number",
        description: "最多返回多少条结果，默认 50",
      },
    },
    required: ["pattern"],
  },

  async execute(
    args: Record<string, unknown>,
    state: AgentState,
  ): Promise<string> {
    const pattern = String(args.pattern);
    const maxResults = Number(args.maxResults) || 50;

    try {
      /** 排除的目录，不需要搜索 */
      const ignore = new Set(["node_modules", ".git"]);

      /** 递归读取目录下的所有文件路径 */
      const allFiles = await readdir(state.workingDir, {
        recursive: true,
      }).then((entries) =>
        (entries as string[]).filter(
          (entry) =>
            !entry.split("/").some((segment) => ignore.has(segment)),
        ),
      );

      /** 将 glob 模式转为正则：* → [^/]*, ** → .*, ? → [^/] */
      const regex = globToRegex(pattern);
      const matched = allFiles.filter((f) => regex.test(f));

      if (matched.length === 0) {
        return `未找到匹配 "${pattern}" 的文件。`;
      }

      const results = matched.slice(0, maxResults);
      const truncated =
        matched.length > maxResults
          ? `\n\n... 共 ${matched.length} 个文件，仅显示前 ${maxResults} 个`
          : "";

      return results.join("\n") + truncated;
    } catch (error: unknown) {
      return `列出文件出错：${String(error)}`;
    }
  },
};

/**
 * 将简易 glob 模式转为正则表达式
 *
 * 支持的模式：
 * - ** 匹配任意层级目录（包括零层）
 * - *  匹配除 / 外的任意字符
 * - ?  匹配单个字符（除 /）
 * - 其他字符原样匹配
 */
function globToRegex(pattern: string): RegExp {
  const escaped = pattern
    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
    .replace(/\*\*/g, "{{GLOBSTAR}}")
    .replace(/\*/g, "[^/]*")
    .replace(/\?/g, "[^/]")
    .replace(/\{\{GLOBSTAR\}\}/g, ".*");
  return new RegExp(`^${escaped}$`);
}

// src/tools/index.ts

import { searchTool } from "./search";
import { globTool } from "./glob";
import { readFileTool } from "./read-file";
// ... 其他工具的 import

/** 基础工具集 */
export const tools: Tool[] = [
  searchTool,
  globTool,
  readFileTool,
  // ... 其他工具
];