# TFDS B 端设计原则（设计品味与体验判断）

> **本文档定位（AI 必读）**：本文件回答“**为什么这样做**”，是 UX 取舍、信息优先级、视觉气质的判断书。**它不是事实源**。
>
> - 具体组件、props、rules、examples → `components.index.json`
> - 整页生成硬规则 + 交付前 Checklist → `SKILL.md` / `CHECKLIST.md`
> - 该页用哪个模板 + 触发关键词 → `PAGE_ARCHETYPES.md`
> - 选定模板后的容器语义 / 间距 / 滚动 → `LAYOUT_RECIPES.md`
> - 骨架 / 双栏多栏 / 宽度 / 嵌套 / 响应式 → `LAYOUT_RULES.md`
> - Token 兜底（组件未覆盖时） + Token 自检 → `GLOBAL_DESIGN_RULES.md`
> - **本文件冲突时一律以以上 6 份文档为准**（详见 §9）。
>
> **作用域**：生成任何 TFDS B 端页面前，先用本文件判断页面气质、信息优先级和 UX 取舍。

---

## 0.0 快查索引（按问题找章节，不要从头读到尾）

> 本文件较长。**生成前**先查这张表定位章节；**生成后**用 §8 设计自检 + `GLOBAL_DESIGN_RULES.md §14` 跑 Token 自检。

| 你的问题 / 信号 | 直接跳到 |
| --- | --- |
| 整页第一屏要让用户看见什么？取舍优先级是什么？ | §1.1 任务先于装饰、§1.2 内容先于容器 |
| 标题为什么不能用大字号 / `font-bold`？层级到底靠什么？ | §1.3 层级靠结构、§2 视觉调性 |
| 什么时候允许用 AI 渐变？非 AI 页能否装饰性使用？ | §1.5、§2.3、+ `GLOBAL_DESIGN_RULES.md §1.4` |
| 页面 header 到底坐灰底还是包白卡？ | §4.1 页面元信息直接坐灰底、§4.2 白卡只承载工作内容 |
| “Card 组件” 和 “工作白卡” 怎么区分？什么时候用哪个？ | §4.3 工作白卡 vs Card 组件 |
| **`Card` 五类语义（data / product / info / info2 / info3）怎么选？** | **§4.4 Card 五类语义选型（AI 必读）** |
| Card / 图标的色系语义（pink / blue / orange…）怎么对应业务？ | §4.5 图标统一语义规则 |
| `AgentNodeCard` ↔ `AgentStatusBar` 强配套？节点上下间距像素值？ | §4.6 Agent Flow 双组件配套准则 |
| `AgentNodeCard` 内能放哪些 Card type？分组标题用什么？ | §4.6.1 AgentNodeCard 内嵌组件样式与文案 |
| 工作台左侧 `ConversationList` 折叠时为什么主区被挤出？ | §4.7 工作台左列折叠协同 |
| `ConversationList` 列表项右侧标签的色 / 文案 / 顺序规则？ | §4.8 会话列表项标签层级 |
| 客服 / 工单 Agent 工作台拖拽链路丢失？必传 props 清单？ | §4.9 工作台框架拖拽能力完整性 |
| 这一类页面（列表 / 详情 / IM / Playground / 入口…）的设计要点 | §5.1 – §5.11（先去 `PAGE_ARCHETYPES.md` 选模板） |
| NavBar / FormTitle / Button / Tabs / Form / Chat / Modal 用什么角色？ | §6 组件设计角色 |
| 写代码前还要回答哪些问题？ | §7 生成前决策流程（排除式 + 确认式） |
| 交付前要检查哪些设计层面的事？ | §8 生成后设计自检 |
| 本文档与其他规范冲突时听谁的？ | §9 与其他规范的关系 |

---

## 目录

- §0 一句话定位
- §1 设计哲学
- §2 视觉调性
- §3 平台视觉 DNA（标杆页面沉淀）
- §4 页面层级判断
  - §4.1 页面元信息直接坐灰底
  - §4.2 白卡只承载工作内容
  - §4.3 工作白卡 vs Card 组件
  - **§4.4 Card 五类语义选型（AI 必读）**
  - **§4.5 图标统一语义规则**
  - §4.6 Agent Flow 双组件配套准则
  - §4.7 工作台左列折叠协同
  - §4.8 会话列表项标签层级
  - §4.9 工作台框架拖拽能力完整性
- §5 页面类型设计判断（先去 `PAGE_ARCHETYPES.md` 选模板再读本节）
- §6 组件设计角色
- §7 生成前决策流程
- §8 生成后设计自检
- §9 与其他规范的关系

---

## 0. 一句话定位

TFDS 是面向企业级 B 端平台的高密度浅色系统，适用于管理后台、运营平台、数据平台、客服工作台、配置中心、审核系统、流程工具和 AI 辅助工作台等场景。页面应当专业、克制、清晰，把任务、数据、输入、流程和协作放在视觉中心。品牌青绿用于交互与状态信号；AI 渐变只在明确智能能力场景中作为语义信号，不作为装饰背景。

---

## 1. 设计哲学

### 1.1 任务先于装饰

用户打开 B 端页面是为了完成任务，不是欣赏视觉包装。页面第一屏必须让用户立刻知道：

- 当前在处理什么业务对象
- 当前最重要的状态或风险是什么
- 下一步最合理的操作在哪里
- 需要输入、筛选、对比、确认或查看的内容在哪个区域

如果某个视觉元素不能帮助完成以上任一目标，就不要加。

### 1.2 内容先于容器

TFDS 的容器负责承载工作流，不负责抢视觉权重。大白卡、面板、分区只提供稳定边界；真正的层级来自标题、状态、控件和数据本身。

- 最外层工作白卡：纯白底 + 12px 圆角 + 无 border + 无 shadow
- 白卡之间：靠灰底与 8px 间距分层
- 白卡内部：由 FormTitle、Tabs、Table、Form、TextArea、ChatInput 等组件建立功能区
- 内部控件描边保留，白卡外边界不加描边

### 1.3 层级靠结构，不靠大字号

TFDS 不用“大标题 + 大留白 + 重阴影”制造气势。企业工作台更需要稳定扫描。

- 标题默认用 `FormTitle`，字重 600
- 常规 UI 字号以 14px 为主体，标题通过 600 字重和组件结构区分
- 页面只允许少量 18px / 20px 标题，避免整页所有模块都在喊话
- 强调信息优先用位置、分组、Tag 和操作优先级表达，不靠 `font-bold` 或任意字号

### 1.4 高密度但可扫描

TFDS 的密度应当像成熟企业软件：信息多，但不乱。

- 同组元素用 8px 或 12px，表单字段用 16px，白卡内 padding 用 24px
- 表格、列表、会话、编辑器应撑满可用空间，而不是堆成窄窄一列
- 重要说明完整展示；列表预览、文件名、模型 ID 可省略，但必须配 Tooltip 或详情入口
- 不为了“留白好看”牺牲数据对比效率
- 默认浏览器缩放下必须可用；不要通过缩小页面、扩大浏览器或隐藏控件来掩盖布局碰撞、横向溢出和底部操作不可达的问题

### 1.5 智能能力是局部身份信号，不是全局装饰主题

TFDS 不只服务 AI 工作台。AI 渐变只在页面存在明确智能能力时出现，并只服务于 AI 相关对象，例如 AI 输入框、AI 消息、AI 推荐、AI 执行流、AI 标识。不要把 AI 渐变铺到普通卡片、页面背景、按钮、统计模块上，也不要让非 AI 平台页面带上“为了显得智能”的装饰感。

---

## 2. 视觉调性

### 2.1 基础气质

- **专业**：对齐、清晰、稳定，避免花哨装饰
- **克制**：品牌色少量出现，阴影和渐变不泛用
- **轻盈**：浅灰底 + 白色工作区，靠明度差和圆角分层
- **可信**：状态语义明确，危险、警告、成功、信息不能混用
- **企业平台感**：结构稳定、信息密度适中，既能承载通用管理后台，也能承载 AI 辅助工作流

### 2.2 色彩使用

- 页面底色：浅灰 `var(--color-blueGrey-200)`，用于承载整页工作区
- 白卡底色：`var(--color-surface)`，用于承载真实工作内容
- 主文字：`var(--color-foreground)`，次级说明：`var(--color-foreground-secondary)` / `muted`
- 品牌青绿：只用于焦点、激活、链接、品牌状态、标题竖条
- 语义色：只用于状态反馈，不用于装饰
- AI 渐变：只用于 AI 语义面，不用于普通业务面

### 2.3 禁止的视觉倾向

- 禁止营销页式 hero、彩色光斑、大面积渐变背景，除非当前页面就是明确的 AI 入口页模板
- 禁止普通白卡加重阴影、灰色描边、黑色边框来“显得有层次”
- 禁止整页多个黑色主按钮并列，主操作必须收敛
- 禁止把 Tag、Button、Tabs、Card、FormTitle 用 `div/span` 手搓相似样式
- 禁止用随机 `text-[15px]`、`p-[18px]`、`#333`、`bg-gray-*` 填补审美空白
- 禁止把结构性工作容器做成可点击卡片效果：主白卡、表单面板、结果面板、对话区、详情侧栏不做整卡 hover 变色、投影或浮起
- 禁止把密集表格、表单、日志、代码、配置、结果区放在渐变、透明或弱对比背景上

---

## 3. 平台视觉 DNA（标杆页面沉淀）

### 3.1 灰色应用壳 + 白色工作区

TFDS 平台不是白底网页，也不是传统后台的强边框面板。标准气质是浅灰应用壳承载多个白色工作区。

- 最外层是浅灰画布，导航、页头、分区间距都坐在灰底上
- 真正工作内容进入白色大圆角区域，白卡之间用 8px 灰底缝隙分层
- 白卡不靠边框和阴影强调，靠明度差、圆角、内容标题和控件边界建立层级
- 页面贴近浏览器边缘，不做居中 `max-width` 后台页面

### 3.2 平台导航是“窄侧栏 + 顶部语境切换”

