weapp-vite 7.9.0 → 7.10.0

package/skills/weapp-vite-best-practices/references/config-playbook.md

@@ -0,0 +1,51 @@
+# weapp-vite Config Playbook
+
+## 最小起步
+
+```ts
+import { defineConfig } from 'weapp-vite/config'
+
+export default defineConfig({
+  weapp: {
+    srcRoot: 'src',
+    autoRoutes: true,
+  },
+})
+```
+
+## 常见增长路径
+
+- 组件规模上来后再加 `autoImportComponents.globs/resolvers`
+- 目录边界稳定后再加 `subPackages`
+- 观察真实输出重复后再调 `chunks` 策略
+- 需要局部验证时再加 `buildScope` 或 `--scope`，并检查主包/分包路由归属
+- 多平台项目始终显式选择单个 `-p <platform>`，project config 放在稳定平台目录
+
+## 分包决策提示
+
+- 默认先用普通分包 + 默认 chunks
+- 重复体积明显时考虑 `sharedStrategy: 'hoist'`
+- 冷启动优先时保留 `duplicate`
+
+## CI 提示
+
+- build 与 IDE upload 分开
+- `dist` 根目录与 `project.config.json` 保持一致
+- 自动化场景优先非交互 CLI 参数
+- sourcemap 验证要覆盖构建后 npm、平台 API 和 chunk 重写，不能只看 Vite 初始 map
+- React 项目只在这里配置 `weapp.react`；render mode、Compiler 和 bridge 转交 React skill
+
+## 最终模板转换
+
+- 精确删除使用 `weapp.wxml.remove.attr: [{ tag: 'view', name: 'data-testid' }]`；修改、属性改名、标签转换使用 `weapp.wxml.transform(code, ctx)`，支持异步及函数数组。
+- 推荐 `return ctx.edit(code, node => { if (node.tagName === 'view') node.removeAttribute('data-testid') })`；匹配最终静态标签名，Vue HTML 映射发生在此前。
+- 字符串属性值是字面量，数字与布尔值保留类型；动态值写 `{ expression: 'value' }`，无值属性用 `setBooleanAttribute`。读取 `rawValue` 不代表运行时值。
+- 编辑工具保护事件、平台指令、框架元数据和结构标签；原始字符串返回提供完整控制。替换自定义组件时必须自行注册，不自动改组件依赖。
+- 子树编辑使用 `node.children`（直接子标签）和 `await node.walk(visitor)`（全部后代，不含自身）。手动 walk 不消费外层遍历；外层当前节点调用 `skipChildren()` 可避免再次处理。内层 skip 只影响内层遍历。父节点与 `validate` 中的 `node.children` 始终只读；删除父节点使全部后代句柄失效，不并发遍历或跨会话保存句柄。
+- `transform` 在 `remove` 前执行，后续 Tailwind/compiler-plugin 仍能修改输出。显式注册外部依赖 `ctx.addWatchFile('rules.json')`，变化触发完整模板重建；不要依赖跨文件回调顺序或全局计数。
+
+- 最终产物约束使用 `weapp.wxml.validate(code, ctx)`，支持同步／异步和顺序数组；它在 transform/remove 和框架输出插件之后、HMR 比较及发布之前执行，不修改源码。
+- 使用 `await ctx.walk(node => { ... })` 观察只读节点，以 `ctx.report({ severity: 'warning' | 'error', message, code?, location? })` 报告结果；warning 允许发布，error 汇总后阻止输出。回调只能返回 undefined，不能返回模板字符串或 null。
+- 校验位置是最终模板位置，`rawValue` 是原始绑定内容；不要把动态绑定当运行时值。外部规则读取前登记 `addWatchFile`，转换与校验共享监听但分别维护依赖；独立分包校验不在主包重复执行。
+
+自动路由仅选择 Vue/TSX 入口时可设置 `autoRoutes: { extensions: ['vue', 'tsx'] }`。`include` 仍匹配无扩展名路径；空扩展名列表保留默认行为。所选页面的配套资源及显式业务导入仍参与构建。

package/skills/weapp-vite-best-practices/references/debug-playbook.md

