现象 / Symptom
在内容型网站（我们这边复现于小红书）上，shared_browser_click 点击一个被浮层/悬浮组件遮挡的元素时，调用不会快速失败，而是挂起直到网关返回 504 timeout。对 agent 侧来说，一次点击要等满整个超时窗口才知道失败，而且拿到的是网关错误，看不出"元素被遮挡"这个真实原因。
When the target element is covered by an overlay (floating login prompt, image viewer mask, sticky bar — reproduced on xiaohongshu.com), shared_browser_click hangs until the gateway returns a 504 instead of failing fast. The agent burns the whole timeout window and receives a gateway error that says nothing about the real cause (obstructed element).
复现 / Repro
- 打开一个有悬浮遮罩的页面（例：小红书帖子页，登录提示浮层出现时）
shared_browser_snapshot 取到目标元素 ref（元素在快照里存在且可见）shared_browser_click 该 ref- 等待 ~数十秒后收到 504；页面上点击并未生效
目前的绕法 / Current workaround
- 跳过点击：
shared_browser_open 直接携 URL 导航
- 输入类交互改用
shared_browser_type 对 contenteditable 灌字 + press Enter
能用，但等于放弃了"和人共用一双手"里点击这半只手。
建议 / Suggestions
- 快速失败：click 执行前用
elementFromPoint（或 Playwright 的 actionability 检查结果）判断命中点是否被其他元素接收，若被遮挡立即返回结构化错误（如 {error: "obstructed", covered_by: <selector>}），不要等到网关超时。
- 错误透传：把 Playwright 侧的真实失败原因（
element is not receiving pointer events 等）带回 MCP 响应，而不是让上层只看到 504。
- （可选）提供
force 或 dismiss_overlay_hint 之类的显式选项，让 agent 自己决定下一步，而不是盲重试。
感谢这个项目——"一扇窗、两双手"的设计我们家每天都在用。
Thanks for the project — we use the "one window, two sets of hands" design daily.
现象 / Symptom
在内容型网站（我们这边复现于小红书）上，
shared_browser_click点击一个被浮层/悬浮组件遮挡的元素时，调用不会快速失败，而是挂起直到网关返回 504 timeout。对 agent 侧来说，一次点击要等满整个超时窗口才知道失败，而且拿到的是网关错误，看不出"元素被遮挡"这个真实原因。When the target element is covered by an overlay (floating login prompt, image viewer mask, sticky bar — reproduced on xiaohongshu.com),
shared_browser_clickhangs until the gateway returns a 504 instead of failing fast. The agent burns the whole timeout window and receives a gateway error that says nothing about the real cause (obstructed element).复现 / Repro
shared_browser_snapshot取到目标元素 ref（元素在快照里存在且可见）shared_browser_click该 ref目前的绕法 / Current workaround
shared_browser_open直接携 URL 导航shared_browser_type对 contenteditable 灌字 +press Enter能用，但等于放弃了"和人共用一双手"里点击这半只手。
建议 / Suggestions
elementFromPoint（或 Playwright 的 actionability 检查结果）判断命中点是否被其他元素接收，若被遮挡立即返回结构化错误（如{error: "obstructed", covered_by: <selector>}），不要等到网关超时。element is not receiving pointer events等）带回 MCP 响应，而不是让上层只看到 504。force或dismiss_overlay_hint之类的显式选项，让 agent 自己决定下一步，而不是盲重试。感谢这个项目——"一扇窗、两双手"的设计我们家每天都在用。
Thanks for the project — we use the "one window, two sets of hands" design daily.