标杆页面普遍使用两层导航：左侧窄导航负责产品/业务域，顶部胶囊负责当前模块或工作模式。

- 左侧导航窄、轻、稳定，图标为主，当前业务项用浅底或品牌色信号提示
- 顶部模块切换优先用胶囊 Tabs / segment，选中态可以是黑色实心胶囊，未选中态保持灰色轻量
- 页面右上角放全局操作，主操作用黑色 primary，次要操作用白底描边或 icon button
- 不要把顶部导航、页面标题和操作按钮塞进白卡内；它们属于应用壳

### 3.3 选择态是细信号，不是大面积染色

TFDS 的选中、激活、当前态都很克制。

- 表格或列表选中：使用品牌描边、左侧细竖条、浅品牌底或小图标，不整块强色填充
- 顶部模块选中：可以使用黑色胶囊，形成明确当前模式
- 状态徽标：使用低饱和浅底 Tag，避免大面积红/绿/橙背景
- hover 只做轻微底色、描边或阴影变化，不做浮夸动效
- hover 反馈必须跟随交互对象本身：按钮、行、选项、入口卡可以响应；工作区容器、设置面板、结果面板只提供稳定边界，不因鼠标经过整体变成“可点击卡”

### 3.4 信息密度高，但阅读路径清楚

标杆页面的密度来自稳定排布，不是把控件挤小。

- 表格行高、列表项高度保持充足，文字 14px 为主，元信息 12px
- 核心对象名用 600 字重，描述和时间戳用 muted 色
- 筛选区靠近内容标题，筛选控件横向排布且固定宽
- 分页、总数、每页数量固定在列表底部，不漂浮在内容中间
- Tabs、筛选栏、按钮组、表单网格和工具条必须适配容器宽度；当信息过多时优先局部滚动、换行或收进更多菜单，不能把卡片或页面撑宽

### 3.5 工作台优先分屏，不堆叠

复杂任务页不是 Dashboard 堆卡片，而是把“上下文、工作内容、配置/详情/产物”分成稳定面板。

- 常见骨架：左侧列表/会话/进程，中间主工作区，右侧详情/配置/预览
- 每个面板只承担一个职责，面板头固定，正文内部滚动
- 左侧用于定位和上下文，中间用于编辑/对话/主内容，右侧用于参数、详情、产物或结果
- 不要把三类内容纵向堆成一个长页面；那会破坏工作流对照

### 3.6 内容产物要像“可交付物”，不是普通卡片

报告、文档、HTML 预览、策略说明、运行产物需要被当作主内容画布处理。

- 产物区通常占据最大面积，使用大白内容画布
- 顶部只保留必要标题、状态和工具图标，减少容器噪音
- 正文排版以可读性为优先，段落、标题、图表、指标卡要形成文档式阅读节奏
- 产物预览不要压缩成多个小卡片，也不要被 AI 进程面板抢占视觉中心

### 3.7 AI 辅助是伴随式，不默认主宰页面

标杆页面中的 AI 能力通常以“进程、建议、输入、产物生成”方式嵌入工作流，而不是把所有页面都变成聊天页。

- 用户未进入具体上下文时，可以使用居中的 AI 输入入口
- 用户已经在处理对象时，AI 应在侧栏、底部输入框、进程卡或建议区中辅助
- AI 进程卡使用轻灰容器、步骤状态和简短总结，避免大段营销式解释
- 只有明确的 AI 入口页，ChatInput 才成为页面中心；管理页和配置页仍以对象和任务为中心

---

## 4. 页面层级判断

### 4.1 页面元信息直接坐灰底

页面级标题、返回、面包屑、页面级 Tabs、页面主次操作属于页面元信息，应直接放在灰底上。不要为了“规整”把页面 header 再包一张白卡。

适用对象：

- 页面标题和描述
- 页面级主按钮、导出、创建、同步等操作
- 页面级筛选入口或全局切换
- 返回、面包屑、产品级上下文

### 4.2 白卡只承载工作内容

白卡应当承载用户真正要处理的内容：

- 表格、列表、筛选结果
- 表单配置、字段编辑
- Prompt / JSON / 代码 / 参数编辑区
- 对话流、消息列表、客服会话
- 运行结果、审核结果、风险明细

不要把“页面标题 + 描述 + 操作按钮”单独包成一张白卡。那会让页面失去主从关系。

### 4.3 区分工作白卡和 Card 组件

TFDS 中有两类“卡片”，不能混用：

- **工作白卡**：页面布局容器，纯白底、12px 圆角、无 border、无 shadow，通常由页面骨架创建。
- **Card 组件**：业务摘要、入口卡、信息卡，使用组件自身样式和 props。它不是所有白色容器的替代品。

不要把 Card 的玻璃感、hover 阴影、20px 圆角套到所有工作白卡上。工作白卡遵守 `GLOBAL_DESIGN_RULES.md` 的白卡铁律。

### 4.4 Card 五类语义选型（AI 必读）

Card 组件提供 `data / product / info / info2 / info3` 五种 `type`，本质是「**承载对象不一样**」，AI 必须按对象语义选型，禁止凭视觉喜好挑卡片样式。

**承载对象映射表（一眼定型）**

| 内容承载对象 | 选 type |
|---|---|
| 摘要 / 趋势 / 工具入口 / 模板入口（脚本、SOP、话术、案例模版） | `data`（数据卡片） |
| 具体业务对象（订单、商品、门店、素材、工单附件、查询结果） | `product`（商品卡片） |
| 身份对象 / 能力本体 + 陈列展示（智能体、知识库、应用、官方能力，3-12 张同屏） | `info`（信息卡片1 / Profile） |
| 推荐入口 / 强行动 CTA（AI 推荐、配置向导、单步启动入口，单页 ≤ 2 张） | `info2`（信息卡片2 / CTA） |
| 列表条目 + 状态识别 + 列表-详情联动（知识列表、规则、策略、SOP、工单列表，单页 ≥ 5 条） | `info3`（信息卡片3 / List Object Row） |

**AI 选型决策树（按顺序提问）**

1. 这段内容是「**具体业务对象**」吗？（订单 / 商品 / 门店 / 素材 / 工单 / 查询结果）→ 是 → `product`。
2. 这段内容是「**身份对象 / 能力本体**」吗？（智能体 / 知识库 / 应用 / 官方能力）→ 是 → 进入 2a；否 → 跳到 3。
   - 2a. 这一屏会出现 ≥ 5 条同类、需要批量比较 / 选择 / 联动右侧详情面板？→ 是 → `info3`；否 → `info`。
3. 这段内容是「**让用户立刻去做某个动作**」吗？（一键生成 / 立即体验 / 开始配置）且单页 ≤ 2 张？→ 是 → `info2`；否 → `data`。

**一句话口诀**：对象 = 商品 → product；对象 = 身份且陈列 → info；对象 = 身份且列表 → info3；对象 = 行动 → info2；对象 = 摘要/趋势/模板 → data。

**信息密度分级**：data（中：标题+描述+1-3 指标+标签）｜ product（中：缩略图+标题+副标题+状态标签）｜ info（高：图标+主副标题+徽标+创建人头像+1-3 辅助指标）｜ info2（低：图标+短标题+短描述+底部徽标+右下圆形箭头）｜ info3（中：标题+右上角状态标签+2 行描述+底部 metaItems 元信息行）。AI 应按"信息密度匹配信息量"避免错配。

**一屏数量节奏（强约束）**：info2 ≤ 2 张（多了退化成"信息广场"，请改 info）｜ info 3-12 张（陈列矩阵）｜ info3 5-30+ 条（密集列表，"列表+详情面板"双栏页）｜ product ≤ 6 张（IM/订单侧栏）｜ data 1-9 张（首页指标 / 工具入口区）。

**强制配套字段（缺即错配）**：
- `product` → `productImageSrc`（或蓝色占位）+ `productStatus`
- `info` → `infoIconName` + `infoMetaBadge` + `infoMetaLabel`（身份感缺一不可）
- `info2` → `onAction` + `animatedActionText`（无动作就别用推荐入口卡）
- `info3` → `status` + `metaItems`（**状态 Tag 是 info3 的灵魂**，缺了就退化成普通描述卡）
- `data` → 建议至少传 `stats` 或 `tags` 之一以承担"摘要"语义

**典型业务场景对照**

| type | 典型业务场景（每类 3 个） |
|---|---|
| `data` | 首页"近 7 天会话量"指标卡 / 工具入口"批量话术生成器" / 模板入口"优秀知识模版" |
| `product` | IM 对话上下文订单卡"订单 202604300018 退款中" / 商品检索结果"海底捞双人套餐" / 工单附件"故障截图.png" |
| `info` | 智能体广场"抖音 AI 创作助手" / 应用中心"直播数据洞察" / 知识库列表（陈列式）"客服话术库" |
| `info2` | 首页推荐区"立即生成报告" / 配置向导首屏"开始配置" / 空态引导"创建第一个 Agent" |
| `info3` | 知识库列表（密集式）"客服话术-退款流程 · 已发布" / 策略列表"高优工单分配 · 审核中" / 工单摘要列表（左列表+右详情） |

**错配自查清单（AI 生成完一定要回看）**

1. 是否用 `info` 来承载列表条目？→ 改 `info3`
2. 是否一页放了 ≥ 3 张 `info2`？→ 把多余的换成 `info`
3. 是否用 `product` 展示纯指标趋势？→ 改 `data`
4. 是否用 `data` 展示具体订单/商品？→ 改 `product`
5. `info3` 是否漏了 status？→ 必须补
6. `info2` 是否漏了 onAction？→ 必须补
7. `info` 是否漏了 `infoMetaBadge` / `infoMetaLabel`？→ 必须补
8. 同一页 `info` 卡的色系是否超过 4 个？→ 多余的统一收敛为 grey 或 inverse

**优先级仲裁**：同一内容同时满足多个条件时，优先级 `info3`（列表条目，强批量场景）> `product`（具体对象）> `info`（身份对象）> `info2`（推荐入口）> `data`（摘要入口）。

