WeChat Mini-Program Agent

只读探测当前连接目标的状态（port 是否监听、devtools 是否在线、ws 是否可达、automator 是否已连），不启动 IDE、不重连、不改任何项目状态。 何时用：只想拿一份不改动现状的连接快照时（如用户问“为什么连不上”但不想动环境），或在 mp_ensureConnection / mp_recoverConnection 已失败后，用本工具读细节辅助判断。 何时不用：想“把连接弄通”时不要先调本工具——直接调 mp_ensureConnection，它会自愈/自动拉起 IDE，并在返回里自带一份 diagnosis。 ⚠️ 本工具是保守设计：它如实报告 “port not listening / automation not enabled” 等，但**不会修复**。这种红色结果**不是死路、也不需要找用户确认**——下一步就是调 mp_ensureConnectio

{
  "tool": "mp_diagnoseConnection",
  "arguments": {
    "connection": {}
  }
}

确保小程序自动化会话就绪——这是连接链路的**默认入口**：在 mp_screenshot / page_* / element_* 之前先调它。它会**自愈**:会话未就绪时自动拉起微信开发者工具 / 重启 cli auto 并建立 automator 连接,不只是被动检查。 何时用:任何“先连上再操作”的场景,直接调本工具,不需要先 mp_diagnoseConnection(那是只读探测,可跳过)。 失败时:**先读错误信息里的 Next step 引导**,通常是 ① 带 reconnect=true 重试,或 ② 先 mp_listProjects 再带 projectSelection 重试——不要原样重试同一调用,也不要直接停下来找用户。 defaultProject 不在 recents 时,server 会用 defaultProject 重启 cli auto,第一

{
  "tool": "mp_ensureConnection",
  "arguments": {
    "connection": {},
    "reconnect": true,
    "projectSelection": "…"
  }
}

只读聚合当前自动化环境健康状态:连接(devtoolsOnline / wsReachable / automatorConnected)、当前页面路由、项目、日志监听、以及上次 mp_screenshot 结果(lastScreenshotOk / errorCode)。不修复任何东西——要恢复用 mp_recoverConnection,要建立连接用 mp_ensureConnection。 何时用:操作出问题时先调它看全局状态;尤其在 mp_screenshot / page_snapshot 反复失败后,先 healthCheck 再决定是否 mp_recoverConnection。 关键字段:summary='degraded' 表示至少一项能力降级,但不一定可通过重连修复；**只有 needsRecovery=true 才调 mp_recoverConnection**。连

{
  "tool": "mp_healthCheck",
  "arguments": {
    "connection": {},
    "includePage": true,
    "includeLogs": true
  }
}

按标准顺序修复一个**已存在但降级/失效**的连接:重建 automator 会话 → 重挂日志监听 → 恢复项目上下文,并返回恢复前后对比。 何时用:这是**升级修复步**——只有当 mp_healthCheck 显示 needsRecovery=true 时调它,而不是只看 summary='degraded' 就重连。 何时不用:首次“建立连接”不要用本工具,用 mp_ensureConnection(它才负责自动拉起 IDE)；连接全绿但截图失败且 needsRecovery=false 时也不要用,重连无法修复截图通道。与 ensure(reconnect=true) 的区别:本工具跑一套有序修复并报告 before/after,ensure 只是把会话弄就绪。 ⚠️ 副作用(launch 模式):重连会退出并重新 launch 小程序(App.exit + 关 IDE 窗口

{
  "tool": "mp_recoverConnection",
  "arguments": {
    "connection": {},
    "reconnect": true
  }
}

在小程序内导航并返回导航后的 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-ta

{
  "tool": "mp_navigate",
  "arguments": {
    "connection": {},
    "path": "…",
    "query": {}
  }
}

截取当前小程序视口截图。需已有活动会话(无会话先 mp_ensureConnection)。**不传 path 返回内联图片(image content);传 path 则存文件并返回 JSON {ok,path,route} —— 此时拿不到图像本身，route 为可空诊断字段。** 父目录不存在会自动 mkdir -p；文件模式会验证输出存在且非零字节后才返回成功。 ⚠️ 截图是**单通道串行**能力:全局一次只跑一个,不要并发拍图;超时后也不要立刻重发(底层那条超时请求仍占着单通道,再发会互相打乱)—— 等本次调用返回再说。截图前不会额外读取 currentPage，避免非必要请求先占住截图通道。仅支持开发者工具模拟器(客户端环境可能返回 EMPTY_OUTPUT)。 失败时返回 reasonCode 并附可操作建议:SCREENSHOT_TIMEOUT、SIMULATOR_HI

{
  "tool": "mp_screenshot",
  "arguments": {
    "connection": {},
    "path": "…",
    "timeoutMs": 0
  }
}

调用微信小程序 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

{
  "tool": "mp_callWx",
  "arguments": {
    "method": "…"
  }
}

向小程序 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`

{
  "tool": "mp_evaluate",
  "arguments": {
    "functionSource": "…"
  }
}

**通用 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 是按顺序展开给这两个函数的入参数组。轮询由 ser

{
  "tool": "mp_pollUntil",
  "arguments": {
    "connection": {},
    "predicate": "…",
    "predicateArgs": []
  }
}

读取当前连接目标的小程序控制台日志,支持过滤。不同项目 / 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...}:c

{
  "tool": "mp_getLogs",
  "arguments": {
    "connection": {},
    "clear": true,
    "contains": "…"
  }
}

按顺序执行一组小程序调试/回归步骤,一次调用跑完并汇总每步 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

{
  "tool": "mp_runScenario",
  "arguments": {
    "steps": []
  }
}

执行一个 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/sna

{
  "tool": "mp_generateScenarioReport",
  "arguments": {
    "steps": []
  }
}

获取当前页面信息(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_

{
  "tool": "mp_currentPage",
  "arguments": {
    "connection": {},
    "withData": true,
    "dataPaths": []
  }
}

列出微信开发者工具里的最近项目(返回 { defaultProject, projects:[{index,name,path}] }),并显示当前 defaultProject。 何时用:① mp_ensureConnection 返回“需要选择项目”提示后,先调本工具看有哪些项目,再把某项的 index / name / path 作为 projectSelection 传回 mp_ensureConnection;② 想固定后续连接用哪个项目时,把 path 传给 mp_setDefaultProject;③ 不确定有哪个项目可连时先调它确认。 注意:返回的是“可连接的项目”,不是项目内的页面路由——要找页面路径需读项目的 app.json,本工具不提供。无参数。

{
  "tool": "mp_listProjects",
  "arguments": {}
}

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

{
  "tool": "mp_setDefaultProject",
  "arguments": {
    "projectPath": "…"
  }
}

通过选择器获取单个页面元素，相当于 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）；组件内部元

{
  "tool": "page_getElement",
  "arguments": {
    "selector": "…"
  }
}

通过选择器获取页面元素数组，相当于 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/addG

{
  "tool": "page_getElements",
  "arguments": {
    "selector": "…"
  }
}

轮询等待选择器对应的元素出现（最长 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+；ret

{
  "tool": "page_waitElement",
  "arguments": {
    "selector": "…"
  }
}

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

{
  "tool": "page_waitElementGone",
  "arguments": {
    "selector": "…"
  }
}

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

{
  "tool": "page_waitRoute",
  "arguments": {
    "path": "…"
  }
}