# TFDS 页面范式选型（AI 先判页面，再选组件）

> **作用域**：生成整页前，用本文件判断页面属于哪种范式。选定范式后，再到 `components.summary.json` 选组件、到 `components.index.json` 读取命中组件详情。
>
> **原则**：页面范式由用户第一步动作决定，而不是由视觉喜好决定。

---

## 目录

- §0 选型决策树
- §1 平台壳 / 模块工作区
- §2 列表管理页
- §3 分类列表 / 知识库详情页
- §4 策略 / 编辑详情页
- §5 会话工作台 / 托管页
- §6 入口页 / AI 入口页
- §7 产物预览 / 任务协同页
- §8 多步骤配置 / 批测评估页
- §9 选型后必须做

---

## 0. 选型决策树

| 用户第一步动作 | 首选页面模板 | 布局 Recipe | 必须出现的主组件 | 典型触发关键词（5–10） | 不要误选 |
| --- | --- | --- | --- | --- | --- |
| 筛选、搜索、浏览一批结构化对象、批量操作、查看详情 | `BasePageFramePattern`，再从 `StrategyListPage` / `VariableManagementPage` / `McpManagementPage` / `TabTopBarListPage` 选子模板 | `base-management` | `NavBar`、`FormTitle`、`Input/Select/DatePicker/TagInput`、`Table`、`Tag`、`Button`，有分类维度时加 `TagBar` | 列表管理、筛选、搜索、批量操作、表格、对象管理、状态Tag、分页、创建/导入、详情查看 | 不要因为页面里有 AI 字样就选 `ChatHomePagePattern` 或 `ChatConversationPattern` |
| 用户尚未进入具体上下文，第一步是输入一句需求、搜索助手、从模板 / 案例开始 | `ChatHomePagePattern` | `chat-home` | `NavBar`、`ChatInput`、`Tabs`、`Card`、`Input`、`Icon`；右侧主区保持浅灰底，模板卡用白底 Card | 从0发起、输入需求、一句话描述、模板广场、助手推荐、搜索助手、开始对话、热门模板、示例卡片、入口页 | 不要做成“标题 + 筛选 + 表格”的白卡管理页；不要在右侧内容区外包一整张白色大卡 |
| 用户已在一个 AI 任务 / 会话里，第一步是继续追问、看执行进度、看 AI 消息流 | `ChatConversationPattern` | `chat-conversation` | `ChatMessage`、`ChatInput`、`Button`、`Icon` | 继续追问、消息流、执行进度、任务规划、流式输出、follow-up、产物卡片、对话记录、继续输入、会话 | 不要用 `ChatBubble` 手搓 AI 回复，也不要把消息流塞进表格 / 白卡列表 |
| 用户正在编辑 / 查看一个对象或产物，同时需要 AI 辅助分析、改写、解释、侧边追问 | `CopilotPagePattern` | `copilot-workbench` | `Button`、`Tabs`、`ChatInput`、`Switch`、`Icon`，编辑区按内容补 `FormTitle/TextArea/InputNumber/Select` | 编辑、预览、产物、报告、解释/改写、侧边助手、配置面板、对象详情、工作区、对照 | 不要选纯 `ChatConversationPattern`，因为主角不是消息流，而是右侧对象 / 产物 / 画布 |
| 用户在“工单 Agent 工作台”里推进一个工单/任务的处理流程：第一步是查看多个 Agent 节点卡、阅读总结、进行干预（底部状态栏输入/按钮）并驱动流程继续 | `TicketAgentWorkspaceFramePattern` | `customer-service-workspace`（工作台容器语义） | `AgentNodeCard`、`AgentStatusBar`、`Button`、`Input`；如包含会话/沟通区，再配套 `IMConversationPattern` / `ConversationList` | 工单Agent、Agent节点、节点卡、planSteps、节点总结、干预、底部状态栏、完结/转交、处理流程、执行链路 | 不要误选为 `CustomerServiceWorkspaceFramePattern`（客服三栏 IM 工作台）或 `CopilotPagePattern`（对象编辑页）；不要手搓节点卡与底部状态栏 |
| 用户正在客服工作台 / IM 工作台处理会话，页面是三栏结构：左侧会话/工单列表，中间沟通聊天区，右侧信息区或 N 个信息 Tabs（托管助手、历史工单、工单日志等） | `CustomerServiceWorkspaceFramePattern` | `customer-service-workspace` | `ConversationList`、`IMConversationPattern`、`InfoDisplayPanel`、`ChatBubble`、`ChatInput variant="im-basic"`；托管助手 tab 用 `ChatMessage` 执行流 | 客服工作台、三栏、会话列表、聊天区、右侧信息Tabs、工单信息、订单/用户信息、托管助手、接待/质检、联动 | 不要新造三栏框架；不要只用 `IMConversationPattern + ConversationList` 拼装；不要用 Card / div 手搓右侧信息 Tabs |
| 用户处理真实人际消息、客服接待、私信、站内信、履约沟通，第一步是查看历史消息并回复 | `IMConversationPattern`，多线程时外层组合 `ConversationList` | `im-thread` | `ChatBubble`、`ChatInput variant="im-basic"`，多线程加 `ConversationList` | 私信、站内信、客服接待、历史消息、回复输入、气泡、真人会话、单线程、消息记录、会话 | 不要用 `ChatMessage` 渲染普通 IM 气泡；不要把普通客服会话误判为 AI 对话页 |
| 无权限、建设中、无数据 | `BasePageFramePattern` 的 NoAccess / Construction 子示例或 `Empty` | 跟随承载页面，通常 `base-management` | `Empty`、`Button` | 无数据、无权限、建设中、暂未开通、空列表、引导创建、去配置、返回、刷新、联系管理员 | 不要新造插画、空状态卡片或手写状态徽标 |

