weapp-vite 7.4.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
@@ -64,6 +78,22 @@ 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 自动加载。
@@ -109,6 +139,15 @@ DevTools `0.7.6` 自身存在程序化重启边界：重复使用同一个 `DevT
 
 仓库内可通过 `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
@@ -377,6 +416,7 @@ 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
@@ -388,6 +428,8 @@ wv upload -p xhs,tt --mode test --bump patch --git-desc --dry-run
 
 `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` 替代。
@@ -443,7 +485,7 @@ wv upload -p ./dist -v 1.2.3 -d "release"
 
 每次旧顶层调用只警告一次未来移除，不要求立即改写脚本；若只想保留 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`（含其 `--no-*` 形式）混用，在 IDE、编译或版本修改前报错；SDK dry-run/自动版本不适用于 IDE。`--desc` 共用，`-d` 只在旧调用中是说明，原生命令中仍是 debug。
+`-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)。
 
@@ -540,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

@@ -61,6 +61,8 @@ wv upload -p xhs,tt --mode test --bump patch --git-desc --dry-run
 
 `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 上运行。
@@ -76,7 +78,7 @@ SDK 命令 `wv upload -p weapp` 无需 `--project`，会自动定位本次构建
 
 旧顶层语法每次只警告一次未来弃用，不要求立即迁移；稳定的显式 `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` 不能用于旧 IDE 上传。`wv upload --help` 是 SDK 帮助，`wv help upload` 保留旧 IDE 帮助并警告，`wv ide help upload` 不警告。完整标记、短参数和 `=` / `--` 规则见[本地速查](./upload.md#旧上传兼容与迁移)。
+`-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#旧上传兼容与迁移)。
 
 ### 构建并预览
 

package/dist/docs/index.md

@@ -21,10 +21,12 @@
 
 ## 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 的推荐工作流。
