waxiang-store
挖象浏览器打开店铺工作流:在挖象浏览器中登录之后,打开用户指定分组指定名称的店铺。当用户需要在挖象浏览器中打开某个店铺(给出店铺名称与所属分组)时使用。
How do I install this agent skill?
npx skills add https://clawhub.ai --skill waxiang-storeIs this agent skill safe to install?
No partner audit is available yet. Read the source before installing.
What does this agent skill do?
挖象浏览器启动店铺
本技能封装“在挖象浏览器中远程打开某个店铺”的完整可执行流程。按给定步骤执行,在登陆状态下打开指定分组指定名称的店铺,未登录时先执行登录流程;若挖象浏览器已在运行,先提醒用户并在征得同意后关闭,再以远程调试模式启动(使用浏览器默认用户数据目录)。
⚠️ 用户警告(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 步),已登录则跳过登录分支。
流程总览
flowchart TD
A[1. 检查店铺名称与所属分组] -->|未指定| Z[10. 结束 started=false]
A -->|已指定| B1[2a. 检测挖象浏览器是否在运行]
B1 -->|在运行| B2[提醒用户并征询是否关闭]
B2 -->|用户同意| B4[关闭浏览器并等待进程退出]
B2 -->|用户拒绝| Z
B4 --> B3[2b. 选用空闲端口(如 9222)]
B1 -->|未运行| B3
B3 --> B5[2c. 远程调试模式启动挖象浏览器<br>用默认用户数据目录<br>等 CDP 就绪]
B5 --> C[3. 打开 userAdmin<br>等 userinfo-right 渲染]
C --> D{4. 登录判定<br>读 userinfo-right 文本}
D -->|登录| E0[4a. 等登录弹窗出现]
E0 --> E[5. 切换密码登录<br>等密码框出现]
E --> F[6. 填用户名<br>用户名空则跳过]
F --> G[7. 填密码并校验<br>密码空则跳过]
G --> H[8. 提交登录<br>等成功/失败信号]
H --> I[9. CDP 打开店铺<br>openFingerprint → 打印返回并暴露 windows.port]
D -->|退出登录/不存在| I
I --> Z[10. 按 CDP 返回结果输出 started 及原因]
执行步骤
统一约定:条件等待 + 超时兜底(不使用固定停顿)
等待(条件, 超时, 轮询间隔=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自增且唯一),把“打开指定店铺”指令直接发过去:{"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 打开。
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/clawhub.ai/waxiang-store">View waxiang-store on skillZs</a>