### 0.0 页面模板保真契约

- 选中首选页面模板后，模板本身就是页面一级骨架，必须优先直接 import 对应 `*Pattern` / 列表示例组件。
- 需要业务改造时，完整复制模板源码作为起点，只替换业务数据、文案、tab 内容、表格列/行、列表项、卡片项和插槽内容。
- 禁止只按视觉截图重拼，禁止只摘取局部 JSX，禁止把模板外层容器、滚动层、拖拽/折叠/吸底/上下文同步能力删掉后再用普通组件拼页面。
- 验收时必须能在页面根节点或关键节点看到模板标识 `.tfds-page-*`，并能对照模板源码确认容器顺序、间距、滚动归属和交互能力未被破坏。

### 0.1 模板选择优先级

当用户描述同时命中多个模板时，按下面顺序裁决，裁决依据是“用户进入页面后的第一步动作”和“页面主角”，不是页面里出现了哪个组件名。

1. **客服 / IM 三栏工作台优先判 `CustomerServiceWorkspaceFramePattern`**：只要出现“客服工作台 / IM 工作台 / 三栏 IM / 左侧 IM 列表 / 会话列表 + 沟通聊天区 + 信息区 / 托管助手 / 历史工单 / 工单日志 / 右侧信息 Tabs”等结构信号，先判断客服工作台框架是否兼容。若页面主结构是左侧多会话队列、中间 IM 聊天、右侧信息区，就不要新造框架。
2. **工单 Agent 工作台优先判 `TicketAgentWorkspaceFramePattern`**：当描述出现“Agent 节点卡 / 节点总结 / planSteps / 干预 / 底部状态栏输入 / 完结 / 工单 Agent 工作台”等结构信号，且页面主角是“多个 Agent 节点 + 底部状态栏驱动流程”，优先直接命中工单 Agent 工作台模板，禁止手搓节点卡与底部状态栏。

> **客服三栏 vs 工单 Agent 工作台同时命中时的裁决依据**（高频误判点）：按“页面主角”一次性裁决，不要反复犹豫。
>
> - 主角是「左侧 IM 会话队列 + 中间聊天 + 右侧信息 Tabs」 → `CustomerServiceWorkspaceFramePattern`
> - 主角是「多个 Agent 节点卡 + 底部状态栏驱动流程（planSteps / 节点总结 / 干预 / 完结）」 → `TicketAgentWorkspaceFramePattern`
> - 如果两类内容并存（例如左侧带 IM 队列 + 中间是 Agent 节点流），优先 `TicketAgentWorkspaceFramePattern`，把 IM 区作为模板内辅助插槽而不是另起一个客服三栏。

