提案：基于 Devframe 提供可组合的 weapp-tailwindcss DevTools

[daguanren21]

背景与现状

weapp-tailwindcss 已经是一套跨 Vite、Webpack、Rspack、Gulp、CLI 和多端运行时的 Tailwind CSS 工具链。当前主线围绕 Tailwind CSS v4，通过真实构建器生命周期维护 CSS entry、source、candidate、类名转译、平台兼容、生成产物和 watch 关系。

现有命令行日志、构建输出、文档和测试能够验证结果，但开发者在真实项目中定位“某个 class 为什么没有生成、如何被转译、哪一步变慢、某条 CSS 为什么不兼容小程序”时，仍需要在配置、源码、产物和日志之间手工关联。

随着 weapp-vite DevTools 计划引入可组合 Hub，weapp-tailwindcss 可以作为独立 Devframe 接入该 Hub，同时保持能够挂载到官方 Vite DevTools 或其他兼容宿主。

目前的缺点和劣势

1. 构建内部状态不够可观察

candidate 确认、class 映射、CSS entry/source、缓存、watch 关系和阶段耗时主要存在于插件内部。最终产物能说明结果，但不能低成本解释过程。

2. 排障依赖日志和人工比对

缺失 class、动态 class、平台不支持的选择器/属性、source 范围错误等问题，通常需要用户手工检查配置、源码和生成 CSS，诊断链路较长。

3. 多构建器的数据表达不统一

Vite、Webpack、Rspack、Gulp 和 CLI 生命周期不同。若未来每个入口单独增加 UI 或调试输出，容易形成多套字段和行为。

4. 与上层工具无法组合

weapp-vite、组件库和 weapp-tailwindcss 的构建信息互相关联，但目前没有稳定协议让它们在同一个 DevTools 中各自展示、互相引用，同时保持 ownership 独立。

5. Agent 与浏览器 UI 缺少同一事实源

Agent 可以读取配置和产物，但缺少来自真实 generator 生命周期的结构化状态；另做一套扫描器又会与实际构建结果漂移。

接入方案

由 weapp-tailwindcss 自己发布 createWeappTailwindcssDevframe()，复用现有插件生命周期采集的结构化摘要，不让 weapp-vite 读取或推断其内部状态。

建议能力：

• Overview：版本、target、构建器、CSS entries、source 范围；
• Candidates：已确认 candidate、来源和未生成原因；
• Class Mapping：原始 class 到小程序安全 class 的映射；
• Generated CSS：按 entry/chunk 查看体积和稳定语义摘要；
• Compatibility：不支持或已转换的选择器、属性、单位和平台差异；
• Performance：generate/transform/optimize/minify 阶段耗时、缓存和 HMR 原因；
• Theme：Tailwind theme、CSS variables 和 token 摘要；
• Diagnostics：可定位到配置或源码的结构化问题。

实现约束：

• DevTools 未启用时不增加可测量的热路径成本；
• 只复用真实 generator 和构建器生命周期，不运行第二遍 Tailwind；
• 不通过后置扫描项目目录补状态；
• 大型 candidate/class map 按需 RPC 查询，不全部进入 shared state；
• 文件路径默认归一化为项目相对路径；
• 由各构建器 adapter 归一到同一只读 DevTools snapshot contract。

接入的优点

1. 显著缩短排障路径

开发者可以从 class、source、entry、映射、兼容诊断直接追到生成结果，不再主要依赖日志和产物全文搜索。

2. 与真实构建保持一致

数据来自当前 generator 和插件生命周期，而不是 DevTools 自己重新扫描，因此能够保持单一事实源。

3. 支持多个宿主

同一 Devframe 可以挂载到 weapp-vite Hub、官方 Vite DevTools 或独立调试入口，不需要分别实现 UI 协议。

4. 保持生态 ownership

weapp-tailwindcss 定义自己的数据、RPC、诊断和版本；weapp-vite 只负责聚合，不承担 Tailwind 内部兼容逻辑。

