FastGPT智能体对话框HTML渲染实战：从消息协议到iframe沙箱

1. 为什么要在FastGPT智能体里专门做对话框和HTML渲染

前阵子接了个内部项目：在FastGPT上搭一个智能体，用户问销售数据的时候，不能只回一堆Markdown文字，而是要在对话框里直接渲染出一张带进度条、图表、跳转链接和申请按钮的报表卡片。打开需求文档的瞬间我就知道，这事儿的核心根本不是“怎么让模型回答得更准”，而是“怎么让回答内容在对话框里以HTML形式变成可交互的组件”。

FastGPT默认的对话框输出链路很清晰：模型生成Markdown -> 前端解析渲染。这个链路应付普通问答、知识库引用、列表展示完全够用。但一旦业务方想要更多——按钮触发下一步、卡片里嵌表单、点击明细跳转新页面——Markdown就彻底不够了。Markdown可以表达结构和样式，但表达不了“事件”和“状态”。按钮点击之后干什么、表单提交之后怎么回传、图表数据从哪里加载，这些都需要一个HTML渲染层，而不是简单的文本渲染。

还有一个容易被忽视的问题：对话框本身不只是“输入框+消息列表”。在FastGPT智能体开发里，对话框就是用户和系统之间的完整交互界面，它要负责会话状态的延续、历史消息的展示、流式输出的中间态、以及富内容的最终呈现。如果只把HTML渲染做成“把字符串塞进innerHTML”，后面每一步都会踩坑。

这个项目最终的目标我拆成了三条：

• 用户问题进入FastGPT，智能体根据意图决定回复普通文字还是渲染HTML卡片。
• 对话框前端能识别消息类型，对HTML卡片做安全的、隔离的渲染。
• 卡片里的按钮、表单能和对话框主页面通信，再把用户操作作为新的对话消息发回给FastGPT，让上下文保持连贯。

说白了，HTML渲染不是给对话框“美化一下”，而是给智能体扩展出一种新的表达能力。下面我会按照方案选型、渲染层实现、工作流设计和踩坑记录的顺序，把整条链路完整讲一遍。

1.1 当Chatbot不只是一问一答

很多团队用FastGPT做智能体，一开始就是“问答机器人”。用户问，机器人答，答完结束。但实际业务场景里，问答往往是一个动作的开始。比如员工问“我这个月还剩几天年假”，真正的需求可能不仅是要一个数字，而是想要一个“申请休假”的入口。如果智能体的回答是纯文本，用户还得自己去OA系统里找入口；如果回答是一张带剩余天数、申请按钮、最近请假记录的HTML卡片，这个问题就被完整闭环了。

所以智能体开发的思考起点，应该从“回答一个问题”转变成“完成一次交互”。对话框就是承载交互的容器。HTML渲染就是让交互变得可落地的技术手段。

1.2 项目需求与最终效果

我们这个智能体定位是“经营数据分析助手”。使用场景有三种：一，销售问“华东区域上个月业绩完成率”，智能体返回一张带进度条的汇总卡片，点击卡片上的“查看明细”能展开表格；二，运营问“本周用户反馈最多的三个问题”，智能体返回分类列表，每条后面有“生成工单”按钮；三，普通聊天，比如“你是谁”“你能做什么”，智能体用Markdown返回就行。

这个设计从一开始就把“内容形态”和“内容场景”绑定了。不是所有回答都适合HTML卡片，卡片化是重表达，只用在数据密度高、操作意图强的场景。

1.3 对话框要承担的三个职责

在开发过程中，我把对话框拆成三个层次：

• 会话层：维护历史消息，把多轮上下文传给FastGPT。
• 消息层：负责消息的增删改、流式状态、错误处理。一条消息在发送前是loading，发送中是流式文本，发送完成后可能是文本、Markdown、HTML卡片或错误提示。
• 渲染层：根据消息类型选择渲染器。纯文本走普通文本渲染，Markdown走markdown-it，HTML卡片走iframe沙箱渲染器。

这三个层次分开之后，HTML渲染就成了一个独立的渲染器，不会污染原有的聊天逻辑。FastGPT的对话接口只要返回结构化消息，前端就能自动选择渲染方式。

2. 对话框方案选型：在自研页面里接入FastGPT的消息流

先选对话框的实现方式。FastGPT本身有二开能力，但直接把它的开源前端页面拿来改，维护成本和升级成本都比较高。我更倾向于在自研的管理系统里，用FastGPT的API通道做一个独立对话框组件。

2.1 三种接入路径的对比

我把方案比了一圈，列在下面：

我最终选了第二个方案。理由很简单：HTML渲染层需要和业务系统里的登录态、权限、菜单深度联动，iframe方式会把通信变成一个绕不开的坎，自带页面二开又会受限于上游结构。

2.2 定义消息协议：让前端知道“这段内容怎么渲染”

自建对话框最大的好处，是可以自己定义消息协议。Fas