weapp-vite 6.12.0 → 6.12.3

package/README.md

@@ -31,6 +31,8 @@
 
 ## 快速开始
 
+> 说明：CLI 同时支持完整命令 `weapp-vite` 与简写命令 `wv`，两者等价。下面的示例默认使用 `weapp-vite`，你也可以按个人习惯替换成 `wv`。
+
 ### Vue 项目
 
 ```typescript
@@ -85,6 +87,42 @@ function handleClick() {
 - Vite 插件识别 weapp-vite 宿主：https://vite.icebreaker.top/guide/vite-plugin-host
 - MCP 集成使用指南：[docs/mcp.md](./docs/mcp.md)
 
+## AI 项目指引
+
+通过 `create-weapp-vite` 创建的新项目，现在会默认携带一个根目录 `AGENTS.md`。同时，`weapp-vite` npm 包会随版本发布一份本地文档目录：`node_modules/weapp-vite/dist/docs/`。
+
+这个文件会告诉常见 AI 编程代理：
+
+- 安装依赖后，优先阅读 `node_modules/weapp-vite/dist/docs/README.md`、`node_modules/weapp-vite/dist/docs/mcp.md` 等本地版本文档
+- CLI 同时支持 `weapp-vite` 与 `wv`
+- 需要做小程序截图验收时，优先使用 `weapp-vite screenshot` 或 `wv screenshot`
+- 不要把小程序运行时截图退化成通用浏览器截图
+- 需要看 DevTools 终端日志时，优先使用 `weapp-vite ide logs --open` 或 `wv ide logs --open`
+
+`dist/docs` 当前会内置这些文件：
+
+- `README.md`
+- `getting-started.md`
+- `ai-workflows.md`
+- `project-structure.md`
+- `weapp-config.md`
+- `wevu-authoring.md`
+- `vue-sfc.md`
+- `troubleshooting.md`
+- `mcp.md`
+- `volar.md`
+- `define-config-overloads.md`
+- `index.md`
+
+推荐的截图命令示例：
+
+```sh
+weapp-vite screenshot --project ./dist/build/mp-weixin --page pages/index/index --output .tmp/acceptance.png --json
+
+# 等价写法
+wv screenshot --project ./dist/build/mp-weixin --page pages/index/index --output .tmp/acceptance.png --json
+```
+
 ## DevTools 日志桥接
 
 `weapp-vite` 现在支持把微信开发者工具里的小程序 `console` 输出桥接到当前终端。
@@ -116,6 +154,9 @@ export default defineConfig({
 ```sh
 weapp-vite ide logs
 weapp-vite ide logs --open
+# 等价写法
+wv ide logs
+wv ide logs --open
 ```
 
 ## CLI 中调用 weapp-ide-cli
@@ -127,6 +168,8 @@ weapp-vite preview --project ./dist/build/mp-weixin
 weapp-vite upload --project ./dist/build/mp-weixin -v 1.0.0 -d "release"
 weapp-vite config lang zh
 weapp-vite navigate pages/index/index --project ./dist/build/mp-weixin
+# 等价写法
+wv preview --project ./dist/build/mp-weixin
 ```
 
 也支持命名空间写法：
@@ -135,6 +178,8 @@ weapp-vite navigate pages/index/index --project ./dist/build/mp-weixin
 weapp-vite ide preview --project ./dist/build/mp-weixin
 weapp-vite ide config show
 weapp-vite ide logs --open
+# 等价写法
+wv ide preview --project ./dist/build/mp-weixin
 ```
 
 ## CLI 启动 MCP
@@ -146,12 +191,16 @@ weapp-vite ide logs --open
 
 ```sh
 weapp-vite mcp
+# 等价写法
+wv mcp
 ```
 
 指定工作区根路径：
 
 ```sh
 weapp-vite mcp --workspace-root /absolute/path/to/weapp-vite
