@tfdesign/b-end 1.0.4

package/skills/tfds/CHECKLIST.md

@@ -0,0 +1,205 @@
+# TFDS 生成后自检 Checklist
+
+> **作用域**：页面或组件生成完成后，按本文件逐项检查。任一项失败，先修复再交付。
+
+---
+
+## 1. Skill 读取链路
+
+- 已读取 `DESIGN_PRINCIPLES.md` 判断页面气质。
+- 已读取 `PAGE_ARCHETYPES.md` 判断页面范式。
+- 已读取 `LAYOUT_RECIPES.md` 并选择唯一主 recipe（`base-management` / `chat-home` / `chat-conversation` / `copilot-workbench` / `im-thread`）。
+- 已用 `components.summary.json` 做组件初选。
+- 已对命中的组件读取 `components.index.json` 中完整 props / rules / examples。
+- 自定义区块已查 `LAYOUT_RULES.md` 与 `GLOBAL_DESIGN_RULES.md`。
+
+---
+
+## 2. 组件调用
+
+- `components.index.json` 里有对应组件时，已整体 import 使用。
+- 没有用 `div/span` 手搓 Tag、Button、Tabs、Card、FormTitle、ChatInput、Table。
+- **Tabs 尺寸默认铁律**：页面内/白卡内/面板内/表单分段/筛选维度/Playground 内的 `<Tabs />` **默认一律 SM**（省略 `size` 或显式 `size="sm"`）；只有平台顶部 header / 页面级顶导 / 产品级一级导航才允许使用 `md/lg`。
+- 页面标题、白卡标题、面板标题、section 标题全部使用 `FormTitle`。
+- 状态、类型、风险、数量徽标优先使用 `Tag`。
+- 所有纯图标按钮必须使用 `<Button iconOnly tooltip="操作文案" />`，不论 primary / outline / ghost / text 任一变体；禁止只放 icon 让用户猜操作含义。
+- 对话、消息、输入使用 `ChatMessage` / `ChatBubble` / `ChatInput`。
+- 所有人像类头像使用 `Avatar` / `AvatarGroup` 等 TFDS 组件，并默认优先使用包内本地成员头像素材；未使用 pravatar / Unsplash / placeholder 等随机外链头像。
+
+---
+
+## 3. 页面范式
+
+- 页面第一屏能看出当前对象、关键状态和下一步操作。
+- 页面主 recipe 与用户第一步动作一致：对象管理走 `base-management`，从 0 发起 AI 任务走 `chat-home`，持续 AI 协作走 `chat-conversation`，对象/产物主工作区 + AI 侧助走 `copilot-workbench`，真人会话走 `im-thread`。
+- 页面 header 直接坐灰底，没有被错误包进白卡。
+- 内容白卡只承载真实工作区：表格、列表、表单、对话、编辑器、运行结果。
+- 复杂任务使用稳定分屏，而不是纵向堆叠成长页面。
+- 入口页主行动居中，模板/案例卡片只做辅助路径；`ChatHomePagePattern` 右侧主内容区保持浅灰底，未用大白卡包住 Hero / ChatInput / Tabs / Card 网格。
+- 产物预览像可交付文档，不被压缩成普通信息卡。
+
+---
+
+## 4. 布局与滚动
+
+- 根容器 `h-dvh` / `h-full` 链路完整，关键层有 `min-h-0` / `min-w-0`。
+- 表格、消息流、编辑器、产物区在自身容器内滚动。
+- Playground、会话、多面板页没有错误地整页滚动。
+- 双栏 / 三栏布局中固定侧 `shrink-0`，主内容 `flex-1 min-w-0`。
+- **横向并列大卡工作区**（如双白卡 / 左筛选 + 右主表）：辅助侧默认具备宽度拖拽（`resizable` + `minWidth` / `maxWidth` / `overflow-visible`），主卡 `flex-1 min-w-0`；对照 `LAYOUT_RULES.md` §3.2 / `McpManagementPage`。
+- 白卡距浏览器边缘约 16px，卡与卡之间约 8px。
+- 白卡内部 padding 使用 24px，未误用到页面外框。
+- PageMetaBar / 白卡 Header / 筛选栏 / 卡片网格已按 `LAYOUT_RECIPES.md` 对齐：左侧标题 `min-w-0 flex-1`，右侧操作 `shrink-0 flex-wrap gap-2`；筛选栏固定宽而非全宽；卡片网格使用 `auto-fit/minmax`。
+- AI 入口页的 Hero、`ChatInput`、Tabs、搜索和模板网格直接坐灰底；模板卡 `Card color="white"`；网格 `gap-4`；Tabs 为 `size="sm"`。
+- `ChatMessage role="user"` 默认保持 `userBubbleTone="auto"`；白色大背景 / 白色工作卡内用户气泡应自动呈现 `fill-default` 灰底，浅灰或其他非白背景上应呈现白色气泡；不要在白底上强行写 `userBubbleTone="surface"`。
+
+---
+
+## 5. Token 与视觉
+
+- 无硬编码 `#000` / `#fff` / `#333` 等颜色。
+- 无 Tailwind 任意值 `text-[15px]` / `p-[18px]` / `rounded-[10px]` 等。
+- 须与设计一致的字重使用 `[font-weight:var(--font-semibold)]` / `[font-weight:var(--font-bold)]`，避免裸 `font-semibold` / `font-bold`（见 `GLOBAL_DESIGN_RULES.md` §2.2）。
+- 最外层白卡为纯白底 + 12px 圆角 + 无 border + 无 shadow。
+- 品牌青绿只用于焦点、激活、链接、品牌状态和标题竖条。
+- AI 渐变只出现在明确 AI 语义面。
+- 每个区域最多一个 primary 主按钮。
+
+---
+
+## 6. 文本与可读性
+
+- 核心说明、错误原因、状态说明完整可读，不被静默裁切。
+- 列表预览、文件名、对象 ID 可省略，但有 Tooltip 或详情入口。
+- 标题横向可读，没有一字一行、竖排、过窄标题列。
+- 普通标题默认不展示 description；只有确有说明诉求才开启。
+
+---
+
+## 7. 工程集成
+
+- 全局 CSS 已引入 `@import "@tf-designsystem/b-end/theme.css"`。
+- Tailwind 已扫描 `node_modules/@tf-designsystem/b-end/**/*.{js,jsx}`。
+- 交付前可运行：
+
+```bash
+node node_modules/@tf-designsystem/b-end/scripts/check-tfds-integration.mjs
+node node_modules/@tf-designsystem/b-end/scripts/check-tfds-contract.mjs
+```
+
+---
+
+## 8. FormTitle 真伪五件套（每个标题逐项目测）
+
+仅"竖条 + 文字"**不算**用对 FormTitle，必须**逐项**通过；任一不中即视为伪 FormTitle，必须改：
+
+1. **字重 = 600**（与组件一致：`[font-weight:var(--font-semibold)]`，禁止依赖裸 `font-semibold` 类）
+2. **字色 = `var(--color-foreground)` 深色**（不是 secondary 灰色）
+3. **竖条 = brand-500 蓝绿色 3×14/16px 圆角条**（不是品牌浅底、不是 1px border-left 直线）
+4. **描述默认隐藏**：无明确说明诉求时不写 `description`；确需展示时必须写 `showDescription`
+5. **描述位置正确**：`form` / `level-1` 描述在标题**下方独占一行**；`level-2` / `level-3` 描述在标题**同行右侧**；`card` 标题描述同排且**无竖条**
+6. **标题横向可读**：主标题保持横排，标题区最小宽度不低于 120px，右侧操作宁可换行也不能挤压标题
+
+**variant 选型速记**：整体页面左上角总标题 / 工作台名 → `form`；列表/管理页单张主白卡顶栏、页内一级板块标题 → `level-1`；白卡内 section 区块标题（"Prompt Workspace / System Prompt / Conversation / Tools / Run Result"等）→ `level-2`；level-2 之下子分区 → `level-3`；Card 内嵌摘要条 → `card`。
+
+**常见伪装**（命中即必须替换为 `<FormTitle />`）：
+
+- ❌ 手搓竖条：`<div className="flex gap-2"><div className="w-1 h-4 bg-teal-500 rounded" /><h3 className="text-base">Prompt Workspace</h3></div>`
+- ❌ 错用 `variant="card"` 当面板主标题（card 是弱化标题，不能用于 Workspace / System Prompt 等面板主标题）
+- ❌ `<FormTitle className="font-normal text-gray-600" />`（违反"严禁覆写"铁律）
+- ❌ 用 `<p>` 代替 `description` prop
+- ❌ 标题竖排/逐字换行：`writing-mode: vertical-rl` / `break-all` / 给标题列固定 12-24px 宽
+
+**标题状态 Tag 必须用 `titleSuffix`**：标题旁的状态 / 数量 / 身份 Tag（如 `0 条消息`、`Beta`、`只读`、`推荐`）必须作为 `titleSuffix` 紧跟主标题，不能放进右侧 action 区。
+
+✅ Good：`<FormTitle variant="level-2" title="Conversation" titleSuffix={<Tag variant="grey" size="m">0 条消息</Tag>} />`
+
+---
+
+## 9. 黑色边框误用 → 正确组件映射（高频）
+
+| 误用场景                                                | 必须改成                                              |
+| --------------------------------------------------- | ------------------------------------------------- |
+| 数值型模型参数（Temperature/Top-P/Max Tokens/阈值/权重）         | `<InputNumber />`                                 |
+| System Prompt / 模型高级参数 JSON / 请求参数 / 代码参数 / 代码输入 | `<TextArea variant="code" minRows={5} />`         |
+| 模型 ID/URL 输入                                        | `<TextArea minRows={1} />`                        |
+| 操作描述                                                | `<TextArea minRows={2} />`                        |
+| 表单备注                                                | `<TextArea minRows={3} />`                        |
+| 模型/Effort 枚举                                        | `<Select />`                                      |
+| user/assistant 角色切换                                 | `<Tabs variant="segment" />`                      |
+| Model List / 查看全部 文字链                               | `<Button variant="text-brand" />`                 |
+
+---
+
+## 10. TextArea 撑满卡片高度（卡片主编辑区标准结构）
+
+主编辑区（System Prompt / 模型高级参数 / 代码 / JSON / 长文本）**必须**：
+
+```jsx
+<section className="flex-1 min-h-0 flex flex-col overflow-hidden">
+  <header className="shrink-0 px-6 py-4">
+    <FormTitle variant="level-2" title="System Prompt" />
+  </header>
+  <div className="flex-1 min-h-0 overflow-hidden px-6 pb-6">
+    <TextArea variant="code" fillHeight resize="none" className="flex-1 min-h-0 w-full" />
+  </div>
+</section>
+```
+
+⛔ Bad：`<TextArea minRows={5} />` 直接放在高卡片里，导致控件不撑满、下方空白。
+✅ Good：header `shrink-0` 固定，body `flex-1 min-h-0 overflow-hidden`，TextArea `fillHeight` 后内部滚动。
+
+**code 字号铁律**：`variant="code"` 正文与行号必须保持 14px / 20px，⛔ 禁止外层套 `text-base` / `text-lg` / `leading-7` / `style={{ fontSize: 16 }}`。
+
+---
+
+## 11. 多面板 / Playground 嵌套结构（防整页滚）
+
+**触发关键词**：`playground` / `调试` / `试验` / `IDE` / `多面板` / `prompt editor` / `prompt workspace` / `runtime` / `run result` / `输入区+输出区+参数区` / `A/B 对比` / `编辑器+预览`。
+
+**必须从根到面板正文逐层匹配此骨架**：
+
+```
+h-dvh + overflow-hidden                              ← 根：永不滚
+  └─ main: flex-1 min-h-0 + overflow-hidden          ← 主区：永不滚
+       └─ section/aside（横向子项）
+            └─ flex-1 min-h-0 min-w-0 + flex-col + overflow-hidden  （或 shrink-0 w-[Npx]）
+                 ├─ header: shrink-0
+                 └─ body:   flex-1 min-h-0 overflow-y-auto          ← 唯一滚动层
+```
+
+任一层 `overflow-y-auto` 写在错误位置或漏 `min-h-0`，整页就会一起滚。
+
+仅 **Dashboard / 入口聚合首页 / KPI 看板**（纯堆叠浏览，无面板内编辑）才允许整页滚（LAYOUT_RULES § 12.4）。
+
+---
+
+## 12. 页面 header 灰底裸放（Bad / Good 对照）
+
+**白卡装什么 / 灰底装什么**：
+
+| 内容类型                                  | 装在哪    | 理由                          |
+| ------------------------------------- | ------ | --------------------------- |
+| 列表 / 表格 / 对话流 / 参数表单 / 运行结果 / 编辑器主体 | ✅ 白卡   | 用户在这里"做事"——这是工作区            |
+| 页面标题 + 描述 + 主次操作按钮（返回/导入/导出）       | ✅ 灰底裸放 | 用户"了解 / 切换位置 / 触发动作"——页面元数据 |
+| 面包屑 / 页面级 Pill Tabs（业务模块切换）        | ✅ 灰底裸放 | 页面级导航，不是卡内子页签               |
+| 全局浮窗工具条（Floating Action Bar）        | ✅ 灰底裸放 | 页面级动作                       |
+| 白卡内的子区块标题（FormTitle level-2/3）     | ✅ 在白卡内 | 卡内层级，不是页面级 header           |
+
+| ❌ 误用                                                      | ✅ 必须改成                                                                                                       |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `<div bg=surface rounded-lg p-6>{标题 + 描述 + 操作按钮}</div>` | `<header className="shrink-0 px-4 pt-3 pb-2 flex justify-between">{...}</header>`（直接坐灰底，参照 LAYOUT_RULES § 1.5.2） |
+| 把页面级 Pill Tabs（业务模块切换）放进白卡                                | Pill Tabs 直接坐灰底（参照 CopilotPagePattern 的 TopBarTabs）                                                          |
+| "标题白卡 + Tab 白卡 + 内容白卡"三张白卡叠加                              | 顶部一行灰底裸放 + 一张内容白卡                                                                                            |
+
+**参考样本**：`CopilotPagePattern` TopBar = 裸顶导栏标杆；`BasePageFramePattern` = 顶部灰底 PageHeader + 单白卡 / 双白卡内容区组合。
+
+---
+
+## 13. 全宽撑满 / 左右大空白专项
+
+- `main` padding **只能是 `p-4`（16px）**，⛔ 禁止 `p-2` / `p-6` / `p-8` 当外框间距
+- ⛔ **禁止**在 `main` 内套 `<div className="max-w-* mx-auto">` 居中容器
+- 白卡 div 自身**不加 `mx-` 外边距**，靠 `flex-1` / `shrink-0 w-[Npx]` 控制宽度
+- ⛔ 禁止根容器 / `main` 加 `max-w-screen-xl` / `max-w-7xl` / `max-w-[1440px]` 等收窄值
+- AI 入口页（`ChatHomePagePattern`）右侧主内容区禁止用 `bg-surface` / 白卡 wrapper 包住 Hero + ChatInput + Tabs + Card 网格；只允许模板卡自身是 `<Card color="white" />`

