Smooth Browser

Smooth CLI 是一款专为 AI 智能体设计的浏览器工具，支持与网站交互、身份认证、数据抓取，以及通过自然语言执行复杂的网页端任务。

前置条件

假设 Smooth CLI 已安装。若尚未安装，可通过以下命令安装：

pip install smooth-py

假设 API 密钥已配置完成。如遇认证错误，请使用以下命令配置：

smooth config --api-key 

验证当前配置：

smooth config --show

API 密钥获取地址：https://app.smooth.sh

若账户余额不足，请提示用户前往 https://app.smooth.sh 升级订阅计划。

基础工作流

1. 创建 Profile（可选）

Profile 可用于在多次会话间持久化 Cookie、登录态及浏览器状态。

smooth create-profile --profile-id "my-profile"

列出已有 Profile：

smooth list-profiles

2. 启动浏览器会话

smooth start-session --profile-id "my-profile" --url "https://example.com"

选项说明：

• --profile-id —— 指定使用的 Profile（可选；未提供时将创建匿名会话）
• --url —— 初始跳转 URL（可选）
• --files —— 以逗号分隔的文件 ID 列表，用于在会话中挂载对应文件（可选）
• --device mobile|desktop —— 设备类型（默认为 mobile）
• --profile-read-only —— 仅加载 Profile，不保存任何更改
• --allowed-urls —— 以逗号分隔的 URL 模式列表，用于限制会话仅可访问指定域名（例如："https://*.example.com/,https://*.api.example.com/"）
• --no-proxy —— 禁用默认代理（详见下方说明）

重要提示：请务必保存命令输出中的会话 ID（session ID），后续所有操作均需该 ID。

代理行为说明：默认情况下，CLI 会自动为浏览器会话配置内置代理。若目标网站屏蔽该代理，或您需要直连网络，请使用 --no-proxy 参数禁用代理。

3. 在会话中执行任务

使用自然语言描述任务：

smooth run --  "访问 LocalLLM 子版块，并找出热度最高的 3 篇帖子"

带结构化输出的任务（适用于需交互的场景）：

smooth run --  "搜索‘wireless headphones’，筛选评分 ≥4 星的商品，按价格排序，并提取排名前三的结果" 
  --url "https://shop.example.com" 
  --response-model '{"type":"array","items":{"type":"object","properties":{"product":{"type":"string","description":"Thenameoftheproductbeingdescribed."},"sentiment":{"type":"string","enum":["positive","negative","neutral"],"description":"The overall sentiment about the product."}},"required":["product","sentiment"]}}'

携带元数据的任务（智能体将获得如下上下文）：

smooth run --  "使用用户信息填写表单" 
  --metadata '{"email":"user@example.com","name":"John Doe"}'

选项说明：

• --url —— 执行任务前先跳转至该 URL
• --metadata —— 提供 JSON 格式的变量对象，作为任务上下文
• --response-model —— 定义结构化输出所需的 JSON Schema
• --max-steps —— 智能体最大执行步数（默认值：32）
• --json —— 以 JSON 格式输出结果

注意事项：
请确保任务描述处于恰当的抽象层级：既不能过于具体（例如仅描述单步操作），也不能过于宽泛或模糊。

良好的任务示例：

• "在 LinkedIn 上搜索在 Amazon 任职的软件开发工程师（SDE），返回 5 个个人主页链接"
• "查找 iPhone 17 在 Amazon 上的售价"

不良的任务示例：

• "点击搜索按钮" → 过于具体！
• "打开 google.com，输入‘restaurants near me’，点击搜索，等待页面加载完成，提取前 5 条结果并返回" → 过于具体！应简化为："在 Google 上搜索‘restaurants near me’并返回前 5 条结果"
• "寻找适合我们公司的软件工程师" → 过于宽泛！您需自行规划达成目标的具体路径，并拆解为若干定义清晰、可执行的子任务

重要提示：Smooth 由智能代理驱动，请勿过度控制其行为；应提供目标明确、面向结果的任务，而非逐条操作指令。

4. 关闭会话

任务完成后必须显式关闭会话。

smooth close-session -- 

重要提示：关闭会话后请等待 5 秒，以确保 Cookie 和浏览器状态已完整写入 Profile（如需在后续会话中复用）。

常见使用场景

身份认证与持久化会话

为特定网站创建 Profile：

# 创建 Profile
smooth create-profile --profile-id "github-account"

# 启动会话
smooth start-session --profile-id "github-account" --url "https://github.com/login"

