企业官网建设流程全解析

Agent-Sandbox UI上线到现在已经有段时间了，后台私信和群里问得最多的一个问题就是：这些面板到底怎么用，哪些功能值得每天点开？今天干脆写一篇完整的盘点，把Agent-Sandbox的界面功能从设计逻辑到实际使用习惯都聊一遍。标题里的“韶”字其实就是老样子打招呼，跟设备、编程语言都没关系，各位看官别多想。如果你手里也有一个需要反复调试的Agent项目，或者正准备给自己写的Agent工具加一层Web界面，那这篇应该能帮你少走不少弯路。

这篇文章会按照“为什么做这个UI → 每个面板具体有什么 → 我实际最常用哪些 → 性能卡顿怎么处理 → 问题排查速查”的顺序来写，最后附上我自己踩过的坑和后续的一些想法。内容尽量讲得具体，你读完可以直接拿这些思路去对照自己的项目。

1. 为什么给Agent-Sandbox补一个UI层

1.1 纯命令行用着有多难受

最早版本的Agent-Sandbox是没有界面的，只有一个CLI工具。说实话，在只有一个Agent、一次跑一个任务的时候，命令行完全够用，打印几行日志就能看清结果。但Agent项目一旦多起来，或者单个任务里拉起多个子Agent协作，命令行马上就变得不太够用了。

举个实际例子。我本地起两个Agent做“信息搜集 + 总结”的分工流程，第一个Agent先搜索资料，把中间结果传给第二个Agent做总结。如果只靠CLI，这个过程中间态只能靠print输出，几个Agent同时在跑的时候，控制台里各种日志混在一起，根本分不清哪一段是A的输出、哪一段是B的输出，上下文一多就非常混乱。有一次我在排查一个“搜索到了内容但总结丢信息”的问题，翻了几千行日志才定位到是子Agent在传参时截断了文本，那一天下来效率特别低。

后来我意识到，Agent调试和普通后端接口调试很不一样。普通接口是“请求进来、响应出去”，看两行日志就够了；Agent是连续的决策过程，有内部思考、有多次工具调用、有中间结果传递，这些过程如果不可视化，问题定位基本靠猜。UI层的核心价值就在这里：把不可见的Agent决策过程变成一条可以回看、可以点击、可以重放的路径。

1.2 UI设计目标：让Agent的思考过程可见、可控、可回放

给Agent-Sandbox设计UI之前，我先定了三个目标，后面所有面板都是围绕这三个目标来做的。

第一个是“可见”。Agent在做什么、做到哪一步、上一轮调用了什么工具、返回了什么结果，所有这些信息必须一眼能看到，不能藏在一层层日志里。这个目标主要靠工作台中间的“运行轨迹”面板来实现，后面会细说。

第二个是“可控”。调试场景下，用户需要频繁修改Prompt、调整模型参数、切换工具，甚至要对某一次失败的会话做重放。UI不能只是展示，还得能操作，而且要操作得足够快，不能每次改个参数都要翻三层菜单。

第三个是“可回放”。一次Agent运行结束之后，用户常常需要回头看：某一步为什么这么走？为什么在这个地方多调用了一次工具？这意味着运行过程必须被完整记录下来，并且支持按时间线拖动、按节点点击查看。这也是Agent调试工具和普通监控系统最大的区别。

这三个目标定下来之后，界面骨架其实就差不多出来了：一个负责会话和运行的树形结构，一个负责展示当前工作状态的主工作区，一个负责承载属性和完整数据的抽屉面板。

1.3 界面布局与技术选型

最终确定的布局是三栏结构：左侧是会话树，宽度默认320px，可以折叠成图标栏；中间是主工作区，负责展示当前选中的会话详情、运行轨迹和工具调用链；右侧是属性抽屉，默认收起，点击节点或日志后弹出，用来展示完整的入参、出参、耗时和原始返回数据。

技术选型上，我一开始纠结过到底用原生桌面技术还是Web技术。后来直接选了Web方案，理由有三个：一是跨平台，团队里有人用Windows、有人用macOS、有人Linux服务器远程访问，Web界面一套代码到处跑；二是免安装，部署在局域网内，浏览器打开就能用，不用给每个人都配一套本地环境；三是好嵌入，后端本身就是Python写的，用WebSocket推送运行日志很自然，前端只需要做渲染和交互。

前端框架没有堆特别新的东西，用了一个主流的响应式组件库，配合虚拟滚动列表来渲染大量日志。这里有个经验：Agent工具界面最怕的不是功能少，而是DOM节点太多导致卡顿，所以虚拟滚动从一开始就做了，后面体验好了很多。

