Smooth Browser

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

前置条件

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

pip install smooth-py

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

smooth config --api-key 

验证当前配置：

smooth config --show

在 https://app.smooth.sh 获取 API 密钥

若账户余额不足，请提示用户前往 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 --  "搜索‘无线耳机’，筛选评分 ≥4 星的商品，按价格排序，并提取前 3 条结果" 
  --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 个个人资料页面 URL"
• "查找 iPhone 17 在 Amazon 上的售价"

不佳的任务示例：

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

重要提示：Smooth 由智能 Agent 驱动，请勿过度控制其行为，应为其提供目标明确、结果导向的任务，而非操作步骤。

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、页面内容），但不保留浏览器 Agent 的内存。如需在任务间传递信息，请显式地将其作为上下文写入 prompt 中。

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

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

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

注意事项：

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

带结构化输出的网页抓取

方式一：使用 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 命令专为纯数据提取优化，不消耗 Agent 步数，效率更高。

它类似于一种“智能 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
• 当您需要 Agent 自动导航、交互或执行复杂操作后再提取数据时，请使用 run

文件处理

上传文件供会话使用：

文件须在启动会话前上传，再通过文件 ID 传入会话：

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

# 第二步：启动携带该文件的会话
smooth start-session --files "$FILE_ID" --url "https://example.com"

# 第三步：Agent 即可在任务中访问该文件
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：

# 简单 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 — 后续所有命令均需使用
2. 对需认证的会话使用 Profile — 记录各 Profile 对应的网站
3. 关闭会话后等待 5 秒 — 确保状态已正确持久化
4. 使用具描述性的 Profile ID — 例如："linkedin-personal"、"twitter-company"
5. 任务完成后及时关闭会话 — 默认的优雅关闭（graceful close）可确保资源正确释放
6. 数据提取优先使用结构化输出 — 输出结果更规范、类型更明确
7. 依赖前序工作的任务应在同一会话中顺序执行 — 保持会话连续性
8. 对相互独立的任务，使用子 Agent 并各自分配独立会话 — 实现并行加速
9. 协调资源分配 — 使用子 Agent 时，您需主动创建并为每个子 Agent 分配唯一会话，禁止子 Agent 自行创建会话
10. 避免在 URL 中添加查询参数（如 ?filter=xyz） — 应从基础 URL 启动，交由 Agent 通过 UI 操作完成筛选
11. Smooth 由智能 Agent 驱动 — 请交付任务目标，而非具体操作步骤

故障排查

"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 格式输出。