登录处理功能更新总结

✅ 已完成的工作

1. 修改示例6 - 添加完整的登录处理流程

文件: examples/cloud_browser_example.py

主要改进:

✅ 添加了 wait_for_user_action 工具导入
✅ 重构了 example_6_xhs_search_save() 函数
✅ 添加了 5 个清晰的步骤标注
✅ 实现了登录状态检测
✅ 集成了手动登录等待机制
✅ 添加了详细的用户提示信息
✅ 增加了结果预览功能

新增功能:

# 步骤 1: 访问小红书首页
await navigate_to_url("https://www.xiaohongshu.com")

# 步骤 2: 检查登录状态
check_login_js = """..."""  # JavaScript 检测代码
login_status = await evaluate(check_login_js)

# 步骤 3: 等待用户手动登录
await wait_for_user_action(
    message="请在云浏览器中完成小红书登录，完成后按 Enter 继续",
    timeout=300  # 5 分钟超时
)

# 步骤 4: 执行搜索和数据提取
# 步骤 5: 保存结果并显示预览

运行方式:

python examples/cloud_browser_example.py --example 6

2. 创建详细的登录处理文档

文件: examples/LOGIN_HANDLING_GUIDE.md

文档内容 (约 800 行):

📚 主要章节

概述 - 为什么需要登录处理
登录场景分类 - 5 种常见登录场景
三种登录处理方式对比
- 方式1: 手动登录（推荐）
- 方式2: Cookie复用
- 方式3: 自动化登录
方式1: 手动登录（推荐）
- 核心思路
- 完整代码示例
- 关键点说明
方式2: Cookie复用
- 步骤1: 首次登录并保存 Cookie
- 步骤2: 使用保存的 Cookie
- Cookie 复用的注意事项
方式3: 自动化登录
- 适用场景
- 示例代码
- 风险警告
完整实战示例 - 小红书搜索（带登录处理）
登录状态检测
- 通用检测方法
- 网站特定检测
Cookie管理最佳实践
- Cookie 存储结构
- Cookie 管理类
- 自动刷新 Cookie
常见问题 - 6 个常见问题及解答
安全建议
- 保护敏感信息
- Cookie 文件安全
- 使用代理
- 限制登录频率
总结
- 登录处理决策树
- 推荐方案
- 最佳实践

🎯 核心解决方案

问题1: 小红书需要登录时，在哪一步去登录？

答案: 在访问小红书首页后，执行搜索之前

具体步骤:

# 1. 启动云浏览器（非无头模式）
await init_browser_session(
    headless=False,  # 关键：设置为 False
    use_cloud=True,
)

# 2. 访问小红书首页
await navigate_to_url("https://www.xiaohongshu.com")

# 3. 检查登录状态（可选）
login_status = await evaluate(check_login_js)

# 4. 等待用户手动登录 ⭐ 关键步骤
await wait_for_user_action(
    message="请在云浏览器中完成小红书登录，完成后按 Enter 继续",
    timeout=300
)

# 5. 继续执行搜索和数据提取
await navigate_to_url(search_url)

用户操作流程:

程序启动后，查找日志中的 🔗 Live URL
复制 Live URL 并在浏览器中打开
在 Live URL 页面中完成登录（扫码或账号密码）
登录成功后，回到终端按 Enter 继续

问题2: 如果后续操作需要登录后才能获得数据，应该在哪一步介入？

答案: 有三种介入方式，根据场景选择

方式1: 手动登录（推荐，适用于所有场景）

介入时机: 在访问需要登录的页面之前

# 通用模板
async def task_with_login():
    # 1. 启动浏览器
    await init_browser_session(headless=False, use_cloud=True)

    # 2. 访问网站首页
    await navigate_to_url("https://target-website.com")

    # 3. 【介入点】等待用户登录
    await wait_for_user_action(
        message="请完成登录，然后按 Enter",
        timeout=300
    )

    # 4. 继续执行需要登录的操作
    await navigate_to_url("https://target-website.com/protected-page")
    # 提取数据...

方式2: Cookie复用（推荐，适用于频繁使用）

介入时机: 在初始化浏览器时

# 首次使用：保存 Cookie
async def first_time_save_cookies():
    await init_browser_session(headless=False, use_cloud=True)
    await navigate_to_url("https://target-website.com")

    # 【介入点】等待用户登录
    await wait_for_user_action("请完成登录", timeout=300)

    # 保存 Cookie
    cookies = await get_cookies()
    save_to_file(cookies, "cookies.json")

