跳到主要内容

第 2.10.3 节：把工具审批卡片和前端状态接入复核流程

工具审批卡片和前端状态只有拆成可执行步骤，才容易复核、排错和交接。完成本节后，你应该能够写出工具审批卡片和前端状态的验收样例、通过/不通过标准、判断阈值和风险说明。

实现步骤或决策流程​

推荐技术流​

本章不要求读者立刻掌握某个前端框架。推荐技术流是从“界面能力”倒推，而不是从“我要用哪个框架”出发。

阶段推荐做法重点
原型阶段用静态页面或低代码原型画出工作台先确认信息架构和状态，不急着写复杂交互。
MVP（最小可行产品）阶段使用 React（前端框架）或类似组件化框架拆出对话、引用、工具卡片、审批卡片和状态组件。
接口联调阶段用稳定字段契约连接后端不把后端原始日志直接暴露给用户。
试点阶段加入权限提示、转人工、质检反馈和管理配置验证真实客服流程能不能跑通。
生产阶段加入监控、可访问性、审计日志、错误分级和配置开关让系统可维护、可追责、可扩展。

推荐技术组合可以这样理解：

能力可以选择的技术方向本章关注点
页面框架React（前端框架）、Vue（前端框架）、Svelte（前端框架）等不讲语法，只要求组件边界清楚。
数据请求REST（表现层状态转移接口风格）接口、Server-Sent Events（服务器发送事件）、WebSocket（双向通信协议）能展示流式状态和中间事件。
状态管理URL（统一资源定位符）参数、本地状态、服务端会话状态conversation_id（对话编号）和任务状态不能丢。
UI（用户界面）组件对话列表、卡片、徽标、表格、抽屉、弹窗每个组件对应一个业务事实。
可观测性Trace ID（追踪编号）、日志摘要、前端错误上报用户操作和后端链路能串起来。

新手要记住：前端技术栈不是本章重点。真正的重点是，你能不能把 Agent（智能体）系统的状态设计成用户看得懂、客服接得住、管理员查得到的界面。

字段契约​

前端和后端之间必须有稳定字段契约。没有契约，前端只能猜后端状态，后端也不知道前端需要展示什么。

下面这张表是本章的核心交付物，覆盖客服 Agent 工作台最小字段。

字段中文含义前端展示位置来源设计原因
conversation_id（对话编号）一段多轮客服对话的编号对话详情、日志摘要、客服接管页会话系统生成串联多轮消息、工具调用、转人工和质检。
message_id（消息编号）单条消息编号消息气泡、反馈记录、引用定位消息服务生成让每条回答可追踪、可反馈、可复盘。
role（角色）消息发送者身份消息头像或标签用户、Agent、客服、系统区分用户、模型、人工客服和系统提示。
content_summary（内容摘要）消息或工具结果的简短摘要对话列表、客服接管摘要、日志摘要Agent 或后端摘要服务让客服快速理解上下文，避免阅读全部原文。
citations（引用来源）回答依据的资料列表回答下方、引用抽屉、质检页RAG（检索增强生成）检索层降低黑箱感，支持依据检查和资料更新。
tool_call_card（工具调用卡片）工具调用的可视化信息对话流中间、工具时间线Tool Calling（工具调用）层展示工具名称、状态、输入摘要、输出摘要和错误。
approval_card（审批卡片）高风险动作的审批信息对话流、审批中心、主管页审批中心支持人工确认、拒绝、修改和审计。
state_badge（状态标识）当前消息或任务状态消息右上角、任务进度条状态机或任务系统让用户知道处理中、需要补充信息、审批中、失败或完成。
error_banner（错误提示条）用户可见错误提示对话顶部、卡片内部、页面顶部后端错误映射层把技术错误转换成可理解、可操作的提示。
handoff_status（转人工状态）人工接管进度转人工面板、对话底部工单系统或客服系统告诉用户是否已排队、已接管、已完成或失败。
permission_notice（权限提示）权限不足或字段隐藏说明引用卡、工具卡、管理页权限系统解释为什么看不到资料、不能调用工具或需要登录。
trace_id（追踪编号）串联一次请求链路的编号日志摘要、客服内部视图、错误详情可观测性系统生成排查问题时连接前端操作、后端检索、工具和日志。
feedback_score（反馈评分）用户或质检对回答的评价回答底部、质检页、统计面板用户反馈或质检系统衡量回答质量，驱动优化和复盘。

