From 864224e07c7ed347f08ec10503e1fea50e608dae Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=90=89=E9=91=AB=E5=8D=87?= <xsji@kland.com.cn>
Date: Thu, 25 Jun 2026 16:07:54 +0800
Subject: [PATCH] =?UTF-8?q?feat(message-token-usage):=20=E9=80=9F=E5=BA=A6?=
 =?UTF-8?q?=E6=9D=A1=E4=B8=8B=E6=96=B9=E5=B8=B8=E9=A9=BB=E9=A2=9C=E8=89=B2?=
 =?UTF-8?q?=E5=90=AB=E4=B9=89=E5=9B=BE=E4=BE=8B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

生成结束后在速度条下方展示一行图例(SpeedLegend),把进度条配色归并为用户视角的
延迟正常/微长/长 + 无响应四类说明,帮助用户理解速度条颜色代表的模型生成延迟状态。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../messages/message-token-usage.tsx          | 40 +++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/frontend-web/src/components/workspace/messages/message-token-usage.tsx b/frontend-web/src/components/workspace/messages/message-token-usage.tsx
index f45b2ef0..21cf508b 100644
--- a/frontend-web/src/components/workspace/messages/message-token-usage.tsx
+++ b/frontend-web/src/components/workspace/messages/message-token-usage.tsx
@@ -31,6 +31,44 @@ export function formatDuration(ms: number): string {
   return `${mins}m ${secs}s`;
 }
 
+/**
+ * 速度条颜色含义图例 —— 生成结束后常驻在速度条下方一行，向用户解释进度条
+ * 颜色代表的「模型生成延迟」状态。进度条本身仍是 5 档(极快/流畅/一般/偏慢/
+ * 缓慢)的连续配色;这里把它归并成用户视角的 3 类延迟 + 「无响应」来说明:
+ *   绿(#16a34a，极快/流畅) → 延迟正常
+ *   黄(#eab308，一般)       → 延迟微长
+ *   红(#ef4444，偏慢/缓慢)  → 延迟长，可能失败
+ *   灰(#9ca3af)            → 无响应(无进度条/0 tok/s)，任务失败，请重试
+ */
+const SPEED_LEGEND: { color: string; label: string }[] = [
+  { color: "#16a34a", label: "延迟正常" },
+  { color: "#eab308", label: "延迟微长" },
+  { color: "#ef4444", label: "延迟长，可能失败" },
+  { color: "#9ca3af", label: "无响应，任务失败，请重试" },
+];
+
+export function SpeedLegend({ className }: { className?: string }) {
+  return (
+    <span
+      className={cn(
+        "text-muted-foreground inline-flex flex-wrap items-center gap-x-2.5 gap-y-0.5",
+        className,
+      )}
+    >
+      {SPEED_LEGEND.map((item) => (
+        <span className="inline-flex items-center gap-1" key={item.label}>
+          <span
+            aria-hidden
+            className="inline-block size-2 shrink-0 rounded-full"
+            style={{ backgroundColor: item.color }}
+          />
+          {item.label}
+        </span>
+      ))}
+    </span>
+  );
+}
+
 export function SpeedPill({ metric }: { metric: MessageMetric }) {
   const fill = Math.max(0, Math.min(1, metric.tokensPerSec / FULL_SCALE_TOKENS_PER_SEC));
   const { color, label } = classifySpeed(metric.tokensPerSec);
@@ -132,6 +170,8 @@ export function MessageTokenUsage({
               {formatDuration(resolvedMetric.durationMs)}
             </span>
           )}
+          {/* 生成结束(非流式中)后常驻一行颜色含义说明。 */}
+          {!resolvedMetric.isActive && <SpeedLegend className="basis-full" />}
         </>
       ) : null}
     </div>