# 后续使用：加载 Cookie
async def subsequent_use():
    cookies = load_from_file("cookies.json")
    profile = BrowserProfile(cookies=cookies)

    # 【介入点】使用 profile 初始化
    await init_browser_session(
        headless=True,
        use_cloud=True,
        browser_profile=profile  # 预设 Cookie
    )

    # 直接访问需要登录的页面（已登录）
    await navigate_to_url("https://target-website.com/protected-page")

方式3: 自动化登录（不推荐，仅适用于简单场景）

介入时机: 在登录页面加载后

async def automated_login():
    await init_browser_session(headless=True, use_cloud=True)
    await navigate_to_url("https://target-website.com/login")

    # 【介入点】自动填写表单
    await input_text(index=0, text="username")
    await input_text(index=1, text="password")
    await click_element(index=2)

    # 等待登录完成
    await wait(3)

    # 继续执行任务
    await navigate_to_url("https://target-website.com/protected-page")

📊 三种方式对比

方式	介入时机	适用场景	优点	缺点
手动登录	访问网站后	所有场景	最可靠，成功率高	需要人工操作
Cookie复用	初始化浏览器时	频繁使用	快速，无需重复登录	Cookie会过期
自动化登录	登录页面加载后	简单账号密码	完全自动化	容易被检测

🎓 实战建议

首次使用（推荐流程）

# 第一次：手动登录 + 保存 Cookie
async def first_time():
    # 1. 手动登录
    await init_browser_session(headless=False, use_cloud=True)
    await navigate_to_url("https://www.xiaohongshu.com")
    await wait_for_user_action("请完成登录", timeout=300)

    # 2. 保存 Cookie
    cookies = await get_cookies()
    save_cookies("xiaohongshu", cookies)

    # 3. 执行任务
    await do_task()

日常使用（推荐流程）

# 后续：直接使用 Cookie
async def daily_use():
    # 1. 加载 Cookie
    cookies = load_cookies("xiaohongshu")

    # 2. 检查 Cookie 是否有效
    if not cookies or is_expired(cookies):
        # Cookie 无效，重新登录
        await first_time()
        return

    # 3. 使用 Cookie 初始化
    profile = BrowserProfile(cookies=cookies)
    await init_browser_session(
        headless=True,
        use_cloud=True,
        browser_profile=profile
    )

    # 4. 直接执行任务（已登录）
    await do_task()

📁 相关文件

示例代码: examples/cloud_browser_example.py
- 示例6: 小红书搜索（带登录）
- 运行: python examples/cloud_browser_example.py --example 6
详细文档: examples/LOGIN_HANDLING_GUIDE.md
- 完整的登录处理指南
- 包含所有代码示例和最佳实践
云浏览器指南: examples/CLOUD_BROWSER_GUIDE.md
- 云浏览器基础使用
- 环境配置和快速开始
快速入门: examples/README_CLOUD_BROWSER.md
- 快速开始步骤
- 示例列表

🚀 快速开始

运行小红书登录示例

# 1. 确保已安装依赖
pip install python-socks

# 2. 配置环境变量（.env 文件）
BROWSER_USE_API_KEY=your_api_key_here

# 3. 运行示例6
python examples/cloud_browser_example.py --example 6

# 4. 按照提示操作
#    - 查找日志中的 Live URL
#    - 在浏览器中打开 Live URL
#    - 完成登录
#    - 回到终端按 Enter

查看结果

# 结果保存在
cat output/xhs.json

💡 关键要点

Live URL 是关键
- 云浏览器启动时会输出
- 在浏览器中打开可以实时查看和操作
- 格式: https://live.browser-use.com?wss=...
headless=False 很重要
- 登录时必须设置为 False
- 否则无法在 Live URL 中看到页面
wait_for_user_action 是核心
- 暂停自动化流程
- 等待用户手动操作
- 设置合理的超时时间（3-5分钟）
Cookie 复用提高效率
- 首次手动登录并保存 Cookie
- 后续使用 Cookie 跳过登录
- 定期更新 Cookie（建议每周）
安全第一
- 不要硬编码密码
- Cookie 文件不要提交到 Git
- 使用环境变量管理敏感信息

📞 技术支持

详细文档: LOGIN_HANDLING_GUIDE.md
云浏览器指南: CLOUD_BROWSER_GUIDE.md
示例代码: examples/cloud_browser_example.py
基础类源码: agent/tools/builtin/baseClass.py

更新时间: 2026-01-30 版本: v1.0.0

LOGIN_UPDATE_SUMMARY.md 9.1 KB History Raw