站斧 Playwright 自动化

通过站斧 WebDriver 版 HTTP API 控制客户端与店铺；拿到 WebDriverPort 之后才用 Playwright connect_over_cdp 做页面自动化。

Agent 提示：技能首次安装、客户问「怎么用 / 如何使用」时，先向客户发送下方「客户使用指南」（可摘要，不必全文照搬）。

前置（Agent）：站斧版本要求 Windows ≥ 5.2.12，macOS > 5.2.10；环境已安装 playwright、requests。

macOS 限制：SetDownLoadPath、ClearCacheFolder、ClearCache、SetInstallPlugins 目前不支持。客户在 Mac 上提出这些需求时，应直接说明暂不支持并停止，勿调用对应 HTTP 接口。

客户使用指南（安装技能时向客户说明）

以下内容可直接复制或摘要发给客户。

一、使用前准备

1. 站斧版本：请确认站斧版本要求（Windows ≥ 5.2.12，macOS > 5.2.10）。
2. 首次打开店铺会下载浏览器内核，耗时较长，建议您先在站斧客户端里手动打开一次目标店铺，等内核下载完成后再用自动化。
3. 不同店铺可能使用不同内核。若自动化打开失败或提示内核相关错误，请先在站斧里手动打开一次该店铺（或与您要用的店铺同内核的店铺），内核就绪后再发指令。
4. 店铺须已绑定 IP / 设备；未绑定时打开会失败，请在站斧客户端检查店铺设备绑定。
5. macOS 暂不支持：设置下载目录、清除缓存（单店/全部）、设置店铺插件（SetDownLoadPath / ClearCache / ClearCacheFolder / SetInstallPlugins）。请在 Windows 上使用这些能力。

二、最常用的说法（推荐）

说法可略有不同，只要包含「打开站斧」「打开店铺」和店铺名称即可；站斧已在运行时，一般不会重启站斧，直接开/关店铺。

三、首次未登录时

若提示「站斧未登录，请提供账号和密码」，请提供您的站斧老板账号和密码（自动化仅使用您当场提供的账号，不会使用内测账号）。

四、店铺已经打开时

若您要的店铺已经在运行，系统会先问：是否需要关闭该店铺？ 按您的选择回复即可；不需要关闭则可直接继续后续操作。

五、页面自动化（进阶）

店铺打开后，可继续用自然语言描述要在店铺浏览器里做的事，例如：

• 「在 B 站搜索并播放某某视频」
• 「打开某网址并填写表单」
• 「抓取当前页面某某信息」

此类操作会先等设备安全检测通过（约 15 秒），再自动操作页面。

七、创建店铺

发送 「创建店铺」 或 「打开站斧并创建店铺 xxx」，按提示提供信息即可（须已登录站斧）。

必填信息

建议提供

选填信息（有则提供，没有可留空）

创建成功后：系统会等列表同步，再按店铺名查询并打开新店铺。若创建失败，请检查店铺名是否重复、IP 是否有效、自定义平台是否填写了网址。

说法示例

创建店铺，店铺名 test001，平台自定义平台，网址 https://www.baidu.com，绑定 IP 118.x.x.x

八、查看店铺列表

发送 「获取店铺列表」、「列出我的店铺」 或 「店铺列表第 1 页」 即可。

• 系统会拉取您账号下的店铺，默认第 1 页、每页 10 条（可说「第 2 页」「每页 20 条」调整 page / limit）。
• 列表中通常包含：店铺名、平台、绑定 IP、创建/更新时间 等。
• 能正常拉到列表 = 站斧已登录；拉不到或报错 = 需要先登录（见「三、首次未登录时」）。

说法示例

获取店铺列表
列出店铺，第 2 页，每页 20 个

十、下载与缓存（进阶）

清除缓存为不可逆操作，执行前系统会向您确认。

macOS 暂不支持本节全部能力（SetDownLoadPath / ClearCache / ClearCacheFolder）。

十一、店铺插件（进阶）

发送 「设置店铺插件」，在打开店铺之前指定默认加载的插件（SetInstallPlugins → OpenBrowser）。

您需提供

可一次提供多个插件；说 「清空店铺插件」、「清除默认插件列表」 或传空列表 [] 表示不额外指定插件。

重要：若插件曾通过自动化安装，清空列表后还须清除该店铺本地缓存（ClearCache），再重新打开店铺，清空才生效。

macOS 暂不支持 SetInstallPlugins（及依赖的 ClearCache）。

