smooth-browser

Smooth 浏览器

Smooth CLI 是一款浏览器，可让 AI Agent 使用自然语言与网站交互、进行身份验证、抓取数据并执行复杂的网页任务。

前置条件

假设 Smooth CLI 已安装。如果尚未安装，可运行以下命令进行安装：

pip install smooth-py

假设 API 密钥已配置。如果遇到身份验证错误，请使用以下命令进行配置：

smooth config --api-key <api-key>

验证配置：

smooth config --show

前往 https://app.smooth.sh 获取 API 密钥。

如果账户余额不足，请让用户前往 https://app.smooth.sh 升级套餐。

基本工作流

1. 创建配置文件（可选）

配置文件有助于在不同会话之间保留 Cookie、登录会话和浏览器状态。

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

列出现有配置文件：

smooth list-profiles

2. 启动浏览器会话

smooth start-session --profile-id "my-profile"

选项：

• --profile-id - 使用指定的配置文件（可选；如果未提供，则创建匿名会话）
• --files - 在会话中提供的文件 ID，以逗号分隔（可选）
• --device mobile|desktop - 设备类型（默认值：mobile）
• --profile-read-only - 加载配置文件，但不保存更改
• --allowed-urls - 以逗号分隔的 URL 模式，仅允许访问指定 URL（例如："https://example.com/,https://api.example.com/"）
• --no-proxy - 禁用默认代理（见下方说明）

重要提示： 保存输出中的会话 ID，后续所有命令都会用到它。

代理行为： 默认情况下，CLI 会自动为浏览器会话配置内置代理。如果某个网站屏蔽了代理，或者你需要直接连接，请使用 --no-proxy 将其禁用。

3. 在会话中运行任务

使用自然语言执行任务：

smooth run <session-id> "Go to the LocalLLM subreddit and find the top 3 posts"

使用结构化输出（适用于需要交互的任务）：

smooth run <session-id> "Search for 'wireless headphones', filter by 4+ stars, sort by price, and extract the top 3 results" \
  --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"]}}'

使用元数据（Agent 将会）：

smooth run <session-id> "Fill out the form with user information" \
  --metadata '{"email":"[email protected]","name":"John Doe"}'

选项：

• --url - 运行任务前先访问此 URL
• --metadata - 包含任务变量的 JSON 对象
• --response-model - 用于结构化输出的 JSON 架构
• --max-steps - Agent 的最大步骤数（默认值：32）
• --json - 以 JSON 格式输出结果

注意事项： 任务的抽象程度要恰当，这一点很重要。不要过于具体（例如指定单步操作），也不要过于宽泛或含糊。

好的任务示例：

• "在 Linkedin 上搜索在 Amazon 担任 SDE 的人员，并返回 5 个个人资料 URL"
• "查找 Amazon 上 iPhone 17 的价格"

不好的任务示例：

• "点击搜索" -> 过于具体！
• "加载 google.com，输入 'restaurants near me'，点击搜索，等待页面加载，提取排名前 5 的结果并返回。" -> 过于具体！可以说 "在 google 上搜索 restaurants near me 并返回排名前 5 的结果"
• "找出适合我们公司的软件工程师" -> 过于宽泛！你需要规划如何实现目标，并运行定义明确、组合后能够达成该目标的任务

重要：Smooth 由智能 Agent 驱动，不要过度控制它；应提供定义明确、以目标为导向的任务，而不是一连串步骤。

4. 关闭会话

完成后必须关闭会话。

smooth close-session <session-id>

重要提示： 关闭后等待 5 秒，以确保 Cookie 和状态已保存到配置文件中（如果你之后还要使用该配置文件）。

---

常见用例

身份验证和持久会话

为特定网站创建配置文件：

# Create profile
smooth create-profile --profile-id "github-account"

# Start session
smooth start-session --profile-id "github-account"

# Load url
smooth goto <session-id> "https://github.com/login"

# Get live view to authenticate manually
smooth live-view <session-id>
# Give the URL to the user so it can open it in the browser and log in

# When the user confirms the login you can then close the session to save the profile data
smooth close-session <session-id>
# Save the profile-id somewhere to later reuse it

复用已通过身份验证的配置文件：

# Next time, just start a session with the same profile
smooth start-session --profile-id "github-account"
smooth run <session-id> "Create a new issue in my repo 'my-project'"

整理配置文件： 将各配置文件对应的服务记录在记忆中，以便日后高效复用。

---

同一浏览器中的顺序任务

按顺序执行多个任务，而不关闭会话：

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

# Task 1: Login
smooth run $SESSION_ID "Log into the website with the given credentials"

# Task 2: First action
smooth run $SESSION_ID "Find the settings and change the notifications preferences to email only"

# Task 3: Second action
smooth run $SESSION_ID "Find the billing section and give me the url of the latest invoice"

smooth close-session $SESSION_ID

重要提示： run 会保留浏览器状态（Cookie、URL、页面内容），但不会保留浏览器 Agent 的记忆。如果需要将信息从一个任务传递到下一个任务，应在提示词中明确提供。

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

# Task 1: Get information
RESULT=$(smooth run $SESSION_ID "Find the product name on this page" --json | jq -r .output)

# Task 2: Use information from Task 1
smooth run $SESSION_ID "Consider the product with name '$RESULT'. Now find 3 similar products offered by this online store."

注意：

