让 Agent 做好前端工具平台:从好看的页面,到可靠的业务流程
用看板、系统拓扑和流程编辑器截图说明怎样向 Agent 描述布局、颜色与交互,再用 Vue 案例检验状态和可靠性。
本文目录
先说清用户任务,再选界面形态
让 Agent 写前端,只说“美观、简洁、有高级感”,很容易得到一个漂亮首屏。标题大一点,下面排几张卡片,左侧加彩色竖线,再放一个闪电图标,页面就有了某种熟悉的“科技感”。
但如果这是一个工具平台,用户接下来要搜索数据、填写表单、创建任务、等待结果,首屏只占很小一部分。提交后一直转圈怎么办?重试会不会重复创建?别人没有权限,能不能直接调用下载接口?
这些问题决定用户敢不敢继续使用。给 Agent 的第一句话可以先写成:
起步指令:请先阅读【项目路径】,说明【目标用户】如何完成【核心任务】,并核实当前技术栈和业务边界。本轮只分析,不修改文件。先给出适合该任务的页面形态、信息层级、关键状态和异常恢复路径;用项目证据说明判断。图标默认不添加,保留专业工具所需的信息密度。报告完成后等我确认,再实施。
下面先看三种常见页面怎样把“好看”拆成能讨论的布局、颜色和交互要求。完整审查任务书放在示例之后。
先选展示方式,再描述布局、颜色和交互
“美观、专业、现代”没有说明用户要看什么、做什么。可以先按任务选页面形态,再描述信息的位置、颜色的职责和操作后的反馈。下面三个页面是独立制作的桌面浏览器交互原型,数值和业务行为均为模拟;截图展示界面表达,不证明真实服务、性能或权限已经接入。它们不是三套所有项目都要照搬的模板。
| 用户主要任务 | 适合先考虑的页面形态 | 需要说清的关系 |
|---|---|---|
| 看数据、找异常、处理记录 | 数据看板 | 指标、趋势、异常、明细的阅读顺序 |
| 理解服务流向、定位瓶颈 | 系统拓扑 | 节点、连线、分组、状态与详情 |
| 配置有先后关系的步骤 | 流程编辑器 | 当前步骤、编辑区、全局检查的关系 |
数据看板:信息层级和语义色

图1:示例看板结构图。左侧是稳定入口,右侧五层从上到下依次回答“我在哪个页面、能筛什么、整体是否正常、异常在哪里、如何进入明细”;底部补出空结果、加载中、请求失败三种状态,以及语义色图例。所有数据均为模拟。
信息层级指用户先看到什么、再看到什么。这里把页面标题与主操作放在最上方,时间和区域筛选紧随其后,关键指标高于明细表格。侧边导航放稳定入口,内容区承担当前任务。语义色让蓝色负责主操作和选中,红色负责紧急异常,琥珀色负责待处理;每种状态仍有文字,不能只靠颜色判断。
筛选不是摆设。点击时间范围后,应更新指标并保留当前筛选状态;搜索没有匹配项时显示空状态,请求失败则显示错误和重试入口。
给 Agent 的描述:设计一个桌面数据看板,采用左侧稳定导航和右侧工作区。按“页面目标与主操作 → 时间/区域筛选 → 关键指标 → 趋势与异常 → 明细表格”的顺序组织内容。蓝色只用于主操作与当前选择,异常颜色必须配状态文字。筛选后更新相关数据;空结果、加载中和请求失败分别呈现,并给出下一步操作。保持表格可读的信息密度。
系统拓扑:用一张图解释任务如何流动
以常见的异步文件处理为例:用户提交一个任务,接入网关把任务写进队列;调度服务根据规则选定一个地域的执行实例;实例处理后把结果写入存储,客户端再查询任务状态和结果。图中一条线表示任务可能经过的处理路径,地域分支是调度选择,并不表示每项任务会同时跑遍所有地域。

