weapp-vite 6.12.0 → 6.12.3

package/dist/docs/define-config-overloads.md

@@ -0,0 +1,108 @@
+# defineConfig 重载与类型推导说明
+
+本文用于说明 `weapp-vite/config` 中 `defineConfig` 的重载行为、推荐写法，以及为什么某些写法会影响编辑器里的 Hover 文档和跳转能力。
+
+## 目标
+
+`defineConfig` 的核心目标有两个：
+
+1. 让 `vite.config.ts` 中 `weapp` 配置获得稳定的字段提示与类型校验。
+2. 保留扩展能力（允许额外自定义字段），兼顾严格与灵活。
+
+## 支持的入参形态
+
+`defineConfig` 支持以下主要形态：
+
+1. **对象配置**：`defineConfig({ ... })`
+2. **Promise 对象配置**：`defineConfig(Promise.resolve({ ... }))`
+3. **无 env 同步函数**：`defineConfig(() => ({ ... }))`
+4. **无 env 异步函数**：`defineConfig(async () => ({ ... }))`
+5. **有 env 同步函数**：`defineConfig((env) => ({ ... }))`
+6. **有 env 异步函数**：`defineConfig(async (env) => ({ ... }))`
+7. **有 env 同步/异步混合返回**：`defineConfig((env) => env.command === 'build' ? Promise.resolve(...) : (...))`
+
+## 关键推导规则
+
+### 1) 重载顺序会直接影响编辑器体验
+
+在 TypeScript 中，函数重载按声明顺序匹配。
+
+为了保证 `vite.config.ts` 里对象字面量字段（例如 `weapp.srcRoot`）能拿到**上下文类型**，并正确展示 JSDoc / 支持跳转，需要把更“具体”的同步重载放在前面，避免过早命中宽泛的联合重载。
+
+### 2) 无 env 异步函数的返回值
+
+`defineConfig(async () => ({ ... }))` 对应 `() => UserConfig | Promise<UserConfig>` 的函数签名。
+
+这意味着调用返回函数时，类型是：
+
+- `UserConfig | Promise<UserConfig>`
+
+如果业务侧明确使用 `async`，建议按 Promise 分支处理。
+
+### 3) `UserConfigLoose` 的兜底行为
+
+`defineConfig` 允许对象中带额外字段（例如 `customFeature`），用于兼容插件场景。
+
+但使用这类“宽松扩展”时，额外字段会按更宽泛类型处理，建议：
+
+- 标准字段走官方类型（如 `weapp.srcRoot`）
+- 自定义字段尽量在项目内补充独立类型约束
+
+## 推荐写法
+
+### 推荐：无 env 同步函数（最稳定）
+
+```ts
+import { defineConfig } from 'weapp-vite/config'
+
+export default defineConfig(() => ({
+  weapp: {
+    srcRoot: 'src',
+  },
+}))
+```
+
+### 推荐：有 env 分支
+
+```ts
+import { defineConfig } from 'weapp-vite/config'
+
+export default defineConfig(env => ({
+  weapp: {
+    srcRoot: env.command === 'build' ? 'src-build' : 'src-dev',
+  },
+}))
+```
+
+### 谨慎：过度动态的混合返回
+
+```ts
+import { defineConfig } from 'weapp-vite/config'
+
+export default defineConfig((env) => {
+  if (env.command === 'build') {
+    return Promise.resolve({ weapp: { srcRoot: 'src-build' } })
+  }
+  return { weapp: { srcRoot: 'src-dev' } }
+})
+```
+
+这种写法可用，但返回类型会变成联合类型，调用侧需要兼容两种分支。
+
+## 常见问题排查
+
+### Hover 无文档、Command+Click 不能跳转
+
+优先检查：
+
+1. 是否使用了 `import { defineConfig } from 'weapp-vite/config'`
+2. 是否在 `tsconfig.node.json` 中包含 `vite.config.ts`
+3. 是否命中过于宽泛的重载（会导致字段退化为局部字面量推断）
+4. 依赖是否已安装且类型入口可解析
+
+## 回归测试
+
+以下测试用于确保上述行为稳定：
+
+- `packages/weapp-vite/test/config-intellisense.test.ts`
+- `packages/weapp-vite/test-d/config-defineConfig.test-d.ts`

