只读探测当前连接目标的状态（port 是否监听、devtools 是否在线、ws 是否可达、automator 是否已连），不启动 IDE、不重连、不改任何项目状态。

何时用：只想拿一份不改动现状的连接快照时（如用户问“为什么连不上”但不想动环境），或在 mp_ensureConnection / mp_recoverConnection 已失败后，用本工具读细节辅助判断。 何时不用：想“把连接弄通”时不要先调本工具——直接调 mp_ensureConnection，它会自愈/自动拉起 IDE，并在返回里自带一份 diagnosis。

⚠️ 本工具是保守设计：它如实报告 “port not listening / automation not enabled” 等，但不会修复。这种红色结果不是死路、也不需要找用户确认——下一步就是调 mp_ensureConnection 让它自动拉起/重连。

返回 JSON 含各探测项的布尔/状态字段；红色项只代表“当前未就绪”，不代表无法恢复。connection 可选，传入可临时覆盖 projectPath / wsEndpoint / mode / port 等连接参数，省略则用已配置的默认值。

确保小程序自动化会话就绪——这是连接链路的默认入口：在 mp_screenshot / page_* / element_* 之前先调它。它会自愈:会话未就绪时自动拉起微信开发者工具 / 重启 cli auto 并建立 automator 连接,不只是被动检查。

何时用:任何“先连上再操作”的场景,直接调本工具,不需要先 mp_diagnoseConnection(那是只读探测,可跳过)。 失败时:先读错误信息里的 Next step 引导,通常是 ① 带 reconnect=true 重试,或 ② 先 mp_listProjects 再带 projectSelection 重试——不要原样重试同一调用,也不要直接停下来找用户。

defaultProject 不在 recents 时,server 会用 defaultProject 重启 cli auto,第一次仍可能失败——此时按错误信息 retry 即可。

返回 JSON 含 mode / projectPath / defaultProjectPath / wsEndpoint / port / 内嵌 diagnosis / currentPage(已就绪可信,无需再调 mp_currentPage 校验)/ systemInfo。connect 模式无法确认 IDE 当前打开项目时 projectPath 会是 null，defaultProjectPath 仅表示持久化默认值，不会冒充当前项目。

参数:reconnect=true 强制丢弃现有会话重连(用于会话疑似失效/卡死);projectSelection 传 mp_listProjects 返回的 index / name / path 之一,用于在“需要选择项目”的提示后定向选中；所选路径会用于当前 ensure 并保存为默认项目，同名项目请用 index 或完整 path 消歧。connection 可选,覆盖默认连接参数。

只读聚合当前自动化环境健康状态:连接(devtoolsOnline / wsReachable / automatorConnected)、当前页面路由、项目、日志监听、以及上次 mp_screenshot 结果(lastScreenshotOk / errorCode)。不修复任何东西——要恢复用 mp_recoverConnection,要建立连接用 mp_ensureConnection。

何时用:操作出问题时先调它看全局状态;尤其在 mp_screenshot / page_snapshot 反复失败后,先 healthCheck 再决定是否 mp_recoverConnection。 关键字段:summary='degraded' 表示至少一项能力降级,但不一定可通过重连修复；只有 needsRecovery=true 才调 mp_recoverConnection。连接全绿但 lastScreenshotOk=false 时会返回 summary='degraded' + needsRecovery=false,说明是截图通道降级,不要循环重连。

serverVersion 是本 MCP server 的版本号(不是小程序版本、不是基础库版本、不是开发者工具版本),反馈/调试时带上它即可。

参数:includePage=true 额外探当前路由,includeLogs=true 额外查日志监听状态(都默认 true;探测失败只会进 warnings,不影响其余字段)。connection 可选,覆盖默认连接参数。

按标准顺序修复一个已存在但降级/失效的连接:重建 automator 会话 → 重挂日志监听 → 恢复项目上下文,并返回恢复前后对比。

何时用:这是升级修复步——只有当 mp_healthCheck 显示 needsRecovery=true 时调它,而不是只看 summary='degraded' 就重连。 何时不用:首次“建立连接”不要用本工具,用 mp_ensureConnection(它才负责自动拉起 IDE)；连接全绿但截图失败且 needsRecovery=false 时也不要用,重连无法修复截图通道。与 ensure(reconnect=true) 的区别:本工具跑一套有序修复并报告 before/after,ensure 只是把会话弄就绪。

