@tfdesign/b-end 1.0.11 → 1.0.13

package/src/_b_end_runtime/components/ChatMessage.jsx

@@ -3,7 +3,7 @@
  *
  * 行业对齐：assistant-ui Message / Vercel AI SDK Message / Microsoft Copilot ChatMessage。
  * 与 ChatBubble（仅气泡）、ChatInput（输入器）共同组成 Chat 命名空间。
- * 样式依赖：入口 CSS 须 @import "@tf-designsystem/b-end/theme.css"（提供 --color-border-default、--color-blueGrey-*、--tfds-ai-execution-* 等）；缺失时 var() 无效，追问/执行流等易出现深黑描边。
+ * 样式依赖：入口 CSS 须 @import "@tfdesign/b-end/theme.css"（提供 --color-border-default、--color-blueGrey-*、--tfds-ai-execution-* 等）；缺失时 var() 无效，追问/执行流等易出现深黑描边。
  * 一个 ChatMessage = 一条会话消息，按 role 渲染：
  *   · role='ai'   AI 输出消息（默认）：header / thinking / plan / 执行流(title+steps/taskGroups)
  *                  / 结果(resultText+resultArtifacts+confirms) / taskBadge / actions / followUps
@@ -41,7 +41,7 @@
  * @prop {string} [statusIconName='check-circle-stroked'] — 标题左侧状态图标名（completed 时使用）
  * @prop {Array|null} [steps=DEFAULT_CHAT_STEPS] — 执行步骤数组
  * @prop {Array|null} [taskGroups=null] — 多任务组（每组可独立折叠 + 流式输出）
- * @prop {Array|null} [confirms=null] — 人工确认节点数组（原 humanConfirmNodes）
+ * @prop {Array|null} [confirms=null] — 人工确认节点数组（原 humanConfirmNodes），支持 mode='text-card'|'card-only'|'option-card'|'form-card'（option-card = 澄清确认卡片1，form-card = 澄清确认卡片2）
  * @prop {string} [resultText=''] — 结果节点文案
  * @prop {object|null} [resultArtifact=null] — 结果节点单个产物卡片（兼容旧 API）
  * @prop {Array|null} [resultArtifacts=null] — 结果节点产物卡片数组
@@ -54,7 +54,10 @@
  */
 
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import Button from './Button';
 import Icon from './Icon';
+import RadioGroup, { Radio } from './Radio';
+import Form from './Form';
 import Tooltip from './Tooltip';
 import catcatSvg from './file-type-assets/catcat.svg';
 import { getFileTypeIcon } from './file-type-assets';
@@ -247,6 +250,77 @@ export const DEFAULT_CHAT_CONFIRMS = [
   },
 ];
 
