概要

联通最近开源的元景万悟作为央企首个开源的智能体开发平台，支持多租户、license友好并且基于golang开发，基于源码分析智能体URL管理及其页面流式对话的实现思路。功能实现如对外URL生成及解析、对话功能，以后端处理为主。

平台源码网址：

https://github.com/UnicomAI/wanwu.git

基于Readme中一键部署，拉取镜像。

预估的功能：

• 智能体对外URL的管理，包括开关以及到期时间的控制。

• 智能体对话页面的历史信息、历史对话记录、流式问答。

需求分析与设计目标：

• 对已创建的智能体生成一个可供对外使用的URL，并对URL进行管理

  为了便于用户快速分享和传播智能体，系统需要提供URL生成功能。当用户完成智能体的创建和配置后，可以通过管理界面一键生成一个独特的访问链接。该URL应具备一定的时效性，例如可设置7天、30天或永久有效，以满足不同场景下的分享需求。同时，系统需提供URL管理面板，允许创建者查看所有已生成的链接、调整有效期、随时禁用特定URL或批量操作。例如，如果某个链接被泄露或不再需要，管理员可以立即使其失效，确保智能体的访问权限可控。此外，URL问答页面可以附带参数，如版权信息、隐私协议、免责声明等，便于后续统计分析访问渠道的效果。

• 免鉴权访问与时效控制

  智能体生成的URL允许用户无需登录或身份验证即可访问智能体问答，降低使用门槛，适用于临时分享、公开演示或嵌入第三方平台等场景。对于高敏感场景，管理员可以随时在后台手动注销某个URL，使其立即失效。这种灵活的访问控制机制既方便了终端用户的无缝体验，又能保障智能体的数据安全。

• 智能体流式问答与用户会话绑定

  在对话过程中，智能体应支持流式响应（Streaming），即逐字或分片返回答案，而非等待全部生成完毕再一次性返回，从而减少用户等待时间，提升交互流畅度。同时，系统需在后台绑定用户的客户端设备信息，以便区分不同用户的对话历史。这一机制使得即使未登录的用户，其会话也能被唯一标识，后续可通过该标识查询历史记录或进行会话恢复。例如，当用户未清理浏览器缓存时，即使多次通过同一URL访问，系统也可以根据客户端信息自动加载之前的对话上下文，提供连贯的交互体验。

• URL解析与智能体对话页面的前后端协作

  前端需要提供两个核心页面：一是URL生成与管理页面，二是智能体对话页面。当用户访问生成的URL时，前端需解析URL中的参数（如客户端设备信息等），并向后端发起请求，获取对应的智能体配置及权限验证结果。后端需校验URL的有效性，并返回智能体的名称、头像、欢迎语等元数据，供前端渲染对话界面。在对话过程中，前端通过WebSocket或HTTP长轮询与后端保持连接，实时传输用户输入和智能体的流式响应。为提高性能，后端可缓存智能体的配置及会话状态，避免频繁查询数据库。同时，前后端需约定错误处理机制，例如当URL失效时，前端展示友好的提示信息，并引导用户联系管理员或重新获取有效链接。

实现方案：

1. URL生成页面（管理端）

• 功能描述：

  • 智能体创建者可在管理后台生成对外分享的URL，并设置有效期、访问限制等参数。

  • 提供可视化面板管理所有已生成的URL，包括启用/禁用、查看访问统计等。

• 技术实现：

  • 前端：使用React/Vue构建管理界面，提供表单（设置有效期、备注信息）和列表展示（URL状态、访问量等）。

  • 后端：

    • 处理URL生成请求，生成规则为：

      http://${EXTERNAL_IP}:${EXTERNAL_PORT}/webChat/[uuid]

      其中 uuid 为随机生成的唯一标识符（如v4 UUID）。

    • 数据库存储 uuid、智能体ID、创建时间、过期时间、是否禁用等字段。

    • 提供API供前端查询URL列表、修改状态（如禁用）、延长有效期等。

2. 智能体对话页面（用户端）

• 功能描述：

  • 用户通过分享的URL直接进入对话界面，无需登录即可与智能体交互。

  • 页面动态加载智能体配置（名称、头像、欢迎语），并支持流式问答。

• 技术实现：

  • 前端：

    • 基于URL解析 uuid，调用后端API获取智能体元数据并渲染页面。

    • 使用 WebSocket 或 SSE 实现流式对话，实时显示智能体回复。

    • 记录客户端信息（如IP、User-Agent）并随每条消息发送至后端，用于会话绑定。

  • 后端：

    • 校验 uuid 是否有效（未过期、未禁用），若无效返回错误提示。

    • 通过 uuid 关联智能体，返回其配置信息（如模型参数、提示词）。

    • 处理对话逻辑时，结合客户端信息生成会话ID，用于存储和检索历史记录。

3. URL唯一标识（UUID）的设计

• 生成规则：

  • 使用 UUID v4 或 NanoID 生成高随机性、无规律的字符串，避免被枚举攻击。

  • 示例：

    http://${EXTERNAL_IP}:${EXTERNAL_PORT}/webChat/3fa2b5c1-2e8a-4fe5-bc3d-9e8f7a6b5c4d

  • 长时效：过期时间置空默认生成永久有效的URL，提升用户体验。

4. 智能体对话的客户端信息绑定

• 绑定方式：

  1. 基础信息：

     • 自动采集用户客户端信息、User-Agent、访问时间等。

     • 前端生成 设备ID（确保匿名但唯一）。

  2. 会话维持：

     • 前端存储 session_id 到 LocalStorage，同一浏览器多次访问可恢复会话。

     • 根据客户端信息哈希生成唯一 client_id，用于关联历史对话。

总结：

本篇我们讲完了这座"桥梁"是怎么设计和搭建的。

简单来说，这个功能就是为了让分享智能体对话工具像分享一个视频链接一样简单。

• 对使用者：无需下载和注册，点开链接就能直接聊天，体验流畅。

• 对创建者：拥有完全控制权，可以灵活管理链接的生效状态和期限，不用担心安全风险。

接下来，我们会带大家看看这座"桥梁"在实际中是如何搭建起来的，并聊聊它未来还能怎么升级。

敬请期待下篇：《Web连接桥梁：智能体URL功能详解与实现【下】— 功能实现》。