css2class 2.0.0

package/docs/guide/faq.md

@@ -0,0 +1,202 @@
+# 常见问题
+
+本页按“能最快定位问题”的方式组织：先看现象，再给最短修复路径，最后给进一步的排查方向。
+
+## 配置相关
+
+### 配置冲突
+
+**问题**：出现 `CSS property conflict detected for 'font-size'` 错误
+
+**解决**：
+1. 运行配置诊断工具检查冲突：
+   ```javascript
+   const ConfigDiagnostics = require('class2css/src/utils/ConfigDiagnostics');
+   const diagnostics = new ConfigDiagnostics(eventBus, configManager);
+   const results = await diagnostics.runFullDiagnostics();
+   console.log(diagnostics.generateReport());
+   ```
+2. 检查 `cssName` 和 `atomicRules` 中是否有重复定义
+3. 使用配置验证工具自动修复：
+   ```javascript
+   const ConfigValidator = require('class2css/src/core/ConfigValidator');
+   const validator = new ConfigValidator(eventBus);
+   const result = validator.validateConfig(config);
+   if (!result.isValid) {
+     const fixed = validator.autoFix(config);
+   }
+   ```
+
+### 单位不一致
+
+**问题**：警告 `Unit inconsistency detected`
+
+**解决**：
+1. 启用 `autoDetect`：
+   ```javascript
+   system: {
+     unitStrategy: {
+       autoDetect: true,
+       propertyUnits: { /* ... */ }
+     }
+   }
+   ```
+2. 统一单位配置，确保所有相关配置使用相同的单位
+
+如果你想系统理解单位规则，建议直接阅读 [单位与转换策略](./units.md)。
+
+### 配置文件找不到
+
+**问题**：`Configuration file not found`
+
+**解决**：
+1. 确保项目根目录存在 `class2css.config.js`
+2. 或使用 `-c` 参数指定配置文件路径：
+   ```bash
+   class2css -c ./my-config.js
+   ```
+
+## 性能相关
+
+### 性能问题
+
+**问题**：CSS 生成速度慢
+
+**解决**：
+1. 启用缓存：
+   ```javascript
+   system: {
+     compression: true
+   }
+   ```
+2. 使用增量更新模式
+3. 检查文件监听范围，避免监听不必要的目录
+
+### 内存使用过高
+
+**问题**：工具占用内存过多
+
+**解决**：
+1. 检查缓存配置，适当降低缓存大小
+2. 使用增量模式，减少全量扫描频率
+3. 检查是否有大量未使用的 class 累积
+
+## 增量模式相关
+
+### 输出文件不断增长
+
+**问题**：使用增量模式后，输出文件越来越大
+
+**解决**：
+1. 这是增量模式的正常行为（只增不删）
+2. 定期重启工具，`rebuildOnStart: true` 会自动清理
+3. 手动删除输出文件后重启，会重新生成干净的文件
+
+### appendDelta 模式不生效
+
+**问题**：设置了 `uniFileWriteMode: 'appendDelta'` 但没有效果
+
+**解决**：
+1. 确保 `rebuildOnStart: true`（appendDelta 模式要求）
+2. 确保 `cssOutType: 'uniFile'`
+3. 检查输出文件是否包含 `/* CLASS2CSS:BASE */` 和 `/* CLASS2CSS:DELTA_START */` 标记
+
+## 文件监听相关
+
+### 文件变更不触发更新
+
+**问题**：修改文件后，CSS 没有更新
+
+**解决**：
+1. 检查文件是否在监听范围内（`multiFile.entry.path`，支持 `string | string[]` 多入口）
+2. 检查文件扩展名是否匹配（`multiFile.entry.fileType`）
+3. 确认监听模式已启用（未使用 `--no-watch`）
+4. 检查文件保存是否完整（某些编辑器可能分步保存）
+
+### 监听延迟
+
+**问题**：文件变更后，CSS 更新有延迟
+
+**解决**：
+1. 这是正常的防抖行为，避免频繁更新
+2. 延迟通常在 100ms 以内
+3. 如需立即更新，可以手动触发全量扫描
+
+## 输出相关
+
+### CSS 格式不正确
+
+**问题**：生成的 CSS 格式不符合预期
+
+**解决**：
+1. 检查 `system.cssFormat` 设置：
+   - `'multiLine'`：多行格式
+   - `'singleLine'`：单行格式
+   - `'compressed'`：压缩格式
+2. 检查 `system.sortClasses` 是否启用排序
+
+### 输出文件路径错误
+
+**问题**：输出文件不在预期位置
+
+**解决**：
+1. 检查 `output.path` 配置（相对路径基于配置文件所在目录）
+2. 使用绝对路径避免路径问题
+3. 使用 CLI 参数 `-o` 覆盖输出路径：
+   ```bash
+   class2css -o ./dist
+   ```
+
+## 诊断工具
+
+### 运行配置诊断
+
+```javascript
+const ConfigDiagnostics = require('class2css/src/utils/ConfigDiagnostics');
+
+const diagnostics = new ConfigDiagnostics(eventBus, configManager);
+const results = await diagnostics.runFullDiagnostics();
+console.log(diagnostics.generateReport());
+
+// 获取优化建议
+const suggestions = diagnostics.generateOptimizationSuggestions();
+console.log(suggestions);
+```
+
+### 获取优化建议
+
+诊断工具会自动生成优化建议，包括：
+- 高优先级：配置错误，必须修复
+- 中优先级：配置警告，建议修复
+- 低优先级：最佳实践建议
+
+## 其他问题
+
+### 版本兼容性
+
+**问题**：从旧版本升级后出现问题
+
+**解决**：
+1. Class2CSS 完全向后兼容旧版配置
+2. 旧版配置会自动映射到新版结构
+3. 使用兼容性适配器迁移：
+   ```javascript
+   const CompatibilityAdapter = require('class2css/src/core/CompatibilityAdapter');
+   const adapter = new CompatibilityAdapter(eventBus);
+   const adaptedConfig = adapter.adaptConfig(oldConfig);
+   ```
+
+### 获取帮助
+
+如果以上方法无法解决问题：
+
+1. 查看 [GitHub Issues](https://github.com/wnagchi/css2class/issues)
+2. 提交新的 Issue，附上：
+   - 配置文件（脱敏后）
+   - 错误信息
+   - 复现步骤
+   - 环境信息（Node 版本、操作系统等）
+
+## 下一步
+
+- 跑通一次并确认输出是否符合预期：阅读 [快速开始](./getting-started.md)

package/docs/guide/getting-started.md

@@ -0,0 +1,83 @@
+# 快速开始
+
+你将完成：安装 → 写最小配置 → 运行生成 → 在模板中使用类名。
+
+## 安装
+
+```bash
+npm install css2class --save-dev
+```
+
+:::tip 推荐
+如果你希望用一条命令直接跑起来，也可以使用 `npx class2css`（前提是已安装到项目里）。
+:::
+
+## 运行方式
+
+### 监听模式（开发）
+
+```bash
+# 启动工具（默认监听模式）
+npm run start
+
+# 开发模式（文件监听）
+npm run dev
+```
+
+### 单次构建（CI/构建）
+
+```bash
+# 构建模式（单次扫描后退出，不监听）
+npm run build
+```
+
+### 帮助与版本
+
+```bash
+npm run help
+npm run version
+```
+
+## 创建最小配置
+
+在项目根目录创建 `class2css.config.js`：
+
+```javascript
+module.exports = {
+  system: { baseUnit: 'rpx', unitConversion: 2, cssFormat: 'compressed' },
+  output: {
+    path: '../dist',
+    fileName: 'styles.wxss',
+  },
+  cssName: {
+    m: { classArr: ['margin'], unit: 'rpx' },
+    w: { classArr: ['width'], unit: 'rpx' },
+    h: { classArr: ['height'], unit: 'rpx' },
+  },
+};
+```
+
+:::tip 下一步
+把配置写“可维护”，并开启单位策略/排序/诊断等能力：建议直接阅读 [配置指南](./config.md) 并从示例配置改起。
+:::
+
+## 使用类名
+
+```html
+<view class="m-10 w-100 h-200"></view>
+```
+
+你会得到类似（取决于单位配置）：
+
+```css
+.m-10 { margin: 20rpx; }
+.w-100 { width: 200rpx; }
+.h-200 { height: 400rpx; }
+```
+
+## 下一步
+
+- 先把“语法与规则”弄清楚：阅读 [类名语法与生成规则](./concepts.md)
+- 需要知道有哪些命令：阅读 [CLI](./cli.md)
+- 想性能更稳：了解 [增量模式（只增不删）](./incremental.md)
+

package/docs/guide/important-and-static.md

@@ -0,0 +1,67 @@
+# Important 与静态类
+
+本页解释两件事：
+
+- **Important 标识**：如何用后缀把某条规则变成 `!important`
+- **静态类**：如何把一段固定 CSS 作为“预设类”注册并复用
+
+## Important 标识
+
+### 使用方式
+
+```html
+<view class="m-10-i p-20-i"></view>
+```
+
+会生成：
+
+```css
+.m-10-i { margin: 20rpx !important; }
+.p-20-i { padding: 40rpx !important; }
+```
+
+### 配置：importantFlags
+
+你可以配置允许的后缀列表：
+
+```js
+module.exports = {
+  importantFlags: {
+    suffix: ['-i', '_i'], // 例如 w-100-i / w-100_i
+  },
+};
+```
+
+:::warning 注意
+Important 只是在生成规则时追加 `!important`，它无法替代更合理的样式组织。建议只在“必须覆盖第三方样式/遗留样式”时使用。
+:::
+
+## 静态类（baseClassName）
+
+静态类适合放“不会变化的片段”，例如布局容器、常用 flex 组合等：
+
+```js
+module.exports = {
+  baseClassName: {
+    container: 'max-width: 1200rpx; margin: 0 auto;',
+    flex: 'display: flex;',
+    'flex-center': 'display: flex; justify-content: center; align-items: center;',
+  },
+};
+```
+
+使用：
+
+```html
+<view class="container flex-center"></view>
+```
+
+:::tip 经验
+静态类适合“语义化的组合”，原子类适合“可参数化的规则”。两者结合往往比单独使用更好维护。
+:::
+
+## 下一步
+
+- 类名解析全貌：阅读 [类名语法与生成规则](./concepts.md)
+- 单位策略：阅读 [单位与转换策略](./units.md)
+

package/docs/guide/incremental.md

@@ -0,0 +1,162 @@
+# 增量模式（只增不删）与 appendDelta
+
+增量模式是 Class2CSS 的高级功能，主要用于**统一文件模式（`cssOutType: 'uniFile'`）**，解决"历史输出文件累积了旧 class，不希望工具主动删除"的场景。
+
+:::tip 什么时候值得用
+当你的项目很大、写入频繁，或者输出文件会被外部工具/人工修改时，增量模式能显著降低“全量重写”的 I/O 成本，同时让输出更可控。
+:::
+
+## 适用场景
+
+- 输出文件可能被其他工具或手动编辑修改
+- 希望保留历史生成的 class，即使当前项目暂时未使用
+- 需要更快的增量更新性能（appendDelta 模式）
+
+## 配置选项
+
+### incrementalOnlyAdd
+
+启用"只增不删"模式。
+
+- **类型**：`boolean`
+- **默认值**：`false`
+- **说明**：当设置为 `true` 时，运行期新增的 class 会被保护，不会因为后续文件变化而删除。
+
+### incrementalBaseline
+
+基线来源策略。
+
+- **类型**：`string`
+- **默认值**：`'fromOutputFile'`
+- **可选值**：
+  - `'fromOutputFile'`：从输出文件中解析已存在的 class 作为基线
+
+### rebuildOnStart
+
+启动时是否重建输出文件。
+
+- **类型**：`boolean`
+- **默认值**：`true`
+- **说明**：开启后会全量扫描并覆盖写出一次，输出文件会被"清理到只包含当前项目使用的 class"，然后进入运行期只增不删。推荐开启，保证每次启动输出文件都是干净且排序好的。
+
+### unusedReportLimit
+
+未使用 class 报告的最大显示数量。
+
+- **类型**：`number`
+- **默认值**：`200`
+- **说明**：启动重建时，如果发现上一版输出文件中存在但当前项目未使用的 class，会在控制台打印。此配置限制打印的示例数量，避免输出过长。
+
+### uniFileWriteMode
+
+统一文件写入策略。
+
+- **类型**：`string`
+- **默认值**：`'rewrite'`
+- **可选值**：
+  - `'rewrite'`：统一文件写入保持兼容（防抖全量覆盖写）
+  - `'appendDelta'`：启动时写入 BASE 段 + `DELTA_START` 标记；运行期仅把新增 class 的 CSS 追加到文件末尾（更快、减少重写）
+
+**注意**：当 `uniFileWriteMode='appendDelta'` 时，`rebuildOnStart` 必须为 `true`（否则历史垃圾无法自动清理）。
+
+## 配置示例
+
+```javascript
+module.exports = {
+  multiFile: {
+    entry: {
+      // 扫描/监听入口：
+      // - string：单目录/单文件
+      // - string[]：多目录/多文件（目录与文件可混用）
+      path: "./src",
+      fileType: ["wxml", "html"],
+    },
+    output: {
+      cssOutType: "uniFile",
+      path: "./dist",
+      fileName: "styles.wxss",
+
+      // 增量"只增不删"
+      incrementalOnlyAdd: true,
+      incrementalBaseline: "fromOutputFile",
+      rebuildOnStart: true,
+      unusedReportLimit: 200,
+
+      // 统一文件写入策略
+      uniFileWriteMode: "appendDelta", // or 'rewrite'
+    },
+  },
+};
+```
+
+## appendDelta 模式
+
+`appendDelta` 模式提供了更快的增量更新性能，通过追加写入而非全量重写来减少文件 I/O。
+
+### 输出文件结构
+
+`appendDelta` 模式下输出文件会包含标记：
+
+```css
+/* CLASS2CSS:BASE */
+.w-100 { width: 200rpx; }
+.m-10 { margin: 20rpx; }
+/* ... 其他基础样式 ... */
+
+/* CLASS2CSS:DELTA_START */
+.new-class-1 { /* 新增的样式 */ }
+.new-class-2 { /* 新增的样式 */ }
+```
+
+- `/* CLASS2CSS:BASE */`：启动重建写入的基础段（压缩/排序后的全量结果）
+- `/* CLASS2CSS:DELTA_START */`：增量追加段起点（运行期新增 class 会追加到该标记之后）
+
+### 工作流程
+
+1. **启动时**：
+   - 读取旧输出文件，提取已存在的 class 作为基线
+   - 执行全量扫描，清理上一次运行累积的多余规则
+   - 生成 BASE CSS（全量生成，压缩+排序）
+   - 写入 BASE + DELTA_START 标记（覆盖写，清空旧 DELTA）
+   - 报告未使用的 class（如果存在）
+
+2. **运行期**：
+   - 文件变更时，只追加新增 class 的 CSS 到 DELTA_START 之后
+   - 新增的 class 自动加入 baseline，保证只增不删
+
+### 优势
+
+- **性能提升**：只追加新增内容，避免全量重写
+- **减少 I/O**：文件写入次数和大小显著减少
+- **保持基线**：BASE 段保持压缩和排序，DELTA 段追加新内容
+
+### 注意事项
+
+- `rebuildOnStart` 必须为 `true`，否则历史垃圾无法自动清理
+- DELTA 段会随时间增长，建议定期重建（重启工具即可）
+- 如果需要完全清理，可以手动删除输出文件后重启
+
+## 标准模式 vs 增量模式
+
+### 标准模式（incrementalOnlyAdd: false）
+
+- 文件变更时，会删除不再使用的 class
+- 输出文件始终保持"干净"，只包含当前使用的 class
+- 适合：希望输出文件始终保持最小化的场景
+
+### 增量模式（incrementalOnlyAdd: true）
+
+- 文件变更时，只新增 class，不删除已存在的 class
+- 输出文件可能随时间增长
+- 适合：需要保留历史 class 或输出文件可能被外部修改的场景
+
+## 最佳实践
+
+1. **推荐开启 rebuildOnStart**：保证每次启动输出文件都是干净且排序好的
+2. **定期检查未使用的 class**：关注启动时的 unused 报告
+3. **使用 appendDelta 提升性能**：在大型项目中，appendDelta 模式可以显著提升增量更新速度
+4. **合理设置 unusedReportLimit**：避免控制台输出过长
+
+## 下一步
+
+- 了解统一文件输出与基础配置：阅读 [配置指南](./config.md)