@tfdesign/b-end 1.0.4

package/AI_READ_FIRST.md

@@ -0,0 +1,131 @@
+# TFDS（@tf-designsystem/b-end）— 给任何 IDE 的 AI 阅读
+
+> **隔离说明（重要）**：本文件仅在用户**显式调用 TFDS**（输入 `/tfds`、`@tfds`，或直接 `@` 引用本文件 / `SKILL.md`）时才应被读取。**禁止**把本文件写进 `AGENTS.md`、`.trae/rules/` 等"始终生效"的全局规则——那样会让 TFDS 规范污染所有与 TFDS 无关的对话。
+
+你现在在一个消费方项目中接入 `@tf-designsystem/b-end`（TFDS B 端组件 + 主题 + 规范索引）。你的目标不是"把页面写出来就行"，而是**生成的任何页面都必须遵循 TFDS 设计规范**，并能在对方项目里直接运行。
+
+适用 IDE：Cursor / Codex / Claude Code / Trae / Copilot 等任何能读文件的 AI。
+
+---
+
+## 📚 规范读取链路（按加载顺序）
+
+设计组件数量有限，无法覆盖所有 AI 生成场景。**生成页面前**，按下列顺序加载规范文档；**所有具体硬规则都在这些文件里，本文件不再重复。**
+
+
+| #   | 文档             | 路径                                                         | 何时读                                                  |
+| --- | -------------- | ---------------------------------------------------------- | ----------------------------------------------------- |
+| ①   | **总指挥（必读）**    | `node_modules/@tf-designsystem/b-end/skills/tfds/SKILL.md` | 决定**整个生成流程**：决策树 + 黄金流程 + 生成后 Checklist             |
+| ②   | **设计原则**       | `.../skills/tfds/DESIGN_PRINCIPLES.md`                     | 判断**页面气质** + UX 取舍 + 视觉权重 + 组件角色                      |
+| ③   | **页面范式**       | `.../skills/tfds/PAGE_ARCHETYPES.md`                       | 判断页面属于列表管理、详情编辑、会话工作台、入口首页、多步骤配置等哪类范式              |
+| ④   | **布局 Recipe**   | `.../skills/tfds/LAYOUT_RECIPES.md`                        | 先选唯一页面 recipe，确定容器语义、间距、对齐和滚动归属                  |
+| ⑤   | **组件摘要（轻量）**   | `.../skills/tfds/components.summary.json`                  | 快速初选页面模板、业务组件、基础组件；不作为样式权威                         |
+| ⑥   | **组件详情索引（权威）** | `.../skills/tfds/components.index.json`                    | 只在组件命中后读取对应条目，抄 props / rules / examples              |
+| ⑦   | **页面布局规范**     | `.../skills/tfds/LAYOUT_RULES.md`                          | 决定**页面骨架** + 宽高自适应 + 滚动层级 + z-index                  |
+| ⑧   | **全局设计规范**     | `.../skills/tfds/GLOBAL_DESIGN_RULES.md`                   | 组件库**未覆盖的自定义区块**：颜色 / 字体 / 间距 / 圆角 / 阴影 token        |
+| ⑨   | **交付自检**       | `.../skills/tfds/CHECKLIST.md`                             | 页面生成后逐项检查组件调用、页面范式、布局、token、文本可读性和工程集成              |
+| ⑩   | **失败修正**       | `.../skills/tfds/COMMON_FAILURES.md`                       | `/tfds` 调用失败、组件像但不准、标题字重不对、白卡/滚动/输入框异常时优先排查       |
+| ⑪   | **本文件（兜底）**    | `node_modules/@tf-designsystem/b-end/AI_READ_FIRST.md`     | 只读隔离声明 + 安装/自检命令                                     |
+
+
+⛔ **未读 ②③④⑦⑧ 就动手写页面 / 自定义信息卡 / 状态条 / KPI 块** → AI 几乎必然生成普通 admin 气质、黑色边框、`#000` 硬编码、`text-[15px]` 任意字号，也容易把 AI 入口页错包进大白卡。⛔ **未命中并回查 ⑥ 就写具体组件** → AI 很容易手搓相似组件。**先读再写**。
+
+头像类组件默认优先使用包内本地成员头像素材：`Avatar` 图片态未传 `src` 时会自动随机取本地成员头像；IM / ChatBubble / NavBar / Table 负责人列不要生成 pravatar、Unsplash、placeholder 等随机外链头像。
+
+> 上述路径是消费方安装 npm 包后的位置；postinstall 也会把 `skills/tfds/` 全目录复制到下列 IDE 标准路径，便于就地读取：
+>
+> - `.cursor/skills/tfds/`（Cursor 重新打开项目 / 新开 Agent 会话后 → `/tfds`）
+> - `.claude/skills/tfds/`（Claude Code 重启会话后 → `/tfds`）
+> - `~/.codex/skills/tfds/`（Codex 用户级 Skill；新开/重启 Codex 会话后 → `/tfds`）
+> - `.codex/skills/tfds/`（Codex 项目内参考）
+> - `.agents/skills/tfds/`（通用 agent 兜底）
+>
+> ⚠️ **故意不写 `.trae/rules/tfds.md`**：Trae rules 是 always-on 全局规则，与本文件第一段隔离声明冲突。Trae 用户请把 `skills/tfds/` 手动加入项目知识库，命名 `tfds`，之后 `@tfds` 引用。
+
+---
+
+## 1. 安装（两种来源，二选一）
+
+### 方式 A：GitHub Packages 私有包
+
+```ini
+# .npmrc
+@tf-designsystem:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
+```
+
+```bash
+npm i react react-dom lucide-react "@tf-designsystem/b-end@^1.0.0" --save
+```
+
+### 方式 B：分发 zip / 本地 file:
+
+优先运行 zip 根目录的一键安装入口；它会自动判断目标是已有项目还是全新空文件夹：
+
+```bash
+node tfds-npm-distribution/setup.mjs
+```
+
+如果 zip 不在业务项目根，显式指定目标项目：
+
+```bash
+node "/绝对路径/.../tfds-npm-distribution/setup.mjs" --target "/绝对路径/.../业务项目根"
+```
+
+仅旧包没有 `setup.mjs` 时，才手动安装：
+
+```bash
+npm i react react-dom lucide-react "file:/绝对路径/.../tfds-npm-distribution/tfds-b-end" --save
+```
+
+脚本会自动判断：
+
+- 已有项目：复用现有 `package.json` / `vite.config` / 入口 CSS，缺什么补什么。
+- 全新空文件夹：自动创建最小 Vite + React 项目，然后继续安装 TFDS。
+
+⚠️ 不要从任何 `tmp-*/` 临时目录安装，不要在 `tfds-b-end/` 包自身目录里手动执行 `npm install file:`。
+
+---
+
+## 2. 必须的工程配置（postinstall 已自动；未自动则手动）
+
+```css
+/* src/index.css */
+@import "tailwindcss";
+@import "@tf-designsystem/b-end/theme.css";
+
+@source "./**/*.{js,jsx,ts,tsx}";
+@source "../node_modules/@tf-designsystem/b-end/**/*.{js,jsx}";
+```
+
+---
+
+## 3. 生成后必做：只读自检
+
+```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
+```
+
+第二个脚本若提示存在任意值 / 硬编码颜色 / 间距漂移，必须改到通过为止。
+
+---
+
+## 4. 强烈推荐：CI 硬门禁（@tfds/eslint-config）
+
+```bash
+npm i -D eslint @eslint/js eslint-plugin-react eslint-plugin-react-hooks globals @tfds/eslint-config
+```
+
+```js
+// eslint.config.js
+import tfds from '@tfds/eslint-config/flat';
+export default [...tfds];
+```
+
+CI / pre-commit：`npx eslint .`
+
+---
+
+> 想看完整硬规则、决策树、骨架代码、token 表、Checklist？
+> **请打开 `skills/tfds/SKILL.md`**（它会引导你按需加载页面范式、组件摘要和命中的组件详情）。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) TFDS contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,353 @@
+# @tf-designsystem/b-end（B 端组件库 · 可安装包）
+
+这个包的目标：**让对方在任意 Cursor + Vite/React 项目里安装后，可以直接 `import { … } from '@tf-designsystem/b-end'` 使用**与 TFDS 平台一致的 **B 端全量组件**（见包内 `src/index.js`）、**页面模板 / PATTERNS**，并拿到与 TFDS 一致的 **Token / theme.css**。
+
+> **独立 npm 安装**：发布时 `prepack` 会把主仓 `src/data/systems/b-end/` 打包到包内 `src/_b_end_runtime/`，因此对方 `npm i @tf-designsystem/b-end` 后**不必 clone 主仓库**即可解析组件源码。
+
+---
+
+## 👀 你是谁？跳到对应章节
+
+
+| 角色                                              | 你想做什么                             | 跳到                                               |
+| ----------------------------------------------- | --------------------------------- | ------------------------------------------------ |
+| 🎨 **设计师 / PM**                                 | 了解 TFDS 是什么、解决什么问题（**不需要写代码**）    | [§ 设计师视角：TFDS 在做什么？](#设计师视角tfds-在做什么)            |
+| 👨‍💻 **前端工程师（已有项目）**                           | 装包 → 用组件                          | [§ TL;DR：安装即完成](#tldr安装即完成全自动)                   |
+| 👨‍💻 **前端工程师（空项目）**                            | 从零搭一个 Vite + React + TFDS         | [§ 全新项目？从这里开始](#全新项目从这里开始)                       |
+| 🤖 **AI / IDE（Cursor / Codex / Trae / Claude）** | 我已被自动配置 → Cursor/Claude/Codex 用 `/tfds`；Trae 用 `@tfds` | `[skills/tfds/SKILL.md](./skills/tfds/SKILL.md)` |
+| 🛠️ **TFDS 维护者**                                | 发布新版本到 npm 仓库                     | 仓库内 `packages/tfds-b-end/PUBLISH.md`（不随 npm 包下发） |
+
+
+---
+
+## 设计师视角：TFDS 在做什么？
+
+> 给设计师 / PM / 没装过开发环境的同学读，**不涉及任何代码**。
+
+**TFDS 是一套"可被 AI 直接调用"的 B 端组件库 + 设计规范**。它解决的核心问题是：
+
+1. **AI 不再"凭感觉画"** —— 我们把所有按钮、表单、表格、聊天输入框等组件，连同它们的颜色、字号、间距规则，全部封装成 AI 能"看懂"的指令字典（`skills/tfds/`）。
+2. **设计师改 Figma = 全平台同步** —— 你只需要在 Figma 里维护组件，工程会自动读取最新规则；AI 生成的页面会和你的设计稿保持一致。
+3. **分层规范链路，覆盖所有场景**：
+  - **设计原则层**：AI 先判断页面气质、UX 取舍、视觉权重和组件角色
+  - **页面范式层**：AI 先判断是列表管理、详情编辑、会话工作台、入口首页还是多步骤配置
+  - **组件层**：AI 先读轻量摘要选型，再回查完整组件索引（Button、Card、Tabs…）
+  - **布局层**：页面骨架怎么搭（一栏 / 两栏 / IM 聊天 / 工作台…）
+  - **token 层**：组件没覆盖的自定义区块，AI 必须用什么颜色/字号/圆角
+
+📂 **你只需要优先打开这些文件浏览，就能看到规范如何约束 AI**：
+
+- `[skills/tfds/DESIGN_PRINCIPLES.md](./skills/tfds/DESIGN_PRINCIPLES.md)` — 设计原则、页面气质与 UX 取舍
+- `[skills/tfds/PAGE_ARCHETYPES.md](./skills/tfds/PAGE_ARCHETYPES.md)` — 页面范式与信息架构选型
+- `[skills/tfds/LAYOUT_RECIPES.md](./skills/tfds/LAYOUT_RECIPES.md)` — 页面 recipe、容器语义、间距和对齐决策
+- `[skills/tfds/LAYOUT_RULES.md](./skills/tfds/LAYOUT_RULES.md)` — 页面骨架规则
+- `[skills/tfds/GLOBAL_DESIGN_RULES.md](./skills/tfds/GLOBAL_DESIGN_RULES.md)` — 全局 token 规则
+
+> 💡 后续 TFDS 平台会把这些规范以可视化形式展示，设计师无需阅读 markdown 也能理解。
+
+---
+
+## 全新项目？从这里开始
+
+如果你还没有业务项目（文件夹里只有下载的包，或者是空文件夹），优先使用平台 zip 内的一键脚本。脚本会自动判断当前文件夹状态：已有项目就复用现有工程，空文件夹就自动创建最小 Vite + React 项目、安装 Tailwind v4、安装 TFDS 并释放 Skill。
+
+### 推荐：一条命令完成
+
+```bash
+node tfds-npm-distribution/setup.mjs
+```
+
+如果安装包不在业务项目根：
+
+```bash
+node "/绝对路径/.../tfds-npm-distribution/setup.mjs" --target "/绝对路径/.../业务项目根"
+```
+
+安装完成，`postinstall` 会自动配置好 CSS 和 Cursor / Claude / Codex / Agents Skill，直接进入 [TL;DR：安装即完成](#tldr安装即完成全自动) 后的使用环节。
+
+### 旧包兜底：手动 file 安装
+
+仅当你拿到的旧 zip 没有 `setup.mjs` 时，再手动创建项目并安装：
+
+```bash
+npm create vite@latest my-app -- --template react
+cd my-app
+npm install
+npm install tailwindcss @tailwindcss/vite
+npm i "file:/Users/yourname/Downloads/tfds-npm-distribution/tfds-b-end" --save
+```
+
+并确保 `vite.config.js` 含 `tailwindcss()`，入口 CSS 含：
+
+```js
+import tailwindcss from '@tailwindcss/vite';
+```
+
+> ⚠ **关键**：新版离线包优先执行 `node tfds-npm-distribution/setup.mjs`。只有旧包没有 `setup.mjs`、必须手动 `npm i file:.../tfds-b-end` 时，才要求你已经位于含自己 `package.json` 的业务项目根。
+
+---
+
+## TL;DR：安装即完成（全自动）
+
+`npm install` 完成后，`postinstall` 会自动执行下面几件事，**无需任何手动配置**：
+
+
+| #   | 自动完成                                     | 目标位置                                               |
+| --- | ---------------------------------------- | -------------------------------------------------- |
+| 1   | 复制 Cursor Skill                          | `.cursor/skills/tfds/`（Agent 输入 `/tfds` 唤起）        |
+| 2   | 复制 Claude Code Skill                     | `.claude/skills/tfds/`（输入 `/tfds` 唤起）              |
+| 3   | 复制 Codex 用户级 Skill                       | `~/.codex/skills/tfds/`（新开/重启 Codex 后输入 `/tfds`） |
+| 4   | 写入 Codex 项目内参考文件                     | `.codex/skills/tfds/` |
+| 5   | 复制 Agents Skill 兜底                       | `.agents/skills/tfds/`（通用 agent 客户端）               |
+| 6   | **插入 `theme.css` import 与 `@source` 扫描** | `src/index.css`（首个含 `@import "tailwindcss"` 的候选文件） |
+
+
+⚠ **故意不自动写入 `.trae/rules/`**：Trae rules 是 always-on 全局规则，与 TFDS"显式调用才生效"的隔离原则冲突。Trae 用户请把 `node_modules/@tf-designsystem/b-end/skills/tfds/` 手动加入「项目知识库」并命名为 `tfds`，之后在对话里 `@tfds` 引用。
+
+Skill 目录内的关键文件：
+
+- `SKILL.md`：总控流程、调用优先级、黄金流程。
+- `DESIGN_PRINCIPLES.md` / `PAGE_ARCHETYPES.md`：设计品味、页面范式、布局判断。
+- `components.summary.json`：轻量组件摘要，用于快速初选组件和模板。
+- `components.index.json`：完整组件详情，命中后读取 props / rules / examples。
+- `CHECKLIST.md` / `COMMON_FAILURES.md`：交付前自检与高频问题修正。
+
+> **前提**：如果你直接执行 `npm install file:.../tfds-b-end`，需要位于已有业务项目根，且入口 CSS 中已有 `@import "tailwindcss";`。如果是平台 zip，本节前提由 `node tfds-npm-distribution/setup.mjs` 自动补齐，空文件夹也可一键完成。
+>
+> ⚠ 不要只打开/只在解压的 `tfds-b-end/` 目录里操作；不要从 `tmp-*/` 临时目录安装（清理后路径 `ENOENT`）。
+
+### 安装方式（任选一种）
+
+- **GitHub Packages 私有包（推荐授权成员）**
+先在本机或项目 `.npmrc` 配置（不要追加全局 `--registry`）：
+  ```ini
+  @tf-designsystem:registry=https://npm.pkg.github.com
+  //npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
+  ```
+  ```bash
+  npm i react react-dom lucide-react "@tf-designsystem/b-end@^1.0.0" --save
+  ```
+- **本地 `file:`（联调最快 / 平台分发 zip）**
+  ```bash
+  npm i react react-dom lucide-react "file:/绝对路径/.../tfds-npm-distribution/tfds-b-end" --save
+  ```
+
+### postinstall 自动写入 CSS 的效果
+
+脚本在 `@import "tailwindcss";` 之后自动插入（已存在则跳过，不重复写入）：
+
+```css
+@import "tailwindcss";
+@import "@tf-designsystem/b-end/theme.css";
+@source "./**/*.{js,jsx,ts,tsx}";
+@source "../node_modules/@tf-designsystem/b-end/**/*.{js,jsx}";
+```
+
+若入口 CSS **未找到** `@import "tailwindcss"` → 不改写文件，终端打印手动步骤提示。
+
+### 跳过自动操作（可选）
+
+```bash
+# 跳过 CSS 自动补丁（保持 CSS 文件不变）
+SKIP_TFDS_CSS_PATCH=1 npm i "@tf-designsystem/b-end" --save
+
+# 跳过 Skill 复制（如 CI 环境只需依赖不需 IDE Skill）
+SKIP_TFDS_CURSOR_SKILL=1 npm i "@tf-designsystem/b-end" --save
+```
+
+### 安装后验证（可选，只读）
+
+```bash
+node node_modules/@tf-designsystem/b-end/scripts/check-tfds-integration.mjs
+```
+
+---
+
+## 1) 安装详解
+
+### 方式 A：从 Git 安装（推荐团队内部）
+
+```bash
+npm i git+ssh://git@github.com/<org>/<tfds-repo>.git#main
+```
+
+### 方式 B：本地 file 依赖（联调最快）
+
+```bash
+npm i file:../TFDS-Design-Skill/packages/tfds-b-end
+```
+
+### 方式 C：GitHub Packages 私有包（授权成员）
+
+先在本机或项目 `.npmrc` 配置 GitHub Packages registry 与个人 token：
+
+```ini
+@tf-designsystem:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
+```
+
+```bash
+npm i react react-dom lucide-react "@tf-designsystem/b-end@^1.0.0" --save
+```
+
+安装者需要拥有该 package 的 Read 权限，token 至少需要 `read:packages`。包页：[GitHub Packages 包页](https://github.com/orgs/TF-Designsystem/packages/npm/package/b-end)。维护者发版见仓库内 `packages/tfds-b-end/PUBLISH.md`。
+
+---
+
+## 2) 引入主题（postinstall 已自动完成，此节供手动回退参考）
+
+若 postinstall 未自动写入（例如 CSS 中尚无 `@import "tailwindcss"`），请手动在全局样式入口（如 `src/index.css`）中补充：
+
+```css
+@import "tailwindcss";
+@import "@tf-designsystem/b-end/theme.css";
+
+/* Tailwind v4 推荐 @source（与 tailwind.config content 二选一） */
+@source "./**/*.{js,jsx,ts,tsx}";
+@source "../node_modules/@tf-designsystem/b-end/**/*.{js,jsx}";
+```
+
+> `theme.css` 包含 `@theme { ... }` 的完整 token 定义（由 TFDS 的 `generateThemeCssVars()` 生成）。
+
+---
+
+## 3) Tailwind 扫描说明
+
+若你仍使用 `tailwind.config` 的 `content` 方式（Tailwind v3 / 旧项目），在配置里加入：
+
+```js
+export default {
+  content: [
+    './index.html',
+    './src/**/*.{js,jsx,ts,tsx}',
+    './node_modules/@tf-designsystem/b-end/**/*.{js,jsx}',
+  ],
+};
+```
+
+> 与 `@source` 二选一，不要同时使用。
+
+---
+
+## 4) 使用组件
+
+**选型先看随包 Skill 的 `skills/tfds/components.summary.json`，具体 props / rules / examples 以 `skills/tfds/components.index.json` 命中条目为准**（全量组件含 Avatar、NavBar、Table、Modal、ChatInput、ChatMessage 等）。
+
+头像类组件默认使用包内本地成员头像素材：`Avatar` 图片态未传 `src` 时会随机取本地成员头像；需要稳定绑定时可从包内导出的 `getTeamMemberByIndex` / `getTeamAvatarBySeed` 获取本地头像后传给 `avatarSrc`。不要为默认头像使用 pravatar / Unsplash / placeholder 外链。
+
+```jsx
+import { NavBar, Button, Table, ChatInput } from '@tf-designsystem/b-end';
+
+export default function Demo() {
+  return (
+    <div className="flex min-h-screen flex-col gap-4 p-6">
+      <NavBar platform="ola" selectedItemId="knowledge" />
+      <Button variant="primary">主操作</Button>
+      <ChatInput variant="default" />
+    </div>
+  );
+}
+```
+
+### 4.1 页面模板：IM 对话（静态片段）
+
+```jsx
+import { IMConversationPattern } from '@tf-designsystem/b-end';
+
+export default function ImDemoPage() {
+  return (
+    <div className="p-6" style={{ background: 'var(--color-blueGrey-200)' }}>
+      <IMConversationPattern />
+    </div>
+  );
+}
+```
+
+> 重要：`IMConversationPattern` 会间接依赖 `ChatBubble → Avatar/Tooltip/...` 等链路。请确保 Tailwind 扫描覆盖到包内所有 `.jsx`（`node_modules/@tf-designsystem/b-end/**/*.{js,jsx}` 通常足够）。
+
+---
+
+## 5) Cursor Agent Skill `tfds`（`/tfds` 唤起）
+
+安装包时 `postinstall` 已自动复制 Skill 到 `.cursor/skills/tfds/`。
+
+### 5.1 安装后会发生什么
+
+- 若 `.cursor/skills/tfds/` 不存在 → 自动复制包内 `skills/tfds/` 到项目根
+- 若目录已存在 → **不覆盖**，终端提示 skipped
+- 若仅有旧大写路径 `.cursor/skills/TFDS/` → 自动**重命名**为 `tfds/`
+
+### 5.2 跳过自动释放
+
+```bash
+SKIP_TFDS_CURSOR_SKILL=1 npm i @tf-designsystem/b-end
+```
+
+### 5.3 用户如何在 Cursor 里唤起（`/tfds`）
+
+1. 安装完成后，先重新打开项目或新开 Agent 会话，让 Cursor 重新扫描 `.cursor/skills/tfds/`。
+2. 在 **Agent** 聊天输入框输入 `/tfds`，从列表中选择本 Skill（描述含「【TFDS】…」）。
+3. 若列表没有 `tfds`，先确认 `.cursor/skills/tfds/SKILL.md` 存在，再重启 Cursor。
+4. 继续描述要生成的页面（例如「做一个带 IM 会话区 + 底部 ChatInput 的客服页」）。
+5. 模型必须先读取 `.cursor/skills/tfds/components.summary.json` 初选组件，再回查 `.cursor/skills/tfds/components.index.json` 命中条目写 props。
+
+### 5.4 与单组件 Skill 的关系
+
+- `tfds`（/tfds）：总控 Skill，索引里包含 **ChatInput + IMConversationPattern** 等，适合「直接生成页面」。
+- **单组件 zip**：仍可按需额外解压到 `.cursor/skills/...`，与 `tfds` 不冲突；若规则冲突，以 `tfds` + 本包 `components.index.json` 命中条目为准。
+
+### 5.5 手动安装 / 平台下载
+
+- **手动**：从本仓库复制 `packages/tfds-b-end/skills/tfds` → 对方项目 `.cursor/skills/tfds`。
+- **平台**：亦可在 TFDS Skill 中心下载 **【TFDS】** 对应 zip，解压到 `.cursor/skills/tfds/`（**目录名须为 `tfds`**，否则 `/tfds` 无法命中）。
+
+---
+
+## 5.6) 给 AI / Agent 的规范入口
+
+TFDS 规范只应在显式调用时读取，**不要**放进 `AGENTS.md`、`.trae/rules/` 等 always-on 规则。
+
+- **首选入口**：`/tfds` 或 `@tfds` → `skills/tfds/SKILL.md`
+- **设计原则**：`skills/tfds/DESIGN_PRINCIPLES.md`
+- **页面范式**：`skills/tfds/PAGE_ARCHETYPES.md`
+- **布局 Recipe**：`skills/tfds/LAYOUT_RECIPES.md`
+- **组件轻量摘要**：`skills/tfds/components.summary.json`
+- **组件权威索引**：`skills/tfds/components.index.json`
+- **交付自检 / 失败修正**：`skills/tfds/CHECKLIST.md` / `skills/tfds/COMMON_FAILURES.md`
+- **跨 IDE 兜底入口**：`AI_READ_FIRST.md`
+- **深层规则**：由 `SKILL.md` 按需引导读取 `LAYOUT_RECIPES.md`、`LAYOUT_RULES.md` 与 `GLOBAL_DESIGN_RULES.md`
+
+### 各 IDE 调用方式
+
+
+| IDE                | 调用方式                                                                                    | postinstall 是否自动配置                     |
+| ------------------ | --------------------------------------------------------------------------------------- | -------------------------------------- |
+| **Cursor**         | 重新打开项目 / 新开 Agent 会话后输入 `/tfds`；若未出现，确认 `.cursor/skills/tfds/SKILL.md` 后重启 Cursor          | ✅ `.cursor/skills/tfds/`               |
+| **Claude Code**    | 重启 Claude Code 会话后输入 `/tfds`；若不支持 Skill 热加载，直接引用 `skills/tfds/SKILL.md`                     | ✅ `.claude/skills/tfds/`               |
+| **Codex**          | 必须新开/重启 Codex 会话后输入 `/tfds`；当前会话通常不会热加载新安装的 `~/.codex/skills/tfds/`                  | ✅ `~/.codex/skills/tfds/` + `.codex/skills/tfds/` |
+| **Trae**           | 不会自动出现 `/tfds`；把 `node_modules/@tf-designsystem/b-end/skills/tfds/` 加入项目知识库（命名 `tfds`），之后 `@tfds` 引用 | ❌ 故意不写 `.trae/rules/`（避免 always-on 污染） |
+| **其他 IDE / Agent** | 不保证支持 `/tfds`；显式让 AI 先读 `AI_READ_FIRST.md`，再按其指引读取 `skills/tfds/SKILL.md`                    | —                                      |
+
+
+> 输入 `/` 后没看到 `tfds` 选项？先确认对应 Skill 文件真的存在；再「重启 IDE / 重新打开项目」让 IDE 重新扫描 Skill 目录。Codex 需要新开或重启会话后重新扫描 `~/.codex/skills`。
+
+---
+
+## 6) 硬门禁：ESLint（@tfds/eslint-config）
+
+仅靠 Skill 无法从工程上禁止 AI/人写出"漂移样式"。请让对方项目安装并使用：
+
+```bash
+npm i -D eslint @eslint/js eslint-plugin-react eslint-plugin-react-hooks globals @tfds/eslint-config
+```
+
+新增 `eslint.config.js`：
+
+```js
+import tfds from '@tfds/eslint-config/flat';
+export default [...tfds];
+```
+
+并在 CI 中执行 `npx eslint .`。
+
+规则细节见：`packages/tfds-eslint-config/README.md`。

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@tfdesign/b-end",
+  "version": "1.0.4",
+  "private": false,
+  "type": "module",
+  "description": "TFDS B-end React components + Tailwind v4 theme.css; self-contained npm install (no monorepo clone required).",
+  "keywords": [
+    "tfds",
+    "design-system",
+    "react",
+    "tailwindcss",
+    "b-end",
+    "components"
+  ],
+  "author": "duanran_ryan",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TF-Designsystem/TFDS.git",
+    "directory": "packages/tfds-b-end"
+  },
+  "bugs": {
+    "url": "https://github.com/TF-Designsystem/TFDS/issues"
+  },
+  "homepage": "https://github.com/TF-Designsystem/TFDS/tree/main/packages/tfds-b-end#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "bin": {
+    "tfds-setup": "./scripts/setup.mjs"
+  },
+  "scripts": {
+    "prepack": "node ../../scripts/generate-tfds-b-end-bundle.mjs && node ../../scripts/generate-tfds-b-end-types.mjs",
+    "postinstall": "node ./scripts/postinstall-cursor-skill.mjs"
+  },
+  "files": [
+    "src",
+    "theme.css",
+    "README.md",
+    "AI_READ_FIRST.md",
+    "LICENSE",
+    "package.json",
+    "skills",
+    "scripts"
+  ],
+  "sideEffects": [
+    "./theme.css"
+  ],
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./theme.css": "./theme.css"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18",
+    "lucide-react": ">=0.400.0"
+  }
+}