create-weapp-vite 3.2.0 → 3.3.0

package/README.md

@@ -17,9 +17,11 @@
 
 推荐直接使用包管理器的 create 命令：
 
-> 需要 Node.js 22（至少 `22.22.2`）、24（至少 `24.15.0`）或 26 及以上版本，再执行 `pnpm create weapp-vite`、`yarn create weapp-vite` 或 `npm create weapp-vite@latest`。不再支持 Node.js 20。
+> 官方支持 Node.js 22（至少 `22.23.4`）、24（至少 `24.22.1`）或 26（至少 `26.12.1`）及以上版本。建议使用受支持 LTS 分支的最新安全补丁版本，再执行 `pnpm create weapp-vite`、`yarn create weapp-vite` 或 `npm create weapp-vite@latest`。
 
-框架包 `weapp-vite` 的最低版本为 Node 22.18.0、24.11.0 或 26 及以上；脚手架要求以本页较高的版本为准。
+框架包 `weapp-vite` 与脚手架采用相同的 Node 支持范围；Vite+ 模板要求 `^24.22.1 || >=26.12.1`。
+
+生成项目中的 `weapp-vite` CLI（含 `prepare`）与 Tailwind 集成遇到范围外的 Node 版本时，会提示升级并继续尝试执行。Node 缺少依赖所需的语法或 API 时仍可能失败；项目或团队启用严格 engines 校验时，包管理器也可能拒绝安装。
 
 ```bash
 pnpm create weapp-vite

package/dist/cli.d.ts

@@ -1,7 +1,5 @@
-//#region src/cli.d.ts
 export declare function run(): Promise<void>;
 /**
  * @description CLI 主入口执行 Promise（便于测试或外部调用）
  */
-export declare const runPromise: Promise<void>;
-//#endregion
+export declare const runPromise: Promise<void>;

package/dist/cli.js

@@ -1,11 +1,11 @@
-import { a as validateDependencyVersionStrategy, n as validateToolchain, t as createProject } from "./src-CwQw4KHz.js";
+import { a as validateDependencyVersionStrategy, n as validateToolchain, t as createProject } from "./src-Dz0Mumdl.js";
 import process from "node:process";
 import logger from "@weapp-core/logger";
 import { fs } from "@weapp-core/shared/fs";
 import path from "node:path";
 import { confirm, input, select } from "@inquirer/prompts";
 import { initConfig } from "@weapp-core/init";
-//#region src/cli.ts
+// src/cli.ts
 const cwd = process.cwd();
 const TEMPLATE_CHOICES = [
 	{
@@ -146,5 +146,4 @@ const runPromise = run().catch((err) => {
 	logger.error("✗ 创建失败:", message);
 	process.exitCode = 1;
 });
-//#endregion
 export { run, runPromise };

package/dist/index.d.ts

@@ -1,12 +1,7 @@
 import "npm-registry-fetch";
 import "pkg-types";
-//#region src/dependencyVersions/index.d.ts
 type DependencyVersionStrategy = 'compatible' | 'bundled';
-//#endregion
-//#region src/toolchain.d.ts
 type Toolchain = 'wv' | 'vite' | 'vite-plus';
-//#endregion
-//#region src/enums.d.ts
 export declare enum TemplateName {
   default = "default",
   multiPlatform = "multi-platform",
@@ -20,8 +15,6 @@ export declare enum TemplateName {
   react = "react",
   lib = "lib"
 }
-//#endregion
-//#region src/createProject.d.ts
 interface CreateProjectOptions {
   /** 选择构建宿主，业务模板与工具链独立。 */
   toolchain?: Toolchain;
@@ -34,5 +27,4 @@ interface CreateProjectOptions {
  * @description 根据模板创建项目
  */
 export declare function createProject(targetDir?: string, templateName?: TemplateName, options?: CreateProjectOptions): Promise<void>;
-//#endregion
 export type { CreateProjectOptions, DependencyVersionStrategy, Toolchain };

package/dist/index.js

@@ -1 +1 @@
-export { i as TemplateName, t as createProject } from "./src-CwQw4KHz.js";
+export { i as TemplateName, t as createProject } from "./src-Dz0Mumdl.js";

package/dist/{src-CwQw4KHz.js → src-Dz0Mumdl.js}

@@ -14,7 +14,7 @@ import makeFetch from "make-fetch-happen";
 import registryFetch from "npm-registry-fetch";
 import { isIP } from "node:net";
 import { execa } from "execa";
-//#region src/generated/agents.ts
+// src/generated/agents.ts
 const generatedAgentGuidelines = {
 	"default": "# AGENTS Guidelines\n\n<!-- agents-generated: v1 -->\n<!-- source: template:default; manifest-version: 1; generator-version: 1 -->\n\n## Mini-program Runtime Host APIs\n\n- 小程序 AppService 不是浏览器或 Node.js。新增 `queueMicrotask`、Web API、DOM/Node 全局或现代内建前，必须先在目标平台的真实 IDE、目标基础库和 renderer 中探测存在性与最小调用语义；浏览器、Node、类型声明和 headless simulator 结果都不能替代真实 IDE 证据。\n- 微信运行时不得假定存在 `queueMicrotask`。即使某个 DevTools 版本探测为可用，也必须使用显式兼容层，或确认项目已经启用对应的 weapp-vite runtime global 注入。\n- 项目 ESLint 配置应接入 `@weapp-vite/eslint` 的 `miniProgramRuntimeRecommended` 或 `createMiniProgramRuntimeConfig()`，只检查会进入小程序运行时的 `src` 代码；config、构建脚本、测试、Web-only、WXS 和生成产物不纳入该规则。\n\n## Local Docs First\n\n- After dependencies are installed, prefer reading local package docs under `node_modules/weapp-vite/dist/docs/` first.\n- Start with `node_modules/weapp-vite/dist/docs/index.md`, then read `README.md` and `mcp.md` as needed.\n- Prefer local package docs over stale model memory or old web pages when command behavior is unclear.\n\n## CLI Entry\n\n- This project supports both `weapp-vite` and `wv` CLI commands.\n- Treat `weapp-vite dev` and `wv dev` as equivalent forms.\n- Prefer project scripts such as `pnpm dev`, `pnpm build`, `pnpm open`, and `pnpm g` before ad-hoc shell commands.\n- Use `weapp-vite prepare` or `wv prepare` when managed support files under `.weapp-vite/` need to be refreshed.\n- Prefer `weapp-vite screenshot` or `wv screenshot` for mini-program screenshot acceptance.\n- Prefer `weapp-vite compare` or `wv compare` for mini-program screenshot diff, baseline comparison, and visual regression checks.\n- Prefer `weapp-vite ide logs --open` or `wv ide logs --open` for DevTools terminal log bridging.\n- Do not default to generic browser screenshot tools when the target is the mini-program runtime in WeChat DevTools.\n\n## AI Intent Routing\n\n- When the request mentions screenshot, 截图, 页面快照, runtime screenshot, or capture the current mini-program page, default to `weapp-vite screenshot` / `wv screenshot`.\n- When the request mentions screenshot compare, 截图对比, diff, baseline, visual regression, 像素对比, or acceptance comparison, default to `weapp-vite compare` / `wv compare`.\n- Treat these commands as the primary screenshot contract for AI workflows in this project.\n- Only fall back to generic browser screenshot tools when the target is explicitly the web runtime instead of WeChat DevTools.\n\n## Weapp-vite Workflow\n\n- Keep `vite.config.ts` as the source of truth for `weapp` config, output behavior, and IDE/MCP automation.\n- Confirm `weapp.srcRoot`, routes, subpackages, and auto-import strategy before broad refactors.\n- Prefer minimal scoped verification: targeted `pnpm build`, targeted tests, then broader checks only when required.\n- If editing package source in a monorepo dependency, rebuild the touched package before validating downstream apps to avoid stale `dist`.\n- Keep CLI ownership explicit: native `weapp-vite` commands first, IDE passthrough second.\n- For Rust/native acceleration, treat JS ↔ Rust boundary crossings as a primary performance cost. Prefer batch analysis that sends source once, parses once, and returns structured results; only put fine-grained native APIs on hot paths when profiling proves a net win.\n- Keep native AST fast paths optional and explicitly enabled. They must fall back to Babel/Oxc/Vue compiler behavior on load, parse, or runtime failure, and new native coverage needs correctness tests plus real profiling.\n\n## WeChat DevTools\n\n- Before using screenshot, preview, upload, automator, or `--open`, ensure WeChat DevTools is logged in and the service port is enabled.\n- `wv open`, `wv dev -o`, and `wv build -o` use the official DevTools CLI first, then connect automator; if the IDE is open but automator is unavailable, run `wv ide doctor --json` before retrying.\n- Use `--ide-open-strategy automator` only for explicit compatibility debugging; do not treat it as the default startup path.\n- Prefer writing screenshots to workspace paths such as `.tmp/acceptance.png`.\n\n## AI Skills\n\n- Recommend installing shared skills with `npx skills add sonofmagic/skills`.\n- In Codex/Claude environments, prefer these skills first when available:\n  - `$weapp-vite-best-practices` for config, build, subpackage, route, DevTools CLI orchestration, and screenshot/compare command work.\n  - `$weapp-vite-vue-sfc-best-practices` for `.vue` SFC macros, JSON blocks, and template compatibility.\n  - `$release-and-changeset-best-practices` for issue delivery, pnpm change intents, repoctl release decisions, and PR workflow.\n  - `$docs-and-website-sync` when documentation or AI guidance must be refreshed together with code changes.\n  - Use `$weapp-vite-best-practices` for stateful HMR, pluginRoot/dist-plugin, Web runtime compatibility, and native AST profiling; use `$wevu-best-practices` for `wevu/router` navigation semantics.\n  - Use `$weapp-devtools-e2e-best-practices` for serialized DevTools runtime suites, shared automator sessions, and known host compatibility skips.\n  - `$weapp-acceptance` for repeatable checks with `wv accept`, assertions and current-code evidence; no extra model Key.\n  - `$native-to-weapp-vite-wevu-migration` when migrating native mini-program projects to `weapp-vite + native`, or further toward Vue SFC / wevu.\n\n## Native Mini-program Authoring\n\n- Keep native page/component structure consistent with the template unless there is a clear migration goal.\n- Prefer `weapp-vite generate` or `wv generate` for new app/page/component scaffolds.\n- If migrating this project, first decide whether the target is `weapp-vite + native` or a further Vue SFC / `wevu` migration, then keep each migration wave explicit.\n\n## Local Overlay\n\n- If `AGENTS.local.md` exists in this project or directory, read it after this file and apply its project-specific additions.\n- Keep generated `AGENTS.md` files managed by the repository tooling; put user-owned custom rules in `AGENTS.local.md`.\n",
 	"multi-platform": "# AGENTS Guidelines\n\n<!-- agents-generated: v1 -->\n<!-- source: template:multi-platform; manifest-version: 1; generator-version: 1 -->\n\n## Mini-program Runtime Host APIs\n\n- 小程序 AppService 不是浏览器或 Node.js。新增 `queueMicrotask`、Web API、DOM/Node 全局或现代内建前，必须先在目标平台的真实 IDE、目标基础库和 renderer 中探测存在性与最小调用语义；浏览器、Node、类型声明和 headless simulator 结果都不能替代真实 IDE 证据。\n- 微信运行时不得假定存在 `queueMicrotask`。即使某个 DevTools 版本探测为可用，也必须使用显式兼容层，或确认项目已经启用对应的 weapp-vite runtime global 注入。\n- 项目 ESLint 配置应接入 `@weapp-vite/eslint` 的 `miniProgramRuntimeRecommended` 或 `createMiniProgramRuntimeConfig()`，只检查会进入小程序运行时的 `src` 代码；config、构建脚本、测试、Web-only、WXS 和生成产物不纳入该规则。\n\n## Local Docs First\n\n- After dependencies are installed, prefer reading local package docs under `node_modules/weapp-vite/dist/docs/` first.\n- Start with `node_modules/weapp-vite/dist/docs/index.md`, then read `README.md` and `mcp.md` as needed.\n- Prefer local package docs over stale model memory or old web pages when command behavior is unclear.\n\n## CLI Entry\n\n- This project supports both `weapp-vite` and `wv` CLI commands.\n- Treat `weapp-vite dev` and `wv dev` as equivalent forms.\n- Prefer project scripts such as `pnpm dev`, `pnpm build`, `pnpm open`, and `pnpm g` before ad-hoc shell commands.\n- Use `weapp-vite prepare` or `wv prepare` when managed support files under `.weapp-vite/` need to be refreshed.\n- Prefer `weapp-vite screenshot` or `wv screenshot` for mini-program screenshot acceptance.\n- Prefer `weapp-vite compare` or `wv compare` for mini-program screenshot diff, baseline comparison, and visual regression checks.\n- Prefer `weapp-vite ide logs --open` or `wv ide logs --open` for DevTools terminal log bridging.\n- Do not default to generic browser screenshot tools when the target is the mini-program runtime in WeChat DevTools.\n\n## AI Intent Routing\n\n- When the request mentions screenshot, 截图, 页面快照, runtime screenshot, or capture the current mini-program page, default to `weapp-vite screenshot` / `wv screenshot`.\n- When the request mentions screenshot compare, 截图对比, diff, baseline, visual regression, 像素对比, or acceptance comparison, default to `weapp-vite compare` / `wv compare`.\n- Treat these commands as the primary screenshot contract for AI workflows in this project.\n- Only fall back to generic browser screenshot tools when the target is explicitly the web runtime instead of WeChat DevTools.\n\n## Weapp-vite Workflow\n\n- Keep `vite.config.ts` as the source of truth for `weapp` config, output behavior, and IDE/MCP automation.\n- Confirm `weapp.srcRoot`, routes, subpackages, and auto-import strategy before broad refactors.\n- Prefer minimal scoped verification: targeted `pnpm build`, targeted tests, then broader checks only when required.\n- If editing package source in a monorepo dependency, rebuild the touched package before validating downstream apps to avoid stale `dist`.\n- Keep CLI ownership explicit: native `weapp-vite` commands first, IDE passthrough second.\n- For Rust/native acceleration, treat JS ↔ Rust boundary crossings as a primary performance cost. Prefer batch analysis that sends source once, parses once, and returns structured results; only put fine-grained native APIs on hot paths when profiling proves a net win.\n- Keep native AST fast paths optional and explicitly enabled. They must fall back to Babel/Oxc/Vue compiler behavior on load, parse, or runtime failure, and new native coverage needs correctness tests plus real profiling.\n\n## WeChat DevTools\n\n- Before using screenshot, preview, upload, automator, or `--open`, ensure WeChat DevTools is logged in and the service port is enabled.\n- `wv open`, `wv dev -o`, and `wv build -o` use the official DevTools CLI first, then connect automator; if the IDE is open but automator is unavailable, run `wv ide doctor --json` before retrying.\n- Use `--ide-open-strategy automator` only for explicit compatibility debugging; do not treat it as the default startup path.\n- Prefer writing screenshots to workspace paths such as `.tmp/acceptance.png`.\n\n## AI Skills\n\n- Recommend installing shared skills with `npx skills add sonofmagic/skills`.\n- In Codex/Claude environments, prefer these skills first when available:\n  - `$weapp-vite-best-practices` for config, build, subpackage, route, DevTools CLI orchestration, and screenshot/compare command work.\n  - `$weapp-vite-vue-sfc-best-practices` for `.vue` SFC macros, JSON blocks, and template compatibility.\n  - `$release-and-changeset-best-practices` for issue delivery, pnpm change intents, repoctl release decisions, and PR workflow.\n  - `$docs-and-website-sync` when documentation or AI guidance must be refreshed together with code changes.\n  - Use `$weapp-vite-best-practices` for stateful HMR, pluginRoot/dist-plugin, Web runtime compatibility, and native AST profiling; use `$wevu-best-practices` for `wevu/router` navigation semantics.\n  - Use `$weapp-devtools-e2e-best-practices` for serialized DevTools runtime suites, shared automator sessions, and known host compatibility skips.\n  - `$weapp-acceptance` for repeatable checks with `wv accept`, assertions and current-code evidence; no extra model Key.\n  - `$native-to-weapp-vite-wevu-migration` when migrating native mini-program projects to `weapp-vite + native`, or further toward Vue SFC / wevu.\n\n## Native Mini-program Authoring\n\n- Keep native page/component structure consistent with the template unless there is a clear migration goal.\n- Prefer `weapp-vite generate` or `wv generate` for new app/page/component scaffolds.\n- If migrating this project, first decide whether the target is `weapp-vite + native` or a further Vue SFC / `wevu` migration, then keep each migration wave explicit.\n\n## Multi-platform Workflow\n\n- This project builds one target at a time. Always pass an explicit platform or use `pnpm dev:<platform>` / `pnpm build:<platform>`.\n- Keep platform IDE configuration under `config/<platform>` and import `dist/<platform>` into the matching mini-program IDE.\n- Use `pnpm dev:web` for browser compatibility work, but keep mini-program DevTools or device acceptance as the release authority.\n- Treat WeChat, Web, official IDE compilation, and unsupported automator targets as separate verification layers; do not report a build-only check as runtime E2E.\n\n## Local Overlay\n\n- If `AGENTS.local.md` exists in this project or directory, read it after this file and apply its project-specific additions.\n- Keep generated `AGENTS.md` files managed by the repository tooling; put user-owned custom rules in `AGENTS.local.md`.\n",
@@ -28,8 +28,7 @@ const generatedAgentGuidelines = {
 	"react": "# AGENTS Guidelines\n\n<!-- agents-generated: v1 -->\n<!-- source: template:react; manifest-version: 1; generator-version: 1 -->\n\n## Mini-program Runtime Host APIs\n\n- 小程序 AppService 不是浏览器或 Node.js。新增 `queueMicrotask`、Web API、DOM/Node 全局或现代内建前，必须先在目标平台的真实 IDE、目标基础库和 renderer 中探测存在性与最小调用语义；浏览器、Node、类型声明和 headless simulator 结果都不能替代真实 IDE 证据。\n- 微信运行时不得假定存在 `queueMicrotask`。即使某个 DevTools 版本探测为可用，也必须使用显式兼容层，或确认项目已经启用对应的 weapp-vite runtime global 注入。\n- 项目 ESLint 配置应接入 `@weapp-vite/eslint` 的 `miniProgramRuntimeRecommended` 或 `createMiniProgramRuntimeConfig()`，只检查会进入小程序运行时的 `src` 代码；config、构建脚本、测试、Web-only、WXS 和生成产物不纳入该规则。\n\n## Local Docs First\n\n- After dependencies are installed, prefer reading local package docs under `node_modules/weapp-vite/dist/docs/` first.\n- Start with `node_modules/weapp-vite/dist/docs/index.md`, then read `README.md` and `mcp.md` as needed.\n- Prefer local package docs over stale model memory or old web pages when command behavior is unclear.\n\n## CLI Entry\n\n- This project supports both `weapp-vite` and `wv` CLI commands.\n- Treat `weapp-vite dev` and `wv dev` as equivalent forms.\n- Prefer project scripts such as `pnpm dev`, `pnpm build`, `pnpm open`, and `pnpm g` before ad-hoc shell commands.\n- Use `weapp-vite prepare` or `wv prepare` when managed support files under `.weapp-vite/` need to be refreshed.\n- Prefer `weapp-vite screenshot` or `wv screenshot` for mini-program screenshot acceptance.\n- Prefer `weapp-vite compare` or `wv compare` for mini-program screenshot diff, baseline comparison, and visual regression checks.\n- Prefer `weapp-vite ide logs --open` or `wv ide logs --open` for DevTools terminal log bridging.\n- Do not default to generic browser screenshot tools when the target is the mini-program runtime in WeChat DevTools.\n\n## AI Intent Routing\n\n- When the request mentions screenshot, 截图, 页面快照, runtime screenshot, or capture the current mini-program page, default to `weapp-vite screenshot` / `wv screenshot`.\n- When the request mentions screenshot compare, 截图对比, diff, baseline, visual regression, 像素对比, or acceptance comparison, default to `weapp-vite compare` / `wv compare`.\n- Treat these commands as the primary screenshot contract for AI workflows in this project.\n- Only fall back to generic browser screenshot tools when the target is explicitly the web runtime instead of WeChat DevTools.\n\n## Weapp-vite Workflow\n\n- Keep `vite.config.ts` as the source of truth for `weapp` config, output behavior, and IDE/MCP automation.\n- Confirm `weapp.srcRoot`, routes, subpackages, and auto-import strategy before broad refactors.\n- Prefer minimal scoped verification: targeted `pnpm build`, targeted tests, then broader checks only when required.\n- If editing package source in a monorepo dependency, rebuild the touched package before validating downstream apps to avoid stale `dist`.\n- Keep CLI ownership explicit: native `weapp-vite` commands first, IDE passthrough second.\n- For Rust/native acceleration, treat JS ↔ Rust boundary crossings as a primary performance cost. Prefer batch analysis that sends source once, parses once, and returns structured results; only put fine-grained native APIs on hot paths when profiling proves a net win.\n- Keep native AST fast paths optional and explicitly enabled. They must fall back to Babel/Oxc/Vue compiler behavior on load, parse, or runtime failure, and new native coverage needs correctness tests plus real profiling.\n\n## WeChat DevTools\n\n- Before using screenshot, preview, upload, automator, or `--open`, ensure WeChat DevTools is logged in and the service port is enabled.\n- `wv open`, `wv dev -o`, and `wv build -o` use the official DevTools CLI first, then connect automator; if the IDE is open but automator is unavailable, run `wv ide doctor --json` before retrying.\n- Use `--ide-open-strategy automator` only for explicit compatibility debugging; do not treat it as the default startup path.\n- Prefer writing screenshots to workspace paths such as `.tmp/acceptance.png`.\n\n## AI Skills\n\n- Recommend installing shared skills with `npx skills add sonofmagic/skills`.\n- In Codex/Claude environments, prefer these skills first when available:\n  - `$weapp-vite-best-practices` for config, build, subpackage, route, DevTools CLI orchestration, and screenshot/compare command work.\n  - `$weapp-vite-vue-sfc-best-practices` for `.vue` SFC macros, JSON blocks, and template compatibility.\n  - `$release-and-changeset-best-practices` for issue delivery, pnpm change intents, repoctl release decisions, and PR workflow.\n  - `$docs-and-website-sync` when documentation or AI guidance must be refreshed together with code changes.\n  - Use `$weapp-vite-best-practices` for stateful HMR, pluginRoot/dist-plugin, Web runtime compatibility, and native AST profiling; use `$wevu-best-practices` for `wevu/router` navigation semantics.\n  - Use `$weapp-devtools-e2e-best-practices` for serialized DevTools runtime suites, shared automator sessions, and known host compatibility skips.\n  - `$weapp-vite-react-best-practices` for React 19 JSX/TSX ownership, render modes, root lifecycle, React Compiler, and native/Wevu component bridges.\n\n## React Mini-program Authoring\n\n- Keep `weapp.react` as the project-level owner for all `.jsx` and `.tsx` modules; do not mix Wevu JSX in the same build.\n- Use the current workspace baseline of React 19.3.x, `react-reconciler` 0.34.x, and `@weapp-vite/react` without `react-dom`.\n- Start with `renderMode: 'auto'`; use `dynamic` only for reconciler-tree diagnostics and `static` for strict static-shape validation.\n- Create and unmount `createReactMiniProgramRoot` in the native page/component lifecycle, and forward host events through the root.\n- Register native or Wevu custom components in `usingComponents` before declaring a top-level `createNativeComponent()` bridge in the current TSX file.\n- Treat the current React runtime as WeChat-only; Web, Alipay, and Douyin builds are not runtime compatibility evidence.\n\n## Local Overlay\n\n- If `AGENTS.local.md` exists in this project or directory, read it after this file and apply its project-specific additions.\n- Keep generated `AGENTS.md` files managed by the repository tooling; put user-owned custom rules in `AGENTS.local.md`.\n",
 	"lib": "# AGENTS Guidelines\n\n<!-- agents-generated: v1 -->\n<!-- source: template:lib; manifest-version: 1; generator-version: 1 -->\n\n## Mini-program Runtime Host APIs\n\n- 小程序 AppService 不是浏览器或 Node.js。新增 `queueMicrotask`、Web API、DOM/Node 全局或现代内建前，必须先在目标平台的真实 IDE、目标基础库和 renderer 中探测存在性与最小调用语义；浏览器、Node、类型声明和 headless simulator 结果都不能替代真实 IDE 证据。\n- 微信运行时不得假定存在 `queueMicrotask`。即使某个 DevTools 版本探测为可用，也必须使用显式兼容层，或确认项目已经启用对应的 weapp-vite runtime global 注入。\n- 项目 ESLint 配置应接入 `@weapp-vite/eslint` 的 `miniProgramRuntimeRecommended` 或 `createMiniProgramRuntimeConfig()`，只检查会进入小程序运行时的 `src` 代码；config、构建脚本、测试、Web-only、WXS 和生成产物不纳入该规则。\n\n## Local Docs First\n\n- After dependencies are installed, prefer reading local package docs under `node_modules/weapp-vite/dist/docs/` first.\n- Start with `node_modules/weapp-vite/dist/docs/index.md`, then read `README.md` and `mcp.md` as needed.\n- Prefer local package docs over stale model memory or old web pages when command behavior is unclear.\n\n## CLI Entry\n\n- This project supports both `weapp-vite` and `wv` CLI commands.\n- Treat `weapp-vite dev` and `wv dev` as equivalent forms.\n- Prefer project scripts such as `pnpm dev`, `pnpm build`, `pnpm open`, and `pnpm g` before ad-hoc shell commands.\n- Use `weapp-vite prepare` or `wv prepare` when managed support files under `.weapp-vite/` need to be refreshed.\n- Prefer `weapp-vite screenshot` or `wv screenshot` for mini-program screenshot acceptance.\n- Prefer `weapp-vite compare` or `wv compare` for mini-program screenshot diff, baseline comparison, and visual regression checks.\n- Prefer `weapp-vite ide logs --open` or `wv ide logs --open` for DevTools terminal log bridging.\n- Do not default to generic browser screenshot tools when the target is the mini-program runtime in WeChat DevTools.\n\n## AI Intent Routing\n\n- When the request mentions screenshot, 截图, 页面快照, runtime screenshot, or capture the current mini-program page, default to `weapp-vite screenshot` / `wv screenshot`.\n- When the request mentions screenshot compare, 截图对比, diff, baseline, visual regression, 像素对比, or acceptance comparison, default to `weapp-vite compare` / `wv compare`.\n- Treat these commands as the primary screenshot contract for AI workflows in this project.\n- Only fall back to generic browser screenshot tools when the target is explicitly the web runtime instead of WeChat DevTools.\n\n## Weapp-vite Workflow\n\n- Keep `vite.config.ts` as the source of truth for `weapp` config, output behavior, and IDE/MCP automation.\n- Confirm `weapp.srcRoot`, routes, subpackages, and auto-import strategy before broad refactors.\n- Prefer minimal scoped verification: targeted `pnpm build`, targeted tests, then broader checks only when required.\n- If editing package source in a monorepo dependency, rebuild the touched package before validating downstream apps to avoid stale `dist`.\n- Keep CLI ownership explicit: native `weapp-vite` commands first, IDE passthrough second.\n- For Rust/native acceleration, treat JS ↔ Rust boundary crossings as a primary performance cost. Prefer batch analysis that sends source once, parses once, and returns structured results; only put fine-grained native APIs on hot paths when profiling proves a net win.\n- Keep native AST fast paths optional and explicitly enabled. They must fall back to Babel/Oxc/Vue compiler behavior on load, parse, or runtime failure, and new native coverage needs correctness tests plus real profiling.\n\n## WeChat DevTools\n\n- Before using screenshot, preview, upload, automator, or `--open`, ensure WeChat DevTools is logged in and the service port is enabled.\n- `wv open`, `wv dev -o`, and `wv build -o` use the official DevTools CLI first, then connect automator; if the IDE is open but automator is unavailable, run `wv ide doctor --json` before retrying.\n- Use `--ide-open-strategy automator` only for explicit compatibility debugging; do not treat it as the default startup path.\n- Prefer writing screenshots to workspace paths such as `.tmp/acceptance.png`.\n\n## AI Skills\n\n- Recommend installing shared skills with `npx skills add sonofmagic/skills`.\n- In Codex/Claude environments, prefer these skills first when available:\n  - `$weapp-vite-best-practices` for config, build, subpackage, route, DevTools CLI orchestration, and screenshot/compare command work.\n  - `$weapp-vite-vue-sfc-best-practices` for `.vue` SFC macros, JSON blocks, and template compatibility.\n  - `$release-and-changeset-best-practices` for issue delivery, pnpm change intents, repoctl release decisions, and PR workflow.\n  - `$docs-and-website-sync` when documentation or AI guidance must be refreshed together with code changes.\n  - Use `$weapp-vite-best-practices` for stateful HMR, pluginRoot/dist-plugin, Web runtime compatibility, and native AST profiling; use `$wevu-best-practices` for `wevu/router` navigation semantics.\n  - Use `$weapp-devtools-e2e-best-practices` for serialized DevTools runtime suites, shared automator sessions, and known host compatibility skips.\n  - `$weapp-acceptance` for repeatable checks with `wv accept`, assertions and current-code evidence; no extra model Key.\n  - `$native-to-weapp-vite-wevu-migration` when migrating native mini-program projects to `weapp-vite + native`, or further toward Vue SFC / wevu.\n\n## Native Mini-program Authoring\n\n- Keep native page/component structure consistent with the template unless there is a clear migration goal.\n- Prefer `weapp-vite generate` or `wv generate` for new app/page/component scaffolds.\n- If migrating this project, first decide whether the target is `weapp-vite + native` or a further Vue SFC / `wevu` migration, then keep each migration wave explicit.\n\n## Local Overlay\n\n- If `AGENTS.local.md` exists in this project or directory, read it after this file and apply its project-specific additions.\n- Keep generated `AGENTS.md` files managed by the repository tooling; put user-owned custom rules in `AGENTS.local.md`.\n"
 };
-//#endregion
-//#region src/agents.ts
+// src/agents.ts
 /**
 * @description 根据模板 profile 返回生成的 AGENTS 指引。
 */
@@ -39,23 +38,17 @@ function createAgentsGuidelines(templateName, toolchain = "wv") {
 	if (toolchain === "wv") return guidelines;
 	return guidelines.replace("- Keep `vite.config.ts` as the source of truth for `weapp` config, output behavior, and IDE/MCP automation.", "- Keep shared mini-program configuration in `weapp-vite.config.ts`; the `vite*.config.ts` host entries import it explicitly. Use project `dev`/`build` scripts for the selected host and `wv prepare/open/upload/mcp` for mini-program tooling. Do not pass `wv --platform` flags to Vite or Vite+.");
 }
-//#endregion
-//#region ../../packages-runtime/react/package.json
-var version$5 = "0.2.13";
-//#endregion
-//#region ../../packages-runtime/wevu/package.json
-var version$4 = "7.6.0";
-//#endregion
-//#region ../dashboard/package.json
-var version$3 = "7.6.0";
-//#endregion
-//#region ../eslint/package.json
-var version$2 = "0.2.11";
-//#endregion
-//#region ../weapp-vite/package.json
-var version$1 = "7.6.0";
-//#endregion
-//#region src/pnpmBuildPolicy.ts
+// ../../packages-runtime/react/package.json
+var version$5 = "0.3.0";
+// ../../packages-runtime/wevu/package.json
+var version$4 = "7.7.0";
+// ../dashboard/package.json
+var version$3 = "7.7.0";
+// ../eslint/package.json
+var version$2 = "0.3.0";
+// ../weapp-vite/package.json
+var version$1 = "7.7.0";
+// src/pnpmBuildPolicy.ts
 const WORKSPACE_CONFIG = `packages: []
 
 # 仅允许模板依赖中需要的安装脚本，新增依赖仍需单独审批。
