opensteer

Opensteer

Opensteer 是一款全球浏览器控制运行时。它向 Agent 和 harness 包提供小型 CDP 原语。

用法

opensteer -c "open_browser(profile='fresh'); new_tab('https://example.com'); print(page_info())"

Python 代码片段运行时会预先导入辅助函数：

opensteer -c "new_tab('https://docs.opensteer.com'); wait_for_load(); print(page_info())"

对于 harness 代码，请从已安装的软件包中导入辅助函数：

from opensteer.helpers import goto_url, js, click_at_xy, type_text, wait_for_load

显式浏览器会话

进行浏览器操作时，请明确选择浏览器配置文件和复用模式。返回的句柄恰好绑定到一个平台会话，其稳定身份使浏览器可供后续 CLI 调用和后续 Agent 运行复用：

opensteer -c "browser = open_browser(label='research', profile='fresh'); browser.new_tab('https://example.com')"
opensteer -c "browser = open_browser(label='work', profileId='bp_...'); print(browser.page_info())"
opensteer -c "browser = open_browser(profileId='bp_...'); print(browser.page_info())"

仅当你有意让平台选择唯一获准的配置文件（或者在没有授权配置文件时选择未指定配置文件的浏览器），才使用 profile='auto'。 mode='reuse' 是默认值。它会为此 Agent、位置和配置文件选择稳定的主浏览器。label 是可选的可变显示元数据：指定不同的标签会在 UI 中重命名同一浏览器；省略该参数则保留当前标签。它绝不会选择或创建其他浏览器。只有在有意使用另一个独立逻辑浏览器时，才使用 mode='new'。

profile='fresh' 表示不附加已保存的配置文件。它不保证浏览器是全新的、干净的或已退出登录，因为 mode='reuse' 可能会返回之前使用过的未指定配置文件的浏览器，包括之前运行中使用的浏览器。需要独立的干净状态时，请使用 profile='fresh', mode='new'。

读取辅助函数不会创建云端浏览器。如果没有活动浏览器，请先调用 open_browser(...)。

列出并明确选择正在运行的浏览器，不创建新浏览器：

opensteer -c "print(list_browsers())"
opensteer -c "browser = use_browser('linkedin'); print(browser.page_info())"

list_browsers() 只读。use_browser(...) 接受唯一标签或列表返回的确切 sessionId。

浏览器的生命周期会超出单次 Agent 命令或运行。正常的进程或运行关闭只会断开控制中继。仅当需要销毁浏览器本身时，才调用 browser.close()（或相应的关闭 API）。

浏览器传输方式独立于 Agent 的执行位置。需要本地执行的 Agent 使用隔离的云端浏览器时，请使用 location='cloud'；需要使用桌面应用内嵌浏览器时，请使用 location='inapp'；需要使用独立的机器 Chromium 窗口时，请使用 location='local'。常规自动路由时，请省略此参数（或使用 location='auto'）。云端执行仅支持 auto 和 cloud，不接受仅限设备的位置：

opensteer -c "open_browser(label='research', profile='fresh', location='cloud')"

浏览器配置文件

浏览器配置文件是已保存并登录的浏览器身份（Cookie、身份验证状态），云浏览器可以使用它启动。配置文件访问权限通过授权授予：服务器会跟踪此 Agent 可以使用哪些配置文件，并且不会为每个 Agent 设置默认配置文件。

• list_cloud_profiles() 会列出可见的配置文件；每个条目都带有 granted 标记，说明此 Agent 是否可以使用该配置文件。
• open_browser(label=name, profile='auto') 会让服务器解析配置文件：恰好有一个已授权的配置文件时会自动附加；没有已授权的配置文件时会启动一个未关联配置文件的会话；有多个已授权的配置文件时则会报错，提示你传入 profileName 或 profileId。
• 有多个配置文件获授权时，请明确选择一个：open_browser(label='linkedin', profileName='LinkedIn work') 或 open_browser(label='linkedin', profileId='bp_...')。需要长期使用的脚本应固定使用 profileId，因为它在配置文件重命名后仍然有效。
• 传入未授权给此 Agent 的配置文件时会失败，并返回 403 错误；错误消息会说明后续操作（列出已授权的配置文件或申请访问权限）。
• 已授权的配置文件可搭配 location='inapp' 或 location='cloud' 使用。如果提供方无法满足请求的配置文件或位置要求，则会失败，且两者都不会改变。

平台配置文件工具会将访问申请与保存当前状态分开处理：

• request_browser_profile 会请用户选择现有配置文件或授予其访问权限。如果已授权的配置文件处于登出状态，请打开该确切的配置文件，让用户接管并登录，然后继续。此处没有修复模式；浏览器正常关闭时的持久化操作会保存更新后的登录状态。
• request_save_browser_profile 会保存已打开但未关联配置文件的浏览器。只有在未来可能需要再次使用时才提供此选项；切勿自动保存，也不要在用户拒绝后继续询问。用户直接要求保存即表示已批准；否则，请先通过 request_user_input 获得明确批准。保留 open_browser(...) 返回的句柄（或通过 use_browser(...) 找回），并传入其中准确的 browser.browser_ref；绝不能传入其标签，也不能猜测当前浏览器。专用 Agent 不传入 cloudAgentId，并由其自身获得授权。Chat 可以指定目标专用 Agent，也可以省略目标以保存为未分配状态；Chat 自身永远不会获得授权。持久保存的内容是某一时刻基于 Cookie 的身份验证快照，不会关闭或重新绑定源浏览器，也不会持续同步。

交互技能

通用浏览器操作机制位于 interaction-skills/ 中：

• connection.md
• cookies.md
• cross-origin-iframes.md
• dialogs.md
• downloads.md
• drag-and-drop.md
• dropdowns.md
• iframes.md
• network-requests.md
• print-as-pdf.md
• screenshots.md
• scrolling.md
• shadow-dom.md
• tabs.md
• uploads.md
• viewport.md

页面操作机制较复杂时请使用这些技能。领域专用的选择器、工作流、API、本地数据库和任务工具应放在 harness pack 中。

适用场景

• 查看可见状态时，先截取屏幕截图：capture_screenshot()。
• 对可见目标，优先使用坐标点击：click_at_xy(x, y)。
• 使用 js(...) 检查和提取 DOM，并发现页面 API。
• 对辅助工具未涵盖的原始 CDP 操作，使用 cdp("Domain.method", ...)。
• 页面导航后，调用 wait_for_load()。
• 默认导航到当前由 Opensteer 管理的标签页；只有用户明确要求使用某个特定的现有标签页时，才使用 list_tabs() 和 switch_tab(target_id)。
• 如果页面重定向到登录页，请停止并询问用户。不要根据屏幕截图输入凭据。

职责边界

Opensteer 负责通用浏览器基础功能、本地连接、远程连接、云浏览器连接以及通用交互技能。

Harness pack 负责领域专用工具、选择器、工作流、存储、设置文档和 Agent 技能。