17.2 实验二：为 CLI 工具添加 Tool Use 能力

模型: claude-opus-4-6 (anthropic/claude-opus-4-6) 生成日期: 2026-02-18

---

上一节我们实现了一个能与 LLM 进行流式对话的 CLI 工具。但纯粹的对话并不能完成实际的编程任务——AI 需要能够读取文件、编辑代码和执行命令。这就是 Tool Use（工具调用）的作用。

本节将为 CLI 工具添加三个核心工具：文件读取（Read）、文件写入（Write）和命令执行（Bash），直接对应 OpenCode 第 5 章分析的 tool/read.ts、tool/write.ts 和 tool/bash.ts。

17.2.1 目标

实现三个工具并集成到对话流程中，使 AI 能够：

1. 读取本地文件内容

2. 创建或覆盖文件

3. 执行 Shell 命令

更重要的是，实现Agentic Loop（Agent 循环）——AI 调用工具 → 我们执行工具 → 将结果返回给 AI → AI 继续思考——直到 AI 认为任务完成。

衍生解释——Function Calling / Tool Use

Function Calling（函数调用）是现代 LLM 的核心能力之一。它允许 LLM 在生成文本的过程中"决定"调用一个预定义的函数，而不是直接输出文本。流程如下：

1. 开发者向 LLM 描述可用的工具（名称、参数、用途）

2. 用户发送请求，LLM 判断需要调用哪个工具，输出工具名称和参数

3. 开发者接收工具调用请求，在本地执行工具

4. 将执行结果返回给 LLM

5. LLM 基于结果继续生成回复（可能再次调用工具）

这个机制使 LLM 从"只会说话"进化为"能做事"的 Agent。

17.2.2 实现步骤

步骤一：定义工具 Schema

使用 Zod 定义工具的参数结构。这与 OpenCode 中 tool/tool.ts 的 Tool.define() 机制一致：

import { z } from "zod"
import { tool } from "ai"
import * as fs from "fs"
import { execSync } from "child_process"

// 工具一：文件读取
const readFileTool = tool({
  description: "读取指定路径的文件内容。用于查看代码、配置文件等。",
  parameters: z.object({
    filePath: z.string().describe("要读取的文件的绝对路径或相对路径"),
  }),
  execute: async ({ filePath }) => {
    try {
      const content = fs.readFileSync(filePath, "utf-8")
      return `文件内容 (${filePath}):\n${content}`
    } catch (e: any) {
      return `错误：无法读取文件 ${filePath}: ${e.message}`
    }
  },
})

// 工具二：文件写入
const writeFileTool = tool({
  description: "将内容写入指定路径的文件。如果文件不存在则创建，存在则覆盖。",
  parameters: z.object({
    filePath: z.string().describe("要写入的文件路径"),
    content: z.string().describe("要写入的文件内容"),
  }),
  execute: async ({ filePath, content }) => {
    try {
      fs.writeFileSync(filePath, content, "utf-8")
      return `成功写入文件: ${filePath} (${content.length} 字符)`
    } catch (e: any) {
      return `错误：无法写入文件 ${filePath}: ${e.message}`
    }
  },
})

// 工具三：命令执行
const bashTool = tool({
  description: "在 Shell 中执行命令。用于运行代码、安装依赖、查看目录等。",
  parameters: z.object({
    command: z.string().describe("要执行的 Shell 命令"),
  }),
  execute: async ({ command }) => {
    try {
      const output = execSync(command, {
        encoding: "utf-8",
        timeout: 30000,  // 30 秒超时
        maxBuffer: 1024 * 1024,  // 1MB 输出上限
      })
      return `命令输出:\n${output}`
    } catch (e: any) {
      return `命令执行失败:\n${e.stderr || e.message}`
    }
  },
})

注意 description 字段的重要性——LLM 通过阅读这些描述来决定何时使用哪个工具。描述越清晰准确，LLM 的工具选择就越正确。这与 OpenCode 中每个工具的 .txt 描述文件（如 tool/read.txt）的作用完全一致。

步骤二：集成到 streamText

将工具传递给 streamText 的 tools 参数：

const result = streamText({
  model,
  system: `你是一个 AI 编程助手，可以读取文件、写入文件和执行命令。
规则：
1. 需要查看文件内容时，使用 readFile 工具
2. 需要创建或修改文件时，使用 writeFile 工具
3. 需要执行命令时，使用 bash 工具
4. 在修改文件之前，先读取文件了解当前内容
5. 如果任务完成，直接告诉用户结果`,
  messages,
  tools: {
    readFile: readFileTool,
    writeFile: writeFileTool,
    bash: bashTool,
  },
  maxSteps: 10,  // 最多允许 10 轮工具调用
})

maxSteps 参数是 Vercel AI SDK 对 Agentic Loop 的内置支持——它允许 LLM 在一次 streamText 调用中多次调用工具，SDK 自动处理"调用工具 → 获取结果 → 继续生成"的循环。

步骤三：实现 Agentic Loop

完整的对话函数需要处理工具调用事件：

async function chat(userInput: string) {
  messages.push({ role: "user", content: userInput })

  const result = streamText({
    model,
    system: `你是一个 AI 编程助手...（同上）`,
    messages,
    tools: {
      readFile: readFileTool,
      writeFile: writeFileTool,
      bash: bashTool,
    },
    maxSteps: 10,
  })

  let fullResponse = ""
  process.stdout.write("\nAssistant: ")

  // 处理流式输出——包括文本和工具调用
  for await (const part of result.fullStream) {
    switch (part.type) {
      case "text-delta":
        // 文本块
        process.stdout.write(part.textDelta)
        fullResponse += part.textDelta
        break

      case "tool-call":
        // LLM 决定调用工具
        console.log(`\n  [工具调用] ${part.toolName}(${
          JSON.stringify(part.args)
        })`)
        break

      case "tool-result":
        // 工具执行完成
        const preview = String(part.result).slice(0, 200)
        console.log(`  [工具结果] ${preview}${
          String(part.result).length > 200 ? "..." : ""
        }`)
        break

      case "step-finish":
        // 一轮工具调用完成，LLM 继续思考
        break
    }
  }

  console.log("\n")
  messages.push({ role: "assistant", content: fullResponse })
}

步骤四：测试

bun run index.ts

You: 帮我创建一个 hello.py 文件，写一个简单的 Flask 服务器