weixin-devtools-mcp 0.0.1 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (139) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +101 -114
  3. package/build/MiniProgramContext.d.ts +307 -0
  4. package/build/MiniProgramContext.d.ts.map +1 -0
  5. package/build/MiniProgramContext.js +650 -0
  6. package/build/MiniProgramContext.js.map +1 -0
  7. package/build/collectors/Collector.d.ts +127 -0
  8. package/build/collectors/Collector.d.ts.map +1 -0
  9. package/build/collectors/Collector.js +252 -0
  10. package/build/collectors/Collector.js.map +1 -0
  11. package/build/collectors/ConsoleCollector.d.ts +104 -0
  12. package/build/collectors/ConsoleCollector.d.ts.map +1 -0
  13. package/build/collectors/ConsoleCollector.js +157 -0
  14. package/build/collectors/ConsoleCollector.js.map +1 -0
  15. package/build/collectors/NetworkCollector.d.ts +167 -0
  16. package/build/collectors/NetworkCollector.d.ts.map +1 -0
  17. package/build/collectors/NetworkCollector.js +265 -0
  18. package/build/collectors/NetworkCollector.js.map +1 -0
  19. package/build/collectors/index.d.ts +13 -0
  20. package/build/collectors/index.d.ts.map +1 -0
  21. package/build/collectors/index.js +17 -0
  22. package/build/collectors/index.js.map +1 -0
  23. package/build/config/tool-profile.d.ts +30 -0
  24. package/build/config/tool-profile.d.ts.map +1 -0
  25. package/build/config/tool-profile.js +138 -0
  26. package/build/config/tool-profile.js.map +1 -0
  27. package/build/connection/adapters.d.ts +3 -0
  28. package/build/connection/adapters.d.ts.map +1 -0
  29. package/build/connection/adapters.js +134 -0
  30. package/build/connection/adapters.js.map +1 -0
  31. package/build/connection/errors.d.ts +34 -0
  32. package/build/connection/errors.d.ts.map +1 -0
  33. package/build/connection/errors.js +101 -0
  34. package/build/connection/errors.js.map +1 -0
  35. package/build/connection/health-probe.d.ts +4 -0
  36. package/build/connection/health-probe.d.ts.map +1 -0
  37. package/build/connection/health-probe.js +60 -0
  38. package/build/connection/health-probe.js.map +1 -0
  39. package/build/connection/index.d.ts +6 -0
  40. package/build/connection/index.d.ts.map +1 -0
  41. package/build/connection/index.js +6 -0
  42. package/build/connection/index.js.map +1 -0
  43. package/build/connection/manager.d.ts +19 -0
  44. package/build/connection/manager.d.ts.map +1 -0
  45. package/build/connection/manager.js +198 -0
  46. package/build/connection/manager.js.map +1 -0
  47. package/build/connection/resolver.d.ts +3 -0
  48. package/build/connection/resolver.d.ts.map +1 -0
  49. package/build/connection/resolver.js +96 -0
  50. package/build/connection/resolver.js.map +1 -0
  51. package/build/connection/types.d.ts +95 -0
  52. package/build/connection/types.d.ts.map +1 -0
  53. package/build/connection/types.js +16 -0
  54. package/build/connection/types.js.map +1 -0
  55. package/build/formatters/consoleFormatter.d.ts +50 -0
  56. package/build/formatters/consoleFormatter.d.ts.map +1 -0
  57. package/build/formatters/consoleFormatter.js +116 -0
  58. package/build/formatters/consoleFormatter.js.map +1 -0
  59. package/build/formatters/snapshotFormatter.d.ts +41 -0
  60. package/build/formatters/snapshotFormatter.d.ts.map +1 -0
  61. package/build/formatters/snapshotFormatter.js +156 -0
  62. package/build/formatters/snapshotFormatter.js.map +1 -0
  63. package/build/index.d.ts +11 -0
  64. package/build/index.d.ts.map +1 -0
  65. package/build/index.js +45 -9
  66. package/build/index.js.map +1 -0
  67. package/build/server.d.ts +7 -0
  68. package/build/server.d.ts.map +1 -0
  69. package/build/server.js +70 -30
  70. package/build/server.js.map +1 -0
  71. package/build/tools/ToolDefinition.d.ts +215 -0
  72. package/build/tools/ToolDefinition.d.ts.map +1 -0
  73. package/build/tools/ToolDefinition.js +9 -7
  74. package/build/tools/ToolDefinition.js.map +1 -0
  75. package/build/tools/assert.d.ts +17 -0
  76. package/build/tools/assert.d.ts.map +1 -0
  77. package/build/tools/assert.js +8 -88
  78. package/build/tools/assert.js.map +1 -0
  79. package/build/tools/connection.d.ts +13 -0
  80. package/build/tools/connection.d.ts.map +1 -0
  81. package/build/tools/connection.js +332 -615
  82. package/build/tools/connection.js.map +1 -0
  83. package/build/tools/console.d.ts +20 -0
  84. package/build/tools/console.d.ts.map +1 -0
  85. package/build/tools/console.js +162 -152
  86. package/build/tools/console.js.map +1 -0
  87. package/build/tools/diagnose.d.ts +22 -0
  88. package/build/tools/diagnose.d.ts.map +1 -0
  89. package/build/tools/diagnose.js +400 -13
  90. package/build/tools/diagnose.js.map +1 -0
  91. package/build/tools/index.d.ts +6 -0
  92. package/build/tools/index.d.ts.map +1 -0
  93. package/build/tools/index.js +3 -77
  94. package/build/tools/index.js.map +1 -0
  95. package/build/tools/input.d.ts +21 -0
  96. package/build/tools/input.d.ts.map +1 -0
  97. package/build/tools/input.js +73 -139
  98. package/build/tools/input.js.map +1 -0
  99. package/build/tools/navigate.d.ts +21 -0
  100. package/build/tools/navigate.d.ts.map +1 -0
  101. package/build/tools/navigate.js +63 -126
  102. package/build/tools/navigate.js.map +1 -0
  103. package/build/tools/network.d.ts +17 -0
  104. package/build/tools/network.d.ts.map +1 -0
  105. package/build/tools/network.js +75 -887
  106. package/build/tools/network.js.map +1 -0
  107. package/build/tools/page.d.ts +13 -0
  108. package/build/tools/page.d.ts.map +1 -0
  109. package/build/tools/page.js +4 -1
  110. package/build/tools/page.js.map +1 -0
  111. package/build/tools/screenshot.d.ts +9 -0
  112. package/build/tools/screenshot.d.ts.map +1 -0
  113. package/build/tools/screenshot.js +3 -1
  114. package/build/tools/screenshot.js.map +1 -0
  115. package/build/tools/script.d.ts +6 -0
  116. package/build/tools/script.d.ts.map +1 -0
  117. package/build/tools/script.js +92 -0
  118. package/build/tools/script.js.map +1 -0
  119. package/build/tools/snapshot.d.ts +9 -0
  120. package/build/tools/snapshot.d.ts.map +1 -0
  121. package/build/tools/snapshot.js +78 -12
  122. package/build/tools/snapshot.js.map +1 -0
  123. package/build/tools/tools.d.ts +15 -0
  124. package/build/tools/tools.d.ts.map +1 -0
  125. package/build/tools/tools.js +62 -0
  126. package/build/tools/tools.js.map +1 -0
  127. package/build/tools.d.ts +431 -0
  128. package/build/tools.d.ts.map +1 -0
  129. package/build/tools.js +235 -117
  130. package/build/tools.js.map +1 -0
  131. package/build/types/errors.d.ts +189 -0
  132. package/build/types/errors.d.ts.map +1 -0
  133. package/build/types/errors.js +257 -0
  134. package/build/types/errors.js.map +1 -0
  135. package/build/utils/idGenerator.d.ts +21 -0
  136. package/build/utils/idGenerator.d.ts.map +1 -0
  137. package/build/utils/idGenerator.js +23 -0
  138. package/build/utils/idGenerator.js.map +1 -0
  139. package/package.json +34 -10
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Wooter Shen
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -8,12 +8,13 @@
8
8
 
