03 · 让 Agent 学会搜索和读文件

// src/tools/search.ts

import { exec } from "node:child_process";
import { promisify } from "node:util";
import type { Tool, AgentState } 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"],
  },
  execute: async (args, state: AgentState) => {
    const query = String(args.query);
    const maxResults = Number(args.maxResults) || 20;

    try {
      const { stdout } = await execAsync(
        `rg --line-number --max-count ${maxResults} -- "${query}" "${state.workingDir}"`,
        { maxBuffer: 1024 * 1024 }
      );

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

      const lines = stdout.trim().split("\n");
      const results = lines.slice(0, maxResults).map((line) => {
        const match = line.match(/^(.+?):(\d+):(.*)$/);
        if (!match) return line;
        const [, filePath, lineNum, content] = match;
        // 转为相对路径，让输出更简洁
        const relativePath = filePath.replace(state.workingDir + "/", "");
        return `${relativePath}:${lineNum}: ${content.trim()}`;
      });

      const truncated =
        lines.length > maxResults
          ? `\n\n... 共 ${lines.length} 条结果，仅显示前 ${maxResults} 条`
          : "";

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

// src/tools/read-file.ts

import { readFile } from "node:fs/promises";
import { resolve, relative } from "node:path";
import type { Tool, AgentState } from "../types";

export const readFileTool: Tool = {
  name: "read_file",
  description:
    "读取指定文件的内容。" +
    "可以指定读取的起始行和结束行，适合读取大文件的特定部分。" +
    "如果文件超过 200 行，建议只读取相关部分。",
  parameters: {
    type: "object",
    properties: {
      path: {
        type: "string",
        description: "要读取的文件路径（相对于工作目录）",
      },
      startLine: {
        type: "number",
        description: "起始行号（从 1 开始），默认 1",
      },
      endLine: {
        type: "number",
        description: "结束行号，默认读取到文件末尾（最多 200 行）",
      },
    },
    required: ["path"],
  },
  execute: async (args, state: AgentState) => {
    const filePath = resolve(state.workingDir, String(args.path));
    const startLine = Number(args.startLine) || 1;
    const maxLines = 200;
    const endLine = Number(args.endLine) || startLine + maxLines - 1;

    // 安全检查：确保不会读取工作目录之外的文件
    if (!filePath.startsWith(state.workingDir)) {
      return `错误：不能读取工作目录之外的文件。`;
    }

    try {
      const content = await readFile(filePath, "utf-8");
      const lines = content.split("\n");
      const totalLines = lines.length;

      const selectedLines = lines.slice(startLine - 1, endLine);
      const numberedLines = selectedLines.map(
        (line, i) => `${startLine + i}: ${line}`
      );

      const header = `文件: ${relative(state.workingDir, filePath)} (${totalLines} 行)`;
      const range =
        endLine < totalLines
          ? `显示第 ${startLine}-${endLine} 行`
          : `显示第 ${startLine}-${totalLines} 行`;
      const truncation =
        endLine < totalLines
          ? `\n\n... 共 ${totalLines} 行，仅显示第 ${startLine}-${endLine} 行。可以使用 startLine 和 endLine 参数读取更多内容。`
          : "";

      return `${header}\n${range}\n\n${numberedLines.join("\n")}${truncation}`;
    } catch (error: unknown) {
      if (
        error &&
        typeof error === "object" &&
        "code" in error &&
        (error as { code: string }).code === "ENOENT"
      ) {
        return `错误：文件不存在 ${args.path}`;
      }
      return `读取文件出错：${String(error)}`;
    }
  },
};

// src/tools/index.ts

import type { Tool } from "../types";
import { searchTool } from "./search";
import { readFileTool } from "./read-file";

export const tools: Tool[] = [searchTool, readFileTool];

// src/main.ts

import { Model } from "./model";
import { runAgent } from "./agent";
import { tools } from "./tools/index";
import type { AgentState, Message } from "./types";

const apiKey = process.env.OPENAI_API_KEY!;
const model = new Model(apiKey);

const userMessage: Message = {
  role: "user",
  content: "这个项目的入口文件在哪？",
};

const state: AgentState = {
  messages: [userMessage],
  task: "这个项目的入口文件在哪？",
  workingDir: process.cwd(),
};

const result = await runAgent(state, model, tools);
console.log(result);

1. [模型] 收到问题，决定调用 search 工具搜索 "dependencies"
2. [search] 执行 rg --line-number "dependencies" ./mini-coding-agent
   返回:
   package.json:5:  "dependencies": {
   package.json:6:    "openai": "^4.x"
   }
3. [模型] 看到搜索结果，决定调用 read_file 读取 package.json
4. [read_file] 读取 package.json
   返回:
   文件: package.json (18 行)
   显示第 1-18 行
   1: {
   2:   "name": "mini-coding-agent",
   ...
   5:   "dependencies": {
   6:     "openai": "^4.x"
   7:   },
   ...
4. [模型] 根据读取的内容给出回答

输出: 这个项目的主要依赖是 openai（用于调用 LLM API），
      开发依赖有 typescript 和 @types/node。