图2:模拟的文件处理拓扑图。箭头交代方向,华北、华东、华南先按地域折叠;吞吐、队列与延迟均为演示数据。
读这种图,先分清四个词:
- 节点(Node):一个处理阶段、服务、地域集群或具体实例。节点里只放识别身份和判断健康度必需的指标。
- 边(Edge):节点间的任务流向。箭头表示方向;边上的吞吐、P95 和失败率应来自这段连接的真实统计,不能把节点指标随便搬到线上。
- 分组 / 聚合节点(Cluster / Group):先把同一地域的多个实例收起来。华北 3 个、华东 4 个、华南 2 个只是示例;真实数量应来自配置或接口。
- 状态(State):接入、排队、处理中、完成、失败描述任务;正常、繁忙、不可用描述实例或集群。两类状态不能混用,颜色也要配文字。
这张图的视觉编码很克制:从左到右的位置表达先后,箭头表达方向,琥珀色和“繁忙”文字一起提示华南负载较高。点击“展开实例”再看到 worker 的处理中、空闲和队列高,属于渐进披露;点击节点后在旁边的上下文详情面板看队列、处理时长和告警。状态筛选用于突出异常,采样时间告诉用户数据有多新;暂停只冻结画面,不暂停服务器任务。
这里的 P95 处理时长,表示选定统计窗口内 95% 的任务在该时间以内完成。正式页面还要写清窗口、单位、样本量和数据是否过期。用这种图之前,先核实真实调度策略、重试路径、失败去向与结果存储方式;图必须忠实表达系统,不能为了对称而虚构连线。
给 Agent 的描述:以现有异步任务流程为依据,先核实接入、入队、调度、地域执行实例、结果保存和客户端查询之间的真实关系。设计从左到右的拓扑:节点显示阶段名称、任务量或队列量、健康状态;边用箭头明确流向,并在有数据来源时显示吞吐、P95 与失败率。地域先聚合,点击后展开实例,实例显示空闲、处理中、繁忙或不可用及队列长度。点击节点打开上下文详情,保留整张图;支持按地域和状态筛选、显示采样时间、暂停画面更新。地域和实例数量由配置或接口驱动。第一阶段用明确标注的 Mock 数据,先交付两种布局预览,并说明每种布局在实例增多时如何保持可读。
流程编辑器:主从布局和发布前检查