9
9
  ## ✨ 核心特性
10
10
 
11
- - 🚀 **31个专业工具** - 覆盖连接、查询、交互、断言、导航、调试等完整测试场景
11
+ - 🚀 **27个专业工具(full profile)** - 覆盖连接、查询、交互、断言、导航、调试等完整测试场景
12
12
  - 🤖 **智能连接** - 支持 auto/launch/connect 三种模式,自动端口检测,无需手动配置
13
13
  - 🔍 **自动网络监控** - 连接时自动启动,实时拦截 wx.request/uploadFile/downloadFile
14
14
  - ✅ **完整断言体系** - 5类断言工具,验证元素存在、可见性、文本、属性、状态
15
15
  - 📸 **丰富调试能力** - 支持页面截图、Console 监听、网络请求追踪、诊断工具
16
16
  - 🏗️ **模块化架构** - 基于 chrome-devtools-mcp 架构模式,易于扩展和维护
17
+ - 🧩 **可配置工具暴露** - 默认 core profile(17个工具),支持按类别开启 Console/Network/Debug
17
18
  - 🧪 **全面测试覆盖** - 单元测试 + 集成测试,测试覆盖率 >80%
18
19
 
19
20
  ## 📦 安装
@@ -101,15 +102,54 @@ npm run build
101
102
  }