2. Agent-Sandbox UI 功能全景拆解

2.1 会话管理区

左侧的会话树是整个工具的总入口。结构上按“项目 → Agent → 会话”三级组织，一个项目下可以有多个Agent，一个Agent下挂着多次运行记录。每次运行会话会显示开始时间、状态（成功/失败/运行中）、耗时和token消耗，一眼就能看出哪次运行有问题。

会话树支持右键菜单，可以重命名、归档、导出、删除。归档功能我是强烈建议用的，因为跑测试套件的时候会生成大量临时会话，不归档的话列表很快就会变得很长。搜索框支持按会话ID、Agent名称、模型名称和耗时范围过滤，比如我可以直接输入“耗时>30s”来筛出那些明显异常的运行记录，不用一个个点开看。

这个小面板看起来简单，但对多Agent项目来说非常关键。没有会话管理的时候，每次跑完任务还要自己复制粘贴保存一份结果，现在右键归档一下就完事，配合导出功能可以直接把完整运行记录存成JSON，方便后面分析或复现。

2.2 调试工作台

中间的主工作区是日常操作最频繁的地方。顶部是会话信息栏，显示当前Agent的配置状态、模型名称、温度等参数；中间是对话/Prompt编辑区，支持多轮对话历史折叠，也支持模板变量高亮。

Prompt编辑这块我花了不少心思。很多Agent工具只给一个文本框，塞一段很长的Prompt进去，变量和指令混在一起，看得人头晕。Agent-Sandbox做成了模板形式，像{{query}}、{{context}}这种变量会单独高亮，旁边还会显示变量的来源说明，这样调Prompt的时候思路会清楚很多。编辑区旁边挂着参数面板，温度、top_p、max_tokens、stop序列这些都能直接调，改完之后可以一键保存为一个Prompt模板，下次直接复用。

调试工作台还有一个很实用的细节：发送请求之后，界面会实时显示请求的排队时间、模型推理耗时和返回token数。这些数据虽然小，但排查“为什么某个Agent响应特别慢”的时候非常有用，能直接把慢的环节定位到是网络层、模型层还是工具调用层。

2.3 工具调用链可视化

这个面板是我个人认为整个UI最有价值的部分，也是被问得最多的功能。Agent在执行任务时，每调用一次工具，界面上就会生成一个节点。节点上直接显示工具名称、入参摘要、出参摘要、耗时和状态，状态有成功、失败、重试、跳过四种，失败和重试的节点会标红，一眼就能发现异常点。

点击任意节点，右侧抽屉会展开完整的入参和出参JSON，同时显示该次工具调用对应的模型原始输出片段，这样就能看清Agent到底是从哪句话开始决定调用工具的、调用时传了什么参数、调用结果对它下一步决策产生了什么影响。

举个例子。之前排查一个“搜索后无法正确回答”的问题，单纯看文字日志怎么都看不出毛病。后来在调用链面板展开看，发现Agent第一次调用搜索工具时传的query是“[object Object]”，后面的答案自然全是错的。这个问题如果没可视化，靠print排查，估计又得折腾半天。

调用链面板还支持展开多个并行调用，就是Agent同时调多个工具的场景，节点会以并列方式排开，每条分支都清晰。这个特性在跑复杂的多工具链路时特别有用，能直接看到哪些调用是串行的、哪些是并行的，对优化运行时间也有帮助。

2.4 资源状态面板

顶部有一条细长的状态栏，展示当前Agent-Sandbox整体的运行情况：今日请求数、token消耗总量、当前排队任务数、平均单次请求耗时、最近一次运行状态。这个面板主要是给“整体观察”用的，比如批量跑测试的时候，可以实时看到队列有没有堆积、token消耗是不是异常增加。

右下角还有一个可折叠的资源小面板，展开后能看到更细的监控：每个Agent的累计请求量、平均耗时、成功率，以及最近几次慢请求的分布。这个面板默认是收起来的，避免干扰主工作区，但需要的时候随时能拉出来。

这个资源状态面板在初期版本里其实是没有的，后来我自己跑并发测试时发现，一堆Agent同时跑的时候，根本不知道系统是不是还正常，看着又卡又没反馈，心里特别没底。加了这个面板之后，至少能知道队列深度和平均耗时，遇到问题也能判断是Agent逻辑问题还是后端资源被占满了。

3. 这些功能我每天都会用

3.1 一键重放与结果对比

如果说只能选一个功能保留，我会选“一键重放”。日常调试Agent，最常做的事情就是“刚才那一步没做好，我想换个Prompt再来一次”。如果靠手工复制、改参数、重新提交，一次两次还行，次数多了真的会暴躁。