### 4.5 图标统一语义规则（强制）

Card 体系内所有出现"图标容器"的位置（信息卡片1 主图标、信息卡片2 左上图标、数据卡片右上可选图标）共用同一套**色系 + 风格**规则。AI 必须按"图标承载什么语义"选择，禁止凭视觉喜好挑色或挑黑底白标。

#### 4.5.1 图标风格选择 — 黑底白标 vs 彩色浅底

| 风格 | 适用语义 | 何时使用 |
|---|---|---|
| `infoIconStyle="inverse"`（黑底白标） | 中性 / 经典 / 专业 / 通用入口 | 卡片要传递"官方/通用/中性能力"，希望标题与描述成为视觉主角；同区块只有 1-2 张同类、强调"通用入口"；**不确定时默认这个**（永远不会出错的安全色） |
| `infoIconStyle="tone"`（彩色浅底） | 类别识别 / 状态识别 / AI 与品牌强调 | 卡片要表达类别区分（数据洞察 vs 风控 vs 客服 vs 知识库），让色系帮助快速识别；同区块出现 ≥ 4 张同类型卡且需要色系矩阵作为信息节奏 |

> **不确定时默认 `inverse`（黑底白标），它是 Card 体系的"安全色"，永远不会出错。**

#### 4.5.2 图标色系选择 — 按业务语义分配色 token

不要为了"好看"而堆色，色系是分类信号。语义→色系映射如下，AI 必须遵守，禁止反向（例如把"风控告警"涂成 pink）：

| 业务语义 | 色 token |
|---|---|
| AI / 智能能力 / 创作助手 / 内容生成 | `pink` 或 `brand` |
| 数据洞察 / 趋势分析 / 报表 / 看板 | `blue` |
| 任务自动化 / 工作流 / 配置 / 调度 | `orange` |
| 安全 / 审核 / 风控 / 异常告警 | `orange`（中度）或 `red`（强警示，慎用） |
| 知识库 / 文档 / 帮助 / FAQ | `green` 或 `blue` |
| 客服 / 会话 / 沟通 | `green` 或 `blue` |
| 用户 / 团队 / 成员 / 协作 | `purple` |
| 通用工具 / 中性入口 / 不归类的"其它" | `grey` |

#### 4.5.3 图标色系冲突仲裁

若一段内容同时命中多个色系，按"**业务核心动作**"优先：
- "AI 风控巡检" = AI 能力 + 风控 → 主语义是"风控" → 用 `orange`
- "AI 客服助手" = AI 能力 + 客服 → 主语义是"客服" → 用 `green`（强调 AI 能力时也可 `brand`）

同一页面多张 `info` 卡时，色系应形成"**分类矩阵**"而非"彩虹大杂烩"——一个页面建议用色 ≤ 4 个色系，其余统一用 `grey` 收敛。

#### 4.5.4 图标 Hover 自动反色

`tone` 模式下卡片 hover 时图标容器**必须**自动切换为对应色系 500 token + 纯白 icon + 透明描边（pink→pink-500、brand→brand-500、blue→blue-500、purple→purple-500、green→green-500、orange→orange-500、grey→black）。`inverse` 模式下不参与 hover 变色，保持黑底白标的稳定感。

#### 4.5.5 图标尺寸与圆角统一

- 信息卡片1 / 信息卡片2 主图标容器：**48×48px、圆角 12px (`rounded-lg`)、内部 Icon 24px**
- 数据卡片右上可选图标容器：**48×48px、圆角 16px (`rounded-xl`)、内部 Icon 24px**
- 数据卡片底部指标 / 信息卡片1 底部 `infoStats` / 信息卡片3 `metaItems` 辅助 icon：**14px**

⛔ 禁止手写 `className` / `style` 覆盖图标容器尺寸或圆角；⛔ 禁止给 `info3` 加 48px 大图标容器（图标在元信息行用 14px Icon 即可）。

---

### 4.6 Agent Flow 双组件配套准则（强约束）

> **TL;DR（缺这条 = 错配）**：出现 `AgentNodeCard` 必有 `AgentStatusBar` 吸底，反之亦然；节点顶部留白 24px、节点之间 24px、最后一节点到状态栏 16px——三个值都是像素级契约，由父容器 `gap-6` / `pt-6` / 状态栏外层 `pt-4` 承担，**不要写到节点卡的 `mt-*/mb-*` 上**。
>
> **本节为组件契约的镜像**：所有 props、间距 px 值、状态图标颜色等执行细节，最终以 `components.index.json` 中 `AgentNodeCard` / `AgentStatusBar` 的 rules 与 `src/data/systems/b-end/page-patterns/TicketAgentWorkspaceFramePattern.jsx` 模板源码为准。本文档与源码不一致时**以源码为准**。

**核心原则**：`AgentNodeCard`（节点流单元）与 `AgentStatusBar`（吸底状态栏）是双向强配套，两者构成 **Agent Flow** 这一最小业务单元，不可拆开使用。

**双向强约束**

| 触发条件 | 必须配套 |
|---|---|
| 业务页面出现 `AgentNodeCard`（任意数量） | 底部必须默认显示 `AgentStatusBar` 作为常驻吸底状态栏 |
| 业务页面出现 `AgentStatusBar` | 上方默认一定有 `AgentNodeCard` 节点流（动态 N 张） |

**典型 Agent Flow 结构**：
- 上方：`AgentNodeCard × N`（垂直可滚动，旧→新正序，最新节点贴底）
- 下方：`AgentStatusBar × 1`（吸底常驻、默认收起态、向上展开更多内容）
- 两者共用同一个 `flex flex-col + overflow-hidden` 父容器；节点流区域 `flex-1 + overflow-y-auto`、状态栏区域 `shrink-0`

**Agent 节点上下间距规范（强约束 / 像素级契约）**

客服工单Agent工作台（曾用名：工单 Agent 工作台框架，`TicketAgentWorkspaceFramePattern`）中，主白卡内 Agent 节点流必须严格遵守以下间距规则；任何复刻或迁移到其它 Agent 工作台模板都必须 1:1 复用这套间距，不得自行调整：

| 位置 | 规范值 | 实现 | 用途 |
|---|---|---|---|
| 节点滚动区顶部留白（首个 `AgentNodeCard` 上方） | **24px** | 滚动容器 `pt-6` | 让首个节点与主白卡顶部脱开，避免节点头像与卡片顶部贴边 |
| `AgentNodeCard` 之间的纵向间距（节点-节点） | **24px** | 滚动容器 `gap-6` | 通过 `flex flex-col gap-6` 统一节点间距，禁止在节点卡内部叠加 `mt-*/mb-*` |
| 最后一个 `AgentNodeCard` 与底部 `AgentStatusBar` 的固定间距 | **16px** | `AgentStatusBar` 外层 sticky 容器 `pt-4` | 让 AgentStatusBar 整个板块（含上方阴影/彩光）顶部与最后一节点保持 16px 留白；禁止把这 16px 改放到节点流底部 `pb-*` |
| `AgentStatusBar` 板块下方留白 | **由组件自身 padding/彩光条提供** | 不在外层叠加 `pb-*` | 外层 STICKY 容器只负责 `pt-4`，下方一律由 AgentStatusBar ROOT 内蕴间距承担 |

**禁止项**：

- ❌ 禁止把节点间距改用 `space-y-*`、`mt-*` 或在 `AgentNodeCard` 上下加 `margin`，必须通过父级 `gap-6` 控制。
- ❌ 禁止把"节点流 ↔ AgentStatusBar"的 16px 间距挪到节点流底部（如 `pb-4`）；必须由 AgentStatusBar 外层 STICKY 容器 `pt-4` 提供，确保滚动条不会出现一段无内容的尾部空隙。
- ❌ 禁止改写顶部 `pt-6`（24px）为更小或更大的值；首节点与主白卡顶部留白固定 24px。
- ❌ 禁止在 AgentStatusBar 外层叠加 `pb-*`；下方留白由 AgentStatusBar 自身组件提供，重复叠加会让吸底栏与白卡底部出现多余灰条。

**节点之间允许的视觉分组**：节点之间默认只用 24px 纯空间分隔，不画分隔线、不加箭头、不加装饰条；不同 Agent 角色之间的差异由 `AgentFamilyAvatar` 头像 + `mentionLabel` 文案体现，不靠间距大小区分主次节点。

**配套例外**（仅以下三种情况可单独出现）：
1. 规范页单独预览 `AgentNodeCard` 自身结构 / 收起展开态 / `cardType` 切换
2. 静态文档示意单一节点卡的字段映射
3. 节点卡作为 `AgentStatusBar` 内嵌内容（如规划步骤摘要）的一部分被反向引用

**模板落地**：完整 Agent Flow 已沉淀在工单 Agent 工作台模板（`ticket-agent-workspace-frame`）中间主白卡内。AI 在生成"Agent 工作台 / 工单托管 / 客服辅助 / 流程编排"等场景时，必须按强配套关系自动补齐另一侧；不允许只渲染节点卡而无状态栏，或只渲染状态栏而无节点流。

**AgentStatusBar 文案同步**：

- 工单 Agent 工作台模板中，底部 `AgentStatusBar` 的所有文案必须和上方 5 个 `AgentNodeCard` 节点真实内容一一对应。
- 顶部头像必须取最新节点的 `agentFamilyAvatar`，顶部标题必须等于最新节点的 `summary`，不得保留 `已完成任务规划` 等组件默认文案。
- 展开区 `planSteps` 必须由每个节点的 `summary + mentionLabel + statusTone` 生成，顺序与节点流一致。
- 展开区 `summarySections` 必须覆盖每一个节点，由节点 `statusText/title` 和 `detailFields/textContent/customContent/form` 摘要生成；禁止漏掉任意节点。
- “Agent 节点总结”左侧黑色加粗标题必须统一为 4 个中文字符，并使用固定宽度列对齐展示，例如“进线归集 / 工单研判 / 商家核实 / 退款执行 / 风险确认”。
- 标题列必须黑色加粗、不换行、固定宽度（组件默认 `w-16`），保证右侧正文起始位置纵向对齐；禁止直接使用过长 `statusText` 作为左侧标题。
- 展开区 `summaryTags` 必须由节点数量、完成数、待确认数和最新节点状态生成，禁止使用静态样例标签。
- 输入框 placeholder 与主操作文案必须优先引用最新节点的 `title/primaryActionText/secondaryActionText`，使底部可执行动作与当前节点语义一致。
- 禁止在工单 Agent 框架里继续使用 `SAMPLE_PLAN_STEPS`、`SAMPLE_SUMMARY_SECTIONS`、`SAMPLE_SUMMARY_TAGS` 或其它与当前节点剧本无关的静态样例文案。

