weapp-vite 7.3.0 → 7.5.0

package/dist/docs/README.md

@@ -14,6 +14,20 @@
 
 <p>&nbsp;</p>
 
+## Node.js 支持范围
+
+框架及编译依赖链要求 `^22.18.0 || ^24.11.0 || >=26.0.0`：Node 22 至少 22.18.0、Node 24 至少 24.11.0，或 Node 26 及以上版本；不支持 Node 20、23、25。这是 Babel 8 与必需构建依赖支持范围的交集，不能通过关闭 engines 校验恢复旧版本支持。
+
+升级已有项目时先升级 Node.js，再重新安装依赖。CLI 会在加载编译依赖前检查实际 Node 版本；`prepare` 也会明确拒绝不支持的环境。直接通过 Vite 或程序 API 消费时同样需要遵守包的 `engines.node`。
+
+`create-weapp-vite` 自身依赖要求更高：Node 22 至少 22.22.2、Node 24 至少 24.15.0，或 Node 26 及以上版本。新建项目按脚手架要求选择 Node，不要将框架最低版本误认为脚手架最低版本。
+
+发布候选在构建环境中打包，再在独立临时消费者中以严格 engines/peer 校验安装；CI 覆盖 Linux、Windows、macOS 的 Node 22.18.0、24.11.0、26.0.0 及 22/24 当前补丁版本，验证原生和 SFC 构建、prepare 与公开类型。
+
+## 普通 Vite 与 Vite+
+
+独立项目继续使用 `wv dev/build`，不需要注册插件或安装 Vite+。采用普通 Vite / Vite+ 时，在顶层 `weapp` 配置旁注册 `weapp-vite/vite` 的 `weapp()`，使用原生 `vite dev/build` / `vp dev/build`。当前插件开放微信 TS/Vue/React 生产构建、原生 `build --watch` 与实验性 classic/stateful 开发；通过 `weapp.hmr.runtime` 选择模式，已支持普通分包、独立分包与 worker，其他高级目标仍在分阶段对齐。Vite+ 需要配套 core alias 与依赖覆盖，详见[标准插件指南](https://vite.weapp.dev/guide/vite-plugin.html)。
+
 ## 使用文档地址: [vite.weapp.dev](https://vite.weapp.dev)
 
 ## Features
@@ -31,7 +45,7 @@
 - 🌐 **实验性 Web Runtime**：同一份原生 WXML/WXSS/TS 或 wevu Vue SFC 源码可通过 `-p web` 启动和构建浏览器版本
 - 🎨 **内置 Tailwind CSS**：通过 `weapp.tailwindcss` 配置 `weapp-tailwindcss` 的 core 与 generator 集成；Tailwind CSS v4 项目引入 `tailwindcss` 后可自动启用
 - 🧩 **实验性 uni-app 组件库兼容**：通过显式依赖白名单与 `WotUiResolver()` 在微信小程序和 Web 中使用 Wot UI Vue SFC
-- 🧰 **IDE 命令增强**：可直接透传 `weapp-ide-cli` 全量命令（`preview/upload/config/automator` 等）
+- 🧰 **IDE 命令增强**：通过 `wv ide <command>` 调用 `weapp-ide-cli`；保留旧顶层上传参数并提示未来弃用，SDK 与 IDE 边界见下文
 - 🧪 **真实产物单测**：`weapp-vite/test` 提供不启动 CLI 的程序化测试构建入口，可配合 `@mpcore/test` 测试页面和组件
 - 🌍 **内置 i18n**：构建期编译 locale JSON，通过 WXS 翻译模板，并在逻辑层安全切换已构建语言
 
@@ -64,6 +78,76 @@ wv build -p web
 
 `web` 是浏览器 runtime 的规范平台名，`h5` 仅作为向后兼容别名保留；未选择 Web 平台时不改变现有小程序构建。完整配置和兼容边界见 [Web 运行时配置](https://vite.weapp.dev/config/web) 与 [`@weapp-vite/web`](https://vite.weapp.dev/packages/web)。
 
+### 可选 Hub 工作台
+
+`wv dev --ui` / `wv build --ui` 保持独立 Dashboard。安装可选面板包 `@weapp-vite/dashboard` 后，可显式启用 DevFrame 1.2 的官方 Hub，无需安装 Vite DevTools：
+
+```bash
+wv dev --ui-host hub
+wv build --ui-host hub
+wv analyze --ui-host hub
+```
+
+`--ui-host` 只接受 `standalone` 和 `hub`，并隐式启用 UI；不传 UI 参数时，`dev` / `build` 不新增服务。Hub 入口为 `/__devframes/`，Dashboard 面板仍为 `/__weapp-vite/`，共用 loopback 服务、OTP 认证、报告控制器和原生连接。Hub 提供停靠面板与内建设置，不安装终端或其他默认工具；语言设置不自动翻译自定义 Dashboard。
+
+Dashboard dock 与 Hub 品牌使用与官网相同图案的包内 SVG 字符串，以 data URL 提供。源码入口和发布产物均无需 SVG loader、官网目录或外部图标服务。
+
+Hub 的 `/__devframes/__mcp` 聚合端点保持关闭，但与独立模式一样发布 Dashboard scoped MCP 实例，地址为 `/__weapp-vite/__mcp`，不继承其他插件的工具或 Resources。`analyze --json`、`--markdown`、`--report` 等输出选项优先级保持不变；Hub 不是离线报告导出。完整参数见 [CLI 指南](https://vite.weapp.dev/guide/cli#可选-hub-工作台)。
+
+### Dashboard 嵌入 Vite DevTools
+
+`weapp-vite/dashboard` 是 Node 端共享核心；CLI 独立工作台与 Vite DevTools 复用同一个 `DevframeDefinition` 和 `@weapp-vite/dashboard` 面板。可选适配器位于 `weapp-vite/dashboard/vite`，使用官方 `createPluginFromDevframe`，不会由普通包入口或 CLI 自动加载。
+
+接入方安装 `@weapp-vite/dashboard`、`@vitejs/devtools` 和 `@vitejs/devtools-kit`。当前接入按 Vite `8.3.0`、DevTools / Kit `0.7.6`、Devframe `1.1.0` 验证；Kit 是可选 peer，宿主依赖不进入小程序产物。
+
+```ts
+import type { DevToolsConfig } from '@vitejs/devtools/config'
+import type { DashboardAnalyzeSnapshot, DashboardContentRoots } from 'weapp-vite/dashboard'
+import { DevTools } from '@vitejs/devtools'
+import { createAnalyzeDashboardDevframe, resolveDashboardClientAssets } from 'weapp-vite/dashboard'
+import { createAnalyzeDashboardPlugin } from 'weapp-vite/dashboard/vite'
+
+export function createDashboardHost(snapshot: DashboardAnalyzeSnapshot, roots: DashboardContentRoots) {
+  const dashboard = createAnalyzeDashboardDevframe({
+    snapshot,
+    roots,
+    clientAssets: resolveDashboardClientAssets(roots.projectRoot),
+  })
+  const hostOptions: DevToolsConfig = {
+    builtinDevTools: false,
+    clientAuth: true,
+    allowedOrigins: [],
+    mcp: false,
+  }
+  return {
+    dashboard,
+    plugins: [
+      DevTools(hostOptions),
+      createAnalyzeDashboardPlugin(dashboard, { base: '/tools/weapp/' }),
+    ],
+  }
+}
+```
+
+将返回的 `plugins` 交给 Vite 配置。调用方先完成分析及历史元数据持久化，用 `createDashboardArtifactSnapshot().capture` 收集该次分析的产物，再提交 `{ current, previous, artifacts }`。后续调用 `dashboard.update(result, artifacts, previousResult?)`；仅运行事件变化时调用 `dashboard.emitRuntimeEvents(events)`。提交后不要再修改报告或产物 Map。
+
+每个控制器只同时挂载到一个逻辑宿主。适配器记录成功安装的 Vite 配置身份，并仅在该配置拥有的环境关闭时释放核心。成功重启将所有权移交给新配置，旧实例和未安装的失败候选的清理都不会误释放当前控制器；替换前的资源校验失败时，旧宿主仍可查询和更新。首次 setup 失败或 SDK 安装开始后的失败会释放核心，不承诺回滚部分安装。自行使用 `dashboard.definition` 对接其他 Devframe 宿主时，调用方必须负责最终关闭和启动失败时的 `dashboard.dispose()`。核心不启动服务器，也不拥有外部宿主的认证、Origin 或 MCP 策略；共享宿主不是只读沙箱。
+
+DevTools `0.7.6` 自身存在程序化重启边界：重复使用同一个 `DevTools()` 返回值时，旧实例关闭可能同时关闭新实例的 WebSocket；不安装 Dashboard 也能复现。应在每次重载的 Vite 配置中重新调用 `DevTools()`，不要把该 SDK 插件实例长期缓存在复用的 inline 配置里。上述重启验证使用重新创建的 SDK 宿主和保留的 Dashboard 控制器，不代表修复了上游传输问题。
+
+面板默认位于 `/__weapp-vite/`，自定义目录与应用 `base` 独立。前端复用宿主连接或从页面相对位置发现元数据，复制视图链接保留目录和查询参数但排除认证 fragment。适配器只在开发模式挂载，生产构建不要求可选面板资源，也不导出报告。以上入口仅用于 Node 开发 / 构建宿主，不应导入小程序 AppService。
+
+仓库内可通过 `apps/dashboard-ui-lab` 的 `dev:inspector` 与 `dev:inspector:host` 验证两种宿主，详见其 [实验说明](../../apps/dashboard-ui-lab/README.md)。
+
+### Dashboard MCP
+
+CLI 的 standalone 与 Hub 模式均向 AI 提供摘要／预算、包与产物／模块检索、重复分析、构建比较、最近事件与受限文件片段，并提供调查列表、详情和领取／提案／开始／回报四个元数据动作。页面与工具共享报告、产物及 `weapp-vite/dashboard/analyze` 纯计算，缺失基线或测量不会假造增减。实际监听后可通过 `devframe connect` 发现 scoped 实例；MCP 校验 loopback 对端与 Origin，浏览器使用 OTP。本机模式不区分本机用户，请勿通过代理、隧道或端口转发对外发布。
+
+「对象检查」以真实包 → 产物 → 模块关系浏览完整报告，选择与显式筛选分离，证据／内容／变化／调查共用一个上下文区。浏览器提交绑定报告的调查，外部 Agent 回传提案后需用户明确授权；执行仍在外部，回执不能代替更新报告上的人工复验。创建、取消、授权和复验不暴露为 Agent 工具，也不提供通用 shared-state、任意文件写入或命令执行。
+
+旧 revision 请求与旧提案授权会被拒绝。嵌入 Vite DevTools 时仍由宿主决定是否开放 MCP；现有 `wv mcp`、REST 与微信 IDE 自动化入口保持不变。客户端配置、任务版本和领取令牌用法见 [随包 MCP 指南](docs/mcp.md#dashboard-证据查询与对象调查devframe)。
+
+
 ### Vue 项目
 
 ```typescript
@@ -73,10 +157,10 @@ import { defineConfig } from 'weapp-vite/config'
 export default defineConfig({
   weapp: {
     srcRoot: 'src',
+    wxml: { remove: { comment: true } },
     vue: {
       enable: true,
       template: {
-        removeComments: true,
         htmlTagToWxml: true,
         htmlTagToWxmlTagClass: true,
       },
@@ -321,20 +405,61 @@ weapp-vite dev --open
 # o -> 重新打开当前 DevTools 项目
 ```
 
+## 六端构建并上传
+
+显式执行 `wv build --upload`，在本次构建成功并校验产物后上传，不重复构建。支持微信 `weapp`、支付宝 `alipay`、抖音 `tt`、小红书 `xhs`、京东 `jd`、百度 `swan`；只上传开发版本，不自动提审或正式上线。
+
+```sh
+wv build --upload --dry-run
+wv build --upload -p weapp
+
+# 独立 upload 命令仍支持多个小程序目标；all 在此表示六端
+wv upload --platform jd,swan
+wv upload --platform all --dry-run
+wv upload --platform xhs,tt --json --timeout 180
+
+# 内置本地自动版本演练，不修改版本或锁文件
+wv upload -p xhs,tt --mode test --bump patch --git-desc --dry-run
+```
+
+通常无需配置 `weapp.upload`：默认读取业务 `package.json.version`，说明自动生成 `项目名@版本`；默认不升版、不读取 Git、不运行 npm。需要覆盖时用 `weapp.upload` 或 CLI `--uv` / `--desc`；本地自动版本显式使用 CLI `--bump patch|minor|major` / `--git-desc`，分别与 `--uv` / `--desc` 冲突，不写入 Vite 配置。`.env.test` / `.env.production`、不同 AppID、本地自动版本与 CI 方案见[上传环境与自动版本](https://vite.weapp.dev/guide/upload/environments.html)。普通 `build`、`dev/HMR` 不上传，`preview` 不使用上传默认参数；配置文件仍正常求值。`build` 的上传专属参数必须与 `--upload` 一起使用，不支持 `--watch` 或 Web-only。
+
+自动元数据在首次配置求值、编译前准备一次，批量共用；升版仅处理命令根目录的应用清单，不向父目录查找。真实升版需要本机 npm，只有 Git 说明要求已有提交的 Git 仓库；不执行生命周期钩子、不 commit/tag/push。dry-run 不运行 npm、不修改版本或锁文件，直接导入 `package.json` 的构建代码仍读取原始版本。实际升版后的构建或上传失败不回滚，重试去掉 `--bump` 并复用原版本，必要时用 `--uv` / `--desc` 固定上一批元数据。
+
+`build -p all --upload` 保持“小程序 + Web”语义，等两个后端都构建成功后只上传小程序；独立 `wv upload -p all` 才是六端逐一构建上传，首次失败停止。`--dry-run` 只构建并校验产物，不校验凭据、不调用 SDK。
+
+独立 `upload --json` 将单个结构化报告写入 stdout，构建日志与官方进度进入 stderr；失败保留前序成功、当前错误和后续 `not-run` 条目，并以非零状态退出。`--timeout <秒>` 只限制各平台 SDK worker，不包含构建。SDK 开始后超时或中断标记远端结果未确认；终止本地进程不能取消远端任务，不自动重试。六端可选结果与进度差异见[结果、进度与本地超时](https://vite.weapp.dev/guide/upload.html#report)。这两个选项不适用于 `build --upload`、`preview` 或 IDE 上传。
+
+多个平台可用一份 `weapp.multiPlatform.projectConfigs` 映射集中配置 AppID，公共字段用对象展开复用，不必手工维护六份原生 JSON。构建器在代码输出目录内生成对应项目配置；原生文件方式仍可使用。完整配置见[一份配置与批量上传](https://vite.weapp.dev/guide/upload.html#batch)。
+
+官方工具按目标安装，凭据只使用环境变量，不在 `weapp.upload` 中配置。完整的项目配置、AppID、凭据获取与环境文件、上传、预览、批量操作、CI 与排障见[小程序上传与预览指南](https://vite.weapp.dev/guide/upload.html)：[小红书](https://vite.weapp.dev/guide/upload/xhs.html)、[抖音](https://vite.weapp.dev/guide/upload/tt.html)、[微信](https://vite.weapp.dev/guide/upload/weapp.html)、[支付宝与淘宝边界](https://vite.weapp.dev/guide/upload/alipay.html)、[京东](https://vite.weapp.dev/guide/upload/jd.html)、[百度](https://vite.weapp.dev/guide/upload/swan.html)。本地速查见 `dist/docs/upload.md`；淘宝暂不支持，不要用 `-p alipay` 替代。
+
+## 六端构建并预览
+
+```sh
+wv preview -p tt --mode test
+wv preview -p xhs,jd,swan --mode production
+wv preview -p all --dry-run
+```
+
+`preview` 复用上述六端构建与凭据，调用官方预览接口，不上传开发版本、不提审、不正式发布。微信返回 `.weapp-vite/preview/` 下本次生成的二维码图片；支付宝、京东返回二维码图片 URL；抖音、小红书、百度返回官方预览链接。默认 mode 为 `production`，不要求上传版本，也不接受 `--uv`、`--bump` 或 `--git-desc`。百度预览也需要 `SWAN_MIN_VERSION`。
+
+`--dry-run` 只构建和校验产物，不调用 SDK、不生成预览结果。真实扫码权限与有效期依平台规则，详情见 [CLI 预览文档](https://vite.weapp.dev/guide/cli.html)。
+
 ## CLI 中调用 weapp-ide-cli
 
-`weapp-vite` 内置了对 `weapp-ide-cli` 的透传能力，除了 `dev/build/close/open/init/generate/analyze/npm/prepare/mcp` 等原生命令外，其它 IDE 相关命令都可以直接调用：
+`weapp-vite` 内置了对 `weapp-ide-cli` 的透传能力：原生命令通常优先，其他命令仅在 IDE catalog 命中时透传。`wv upload` 默认走六端 SDK，但保留带明确旧参数的顶层微信 IDE 上传；`wv preview` 仍是 SDK 预览，不属于旧语法兼容范围。稳定的显式 `ide upload`、`ide preview` 不弃用：
 
 ```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 ide preview --project ./dist/build/mp-weixin
+weapp-vite ide upload --project ./dist/build/mp-weixin -v 1.0.0 -d "release"
 weapp-vite cache --clean compile
 weapp-vite cache --clean all
 weapp-vite config lang zh
 weapp-vite config set autoTrustProject true
 weapp-vite navigate pages/index/index --project ./dist/build/mp-weixin
 # 等价写法
-wv preview --project ./dist/build/mp-weixin
+wv ide preview --project ./dist/build/mp-weixin
 wv cache --clean all
 ```
 
@@ -349,6 +474,21 @@ weapp-vite ide logs --open
 wv ide preview --project ./dist/build/mp-weixin
 ```
 
+原有顶层上传的长、短参数仍可原样执行，不额外触发 weapp-vite 构建：
+
+```sh
+wv upload --project ./dist --version 1.2.3 --desc "release"
+wv upload -p ./dist -v 1.2.3 -d "release"
+```
+
+新 SDK 上传使用 `wv upload -p weapp` 即可，无需 `--project`，框架按项目配置与本轮实际输出自动定位。上面 `./dist` 只是旧 IDE 工程目录示例，应包含 `project.config.json`；旧入口省略定位参数时保持透传，不会默认补 `dist`。
+
+每次旧顶层调用只警告一次未来移除，不要求立即改写脚本；若只想保留 IDE 行为，改为 `wv ide upload -p ./dist -v 1.2.3 -d "release"`，该显式入口不警告。若迁移到 SDK，先在**源码项目根**安装 `miniprogram-ci`、配置 AppID、代码上传私钥与 IP 白名单，再执行 `wv build --upload -p weapp --uv 1.2.3 --desc "release"`。SDK 会重新构建、使用新凭据，不复用 IDE 登录；不要把旧 `--project` 的产物目录直接作为 `[root]`。
+
+`-p` 有 `--version/-v`、`--project`、`--appid`、`--ext-appid` 或 `--info-output/-i` 等旧标记时才表示 IDE 项目目录，否则表示平台，不猜测路径。旧标记与 SDK 的 `--platform`、`--uv`、`--bump`、`--git-desc`、`--dry-run`、`--json`、`--timeout`（含其 `--no-*` 形式）混用，在 IDE、编译或版本修改前报错；SDK 专属选项不适用于 IDE。`--desc` 共用，`-d` 只在旧调用中是说明，原生命令中仍是 debug。
+
+`wv upload --help` 查看 SDK 帮助；`wv help upload` 保留旧 IDE 帮助并提示未来弃用；`wv ide help upload` 不弃用、不警告。等号写法、选项值与 `--` 边界等完整规则见[旧上传兼容与迁移](https://vite.weapp.dev/guide/cli.html#legacy-upload)。
+
 ## CLI 启动 MCP
 
 `weapp-vite` 已集成 `@weapp-vite/mcp`：
@@ -442,3 +582,11 @@ const artifact = await buildTestArtifact({ cwd: process.cwd() })
 [MIT](./LICENSE)
 
 <!-- "//------":""esbuild": "^0.21.3",", -->
+
+## 实验性标准 Vite 插件
+
+`weapp-vite/vite` 导出 `weapp()`，通过 `plugins: [weapp()]` 和顶层 `weapp` 配置接入原生 `vite build` / `vp build`。当前开放微信 TS/Vue/React 生产构建、原生 build watch 与实验性 classic/stateful 开发；已支持普通分包、独立分包与 worker，其他高级目标继续分阶段对齐。配置、Vite+ alias 与未开放能力见 [标准插件指南](https://vite.weapp.dev/guide/vite-plugin)。离线说明随包发布在 `dist/docs/vite-plugin.md`。
+
+## AI 改动验收
+
+通过 `wv accept --inspect --json` 检查环境；审阅配置后运行 `wv accept --trust --json`。现有 MCP 同时提供验收启动、状态、取消和报告工具，无需模型 Key。[接入指南](https://vite.weapp.dev/guide/acceptance)。独立 `weapp-agent` CLI 同仓维护并保留原命令。

package/dist/docs/ai-workflows.md

@@ -126,3 +126,7 @@ wv mcp doctor codex
 - wevu 页面、组件、store 写法：[`wevu-authoring.md`](./wevu-authoring.md)
 - Vue SFC 宏与模板约束：[`vue-sfc.md`](./vue-sfc.md)
 - 常见告警与排障：[`troubleshooting.md`](./troubleshooting.md)
+
+## 确定性验收
+
+使用 `wv accept --init` 创建配置、`wv accept --inspect --json` 检查环境。审阅后 `wv accept --trust --json`，通过 `wv accept --report <jobId> --json` 读取报告。现有 MCP 的 weapp_project_inspect 和 weapp_acceptance_start/status/cancel/report 支持相同流程；使用 weapp-acceptance Skill。缺失必需检查、过期证据和单张截图都不能代表完整验收通过。

package/dist/docs/doctor.md

@@ -0,0 +1,38 @@
+# Doctor
+
+`wv doctor` / `runDoctor`（来自 `weapp-vite/doctor`）共享只读事实检查引擎，分别记录 project/source/artifact/runtime 覆盖。默认读取项目 JSON 和 `src`，不执行配置、不启动 IDE、不上传数据或修改代码。其他源码目录须显式传入 `--source`；构建模式会使用实际编译源码目录。
+
+```sh
+wv doctor --format json
+wv doctor --build --targets weapp,alipay,swan,tt,xhs
+wv doctor --artifact dist --platform weapp --format sarif
+wv doctor --runtime --platform weapp
+```
+
+`--build` 明确允许执行配置/插件，在独立子进程中通过正常编译器生成 `.weapp-vite/doctor` 下的最终产物，再读取快照。构建日志走 stderr，不污染 JSON/SARIF。报告包含实际相对目录、文件摘要和预算。与 `--artifact` 互斥，后者标记新鲜度未验证、缺失编译预算时 incomplete。
+
+`--runtime` 只连接已打开的微信 DevTools 项目并读取 Tool.getInfo 与当前页面，不启动 IDE、不切换路由；已有非默认 automator 会话可使用 `--runtime-port <port>`。这不代表应用功能已经通过 E2E。其他宿主无探针、连接失败或未打开项目均为 incomplete。
+
+
+宿主分层证据会保留 CLI 可执行条件、指定服务监听、登录查询与登录状态、项目连接、工具信息、当前页面以及本次连接释放的独立结果。`passed`、`failed`、`unknown`、`not-run` 分开记录；部分失败仍保留成功阶段、实际 IDE/SDK 版本和脱敏证据，退出码为 2。TCP 可达只证明有监听，不证明它属于所选 IDE；Tool.getInfo/页面快照也不证明完整应用功能已通过。
+
+- `--runtime-cli <path>`：只读检查显式选择的 CLI，不执行、不回退其他安装。
+- `--runtime-service-port <port>`：连接指定回环 TCP 端口检查监听，仅释放本次 socket。
+- `--runtime-login`：单独允许执行原生 islogin，需要同时传入 `--runtime-cli`；原生 CLI 可能启动 IDE。没有此开关不会查询或推断登录状态。
+
+上述选项都需要 `--runtime`。JSON/SARIF 中的 `runtime.<target>.bundle` 包含框架/Node 版本、可取得的 IDE/基础库版本、配置选择摘要、最后成功阶段、有限的固定分类事件及通用复现命令。未知版本省略，终端显示 unknown；不保存原始 Tool.getInfo、CLI 输出、凭据、绝对路径或页面查询参数，不自动上传。`not-run` 不代表检查通过；旧的自定义 runtime adapter 仍可使用原证据结构。
+
+连接和页面/工具 RPC 有界等待，迟到连接只断开自身 websocket，迟到 RPC 不会改写已返回的报告。完整操作层的总 deadline、分类重试和跨进程取消由相应操作层负责；此探针不替代 #1141 的完整工作。
+
+退出码：0 为请求范围完整且无错误；1 为发现门禁错误；2 为未完成或执行失败（优先于 1）。未请求的层标为 not-requested。
+
+复用平台注册表、ESLint 兼容规则和包体预算。非微信平台不使用微信 API 基线；尚无完整 API 目录时相应层 incomplete。HarmonyOS 等设备系统不作为编译目标别名。源码风险与产物诊断分离；动态引用、外部插件、自定义 npm 输出等事实不足的范围不判定通过。
+
+产物检查包含页面/组件文件与引用、静态脚本/模板/样式依赖、独立分包边界、worker 目录和预算。诊断包含稳定 ruleId、location、evidence、responsibility、fingerprint、suggestion。无法确定责任时保留 unknown；confirmed 仅指当前静态契约的确定违反，不代表已确认框架 bug。报告只保留产物字节数与摘要，不附带完整源码。工具不会自动发布报告或创建 issue。
+
+```ts
+import { formatDoctorReport, runDoctor } from 'weapp-vite/doctor'
+
+const report = await runDoctor({ cwd: '.', build: true, targets: ['weapp'] })
+const json = formatDoctorReport(report, 'json')
+```

package/dist/docs/getting-started.md

@@ -39,6 +39,57 @@ weapp-vite ide logs --open
 weapp-vite build
 ```
 
+### 构建并上传
+
+```bash
+wv build --upload --dry-run
+wv build --upload -p weapp
+
+# 独立命令保留六端批量上传能力
+wv upload --platform jd,swan
+wv upload --platform all --dry-run
+
+# 内置自动版本演练：不修改版本或锁文件
+wv upload -p xhs,tt --mode test --bump patch --git-desc --dry-run
+```
+
+`build --upload` 复用本次构建，构建成功并校验产物后才上传，不重复构建。六个平台为 `weapp/alipay/tt/xhs/jd/swan`；独立 `wv upload` 还支持逗号分隔或显式 `all`，每个目标先构建再上传，失败后停止后续目标。上传不自动提审或正式上线；`--dry-run` 只构建和检查产物，不校验凭据、不调用 SDK。
+
+通常无需添加 `weapp.upload`：默认读取业务 `package.json.version`，说明自动生成为 `项目名@版本`；默认不升版、不读取 Git、不运行 npm。需要覆盖时传 `--uv` / `--desc` 或配置 `weapp.upload`；本地自动版本显式使用 CLI `--bump patch|minor|major` / `--git-desc`，二者分别与 `--uv` / `--desc` 冲突，不是 Vite 配置字段。真实升版需要本机 npm，只有 Git 说明要求已有提交的 Git 仓库。完整 `.env.test` / `.env.production`、独立 AppID、本地自动升版与 CI 配置见[上传环境与自动版本](https://vite.weapp.dev/guide/upload/environments.html)。普通 `build`、`dev/HMR` 不上传；配置仍正常求值。`build` 的上传专属参数必须与 `--upload` 一起使用，不能用于 watch 或 Web-only。
+
+自动元数据在首次配置求值、编译前准备一次，批量共用；升版仅处理命令根目录的应用清单，不向父目录查找、不执行生命周期钩子、不 commit/tag/push。dry-run 不运行 npm、不修改版本或锁文件，直接导入 `package.json` 的构建代码仍读取原始版本。实际升版后的构建或上传失败不回滚，重试去掉 `--bump` 并复用原版本。完整边界见[本地速查](./upload.md#内置本地自动版本)。
+
+`build -p all --upload` 是“小程序 + Web”，等两者都构建成功后只上传小程序，不等于独立 `upload -p all` 的六端批量上传。
+
+需要 CI 报告时使用 `wv upload -p xhs,tt --json --timeout 180`：stdout 为单个 JSON 汇总，日志与官方进度进入 stderr；首次失败停止并保留未执行目标。超时仅限 SDK worker，不含构建；中断后不能推断远端取消，不自动重试。这两个选项不适用于 `build --upload`、`preview` 或 IDE，完整边界见[本地结果参考](./upload.md#结构化结果与本地超时)。
+
+多个平台推荐使用一份 `weapp.multiPlatform.projectConfigs` 映射，公共字段用对象展开，各平台只提供 AppID 和差异；标准项目 JSON 由构建器生成，不必手工维护六份文件。原生文件方式仍可使用，完整示例见本地[上传速查](./upload.md#多平台与输出校验)。
+
+按目标安装官方工具，并通过未提交的 `.env.<mode>.local` 或 CI Secrets 提供凭据，不要在 `weapp.upload` 中添加凭据字段。先读本地 [六端上传与预览速查](./upload.md)，再按[分平台操作指南](https://vite.weapp.dev/guide/upload.html)配置 AppID、密钥或 Token。淘宝不在支持列表内；百度官方 CLI Token 会进入子进程参数，仅在可信隔离 runner 上运行。
+
+旧的微信 IDE 顶层上传仍可原样执行，不额外触发 weapp-vite 构建：
+
+```bash
+wv upload --project ./dist --version 1.2.3 --desc "release"
+wv upload -p ./dist -v 1.2.3 -d "release"
+```
+
+SDK 命令 `wv upload -p weapp` 无需 `--project`，会自动定位本次构建产物。这里的 `./dist` 只是假设旧 IDE 工程根位于该目录，不是默认值，应按实际 `project.config.json` 所在目录填写；旧入口省略定位参数时保持透传，不自动补 `dist`。
+
+旧顶层语法每次只警告一次未来弃用，不要求立即迁移；稳定的显式 `wv ide upload -p ./dist -v 1.2.3 -d "release"` 不弃用、不警告，仍依赖 IDE 登录。若改用 SDK，需要从源码项目根安装 `miniprogram-ci`、配置 AppID、上传私钥和 IP 白名单，再执行 `wv build --upload -p weapp --uv 1.2.3 --desc "release"`；不复用 IDE 登录，也不能把旧 `--project` 的产物目录直接作为 SDK `[root]`。
+
+`-p` 只有与明确旧标记（如 `--version/-v` 或 `--project`）一起出现时才是 IDE 项目目录，否则是平台，不猜测路径。新旧方言混用在 IDE、构建或升版副作用前报错，`--dry-run` / `--bump` / `--git-desc` / `--json` / `--timeout` 不能用于旧 IDE 上传。`wv upload --help` 是 SDK 帮助，`wv help upload` 保留旧 IDE 帮助并警告，`wv ide help upload` 不警告。完整标记、短参数和 `=` / `--` 规则见[本地速查](./upload.md#旧上传兼容与迁移)。
+
+### 构建并预览
+
+```bash
+wv preview -p tt --mode test
+wv preview -p xhs,jd,swan --mode production
+wv preview -p all --dry-run
+```
+
+使用同一套六端工具与凭据，先构建再调用官方预览接口，不上传开发版本、不提审、不正式发布。微信返回本次生成的本地二维码图片；支付宝、京东返回二维码图片 URL；抖音、小红书、百度返回预览链接。百度仍需 `SWAN_MIN_VERSION`；预览不使用上传默认参数，不接受 `--uv`、`--bump` 或 `--git-desc`。旧微信 IDE 预览使用 `wv ide preview --project <IDE项目根>`，不额外构建。
+
 ### 4. 分包预下载审计
 
 微信小程序可以检查静态跨分包跳转，并把建议输出为 JSON：
@@ -90,7 +141,7 @@ weapp-vite build
 wv dev -p web --host
 wv build -p web
 weapp-vite open
-weapp-vite preview --project ./dist/build/mp-weixin
+weapp-vite preview -p weapp --mode test
 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

package/dist/docs/index.md

@@ -16,21 +16,25 @@
 8. 涉及 wevu 运行时与页面/组件/store 约束时读 `wevu-authoring.md`。
 9. 涉及 Vue SFC 宏、模板约束与编辑器提示时读 `vue-sfc.md`、`volar.md` 与 `define-config-overloads.md`。
 10. 编写页面或组件单测时读 `testing.md`。
-11. 遇到告警、prepare、截图、日志、依赖异常时读 `troubleshooting.md`。
+11. 上传或预览小程序时读 `upload.md`，核对平台、AppID、凭据与输出目录。
+12. 遇到告警、prepare、截图、日志、依赖异常时读 `troubleshooting.md`。
 
 ## Included Docs
 
+- `doctor.md`: 分层静态/构建/宿主证据、JSON/SARIF 与完整性退出码。
 - `README.md`: weapp-vite npm 包内置文档入口，供 AI 与开发者优先读取本地版本说明。
 - `mcp.md`: MCP、AI 工作流与 screenshot 验收说明。
 - `volar.md`: Volar、JSON 宏与编辑器智能提示支持说明。
 - `define-config-overloads.md`: defineConfig 类型重载与配置推导说明。
+- `vite-plugin.md`: 实验性标准 Vite 插件、Vite+ alias 与分阶段支持边界。
 - `getting-started.md`: CLI 命令、prepare、build、screenshot、MCP 等快速入口。
+- `upload.md`: 六端上传/预览、AppID 与凭据、批量执行、CI 和淘宝支持边界。
 - `ai-workflows.md`: AI 代理在其他仓库里使用 weapp-vite 的推荐工作流。
 - `project-structure.md`: AGENTS.md、.weapp-vite、dist 与源码目录的职责说明。
 - `weapp-config.md`: weapp 配置、autoRoutes、autoImportComponents、routeRules 与 chunk 策略。
 - `glass-easel.md`: glass-easel 宿主配置、迁移诊断与无法无损自动改写的边界。
 - `i18n.md`: 内置 locale 编译、WXS 模板翻译、运行时切换与分包实例边界。
-- `uni-app-component-libraries.md`: 实验性的 uni-app 组件库转换、Wot UI 配置、99 组件矩阵与双端边界。
+- `uni-app-component-libraries.md`: 实验性的 uni-app 组件库转换、Wot UI 配置、100 组件矩阵与双端边界。
 - `wevu-authoring.md`: wevu 页面、组件、store、router 与事件契约的推荐写法。
 - `vue-sfc.md`: definePageJson、definePageMeta、v-model 与模板兼容约束。
 - `troubleshooting.md`: prepare、截图、日志、wevu 依赖与 dist 同步等常见排障。

package/dist/docs/mcp.md

@@ -24,6 +24,95 @@
 5. 仓库级受限命令执行（`pnpm/node/git/rg`）
 6. 面向改造和排障的标准 Prompt 模板
 
+### Dashboard 证据查询与对象调查（DevFrame）
+
+`wv dev --ui` / `wv build --ui` 可通过 DevFrame MCP 查询**当前运行中的 Dashboard**，并领取、回传对象调查。这与下文的 `wv mcp` 是两个入口：现有工具、Resources、Prompts、REST 和微信 IDE 会话保持不变，`wv mcp init` 不会改为连接 Dashboard。
+
+在项目中安装面板及可选的 stdio 连接器：
+
+```bash
+pnpm add -D @weapp-vite/dashboard devframe@1.2.0 @devframes/agentic@1.2.0
+```
+
+启动 `wv dev --ui` / `wv build --ui` 后，Dashboard 自动开放本机 scoped MCP，无需生成令牌或配置认证环境变量。浏览器仍使用终端提供的 OTP magic link；MCP 不需要先完成浏览器授权。
+
+默认 `standalone` 与 `--ui-host hub` 都发布同一 Dashboard 范围的 MCP 发现记录，端点为 `/__weapp-vite/__mcp`。Hub 的 `/__devframes/__mcp` 聚合入口仍关闭：该端点不继承宿主其他插件的工具、Resources 或 shared-state，也不授予文件修改或命令执行权限。`--no-mcp` 控制的是原有 CLI MCP 服务，不关闭随 UI 启动的 Dashboard scoped MCP。
+
+在项目目录启动 stdio 连接器：
+
+```bash
+pnpm exec devframe connect
+```
+
+支持 `mcpServers` 配置的客户端可使用：
+
+```json
+{
+  "mcpServers": {
+    "weapp-dashboard": {
+      "command": "pnpm",
+      "args": ["exec", "devframe", "connect"]
+    }
+  }
+}
+```
+
+先调用 `devframe_connect_list-instances`，按项目与端口选择实例，再用 `devframe_connect_call-tool` 调用工具。实例只在真实监听后注册；关闭或重启时移除本实例的旧记录。若注册目录不可写，上游会输出诊断，可改用 `devframe connect --port <port> --base /__weapp-vite/` 显式探测终端 UI 地址中的端口。
+
+| 工具 | 输入 | 结果 |
+| --- | --- | --- |
+| `weapp-vite_get-dashboard-state` | `{}` | 当前 sessionId、revision、报告描述符、调查状态与最近事件 |
+| `weapp-vite_get-analyze-summary` | `{ "arg0": { "revision": 0 } }` | 包、文件、模块、已知字节总量及预算状态汇总 |
+| `weapp-vite_query-analyze-packages` | `{ "arg0": { "revision": 0, "budgetStatus": "exceeded" } }` | 按包类型、名称、预算状态筛选，按体积、名称或预算比例排序 |
+| `weapp-vite_query-analyze-artifacts` | `{ "arg0": { "revision": 0, "limit": 10 } }` | 最大产物；也可按 `packageId`、`moduleId`、类型和路径定位 |
+| `weapp-vite_query-analyze-modules` | `{ "arg0": { "revision": 0, "duplicateOnly": true, "sortBy": "estimatedSavingBytes" } }` | 模块体积、跨包重复估算及独立分包边界提示 |
+| `weapp-vite_compare-analyze-builds` | `{ "arg0": { "revision": 0, "scope": "file" } }` | 包、文件或模块的新增、删除、增长、缩小及构建总量差异 |
+| `weapp-vite_query-runtime-events` | `{ "arg0": { "kind": "hmr", "limit": 10 } }` | 最近事件、HMR profile 和窗口保留／丢弃计数 |
+| `weapp-vite_read-dashboard-file` | `{ "arg0": { "kind": "artifact", "path": "app.js", "revision": 0, "range": { "offset": 0, "limit": 4096 } } }` | 报告内源码或当前构建产物的有界文本片段 |
+| `weapp-vite_get-analyze-page` | `{ "arg0": { "target": "current", "index": 0, "revision": 0 } }` | 全量导出用的 JSON 文本页，不是常规诊断的必经步骤 |
+| `weapp-vite_list-investigations` | `{}` | 当前宿主会话的调查列表及列表版本，不含领取令牌 |
+| `weapp-vite_get-investigation` | `{ "arg0": { "id": "<任务 UUID>" } }` | 单个调查的权威状态、任务版本及报告绑定 |
+| `weapp-vite_claim-investigation` | `arg0`：`id`、`version`、`agentName` | 领取任务；仅本次响应返回私有 `claimToken` |
+| `weapp-vite_propose-investigation` | `arg0`：`id`、`version`、`claimToken`、`proposal` | 回传精确路径、变更说明、检查与风险；服务端生成提案 ID |
+| `weapp-vite_start-investigation` | `arg0`：`id`、`version`、`claimToken` | 消费浏览器对当前提案的授权，记录开始；不启动进程 |
+| `weapp-vite_complete-investigation` | `arg0`：`id`、`version`、`claimToken`、`receipt` | 回传外部执行结果；不自动标记验证通过 |
+
+示例 revision、路径和 ID 必须来自当前状态与查询结果。参数使用 DevFrame 原生的位置参数包装 `arg0`，结果提供对象型 `structuredContent`。推荐先取状态和摘要，再查询包／产物／模块，最后按需读取文件片段；无需下载整份报告自行排序或比较。
+
+- 摘要和目录查询的 `target` 默认为 `current`，也可读 `previous` 的报告元数据；结果携带 `revision` 与 `reportHash`。列表默认 `offset: 0`、`limit: 20`，最多 100 项，返回匹配 `total` 和 `nextOffset`，末页为 `null`。报告更新后旧 revision 与过期异步读取会被拒绝，须重新取状态，不能混用跨版本页面。
+- 包与产物的模块归属来自报告的模块使用记录，包含没有 chunk 贡献列表的资源源码。模块查询支持 `packageId`、`artifact`、`sourceType`、`query`，包与产物条件必须命中同一处归属。用返回的模块 `id` 查询产物可定位构建位置，不代表已经取得源码 importer 因果链。
+- 模块 `bytes` 沿用共享分析的最大已知单份体积口径；缺失贡献时可使用原始体积估算。`estimatedSavingBytes` 不是保证可删除的字节，`hasIndependentPackage` 提示可能必须保留隔离。未记录大小的产物返回 `size: null`，摘要与包行的 `unmeasuredFiles` 标明未计入字节总量的文件。
+- 预算复用构建侧的文件去重、分包 `packageBytes` 覆盖与 `runtimeBytes` 限额。摘要分别返回 `totalBudget`、`runtimeBudget`（未配置时为 `null`）和仅统计包的 `packageBudgets`；缺失体积或运行时归因时状态为 `unknown`，包查询支持 `budgetStatus: "unknown"`。`measurement` 区分 `file-bytes`、`upper-bound` 与 `unavailable`；运行时混合 chunk 的文件上界不是精确运行时代码量。摘要及包行的预算对象不附带全量 `files` 数组，须通过产物查询继续定位。
+- 比较的 `scope` 为 `package`、`file` 或 `module`，可筛选 `packageId`、`change`、`query`。包筛选在模块归并前生效，`totals` 始终表示整个构建的产物总量。模块差异基于已记录的模块体积贡献并按来源身份归并；资源文件变化可用 `file` 查询。模块与文件增量不能相加。没有上次报告时返回 `available: false`、`totals: null`，不假造零基线。
+- 比较中的缺失测量不视为零：对应 `currentBytes`／`previousBytes` 与 `deltaBytes` 返回 `null`，仍存在但不可判断增减的行标为 `change: "unmeasured"`（两边都缺失时也返回）。新增／删除保留成员变化，哪怕字节为零或未知。`totals.currentUnmeasuredFiles`／`previousUnmeasuredFiles` 标明完整性；任一文件未测量时，该侧总量和总增量为 `null`。列表先按已知增量绝对值排序，再列出未测量行。
+- 事件支持 `kind`、`level`、精确 `source`、文本 `query` 和含时区的 ISO `since`／`until`（包含边界），按 ISO `occurredAt` 记录时间筛选，不比较本地化显示时间。事件独立于构建 revision；最多保留 24 条，`total` 是当前窗口的匹配数，`retention` 返回容量、保留数、实际丢弃数和最早保留时间。它不是持久历史，也不是小程序 console/network。
+- 文件 `range` 使用零起始 UTF-16 码元偏移，`limit` 为 1–16384；返回 `totalCharacters` 与可继续读取的 `nextOffset`。`size` 仍是完整文件的 UTF-8 字节数。EOF 偏移返回空片段，超出 EOF 拒绝；省略 `range` 保留页面所需的全文读取。片段读取不会绕过单文件 2 MiB、报告 allowlist、根目录和符号链接限制。
+- 源码是受限的实时磁盘读取；产物只来自当前分析快照，不回退到实时 `dist`，也不提供上一快照的文件内容。只有确需导出完整报告时才按描述符 `pages` 依次拼接 JSON 文本页。
+
+证据查询复用同一份报告与读取边界；预算、重复分析和比较由浏览器安全的 `weapp-vite/dashboard/analyze` 纯计算入口统一提供，UI、MCP 与 Markdown 报告不另建分析服务。该入口导出 `createAnalyzeBudgetCheck`、`createDuplicateModuleInsights`、`createAnalyzeComparison` 及对应类型。新增的四个调查动作只写任务元数据；MCP 不提供通用 shared-state、任意文件写入或命令执行。
+
+直接使用 Streamable HTTP 时，地址为 `http://127.0.0.1:<port>/__weapp-vite/__mcp`，不需要 `Authorization`，但必须发送规范 loopback `Origin`，例如 `http://127.0.0.1:<port>`。MCP 协议请求（POST / GET / DELETE）缺少或携带不合法的 Origin，或 socket 对端非 loopback / 无法识别时返回 403；`Forwarded` / `X-Forwarded-For` 等请求头不能替代真实连接对端。OPTIONS 预检由 Vite 原生 CORS 处理，可能返回空的 204；它不执行 MCP 工具，也不放宽后续协议请求的门禁。
+
+该模式信任同机进程，不区分本机用户。不要通过代理、隧道或端口转发对外发布 Dashboard：本机代理会使远端请求表现为本机连接。共享机器上需要身份隔离时，应使用具有相应认证策略的宿主，而不是将独立 Dashboard 当作用户级权限边界。
+
+嵌入 Vite DevTools 时，同一份定义可由宿主的 MCP 暴露，但认证、Origin、共享状态和发现策略仍由宿主配置持有；独立 Dashboard 的本机策略不会打开或收窄共享宿主的 MCP。
+
+#### 调查、授权与复验
+
+1. 在 Dashboard「对象检查」中选择真实包、产物或模块落点，创建并编辑调查。提交绑定 `{ sessionId, revision, reportHash }`、目标和问题；后续浏览其他对象不会改绑草稿。仅有模块落点但没有对应真实产物时，不提供调查提交或内容读取。
+2. 外部客户端先取得状态与任务，再用当前 `id`、`version` 领取。保存领取响应中的 `claimToken`，不要写入共享上下文；它不会出现在列表、状态通知或复制文本中。`agentName` 是自报名称，不是认证身份或在线心跳。
+3. 使用证据查询调查，再回传 `proposal: { summary, changes: [{ path, description }], checks, risks }`。至少列出一项变更与一项检查；提议的检查不是已执行结果。浏览器展示路径、风险和服务端生成的提案 ID，用户勾选并明确授权该提案；替换提案、报告变化或任务版本变化后不能沿用旧确认。
+4. 客户端重新读取任务版本，再调用 `start-investigation`。成功仅记录本次提案的执行意图；文件和命令权限仍须由外部工作区单独授予。真正执行发生在外部，Dashboard 不运行命令，也不会因为复制上下文或提交任务而启动 Agent。
+5. 执行后回传 `receipt: { outcome, summary, changedFiles, checks: [{ command, outcome, summary }] }`。顶层 `outcome` 为 `completed` 或 `failed`，检查结果为 `passed`、`failed` 或 `not-run`。浏览器将这些内容标为 Agent 自报，不把它们当作独立验证。
+6. 回报完成后，在同一宿主生成更新报告，实际检查对象和行为，再由浏览器提交复验摘要与明确确认。原报告、缺少摘要或未确认时不能复验。对象已从新报告删除时，复验测量为 `null`，不把缺失当作零字节；新报告本身也不证明修复或节省量。
+
+创建、取消、授权和复验只向浏览器 RPC 开放，不列入 Agent 工具，猜测工具名也不能调用。所有已有任务变更使用 `id`／`version` 比较并更新；冲突后重新取权威状态，不盲目重放变更。调查变更有独立版本，不递增构建 revision。
+
+报告更新会将尚未开始执行的提交、领取、提案或授权置为 `stale`，撤销旧领取与授权；执行中及已有回报保留原报告绑定。取消只停止接受本任务的后续回报，不能终止外部进程或撤销文件修改。任务保存在宿主会话内，最多 32 项；最旧已结束记录可能被移除，活动任务占满时拒绝新增，不是持久审计库。
+
+「浏览器授权」是协议入口与明确确认的区分，不是不可伪造的人类身份或操作系统权限隔离。同机进程的信任边界仍适用。报告 hash 固定报告内容，不固定实时源码；原始产物、Gzip、Brotli、模块归因和源码字节必须分开解释，不能相加或推导虚假的优化收益。
+
+
 ## 2. 快速接入客户端
 
 如果你的目标不是“研究 MCP 地址”，而是尽快让 AI 工具开始可用，推荐直接使用下面这组命令：
@@ -302,7 +391,7 @@ MCP 服务端做了以下约束：
 
 1. `wv mcp init <client>` 写入失败：先确认目标配置文件可写。
 2. `wv mcp doctor <client>` 失败：优先看配置文件里是否已经生成 `weapp-vite-*` server 条目。
-3. `weapp-vite mcp` 启动失败：确认 Node 版本符合 `^20.19.0 || >=22.12.0`。
+3. `weapp-vite mcp` 启动失败：确认 Node 版本符合 `^22.18.0 || ^24.11.0 || >=26.0.0`。
 4. AI 看不到包内容：检查 `--workspace-root` 是否指向正确仓库根目录。
 5. 命令执行失败：确认命令在白名单中，并检查子目录权限与脚本名是否存在。
 
@@ -355,3 +444,7 @@ MCP 服务端做了以下约束：
 4. 如果命令通过，输出 compare-ok；如果对比失败，输出 compare-failed。
 5. 最后汇总：执行命令、关键输出、最终结论。
 ```
+
+## 验收任务
+
+现有服务提供 weapp_project_inspect、weapp_acceptance_start/status/cancel/report，无需模型 Key。验收与其他运行操作按工程互斥；任务使用独立日志订阅。HTTP 请求共享任务服务，断开单次请求不会丢失任务；服务关闭保存取消结果，重启不重放交互。

package/dist/docs/testing.md

@@ -20,7 +20,7 @@ export default defineConfig({
 ## 接入
 
 ```ts
-import { mpcoreTest } from '@mpcore/vitest'
+import { mpcoreTest } from '@mpcore/vitest/config'
 import { defineConfig } from 'vitest/config'
 
 export default defineConfig({
@@ -37,7 +37,34 @@ const project = await createWeappViteTestProject({ cwd: process.cwd() })
 const result = await project.renderPage('/pages/index/index?source=test')
 ```
 
-默认产物目录为 `.weapp-vite/test-artifacts/`。构建调用 `weapp-vite/test` 程序化入口，最终文件仍由 Vite/Rolldown emit；不会启动 CLI 或由测试适配器手写 bundle。
+默认在 `.weapp-vite/test-artifacts/` 下按进程、配置和构建批次创建独立产物。缓存同时检查源码、配置、编译依赖和产物内容；新构建不会覆盖正在运行的测试所用批次。显式 `outDir` 由调用方负责避免并发共享。所有测试关闭后，可以清理这个生成目录。
+
+构建调用 `weapp-vite/test` 程序化入口，最终文件仍由 Vite/Rolldown emit；不会启动 CLI 或由测试适配器手写 bundle。`isTestArtifactCurrent(artifact)` 可检查当前进程生成的产物是否仍然有效。
+
+## Vitest watch 联动
+
+在配置中显式接入产物构建和监听：
+
+```ts
+import { mpcoreTest } from '@mpcore/vitest/config'
+import { buildWeappViteTestArtifact, watchWeappViteTestArtifact } from '@mpcore/weapp-vite'
+import { defineConfig } from 'vitest/config'
+
+const options = { cwd: import.meta.dirname }
+
+export default defineConfig({
+  plugins: [mpcoreTest({
+    artifact: {
+      build: () => buildWeappViteTestArtifact(options),
+      watch: callbacks => watchWeappViteTestArtifact({ ...options, ...callbacks }),
+    },
+  })],
+})
+```
+
+测试文件从 `@mpcore/vitest` 导入 `createMpcoreTest()`，无参调用会使用当前 runner 提供的完整产物，每个测试创建独立运行时。一次性执行只构建一次；watch 在源码、配置及编译依赖重建完成后重新运行所属测试项目。退出会等待进行中的构建并关闭监听。不要从测试配置导入包含 fixture 的根入口，配置入口使用 `/config`。
+
+Vitest 的源码覆盖率、生成的小程序 JS 覆盖率和模拟器自身覆盖率属于不同观察面；此适配不会把它们自动合并成业务源码覆盖率。
 
 ## 组件
 

package/dist/docs/troubleshooting.md

@@ -39,6 +39,10 @@ weapp-vite ide logs --open
 
 如果 DevTools 未能自动连接，先运行 `wv ide doctor --json`。`wv open`、`wv dev -o` 和 `wv ide logs --open` 默认先通过官方 CLI 打开项目，再连接 automator；只有需要兼容旧链路时才使用 `--ide-open-strategy automator`。
 
+`wv ide doctor` 的原生 `islogin` 查询可能拉起 IDE；只需要静态诊断时使用 `wv doctor --format json`。只读 automator 连接失败不会删除持久化会话记录。连接成功后若 `Tool.getInfo` 失败，`automator` 仍为 ok，`tool` 单独标记 warning，并释放本次连接；不能据此认定登录失效。
+
+登录诊断仅在原生响应明确包含 `login: true/false` 时确认状态。CLI 退出成功但没有明确结果、查询超时或执行失败均标为 unknown，不再误报已登录或未登录。
+
 如果项目启用了 `weapp.forwardConsole.enabled = 'auto'`，AI 终端场景下 `dev --open` 也可能自动附加日志桥。
 
 ## `.vue` 文件存在，但提示未安装 `wevu`
@@ -62,3 +66,7 @@ pnpm --filter weapp-vite build
 ```
 
 再做下游验证。
+
+## IDE 恢复与窗口保留
+
+打开项目、刷新索引或截图重试失败时，CLI 会保留现有开发者工具窗口，只重试目标项目连接；不会自动退出整个应用或按进程名终止宿主。`--no-open-recovery` 可禁用打开后的自动重试。需要真正关闭窗口时，请在 IDE 中明确选择目标项目；`wv close` 失败会返回非零退出码，不会升级为系统级退出。

package/dist/docs/uni-app-component-libraries.md

@@ -1,12 +1,12 @@
 # uni-app 组件库兼容（实验性）
 
 > [!WARNING]
-> 这是实验性能力，当前兼容基线固定为 `@wot-ui/ui@2.2.0` 与 `uview-plus@3.8.112`。默认完全关闭；只有项目源码和 `weapp.uniApp.include` 明确列出的 npm 包会进入 uni-app 方言转换。
+> 这是实验性能力，当前兼容基线固定为 `@wot-ui/ui@2.3.2` 与 `uview-plus@3.8.130`。默认完全关闭；只有项目源码和 `weapp.uniApp.include` 明确列出的 npm 包会进入 uni-app 方言转换。
 
 ## uview-plus
 
 ```bash
-pnpm add weapp-vite wevu uview-plus@3.8.112
+pnpm add weapp-vite wevu uview-plus@3.8.130
 ```
 
 ```ts
@@ -36,9 +36,9 @@ export default defineConfig({
 
 应用启动时调用 `mount$u()`，再把 `uni.$u` 同步到 `app.config.globalProperties.$u`；全局样式引入 `uview-plus/index.scss`。不要使用会在 Web 调用 `Vue.component` 的默认插件注册流程。
 
-仓库兼容矩阵通过 `patches/uview-plus@3.8.112.patch` 保留 9 项小程序选择器与微信组件主题变量兼容调整。3.8.86 基线中的 `u-slider` 和 `u-tabbar-item` 补丁已经由上游修复，新版不再重复应用。
+上游 3.8.130 已修复 `u-barcode` 获取 canvas 引用前的组件实例 `this.$nextTick()` 等待逻辑，仓库已移除对应补丁。旧版的选择器、主题变量及其他组件兼容补丁也已由上游修复。
 
-`UviewPlusResolver()` 同时解析 `u-*` 与 `up-*` 标签。静态清单以 3.8.112 npm 发布包中的 139 个顶层 SFC 为准，双前缀共 278 个标签；137 个具名组件各有独立测试页。`u-action-sheet-data` 与 `u-column-notice` 没有组件名，分别由 action-sheet 和 notice-bar 页面覆盖。
+`UviewPlusResolver()` 同时解析 `u-*` 与 `up-*` 标签。静态清单以 3.8.130 npm 发布包中的 141 个源码入口为准，139 个具名组件各有独立测试页。`u-action-sheet-data` 与 `u-column-notice` 没有组件名，分别由 action-sheet 和 notice-bar 页面覆盖。
 
 `supportFilesStrategy` 默认为 `'used'`；需要生成全量组件辅助文件时可传入 `UviewPlusResolver({ supportFilesStrategy: 'full' })`。
 
@@ -59,7 +59,7 @@ pnpm e2e:ide:component-libraries:visual:full
 ## 安装
 
 ```bash
-pnpm add weapp-vite wevu @wot-ui/ui@2.2.0
+pnpm add weapp-vite wevu @wot-ui/ui@2.3.2
 ```
 
 ## 配置
@@ -82,7 +82,7 @@ export default defineConfig({
 })
 ```
 
-`WotUiResolver()` 使用 Wot UI 2.2.0 的真实公开 SFC 清单建立标签映射，并返回 `sourceType: 'wevu-sfc'` 与可解析的源码 ID。不要自行假设所有 `wd-*` 标签都能通过目录名拼接得到入口。
+`WotUiResolver()` 使用 Wot UI 2.3.2 的真实公开 SFC 清单建立标签映射，并返回 `sourceType: 'wevu-sfc'` 与可解析的源码 ID。不要自行假设所有 `wd-*` 标签都能通过目录名拼接得到入口。
 
 `weapp.uniApp` 的行为：
 
@@ -109,7 +109,7 @@ pnpm build:web
 
 ## 兼容矩阵
 
-矩阵以 `@wot-ui/ui@2.2.0/global.d.ts` 实际公开的 99 个 Vue SFC 为准。每个组件都有独立页面；依赖父容器的组件会在自己的页面内使用最小父组件承载。
+矩阵以 `@wot-ui/ui@2.3.2/global.d.ts` 实际公开的 100 个 Vue SFC 为准。2.3.2 新增 `wd-qr-code`，每个组件都有独立页面；依赖父容器的组件会在自己的页面内使用最小父组件承载。
 
 ```text
 组件 | 独立页 | Web | 微信小程序 | Headless
@@ -172,6 +172,7 @@ wd-picker-view | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
 wd-popover | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
 wd-popup | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
 wd-progress | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
+wd-qr-code | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
 wd-radio | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
 wd-radio-group | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
 wd-rate | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为