docs(skill): 优化 weapp-tailwindcss 技能流程并同步文档

sonofmagic · sonofmagic · commit 7e1cb77a24ce · 2026-02-27T15:34:04.000+08:00
diff --git a/README.md b/README.md
@@ -84,9 +84,24 @@ npx skills add sonofmagic/skills --skill weapp-tailwindcss
 - 输出可复制的安装命令、配置文件与验证步骤
 - 处理 `rpx` 任意值、`JS` 字符串 class 不生效等常见问题
 
-详细使用说明见 AI 学习中心：
+Skill 的执行流程（简版）：
+
+1. 先分流任务类型：新接入、迁移、排障、写法规范
+2. 先补齐最小上下文：框架、构建器、目标端、Tailwind 版本、是否 `pnpm@10+`
+3. 再给出可落地方案，并强制包含回滚路径
+
+Skill 输出默认包含：
+
+- 结论（框架 + Tailwind 版本 + 目标端）
+- 修改文件清单
+- 可复制配置与命令（默认 `pnpm`）
+- 验证步骤与预期结果
+- 回滚方案
+
+推荐同时阅读：
 
 - [Skill（技能系统）](https://tw.icebreaker.top/docs/ai/basics/skill)
+- [Tailwind 写法最佳实践（Skill 引用）](./skills/weapp-tailwindcss/references/tailwind-writing-best-practices.md)
 
 ## [安装与使用方式](https://tw.icebreaker.top/docs/quick-start/install)
 
diff --git a/README_en.md b/README_en.md
@@ -27,6 +27,7 @@
 - [Features](#features)
   - [Plugin Introduction](#plugin-introduction)
 - [Requirements](#requirements)
+- [AI Skill (For Users)](#ai-skill-for-users)
 - [Installation and usage](#installation-and-usage)
 - [Migrating from v1 to v2](#migrating-from-v1-to-v2)
 - [Configuration reference](#configuration-reference)
@@ -79,6 +80,31 @@ Currently, these plugins support the latest version of the `tailwindcss v3.x.x`
 
 - Node.js `^20.19.0` or `>=22.12.0` (LTS recommended)
 
+## AI Skill (For Users)
+
+If you want AI to integrate `weapp-tailwindcss` in your business project with stable best practices, install the official Skill first:
+
+```bash
+npx skills add sonofmagic/skills --skill weapp-tailwindcss
+```
+
+After installation, AI can help you with:
+
+- Fast setup for `uni-app` / `taro` / `uni-app x`
+- Copy-paste ready commands and config snippets
+- Troubleshooting for `rpx` ambiguities, JS string class issues, and `space-y/space-x` behavior
+
+The Skill workflow (short version):
+
+1. Route the request type first: setup, migration, troubleshooting, or coding-style guidance
+2. Collect minimum context: framework, bundler, targets, Tailwind version, and whether you use `pnpm@10+`
+3. Return an actionable plan with validation steps and rollback guidance
+
+Read more:
+
+- [Skill System](https://tw.icebreaker.top/docs/ai/basics/skill)
+- [Tailwind Writing Best Practices (Skill Reference)](./skills/weapp-tailwindcss/references/tailwind-writing-best-practices.md)
+
 ## [Installation and usage](https://tw.icebreaker.top/docs/quick-start/install)
 
 ## [Migrating from v1 to v2](https://tw.icebreaker.top/docs/migrations/v1)
diff --git a/skills/weapp-tailwindcss/SKILL.md b/skills/weapp-tailwindcss/SKILL.md
@@ -1,12 +1,14 @@
 ---
 name: weapp-tailwindcss
-description: 帮助用户在 uni-app、taro、原生小程序与 uni-app x 项目中集成 weapp-tailwindcss，并输出 Tailwind CSS 写法最佳实践（动态类、任意值、rpx、merge、content/@source）与排障步骤。
+description: 帮助用户在 uni-app、taro、uni-app x 与原生小程序项目中接入和排障 weapp-tailwindcss。Use when 用户提到 weapp-tailwindcss、小程序 Tailwind 不生效、rpx 任意值、JS 字符串 class、space-y/space-x、weapp-tw patch、content/@source、twMerge/cva/tv。
 ---
 
 # weapp-tailwindcss Skill
 
 用于业务项目接入 `weapp-tailwindcss`，并让 AI 稳定完成“小程序 + 多端”配置、排障与 Tailwind 写法规范落地。
 
+> 本 Skill 服务“项目使用者”场景，不是仓库内部二次开发指南。
+
 ## 适用任务
 
 - 新项目快速启用 `tailwindcss + weapp-tailwindcss`
@@ -15,68 +17,82 @@ description: 帮助用户在 uni-app、taro、原生小程序与 uni-app x 项
 - 样式不生效、`rpx` 任意值异常、`JS` 字符串 class 未转译等问题排查
 - 需要“Tailwind class 应该怎么写”的团队规范与代码评审清单
 
-## 先收集信息
+## 任务分流
+
+先判断用户当前任务类型，再进入对应流程：
+
+- 集成新项目
+- 迁移存量项目
+- 排查已有问题
+- 沉淀 Tailwind 写法规范
 
-缺少关键信息时，先补齐：
+## 信息收集最小集
+
+缺少关键信息时，先补齐后再输出方案：
 
 - 当前框架：`uni-app` / `taro` / `uni-app x` / 原生小程序 / 其他
-- 构建工具：`vite` / `webpack5` / `webpack4`
+- 构建工具：`vite` / `webpack5` / `webpack4` / 其他
 - 目标端：仅小程序，还是小程序 + `H5` / `App`
-- `tailwindcss` 主版本（v3 / v4）与包管理器（尤其是否为 `pnpm@10+`）
-- 当前诉求是“集成配置”、“问题排查”还是“写法规范沉淀”
+- `tailwindcss` 主版本（v3 / v4）与包管理器（重点确认是否 `pnpm@10+`）
+- 运行环境：`node` 版本（建议 `^20.19.0 || >=22.12.0`）
+- 当前诉求是“集成配置 / 问题排查 / 写法规范沉淀”中的哪一类
 
 ## 执行流程
 
-1. 先确定 Tailwind 主版本与扫描方式
+### 1) 基线配置（所有任务通用）
 
-- `tailwindcss@3`：使用 `tailwind.config.js` 的 `content`
-- `tailwindcss@4`：使用入口 CSS 的 `@source`
-- 确保扫描范围覆盖真实模板与脚本文件，且排除 `dist` / `unpackage` / `node_modules`
+- 先判断 Tailwind 主版本与扫描方式：
+- `tailwindcss@3` 用 `tailwind.config.js -> content`
+- `tailwindcss@4` 用入口 CSS 的 `@source`
+- 扫描范围必须覆盖真实模板与脚本文件，并排除 `dist` / `unpackage` / `node_modules`
+- 明确 `postinstall` 需要有 `weapp-tw patch`
+- 若是 `pnpm@10+`，提醒执行 `pnpm approve-builds weapp-tailwindcss`
+- 如怀疑补丁缓存或目标记录异常，可使用 `weapp-tw patch --clear-cache`
 
-2. 安装并激活 `weapp-tailwindcss`
+### 2) 按任务类型执行
 
-- 安装 `weapp-tailwindcss`
-- 在 `package.json` 添加 `postinstall: "weapp-tw patch"`
-- 若使用 `pnpm@10+`，提醒执行 `pnpm approve-builds weapp-tailwindcss`
-- 补丁失效时可引导执行 `npx weapp-tw patch --clear-cache`
+- 集成/迁移任务：
+- 优先读取 [references/integration-playbook.md](references/integration-playbook.md)
+- 按框架给出“可复制最小配置”，不要只给概念
+- 多端场景下，明确 `disabled` 条件，避免把小程序插件能力无条件作用到纯 `H5`
 
-3. 按框架注册插件并给出最小配置
+- 排障任务：
+- 优先读取 [references/troubleshooting-playbook.md](references/troubleshooting-playbook.md)
+- 先按“症状 -> 最短排查路径”输出步骤，再给修复示例
+- 明确每一步“期望现象/验证点”，避免模糊建议
 
-- `uni-app cli vue3 vite`：使用 `weapp-tailwindcss/vite`，并在 `vite.config` 内联注册 `postcss`
-- `uni-app cli vue2 webpack`：使用 `weapp-tailwindcss/webpack`（或历史项目按版本选 `webpack4`）
-- `taro webpack5`：在 `webpackChain` 注册 `UnifiedWebpackPluginV5`
-- `taro vite`：用 `weapp-tailwindcss/vite` + 内联 `postcss`，并处理 css 变量注入
-- `uni-app x`：使用 `vite` + `weapp-tailwindcss/vite`，按官方专题配置
-- 原生小程序：优先引导到官方模板（`gulp` / `webpack`）
+- 写法规范任务：
+- 读取 [references/tailwind-writing-best-practices.md](references/tailwind-writing-best-practices.md)
+- 按“推荐写法 / 反例 / 评审清单”输出
+- 需要运行时拼类时，优先 `@weapp-tailwindcss/merge` / `cva` / `variants`
+- 涉及封装重命名时，提醒 `ignoreCallExpressionIdentifiers`
 
-4. 根据任务类型补充专项指导
+### 3) 回归验证（所有任务都要给）
 
-- 如果用户要“写法最佳实践”，读取 [references/tailwind-writing-best-practices.md](references/tailwind-writing-best-practices.md) 并按其中模板输出
-- 如果用户要“运行时拼类”，优先推荐 `@weapp-tailwindcss/merge` / `cva` / `variants` 组合
-- 如果用户反馈“压缩后失效”，提醒保留关键函数名，或补充 `ignoreCallExpressionIdentifiers`
+- 先跑开发态，再跑目标端构建
+- 至少验证 3 类样式：基础工具类、任意值（含 `rpx`）、变体/伪类
+- 若 `JS/TS` 中 class 不生效，优先检查 `content/@source` 是否覆盖该文件与扩展名
+- 若 `space-y-*` / `space-x-*` 不生效，固定优先级：
+- 先改结构（子节点落到 `view/text` 或外层补 `view`）
+- 再评估 `virtualHost`
+- 最后才扩展 `cssChildCombinatorReplaceValue`（保持最小标签集合）
 
-5. 验证与回归
+## 输出格式要求
 
-- 先跑开发态编译，再跑目标端构建
-- 至少验证 3 类样式：基础工具类、任意值（含 `rpx`）、变体/伪类
-- 若 `JS/TS` 内 class 不生效，优先检查 `content/@source` 是否覆盖该文件与扩展名
-- 若 `space-y-*` / `space-x-*` 不生效，按固定优先级排查：
-  1. 先改结构（子节点改为 `view/text` 或外层包裹 `view`）
-  2. 再评估 `virtualHost`
-  3. 最后才扩展 `cssChildCombinatorReplaceValue`
+最终输出必须包含：
 
-## 输出要求
+1. 结论（适用框架、Tailwind 版本、目标端）
+2. 修改文件清单（按文件逐条列出）
+3. 可直接复制的配置片段
+4. 安装/运行命令（默认 `pnpm`）
+5. 验证步骤与预期结果
+6. 回滚方案（至少一条）
 
-输出结果需包含：
+若用户要求“规范沉淀”，额外补充：
 
-1. 修改文件清单
-2. 可直接复制的配置片段
-3. 安装/运行命令
-4. 验证步骤与预期结果
-5. 若用户要求规范沉淀，额外给出：
-   - 推荐写法（Do）
-   - 禁止写法（Don't）
-   - 最小回归检查清单（Code Review Checklist）
+- 推荐写法（Do）
+- 禁止写法（Don't）
+- 最小回归检查清单（Code Review Checklist）
 
 ## 关键约束
 
@@ -89,10 +105,17 @@ description: 帮助用户在 uni-app、taro、原生小程序与 uni-app x 项
 - 需要原样透传第三方类名时，优先使用 `weappTwIgnore`
 - 对 `space-y-*` / `space-x-*`，默认按 `view + view`（含 `text`）处理，不要假设会自动覆盖全部标签
 - `space-y-*` / `space-x-*` 的标签扩展应最小化，只加入业务确实需要的标签，避免选择器污染
+- 不要提供与仓库原则冲突的建议：`JS` 转译基于 `classNameSet` 精确命中，禁止启发式兜底转译
 - 对版本不确定时，优先给出与官方文档一致的最小可用方案，再做增量优化
 
 ## 引用资料
 
+- [references/integration-playbook.md](references/integration-playbook.md)
+  - 在“新接入/迁移”类问题中优先读取
+  - 直接复用其中的最小配置骨架与验证清单
+- [references/troubleshooting-playbook.md](references/troubleshooting-playbook.md)
+  - 在“样式不生效/行为异常”类问题中优先读取
+  - 按症状路径输出排查步骤，不跳步
 - [references/tailwind-writing-best-practices.md](references/tailwind-writing-best-practices.md)
   - 在用户要求“Tailwind 写法建议、团队规范、代码评审清单、动态类治理”时读取
   - 按“决策顺序 + 示例 + 反例 + 验证步骤”输出，不只给概念
diff --git a/skills/weapp-tailwindcss/references/integration-playbook.md b/skills/weapp-tailwindcss/references/integration-playbook.md
@@ -0,0 +1,149 @@
+# weapp-tailwindcss 集成清单（最小可用）
+
+本文件用于“新项目接入”与“老项目迁移”场景，目标是快速给出可复制、可验证的最小方案。
+
+## 1. 通用前置检查
+
+1. Node 版本建议 `^20.19.0 || >=22.12.0`
+2. 包管理器默认 `pnpm`
+3. 明确 Tailwind 主版本：`v3` 或 `v4`
+4. 明确目标端：仅小程序 or 小程序 + `H5/App`
+
+## 2. 安装与补丁
+
+```bash
+pnpm add -D tailwindcss weapp-tailwindcss postcss autoprefixer
+```
+
+`package.json` 保持：
+
+```json
+{
+  "scripts": {
+    "postinstall": "weapp-tw patch"
+  }
+}
+```
+
+`pnpm@10+` 额外执行：
+
+```bash
+pnpm approve-builds weapp-tailwindcss
+```
+
+怀疑缓存或 patch 目标记录异常时：
+
+```bash
+npx weapp-tw patch --clear-cache
+```
+
+## 3. Tailwind 扫描配置基线
+
+### Tailwind v3（`content`）
+
+```js
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: ['./src/**/*.{wxml,html,js,ts,jsx,tsx,vue}'],
+}
+```
+
+### Tailwind v4（`@source`）
+
+```css
+@import 'tailwindcss';
+@source "../src/**/*.{vue,wxml,js,ts,jsx,tsx}";
+@source not "../dist/**";
+@source not "../unpackage/**";
+```
+
+## 4. 框架最小接入骨架
+
+### uni-app cli vue3 vite
+
+```ts
+import uni from '@dcloudio/vite-plugin-uni'
+import autoprefixer from 'autoprefixer'
+import tailwindcss from 'tailwindcss'
+import { defineConfig } from 'vite'
+import { UnifiedViteWeappTailwindcssPlugin as uvtw } from 'weapp-tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [uni(), uvtw()],
+  css: {
+    postcss: {
+      plugins: [tailwindcss(), autoprefixer()],
+    },
+  },
+})
+```
+
+### taro webpack5
+
+```js
+const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack')
+
+// config/index.[jt]s
+module.exports = {
+  mini: {
+    webpackChain(chain) {
+      chain.merge({
+        plugin: {
+          install: {
+            plugin: UnifiedWebpackPluginV5,
+            args: [{ rem2rpx: true }],
+          },
+        },
+      })
+    },
+  },
+}
+```
+
+### taro vite
+
+```ts
+import type { Plugin } from 'vite'
+import tailwindcss from 'tailwindcss'
+import { UnifiedViteWeappTailwindcssPlugin as uvtw } from 'weapp-tailwindcss/vite'
+
+export default {
+  compiler: {
+    type: 'vite',
+    vitePlugins: [
+      {
+        name: 'postcss-config-loader-plugin',
+        config(config: { css?: { postcss?: { plugins?: unknown[] } } }) {
+          if (typeof config.css?.postcss === 'object') {
+            config.css?.postcss.plugins?.unshift(tailwindcss())
+          }
+        },
+      },
+      uvtw({
+        rem2rpx: true,
+        injectAdditionalCssVarScope: true,
+        disabled: process.env.TARO_ENV === 'h5',
+      }),
+    ] as Plugin[],
+  },
+}
+```
+
+### uni-app x / 原生小程序
+
+- `uni-app x` 优先走官方 `vite + weapp-tailwindcss/vite` 方案
+- 原生小程序优先引导到官方模板（`gulp` / `webpack`）后再增量改动
+
+## 5. 多端项目策略
+
+1. 小程序优先时再开启 `rem2rpx/px2rpx`
+2. 纯 `H5` 构建禁用小程序转译插件
+3. 样式入口统一管理，避免端间配置漂移
+
+## 6. 最小验证清单
+
+1. 启动开发构建并确认无报错
+2. 验证基础工具类（如 `flex`, `px-4`）
+3. 验证任意值（如 `w-[22rpx]`, `text-[length:22rpx]`）
+4. 验证变体/伪类（如 `hover:`, `after:`）
+5. 产物检查：确认 `weapp-tw patch` 已执行过
diff --git a/skills/weapp-tailwindcss/references/tailwind-writing-best-practices.md b/skills/weapp-tailwindcss/references/tailwind-writing-best-practices.md
@@ -17,6 +17,7 @@
 - 必须动态时，使用“完整字面量枚举”，不要拼半截 token。
 - 动态组合统一经过 `cn`（`clsx + twMerge`）或 `cva/tv`。
 - 小程序项目默认保留 `postinstall: "weapp-tw patch"`。
+- `JS` 转译遵循 `classNameSet` 精确命中：不要依赖“看起来像 Tailwind”的启发式字符串拼接。
 
 ## 3. 推荐写法与反例
 
diff --git a/skills/weapp-tailwindcss/references/troubleshooting-playbook.md b/skills/weapp-tailwindcss/references/troubleshooting-playbook.md
diff --git a/website/docs/ai/basics/skill.md b/website/docs/ai/basics/skill.md