这些字段不是为了“显得专业”，而是为了让前端知道该展示什么、何时展示、给谁展示、失败时怎么展示。

对话消息字段​

字段含义展示建议
message_id（消息编号）单条消息唯一编号不一定给普通用户看，但要用于反馈和日志。
role（角色）user、assistant、human_agent、system 等用户端用头像或标签表达，管理员端可显示完整角色。
content_summary（内容摘要）消息摘要客服接管时优先展示摘要，再允许展开全文。
state_badge（状态标识）drafting、answering、needs_info、completed 等避免用户误以为系统卡死。
feedback_score（反馈评分）点赞、点踩、1 到 5 分或质检分反馈要绑定具体消息，而不是只绑定整段对话。

引用来源字段​

字段含义展示建议
source_title（来源标题）资料标题显示给用户和客服。
source_type（来源类型）政策、订单、工单、FAQ（常见问题）等帮用户判断依据性质。
source_version（来源版本）资料版本或生效时间防止引用过期资料。
snippet_summary（片段摘要）命中内容摘要不直接暴露无权限原文。
permission_notice（权限提示）是否隐藏部分字段普通用户看到“部分内部字段已隐藏”。

工具调用卡片字段​

字段含义展示建议
tool_name（工具名称）查询订单、创建工单等用业务名称，不用内部接口名。
tool_action_summary（动作摘要）工具要做什么例如“查询订单发货状态”。
tool_status（工具状态）pending、running、success、failed、blocked用状态标识和进度提示。
tool_input_summary（输入摘要）关键输入只展示脱敏后的订单号、问题类型等。
tool_output_summary（输出摘要）工具返回摘要成功时展示结果，失败时展示可理解原因。
trace_id（追踪编号）链路编号普通用户不必看，客服和管理员可见。

审批卡片字段​

字段含义展示建议
approval_id（审批编号）审批单编号审批中心和日志可见。
proposed_action（拟执行动作）Agent 建议执行的动作用业务语言展示，例如“发起退款申请”。
evidence_refs（证据引用）支撑审批的资料和工单审批人可以展开查看。
risk_reason（风险原因）为什么需要审批例如涉及资金、外部联系或敏感投诉。
approval_status（审批状态）pending、approved、rejected、expired直接影响工具是否能继续。
approval_card（审批卡片）前端聚合后的卡片对象对话流和审批中心复用。

读图重点：审批卡不是确认按钮：pending 期间工具必须暂停；只有 approved 能进入执行，rejected、expired 和执行失败都要留下可复盘记录。

制作步骤​

第一步：先画工作台信息架构​

不要一开始就写聊天页面。先画出客服工作台需要哪些区域。

区域必须回答的问题
对话区用户和 Agent 说了什么？当前回答状态是什么？
引用区回答依据哪些资料？资料是否过期或无权限？
工具区系统调用了什么工具？执行结果是什么？
审批区哪些动作需要人确认？审批状态是什么？
转人工区是否已转人工？谁接管？当前进度是什么？
日志摘要区这次对话怎么复盘？trace_id（追踪编号）是什么？
管理配置区管理员如何维护知识库、工具、权限和展示策略？

第二步：列出所有前端状态​

把成功、等待、失败、无权限、审批中、转人工、重试、完成都列出来。只设计成功路径是不够的。

建议至少准备：

  • 用户提问中。
  • Agent 处理中。
  • 知识库检索中。
  • 引用来源已返回。
  • 工具调用中。
  • 等待用户确认。
  • 等待审批。
  • 已转人工。
  • 工具失败。
  • 权限拒绝。
  • 回答完成。
  • 用户已反馈。

第三步：设计字段契约​

字段契约要先于页面细节。否则前端会出现“页面想展示，但后端没有字段”的问题。

本章建议先完成这 4 张契约表：

  • 对话消息字段。
  • 引用来源字段。
  • 工具调用卡片字段。
  • 审批与转人工字段。

