可嵌入任意 .NET 业务项目的对话式数据查询 AI Agent
系统概述
本系统是一套可嵌入任意 .NET 业务项目的对话式数据查询 AI Agent。用户用自然语言提问，系统自动：
1. 从已学习的 API Index 中匹配最合适的接口；
2. 将自然语言参数（如「上海」「上个月」「大于1000」）绑定为 API 查询参数；
3. 以 只读 GET 方式调用业务系统现有 API；
4. 以表格 + ECharts 图表展示结果。
1.1 系统架构
下图展示各组件之间的关系与数据流向。
图 1-1 系统架构总览
|
组件 |
端口（默认） |
作用 |
|
API Scanner |
CLI / 3100 |
扫描前端源码，生成 API Index |
|
API Index Server |
3100 |
提供 Index 的 REST 查询/重建 |
|
AI Agent 服务 |
5100 |
自然语言理解、API 匹配与调用 |
|
Chat UI |
8080（开发）/ 随 Agent 静态托管 |
对话界面 Web Component |
|
业务系统 API |
5200（示例） |
您现有的 .NET Web API |
1.2 核心约束
- 不修改业务代码逻辑
- 不依赖 Swagger / OpenAPI / XML 注释
- 不直连数据库写操作，仅通过现有 GET API 只读查询
- 复用原系统 Cookie / JWT 鉴权
2. 环境要求
|
软件 |
版本 |
用途 |
|
Node.js |
≥ 18 |
Scanner、Chat UI 开发服务器 |
|
.NET SDK |
8.0 |
AI Agent 服务、业务 API |
|
npm |
随 Node 安装 |
依赖管理 |
|
浏览器 |
Chrome / Edge 最新版 |
使用 Chat UI |
内网离线环境说明：
- 所有前端 JS（含 ECharts）已本地化，运行时不需要访问公网 CDN。
- 仅首次 npm install 需要联网下载依赖（可提前在有网环境执行后拷贝 node_modules）。
3. 目录结构说明
|
LLM/ ├── scanner/ # Node.js 扫描器 + Index Server │ ├── src/scanners/ # Vue2/Vue3/jQuery/MVC 扫描插件 │ ├── src/server/ # Index REST 服务 │ ├── data/ # 生成的 API Index JSON │ └── package.json ├── agent/ # .NET 8 AI Agent │ └── src/ │ ├── AiAgent.Api/ # Web API + 静态文件托管 │ ├── AiAgent.Core/ # 领域模型 │ └── AiAgent.Infrastructure/ ├── chat-ui/ # Web Component 聊天组件 │ ├── vendor/echarts.min.js # 本地 ECharts（无 CDN） │ ├── ai-chat-agent.js │ ├── demo.html │ └── package.json ├── samples/DemoApp/ # 示例业务 API ├── docs/ │ ├── 操作手册.md # 本文档 │ └── images/ # 手册配图 └── package.json # 根目录 npm run dev |
4. 扫描业务项目并生成 API Index
将 AI Agent 接入真实项目前，必须先扫描该项目的前后端代码，生成 API Index。
4.1 确认项目包含可扫描内容
Scanner 支持以下文件类型：
|
框架 |
扫描文件 |
提取内容 |
|
Vue2 |
.vue |
axios.get/post、el-table-column 列名、页面标题 |
|
Vue3 |
.vue |
Composition API 中的 fetch/axios、列名 |
|
jQuery |
.js .html .cshtml |
$.ajax、$.get、fetch、<th> 列名 |
|
MVC |
.cshtml .cs |
Html.BeginForm、@Url.Action、Controller Action |
4.2 执行扫描命令
|
powershell cd d:\项目源码\2026\软件产品\LLM\scanner # 基本扫描（不使用 LLM，适合内网） node src/cli.js scan ^ --project my-sales-system ^ --root "D:\您的项目\前端源码根目录" ^ --no-llm ^ -o ./data # 指定框架（可选） node src/cli.js scan --project my-app --root "D:\path" --framework vue3 --no-llm |
扫描成功后，终端将显示找到的 API 数量及输出文件路径，如下图所示。
图 6-1 Scanner 扫描完成输出示例
参数说明：
|
参数 |
必填 |
说明 |
|
--project |
是 |
项目唯一标识，后续 Chat UI 的 project 属性与之对应 |
|
--root |
是 |
待扫描项目根目录（含 .vue / .cshtml / Controllers 等） |
|
-o / --output |
否 |
Index 输出目录，默认 ./data |
|
--no-llm |
否 |
跳过 LLM 语义推断，使用启发式规则（内网推荐） |
|
--framework |
否 |
强制框架：vue2 vue3 jquery mvc |
4.3 使用 LLM 增强语义（有 OpenAI 兼容 API 时）
|
powershell # 复制并编辑环境变量 copy .env.example .env # 设置 OPENAI_API_KEY、OPENAI_BASE_URL 等 node src/cli.js scan --project my-app --root "D:\path" -o ./data |
LLM 将为每个 API 补充 apiPurpose、paramMeanings、confidence 等字段，提高自然语言匹配准确率。
4.4 通过 Index Server 远程重建
|
powershell # 先启动 npm run serve curl -X POST http://localhost:3100/api-index/rebuild ^ -H "Content-Type: application/json" ^ -d "{\"project\":\"my-app\",\"root\":\"D:\\\\path\\\\to\\\\project\",\"useLlm\":false}" |
4.5 检查生成的 Index
打开 scanner/data/my-sales-system.json，确认关键字段：
|
json { "project": "my-sales-system", "apis": [ { "url": "/api/orders", "method": "GET", "pageTitle": "销售订单查询", "apiPurpose": "按地区、日期查询订单", "agentUsable": true, "confidence": 0.85, "columns": ["订单号", "地区", "金额"] } ] } |
仅 agentUsable: true 且 method: GET 的 API 会参与自然语言匹配。
5. 配置 AI Agent 服务
编辑 agent/src/AiAgent.Api/appsettings.json：
|
json { "Agent": { "ApiIndexServerUrl": "http://localhost:3100", "TargetApiBaseUrl": "http://localhost:5200", "DefaultProject": "demo", "IndexDataPath": "../../../scanner/data", "MaxRows": 1000, "TimeoutSeconds": 5, "Llm": { "Provider": "openai", "ApiKey": "", "BaseUrl": "https://api.openai.com/v1", "Model": "gpt-4o-mini" } } } |
配置项详解
|
配置项 |
说明 |
接入真实项目时 |
|
TargetApiBaseUrl |
业务 API 根地址 |
改为 https://your-app.company.com |
|
DefaultProject |
默认 API Index 项目名 |
改为扫描时的 --project 值 |
|
IndexDataPath |
本地 Index JSON 目录（相对 Agent 运行目录） |
确保包含 {project}.json |
|
ApiIndexServerUrl |
Index Server 地址 |
使用 Index Server 时填写 |
|
Llm.ApiKey |
LLM Key（参数归一化增强） |
内网可留空，使用启发式规则 |
接入真实项目示例：
|
json { "Agent": { "TargetApiBaseUrl": "https://erp.mycompany.local", "DefaultProject": "erp-sales", "IndexDataPath": "../../../scanner/data" } } |
修改配置后需重启 Agent 服务。
6 使用对话查询界面
6.1 打开聊天窗口
访问 http://localhost:8080/demo.html，点击右下角蓝色 💬 按钮打开助手面板。
图 8-1 聊天助手初始界面
6.2 输入自然语言查询
在底部输入框输入问题，点击 发送 或按 Enter。
示例问题：
|
用户输入 |
系统行为 |
|
查一下上海的订单 |
匹配订单列表 API，绑定 region=上海 |
|
上海上个月金额超过1000的订单 |
绑定地区 + 日期范围 + 最小金额 |
|
各地区订单汇总 |
匹配汇总统计 API |
6.3 查看查询结果
成功时界面显示：
1. 摘要：匹配的 API 及用途说明
2. 表格：数据明细（最多显示 20 行）
3. 图表：自动选择柱状图/折线图/饼图
图 8-2 自然语言查询成功（表格 + 图表）
6.4 通过 API 直接调用（供集成测试）
|
powershell $body = '{"query":"查一下上海的订单","project":"demo"}' Invoke-RestMethod -Uri "http://localhost:5100/api/chat/query" ` -Method POST -Body $body -ContentType "application/json" |
返回 JSON 包含 success、table、chart、matchedApi 等字段。
7. 嵌入到现有项目
将 AI Agent 嵌入业务项目分三步：
|
① 扫描目标项目 → 生成 API Index ② 部署/配置 Agent 服务 → TargetApiBaseUrl 指向业务系统 ③ 在业务页面引入 Chat UI 静态资源 |
需要复制的文件（均在 chat-ui/ 或 wwwroot/）：
|
vendor/echarts.min.js # 约 1MB，图表库 ai-chat-agent.js # Web Component 主文件 iframe.html # iframe 方式（可选） |
7.1 嵌入 Vue2 / Vue3 项目
步骤 1：复制静态资源
将以下文件复制到 Vue 项目的 public/ai-agent/ 目录：
|
public/ai-agent/vendor/echarts.min.js public/ai-agent/ai-chat-agent.js |
步骤 2：在 public/index.html 中引入
|
html <!DOCTYPE html> <html> <head> <!-- 其他 head 内容 --> <script src="/ai-agent/vendor/echarts.min.js"></script> <script src="/ai-agent/ai-chat-agent.js"></script> </head> <body> <div id="app"></div> <!-- 全局挂载 AI 助手 --> <ai-chat-agent api-base="https://ai-agent.mycompany.local" project="erp-sales" title="数据助手"> </ai-chat-agent> </body> </html> |
步骤 3：配置 api-base
|
部署方式 |
api-base 取值 |
|
Agent 独立域名 |
https://ai-agent.mycompany.local |
|
与业务 API 同域反向代理 /ai-agent |
https://erp.mycompany.local/ai-agent |
|
开发时 Vite 代理（见下方） |
留空或不设置 |
Vue CLI / Vite 开发代理示例（`vue.config.js`）：
|
javascript module.exports = { devServer: { proxy: { '/api/chat': { target: 'http://localhost:5100', changeOrigin: true } } } } |
此时 api-base 留空，组件自动请求同源 /api/chat/query。
图 9-1 Vue 项目嵌入效果示意
步骤 4：扫描该 Vue 项目
|
powershell node scanner/src/cli.js scan --project erp-sales --root "D:\您的Vue项目" --no-llm |
7.2 嵌入 jQuery / 静态 HTML 项目
步骤 1：复制文件到 Web 根目录
|
wwwroot/ai-agent/vendor/echarts.min.js wwwroot/ai-agent/ai-chat-agent.js |
步骤 2：在页面 </body> 前添加
|
html <script src="/ai-agent/vendor/echarts.min.js"></script> <script src="/ai-agent/ai-chat-agent.js"></script> <ai-chat-agent api-base="http://localhost:5100" project="demo" title="AI 助手"></ai-chat-agent> |
步骤 3：iframe 方式（老项目兼容）
若 Web Component 与旧版 jQuery 冲突，使用 iframe：
|
html <iframe src="/ai-agent/iframe.html" style="position:fixed;right:0;bottom:0;width:420px;height:600px;border:none;z-index:99999;"> </iframe> |
修改 iframe.html 内 api-base 为 Agent 服务地址。
7.3 嵌入 ASP.NET MVC Razor 项目
步骤 1：复制静态文件
复制到 wwwroot/ai-agent/（与 jQuery 方式相同）。
步骤 2：在 _Layout.cshtml 底部添加
|
cshtml @* AI Agent 对话助手 *@ <script src="~/ai-agent/vendor/echarts.min.js"></script> <script src="~/ai-agent/ai-chat-agent.js"></script> <ai-chat-agent api-base="@Url.Content("~/")" project="mvc-demo" title="数据助手"></ai-chat-agent> |
若 Agent 部署在独立站点：
|
cshtml <ai-chat-agent api-base="https://ai-agent.internal" project="mvc-demo"></ai-chat-agent> |
步骤 3：扫描 MVC 项目
|
powershell node scanner/src/cli.js scan --project mvc-demo --root "D:\您的MVC项目" --framework mvc --no-llm |
Scanner 会自动解析：
- Html.BeginForm("Action", "Controller") → POST 路由（标记为不可用于 Agent）
- @Url.Action("GetData", "Report") → GET 路由
- .cs Controller 中的 [HttpGet] + JsonResult → agentUsable: true
图 9-2 MVC 项目嵌入效果示意
步骤 4：鉴权传递
用户登录 MVC 后，浏览器 Cookie 会自动随 Chat UI 的 fetch 请求发送到 Agent；Agent 再转发 Cookie 调用业务 API，无需额外登录。
7.4 嵌入 ASP.NET Core Web API / Blazor 项目
方式 A：Agent 静态文件随 Agent 服务托管（推荐）
1. 执行 npm run sync:wwwroot 将 Chat UI 同步到 AiAgent.Api/wwwroot
2. 业务页面通过 iframe 或跨域 Web Component 引用 Agent 站点
3. 配置业务系统 CORS 允许 Agent 域名（若跨域调用业务 API）
方式 B：与业务 API 同站点部署
1. 将 wwwroot/ai-agent/* 复制到业务项目的 wwwroot/ai-agent/
2. 在业务项目中添加反向代理，将 /api/chat/* 转发到 Agent 服务
3. 页面引用：
|
html <script src="~/ai-agent/vendor/echarts.min.js"></script> <script src="~/ai-agent/ai-chat-agent.js"></script> <ai-chat-agent project="my-api-project"></ai-chat-agent> |
更多推荐
13
0- 0
已为社区贡献1条内容
所有评论(0)