#### 4.6.0 页面模板保真契约（强约束）

- 页面模板不是普通组件拼图，而是“页面一级骨架 + 容器语义 + 布局层级 + 基础交互能力”的完整契约。
- AI 命中 `BasePageFramePattern`、`CustomerServiceWorkspaceFramePattern`、`TicketAgentWorkspaceFramePattern`、`ChatHomePagePattern`、`ChatConversationPattern`、`CopilotPagePattern`、`IMConversationPattern` 或列表示例模板时，必须优先直接 import 并渲染对应模板组件。
- 如果业务需要改造模板，只允许完整复制 `src/data/systems/b-end/page-patterns/<Template>.jsx` 或 npm 包 `_b_end_runtime/page-patterns/<Template>.jsx` 作为起点，再替换业务 props、数据数组、文案、tabs、表格列/行、列表项和插槽内容。
- 禁止只摘取模板局部 JSX、按截图重拼、用 `div + Card + Table` 手搓伪模板，或把页面模板拆成多个普通组件后自由重排。
- 模板根容器、`.tfds-page-*` 类名、页面灰底、主白卡层级、外层间距、圆角、`min-h-0/min-w-0/overflow-*` 滚动链路、拖拽/折叠/吸底/上下文同步等能力都属于模板契约，默认不可删减。
- 业务可替换内容，不可替换框架：Header / Workspace / 主内容区 / 右侧信息区 / 底部输入或状态栏 / 侧栏导航等结构顺序必须跟模板保持一致。
- 交付前必须反查命中的 `components.index.json` 条目和模板源码，确认根容器、布局层级、标准组件调用、滚动归属、交互状态与模板一致；任一不一致都视为未正确使用页面模板。

#### 4.6.1 AgentNodeCard 内嵌组件样式与文案（强约束）

> **TL;DR（缺这条 = 错配）**：节点内自定义槽位只允许 4 类布局（`product / info3 / mixed / comparison`）；分组标题只能用 `FormTitle variant="level-3"`；展开高度上限 500px，超过在卡内滚；所有 Card 默认 `color="grey"`；文案必须真实业务文案，禁占位。
>
> **本节为组件契约的镜像**：所有 px 值、color token、组件 props 最终以 `AgentNodeCard` 源码与 `components.index.json` 对应条目为准。

`AgentNodeCard` 的 `customContent` 与 `form` 区域只能承载标准 TFDS B 端组件样式，例如 `Table`、`Form`、`Card` 等；禁止在节点卡内部手搓原生 `table`、原生 `form`、临时 `button` 或散装 `div` 卡片来模拟业务组件。

**节点状态图标**

- `statusTone="success"` 表达“执行完成/已完成/已研判”，默认使用 Figma `Property 1=完成` 的 14px 绿色圆形勾图标，颜色固定 `#24CDA5`。
- `statusTone="warning"` 或 `statusTone="error"` 表达“执行异常/报错/明确风险”，默认使用 Figma `Property 1=报错` 的 14px 粉色圆形感叹号图标，颜色固定 `#F2496F`。
- `statusTone="pending"` 表达“执行中/待人工确认/待用户确认/节点加载中”，默认使用 `<IconLoading size="sm" />` 标准彩环，不能替换为 Figma 完成/报错图标。
- `statusIconName` 仅用于业务显式覆盖；没有特殊业务诉求时禁止用 `check-circle-stroked` / `alert-circle-stroked` 替代 AgentNodeCard 默认完成/异常状态图标。

**卡片型自定义内容颜色**

- 为提高信息密度和屏幕效率，`AgentNodeCard` 的自定义槽位仅适合使用 `Card type="product"`（商品/订单对象）与 `Card type="info3"`（规则/知识/SOP 列表条目）两类卡片。
- 禁止在 `AgentNodeCard customContent` 中使用 `Card type="data/info/info2"` 作为自定义槽位卡片类型；这些类型信息密度或视觉占位不适合 Agent 节点面板。
- 当 `cardType="custom"` 且 `customContent` 承载 `Card type="product/info3"` 时，默认必须传 `color="grey"`，让卡片在 AgentNodeCard 的白底详情容器内形成灰底层级。
- 只有当父容器明确不是白底，而是灰底、浅灰底或其他非纯白背景时，才允许按 Card 反衬规则切换为 `color="white"`。
- `Table`、`Form` 等非 Card 组件保持各自组件默认 token，不额外手写背景、描边、圆角或阴影。

**内容高度上限**

- 单个 `AgentNodeCard` 展开态内容承载区最大高度固定为 `500px`。
- 当 `detailFields`、`textContent`、`customContent`、`form` 等内容超过 `500px` 时，必须在节点卡片内部纵向滚动查看。
- 禁止让内容继续撑高整张 Agent 节点面板，导致预览页、工作台主面板或节点流容器被挤出可视区域。

**自定义内容四类型**

- `product / 商品卡片`：用于订单、商品、服务对象摘要。布局固定为 5 张 `Card type="product" color="grey"` 纵向列表，适合快速浏览多个业务对象。
- `info3 / 信息卡片3`：用于规则、知识、SOP、策略条目。布局固定为 5 张 `Card type="info3" color="grey"` 纵向列表，适合高信息密度知识命中结果。
- `mixed / 混排`：用于同一节点内同时需要结论、关键字段、命中知识和表格记录的复合研判。布局固定为 `FormTitle + 字段描述 + Card info3 + Table` 的纵向 section 框架。
- `comparison / 信息对照`：用于左右对照两组业务信息。布局固定为“对照结论 + 双栏镜像研判卡片”，适合客服举证、变更前后、用户诉求 vs 平台规则等横向对比场景。
- AI 生成真实页面时必须先按业务语义选择四类之一，再严格套用对应自定义内容样式布局框架；禁止自由拼装临时自定义内容、改变外层结构或混用不适合 Agent 节点面板的 Card 类型。
- 当 `cardType="custom"` 的节点默认收起，或规范页选择“仅收起”案例时，也必须预先绑定当前已选自定义内容类型对应的真实 `customContent`、summary 与 statusText。
- 用户点击收起态节点展开后，必须展示已选中的 `product / info3 / mixed / comparison` 样式组合；禁止展开后只出现空状态卡、空白面板或退回默认字段描述内容。

**卡片组预览**

- 当 `cardType="custom"` 且自定义内容选择 Card 类型组件时，规范预览仅提供 `product` 与 `info3` 两类，并必须模拟 5 张同类业务卡片在节点内部纵向排列的样式。
- 5 张卡片都必须使用真实页面业务文案，并默认使用 `color="grey"`。
- 该预览用于验证灰底 Card 列表、节点内部滚动和长内容承载，不允许只放 1 张卡片导致高度风险不可见。

**混排自定义槽位**

- `mixed / 混排` 用于同一节点内同时承载纯文本研判结论、字段描述、信息卡片3 与 Table。
- 混排中的信息卡片也必须使用 `Card type="info3" color="grey"`；表格必须使用标准 `Table`，且默认关闭独立搜索筛选与分页。
- 混排仍然遵守 `500px` 内容高度上限，超出内容在节点卡片内部滚动。
- 混排或其他自定义槽位里只要出现类似“研判结论”“关键字段”“命中知识”“相关售后记录”的分组标题、区块标题、表格标题或卡片列表标题，必须使用 B 端基础组件 `FormTitle`，禁止手写 `p/h2/h3/div` 模拟标题。
- AgentNodeCard 内部分组标题默认使用 `<FormTitle variant="level-3" title="..." />`，保留 FormTitle 的品牌色竖条与标准标题字重。
- 禁止在 AgentNodeCard 内部用 `FormTitle variant="card"` 承载“研判结论”“关键字段”“命中知识”“相关售后记录”等分组标题，避免视觉上退化成普通文本标题。
- 例外：信息对照中的左右举证栏或左右板块标题必须使用标准 `Icon + 文本` 标题行，而不是 `FormTitle` 的绿色竖条；不同主体应使用不同图标和类型色做明显区分。
- 每一组 `FormTitle + 对应内容` 视为一个 section；不同 section 之间的上下间距必须固定为 `16px`（Tailwind `gap-4` / spacing-4），确保混排内容分组清晰且不浪费节点面板高度。
- 组内 `FormTitle` 与正文、字段、Card 或 Table 的距离可保持紧凑的 `8px`（Tailwind `gap-2`），但组与组之间不得小于或大于 `16px`。
- 混排中的“关键字段”等描述字段必须与 `cardType="field-description"` 字段描述卡片保持一致：无底色、无额外圆角、无灰色包裹块，按左 key / 右 value 两列上下平铺展示。
- 字段描述列宽与换行规则保持一致：左侧标题列 `112px`、列间距 `12px`、行间距 `8px`；key 使用次级文字色，value 使用主文字色，长文案必须自动换行。

**信息对照自定义槽位**