+# 等价写法
+wv mcp --workspace-root /absolute/path/to/weapp-vite
 ```
 
 在 `vite.config.ts` 中开启自动启动：

package/dist/auto-import-components/resolvers.mjs

@@ -18,6 +18,7 @@ var tdesign_default = [
 	"collapse",
 	"collapse-panel",
 	"color-picker",
+	"config-provider",
 	"count-down",
 	"date-time-picker",
 	"dialog",

package/dist/auto-routes.mjs

@@ -1,4 +1,4 @@
-import { i as getCompilerContext, l as getRouteRuntimeGlobalKeys } from "./createContext-Cy_160Dm.mjs";
+import { i as getCompilerContext, l as getRouteRuntimeGlobalKeys } from "./createContext-f0OMYoia.mjs";
 //#region src/auto-routes.ts
 const ROUTE_RUNTIME_OVERRIDE_KEY = Symbol.for("weapp-vite.route-runtime");
 function createGetter(resolver) {

package/dist/cli.mjs

@@ -1,16 +1,16 @@
-import { _ as normalizeMiniPlatform, b as isPathInside, c as SHARED_CHUNK_VIRTUAL_PREFIX, d as checkRuntime, f as getProjectConfigFileName, g as getDefaultIdeProjectRoot, h as DEFAULT_MP_PLATFORM, m as createCjsConfigLoadError, n as syncProjectSupportFiles, o as formatBytes, p as parseCommentJson, r as syncManagedTsconfigBootstrapFiles, s as createSharedBuildConfig, t as createCompilerContext, u as resolveWeappConfigFile, v as resolveMiniPlatform, y as shouldPassPlatformArgToIdeOpen } from "./createContext-Cy_160Dm.mjs";
+import { _ as getDefaultIdeProjectRoot, b as shouldPassPlatformArgToIdeOpen, c as SHARED_CHUNK_VIRTUAL_PREFIX, d as checkRuntime, f as getProjectConfigFileName, g as DEFAULT_MP_PLATFORM, h as createCjsConfigLoadError, m as parseCommentJson, n as syncProjectSupportFiles, o as formatBytes, p as loadViteConfigFile, r as syncManagedTsconfigBootstrapFiles, s as createSharedBuildConfig, t as createCompilerContext, u as resolveWeappConfigFile, v as normalizeMiniPlatform, x as isPathInside, y as resolveMiniPlatform } from "./createContext-f0OMYoia.mjs";
 import { r as logger_default, t as colors } from "./logger-gutcwWKE.mjs";
-import { p as VERSION } from "./file-DKg072cZ.mjs";
+import { p as VERSION } from "./file-DRs69M1m.mjs";
 import { resolveWeappMcpConfig, startWeappViteMcpServer } from "./mcp.mjs";
 import { createRequire } from "node:module";
 import { defu } from "@weapp-core/shared";
 import path, { posix } from "pathe";
 import fs from "fs-extra";
 import process from "node:process";
-import { build, createServer, loadConfigFromFile } from "vite";
+import fs$1 from "node:fs/promises";
+import { build, createServer } from "vite";
 import { execFile } from "node:child_process";
 import { Buffer } from "node:buffer";
-import fs$1 from "node:fs/promises";
 import fs$2 from "node:fs";
 import { cac } from "cac";
 import { resolveCommand } from "package-manager-detector/commands";
@@ -1289,7 +1289,7 @@ async function loadConfig(configFile) {
 	};
 	let loaded;
 	try {
-		loaded = await loadConfigFromFile(configEnv, resolvedConfigFile, cwd, void 0, void 0, "runner");
+		loaded = await loadViteConfigFile(configEnv, resolvedConfigFile, cwd, void 0, void 0, "runner");
 	} catch (error) {
 		const cjsError = createCjsConfigLoadError({
 			error,
@@ -1309,7 +1309,7 @@ async function loadConfig(configFile) {
 		const normalizedLoadedPath = loaded?.path ? path.resolve(loaded.path) : void 0;
 		if (normalizedLoadedPath && normalizedLoadedPath === normalizedWeappPath) weappLoaded = loaded;
 		else try {
-			weappLoaded = await loadConfigFromFile(configEnv, weappConfigFilePath, cwd, void 0, void 0, "runner");
+			weappLoaded = await loadViteConfigFile(configEnv, weappConfigFilePath, cwd, void 0, void 0, "runner");
 		} catch (error) {
 			const cjsError = createCjsConfigLoadError({
 				error,

package/dist/{config-Av2eTTDE.d.mts → config-DKt372Bv.d.mts}

@@ -3,8 +3,8 @@ import { t as AutoRoutes } from "./routes-DUBjYF43.mjs";
 import { LRUCache } from "lru-cache";
 import { LoggerConfig } from "@weapp-core/logger";
 import { WeappAstConfig } from "@weapp-vite/ast";
-import { fdir } from "fdir";
 import { ConfigEnv, ConfigEnv as ConfigEnv$1, InlineConfig, InlineConfig as InlineConfig$1, Plugin as Plugin$1, PluginOption, ResolvedConfig, UserConfig, ViteDevServer, ViteDevServer as ViteDevServer$1, build } from "vite";
+import { fdir } from "fdir";
 import { InputOption, RolldownBuild, RolldownOptions, RolldownOutput, RolldownOutput as RolldownOutput$1, RolldownPlugin, RolldownPluginOption, RolldownWatcher, RolldownWatcher as RolldownWatcher$1, WatchOptions as RolldownWatchOptions } from "rolldown";
 import { Options } from "rolldown-plugin-dts";
 import { Buffer } from "node:buffer";

package/dist/config.d.mts

@@ -1,2 +1,2 @@
-import { An as resolveWeappViteHostMeta, Dn as applyWeappViteHostMeta, En as WeappViteRuntime, On as createWeappViteHostMeta, Tn as WeappViteHostMeta, _ as definePageJson, a as UserConfigFnNoEnvPlain, c as UserConfigFnPromise, d as Component, f as Page, g as defineComponentJson, h as defineAppJson, i as UserConfigFnNoEnv, kn as isWeappViteHost, l as defineConfig, m as Theme, n as UserConfigExport, nt as WeappViteConfig, o as UserConfigFnObject, p as Sitemap, r as UserConfigFn, s as UserConfigFnObjectPlain, t as UserConfig, u as App, v as defineSitemapJson, wn as WEAPP_VITE_HOST_NAME, y as defineThemeJson } from "./config-Av2eTTDE.mjs";
+import { An as resolveWeappViteHostMeta, Dn as applyWeappViteHostMeta, En as WeappViteRuntime, On as createWeappViteHostMeta, Tn as WeappViteHostMeta, _ as definePageJson, a as UserConfigFnNoEnvPlain, c as UserConfigFnPromise, d as Component, f as Page, g as defineComponentJson, h as defineAppJson, i as UserConfigFnNoEnv, kn as isWeappViteHost, l as defineConfig, m as Theme, n as UserConfigExport, nt as WeappViteConfig, o as UserConfigFnObject, p as Sitemap, r as UserConfigFn, s as UserConfigFnObjectPlain, t as UserConfig, u as App, v as defineSitemapJson, wn as WEAPP_VITE_HOST_NAME, y as defineThemeJson } from "./config-DKt372Bv.mjs";
 export { App, Component, Page, Sitemap, Theme, UserConfig, UserConfigExport, UserConfigFn, UserConfigFnNoEnv, UserConfigFnNoEnvPlain, UserConfigFnObject, UserConfigFnObjectPlain, UserConfigFnPromise, WEAPP_VITE_HOST_NAME, WeappViteConfig, WeappViteHostMeta, WeappViteRuntime, applyWeappViteHostMeta, createWeappViteHostMeta, defineAppJson, defineComponentJson, defineConfig, definePageJson, defineSitemapJson, defineThemeJson, isWeappViteHost, resolveWeappViteHostMeta };

package/dist/{createContext-Cy_160Dm.mjs → createContext-f0OMYoia.mjs}

@@ -1,7 +1,7 @@
 import { t as __exportAll } from "./rolldown-runtime-twds-ZHy.mjs";
 import { n as applyWeappViteHostMeta } from "./pluginHost-SJdl15d3.mjs";
 import { n as configureLogger, r as logger_default } from "./logger-gutcwWKE.mjs";
-import { _ as templateExtensions, a as findJsEntry, c as findVueEntry, d as isTemplate, f as touch, g as supportedCssLangs, h as jsExtensions, i as findCssEntry, l as inlineAutoRoutesImports, m as configExtensions, n as extractConfigFromVue, o as findJsonEntry, s as findTemplateEntry, t as changeFileExtension, u as isJsOrTs, v as vueExtensions } from "./file-DKg072cZ.mjs";
+import { _ as templateExtensions, a as findJsEntry, c as findVueEntry, d as isTemplate, f as touch, g as supportedCssLangs, h as jsExtensions, i as findCssEntry, l as inlineAutoRoutesImports, m as configExtensions, n as extractConfigFromVue, o as findJsonEntry, s as findTemplateEntry, t as changeFileExtension, u as isJsOrTs, v as vueExtensions } from "./file-DRs69M1m.mjs";
 import { createRequire, isBuiltin } from "node:module";
 import { addExtension, defu, get, isEmptyObject, isObject, objectHash, removeExtension, removeExtensionDeep, set } from "@weapp-core/shared";
 import { LRUCache } from "lru-cache";
@@ -18,20 +18,20 @@ import picomatch from "picomatch";
 import { VUE_COMPONENT_TAG_RE, WE_VU_MODULE_ID, WE_VU_RUNTIME_APIS, buildClassStyleComputedCode, collectVueTemplateTags, compileJsxFile, compileVueFile, createJsonMerger, createPageEntryMatcher, createPageEntryMatcher as createPageEntryMatcher$1, getClassStyleWxsSource, getMiniProgramTemplatePlatform, getSfcCheckMtime, injectWevuPageFeaturesInJsWithResolver, invalidateFileCache, isAutoImportCandidateTag, isBuiltinComponent, pathExists, readAndParseSfc, readFile as readFile$1, resolveClassStyleWxsLocation } from "wevu/compiler";
 import process from "node:process";
 import { parse as parse$1, stringify } from "comment-json";
+import fs$1, { readFile, readdir, rm } from "node:fs/promises";
+import { build, createServer, loadConfigFromFile, preprocessCSS } from "vite";
 import { createHash } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import semverGte from "semver/functions/gte.js";
 import semverSatisfies from "semver/functions/satisfies.js";
 import semverValid from "semver/functions/valid.js";
 import { fdir } from "fdir";
-import { build, createServer, loadConfigFromFile, preprocessCSS } from "vite";
 import { build as build$1 } from "rolldown";
 import { dts } from "rolldown-plugin-dts";
 import os from "node:os";
 import { getPackageInfo, getPackageInfoSync, resolveModule } from "local-pkg";
 import { spawn } from "node:child_process";
 import { Buffer } from "node:buffer";
-import fs$1, { readFile, readdir, rm } from "node:fs/promises";
 import fs$2, { existsSync } from "node:fs";
 import chokidar from "chokidar";
 import { detect } from "package-manager-detector/detect";
@@ -225,7 +225,9 @@ function createEnabledAutoImportComponents(configService) {
 	return {
 		...defaults,
 		globs: [...globs],
+		output: true,
 		typedComponents: true,
+		htmlCustomData: true,
 		vueComponents: true,
 		vueComponentsModule: hasWevuDependency$1(configService) ? "wevu" : void 0
 	};
@@ -4706,6 +4708,30 @@ function resolveJson(entry, aliasEntries, platform, options) {
 	}
 }
 //#endregion
+//#region src/utils/loadViteConfigFile.ts
+const DEFAULT_VITE_CONFIG_FILES = [
+	"vite.config.ts",
+	"vite.config.mts",
+	"vite.config.cts",
+	"vite.config.js",
+	"vite.config.mjs",
+	"vite.config.cjs"
+];
+async function resolveImplicitConfigFile(configRoot) {
+	for (const fileName of DEFAULT_VITE_CONFIG_FILES) {
+		const filePath = path.resolve(configRoot, fileName);
+		try {
+			await fs$1.access(filePath);
+			return filePath;
+		} catch {
+			continue;
+		}
+	}
+}
+async function loadViteConfigFile(configEnv, configFile, configRoot, configFileDependencies, configFileExport, configLoader, runner) {
+	return loadConfigFromFile(configEnv, configFile ?? await resolveImplicitConfigFile(configRoot), configRoot, configFileDependencies, configFileExport, configLoader ?? "bundle", runner);
+}
+//#endregion
 //#region src/utils/projectConfig.ts
 const DEFAULT_PROJECT_PRIVATE_CONFIG_FILE_NAME = "project.private.config.json";
 function getProjectConfigFileName(platform) {
@@ -9493,7 +9519,7 @@ function createLoadConfig(options) {
 		});
 		let loaded;
 		try {
-			loaded = await loadConfigFromFile({
+			loaded = await loadViteConfigFile({
 				command: isDev ? "serve" : "build",
 				mode
 			}, resolvedConfigFile, cwd, void 0, void 0, "runner");
@@ -9510,7 +9536,7 @@ function createLoadConfig(options) {
 		let weappLoaded;
 		if (weappConfigFilePath) if (shouldReuseLoadedWeappConfig(weappConfigFilePath, loaded?.path)) weappLoaded = loaded;
 		else try {
-			weappLoaded = await loadConfigFromFile({
+			weappLoaded = await loadViteConfigFile({
 				command: isDev ? "serve" : "build",
 				mode
 			}, weappConfigFilePath, cwd, void 0, void 0, "runner");
@@ -18283,6 +18309,9 @@ function resolveNpmDistDirName(configService) {
 	if (configService?.platform) return getPlatformNpmDistDirName(configService.platform, { alipayNpmMode: configService.weappViteConfig?.npm?.alipayNpmMode });
 	return getPlatformNpmDistDirName("weapp");
 }
+function resolveNpmSourceCacheOutDir(cwd, npmDistDirName) {
+	return path.resolve(cwd, ".weapp-vite/npm-source", npmDistDirName);
+}
 function createNpmService(ctx) {
 	const oxcVitePlugin = createOxcRuntimeSupport().vitePlugin;
 	const cache = createDependenciesCache(ctx);
@@ -18300,7 +18329,7 @@ function createNpmService(ctx) {
 			const pkgJson = await fs.readJson(packageJsonPath);
 			const npmDistDirName = resolveNpmDistDirName(ctx.configService);
 			const outDir = path.resolve(ctx.configService.cwd, mainRelation.miniprogramNpmDistDir, npmDistDirName);
-			const cachedSourceOutDir = path.resolve(ctx.configService.cwd, "node_modules/weapp-vite/.cache/npm-source", npmDistDirName);
+			const cachedSourceOutDir = resolveNpmSourceCacheOutDir(ctx.configService.cwd, npmDistDirName);
 			const localSubPackageOutRoot = ctx.configService.outDir || path.resolve(ctx.configService.cwd, mainRelation.miniprogramNpmDistDir);
 			if (pkgJson.dependencies) {
 				const allDependencies = Object.keys(pkgJson.dependencies);
@@ -18343,7 +18372,7 @@ function createNpmService(ctx) {
 					await fs.remove(targetDir);
 					await fs.copy(outDir, targetDir, { overwrite: true });
 				}));
-				await Promise.all(Array.from(localSubPackageMetas, async (meta) => {
+				for (const meta of localSubPackageMetas) {
 					const targetDir = path.resolve(localSubPackageOutRoot, meta.subPackage.root, npmDistDirName);
 					if (await cache.checkDependenciesCacheOutdate(meta.subPackage.root) || !await fs.pathExists(targetDir)) {
 						await fs.remove(targetDir);
@@ -18360,7 +18389,7 @@ function createNpmService(ctx) {
 						});
 					}
 					await cache.writeDependenciesCache(meta.subPackage.root);
-				}));
+				}
 			}
 		}
 		debug$2?.("buildNpm end");
@@ -18948,7 +18977,7 @@ function createScanService(ctx) {
 		let vueAppPath;
 		if (!appEntryPath) vueAppPath = await findVueEntry(appBasename);
 		if (!appConfigFile && vueAppPath) {
-			const { extractConfigFromVue } = await import("./file-DKg072cZ.mjs").then((n) => n.r);
+			const { extractConfigFromVue } = await import("./file-DRs69M1m.mjs").then((n) => n.r);
 			configFromVue = await extractConfigFromVue(vueAppPath);
 			if (configFromVue) appConfigFile = vueAppPath;
 		}
@@ -19718,4 +19747,4 @@ async function createCompilerContext(options) {
 	return ctx;
 }
 //#endregion
-export { normalizeMiniPlatform as _, getInstance_exports as a, isPathInside as b, SHARED_CHUNK_VIRTUAL_PREFIX as c, checkRuntime as d, getProjectConfigFileName as f, getDefaultIdeProjectRoot as g, DEFAULT_MP_PLATFORM as h, getCompilerContext as i, getRouteRuntimeGlobalKeys as l, createCjsConfigLoadError as m, syncProjectSupportFiles as n, formatBytes as o, parseCommentJson as p, syncManagedTsconfigBootstrapFiles as r, createSharedBuildConfig as s, createCompilerContext as t, resolveWeappConfigFile as u, resolveMiniPlatform as v, shouldPassPlatformArgToIdeOpen as y };
+export { getDefaultIdeProjectRoot as _, getInstance_exports as a, shouldPassPlatformArgToIdeOpen as b, SHARED_CHUNK_VIRTUAL_PREFIX as c, checkRuntime as d, getProjectConfigFileName as f, DEFAULT_MP_PLATFORM as g, createCjsConfigLoadError as h, getCompilerContext as i, getRouteRuntimeGlobalKeys as l, parseCommentJson as m, syncProjectSupportFiles as n, formatBytes as o, loadViteConfigFile as p, syncManagedTsconfigBootstrapFiles as r, createSharedBuildConfig as s, createCompilerContext as t, resolveWeappConfigFile as u, normalizeMiniPlatform as v, isPathInside as x, resolveMiniPlatform as y };

package/dist/docs/README.md

@@ -0,0 +1,237 @@
+<div align="center">
+  <a href="https://vite.icebreaker.top">
+    <img width="200" height="200" hspace="10" src="https://vite.icebreaker.top/logo.png" alt="vite logo" />
+  </a>
+  <h1>Weapp Vite</h1>
+  <p>
+    给小程序以现代化的开发体验
+  </p>
+  <img src="https://img.shields.io/node/v/weapp-vite" alt="node-current" />
+  <img src="https://img.shields.io/npm/dependency-version/weapp-vite/peer/vite" alt="npm peer dependency version" />
+  <img src="https://img.shields.io/github/v/release/weapp-vite/weapp-vite" alt="GitHub release" />
+  <img src="https://img.shields.io/npm/l/weapp-vite" alt="licence" />
+</div>
+
+<p>&nbsp;</p>
+
+## 使用文档地址: [vite.icebreaker.top](https://vite.icebreaker.top)
+
+## Features
+
+- 🚀 **Vue 3 支持**：完整的 Vue 单文件组件（SFC）支持，使用 Vue 官方编译器
+  - `<script setup>` 和 TypeScript 完整支持
+  - 完整的模板语法（v-if、v-for、v-model 等）
+  - Scoped CSS 和 CSS Modules
+  - 动态组件、过渡动画、KeepAlive
+  - [详细文档 →](./test/vue/README.md)
+
+- ⚡️ **Vite 构建**：带来了 `typescript` / `scss` / `less` 等等的原生支持
+- 🔌 **插件生态**：Vite 插件生态支持，也可以自定义编写插件，方便扩展
+- 🧰 **IDE 命令增强**：可直接透传 `weapp-ide-cli` 全量命令（`preview/upload/config/automator` 等）
+
+## 快速开始
+
+> 说明：CLI 同时支持完整命令 `weapp-vite` 与简写命令 `wv`，两者等价。下面的示例默认使用 `weapp-vite`，你也可以按个人习惯替换成 `wv`。
+
+### Vue 项目
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'weapp-vite/config'
+
+export default defineConfig({
+  weapp: {
+    srcRoot: 'src',
+    vue: {
+      enable: true,
+      template: {
+        removeComments: true,
+      },
+    },
+  },
+})
+```
+
+```vue
+<!-- App.vue -->
+<script setup>
+import { ref } from 'vue'
+
+const message = ref('Hello Vue in Mini-program!')
+
+function handleClick() {
+  console.log('Button clicked!')
+}
+</script>
+
+<template>
+  <view class="container">
+    <text>{{ message }}</text>
+    <button @click="handleClick">
+      Click
+    </button>
+  </view>
+</template>
+
+<style scoped>
+.container {
+  padding: 20rpx;
+}
+</style>
+```
+
+📚 **完整文档**: [Vue 支持文档](./test/vue/README.md)
+
+- 配置智能提示文档：[docs/volar.md](./docs/volar.md)
+- defineConfig 重载说明：[docs/define-config-overloads.md](./docs/define-config-overloads.md)
+- Vite 插件识别 weapp-vite 宿主：https://vite.icebreaker.top/guide/vite-plugin-host
+- MCP 集成使用指南：[docs/mcp.md](./docs/mcp.md)
+
+## AI 项目指引
+
+通过 `create-weapp-vite` 创建的新项目，现在会默认携带一个根目录 `AGENTS.md`。同时，`weapp-vite` npm 包会随版本发布一份本地文档目录：`node_modules/weapp-vite/dist/docs/`。
+
+这个文件会告诉常见 AI 编程代理：
+
+- 安装依赖后，优先阅读 `node_modules/weapp-vite/dist/docs/README.md`、`node_modules/weapp-vite/dist/docs/mcp.md` 等本地版本文档
+- CLI 同时支持 `weapp-vite` 与 `wv`
+- 需要做小程序截图验收时，优先使用 `weapp-vite screenshot` 或 `wv screenshot`
+- 不要把小程序运行时截图退化成通用浏览器截图
+- 需要看 DevTools 终端日志时，优先使用 `weapp-vite ide logs --open` 或 `wv ide logs --open`
+
+`dist/docs` 当前会内置这些文件：
+
+- `README.md`
+- `getting-started.md`
+- `ai-workflows.md`
+- `project-structure.md`
+- `weapp-config.md`
+- `wevu-authoring.md`
+- `vue-sfc.md`
+- `troubleshooting.md`
+- `mcp.md`
+- `volar.md`
+- `define-config-overloads.md`
+- `index.md`
+
+推荐的截图命令示例：
+
+```sh
+weapp-vite screenshot --project ./dist/build/mp-weixin --page pages/index/index --output .tmp/acceptance.png --json
+
+# 等价写法
+wv screenshot --project ./dist/build/mp-weixin --page pages/index/index --output .tmp/acceptance.png --json
+```
+
+## DevTools 日志桥接
+
+`weapp-vite` 现在支持把微信开发者工具里的小程序 `console` 输出桥接到当前终端。
+
+默认行为：
+
+- `weapp.forwardConsole` 默认是 `enabled: 'auto'`
+- 当检测到当前运行环境是 AI 终端时，`weapp-vite dev --open` 会自动尝试附加日志桥
+- 也可以手动进入持续监听模式
+
+配置示例：
+
+```ts
+import { defineConfig } from 'weapp-vite/config'
+
+export default defineConfig({
+  weapp: {
+    forwardConsole: {
+      enabled: 'auto',
+      logLevels: ['log', 'info', 'warn', 'error'],
+      unhandledErrors: true,
+    },
+  },
+})
+```
+
+手动启动持续监听：
+
+```sh
+weapp-vite ide logs
+weapp-vite ide logs --open
+# 等价写法
+wv ide logs
+wv ide logs --open
+```
+
+## CLI 中调用 weapp-ide-cli
+
+`weapp-vite` 内置了对 `weapp-ide-cli` 的透传能力，除了 `dev/build/open/init/generate/analyze/npm` 等原生命令外，其它 IDE 相关命令都可以直接调用：
+
+```sh
+weapp-vite preview --project ./dist/build/mp-weixin
+weapp-vite upload --project ./dist/build/mp-weixin -v 1.0.0 -d "release"
+weapp-vite config lang zh
+weapp-vite navigate pages/index/index --project ./dist/build/mp-weixin
+# 等价写法
+wv preview --project ./dist/build/mp-weixin
+```
+
+也支持命名空间写法：
+
+```sh
+weapp-vite ide preview --project ./dist/build/mp-weixin
+weapp-vite ide config show
+weapp-vite ide logs --open
+# 等价写法
+wv ide preview --project ./dist/build/mp-weixin
+```
+
+## CLI 启动 MCP
+
+`weapp-vite` 已集成 `@weapp-vite/mcp`：
+
+- 默认不自动启动 MCP 服务（可通过配置开启自动启动）
+- 也可以手动启动 MCP Server
+
+```sh
+weapp-vite mcp
+# 等价写法
+wv mcp
+```
+
+指定工作区根路径：
+
+```sh
+weapp-vite mcp --workspace-root /absolute/path/to/weapp-vite
+# 等价写法
+wv mcp --workspace-root /absolute/path/to/weapp-vite
+```
+
+在 `vite.config.ts` 中开启自动启动：
+
+```ts
+import { defineConfig } from 'weapp-vite/config'
+
+export default defineConfig({
+  weapp: {
+    mcp: {
+      autoStart: true,
+    },
+  },
+})
+```
+
+详细说明见：[docs/mcp.md](./docs/mcp.md)
+
+## Contribute
+
+我们邀请你来贡献和帮助改进 `weapp-vite` 💚💚💚
+
+以下有几个方式可以参与:
+
+- 报告错误：如果您遇到任何错误或问题，请提`issue`并提供完善的错误信息和复现方式。
+- 建议：有增强 `weapp-vite` 的想法吗？请提 `issue` 来分享您的建议。
+- 文档：如果您对文档有更好的见解或者更棒的修辞方式，欢迎 `pr`。
+- 代码：任何人的代码都不是完美的，我们欢迎你通过 `pr` 给代码提供更好的质量与活力。
+
+## License
+
+[MIT](./LICENSE)
+
+<!-- "//------":""esbuild": "^0.21.3",", -->

