feat: 增加微信 rpx 主题风险诊断并补充限制文档

[sonofmagic]

变更说明

微信小程序中，Tailwind v4 的 @theme { --spacing: 1rpx } 可以生成合法 WXSS，但运行时 calc 的尺寸可能与直接长度不同。本 PR 补充已有 DevTools 对照和中英文限制说明，并增加建议性构建 warning；warning 不代表构建失败，也不会修改 CSS 或 classSet。

• 当输出目标为 weapp 且配置/框架环境明确识别为微信时，检查 @theme / @theme inline 内所有包含 rpx 维度的自定义属性，不限于 spacing，也覆盖已扫描入口依赖图中的本地导入主题。
• 共享生成流程完成框架 PostCSS 重放和作用域组合后，区分相关变量 calc、内联 rpx calc、未检测到相关表达式及无法解析的输出。静态输出也保留配置提醒；单独 inline 不等于静态化。
• 每个 runtimeState 会话最多提示一次，watch/HMR 不刷屏；沿用 logLevel，silent/error 隐藏提示。H5/Web、其他平台和未知平台不提示。
• CSS 诊断、v4 生成样式适配和重复的自定义属性收集统一到 PostCSS 包；主包保留兼容 facade 和平台/生命周期编排。复用扫描 AST，变量合并减少中间 Map，并以架构回归约束相关模块。本次没有宣称全仓历史样式逻辑已全部迁移或端到端构建速度提升。
• 更新中英文 spacing-rpx、multi-platform、文档静态索引、中文 patch intent 和工程复盘。

文案保持事实边界：微信可能先对带单位操作数独立换算或量化再乘法，不能断言内部一定是 0.5px 后四舍五入。已有 3rpx 和偶数基数对照均表明偶数不保证准确。固定像素尺寸优先 px；需缩放时优先构建期输出最终静态 rpx，并检查最终 WXSS 和目标设备。

Refs #1214

本地验证

• 主包风险策略、真实 Tailwind legacy/graph 生成、source、cssCalc、generator pipeline、架构回归：8 文件 234 用例通过。另补迁移相关引擎回归 2 文件 63 用例通过。
• PostCSS 全包：80 文件，807 用例通过、3 个既有用例跳过。
• 两包 build 与类型声明检查通过；ESLint 通过。
• website build 成功，包含 check:docs-i18n（157 对）和 check:config-docs；中英文静态索引已重新生成。
• agents:check、release status、git diff --check 通过。

验证命令与边界见 docs/engineering/lessons/rpx-theme-warning.md。保留已有 mixed exports、模块类型和 CSS minimizer 字体警告，无未解决的本地检查失败。本次未改 demo/static fixture，也未新增真机、Skyline 或完整框架 HMR 验收；不宣称修复微信运行时算法。未等待远端 CI。

[github-actions]

PR 性能基准报告：部分结果

• Commit：821f4dd4bea8
• 生成时间：2026-09-18T17:24:20.366Z
• Benchmark：success
• Watch：未触发/无产物

总览

指标	结果
Build 稳态中位数平均变化	-0.70%
HMR 稳态 P95 平均变化	-1.49%
插件 Build 中位数平均变化	-0.05%
插件 HMR 门禁统计平均变化	+5.83%
Watch HMR p50 / p95	N/A / N/A ms
Watch RSS 峰值 / 最大增量	0.00 / 0.00 MB
Watch Heap 峰值	0.00 MB

Benchmark 项目矩阵

