weapp-ide-cli 6.1.9 → 6.3.0

package/README.md

@@ -253,6 +253,59 @@ if (isWeappIdeTopLevelCommand('preview')) {
 console.log(WEAPP_IDE_TOP_LEVEL_COMMAND_NAMES)
 ```
 
+截图发生协议、导航或截图请求超时时，默认最多重试一次，失败连接由原会话生命周期释放，不在重试层按项目键再次关闭共享连接；不调用无项目定位的 `close` 或退出共享宿主。重试仍失败时保留原始错误，手动打开的窗口和其他项目保持不变。
+
+登录诊断可使用 `queryWechatIdeLogin(cliPath, { timeout: 3000 })`，显式指定本轮选择的 CLI。只有原生 JSON 中的 `login` 布尔值才返回 `{ status: 'success', login }`；超时、命令失败、空输出或矛盾响应均返回 `{ status: 'unknown', reason }`。`unknown` 不等于未登录。机器租约冲突返回 `reason: 'runtime-busy'`，应等待持有者结束后再查询。该方法不提示、不重试、不回退安装路径；原生 `islogin` 可能启动 IDE，不属于静态探针。旧的 `isWechatIdeLoggedIn()` 保留 CLI 透传行为，其 Promise 完成不能作为登录事实。
+
+### 安装选择与共享登录
+
+默认选择本机已安装的最新 Stable；官方灰度发布或网络查询失败不会阻塞默认选版。macOS 扫描系统及用户 Applications，Windows 读取安装登记和常见目录，Linux 与自定义位置通过显式 CLI 路径或本地登记接入。渠道和产品版本读取实际应用元数据，按数字段比较版本；符号链接按真实安装去重，同版本存在多份安装时要求 `--cli-path`。
+
+```sh
+weapp devtools list --json
+weapp devtools add "<path-to-cli>"
+weapp devtools remove "<path-to-cli>"
+wv ide devtools list
+wv open --devtools-channel=nightly
+wv dev --open --devtools-channel=rc
+wv ide preview --devtools-channel=rc --devtools-version=2.02.2608080
+```
+
+安装由用户完成，登记只保存 CLI 路径，每次重新读取元数据。列表显示渠道、版本、安装身份、实际配置目录及失效原因；登录使用各安装自己的配置目录，不复制 ticket、Cookie 或账号数据。
+
+同一微信账号切换安装后，另一安装的登录可能失效。无需准备多个账号，可在需要测试的版本中重新扫码；工具不共享或迁移登录数据。矩阵使用非交互模式，登录失效记录为 `blocked`，附带 `runtimeBlocker.code: "needs-login"`，保留原始错误并继续其他版本；不会等待扫码或自动重试，最终返回非零退出码。重新登录后可单独运行该渠道补测。
+
+选择优先级为：已固定的 `target` / 当前操作安装 → 本次 `cliPath`、`devtoolsChannel`、`devtoolsVersion` → 环境变量 → 旧全局 `cliPath` → 本机最新 Stable。显式渠道/版本覆盖继承的路径固定；同层路径、渠道、版本必须一致。`--devtools-version` 是开发者工具产品版本，上传的 `--version` 仍为小程序版本。包装参数不会传给官方 CLI。RC/nightly 需要明确选择，操作的启动、构建、连接、恢复和清理沿用同一安装。
+
+公共环境变量为 `WEAPP_IDE_CLI_PATH`、`WEAPP_IDE_DEVTOOLS_CHANNEL`、`WEAPP_IDE_DEVTOOLS_VERSION`；E2E 使用对应的 `WEAPP_VITE_E2E_DEVTOOLS_*`，解析后向全部子进程传入具体 CLI。兼容 `WEAPP_VITE_E2E_ACCEPTED_DEVTOOLS_VERSION` / `WEAPP_VITE_E2E_ACCEPTED_DEVTOOLS_CHANNEL` 的固定选择。显式 `--require-official-latest`（或公共 `WEAPP_IDE_REQUIRE_OFFICIAL_LATEST=1`、E2E `WEAPP_VITE_E2E_REQUIRE_OFFICIAL_LATEST=1`）才要求匹配所选渠道官方最新版本，查询失败也会阻塞此严格模式。
+
+```ts
+import { listWechatDevtoolsInstallations, previewWechatIde, resolveWechatDevtoolsTarget } from 'weapp-ide-cli'
+
+const installations = await listWechatDevtoolsInstallations()
+const target = await resolveWechatDevtoolsTarget({ devtoolsChannel: 'rc' })
+await previewWechatIde({ projectPath: './dist', target })
+```
+
+两套 MCP 的连接工具和相关 REST 输入都支持 `cliPath`、`devtoolsChannel`、`devtoolsVersion`、`requireOfficialLatest`；会话按真实安装身份隔离，同一项目不会串用 Stable 与 nightly 连接。
+
+```sh
+pnpm e2e:ide:matrix --targets=stable,rc,nightly --suite=ide-smoke
+pnpm e2e:ide:matrix --targets=stable@2.02.2608080,nightly --suite=ide-gate --filter=<task>
+```
+
+矩阵默认只测 Stable，复用既有 suite 及其筛选和严格策略，全程持有同机同用户串行租约。普通测试失败或缺失安装记录后继续；所有权异常、清理失败、OOM 或取消停止后续目标。报告保存在 `docs/reports/devtools-matrix`，分别记录请求、实际安装、runtime/基础库版本、官方查询状态和结果。缺失、阻塞、partial 或未执行不能计为完整通过，返回非零退出码；全量正式验收仍遵守主线工作树要求。
+
+HTTP 服务端口和 automator 会话都绑定选定安装。另一安装的配置较新、端口可连或版本号相同，均不代表可以复用。未知旧会话不会直接连接；宿主或监听端口归属不一致时停止操作，保留原有 IDE 和账号状态。`port` 仍表示对应接口原有的端口类型，不将 automator WebSocket 端口当作 HTTP 服务端口。
+
+显式 HTTP 或 automator 端口必须是 `1` 到 `65535` 的整数；CLI、MCP 和 REST 同样拒绝无效端口，不会将 `0`、小数、混合文本或超范围值当作默认端口。打开项目的 HTTP 请求与官方 CLI 回退共用一次安装选择和机器租约，安装冲突不会触发回退。
+
+`openWechatIdeProjectByHttp()` 使用 `/v2/open` 的 `project` 参数并保留原始响应正文；空正文或空 JSON 对象会抛出 `WECHAT_DEVTOOLS_HTTP_OPEN_UNCONFIRMED`，不能把 HTTP 200 当作项目已打开的证据。目标项目及 runtime 是否就绪仍需通过会话或 IDE 界面确认。
+
+本仓库真实 IDE E2E 自动解析并固定本轮安装，核对实际宿主及 runtime 版本；不会自动安装工具。不同 worktree 的 E2E 使用同机同用户的排他租约，冲突报告 `Runtime busy`，应等待持有者结束。普通 CLI 的宿主变更同样参与协调，已建立的多项目连接不长期占用此租约。自动恢复不清共享缓存、不退出账号；只释放本任务登记的资源。
+
+macOS 安装退出核验直接使用系统报告的映像路径，避免无关进程的受保护或已删除文件阻塞清理。当前磁盘路径被替换也不会覆盖原映像的归属判断；PID、启动时间、端口和任务登记仍须通过校验。
+
 ### 6. 程序化 opened-session helper
 
 除了官方 CLI 透传和 automator 子命令，`weapp-ide-cli` 也提供了一组面向「已打开 DevTools 会话」的 helper。它们会优先复用当前项目对应的会话，在官方 HTTP / Tool 域能力可用时直接下发指令，减少再次拉起 IDE 或误打开项目选择页的概率。
@@ -300,6 +353,27 @@ await clearWechatIdeCacheByAutomator({
 console.log(info, ticket)
 ```
 
+### 7. 程序化 automator 与异步断开
+
+`connectOpenedAutomator()` 返回的会话提供公开 `send(method, params?, { timeout }?)` 与 `CDP().enable/sendCommand/listProtocol/onEvent`，用于直接调用已连接 DevTools 支持的自动化和调试协议。`onEvent` 返回取消订阅函数；可用域和命令以目标宿主 `listProtocol()` 的结果为准。
+
+```ts
+import { connectOpenedAutomator } from 'weapp-ide-cli'
+
+const miniProgram = await connectOpenedAutomator({ projectPath: '.' })
+try {
+  console.log(await miniProgram.send('Tool.getInfo', {}, { timeout: 3_000 }))
+  console.log(await miniProgram.CDP().listProtocol({ timeout: 3_000 }))
+}
+finally {
+  await miniProgram.disconnect()
+}
+```
+
+`disconnect()` 现在返回 `Promise<void>`，调用时立即停止订阅并拒绝未完成请求，等待 WebSocket 关闭后完成。迁移同步清理回调时应返回或 `await` 此 Promise；超时和清理失败继续抛出。它只释放本连接，保留已打开项目窗口；需要关闭本任务受管窗口时使用相应会话的 `close()`，并等待窗口 owner 完成确认。MCP、日志转发及命令结束清理均等待各自持有的连接，不重新启动 IDE。
+
+headless 会话的 `send` 仅适配 `Tool.getInfo`、`App.getCurrentPage/getPageStack/callFunction/callWxMethod`；`CDP()` 和其他原始协议明确报告 `HEADLESS_PROTOCOL_UNSUPPORTED`。触摸接口使用标准 `changedTouches`，旧 `changeTouches` 仍兼容，同时传入以标准字段为准。
+
 ## 路径与参数兼容
 
 - `-p` 会被自动替换为 `--project`，并且相对路径会解析为绝对路径。