字段设计要说明来源、展示位置、权限等级和失败状态。特别是 trace_id（追踪编号）、conversation_id（对话编号）和 message_id（消息编号），不要到最后才补。

第四步：把后端事件映射成前端卡片​

后端可能返回的是“检索开始、工具开始、工具成功、工具失败、审批创建、人工接管”等事件。前端要把这些事件组织成用户看得懂的卡片和状态。

后端事件前端表现
retrieval_started（检索开始）显示“正在查找相关资料”。
retrieval_completed（检索完成）展示引用来源和资料版本。
tool_call_started（工具开始）插入工具调用卡片。
tool_call_failed（工具失败）在卡片中显示错误原因和兜底动作。
approval_created（审批创建）展示审批卡片和等待状态。
handoff_created（转人工创建）展示转人工队列和工单状态。
answer_completed（回答完成）展示回答、引用、反馈和追问入口。

第五步：设计权限和可见性​

同一份数据，不同角色看到的内容不一样。

信息终端用户客服主管管理员
引用来源标题可见可见可见可见
内部政策全文不可见按权限可见可见可见
工具输入摘要脱敏可见可见可见可见
trace_id（追踪编号）一般隐藏可见可见可见
审批理由部分可见可见可见可见
系统错误细节不可见摘要可见可见可见
敏感字段脱敏按权限展示按权限展示按权限展示

前端要配合权限系统做展示，但不能把权限判断只放在前端。

第六步：写兜底文案和人工接管策略​

每类失败都要有用户能理解的文案。

失败类型不推荐文案推荐文案
工具超时“系统错误。”“订单系统暂时没有返回结果，我可以帮你稍后重试或转人工处理。”
无权限“403。”“当前账号不能查看这份资料。如果你认为这是误判，可以联系管理员或转人工。”
无引用“无法回答。”“我没有找到可引用的资料，因此不能给出确定结论。建议补充资料或转人工确认。”
审批中“处理中。”“这个动作需要主管审批，审批完成前不会执行。”
转人工“已提交。”“已为你转人工，客服会看到本次对话摘要和已查询的资料。”

第七步：准备验收样例​

前端验收不能只看页面是否漂亮。至少准备这些样例：

  • 有引用的成功回答。
  • 无引用时拒绝编造。
  • 查订单工具成功。
  • 查订单工具超时。
  • 创建工单前需要用户确认。
  • 退款申请进入审批。
  • 普通用户无法查看内部政策。
  • 转人工后客服能看到对话摘要。
  • 用户点踩回答后，质检页能看到反馈评分。
  • 管理员能通过 trace_id（追踪编号）找到日志摘要。

和后续章节的关系​

本章和后续章节关系很紧密。

后续内容本章提供什么基础
可观测性与日志前端要展示 trace_id（追踪编号）、错误摘要和用户反馈入口。
安全、权限、Guardrail（护栏）与审批前端承载 permission_notice（权限提示）、approval_card（审批卡片）和兜底提示。
商业需求、报价与验收工作台模块数量、审批流和管理配置会影响报价和交付范围。
综合知识库 Agent 制作方法最终项目需要把对话、RAG、工具、转人工和质检串起来。
作品集项目前端工作台是面试官最容易看懂的展示入口。

本章也会反向连接前面章节：

  • 第 1.6 章 Tool Calling：工具调用卡片是工具治理在前端的呈现。
  • Agent 状态、记忆与会话：conversation_id（对话编号）和状态标识来自会话状态设计。
  • RAG 章节：citations（引用来源）让检索结果可解释。
  • MCP（模型上下文协议）章节：工具和资源标准化后，前端要能展示工具目录和权限状态。
  • LangGraph（智能体状态图框架）章节：状态图里的节点可以映射成前端进度和卡片。

版本与资料来源​

本节聚焦 AI（人工智能）应用前端的信息架构、字段契约、状态设计、权限提示、日志摘要、兜底体验和面试表达。

资料依据：

过时风险：前端框架、流式传输方案、Agent 运行时事件格式和供应商 SDK（软件开发工具包）会持续变化。进入真实项目开发前，必须重新核对所用框架、模型服务商、企业权限系统和客服平台的最新文档。

继续学习​