ai draw.io 前端工程初始化：基于 React 搭建 AI Agent 智能绘图场景的环境与工程准备

• 文档
• 教程
• 后端

导读：本节是《AI Agent 场景应用 - ai draw.io》第 4 部分的第一个实操环节，核心任务是初始化 ai draw.io 的前端工程。由于 draw.io 的开发插件基于 React 语言构建，因此前端工程同样选择 React 技术栈。读完本节，你将掌握 Node.js 环境的安装与 npm 镜像源配置、WebStorm 开发工具的准备，以及 TypeScript 的快速入门路径，为后续基于 AI IDE 完成页面嵌入、接口对接与交互式画图打下工程基础。

一、本章诉求：为什么要先初始化前端工程

ai draw.io 是 AI Agent 脚手架 + 场景应用 项目第 4 部分的业务场景，它的目标非常明确：基于 AI Agent 智能体脚手架，在 draw.io 场景下，使用 React 开发一套 AI 智能绘图功能（详见 第4-0节：ai + draw.io 产品设计）。

而本节的诉求只有一件事——初始化搭建 ai draw.io 前端工程。之所以选择 React，原文给出的理由非常直接：

draw.io 的开发插件是 React 语言的，所以我们也要基于 React 语言构建工程。

也就是说，技术选型不是拍脑袋，而是由后续要嵌入的 react-drawio 组件决定的。react-drawio 把 draw.io 编辑器以 React 组件的形式封装出来，提供了相关的 API 操作，既能将 AI 生成的 XML 渲染到 draw.io 面板上，也能读取面板内容再交给 AI 分析和调整。因此前端工程必须与它保持同语言、同生态，才能以最小的成本完成嵌入与双向通信。

从项目笔记（notes.md）中可以进一步确认，该场景的简历级核心技术栈包含：React、Draw.io (mxGraph)、TypeScript、Maven Archetype、Docker、Nginx等，其中前端正是 React + TypeScript 的组合。

二、场景定位：前端工程在整个项目中的位置

在动工之前，先看清本节在整个课程体系中的坐标。整体项目分为 5 个部分：

第 4 部分的 6 节课是一条完整的链路：

1. 第4-0节：ai + draw.io 产品设计 —— 场景定位与产品效果设计；
2. 第4-1节：初始化工程搭建（本文）—— React 前端工程从 0 到 1；
3. 第4-2节：在页面嵌入draw.io组件和对话框 —— 引入 react-drawio，页面右侧放置对话框；
4. 第4-3节：智能体API接口对接 —— 创建会话 SessionID、调用对话接口进行绘图；
5. 第4-4节：AI+用户+DrawIO，交互式画图 —— 分析、绘制、检查的多智能体流程增强；
6. 第4-5节：ai-draw-io，云服务器部署 —— 前后端 Docker 化部署。

可以看到，本节是第 4 部分的地基工程，后续所有画图、对话、部署操作都建立在这套 React 工程之上。

三、开发环境准备

原文档对本节的开发环境给出了明确的要求清单，这是初始化工程前必须完成的准备工作，逐项落实即可。

1. Node.js v20+

前端工程基于 React 构建，而 React 工程的依赖安装、脚本运行都依赖 Node.js 运行时，因此第一步是安装 Node.js，版本要求 v20 及以上。可以直接从 Node.js 官网下载对应操作系统的安装包安装，安装完成后可以在终端验证版本：

node -v npm -v

确保node -v输出为v20.x或更高版本，npm -v能正常输出版本号，即表示 Node.js 与 npm（Node 包管理器）环境就绪。npm 随 Node.js 一同安装，后续无论是安装 react-drawio、Vite 等依赖，还是运行构建脚本，都依赖它。

2. WebStorm 2023.1

开发工具建议使用WebStorm 2023.1。原文档给出的理由是：WebStorm 自带了一整套开发前端的工具能力（代码提示、调试、内置终端、版本管理等），因此对前端开发"非常好用"。对于长期做后端、初次接触前端工程的程序员，使用这类开箱即用的 IDE 可以显著降低环境配置的心智负担。

说明：工具本身是可替换的，VSCode 等同样可以胜任。选择 WebStorm 更多是出于开箱即用的体验考虑，并非工程硬性依赖。

3. 配置 npm 镜像源（关键一步）

安装好环境后，务必先设置 npm 源地址。原文档特别强调：如果不配置，后续构建项目会非常慢。执行以下命令即可：

npm config set registry https://registry.npmmirror.com

registry.npmmirror.com是国内的 npm 镜像源，将 npm 默认的官方源切换为国内镜像后，npm install下载 react、react-drawio、TypeScript 等依赖的速度会有质的提升。配置完成后，可以通过以下命令确认是否生效：

npm config get registry

输出https://registry.npmmirror.com即表示镜像源配置成功。

4. TypeScript 学习资料

