前言

随着人工智能技术的快速发展，智能聊天应用已经成为企业、开发者和教育场景中不可或缺的工具。然而，从零搭建一个完整的聊天系统，通常需要处理前端界面设计、智能体逻辑配置、工具接口集成以及热更新调试等多个环节。这不仅耗时，还容易出现配置错误，降低开发效率。为此，MateChat 官方提供了 CLI 脚手架 create-matechat，可以在几分钟内生成基础项目结构，自动集成 Vue 前端模板，并预配置智能体示例和工具接口。这意味着开发者无需从零开始构建环境，即可直接进入业务开发阶段，专注于智能体逻辑、工具集成和数据交互。

本文将详细介绍如何通过 CLI 快速创建 MateChat 项目，包括安装流程、模板选择、依赖安装、项目目录解析以及模型适配方法。文章还将提供实际案例和操作提示，帮助读者在最短时间内完成智能聊天应用的搭建。

---

1. 通过 CLI 创建 MateChat 项目

MateChat 提供的 CLI 脚手架支持交互式项目生成，使开发者可以快速初始化项目。整个过程包括三个核心环节：安装与创建项目、填写项目信息与选择模板，以及安装依赖并启动开发环境。以下将详细展开每个环节的操作流程和注意事项。

1.1 安装与创建项目

在创建项目之前，请确保本地已安装 Node.js，并具备 npm 或 pnpm 包管理工具。使用以下命令即可启动项目创建流程：

 使用 npm 创建项目
npm create matechat@latest

 或使用 pnpm 创建项目
pnpm create matechat@latest

执行命令后，CLI 会自动下载安装 create-matechat 脚手架，并启动交互式引导。这意味着开发者无需手动下载、解压或配置复杂依赖，整个过程非常便捷。根据网络环境不同，下载和安装过程可能需要几分钟。在此过程中，如果遇到依赖下载缓慢或超时的问题，可以通过配置国内镜像源或者提前手动安装依赖的方式解决。

创建项目时，CLI 会在当前目录生成新的项目文件夹，名称为用户输入的项目名称。文件夹内已经包含基础的前端模板、智能体示例和工具接口示例，为后续开发打下坚实基础。

---

1.2 填写项目信息与模板选择

创建项目时，CLI 会提示输入项目名称并选择模板。例如，输入以下信息：

Please input the project name: matechat-project
Please select the template: Vue Starter

项目名称用于创建对应的文件夹，并在内部配置文件中标识整个项目。选择模板时，Vue Starter 模板是最常用的入门模板，它已经内置基础对话界面、示例智能体以及工具调用示例。这个模板支持热更新开发环境，开发者可以在修改源码后立即看到效果，无需手动刷新页面。

选择 Vue Starter 模板后，CLI 会自动生成一套可运行的前端界面。你可以直接启动开发环境，验证默认智能体的对话能力。例如，在浏览器聊天窗口中输入“你好”，系统会返回示例回应，实现基本交互。对于初学者来说，这一模板既可以作为快速验证概念的环境，也可以作为进一步开发和扩展的基础框架。

值得注意的是，CLI 还提供了其他模板选择，例如仅包含前端页面或更高级的智能体配置模板。不同模板的差异主要在于界面组件、默认智能体功能以及工具接口的完整性。开发者可以根据自己的项目需求选择最合适的模板。

---

1.3 安装依赖并启动开发环境

在项目创建完成后，需要进入项目目录并安装依赖：

cd matechat-project
npm install
npm run dev

这一步会根据 package.json 文件中的依赖列表，自动下载所需的 npm 包，包括 Vue、Vite、TypeScript 及相关前端工具。安装完成后，运行 npm run dev 可以启动开发服务器，浏览器会自动打开项目主页。

启动成功后，左侧会显示完整的聊天窗口，可与默认智能体进行交互。右侧提供工具栏，支持调用内置工具，例如计算器或知识库查询。热更新功能保证在修改代码后，页面会自动刷新，开发者可以即时验证修改效果。这一机制显著提高了开发效率，使得功能迭代变得非常便捷。