package/skills/tfds/COMMON_FAILURES.md

@@ -0,0 +1,238 @@
+# TFDS 常见失败模式与修复
+
+> **作用域**：当生成页面“不像 TFDS”、组件看起来对但细节不对、或 IDE 不能稳定调用 `/tfds` 时，先查本文件。
+
+---
+
+## 目录
+
+- §1 `/tfds` 没有真正加载规范
+- §2 只读了设计原则，没有读组件详情
+- §3 手写“看起来像”的组件
+- §4 FormTitle 仍然是细体或伪标题
+- §5 白卡被灰边框或阴影圈死
+- §6 页面 header 被包进白卡
+- §7 多面板页整页滚动
+- §8 AI 入口页被大白卡包住
+- §9 输入框在白卡正文里没有撑满
+- §10 Tabs 被 Button 或 Tag 冒充
+- §11 TextArea 代码字号偏大
+- §12 Tailwind 没扫描包内组件
+- §13 字重用了裸 `font-semibold` / `font-bold`
+- §14 没有先选布局 Recipe，导致容器和间距混乱
+- §15 头像用了随机外链或手写 img
+- §16 ChatMessage 用户气泡在白底上仍是白色
+
+---
+
+## 1. `/tfds` 没有真正加载规范
+
+**现象**：AI 说按 TFDS 做了，但仍在手搓组件、写 hex、用普通后台模板。
+
+**原因**：当前对话没有加载 Skill，或 IDE 未重新扫描安装后的 Skill 目录。
+
+**修复**：
+
+- Cursor / Claude Code：重启 IDE 或重新打开项目后输入 `/tfds`。
+- Codex：新开/重启会话后输入 `/tfds`；不出现时引用 `~/.codex/skills/tfds/SKILL.md`。
+- 其他 IDE：先读 `AI_READ_FIRST.md`，再按其中链路读取 Skill 文档。
+
+---
+
+## 2. 只读了设计原则，没有读组件详情
+
+**现象**：页面气质接近，但 props、尺寸、交互和组件不一致。
+
+**原因**：只读了 `DESIGN_PRINCIPLES.md` 或 `components.summary.json`，没有读取命中组件在 `components.index.json` 里的完整 rules。
+
+**修复**：每个命中组件必须回查 `components.index.json#组件 id`。
+
+---
+
+## 3. 手写“看起来像”的组件
+
+**现象**：Tag、Button、Tabs、FormTitle、ChatInput 看起来接近，但 hover、focus、字号、状态不一致。
+
+**原因**：用 `div/span/button` 仿样式，而不是 import 组件。
+
+**修复**：凡 `components.summary.json` 命中组件，必须整体 import：
+
+```jsx
+import { FormTitle, Tag, Button, Tabs } from '@tf-designsystem/b-end';
+```
+
+---
+
+## 4. FormTitle 仍然是细体或伪标题
+
+**现象**：标题左侧有竖条，但文字不是 600 字重，或仍是 `<h2>` / `<span>`。
+
+**原因**：没有使用 `FormTitle`，或外部 className 覆写了组件字体。
+
+**修复**：
+
+- 页面、白卡、面板、section 标题全部用 `<FormTitle />`。
+- 不传 `font-`*、`text-`* 覆写标题；字重以组件内 `[font-weight:var(--font-semibold)]` 为准（见 `GLOBAL_DESIGN_RULES.md` §2.2）。
+- 状态数量用 `titleSuffix`。
+
+---
+
+## 5. 白卡被灰边框或阴影圈死
+
+**现象**：页面看起来像旧式 admin，白卡边界很硬。
+
+**原因**：最外层白卡加了 `border`、`outline`、`ring`、`shadow`。
+
+**修复**：最外层工作白卡只保留：
+
+```jsx
+style={{ background: 'var(--color-surface)', borderRadius: 'var(--radius-lg)' }}
+```
+
+内部 Input / Select / Table / Tag 的描边保留。
+
+---
+
+## 6. 页面 header 被包进白卡
+
+**现象**：顶部“标题 + 描述 + 操作按钮”是一张白卡，下方内容又是一张白卡，主从混乱。
+
+**原因**：把页面元信息误当成工作区内容。
+
+**修复**：页面 header 直接坐灰底；只有列表、表格、表单、对话、编辑器、运行结果进入白卡。
+
+---
+
+## 7. 多面板页整页滚动
+
+**现象**：写 prompt、调参数、看结果需要上下滚，输入输出无法对照。
+
+**原因**：Playground / 会话 / 编辑详情页误用了普通 Dashboard 滚动模型。
+
+**修复**：整页 `overflow-hidden`，每个面板内部滚动；标题栏 `shrink-0`，正文 `flex-1 min-h-0 overflow-y-auto`。
+
+---
+
+## 8. AI 入口页被大白卡包住
+
+**现象**：AI 入口首页外层是浅灰底，但右侧内容区又套了一整张很大的白色圆角卡，里面再放 `ChatInput` 和模板卡片，视觉变成“灰底 → 大白卡 → 卡片”。
+
+**原因**：AI 把“白卡承载工作内容”泛化到入口页，把 Hero / 输入框 / 模板广场误判为结构化管理页工作区。
+
+**修复**：
+
+- 先确认页面是否是 `ChatHomePagePattern`：用户尚未进入上下文，第一步是输入需求 / 搜索助手 / 从模板开始。
+- 若命中入口页，右侧主内容区保持 `var(--color-blueGrey-200)` 浅灰底。
+- Hero、`ChatInput`、Tabs、搜索框、模板 Card 网格直接坐灰底。
+- 删除包住整块首页内容的 `bg-surface rounded-*` / `background: var(--color-surface)` wrapper。
+- 模板卡片自身使用 `<Card color="white" />`；只有列表管理、表单详情、表格、编辑器、多面板工作区才进入白色工作卡。
+
+---
+
+## 9. 输入框在白卡正文里没有撑满
+
+**现象**：配置项、名称、标题输入框只占一小段，显得不专业。
+
+**原因**：把筛选栏固定宽规则误用到正文表单。
+
+**修复**：
+
+- 筛选栏：固定宽。
+- 白卡正文单列字段：`w-full`。
+
+---
+
+## 10. Tabs 被 Button 或 Tag 冒充
+
+**现象**：一排按钮用于切换内容，状态和交互不像平台组件。
+
+**原因**：没有区分“动作”和“视图切换”。
+
+**修复**：
+
+- 同一区域互斥内容切换必须用 `<Tabs />`（禁止用 Button/Tag 冒充）。
+- 内容区（白卡/面板/表单分段/筛选维度/Playground）默认 **一律** `size="sm"`（省略 size 也等价）；只有平台顶部 header / 页面级顶导 / 产品级一级导航才允许 `md/lg`。
+
+---
+
+## 11. TextArea 代码字号偏大
+
+**现象**：JSON / Prompt / 代码编辑区像放大版文本，行号和正文不稳。
+
+**原因**：给 `TextArea variant="code"` 外部传了 `text-base` / `leading-6` 等覆写。
+
+**修复**：直接使用组件默认 code variant，保持 14px / 20px。
+
+---
+
+## 12. Tailwind 没扫描包内组件
+
+**现象**：组件样式缺失，黑边框、默认字体、颜色退化。
+
+**原因**：缺少 theme.css 或 `@source`。
+
+**修复**：
+
+```css
+@import "tailwindcss";
+@import "@tf-designsystem/b-end/theme.css";
+
+@source "./**/*.{js,jsx,ts,tsx}";
+@source "../node_modules/@tf-designsystem/b-end/**/*.{js,jsx}";
+```
+
+## 13. 字重用了裸 `font-semibold` / `font-bold`
+
+**现象**：标题或列表主文案「看起来加粗了」，但和预览 / Token 面板不一致，或在不同 Tailwind 版本下忽粗忽细。
+
+**原因**：直接用 Tailwind 语义类 `font-semibold` / `font-bold`；在 Tailwind v4 下 `--font-`* 可能与 font-family 语义冲突。
+
+**修复**：
+
+- 需要 **600** 时写：`[font-weight:var(--font-semibold)]`（与 `FormTitle` / `Button` / `Form` 标签等一致）。
+- 需要 **700** 且组件 rules 允许时写：`[font-weight:var(--font-bold)]`。
+- 页面标题一律用 `<FormTitle />`，不要手写 `h2 + font-semibold`。
+
+---
+
+## 14. 没有先选布局 Recipe，导致容器和间距混乱
+
+**现象**：页面看起来用了 TFDS 组件，但布局像拼贴：入口页被白卡包住、列表页左右留白过大、筛选栏控件不齐、卡片网格间距不统一、Tabs 尺寸忽大忽小。
+
+**原因**：AI 直接从组件开始写 JSX，没有先判断页面属于 `base-management` / `chat-home` / `chat-conversation` / `copilot-workbench` / `im-thread` 哪个 recipe。
+
+**修复**：
+
+1. 回到 `PAGE_ARCHETYPES.md`，用“用户第一步动作”选模板。
+2. 打开 `LAYOUT_RECIPES.md`，选择唯一主 recipe。
+3. 按 recipe 决定容器：灰底直排、白色工作卡、会话流、Copilot 工作台或 IM 线程。
+4. 再补组件：`FormTitle`、`Tabs`、`Input`、`Table`、`ChatInput`、`Card` 等。
+5. 最后扫描反例：`main p-2/px-6`、`max-w-* mx-auto`、`bg-surface rounded` 包入口页、筛选栏 `w-full`、内容区 `Tabs size="md"`。
+
+---
+
+## 15. 头像用了随机外链或手写 img
+
+**现象**：IM 对话、ChatBubble、Table 负责人列、NavBar 底部用户头像使用 `https://i.pravatar.cc`、Unsplash、placeholder 图片，或手写 `<img className="rounded-full">`。
+
+**原因**：AI 把头像当成普通图片占位，没有读取 `Avatar` / `ChatBubble` / `Table` 的素材来源规则。
+
+**修复**：
+
+- 人像类头像必须用 `Avatar` / `AvatarGroup`，IM 气泡用 `ChatBubble`，表格头像列用 `Table type="avatar"` / `type="avatarText"`。
+- 缺省头像不要传随机外链；`Avatar` 图片态未传 `src` 时会自动随机使用包内本地成员头像素材。
+- 需要稳定绑定成员时，从包内导出的 `getTeamMemberByIndex` / `getTeamAvatarBySeed` 取本地成员头像，再传给 `avatarSrc`。
+
+---
+
+## 16. ChatMessage 用户气泡在白底上仍是白色
+
+**现象**：白色大背景 / 白色工作卡内，`ChatMessage role="user"` 仍然是纯白气泡，气泡边界和父背景混在一起。
+
+**原因**：旧规则要求手动传 `userBubbleTone="fill"`，AI 容易漏传；或直接写死 `userBubbleTone="surface"`，导致白底上仍使用白色气泡。
+
+**修复**：
+
+- 默认不传 `userBubbleTone`，让组件使用 `auto` 根据最近父级背景自动适配。
+- 白色大背景 / 白色工作卡内应呈现灰色 `fill` 气泡；复杂白底无法识别时显式传 `userBubbleTone="fill"`。
+- 浅灰、蓝灰、AI 会话灰底等非白背景应呈现白色 `surface` 气泡；只有复杂非白背景无法识别时才显式传 `userBubbleTone="surface"`。