图3:示例流程编辑器结构图。左侧步骤列表、中间配置区和右侧发布检查共同构成三栏主从布局;所有内容均为模拟。
主从布局是左侧选对象、中间编辑所选对象,同时保留全局上下文。这个例子把步骤、配置和发布检查分成三栏。复杂设置只在对应步骤打开,称为渐进披露;修改后出现“未保存”,称为脏状态反馈。字段标签始终可见,错误靠近字段;发布按钮旁说明还缺什么,而不是点击后才让用户猜。
给 Agent 的描述:为多步骤配置设计三栏主从布局:左栏展示步骤顺序和当前选择,中栏编辑当前步骤,右栏持续展示发布检查。切换步骤时保留未保存内容或明确提示;字段有可见标签、就近校验和保存反馈。发布前列出阻塞项、原因与可执行动作。先用真实长度和异常状态做浏览器预览,再确定组件拆分。
这三段指令的共同点是:先说用户任务和页面形态,再说信息关系、状态与交互,最后写清数据来源和验收方式。颜色、圆角或阴影可以由现有 Design System 决定;“看起来高级”不应代替这些可核对的要求。
完整任务书:先审查,再实施
下面这段用于已有前端项目的第一轮只读审查。先填好方括号中的项目、用户和任务;审查报告出来后,再决定实施范围。
请审查并改进【项目路径】中的前端工具 / SaaS 界面,目标用户是【用户】,他们要完成【最重要的业务任务】。本轮重点页面或流程是【页面/流程】;需要支持【桌面、移动端、浏览器或无障碍范围】。如果信息缺失,先从项目文件核实;只有会改变方案的关键问题才提问。
先阅读项目说明,并使用项目中已有的 Impeccable、UI UX Pro Max 等设计技能;技能不可用时如实说明,不自行安装依赖或运行来源不明的脚本。
第一轮只做分析,不修改文件。先确认框架与版本、构建工具、UI 组件库、路由、公共布局、样式变量、API 边界和测试方式。沿一条真实用户任务梳理“输入—请求—服务端状态—页面反馈—后续操作”,列出每个状态、允许的操作和失败后的恢复路径。按项目实际功能判断表格、表单、异步任务、上传下载、账号多租户、实时数据等场景哪些适用;不要把不相关功能机械套进来。
审查 UI/UX:保持专业工具所需的信息密度,用字体、间距、对齐和一致组件建立层级;默认不添加图标。左侧导航图标只有在项目已有统一图标体系、且确实能帮助识别稳定功能入口时才保留;同级菜单的尺寸、线宽、对齐和含义必须一致,不给个别入口单独加图标装饰或制造主次。操作图标限于含义明确、无需猜测的常见动作;陌生含义要配文字,不让图标代替状态说明。禁止闪电、火箭、星光、魔法棒、机器人等泛化科技装饰,也不许用 emoji 或临时混搭的图标规避限制。先复用现有图标组件;没有就用文字,不加图标库依赖。不要用彩色侧边竖线、无意义渐变或动画。检查长文本、空数据、加载、错误、权限不足、键盘操作、焦点和窄屏行为。任何状态都要让用户看懂当前发生什么、能做什么。
审查鲁棒性与稳定性:检查搜索请求乱序、过期响应、取消与清理;表单重复提交;请求超时后结果未知;重试、幂等和限流;轮询重叠、页面切换及刷新恢复;401/403/404/409/422/429/5xx 和断网反馈。区分取消浏览器请求与取消服务端任务。指出前端能处理和必须由后端保证的边界。
审查性能但不要猜数字:区分首屏、交互、列表渲染、网络请求和后端耗时;注明设备、数据规模、网络与测量方式。先找证据再建议分页、懒加载、虚拟列表或缓存,不为“优化”随意增加依赖。未测的指标明确标为待测,不编造评分和提升比例。
审查安全边界:把浏览器输入视为不可信;确认服务端逐请求验证身份、对象权限和租户归属;检查 XSS/不可信 HTML、CSRF(若使用 Cookie 会话)、文件上传下载、CSV 公式注入、前端密钥、敏感日志和依赖风险。隐藏按钮、路由守卫、CORS 或 Origin 检查不能替代后端授权。只在授权环境用无害样本验证,不外传数据或放宽安全策略。
交付一份可核对的报告:项目事实及文件证据;核心业务流程和适用场景;按 P0/P1/P2 排序的问题(触发条件、用户影响、证据、责任层、建议和回归方式);初步 Design System 与复用组件建议;最值得先改的页面、分阶段计划、风险、验证和回滚方式。将结论分为“已实测 / 代码判断 / 未验证 / 不适用”。保留现有业务逻辑、API 合同、路由、权限、框架和组件库;不添加未经批准的依赖。
报告完成后停止并等待我确认。没有我的明确确认,不修改项目文件、不提交、不推送、不部署。
把任务分阶段,是为了让 Agent 先把项目和风险说清楚,再在确认范围内实施,最后用独立验收检查边界。若你已经明确授权直接实施,把最后的“只读审查”改成具体改动范围,并保留“不擅自扩大范围”的约束。
用 Vue 案例检验:先还原真实任务
前三个原型说明如何描述界面。这次的临时 Vue 项目“序列”,则用一条完整任务链检查描述是否能落地:选择示例数据,创建批量处理任务,后端实际执行,前端查询进度,最后下载 CSV。以下五张是桌面浏览器实拍。数据和预置历史为示例,新任务的处理、日志与结果来自本机后端。这是一次交互演示,不是已经通过生产验证的 SaaS。
这个 Vue 演示的源码与五张截图(GitHub,MIT)可本地运行;没有提供线上演示。前三张界面形态图来自独立原型,不属于这个仓库。