@@ -32,7 +34,7 @@
 - `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 | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为

package/dist/docs/upload.md

@@ -97,12 +97,28 @@ CI 可继续按 `run_number` 生成版本并显式传 `--uv` / `--desc`，不需
 ## 环境与密钥安全
 
 - 默认 mode 为 `production`；`--mode test` 选择测试环境文件，但仍是生产构建。
-- 覆盖优先级：`.env` → `.env.local` → `.env.<mode>` → `.env.<mode>.local` → 进程环境。不要用保留的 mode `local`。
-- 环境目录由 Vite `root` / `envDir` 决定；`envDir: false` 只读取进程环境。
+- 覆盖优先级：`.env` → `.env.local` → `.env.<mode>` → `.env.<mode>.local` → 进程环境；支持变量引用。不要用保留的 mode `local`。
+- 环境文件采用 `dotenv-expand 1000.0.0`：文件值中的 `$(...)` 自动执行命令替换；提供 `DOTENV_PRIVATE_KEY` 时，`encrypted:` 前缀的文件值会尝试解密，未提供私钥时保留该值。没有公开的命令替换或解密禁用开关，反斜杠不能阻止 `$(...)` 命令替换，只加载可信文件。
+- 进程同名值包括空字符串均原样采用；被覆盖的文件值在展开前排除，不执行其命令替换或解密。加载器不将展开后的凭据写回 `process.env`。
+- 含字面 `$(...)` 的凭据直接通过 CI Secrets 或进程环境提供，不写入环境文件，也不在其他文件变量中再次引用它；引用展开后仍可能执行命令替换。
+- 环境目录由 Vite `root` / `envDir` 决定；`envDir: false` 完全禁用此入口的环境文件加载与展开，只读取进程环境，不对其值执行命令替换或解密。
 - 两个密钥文件路径相对源码项目根（命令的 `[root]`），不是相对环境目录或输出目录。
 - `.env.local`、`.env.*.local`、`.keys/` 加入 `.gitignore`；密钥放在源码和静态资源目录之外，不加 `VITE_` 前缀。
 - CI 使用 Secrets 或临时安全文件，测试通过后显式上传；文件用后删除，不向不可信 PR 暴露凭据。
 
+单层反向引用 `A=$B`、`B=value` 仍可展开；多级反向声明 `A=$B`、`B=$C`、`C=value` 会得到 `A` 为字面 `$C`，而 `B`、`C` 为 `value`。多级引用应按依赖顺序先定义基础值，例如依次声明 `C=value`、`B=$C`、`A=$B`，不要依赖任意反向链递归展开。
+
+变量引用必须无环，否则展开可能停滞。避免在同一文件重复声明同名变量；覆盖放到更高优先级的环境文件，先声明基础值，再声明引用它的变量。合并后的文件变量按最后生效声明的位置展开，以复用已经展开的命令输出或解密结果。
+
+默认值与替代值表达式区分未定义和空字符串：
+
+| 表达式 | `VAR` 未定义 | `VAR` 是空字符串 |
+| --- | --- | --- |
+| `${VAR-fallback}` | `fallback` | 空字符串 |
+| `${VAR:-fallback}` | `fallback` | `fallback` |
+| `${VAR+alternate}` | 空字符串 | `alternate` |
+| `${VAR:+alternate}` | 空字符串 | 空字符串 |
+
 ## 多平台与输出校验
 
 单平台根目录原生 JSON、多平台各端独立 JSON、统一 `projectConfigs` 三种入口都保留，不强制迁移。想减少重复文件时，可以在一份 `vite.config.ts` 中使用 `weapp.multiPlatform.projectConfigs`：
@@ -156,6 +172,27 @@ pnpm exec wv preview -p xhs,tt
 
 `--dry-run` 不加载 SDK、不校验凭据或官方平台规则、不生成二维码；上传入口仍要求非空版本。它不能证明平台授权、网络、IP 白名单或扫码权限正确。上传失败后保留错误并定位根因，不把 SDK 提前退出视为成功；取消命令不能撤回已被平台接收的版本。
 
+## 结构化结果与本地超时
+
+```bash
+wv upload -p xhs,tt --json --timeout 180 > upload-report.json
+wv upload -p all --dry-run --json
+```
+
+`--json` 让 stdout 只输出一个报告，日志和官方进度进入 stderr；失败退出码非零。不使用 JSON 时仍打印逐平台汇总。`--json` / `--timeout` 仅适用于独立 SDK `upload`，不适用于 `build --upload`、`preview`、IDE 上传或 `weapp.upload` 配置。
+
+报告为 `{ schemaVersion: 1, action: "upload", status, results, error? }`。整批 `status` 为 `success` / `failed`；`results` 按请求顺序保留各平台的 `platform`、可选 `requestedVersion`、最后进入的 `stage`（`prepare` / `build` / `validate` / `upload`）及 `status`（`success` / `failed` / `not-run` / `dry-run` / `unknown`）。从配置推断但尚未解析的平台为 `null`；列表解析前失败时 `results` 可为空。首次失败后保留前序结果，后续条目为 `not-run`。
+
+成功条目的 `result` 只含官方实际返回的可选信息：微信的 `subPackages` / `plugins`（体积为字节），支付宝的 `sdkVersion` / `qrCodeUrl`，抖音的 `previewUrl` / `qrCodeFile`，京东的 `qrCodeUrl` / `qrCodeBase64`，百度的 `previewUrl` / `fileSize` / `warnings`；小红书成功结果为 `{}`。不从请求版本或内部标识推断 SDK 确认版本，不因可选信息缺失而改判失败。字段结构见[完整结果参考](https://vite.weapp.dev/guide/upload.html#report)。
+
+进度只使用公开能力：微信任务状态／消息、小红书百分比、支付宝日志／任务创建／版本创建事件。其他平台不伪造百分比；任何进度事件都不能替代 SDK 完成确认和正常退出。
+
+`--timeout` 是每个平台 SDK worker 的本地超时，不含构建；默认不增加超时。值为正数秒，精度不超过毫秒，最大 `2147483.647` 秒。SDK 执行期间，`SIGINT` / `SIGTERM` 或超时会触发本地上传进程树清理，无法确认清理完成时报告错误。构建等前置阶段保留原有信号退出行为，不等待挂起的构建，也不保证生成最终报告。
+
+Windows 使用 PowerShell 查询已退出 worker 的子进程归属，单次查询最多等待 30 秒；这是 SDK 执行结束后的本地清理预算，不包含在 `--timeout` 内。查询或终止失败仍然报错，不会跳过清理或自动重试上传。
+
+SDK 开始后超时／中断标记 `status: "unknown"`、`remoteOutcome: "unknown"`；SDK 尚未开始时可为 `remoteOutcome: "not-started"`。其他 SDK 错误也可能携带 `remoteOutcome: "unknown"`。**本地停止不代表远端取消**，先核实平台状态再重试；不会自动重试、回滚、提审、设置体验版或正式发布。
+
 ## 完整教程
 
 - [微信](https://vite.weapp.dev/guide/upload/weapp.html)
@@ -182,7 +219,7 @@ wv upload --project=./dist --version=1.2.3 --desc="release"
 
 SDK 迁移不是等价换名：回到包含 `package.json`、Vite 配置和源码的项目根，安装 `miniprogram-ci` 并配置 AppID、上传私钥和 IP 白名单，再执行 `wv build --upload -p weapp --uv 1.2.3 --desc "release"`。不要把旧 `--project` 的构建产物目录当作 SDK `[root]`；SDK 需要新凭据，不复用 IDE 登录。
 
-- 旧标记为 `--version/-v`、`--project`、`--appid`、`--ext-appid`、`--info-output/-i`；SDK 标记为长参数 `--platform`、`--uv`、`--bump`、`--git-desc`、`--dry-run`。混用在 IDE、编译或版本修改前报错；SDK 标记的 `--no-*` 形式也不能混入旧调用。dry-run、自动升版与 Git 说明不适用于 IDE。
+- 旧标记为 `--version/-v`、`--project`、`--appid`、`--ext-appid`、`--info-output/-i`；SDK 标记为长参数 `--platform`、`--uv`、`--bump`、`--git-desc`、`--dry-run`、`--json`、`--timeout`。混用在 IDE、编译或版本修改前报错；SDK 标记的 `--no-*` 形式也不能混入旧调用。SDK 专属选项不适用于 IDE。
 - `-p` 仅在有旧标记时表示 IDE 项目目录，否则表示原生平台；不根据路径存在与否或值是否像平台名猜测。`--desc` 共用，`-d` 仅在旧调用中是说明，原生命令中仍是 debug。
 - 参数支持分开和 `=` 形式；必填值只是数据，仅在选项位置遇到 `--` 后停止扫描。
 - `wv upload --help` 查看 SDK 帮助；`wv help upload` 保留旧 IDE 帮助并警告未来弃用；`wv ide help upload` 保持显式 IDE 帮助、不警告。工具自身版本查询用 `wv --version`。