菜单
Browser Agent 调试方案（通用版）。触发条件：需要调试浏览器自动化脚本、验证发布流程、修复元素选择问题。核心原则：每步必截图、逐步验证、免登录调试。支持所有 AI 编程工具（Lingma/Cursor/Claude Code等），通过 CDP 连接到 CloakBrowser。
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/drgon1/santian --skill browser-agent-debug命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
基于 SOC 职业分类
| name | browser-agent-debug |
| description | Browser Agent 调试方案（通用版）。触发条件：需要调试浏览器自动化脚本、验证发布流程、修复元素选择问题。核心原则：每步必截图、逐步验证、免登录调试。支持所有 AI 编程工具（Lingma/Cursor/Claude Code等），通过 CDP 连接到 CloakBrowser。 |
设计原则：严格遵循"截图→操作→截图→验证"循环，确保每一步都经过人工确认。支持三种测试方案，优先使用免登录策略。
🎯 重要升级：本 Skill 已升级为通用版本，不再依赖特定 AI 工具的内置 Browser Agent，而是通过 CDP 连接到我们自己的 CloakBrowser，可以在任何 AI 编程工具中使用（Lingma、Cursor、Claude Code 等）。
| 特性 | 传统方案（Lingma 内置） | 新方案（CloakBrowser + CDP） |
|---|---|---|
| 依赖 | Lingma 内置 Browser Agent | 任何支持 CDP 连接的 AI 工具 |
| 浏览器 | Lingma 控制的 Chrome | 我们的 CloakBrowser（反检测） |
| 可迁移性 | ❌ 仅限 Lingma | ✅ 可在任何 AI 工具中使用 |
| 反检测 | ❌ 普通 Chrome | ✅ CloakBrowser（源码级修改） |
| 持久化登录 | ⚠️ 有限支持 | ✅ 完整支持（独立用户目录） |
| CDP 端口 | 自动管理 | 9222（固定） |
┌─────────────────────────────────────────────────┐
│ AI 编程工具（任意） │
│ ┌──────────────────────────────────────┐ │
│ │ Browser Agent / Subagent │ │
│ │ - 接收任务指令 │ │
│ │ - 执行 Playwright 代码 │ │
│ │ - 截图分析 │ │
│ └──────────────┬───────────────────────┘ │
│ │ CDP 连接 (ws://localhost:9222) │
└─────────────────┼───────────────────────────────┘
│
┌─────────────────▼───────────────────────────────┐
│ CloakBrowser（反检测浏览器） │
│ ┌──────────────────────────────────────┐ │
│ │ Chromium（源码级修改） │ │
│ │ - 消除 navigator.webdriver │ │
│ │ - Canvas/WebGL 指纹伪装 │ │
│ │ - TLS 指纹伪装 │ │
│ │ - 30/30 通过检测测试 │ │
│ └──────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────┐ │
│ │ 持久化用户数据目录 │ │
│ │ - browser_data/cloak/{platform}/ │ │
│ │ - 保存登录状态（Cookies/LocalStorage）│ │
│ │ - 下次启动自动登录 │ │
│ └──────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘
启动 CloakBrowser（Python 脚本）
python f:/myclaw/test/start_logged_in_browser.py --platform baijia --url https://baijiahao.baidu.com/builder/rc/edit?type=news
AI 工具通过 CDP 连接
# 在任何 AI 工具中都可以这样连接
from playwright.sync_api import sync_playwright
playwright = sync_playwright().start()
browser = playwright.chromium.connect_over_cdp("http://localhost:9222")
context = browser.contexts[0] # 复用已有上下文
page = context.pages[0] if context.pages else context.new_page()
执行调试任务
关闭浏览器
start_logged_in_browser.py 终端按 Ctrl+C以下任一关键词出现时，自动启用本 Skill：
| 触发关键词 | 典型需求 |
|---|---|
| 测试发布脚本 | "测试头条发布"、"验证百家号流程"、"调试大鱼号" |
| 修复脚本bug | "脚本报错了"、"某步失败了"、"选择器不对" |
| 用户反馈问题 | "这里有问题"、"截图显示失败"、"某步没执行" |
| 优化选择器 | "改进点击逻辑"、"增强容错能力" |
非触发场景（不启用本 Skill）：
universal_publisher.py）需要截图：
# Browser Agent 连接浏览器 → 每步截图 → 视觉分析 → 找出问题
await page.screenshot(path="f:/myclaw/test/debug_step1.png")
# 然后用大模型视觉能力分析截图
特点：
不需要截图：
# 直接执行操作，不需要截图
# 脚本中没有大模型，截图没有意义
page.click(selector)
page.fill(input, value)
# 只需要日志输出，不需要截图
特点：
总结：
截图 → 判断当前状态 → 执行操作 → 截图验证 → 继续下一步
每次操作前必须先截图判断当前状态，不要盲目操作！
核心机制：使用 CloakBrowser + launch_persistent_context 实现真正的浏览器状态持久化。
所有平台都有独立的持久化用户数据目录，位于 f:\myclaw\multi-platform-automation\browser_data\cloak\：
| 平台 | 用户数据目录路径 |
|---|---|
| 头条号 | f:\myclaw\multi-platform-automation\browser_data\cloak\toutiao\ |
| 百家号 | f:\myclaw\multi-platform-automation\browser_data\cloak\baijia\ |
| 大鱼号 | f:\myclaw\multi-platform-automation\browser_data\cloak\dayu\ |
| QQ号 | f:\myclaw\multi-platform-automation\browser_data\cloak\qq\ |
| 微信公众号 | f:\myclaw\multi-platform-automation\browser_data\cloak\wechat\ |
| 小红书 | f:\myclaw\multi-platform-automation\browser_data\cloak\xiaohongshu\ |
工作原理：
使用方式：
# BrowserAutomation 类会自动使用对应平台的持久化目录
from utils.browser_automation import BrowserAutomation
# 传入 platform 参数，自动加载对应的用户数据目录
browser = BrowserAutomation(platform='toutiao') # 使用 toutiao 目录
⚠️ 重要：
⚠️ 重要规则：每次调试必须完整管理浏览器生命周期
核心原则：启动一次浏览器，连续测试所有步骤，不要反复重启！
# ✅ 正确的连续调试流程
# 步骤1：启动已登录的浏览器（只做一次）
python test/start_logged_in_browser.py --platform toutiao --url https://mp.toutiao.com/profile_v4/graphic/publish
# 步骤2：AI 工具连接到 CDP 端口 9222（只做一次）
# 在任何 AI 工具中都可以这样连接：
from playwright.sync_api import sync_playwright
playwright = sync_playwright().start()
browser = playwright.chromium.connect_over_cdp("http://localhost:9222")
context = browser.contexts[0]
page = context.pages[0] if context.pages else context.new_page()
# 步骤3：连续执行所有测试步骤（不要关闭浏览器！）
步骤1: 关闭AI助手 → 截图验证 → 继续
步骤2: 填写标题 → 截图验证 → 继续
步骤3: 粘贴内容 → 截图验证 → 继续
步骤4: 添加标签 → 截图验证 → 继续
步骤5: 上传封面 → 截图验证 → 继续
...（所有步骤连续执行）
# 步骤4：所有步骤测试完成后，再关闭浏览器
# 在 start_logged_in_browser.py 的终端中按 Ctrl+C
优势：
❌ 错误做法（禁止）：
# 测试步骤1 → 关闭浏览器 → 重新登录 → 测试步骤1-2 → 关闭浏览器 → ...
# 这种“逐步累加”的测试方式极其浪费时间！
# 步骤1：启动已登录的浏览器
python test/start_logged_in_browser.py --platform toutiao --url https://mp.toutiao.com/profile_v4/graphic/publish
# 步骤2：等待看到以下输出
✅ 浏览器已就绪！
Browser Agent 现在可以连接到 CDP 端口 9222 进行调试
按 Ctrl+C 关闭浏览器
# 步骤3：让 AI 工具连接到 CDP 端口 9222
# ⚠️ 重要：AI 工具应该连接到这个已登录的浏览器，不要创建新的！
适用场景：
注意：即使使用分步调试，也应该尽量在一次会话中完成多个步骤，避免反复重启。
问题现象：
根本原因： AI 工具连接到 CDP 端口时，可能创建了一个新的浏览器上下文，而不是复用已有的登录会话。
解决方案：
browser.contexts[0] 复用已有上下文，而不是 browser.new_context()为什么能保持登录状态？
browser_data/cloak/{platform}/# 调试结束后，在 start_logged_in_browser.py 的终端中按 Ctrl+C
# 确认浏览器已关闭
netstat -ano | findstr :9222 # 应该没有输出
❌ 错误做法：
browser_data/cloak/{platform} 目录（会丢失登录状态）✅ 正确做法：
Remove-Item -Recurse -Force "browser_data\cloak\toutiao"
⚠️ 关键原则：截图不是为了保存，而是为了用视觉能力分析！
1. 截图
2. 使用大模型视觉能力分析截图：
- 页面标题是什么？
- URL 是什么？
- 当前状态（已登录/未登录/错误页面）？
- 关键元素位置（标题框、编辑器、按钮等）
- 是否有弹窗需要关闭？
3. 基于分析结果决定下一步操作
4. 执行操作
5. 再次截图验证
6. 重复步骤2-5
每次截图后，必须分析：
页面基本信息
登录状态
关键元素位置
弹窗和干扰元素
下一步建议
适用场景：首次调试某个发布脚本，需要验证每一步是否正确
⚠️ 重要原则：启动一次浏览器，连续执行所有步骤，不要反复重启！
执行流程：
1. 启动已登录的浏览器（只做一次）
2. Browser Agent 连接到 CDP 端口（只做一次）
3. 读取目标脚本（如 publish_toutiao.py）
4. 提取所有操作步骤
5. 严格按顺序连续执行每一步（不要关闭浏览器！）：
├─ 步骤1: 截图 → 执行 → 截图验证 → 继续
├─ 步骤2: 截图 → 执行 → 截图验证 → 继续
├─ 步骤3: 截图 → 执行 → 截图验证 → 继续
└─ ...（所有步骤连续执行）
6. 记录所有发现的问题
7. 所有步骤完成后，再关闭浏览器
8. 生成修复建议
示例：测试头条发布脚本
# 从 publish_toutiao.py 提取的步骤：
步骤列表 = [
"步骤0: 关闭AI助手弹窗",
"步骤1: 打开HTML文件并复制内容",
"步骤2: 导航到发布页面",
"步骤3: 填写标题",
"步骤4: 粘贴正文",
"步骤5: 添加标签",
"步骤6: 上传封面",
"步骤7: 设置定时发布",
"步骤8: 点击发布按钮"
]
# Browser Agent 执行：
for 步骤 in 步骤列表:
截图(f"before_{步骤}")
执行(步骤)
截图(f"after_{步骤}")
验证(步骤) # 人工确认
输出要求：
f:\myclaw\test\适用场景：脚本运行时报错，需要定位并修复具体步骤
执行流程：
1. 先完整运行一次脚本，记录报错位置和错误信息
2. 分析报错原因（选择器错误？元素不存在？超时？）
3. 手动执行到报错步骤的前一步
4. 截图确认当前状态
5. 尝试不同的解决方案：
├─ 方案A: 修改选择器
├─ 方案B: 增加等待时间
├─ 方案C: 更换操作方式（click → JavaScript）
└─ 方案D: 多策略降级（4层fallback）
6. 每尝试一种方案都要：
├─ 截图（尝试前）
├─ 执行方案
├─ 截图（尝试后）
└─ 验证是否成功
7. 找到可行方案后，更新脚本
示例：修复头条标签选择失败
问题：脚本在第5步"添加标签"时报错
执行流程：
1. 运行脚本，发现报错：Element not found for selector '#tag-game'
2. 手动执行到第4步（粘贴正文完成）
3. 截图确认：正文已粘贴，光标在末尾
4. 尝试方案A：使用 locator 匹配
- 截图：before_try_locator
- 执行：page.locator('div:has-text("#游戏#")').click()
- 截图：after_try_locator
- 验证：❌ 失败，元素不可见
5. 尝试方案B：使用 get_by_text
- 截图：before_try_get_by_text
- 执行：page.get_by_text("#游戏#").click()
- 截图：after_try_get_by_text
- 验证：✅ 成功！
6. 更新脚本，将选择器改为 get_by_text
输出要求：
适用场景：用户提供截图指出某处有问题，但不确定如何修复
执行流程：
1. 接收用户截图，分析问题
2. 从脚本中找到对应位置的代码
3. ⚠️ 重要：不要直接写泛化低效的代码
4. 严格按照脚本步骤执行到问题位置
5. 截图确认当前状态与用户截图一致
6. 尝试调通这一步：
├─ 分析为什么失败
├─ 尝试多种解决方案
├─ 每步都截图验证
└─ 找到可行的方案
7. 用确认的方案修复脚本中的bug
8. 重新运行完整流程验证
示例：用户反馈"封面上传失败"
用户截图显示：点击"本地上传"后没有弹出文件选择器
执行流程：
1. 从脚本找到封面上传代码（第390-480行）
2. 不要直接改成复杂的 fallback 逻辑
3. 手动执行到封面上传步骤：
- 截图：before_upload_cover
- 确认：封面框已显示
4. 尝试方案A：直接点击封面框
- 执行：page.click('div.cover-upload')
- 截图：after_click_cover
- 验证：❌ 没有反应
5. 尝试方案B：点击"本地上传"按钮
- 执行：page.click('button:has-text("本地上传")')
- 截图：after_click_local_upload
- 验证：✅ 文件选择器弹出！
6. 分析原因：应该先点封面框，再点"本地上传"
7. 修复脚本，确保两步都执行
8. 重新测试完整流程
关键原则：
# 方法1：使用 start_logged_in_browser.py（推荐）
python f:/myclaw/test/start_logged_in_browser.py --platform toutiao --url https://mp.toutiao.com/profile_v4/graphic/publish
# 方法2：直接使用 BrowserAutomation 类
# BrowserAutomation 会自动加载 auth_state 并启用 CDP 端口 9222
在任何 AI 工具中都可以这样连接：
from playwright.sync_api import sync_playwright
# 连接到 CDP 端口 9222
playwright = sync_playwright().start()
browser = playwright.chromium.connect_over_cdp("http://localhost:9222")
# 复用已有上下文（重要！不要创建新的）
context = browser.contexts[0]
page = context.pages[0] if context.pages else context.new_page()
# 现在可以执行操作了
print(f"当前页面: {page.url}")
print(f"页面标题: {page.title()}")
关键要点：
browser.contexts[0]：复用已有上下文，保留登录状态browser.new_context()：会创建新的空白上下文，丢失登录状态start_logged_in_browser.py 启动时配置# 导航
await page.goto("https://mp.toutiao.com/profile_v4/graphic/publish")
# 截图
await page.screenshot(path="f:/myclaw/test/debug_step_name.png")
# 填写表单
await page.fill("input[placeholder='标题']", "测试标题")
# 点击元素
await page.click("button:has-text('发布')")
# 键盘输入
await page.keyboard.type("#游戏")
await page.keyboard.press("Enter")
# 执行 JavaScript
result = await page.evaluate("""
() => {
const buttons = document.querySelectorAll('button');
for (let btn of buttons) {
if (btn.textContent.includes('发布')) {
btn.click();
return true;
}
}
return false;
}
""")
## 测试目标：头条号发布流程
### 步骤清单（从 publish_toutiao.py 提取）
#### 步骤0：关闭AI助手弹窗
- 操作前截图：debug_before_close_ai_assistant.png
- 执行操作：点击关闭按钮
- 操作后截图：debug_after_close_ai_assistant.png
- 验证结果：✅ AI助手已关闭
#### 步骤1：打开HTML文件并复制内容
- 操作前截图：debug_before_open_html.png
- 执行操作：打开 file:///.../article.html，Ctrl+A, Ctrl+C
- 操作后截图：debug_after_copy_content.png
- 验证结果：✅ 内容已复制到剪贴板
#### 步骤2：导航到发布页面
- 操作前截图：debug_before_navigate.png
- 执行操作：goto https://mp.toutiao.com/profile_v4/graphic/publish
- 操作后截图：debug_after_navigate.png
- 验证结果：✅ 发布页面已加载
...（继续所有步骤）
## Bug修复：头条标签选择失败
### 问题分析
- 报错位置：第330行，添加标签步骤
- 错误信息：Element not found for selector 'div:has-text("#游戏#")'
- 可能原因：下拉菜单未出现，或选择器不匹配
### 调试过程
#### 准备阶段
- 执行到第4步（粘贴正文完成）
- 截图：debug_before_fix_tag.png
- 确认：正文已粘贴，光标在末尾
#### 尝试方案A：locator 匹配
- 截图：debug_try_locator_before.png
- 执行：page.locator('div:has-text("#游戏#")').click()
- 截图：debug_try_locator_after.png
- 结果：❌ 失败，元素不可见
#### 尝试方案B：get_by_text
- 截图：debug_try_get_by_text_before.png
- 执行：page.get_by_text("#游戏#").first.click()
- 截图：debug_try_get_by_text_after.png
- 结果：✅ 成功！
### 最终方案
将脚本第341行的选择器改为：
```python
tag_option = page.get_by_text(f"#{tag}#").first
if tag_option.is_visible(timeout=2000):
tag_option.click()
### 5.3 方案3模板：用户截图反馈
```markdown
## 问题修复：用户反馈封面上传失败
### 用户提供的截图
- 截图路径：user_report_cover_fail.png
- 问题描述：点击"本地上传"后没有弹出文件选择器
### 调试过程
#### 定位问题代码
- 脚本位置：publish_toutiao.py 第390-480行
- 相关代码：封面上传逻辑
#### 手动复现
- 执行到封面上传步骤
- 截图：debug_reproduce_issue.png
- 确认：与用户截图一致
#### 尝试方案A：直接点击封面框
- 截图：debug_try_click_cover_before.png
- 执行：page.click('div.cover-upload')
- 截图：debug_try_click_cover_after.png
- 结果：❌ 没有反应
#### 尝试方案B：点击"本地上传"按钮
- 截图：debug_try_local_upload_before.png
- 执行：page.click('button:has-text("本地上传")')
- 截图：debug_try_local_upload_after.png
- 结果：✅ 文件选择器弹出！
#### 根本原因分析
应该先点击封面框，再点击"本地上传"按钮
### 最终修复
确保脚本中两步都执行：
```python
# 步骤1：点击封面框
page.click('div.cover-upload')
time.sleep(2)
# 步骤2：点击本地上传
with page.expect_file_chooser() as fc_info:
page.click('button:has-text("本地上传")')
---
## 六、常见问题与解决方案
### 6.1 元素找不到
**症状**：`Element not found` 或 `TimeoutError`
**排查步骤**：
1. 截图确认页面状态
2. 检查是否在正确的页面
3. 检查元素是否被遮挡（弹窗、抽屉）
4. 尝试不同的选择器策略
5. 增加等待时间
**解决方案**：
```python
# 方案1：增加等待
await page.wait_for_selector(selector, timeout=10000)
# 方案2：滚动到元素
await page.evaluate(f"""
() => {{
const el = document.querySelector('{selector}');
if (el) el.scrollIntoView({{behavior: 'smooth'}});
}}
""")
# 方案3：多策略降级
async def click_with_fallback(page, text):
# 策略1: locator
# 策略2: get_by_text
# 策略3: JavaScript
# 策略4: Enter键
症状：页面跳转到登录页
解决方案：
browser_data/cloak/{platform} 目录是否存在且有内容Default/Network/Cookies 文件是否存在Remove-Item -Recurse -Force "browser_data\cloak\toutiao"
调试代码：
import os
project_root = r"f:\myclaw\multi-platform-automation"
platform = 'toutiao'
user_data_dir = os.path.join(project_root, 'browser_data', 'cloak', platform)
print(f"用户目录: {user_data_dir}")
print(f"目录存在: {os.path.exists(user_data_dir)}")
cookies_file = os.path.join(user_data_dir, 'Default', 'Network', 'Cookies')
if os.path.exists(cookies_file):
print(f"Cookies 文件大小: {os.path.getsize(cookies_file)} bytes")
else:
print("Cookies 文件不存在！")
症状：点击无效，元素被遮挡
解决方案：
# 步骤0：关闭所有弹窗
close_selectors = [
'.ai-assistant-drawer .byte-drawer-close',
'button:has-text("我知道了")',
'button:has-text("下一步")',
'button:has-text("完成")'
]
for selector in close_selectors:
try:
if await page.is_visible(selector, timeout=2000):
await page.click(selector)
await page.wait_for_timeout(1000)
except:
pass
问题：某些网站的编辑器在 iframe 内部，使用普通选择器无法定位。
典型案例：百家号的正文编辑器在 name="ueditor_0" 的 iframe 内部。
# 错误1：使用 frame_locator（不起作用）
ueditor_frame = page.frame_locator('iframe[name="ueditor_0"]')
editor = ueditor_frame.locator('.view')
if editor.count() > 0: # ❌ 返回 0，找不到元素
editor.click()
# 错误2：遍历所有 contenteditable（会选中标题）
editors = page.locator('div[contenteditable="true"]')
# 标题输入框也是 contenteditable，会先被选中
editors.first.click() # ❌ 点击的是标题，不是正文
# 错误3：凭经验猜测选择器，不实际验证
editor_selector = '#newsTextArea [contenteditable="true"]' # ❌ 可能不存在
page.locator(editor_selector).click()
方法1：通过 frame 对象访问（推荐）
# 步骤1：找到目标 frame
from playwright.sync_api import sync_playwright
playwright = sync_playwright().start()
browser = playwright.chromium.connect_over_cdp('http://localhost:9222')
context = browser.contexts[0]
page = context.pages[0] if context.pages else context.new_page()
# 遍历所有 frames，找到 name='ueditor_0' 的 frame
target_frame = None
for frame in page.frames:
if frame.name == 'ueditor_0':
target_frame = frame
break
if target_frame:
print(f"✅ 找到目标 frame")
# 步骤2：在 frame 内查找 contenteditable 元素
editables = target_frame.query_selector_all('[contenteditable]')
if editables and len(editables) > 0:
print(f"✅ 找到 {len(editables)} 个 contenteditable 元素")
# 步骤3：点击第一个 contenteditable 元素
editables[0].click()
time.sleep(1)
# 步骤4：粘贴内容
page.keyboard.press('Control+V')
time.sleep(3)
print(f"✅ 正文已正确粘贴到编辑器中！")
else:
print(f"❌ frame 内未找到 contenteditable 元素")
else:
print(f"❌ 未找到 name='ueditor_0' 的 frame")
方法2：备用方案 - 直接定位 UEditor 容器
# 如果 frame 方法失败，尝试直接点击 UEditor 容器
try:
editor = page.locator('#edui1_iframeholder').first
if editor.is_visible(timeout=1000):
editor.click()
time.sleep(1)
page.keyboard.press('Control+V')
print(f"✅ 通过 #edui1_iframeholder 找到编辑器")
except Exception as e:
print(f"⚠️ UEditor 容器方法失败: {e}")
步骤1：检查页面结构
# 检查所有 frames
print(f"页面共有 {len(page.frames)} 个 frame:")
for i, frame in enumerate(page.frames):
print(f" Frame {i}: name='{frame.name}', url='{frame.url[:50]}'")
# 输出示例：
# Frame 0: name='', url='https://baijiahao.baidu.com/builder/rc/edit?type=n'
# Frame 1: name='', url='about:blank'
# Frame 2: name='', url='about:blank'
# Frame 3: name='ueditor_0', url='about:blank' ← 这是目标 frame
步骤2：检查 frame 内的元素
# 在目标 frame 内查找 contenteditable 元素
target_frame = None
for frame in page.frames:
if frame.name == 'ueditor_0':
target_frame = frame
break
if target_frame:
editables = target_frame.query_selector_all('[contenteditable]')
print(f"找到 {len(editables)} 个 contenteditable 元素")
for i, el in enumerate(editables):
box = el.bounding_box()
text = el.inner_text()
print(f" [{i}] x={box['x']}, y={box['y']}, w={box['w']}, h={box['h']}")
print(f" 内容长度: {len(text)} 字符")
print(f" 前50字符: {text[:50]}...")
步骤3：截图验证
# 操作前截图
page.screenshot(path='f:/myclaw/test/debug_before_click.png')
# 点击编辑器
editables[0].click()
time.sleep(1)
# 操作后截图
page.screenshot(path='f:/myclaw/test/debug_after_click.png')
# 输入测试文本
test_text = "这是测试正文内容"
page.keyboard.type(test_text, delay=50)
# 最终截图
page.screenshot(path='f:/myclaw/test/debug_final.png')
# 验证内容
content = editables[0].inner_text()
if test_text in content:
print(f"🎉 成功！正文已正确粘贴到编辑器中！")
else:
print(f"❌ 失败！测试文本未在编辑器中找到")
frame_locator：page.frame_locator() 在某些情况下不起作用，必须使用 page.frames 遍历frame.namecontenteditable 会选中标题或其他元素，必须通过 iframe 隔离iframe[name="ueditor_0"] → [contenteditable]问题：头条号发布文章时，需要添加话题标签（如 #游戏#），但自动化脚本中经常遇到标签选择失败的问题。
核心发现（经过多次测试验证）：
#游戏 → ↓ → Enter，标签会显示为蓝色高亮\u0002错误做法总结（❌ 已验证失败）：
# 错误1：只输入标签名，不按Enter或点击选择
publish_page.keyboard.type(f"#{tag}")
time.sleep(1.5)
# 结果：标签建议框显示，但标签未选中，仍是普通文本
# 错误2：直接输入完整格式 #游戏#
publish_page.keyboard.type(f"#{tag}#")
# 结果：仍然触发建议框，不会自动识别为标签
# 错误3：输入后按Enter，但不先选中建议项
publish_page.keyboard.type(f"#{tag}")
publish_page.keyboard.press('Enter')
# 结果：可能只是换行，没有选择标签
# 错误4：在两个标签之间加空格（已验证失败）
publish_page.keyboard.type(f"#{tag1}")
# ... ↓ + Enter ...
publish_page.keyboard.type(' ') # 加空格
publish_page.keyboard.type(f"#{tag2}")
# 结果：第二个标签仍然是普通文本，无法触发建议框
正确做法（✅ 经过测试验证，仅适用于单个标签）：
方案A：输入后按 ↓ + Enter（推荐，仅单标签）
# 步骤1：输入 # + 标签名
publish_page.keyboard.type(f"#{tag}")
time.sleep(1.5) # 等待下拉框出现
# 步骤2：按 ↓ 选中第一项
publish_page.keyboard.press('ArrowDown')
time.sleep(0.3)
# 步骤3：按 Enter 确认选择
publish_page.keyboard.press('Enter')
time.sleep(0.5)
# 验证：标签应显示为蓝色高亮格式 #游戏#
验证成功的标志：
#游戏#关键限制：
测试截图参考：
f:\myclaw\test\debug_tag_methodA_after.png（蓝色高亮）f:\myclaw\test\verify_space_solution.png（普通文本）待解决问题：
#游戏 → ↓ → Enter什么才算成功经验？
核心原则：只测试需要测试的内容，其他一律不做！
1. 截图当前页面
2. 用大模型视觉能力分析截图，判断当前在哪个页面：
- 发布页面
- 用户创作平台
- 登录页面
情况A：当前在发布页面
情况B：当前在用户创作平台
情况C：当前在登录页面
特殊情况：测试定时发布和发布
1. 执行测试操作
2. 截图保存结果
3. 用大模型视觉能力分析截图
4. 记录结果（成功/失败）
5. 重复测试至少3次验证可复现性
fill() 会清空所有内容，导致第一个标签被删除！应该用 keyboard.type() 追加内容！fill() 或 locator.fill() 方法！这两个方法都会清空现有内容，应该用 keyboard.type() 追加内容！核心原则：测试必须有明确的目标，不能盲目测试！
1. 查看之前总结的成功经验
2. 用 Browser Agent 按照经验执行
3. 重复测试至少3次验证可复现性
情况A：复现成功（3次都成功）
情况B：复现失败（有失败案例）
1. 记录所有失败的方案和原因
2. 分析可能的根本原因
3. **找用户帮忙解决**：
- 报告所有失败的尝试
- 提供详细的失败案例和截图
- 询问用户是否有其他思路或解决方案
1. 如果用户提供了解决方案：
- 用 Browser Agent 验证方案
- 重复测试3次确认可复现
- 更新 Skill 和发布脚本
2. 如果用户也无法解决：
- 记录为已知问题
- 标记为待后续研究
- 在 Skill 中注明限制条件
示例1：测试头条号标签选择
1. 查看已有经验：方案A（输入 `#游戏` → ↓ → Enter）
2. 用 Browser Agent 复现方案A：
- 第1次：✅成功
- 第2次：❌失败（标签是普通文本）
- 第3次：❌失败（标签是普通文本）
3. 得出结论：方案A不是可复现的成功经验，是概率事件
4. 继续测试其他方案（方案B、C、D）
5. 如果所有方案都失败：找用户帮忙解决
示例2：测试头条号标题填写
1. 查看已有经验：直接点击标题框输入
2. 用 Browser Agent 复现：
- 第1次：✅成功
- 第2次：✅成功
- 第3次：✅成功
3. 得出结论：这是可复现的成功经验
4. 写进 Skill 和发布脚本
示例1：测试头条号标签选择
1. 判断当前在哪：截图 → 视觉分析 → 发现在发布页面
2. 直接测试标签：
- 输入 `#游戏` → ↓ → Enter
- 截图 → 视觉分析 → 确认标签是否是蓝色高亮
- 重复3次验证可复现性
3. 记录结果
示例2：测试头条号标题填写
1. 判断当前在哪：截图 → 视觉分析 → 发现在发布页面
2. 直接测试标题：
- 点击标题框 → 输入标题
- 截图 → 视觉分析 → 确认标题是否正确填写
- 重复3次验证可复现性
3. 记录结果
示例3：测试头条号封面上传
1. 判断当前在哪：截图 → 视觉分析 → 发现在发布页面
2. 直接测试封面上传：
- 点击封面上传区 → 选择图片
- 截图 → 视觉分析 → 确认封面是否正确上传
- 重复3次验证可复现性
3. 记录结果
如何验证方案是可复现的？
# 验证流程
1. 用 Browser Agent 执行方案
2. 截图保存结果
3. **调用大模型视觉能力分析截图**（关键！）
4. 记录结果（成功/失败）
5. 重复步骤1-4，至少3次
6. 如果3次都成功：是可复现的成功经验
7. 如果有失败：不是可复现的，需要进一步研究
核心步骤：
#游戏 → 等待1.5秒.forum-list-item#游戏评测 → 等待1.5秒.forum-list-item验证结果：
#游戏# 显示为蓝色高亮（见截图 test_first_tag_final.png）# → 等待0.5秒（触发建议框）.forum-list-item↓ + Enter 方式为什么用 keyboard.type()？
keyboard.type() 是追加内容，不会清空现有内容fill() 或 locator.fill() 会清空现有内容，导致第一个标签被删除为什么要在两个标签之间加空格或换行？
# 能够触发下拉列表#游戏##游戏评测#），第二个 # 可能无法触发下拉列表如何输入标签？
# 触发建议框，然后输入文字
page.keyboard.type('#') # 单独输入 #，触发标签建议框（类似 IDE 代码补全）
time.sleep(0.5) # 等待建议框出现
page.keyboard.type('游戏') # 输入文字，在建议框中搜索
time.sleep(1.5) # 等待建议框更新
# 然后用 locator 点击第一项
first_option = page.locator('.forum-list-item').first
if first_option.count() > 0 and first_option.is_visible(timeout=2000):
first_option.click()
page.keyboard.type('#游戏')、JavaScript evaluate 等，会导致不一致！如何清理错误的标签？
#游戏 而不是 #游戏评测）：
#游戏 的左侧，使光标位于 #游戏 前面page.keyboard.press('Delete') → 这会删除光标右边的 #游戏#游戏评测 → 等待1.5秒.forum-list-item重要发现：
#游戏，而不是蓝色高亮的标签 #游戏#方案3_输入后.png 可以看到，输入 #游戏 后下拉列表确实出现了待测试方案：
# 输入 #游戏
page.keyboard.type('#游戏')
time.sleep(1.5) # 等待下拉列表出现
# 用 locator 定位并点击第一个选项
first_option = page.locator('.forum-list-item').first
if first_option.count() > 0 and first_option.is_visible(timeout=2000):
first_option.click()
time.sleep(0.5)
print("✅ 标签已选择")
verify_locator_after.png）#游戏# #游戏评测# 格式（不依赖自动选择）下一步行动：
图片池位置：f:/myclaw/multi-platform-automation/article_images/
.jpeg 和 .jpg 图片文件001a5ced.jpeg）解决方案：
# 步骤1：截图确认封面上传区域状态
await page.screenshot(path="f:/myclaw/test/debug_before_upload_cover.png")
# 步骤2：视觉分析封面上传区域
# - 确认当前选中的模式（单图/三图/无封面）
# - 找到上传按钮的位置
# - 记录提示文字
# 步骤3：点击封面上传区域
# 根据视觉分析的结果，找到正确的上传按钮并点击
# 可能的操作：
# - 点击"+"图标
# - 点击"选择封面"按钮
# - 点击"点击本地上传"链接
cover_upload_selector = 'div.cover-upload-area' # 需要根据实际页面调整
await page.click(cover_upload_selector)
await page.wait_for_timeout(2000) # 等待文件选择对话框打开
# 步骤4：上传测试图片
image_path = "f:/myclaw/multi-platform-automation/article_images/001a5ced.jpeg"
async with page.expect_file_chooser() as fc_info:
file_chooser = await fc_info.value
await file_chooser.set_files(image_path)
# 步骤5：等待上传完成
await page.wait_for_timeout(10000) # 等待10秒让图片上传和处理完成
# 步骤6：截图验证
await page.screenshot(path="f:/myclaw/test/debug_after_upload_cover.png")
# 步骤7：视觉分析验证结果
# - 确认封面是否成功上传
# - 确认是否显示预览图
# - 确认是否有错误提示
关键要点：
常见问题：
| 文件类型 | 位置 | 命名规则 |
|---------|------|---------||
| 测试脚本 | f:\myclaw\test\test_<目标>.py | test_ 前缀 |
| 调试截图 | f:\myclaw\test\debug_<步骤>_<时间戳>.png | debug_ 前缀（强制！） |
| 持久化用户目录 | f:\myclaw\multi-platform-automation\browser_data\cloak\{platform}\ | 平台名子目录 |
| 场景 | 推荐方案 | 原因 |
|---|---|---|
| 新脚本首次调试 | 方案1：逐步提取测试 | 系统性验证每步 |
| 脚本运行报错 | 方案2：Bug定位修复 | 精准定位问题 |
| 用户反馈问题 | 方案3：用户截图反馈 | 针对性解决 |
执行每步前确认：
执行每步后确认：
Browser Agent 调试的核心：
f:\myclaw\test\ 目录f:/myclaw/multi-platform-automation/article_images/⚠️ 效率陷阱（必须避免）：
✅ 正确做法：
记住：每一步都要经过你的眼睛确认，不要盲目执行！但也要保持连续性，不要反复重启！
| 特性 | Lingma 内置 Browser Agent | CloakBrowser + CDP |
|---|---|---|
| 可迁移性 | ❌ 仅限 Lingma | ✅ 可在任何 AI 工具中使用 |
| 反检测能力 | ❌ 普通 Chrome | ✅ CloakBrowser（源码级修改） |
| 持久化登录 | ⚠️ 有限支持 | ✅ 完整支持（独立用户目录） |
| 控制权 | ❌ 由 Lingma 控制 | ✅ 完全自主控制 |
| CDP 端口 | 自动管理 | 9222（固定，易于配置） |
# 在项目根目录执行
cd f:/myclaw/multi-platform-automation
pip install cloakbrowser playwright
# 启动已登录的浏览器
python f:/myclaw/test/start_logged_in_browser.py --platform baijia --url https://baijiahao.baidu.com/builder/rc/edit?type=news
在任何 AI 工具中都可以这样连接：
from playwright.sync_api import sync_playwright
# 连接到 CDP 端口 9222
playwright = sync_playwright().start()
browser = playwright.chromium.connect_over_cdp("http://localhost:9222")
# 复用已有上下文（重要！）
context = browser.contexts[0]
page = context.pages[0] if context.pages else context.new_page()
# 开始调试
page.screenshot(path="f:/myclaw/test/debug_start.png")
print(f"当前页面: {page.url}")
按照本 Skill 中的三种测试方案执行调试任务。
在 start_logged_in_browser.py 的终端中按 Ctrl+C。
Q1：为什么不能直接使用 Lingma 的 Browser Agent？
A：Lingma 的 Browser Agent 是专有的，只能在 Lingma 中使用。通过 CDP 连接到 CloakBrowser，可以在任何支持 Playwright 的 AI 工具中使用（Cursor、Claude Code、GitHub Copilot 等）。
Q2：CloakBrowser 和普通 Playwright 有什么区别？
A：CloakBrowser 是源码级修改的 Chromium，彻底消除了自动化特征（navigator.webdriver、Canvas 指纹等），30/30 通过所有机器人检测测试，适合需要反检测的场景（如百家号、头条号等平台）。
Q3：如何验证反检测效果？
A：访问 https://bot.sannysoft.com/ 或 https://abrahamjuliot.github.io/creepjs/，查看检测结果。
Q4：如果 CloakBrowser 不可用怎么办？
A：browser_automation.py 中有降级方案，会自动切换到普通 Playwright。但建议优先使用 CloakBrowser。
Q5：如何在其他 AI 工具中使用这个 Skill？
A：将本 Skill 文件复制到目标 AI 工具的 Skills 目录中，然后按照上述步骤操作即可。核心是通过 CDP 连接到 CloakBrowser，与具体的 AI 工具无关。
症状：
UnicodeEncodeErrorUnicodeEncodeError: 'gbk' codec can't encode character '\u2705'根本原因：
sys.stdout 和 sys.stderr 默认编码可能仍是 GBKlogging.StreamHandler() 使用 sys.stdout，导致输出时编码不匹配在所有 Python 脚本开头添加以下代码（必须在 logging 配置之前）：
import sys
# 确保标准输出使用 UTF-8 编码（Windows 专用）
if sys.platform == 'win32':
import io
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')
logging 配置示例：
import logging
# 配置日志
logging.basicConfig(
level=logging.INFO,
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
handlers=[
logging.FileHandler('app.log', encoding='utf-8'), # 文件也要指定 UTF-8
logging.StreamHandler(sys.stdout) # 使用 sys.stdout
]
)
logger = logging.getLogger('my_app')
# 现在可以安全使用表情符号
logger.info("✅ 初始化成功")
logger.warning("⚠️ 警告信息")
logger.error("❌ 错误信息")
测试脚本：
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
import sys
import logging
# Windows UTF-8 配置
if sys.platform == 'win32':
import io
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')
# 配置日志
logging.basicConfig(
level=logging.INFO,
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
stream=sys.stdout
)
logger = logging.getLogger('test_emoji')
logger.info("✅ 测试成功：可以使用表情符号")
logger.info("❌ 测试失败标记")
logger.info("⚠️ 测试警告标记")
logger.info("🎉 测试庆祝标记")
预期输出：
2026-05-20 12:05:25,005 - test_emoji - INFO - ✅ 测试成功：可以使用表情符号
2026-05-20 12:05:25,006 - test_emoji - INFO - ❌ 测试失败标记
2026-05-20 12:05:25,006 - test_emoji - INFO - ⚠️ 测试警告标记
2026-05-20 12:05:25,006 - test_emoji - INFO - 🎉 测试庆祝标记
❌ 错误做法1：只在 logging 配置中指定 encoding='utf-8'
# 这样还不够！
logging.basicConfig(
handlers=[
logging.StreamHandler() # 没有指定 sys.stdout
]
)
❌ 错误做法2：忘记在脚本开头设置 UTF-8
import logging
# 直接配置 logging，没有先设置 sys.stdout
logging.basicConfig(stream=sys.stdout) # sys.stdout 可能还是 GBK
✅ 正确做法：先设置 sys.stdout，再配置 logging
import sys
if sys.platform == 'win32':
import io
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')
import logging
logging.basicConfig(stream=sys.stdout) # 现在 sys.stdout 是 UTF-8
需要添加 UTF-8 配置的场景：
logging 模块的 Python 脚本不需要添加的场景：
记住这个顺序：
sys 和 iosys.platform == 'win32'sys.stdout 和 sys.stderrlogging（此时 sys.stdout 已经是 UTF-8）关键原则：
encoding='utf-8'当前方案的问题：
navigator.webdriver=true、Headless Chrome 标识等CloakBrowser 的优势：
CloakBrowser（推荐）
pip install cloak-browserfrom cloak_browser import CloakBrowser
browser = CloakBrowser.launch()
page = browser.new_page()
page.goto("https://example.com")
Obscura
其他相关项目:
项目中已创建 utils/cloak_browser_adapter.py，提供与 Playwright 兼容的 API：
from utils.cloak_browser_adapter import CloakBrowserAdapter
adapter = CloakBrowserAdapter()
browser = adapter.launch(headless=False)
page = browser.new_page()
page.goto("https://mp.toutiao.com/")
优势:
下一步行动:
pip install cloakbrowserutils/cloak_browser_adapter.pyrequirements.txt（包含所有依赖）.env 文件（指定缓存目录到项目内）.gitignore 文件（排除敏感文件和缓存）DEPLOYMENT.md 部署指南f:/myclaw/.cloakbrowser_cache/BrowserAutomation(platform='toutiao') 会自动加载 toutiao_auth_state.json