挖象浏览器打开店铺
挖象浏览器打开店铺工作流:在挖象浏览器中登录之后,打开用户指定分组指定名称的店铺。当用户需要在挖象浏览器中打开某个店铺(给出店铺名称与所属分组)时使用。
挖象浏览器启动店铺
本技能封装“在挖象浏览器中远程打开某个店铺”的完整可执行流程。按给定步骤执行,在登陆状态下打开指定分组指定名称的店铺,未登录时先执行登录流程;若挖象浏览器已在运行,先提醒用户并在征得同意后关闭,再以远程调试模式启动(使用浏览器默认用户数据目录)。
⚠️ 用户警告(User Warning)与安全声明
执行前必须先向用户展示本节并获得用户确认:未确认前不得执行启动浏览器及登录。
- 凭据使用(Credential Use):本技能会使用用户主动提供的挖象账号(手机号)与密码完成登录。凭据无任何内置默认值;仅通过 HTTPS 提交至挖象官方登录页(
https://hao.waxiang.com);不写入日志、不写入文件、不用于其他用途、不发送给任何第三方。 - 本地调试端口(Local Debug Port):本技能会以
--remote-debugging-port在本机启动挖象浏览器,调试端口仅绑定本机回环地址(127.0.0.1),仅本机进程可访问;任务结束即断开调试连接。请仅在可信设备上执行。 - 本地进程与文件(Local Processes & Files):打开店铺会在本机启动新的浏览器进程与窗口;若检测到挖象浏览器已在运行,会先提醒用户并在征得同意后关闭该进程再重新启动;文件访问仅限挖象浏览器自身与其浏览器默认用户数据目录,不做文件系统枚举(No File System Enumeration)、不扫描或读取无关目录。
- 数据不外传(No External Data Transmission):除访问挖象官方域名与本机回环地址(
127.0.0.1)外,本技能不向任何其他地址传输数据;无遥测、无数据收集、不上传本地文件。第 9 步输出的店铺调试端口仅在本机日志/返回值中使用(供同一台机器上的后续自动化),不通过网络外发。
权限与数据使用清单
| 项目 | 用途 | 范围与限制 |
|---|---|---|
| 用户凭据(手机号/密码) | 登录挖象账号 | 运行时由用户提供;仅提交挖象官方 HTTPS 登录页;不落盘、不入日志、不外传 |
| 网络访问 | 登录、打开店铺 | 仅 hao.waxiang.com(挖象官方)与 127.0.0.1(本机 CDP);无第三方地址 |
| 环境变量 | 拼装 Windows 默认安装路径 | 仅在 Windows 上将 %LocalAppData% 作为默认路径占位符(可由用户显式覆盖);macOS 从 /Applications 下定位挖象浏览器应用;不读取其他环境变量内容(No Env Variable Harvesting) |
| 本地文件 | 启动浏览器 | 仅挖象浏览器可执行文件与其浏览器默认用户数据目录;不枚举文件、不读取其他文件 |
| 本地进程 | 启动浏览器;必要时经用户同意后关闭并重启 | 用户主动发起的正常业务操作;关闭动作仅在用户明确同意后执行;调试端口仅本机可用 |
适用场景
- “打开店铺”
- “把 XXX 店铺打开/跑起来”
- “远程启动挖象店铺 <店铺名>”
前置参数
| 参数 | 必填 | 说明 |
|---|---|---|
| 挖象浏览器路径 | 可选 | Windows 默认 %LocalAppData%\WaXiangBrowser\waxiang.exe;macOS 使用 /Applications 目录下的挖象浏览器应用(可由用户显式覆盖) |
| 挖象用户名 | 可选 | 手机号,登录用(无内置默认值,运行时由调用方提供) |
| 挖象密码 | 可选 | 登录用(无内置默认值,运行时由调用方提供) |
| 待启动店铺名称 | 必填 | 未指定则直接结束 |
| 待启动店铺所属分组名称 | 必填 | 未指定则直接结束 |
| 监听端口 | 可选 | 选用空闲端口(如 9222) |
| 用户数据目录 | 可选 | 使用浏览器默认用户数据目录(启动不传 --user-data-dir;源码已移除 CDP 对该参数的依赖) |
启动不传
--user-data-dir,使用浏览器默认用户数据目录;启动前必须先检查有无正在运行的实例(见第 2 步)。 若用户名/密码未给出,按“已登录”前提执行:启动后先做登录判定(第 4 步),已登录则跳过登录分支。
流程总览
执行步骤
统一约定:条件等待 + 超时兜底(不使用固定停顿)
等待(条件, 超时, 轮询间隔=300ms):在目标页面用 JS 每 300ms 轮询一次条件,成立立即继续;超时仍未成立则执行该步“兜底”分支(记录原因并结束或补救)。- 条件一旦满足马上继续:正常网络下多数步骤 1~2s 内完成;超时上限仅用于防卡死/防误判。
- 判定类步骤(登录成功、登录态、CDP 返回结果)改为“监测成功/失败信号”,而非空等固定时长。
1. 检查待启动店铺名称与所属分组
店铺名称或所属分组未指定则直接结束:未指定店铺名 → 跳到第 10 步结束(started=false,原因=未指定店铺名);未指定分组 → 跳到第 10 步结束(原因=未指定分组名)。
2. 关闭现有实例、选用空闲端口并启动浏览器
本步为敏感操作,需先向用户展示《用户警告与安全声明》;按顺序执行:2a(检测并在需要时关闭现有实例)→ 2b(选用空闲端口)→ 2c(启动新的调试浏览器):
2a. 检测并关闭现有浏览器(如存在)
检测本机是否存在挖象浏览器进程(如 waxiang.exe;示例:tasklist /FI "IMAGENAME eq waxiang.exe" 或 PowerShell Get-Process -Name waxiang -ErrorAction SilentlyContinue)。
- 未运行 → 直接进入 2b;
- 已在运行 → 提醒用户“挖象浏览器正在运行,需先关闭它,才能以远程调试模式启动新的浏览器”,并等待用户明确答复(未获同意不得关闭):
- 用户同意 → 结束该浏览器进程(示例:
taskkill /IM waxiang.exe /F,或Stop-Process -Name waxiang -Force),并轮询等待进程完全退出(每 500ms,超时 30s);兜底:超时仍检测到进程 → 结束(原因=浏览器未能关闭);退出后进入 2b; - 用户不同意 → 结束(原因=
用户未同意关闭浏览器)。
- 用户同意 → 结束该浏览器进程(示例:
2b. 选用空闲端口(如 9222)
从空闲端口中选定一个(如 9222);2c 的启动参数与后续 CDP 探测均使用该端口。
2c. 以远程调试模式启动浏览器(使用默认用户数据目录)
waxiang.exe --remote-debugging-port=9222 --remote-allow-origins=* --no-first-run --no-default-browser-check about:blank
不携带
--user-data-dir:源码已移除 CDP 对 user-data-dir 的依赖,直接使用浏览器默认用户数据目录启动。若已有实例在运行,新进程可能转发给它、调试端口不生效,所以 2a 的关闭动作是启动的前置条件。安全说明:调试端口仅绑定本机回环地址(
127.0.0.1),不对局域网/公网开放;--remote-allow-origins=*仅为兼容会携带 Origin 头的本机调试客户端,若所用客户端不发送 Origin 头可移除该开关。请仅在可信设备上执行。
等待:轮询探测 http://127.0.0.1:9222/json/version 可访问(每 500ms,超时 30s)。兜底:超时未就绪 → 结束(原因=浏览器未就绪)。
3. 打开 userAdmin 并等待登录控件渲染
在当前标签页打开 https://hao.waxiang.com/account/userAdmin。
等待条件:userinfo-right 元素已渲染(首选 XPath //div[contains(@class,'userinfo-right')],失败用备选绝对路径);轮询 300ms,超时 20s。
兜底:超时仍未出现 → 追加一次判定:
- 若页面已出现登录弹窗(
.el-dialog内含手机号输入框input[@placeholder='请输入手机号'])或已跳转登录页 → 说明已处于登录入口,直接进入第 5 步; - 否则 → 结束(原因=
登录控件未渲染)。
先确认控件渲染完成再做判定,避免把“页面还没加载出来”误判成“已登录”。
4. 登录判定(幂等分支)
读取第 3 步已确认存在的 userinfo-right 文本:
- 为
登录:点击该元素 → 执行 4a; - 为
退出登录:已登录,跳过第 5~8 步,直接到第 9 步(CDP 打开店铺)。
说明:该元素是登录/登出切换控件,未登录显示“登录”,已登录显示“退出登录”。
4a.(点“登录”后)等待登录弹窗
等待条件:弹窗内出现 input[@placeholder='请输入手机号'];轮询 300ms,超时 10s。兜底:超时未出现 → 结束(原因=登录弹窗未出现)。
5. 切换密码登录(仅登录分支执行)
密码图标 XPath://img[contains(@class,'icon-img') and contains(@src,'pwd')]
- 未命中:点击“其他登录方式”,等待密码图标出现(轮询 300ms,超时 5s);仍无 → 结束(原因=
无其他登录方式入口)。 - 点击密码图标后:等待弹窗内出现
input[@type='password'](轮询 300ms,超时 8s)。兜底:未出现 → 结束(原因=密码登录表单未出现)。
6. 填入用户名
前置条件:仅当挖象用户名非空时才定位并输入;为空则跳过本步(不定位、不输入),继续第 7 步。
定位 input[@placeholder='请输入手机号'],用 value setter 清空并写入、触发 input/change 事件。
校验(替代停顿):立即回读 value 应等于用户名;未即时生效则轮询至多 3 次(300ms 间隔);仍不一致 → 重填 1 次 → 再失败则结束(原因=用户名填写失败)。
7. 填入密码
前置条件:仅当挖象密码非空时才定位并输入;为空则跳过本步(不定位、不输入),继续第 8 步。
定位 input[@type='password'],同上写入并回读校验;失败重填 1 次,仍失败 → 结束(原因=密码填写失败)。
附加:填完后检测一次验证码/滑块(img[src*='captcha'|'verify']、canvas 或“滑块/验证”文案),仅作第 8 步失败预判提示,不需停顿。
8. 提交登录(按成功/失败信号等待)
点击“登录”按钮:首选 XPath(锚定手机号输入框所在表单)//form[.//input[@placeholder='请输入手机号']]//div[contains(@class,'btn') and contains(.,'登录')];兜底 1 为绝对路径 /html/body/div[1]/div/div[2]/div/div/div/div/div[2]/form/div[4]/div/div;兜底 2 为弹窗内可见且文本为“登录”的叶子元素。
等待(轮询 400ms,窗口 A 30s):
- 成功信号:
userinfo-right变为退出登录,或 URL 离开登录态进入账号相关页面 → 继续第 9 步(CDP 打开店铺); - 失败信号(同步监测):
.el-message错误提示(含 密码/账号/验证 等)或滑块/验证码出现 → 结束(原因=登录失败:<错误文本>)。 - 兜底 1:窗口 A 30s 内无任何信号 → 不判失败,进入“登录后台补发监控”(防御性兜底,每 1s 轮询,最长再等 90s;登录正常 1~3s 即成功,此兜底仅在页面信号延迟/网络波动时生效):
- 出现成功信号 → 视为登录成功,继续第 9 步(CDP 打开店铺,即登录完成后自动补发 openFingerprint);
- 出现失败信号 → 结束(原因=
登录失败:<错误文本>); - 累计仍无信号 → 结束(原因=
登录结果未知)。
9. 通过 CDP 打开指定店铺(已登录 / 登录成功后执行)
已登录(第 4 步判为“退出登录”)或第 8 步登录成功后执行本步;替代原“打开 accManage 查表点启动”的 DOM 流程,本流程不再访问 accManage 页面,因此不存在“关闭唯一标签页导致主窗口退出、终止启动中店铺”的风险。
FingerprintCenter.openFingerprint 是浏览器级会话上的自定义方法,须连接浏览器级调试端点(勿连页面 target);CDP 即经该调试 WebSocket 收发 JSON-RPC 报文。
动作:
-
取浏览器级调试端点:
GET http://127.0.0.1:<监听端口>/json/version(<监听端口>= 第 2 步选定的空闲端口,非固定 9222),读取返回中的webSocketDebuggerUrl(形如ws://127.0.0.1:<监听端口>/devtools/browser/<uuid>); -
用 WebSocket 客户端连上该地址;
-
发送一条 JSON-RPC 请求帧(
id自增且唯一),把“打开指定店铺”指令直接发过去:json {"id": 1, "method": "FingerprintCenter.openFingerprint", "params": {"shopName": "<待启动店铺名称>", "teamName": "<待启动店铺所属分组名称>"}} -
等待服务端返回
id与请求一致 的响应帧,解析该响应帧中的数据:windows.port就是新打开的店铺所在浏览器的 CDP 远程调试端口,向上暴露这个端口供 AI Agent 进一步使用(JSON.stringify格式化输出);本步以该返回结果为准判定,不再做任何 DOM 二次校验。该端口仅用于同一台机器上的后续自动化(仅输出到本机日志/返回值),不通过网络外发。
判定(以 CDP 返回结果为准):
- 收到响应且返回内容无错误(无错误码/错误信息字段)→
started=true,原因=CDP 已请求打开店铺(详见日志返回); - 返回内容含错误(错误码/错误信息)→
started=false,原因=CDP 打开店铺失败:<返回中的错误文本>; - 建连/发送/等待超时、连接断开或未收到匹配
id的响应 →started=false,原因=CDP 调用失败:<异常信息>。
收尾:关闭该 WebSocket 调试连接(仅断开调试连接,不关闭挖象浏览器主窗口/店铺窗口)。
10. 结束
输出结论:started=true/false 及原因(CDP 已请求打开店铺 / CDP 打开店铺失败:<错误> / CDP 调用失败:<异常> / 登录失败:<错误> / 登录结果未知 / 登录弹窗未出现 / 登录控件未渲染 / 浏览器未就绪 / 浏览器未能关闭 / 用户未同意关闭浏览器 / 未指定店铺名 / 未指定分组名 等)。
注意事项
- 店铺名称与所属分组是必填参数(分别作为
openFingerprint的shopName/teamName);浏览器路径有内置默认值;用户名/密码无内置默认值(运行时由调用方提供,未提供时按“已登录”前提处理,第 6/7 步会自动跳过填入)。 - 启动不携带
--user-data-dir,直接使用浏览器默认用户数据目录(源码已移除 CDP 对该参数的依赖)。启动前先执行第 2 步(存在运行中的实例时,先征得用户同意后关闭 → 选用空闲端口 → 启动),避免新进程转发到已有实例、调试端口不生效。 - 打开店铺一律通过 CDP 命令
FingerprintCenter.openFingerprint完成:取/json/version的webSocketDebuggerUrl→ WebSocket 连接 → 发送 JSON-RPC 请求帧(method=FingerprintCenter.openFingerprint、params={shopName, teamName})→ 按id匹配响应帧;不再操作 accManage 页面 DOM,也不存在“关闭唯一标签页=关闭主窗口、终止启动中店铺”的风险。 - 日志要求:发送后必须把该 CDP 请求的返回结果完整打印到日志(
JSON.stringify(result, null, 2)),并以返回内容为准判定成败;同时解析windows[].port(新开店铺浏览器的 CDP 远程调试端口)并向上暴露,供 AI Agent 后续使用(-1表示该窗口未提供端口;该端口仅限本机使用,不外发)。 - 一律用“条件等待 + 超时兜底”,不要写死停顿:等待对象是元素出现 / 登录成功或失败信号,而非固定秒数。
- 定位优先使用属性 XPath(更抗页面结构调整),绝对路径仅在首选失效时作为兜底。
- 登录是幂等分支:已登录的浏览器应跳过登录分支,直接执行第 9 步 CDP 打开。
Related skills
- Downloads
- Security audit
- Pass
- Last updated
- 1mo ago
- Current version
- v1.0.4
- License
- MIT-0