- `comparison / 信息对照` 用于必须左右对照阅读两组信息的场景，既包括客服举证（商家举证 vs 消费者举证），也泛化适用于任意两个板块横向对比，例如变更前 vs 变更后、用户诉求 vs 平台规则、规则命中 vs 订单事实。
- 信息对照必须先展示一段简短“对照结论”，帮助用户先获得判断方向，再进入左右两栏查看差异证据。
- 左右两栏必须采用镜像结构：每栏使用标准 `Icon + 文本` 标题行作为栏标题，并包含字段描述、凭证/证据摘要和研判要点。
- 举证主体或对比板块图标应表达信息来源，例如商家/供给侧/平台侧使用 `building-05-stroked`，消费者/用户侧使用 `user-square-stroked`；禁止继续使用 `FormTitle` 绿色竖条作为左右对照栏标题。
- 左右卡片必须使用平台标准 token 编写内容样式：浅灰描边白底卡片，类名建议为 `rounded-lg border border-border-default bg-white`，不要使用深色描边、临时色值或额外阴影。
- 标题图标容器必须使用 `size-6 rounded-md`，其中 `rounded-md` 对应 8px 圆角 token；图标容器必须为纯色背景且无描边。
- 类型色默认规则：商家/供给侧/平台侧使用蓝色 token `bg-blue-500`，消费者/用户侧使用粉色 token `bg-pink-500`，无法归属的中性板块可使用 `bg-blueGrey-900`。
- Icon 组件默认使用 `size="sm"`，颜色必须继承外层 `text-white`，即白色 icon；禁止使用灰底图标、深色 icon、透明 icon 或非 token 色值。
- 每一个信息对照研判卡片右上角默认展示 2-3 个“研判相关信息”标签，例如风险等级、证据状态、处理动作、命中规则等。
- 研判标签必须使用标准 `Tag` 组件，固定使用 `size="m" radius="md" fontWeight="bold"`；禁止用手写 `span`、临时 chip 或纯文本模拟标签。
- 标题行布局必须保持左侧 `Icon + 文本`、右侧 `Tag` 组；右侧 Tag 组允许换行，但不得遮挡标题、覆盖证据内容或撑破卡片。
- 字段描述继续沿用无底色字段描述规则；凭证/证据摘要可以使用标准图片缩略图、文件摘要或业务证据文本，但必须使用真实业务文案，不允许出现占位内容。
- 双栏最小列宽建议 `240px`，空间不足时必须自动降级为单栏纵向堆叠；禁止固定双栏宽度导致 Agent 节点卡片横向溢出。
- 两栏之间的横向间距固定为 `16px`（Tailwind `gap-4` / spacing-4），对照结论与双栏区域之间也保持 `16px`。

**真实业务文案**

- 节点内嵌组件的标题、字段、标签、表格列、状态、指标和说明必须根据真实页面业务模拟生成。
- 电商客服售后场景应使用订单号、商品名、退款金额、售后类型、规则外退款、仅退款、退货退款、处理状态、命中率、风险预警、客服 SOP、订单详情、退款记录、用户画像等真实语义。
- 禁止保留组件库原生默认文案或无业务含义占位内容，例如"标题"、"标签"、"默认内容"、"这里输入的是关键词"、"数据 1"、"测试按钮"。

**错配自查清单**（按 5 类分组，按顺序自检；命中任一行视为错配，必须修）：

**A. 双组件配套（AgentNodeCard ↔ AgentStatusBar）**
1. 是否生成了 `AgentNodeCard` 但底部漏了 `AgentStatusBar`？→ 必须补
2. 是否生成了 `AgentStatusBar` 但上方没有节点流？→ 必须补 `AgentNodeCard × N`
3. 是否把 `AgentStatusBar` 放在节点流中间或顶部？→ 必须放底部并吸底
4. 是否漏了 `flex flex-col + overflow-hidden` 父容器导致状态栏不吸底、节点流不滚动？→ 按双容器规范修

**B. 自定义槽位类型与组件**
5. 是否已根据业务语义从 `product / info3 / mixed / comparison` **四种**自定义内容类型中选择**一种**，而不是自由拼装？
6. `customContent` 是否复用了标准 TFDS B 端组件，并用真实业务文案替换默认占位文案？
7. Card 类型自定义内容是否只使用 `product / info3`，且按 5 张同类业务卡片模拟？
8. 自定义槽位默认收起或“仅收起”时，点击展开后是否仍展示当前已选样式组合的真实内容？

**C. 颜色 / 高度 / 标题**
9. `customContent` 若承载 Card 类型组件，是否默认使用了 `color="grey"`？
10. 展开态内容是否被限制在 `500px` 内，并在节点内部滚动而不是撑高整张节点面板？
11. Agent 节点内的分组标题是否使用 `FormTitle variant="level-3"`，而不是手写标题标签或 `FormTitle variant="card"`？
12. 每组 `FormTitle + 对应内容` 之间是否保持 `16px`（`gap-4`）上下间距？

**D. 混排专项（cardType="mixed"）**
13. 混排内容是否同时包含纯文本、字段描述、信息卡片3 与 Table，并继续遵守标准组件与真实文案规则？
14. 混排关键字段是否无底色，并与字段描述卡片保持一致的左 key / 右 value 上下平铺样式？

**E. 信息对照专项（cardType="comparison"）**
15. 信息对照是否先给出对照结论，再用左右镜像栏展示两组信息？
16. 信息对照双栏是否支持小宽度自动降级为单栏（最小列宽建议 240px），避免横向溢出？
17. 信息对照左右栏标题是否使用 `Icon + 文本` 做主体区分，而不是继续使用 `FormTitle` 绿色竖条？
18. 信息对照卡片是否使用 `border-border-default bg-white` 浅灰描边白卡？
19. 信息对照图标容器是否 `size-6 rounded-md` + 蓝/粉/中性 token 纯色背景 + 白色 icon？
20. 每个信息对照研判卡片右上角是否使用标准 `Tag size="m" fontWeight="bold"` 展示 2–3 个研判相关信息？

### 4.7 工作台左列折叠协同（强约束）

> **TL;DR（缺这条 = 错配）**：左侧 `ConversationList` 折叠 / 切 variant 时，**外层左板块的整体宽度必须跟随同步缩放**——不能只组件缩、外层固定列宽不变。`ConversationList` 必传 `resizable={false} + onLayoutWidthRequest + onVariantChange`，框架必传 `sideWidth + onSideWidthChange + leftContentMinWidth`；写死 `w-[400px]` / `grid-cols-[400px_1fr]` 一律错。
>
> **本节为模板契约的镜像**：完整接入代码以 `TicketAgentWorkspaceFramePattern.jsx` / `CustomerServiceWorkspaceFramePattern.jsx` 为准。

**适用范围**：`ticket-agent-workspace-frame`（客服工单Agent工作台，曾用名：工单 Agent 工作台框架）/ `customer-service-workspace-frame`（客服融合工作台，曾用名：客服工作台框架）/ 任何嵌入了 `ConversationList` 的两栏 / 三栏工作台页面。

**核心原则**：左侧 `ConversationList` 在「常规列表 ↔ 纯头像列」之间切换时，**外层左板块的整体宽度必须跟随同步缩放**，而不是仅组件自身变窄、外层固定列宽不变（否则会导致主区域被挤出视口右侧、按钮/标题被裁断、出现横向滚动 —— 截图典型错位场景）。

**宽度派生公式**（单一事实源）

| 列表形态 | 内容宽 `inner` | 外层板块宽 `outer = inner + 32px 覆盖区` |
|---|---|---|
| 默认列表 · 纯头像态（折叠） | `88px` | `120px` |
| 默认列表 · 展开态 | `400px`（典型） | `432px`（典型） |
| 卡片列表 · 最小态 | `333px` | `365px` |

> ⚠️ 卡片列表场景外层最小宽度是 **365px**（不是 120px），切换 `variant` 时必须按公式重算，不能写死。

**强制接入规范**

```jsx
// ① 模板/页面级 state（也可抽 useConversationFrameCollab 自定义 hook）
const [sideWidth, setSideWidth] = useState(432);
const [leftContentMinWidth, setLeftContentMinWidth] = useState(88);

// ② ConversationList 必须 resizable={false}，把宽度大权让渡给框架
<ConversationList
  resizable={false}
  collapsible
  autoCollapseOnNarrow
  onLayoutWidthRequest={(width) => setSideWidth(width + 32)}
  onVariantChange={(variant) => {
    setLeftContentMinWidth(variant === 'card' ? 333 : 88);
  }}
  style={{ width: '100%', height: '100%' }}
/>

// ③ 框架接受 sideWidth / leftContentMinWidth 撑出占位列宽
<CustomerServiceWorkspaceFrame
  sideWidth={sideWidth}
  minSideWidth={120}
  leftContentMinWidth={leftContentMinWidth}
  mainMinWidth={720}
  onSideWidthChange={setSideWidth}
  leftPanel={...}
  mainPanel={...}
/>
```

**布局骨架（不嵌框架时的最小写法）**

- 外层用两栏 flex：左侧 `<div className="shrink-0 transition-[width] duration-200 ease-out" style={{ width: ${sideWidth}px }}>`，右侧容器必须 `flex-1 min-w-0`（白卡 / 主工作区在内部自滚动）。
- 若必须用 grid，左列必须是 `auto`：`grid-cols-[auto_1fr]`，**严禁写死像素列宽**。

**禁用清单（⛔ AI 复刻易错点）**

1. ⛔ 外层写死 `w-[400px]` / `w-[432px]` —— 折叠时仅组件缩到 88px，外层 400px 框依然占位 → 主区被挤
2. ⛔ `grid-cols-[400px_1fr]` —— 同上，固定列内"缩内容不缩列"
3. ⛔ 漏 `min-w-0` —— 主区域 `flex-1` 在内容溢出时无法收缩，导致左列被反向挤压
4. ⛔ 切换 `variant` 时不重算 `leftContentMinWidth` —— 卡片列表场景宽度算成 120px → 列表渲染破裂
5. ⛔ `<aside style={{ width: 400 }}>` 等宿主容器固定宽度 —— 与 `ConversationList` 自身折叠脱钩

**错配自查清单**

1. 折叠时整个左板块（含覆盖区）有没有从 432px → 120px 整体缩小？
2. 主区域容器有没有 `flex-1 min-w-0`？
3. 切换"默认 / 卡片列表"时 `leftContentMinWidth` 有没有按 `88 ↔ 333` 切换？
4. 是否给 `ConversationList` 显式传了 `resizable={false}`？
5. 折叠 / 展开切换有没有 `transition-[width] duration-200` 让宽度变化不"啪"地闪？