⚠️ 副作用(launch 模式):重连会退出并重新 launch 小程序(App.exit + 关 IDE 窗口 → cli auto 冷启),页面栈被重置回项目的启动/入口页 —— 当前所在页 / reLaunch 的现场会丢失。所以仅在连接确实降级失效(needsRecovery=true)时用;若只是想保留当前页、连接其实没坏,不要用本工具。connect 模式(配置了 wsEndpoint)只断开重连 WS、不重启小程序,不丢页。

返回 JSON 含 ok / recovered、actions、before/after 状态、health.summary、warnings/errors。recovered=true 只表示连接恢复完成；若历史截图仍失败,health.summary 会保持 degraded 但 needsRecovery=false。recovered=false 说明连接修复未完成——此时不要无限重试,确认开发者工具确实在运行,必要时反馈给用户。

参数:reconnect 默认 true(丢弃旧会话重连);设 false 仅在不想强制重连、只想跑其余修复步骤时用。connection 可选,覆盖默认连接参数。

在小程序内导航并返回导航后的 activePage(path+query)。返回的 activePage 是这次导航 resolve 的真实当前页,可直接信任,无需再调 mp_currentPage 或 mp_evaluate 交叉校验路由。

transition 怎么选:

• navigateTo(默认):压栈打开新页,可 navigateBack 返回。

• redirectTo:关掉当前页再打开,不入栈。

• reLaunch:关掉所有页栈后打开(回首页 / 重置状态用)。

• switchTab:仅用于 app.json tabBar 里注册的 tab 页,且不支持 query;跳非 tabBar 页会报 'can not switch to no-tabBar page' —— 这种情况改用 navigateTo。(不确定哪些是 tab 页时,custom-tab-bar 项目 tabBar 可能为空,需查 app.json 的 tabBar.list 或 pages。)

• navigateBack:返回上一页,此时整个省略 path(切勿传空字符串 ""——会被 schema 当作非法 path 拒绝);其余 transition 都必须传 path。

query 用 query 参数传(对象,如 {id:'1'}),会自动拼到 url,不要手动拼进 path;switchTab 除外。

⚠️ waitMs 是 dumb sleep,不是等条件。时序敏感场景(onShow 鉴权 / SSE 初始化 / 异步 setData)建议 waitMs 留小(如 500 给 transition 过渡),再用 mp_pollUntil 等具体条件就绪。若 waitMs 阶段超时,错误里会带 currentRoute 帮你判断导航是否其实已生效。

截取当前小程序视口截图。需已有活动会话(无会话先 mp_ensureConnection)。不传 path 返回内联图片(image content);传 path 则存文件并返回 JSON {ok,path,route} —— 此时拿不到图像本身，route 为可空诊断字段。 父目录不存在会自动 mkdir -p；文件模式会验证输出存在且非零字节后才返回成功。

⚠️ 截图是单通道串行能力:全局一次只跑一个,不要并发拍图;超时后也不要立刻重发(底层那条超时请求仍占着单通道,再发会互相打乱)—— 等本次调用返回再说。截图前不会额外读取 currentPage，避免非必要请求先占住截图通道。仅支持开发者工具模拟器(客户端环境可能返回 EMPTY_OUTPUT)。

失败时返回 reasonCode 并附可操作建议:SCREENSHOT_TIMEOUT、SIMULATOR_HIDDEN、RENDERER_NOT_READY、LOCAL_OUTPUT_ERROR、EMPTY_OUTPUT、UNKNOWN。只有 RENDERER_NOT_READY 会自动重试一次；本地输出错误不会计入截图通道连续失败。连续 2 次拿不回帧后,后续截图会直接返回 SCREENSHOT_UNAVAILABLE 跳过;确认环境恢复后传 force:true 再试。

调用微信小程序 API。method 不带 wx. 前缀(内部自动拼),例如传 pageScrollTo 而非 wx.pageScrollTo。args 是按位置依次展开的参数数组:多数 wx API 收单个 options 对象,所以传 [{ scrollTop: 0, duration: 300 }](数组里放那一个 options 对象),而不是裸对象。返回 {method, arguments, result},result 为 API 返回值。

何时用:直接触发 wx.* 能力(滚动、剪贴板、storage 等)。要读 / 改 page.data 或跑任意页面逻辑用 mp_evaluate(注:个别环境的 evaluate 注入通道不可用、对任意函数都报 'is not a function',此时改用 page_getData / page_setData / page_callMethod 兜底);要等某条件就绪用 mp_pollUntil。

向小程序 AppService 注入并执行一个函数,返回其结果。functionSource 必须是完整的 function 表达式字符串(如 function(){ return getCurrentPages().pop().data.ready } 或 () => wx.getStorageSync('token')),不能是裸语句。函数体跑在 AppService 上下文,可用 getCurrentPages()、getApp()、wx 等全局;args 数组会按顺序作为函数入参展开。返回值经 JSON 序列化,别返回 DOM/句柄类不可序列化对象。

