第3章 工具系统——给 Agent 装上瑞士军刀

You: 帮我把 src/config.ts 里的端口从 3000 改成 8080
Ling: 好的，我已经将端口从 3000 修改为 8080。

// src/tools/types.ts
 
export interface Tool {
  name: string;
  description: string;
  schema: Record<string, unknown>; // JSON Schema for parameters
  execute(params: Record<string, unknown>): Promise<string>;
}

// src/tools/types.ts
 
export class ToolRegistry {
  private tools = new Map<string, Tool>();
 
  register(tool: Tool): void {
    if (this.tools.has(tool.name)) {
      throw new Error(`Tool "${tool.name}" already registered`);
    }
    this.tools.set(tool.name, tool);
  }
 
  get(name: string): Tool | undefined {
    return this.tools.get(name);
  }
 
  list(): Tool[] {
    return Array.from(this.tools.values());
  }
 
  async execute(name: string, params: Record<string, unknown>): Promise<string> {
    const tool = this.tools.get(name);
    if (!tool) {
      throw new Error(`Unknown tool: "${name}"`);
    }
    return tool.execute(params);
  }
 
  // 转换为 OpenAI function calling 格式
  toOpenAITools() {
    return this.list().map((tool) => ({
      type: "function" as const,
      function: {
        name: tool.name,
        description: tool.description,
        parameters: tool.schema,
      },
    }));
  }
}

npm install openai glob
npm install -D tsx typescript

// src/tools/read-file.ts
import { readFile } from "fs/promises";
import type { Tool } from "./types.js";
 
export const readFileTool: Tool = {
  name: "read_file",
  description:
    "Read a file and return its content with line numbers. Supports offset and limit for reading specific ranges.",
  schema: {
    type: "object",
    properties: {
      file_path: { type: "string", description: "Absolute path to the file" },
      offset: { type: "number", description: "Start line (1-based, default: 1)" },
      limit: { type: "number", description: "Max lines to read (default: all)" },
    },
    required: ["file_path"],
  },
  async execute(params) {
    const filePath = params.file_path as string;
    const offset = (params.offset as number) ?? 1;
    const limit = params.limit as number | undefined;
 
    const content = await readFile(filePath, "utf-8");
    const lines = content.split("\n");
    const start = Math.max(0, offset - 1);
    const end = limit ? start + limit : lines.length;
    const slice = lines.slice(start, end);
 
    return slice
      .map((line, i) => `${String(start + i + 1).padStart(4)}\t${line}`)
      .join("\n");
  },
};

// src/tools/write-file.ts
import { writeFile, mkdir } from "fs/promises";
import { dirname } from "path";
import type { Tool } from "./types.js";
 
export const writeFileTool: Tool = {
  name: "write_file",
  description:
    "Create or overwrite a file with the given content. Parent directories are created automatically.",
  schema: {
    type: "object",
    properties: {
      file_path: { type: "string", description: "Absolute path to write" },
      content: { type: "string", description: "File content" },
    },
    required: ["file_path", "content"],
  },
  async execute(params) {
    const filePath = params.file_path as string;
    const content = params.content as string;
 
    await mkdir(dirname(filePath), { recursive: true });
    await writeFile(filePath, content, "utf-8");
    return `File written: ${filePath} (${content.length} bytes)`;
  },
};

// src/tools/edit-file.ts
import { readFile, writeFile } from "fs/promises";
import type { Tool } from "./types.js";
 
export const editFileTool: Tool = {
  name: "edit_file",
  description:
    "Replace an exact string in a file. old_string must appear exactly once (unless replace_all is true). Fails if not found or ambiguous.",
  schema: {
    type: "object",
    properties: {
      file_path: { type: "string", description: "Absolute path to the file" },
      old_string: { type: "string", description: "Exact text to find" },
      new_string: { type: "string", description: "Replacement text" },
      replace_all: {
        type: "boolean",
        description: "Replace all occurrences (default: false)",
      },
    },
    required: ["file_path", "old_string", "new_string"],
  },
  async execute(params) {
    const filePath = params.file_path as string;
    const oldStr = params.old_string as string;
    const newStr = params.new_string as string;
    const replaceAll = (params.replace_all as boolean) ?? false;
 
    const content = await readFile(filePath, "utf-8");
    const count = content.split(oldStr).length - 1;
    if (count === 0) return `Error: old_string not found in ${filePath}`;
    if (count > 1 && !replaceAll)
      return `Error: old_string found ${count} times. Use replace_all or provide more context.`;
 
    const updated = replaceAll
      ? content.replaceAll(oldStr, newStr)
      : content.replace(oldStr, newStr);
    await writeFile(filePath, updated, "utf-8");
    return `Edited ${filePath}: replaced ${replaceAll ? count : 1} occurrence(s)`;
  },
};