5. 为组件库提供关联能力

Varo 等基于 weapp-tailwindcss 的组件库可以引用稳定的 candidate、theme 和生成 CSS 信息，但不需要复制 Tailwind 分析逻辑。

6. 浏览器 UI 与 Agent 可复用事实源

经过筛选的 read-only query 可以按需暴露给 Agent，避免再实现一套与构建过程脱节的分析器。

接入的缺点和风险

1. 热路径开销

记录每个 candidate、映射和阶段事件可能增加内存、序列化和构建耗时。必须按 DevTools 启用状态采样或汇总，并用真实项目 benchmark 证明开销可接受。

2. 多构建器归一化成本

Vite、Webpack、Rspack、Gulp 和 CLI 不具备完全相同的生命周期。过度追求统一可能丢失构建器特有语义，过度暴露差异又会让 UI 复杂。

3. Devframe pre-1.0 与依赖体积

需要隔离 adapter boundary、精确锁版本，并考虑 Devframe 是否作为可选依赖，避免所有只需要构建能力的用户承担 DevTools runtime。

4. 大型数据集

大型项目可能产生数量很大的 candidate 和 class map。不能整包同步，必须使用 revision、过滤、分页和按需读取。

5. 源码与路径隐私

class、source、文件路径和配置可能包含项目内部信息。默认只绑定 loopback、只返回项目相对路径，并明确 Agent 暴露范围。

6. 兼容诊断存在误导风险

生成器转换、平台能力和宿主实际支持并非完全等价。诊断必须区分“已确认不支持”“已转换”“静态未知”，不能把启发式判断展示为事实。

7. 可选宿主不能抬高核心 Vite 最低版本

weapp-tailwindcss 覆盖多个 Vite major，而官方 Vite DevTools 当前仍是面向 Vite 8 的 early preview。Devframe/Vite DevTools 必须保持可选 adapter，不能因为调试 UI 抬高 weapp-tailwindcss 核心包的 Vite 最低版本或破坏既有构建器兼容范围。

建议分阶段实施

Phase 1：Vite 只读 POC

• 导出一个可选 Devframe definition；
• 接入真实 Vite 插件生命周期；
• 提供 Overview、entries/sources、阶段耗时和有界 diagnostics；
• 不增加第二遍扫描；
• benchmark DevTools 开启/关闭的构建与 HMR 开销。

Phase 2：Candidates 与 Class Mapping

• 增加 revision、过滤、分页和按需 RPC；
• 连接源码、candidate、映射和生成 CSS；
• 建立稳定的 changed-contract 测试。

Phase 3：Compatibility 与 Theme

• 接入平台转换结果和 theme/token 摘要；
• 明确 confirmed/transformed/unknown 三种诊断置信度。

Phase 4：其他构建器与 Agent 接口

• 在不丢失构建器特有语义的前提下扩展 Webpack、Rspack、Gulp 和 CLI；
• 仅将明确安全、稳定、只读的查询暴露给 Agent。

Non-goals

• 不增加第二套 Tailwind generator；
• 不扫描项目目录来猜测真实 candidate；
• 不由 weapp-vite 实现或拥有 Tailwind 面板；
• 第一阶段不自动修改用户配置；
• 第一阶段不覆盖所有构建器；
• 不把随机生成的内部 helper 名作为稳定 UI 或测试契约。

希望讨论的问题

1. Devframe runtime 应作为可选 peer、可选 dependency，还是由宿主注入？
2. Phase 1 是否只支持 Vite，以真实开销数据决定是否扩展其他构建器？
3. 哪些 generator 状态可以稳定成为公共 DevTools contract，哪些应继续保持内部实现？
4. candidate/class mapping 的默认保留量、分页和脱敏策略如何设计？
5. 与 weapp-vite Hub 组合时，插件扫描和显式注册哪一种更适合作为主路径？