3. **普通单线程 IM 优先判 `IMConversationPattern`**：只有当前页面主角是单个线程的历史消息与回复，且不需要左侧多会话队列和右侧信息区时，才用 IM。
4. **AI 消息流优先判 `ChatConversationPattern`**：如果主线是一条 AI 任务会话，用户要追问、确认任务规划、看流式执行、查看 AI 产物卡，就用 AI 对话页。
5. **对象编辑 + AI 侧助优先判 `CopilotPagePattern`**：如果右侧对象、文档、策略画布、报告预览是主工作区，AI 只是辅助解释 / 改写 / 追问，就用 Copilot。
6. **从 0 开始发起任务优先判 `ChatHomePagePattern`**：如果用户还没选对象、没进入会话，只是要搜索助手、输入需求、从模板开始，就用 AI 入口页。
7. **结构化对象管理默认判 `BasePageFramePattern`**：只要第一步是筛选、浏览、批量处理一批对象，就回到白卡管理页，不因为“AI 变量 / 智能策略 / 机器人列表”等名词改变模板。

### 0.2 模板到组件的生成矩阵

| 模板 | 组件调用铁律 | 常见错误 |
| --- | --- | --- |
| `BasePageFramePattern` | 页面壳先放 `NavBar`；白卡标题用 `FormTitle`；筛选用 `Input/Select/DatePicker/Checkbox/TagInput`；列表用 `Table`；分类维度用 `TagBar`；状态全部用 `Tag`；动作全部用 `Button` | 手写标题、手写状态徽标、用 `Button` 冒充 Tabs、表格外层没有独立滚动 |
| `ChatHomePagePattern` | 主入口必须是 `ChatInput`；模板 / 助手推荐用 `Card`；分类切换用 `Tabs`；搜索只用 `Input`；卡片网格用 `auto-fit/minmax` | 把入口页改成白卡筛选表格、用普通 `<textarea>` 当 AI 输入框、固定 3 列导致窄屏溢出 |
| `ChatConversationPattern` | 每条消息统一用 `ChatMessage`；用户消息走 `role="user"`；AI 消息走 `header` + `thinking/plan/taskGroups/resultArtifacts/followUps`；底部吸底 `ChatInput` | 用 `ChatBubble` 或裸 div 模拟 AI 消息、把执行流拆成多张随机卡片、输入框随消息滚走 |
| `CopilotPagePattern` | 页面级 header 直接坐灰底；主内容白卡是主角；AI 面板用 `ChatInput`；对象编辑区按字段语义使用 `TextArea/InputNumber/Select/Switch/Tabs`；长编辑器必须内部滚动 | 把 header 包白卡、让 AI 侧栏抢主内容宽度、把对象编辑页做成纯聊天页 |
| `TicketAgentWorkspaceFramePattern` | 节点区必须复用 `AgentNodeCard`，底部干预区必须复用 `AgentStatusBar`；离散动作全部用 `Button`，复合动作优先 `SplitButton`；输入区必须复用 `Input` 并支持真实录入/回车提交；数据与文案必须由节点真实内容派生，禁止使用静态 `SAMPLE_*` | 手搓节点卡/状态栏；用 `<p>` 模拟输入框；把“工单 Agent 工作台”错误做成客服三栏 IM 工作台；底部状态栏文案与上方节点不一致 |
| `CustomerServiceWorkspaceFramePattern` | 整页框架承载左侧 `ConversationList`、中间 `IMConversationPattern`、右侧 `InfoDisplayPanel`；托管助手 tab 默认用模板内置 `ChatMessage role="user"` + `HiAI` 执行流 + 推荐回复 + 复制/发送交互，并映射当前 IM 线程文案 | 新造三栏 AppShell、用多个 Card 手搓信息区、托管助手只写静态 AssistantPanel、让信息区与 IM 当前线程上下文错位 |
| `IMConversationPattern` | 当前线程消息用 `ChatBubble`；普通回复输入用 `ChatInput variant="im-basic"`；多线程列表用 `ConversationList`；系统事件用居中弱化文字 | 用 `ChatMessage` 做普通客服气泡、在消息区和输入框之间插入额外推荐层、横向滚动查看气泡 |

### 0.3 选型后立即读取 Recipe

选定模板后，必须马上到 `LAYOUT_RECIPES.md` 读取对应 recipe，再写 JSX：