// src/tools/grep.ts
import { execFile } from "child_process";
import { promisify } from "util";
import type { Tool } from "./types.js";
 
const exec = promisify(execFile);
 
export const grepTool: Tool = {
  name: "grep",
  description:
    "Search file contents using regex pattern. Returns matching lines with file paths and line numbers.",
  schema: {
    type: "object",
    properties: {
      pattern: { type: "string", description: "Regex pattern to search" },
      path: { type: "string", description: "Directory or file to search in (default: .)" },
      glob: { type: "string", description: "File glob filter, e.g. '*.ts'" },
    },
    required: ["pattern"],
  },
  async execute(params) {
    const pattern = params.pattern as string;
    const path = (params.path as string) ?? ".";
    const args = ["-rn", "--color=never", "-E", pattern, path];
    if (params.glob) args.splice(1, 0, `--include=${params.glob}`);
 
    try {
      const { stdout } = await exec("grep", args, { maxBuffer: 1024 * 1024 });
      const lines = stdout.trimEnd().split("\n");
      return lines.length > 100
        ? lines.slice(0, 100).join("\n") + `\n... (${lines.length} total matches)`
        : stdout.trimEnd();
    } catch {
      return "No matches found.";
    }
  },
};

// src/tools/glob.ts
import { glob } from "glob";
import type { Tool } from "./types.js";
 
export const globTool: Tool = {
  name: "glob",
  description: "Find files matching a glob pattern. Returns a list of matching file paths.",
  schema: {
    type: "object",
    properties: {
      pattern: { type: "string", description: "Glob pattern, e.g. 'src/**/*.ts'" },
      cwd: { type: "string", description: "Base directory (default: .)" },
    },
    required: ["pattern"],
  },
  async execute(params) {
    const pattern = params.pattern as string;
    const cwd = (params.cwd as string) ?? ".";
 
    const files = await glob(pattern, { cwd, nodir: true });
    if (files.length === 0) return "No files matched.";
    return files.sort().join("\n");
  },
};

// src/tools/bash.ts
import { exec } from "child_process";
import { promisify } from "util";
import type { Tool } from "./types.js";
 
const execAsync = promisify(exec);
 
export const bashTool: Tool = {
  name: "bash",
  description:
    "Execute a shell command. Returns stdout and stderr. Use for git, npm, build commands, etc.",
  schema: {
    type: "object",
    properties: {
      command: { type: "string", description: "Shell command to run" },
      timeout: { type: "number", description: "Timeout in ms (default: 30000)" },
    },
    required: ["command"],
  },
  async execute(params) {
    const command = params.command as string;
    const timeout = (params.timeout as number) ?? 30_000;
 
    try {
      const { stdout, stderr } = await execAsync(command, {
        timeout,
        maxBuffer: 1024 * 1024,
      });
      let result = "";
      if (stdout) result += stdout.trimEnd();
      if (stderr) result += (result ? "\n[stderr]\n" : "") + stderr.trimEnd();
      return result || "(no output)";
    } catch (err: unknown) {
      const e = err as { killed?: boolean; stdout?: string; stderr?: string; message: string };
      if (e.killed) return `Error: command timed out after ${timeout}ms`;
      return `Error: ${e.stderr || e.message}`;
    }
  },
};

// src/tools/list-files.ts
import { readdir, stat } from "fs/promises";
import { join } from "path";
import type { Tool } from "./types.js";
 