适合在 page.data 不稳定时显式读取 / 状态机断言 / 内联绕过 modal。可选 timeoutMs 覆盖默认 15s(上限 600s),用于长耗时异步。⚠️ 等任意条件请用 mp_pollUntil(内置 predicate 轮询,比 evaluate+waitTimeout+evaluate 手写循环稳);要调 wx.* API 用 mp_callWx。注意:函数体别遍历完整 prototype 链或做复杂反射,可能命中 SDK wrapper 抛 'Cannot read property is of undefined',保持函数体最小。

通用 wait-for-condition / waitData 工具:轮询执行 predicate(返回任意真值即命中)直到命中或超时,可选在命中后执行 action,并按 snapshotPaths 拍 before/after 快照。典型场景:等 page.data 某字段变化(predicate 写 function(){ return getCurrentPages().pop().data.conversationHistory.length === 1 })、等异步状态切换、等 SSE 流式中段、时序敏感打断。

predicate / action 是 function 源码字符串,跑在 AppService(可用 getCurrentPages、wx 等);predicateArgs / actionArgs 是按顺序展开给这两个函数的入参数组。轮询由 server 端管理,重连不留脏 setInterval。

predicate 与 dataPath 二选一:若该环境 evaluate 注入通道不可用(对任意函数都报 'is not a function'),改用 dataPath 直接轮询 page.data 的某条路径(SDK 端单路径投影,不走 evaluate)——dataEquals 省略时按真值命中、给了则与该值 deep-equal 命中(可精确等 false/0/null)。注意:命中后的 action 仍走 evaluate,evaluate 不可用时只用 dataPath+snapshotPaths(snapshot 读 page.data、不依赖 evaluate)。

snapshotPaths 走点路径取值,支持 [N] 下标、负索引、[*] 通配(如 conversationHistory[*].aiStatus、list.length);before = predicate 命中时刻的 page.data,after = action 跑完且等 snapshotAfterMs 后的 page.data(snapshotAfterMs 给异步 setData 留时间,默认 0,上限 60000,仅在传 snapshotPaths 时有效)。结果超过 maxBytes(默认 50000B)会截断。

注意:timeoutMs(默认 15s,上限 600s)是 predicate、action、等待和快照的整体预算;若比单次 evaluate 还短,可能只跑 1 次 predicate 就超时。

读取当前连接目标的小程序控制台日志,支持过滤。不同项目 / wsEndpoint 的持久化日志会隔离,不会混读或互相清空。常见用法:操作前用 clear=true 清空当前目标缓冲,操作后再读以拿到本次产生的日志。

过滤参数:

• contains:子串匹配(对 message + 序列化后的 data 一起匹配,非正则)。

• type:按级别过滤,枚举 log/info/warn/error/exception(exception 是未捕获异常,区别于 console.error)。

• since:相对时间窗口,单位毫秒 —— 只返回过去 N ms 内的日志(不是绝对时间戳)。

• limit:最多返回条数,默认 100,取最新的 N 条。

返回 {count, totalCount, logs[], filters, listenerAttached...}:count 是过滤后条数,totalCount 是当前目标缓冲区总条数(count<totalCount 说明被 limit/过滤截断)。listenerAttached=false 说明日志监听没挂上,可能漏日志,需 mp_recoverConnection。clear=true 只清空当前连接目标的缓冲。

按顺序执行一组小程序调试/回归步骤,一次调用跑完并汇总每步 pass/fail。用于把一条短链路脚本化复跑(导航→操作→断言);只做单次交互探查请用单个 page_*/element_* 工具。要把结果整理成 markdown 复核产物时改用 mp_generateScenarioReport(参数相同)。

steps[] 每项必带 type,最多 25 步,共 12 种(分动作类与断言类): ● 动作类(不返回 pass,只在抛错时算失败):

• navigate {path?, query?, transition?=navigateTo|redirectTo|reLaunch|switchTab|navigateBack, waitMs?} — 只有 navigateBack 可省略 path;waitMs 是 dumb sleep,时序敏感场景宁可用 waitRoute 步或拆出来用 mp_pollUntil

• tap {selector, innerSelector?, waitMs?}

• input {selector, innerSelector?, value(string|number)}

• snapshot {selectors?[], dataPaths?[], withData?=false, withElements?=true, withWxml?=false, limit?=10, maxBytes?=50000} — 每个 selector 受 limit 限制，所有 selector 合计最多汇总 100 个元素摘要；超 maxBytes 会截断并返回 note;比独立 page_snapshot 弱