@@ -103,8 +96,7 @@ async function ensurePnpmBuildPolicy(root) {
 		if (error.code !== "EEXIST") throw error;
 	}
 }
-//#endregion
-//#region src/npm/config.ts
+// src/npm/config.ts
 const NPM_REGISTRY = "https://registry.npmjs.org/";
 const transportKeys = [
 	"proxy",
@@ -261,8 +253,7 @@ function registryEnvironment(options) {
 	if (!options.cafile && options.ca) env.npm_config_ca = Array.isArray(options.ca) ? options.ca.join("\n") : String(options.ca);
 	return env;
 }
-//#endregion
-//#region src/npm/proxy.ts
+// src/npm/proxy.ts
 function bypassProxy(url, noProxy) {
 	const hostname = url.hostname.replace(/^\[|\]$/g, "").toLowerCase();
 	const port = url.port || (url.protocol === "https:" ? "443" : "80");
@@ -284,8 +275,7 @@ function proxyOptions(uri, options) {
 		noProxy: []
 	};
 }
-//#endregion
-//#region src/npm/transport.ts
+// src/npm/transport.ts
 const { getAuth } = registryFetch;
 /** 复用 npm 的认证解析和网络传输，限制认证请求的重定向边界。 */
 async function requestMetadata(uri, options, signal, timeout) {
@@ -336,8 +326,7 @@ async function requestMetadata(uri, options, signal, timeout) {
 		throw Object.assign(/* @__PURE__ */ new Error("registry HTTP request failed"), { statusCode: response.status });
 	}
 }
-//#endregion
-//#region src/npm/index.ts
+// src/npm/index.ts
 const REQUEST_TIMEOUT_MS = 5e3;
 function requestError(error, registry) {
 	const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
@@ -395,15 +384,13 @@ async function getPackageVersionsFromNpm(packageName, signal, options) {
 	if (!isRecord(metadata) || !isRecord(metadata.versions)) throw new Error("registry 响应缺少有效的 versions 信息");
 	return Object.keys(metadata.versions);
 }
-//#endregion
-//#region src/dependencyVersions/compatible.ts
+// src/dependencyVersions/compatible.ts
 /** 仅选择所有已使用核心包共同发布、且兼容各自基线的最高稳定版本。 */
 function findCompatibleVersion(packages) {
 	if (packages.length === 0 || packages.some((pkg) => !valid(pkg.version) || prerelease(pkg.version))) return;
 	return packages[0].versions.filter((version) => valid(version) && !prerelease(version)).filter((version) => packages.every((pkg) => pkg.versions.includes(version) && gte(version, pkg.version) && satisfies(version, `^${pkg.version}`))).sort(rcompare)[0];
 }
-//#endregion
-//#region src/dependencyVersions/deadline.ts
+// src/dependencyVersions/deadline.ts
 /** 将整个查询批次约束在同一时间预算内，并清理未完成的请求。 */
 async function queryWithDeadline(query, timeoutMs) {
 	const controller = new AbortController();
@@ -424,8 +411,7 @@ async function queryWithDeadline(query, timeoutMs) {
 		clearTimeout(timer);
 	}
 }
-//#endregion
-//#region src/dependencyVersions/index.ts
+// src/dependencyVersions/index.ts
 const BUNDLED_VERSIONS = {
 	"weapp-vite": version$1,
 	"wevu": version$4,
@@ -513,8 +499,7 @@ async function resolveDependencyVersions(pkg, strategy = "bundled", network) {
 		return { strategy: "bundled" };
 	}
 }
-//#endregion
-//#region src/enums.ts
+// src/enums.ts
 let TemplateName = /* @__PURE__ */ function(TemplateName) {
 	TemplateName["default"] = "default";
 	TemplateName["multiPlatform"] = "multi-platform";
@@ -529,8 +514,7 @@ let TemplateName = /* @__PURE__ */ function(TemplateName) {
 	TemplateName["lib"] = "lib";
 	return TemplateName;
 }({});
-//#endregion
-//#region src/installationCommand.ts
+// src/installationCommand.ts
 const SAFE_REGISTRY_RE = /^https?:\/\/[\w.:/-]+$/;
 /** 生成可复制的安装命令；Windows 的特殊地址使用明确标注的 PowerShell 语法。 */
 function installationCommand(registry, platform = process.platform) {
@@ -539,8 +523,7 @@ function installationCommand(registry, platform = process.platform) {
 	const quoted = platform === "win32" ? `'${registry.replaceAll("'", "''")}'` : `'${registry.replaceAll("'", "'\\''")}'`;
 	return `${platform === "win32" ? "PowerShell: " : ""}pnpm --config.registry=${quoted} install`;
 }
-//#endregion
-//#region src/skills.ts
+// src/skills.ts
 const RECOMMENDED_SKILLS_SOURCE = "sonofmagic/skills";
 const RECOMMENDED_SKILLS_INSTALL_COMMAND = `npx --yes skills add ${RECOMMENDED_SKILLS_SOURCE}`;
 const SKILLS_INSTALL_TIMEOUT_MS = 6e4;
@@ -611,18 +594,17 @@ async function installRecommendedSkills(cwd, options = {}) {
 		clearTimeout(timer);
 	}
 }
-//#endregion
-//#region src/generated/catalog.ts
+// src/generated/catalog.ts
 const TEMPLATE_CATALOG = {
-	"@babel/core": "^8.0.7",
+	"@babel/core": "^8.0.9",
 	"@babel/generator": "^8.0.6",
-	"@babel/parser": "^8.0.7",
+	"@babel/parser": "^8.0.8",
 	"@babel/traverse": "^8.0.7",
-	"@babel/types": "^8.0.6",
+	"@babel/types": "^8.0.8",
 	"@douyin-microapp/typings": "^1.3.1",
 	"@egoist/tailwindcss-icons": "^1.9.2",
-	"@icebreakers/eslint-config": "8.0.9",
-	"@icebreakers/stylelint-config": "5.1.3",
+	"@icebreakers/eslint-config": "8.0.11",
+	"@icebreakers/stylelint-config": "5.1.5",
 	"@iconify-json/mdi": "^1.2.3",
 	"@iconify/tailwind4": "^1.2.3",
 	"@mini-types/alipay": "^3.0.14",
@@ -630,7 +612,7 @@ const TEMPLATE_CATALOG = {
 	"@types/d3": "^7.4.3",
 	"@types/node": "^26.6.5",
 	"@types/react": "19.3.0",
-	"@types/react-reconciler": "0.34.0",
+	"@types/react-reconciler": "0.34.1",
 	"@types/semver": "^7.8.0",
 	"@vant/weapp": "^1.11.7",
 	"@vitejs/devtools": "0.8.0",
@@ -641,7 +623,8 @@ const TEMPLATE_CATALOG = {
 	"@vue/compiler-dom": "^3.5.44",
 	"@vue/language-core": "^3.3.13",
 	"@vue/reactivity": "^3.5.44",
-	"@wot-ui/ui": "2.3.2",
+	"@vue/shared": "^3.5.44",
+	"@wot-ui/ui": "2.4.0",
 	"antd-mini": "^3.4.3",
 	"bundle-require": "^5.1.0",
 	"class-variance-authority": "^0.7.1",
@@ -649,16 +632,16 @@ const TEMPLATE_CATALOG = {
 	"estree-walker": "^3.0.3",
 	"gm-crypto": "^0.1.12",
 	"graphql-request": "^7.4.0",
-	"happy-dom": "^21.0.3",
+	"happy-dom": "^21.0.4",
 	"lru-cache": "^11.5.3",
 	"magic-string": "^1.4.3",
 	"miniprogram-api-typings": "^5.2.3",
-	"oxc-parser": "^0.154.0",
+	"oxc-parser": "^0.155.0",
 	"oxc-walker": "^1.1.1",
-	"pkg-types": "^2.3.3",
-	"postcss-selector-parser": "^7.1.6",
+	"pkg-types": "^2.4.0",
+	"postcss-selector-parser": "^7.1.7",
 	"react-reconciler": "0.34.0",
-	"sass-embedded": "^1.105.2",
+	"sass-embedded": "^1.106.1",
 	"socket.io-client": "^4.8.4",
 	"tailwind-merge": "^3.7.0",
 	"tailwind-variants": "^3.3.1",
@@ -673,7 +656,7 @@ const TEMPLATE_CATALOG = {
 	clsx: "^2.1.1",
 	d3: "^7.9.0",
 	dayjs: "^1.11.23",
-	devframe: "1.2.5",
+	devframe: "1.2.6",
 	echarts: "^6.1.0",
 	esbuild: "^0.28.2",
 	eslint: "^10.13.0",
@@ -684,17 +667,17 @@ const TEMPLATE_CATALOG = {
 	obug: "^3.0.0",
 	pathe: "^2.0.3",
 	picocolors: "^1.1.1",
-	postcss: "^8.5.30",
+	postcss: "^8.5.31",
 	react: "19.3.1",
-	rolldown: "1.2.14",
-	sass: "^1.105.2",
+	rolldown: "1.2.15",
+	sass: "^1.106.1",
 	sharp: "^0.35.5",
 	stylelint: "^17.16.0",
 	tailwindcss: "^4.3.3",
 	tslib: "^2.8.1",
 	tsx: "^4.23.15",
 	typescript: "^6.0.3",
-	vite: "8.3.4",
+	vite: "8.3.5",
 	vue: "^3.5.44",
 	zod: "^4.6.7"
 };
@@ -707,8 +690,7 @@ const TEMPLATE_NAMED_CATALOG = {
 	},
 	tailwind4: { tailwindcss: "^4.3.3" }
 };
-//#endregion
-//#region src/templateDependencies/index.ts
+// src/templateDependencies/index.ts
 const DIGIT_RE = /\d/;
 const templateCatalogMap = { ...TEMPLATE_CATALOG };
 const templateNamedCatalogMap = Object.fromEntries(Object.entries(TEMPLATE_NAMED_CATALOG).map(([name, deps]) => [name, { ...deps }]));
@@ -753,12 +735,12 @@ function ensureManagedTypeScriptDevDependencies(pkgJson) {
 	if (pkgJson.dependencies?.["@types/node"] || pkgJson.devDependencies["@types/node"] || pkgJson.peerDependencies?.["@types/node"] || pkgJson.optionalDependencies?.["@types/node"]) return;
 	pkgJson.devDependencies["@types/node"] = templateCatalogMap["@types/node"];
 }
-//#endregion
-//#region src/vitePlusVersions.json
+// package.json
+var engines = { "node": "^22.23.4 || ^24.22.1 || >=26.12.1" };
+// src/vitePlusVersions.json
 var version = "1.0.0";
 var vitest = "5.0.1";
-//#endregion
-//#region src/toolchain.ts
+// src/toolchain.ts
 const VITE_PLUS_VERSION = version;
 const VITE_PLUS_VITEST_VERSION = vitest;
 const VITE_PLUS_CORE = `npm:@voidzero-dev/vite-plus-core@${VITE_PLUS_VERSION}`;
@@ -804,6 +786,10 @@ export default defineConfig(async (env) => {
 }
 /** 从共享业务模板派生宿主入口，仅改写普通 build/dev，保留小程序专属命令。 */
 async function applyToolchain(root, pkg, toolchain) {
+	pkg.engines = {
+		...pkg.engines,
+		node: engines.node
+	};
 	if (toolchain === "wv") return;
 	const source = "weapp-vite.config.ts";
 	if (!await fs.pathExists(path.join(root, source))) await fs.move(path.join(root, "vite.config.ts"), path.join(root, source));
@@ -823,10 +809,6 @@ async function applyToolchain(root, pkg, toolchain) {
 	}
 	for (const [fileName, config] of configurations) await fs.writeFile(path.join(root, fileName), renderConfig(toolchain, config.source, config.platform));
 	pkg.devDependencies ??= {};
-	pkg.engines = {
-		...pkg.engines,
-		node: "^22.22.2 || ^24.15.0 || >=26.0.0"
-	};
 	if (toolchain === "vite") {
 		pkg.devDependencies.vite = TEMPLATE_CATALOG.vite;
 		return;
@@ -838,7 +820,7 @@ async function applyToolchain(root, pkg, toolchain) {
 		vite: VITE_PLUS_CORE,
 		vitest: VITE_PLUS_VITEST_VERSION
 	};
-	pkg.engines.node = "^24.15.0 || >=26.0.0";
+	pkg.engines.node = "^24.22.1 || >=26.12.1";
 	const workspace = await findPnpmWorkspaceRoot(root);
 	if (workspace && path.resolve(workspace) === path.resolve(root)) {
 		const fileName = path.join(workspace, "pnpm-workspace.yaml");
@@ -853,8 +835,7 @@ async function applyToolchain(root, pkg, toolchain) {
 		await fs.writeFile(fileName, document.toString());
 	}
 }
-//#endregion
-//#region src/gitignore.ts
+// src/gitignore.ts
 const DEFAULT_GITIGNORE = `# dependencies
 node_modules
 .pnp
@@ -928,8 +909,7 @@ function mergeGitignore(existing) {
 	}
 	return ensureTrailingNewline(trimTrailingBlankLines(merged).join("\n"));
 }
-//#endregion
-//#region src/utils/fs.ts
+// src/utils/fs.ts
 /**
 * @description 文件读取错误
 */
@@ -978,8 +958,7 @@ async function writeFile$1(filepath, contents) {
 		throw new FsWriteError(filepath, error);
 	}
 }
-//#endregion
-//#region src/updateGitignore.ts
+// src/updateGitignore.ts
 async function updateGitIgnore(options) {
 	const { root, write = true } = options;
 	const gitignorePath = path.resolve(root, ".gitignore");
@@ -991,8 +970,7 @@ async function updateGitIgnore(options) {
 	}
 	return merged;
 }
-//#endregion
-//#region src/createProject.ts
+// src/createProject.ts
 const CRLF_RE = /\r\n/g;
 const WINDOWS_VERBATIM_PATH_RE = /^\\\\\?\\/;
 const TOURIST_APP_ID = "touristappid";
@@ -1164,5 +1142,4 @@ async function writeAgentsGuidelines(targetDir, templateName, toolchain = "wv")
 	}
 	await fs.writeFile(agentsPath, createAgentsGuidelines(templateName, toolchain));
 }
-//#endregion
 export { validateDependencyVersionStrategy as a, TemplateName as i, validateToolchain as n, RECOMMENDED_SKILLS_INSTALL_COMMAND as r, createProject as t };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-weapp-vite",
   "type": "module",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "create-weapp-vite tools and runtime components for modern WeChat and multi-platform mini-program development.",
   "author": "ice breaker <1324318532@qq.com>",
   "license": "MIT",
@@ -51,24 +51,24 @@
     "templates"
   ],
   "engines": {
-    "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
+    "node": "^22.23.4 || ^24.22.1 || >=26.12.1"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@inquirer/prompts": "^8.7.3",
+    "@inquirer/prompts": "^8.7.4",
     "@npmcli/config": "^11.2.0",
-    "@weapp-core/init": "6.0.26",
-    "@weapp-core/logger": "3.1.10",
-    "@weapp-core/shared": "3.3.0",
-    "execa": "^10.1.1",
+    "@weapp-core/init": "6.1.0",
+    "@weapp-core/logger": "3.2.0",
+    "@weapp-core/shared": "3.4.0",
+    "execa": "^10.2.1",
     "make-fetch-happen": "^16.0.1",
     "npm-registry-fetch": "^20.0.1",
     "pathe": "^2.0.3",
     "picomatch": "^4.0.7",
-    "pkg-types": "^2.3.3",
+    "pkg-types": "^2.4.0",
     "semver": "^7.8.5",
     "yaml": "^2.9.1"
   },

package/templates/lib/package.json

@@ -1,7 +1,7 @@
 {
   "name": "weapp-vite-lib-template",
   "type": "module",
-  "version": "11.0.5",
+  "version": "11.0.6",
   "private": true,
   "description": "weapp-vite 组件库（lib 模式）模板",
   "author": "ice breaker <1324318532@qq.com>",

package/templates/react/package.json

@@ -1,7 +1,7 @@
 {
   "name": "weapp-vite-react-template",
   "type": "module",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "private": true,
   "weappVite": {
     "web": false
@@ -26,7 +26,7 @@
   "devDependencies": {
     "@icebreakers/eslint-config": "catalog:",
     "@icebreakers/stylelint-config": "catalog:",
-    "@swc/core": "^1.16.18",
+    "@swc/core": "^1.16.20",
     "@types/node": "catalog:",
     "@types/react": "catalog:",
     "@types/react-reconciler": "catalog:",