export const listFilesTool: Tool = {
  name: "list_files",
  description: "List files and directories in a given path. Shows type (file/dir) and size.",
  schema: {
    type: "object",
    properties: {
      path: { type: "string", description: "Directory path (default: .)" },
    },
  },
  async execute(params) {
    const dirPath = (params.path as string) ?? ".";
    const entries = await readdir(dirPath, { withFileTypes: true });
    const lines: string[] = [];
 
    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
      const fullPath = join(dirPath, entry.name);
      if (entry.isDirectory()) {
        lines.push(`[dir]  ${entry.name}/`);
      } else {
        const s = await stat(fullPath);
        lines.push(`[file] ${entry.name} (${s.size} bytes)`);
      }
    }
    return lines.join("\n") || "(empty directory)";
  },
};

// src/tools/ask-user.ts
import * as readline from "readline";
import type { Tool } from "./types.js";
 
export const askUserTool: Tool = {
  name: "ask_user",
  description:
    "Ask the user a question and wait for their response. Use when you need clarification or confirmation.",
  schema: {
    type: "object",
    properties: {
      question: { type: "string", description: "The question to ask" },
    },
    required: ["question"],
  },
  async execute(params) {
    const question = params.question as string;
    const rl = readline.createInterface({
      input: process.stdin,
      output: process.stderr,
    });
    return new Promise<string>((resolve) => {
      rl.question(`\n🤖 Agent asks: ${question}\n> `, (answer) => {
        rl.close();
        resolve(answer);
      });
    });
  },
};

// src/tools/index.ts
import { ToolRegistry } from "./types.js";
import { readFileTool } from "./read-file.js";
import { writeFileTool } from "./write-file.js";
import { editFileTool } from "./edit-file.js";
import { grepTool } from "./grep.js";
import { globTool } from "./glob.js";
import { bashTool } from "./bash.js";
import { listFilesTool } from "./list-files.js";
import { askUserTool } from "./ask-user.js";
 
export function createToolRegistry(): ToolRegistry {
  const registry = new ToolRegistry();
  registry.register(readFileTool);
  registry.register(writeFileTool);
  registry.register(editFileTool);
  registry.register(grepTool);
  registry.register(globTool);
  registry.register(bashTool);
  registry.register(listFilesTool);
  registry.register(askUserTool);
  return registry;
}

// src/ling.ts
import OpenAI from "openai";
import * as readline from "readline";
import { createToolRegistry } from "./tools/index.js";
 
const client = new OpenAI();
const registry = createToolRegistry();
const model = "gpt-4o";
 
type Message = OpenAI.ChatCompletionMessageParam;
 
const systemPrompt = `You are Ling, a coding assistant. You have access to tools to read, write, edit files, search code, and run commands. Use tools to accomplish tasks step by step.`;
 
async function agentLoop(userMessage: string, history: Message[]): Promise<string> {
  history.push({ role: "user", content: userMessage });
 
  while (true) {
    const response = await client.chat.completions.create({
      model,
      messages: [{ role: "system", content: systemPrompt }, ...history],
      tools: registry.toOpenAITools(),
    });
 
    const message = response.choices[0].message;
    history.push(message as Message);
 
    // 没有工具调用 → 返回最终回答
    if (!message.tool_calls || message.tool_calls.length === 0) {
      return message.content ?? "(no response)";
    }
 
    // 执行每个工具调用
    for (const toolCall of message.tool_calls) {
      const name = toolCall.function.name;
      const params = JSON.parse(toolCall.function.arguments);
 
      console.log(`  [tool] ${name}(${JSON.stringify(params).slice(0, 80)}...)`);
 
      let result: string;
      try {
        result = await registry.execute(name, params);
      } catch (err) {
        result = `Error: ${(err as Error).message}`;
      }
 
      history.push({
        role: "tool",
        tool_call_id: toolCall.id,
        content: result,
      });
    }
    // 带着工具结果继续循环
  }
}

"Edit a file."

"Replace an exact string in a file. old_string must appear exactly once
(unless replace_all is true). Fails if not found or ambiguous."

"Run a command."

"Execute a shell command. Returns stdout and stderr. Use for git, npm, build commands, etc."

// Claude Code 风格的类型定义（示意）
interface FileReadInput {
  file_path: string;
  offset?: number;
  limit?: number;
}
 
interface FileEditInput {
  file_path: string;
  old_string: string;
  new_string: string;
  replace_all?: boolean;
}
 
interface BashInput {
  command: string;
  description: string;  // 描述命令目的，给用户看
  timeout?: number;
}