feat(skills): migrate browser workflows to flocks browser

.flocks/plugins/skills/browser-use/references/cdp-setup.md

@@ -0,0 +1,16 @@
+# Flocks browser setup
+
+浏览器已运行，但 daemon 或 active browser connection 不可用
+
+必须直接提示用户：
+
+```text
+browser: not connected — 请确保 Chrome / Chromium / Edge 已打开，然后访问对应浏览器的 inspect 页面（例如 chrome://inspect/#remote-debugging 或 edge://inspect/#remote-debugging）并勾选 Allow remote debugging
+```
+
+然后等待用户进一步指示，不要直接操作。
+
+当用户确认已开启remote-debugging后:
+1. 执行 `flocks browser --setup` 触发交互式 attach，不要用短超时包装该命令
+2. 再运行 `flocks browser --doctor` 做只读确认。
+3. 如果还失败，先执行 `flocks browser --reload` 清理旧 daemon，再重新执行 `flocks browser --setup`，避免因为残留 daemon 造成干扰。

.flocks/plugins/skills/onesec-use/references/onesec-incident.md

@@ -10,12 +10,18 @@
 ## 方式一：威胁图 / 事件详情页
 
 ```bash
-agent-browser --headed open "https://<onesec-domain>/pcedr/threatincidents"
-agent-browser wait --load networkidle
-agent-browser snapshot -i
-agent-browser --headed open "https://<onesec-domain>/pcedr/threatincidents/incident?umid=<umid>&guid=<guid>"
-agent-browser wait --load networkidle
-agent-browser get text body
+flocks browser -c '
+list_tid = new_tab("https://<onesec-domain>/pcedr/threatincidents", activate=True)
+wait_for_load()
+print(list_tid)
+detail_tid = new_tab(
+  "https://<onesec-domain>/pcedr/threatincidents/incident?umid=<umid>&guid=<guid>",
+  activate=True,
+)
+wait_for_load()
+print(detail_tid)
+print(js("document.body.innerText.slice(0, 2500)"))
+'
 ```
 
 详情页 URL 形式：
@@ -27,15 +33,21 @@ agent-browser get text body
 优先用 `tbody tr`，不行再用 `data-row-key`：
 
 ```bash
-agent-browser eval "document.querySelectorAll('tbody tr')[0]?.click()"
-agent-browser wait 500
-agent-browser get text body
+flocks browser -c '
+attach_tab("<TARGET_ID>")
+js("document.querySelectorAll(\"tbody tr\")[0]?.click()")
+wait(0.8)
+print(js("document.body.innerText.slice(0, 2000)"))
+'
 ```
 
 ```bash
-agent-browser eval "document.querySelector('[data-row-key=\"table0\"]')?.click()"
-agent-browser wait 500
-agent-browser get text body
+flocks browser -c '
+attach_tab("<TARGET_ID>")
+js("document.querySelector(\"[data-row-key=\\\"table0\\\"]\")?.click()")
+wait(0.8)
+print(js("document.body.innerText.slice(0, 2000)"))
+'
 ```
 
 > 事件概览只适合看摘要；需要完整攻击链时，优先用详情页。

.flocks/plugins/skills/onesig-use/references/browser-workflow.md

@@ -10,6 +10,8 @@
 如果走 API 能完成，请回到 [api-reference.md](api-reference.md) —— 浏览器操作不稳定、不可批量、字段不一定完整。
 
 > ⚠️ OneSIG 的 Web 控制台与 OneSEC、青藤是不同产品；不要把 OneSEC / 青藤的页面路径或 API 套用到 OneSIG。
+> 本文档统一按 `browser-use` 的 `cdp-direct` 流程执行：先 `flocks browser --doctor`，doctor 通过后只使用 `flocks browser`。
+> 对后台任务 / 定时任务，或系统不支持可视化，使用 `browser-use` 的 `cdp-headless` 模式。
 
 ## 零、登录认证
 
@@ -18,8 +20,31 @@ State 文件路径：`~/.flocks/browser/onesig/auth-state.json`（固定，全
 ### 首次登录 / Session 过期重新登录
 
 ```bash
-agent-browser close
-agent-browser --headed open "https://<onesig-domain>/login"
+flocks browser --doctor
+```
+
+如果 `flocks browser --doctor` 提示浏览器已运行，但 daemon 或 active browser connection 不可用，必须直接提示用户：
+
+```text
+browser: not connected — 请确保 Chrome / Chromium / Edge 已打开，然后访问对应浏览器的 inspect 页面（例如 chrome://inspect/#remote-debugging 或 edge://inspect/#remote-debugging）并勾选 Allow remote debugging
+```
+
+然后等待用户进一步指示，不要直接操作。
+
+当用户确认已开启 remote debugging 后：
+
+1. 执行 `flocks browser --setup` 触发交互式 attach，不要用短超时包装该命令。
+2. 再运行 `flocks browser --doctor` 做只读确认。
+3. 如果还失败，先执行 `flocks browser --reload` 清理旧 daemon，再重新执行 `flocks browser --setup`，避免因为残留 daemon 造成干扰。
+4. 只有随后 `--doctor` 通过后，才继续后面的登录或页面操作。
+
+```bash
+flocks browser -c '
+tid = new_tab("https://<onesig-domain>/login", activate=True)
+wait_for_load()
+print(tid)
+print(page_info())
+'
 ```
 
 OneSIG 多数部署启用了图形验证码 + TOTP + 强制改密：