由于前端工程使用 TypeScript，原文档建议先花少量时间了解 TypeScript 的语言结构。原文特别点出了对后端程序员友好的一个重要事实：

TypeScript 的语言结构比较清晰，甚至和我们学习的 Java 是有类似的地方的。

TypeScript 作为 JavaScript 的超集，引入了类型系统、接口、泛型等面向对象能力，这与 Java 的思维模式天然契合。有 Java 基础的同学看 TypeScript 代码基本没有障碍——所有的面向对象语言代码，核心概念是通用的。原文档给出的学习路径是两份入门教程（菜鸟入门教程 + TypeScript 中文文档），可以作为课下补充材料。

四、工程初始化实操要点

1. 技术栈定位：React + TypeScript

工程的技术栈是React + TypeScript。这一点可以从多个仓库文档相互印证：

• 第 4-0 节产品设计明确指出要"使用 react 开发一套 ai + draw.io 智能绘图功能场景"；
• 项目笔记（notes.md）的核心技术清单中列有React、Draw.io (mxGraph)、TypeScript；
• 后续第 4-5 节部署文档中提到前端页面运行在3000 端口，这符合 React 工程本地开发服务的常见约定。

初始化一个 React + TypeScript 工程的方式有很多（如 Vite、Create React App 等），从仓库文档无法确认具体采用的脚手架工具，实操时选择你熟悉的任一种 React 工程初始化方式即可。核心是：工程创建完成后，语言是 TypeScript，框架是 React，且能正常启动一个跑在 3000 端口的开发服务。

2. 为什么这节对后端程序员很友好

原文档给出了一个非常务实的定位——这部分前端的内容，会使用即可：

• 初始化工程搭建完成后，就可以基于 AI IDE 工具（如 Cursor、Trae、通义灵码等任一款）来完成后续开发，前端页面、组件、接口对接的代码可以大量借助 AI 生成，开发效率远高于手写；
• 对后端程序员来说，找工作一般后端岗位不会考察前端细节，所以前端部分仅仅是当做使用即可，重点精力仍应放在后端智能体脚手架的装配与编排能力上。

也就是说，本节的目标不是让后端同学成为前端专家，而是搭好一个能跑的 React 工程底座，让后续的 AI IDE 编程、页面嵌入、接口对接有地方落地。

3. 初始化完成后的"最小可运行"标准

从后续课程的衔接来看，工程初始化完成后应当满足以下最小标准，才算是合格：

1. npm install能顺利安装依赖（依赖镜像源配置正确，开发环境准备 的第 3 步在此发挥作用）；
2. 开发服务能正常启动，浏览器可访问前端页面（后续第 4-5 节部署时前端对应 3000 端口）；
3. 工程内已预留引入 react-drawio 的基础目录结构（第 4-2 节会在初始页面中引入 react-drawio 组件，并在右侧放置对话框）。

五、初始化之后：前端工程将要承载的能力

为了让本节的工作更有画面感，这里提前预告一下这套前端工程后续要承载的核心能力（均来自仓库中后续章节文档）：

• 嵌入 draw.io 编辑器：通过 react-drawio 将 draw.io 嵌入到初始页面，实现"AI 生成 XML → draw.io 渲染"的闭环（第4-2节）；
• 对接智能体 API：前端打开页面时加载智能体列表 → 选择智能体创建会话 SessionID → 调用对话接口，服务端以 draw.io XML 格式返回结果并渲染到面板上（第4-3节）；
• 交互式画图：服务端智能体按"分析 → 绘制 → 检查"流程工作，信息不全时以 JSON 类型返回让用户补充，前端按user（对话）与drawio（XML 渲染）两种类型分发处理，并增加对话历史记录、浏览器本地保存绘图等能力（第4-4节）；
• 云服务器部署：前端与后端分别构建 Docker 镜像，在 2c4g 云服务器（Ubuntu 24）上通过 Docker + Portainer 完成部署，并开放9000（管理面板）、8091（后端接口）、3000（前端页面）端口（第4-5节）。

六、小结

本节完成的工作可以概括为一句话：搭好 React + TypeScript 的 ai draw.io 前端工程，并备齐 Node.js v20+、WebStorm、npm 镜像源、TypeScript 基础四样开发前提。

理解本节时有三个重点值得反复体会：

1. 技术选型跟随生态：因为 draw.io 插件是 React 生态，所以前端工程选择 React，这是"场景决定技术"的典型例子；
2. 环境配置先行：npm 镜像源配置虽是一行命令，却直接决定后续所有依赖安装的速度，是新手最容易忽略、也最影响体验的一步；
3. 定位是"会用即可"：前端部分对后端程序员友好，初始化完成后即可借助 AI IDE 工具完成后续开发，核心精力应放在智能体后端能力的构建上。

工程底座就绪后，下一节将正式进入 在页面嵌入 draw.io 组件和对话框，开始绘制这套智能绘图系统的第一块界面拼图。

• 文档
• 教程
• 后端