• run 命令会阻塞执行。如果需要同时执行多个任务，必须使用子 Agent（Task 工具）。
• 所有任务都会使用当前标签页，无法要求在新标签页中运行任务。如果需要保留当前标签页的状态，可以打开一个新会话。
• 每个会话一次只能运行一个任务。如需同时运行多个任务，请为每个子 Agent 使用一个会话。
• 并发会话的最大数量取决于用户套餐。
• 如有帮助，可以提醒用户升级套餐，以获得更多并发会话。

---

使用结构化输出进行网页抓取

选项 1：使用带结构化输出的 run：

smooth start-session
smooth run <session-id> "Extract the top 10 posts" \
  --url "https://news.ycombinator.com" \
  --response-model '{
    "type": "object",
    "properties": {
      "posts": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "title": {"type": "string"},
            "url": {"type": "string"},
            "points": {"type": "number"}
          }
        }
      }
    }
  }'

选项 2：使用 extract 直接提取数据：

对于纯数据提取，extract 命令效率更高，因为它不使用 Agent 步骤。

它类似于智能抓取，可以从动态渲染的网站中提取结构化数据：

smooth start-session
smooth extract <session-id> \
  --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 "Extract the top 10 posts"

何时使用各命令：

• 如果你已在正确页面，或知道正确的 URL，只需提取结构化数据，请使用 extract
• 如果需要 Agent 先进行导航、交互或执行复杂操作，再提取数据，请使用 run

---

处理文件

上传文件以在会话中使用：

必须先上传文件，再启动会话，然后通过文件 ID 将文件传递给会话：

# Step 1: Upload files
FILE_ID=$(smooth upload-file /path/to/document.pdf --purpose "Contract to analyze" --json | jq -r .file_id)

# Step 2: Start session with the file
smooth start-session --files "$FILE_ID"

# Step 3: The agent can now access the file in tasks
smooth run <session-id> "Analyze the contract document and extract key terms" --url "https://example.com"

上传多个文件：

# Upload files
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)

# Start session with multiple files
smooth start-session --files "$FILE_ID_1,$FILE_ID_2"

从会话下载文件：

smooth run <session-id> "Download the monthly report PDF"
smooth close-session <session-id>

# After session closes, get download URL
smooth downloads <session-id>
# curl the URL to download files

---

实时视图与手动干预

当自动化需要人工输入时（CAPTCHA、2FA、复杂身份验证）：

smooth start-session --profile-id "my-profile"
smooth run <session-id> "Go to secure-site.com and log in"

# If task encounters CAPTCHA or requires manual action:
smooth live-view <session-id>
# Open the URL and complete the manual steps

# Continue automation after manual intervention:
smooth run <session-id> "Now navigate to the dashboard and export data"

---

直接执行浏览器操作

从当前页面提取数据：

smooth extract <session-id> \
  --schema '{"type":"object","properties":{"products":{"type":"array"}}}' \
  --prompt "Extract all product names and prices"

导航到 URL，然后提取数据：

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

在浏览器中执行 JavaScript：

# Simple JavaScript
smooth evaluate-js <session-id> "document.title"

# With arguments
smooth evaluate-js <session-id> "(args) => {return args.x + args.y;}" --args '{"x": 5, "y": 10}'

# Complex DOM manipulation
smooth evaluate-js <session-id> \
  "document.querySelectorAll('a').length"

---

配置文件管理

列出所有配置文件：

smooth list-profiles

删除配置文件：

smooth delete-profile <profile-id>

何时使用配置文件：

• ✅ 需要身份验证的网站
• ✅ 在多次任务运行间保持会话状态
• ✅ 避免重复登录
• ✅ 保留 Cookie 和本地存储

何时跳过配置文件：

• 无需身份验证的公共网站
• 一次性抓取任务
• 测试场景

---

文件管理

上传文件：

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

删除文件：

smooth delete-file <file-id>

---

最佳实践

1. 务必保存会话 ID - 后续命令会用到
2. 对需要身份验证的会话使用配置文件 - 记录每个配置文件对应的网站
3. 关闭会话后等待 5 秒 - 确保状态已正确保存
4. 使用有描述性的配置文件 ID - 例如，"linkedin-personal"、"twitter-company"
5. 完成后关闭会话 - 默认的正常关闭方式可确保正确清理
6. 使用结构化输出提取数据 - 可获得整洁且类型明确的结果
7. 在同一会话中运行顺序任务 - 当各步骤依赖先前操作时，保持会话连续。
8. 为每个独立任务使用一个子 Agent 和一个会话 - 并行运行任务以加快工作。
9. 协调资源 - 使用子 Agent 时，必须为每个子 Agent 创建并分配一个分区，且不要让它们自行创建分区。
10. 不要向 URL 添加查询参数，例如避免使用 ?filter=xyz - 从基础 URL 开始，让 Agent 通过 UI 导航并应用筛选条件。
11. Smooth 由智能 Agent 驱动 - 给它分配任务，而不是单独的步骤。

---

故障排除

“Session not found” - 会话可能已超时或关闭。请启动一个新会话。

“Profile not found” - 查看 smooth list-profiles，了解可用的配置文件。

验证码或身份验证问题 - 使用 smooth live-view <session-id>，让用户手动处理。

任务超时 - 增加 --max-steps，或将任务拆分为更小的步骤。

已知问题

处理以 -（连字符）开头的会话 ID - 会话 ID 可能以连字符开头。在这种情况下，请使用 --（双连字符）分隔符处理。

---

命令参考

配置文件命令

• smooth create-profile [--profile-id ID] - 创建新的配置文件
• smooth list-profiles - 列出所有配置文件
• smooth delete-profile <profile-id> - 删除配置文件

文件命令

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

会话命令

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

所有命令均支持用于输出 JSON 的 --json 标志。