如何扩展 chatbot-template:添加自定义 Tool 与 Part 组件完整步骤

原创2026-10-14 20:10:461,608 阅读

如何扩展 chatbot-template:添加自定义 Tool 与 Part 组件完整步骤

chatbot-template 是一个基于 Next.js + Vercel AI SDK + shadcn/ui 构建的极简 AI 聊天机器人模板,运行在 Vercel AI Gateway 上。本文带你走通扩展聊天机器人的完整流程:从定义自定义 Tool、注册到工具集,到创建配套的 Part 组件并接入消息渲染,一个示例讲清全部步骤。

先认识模板:为什么扩展只需改两个地方

模板内置了三个现成的 Tool 可以当"参考样板":

Tool 定义文件 说明
github_repo tools/github_repo.ts 服务端执行,查询 GitHub 仓库数据
web_search tools/web_search.ts 各模型提供商的原生联网搜索
ask_user tools/ask_user.ts 交互式问卷,由用户在界面中作答

要给它加新能力(比如查天气、查汇率、连内部 API),只需要动两处:

  1. Tool(工具):模型"会做什么"——在服务端定义能力,模型调用后返回结果。
  2. Part(部件):消息"长什么样"——把工具的输入/输出渲染成界面上的一块内容。

一条助手消息是由若干有类型的 Part 组成的列表。app/api/chat/route.ts 用 streamText 流式返回响应,components/chat-message.tsx 则对每个 part.type 做 switch 分发,把每种 Tool Part 交给 components/parts/ 目录下对应的组件渲染。

理解关键机制:Tool 状态流转与类型推导

Tool Part 在流式输出过程中会经历如下状态,这是写 Part 组件时的核心依据:

input-streaming → input-available → output-available(或 output-error)

以 components/parts/github-repo-part.tsx 为例:前两个状态显示"正在查询…"的加载动画,output-available 渲染 stars/forks 统计,output-error 显示错误信息。

更省心的是类型推导:消息类型由工具定义通过 AI SDK 的 InferUITools 自动推断,所以在 Part 组件里 part.input 和 part.output 都是完整类型化的——改错一个字段名,构建会直接报错,而不是运行时悄悄出现 undefined。

第 1 步:在 tools/ 下创建 Tool 定义文件

新建 tools/get_weather.ts。注意:文件名就是模型识别到的工具名,推荐用下划线命名(如 get_weather、github_repo)。文件内导出一个 tool() 调用,包含三部分:

import { tool } from "ai"
import { z } from "zod"

export const getWeather = tool({
  description: "Get the current weather for a city.",
  inputSchema: z.object({
    city: z.string().describe("The city name"),
  }),
  outputSchema: z.object({
    temperature: z.number(),
    condition: z.string(),
  }),
  execute: ({ city }) => {
    // 调用你的天气 API,这里只是示意
    return { temperature: 25, condition: "Sunny" }
  },
})
  • description:写给模型看的"说明书",决定模型何时调用它,建议写清楚触发场景。
  • inputSchema / outputSchema:用 zod 描述输入输出结构。
  • execute:服务端执行逻辑。💡 如果是"由用户在界面中作答"的交互型工具(如 ask_user),可以省略 execute,后面进阶部分会讲。

第 2 步:在 tools/index.ts 注册工具

打开 tools/index.ts,把新工具加进 baseTools 并导入即可:

import { getWeather } from "./get_weather"

const baseTools = {
  github_repo: githubRepo,
  ask_user: askUser,
  get_weather: getWeather, // ← 新增
}

baseTools 会被 getTools() 取出并传入聊天路由的 streamText,模型从此就能调用它了。同时,ChatUIMessage 类型基于 InferUITools<typeof baseTools> 自动推导,新工具的 part.input / part.output 类型也随之就绪。

第 3 步:创建配套的 Part 组件

在 components/parts/ 新建 get-weather-part.tsx,按 part.state 分支渲染不同阶段:

import { type ChatMessagePart } from "@/tools"
import { Spinner } from "@/components/ui/spinner"

type GetWeatherToolPart = Extract<
  ChatMessagePart,
  { type: "tool-get_weather" }
>

export function GetWeatherPart({ part }: { part: GetWeatherToolPart }) {
  switch (part.state) {
    case "input-streaming":
    case "input-available":
      return (
        <div className="flex items-center gap-2 text-sm">
          <Spinner /> Looking up weather…
        </div>
      )
    case "output-available":
      return <div>🌤 {part.output.temperature}°C, {part.output.condition}</div>
    case "output-error":
      return <div className="text-destructive">{part.errorText}</div>
    default:
      return null
  }
}

类型 GetWeatherToolPart 从 ChatMessagePart 中用 Extract 精确挑出来(写法与 tools/index.ts 中 GithubRepoToolPart、AskUserToolPart 完全一致),保证只接收自己那种 Part。

第 4 步:在 chat-message.tsx 中接入渲染

最后一步,打开 components/chat-message.tsx,在 switch 中新增一个 case:

case "tool-get_weather":
  return <GetWeatherPart key={part.toolCallId} part={part} />

到这里,pnpm dev 跑起来后,只要对话中模型判断需要查天气,界面就会先显示加载动画,再显示天气结果——完整的 Tool + Part 扩展就完成了。✅

进阶:交互型 Tool(ask_user 模式)

如果工具的结果不来自服务端,而来自用户本人(例如问卷、审批、表单确认),可以省略 execute,参考 tools/ask_user.ts。此时流程变为:

  1. 模型调用 ask_user 并传入问题列表;
  2. components/chat.tsx 检测到最后一条消息存在待回答的 tool-ask_user Part,就在滚动区底部钉住一个 components/question-card.tsx 问卷卡片;
  3. 用户作答后,客户端调用 addToolOutput 把答案作为工具输出回传,sendAutomaticallyWhen 配置会自动续流,模型继续生成回复。

这个"服务端执行"与"客户端作答"两种模式,覆盖了绝大多数自定义 Tool 场景。

新手常见问题 FAQ

Q1:Tool 的字段类型在 Part 里是 undefined,为什么? 确认该工具已经加进 tools/index.ts 的 baseTools——类型是通过 InferUITools 从 baseTools 推导的,未注册的工具没有对应类型。

Q2:想给 Part 组件加按钮、抽屉等 UI,怎么装? 模板已内置 shadcn CLI,直接运行:

npx shadcn@latest add button

组件会落到 components/ui/,Spinner、Drawer、Item 等现成组件可直接复用。

Q3:想换模型或加模型,在哪改? 模型列表在 lib/models.ts,第一个条目是默认模型;聊天路由会用它校验请求,防止调用未授权的模型。

Q4:web_search 为什么不在 baseTools 里? 它由模型 ID 决定——tools/web_search.ts 根据前缀(openai/ 或 anthropic/)动态返回对应提供商的搜索工具,getTools() 会按需合并进工具集。这是"条件性工具"的参考写法。

小结

步骤 文件位置 做什么
1 tools/<name>.ts 定义 tool():description + schema + execute
2 tools/index.ts 注册进 baseTools
3 components/parts/<name>-part.tsx 按 part.state 渲染各阶段 UI
4 components/chat-message.tsx 新增 case "tool-<name>"

记住这条主线:文件名即工具名,注册后类型自动推导,状态驱动渲染。有了 github_repo 这个样板,加上任意能力都不过是四步小事——这就是 chatbot-template 作为扩展底座的魅力。

登录后查看全文
chatbot-template