• getLogs {clear?, contains?, logType?, since?, limit?=100}

• screenshot {path?, timeoutMs?=30000} — 不传 path 时不回传 base64(只给 note),要图请单独调 mp_screenshot 或传 path 存文件;连续 2 次截图通道失败后会短路 ● 断言类(决定 scenario 整体 ok/pass):

• waitRoute {path, timeout?=5000, retryInterval?=200} — 轮询直到 route 命中,返回 matched

• expectRoute {path} — 即时断言当前 route

• expectVisible {selector} — 命中 ≥1 个即过

• expectText {selector, expected, mode?=equals|includes}

• expectCount {selector, expected(整数)}

• expectData {path, expected} — 必须显式给 expected;path 未解析到值且 expected 省略时直接判失败(避免 undefined===undefined 静默判过)

⚠️ selector 用 page.$ / page.$$,不穿透自定义组件内部;组件内元素用 innerSelector(在父元素内再查),取第 N 个匹配用 selector[index=N] 语法。 ⚠️ 想要真正验证就必须放至少一个断言步:纯动作步全部不抛错也只代表跑通了,ok=true 不等于断言通过。

stopOnFailure 默认 true:遇到首个失败步即停,后续步不执行;设 false 跑完所有步再汇总。scenarioTimeoutMs 控制整体预算,默认 120000ms、最大 600000ms。maxBytes 控制聚合结果大小,默认 500000B。

建议每个 scenario 保持短(≤ ~10 步):snapshot/screenshot 在长链路后段更易超时/抖动 — 拆成多个短 scenario 分段跑。

返回 {ok, totalSteps, executedSteps, passedSteps, failedSteps, results[]},每个 result = {index, type, pass, step, result 或 error}。

执行一个 scenario(步骤定义与执行语义完全同 mp_runScenario:同样的 12 种 step、断言/动作 pass 规则、stopOnFailure 默认 true、selector 不穿透自定义组件等 — 先看 mp_runScenario 了解如何写 steps[]),并额外生成一份人可复核的 markdown 回归报告。只需要机器可读的 pass/fail 结果、不要报告时,用 mp_runScenario。

markdown 始终通过返回值的 report 字段回传(无论是否写盘);传 outputPath 时同时写入该路径(父目录自动 mkdir -p 创建)。

报告内容开关:includePassedSteps=false 只保留失败步(适合失败聚焦报告);includeSnapshots=false 从各步结果剥掉 data/elements/snapshot;includeLogs=false 剥掉 logs。title 为报告大标题(默认 'Scenario Report')。

返回 {ok, outputPath, title, totalSteps, executedSteps, passedSteps, failedSteps, report}。

获取当前页面信息(path、query、size、scrollTop)。withData=true 额外返回 page.data。

何时用:想一次拿“路由 + 尺寸/滚动 + 部分 data”的概览时。 何时改用别的:只想读 data 字段 → 用 page_getData;想断言/等待某个路由 → 用 page_expectRoute / page_waitRoute(它们已替你处理路由滞后),不要在这里读 path 再手动比较。

⚠️ 路由滞后:path 来自 SDK currentPage() 句柄,是快照型,仅在“刚做完快速 navigate / reLaunch / switchTab 的那一瞬间”可能落后于真实路由;稳态下可信。刚导航完一般不用调本工具——mp_navigate 返回的 activePage 已经可信。只有在确实怀疑该瞬间滞后时,才用 mp_evaluate 跑 return getCurrentPages().slice(-1)[0].route 交叉校验,别默认每次都加这步。

参数:dataPaths 只取关键字段、避免大数组爆 token,支持点路径、数组下标(含负数如 [-1])、.length、以及通配 [*](如 ['conversationHistory[*].aiStatus','isSearching']);解析不到的路径会进返回里的 missingPaths。maxBytes 默认 50000,超出按字节截断并置 truncated=true,字节数见 bytes(字段名与 page_getData 一致)。connection 可选。

列出微信开发者工具里的最近项目(返回 { defaultProject, projects:[{index,name,path}] }),并显示当前 defaultProject。

何时用:① mp_ensureConnection 返回“需要选择项目”提示后,先调本工具看有哪些项目,再把某项的 index / name / path 作为 projectSelection 传回 mp_ensureConnection;② 想固定后续连接用哪个项目时,把 path 传给 mp_setDefaultProject;③ 不确定有哪个项目可连时先调它确认。