package/dist/docs/getting-started.md

@@ -0,0 +1,74 @@
+# Getting Started
+
+## CLI 别名
+
+`weapp-vite` 和 `wv` 完全等价。
+
+```bash
+weapp-vite build
+wv build
+```
+
+## 最小工作流
+
+### 1. 准备支持文件
+
+```bash
+weapp-vite prepare
+```
+
+如果项目里存在 `.weapp-vite` 支持文件缺失或过期，这一步会更新它们。
+
+### 2. 本地开发
+
+```bash
+weapp-vite dev
+weapp-vite dev --open
+```
+
+如果需要打开微信开发者工具并把日志桥接回终端，可使用：
+
+```bash
+weapp-vite dev --open
+weapp-vite ide logs --open
+```
+
+### 3. 构建
+
+```bash
+weapp-vite build
+```
+
+### 4. 截图验收
+
+```bash
+weapp-vite screenshot --project ./dist/build/mp-weixin --page pages/index/index --output .tmp/acceptance.png --json
+```
+
+### 5. 启动 MCP
+
+```bash
+weapp-vite mcp
+```
+
+## 何时先读哪些文档
+
+- 命令、脚手架、AI 工作流：[`ai-workflows.md`](./ai-workflows.md)
+- 目录结构、`AGENTS.md`、`.weapp-vite`：[`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 宏、`definePageMeta`、`v-model`：[`vue-sfc.md`](./vue-sfc.md)
+
+## 常见命令
+
+```bash
+weapp-vite dev
+weapp-vite dev --open
+weapp-vite build
+weapp-vite open
+weapp-vite preview --project ./dist/build/mp-weixin
+weapp-vite ide preview --project ./dist/build/mp-weixin
+weapp-vite ide logs --open
+weapp-vite screenshot --project ./dist/build/mp-weixin --page pages/index/index --output .tmp/acceptance.png --json
+weapp-vite mcp
+```

package/dist/docs/index.md

@@ -0,0 +1,30 @@
+# weapp-vite dist docs
+
+这个目录会随 `weapp-vite` npm 包一起发布，供 AI 代理和开发者优先读取与当前包版本匹配的本地文档。
+
+这不是 `website` 的完整镜像，而是面向 AI 与离线开发场景的精简本地知识包。
+
+推荐顺序：
+
+1. 先读 `README.md` 与 `getting-started.md` 获取总体能力与常用命令。
+2. 涉及 AI / MCP / screenshot / DevTools logs 时读 `ai-workflows.md` 与 `mcp.md`。
+3. 涉及项目目录、`AGENTS.md`、`.weapp-vite` 时读 `project-structure.md`。
+4. 涉及 `vite.config.ts`、`weapp` 配置与 chunk 策略时读 `weapp-config.md`。
+5. 涉及 wevu 运行时与页面/组件/store 约束时读 `wevu-authoring.md`。
+6. 涉及 Vue SFC 宏、模板约束与编辑器提示时读 `vue-sfc.md`、`volar.md` 与 `define-config-overloads.md`。
+7. 遇到告警、prepare、截图、日志、依赖异常时读 `troubleshooting.md`。
+
+## Included Docs
+
+- `README.md`: weapp-vite npm 包内置文档入口，供 AI 与开发者优先读取本地版本说明。
+- `mcp.md`: MCP、AI 工作流与 screenshot 验收说明。
+- `volar.md`: Volar、JSON 宏与编辑器智能提示支持说明。
+- `define-config-overloads.md`: defineConfig 类型重载与配置推导说明。
+- `getting-started.md`: CLI 命令、prepare、build、screenshot、MCP 等快速入口。
+- `ai-workflows.md`: AI 代理在其他仓库里使用 weapp-vite 的推荐工作流。
+- `project-structure.md`: AGENTS.md、.weapp-vite、dist 与源码目录的职责说明。
+- `weapp-config.md`: weapp 配置、autoRoutes、autoImportComponents、routeRules 与 chunk 策略。
+- `wevu-authoring.md`: wevu 页面、组件、store、router 与事件契约的推荐写法。
+- `vue-sfc.md`: definePageJson、definePageMeta、v-model 与模板兼容约束。
+- `troubleshooting.md`: prepare、截图、日志、wevu 依赖与 dist 同步等常见排障。
+

package/dist/docs/mcp.md

@@ -0,0 +1,230 @@
+# weapp-vite MCP 集成使用指南
+
+## 1. 能力概览
+
+`weapp-vite` 现在内置了对 `weapp-vite/mcp` 的集成，支持直接通过 `weapp-vite mcp` 启动 MCP Server（`stdio` 传输）。
+
+如果你是在其他仓库里通过 npm 依赖使用 `weapp-vite`，建议先让 AI 读取本地随包文档目录：
+
+- `node_modules/weapp-vite/dist/docs/index.md`
+- `node_modules/weapp-vite/dist/docs/README.md`
+- `node_modules/weapp-vite/dist/docs/mcp.md`
+
+这样可以优先命中与当前安装版本一致的本地说明，而不是依赖可能过期的外部网页或模型记忆。
+
+这个 MCP Server 主要面向 AI 编程助手，暴露了 `weapp-vite / wevu / wevu-compiler` 的关键研发能力：
+
+1. 工作区能力目录（版本、脚本、文档）
+2. 源码文件列表、按行读取、全文检索
+3. 包级脚本执行（`pnpm run`）
+4. `weapp-vite` CLI 调用
+5. 仓库级受限命令执行（`pnpm/node/git/rg`）
+6. 面向改造和排障的标准 Prompt 模板
+
+## 2. 启动方式
+
+### 2.0 CLI 自动启动（默认关闭）
+
+默认情况下，`weapp-vite` 不会在 CLI 启动时自动拉起 MCP 服务。
+如果你希望开发命令执行时自动拉起本地 MCP HTTP 服务（`streamable-http`），可在 `vite.config.ts` 显式开启：
+
+```ts
+import { defineConfig } from 'weapp-vite/config'
+
+export default defineConfig({
+  weapp: {
+    mcp: {
+      enabled: true,
+      autoStart: true,
+    },
+  },
+})
+```
+
+默认地址：
+
+- `http://127.0.0.1:3088/mcp`
+
+完全关闭 MCP：
+
+```ts
+import { defineConfig } from 'weapp-vite/config'
+
+export default defineConfig({
+  weapp: {
+    mcp: false,
+  },
+})
+```
+
+### 2.1 CLI 启动（推荐）
+
+在 monorepo 根目录或任意子目录执行：
+
+```bash
+weapp-vite mcp
+```
+
+可选指定工作区根路径：
+
+```bash
+weapp-vite mcp --workspace-root /path/to/weapp-vite
+```
+
+以 HTTP 方式手动启动：
+
+```bash
+weapp-vite mcp --transport streamable-http --host 127.0.0.1 --port 3088 --endpoint /mcp
+```
+
+说明：
+
+1. 不传 `--workspace-root` 时，会从当前目录向上自动定位 `pnpm-workspace.yaml`。
+2. `--transport stdio` 通过标准输入输出通信，不会启动 HTTP 端口。
+3. `--transport streamable-http` 会启动本地 HTTP 服务，可供支持 URL 连接的 MCP Client 使用。
+
+### 2.2 程序化启动
+
+`weapp-vite` 暴露了 `weapp-vite/mcp` 子路径，可直接在 Node 脚本中使用。
+
+```ts
+import { startWeappViteMcpServer } from 'weapp-vite/mcp'
+
+await startWeappViteMcpServer({
+  workspaceRoot: process.cwd(),
+})
+```
+
+如果你需要自定义生命周期，继续通过 `weapp-vite/mcp` 即可：
+
+```ts
+import { startStdioServer } from 'weapp-vite/mcp'
+
+await startStdioServer({
+  workspaceRoot: process.cwd(),
+})
+```
+
+如果你需要手动控制 `stdio` / `streamable-http` 两种 transport，也可以直接调用：
+
+```ts
+import { startWeappViteMcpServer } from 'weapp-vite/mcp'
+
+const handle = await startWeappViteMcpServer({
+  workspaceRoot: process.cwd(),
+  transport: 'streamable-http',
+  host: '127.0.0.1',
+  port: 3088,
+  endpoint: '/mcp',
+})
+
+await handle.close?.()
+```
+
+## 3. 客户端接入示例
+
+以下是通用的 MCP Client `stdio` 配置示例，请按你的客户端格式调整字段名：
+
+```json
+{
+  "mcpServers": {
+    "weapp-vite": {
+      "command": "weapp-vite",
+      "args": [
+        "mcp",
+        "--workspace-root",
+        "/absolute/path/to/weapp-vite"
+      ]
+    }
+  }
+}
+```
+
+如果你是仓库开发者，也可以直接指向本地脚本命令（例如 `pnpm` 脚本）来启动同一服务。
+
+## 4. 可用 Tools
+
+1. `workspace_catalog`
+2. `list_source_files`
+3. `read_source_file`
+4. `search_source_code`
+5. `run_package_script`
+6. `run_weapp_vite_cli`
+7. `run_repo_command`
+
+建议使用顺序：
+
+1. 先调用 `workspace_catalog` 获取可操作包与脚本。
+2. 再用 `search_source_code` / `read_source_file` 做定位。
+3. 最后用 `run_package_script` 或 `run_repo_command` 做验证。
+
+## 5. 可用 Resources
+
+1. `weapp-vite://workspace/catalog`
+2. `weapp-vite://docs/{package}/README.md`
+3. `weapp-vite://docs/{package}/CHANGELOG.md`
+4. `weapp-vite://source/{package}?path={path}`
+
+`{package}` 目前支持：
+
+1. `weapp-vite`
+2. `wevu`
+3. `wevu-compiler`
+
+## 6. 可用 Prompts
+
+1. `plan-weapp-vite-change`
+2. `debug-wevu-runtime`
+
+典型用途：
+
+1. 需求改造前先生成实施计划。
+2. `wevu` 生命周期或响应式问题排查时快速建立诊断框架。
+
+## 7. 安全边界与限制
+
+MCP 服务端做了以下约束：
+
+1. 文件访问限制在工作区根目录内，阻止路径越界。
+2. 命令执行限制在白名单：`pnpm/node/git/rg`。
+3. 命令与文件读取有输出截断与超时控制，避免上下文爆炸。
+
+建议在 CI 或团队环境中继续加上外层沙箱策略（容器、只读挂载、命令审计）。
+
+## 8. 故障排查
+
+1. `weapp-vite mcp` 启动失败：先确认 Node 版本符合 `^20.19.0 || >=22.12.0`。
+2. AI 看不到包内容：检查 `--workspace-root` 是否指向正确仓库根目录。
+3. 命令执行失败：确认命令在白名单中，并检查子目录权限与脚本名是否存在。
+
+## 9. 示例：AI 驱动 weapp-vite screenshot 验收
+
+下面给一个简化版示例：只给 AI 一段提示词，让它通过 MCP 自动执行构建与截图验收。
+
+前置条件：
+
+1. 客户端已接入 `weapp-vite` MCP。
+2. 微信开发者工具已登录，并开启「设置 -> 安全设置 -> 服务端口」。
+
+### 9.1 可直接复制的提示词
+
+```text
+你现在连接的是 weapp-vite MCP。请帮我完成一次小程序截图验收：
+1. 先阅读 node_modules/weapp-vite/dist/docs/index.md 和 node_modules/weapp-vite/dist/docs/mcp.md，确认当前版本的本地说明。
+2. 构建 e2e-apps/auto-routes-define-app-json（platform=weapp）。
+3. 执行 weapp-vite screenshot，参数如下：
+   - project: e2e-apps/auto-routes-define-app-json/dist/build/mp-weixin
+   - page: pages/home/index
+   - output: .tmp/mcp-screenshot.png
+   - 使用 --json 返回结果
+4. 检查 .tmp/mcp-screenshot.png 是否存在：
+   - 存在输出 screenshot-ok
+   - 不存在输出 screenshot-missing
+5. 最后汇总：执行命令、关键输出、最终结论。
+```
+
+### 9.2 期望结果
+
+1. AI 输出 `screenshot-ok`。
+2. 工作区生成 `.tmp/mcp-screenshot.png`。
+3. AI 输出本次验收摘要（命令、关键日志、结论）。

package/dist/docs/project-structure.md

@@ -0,0 +1,52 @@
+# Project Structure
+
+## 常见目录
+
+典型 `weapp-vite` 项目通常包含这些内容：
+
+- `vite.config.ts`
+- `src/`
+- `.weapp-vite/`
+- `dist/`
+- `project.config.json`
+- `AGENTS.md`
+
+## 关键文件职责
+
+### `vite.config.ts`
+
+`weapp-vite` 的主要配置入口。`weapp` 相关能力都从这里进入。
+
+### `src/`
+
+小程序源码根目录，通常通过 `weapp.srcRoot` 指定。
+
+### `.weapp-vite/`
+
+托管的 TypeScript 支持文件目录。它通常由 `weapp-vite prepare` 生成或更新。
+
+不要手写依赖它的生成内容并长期偏离工具输出。
+
+### `dist/`
+
+构建产物目录。微信小程序通常会输出到 `dist/build/mp-weixin` 或相近结构。
+
+### `AGENTS.md`
+
+脚手架生成项目中的 AI 工作流说明。AI 代理进入项目后应优先读取。
+
+## AI 处理项目时的顺序
+
+1. 读根目录 `AGENTS.md`
+2. 读 `node_modules/weapp-vite/dist/docs/index.md`
+3. 读 `vite.config.ts`
+4. 再进入 `src/` 与业务代码
+
+## 何时运行 `prepare`
+
+出现这些情况时优先执行 `weapp-vite prepare`：
+
+- `.weapp-vite` 支持文件缺失
+- 升级了 `weapp-vite`
+- TypeScript / Volar 提示异常
+- 工具提示要求重新生成支持文件

package/dist/docs/troubleshooting.md

@@ -0,0 +1,62 @@
+# Troubleshooting
+
+## `.weapp-vite` 支持文件缺失或过期
+
+现象：
+
+- 终端提示支持文件缺失或已过期
+- 类型提示异常
+- Volar / TypeScript 行为不一致
+
+优先操作：
+
+```bash
+weapp-vite prepare
+```
+
+## AI 截图失败
+
+优先检查：
+
+1. 微信开发者工具是否已登录
+2. 是否开启了「设置 -> 安全设置 -> 服务端口」
+3. `--project` 是否指向真实的小程序构建目录
+4. `--page` 是否为真实路由
+
+推荐命令：
+
+```bash
+weapp-vite screenshot --project ./dist/build/mp-weixin --page pages/index/index --output .tmp/acceptance.png --json
+```
+
+## 终端里看不到小程序日志
+
+优先使用：
+
+```bash
+weapp-vite ide logs --open
+```
+
+如果项目启用了 `weapp.forwardConsole.enabled = 'auto'`，AI 终端场景下 `dev --open` 也可能自动附加日志桥。
+
+## `.vue` 文件存在，但提示未安装 `wevu`
+
+这通常意味着项目启用了 Vue SFC，但依赖侧没有满足当前约束。
+
+优先确认：
+
+1. 是否真的在使用 `wevu`
+2. 当前项目依赖是否完整安装
+3. SFC 相关写法是否应该参考 [`vue-sfc.md`](./vue-sfc.md)
+
+## 下游验证与源码修改不一致
+
+如果你正在修改 `packages/weapp-vite/src/**`，而验证走的是 app/template/e2e 产物，优先怀疑 `dist` 产物陈旧。
+
+先重建：
+
+```bash
+pnpm --filter weapp-vite build
+```
+
+再做下游验证。