@tfdesign/b-end 1.0.4

package/skills/tfds/PAGE_ARCHETYPES.md

@@ -0,0 +1,201 @@
+# TFDS 页面范式选型（AI 先判页面，再选组件）
+
+> **作用域**：生成整页前，用本文件判断页面属于哪种范式。选定范式后，再到 `components.summary.json` 选组件、到 `components.index.json` 读取命中组件详情。
+>
+> **原则**：页面范式由用户第一步动作决定，而不是由视觉喜好决定。
+
+---
+
+## 目录
+
+- §0 选型决策树
+- §1 平台壳 / 模块工作区
+- §2 列表管理页
+- §3 分类列表 / 知识库详情页
+- §4 策略 / 编辑详情页
+- §5 会话工作台 / 托管页
+- §6 入口页 / AI 入口页
+- §7 产物预览 / 任务协同页
+- §8 多步骤配置 / 批测评估页
+- §9 选型后必须做
+
+---
+
+## 0. 选型决策树
+
+| 用户第一步动作 | 首选页面模板 | 布局 Recipe | 必须出现的主组件 | 不要误选 |
+| --- | --- | --- | --- | --- |
+| 筛选、搜索、浏览一批结构化对象、批量操作、查看详情 | `BasePageFramePattern`，再从 `StrategyListPage` / `VariableManagementPage` / `McpManagementPage` / `TabTopBarListPage` 选子模板 | `base-management` | `NavBar`、`FormTitle`、`Input/Select/DatePicker/TagInput`、`Table`、`Tag`、`Button`，有分类维度时加 `TagBar` | 不要因为页面里有 AI 字样就选 `ChatHomePagePattern` 或 `ChatConversationPattern` |
+| 用户尚未进入具体上下文，第一步是输入一句需求、搜索助手、从模板 / 案例开始 | `ChatHomePagePattern` | `chat-home` | `NavBar`、`ChatInput`、`Tabs`、`Card`、`Input`、`Icon`；右侧主区保持浅灰底，模板卡用白底 Card | 不要做成“标题 + 筛选 + 表格”的白卡管理页；不要在右侧内容区外包一整张白色大卡 |
+| 用户已在一个 AI 任务 / 会话里，第一步是继续追问、看执行进度、看 AI 消息流 | `ChatConversationPattern` | `chat-conversation` | `ChatMessage`、`ChatInput`、`Button`、`Icon` | 不要用 `ChatBubble` 手搓 AI 回复，也不要把消息流塞进表格 / 白卡列表 |
+| 用户正在编辑 / 查看一个对象或产物，同时需要 AI 辅助分析、改写、解释、侧边追问 | `CopilotPagePattern` | `copilot-workbench` | `Button`、`Tabs`、`ChatInput`、`Switch`、`Icon`，编辑区按内容补 `FormTitle/TextArea/InputNumber/Select` | 不要选纯 `ChatConversationPattern`，因为主角不是消息流，而是右侧对象 / 产物 / 画布 |
+| 用户处理真实人际消息、客服接待、私信、站内信、履约沟通，第一步是查看历史消息并回复 | `IMConversationPattern`，多线程时外层组合 `ConversationList` | `im-thread` | `ChatBubble`、`ChatInput variant="im-basic"`，多线程加 `ConversationList` | 不要用 `ChatMessage` 渲染普通 IM 气泡；不要把普通客服会话误判为 AI 对话页 |
+| 无权限、建设中、无数据 | `BasePageFramePattern` 的 NoAccess / Construction 子示例或 `Empty` | 跟随承载页面，通常 `base-management` | `Empty`、`Button` | 不要新造插画、空状态卡片或手写状态徽标 |
+
+### 0.1 五模板选择优先级
+
+当用户描述同时命中多个模板时，按下面顺序裁决，裁决依据是“用户进入页面后的第一步动作”和“页面主角”，不是页面里出现了哪个组件名。
+
+1. **普通 IM / 客服沟通优先判 `IMConversationPattern`**：只要主线是人与人 / 人与客服 / 用户与机器人按时间线往返，且业务目标是继续回复当前线程，就用 IM；AI 只作为机器人角色存在时也仍是 IM。
+2. **AI 消息流优先判 `ChatConversationPattern`**：如果主线是一条 AI 任务会话，用户要追问、确认任务规划、看流式执行、查看 AI 产物卡，就用 AI 对话页。
+3. **对象编辑 + AI 侧助优先判 `CopilotPagePattern`**：如果右侧对象、文档、策略画布、报告预览是主工作区，AI 只是辅助解释 / 改写 / 追问，就用 Copilot。
+4. **从 0 开始发起任务优先判 `ChatHomePagePattern`**：如果用户还没选对象、没进入会话，只是要搜索助手、输入需求、从模板开始，就用 AI 入口页。
+5. **结构化对象管理默认判 `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 侧栏抢主内容宽度、把对象编辑页做成纯聊天页 |
+| `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`
+- `IMConversationPattern` → `im-thread`
+
+⛔ 禁止只凭“白卡承载工作内容”这句通用原则生成整页。页面级 header、AI 入口页、会话输入区、产物预览区分别有不同容器语义，必须由 recipe 决定。
+
+---
+
+## 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。
+- 底部输入、确认、执行按钮固定，不随消息流滚走。
+- 右侧用户信息、订单、工单详情只做辅助，不抢会话主线。
+
+**优先组件**：
+
+- 消息：`ChatMessage` / `ChatBubble`
+- 输入：`ChatInput`
+- 静态 IM 剧本：`IMConversationPattern`
+
+---
+
+## 6. 入口页 / AI 入口页
+
+**适用**：HiSeek 首页、分析入口、模板广场、任务入口。
+
+- 用户尚未进入具体上下文时，主输入或核心入口可以居中。
+- 右侧主内容区必须是 `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. 多步骤配置 / 批测评估页
+
+**适用**：评估集构建、选择对象、评估配置、批测配置。
+
+- 横向多栏优先于纵向长表单。
+- 步骤编号用小黑底数字或明确序号。
+- 每栏白卡内部可用轻描边子区块承载选项、预览和参数。
+- 中间预览/对象列表保持可见，右侧配置不挤压它。
+- 顶部右侧固定“发起评估 / 发布 / 保存”。
+
+---
+
+## 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` 自检。