注意:返回的是“可连接的项目”,不是项目内的页面路由——要找页面路径需读项目的 app.json,本工具不提供。无参数。

把指定项目设为持久化的默认项目;设置后下次 mp_ensureConnection 会优先用它连接。本工具只写默认值,不会自己建立连接。

何时用:只想修改后续连接默认项目、暂时不建立连接时。projectPath 传 mp_listProjects 返回的 projects[].path(项目目录绝对路径);路径无效或目录不存在会返回错误,不会静默成功。 与 mp_ensureConnection 的 projectSelection 区别:projectSelection 会在当前 ensure 调用里立即选中并连接该项目,同时也保存为默认项目;本工具只保存默认项目。设完需再调 mp_ensureConnection 才真正连上。

通过选择器获取单个页面元素，相当于 page.$(selector)。返回该元素摘要 {tagName,text,value,size,offset}（取不到的字段为 null，不代表元素不存在）；withWxml=true 额外返回完整 outerWxml。支持 selector[index=N] 选第 N 个（0 基，仅作用于 selector，innerSelector 内不支持下标）。⚠️ 单次查询，元素不存在直接抛错——若元素来自 setData 后异步渲染 / SSE 流式 / navigateTo 未稳定，先用 page_waitElement 等到再调本工具；等任意非元素条件（page.data 字段变化等）用 mp_pollUntil。⚠️ page.$ 默认不穿透自定义组件（取决于组件 styleIsolation/addGlobalClass）；组件内部元素用 selector(组件)+innerSelector，或 element_getInnerElement(s)；本工具的 innerSelector 同样是「在已匹配元素内部再查一层」。结果超过 maxBytes（默认 50000B）返回 {selector,index,truncated,bytes,maxBytes,note,data} 包装——多由 withWxml 引起，可关掉它或调大 maxBytes。

通过选择器获取页面元素数组，相当于 page.$$(selector)。返回 {selector,count,totalCount,limited,elements:[{index,tagName,text,value,size,offset}]}；limit 默认/最大 100，避免大页面一次汇总所有元素卡住连接；totalCount 是总命中数，count 是实际返回数。无匹配时返回 count:0 的空列表（不抛错，这是与会抛错的 page_getElement 的关键区别——批量/计数用本工具，单个必存在的元素用 page_getElement）。withWxml=true 给每个元素附完整 outerWxml。支持 selector[index=N]（0 基）只取第 N 个。⚠️ page.$$ 默认不穿透自定义组件（是否穿透取决于组件 styleIsolation/addGlobalClass，可用 page_getElements 看实际命中数判断）；组件内部元素用 element_getInnerElements，或 element_* 工具的 selector(组件)+innerSelector(内部)。结果超过 maxBytes（默认 50000B）返回截断包装。

轮询等待选择器对应的元素出现（最长 timeout 毫秒，每 retryInterval 毫秒重试一次）。何时用：元素来自 setData 后异步渲染 / SSE 流式 / navigateTo 未稳定——先 wait 到再用 page_getElement 取内容（本工具只确认出现，返回 {selector,index?,found:true,waitTime}，不返回元素摘要）。元素若必然已存在则直接用 page_getElement（一次性、不存在即抛错）。等任意非元素条件（page.data 字段变化 / SSE done / aiStatus='completed'）用 mp_pollUntil（通用 predicate 轮询）。支持 selector[index=N]（0 基）。timeout 默认 5000ms，SSE/异步场景建议调大到 10000+；retryInterval 默认 200ms。超时抛错并带具体排查建议（模板插值 class / shadow 不穿透 / 连接级故障 / timeout 太短）。

轮询等待选择器对应的元素从页面消失（最长 timeout 毫秒，每 retryInterval 毫秒重试）。何时用：验证 toast / loading / 弹窗 / 骨架屏已消失。成功返回 {selector,gone:true,waitTime}。带 selector[index=N] 时，该索引越界也算「已消失」。timeout 默认 5000ms，retryInterval 默认 200ms。等任意非元素条件（page.data 变化等）改用 mp_pollUntil。超时抛错;若轮询期间持续底层报错会提示可能是连接级故障，建议 mp_healthCheck / mp_recoverConnection。

轮询等待当前页面路径变为指定值,用于验证跳转真正完成（尤其是由 tap / callMethod 间接触发的跳转）。path 传页面路由,与 page.path 同形：无前导 /、不含 query（如 pages/detail/detail）。成功返回 {path,matched:true,waitTime,query}；超时抛错并附当前实际 path 便于排查。注意：mp_navigate 返回的 activePage 已是可信的最新路由,导航后通常无需再 waitRoute;本工具主要用于间接跳转。timeout 默认 5000ms,retryInterval 默认 200ms。