102
103
  ```
103
104
 
105
+ ### 工具 Profile 配置(v0.4+)
106
+
107
+ 服务器支持按 profile 控制暴露工具,降低默认工具数量:
108
+
109
+ - `core`(默认):17 个核心自动化工具
110
+ - `full`:27 个完整工具
111
+ - `minimal`:9 个最小工具
112
+
113
+ 也支持按类别增减:
114
+
115
+ - `--enable-categories=console,network,debug`
116
+ - `--disable-categories=console,network,debug,core`
117
+
118
+ `npx` 配置示例(启用 full):
119
+
120
+ ```json
121
+ {
122
+ "mcpServers": {
123
+ "weixin-devtools-mcp": {
124
+ "command": "npx",
125
+ "args": ["-y", "weixin-devtools-mcp", "--tools-profile=full"]
126
+ }
127
+ }
128
+ }
129
+ ```
130
+
131
+ 本地二进制示例(在 core 基础上启用 network + debug):
132
+
133
+ ```json
134
+ {
135
+ "mcpServers": {
136
+ "weixin-devtools-mcp": {
137
+ "command": "/path/to/weixin-devtools-mcp/build/server.js",
138
+ "args": ["--enable-categories=network,debug"]
139
+ }
140
+ }
141
+ }
142
+ ```
143
+
104
144
  ## 🚀 快速开始
105
145
 
106
146
  ### 第一个自动化测试
107
147
 
108
148
  ```typescript