@@ -0,0 +1,47 @@
+# weapp-vite Debug Playbook
+
+## 症状 -> 第一检查点
+
+### 页面或路由缺失
+
+- 检查 `srcRoot`
+- 检查页面目录结构
+- 检查 `autoRoutes` 与生成的 route typings
+
+### 组件未解析
+
+- 检查组件目标与路径大小写
+- 检查 `autoImportComponents.globs/resolvers`
+
+### 构建输出位置不对
+
+- 检查 `project.config.json`
+- 检查 `build.outDir`
+- 检查小程序输出根目录假设
+
+### 支付宝或抖音原生文件缺失
+
+- 确认使用了正确的 `-p alipay|tt` 和平台描述符
+- 检查 `.axml/.acss`、`.ttml/.ttss` 与 script module 扩展名
+- 不复制或重命名成微信扩展名掩盖扫描问题
+
+### scoped build 路由漂移
+
+- 检查 `weapp.buildScope` / `--scope` 与 autoRoutes 的分包 root
+- 确认目标分包页面没有被加入主包或重复构建
+
+### 分包 chunk 异常
+
+- 确认 `sharedStrategy` 与 overrides
+- 先看 analyze 输出，再决定是否加更多 override
+
+### HMR 慢或热更新不稳定
+
+- 先看 `weapp.hmr.sharedChunks` 与 `touchAppWxss`
+- 临时设置 `weapp.hmr.logLevel: 'concise' | 'verbose'`
+- 需要结构化复盘时打开 `weapp.hmr.profileJson`
+
+### sourcemap 指向旧代码
+
+- 检查 CLI `--sourcemap` 是否透传
+- 检查 npm 本地化、平台 API、shared chunk 与入口注入重写是否组合旧 map

package/skills/weapp-vite-best-practices/references/ide-command-playbook.md

@@ -0,0 +1,26 @@
+# IDE Command Playbook
+
+## 命令所有权
+
+1. 通常由 `weapp-vite` 原生命令先执行；旧顶层微信 IDE `upload` / `help upload` 是兼容例外，具体参数边界见 `cli-dispatch-playbook.md`。
+2. 只有命中 `weapp-ide-cli` catalog 的顶层命令才透传。
+3. 未知命令不要盲目 passthrough。
+
+## 重点命令与边界
+
+- `preview`
+- `upload`
+- `config`
+- `screenshot`
+- `compare`
+- `ide logs`
+- `close`
+- `mcp init|print|doctor`
+
+## 契约要点
+
+- `screenshot` / `compare` 的文件输出路径与 `--json` 结构保持稳定。
+- `compare` 失败时返回非零退出码。
+- `ide logs` 的持续监听与退出行为要可预测。
+- `mcp init|print|doctor` 的客户端名称、transport 与写入确认行为要和 CLI 实现一致。
+- `wv` 与 `weapp-vite` 示例口径保持一致。

package/skills/weapp-vite-best-practices/references/ide-i18n-config-playbook.md

@@ -0,0 +1,29 @@
+# IDE I18n And Config Playbook
+
+## 语言策略
+
+- 默认中文：`zh`
+- 英文兜底：`en`
+- 支持 `--lang` 临时覆盖
+- 支持配置文件持久化
+
+## 常见配置字段
+
+- `cliPath`
+- `locale`
+
+## `config` 子命令稳定面
+
+- `config show`
+- `config get <key>`
+- `config set <key> <value>`
+- `config unset <key>`
+- `config doctor`
+- `config export [path]`
+- `config import <path>`
+
+## 校验
+
+- locale 严格限定在 `zh|en`
+- 导入 payload 严格校验结构
+- 用户提示保持中文优先

package/skills/weapp-vite-best-practices/references/native-ast-performance-checklist.md

@@ -0,0 +1,7 @@
+# Native AST Performance Checklist
+
+本表用于项目已接入自定义构建插件或评估 native AST 扩展时的设计判断，不要求普通消费项目修改构建器源码、安装 native 扩展或运行框架仓库 benchmark。常规性能排障先用项目相同输入的 build/HMR profile；没有扩展需求时保持现有构建路径。
+
+- 一次调用传入完整源码、配置和分析任务，返回结构化摘要；不要逐节点往返 JS/Rust。
+- native fast path 必须显式启用、可选依赖，加载、解析或运行失败时回退现有 JS/Babel/Oxc/Vue compiler 路径。
+- 新增覆盖同时补 correctness 对齐测试和真实 HMR/build profile；没有 profile 不扩大迁移范围。

package/skills/weapp-vite-best-practices/references/plugin-build-playbook.md

@@ -0,0 +1,11 @@
+# Plugin Build Playbook
+
+## 配置
+
+设置 `weapp.pluginRoot` 指向包含 `plugin.json` 的插件源码目录。host 源码仍由 `srcRoot` 管理。
+
+## 验证
+
+- 结构或入口变化后同时检查 `dist/` 和插件 `dist-plugin/`。
+- plugin AppID/provider 变化时同步 project config 与插件声明。
+- 共享模块可以从 host 和 plugin 入口引用，但必须分别验证输出路径。

package/skills/weapp-vite-best-practices/references/stateful-hmr-playbook.md