等待指定的毫秒数（dumb sleep）。⚠️ 仅用于「渲染 tick 留白」等无明确信号的极短等待；等任意条件（page.data 变化 / SSE done / 异步状态切换）请改用 mp_pollUntil，否则容易出现时间太短抓空 / 时间太长拖慢测试。

一次性断言当前页面路径是否等于预期值（不轮询、不抛错——失败返回 pass:false）。返回 {pass,expected,actual,snapshot:{path,query}}，读 pass 判断结果。path 须与 page.path 同形：无前导 /、不含 query。若路由可能尚未稳定,先用 page_waitRoute 等到再断言。

一次性断言选择器能否在页面定位到元素（基于 page.$$ 命中数 > 0,或带 [index=N] 时该索引在范围内）。⚠️ 只判「存在/可定位」,不检查视觉可见性（不看 display/opacity/视口）。不轮询、不抛错——结果在返回的 {pass,expected:true,actual,snapshot:{selector,count,index}} 的 pass 里。⚠️ page.$$ 默认不穿透自定义组件（是否穿透取决于组件 styleIsolation/addGlobalClass，可用 page_getElements 看实际命中数判断）,组件内部元素会误判 pass:false,此类用 element_getInnerElements 校验。支持 selector[index=N]（0 基）。

一次性断言元素文本（element.text(),含子节点渲染文本,非 input 的 value）是否匹配预期。mode='equals'(默认,整串精确相等) 或 'includes'(子串包含)。返回 {pass,expected,actual,snapshot:{selector,mode}}——读 pass,失败时看 actual 排查。结果超过 maxBytes（默认 50000B）会截断。⚠️ 与 page_expectVisible/Count 不同:元素不存在时本工具抛错(而非返回 pass:false)。支持 selector[index=N]（0 基）。校验 input/textarea 的输入值请改走 element 取 value,不要用本工具。

一次性断言匹配选择器的元素数量是否「精确等于」expected（基于 page.$$,不是 >=）。支持 selector[index=N]，此时命中该索引计 1、越界计 0。不抛错——结果在返回的 {pass,expected,actual,snapshot:{selector,index}} 的 pass 里,失败看 actual。⚠️ page.$$ 默认不穿透自定义组件（是否穿透取决于组件 styleIsolation/addGlobalClass，可用 page_getElements 看实际命中数判断）,组件内部的元素不计入,会偏少。

一次性断言当前页面某个 data 路径的值是否与 expected 深度相等。expected 为必填——省略会抛错（早期省略会让缺失路径与 undefined 误判为相等而静默判过,故强制传)。返回 {pass,expected,actual,pathResolved,snapshot:{path}}:读 pass;pathResolved(=actual 是否 !==undefined) 用来区分「路径不存在」与「值确实是 undefined」。对象键插入顺序不影响比较结果。结果超过 maxBytes（默认 50000B）会截断。path 为单条点/方括号路径(如 user.profile.name、list[0].id),不支持 page_getData 的 [*] 通配投影。

返回当前页面的轻量结构快照,聚合 route、query、指定 data 路径、关键选择器的元素摘要。最适合「不确定页面上有什么」时探查 DOM/状态（page_waitElement 超时排查也会指向它）。返回 {route,query,selectors,elementCount,elementsLimited,processedSelectorCount,elementSummaryLimit,elements:[{selector,index,tagName,text,value,size,offset}],data?,hint?}。⚠️ 不传 selectors/dataPaths/withData 时只返回 route——这不代表页面为空,会附 hint 提示补参。withData=true 会把整棵 data 树塞进 data['$']（token 炸弹,大对象改用 dataPaths 按字段投影）。limit 默认 10,限制每个 selector 返回的元素数；所有 selector 合计最多汇总 100 个元素摘要，达到上限时 elementsLimited=true。整个快照超过 maxBytes（默认 50000B）返回 truncated 包装。单个已知字段用 page_getData,单个元素用 page_getElement。对自定义组件同样默认不穿透（取决于 styleIsolation/addGlobalClass）。

获取当前页面的数据对象。三种模式：1) 无参 → 返回整树（小心 token 限制）；2) 传 path → 返回单个子路径；3) 传 paths[] → 按多路径投影（推荐用于大对象，支持 conversationHistory[*].aiStatus 这种 wildcard 语法、conversationHistory.length、conversationHistory[-1].aiStatus 负索引）。默认 maxBytes=50000 字节硬截断，超出返回 truncated=true 标识。paths 与 path 互斥时 paths 优先。