Agent-Sandbox的做法是在每条会话记录上直接放一个“重放”按钮，点击后会带着原始配置重新发起一次任务。重放的时候可以选择“保持原参数”还是“使用当前工作区的参数”，方便做对比实验。对比功能也做得比较顺手，选中两条会话记录后点击“对比”，页面会并排显示两次运行的工具调用链和关键输出，差异点用颜色标出来，省得自己肉眼找不同。

这个功能对调整Prompt特别有用。我经常是同一段Prompt改一个词，重放两次，对比输出差异，很快就能判断这个词的影响方向。没有对比功能之前，我只能靠截屏或者复制粘贴到笔记里对比，效率完全不是一个级别。

3.2 日志筛选与关键词定位

日志面板虽然看起来不如调用链面板“高级”，但在排查复杂问题时反而是最高频的工具。Agent-Sandbox的日志面板支持级别过滤（DEBUG/INFO/WARNING/ERROR）、关键词搜索、正则搜索和时间范围筛选，四个条件可以组合使用。

实际操作中，我一般先用级别过滤把ERROR日志拉出来，看看整体有几处报错；然后针对某个工具调用节点，打开该节点的日志上下文，用关键词搜索定位到具体的输入输出。有一点值得提：日志面板是跟着调用链节点联动的，我点调用链上的某个节点，日志面板会自动跳到对应时间段，不用自己去对时间戳。

还有一个很小的功能但很贴心，就是“只看工具调用”开关。打开之后日志只显示工具相关的记录，模型内部的思考过程会暂时隐藏。这样排查工具调用问题时，界面会清爽很多，不容易被大段大段的推理文本干扰。

3.3 配置导出与多环境切换

Agent项目跑到一定阶段，配置就会多起来：不同的Prompt模板、不同的模型参数、不同的工具列表。每次在本地调好的配置，要部署到服务器上，如果靠手动复制，大概率会出问题——不是少个参数就是改错一个标点。

Agent-Sandbox把配置管理做成了“环境”维度。本地环境、测试环境、正式环境分开维护，每个环境有自己的API地址、模型列表和Prompt模板集。切换环境只需要在右上角下拉框里选一下，界面上所有配置会自动跟着切换。配置支持导出成JSON文件，也支持从JSON文件导入，这样可以把配置提交到git仓库里，所有环境变更都有记录可查。

这个习惯我强烈建议养成。以前我吃过亏，在本地调好的Agent，部署到服务器后发现行为不一致，查了一晚上才找到是环境变量里某个参数没同步。现在配置都走UI的导入导出，配合git版本管理，再没出过这种低级问题。

4. UI卡顿与性能优化，我踩过的坑

4.1 卡顿的根源：高频日志与大列表

热词里有一堆“ui界面卡顿”“循环数据采集和ui刷新卡顿”相关的搜索，看得出来这是很多人的痛点。Agent-Sandbox早期版本也遇到过，尤其在会话数量多、Agent运行频繁的时候，界面会明显变卡，最严重的时候切换一次会话要等好几秒。

我排查下来，卡顿根源基本集中在三个地方。

第一个是高频日志推送。Agent运行时，后端会通过WebSocket实时推送日志，频率高的时候每秒几十条甚至上百条。前端如果每收到一条就立刻更新一次DOM，浏览器主线程马上就会被占满，界面自然卡得不行。这个问题和开发传统UI时遇到的“频繁刷新卡顿”是一个道理，本质就是更新频率超过了浏览器能承受的渲染能力。

第二个是大列表渲染。会话多了之后，日志面板可能有几千行甚至上万行记录。如果全部渲染成DOM节点，内存占用很高，滚动也会变得非常卡顿。这个问题在打开一个长时间运行的Agent会话时尤其明显。

第三个是WebSocket断线重连不完善。早期版本里，WebSocket一旦断线，前端不会自动重连，要手动刷新页面才能恢复。如果没刷新，界面就一直停在一个假死的状态，用户感知就是“卡住了”。

4.2 几个有效的优化动作

针对上面三个问题，我做了几个优化，实测效果都很明显。

第一，前端日志改为“增量聚合+节流刷新”。日志事件到了前端之后，先放进一个缓冲区，每隔500毫秒统一更新一次DOM，而不是每来一条就刷新一次。对于需要实时查看的场景，500毫秒的延迟体感上基本无感，但DOM更新频率降低了90%以上。

第二，日志列表使用虚拟滚动。只渲染当前可视区域内的日志行，一套下来，即使日志有几万行，DOM节点数量也始终保持在一个很低的水平，滚动流畅度提升非常明显。这个方案在市面上一些大列表场景已经很成熟，Agent工具界面一样适用。