+export const DEFAULT_CHAT_OPTION_CONFIRM = [
+  {
+    id: 'confirm-option-card',
+    mode: 'option-card',
+    title: '澄清确认',
+    iconName: 'clipboard-check-stroked',
+    primaryActionLabel: '确认',
+    secondaryActionLabel: '',
+    defaultSelectedValue: 'handoff-guide',
+    options: [
+      {
+        value: 'handoff-guide',
+        label: '方案1： 用户请求转人工但系统未触发转接，持续引导自助操作',
+      },
+      {
+        value: 'handoff',
+        label: '方案2： 用户请求转人工',
+      },
+      {
+        value: 'self-service',
+        label: '方案3： 持续引导自助操作',
+      },
+    ],
+  },
+];
+
+export const DEFAULT_CHAT_FORM_CONFIRM = [
+  {
+    id: 'confirm-form-card',
+    mode: 'form-card',
+    title: '澄清确认',
+    iconName: 'clipboard-check-stroked',
+    primaryActionLabel: '确认',
+    secondaryActionLabel: '',
+    formItems: [
+      {
+        id: 'scene',
+        label: '业务场景',
+        type: 'select',
+        placeholder: '请选择业务场景',
+        defaultValue: 'after-sales',
+        options: [
+          { value: 'after-sales', label: '售后咨询' },
+          { value: 'pre-sales', label: '售前咨询' },
+          { value: 'logistics', label: '物流问题' },
+        ],
+        fullWidth: true,
+      },
+      {
+        id: 'channel',
+        label: '处理渠道',
+        type: 'select',
+        placeholder: '请选择处理渠道',
+        defaultValue: 'self-service',
+        options: [
+          { value: 'self-service', label: '自助引导' },
+          { value: 'handoff', label: '转人工' },
+        ],
+        fullWidth: true,
+      },
+      {
+        id: 'remark',
+        label: '补充说明',
+        type: 'input',
+        placeholder: '请输入补充说明（可选）',
+        fullWidth: true,
+      },
+    ],
+  },
+];
+
 /* ── 默认示例数据：新增模块 ── */
 export const DEFAULT_CHAT_HEADER = {
   name: 'OLA AI',
@@ -407,29 +481,15 @@ const HUMAN_CONFIRM_TOGGLE = [
 const HUMAN_CONFIRM_BODY = 'flex w-full min-w-0 flex-col items-stretch justify-center rounded-[12px] border border-border-default px-[19px] py-[15px]';
 const HUMAN_CONFIRM_DESCRIPTION = 'w-full min-w-0 text-sm font-normal leading-5 tracking-[0] text-justify';
 const HUMAN_CONFIRM_ACTIONS = 'flex w-full min-w-0 items-center justify-end gap-3';
-const HUMAN_CONFIRM_SECONDARY_BUTTON = [
-  'inline-flex h-[36px] shrink-0 items-center justify-center rounded-md border',
-  'border-border-default bg-surface px-[11px] py-[5px]',
-  'text-sm [font-weight:var(--font-semibold)] leading-5 tracking-[0] text-foreground-secondary',
-  'cursor-pointer transition-all duration-150',
-  '[outline:2px_solid_transparent] outline-offset-2',
-  'hover:bg-blueGrey-50 hover:border-border-strong',
-  'active:bg-blueGrey-100 active:scale-[0.97]',
-  'focus-visible:outline-blueGrey-400',
-  'disabled:opacity-50 disabled:cursor-not-allowed disabled:pointer-events-none',
-].join(' ');
-const HUMAN_CONFIRM_PRIMARY_BUTTON = [
-  'inline-flex h-[36px] shrink-0 items-center justify-center rounded-md border border-transparent',
-  'bg-blueGrey-800 px-3 py-[6px]',
-  'text-sm [font-weight:var(--font-semibold)] leading-5 tracking-[0] text-white',
-  'cursor-pointer transition-all duration-150',
-  '[outline:2px_solid_transparent] outline-offset-2',
-  'hover:bg-blueGrey-700',
-  'active:bg-blueGrey-800 active:scale-[0.97]',
-  'focus-visible:outline-blueGrey-400',
-  'disabled:opacity-50 disabled:cursor-not-allowed disabled:pointer-events-none',
-].join(' ');
 const HUMAN_CONFIRM_COLLAPSED = 'flex w-full min-w-0 max-w-full items-center gap-2 rounded-[12px] border border-border-default px-4 py-3';
+const HUMAN_CONFIRM_OPTION_CARD = HUMAN_CONFIRM_CARD;
+const HUMAN_CONFIRM_OPTION_HEADER = HUMAN_CONFIRM_HEADER;
+const HUMAN_CONFIRM_OPTION_ICON_WRAP = HUMAN_CONFIRM_ICON_WRAP;
+const HUMAN_CONFIRM_OPTION_TITLE = HUMAN_CONFIRM_TITLE;
+const HUMAN_CONFIRM_OPTION_BODY = HUMAN_CONFIRM_BODY;
+const HUMAN_CONFIRM_OPTION_GROUP = 'w-full gap-2';
+const HUMAN_CONFIRM_OPTION_RADIO = 'w-full min-w-0 !justify-start';
+const HUMAN_CONFIRM_OPTION_ACTIONS = HUMAN_CONFIRM_ACTIONS;
 
 /* ── 新增：AI 头像 / 深度思考 / 任务规划 / 追问 / 消息操作 / 任务徽章 / 用户气泡 类名 ── */
 const AI_HEADER = 'flex w-full min-w-0 items-center gap-2';
@@ -487,7 +547,7 @@ const TASK_PLAN_ITEM_TEXT = [
   'flex-1 min-w-0 text-sm font-normal leading-5 tracking-[0]',
 ].join(' ');
 const TASK_PLAN_FOOTER = 'mt-3 flex w-full min-w-0 items-center justify-end gap-3';
-/* TASK_PLAN_PRIMARY_BUTTON 已废弃，统一复用 HUMAN_CONFIRM_PRIMARY_BUTTON / HUMAN_CONFIRM_SECONDARY_BUTTON */
+/* TaskPlan / HumanConfirm 的主次操作统一复用基础 Button */
 
 const FOLLOW_UP_GROUP = 'flex w-full min-w-0 flex-col items-stretch gap-2';
 const FOLLOW_UP_BUTTON = [
@@ -701,8 +761,28 @@ function normalizeResultArtifacts(resultArtifacts, resultArtifact) {
   return normalizedSingle ? [normalizedSingle] : [];
 }
 
+function normalizeConfirmOption(option, index) {
+  if (typeof option === 'string') {
+    return {
+      value: option,
+      label: option,
+    };
+  }
+  const value = option?.value ?? option?.id ?? `option-${index}`;
+  return {
+    value,
+    label: option?.label ?? option?.title ?? String(value),
+    disabled: option?.disabled === true,
+  };
+}
+
 function normalizeHumanConfirmNode(node, index) {
-  const mode = ['text-card', 'card-only', 'collapsed'].includes(node?.mode) ? node.mode : 'text-card';
+  const mode = ['text-card', 'card-only', 'option-card', 'form-card', 'collapsed'].includes(node?.mode) ? node.mode : 'text-card';
+  const options = Array.isArray(node?.options)
+    ? node.options.map(normalizeConfirmOption).filter((option) => option.label)
+    : [];
+  const defaultSelectedValue = node?.defaultSelectedValue ?? node?.selectedValue ?? options[0]?.value;
+  const formItems = Array.isArray(node?.formItems) ? node.formItems : [];
   return {
     id: node?.id ?? `human-confirm-${index}`,
     mode,
@@ -713,6 +793,11 @@ function normalizeHumanConfirmNode(node, index) {
     iconName: node?.iconName ?? 'sticker-square-stroked',
     primaryActionLabel: node?.primaryActionLabel ?? '确认执行',
     secondaryActionLabel: node?.secondaryActionLabel ?? '编辑',
+    defaultConfirmed: node?.defaultConfirmed === true,
+    options,
+    defaultSelectedValue,
+    formItems,
+    onOptionChange: typeof node?.onOptionChange === 'function' ? node.onOptionChange : null,
     onPrimaryAction: typeof node?.onPrimaryAction === 'function' ? node.onPrimaryAction : null,
     onSecondaryAction: typeof node?.onSecondaryAction === 'function' ? node.onSecondaryAction : null,
     onToggleCollapsed: typeof node?.onToggleCollapsed === 'function' ? node.onToggleCollapsed : null,
@@ -1182,26 +1267,26 @@ function TaskPlanCard({ taskPlan, tokenStyles }) {
           {taskPlan.primaryActionLabel || taskPlan.secondaryActionLabel ? (
             <div className={TASK_PLAN_FOOTER}>
               {taskPlan.secondaryActionLabel ? (
-                <button
-                  type="button"
-                  className={HUMAN_CONFIRM_SECONDARY_BUTTON}
+                <Button
+                  variant="outline-black"
+                  size="md"
                   onClick={handleSecondary}
                   disabled={confirmed}
                   data-tfds-component="ChatMessage.TaskPlanAction"
                 >
                   {taskPlan.secondaryActionLabel}
-                </button>
+                </Button>
               ) : null}
               {taskPlan.primaryActionLabel ? (
-                <button
-                  type="button"
-                  className={HUMAN_CONFIRM_PRIMARY_BUTTON}
+                <Button
+                  variant="primary"
+                  size="md"
                   onClick={handlePrimary}
                   disabled={confirmed}
                   data-tfds-component="ChatMessage.TaskPlanAction"
                 >
                   {taskPlan.primaryActionLabel}
-                </button>
+                </Button>
               ) : null}
             </div>
           ) : null}
@@ -1569,24 +1654,49 @@ function HumanConfirmNode({ node, tokenStyles }) {
     : () => setInternalCollapsed((v) => !v);
 
   /* 点击主按钮后进入"已确认"禁用态：内容半透明、按钮禁用 */
-  const [confirmed, setConfirmed] = useState(false);
+  const [confirmed, setConfirmed] = useState(node.defaultConfirmed === true);
+  const [selectedOptionValue, setSelectedOptionValue] = useState(node.defaultSelectedValue);
+  useEffect(() => {
+    if (node.defaultConfirmed === true) setConfirmed(true);
+  }, [node.defaultConfirmed]);
+  useEffect(() => {
+    setSelectedOptionValue(node.defaultSelectedValue);
+  }, [node.defaultSelectedValue]);
   const handlePrimary = () => {
-    if (typeof node.onPrimaryAction === 'function') node.onPrimaryAction();
+    const selectedOption = node.options.find((option) => String(option.value) === String(selectedOptionValue)) ?? null;
+    if (typeof node.onPrimaryAction === 'function') {
+      node.onPrimaryAction({
+        value: selectedOptionValue,
+        option: selectedOption,
+      });
+    }
     setConfirmed(true);
   };
   const handleSecondary = () => {
     if (typeof node.onSecondaryAction === 'function') node.onSecondaryAction();
   };
+  const handleOptionChange = (nextValue) => {
+    setSelectedOptionValue(nextValue);
+    const selectedOption = node.options.find((option) => String(option.value) === String(nextValue)) ?? null;
+    if (typeof node.onOptionChange === 'function') {
+      node.onOptionChange(nextValue, selectedOption);
+    }
+  };
 
   const showIntroText = node.mode === 'text-card' && node.introText && !isCollapsed;
   const showCardBody = !isCollapsed;
+  const isOptionCard = node.mode === 'option-card';
+  const isFormCard = node.mode === 'form-card';
 
+  const headerClassName = isOptionCard ? HUMAN_CONFIRM_OPTION_HEADER : HUMAN_CONFIRM_HEADER;
+  const iconWrapClassName = isOptionCard ? HUMAN_CONFIRM_OPTION_ICON_WRAP : HUMAN_CONFIRM_ICON_WRAP;
+  const titleClassName = isOptionCard ? HUMAN_CONFIRM_OPTION_TITLE : HUMAN_CONFIRM_TITLE;
   const header = (
-    <div className={HUMAN_CONFIRM_HEADER}>
-      <div className={HUMAN_CONFIRM_ICON_WRAP} style={tokenStyles.iconWrap} aria-hidden="true">
+    <div className={headerClassName}>
+      <div className={iconWrapClassName} style={tokenStyles.iconWrap} aria-hidden="true">
         <Icon name={node.iconName} size={16} color="var(--color-foreground-secondary)" aria-hidden="true" />
       </div>
-      <p className={HUMAN_CONFIRM_TITLE} style={tokenStyles.title}>
+      <p className={titleClassName} style={tokenStyles.title}>
         {node.title}
       </p>
       <button
@@ -1623,39 +1733,78 @@ function HumanConfirmNode({ node, tokenStyles }) {
           {node.introText}
         </p>
       ) : null}
-      <div className={HUMAN_CONFIRM_CARD} style={tokenStyles.humanConfirmCard}>
+      <div
+        className={isOptionCard || isFormCard ? HUMAN_CONFIRM_OPTION_CARD : HUMAN_CONFIRM_CARD}
+        style={tokenStyles.humanConfirmCard}
+      >
         {header}
         {showCardBody ? (
           <div
-            className={[HUMAN_CONFIRM_BODY, confirmed ? 'opacity-60' : ''].filter(Boolean).join(' ')}
+            className={[
+              isOptionCard || isFormCard ? HUMAN_CONFIRM_OPTION_BODY : HUMAN_CONFIRM_BODY,
+              confirmed ? 'opacity-60' : '',
+            ].filter(Boolean).join(' ')}
             style={tokenStyles.humanConfirmBody}
           >
-            {node.description ? (
+            {isOptionCard ? (
+              <RadioGroup
+                variant="brand"
+                styleType="pureCard"
+                layout="vertical"
+                value={selectedOptionValue}
+                onChange={handleOptionChange}
+                disabled={confirmed}
+                className={HUMAN_CONFIRM_OPTION_GROUP}
+                data-tfds-component="ChatMessage.OptionCardRadioGroup"
+              >
+                {node.options.map((option) => (
+                  <Radio
+                    key={String(option.value)}
+                    value={option.value}
+                    disabled={option.disabled}
+                    className={HUMAN_CONFIRM_OPTION_RADIO}
+                  >
+                    {option.label}
+                  </Radio>
+                ))}
+              </RadioGroup>
+            ) : isFormCard ? (
+              <Form
+                items={node.formItems}
+                layout="vertical"
+                size="md"
+                disabled={confirmed}
+                className="w-full min-w-0 gap-3 pb-2"
+                data-tfds-component="ChatMessage.FormCardForm"
+              />
+            ) : node.description ? (
               <p className={HUMAN_CONFIRM_DESCRIPTION} style={tokenStyles.title}>
                 {node.description}
               </p>
             ) : null}
           </div>
         ) : null}
-        <div className={HUMAN_CONFIRM_ACTIONS}>
-          <button
-            type="button"
-            className={HUMAN_CONFIRM_SECONDARY_BUTTON}
-            onClick={handleSecondary}
-            disabled={confirmed}
-            data-tfds-component="ChatMessage.ConfirmAction"
-          >
-            {node.secondaryActionLabel}
-          </button>
-          <button
-            type="button"
-            className={HUMAN_CONFIRM_PRIMARY_BUTTON}
+        <div className={isOptionCard || isFormCard ? HUMAN_CONFIRM_OPTION_ACTIONS : HUMAN_CONFIRM_ACTIONS}>
+          {node.secondaryActionLabel ? (
+            <Button
+              variant="outline-black"
+              size="md"
+              onClick={handleSecondary}
+              disabled={confirmed}
+              data-tfds-component="ChatMessage.ConfirmAction"
+            >
+              {node.secondaryActionLabel}
+            </Button>
+          ) : null}
+          <Button
+            variant="primary"
+            size="md"
             onClick={handlePrimary}
-            disabled={confirmed}
+            disabled={confirmed || (isOptionCard && node.options.length === 0)}
             data-tfds-component="ChatMessage.ConfirmAction"
           >
             {node.primaryActionLabel}
-          </button>
+          </Button>
         </div>
       </div>
     </div>
@@ -1918,13 +2067,13 @@ export default function ChatMessage({
   useEffect(() => {
     if (initialCardActioned) setCardActioned(true);
   }, [initialCardActioned]);
-  const wrapPrimaryAction = (originalFn) => () => {
-    if (typeof originalFn === 'function') originalFn();
+  const wrapPrimaryAction = (originalFn) => (...args) => {
+    if (typeof originalFn === 'function') originalFn(...args);
     setCardActioned(true);
   };
   /* 取消按钮也算作"已处理"：消息变为历史消息后操作栏占位需要保留 */
-  const wrapSecondaryAction = (originalFn) => () => {
-    if (typeof originalFn === 'function') originalFn();
+  const wrapSecondaryAction = (originalFn) => (...args) => {
+    if (typeof originalFn === 'function') originalFn(...args);
     setCardActioned(true);
   };
 

package/src/_b_end_runtime/components/ChatMessage.tokens.js

@@ -67,6 +67,36 @@ export const CHAT_MESSAGE_TOKEN_MAP = {
     { label: '正文描边', cssProp: 'border-color', token: '--color-white', value: '#FFFFFF', state: 'body' },
     { label: '正文底色', cssProp: 'background', token: '--color-card-secondary', value: 'rgba(255,255,255,0.65)', state: 'body' },
   ],
+  澄清确认卡片1: [
+    { label: '实现来源', cssProp: 'component', value: 'RadioGroup + Radio / styleType="pureCard" / variant="brand"', state: 'mode=option-card' },
+    { label: '外框背景', cssProp: 'background', token: '--color-fill', value: 'rgba(83, 96, 143, 0.07)' },
+    { label: '外框圆角', cssProp: 'border-radius', value: '12px' },
+    { label: '外框内边距', cssProp: 'padding', value: '12px 16px' },
+    { label: '标题字号', cssProp: 'font-size', value: '14px' },
+    { label: '标题行高', cssProp: 'line-height', value: '20px' },
+    { label: '标题字重', cssProp: 'font-weight', token: '--font-semibold', value: '600（运行时使用 [font-weight:var(--font-semibold)]）' },
+    { label: '内容描边', cssProp: 'border-color', token: '--color-white', value: '#FFFFFF' },
+    { label: '内容底色', cssProp: 'background', token: '--color-card-secondary', value: 'rgba(255,255,255,0.65)' },
+    { label: '内容圆角', cssProp: 'border-radius', value: '12px' },
+    { label: '内容内边距', cssProp: 'padding', value: '15px 19px' },
+    { label: '选项间距', cssProp: 'gap', value: '8px', state: 'RadioGroup vertical' },
+  ],
+  澄清确认卡片2: [
+    { label: '实现来源', cssProp: 'component', value: 'Form + FormField / type="select" | "input" | ...', state: 'mode=form-card' },
+    { label: '外框背景', cssProp: 'background', token: '--color-fill', value: 'rgba(83, 96, 143, 0.07)' },
+    { label: '外框圆角', cssProp: 'border-radius', value: '12px' },
+    { label: '外框内边距', cssProp: 'padding', value: '12px 16px' },
+    { label: '标题字号', cssProp: 'font-size', value: '14px' },
+    { label: '标题行高', cssProp: 'line-height', value: '20px' },
+    { label: '标题字重', cssProp: 'font-weight', token: '--font-semibold', value: '600（运行时使用 [font-weight:var(--font-semibold)]）' },
+    { label: '内容描边', cssProp: 'border-color', token: '--color-white', value: '#FFFFFF' },
+    { label: '内容底色', cssProp: 'background', token: '--color-card-secondary', value: 'rgba(255,255,255,0.65)' },
+    { label: '内容圆角', cssProp: 'border-radius', value: '12px' },
+    { label: '内容内边距', cssProp: 'padding', value: '15px 19px' },
+    { label: '表单布局', cssProp: 'layout', value: 'vertical', state: 'Form layout' },
+    { label: '表单尺寸', cssProp: 'size', value: 'md', state: 'Form size' },
+    { label: '字段间距', cssProp: 'gap', value: '12px', state: 'Form items vertical' },
+  ],
   确认按钮: [
     { label: '主背景', cssProp: 'background', token: '--color-neutral', value: '#343B3A', state: 'primary' },
     { label: '主文字', cssProp: 'color', token: '--color-white', value: '#FFFFFF', state: 'primary' },

package/src/_b_end_runtime/components/ChatMessagePreview.jsx

@@ -6,6 +6,8 @@ import ChatMessage, {
   DEFAULT_CHAT_ARTIFACT_GROUP,
   DEFAULT_CHAT_CONFIRMS,
   DEFAULT_CHAT_FOLLOW_UPS,
+  DEFAULT_CHAT_FORM_CONFIRM,
+  DEFAULT_CHAT_OPTION_CONFIRM,
   DEFAULT_CHAT_PLAN,
   DEFAULT_CHAT_RESULT,
   DEFAULT_CHAT_RESULT_ARTIFACTS,
@@ -91,6 +93,18 @@ function getProps(subComponent, variant, options = {}) {
           confirms: DEFAULT_CHAT_CONFIRMS.map(({ introText, ...rest }) => rest),
         };
       }
+      if (variant === 'option-card') {
+        return {
+          role: 'ai', title: '', steps: null,
+          confirms: DEFAULT_CHAT_OPTION_CONFIRM,
+        };
+      }
+      if (variant === 'form-card') {
+        return {
+          role: 'ai', title: '', steps: null,
+          confirms: DEFAULT_CHAT_FORM_CONFIRM,
+        };
+      }
       return {
         role: 'ai', title: '', steps: null,
         plan: DEFAULT_CHAT_PLAN,

package/src/_b_end_runtime/components/CustomerServiceWorkspaceFrame.jsx

@@ -9,6 +9,7 @@ import { useEffect, useMemo, useRef, useState } from 'react';
 import Icon from './Icon';
 import Button from './Button';
 import Tabs from './Tabs';
+import Tooltip from './Tooltip';
 
 const DEFAULT_STATS = [
   { id: 'online-users', iconName: 'users-01-stroked', value: '12', label: '在线接待数' },
@@ -27,6 +28,9 @@ const DEFAULT_MODES = [
   { id: 'managed', label: '托管模式' },
 ];
 
+const MAX_STATS = 4;
+const MAX_TOOLS = 3;
+
 // 覆盖深度必须大于 16px 圆角半径，避免主面板圆角切角处露出左板块右边界。
 const PANEL_OVERLAP = 32;
 
@@ -79,6 +83,14 @@ function normalizeItems(items, fallback) {
   return Array.isArray(items) && items.length > 0 ? items : fallback;
 }
 
+function getStatTooltip(item) {
+  return item.tooltip || item.description || item.label || item.value;
+}
+
+function getStatAriaLabel(item) {
+  return [item.label, item.value].filter(Boolean).join(' ');
+}
+
 function resolveMaxSideWidth(workspaceWidth, maxSideWidth, minSideWidth, mainMinWidth) {
   const finiteMaxSideWidth = Number.isFinite(maxSideWidth) ? maxSideWidth : Number.POSITIVE_INFINITY;
   if (workspaceWidth <= 0) {
@@ -116,8 +128,8 @@ export default function CustomerServiceWorkspaceFrame({
 }) {
   const workspaceRef = useRef(null);
   const modeItems = useMemo(() => normalizeItems(modes, DEFAULT_MODES), [modes]);
-  const statItems = useMemo(() => normalizeItems(stats, DEFAULT_STATS), [stats]);
-  const toolItems = useMemo(() => normalizeItems(tools, DEFAULT_TOOLS), [tools]);
+  const statItems = useMemo(() => normalizeItems(stats, DEFAULT_STATS).slice(0, MAX_STATS), [stats]);
+  const toolItems = useMemo(() => normalizeItems(tools, DEFAULT_TOOLS).slice(0, MAX_TOOLS), [tools]);
   const isControlled = typeof mode === 'string';
   const [innerMode, setInnerMode] = useState(defaultMode);
   const [workspaceWidth, setWorkspaceWidth] = useState(0);
@@ -235,10 +247,21 @@ export default function CustomerServiceWorkspaceFrame({
           <div className={METRICS_SLOT}>
             <div className={METRICS_CARD} data-tfds-component="CustomerServiceWorkspaceFrame.Metrics">
               {statItems.map((item, index) => (
-                <div className={METRIC_ITEM} key={item.id || `${item.iconName}-${index}`} title={item.label}>
-                  <Icon name={item.iconName} size={14} className="text-foreground" aria-hidden="true" />
-                  <p className={METRIC_TEXT}>{item.value}</p>
-                </div>
+                <Tooltip
+                  key={item.id || `${item.iconName}-${index}`}
+                  content={getStatTooltip(item)}
+                  placement="top"
+                  triggerClassName="inline-flex shrink-0"
+                >
+                  <div
+                    className={METRIC_ITEM}
+                    title={item.label}
+                    aria-label={getStatAriaLabel(item)}
+                  >
+                    <Icon name={item.iconName} size={14} className="text-foreground" aria-hidden="true" />
+                    <p className={METRIC_TEXT}>{item.value}</p>
+                  </div>
+                </Tooltip>
               ))}
               {toolItems.length > 0 ? <span className={METRIC_DIVIDER} aria-hidden="true" /> : null}
               {toolItems.length > 0 ? (
@@ -251,6 +274,7 @@ export default function CustomerServiceWorkspaceFrame({
                       size="sm"
                       icon={<Icon name={item.iconName} size={16} />}
                       iconOnly
+                      tooltip={item.label}
                       aria-label={item.label}
                       title={item.label}
                     />

package/src/_b_end_runtime/components/CustomerServiceWorkspaceFrame.tokens.js

@@ -24,6 +24,11 @@ export const CUSTOMER_SERVICE_WORKSPACE_FRAME_TOKEN_MAP = {
     { label: '在线点颜色', cssProp: 'background', token: '--color-green-500', value: '#3EB346' },
   ],
   指标工具区: [
+    { label: '数据展示上限', cssProp: 'count', value: '最多 4 类高优关注数据', state: 'stats' },
+    { label: '数据展示形式', cssProp: 'structure', value: 'Icon + 数字值', state: 'stats' },
+    { label: '数据说明', cssProp: 'component', value: 'Tooltip / hover + focus 展示文案解释', state: 'stats' },
+    { label: '工具按钮上限', cssProp: 'count', value: '最多 3 个平台框架级按钮', state: 'tools' },
+    { label: '工具按钮语义', cssProp: 'scope', value: '全局设置 / 平台公告 / 平台数据统计等', state: 'tools' },
     { label: '背景', cssProp: 'background', value: 'rgba(255,255,255,0.6)' },
     { label: '描边', cssProp: 'border-color', token: '--color-white', value: '#FFFFFF' },
     { label: '圆角', cssProp: 'border-radius', token: '--radius-md', value: '8px（Figma 6px，落到现有 md 档）' },