图4:主页面把任务名称、状态和操作放在同一阅读路径上。截图能证明布局,不能证明性能或权限安全。
这个项目使用 Vue 3、Vite 和 Node 原生 HTTP 服务,没有另加 UI 组件库。前端发送创建请求,服务器生成任务编号;之后列表与详情读取该编号的状态,成功后才提供结果文件。
这条链路把界面接到了真实对象上:输入变成请求,请求产生任务,任务状态改变,页面再交代接下来能做什么。创建接口返回成功,只说明任务建立,不说明数据已经处理完成。
让 Agent 改已有项目,也该先还原这条链。框架版本、路由、组件库、公共布局、CSS 变量、API 层、测试入口,都要从代码核实。不能因为“Vue 工具平台”几个字,就自动替换组件库、重写状态管理或顺便调整权限。
我这次使用 Impeccable 的工具界面指导和 UI UX Pro Max 的检索建议,再按实际场景取舍。设计技能能提供观察角度,不能替代业务合同;检索出营销页建议,也不能原样塞进任务中心。在线方案服务未能使用的部分,不能写成已经做过完整比选。
美观来自清楚的关系,图标默认不添加
工作台需要让人快速找到任务、辨认状态、完成操作。它不需要每个区域都表达自己很重要。
最初审查发现,表格虽然有足够行高,主数据却只有12px,辅助信息更小。后来把任务名称和主数据调到14px,元信息调到12px,保留原本密度。这个改动比多加一个彩色盒子更有用。
颜色只承担明确职责:主操作、当前选择,以及失败、运行、完成等状态。状态同时写出文字,避免用户只能靠红绿区分。标题、数据和辅助说明的关系,则交给字号、字重、间距和对齐。
图标也一样。左侧导航是稳定入口,只有已有统一图标体系且能加快识别时才保留整组图标;不能只给某一项单独点缀。搜索、下载、关闭等常见操作可使用一致图标,陌生操作则加文字。标题旁、概览区和空状态不为填空而加装饰。规则要同时列出允许条件、禁止样式和替代做法,避免 Agent 把闪电换成火箭。
这套取舍适用于当前任务页,不是一套所有产品都该照搬的配色。优先复用现有组件和主题变量,比另造一套局部漂亮、全局冲突的样式更可靠。
把状态写清楚,异常才有恢复路径

图5:错误说明输入缺什么,并保留继续填写的路径。字段校验不等于服务器幂等。
一个创建表单至少有未填写、输入错误、提交中、成功、失败几种状态。提交时要防连点,失败时保留输入,错误应靠近相关字段。弹窗的焦点、退出与返回,也属于能否完成操作的一部分。
任务建立以后,又有排队、执行、成功、失败和取消。不是把同一个按钮换几次颜色:不同状态允许的动作不同,服务器也需要检查。例如,已经成功的任务不能因为前端残留了“重试”按钮,就再次执行。

图6:首次中断是显式设置的演示故障;任务编号SQ-1050贯穿这次恢复过程。
我让同一个任务重试。第二次执行成功,128条输入最终保留114条,剔除7条无效邮箱和7条重复记录。前后截图对应同一编号,不靠另外创建一个成功任务来代替恢复证明。

图7:结果、执行次数和日志能互相核对。下载按钮代表可以请求文件,不代表用户已经保存到磁盘。
同样要分清“查不到数据”和“请求失败”。