package/skills/tfds/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: tfds
+description: "体服DesignSystem，一键调用TFDS组件生成符合体服设计规范的UI组件与页面"
+disable-model-invocation: true
+metadata:
+  version: "3"
+  system: "b-end"
+  display_name: "【TFDS】"
+---
+
+# 【TFDS】B 端页面生成 Skill
+
+你是 **TFDS 前端实现助手**。用户已通过 `npm` 安装 `@tf-designsystem/b-end`，并在项目里安装了本 Skill（路径通常为 `.cursor/skills/tfds/`、`.agents/skills/tfds/`、`.claude/skills/tfds/` 之一）。
+
+> 本文件只保留**决策树 + 5 条铁律 + 必读链路**。逐项 Bad/Good 反例与五件套下沉到 [CHECKLIST.md](./CHECKLIST.md) 与 [COMMON_FAILURES.md](./COMMON_FAILURES.md)：高风险场景（FormTitle / Playground / ChatHome / 多面板 / IM）生成前按需读取命中章节，交付前再全量自检。
+
+---
+
+## 0. 启动判断（决策树）
+
+| 触发信号                                                            | 强度   | 行为                                       |
+| --------------------------------------------------------------- | ---- | ---------------------------------------- |
+| 用户输入 `/tfds`、`@tfds`、点名「【TFDS】」                                 | 🟢 强 | **必须**完整执行本 Skill 流程                     |
+| 用户说「按 TFDS 生成 / 用 b-end 设计 / 按设计系统做」                            | 🟢 强 | **必须**完整执行本 Skill 流程                     |
+| 当前业务项目已 `import` 了 `@tf-designsystem/b-end` 且用户在写 React/Vite 页面 | 🟡 中 | 主动应用本 Skill；若用户明显意图不在 UI（如改 API/写测试），不强制 |
+| 其他对话（聊天、写后端、写脚本等）                                               | ⚪ 无  | **不要**启动本 Skill                          |
+
+启动后**先看下方 5 条铁律**（最高优先级），再按"必读文档"和"黄金流程"执行。
+
+---
+
+## ⚡ AI 调用优先级 · 5 条铁律（最高级别 · 高于本文件其他章节）
+
+**每生成一个 UI 元素之前**，必须先按下面的决策树判断：
+
+```
+┌─ ① 私有 NPM 组件（summary 初选 + index 详情）── 首选：整体复用
+│      匹配 → 直接 import + 传 props，⛔ 禁止"仿造样式"
+│      不匹配 ↓
+├─ ② 通用设计规范（LAYOUT_RULES.md + GLOBAL_DESIGN_RULES.md）── 次选：用 token 拼装
+│      仍找不到 ↓
+└─ ③ 严禁"凭审美随机生成"     ← 最高禁忌
+```
+
+> **头像素材硬规则**：凡使用 `Avatar` / `AvatarGroup` / `ChatBubble` / `ConversationList` / `NavBar` / `Table` 的人像类头像，默认优先使用包内本地成员头像素材（`team-avatar-assets`，可随机或按数据 seed 取用）。`Avatar` 图片态未传 `src` 时会自动随机使用本地成员头像；生成页面时不要写 pravatar / Unsplash / placeholder 等随机外链头像，只有业务真实接口返回用户头像 URL 时才传远程 `src`。
+
+> **ChatMessage 用户气泡背景硬规则**：`ChatMessage role="user"` 默认保留 `userBubbleTone="auto"`；白色大背景 / 白色工作卡内自动用灰色 `fill` 气泡，浅灰、蓝灰、AI 会话灰底等非白背景自动用白色 `surface` 气泡。不要在白底上显式写 `userBubbleTone="surface"`，复杂背景无法识别时才手动传 `fill` / `surface`。
+
+1. ✅ **优先调用私有组件，整体复用**
+   组件索引里有对应组件 → **必须**直接 `import` 整体使用 + 通过 props 配置；
+   ⛔ **禁止**"参考样式自己手搓相似组件"；⛔ **禁止**仅改颜色/字号等样式片段后冒充组件（如把 `<Tag />` 写成 `<span className="rounded bg-… text-…">`）。
+   **标题是最高频组件，不是排版细节**：任何页面标题、白卡标题、面板标题、卡片左上角标题、section 标题、workspace 标题、Conversation/Settings/Result 标题，必须先 `import { FormTitle } from '@tf-designsystem/b-end'` 并用 `<FormTitle />`；⛔ 禁止手写 `h2/h3/span + 自绘竖条`。
+2. ✅ **私有未覆盖时走通用规范**
+   组件索引找不到对应模块 → **必须**按 `LAYOUT_RULES.md` + `GLOBAL_DESIGN_RULES.md` 用现有 token 拼装出新模块，**不**回退到"裸 div + 自定义样式"。
+3. ✅ **混合使用必须对齐原子变量**
+   通用模块与私有组件同屏组合时 → 颜色/间距/圆角/阴影/字号/行高**全部走 token**（`var(--color-...)` / `var(--spacing-...)` / `var(--radius-...)` / `var(--shadow-...)` / `var(--text-...)`）；
+   ⛔ **禁止**任何 `#hex` 硬编码、`text-[Npx]` / `p-[Npx]` 等任意值、`text-black` / `border-black` / `bg-gray-N` 通用调色板。
+4. ⛔ **严禁脱离两大规范**
+   "私有组件库（components.summary.json + components.index.json）" + "通用设计规范（LAYOUT + GLOBAL）" 是 AI **唯一允许**的创作素材库。
+   ⛔ **禁止**随机生成无规则的组件、样式、布局；⛔ **禁止**用模型自身审美填空。
+5. ✅ **新场景拓展只能走通用规范**
+   遇到组件库与通用规范都未直接覆盖的特殊场景 → **必须**基于 `GLOBAL_DESIGN_RULES.md` 现有 token 组合拓展；
+   ⛔ **禁止**自行新增任何 token、⛔ **禁止**绕开 token 体系硬写值。
+
+> ⚠️ **本节优先级最高**：与下方任何章节、任何 component rules 有歧义时，以本节 5 条铁律为准。
+
+---
+
+## 1. 必读文档（按加载顺序）
+
+设计组件数量有限，无法覆盖所有 AI 生成场景。生成页面前**必须**按下面顺序加载文档；其中 `components.index.json` 是完整权威索引，只在 `components.summary.json` 初选命中后读取对应条目，不要一开始全文吞入。
+
+| #   | 文档             | 路径                         | 读取时机                                      |
+| --- | -------------- | ---------------------------- | --------------------------------------------- |
+| 1   | **设计原则**       | `./DESIGN_PRINCIPLES.md`     | 先判断页面气质、UX 取舍、视觉权重和组件角色              |
+| 2   | **页面范式**       | `./PAGE_ARCHETYPES.md`       | 判断页面类型、信息架构、主工作流和首选模板                |
+| 3   | **布局 Recipe**   | `./LAYOUT_RECIPES.md`        | 把页面范式映射为容器语义、间距、对齐、滚动和反例扫描           |
+| 4   | **组件摘要**       | `./components.summary.json`  | 快速筛选页面模板 / 业务组件 / 基础组件，不作为样式权威       |
+| 5   | **组件详情索引**    | `./components.index.json`    | 只读取命中的组件条目，抄 props / rules / examples     |
+| 6   | **页面布局规范**    | `./LAYOUT_RULES.md`          | 决定页面骨架、滚动层级、宽高自适应                     |
+| 7   | **全局设计规范**    | `./GLOBAL_DESIGN_RULES.md`   | 写组件库未覆盖的自定义区块时（颜色/字体/间距/圆角/阴影 token） |
+| 8   | **场景/交付自检**    | `./CHECKLIST.md`             | 高风险场景生成前按命中章节读取；交付前全量检查组件调用、页面范式、布局、token 和工程集成 |
+| 9   | **常见失败修正**    | `./COMMON_FAILURES.md`       | 生成前遇到命中反例按需读取；页面"不像 TFDS"或 `/tfds` 调用失败时优先排查 |
+
+### 规范优先级（冲突时从高到低）
+
+```
+0. ⚡ 本文件「5 条铁律」                          ← 最高
+1. components.index.json 命中组件 rules / examples
+2. 本 SKILL.md 决策（§2 黄金流程）
+3. LAYOUT_RECIPES.md（容器语义、容器模式、间距对齐 recipe）
+4. LAYOUT_RULES.md（页面骨架、响应式）
+5. GLOBAL_DESIGN_RULES.md（颜色/字体/间距 token）
+6. DESIGN_PRINCIPLES.md / PAGE_ARCHETYPES.md / components.summary.json
+7. 模型自身审美                                   ← 永远最后
+```
+
+---
+
+## 2. 黄金流程（生成任意页面前必走）
+
+1. **栈对齐**：项目为 Vite + React + Tailwind v4；全局样式已 `@import "tailwindcss"` 且已 `@import "@tf-designsystem/b-end/theme.css"`；Tailwind 已扫描 `node_modules/@tf-designsystem/b-end/**/*.{js,jsx}`。
+2. **先选页面骨架**：按 `PAGE_ARCHETYPES.md` 判断页面范式 → 按 `LAYOUT_RECIPES.md` 选唯一主 recipe → 用 `components.summary.json` 初选 `kind: "page-pattern"` / `kind: "page-template"` → 回查 `components.index.json`：
+   - **结构化对象管理** → `BasePageFramePattern`（浅灰底整页 + 多白卡分区，贴浏览器边缘，无外圈圆角/描边）
+   - **从 0 发起 AI 任务** → `ChatHomePagePattern`（右侧主内容区**保持灰底**，⛔ 禁止包大白卡 wrapper；模板卡用 `<Card color="white" />`）
+   - **围绕 AI 任务持续协作** → `ChatConversationPattern`（消息流必须用 `ChatMessage`）
+   - **对象编辑 / 产物查看 + AI 侧助** → `CopilotPagePattern`
+   - **真实 IM / 客服 / 私信线程** → `IMConversationPattern`（`ChatBubble` + `ChatInput variant="im-basic"`）
+   - **客服多模块工作台框架** → `CustomerServiceWorkspaceFramePattern`（`activeConversationId` 单一事实源，左右联动）
+   - **页面模板示例**：`StrategyListPage` / `VariableManagementPage` / `McpManagementPage`（双白卡 + 横向拖拽标杆）/ `TabTopBarListPage`；无权限 / 建设中先用 `Empty + Card + Button` 按通用规范组合，除非 `components.index.json` 明确导出对应模板
+3. **有组件不手搓**：
+   - 顶/侧导 → `NavBar`（命中即一级骨架切到 `flex-row` app shell，⛔ 禁止纵向堆叠）；列表 → `Table`；表单 → `Input/Select/Button`；对话 → `ChatInput/ChatMessage`
+   - `summary.json` 只用于初选；具体 JSX 前必须回到 `components.index.json` 命中条目读取 props / rules / examples
+4. **表单控件默认 MD（36px）**：`Input` / `Select` / `TagInput` / `InputNumber` / `Button` 在主区/筛选栏/弹窗/抽屉默认 `md`；`sm` 仅限**表格行内**与**极窄工具条**。**宽度判定**：筛选栏并排字段固定宽（搜索 ≈ 240px、状态/时间 160-200px）；白卡内单列主字段满宽 `w-full`。
+5. **类 Tab 切换硬约束**：同页/同卡内多块互斥内容点选切换**必须**用 `<Tabs />`；内容区/白卡内/Playground 内**默认 SM**（`size="sm"` 或省略）；只有平台顶部 header / 页面级顶导才允许 `md/lg`；分段器 → `variant="segment"`，详情子页签 → `line`，块状分类 → `button`，顶部胶囊 → `pill`。⛔ 禁止用 `Button` / `Tag` 冒充 Tabs。
+6. **标题必须用 `FormTitle`**（按层级选 variant，详细五件套见 [CHECKLIST.md §8](./CHECKLIST.md)）：
+   - `form` → 整页左上角总标题 / 工作台名（最大字号、无竖条）
+   - `level-1` → 一级板块标题、单张主白卡顶栏主标题
+   - `level-2` → 白卡内 section 区块标题（"Prompt Workspace / System Prompt / Conversation / Tools / Run Result"）
+   - `level-3` → level-2 之下子分区
+   - `card` → Card 头、摘要条
+   - 同页必须拉开层级；描述默认隐藏（无说明诉求不写 `description`）；标题状态 Tag 用 `titleSuffix`，⛔ 不进右侧 action 区
+   - **页面级 header 直接坐灰底**，⛔ 不得包白卡（详见 LAYOUT_RULES § 1.5 / [CHECKLIST.md §12](./CHECKLIST.md)）
+7. **状态徽标 / 图标 / 链接**：状态分类 → `<Tag size="m" />`（⛔ `<span>` 假徽标）；图标 → `<Icon name="kebab-case" size="sm" />`（⛔ `lucide-react` 单独引入）；文字链 → `<Button variant="text-brand" />`（⛔ 裸 `<a>`）。
+8. **整页高度与滚动 / 多栏 / IM 骨架**（详见 `LAYOUT_RULES.md`）：
+   - 根容器默认 `h-dvh + overflow-hidden + flex flex-col + w-full min-w-0`
+   - **NavBar 命中**：一级骨架切到 `flex-row`，左侧 `shrink-0`，右侧 `flex-1 min-w-0 flex flex-col overflow-hidden`
+   - 内容区 `flex-1 min-h-0 overflow-y-auto`；底部 `shrink-0` 吸底
+   - 双栏：辅助大卡默认支持宽度拖拽（`width + onWidthChange + minWidth + maxWidth + resizable`）；主卡 `flex-1 min-w-0`
+   - 多栏卡片用 `grid auto-fit + minmax(min(Npx, 100%), 1fr)`，⛔ 禁止固定 `grid-cols-N`
+   - 表格容器 `flex-1 min-h-0 overflow-auto`
+   - **滚动模型**：命中 Playground / 调试 / IDE / 多面板 / Prompt Editor / A-B 对比 → 整页绝不滚（详见 [CHECKLIST.md §11](./CHECKLIST.md)）；仅 Dashboard / 入口聚合首页 / KPI 看板才允许整页滚
+   - **全宽撑满铁律**：`main` padding 只能 `p-4`；⛔ 禁止 `max-w-* mx-auto` 居中容器；⛔ 禁止 `max-w-screen-xl` / `max-w-7xl` 收窄值（详见 [CHECKLIST.md §13](./CHECKLIST.md)）
+9. **Card 颜色映射**：父容器灰底 → `Card color="white"`；父容器白底 → `Card color="grey"`（避免白叠白）。
+10. **可运行交付**：输出完整 JSX 与文件路径级改动说明，保证 `npm run dev` 直接看到结果。
+
+---
+
+## 3. 生成后自检（必做）
+
+完整 13 章自检见 [CHECKLIST.md](./CHECKLIST.md)；常见失败模式与修复见 [COMMON_FAILURES.md](./COMMON_FAILURES.md)。生成前已按命中场景读取相关章节，交付前仍要完整自检；**任一项不满足，先改再交付。**
+
+最高频四个硬门禁（必过）：
+
+- ⚡ **铁律自检**：整页无"自己手搓"的相似组件；无"只复用样式片段"的伪组件；FormTitle 真伪五件套全过（[CHECKLIST.md §8](./CHECKLIST.md)）；token 全部走 var，无硬编码 / 任意值
+- 🧱 **白卡铁律**：最外层白卡纯白底 + 12px 圆角，⛔ 无 `border` / `outline` / `ring` / `shadow`
+- 🪜 **滚动模型**：根容器 `h-dvh + overflow-hidden`；NavBar 命中即 `flex-row`；多面板/Playground 走嵌套骨架（[CHECKLIST.md §11](./CHECKLIST.md)），不整页滚
+- 📐 **页面 header 灰底裸放**：标题/描述/操作按钮直接坐灰底，⛔ 不被白卡包住（[CHECKLIST.md §12](./CHECKLIST.md)）
+
+---
+
+## 4. 隔离保证（按需调用时生效）
+
+`@tf-designsystem/b-end` 可与项目内任何其他资源共存。AI 工具**不会**因为安装了这个包就把 TFDS 规范应用到所有对话——只有用户明确表达 TFDS / b-end / 设计系统意图，或当前项目已接入 `@tf-designsystem/b-end` 且任务是 UI 生成时，规范才生效。
+
+| IDE              | 调用指令                                      | 隔离原理                                                         |
+| ---------------- | ----------------------------------------- | ------------------------------------------------------------ |
+| **Cursor**       | `/tfds`                                   | 本文件已设 `disable-model-invocation: true`；Cursor 不会自动纳入对话，仅显式触发 |
+| **Codex**        | `/tfds` 或 `@.agents/skills/tfds/SKILL.md` | 隔离靠"不放入 `AGENTS.md`"维护；⛔ 禁止把 TFDS 内容写入项目根 `AGENTS.md`        |
+| **Claude Code**  | `/tfds`                                   | 通过 `.claude/skills/tfds/` 显式加载                               |
+| **Trae**         | `@tfds`（知识库引用）                            | Trae 知识库天然 opt-in；⛔ 禁止放进 `.trae/rules/`（always-on 目录）        |
+| **其它 Agent IDE** | `@` 引用本文件 / `AI_READ_FIRST.md`            | 通用原则：放在按需引用知识库，不要放进全局 prompt / 项目规则                          |
+
+**Trae 一次性设置**：在 Trae 打开「知识库」→ 新建命名 `tfds` → 添加 `node_modules/@tf-designsystem/b-end/skills/tfds/` 整个目录；若只能添加文件，至少添加 `AI_READ_FIRST.md`、`SKILL.md`、`DESIGN_PRINCIPLES.md`、`PAGE_ARCHETYPES.md`、`components.summary.json`，生成具体组件前再引用 `components.index.json`。
+
+> **Cursor 规范**（[Agent Skills](https://cursor.com/docs/context/skills)）：`name` 必须与父文件夹名 `tfds` 一致；已设 `disable-model-invocation: true` 确保不自动触发。
+
+---
+
+## 5. 集成与契约自检命令
+
+```bash
+# 集成检测（只读，检查 theme.css 引入、@source 扫描、Skill 目录）
+node node_modules/@tf-designsystem/b-end/scripts/check-tfds-integration.mjs
+
+# 契约自检（只读，扫描 #hex、任意值、间距漂移等）
+node node_modules/@tf-designsystem/b-end/scripts/check-tfds-contract.mjs
+```
+
+---
+
+## 6. 与单组件 Skill 的关系
+
+若项目中另有「ChatInput」等**单组件** zip Skill，与本 Skill **不冲突**：本【TFDS】总控 Skill 负责**整页编排与全量组件选型**；`components.summary.json` 负责快速定位，细节 props / rules / examples 仍以 `components.index.json` 命中条目为准。两者描述歧义时，以本 Skill + 包内索引为准。
+
+---
+
+**版本**：与本目录 `components.index.json` / `components.summary.json` 同步迭代（由主仓 `npm run generate:tfds-b-end-bundle` 生成）。升级 `@tf-designsystem/b-end` 后若需更新 Skill：删除 `.cursor/skills/tfds` 后重新执行 `npm i`，或手动复制 `node_modules/@tf-designsystem/b-end/skills/tfds`。