**模板落地**：完整链路已沉淀在 [`TicketAgentWorkspaceFramePattern.jsx`] 与 [`CustomerServiceWorkspaceFramePattern.jsx`]（`onLayoutWidthRequest → setSideWidth(+32)` + `onVariantChange → setLeftContentMinWidth`）。**任何对工作台壳的复刻都必须 1:1 复用此协同链路，不得自行简化为固定列宽。**

---

### 4.8 会话列表项标签层级（强约束）

> **TL;DR（缺这条 = 错配）**：`item.tags` 数组**最后一个**是主要状态彩色（red/orange/green/blue），其余前置元素全部 `grey`；单 tag 场景该唯一 tag 用彩色；列表渲染 + AgentStatusBar `metaTags` 都必须经过 `normalizeConversationItemTags` 归一化，**禁止硬编码 “已托管 / 催 4 / 重复进线” 等业务文案到模板里**。
>
> **本节为组件契约的镜像**：白名单 / 归一化函数以 `ConversationList.jsx` 源码为准；扩展彩色色板必须同步更新 `isPrimaryStatusTag`。

`ConversationList` 列表项右侧标签 `item.tags` 是一组承载"主要状态 + 辅助上下文"的复合信息。它的颜色、顺序、文案三件事必须严格遵循**层级规则**，否则会让用户误判会话状态、状态色失去语义价值。本规则同时适用于 [`conversation-list`](file:///Users/bytedance/Documents/TFDS%20Design%20Skill/src/data/systems/b-end/components.js) 组件本体、[`ticket-agent-workspace-frame`](file:///Users/bytedance/Documents/TFDS%20Design%20Skill/src/data/systems/b-end/patterns.js) 与 [`customer-service-workspace-frame`](file:///Users/bytedance/Documents/TFDS%20Design%20Skill/src/data/systems/b-end/patterns.js) 模板。

**层级表（强约束）**：

| 位置 | 角色 | variant | 用途 | 数量 |
|---|---|---|---|---|
| **数组最后一个元素** | 主要状态标签 | `red`/`orange`/`green`/`blue` 等彩色（语义色） | 表达当前会话/工单的主导状态：异常/挂起/托管中/已处理 | 必须 1 个 |
| **其余前置元素** | 辅助补充标签 | **必须 `grey`** | 催办次数 / 倒计时 / 异常原因 / 规则命中 / 重复进线计数 | 0–N 个（推荐 ≤ 2） |
| **单标签场景** | 即主要状态 | 彩色（语义色） | 该唯一 tag 直接用语义彩色 variant，不用 grey | 1 个 |

**主要状态色板（与 `isPrimaryStatusTag` 白名单严格对齐）**：

| variant | 语义 | 典型 label |
|---|---|---|
| `red` | 异常/告警/待人工干预 | 待干预、异常 |
| `orange` | 挂起/等待中/待补充 | 已挂起、待回复 |
| `green` | 托管中/进行中/正常 | 托管中、处理中 |
| `blue` | 已处理/已完成 | 已处理、已完结 |

如需扩展彩色色板（如 `purple`/`teal`/`cyan`），必须**同时**更新 [`ConversationList.jsx`](file:///Users/bytedance/Documents/TFDS%20Design%20Skill/src/data/systems/b-end/components/ConversationList.jsx) 内 `isPrimaryStatusTag` 白名单与本表，禁止只在数据里用而不更新白名单。

**视觉规范**：

- 列表项 Tag 内部统一包装层固定 `size="m"` / `radius="md"` / `fontWeight="regular"`，禁止在外层覆盖。
- 辅助 grey 标签可带 `iconName`（如倒计时表盘 / 警告三角），主要状态标签默认**不带** icon（彩色已足够吸睛）。
- grey 辅助标签 mock 文案 ≤ 6 个字；同 section 同 tab 下，所有 item 的最右 tag variant 必须保持一致。

**动态业务态支持**：

- 标签内容 100% 支持业务态动态：所有 `label`/`variant`/`iconName` 必须来自当前业务数据或 `STATUS_TAG_BY_TAB`（仅在切换 tab 时改写最右 tag），**禁止把"催 4"/"已托管"等具体文案硬编码到模板**。
- `normalizeItemTags(tags, statusTagForSection)` 是渲染前的归一化入口：它会确保最后一个 tag 与当前 tab/section 的状态色一致；卡片列表通过 `sortCardTags` 把主状态排到最前用于卡片头部展示。
- 工作台框架（客服 / 工单 Agent）在把 `metaTags` 传给 `AgentStatusBar` 时**必须**经过同一份归一化函数，确保左侧最右彩色 tag 与底部 AgentStatusBar 状态色完全一致；禁止直接传 `item.tags` 原始数据。

**错配自查清单**：

1. 数组最后一个元素的 variant 是不是 `red`/`orange`/`green`/`blue`？❌ grey 即违规。
2. 数组中间是否出现彩色 variant？❌ 中间必须全 grey。
3. 单 tag 场景该唯一 tag 是否用了 grey？❌ 单 tag 必须彩色（即主要状态）。
4. 是否在模板里硬编码了"已托管 / 催 4 / 重复进线"等具体文案？❌ 必须来自业务数据。
5. 工作台 AgentStatusBar `metaTags` 是否使用了原始 `item.tags`（未归一化）？❌ 必须经过 `normalizeConversationItemTags`。
6. 辅助 grey 标签是否超过 6 个字？❌ 超过则截断或进 `+N` 折叠。

**渲染前兜底**：[`ConversationList.jsx`](file:///Users/bytedance/Documents/TFDS%20Design%20Skill/src/data/systems/b-end/components/ConversationList.jsx) 会在渲染前对每个 `item.tags` 做一道 `validateTagHierarchy` 静默校验，命中错配规则时在 dev 环境 `console.warn` 输出"列表项 X 的 tags 违反层级规则"提示，运行时不 crash 不弹错。**校验只是兜底，正确做法是从数据源就遵循层级规则**。

---

### 4.9 工作台框架拖拽能力完整性（强约束）

> **TL;DR（缺这条 = 错配）**：工作台共有 **3 条独立拖拽链路**——①框架左↔右覆盖式拖拽、②`ConversationList` 自身宽度（由外层代管）、③`InfoDisplayPanel` 整体宽度 + 内部栏间拖拽。**任何一条都不能因为只画了截图就静默删除**；以下任一情况都视为错配：`resizable={false}` 传给框架 / `sideWidth` 写死 / 漏 `onLayoutWidthRequest` / `mainMinWidth` 写死 720 / `InfoDisplayPanel resizable={false}` / Agent Flow 外层写 `maxWidth`。
>
> **本节为模板契约的镜像**：完整链路落地以 `TicketAgentWorkspaceFramePattern.jsx` / `CustomerServiceWorkspaceFramePattern.jsx` 为准，必须 1:1 复用其 props 拼装代码。

AI 生成"客服融合工作台"或"客服工单Agent工作台"页面时，**最高频的实现失误**就是只复刻了静态外观，把框架内置的拖拽能力静默删除了：要么传了 `resizable={false}`、要么把 `sideWidth` 写成静态值不接 `onSideWidthChange`、要么省略 `onLayoutWidthRequest`/`onVariantChange` 回调、要么 `mainMinWidth` 写死 720，最终用户拿到的是"拖不动的伪工作台"。本节是该问题的**强约束清单**，AI 在生成前必须逐项校验。

#### 三条独立拖拽链路（缺一不可）

工作台框架共有 **3 条独立拖拽链路**，分别由 3 个组件内置，AI 不能因为"只画了截图"就把任何一条删掉：

| 链路 | 拖拽内容 | 内置组件 | 触发热区 |
|---|---|---|---|
| **链路 1** | 左侧板块 ↔ 右侧主白卡（覆盖式拖拽） | `CustomerServiceWorkspaceFrame` | 主白卡左边缘的 8px 透明热区 |
| **链路 2** | ConversationList 自身宽度（外层框架代管） | `ConversationList` | 列表组件右边缘 |
| **链路 3** | InfoDisplayPanel 整体宽度 + 内部栏间拖拽 | `InfoDisplayPanel` | 信息栏左边缘 + 多 tab 内栏分隔线 |

#### 必传 props 清单

**`<CustomerServiceWorkspaceFrame>`（链路 1）**：

| props | 取值 | 失误后果 |
|---|---|---|
| `sideWidth` + `onSideWidthChange` | 受控成对出现 | 单传 sideWidth → 拖拽失效（静态宽度）；单传 onSideWidthChange → 拖拽不能持久 |
| `minSideWidth` | `100`（兜底） | 缺失 → 拖窄时无下限保护，左侧可能被拖到 0 |
| `leftContentMinWidth` | 默认列表 `88` / 卡片列表 `333` | 缺失 → 收起态/卡片态最小宽度失配，列表内容溢出 |
| `mainMinWidth` | **动态值**（按 §4.8/【mainMinWidth 动态计算】） | 写死 720 → 收起信息栏后右侧无法再拖窄 |
| `resizable` | **不传 / 不显式传 false** | 传 `false` → 整条链路 1 拖拽热区消失 |

**`<ConversationList>`（链路 2，嵌入工作台时）**：

```jsx
<ConversationList
  resizable={false}                  // 必须 false，让外层框架统一管拖拽
  collapsible                         // 必须保留
  autoCollapseOnNarrow                // 必须保留
  onLayoutWidthRequest={(width) => setSideWidth(width + 32)}
  onVariantChange={(variant) =>
    setLeftContentMinWidth(variant === 'card' ? 333 : 88)
  }
  style={{ width: '100%', height: '100%' }}
/>
```

⛔ **省略 `onLayoutWidthRequest` 是最常见错误**：会导致用户切换"卡片列表"或点击"收起列表"时，外层左侧板块容器**不跟随吸附**——即列表已经缩成头像列、但外层灰板还保留大片空白。
⛔ **省略 `onVariantChange`**：切到卡片列表时 `leftContentMinWidth` 不更新，外层框架仍按 88 算最小宽度，卡片在 88px 容器里渲染会溢出。

**`<InfoDisplayPanel>`（链路 3）**：

```jsx
<InfoDisplayPanel
  defaultWidth={380}
  minWidth={320}
  // 不传 resizable={false}
  // 工单 Agent 模板额外要求：
  onClose={onToggleInfoPanel}
  closeActionLabel="关闭信息栏"
/>
```

⛔ 传 `resizable={false}` → 链路 3 整体拖拽 + 内部栏间拖拽全部失效。
⛔ 多 tab 拆分后栏间分隔线必须保留拖拽能力，每栏 ≥ 200px。

#### 渲染前自检清单（AI 生成代码前必须逐项确认）

**客服融合工作台 / 客服工单Agent工作台共有**：

- [ ] **a)** 顶层 state 是否同时存在 `sideWidth` / `leftContentMinWidth` / `infoPanelVisible`（工单 Agent 变体）三个？
- [ ] **b)** `<CustomerServiceWorkspaceFrame>` 是否同时传了 `sideWidth + onSideWidthChange + minSideWidth + leftContentMinWidth + mainMinWidth` 五个 props？
- [ ] **c)** `<ConversationList>` 是否同时传了 `resizable={false} + onLayoutWidthRequest + onVariantChange + collapsible + autoCollapseOnNarrow` 五个 props？
- [ ] **d)** `<InfoDisplayPanel>` 是否**未传**`resizable={false}`？