- `BasePageFramePattern` / 列表示例 → `base-management`
- `ChatHomePagePattern` → `chat-home`
- `ChatConversationPattern` → `chat-conversation`
- `CopilotPagePattern` → `copilot-workbench`
- `CustomerServiceWorkspaceFramePattern` → `customer-service-workspace`
- `TicketAgentWorkspaceFramePattern` → `customer-service-workspace`（与客服三栏同 recipe；都属于工作台容器语义）
- `IMConversationPattern` → `im-thread`

⛔ 禁止只凭“白卡承载工作内容”这句通用原则生成整页。页面级 header、AI 入口页、会话输入区、产物预览区分别有不同容器语义，必须由 recipe 决定。

### 0.4 `ChatMessage` vs `ChatBubble` 快速判别（防 IM / AI 混用 · 高频误判点）

| 你看到的语义信号 | 用谁 | 不要用谁 |
| --- | --- | --- |
| AI 任务会话、执行进度、任务规划、流式输出、产物卡、follow-up、Copilot 侧助、托管助手 tab | `ChatMessage` | ⛔ `ChatBubble`（普通气泡承载不了 AI 多区块结构） |
| 真人客服接待、私信、站内信、履约沟通、IM 单线程、客服工作台中间 IM 聊天区 | `ChatBubble` | ⛔ `ChatMessage`（多区块结构会让普通 IM 视觉变成 AI 对话） |

> 同一页若同时存在「IM 真人对话区」+「托管助手 / AI 推荐流」，前者用 `ChatBubble`，后者用 `ChatMessage`，互不混用。

---

## 1. 平台壳 / 模块工作区

**适用**：变量、MCP、策略、知识库、客服、评估等平台模块。

- 左侧 `NavBar` 承载产品域 / 业务域。
- 顶部模块切换用 `Tabs variant="pill"` 或 `segment`，直接坐灰底。
- 右上角放页面主次操作，主操作用 `Button variant="primary"`。
- 内容白卡只装工作区，不装页面级标题、版本切换、发布按钮。

**不要**：

- 不要把顶部导航和主操作包进白卡。
- 不要在 `main` 中加 `max-w-* mx-auto`。
- 不要用多个 primary 按钮抢层级。

---

## 2. 列表管理页

**适用**：变量管理、策略列表、数据资产、配置列表、审核任务。

- 标题区：`FormTitle variant="level-1"` + 业务范围 Tag / 数量。
- 筛选区：搜索 240px 左右，筛选控件固定宽，横向排布。
- 主体：`Table` 撑满白卡剩余高度，分页固定在表格底部。
- 状态/类型：全部用 `Tag`，操作列收敛。

**优先模板**：

- 单白卡：`VariableManagementPage`
- 树形/版本列表：`StrategyListPage`

---

## 3. 分类列表 / 知识库详情页

**适用**：案例库、知识库、标签树、MCP 分类、QA 对。

- 左侧分类：`TagBar` 或分类树，固定宽，可独立白卡。
- 中间列表：选中态用品牌描边 / 轻品牌底，不大面积染色。
- 右侧详情：富文本、案例内容、知识内容、编辑区优先右侧详情面板，不轻易弹窗。
- 三栏都要 `min-h-0`，各自内部滚动。

**优先模板**：

- 分类 + 列表：`McpManagementPage`
- 列表 + 右详情：`TabTopBarListPage`

---

## 4. 策略 / 编辑详情页

**适用**：策略节点、Prompt、流程画布、模型配置、批测单测。

- 顶部：返回 + 对象名 + 页面级 Tabs + 保存/发布直接坐灰底。
- 中间：编辑器 / 画布 / 文档主体占最大面积。
- 右侧：节点配置、说明文档、单测、批量测试作为辅助面板。
- 左侧：如果存在 AI 执行进程或上下文，只放进程和摘要，不抢编辑主区。

**不要**：

- 不要把编辑详情页做成普通列表页。
- 不要让右侧配置压缩主编辑器标题或正文。
- 不要让整页滚动导致编辑区、配置区、运行区无法对照。

---

## 5. 会话工作台 / 托管页

**适用**：客服托管、工单队列、IM 会话、人工复核。