# 获取实时视图以便手动认证
smooth live-view -- 
# 将生成的 URL 提供给用户，由其在浏览器中打开并完成登录

# 用户确认登录成功后，关闭会话以保存 Profile 数据
smooth close-session -- 
# 将 profile-id 记录下来，以便后续复用

复用已认证的 Profile：

# 下次只需使用同一 Profile 启动会话
smooth start-session --profile-id "github-account"
smooth run --  "在我的仓库 ‘my-project’ 中新建一个 Issue"

保持 Profile 组织有序：建议记录各 Profile 对应的服务站点，便于未来高效复用。

在同一浏览器中顺序执行多个任务

无需关闭会话即可连续执行多项任务：

SESSION_ID=$(smooth start-session --profile-id "my-profile" --json | jq -r .session_id)

# 任务 1：登录
smooth run $SESSION_ID "使用提供的凭据登录网站"

# 任务 2：首次操作
smooth run $SESSION_ID "进入设置页，将通知偏好更改为仅邮件通知"

# 任务 3：二次操作
smooth run $SESSION_ID "进入账单页面，提供最新发票的 URL"

smooth close-session $SESSION_ID

重要提示： run 命令会保留浏览器状态（Cookie、当前 URL、页面内容），但不会保留浏览器智能体自身的记忆。如需在任务间传递信息，请在 prompt 中显式传入。

示例 —— 在任务间传递上下文：

# 任务 1：获取信息
RESULT=$(smooth run $SESSION_ID "提取当前页面上的商品名称" --json | jq -r .output)

# 任务 2：复用任务 1 的结果
smooth run $SESSION_ID "考虑商品名称为 ‘$RESULT’ 的产品。现在查找该在线商店提供的另外 3 款相似商品。"

注意事项：

• run 命令是阻塞式执行。如需并行执行多个任务，必须使用子智能体（Task 工具）。
• 所有任务均运行于当前标签页，不支持指定在新标签页中执行任务。如需保留当前标签页状态，可另启一个新会话。
• 每个会话一次只能运行一个任务。如需并行执行任务，请为每个子智能体单独分配一个会话。
• 并发会话数量上限取决于用户的订阅计划。
• 如有必要，可提醒用户升级订阅计划以获取更多并发会话配额。

结构化网页抓取

方案一：使用 run 命令配合结构化输出：

smooth start-session --url "https://news.ycombinator.com"
smooth run --  "提取热度最高的 10 篇帖子" 
  --response-model '{
    "type": "object",
    "properties": {
      "posts": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "title": {"type": "string"},
            "url": {"type": "string"},
            "points": {"type": "number"}
          }
        }
      }
    }
  }'

方案二：使用 extract 命令进行直接数据提取：

extract 命令专为纯数据提取场景优化，不依赖智能体步骤，效率更高。

它类似于一种“智能 fetch”，可从动态渲染的网页中提取结构化数据：

smooth start-session
smooth extract --  
  --url "https://news.ycombinator.com" 
  --schema '{
    "type": "object",
    "properties": {
      "posts": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "title": {"type": "string"},
            "url": {"type": "string"},
            "points": {"type": "number"}
          }
        }
      }
    }
  }' 
  --prompt "提取热度最高的 10 篇帖子"

适用场景建议：

• 当您已位于目标页面，或已知准确 URL，且仅需提取结构化数据时，请使用 extract；
• 当您需要智能体完成导航、交互或复杂前置操作后再提取数据时，请使用 run。

文件处理

上传文件供会话使用：

文件须在启动会话前完成上传，并通过文件 ID 挂载至会话中：

# 步骤 1：上传文件
FILE_ID=$(smooth upload-file /path/to/document.pdf --purpose "Contract to analyze" --json | jq -r .file_id)

# 步骤 2：启动挂载该文件的会话
smooth start-session --files "$FILE_ID" --url "https://example.com"

# 步骤 3：智能体可在任务中访问该文件
smooth run --  "分析合同文档并提取关键条款"

上传多个文件：

# 上传文件
FILE_ID_1=$(smooth upload-file /path/to/invoice.pdf --json | jq -r .file_id)
FILE_ID_2=$(smooth upload-file /path/to/screenshot.png --json | jq -r .file_id)

# 启动挂载多个文件的会话
smooth start-session --files "$FILE_ID_1,$FILE_ID_2"

从会话中下载文件：

smooth run --  "下载月度报告 PDF" --url
smooth close-session -- 

# 会话关闭后，获取下载链接
smooth downloads -- 
# 访问返回的 URL 即可下载文件