@@ -31,7 +56,7 @@ OneSIG 多数部署启用了图形验证码 + TOTP + 强制改密：
 等用户登录结束、收到通知后保存 state：
 
 ```bash
-agent-browser state save ~/.flocks/browser/onesig/auth-state.json
+flocks browser state save ~/.flocks/browser/onesig/auth-state.json
 ```
 
 ### Session 失效恢复
@@ -45,22 +70,19 @@ agent-browser state save ~/.flocks/browser/onesig/auth-state.json
 恢复步骤（最多尝试 1 次）：
 
 ```bash
-# 1) close 并重新加载 state
-agent-browser close
-agent-browser state load ~/.flocks/browser/onesig/auth-state.json
-
-# 2) 打开受保护页面验证 session
-agent-browser open "https://<onesig-domain>/monitoring/dashboard"
-agent-browser wait --load networkidle
-
-# 3) 根据结果决策
-URL=$(agent-browser get url)
-if [[ "$URL" == *"/login"* ]]; then
-  echo "Session 仍无效，需重新登录"
-else
-  agent-browser state save ~/.flocks/browser/onesig/auth-state.json
-  echo "Session 已恢复，可重试页面操作"
-fi
+# 1) 重新加载 state，并直接带目标 URL 验证
+flocks browser state load ~/.flocks/browser/onesig/auth-state.json --url "https://<onesig-domain>/monitoring/dashboard"
+
+# 2) 读取当前页面状态
+flocks browser -c '
+print(page_info())
+'
+```
+
+如果输出 URL 仍然落回登录页，再要求用户重新登录；否则重新保存一次 state 并继续：
+
+```bash
+flocks browser state save ~/.flocks/browser/onesig/auth-state.json
 ```
 
 如果仍然落回登录页，再要求用户重新登录，**不要无限循环重试**。
@@ -71,9 +93,12 @@ fi
 > 进入页面首选直接拼接 URL（比菜单点击更稳定）。
 
 ```bash
-agent-browser open "https://<onesig-domain>/<path>"
-agent-browser wait --load networkidle
-agent-browser get text body
+flocks browser -c '
+tid = new_tab("https://<onesig-domain>/<path>", activate=True)
+wait_for_load()
+print(page_info())
+print(js("document.body.innerText.slice(0, 2000)"))
+'
 ```
 
 | 模块 | 子功能 | URL 路径 | 主要用途 |
@@ -150,14 +175,18 @@ agent-browser get text body
 
 ## 四、文件下载与导出
 
-OneSIG 控制台的导出按钮（资产 / 黑白名单 / 报表 / 审计 / coredump / pcap）多数会触发浏览器下载。在 `agent-browser` 模式下：
+OneSIG 控制台的导出按钮（资产 / 黑白名单 / 报表 / 审计 / coredump / pcap）多数会触发浏览器下载。优先顺序如下：
+
+1. **优先用 API 的导出 / 下载 action**（参见 [api-reference.md](api-reference.md) "文件类返回 / 上传"小节）。
+2. 如果必须走页面下载，先用 `js(...)` 或稳定 selector 触发下载，再用浏览器系统的下载目录或页面提示确认下载已开始；不要在 skill 里承诺不存在的“等待下载完成”专有命令。
+
+页面下载最小模板：
 
 ```bash
-# 触发下载
-agent-browser click "<导出 / 下载 按钮的 selector>"
-# 等下载完成 —— OneSIG 服务端通常 < 30s
-agent-browser wait --download
-agent-browser download list
+flocks browser -c '
+attach_tab("<TARGET_ID>")
+js("document.querySelector(\"<导出按钮选择器>\")?.click()")
+wait(1.0)
+print(page_info())
+'
 ```
-
-建议优先用 API 的导出 / 下载 action（参见 [api-reference.md](api-reference.md) "文件类返回 / 上传"小节）。

.flocks/plugins/skills/qingteng-use/references/browser-workflow.md

@@ -1,19 +1,105 @@
-
 # 青藤安全平台浏览器自动化
 