- 左侧队列按状态分组，当前项用左品牌条或轻底色。
- 中间会话流保持时间线，任务卡 / 总结卡用轻灰内嵌容器。
- 背景先按场景选：常规 IM / 客服会话默认白色会话背景；AI 问答 / 执行进度 / Copilot 类对话优先浅灰背景。
- 气泡色随背景定：白底用左灰右绿或右 AI；灰底用左灰右白，明确 AI 回复再用右 AI。
- 底部输入、确认、执行按钮固定，不随消息流滚走。
- 右侧用户信息、订单、工单详情只做辅助，不抢会话主线。
- 右侧或辅助区需要展示客服工单信息、商品信息、订单信息、用户信息、客服信息、沟通记录、处理日志等板块时，默认优先使用 `InfoDisplayPanel`；不要用多个 `Card` 或手写 tabs 拼客服信息侧栏。
- 信息板块存在多个分类时，必须通过 `InfoDisplayPanel` 顶部 Tabs 切换分类；只有单一分类时才可降级为标题 + 内容结构。

**优先组件**：

- 消息：`ChatMessage` / `ChatBubble`
- 输入：`ChatInput`
- 静态 IM 剧本：`IMConversationPattern`
- 辅助信息区：`InfoDisplayPanel`

---

## 6. 入口页 / AI 入口页

**适用**：HiSeek 首页、分析入口、模板广场、任务入口。

- **一级 → 二级**：Hero `ChatInput` 发送或模板 `Card` 启动后，整页切换到 `ChatConversationPattern`（不带左侧 `NavBar`），并通过 `bootstrapSendSignal` 自动发出首条用户消息。契约见 [PAGE_FLOW_LINKAGES.md](./PAGE_FLOW_LINKAGES.md) §1。
- 用户尚未进入具体上下文时，主输入或核心入口可以居中。
- 右侧主内容区必须是 `var(--color-blueGrey-200)` 浅灰大背景；Hero、`ChatInput`、模板 Tabs、搜索框和模板网格直接坐灰底。
- 白色卡片只用于推荐模板 / 助手 / 案例本身：模板卡写 `<Card color="white" />`；不要在模板网格外再套一层白卡。
- 模板 / 案例 / 推荐卡片在主输入下方，作为下一步路径。
- AI 渐变只用于输入、AI 推荐、AI 标识，不铺满背景。
- 左侧历史/收藏/定时可以作为轻侧栏存在，但不能抢主输入。
- 反例扫描：若同一右侧首页函数里同时出现 `ChatInput`、模板 `Card` 网格，并且外层有 `background: var(--color-surface)` / `bg-surface rounded-*` 包住整个内容区，必须拆掉这层白卡 wrapper，恢复为灰底裸放。

**优先模板**：`ChatHomePagePattern`

---

## 7. 产物预览 / 任务协同页

**适用**：AI 生成报告、飞书文档、HTML 预览、流程批测产物。

- 产物区是主角，占页面最大面积。
- 顶部工具栏轻量：标题、状态、下载、复制、全屏、链接等。
- 左侧 AI 进程区只承载上下文、进度、下一步建议。
- 正文像文档：段落、标题、指标卡、图表应形成阅读节奏。

**优先模板**：`CopilotPagePattern` / `ChatConversationPattern`

---

## 8. 多步骤配置 / 批测评估页

**适用**：评估集构建、选择对象、评估配置、批测配置。

- 横向多栏优先于纵向长表单。
- 步骤编号用小黑底数字或明确序号。
- 每栏白卡内部可用轻描边子区块承载选项、预览和参数。
- 中间预览/对象列表保持可见，右侧配置不挤压它。
- 顶部右侧固定“发起评估 / 发布 / 保存”。

**落地模板建议（避免选型后无处落脚）**：

- 若第一步动作是“筛选/选择一批对象 + 批量发起评估/批测”，默认从 `BasePageFramePattern` 起步（`base-management`），用筛选栏 + `Table` 承载对象选择，并在白卡 header 放置“发起评估”主操作。
- 若页面主角是“中间预览/结果对照 + 右侧配置/参数 + 可运行执行流”，默认用 `CopilotPagePattern`（`copilot-workbench`）把预览/结果放主工作区，把配置/说明放辅助面板，执行流用 `ChatMessage`/结果卡按模板规则承载。

---

## 9. 选型后必须做

1. 到 `components.summary.json` 查该范式涉及的组件。
2. 对每个命中组件，到 `components.index.json` 读取完整 props / rules / examples。
3. 到 `LAYOUT_RULES.md` 确认滚动模型、宽高和白卡层级。
4. 到 `GLOBAL_DESIGN_RULES.md` 确认自定义区块 token。
5. 交付前按 `CHECKLIST.md` 自检。
