@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 browser_launch --payload '{"name":"figma","userAgentMode":"desktop","copyCookieDomains":["figma.com"]}'
mtop-devtools browser_list

通用选项：

| 选项 | 说明 | | ----------------------- | ------------------------ | | --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_list browser_launch 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 截断会同时保留首尾内容。

browser_list 统一列出普通浏览器和托管浏览器。type 区分 regular / managed，status 区分 connected / running_disconnected / stopped；只有 connected 的浏览器可作为操作目标。

托管浏览器使用独立 Profile 和动态 CDP 端口。控制浏览器需先登录 TDBank；生成的 SSO 地址在本地内部传递，新实例可以使用 headless: true（默认）完成测试账号登录。copyCookieDomains 可把控制浏览器指定域的 Cookie 复制到新实例，Cookie 值不会出现在命令结果或日志中；userAgentMode: "desktop" 可让实例使用匹配本机 Chrome 版本的桌面 UA。完整设计见 托管浏览器与 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