说法示例

打开站斧，设置默认插件名称为紫竹自动化插件，插件 ID 为空，再打开店铺 ztest144
设置店铺插件，插件名 RXMallHelper（省略插件 ID）
设置店铺插件，插件名 紫竹自动化插件，插件 ID 为空
清除默认插件列表，重新打开 ztest144（会先 SetInstallPlugins([]) → ClearCache → 再开店铺）

设置会在后续 OpenBrowser 时生效；若店铺已打开，需先关闭再重新打开才加载新插件。

九、常见问题

硬规矩（红线，最高优先级）

以下规则覆盖本 Skill 其他所有「等待 / 重试 / 备用方案」描述，冲突时以本节为准。

1. 获取端口前：禁止写脚本

在 **OpenBrowser 打开店铺并成功拿到 WebDriverPort 之前**：

• 禁止新建或运行任何 .py / .js / .sh 等可执行脚本文件（含 _tmp_*.py、临时业务脚本）
• 禁止为完成任务而编写「一次性自动化脚本」
• 只允许调用本 Skill 提供的 HTTP 接口（见 reference.md）或 Shell 直接发 HTTP 请求
• 允许读写临时数据文件（如 api_port.json、mall_cache.json、opening_malls.json 状态文件），但数据文件不可执行

Skill 目录下 scripts/*.py 仅供人工参考或本地调试；小龙虾 Agent 在获取端口前不得运行这些脚本，应直接 POST http://127.0.0.1:{api_port}。

2. 通讯失败或关键操作报错：立即结束

出现以下情况，马上停下并向客户报告（**GetBrowserList 探测轮询**、以及「OpenBrowser 前 GetBrowserWebDriver 单次 5s 超时后仍 OpenBrowser」除外，见下节）：

• HTTP 连不上站斧（连接拒绝、超时、无响应）
• 除登录/运行态探测用 GetBrowserList 外，关键 API 返回失败（returnObj.success == false、缺必需字段）
• Login / GetMallByName / CreateBrowser / SetInstallPlugins / OpenBrowser（returnObj !== true）/ GetBrowserWebDriver 失败（例外：OpenBrowser 前探测 GetBrowserWebDriver 超时 5s → 仍执行 OpenBrowser）

禁止：

• 反复重试同一失败操作（GetBrowserList 的 8s 轮询、以及 OpenBrowser 前 GetBrowserWebDriver 仅允许单次 5s，超时改走 OpenBrowser除外）
• 全盘 / 跨盘符搜索站斧安装包（Windows：where.exe、-Recurse、glob **\站斧.exe；macOS：全盘 mdfind / find）
• 遍历桌面全部 .lnk 或解析**文件名不含「站斧」**的快捷方式（如逐个扫 GitHub、VS Code、其他浏览器快捷方式）
• 翻代码库「研究」原因
• 写「等通讯好了再跑」的备用方案或延迟任务
• 自行换端口 / 换路径 / 换工具碰运气（例外：冷启动固定 --httpport=12678；禁止扫描 8081/8082 等备用端口）
• 客户仅要求打开店铺或关闭店铺时，在 api_port HTTP 通讯正常的情况下仍执行杀进程、冷启动或 ExitClient（除非客户明确要求重启站斧）
• 用 CheckClientOpen / LoadSuccess / LoadFailed 判断站斧是否已打开（改用 GetBrowserList，见下）
• 在 macOS 上调用 SetDownLoadPath / ClearCacheFolder / ClearCache / SetInstallPlugins（目前不支持，应直接告知客户）

3. 获取端口前：只能 HTTP，禁止浏览器工具

在拿到 **WebDriverPort 之前**：

• 只允许向 http://127.0.0.1:{api_port} 发 HTTP POST（WebDriverModule）
• 禁止打开系统 Chrome / Edge / Firefox
• 禁止使用 Playwright / Puppeteer（含 launch、connect_over_cdp）
• 禁止使用 Cursor browser MCP / CDP 浏览器工具绕开站斧

拿到端口之后，仅允许 playwright.chromium.connect_over_cdp("http://127.0.0.1:{WebDriverPort}") 接管站斧店铺浏览器。

4. 工具名必须来自清单

禁止瞎编 action、工具名、命令名。只能使用下方「接口清单」中的 action 名称。

阶段 A — 获取端口前（仅 HTTP）

macOS：客户要求下载目录 / 清缓存 / 设插件时，立即停止并告知「macOS 暂不支持该功能」，禁止调用上表标注「仅 Windows」的 action。

HTTP 格式（固定）：

POST http://127.0.0.1:{api_port}
Content-Type: application/json

{
  "module": "WebDriverModule",
  "action": "<上表 action>",
  "browserId": "<mall_id，可选>",
  "args": "<JSON 字符串，可选>"
}

站斧启动命令行参数（按操作系统）：

Windows（固定，缺一不可）：

站斧.exe --multip --run_type=web_driver --ipc_type=http --httpport=12678

macOS（对齐官方 Playwright demo；不含 --multip）：

open -a /Applications/站斧.app --args --run_type=web_driver --ipc_type=http --httpport=12678

也可：open -a 站斧 --args --run_type=web_driver --ipc_type=http --httpport=12678

默认 API 端口：12678。冷启动时固定使用该端口；启动成功后写入 Skill 目录 [api_port.json](api_port.json)（见下节）。

HTTP 请求方式（阶段 A · 禁止 curl / 禁止换工具试错）

Agent 默认只用 Python requests（稳定、无引号逃逸坑）。禁止为同一探测在 PowerShell / curl / Python 之间来回换工具（浪费时间）。

单次探测超时：timeout=1.5 秒（够判通断，勿用 3～30s 长超时堵死）。

推荐模板（直接复制，勿改成复杂转义）：

import requests, json
r = requests.post(
    "http://127.0.0.1:12678",
    json={"module": "WebDriverModule", "action": "GetBrowserList",
          "args": json.dumps({"page": 1, "limit": 20})},
    timeout=1.5,
)
print(r.text)

连接拒绝 / 超时 → 视为站斧未打开，立刻清空 opening_malls.json 并冷启动；不要改用 PowerShell 再探一次。

备选（仅人工调试） PowerShell 手动拼 JSON：

$body = '{"module":"WebDriverModule","action":"GetBrowserList","args":"{\"page\":1,\"limit\":20}"}'
Invoke-RestMethod -Uri "http://127.0.0.1:12678" -Method Post -Body $body -ContentType "application/json"

禁止 Windows curl 手工转义 JSON；禁止 PowerShell ConvertTo-Json 嵌套 args。

打开站斧快速路径（优先按此执行，少读少试）

1. 读 api_port.json → 对 api_port（默认 12678）发 一次 上述 Python GetBrowserList（timeout=1.5）
2. 能取到 mall_list → 已打开，结束（或继续开店铺）
3. 无响应 → 清空 opening_malls.json → 用 install_dir（无效再按 OS 查找；都没有则问客户）定位站斧
4. 杀进程（最多等 1s；进程已没则可立刻继续，禁止固定干等 3s）：

• Windows：taskkill /f /t /im 站斧.exe
• macOS：killall 站斧

5. 启动：

• Windows：站斧.exe --multip --run_type=web_driver --ipc_type=http --httpport=12678
• macOS：open -a /Applications/站斧.app --args --run_type=web_driver --ipc_type=http --httpport=12678

6. 立刻轮询 GetBrowserList（间隔 0.5s，总计最多 8s）；能取到数据即成功写回 api_port.json
7. 8s 内仍无 WebDriver 通讯 → 立即停止、禁止重试，按下方「通讯失败对客户话术」原样提示（含已确认的安装路径）
8. 仅「打开站斧」且无开店需求 → 到此结束，勿继续 OpenBrowser

阶段 B — 拿到 WebDriverPort 之后

禁止：playwright.chromium.launch、browser_navigate（MCP）、Puppeteer launch。

两阶段工作流

阶段 A（仅 HTTP，禁止脚本 / 禁止 Playwright / 失败即停）
  [读 api_port.json → 单次 GetBrowserList 探测该端口] → 能取到数据则站斧已打开，直接继续（开/关店铺均不重启）
  → 无 HTTP 响应 = 站斧未打开 → **立刻清空 opening_malls.json** → 再冷启动(12678)
  → 冷启动前查找站斧：api_port.json →（Windows 快捷方式/常见目录；macOS `/Applications`/`~/Applications`）；**全部找不到则停止并向客户索要安装路径**（禁止全盘搜）
  → GetBrowserList 探测运行态/登录（最多 8s；能取到数据=已打开；禁止用 LoadSuccess 判断）→ [未登录则提示 Login]
  → [SetInstallPlugins / SetDownLoadPath 可选，**仅 Windows**，须在 OpenBrowser 前；**macOS 跳过且勿调用**]
  → 打开（站斧已打开之后）：写入 opening_malls.json → resolve mall_id → GetBrowserWebDriver **单次 5s** 判是否已开（超时仍 OpenBrowser）→ OpenBrowser → GetBrowserWebDriver
  → 关闭：resolve mall_id → CloseBrowser → 从 opening_malls.json 去掉该店铺名
  → 关闭站斧：ExitClient → 清空 opening_malls.json

阶段 B（端口拿到后）
  connect_over_cdp → [设备安全检测 15s] → 业务 Playwright 自动化

Task Progress:
- [ ] 1. 收集客户参数（含 mall_name）
- [ ] 2. 【阶段 A】读 `api_port.json`，对**唯一目标端口**单次 `GetBrowserList`（无文件则用 **12678**）；**能取到数据 = 站斧已打开，禁止冷启动**（开/关店铺均适用；**禁止**用 `LoadSuccess` 判断）
- [ ] 3. 【阶段 A · 探测到站斧未打开】**立刻清空 `opening_malls.json`** → 查安装路径 → 杀进程（Win:`taskkill` / Mac:`killall 站斧`，最多等 1s）→ 冷启动 `--httpport=12678` → **立刻**轮询 `GetBrowserList`（间隔 0.5s，最多 8s）→ 写回 `api_port.json`
- [ ] 4. 【阶段 A】`GetBrowserList` 探测运行态/登录（间隔 **0.5s**，**总计最多 8s**）；能取到 `mall_list` = 已打开且已登录；仍无法确认则提示客户提供账号密码
- [ ] 5. 【阶段 A · 打开店铺 · 仅站斧已打开后】将 `mall_name` **写入** `opening_malls.json`（打开意图配置；**禁止**在站斧未打开时写入）
- [ ] 6. 【阶段 A】resolve mall_id（读 `mall_cache.json` → 未命中则 `GetMallByName` 并写缓存）/ `CreateBrowser`（失败即停）
- [ ] 7. 【阶段 A】resolve mall_id（关店则跳过 OpenBrowser 相关步骤）
- [ ] 8. 【阶段 A · 打开店铺】`GetBrowserWebDriver` **只请求一次、超时 5s** 判断是否已打开；超时/无端口则**仍执行 OpenBrowser**（禁止二次探测、禁止 15s 长超时）
- [ ] 9. 【阶段 A · 已打开】询问客户是否需要关闭店铺；未确认不操作
- [ ] 10. 【阶段 A · 需打开】OpenBrowser（失败即停）→ GetBrowserWebDriver
- [ ] 11. 【阶段 A · 关闭店铺】CloseBrowser → **从 `opening_malls.json` 去掉该店铺名**（HTTP 正常时不重启站斧）
- [ ] 12. 【阶段 A · 关闭站斧】ExitClient → **清空 `opening_malls.json`**
- [ ] 13. 【阶段 B】connect_over_cdp
- [ ] 14. 【阶段 B · 仅业务自动化】设备安全检测（15s 超时）
- [ ] 15. 【阶段 B】执行业务自动化
- [ ] 16. 收尾：CloseBrowser / ExitClient（**仅客户明确要求时** ExitClient；关店/关站斧时同步清理 `opening_malls.json`）

禁止无头模式

1. 站斧必须以 WebDriver 模式有界面启动
2. 只能 connect_over_cdp，禁止 launch(headless=True)
3. 执行 Playwright 前调用 ensure_headed_mode()，设置 PLAYWRIGHT_HEADLESS=0
4. 禁止使用 Cursor 内置 browser MCP 替代站斧浏览器

执行前：向客户收集参数

缺少必填项时先询问，不要猜测账号密码或 IP。

站斧安装路径（打开站斧 / 冷启动时）：先读 api_port.json 的 install_dir → 无效再按操作系统查找（见「启动站斧」）。任一方式命中后，立即把安装路径写回 api_port.json。都找不到时，必须停止并向客户索要安装路径；禁止全盘搜索或猜测路径。

• Windows：目录内需含 站斧.exe；客户提供后验证 {folder_path}\站斧.exe 存在再继续。
• macOS：需为 站斧.app（如 /Applications/站斧.app）；客户提供后验证 .app 存在再继续。

登录态探测与 Login

站斧启动（或复用 API）后，必须在 8s 内通过 GetBrowserList 判断站斧是否已打开且已登录（禁止用 CheckClientOpen / LoadSuccess / LoadFailed 判断）：

{"action": "GetBrowserList", "module": "WebDriverModule", "args": "{\"page\":1,\"limit\":20}"}

不要默认主动索要登录信息；仅在 GetBrowserList 失败且后续需要操作店铺时再向客户索取。

禁止在 Skill、脚本或对话中保存、引用或使用任何内测/示例账号密码；仅使用客户当场提供的 username / password 调用 Login，且固定 isboss=true（老板账号）。

Login 请求示例：

{
  "action": "Login",
  "module": "WebDriverModule",
  "args": "{\"username\":\"...\",\"password\":\"...\",\"isboss\":true}"
}

Login 返回 success != true → 立即结束，原样报告 returnObj.msg（如密码错误）。

按名称打开店铺

创建店铺

创建成功后须等待列表同步，再 resolve mall_id → OpenBrowser。

设置店铺插件（SetInstallPlugins）

客户要求打开店铺前加载指定插件时，须在 OpenBrowser 之前调用。

省略 chrome_id：

{
  "action": "SetInstallPlugins",
  "module": "WebDriverModule",
  "args": "{\"installPlugins\":[{\"plugin_name\":\"RXMallHelper\"}]}"
}

**chrome_id 传空字符串**（客户说「插件 ID 为空」时用此写法）：

{
  "action": "SetInstallPlugins",
  "module": "WebDriverModule",
  "args": "{\"installPlugins\":[{\"plugin_name\":\"紫竹自动化插件\",\"chrome_id\":\"\"}]}"
}

清空插件列表（installPlugins: []）：

{
  "action": "SetInstallPlugins",
  "module": "WebDriverModule",
  "args": "{\"installPlugins\":[]}"
}

通过自动化安装的插件，清空列表后须对该店铺调用 ClearCache，再 OpenBrowser，清空才生效。

清空并重新打开店铺流程：

1. SetInstallPlugins（installPlugins: []）
2. resolve mall_id 取 mall_id
3. ClearCache（browserId = mall_id；会关闭该店铺）
4. OpenBrowser → 等 15s → GetBrowserWebDriver

returnObj.success != true → 立即结束，原样报告 returnObj.msg。

设备安全检测（仅业务自动化）

客户提出页面级自动化（填表、抓取、播放视频等）时，阶段 B 必须先等设备安全检测成功（15s 超时）；仅启动/开店铺不需要。

超时或未成功 → 告知客户：「没检测成功无法进行自动化」，立即结束。

打开店铺 / 关闭店铺（意图路由 · HTTP 正常则不重启）

客户发送打开店铺或关闭店铺指令时，一律先读 api_port.json 并对 api_port 做单次 GetBrowserList 探测（禁止用 LoadSuccess 判断）。

核心：开店铺、关店铺都是 HTTP 操作；GetBrowserList 能取到数据 = 站斧已打开，继续 HTTP 即可，不要「顺手」重启客户端。禁止根据 CheckClientOpen 的 LoadSuccess / LoadFailed 判断站斧是否已打开。

关闭店铺流程（阶段 A · 仅 HTTP）

1. 读 api_port.json → 单次探测 GetBrowserList
2. 能取到数据或有 HTTP 响应 → resolve mall_id（读 mall_cache.json → 未命中则 GetMallByName 并写缓存；失败即停）
3. CloseBrowser（browserId = {mall_id}）；成功时 returnObj === null，失败时 returnObj === false
4. 从 opening_malls.json 去掉该 mall_name
5. 不调用 ExitClient（除非客户明确要求退出站斧客户端）
6. 禁止因关店而冷启动或杀站斧进程（Win:站斧.exe / Mac:killall 站斧）

{"action": "CloseBrowser", "module": "WebDriverModule", "browserId": "{mall_id}"}

站斧运行态复用（读本地端口 · 单次 GetBrowserList · 禁止扫端口）

客户要求打开店铺、关闭店铺或执行业务自动化时，不要默认杀进程重启站斧，也禁止依次试探 8081/8082 等端口。

本地状态记录 api_port.json

路径：Skill 目录下 [api_port.json](api_port.json)（与 SKILL.md 同级）。

{
  "api_port": 12678,
  "install_dir": "I:\\ZhanFu",
  "updated_at": "2026-06-17T12:00:00"
}

单次探测（仅一个端口 · 用 GetBrowserList，禁止 LoadSuccess）

对目标端口（本地记录或 12678）发一次 POST，Body 为正确 JSON 的 GetBrowserList：

{"module":"WebDriverModule","action":"GetBrowserList","args":"{\"page\":1,\"limit\":20}"}

禁止再用 CheckClientOpen 的 LoadSuccess / LoadFailed 判断站斧是否已打开。「模块 undefined 未加载」等说明该端口上已有 HTTP 服务；用正确 JSON 的 GetBrowserList 重发即可，不要换端口。

复用已运行实例时，直接用 GetBrowserList（最多 8s）判断是否已打开/已登录。无论冷启动还是复用，探测总耗时不超过约 8s（不再先等 CheckClientOpen / LoadSuccess）。

打开意图配置 opening_malls.json

路径：Skill 目录下 [opening_malls.json](opening_malls.json)（与 SKILL.md 同级）。

用于记录客户已发出「打开某店铺」指令的店铺名；关店 / 关站斧时清理。OpenBrowser 前用 GetBrowserWebDriver 统一单次 5s 探测（与是否已在列表无关）。

{
  "malls": ["ztest126"],
  "updated_at": "2026-07-14T10:00:00"
}

opening_malls.json 只记店铺名，与 mall_cache.json（店铺 ID）无关。禁止在站斧未打开时写入店铺名。

本地店铺 ID 缓存 mall_cache.json

路径：Skill 目录下 [mall_cache.json](mall_cache.json)（与 SKILL.md 同级）。

{
  "mall_map": {
    "ztest126": "2786463",
    "测试WebDriver随机950317": "2786500"
  },
  "updated_at": "2026-06-24T16:30:00"
}

resolve mall_id（统一查 ID 流程）

凡需 mall_id 的操作（开/关店铺、ClearCache、GetBrowserWebDriver 等），一律先走缓存：

1. 读 mall_cache.json → mall_map[mall_name] 有值？
   ├─ 是 → 直接用该 mall_id（跳过 GetMallByName）
   └─ 否 → 调用 GetMallByName → 成功后立即写入 mall_map
2. 使用 mall_id 调用后续 API
3. 若后续 API 因店铺 ID 无效失败（如 CloseBrowser returnObj===false）：
   → 删除 mall_map 中该 mall_name 条目
   → 重新 GetMallByName 取 id 并写回缓存
   → 用新 id 重试一次（仍失败则立即结束）

注意：mall_cache.json 记录的是店铺 ID，与站斧「清除店铺缓存」(ClearCache) 无关；清浏览器缓存不要清空 mall_cache.json。

已打开店铺的确认（OpenBrowser 前）

客户要求打开某店铺时：

1. 立刻将 mall_name 写入 opening_malls.json（见「打开意图配置」；站斧须已打开）
2. resolve mall_id 拿到 mall_id
3. 先调 GetBrowserWebDriver 判断目标店铺是否已打开——只请求一次，超时固定 5 秒

{"action": "GetBrowserWebDriver", "module": "WebDriverModule", "browserId": "{mall_id}"}

判定已打开：5s 内 returnObj.success == true 且 WebDriverPort 有值。

探测规则（一律单次 5s，禁止加长或重试）

禁止：

• 检测到店铺已打开仍静默调用 OpenBrowser（会干扰客户当前页面）
• 检测到店铺已打开未经确认就调用 CloseBrowser
• OpenBrowser 前因 GetBrowserWebDriver 超时而整流程失败退出（应改走 OpenBrowser）
• OpenBrowser 前对 GetBrowserWebDriver 重试或拉长超时（整体只许 1 次 × 5s）

与客户说「关闭店铺」的区别：客户明确说关闭且 HTTP 正常 → 直接 CloseBrowser 并清理 opening_malls.json，无需再问是否关闭；客户说打开但检测到已开 → 才须询问是否关闭。

启动站斧（阶段 A · 仅冷启动时）

仅当 目标端口无 HTTP 响应，或端口上是非站斧 WebDriver 服务时，才执行：

1. 立刻清空 opening_malls.json（打开站斧命令检测到未打开时必须清理已写入的店铺名）
2. 杀进程（按 OS；只杀站斧，不要停掉占用端口的其他服务）：

Windows：

taskkill /f /t /im 站斧.exe

macOS：

killall 站斧

杀进程后最多等 1s（可用短轮询看进程是否消失）；进程已退出则立刻继续，禁止固定干等 3s。

3. 分配空闲端口：api_port = get_available_port(12678)（或客户/api_port.json 首选端口）；12678 被占用则自动用 12679…，禁止因此停下来要求客户释放端口。
4. 再以 WebDriver 参数启动（见上文接口清单；macOS 用 open -a，不含 --multip），--httpport= 用上一步分配的端口。
5. 启动后立刻轮询 GetBrowserList（间隔 0.5s，总计最多 8s），端口/列表就绪即继续；禁止启动后再固定 sleep 再探测。
6. 8s 内仍无 WebDriver 通讯 → 立即停止、禁止重试，按「通讯失败对客户话术」提示客户。

通讯失败对客户话术（冷启动后 8s 内无 WebDriver 通讯 · 必须原样）

冷启动后轮询 GetBrowserList 总计 8s 仍无 HTTP 响应 / 未能建立 WebDriver 通讯时：

• 立即停止，禁止重复尝试、换端口、再冷启动
• 必须向客户报告以下模板（{install_path} 换成已确认路径，如 I:\ZhanFu\站斧.exe 或 /Applications/站斧.app）：

站斧启动后 8 秒内未能建立 WebDriver 通讯，已按技能规则停止操作，未重复尝试。
安装位置已确认：{install_path}。请确认站斧版本要求（Windows ≥ 5.2.12，macOS > 5.2.10），然后再告诉我“打开站斧”。

禁止再说「请先手动打开站斧并确认版本为 WebDriver 版且不低于 5.2.12」；版本提醒一律写：Windows ≥ 5.2.12，macOS > 5.2.10。

查找站斧（冷启动前 · 禁止全盘搜索）

必须按顺序、逐项尝试，命中即停；禁止 where.exe / mdfind 全盘扫、递归 glob、跨盘符搜索、翻代码库猜路径。

Windows

macOS

任一顺序命中后：立即把该路径写入 api_port.json 的 install_dir，再冷启动。

客户提供路径后：

• Windows：仅检查 {folder_path}\站斧.exe 是否存在
• macOS：仅检查路径为 站斧.app 或目录内含 站斧.app

验证通过后写入 install_dir；不存在则立即结束并再次提示路径无效。

快捷方式解析规则（Windows 顺序 1 · 只查名为「站斧」的快捷方式）

只查找快捷方式文件名中含「站斧」的 .lnk，禁止遍历桌面全部快捷方式，禁止解析文件名不含「站斧」的 .lnk（无论其目标 exe 名称为何）。

查找范围：当前用户桌面 + 公共桌面（Desktop、Public\Desktop）。

文件名匹配（按序尝试，解析到有效 站斧.exe 即停）：

1. 精确名：站斧.lnk、站斧浏览器.lnk
2. 通配：*站斧*.lnk（仅文件名包含「站斧」者，如 站斧浏览器完成版.lnk）

对每个命中的 .lnk：

1. 解析 TargetPath（PowerShell WScript.Shell.CreateShortcut 或等价方式）
2. 取目标文件所在目录为 install_dir
3. 若 TargetPath 本身为 站斧.exe → 直接使用
4. 否则检查 {install_dir}\站斧.exe；存在则使用

全部快捷方式均未解析出 站斧.exe → 进入顺序 2（固定安装路径），不得改用其他命名规则的快捷方式兜底。

阶段 A 操作要点（HTTP only，失败即停）

GetBrowserList（判断站斧是否已打开 + 登录态 · 必做 · 总计最多 8s）

禁止用 CheckClientOpen / LoadSuccess / LoadFailed 判断站斧是否已打开。冷启动或复用后直接轮询 GetBrowserList：

{"action": "GetBrowserList", "module": "WebDriverModule", "args": "{\"page\":1,\"limit\":20}"}

• 轮询 GetBrowserList，间隔 0.5s，总计最多 8s
• returnObj.success == true 且 returnObj.data.mall_list 可解析（非 null）→ 站斧已打开且已登录，禁止无故调用 Login；同时将 mall_list 中 mall_name → mall_id 写入 mall_cache.json
• 有 HTTP 响应但 8s 内仍 success=false、data=null、无法解析 mall_list → 停止，提示客户：「站斧未登录，请提供账号和密码」；拿到凭证后再 Login（禁止因此冷启动）
• 连接拒绝 / 无响应 → 站斧未打开，走冷启动
• 客户未提供账号密码 → 停止，不猜测、不擅自登录
• 单次请求 timeout=1.5；Agent 只用 Python requests，禁止为通断探测切换 PowerShell/curl

CheckClientOpen 不再作为流程步骤；勿等待 LoadSuccess。

Login

仅在 GetBrowserList 表明未登录且客户已提供账号密码时调用；isboss 固定 true。禁止使用内测或历史会话中的账号。success != true → 立即结束。

GetMallByName / resolve mall_id / CreateBrowser

resolve mall_id：先读 mall_cache.json；未命中才调 GetMallByName，成功后立即写缓存。

任一步 GetMallByName / CreateBrowser 的 success != true 或缺字段 → 立即结束，不重试（缓存 id 导致后续 API 失败时的一次刷新重试除外，见「本地店铺 ID 缓存」）。

OpenBrowser（须先过「已打开店铺确认」）

• 仅站斧已打开后再写入 opening_malls.json（探测未打开时已清空，禁止未打开就写入）
• 目标店铺未打开（含 OpenBrowser 前探测 5s 超时）→ 可直接 OpenBrowser
• 目标店铺已打开（客户要求打开该店）→ 须先询问客户是否需要关闭店铺；确认关闭后再视情况 CloseBrowser / OpenBrowser（见「已打开店铺的确认」）
• 客户明确说关闭店铺且 HTTP 正常 → 直接 CloseBrowser，清理 opening_malls.json，不重启站斧
• OpenBrowser 本身 returnObj !== true 或 ret != 200 → 立即结束，并提醒客户：

  打开店铺失败，请确认该店铺是否已绑定 IP / 设备。 可在站斧客户端查看店铺绑定设备后再试。

• OpenBrowser 之后的 GetBrowserWebDriver 失败（含「超时未获取到」）→ 同上，一并提醒检查 IP/设备绑定；并提醒客户：首次使用请先在站斧客户端手动打开该店铺以下载内核；不同内核的店铺需分别手动打开一次

GetBrowserWebDriver

{"action": "GetBrowserWebDriver", "module": "WebDriverModule", "browserId": "{mall_id}"}

• OpenBrowser 前探测（是否已开）：只请求 1 次，timeout=5；超时/无端口 → 仍 OpenBrowser；禁止重试、禁止加长超时
• OpenBrowser 后取端口：WebDriverPort 为空或请求失败 → 立即结束（禁止循环重试、禁止「再等一会」方案）
• OpenBrowser 后允许单次固定等待 15s 再调 GetBrowserWebDriver（不算重试）；若仍失败则结束。

阶段 B：Playwright CDP（端口拿到后）

from headed_mode import ensure_headed_mode
from playwright.sync_api import sync_playwright

ensure_headed_mode()
browser = sync_playwright().start().chromium.connect_over_cdp(
    f"http://127.0.0.1:{webdriver_port}"
)

连接失败 → 立即结束，禁止换系统浏览器替代。

设备安全检测

找 URL 含 check.html 的标签页，15s 内轮询，满足以下任一条件即视为检测通过：

1. 「打开店铺」按钮未禁用（.openMallOpenBtn，且非 disabled / aria-disabled=true / is-disabled）
2. 标签页数量 ≥ 2（通常表示店铺页已打开）

15s 内仍不满足 → 告知「没检测成功无法进行自动化」，立即结束。

可运行 Skill 内置（仅阶段 B）：

python scripts/check_device_security.py --port {webdriver_port} --wait --timeout 15

业务自动化

检测通过后，按客户需求用 Playwright 操作页面。禁止在 Skill 目录新增业务脚本；临时逻辑在对话中执行，不落盘为 .py。

收尾（阶段 A · HTTP）

关闭店铺（客户明确要求时）：

{"action": "CloseBrowser", "module": "WebDriverModule", "browserId": "{mall_id}"}

成功后从 opening_malls.json 去掉该 mall_name。

退出站斧客户端（仅客户明确要求「退出站斧」时；开/关店铺不要顺带调用）：

{"action": "ExitClient", "module": "WebDriverModule", "args": ""}

成功后（或冷启动重启前）清空 opening_malls.json。

失败处理（统一）

禁止：重试、翻代码、写备用脚本、写「稍后重跑」方案；禁止用 LoadSuccess 判断站斧是否已打开。

参考脚本（仅供本地调试，Agent 获取端口前勿运行）

• scripts/zhanfu_playwright.py — 全流程参考实现
• scripts/check_device_security.py — 阶段 B 设备检测
• scripts/headed_mode.py — 强制有界面

API 详情（含通用约定与全部接口）：reference.md