**客服工单Agent工作台额外**：

- [ ] **e)** `dynamicMainMinWidth` 是否随 `infoPanelVisible` 在 `360 / 720` 间切换？（不能写死 720）
- [ ] **f)** `<InfoDisplayPanel>` 是否传了 `onClose + closeActionLabel`？（保证收起后能再次关闭）
- [ ] **g)** Agent Flow 外层白色容器是否**未写** `maxWidth`？（保证可拖宽度）
- [ ] **h)** Agent Flow 内层组件区是否包了 `style={{ maxWidth: 900 }}` + `mx-auto`？

#### 错误模式黑名单

```jsx
// ❌ 错误 1：sideWidth 写死、不接 onSideWidthChange（链路 1 失效）
<CustomerServiceWorkspaceFrame sideWidth={432} ... />

// ❌ 错误 2：传 resizable={false} 给框架（链路 1 失效）
<CustomerServiceWorkspaceFrame resizable={false} ... />

// ❌ 错误 3：ConversationList 没传 onLayoutWidthRequest（外层不吸附）
<ConversationList collapsible ... />  // 缺 onLayoutWidthRequest

// ❌ 错误 4：mainMinWidth 写死 720（收起信息栏后红框卡死）
<CustomerServiceWorkspaceFrame mainMinWidth={720} ... />

// ❌ 错误 5：InfoDisplayPanel 关闭拖拽（链路 3 失效）
<InfoDisplayPanel resizable={false} ... />

// ❌ 错误 6：Agent Flow 外层写 maxWidth（白卡被锁死无法跟随主白卡变宽）
<div style={{ maxWidth: 900 }} className="flex-1 min-w-0">
  {agentNodes}
  <AgentStatusBar />
</div>
```

#### 正确模式参考

