@mtop-devtools/client

@mtop-devtools/client

本地客户端 SDK 与 CLI，通过 Unix Domain Socket 与 Chrome 扩展的 native host 通信，调用浏览器调试与操作能力。

提供两种用法：类型安全的具名方法（getRequests、proxyRequest 等），以及灵活的底层 invoke(action, payload)。

安装

npm install @mtop-devtools/client
# 或
pnpm add @mtop-devtools/client

SDK 使用

import * as client from '@mtop-devtools/client';

// 具名方法（类型安全）
const requests = await client.getRequests({ count: 5 });
const result = await client.proxyRequest({
  url: 'https://api.example.com',
  method: 'GET',
  withCookies: true,
});

// 底层通用方法（灵活扩展）
const data = await client.invoke('proxy_request', { url: '...' });

CLI 使用

安装后提供 mtop-devtools 命令：

# 获取最近 5 个请求
mtop-devtools get_requests --payload '{"count":5}'

# 代理一个 HTTP 请求
mtop-devtools proxy_request --payload '{"url":"https://api.example.com","method":"GET"}'

# 截图并保存
mtop-devtools get_screenshot --output ./screenshot.png

# 从文件读取大体积参数（如 mock 数据）
mtop-devtools set_mock --payload-file ./mock-data.json

# 环境自检
mtop-devtools check

# 查看某个 action 的帮助
mtop-devtools <action> --help

# 启动两个隔离的 headless Chrome，并分别登录不同 TDBank 账号
mtop-devtools browser_launch --payload '{"name":"account-a","accountId":12345}'
mtop-devtools browser_launch --payload '{"name":"account-b","query":"test_account"}'
mtop-devtools browser_launch --payload '{"name":"cookie-copy","copyCookieDomains":["example.com"]}'
mtop-devtools browsers

通用选项：

选项	说明
--payload <json>	直接传入 JSON 参数
--payload-file <path>	从文件读取 JSON 参数
--timeout <seconds>	请求超时时间
--compact	紧凑输出
--output <path>	将结果写入文件（如截图）

支持的操作

分类	Actions
API 调试	get_requests get_logs get_events get_api_schema
Mock & 规则	set_mock get_mocks add_rule
网络代理	proxy_request send_mtop_request
标签页	tab_open tab_close tab_list
页面操作	page_click page_type page_scroll page_eval page_press page_wait page_navigate page_upload page_act
页面感知	page_snapshot get_screenshot get_selected_element page_frames
环境模拟	set_device_emulation set_timezone
用户信息	get_user_info
录制	record_start record_stop record_get
TDBank	tdbank_account
托管浏览器	browser_launch browser_list_managed browser_close

page_act 将一次点击、输入、滚动等动作与动作后的异步稳定判断合并为一个调用。它不替代完整页面理解：mode: "delta" 只返回主文档中的 effects.notifications、effects.interactives 和 effects.focus 等高置信度信号，并明确携带 scope: "main-document"；mode: "navigation" 且 ready: true 时，页面已通过网络静默、骨架状态或保守的内容稳定判定，可在新页面重建快照。仅在 fullSnapshotRecommended 为 true 时根据 snapshotReasons 回退到完整快照或截图。

page_snapshot 默认返回完整 AX Tree；长列表可传 mode: "viewport"，只需要控件时传 mode: "interactive"，已知区域时传 rootSelector。页面缺少 AX 控件语义时，interactive 会自动回退到 viewport，并返回 fallbackMode: "viewport"。maxNodes / maxChars 截断会同时保留首尾内容。

托管浏览器使用独立 Profile 和动态 CDP 端口。控制浏览器需先登录 TDBank；生成的 SSO 地址在本地内部传递，新实例可以使用 headless: true（默认）完成测试账号登录。copyCookieDomains 可把控制浏览器指定域的 Cookie 复制到新实例，Cookie 值不会出现在命令结果或日志中。完整设计见 托管浏览器与 TDBank 多账号设计。

架构

@mtop-devtools/client (CLI / SDK)
  ↓ (Unix Socket)
@mtop-devtools/native-host
  ↓ (Native Messaging)
Chrome Extension / CDP

云端远程调用场景请使用 @mtop-devtools/cloud-client，其操作集与本包完全一致。

构建

pnpm build      # tsc 编译到 dist/，并赋予 cli.js 执行权限
pnpm dev        # tsc --watch
pnpm typecheck  # 仅类型检查

License

ISC