109
- // 1. 智能连接到微信开发者工具(自动检测端口)
110
- connect_devtools_enhanced({
149
+ // 1. 连接微信开发者工具(auto 策略)
150
+ connect_devtools({
111
151
  projectPath: "/path/to/your/miniprogram",
112
- mode: "auto",
152
+ strategy: "auto",
113
153
  verbose: true
114
154
  })
115
155
 
@@ -125,111 +165,25 @@ waitFor({ selector: ".welcome-message", timeout: 5000 })
125
165
  // 5. 验证登录成功
126
166
  assert_text({ uid: ".welcome-message", text: "欢迎回来" })
127
167
 
128
- // 6. 获取页面截图
168
+ // 6. 获取页面截图(需在服务启动参数中启用 --enable-categories=debug)
129
169
  screenshot({ path: "/tmp/login-success.png" })
130
170
  ```
131
171
 
132
172
  ## 🛠️ 功能概览
133
173
 
134
- 项目提供 **31个工具**,分为 8 大类别:
135
-
136
- | 类别 | 工具数 | 主要功能 |
137
- |------|--------|----------|
138
- | **连接管理** | 3个 | 智能连接、传统连接、获取当前页面 |
139
- | **页面查询** | 3个 | CSS选择器查找、条件等待、页面快照 |
140
- | **交互操作** | 7个 | 点击、输入、获取值、表单控件、选择器、开关、滑块 |
141
- | **断言验证** | 5个 | 存在性、可见性、文本、属性、状态断言 |
142
- | **页面导航** | 6个 | 跳转、返回、Tab切换、重启、重定向、页面信息 |
143
- | **调试工具** | 5个 | 截图、Console监听、日志获取、日志清空 |
144
- | **网络监控** | 5个 | 请求拦截、监听控制、请求获取、清空记录、拦截器诊断 |
145
- | **诊断工具** | 3个 | 连接诊断、环境检查、元素调试 |
146
-
147
- ### 工具详细列表
148
-
149
- <details>
150
- <summary><b>连接管理(3个工具)</b></summary>
151
-
152
- - `connect_devtools` - 传统连接方式(兼容性)
153
- - `connect_devtools_enhanced` - 智能连接,支持三种模式,自动端口检测(推荐)
154
- - `get_current_page` - 获取当前活动页面信息
155
-
156
- </details>
174
+ 当前工具暴露采用 profile 机制:
157
175
 
158
- <details>
159
- <summary><b>页面查询和快照(3个工具)</b></summary>
160
-
161
- - `$` - 通过CSS选择器查找元素,返回详细信息
162
- - `waitFor` - 等待条件满足(时间/元素出现/消失/文本匹配)
163
- - `get_page_snapshot` - 获取完整页面快照和所有元素UID
164
-
165
- </details>
166
-
167
- <details>
168
- <summary><b>交互操作(7个工具)</b></summary>
169
-
170
- - `click` - 点击元素(支持单击/双击)
171
- - `input_text` - 向input/textarea输入文本
172
- - `get_value` - 获取元素的值或文本内容
173
- - `set_form_control` - 设置表单控件的值
174
- - `select_picker` - 选择picker控件选项
175
- - `toggle_switch` - 切换switch开关状态
176
- - `set_slider` - 设置slider滑块值
177
-
178
- </details>
179
-
180
- <details>
181
- <summary><b>断言验证(5个工具)</b></summary>
182
-
183
- - `assert_exists` - 断言元素存在或不存在
184
- - `assert_visible` - 断言元素可见或不可见
185
- - `assert_text` - 断言元素文本内容(精确/包含/正则)
186
- - `assert_attribute` - 断言元素属性值
187
- - `assert_state` - 断言元素状态(选中/启用/聚焦/可见)
188
-
189
- </details>
190
-
191
- <details>
192
- <summary><b>页面导航(6个工具)</b></summary>
193
-
194
- - `navigate_to` - 跳转到指定页面
195
- - `navigate_back` - 返回上一页
196
- - `switch_tab` - 切换到指定Tab页
197
- - `relaunch` - 重启小程序并跳转到指定页面
198
- - `redirect_to` - 关闭当前页并跳转
199
- - `get_page_info` - 获取当前页面详细信息
200
-
201
- </details>
202
-
203
- <details>
204
- <summary><b>调试工具(5个工具)</b></summary>
205
-
206
- - `screenshot` - 页面截图(返回base64或保存文件)
207
- - `start_console_monitoring` - 开始监听console和exception
208
- - `stop_console_monitoring` - 停止console监听
209
- - `get_console` - 获取收集的console消息
210
- - `clear_console` - 清空console缓存
211
-
212
- </details>
213
-
214
- <details>
215
- <summary><b>网络监控(5个工具)</b></summary>
216
-
217
- - `start_network_monitoring` - 开始监听网络请求
218
- - `stop_network_monitoring` - 停止网络监听
219
- - `get_network_requests` - 获取拦截的网络请求(支持过滤)
220
- - `clear_network_requests` - 清空网络请求记录
221
- - `diagnose_interceptor` - 诊断网络拦截器状态
222
-
223
- </details>
224
-
225
- <details>
226
- <summary><b>诊断工具(3个工具)</b></summary>
227
-
228
- - `diagnose_connection` - 诊断连接问题,检查配置和环境
229
- - `check_environment` - 检查自动化环境配置
230
- - `debug_page_elements` - 调试页面元素获取问题
231
-
232
- </details>
176
+ - `core`(默认,20个):
177
+ - 连接/页面:`connect_devtools`、`reconnect_devtools`、`disconnect_devtools`、`get_connection_status`、`get_current_page`、`get_page_snapshot`、`$`、`waitFor`
178
+ - 交互:`click`、`input_text`、`get_value`、`set_form_control`
179
+ - 断言:`assert_text`、`assert_attribute`、`assert_state`
180
+ - 导航:`navigate_to`、`navigate_back`、`switch_tab`、`relaunch`
181
+ - 脚本:`evaluate_script`
182
+ - 可选类别(默认关闭):
183
+ - `console`:`list_console_messages`、`get_console_message`
184
+ - `network`:`get_network_requests`、`stop_network_monitoring`、`clear_network_requests`
185
+ - `debug`:`screenshot`、`diagnose_connection`、`check_environment`、`debug_page_elements`、`debug_connection_flow`
186
+ - `full` profile:暴露全部 30 个工具。
233
187
 
234
188
  ## 💡 使用示例
235
189
 
@@ -237,9 +191,9 @@ screenshot({ path: "/tmp/login-success.png" })
237
191
 
238
192
  ```typescript
239
193
  // 连接到开发者工具
240
- connect_devtools_enhanced({
194
+ connect_devtools({
241
195
  projectPath: "/path/to/miniprogram",
242
- mode: "auto"
196
+ strategy: "auto"
243
197
  })
244
198
 
245
199
  // 输入用户名
@@ -260,7 +214,7 @@ waitFor({ selector: ".welcome", timeout: 5000 })
260
214
  // 验证欢迎消息
261
215
  assert_text({ uid: ".welcome", textContains: "欢迎" })
262
216
 
263
- // 检查网络请求
217
+ // 检查网络请求(需在服务启动参数中启用 --enable-categories=network)
264
218
  get_network_requests({ urlPattern: "/api/login", successOnly: true })
265
219
  ```
266
220
 
@@ -272,13 +226,13 @@ input_text({ uid: "input#name", text: "张三" })
272
226
  input_text({ uid: "input#email", text: "zhangsan@example.com" })
273
227
 
274
228
  // 选择下拉框
275
- select_picker({ uid: "picker#city", value: "北京" })
229
+ set_form_control({ uid: "picker#city", value: "北京" })
276
230
 
277
231
  // 切换开关
278
- toggle_switch({ uid: "switch#agree", checked: true })
232
+ set_form_control({ uid: "switch#agree", value: true })
279
233
 
280
234
  // 设置滑块
281
- set_slider({ uid: "slider#age", value: 25 })
235
+ set_form_control({ uid: "slider#age", value: 25 })
282
236
 
283
237
  // 提交表单
284
238
  click({ uid: "button.submit" })
@@ -307,17 +261,35 @@ screenshot({ path: "/tmp/form-submit-success.png" })
307
261
 
308
262
  ### 构建和测试
309
263
 
264
+ 项目采用分层测试架构,分为协议测试、工具测试和集成测试:
265
+
310
266
  ```bash
311
267
  # 开发模式(监听文件变化)
312
268
  npm run watch
313
269
 
314
- # 运行单元测试
270
+ # 运行单元测试(224个测试:协议 + 工具 + 工具类)
315
271
  npm test
316
272
 
317
- # 运行集成测试(需要微信开发者工具)
273
+ # 分类运行单元测试
274
+ npm run test:protocol # 协议层测试(19个)
275
+ npm run test:tools # 工具逻辑测试(196个)
276
+
277
+ # 运行集成测试(需要微信开发者工具,46个测试)
318
278
  npm run test:integration
319
279
 
320
- # 运行所有测试
280
+ # 推荐:复用现有 DevTools 会话,避免反复重启项目(默认)
281
+ INTEGRATION_CLEANUP_MODE=reuse npm run test:integration
282
+
283
+ # 如需强制隔离环境(CI 或排查端口脏状态)
284
+ INTEGRATION_CLEANUP_MODE=force npm run test:integration
285
+
286
+ # 禁用跨 suite 会话复用(仅调试时建议)
287
+ INTEGRATION_REUSE_SESSION=false npm run test:integration
288
+
289
+ # 如需每个 suite 结束后强制断开(默认不强制)
290
+ INTEGRATION_FORCE_DISCONNECT_AFTER_EACH_SUITE=true npm run test:integration
291
+
292
+ # 运行所有测试(单元 + 集成)
321
293
  npm run test:all
322
294
 
323
295
  # 生成测试覆盖率报告
@@ -332,12 +304,27 @@ npm run inspector
332
304
  1. 在 `src/tools/` 下创建或修改工具模块
333
305
  2. 使用 `ToolDefinition` 框架定义工具
334
306
  3. 在 `src/tools/index.ts` 中导出工具
335
- 4. 编写单元测试(`tests/*.test.ts`)
336
- 5. 编写集成测试(`tests/*.integration.test.ts`)
307
+ 4. 编写单元测试(`tests/tools/*.test.ts` 或 `tests/protocol/*.test.ts`)
308
+ 5. 编写集成测试(`tests/integration/*.integration.test.ts`)
337
309
  6. 更新文档
338
310
 
339
311
  详细开发指南请参考 [CLAUDE.md](CLAUDE.md)
340
312
 
313
+ ### 测试架构
314
+
315
+ 项目采用三层测试架构(参考 chrome-devtools-mcp):
316
+
317
+ - **协议层测试** (`tests/protocol/`) - 测试 MCP 服务器协议实现
318
+ - **工具逻辑测试** (`tests/tools/`) - 直接测试工具 handler,无需服务器
319
+ - **集成测试** (`tests/integration/`) - 端到端测试,需要真实环境
320
+
321
+ 集成测试支持以下运行模式:
322
+ - `INTEGRATION_CLEANUP_MODE=reuse`:复用已有 DevTools 实例(默认)
323
+ - `INTEGRATION_CLEANUP_MODE=smart`:优雅关闭后重连
324
+ - `INTEGRATION_CLEANUP_MODE=force`:强制清理全部实例
325
+ - `INTEGRATION_REUSE_SESSION=true/false`:控制跨 suite 连接复用
326
+ - `INTEGRATION_FORCE_DISCONNECT_AFTER_EACH_SUITE=true/false`:控制每个 suite 结束后是否强制断连(默认 `false`)
327
+
341
328
  ## 📋 系统要求
342
329
 
343
330
  - **Node.js** >= 16.0.0
@@ -0,0 +1,307 @@
1
+ /**
2
+ * MiniProgramContext - 小程序自动化上下文管理类
3
+ *
4
+ * 参考 chrome-devtools-mcp 的 McpContext 设计模式
5
+ * 统一管理所有状态,提供类型安全的访问方法
6
+ *
7
+ * 使用 Collector 模式管理 Console 和 Network 数据
8
+ */
9
+ import type { MiniProgram, Page, Element } from 'miniprogram-automator';
10
+ import { ConsoleCollector, NetworkCollector } from './collectors/index.js';
11
+ import type { ConsoleEntry, NetworkRequest } from './collectors/index.js';
12
+ import { type ConnectionConnectResult, type ConnectionRequest, type ConnectionStatusSnapshot } from './connection/index.js';
13
+ import type { ToolContext, ConsoleStorage, NetworkStorage, ConsoleMessage, ExceptionMessage } from './tools/ToolDefinition.js';
14
+ import { type ElementMapInfo, type PageSnapshot } from './tools.js';
15
+ /**
16
+ * MiniProgramContext 配置选项
17
+ */
18
+ export interface MiniProgramContextOptions {
19
+ /** 最大保留的导航会话数 */
20
+ maxNavigations?: number;
21
+ /** 是否启用详细日志 */
22
+ verbose?: boolean;
23
+ /** 快照缓存 TTL(毫秒),默认 5000ms */
24
+ snapshotCacheTtl?: number;
25
+ }
26
+ /**
27
+ * MiniProgramContext 类
28
+ *
29
+ * 统一管理小程序自动化的所有状态:
30
+ * - miniProgram 实例
31
+ * - currentPage 当前页面
32
+ * - elementMap 元素映射
33
+ * - consoleCollector Console 数据收集器
34
+ * - networkCollector 网络请求收集器
35
+ */
36
+ export declare class MiniProgramContext implements ToolContext {
37
+ #private;
38
+ /**
39
+ * 私有构造函数,使用工厂方法创建实例
40
+ */
41
+ private constructor();
42
+ /**
43
+ * 工厂方法:创建 MiniProgramContext 实例
44
+ */
45
+ static create(options?: MiniProgramContextOptions): MiniProgramContext;
46
+ /**
47
+ * 工厂方法:从已有的 MiniProgram 实例创建上下文
48
+ */
49
+ static from(miniProgram: MiniProgram, options?: MiniProgramContextOptions): Promise<MiniProgramContext>;
50
+ /**
51
+ * 获取 MiniProgram 实例
52
+ * @throws 如果未连接则抛出错误
53
+ */
54
+ getMiniProgram(): MiniProgram;
55
+ /**
56
+ * 设置 MiniProgram 实例
57
+ */
58
+ setMiniProgram(miniProgram: MiniProgram): Promise<void>;
59
+ /**
60
+ * 检查是否已连接
61
+ */
62
+ isConnected(): boolean;
63
+ /**
64
+ * 断开连接,重置状态
65
+ */
66
+ disconnect(): void;
67
+ connectDevtools(request: ConnectionRequest): Promise<ConnectionConnectResult>;
68
+ reconnectDevtools(request?: ConnectionRequest): Promise<ConnectionConnectResult>;
69
+ disconnectDevtools(): Promise<ConnectionStatusSnapshot>;
70
+ getConnectionStatus(options?: {
71
+ refreshHealth?: boolean;
72
+ }): Promise<ConnectionStatusSnapshot>;
73
+ /**
74
+ * 获取当前页面
75
+ * @throws 如果未连接或没有当前页面则抛出错误
76
+ */
77
+ getCurrentPage(): Page;
78
+ /**
79
+ * 设置当前页面
80
+ */
81
+ setCurrentPage(page: Page): void;
82
+ /**
83
+ * 刷新当前页面引用
84
+ */
85
+ refreshCurrentPage(): Promise<Page>;
86
+ /**
87
+ * 获取元素映射表(只读)
88
+ */
89
+ getElementMap(): ReadonlyMap<string, ElementMapInfo>;
90
+ /**
91
+ * 设置元素映射
92
+ */
93
+ setElementMapEntry(uid: string, info: ElementMapInfo): void;
94
+ /**
95
+ * 批量设置元素映射
96
+ */
97
+ setElementMap(map: Map<string, ElementMapInfo>): void;
98
+ /**
99
+ * 清空元素映射
100
+ */
101
+ clearElementMap(): void;
102
+ /**
103
+ * 通过 UID 获取元素
104
+ * 统一处理:连接检查、快照检查、元素查找、索引定位
105
+ */
106
+ getElementByUid(uid: string): Promise<Element>;
107
+ /**
108
+ * 获取页面快照(带缓存)
109
+ *
110
+ * 缓存策略:
111
+ * - 在 TTL 内返回缓存的快照(避免重复调用 getPageSnapshot)
112
+ * - 页面路径变化时自动刷新缓存
113
+ * - 支持强制刷新
114
+ *
115
+ * @param options.forceRefresh 强制刷新缓存
116
+ * @param options.ttl 覆盖默认 TTL(毫秒)
117
+ * @returns 页面快照和元素映射
118
+ */
119
+ getPageSnapshotCached(options?: {
120
+ forceRefresh?: boolean;
121
+ ttl?: number;
122
+ }): Promise<{
123
+ snapshot: PageSnapshot;
124
+ elementMap: Map<string, ElementMapInfo>;
125
+ }>;
126
+ /**
127
+ * 使缓存失效
128
+ * 在导航后或 DOM 发生变化时调用
129
+ */
130
+ invalidateSnapshotCache(): void;
131
+ /**
132
+ * 获取缓存状态信息(用于调试)
133
+ */
134
+ getSnapshotCacheStatus(): {
135
+ isCached: boolean;
136
+ path: string;
137
+ age: number;
138
+ elementCount: number;
139
+ ttl: number;
140
+ };
141
+ /**
142
+ * 获取 Console 收集器(新 API)
143
+ */
144
+ getConsoleCollector(): ConsoleCollector;
145
+ /**
146
+ * 开始 Console 监听
147
+ */
148
+ startConsoleMonitoring(): void;
149
+ /**
150
+ * 停止 Console 监听
151
+ */
152
+ stopConsoleMonitoring(): void;
153
+ /**
154
+ * 检查是否正在监听 Console
155
+ */
156
+ isConsoleMonitoring(): boolean;
157
+ /**
158
+ * 添加 Console 消息
159
+ * @returns 分配的 msgid
160
+ */
161
+ addConsoleMessage(message: Omit<ConsoleMessage, 'msgid'>): number;
162
+ /**
163
+ * 添加异常消息
164
+ * @returns 分配的 msgid
165
+ */
166
+ addExceptionMessage(exception: Omit<ExceptionMessage, 'msgid'>): number;
167
+ /**
168
+ * 通过 ID 获取消息
169
+ */
170
+ getConsoleMessageById(msgid: number): ConsoleEntry | undefined;
171
+ /**
172
+ * 获取所有消息(支持分页和过滤)
173
+ */
174
+ getConsoleMessages(options?: {
175
+ includePreserved?: boolean;
176
+ types?: string[];
177
+ pageSize?: number;
178
+ pageIdx?: number;
179
+ }): ConsoleEntry[];
180
+ /**
181
+ * 在导航时分割存储(保留历史)
182
+ */
183
+ splitConsoleAfterNavigation(): void;
184
+ /**
185
+ * 清空 Console 消息
186
+ */
187
+ clearConsoleMessages(): void;
188
+ /**
189
+ * 获取 Network 收集器(新 API)
190
+ */
191
+ getNetworkCollector(): NetworkCollector;
192
+ /**
193
+ * 开始网络监听
194
+ */
195
+ startNetworkMonitoring(): void;
196
+ /**
197
+ * 停止网络监听
198
+ */
199
+ stopNetworkMonitoring(): void;
200
+ /**
201
+ * 检查是否正在监听网络
202
+ */
203
+ isNetworkMonitoring(): boolean;
204
+ /**
205
+ * 添加网络请求
206
+ */
207
+ addNetworkRequest(request: NetworkRequest): number;
208
+ /**
209
+ * 更新网络请求
210
+ */
211
+ updateNetworkRequest(id: string, updates: Partial<Pick<NetworkRequest, 'statusCode' | 'response' | 'responseHeaders' | 'error' | 'duration' | 'completedAt' | 'success' | 'pending'>>): boolean;
212
+ /**
213
+ * 完成网络请求
214
+ */
215
+ completeNetworkRequest(id: string, response: {
216
+ statusCode?: number;
217
+ data?: unknown;
218
+ headers?: Record<string, string>;
219
+ error?: string;
220
+ }): boolean;
221
+ /**
222
+ * 获取网络请求
223
+ */
224
+ getNetworkRequests(options?: {
225
+ type?: 'request' | 'uploadFile' | 'downloadFile' | 'all';
226
+ urlPattern?: string;
227
+ successOnly?: boolean;
228
+ failedOnly?: boolean;
229
+ since?: string;
230
+ limit?: number;
231
+ }): NetworkRequest[];
232
+ /**
233
+ * 清空网络请求
234
+ */
235
+ clearNetworkRequests(): void;
236
+ /**
237
+ * 在导航时分割存储(保留历史)
238
+ */
239
+ splitNetworkAfterNavigation(): void;
240
+ /**
241
+ * ToolContext 接口:获取 miniProgram
242
+ */
243
+ get miniProgram(): MiniProgram | null;
244
+ /**
245
+ * ToolContext 接口:设置 miniProgram
246
+ */
247
+ set miniProgram(value: MiniProgram | null);
248
+ /**
249
+ * ToolContext 接口:获取 currentPage
250
+ */
251
+ get currentPage(): Page | null;
252
+ /**
253
+ * ToolContext 接口:设置 currentPage
254
+ */
255
+ set currentPage(value: Page | null);
256
+ /**
257
+ * ToolContext 接口:获取 elementMap
258
+ */
259
+ get elementMap(): Map<string, ElementMapInfo>;
260
+ /**
261
+ * ToolContext 接口:设置 elementMap
262
+ */
263
+ set elementMap(value: Map<string, ElementMapInfo>);
264
+ /**
265
+ * ToolContext 接口:获取 consoleStorage(向后兼容适配器)
266
+ * 将 Collector 数据转换为 ConsoleStorage 格式
267
+ */
268
+ get consoleStorage(): ConsoleStorage;
269
+ /**
270
+ * ToolContext 接口:设置 consoleStorage(向后兼容适配器)
271
+ * 注意:这个 setter 主要用于兼容性,新代码应直接使用 Collector
272
+ */
273
+ set consoleStorage(value: ConsoleStorage);
274
+ /**
275
+ * ToolContext 接口:获取 networkStorage(向后兼容适配器)
276
+ * 将 Collector 数据转换为 NetworkStorage 格式
277
+ */
278
+ get networkStorage(): NetworkStorage;
279
+ /**
280
+ * ToolContext 接口:设置 networkStorage(向后兼容适配器)
281
+ * 注意:这个 setter 主要用于兼容性,新代码应直接使用 Collector
282
+ */
283
+ set networkStorage(value: NetworkStorage);
284
+ /**
285
+ * ToolContext 接口:获取 connectionStatus
286
+ */
287
+ get connectionStatus(): ConnectionStatusSnapshot;
288
+ /**
289
+ * ToolContext 接口:设置 connectionStatus(兼容层)
290
+ */
291
+ set connectionStatus(value: ConnectionStatusSnapshot);
292
+ /**
293
+ * 获取上下文状态摘要(用于调试)
294
+ */
295
+ getStatusSummary(): {
296
+ connected: boolean;
297
+ hasCurrentPage: boolean;
298
+ elementCount: number;
299
+ consoleMonitoring: boolean;
300
+ consoleMessageCount: number;
301
+ networkMonitoring: boolean;
302
+ networkRequestCount: number;
303
+ snapshotCached: boolean;
304
+ snapshotCacheAge: number;
305
+ };
306
+ }
307
+ //# sourceMappingURL=MiniProgramContext.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"MiniProgramContext.d.ts","sourceRoot":"","sources":["../src/MiniProgramContext.ts"],"names":[],"mappings":"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"}