Cactus's Blog

Cactus li...大约 5 分钟

一、本章介绍

完成脚手架服务接口与前端 UI 的集成，实现服务端核心能力的可视化展示。

在实际业务落地过程中，基于 AI Agent 脚手架构建的应用，通常不仅提供基础的智能体服务能力，还会结合具体业务场景对外开放接口。这些接口能够与客服问答、智能巡检、数据分析、量化决策、风险控制等多种业务系统进行集成，为企业构建智能化应用提供统一的服务支撑。

二、对接效果

1. 登录页

2. 对话页

对话，可以填写信息，发送请求。在一个会话ID下，它是可以记录历史上下文信息的。

三、流程设计

如图，页面UI与服务端接口对接设计；

![AI Agent 脚手架-会话服务接口对接-ui.drawio](https://beauties.eu.org/blogimg/main/img1/AI Agent 脚手架-会话服务接口对接-ui.drawio.png)

在项目里 docs/dev-ops/nginx 下增加 html 文件夹，编写 login.html、index.html 页面。
前端页面对接服务端接口，启动应用加载智能体列表、新建会话、发起对话。另外，如果服务端接口不可用，会在页面提示出来，要启动服务端。

四、功能实现

1. 工程结构

在 docs/dev-ops/nginx 目录中新增了 HTML 静态页面资源，用于部署到 Nginx 环境中，实现前后端分离架构的本地联调与展示。

同时补充了用于 AI 辅助开发的 Prompt 提示词，这些提示词可配合 AI IDE（如 Trae.ai、JoyCode、Claude 等）使用，提升页面开发效率与实现质量。

另外，对 AgentServiceController 中的 createSession 接口进行了调整，将其请求方式修改为 POST，以符合接口语义及数据提交规范。

2. 页面开发（AI）

在 docs/dev-ops/nginx/html 下。开发 login.html 页面一个ai智能体的登录页面，左侧展示信息，以及ai的效果图，右侧是登录信息。账号，密码，先有一个默认的 admin admin。登录后，保存 cookie 信息。

在对话框中输入提示词信息，html 可以选中拖进去。
不过可能一次生成的不是太好，那么可以把生成的内容删掉，让再次生成下。

2.2 index

index 页面的提示词会多一些。
如果生成完，并不能完整使用，可以f12看到浏览器报错，之后让 ai 来处理。

3. 对接说明

3.1 目录结构

静态页面目录：docs/dev-ops/nginx/html
- login.html：演示登录（默认 admin/admin），写入 cookie 后跳转 index.html
- index.html：对话页面（未登录跳转 login.html）
- images/ai-hero.svg：页面效果图
- js/config.js：前端配置（服务端地址）

3.2 前端配置（API_BASE）

前端通过 js/config.js 提供后端根地址：

文件：docs/dev-ops/nginx/html/js/config.js
配置项：window.APP_CONFIG.API_BASE
默认值：https://127.0.0.1:8091

index.html 会读取该配置，拼接为完整接口地址（例如：${API_BASE}/api/v1/query_ai_agent_config_list）。

cookie 名称：ai_agent_login
cookie 内容（JSON 字符串）：{"user":"admin","ts":<登录时间戳>}
login.html：
- 登录成功写入 cookie
- 已存在 cookie 时直接跳转 index.html
index.html：
- 读取 cookie 获取 userId（即 payload.user）
- 未获取到 userId 则跳转 login.html

说明：该登录逻辑用于静态页面演示；真实系统可替换为后端鉴权接口并按需设置 cookie 策略。

3.4 接口与后端位置

后端控制器：

AgentServiceController.java

接口基础前缀：

/api/v1/

统一响应结构（泛型包装）：

Response.java
成功码：code = "0000"（见 ResponseCode.java）

1）查询智能体列表

方法：GET
路径：/api/v1/query_ai_agent_config_list
用途：渲染下拉框智能体列表（展示 agentName，value 为 agentId）
前端调用：index.html 启动时加载

响应示例（简化）：

{
  "code": "0000",
  "info": "成功",
  "data": [
    {
      "agentId": "xxx",
      "agentName": "智能体名称",
      "agentDesc": "描述"
    }
  ]
}

2）创建会话

推荐方式（浏览器更友好）：

方法：POST
路径：/api/v1/create_session
Content-Type：application/json
请求体：

{
  "agentId": "xxx",
  "userId": "admin"
}

响应体（简化）：

{
  "code": "0000",
  "info": "成功",
  "data": { "sessionId": "S-2026..." }
}

兼容方式（可用于手工验证）：

方法：GET
路径：/api/v1/create_session?agentId=xxx&userId=admin

前端调用策略（index.html）：

点击【新建】：立即创建新的 sessionId 并作为“当前会话”
首次【发送】但尚未创建会话：自动创建一次会话
后续发送：复用当前 sessionId
切换智能体：会清空当前 sessionId，避免串会话

3）对话

方法：POST
路径：/api/v1/chat
Content-Type：application/json
请求体字段：
- agentId：下拉框选择的智能体
- userId：从 cookie 读取的登录用户
- sessionId：当前会话 ID（由 create_session 返回）
- message：用户输入

请求体示例：

{
  "agentId": "xxx",
  "userId": "admin",
  "sessionId": "S-2026...",
  "message": "你好，介绍一下你能做什么？"
}

响应体示例（简化）：

{
  "code": "0000",
  "info": "成功",
  "data": { "content": "智能体回复内容..." }
}

页面渲染：

用户消息：左侧气泡（user）
智能体回复：右侧气泡（agent）

3.5 页面时序（从登录到对话）

访问 login.html
输入 admin/admin（演示）
写入 cookie ai_agent_login，跳转到 `index.html``
``index.html校验 cookie，读取userId`
加载 js/config.js 获取 API_BASE
调用 GET /api/v1/query_ai_agent_config_list 获取智能体列表
选择智能体
点击【新建】创建会话（或首次发送时自动创建）
每次发送调用 POST /api/v1/chat 获取回复并渲染

3.6 服务端不可用时的提示策略

当浏览器出现以下常见问题时（服务端没启动、端口不通、跨域失败导致 fetch 抛错）：

页面会弹出“服务端接口不可用”的遮罩弹窗
弹窗会提示检查 docs/dev-ops/nginx/html/js/config.js 的 API_BASE 是否被更换
弹窗提供“我已启动，重试”：重新拉取智能体列表

3.7 常见问题排查

页面提示“服务端接口不可用”
- 检查后端服务是否启动、端口是否为 8091
- 检查 docs/dev-ops/nginx/html/js/config.js 的 API_BASE 是否正确
浏览器控制台出现 CORS 错误
- 确认后端允许跨域（控制器已使用 @CrossOrigin(origins = "*")）
create_session 无法调用
- 浏览器不支持 GET 携带 body，建议使用 POST JSON（页面已按 POST 调用）