用 page.setData 直接更新当前页面 data（传 data 对象,最多 100 个键;键为顶层字段或微信路径语法如 list[0].done,作为部分合并写入）。返回已更新的键名列表确认,不回显值。⚠️ 直接改状态、绕过页面逻辑/事件处理——若想模拟真实交互请改用 page_callMethod 调页面方法或用 element_tap 等触发;本工具仅用于强制构造测试状态。

调用当前页面实例上暴露的方法(等价 page.callMethod(method, ...args),会 await 结果)。args[] 按位置展开为实参(非命名参数;传一个对象就是第一个位置参数)。返回 {method,arguments,result},result 为方法返回值。何时用:触发页面真实逻辑(优于直接 page_setData 改状态);调组件实例方法用 element_callMethod。方法不存在或内部抛错会以 UserError 返回失败信息。

模拟点击 WXML 元素(element.tap())。selector 用 CSS 选择器定位;要点击自定义组件内部的元素时,用 selector 定位组件(如 #my-comp 或标签名)、innerSelector 定位组件内部元素 —— 这是 page_* 无法穿透自定义组件时的正确做法。selector 支持 [index=N] 取第 N 个(0 基,仅作用于 selector,innerSelector 内不支持下标)。waitMs:点击后额外等待的毫秒数,用于等待导航/重渲染稳定再做下一步。返回 JSON 含 routeBefore,以及【仅当传了 waitMs>0 时】的 routeAfter/routeChanged —— 直接告诉你点击有没有触发跳转,省去再调一次 mp_currentPage。不传 waitMs 时不额外探测路由(routeAfter/routeChanged 为 null,语义=未探测):此时跳转通常尚未完成、读了也不准还白费一次往返,要判断跳转请传 waitMs 等导航稳定。routeAfter 读取失败时同样降级为 null,不影响点击本身已成功。

对元素派发底层触摸事件(touchstart/touchmove/touchend)。多数场景不需要它:简单点击用 element_tap,滑动/拖拽用 element_swipe;只有需要自定义多点/长按/分段手势时才用本工具。phase:'start'/'move'/'end' 是单个事件,需自己跨多次调用拼成完整手势;'sequence' 在一次调用内完成 touchstart→moves→touchend(推荐)。x/y 可选,相对元素左上角的像素坐标,默认取元素中心。moves[] 仅在 'sequence' 下使用,是中间移动点序列(每点可带 delayMs)。holdMs:touchstart 后按住的毫秒数(长按)。identifier:触摸点 id(多指时区分,默认 1)。waitMs:整个手势后额外等待毫秒。innerSelector:定位自定义组件内部元素(selector 定位组件)。selector 支持 [index=N](仅作用于 selector)。

对元素执行真实滑动手势(自动 touchstart→多段 touchmove→touchend),适合列表/轮播/可拖拽区域等需要 touch 序列的场景。比 element_touch 简单,优先用本工具做滑动。direction:手指移动方向 up/down/left/right。distance:滑动距离 px,默认取元素宽或高的 60%。durationMs:手势总时长,默认 300。startX/startY:起点相对元素左上角的像素坐标,默认元素中心。waitMs:手势后额外等待毫秒。innerSelector:定位自定义组件内部元素(selector 定位组件)。selector 支持 [index=N](仅作用于 selector)。

向输入类元素(input/textarea 等)填值(element.input())。value 接受字符串或数字。要填自定义组件内部的输入框时,用 selector 定位组件、innerSelector 定位内部输入元素。selector 支持 [index=N] 取第 N 个(0 基,仅作用于 selector)。注意:非输入类元素调用会失败。

调用自定义组件实例的方法(element.callMethod()),返回该方法的返回值(序列化后放在 result)。仅对自定义组件实例有效,普通 WXML 元素会失败;调用页面级方法请用 page_callMethod。读/写组件实例数据用 element_getData / element_setData。method:方法名;args:按顺序展开传入方法的参数数组。要定位嵌套在外层组件内的组件,用 selector + innerSelector。selector 支持 [index=N](仅作用于 selector)。

读取自定义组件实例的渲染数据(element.data())。仅对自定义组件实例有效;读页面 data 用 page_getData。不传 path 返回整棵组件 data(可能很大、易超 token 上限,建议尽量传 path)。path 取精确子值,如 'list.0.id'(单条路径,不支持 page_getData 的 paths[] 多路径/[*] 通配)。结果超过 maxBytes(默认 50000B,最大 1000000B)会截断。要定位嵌套组件用 selector + innerSelector。selector 支持 [index=N](仅作用于 selector)。

写自定义组件实例的渲染数据(element.setData())。仅对自定义组件实例有效;写页面 data 用 page_setData,读用 element_getData。data 为最多 100 个键的 键→值 对象,合并进组件 data(键可用小程序 setData 的路径写法如 'list[0].done')。要定位嵌套组件用 selector + innerSelector。selector 支持 [index=N](仅作用于 selector)。

在一个已定位元素的范围内查询单个子元素(element.$(targetSelector)),返回该子元素摘要(tagName/text/value/size/offset)。用法:selector(+可选 innerSelector)先定位作用域元素,targetSelector 是在该作用域内执行的查询 —— 适合在某容器/自定义组件内部缩小查询范围;若从页面根查询请用 page_getElement。withWxml=true 时额外返回该子元素的完整 outerWxml(可能很大)。结果超过 maxBytes(默认 50000B)返回 {truncated,bytes,maxBytes,note,data} 包装,关掉 withWxml 或调大 maxBytes。selector 支持 [index=N](仅作用于 selector,innerSelector/targetSelector 内不支持下标)。

在一个已定位元素的范围内查询子元素数组(element.$$(targetSelector)),返回 {count,totalCount,limited,elements[]},每个元素含摘要(tagName/text/value/size/offset)及其数组 index。limit 默认/最大 100，避免一次汇总全部子元素卡住连接；totalCount 是总命中数，count 是实际返回数。用法:selector(+可选 innerSelector)定位作用域元素,targetSelector 是在该作用域内执行的查询。withWxml=true 额外返回每个元素的完整 outerWxml。结果超过 maxBytes(默认 50000B)返回截断包装。selector 支持 [index=N](仅作用于 selector,innerSelector/targetSelector 内不支持下标)。

获取元素 WXML。默认 element.wxml() 返回内部 WXML;outer=true 返回含元素自身的 outerWxml。要读自定义组件内部的 WXML,用 selector 定位组件、innerSelector 定位内部元素。结果超过 maxBytes(默认 50000B)返回 {truncated,bytes,maxBytes,note,data} 包装(WXML 最容易撑爆);截断时改用更具体的 selector 或调大 maxBytes。selector 支持 [index=N](仅作用于 selector)。

读取元素的计算样式值(element.style(name))。names 为样式名数组,用 camelCase(如 ['color','fontSize','backgroundColor']);单个读不到的名返回 null,全部读取失败则报错。结果超过 maxBytes（默认 50000B）会截断。要读自定义组件内部元素的样式,用 selector 定位组件、innerSelector 定位内部元素。selector 支持 [index=N](仅作用于 selector)。

将 scroll-view 组件滚动到指定绝对偏移(element.scrollTo(x,y))。仅对 scroll-view 组件有效,其它元素会失败;非 scroll-view 的滚动用手势 element_swipe。x/y 为目标 scrollLeft/scrollTop 像素值(绝对位置,非增量)。要定位自定义组件内部的 scroll-view,用 selector 定位组件、innerSelector 定位内部元素。selector 支持 [index=N](仅作用于 selector)。

读取元素的 WXML 特性值(element.attribute(name)),如 ['class','id','data-index']。读 CSS 样式请用 element_getStyles。单个读不到的特性返回 null,全部读取失败则报错。结果超过 maxBytes（默认 50000B）会截断。要读自定义组件内部元素的特性,用 selector 定位组件、innerSelector 定位内部元素。selector 支持 [index=N](仅作用于 selector)。⚠️ 对象型 data-*(如 data-item 绑定了对象)经 WXML attribute 只能拿到字符串 '[object Object]'——需要结构化值请改用 element_getBoundingClientRect 返回的 dataset。

获取元素相对视口的边界矩形(left/top/width/height/right/bottom),为 CSS transform 变换后的实际渲染尺寸与位置。返回还包含 dataset(元素完整 data-* 绑定对象,含对象型值)与 id——这是读取卡片/组件绑定数据(如 plateCode/path/cardStyle)的便捷途径,优于 element_getAttributes(后者对对象型 data-* 只能拿到 '[object Object]')。支持跨组件查询:selector 设为组件选择器、innerSelector 设为内部元素选择器(内部用 >>> 穿透,比 selectComponent 更可靠)。仅支持 ID 选择器、类选择器。selector 支持 [index=N],但底层 SelectorQuery 无法可靠表达“第 N 个父元素里的 innerSelector”,因此 [index=N] 不能与 innerSelector 同时使用。选择器查询未返回矩形时抛错；微信 SelectorQuery 无法可靠区分元素不存在与 display:none。