实时视图与人工干预

当自动化流程需要人工介入（如 CAPTCHA、双因素认证、复杂登录流程）时：

smooth start-session --profile-id "my-profile"
smooth run --  "访问 secure-site.com 并登录"

# 若任务遇到 CAPTCHA 或其他需人工操作的情形：
smooth live-view -- 
# 打开返回的 URL，在浏览器中完成人工操作

# 人工干预完成后继续自动化流程：
smooth run --  "现在跳转至仪表板并导出数据"

直接浏览器操作

从当前页面提取数据：

smooth start-session --url "https://example.com/products"
smooth extract --  
  --schema '{"type":"object","properties":{"products":{"type":"array"}}}' 
  --prompt "提取全部商品名称与价格"

跳转至指定 URL 后再提取：

smooth extract --  
  --url "https://example.com/products" 
  --schema '{"type":"object","properties":{"products":{"type":"array"}}}'

在浏览器中执行 JavaScript：

# 简单脚本
smooth evaluate-js --  "document.title"

# 带参数调用
smooth evaluate-js --  "(args) => {return args.x + args.y;}" --args '{"x": 5, "y": 10}'

# 复杂 DOM 操作
smooth evaluate-js --  
  "document.querySelectorAll('a').length"

Profile 管理

列出全部 Profile：

smooth list-profiles

删除某个 Profile：

smooth delete-profile 

推荐使用 Profile 的场景：

• ✅ 需要身份认证的网站
• ✅ 多次任务执行间需维持会话状态
• ✅ 避免重复登录
• ✅ 持久化 Cookie 与本地存储数据

可跳过 Profile 的场景：

• 无需认证的公开网站
• 一次性网页抓取任务
• 测试类场景

文件管理

上传文件：

smooth upload-file /path/to/file.pdf --name "document.pdf" --purpose "Contract for review"

删除文件：

smooth delete-file 

最佳实践

1. 始终保存会话 ID —— 后续所有命令均需使用该 ID
2. 对需认证的会话使用 Profile —— 记录各 Profile 对应的网站，便于复用
3. 关闭会话后等待 5 秒 —— 确保状态已正确写入 Profile
4. 使用具描述性的 Profile ID —— 例如："linkedin-personal"、"twitter-company"
5. 任务完成后及时关闭会话 —— 使用默认的优雅关闭方式，确保资源清理到位
6. 数据提取时启用结构化输出 —— 输出格式规范、类型明确
7. 关联性强的任务应在同一会话中顺序执行 —— 避免因状态丢失导致中断
8. 独立任务请使用子智能体，每子智能体分配一个会话 —— 实现并行加速
9. 协调资源分配 —— 使用子智能体时，必须由主智能体统一创建并分配会话，禁止子智能体自行创建
10. URL 中避免添加查询参数（例如不要使用 ?filter=xyz） —— 应从基础 URL 启动，交由智能体通过 UI 交互完成筛选等操作
11. Smooth 由智能代理驱动 —— 请提供目标导向的任务，而非细粒度的操作步骤

故障排查

"Session not found"（会话未找到） —— 会话可能已超时或被主动关闭，请新建会话。

"Profile not found"（Profile 未找到） —— 运行 smooth list-profiles 查看可用 Profile 列表。

CAPTCHA 或认证问题 —— 使用 smooth live-view -- 启动实时视图，交由用户手动干预。

任务超时 —— 可尝试增大 --max-steps 参数值，或将大任务拆分为多个小任务逐步执行。

命令参考

Profile 相关命令

• smooth create-profile [--profile-id ID] —— 创建新 Profile
• smooth list-profiles —— 列出全部 Profile
• smooth delete-profile —— 删除指定 Profile

文件相关命令

• smooth upload-file [--name NAME] [--purpose PURPOSE] —— 上传文件
• smooth delete-file —— 删除已上传的文件

会话相关命令

• smooth start-session [OPTIONS] —— 启动浏览器会话
• smooth close-session -- [--force] —— 关闭会话
• smooth run -- "" [OPTIONS] —— 执行任务
• smooth extract -- --schema SCHEMA [OPTIONS] —— 提取结构化数据
• smooth evaluate-js -- "code" [--args JSON] —— 执行 JavaScript
• smooth live-view -- —— 获取交互式实时访问 URL
• smooth recording-url -- —— 获取会话录制回放 URL
• smooth downloads -- —— 获取文件下载 URL

所有命令均支持 --json 参数以输出 JSON 格式结果。