在开发过程中，你可以通过修改 src/components 中的 Vue 组件来调整界面样式，或修改 src/agents 文件夹中的智能体配置文件来改变智能体的对话策略。对于希望快速扩展功能的开发者来说，这种模块化结构提供了高度灵活性。

---

2. 项目目录结构解析

创建完成的项目目录结构如下所示：

matechat-project/
├── index.html              应用入口 HTML
├── package.json            项目依赖及启动脚本
├── README.md               项目说明文档
├── tsconfig.json           TypeScript 基础配置
├── tsconfig.app.json       应用特定配置
├── tsconfig.node.json      Node 环境配置
├── vite.config.ts          Vite 构建工具配置
├── public/                 静态资源目录
└── src/                    Vue 前端源代码目录

index.html 文件是应用的入口模板，Vue 应用挂载在此页面上，所有的前端组件最终都会渲染到这个页面。package.json 中包含项目的依赖和启动脚本，方便开发者通过 npm 命令管理项目。TypeScript 相关配置文件包括基础配置和应用特定配置，保证在不同环境下都能正常编译。

vite.config.ts 提供 Vite 构建工具的配置信息，用于前端开发和生产环境打包。public 目录用于存放静态资源，例如图片、图标等，而 src 目录则是前端源代码的核心，包括 Vue 组件、页面逻辑、样式以及智能体相关配置。通过查看 src 目录，你可以清楚地看到默认智能体和工具接口的实现逻辑，以及各模块之间的调用关系。

启动开发环境后，浏览器会显示完整的聊天界面。左侧是对话窗口，可以与默认智能体互动。右侧是工具栏，可以调用预置的工具接口，例如输入计算表达式或查询知识库。开发者可以通过调整 Vue 组件或智能体配置，快速验证界面和功能修改效果。

---

3. 模型适配与真实对话

在默认情况下，MateChat 应用使用 Mock 数据进行对话。这种方式适合开发和测试，但在生产环境下，需要接入真实模型才能实现智能对话。要启用真实模型，需要在 src/models/config.ts 文件中修改如下配置：

export const MODEL_CONFIGS = {
  enableMock: false, // 关闭 Mock 数据
};

应用默认接入了 DeepSeek 模型，并通过 LLM_MODELS 配置进行管理。完整示例如下：

export const LLM_MODELS: LLMModelsConfig[] = [
  {
    providerKey: LLMProviders.DEEP_SEEK,
    apiPath: "https://api.deepseek.com",
    apiKey: "", // 填入你的 API Key
    models: [
      { name: "deepseek-chat", iconPath: DeepSeekIcon },
      { name: "deepseek-reasoner", iconPath: DeepSeekIcon },
    ],
    available: true,
    clientKey: LLMClientKey.openai,
  },
];

说明

• providerKey：模型提供商标识；
• apiPath：API 请求地址；
• apiKey：个人申请的 API Key，用于调用模型接口；
• models：可用模型列表及对应图标；
• available：是否启用该模型；
• clientKey：客户端 Key 类型，默认为 OpenAI。

模型配置与应用的模块化结构紧密结合，开发者可以在 src/agents 中配置智能体逻辑，在 src/tools 中添加工具接口，而 LLM_MODELS 则管理模型接入，实现前端、逻辑层与模型服务的分离，保证系统可扩展性和维护性。

---

结语

通过 MateChat 官方 CLI，开发者可以在几分钟内创建可运行的智能聊天应用。结合 Vue 前端模板、默认智能体、工具接口和模型适配功能，开发者可以快速实现真实智能对话。整个项目结构清晰，模块化设计便于后续扩展，无论是用于快速概念验证，还是构建企业级智能聊天系统，create-matechat 都提供了高效便捷的起点。

掌握 CLI 的使用和模型接入配置，将显著提升智能应用开发效率，让开发者将更多精力投入到智能体创新、工具开发和业务逻辑扩展上。未来，随着模型能力和工具接口的丰富，开发者能够在 MateChat 项目基础上快速构建功能强大的智能聊天系统，满足不同场景下的需求。

参考资料

1. MateChat：https://gitcode.com/DevCloudFE/MateChat
2. MateChat官网：https://matechat.gitcode.com
3. DevUI官网：https://devui.design/home