package/dist/docs/ai-workflows.md

@@ -0,0 +1,64 @@
+# AI Workflows
+
+这个文档面向在其他仓库里使用 `weapp-vite` 的 AI 代理。
+
+## 首选信息源
+
+当项目已经安装了 `weapp-vite` 时，优先读取本地随包文档，而不是先看网站旧内容：
+
+1. `node_modules/weapp-vite/dist/docs/index.md`
+2. `node_modules/weapp-vite/dist/docs/README.md`
+3. `node_modules/weapp-vite/dist/docs/getting-started.md`
+4. `node_modules/weapp-vite/dist/docs/weapp-config.md`
+5. 按需继续阅读 `wevu-authoring.md`、`vue-sfc.md`、`troubleshooting.md`
+
+## 项目级约束
+
+如果项目由 `create-weapp-vite` 创建，根目录通常会有 `AGENTS.md`。
+
+应把它视为项目工作流契约，而不是可忽略的模板文件。优先同时遵守：
+
+1. 项目根 `AGENTS.md`
+2. `node_modules/weapp-vite/dist/docs/*.md`
+3. 当前仓库实际代码与 `vite.config.ts`
+
+## 常用 AI 命令
+
+CLI 同时支持完整命令 `weapp-vite` 与简写命令 `wv`，两者等价。
+
+常见工作流：
+
+```bash
+weapp-vite prepare
+weapp-vite dev --open
+weapp-vite build
+weapp-vite screenshot --project ./dist/build/mp-weixin --page pages/index/index --output .tmp/acceptance.png --json
+weapp-vite ide logs --open
+weapp-vite mcp
+```
+
+等价写法：
+
+```bash
+wv prepare
+wv dev --open
+wv build
+wv screenshot --project ./dist/build/mp-weixin --page pages/index/index --output .tmp/acceptance.png --json
+wv ide logs --open
+wv mcp
+```
+
+## 截图与日志
+
+- 小程序截图验收优先使用 `weapp-vite screenshot` / `wv screenshot`
+- 不要退化成普通浏览器截图来替代小程序运行时截图
+- 查看 DevTools 终端日志优先使用 `weapp-vite ide logs --open` / `wv ide logs --open`
+
+## 推荐阅读顺序
+
+- 项目初始化、命令和 AI 使用入口：[`getting-started.md`](./getting-started.md)
+- 项目目录与生成文件：[`project-structure.md`](./project-structure.md)
+- `vite.config.ts` 中的 `weapp` 配置：[`weapp-config.md`](./weapp-config.md)
+- wevu 页面、组件、store 写法：[`wevu-authoring.md`](./wevu-authoring.md)
+- Vue SFC 宏与模板约束：[`vue-sfc.md`](./vue-sfc.md)
+- 常见告警与排障：[`troubleshooting.md`](./troubleshooting.md)