browser-control

name	browser_control
description	使用 PageAgent 强化能力控制浏览器，获取带有交互索引的 DOM 树，并执行精确点击和输入操作。
author	VibeWorker
version	1.0.0

🌐 浏览器强化控制技能 (Browser Control)

该技能使你能够深入理解浏览器中加载的网页，获取结构化的 DOM 树，并进行精确的交互。 如果你需要控制网页并点击特定元素，请始终优先使用此技能，而不是普通的 fetch_url。

💡 使用场景

• 你需要在一个网页表单中输入多个字段。
• 你需要点击一个特定的按钮或链接。
• 你需要抓取一个动态生成的，或者需要登录才能查看的网页内容。

🛠️ 如何使用

要在浏览器中执行操作，你需要向 VibeWorker 的扩展系统发送特定的指令。 你必须使用 python_repl 运行 Python 代码来与扩展通信。

1. 确保目标页面已打开

你可以使用已有的通过请求发向后端触发扩展的能力，但如果需要交互，请直接使用下面的第 2 步和第 3 步代码。 如果目标标签页已经存在，你可以尝试找到它的 tabId。为了方便，我们通常会在需要交互时打开一个新标签页并记住它的 id。

import requests
import json
import time

# 辅助函数：向扩展发送指令
def send_extension_action(action, payload):
    try:
        response = requests.post("http://localhost:8088/api/extension/action", json={
            "action": action,
            "payload": payload
        })
        return response.json()
    except Exception as e:
        return f"Error connecting to extension api: {str(e)}"

2. 获取当前的页面交互树 (Flat DOM Tree)

向扩展发送 PAGE_AGENT_EXTRACT 指令。 你需要提供目标网页所在的 tabId。

# 假设 tab_id 是已知的一个标签页 ID (比如 123)
tab_id = 123 
result = send_extension_action("PAGE_AGENT_EXTRACT", { "tabId": tab_id })
print(json.dumps(result, indent=2, ensure_ascii=False))

仔细分析返回的 FlatDomTree（它通常是一个简化的 HTML 字符串，每个可交互元素带有一个独特的自定义属性，例如 data-page-agent-index="45"）。 找到你需要交互的元素的索引号（index）。

3. 执行交互 (Click / Input)

根据上一步获取的 index，向扩展发送 PAGE_AGENT_ACTION 指令。

点击操作：

# 假设你要点击 index 为 45 的元素
result = send_extension_action("PAGE_AGENT_ACTION", {
    "tabId": tab_id,
    "domAction": "click",
    "index": 45
})
print("Result:", result)

输入文本操作：

# 假设你要在 index 为 12 的输入框中输入 "Hello VibeWorker"
result = send_extension_action("PAGE_AGENT_ACTION", {
    "tabId": tab_id,
    "domAction": "input",
    "index": 12,
    "text": "Hello VibeWorker"
})
print("Result:", result)

向下滚动：

result = send_extension_action("PAGE_AGENT_ACTION", {
    "tabId": tab_id,
    "domAction": "scroll",
    "text": json.dumps({"down": True, "numPages": 1})
})
print("Result:", result)

⚠️ 注意事项

1. 在发送动作前，务必先获取一次 DOM Tree，以确保你使用的 Index 是最新的。页面变化可能导致 Index 改变。
2. 不要在操作之间手动添加 time.sleep() 或 timeout 等待。扩展内部已经内置了必要的渲染等待时间，你可以立刻执行下一步操作。
3. 这些指令依赖于用户的浏览器中安装了 VibeWorker 扩展，并且启用了与后端的连接。