@@ -0,0 +1,17 @@
+# Stateful HMR Playbook
+
+## 前提
+
+- 只支持微信小程序 WebView；确认 `DevTools` 服务端口、热重载和 `setting.compileHotReLoad: true`。
+- 先检查实际 bundle 中的应用/页面 JSON 是否使用 Skyline；命中时工具会关闭项目私有配置中的热重载并强制降级 classic。
+- 显式 `weapp.hmr.runtime` 通常优先；Skyline 兼容降级会覆盖显式 stateful，其他场景未配置时核对工作区 `compileHotReLoad` 自动选择结果。
+- 排障时先用 `classic` 建立行为基线，再显式启用 `stateful-experimental`。
+
+## 判断
+
+- JS/Vue 安全更新：允许在现有 Page、Component 或 wevu 实例上替换并恢复状态。
+- CSS、资源、JSON/配置、模块边界不兼容、补丁积压或执行失败：接受完整构建，并验证当前 route/query 恢复。
+
+## 验收
+
+用真实 runtime 检查状态保留、路由恢复和失败回退；不要只看 dev server 日志。

package/skills/weapp-vite-best-practices/references/web-runtime-compatibility.md

@@ -0,0 +1,39 @@
+# Web Runtime Compatibility
+
+- Web runtime 用来验证跨平台渲染和 Web API 适配，不等价于微信 DevTools 或真机。
+- 项目根目录准备引用 `/@weapp-vite/web/entry` 的 `index.html`，并统一提供 `dev:web: wv dev -p web --host` 与 `build:web: wv build -p web`；`web` 是规范平台名，`h5` 仅作为向后兼容别名保留。
+- 使用消费项目自己的 `dev:web` / `build:web` scripts；若无脚本，已安装 `weapp-vite` 时可用本地 CLI `pnpm exec wv dev -p web --host` / `pnpm exec wv build -p web`。`/@weapp-vite/web/entry` 由构建链解析，不要求业务为此重复安装传递依赖；若业务直接从 `@weapp-vite/web` 导入 API，再显式声明该包。构建后用项目已有浏览器测试或手动检查宿主 API、首屏页面和当前路由，不要求框架仓库的 E2E 矩阵。
+- Web 入口必须先求值 App，再求值页面和组件；依赖 `defineAppSetup()`、`createRouter()`、`provide()` 或 `getApp()` 的首屏代码都以这一顺序为前提。
+- 默认 `runtime.viewport.mode` 为 `mini-program`：移动宽度下铺满，600px 以上使用 375px 居中容器；旧全宽行为显式使用 `responsive`。
+- `runtime.seo` 会在页面栈切换后同步 `document.title`、description 和 canonical；标题默认取页面 `navigationBarTitleText`，`titleTemplate` 用 `%s` 表示页面标题，`enabled: false` 可关闭。
+- `runtime.resourceHints.links` 只在浏览器 Head 中去重注入 `preconnect`、`dns-prefetch`、`prefetch` 和 `preload`，不会改变小程序产物，也不等同于 SSR。
+- `rpx` 按设备容器宽度计算。排查桌面端比例问题时先检查 `#app` 实际宽度和 `--rpx`，不要直接用 `window.innerWidth` 推断。
+- `view`、`text`、`image`、`button`、`input`、`scroll-view`、`form`、`label`、`textarea`、checkbox/radio group、`switch`、`picker`、`picker-view`、`picker-view-column`、`slider`、`icon`、`progress`、`rich-text`、`navigator`、`swiper` / `swiper-item` 会编译成 `weapp-*` 运行时标签；编写浏览器断言时不要继续假设它们是 `div`、`span`、`img` 或原生表单元素。
+- 表单提交只收集带 `name` 且未禁用的控件；checkbox group 返回数组、radio group 返回单值、switch 返回布尔值。验证 reset 时同时检查控件状态和页面提交结果，不要只检查 DOM attribute。
+- 控件属性同步不会发送用户 `change` 事件。浏览器交互断言应操作 runtime 标签 shadow root 内的原生控件，再校验外层收到的微信事件 `detail`。
+- picker 的动态 `range` / `value` 和 picker-view 的 `value` 通过 property 传递，断言时应检查对象数组没有被字符串化。region 模式只提供文本近似，不应把空 `code` / `postcode` 当作真实行政区数据。
+- picker-view 的受控 value 要在子列 slot 就绪后验证，避免把连接早期的空列 clamp 结果当成最终状态；slider 行为同时覆盖 `changing` 与 `change`。
+- `icon` 断言应覆盖九种内建类型以及 size / color 更新。`progress.duration` 按进度每增长 1% 的毫秒数计算，active 动画每次只发送一个 `activeend`，颜色和 show-info 等更新不应重复触发；视觉截图前要等待动画完成。
+- `rich-text.nodes` 是 property 绑定，节点数组不能被字符串化。字符串与数组都应经过同一安全树；测试需覆盖脚本、`on*` 属性、`javascript:` / 非图片 data URL 和危险 CSS 被过滤，避免直接依赖 `innerHTML` 注入。
+- `navigator` 的声明式跳转与 `wx.navigateTo` 等命令式 API 共用页面栈。验证时同时检查目标 route、query 和 navigateBack 后的页面恢复；`target="miniProgram"` 还要覆盖 success/fail/complete。
+- `navigateTo` 后原页面保持存活并触发 `onHide`；`navigateBack` 恢复同一实例、数据、`onShow` 和 `#app` 滚动位置，不会重跑 `onLoad`。排查返回状态丢失时，同时检查 `getCurrentPages()` 全栈、页面 host 的 `hidden` 状态和容器 `scrollTop`。
+- `App.onLaunch` / `App.onShow` 必须先于首个页面挂载；浏览器 `visibilitychange` 会去重触发 `App.onHide` / `App.onShow`。验证重新进入前台时，分别检查 `getLaunchOptionsSync()` 保留初始入口、`getEnterOptionsSync()` 更新为当前页面。
+- 页面滚动由当前栈项持续持有。用户滚动和 `pageScrollTo` 都应同步到对应页面；history/hash 模式会使用 manual scroll restoration，排查滚动跳变时不要再叠加 `window` 级恢复逻辑。
+- `redirectTo` 只卸载当前页，`reLaunch` 从栈顶开始卸载所有旧页面。路由目标无效或首页执行 `navigateBack` 时，Promise 应 reject，`fail` / `complete` 应收到对应 `errMsg`。
+- 标准 `app.json.tabBar` 会生成受 `#app` 设备视口约束的 Web App Shell。`switchTab` 只能进入 tab 路由，会卸载非 tab 页面并缓存其他 tab 实例；切回时验证 `onLoad` 不重复、`onShow` 正常递增和 `getCurrentPages()` 只返回当前 tab 栈。
+- `showTabBar` / `hideTabBar` 会同步页面 inset；`setTabBarItem`、`setTabBarStyle`、badge 与 red-dot API 会更新 shell。`tabBar.custom: true` 只保留路由语义，不会自动渲染业务自定义组件。
+- `swiper` 的 current、autoplay、pointer drag 和事件 source 由容器统一管理。视觉用例保持 autoplay 关闭；行为用例应分别验证 programmatic、touch、autoplay，并确认断开 DOM 时计时器停止、重新连接后恢复。
+- WXSS 的 `page` 映射到页面 Shadow DOM 的 `:host`，原生组件类型选择器同步映射到 `weapp-*`；class、attribute、pseudo 与组合结构应保持稳定。
+- 视觉对比使用消费项目自己保存的基线与截图流程，只有明确授权时才更新基线。微信 DevTools 截图只包含页面 WebView，需记录实际 viewport；宿主原生 tabBar 不进入 PNG，Web shell 另以浏览器尺寸、边界、选中态和 API 行为验收。
+- URL、URLSearchParams、fetch/request globals 需要在目标 runtime 做最小验证；浏览器通过不代表宿主通过。
+- 第三方请求客户端若只在 DevTools 失败，先缩小到宿主构造器兼容问题，再决定 skip、polyfill 或业务修复。
+
+## 小程序 Web API 注入与 SSE
+
+- `weapp.appPrelude.webRuntime` 为小程序注入兼容对象，与浏览器预览的 `weapp.web` 分开。先读 `node_modules/weapp-vite/dist/docs/weapp-config.md`，完整配置见 [Web Runtime 全局对象注入配置](https://vite.weapp.dev/config/web-runtime-globals.html)。
+- Fetch 响应流通过 `webRuntime.networkDefaults.request.enableChunked: true` 开启；普通缓冲 Fetch 继续可用。使用标准 `Response.body`、`pipeThrough()`、`getReader()` 和 `AbortSignal`，业务不直接管理 `onChunkReceived`。
+- `ReadableStream`、`WritableStream`、`TransformStream` 作为一致的一组安装；`TextDecoderStream` 补齐 UTF-8 跨块状态。构建器识别 `eventsource-parser/stream`，其模块初始化会继承 `TransformStream`，必须核对最终 prelude 和 chunk 局部绑定在依赖求值前已就绪。
+- `EventSource` 自动开启分块，支持标准 GET、事件监听、`Last-Event-ID`、`retry` 和重连。POST、自定义鉴权头使用 Fetch，Fetch 不自动重试。若选择 `wevu/fetch`，需显式安装 `wevu`；若直接使用 `@wevu/web-apis/streams` 或 `/eventsource`，需显式安装 `@wevu/web-apis`，不要依赖传递依赖可导入。
+- 微信流式请求要求 chunk 监听和响应结束前的真实状态码。缺失时 Fetch 以 `NotSupportedError` 失败，EventSource 触发 error 并关闭；不得假定 HTTP 200 或静默退回缓冲，也不能用最终 `success.statusCode` 冒充早期元数据。
+- 首版不模拟浏览器 Cookie/CORS，不支持 `EventSource` 的 `withCredentials: true`、流式请求上传或 `Blob.stream()`。JS 流消费不等于网络级反压；不静默丢块，慢消费者和 clone 分支可能增加内存。域名白名单、TLS、超时、后台限制仍属宿主边界。
+- 正路径必须证明服务端仍保持响应打开时页面已显示首条消息，并覆盖 POST 鉴权、断线重连和卸载清理。headless、真实 Stable 与真机结果分开记录；缺失状态码的拒绝路径通过不能写成 SSE 正路径通过。示例见 [复用 Web SSE 写法](https://vite.weapp.dev/guide/web-runtime-globals.html#复用-web-sse-写法)。

package/skills/weapp-vite-vue-sfc-best-practices/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: weapp-vite-vue-sfc-best-practices
+description: 面向使用 weapp-vite 的小程序项目的 Vue SFC 实践手册，覆盖 script setup、纯模板 SFC、JSON 宏、`definePageMeta`/layout、`defineModel`、`usingComponents`、内置 i18n Behavior、JSX/TSX script block、模板指令兼容、多平台 SFC、`.weapp-vite` 类型支持文件与受管 `prepare` 工作流。
+---
+
+# weapp-vite-vue-sfc-best-practices
+
+## 用途
+
+在小程序项目里用 Vue SFC 写出“编译可预测、运行时可验证、类型可跟上”的页面和组件。
+
+## 包与资料边界
+
+- 本 skill 随 `weapp-vite` 提供，负责 SFC 编译、宏、模板和类型支持；本地资料为 `node_modules/weapp-vite/dist/docs/vue-sfc.md`，本文 `references/` 相对本 skill。无需框架源码仓库或其他 skill。
+- 纯模板 SFC 可先检查编译与声明；使用 `<script setup>` 中的响应式、生命周期、事件、store、router、`useCssModule()` 等 Wevu runtime API 时，项目须显式安装 `wevu`，这些运行时能力不由 `weapp-vite` 包替代。
+- React 项目需要显式安装 `@weapp-vite/react` 及其 peer dependencies；Wot UI、uview-plus、原生 UI 库和 Web runtime 只在相应工作流中安装。其他 skill 仅在已安装时作为可选分流。
+- 验证先读消费项目的 `package.json`，使用其已有 typecheck、build 和相关测试 scripts；CLI 示例中的 `wv` 指本地 `weapp-vite`（可用 `pnpm exec wv`）。不要求框架包构建、仓库 E2E 或发布流程。
+
+## 何时使用
+
+- 用户问 `.vue` 文件应该怎么写。
+- 用户问 JSON 宏和 `<json>` 怎么选。
+- 用户问 `definePageMeta` / layout 怎么配。
+- 用户遇到模板兼容或编译错误。
+- 用户遇到 `.weapp-vite` 类型输出、组件声明或 route type 漂移。
+- 用户要在微信小程序与 Web 中使用 Wot UI、uview-plus 等 uni-app Vue SFC 组件库。
+- 用户要使用纯模板 `.vue`、`<script lang="jsx">` / `<script setup lang="tsx">`，或处理多平台 SFC 编译差异。
+
+## 不适用场景
+
+本 skill 聚焦 SFC 编写和编译期兼容。
+
+- 项目级构建配置：使用 `weapp-vite-best-practices`。
+- `wevu` 生命周期和 store：使用 `wevu-best-practices`。
+- 迁移规划：使用 `native-to-weapp-vite-wevu-migration`。
+- 项目启用 `weapp.react` 后的 React JSX/TSX：使用 `weapp-vite-react-best-practices`。
+
+## 核心流程
+
+1. 先确定只读诊断或实施范围，读取目标 SFC、同文件 JSON、组件注册、相关配置与项目 scripts；记录已安装 `weapp-vite`、实际使用的 runtime/组件库、Node、包管理器和构建工具版本。选定单一平台；需要运行观察时再记录实际 IDE、基础库与 renderer，缺失项不猜测。按问题阶段进入：
+   - 模板/JSON/宏：先确认 App/Page/Component 角色及现有写法，按 `references/macro-config-checklist.md`、`references/template-compat-matrix.md` 修改；纯模板不因将来可能用 `ref` 就安装 runtime。检查同文件配置生成的 JSON、目标模板与路由归属。
+   - 组件/插槽/多平台：带上真实 `usingComponents`、resolver 结果和目标配置，对照模板兼容规则；依赖未安装或目标能力未确认时停止对应接入。检查注册路径、slot 产物，再在该目标观察内容、事件与样式，不由其他平台外推。
+   - 类型/prepare/HMR：带上 `.weapp-vite`、Volar/TypeScript 版本及诊断，进入 `references/tooling-and-hmr-matrix.md`；检查 prepare 声明和已有 typecheck，JSON-only 与完整 SFC 更新分开观察，声明成功不代表页面更新。
+   - 响应式/生命周期/事件：先核对实际 `wevu` 依赖与同步 setup；缺 runtime 仍可依据源码和可读公开资料作静态诊断，注明 API 版本限制，只停止需要该依赖的执行与宿主验证。不要为只读诊断安装依赖，也不把编译器当作 runtime。
+2. 默认使用 `<script setup lang="ts">`。
+   - 纯模板 SFC 允许没有 script block；`wv prepare` 必须按 SFC 模板扫描，不能把模板文本误交给 JSX parser。
+   - Wevu JSX/TSX 与 SFC 内 JSX/TSX 归 Wevu compiler；项目级 `weapp.react` 启用后，独立 `.jsx/.tsx` 归 React owner。
+3. 有脚本时 JSON 优先走宏：`defineAppJson`、`definePageJson`、`defineComponentJson`；页面元信息走 `definePageMeta`。已有纯模板 SFC 可保留同文件 `<json>`，不只为配置强加 runtime 或脚本。
+4. 套用模板兼容规则：
+   - `v-model` 只能作用于可赋值左值
+   - 不要假设 Web Vue 的所有模板特性都可用
+   - `usingComponents` 走 JSON 宏 / 自动导入，不走 Web Vue 注册思路
+   - 第三方小程序 UI 库（如 TDesign Mini Program、Vant Weapp）文档中的 `TNode`、`slot`、自定义内容通常是小程序原生 slot 或属性渲染，不要默认按 Vue scoped slot 处理
+   - 第三方 uni-app Vue SFC 组件库与原生小程序 UI 库不是同一路径：前者需要 resolver 返回 `sourceType: 'wevu-sfc'` / 真实 `resolvedId`，并通过 `weapp.uniApp.include` 显式允许依赖转换
+   - 只有存在明确 slot props（如 `<template #item="{ item }">`）或显式增强作用域插槽场景时，才应生成 `generic:scoped-slots-*`
+   - 转发 `<slot />` 到子组件具名插槽时不要生成或建议 `<block slot="..."><slot /></block>`；真实 DevTools 运行时会丢失转发内容。微信平台默认使用内部 `virtualHost` wrapper，需要回到旧版真实节点行为时配置 `weapp.vue.template.slotFallbackWrapperStrategy: 'view'`，需要自定义时优先用组件内静态属性 `slot-wrapper="cover-view"`、`slot-wrapper-footer="view"`、`slot-wrapper-class="..."`、`slot-wrapper-footer-class="..."` 或项目配置 `weapp.vue.template.slotFallbackWrapper`；全局规则里 `component` 匹配模板标签名，`componentName` 匹配子组件静态 `defineOptions({ name })`
+   - 自定义 slot wrapper 必须能承载实际子内容；例如 `text` 不适合包裹 `<view>`，`block` 会被编译器回退为 `view`
+   - Vue/Wevu 组件标签输出保持 kebab-case；可选链与空值合并必须转换成目标小程序模板可执行的表达式
+   - 启用 `weapp.i18n` 时，从 `weapp-vite/i18n` 导入构建实例 `i18n`，并用 `defineOptions({ behaviors: [i18n.behavior] })` 显式接入；逻辑层通过 `i18n.global` 访问翻译和 locale，模板可直接调用配置的 `t(...)`
+   - i18n 只放行配置函数的直接模板调用；`t(resolveKey())` 或其他嵌套调用仍回退逻辑线程，不要依赖任意函数在 WXML 中执行
+   - 微信目标支持 scoped CSS、默认/命名 CSS Modules、同步 setup 中的 `useCssModule()` 与 CSS `v-bind()`；CSS vars 会合并到每个模板根节点已有 style
+   - `:deep()` / `:global()` / `:slotted()` 只使用可映射到小程序选择器的形式；其他平台在对应 IDE/真机验证前按实验性处理
+5. 若 `typed-router.d.ts`、`typed-components.d.ts`、`components.d.ts` 漂移，先跑 `wv prepare`。
+6. 项目已有 `AGENTS.md` 时遵循它；版本相关 SFC 写法对照 `node_modules/weapp-vite/dist/docs/vue-sfc.md`，不把项目根 `dist/docs` 或框架仓库文件当作前提。
+7. 多平台 SFC 每次只验证一个 `-p <platform>` 目标；Web runtime 用于浏览器兼容联调，不替代目标小程序 IDE/真机。
+
+## 工具链与热更新边界
+
+- Volar 类型问题先检查 `.weapp-vite/tsconfig.app.json`、solution references 和 `vueCompilerOptions.plugins`；不要用根目录隐式包含替代受管配置。
+- `skipTemplateCodegen` 会让模板绑定和 WXS 类型离开模板上下文，出现“属性不存在”时先排除该配置。
+- 只有 JSON 宏或配置发生变化时才依赖 JSON-only HMR；行为、模板和运行时变化仍按完整 SFC 编译链验证。
+- `defineConfig` 推荐从 `weapp-vite/config` 导入，以保留 `weapp.*` 的上下文类型和 Hover 文档。
+
+详细矩阵见 `references/tooling-and-hmr-matrix.md`。
+
+## 约束
+
+- 不要在一个 SFC 里混多套 JSON 宏。
+- 不要把小程序组件注册当成 Web Vue 组件注册。
+- 不要只配置 Wot UI 或 uview-plus resolver 而遗漏 `weapp.uniApp.include`，也不要把 npm 依赖自动加入转换范围。使用这些库须显式安装对应依赖；uview-plus 应调用 `mount$u()` 并同步 `$u`，不要走 Web 全局组件注册流程。
+- 不要把 `t-*`、`van-*` 等 kebab-case 第三方原生组件的普通默认插槽误判为增强作用域插槽。
+- 不要忽略 `prepare` 和 `.weapp-vite` 产物。
+- 不要在修 SFC 语法时顺手做无关运行时重构。
+- 不要把内置 i18n 当作 ICU/MessageFormat runtime；v1 只支持简单 key 查询和 `{name}` / `{user.name}` 插值。
+
+## 输出
+
+只输出本次问题阶段、实际版本/平台、SFC 级改动或只读建议、相关模板限制与最小检查。先确认 scripts/工具存在，再给出适合项目包管理器的命令；没有测试 script 就列覆盖缺口，不编造测试命令。未涉及 runtime、组件库或 HMR 时不展开其接入。
+
+每项结论用短记录关联：`对象/版本 → 实际命令或动作 → 观察/产物 → 方法、结果、限制`；同一结论可并列记录多种方法，各自结果互不覆盖，建议与已执行分开。缺前提仅阻塞依赖它的操作/验证，继续可达的只读诊断：
+- 自动验证 `passed`：实际命令/断言通过，仅证明所检查的模板、JSON、类型或运行行为。
+- AI 评估 `passed`：列评估者、判据和材料，不称自动验证；只有实际隔离过才可称独立。
+- 人工确认 `passed`：确认须针对该结果及版本，不能用计划获批代替结果/示例获批。
+- 未验证 `not-run`：未运行或前提不足，写明原因；已执行失败按实际方法保留 `failed` 与证据。构建、声明和 callback 不单独证明实际显示，静态结构检查不证明证据真实或任务执行。
+
+## 完成标记
+
+只判断本次涉及的宏、模板、注册路径与类型同步；未涉及项不适用，失败/未验证项不得写成完成。运行时内容、事件和样式需另有目标 IDE/真机观察，不因编译成功而一并通过。
+- 反馈保留期望/实际、复现前提、证据与限定范围的提议；确定性编译/类型错误优先进入工具或检查，语义/风格先作候选示例交人工审阅。一次偏好只留本次记录，确有复发及具体人工规则决定后才提议长期规则，不自动改源码/全局规则或上传业务数据。
+- Skill 永久修订只在获授权的作者检出目录进行，不编辑包管理器受管的安装副本（如 `node_modules` 内 Skill 或 `.agents/skills` 指向它的链接）；维护用例留在作者仓库，不随消费包提供，也不是使用前提。
+
+## 参考资料
+
+- `references/macro-config-checklist.md`
+- `references/template-compat-matrix.md`
+- `references/troubleshooting-playbook.md`
+- `references/tooling-and-hmr-matrix.md`

package/skills/weapp-vite-vue-sfc-best-practices/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: 'Weapp-vite Vue SFC Best Practices'
+  short_description: 'Vue SFC 宏、JSX/TSX、模板兼容与受管类型'
+  default_prompt: 'Use $weapp-vite-vue-sfc-best-practices to implement or debug Vue SFC macros, Wevu-owned JSX or TSX boundaries, template compatibility, and managed type outputs in a weapp-vite project.'
+
+policy:
+  allow_implicit_invocation: true

package/skills/weapp-vite-vue-sfc-best-practices/references/macro-config-checklist.md

@@ -0,0 +1,20 @@
+# Macro & Config Checklist
+
+## JSON 配置策略
+
+- Component SFC：优先 `defineComponentJson`
+- Page / App SFC：优先 `definePageJson` / `defineAppJson`
+- `<json>` 仅作历史兼容兜底
+
+## 宏规则
+
+- 一个 SFC 角色只保留一套 JSON 宏
+- `definePageMeta` 可与 `definePageJson` 共存
+- 宏调用保持顶层、单参数、无副作用
+
+## IDE / 类型提示
+
+- 在 `vueCompilerOptions.plugins` 中启用 `weapp-vite/volar`
+- 使用 Wevu 宏类型时，先确认项目显式安装 `wevu`，再把 `vueCompilerOptions.lib` 设为 `wevu`。
+
+- `weapp.json.mergeStrategy` 的 `ctx.routeConfig` / `ctx.pageMeta` 可读取当前 SFC 页面的静态声明，贯穿编译、emit、merge-existing 与 JSON-only HMR。包含动态成员的 pageMeta 整体为 undefined，不执行表达式，也不返回部分对象。静态类型由 compiler 持有。

package/skills/weapp-vite-vue-sfc-best-practices/references/template-compat-matrix.md

@@ -0,0 +1,24 @@
+# Template Compatibility Matrix
+
+## `v-model`
+
+- 推荐：可赋值左值，如 `x`、`x.y`、`x[i]`
+- 避免：表达式、函数调用、可选链目标
+- 不要假设 Web Vue 的完整 `v-model` 参数与修饰符能力
+
+## `v-bind`
+
+- 当前小程序模板链路不要使用 `v-bind="object"` 展开
+- 改用显式 `:prop="..."` 与 `@event="..."`
+
+## 组件事件
+
+- 优先小程序事件命名与语义
+- 自定义组件保持 `valueProp` 与 `event` 契约显式
+
+## JSX / TSX 与表达式
+
+- Vue/Wevu JSX 输出的小程序自定义组件 tag 保持 kebab-case。
+- 可选链与空值合并必须转换成目标模板可执行表达式。
+- 启用项目级 `weapp.react` 后，独立 `.jsx/.tsx` 归 React owner；不要按 Wevu JSX 规则处理。
+- 纯模板 SFC 没有 script block 时仍应参与组件和类型扫描。

package/skills/weapp-vite-vue-sfc-best-practices/references/tooling-and-hmr-matrix.md

@@ -0,0 +1,13 @@
+# SFC Tooling And HMR Matrix
+
+| 症状                    | 先查                                                               | 验证                                    |
+| ----------------------- | ------------------------------------------------------------------ | --------------------------------------- |
+| `.vue` 类型漂移         | `.weapp-vite/tsconfig.app.json`、Volar plugin、solution references | `wv prepare` 后运行项目已有 typecheck script |
+| 模板绑定不存在          | `skipTemplateCodegen`、WXS 注入                                    | 编辑器模板诊断与目标构建                |
+| JSON 修改未生效         | JSON-only HMR 条件                                                 | 只改 JSON 与完整 SFC 各跑一次           |
+| `weapp.*` Hover 缺失    | `defineConfig` 导入来源                                            | 从 `weapp-vite/config` 导入后 typecheck |
+| 纯模板 SFC prepare 失败 | 是否把 `<template>` 文本交给 JSX parser、组件扫描结果              | `wv prepare` 后检查声明与目标构建       |
+| JSX/TSX owner 冲突      | 项目是否启用 `weapp.react`、对应 runtime 是否显式安装              | 项目目标构建后验证该页面交互，不调用框架仓库测试 |
+| 多平台 SFC 漂移         | `-p <platform>`、平台 project config、条件编译和原生组件依赖       | 每个目标独立 build，目标 IDE/真机验收   |
+
+上述命令在消费项目根执行；无 build script 时可用 `pnpm exec wv build -p <platform>`。运行时问题还需在目标 IDE/真机观察状态、事件与样式；构建通过不能替代运行时验收。

package/skills/weapp-vite-vue-sfc-best-practices/references/troubleshooting-playbook.md

@@ -0,0 +1,21 @@
+# SFC Troubleshooting Playbook
+
+## 组件不渲染
+
+- 检查 `usingComponents` 路径与大小写
+- 检查组件目标是否声明 `component: true`
+
+## 状态不更新
+
+- 确认项目显式安装 `wevu`，runtime API 来自 `wevu`；仅有 `weapp-vite` 不提供响应式运行时
+- 确认模板真正消费了变化的响应式状态
+
+## Hook 不触发
+
+- 确认在同步 `setup()` 中注册
+- 确认 hook 属于当前 page / component 上下文
+
+## 模板输出异常
+
+- 先查 `v-model`、`v-bind` 等兼容限制
+- 用显式绑定把编译变换问题最小化

package/dist/file-BHca0tSX.mjs

@@ -1 +0,0 @@
-export { t as extractConfigFromVue } from "./file-BSnzOG71.mjs";

package/dist/getInstance-KmwxLWE4.mjs

@@ -1 +0,0 @@
-export { t as getCompilerContext } from "./getInstance-BVPJxJPq.mjs";

package/dist/loadConfig-CTPTKB6I.mjs

@@ -1 +0,0 @@
-export { t as loadConfig } from "./loadConfig-Cz0YvFKX.mjs";