完整的 3 条链路落地参考：[`TicketAgentWorkspaceFramePattern.jsx`](file:///Users/bytedance/Documents/TFDS%20Design%20Skill/src/data/systems/b-end/page-patterns/TicketAgentWorkspaceFramePattern.jsx) 与 [`CustomerServiceWorkspaceFramePattern.jsx`](file:///Users/bytedance/Documents/TFDS%20Design%20Skill/src/data/systems/b-end/page-patterns/CustomerServiceWorkspaceFramePattern.jsx)。**AI 生成时必须 1:1 复用这两个模板的 props 拼装代码，不允许自行简化为静态宽度。**

---

## 5. 页面类型设计判断

> **本节与 `PAGE_ARCHETYPES.md` 的分工**（重要 · 避免重复消化）：
>
> 1. **先去 `PAGE_ARCHETYPES.md`** 按触发关键词 + 决策树**选模板**（决定该用哪个 `*Pattern`、对应哪个 recipe）。
> 2. **再回到本节**读取该类页面的**设计判断要点**（信息优先级、视觉密度、主从关系、AI 取舍）。
> 3. **最后去 `LAYOUT_RECIPES.md` / `LAYOUT_RULES.md`** 写具体 JSX 骨架。
>
> ⛔ **不要把本节当模板目录使用**。本节描述的是“这类页面的设计气质和取舍”，模板真名、触发关键词、组件 import 顺序请用 `PAGE_ARCHETYPES.md`。
>
> **§5.x ↔ `PAGE_ARCHETYPES.md` 章节对应**（生成前用这张表对齐两份文档）：
>
> | 本节 | `PAGE_ARCHETYPES.md` 对应章节 / 模板 |
> | --- | --- |
> | §5.1 平台壳 / 模块工作区 | §1 平台壳 / 模块工作区 |
> | §5.2 列表 / 管理页 | §2 列表管理页 → `BasePageFramePattern` |
> | §5.3 分类 + 列表页 / 知识库页 | §3 分类列表 / 知识库详情页 |
> | §5.4 Tab 顶栏 / 策略详情 / 编辑详情页 | §4 策略 / 编辑详情页 |
> | §5.5 托管 / 客服 / 会话工作台 | §5 会话工作台 / 托管页 → `CustomerServiceWorkspaceFramePattern` / `TicketAgentWorkspaceFramePattern` |
> | §5.6 Playground / 调试台 / Prompt Editor | §4 策略 / 编辑详情页（Playground 变体） |
> | §5.7 入口页 / 首页 / AI 入口页 | §6 入口页 / AI 入口页 → `ChatHomePagePattern` |
> | §5.8 Copilot / 产物预览页 | §7 产物预览 / 任务协同页 → `CopilotPagePattern` |
> | §5.9 三步配置 / 批测 / 评估流 | §8 多步骤配置 / 批测评估页 |
> | §5.10 会话 / 客服 / IM 页 | §5 会话工作台 + `IMConversationPattern` / `ChatConversationPattern` |
> | §5.11 空状态 / 无权限 / 建设中 | §9 选型后必须做（空状态分支） |

### 5.1 平台壳 / 模块工作区

目标是让用户明确当前产品域、当前模块和页面主操作。

- 左侧 NavBar 保持稳定，不随内容滚动
- 顶部模块切换、版本切换、发布/保存/创建等动作直接坐灰底
- 当前模块用黑色胶囊或轻量激活态表达，不用大面积品牌色
- 右上角主操作保持固定位置，不能藏在白卡内部

### 5.2 列表 / 管理页

目标是快速筛选、对比、批量处理。第一优先级是表格或列表的可扫描性。

- 先选列表/管理类 page-template
- 页面级主操作只保留一个，例如“新建”
- 筛选栏控件固定宽，不要全部满宽
- 标题、业务范围 Tag、筛选区、表格之间要形成一条自然的纵向扫描线
- 表格容器撑满剩余高度，避免页面滚动和表格内部滚动同时混乱
- 表格行分隔线轻，行内容靠列对齐和弱文字建立密度
- 状态、风险、类型必须用 Tag，不手写彩色徽标

### 5.3 分类 + 列表页 / 知识库页

目标是让用户先定位分类，再处理右侧对象。

- 左侧用 TagBar / 分类列表表达结构
- 右侧用 Table / 列表表达工作对象
- 需要查看全文、说明、案例详情时，右侧增加详情面板，而不是弹窗打断
- 左侧宽度固定，右侧 `flex-1 min-w-0`
- 分类数量不要做成一排 Button
- 当前分类、数量、筛选条件要贴近列表标题
- 列表项选中态优先用品牌描边或轻底色，详情面板用白色内容容器承载富文本

### 5.4 Tab 顶栏 / 策略详情 / 编辑详情页

目标是让用户在同一对象下切换视图。

- 同一容器内的互斥视图必须用 Tabs
- 内容区 Tabs 默认 sm
- 顶部上下文信息应轻量，不喧宾夺主
- 详情区和列表区要有明确主从，不要双区域都做成强标题
- 编辑详情页常见三分区：左侧上下文/进程，中间编辑器或画布，右侧配置/说明/单测
- 中间编辑器应占最大视觉面积，右侧配置区窄而稳定

### 5.5 托管 / 客服 / 会话工作台

目标是高效处理队列、会话上下文和下一步动作。

- 左侧队列按状态分组，当前项用品牌左边条或轻底色突出
- 中间会话/处理流保持纵向时间线，重要任务卡使用轻灰容器承载
- 待确认、托管中、已挂起、异常等状态必须用 Tag 或固定状态区表达
- 底部输入或确认动作固定，不随会话流滚走
- 右侧详情、用户画像或工单信息只作为辅助，不抢会话主线

### 5.6 Playground / 调试台 / Prompt Editor

目标是输入、参数、运行、结果在同一屏完成对照。

- 整页不滚，面板内部滚
- 多面板同高，标题固定，正文滚动
- Prompt、JSON、代码、日志优先用 TextArea `variant="code"` 或规范代码容器
- 运行按钮、模型参数、结果状态要靠近工作流，不要散在页面角落
- 输入区和输出区不要被大留白隔开

### 5.7 入口页 / 首页 / AI 入口页

目标是降低开始成本，不是做营销落地页。普通企业平台首页应突出业务入口、待办、数据概览和最近访问；AI 入口页才突出 ChatInput 和智能推荐。

- 普通首页的核心入口、待办和关键数据必须是视觉中心
- AI 入口页的 ChatInput、推荐问题、快捷动作、历史入口要围绕输入组织
- AI 渐变只在 AI 入口或智能模块中出现，用于身份信号
- 模板/案例卡片放在入口下方，作为“下一步可选路径”，不要抢输入主行动
- 不要做大面积品牌背景、漂浮装饰、无功能的 slogan 区

### 5.8 Copilot / 产物预览页

目标是主工作区和 AI 辅助区并行，最终产物清晰可读。

- 主内容占主导，AI 侧栏辅助决策
- AI 建议必须可执行、可采纳、可忽略
- 侧栏宽度固定或有合理上下限，主区 `min-w-0`
- 不能让 AI 面板挤压表单标题或正文导致一字一行
- 产物预览区占最大面积，工具栏轻量贴顶，文档正文不被过度卡片化

### 5.9 三步配置 / 批测 / 评估流

目标是让用户按步骤完成配置，同时保留跨步骤对照。

- 多步骤配置优先横向三栏或分区并列，而不是纵向长表单
- 步骤编号用小黑底数字或明确序号，标题简短
- 每栏白卡内部再使用轻描边子区块承载选项、预览和参数
- 中间预览/评估对象要保持可见，右侧配置不要挤压它
- 发起评估、发布、保存等主操作固定在顶部右侧

### 5.10 会话 / 客服 / IM 页

目标是清楚处理“谁在说、说了什么、当前状态、下一步动作”。

- 消息必须使用 ChatMessage / ChatBubble / IMConversationPattern
- 输入区固定底部，消息流内部滚动
- 人工、AI、用户、系统状态必须视觉区分
- 工单、订单、用户画像等辅助信息放侧栏，不要挤进聊天流
- 高风险、待跟进、已解决等状态用 Tag 和固定位置表达

### 5.11 空状态 / 无权限 / 建设中

目标是解释原因并给出下一步。

- 优先使用 Empty 或对应 page-template
- 文案短，说明原因 + 一个主行动
- 不要堆多个按钮
- 不要用大面积插画替代明确操作

---

## 6. 组件设计角色

### 6.1 NavBar / Top Tabs / TagBar

导航组件表达“我在哪里”和“我正在处理哪一类对象”。

- NavBar 负责产品域和一级业务，不承载页面筛选条件
- 顶部 Tabs / segment 负责当前模块、模式、版本或工作台切换
- TagBar / 分类树负责对象过滤和知识分类，不要用按钮组冒充
- 当前态必须稳定可见；未选中态保持轻，不要每个项都加高饱和颜色

### 6.2 FormTitle

FormTitle 是页面语义锚点，不是装饰竖条。

- 页面总标题、白卡标题、面板标题、section 标题都先用 FormTitle
- 标题字重必须由组件内部保持 600，不外部覆写
- 状态和数量贴主标题右侧，用 `titleSuffix`
- 普通标题默认不展示 description
- 只有确实需要解释业务规则、风险、空状态原因时才开启 description

### 6.3 Button

Button 表达操作优先级。

- 每个区域最多一个 primary
- 普通操作用 outline / ghost / text，而不是继续增加 primary
- 危险操作必须有语义区分，不能伪装成普通按钮
- 低频操作收进更多菜单或 icon button，避免工具栏变成按钮墙

### 6.4 Tabs

Tabs 表达同一区域内的视图切换，不表达状态标签。

- 分段切换用 `variant="segment"`
- 内容区默认 sm
- 页面级或产品级导航才考虑 md / lg
- 不要用一排 Button 或 Tag 冒充 Tabs

### 6.5 Form 控件

表单控件承载输入任务，默认应稳定、清晰、可预测。

- 主区、筛选栏、弹窗、抽屉中的 Input / Select / Button 默认 md
- 表格行内或极窄工具条才用 sm
- 筛选栏：多个字段并排，固定宽
- 白卡正文单列字段：默认满宽
- 必填、错误、禁用、帮助说明使用组件内能力，不手写状态样式

### 6.6 TextArea / 代码输入

TextArea 是长内容编辑器，不是普通多行 div。

- 普通描述、备注、工单详情用默认 TextArea
- Prompt、JSON、SQL、日志、代码参数用 `variant="code"`
- 代码类文字必须保持 14px / 20px 节奏
- 主编辑区使用 `fillHeight`，让控件内部滚动
- 不手写原生 textarea + 行号列

### 6.7 Table / 列表

Table 承担 B 端最重要的数据对比。

- 表格优先保持稳定行高和列对齐
- 状态列用 Tag
- 操作列收敛，低频操作用更多菜单
- 长文本可省略，但必须有 Tooltip 或详情入口
- 表格不要被包进多层窄容器导致横向拥挤

### 6.8 Card

Card 用于业务摘要、入口、对象概览，不是通用白卡容器。

- 父级灰底时可用 `color="white"`
- 父级白底时用 `color="grey"` 做次级容器
- 摘要卡内部要有明确标题、状态、主指标或下一步入口
- 不要用 Card 承载大篇幅表单、表格、对话流

### 6.9 Chat 组件

Chat 组件表达消息和 AI 工作流。

- 所有消息用 ChatMessage / ChatBubble
- 用户、AI、系统、客服角色必须清楚
- 先判断会话背景，再选气泡色：AI 问答、任务执行、Copilot、流程跟进等执行类对话优先浅灰背景 `var(--color-blueGrey-200)`；常规 IM、客服进线、人工接待、站内信回复优先白色背景 `var(--color-surface)`
- 浅灰背景：左侧用户气泡用 `incomingTone="grey"`，右侧普通回复用 `outgoingTone="white"`；只有明确 AI / 机器人执行回复时才用 `outgoingTone="ai"`
- 白色背景：左侧用户气泡用 `incomingTone="grey"`，右侧人工/客服回复用 `outgoingTone="default"`，右侧 AI/机器人回复用 `outgoingTone="ai"`；禁止白底上再叠无描边白气泡
- ChatMessage 的 `role="user"` 用户气泡默认使用 `userBubbleTone="auto"` 自动适配：白色大背景 / 白色工作卡内自动变为 `fill-default` 灰气泡；浅灰、蓝灰、AI 会话灰底等非白背景自动保持 `surface` 白气泡。生成页面默认不要手动传 `userBubbleTone`；只有复杂背景无法识别时才显式传 `surface` / `fill`
- AI 建议、执行过程、追问按钮使用组件能力
- 输入区用 ChatInput，不手写渐变输入框

### 6.10 Modal / Sheet / FullScreenPage

浮层表达打断强度。

- 轻量确认用 Modal
- 侧向配置或详情查看用 Sheet
- 复杂编辑、长流程、沉浸任务用 FullScreenPage
- 浮层里同样遵守一主操作原则

---

## 7. 生成前决策流程（两段式：先排除 → 再确认）

每次生成页面前，按以下两段顺序作答；**任何一个排除问题答“否” / 不确定就回去查规范，不要开始写代码**。

### 7.1 第一段 · 4 个排除问题（任一答“否”都不能动手）

1. **页面类型是否已通过 `PAGE_ARCHETYPES.md` 决策树命中**一个 `*Pattern`（含明确触发关键词）？→ 否：去 `PAGE_ARCHETYPES.md` 重选模板。
2. **每个非自定义 UI 元素是否都能在 `components.index.json` 找到对应组件**（不靠手搓 `div + Tailwind` 模拟 `Tag` / `Button` / `FormTitle` / `Tabs` / `Card`）？→ 否：先找组件再开工。
3. **如确有自定义区块，是否完全用 `GLOBAL_DESIGN_RULES.md` 的 Token**（颜色 / 字号 / 字重 / 间距 / 圆角 / 阴影 / 动效）？→ 否：把硬编码值换成 `var(--token-*)`。
4. **页面 / 工作台 / 节点流的滚动模型是否已选定**（整页滚、白卡内滚、表格内滚、消息流滚、面板内滚）？→ 否：去 `LAYOUT_RULES.md §0.5` 滚动模型决策树。

### 7.2 第二段 · 1 个确认问题（用于锁定信息优先级）

5. **用户第一眼必须看到什么**？请一句话指明：状态 / 数据 / 输入框 / 对话 / 风险 / 主操作中的**一个**；其他元素全部按这条主线降级（位置、字号、色权重）。

> 如第 5 题答出两个以上视觉中心，意味着主从关系没建立；回 §1.1 任务先于装饰、§4.1 页面元信息直接坐灰底 重新做取舍。

---

## 8. 生成后设计自检

交付前必须检查：

- 页面是否像“企业级 B 端平台”，而不是营销页、普通 admin 模板或随机 shadcn 页面
- 是否符合“灰色应用壳 + 白色工作区 + 轻导航 + 黑色主操作”的平台气质
- 页面 header 是否直接坐灰底，白卡是否只承载工作内容
- 最外层白卡是否无 border、无 shadow、12px 圆角
- 复杂任务是否采用稳定分屏，而不是纵向堆叠成长页面
- 列表/表格是否撑满工作区，筛选、分页和详情是否位置稳定
- 入口页是否把主行动放在视觉中心，模板/案例卡片是否作为辅助路径
- 产物预览是否像可交付文档，而不是被压缩成普通信息卡
- 所有标题是否使用 FormTitle，且字重没有被外部覆写
- 所有已有组件是否整体 import 使用，没有手搓相似样式
- 品牌青绿是否只用于焦点、激活、链接、品牌状态和标题竖条
- AI 渐变是否只出现在 AI 语义面
- 字号、间距、圆角、阴影是否全部来自 token 或组件默认值
- 主操作是否收敛，每个区域是否最多一个 primary
- 长文本是否不会静默裁切，省略是否有 Tooltip 或详情入口
- Playground / 会话 / 多面板页面是否没有错误地整页滚动

---

## 9. 与其他规范的关系

当本文件与具体实现规则发生冲突时，按以下优先级执行：

1. `components.index.json` 的组件 rules / examples
2. `SKILL.md` 的硬规则和 Checklist
3. `LAYOUT_RULES.md` 的页面骨架、宽高、自适应、滚动规则
4. `GLOBAL_DESIGN_RULES.md` 的 token、白卡、字体、间距、文本规则
5. 本文件的设计原则和 UX 取舍

本文件不能用来绕开组件调用、token 约束或布局铁律。它只负责让 AI 在正确规则内做更专业的页面判断。