-### 浏览器最小操作模板
+> 本文档统一按 `browser-use` 的 `cdp-direct` 流程执行。进入浏览器模式后，优先使用 `flocks browser --doctor` 检查环境；doctor 通过后只使用 `flocks browser`，不要再切回旧的浏览器命令。
+> 对后台任务 / 定时任务，或系统不支持可视化，使用 `browser-use` 的 `cdp-headless` 模式。
+
+## 零、登录认证
+
+State 文件路径：`~/.flocks/browser/qingteng/auth-state.json`（固定，全局唯一）。
+
+### 首次登录 / Session 过期重新登录
+
+先确保本机可复用 Chromium 系浏览器：
+
+```bash
+flocks browser --doctor
+```
+
+如果 `flocks browser --doctor` 提示浏览器已运行，但 daemon 或 active browser connection 不可用，必须直接提示用户：
+
+```text
+browser: not connected — 请确保 Chrome / Chromium / Edge 已打开，然后访问对应浏览器的 inspect 页面（例如 chrome://inspect/#remote-debugging 或 edge://inspect/#remote-debugging）并勾选 Allow remote debugging
+```
+
+然后等待用户进一步指示，不要直接操作。
+
+当用户确认已开启 remote debugging 后：
+
+1. 执行 `flocks browser --setup` 触发交互式 attach，不要用短超时包装该命令。
+2. 再运行 `flocks browser --doctor` 做只读确认。
+3. 如果还失败，先执行 `flocks browser --reload` 清理旧 daemon，再重新执行 `flocks browser --setup`，避免因为残留 daemon 造成干扰。
+4. 只有随后 `--doctor` 通过后，才继续后面的登录或页面操作。
+
+打开登录页并等待用户手动完成登录：
+
+```bash
+flocks browser -c '
+tid = new_tab("https://<domain>/login", activate=True)
+wait_for_load()
+print(tid)
+print(page_info())
+'
+```
+
+用户登录完成后，立即保存状态：
+
+```bash
+flocks browser state save ~/.flocks/browser/qingteng/auth-state.json
+```
+
+### CLI 或页面认证失败时的恢复流程
+
+当出现以下任一情况，优先判定为认证问题：
+
+- 返回 HTTP `401` / `403`
+- 返回内容包含 `Unauthorized`、`login`、未登录、认证失败
+- `auth-state.json` 存在，但 CLI 请求或页面访问仍失败
+
+恢复步骤（最多尝试 1 次）：
+
 ```bash
-agent-browser open "https://<domain>/<path>"
-agent-browser wait --load networkidle
-agent-browser snapshot -i
+# 1) 重新加载 state，并直接带目标 URL 做验证
+flocks browser state load ~/.flocks/browser/qingteng/auth-state.json --url "https://<domain>/"
+
+# 2) 读取当前页面状态
+flocks browser -c '
+print(page_info())
+'
 ```
 
-更多使用方法参考： agent-browser skill
+如果输出 URL 仍然落回登录页，再要求用户重新登录；不要无限循环重试。
+
+## 浏览器最小操作模板
+
+```bash
+flocks browser -c '
+tid = new_tab("https://<domain>/<path>", activate=True)
+wait_for_load()
+print(page_info())
+print(js("document.body.innerText.slice(0, 2000)"))
+'
+```
+
+后续继续使用同一个 tab 时，优先先 attach 再操作：
+
+```bash
+flocks browser -c '
+attach_tab("<TARGET_ID>")
+print(page_info())
+'
+```
+
+## 页面操作原则
+
+- 能直接拼 URL 时，优先直接拼 URL，不走左侧菜单点击。
+- 先用 `page_info()` 和 `js(...)` 读取页面状态，再执行点击、输入或滚动。
+- 需要点击自定义组件时，优先用 `js(...)` 定位 DOM 后直接点击；只有 DOM 很难稳定定位时，才退到 `click_at_xy(...)`。
+- 页面变化后，之前读取到的文本、DOM 状态和坐标都可能失效；必须重新 `page_info()` 或重新跑 `js(...)`。
 
 ## 重要提醒
 
 - **Session 管理**：详见[零、登录认证](#零登录认证)。任务开始前先确认 `auth-state.json` 存在；CLI 认证失败时先走恢复流程，不要立刻要求用户重新登录。
 - **禁止连续失败循环**：同一命令最多重试 2 次；认证恢复流程只走一次，仍失败则提示用户手动重新登录。
   - **以下错误属于需要用户干预的基础设施问题，立即停止所有重试，直接告知用户处理**：
-    - `ERR_CERT_AUTHORITY_INVALID`：站点证书不被本机信任，使用 `--ignore-https-errors` 或请求用户处理。
+    - `ERR_CERT_AUTHORITY_INVALID`：站点证书不被本机信任，请求用户处理。
     - `ERR_NAME_NOT_RESOLVED`：域名无法解析，告知用户确认域名或检查 DNS / hosts 配置。