图8:这是查询成功但没有匹配项;断网不能复用这幅画面,否则用户会误以为记录消失了。
扩展场景时,也应按功能选择:表格关心排序、跨页选择;编辑页关心未保存内容;上传关心大小、取消和失败;多租户平台关心对象归属。把每种场景都开发一遍,不叫全面;知道哪些适用、哪些依赖后端,才是完整审查。
鲁棒性首先是别把旧状态当成新结果
搜索“客户”后立刻改搜“订阅”,第二个请求可能先回来。如果旧结果随后覆盖页面,界面没有报错,用户却看到了错误的数据。
演示的列表使用了取消旧请求和请求序号检查。它减少无效查询,也防止旧响应提交到当前列表。但这不等于整个应用的异步问题都解决了:详情轮询与“重试”响应之间还缺统一版本控制,同一任务的旧状态仍需要额外防护。
AbortController控制的是浏览器里的请求。关闭详情、停止等待,不会自动取消已经开始的服务端任务。取消任务应有独立接口和状态校验。
写请求更要谨慎。创建请求发出后超时,可能只是响应丢了,服务器已经创建成功。此时直接重发,就可能建立两个任务。页面禁用按钮只能防本页连点,不能解决多窗口、重发或网络重试。真正的恢复需要后端幂等合同,或者能关联这次提交的查询机制。
因此,给 Agent 的要求不能只写“加错误处理”。应明确区分失败与结果未知,规定哪些查询可以受控重试、哪些命令必须先查状态;重试次数、退避、限流响应以及输入保留,也都要有边界。
性能要测用户等待的部分,不能拿构建快代替
这次正常链能跑通,构建也通过,但没有测过真实用户的交互延迟,更没有证明它能承受大量任务。
演示每两秒查询一次,页面隐藏时暂停。到了更慢的网络,还要检查请求会不会重叠,或旧查询是否不断被新轮询取消。列表退出、详情关闭、任务结束后,要明确哪些订阅和定时器应该停止,而不是让后台一直请求。
大列表先考虑合适的服务端分页。只有测到 DOM 数量或渲染确实成为瓶颈,再评估虚拟列表。Vue性能指南同时区分加载和更新性能,并提供按需加载、大列表与响应式优化等方向;它不是要求每个页面把这些技术全部用上。
测量至少说明设备、网络、数据量和采样方法。页面首次打开、连续输入后的更新、接口耗时、长时间使用的内存,回答的是不同问题。单次截图看不出这些差异。
Web Vitals可作为页面体验参考,但实验室记录不能直接写成真实用户P75。没有测量,就写待测,不让 Agent 为了交付填一个“性能提升50%”。
这个临时项目同步保存JSON、逐批重算数据前缀,适合解释流程,不适合直接外推规模能力。要上线,应先用业务规模找出瓶颈,再决定存储、队列和前端各自怎么改。
安全要写清责任,前端不能替服务器授权
表单校验让人更容易填对,不是信任输入的理由。按钮隐藏、路由拦截也只是体验层,用户仍然可能直接请求任务或文件地址。服务端需要逐次检查身份、对象和所属范围;OWASP授权指南强调每次请求的授权验证。
用户内容默认按文本显示,不把它拼成Vue模板,也不直接交给HTML执行入口。Vue安全指南明确禁止把不可信内容作为模板;需要富文本时,必须另行设计内容处理和可信边界。
导出也有自己的风险。CSV里转义双引号不等于防公式注入。不可信内容交给表格软件时,某些前缀可能被当成公式;OWASP的说明也指出,处理方式受软件和下游用途影响,不能承诺一种通用转义永远安全。当前演示的列表导出还需要补这层设计。
账号存在时再检查会话与CSRF;文件上传存在时再检查内容、存储与访问。前端环境变量和构建包不能放密钥,日志与截图也要脱敏。缺后端授权时,应把依赖明确列出,不能宣称靠前端改造已经解决。
本演示只有本机服务和基础来源判断,没有账号、多租户与完整安全验证。它能成为讨论材料,不能直接改个监听地址就当成生产平台。
给 Agent 的任务分三轮,验收也要有证据
开头的短版指令帮助先说清任务;前面的完整代码块则用于第一轮只读审查并给出方案。更详细的审查清单另存为第一轮任务书;你确认范围后,再发实施指令,最后用独立验收指令检查正常、异常与恢复。
配套内容可直接复制:第一轮审查任务书、第二轮实施指令、第三轮验收指令。场景与证据表用于核对本次演示做到哪里。
三轮都保留几个约束:不擅自改业务、API、路由和权限;不迁移框架、替换组件库或增加未经批准的依赖;图标默认不添加,不靠彩色侧竖线堆重点。
验收结果也应分清证据。截图证明布局和可见反馈;API、日志、测试证明状态转换与结果。代码里有一段处理,不代表场景已经实测;构建通过,也不等于性能、安全和所有浏览器都通过。
这次已实测本地创建、失败重试、结果、校验、分页和空状态。乱序网络、结果未知恢复、多租户授权、长时间内存与容量测试仍不能填成已完成。配套场景表保留这些缺口,便于下一轮真正补齐。
让 Agent 做前端,最后要交付的是一段用户能理解、能够恢复、结果可信的流程。漂亮的页面是入口;它在等待、失败和边界条件下怎样工作,才决定这个工具是否值得使用。