企业官网建设流程全解析

构建工具选型看维护成本

在大型前端工程里引入 Agent 工作流和 AI 代码补全时，很多团队习惯直接把开源插件或者第三方 SDK 往现有的 Vite 项目里塞。跑 Dev 开发模式时一切正常，一旦敲下vite build压测打包，各种 ESM 与 CommonJS 混搭冲突、AST 解析崩溃以及开发/生产环境代理脱节的问题接踵而至。

大模型 Agent 的工具调用（Tool Calling）机制需要读取大量的工程上下文，包括目录结构、TypeScript 类型定义甚至组件 Schema。如果选型不当或者构建插件设计得太轻率，很容易把开发阶段的代理逻辑误打包进生产 Bundle 中，带来严重的代码安全风险与体积膨胀。

我们需要清楚地识别目前主流 AI 前端构建工具链的方案差异，并编写一个符合 Vite 规范且严格区分环境安全界限的 AI 上下文编排插件。

1. 选型评估：开源 AI 构建插件的坑与版本差异

目前开源社区里用于前端工程与 AI/Agent 衔接的构建插件主要分为两类：开发期 Dev-Server 代理方案与编译期 AST 模式注入方案。

下表列出常见方案的设计差异；具体兼容性应以所用插件、Vite 版本和项目配置为准：

若插件把开发期上下文序列化到客户端，提示词、内部接口描述或其他不应公开的配置可能进入产物。构建产物应作为发布前检查项。

原则是：仅在可信的开发环境暴露 Agent 工具接口；生产构建应不包含该接口及其上下文，并通过产物扫描确认。

2. 架构设计：基于 Vite 钩子的 Agent 工具编排链路

我们设计了一个专为 Vite 工程打造的 AI Agent 上下文编排插件。它在开发阶段拦截 HTTP 协议，为 Agent 提供安全的代码结构查询工具；在打包阶段则彻底切断所有 Node 侧能力。

该架构将开发期接口与生产构建分开。是否真正剥离仍需检查最终产物和部署配置。

3. 代码实现：自定义 Vite Agent 编排插件

下面是使用 TypeScript 开发的 Vite 插件vite-plugin-agent-context的完整实现。

import { Plugin, ViteDevServer } from 'vite'; import fs from 'fs'; import path from 'path'; interface AgentPluginOptions { enableInProduction?: boolean; contextDir?: string; } export function vitePluginAgentContext(options: AgentPluginOptions = {}): Plugin { const { contextDir = 'src/components' } = options; const VIRTUAL_MODULE_ID = 'virtual:agent-context'; const RESOLVED_VIRTUAL_ID = '\0' + VIRTUAL_MODULE_ID; let isBuildCommand = false; return { name: 'vite-plugin-agent-context', // 1. 钩子：获取当前 Vite 执行环境命令 configResolved(config) { isBuildCommand = config.command === 'build'; }, // 2. 钩子：解析虚拟模块，便于前台逻辑无缝 import resolveId(id) { if (id === VIRTUAL_MODULE_ID) { return RESOLVED_VIRTUAL_ID; } return null; }, // 3. 钩子：加载虚拟模块内容 load(id) { if (id === RESOLVED_VIRTUAL_ID) { if (isBuildCommand) { // 生产环境打包时，注入空存根对象，实现 Tree-shaking 安全剥离 return `export const agentTools = null; export const isAgentActive = false;`; } // 开发模式下，注入代理访问标识 return ` export const isAgentActive = true; export const agentTools = { queryComponentSchema: async (name) => { const res = await fetch(\`/__agent_api/schema?name=\${name}\`); return res.json(); } }; `; } return null; }, // 4. 钩子：仅在 Dev Server 模式下拓展中间件，为 Agent 提供安全接口 configureServer(server: ViteDevServer) { server.middlewares.use(async (req, res, next) => { if (!req.url?.startsWith('/__agent_api/schema')) { return next(); } const urlParams = new URLSearchParams(req.url.split('?')[1]); const compName = urlParams.get('name') || ''; const contextRoot = path.resolve(server.config.root, contextDir); const safePath = path.resolve(contextRoot, `${compName}.tsx`); // 限制只能读取组件目录下的简单文件名，避免路径穿越。 const isValidName = /^[A-Za-z0-9_-]+$/.test(compName); const isInContextDir = safePath.startsWith(`${contextRoot}${path.sep}`); if (isValidName && isInContextDir && fs.existsSync(safePath)) { const content = await fs.promises.readFile(safePath, 'utf-8'); res.setHeader('Content-Type', 'application/json'); res.end(JSON.stringify({ name: compName, rawCode: content, status: 'success' })); } else { res.statusCode = 404; res.end(JSON.stringify({ error: 'Component Not Found', status: 'failed' })); } }); }, }; }

在vite.config.ts中注册该插件：

import { defineConfig } from 'vite'; import react from '@vitejs.plugin-react'; import { vitePluginAgentContext } from './plugins/vitePluginAgentContext'; export default defineConfig({ plugins: [ react(), vitePluginAgentContext({ contextDir: 'src/components', }), ], });

前端可按以下方式引用虚拟模块：

import { isAgentActive, agentTools } from 'virtual:agent-context'; if (isAgentActive && agentTools) { // 开发环境下让 Agent 获取组件 Schema agentTools.queryComponentSchema('UserProfile').then(data => { console.log('[Dev Agent] 成功获取组件上下文:', data); }); }

4. 版本升级坑点与规避策略

在将这套插件从 Vite 4 升级适配到 Vite 5 / Vite 6 的过程中，我们需要特别防范三个破坏性变动：

1. Module Runner 架构变更：Vite 5/6 升级了 SSR 模块运行器。如果插件直接在transform钩子里用 Node 的require加载 TS 文件，会导致模块缓存失效。必须使用server.ssrLoadModule来解析 AST。
2. CJS 导出包的处理：部分老旧的 Agent SDK 使用了 CommonJS 导出。必须在 Vite 配置里的optimizeDeps.include中将其显式列出，强制预构建为 ESM 格式，否则 Dev Server 会频繁弹出 504 Outdated Optimize Dep 警告。
3. 安全注入防御：不要在开发中间件里允许 Agent 传递绝对路径（如/etc/passwd或工程根目录外的路径）。所有的 File System 读写操作，必须经由path.resolve校验是否处于server.config.root安全沙盒之内。

将开发工具接口、文件访问范围和生产产物检查纳入发布流程，才能把 AI 工具链的风险控制在可审查范围内。