# TFDS（@tfdesign/b-end）— 给任何 IDE 的 AI 阅读

> **隔离说明（重要）**：本文件仅在用户**显式调用 TFDS**（输入 `/产品设计-体服平台B端-界面生成`、`@产品设计-体服平台B端-界面生成`，或直接 `@` 引用本文件 / `SKILL.md`）时才应被读取。**禁止**把本文件写进 `AGENTS.md`、`.trae/rules/` 等"始终生效"的全局规则——那样会让 TFDS 规范污染所有与 TFDS 无关的对话。

你现在在一个消费方项目中接入 `@tfdesign/b-end`（TFDS B 端组件 + 主题 + 规范索引）。你的目标不是"把页面写出来就行"，而是**生成的任何页面都必须遵循 TFDS 设计规范**，并能在对方项目里直接运行。

> **升级保护（最高优先级）**：当用户更新本地项目的 `@tfdesign/b-end` 版本时，如果发现用户项目已有页面正在使用的 TFDS 组件在新版中有规则 / Props / 示例 / 样式更新，必须先列出所有涉及用户已有项目的更新组件和具体变化范围，让用户明确判断是否要按新版样式更新已有界面。**严禁**在 npm 包更新后自动修改用户页面组件；未经用户明确确认，不得把已有页面内容迁移到新版组件样式。

适用 IDE：Cursor / Codex / Claude Code / Trae / Copilot 等任何能读文件的 AI。

---

## 📚 规范入口（只保留一个“权威指路”）

所有“怎么选模板 / 怎么拼骨架 / 怎么命中组件 / token 规则 / 交付自检 / 失败修正”等硬规则，都在 Skill 目录里。本文件不再重复规则，避免多入口漂移。

**权威入口（必读）：**

- `node_modules/@tfdesign/b-end/skills/产品设计-体服平台B端-界面生成/SKILL.md`

> 说明：安装后 `postinstall` 也会把该 Skill 复制到项目内 `.cursor/skills/产品设计-体服平台B端-界面生成/` 等目录，方便就地读取与唤起（Cursor 输入 `/产品设计-体服平台B端-界面生成`）。Codex 用户级 `~/.codex/skills/` **默认不再写入**（需全局时设 `TFDS_CODEX_GLOBAL=1` 后重新 `npm i`）。Skill 内含 **§0.0 接入门禁**：未声明/未安装 `@tfdesign/b-end` 的项目不得执行本 Skill。

---

## 1. 安装（npm 官网）

在业务项目根目录执行（空文件夹也会自动创建最小 Vite + React 项目）：

```bash
npx -y -p @tfdesign/b-end@latest tfds-b-end-setup
```

指定目标项目根（安装包不在 cwd 时）：

```bash
npx -y -p @tfdesign/b-end@latest tfds-b-end-setup -- --target "/绝对路径/.../业务项目根"
```

⚠️ 不要在 `@tfdesign/b-end` 包自身目录里执行安装；不要从 `tmp-*/` 临时目录安装。

---

## 2. 必须的工程配置（postinstall 已自动；未自动则手动）

```css
/* src/index.css */
@import "tailwindcss";
@import "@tfdesign/b-end/theme.css";

@source "./**/*.{js,jsx,ts,tsx}";
@source "../node_modules/@tfdesign/b-end/**/*.{js,jsx}";
```

---

## 3. 生成后必做：只读自检

```bash
node node_modules/@tfdesign/b-end/scripts/check-tfds-integration.mjs
node node_modules/@tfdesign/b-end/scripts/check-tfds-contract.mjs
```

第二个脚本若提示存在任意值 / 硬编码颜色 / 间距漂移，必须改到通过为止。

---

## 3.5 生成前必做：范式判定 + 计划校验（CLI）

整页生成前，**先判定页面范式并产出 `tfdsPlan`，再写 JSX**：

```bash
npx tfds archetypes              # 列出全部页面范式（按 firstAction 判定 archetype）
npx tfds spec <id>               # 取单组件/模板契约（props/rules/examples/starter，5–15KB，免读 600KB 大索引）
npx tfds spec --pattern 客服      # 模糊查找页面模板
npx tfds blocks                  # 组件未覆盖时：列出第二层自定义区块原型（KPI/信息卡/步骤/可点击磁贴…）
npx tfds spec --block kpi        # 取单个区块的 tokenRoles/交互态/合规骨架
npx tfds validate-plan plan.yaml # 校验 tfdsPlan 是否满足范式 mustUse/mustNotUse（exit≠0 即不通过）
```

`tfdsPlan` 最小结构：

```yaml
tfdsPlan:
  archetype: customer-service-workspace-frame
  pattern: CustomerServiceWorkspaceFramePattern
  components: [conversation-list, im-conversation-page, info-display-panel]
  forbidden: [ChatConversationPattern]
```

> 目的：把「页面范式选错」这一最致命错误在写代码前用机器拦下。详见 `skills/产品设计-体服平台B端-界面生成/SKILL.md` 铁律 0。

---

## 4. 强烈推荐：CI 硬门禁（`@tfdesign/b-end/eslint`）

```bash
npm i -D eslint @eslint/js eslint-plugin-react eslint-plugin-react-hooks globals @tfdesign/b-end
```

```js
// eslint.config.js
import tfds from '@tfdesign/b-end/eslint';
export default [...tfds];
```

CI / pre-commit：`npx eslint .`

---

> 想看完整硬规则、决策树、骨架代码、token 表、Checklist？
> **请打开 `skills/产品设计-体服平台B端-界面生成/SKILL.md`**（它会引导你按需加载页面范式、组件摘要和命中的组件详情）。