项目	平台	Base Build 冷/稳态(ms)	Current Build 冷/稳态(ms)	Build 变化	Base HMR median/P95(ms)	Current HMR median/P95(ms)	HMR 变化	状态
demo-mpx-tailwindcss-v4__mp-weixin	mp-weixin	16815.72 / 16968.07	16869.81 / 16887.85	+0.32%	5674.81 / 6507.59	5691.97 / 6503.56	-0.06%	ok
demo-taro-vite-react-tailwindcss-v4__mp-weixin	mp-weixin	22490.63 / 22140.43	23192.14 / 22217.75	+0.23%	4848.93 / 5353.22	4733.82 / 5222.57	-2.44%	ok
demo-taro-webpack-react-tailwindcss-v4__mp-weixin	mp-weixin	28753.36 / 28627.00	28785.05 / 28126.17	-1.73%	4759.78 / 10911.55	5126.00 / 10721.12	-1.75%	ok
demo-uni-app-vite-tailwindcss-v4__mp-weixin	mp-weixin	6129.58 / 6155.80	6027.48 / 6033.18	-1.67%	730.28 / 2530.05	711.79 / 2443.80	-3.41%	ok
demo-weapp-vite-tailwindcss-v4__mp-weixin	mp-weixin	5953.66 / 5989.98	5913.05 / 5964.14	-0.65%	8193.55 / 8194.19	8210.56 / 8210.78	+0.20%	ok

Benchmark 插件处理阶段

项目	Build Plugin base/current(ms)	变化	HMR Plugin base/current(ms)	变化
demo-mpx-tailwindcss-v4__mp-weixin	1575.00 / 1622.00	+2.98%	1556.00 / 1552.00	-0.26%
demo-taro-vite-react-tailwindcss-v4__mp-weixin	4467.00 / 4470.00	+0.07%	2323.00 / 2692.00	+15.88%
demo-taro-webpack-react-tailwindcss-v4__mp-weixin	8727.00 / 8668.00	-0.68%	7603.00 / 8462.00	+11.30%
demo-uni-app-vite-tailwindcss-v4__mp-weixin	1905.00 / 1856.00	-2.57%	725.00 / 699.00	-3.59%
demo-weapp-vite-tailwindcss-v4__mp-weixin	N/A / N/A	N/A	N/A / N/A	N/A

Benchmark 内存

项目	Build RSS base peak/steady(MB)	Build RSS current peak/steady(MB)	Peak 变化	HMR RSS base peak/steady(MB)	HMR RSS current peak/steady(MB)	Peak 变化
demo-mpx-tailwindcss-v4__mp-weixin	1231.33 / 1158.41	1229.30 / 1150.73	-0.16%	2109.23 / 2013.26	2129.18 / 2011.30	+0.95%
demo-taro-vite-react-tailwindcss-v4__mp-weixin	1745.14 / 1561.51	1696.55 / 1533.19	-2.78%	3028.72 / 2988.34	3067.23 / 3039.04	+1.27%
demo-taro-webpack-react-tailwindcss-v4__mp-weixin	1354.29 / 1296.17	1469.18 / 1286.57	+8.48%	1931.64 / 1797.16	2078.12 / 1987.35	+7.58%
demo-uni-app-vite-tailwindcss-v4__mp-weixin	760.95 / 760.95	769.27 / 769.27	+1.09%	1025.50 / 943.53	911.09 / 818.96	-11.16%
demo-weapp-vite-tailwindcss-v4__mp-weixin	578.73 / 536.59	580.47 / 540.79	+0.30%	1554.27 / 1465.37	1539.93 / 1470.84	-0.92%

Watch 明细

项目	平台	变更类型	样本数	ready(ms)	avg/p50/p95/max(ms)	插件 p50/p95(ms)	RSS peak/delta(MB)	Heap peak(MB)

门禁与诊断

• Benchmark 性能门禁：通过
• Benchmark 缺失项目：无
• Benchmark 错误：0
• Watch 解析错误：0

运行链接

• Benchmark Actions run
• E2E Watch Actions run
• 合并后的完整 artifact

统计口径

• Build/HMR 版本对照沿用现有 benchmark 的 base/current 和门禁统计。
• Watch 仅报告当前提交的真实跨平台 watcher 结果，不额外运行 base；跨 shard 总览分位数按各报告摘要聚合，项目/平台行保留原始口径。
• 未触发或缺失的场景显示为 N/A，不当作 0。