第三，设置日志上限。单个会话的日志默认最多保留5000条，超过后按时间从旧到新自动截断，但会保留一条“日志已截断”的提示。这样既能保证内存不失控，又不会让用户误以为日志缺失。

第四，WebSocket增加心跳和自动重连机制。每30秒发一次心跳，超过90秒无响应就主动断开重连。断线后界面上会显示一个明显的提示条，避免“假死”状态。这个改动虽然不直接提升性能，但对用户体验改善极大。

4.3 硬件不够时的降级方案

有些使用场景是低配机器，或者显卡资源被其他程序占满，浏览器渲染本身就吃力。Agent-Sandbox做了一版“低资源模式”，开关在设置面板里。打开之后，界面会关闭GPU加速合成、减少阴影和动画效果、日志刷新间隔拉长到2秒，同时默认只加载最近100条日志。

这个模式我实际测过，在集成显卡的老笔记本上也能保持基本可用，只是界面少了一些细腻的动效。对于只是临时看一下运行结果的用户来说，这个模式非常实用。另外，如果使用场景是远程服务器跑UI、本地浏览器访问，也建议把日志刷新间隔调大一点，因为网络传输本身就是一道瓶颈，频率太高很容易造成消息堆积。

5. 常见问题速查表

5.1 高频问题与解决思路

这里直接整理成表格，方便各位对照排查。下面的问题都是我自己或者群里用户实际遇到过的，不是凭空编出来的。

这些问题里，WebSocket断开和日志截断是最容易让人困惑的两个。前者会造成“界面好像死了但其实还活着”的错觉，后者会造成“日志缺失”的误判。建议上线前一定要测一下服务异常恢复的场景，养成定期导出会话记录的习惯。

5.2 容易被忽略的交互细节

除了上面的问题，还有几个交互细节是用户经常反馈的，虽然不算“故障”，但对使用体验影响不小。

一个是空状态。早期版本里，没有会话的时候左侧栏就是一片空白，很多用户第一次打开还以为程序没装好。现在空状态下会显示一句指引文案，比如“还没有会话，点击右上角创建一个Agent”，这对新手非常友好。

另一个是快捷键。Agent-Sandbox支持几个常用快捷键：Ctrl/Cmd + K快速打开全局搜索，Ctrl/Cmd + Enter快速发送当前Prompt，G + G快速回到会话列表顶部。这些快捷键看文档时不觉得重要，但实际用起来能明显提升操作节奏。

还有一个是暗色模式。Agent工具的界面基本都偏暗色系，因为用户通常会长时间盯着屏幕。Agent-Sandbox默认跟随系统主题，但可以在设置里手动切换。有一段时间暗色模式下的对比度没调好，日志文字看着很吃力，后来专门调了一版，把前景色和背景色的对比度拉高了，用起来舒服多了。

6. 后续想做的事

6.1 会话回放与团队协作

目前调用链是静态的，可以点击每个节点查看当时的输入输出，但还做不到像视频一样拖动时间轴回放整个Agent的运行过程。下一步打算做一个“时间轴回放”功能，把Agent的每一步决策、每一次工具调用、每一段输出变化按时间线串起来，可以快进、倒退，也可以放慢速度观察。这对分析复杂的多步骤任务会很有帮助。

团队协作也是我一直在想的方向。现在的会话数据都存在本地/单机后端，没法多人共享。如果做成团队版，所有人共享一个Agent运行中心，大家都能查看和评论同一批运行记录，团队成员之间的配合会顺畅很多。不过这个改动牵扯到权限、数据隔离、多人实时同步，工程量不小，还在慢慢规划。

6.2 一个关于UI设计的真实体会

做Agent-Sandbox UI这个过程中，我最大的一个感受是：Agent工具的UI不是装饰，而是调试思维的载体。起初我也觉得CLI够用，UI只是锦上添花；等真正用起来之后才发现，当Agent的决策过程能被清晰地看见时，发现和解决问题的速度完全不一样。

以前我用CLI排查一个问题，可能要来回打印很多轮日志，才能大致拼凑出Agent的思路。现在看着调用链一步步走完，问题往往一眼就能看出来。界面这个东西，做得好的时候你不会觉得它多厉害，但一旦撤掉，工作效率的落差马上就能体会到。

如果你也在做自己的Agent工具，我建议不要等到功能全部完善了再补界面，一开始就应该把可视化考虑进去。哪怕第一版很粗糙，只要能让你“看见”Agent在做什么，后面迭代就会快很多。刚开始多花一点时间在UI上，后面省下的排查时间会是好几倍。