Repository navigation
docs: 补充 strict observation 的发放条件与扩展悬浮层遮挡的排查说明 #551
Description
环境
@wxg-prc-cpg/browser-skill-dsh-plugin0.4.0（扩展报 0.4.1）- Chrome 156 / macOS，页面 viewport 1920x907（uni-app H5）
问题一：strict observation 的"发放条件"未文档化
references/cooperation.md 里有这句：
Scripts, untargeted keys and visual clicks require this sync's observation_id
and retain strict content checks.
所以"脚本/视觉动作需要凭证"是写了的，但没写什么时候 sync 才会产出这个凭证。
实测：只有页面内容实际变化后的那次 sync 返回 kind: "baseline" 并发放可用的 strict
observation；此后反复 sync 都返回 kind: "unchanged"，即使把该次返回的
observation_id 显式传给 wheel / evaluate / reload / resize，仍报：
This action requires an unused strict observation from cooperate sync
(hint: Synchronize, inspect the result and pass its observation_id explicitly ...)
复现步骤：
bsk_session start→sync（baseline，拿到可用凭证）- 任意 ref 点击（消耗凭证）
- 再
sync→ 返回kind: "unchanged"+ 新的observation_id - 把步骤 3 的
observation_id传给bsk_interact(action="wheel")→ 上述报错
后果：调用方很容易陷入「sync → 报错 → 再 sync → 再报错」的循环（本人实测绕了 4~5 轮）。
建议在 cooperation.md 补一句，例如：
只有 baseline sync 会发放 strict observation。
kind: "unchanged"的 sync 返回的
observation_id不能用于脚本/视觉类动作；遇到该报错请改用 ref 点击，或等待页面内容
变化后重新 sync。
问题二：扩展悬浮层遮挡导致点击失败，文档无说明
当目标控件位于视口右下角（本例为卡片标题行最右端的图标，落点约 1707, 860 @ 907 高），
bsk_interact(action="click") 报：
Could not clear the extension overlay from the click point
references/help-and-recovery.md 全文没有 overlay 相关内容，只有兜底的
"Other errors: follow the hint"；而本次 hint 是 "Inspect the reported target"，
对"扩展自身悬浮层遮挡"指向性不足（目标本身完全正常，只是被 HUD 压住）。
已确认可行的绕过：改点同类、但会先被滚动到视口中间的兄弟元素。本例改成点下一张卡片的
同类图标，工具自动滚动后落点 y≈453，点击成功。
建议在 help-and-recovery.md 的 Recover 列表补一条：
点击落点位于视口右下角并报 extension overlay 时，改用会被滚动到视口中间的同类目标，
或先滚动页面再点击。
说明
两条都属于文档缺失，不涉及实现缺陷；各补 1~2 句应能显著减少无效重试。
Activity
FenrirCait commentedon Nov 2, 2026
补充一份 0.4.1 全对齐环境下的实测：问题一未复现，但另有两条使用约束值得写进
references/cooperation.md。环境
@wxg-prc-cpg/browser-skill-dsh-plugin0.4.1version_skew: false注意本单原帖是「插件 0.4.0 + 扩展 0.4.1」的混合版本；0.4.1 的发布说明明确写了不要依赖混合版本连接，下面的差异可能就来自这里。
问题一：
kind: "unchanged"的顶层 observation_id 在 0.4.1 上是可用的复现路径：
bsk_session start→ sync 返回kind: "baseline"，context9a8b6b4e…deltaY 900（消耗该次凭证）→ 页面正常滚动kind: "unchanged"，顶层observation_id: 91697c3e…91697c3e…传给evaluate（同时带 context）→ 成功，返回{y: 0, h: 11459, vh: 773}所以「只有 baseline sync 才发放可用凭证」这条，在 0.4.1 全对齐的环境里没有复现。不确定是版本差异还是别的条件，仅作反例记录。
两条真实约束
① 非定向动作要同时给 context 和顶层 observation_id。
observation_id→requires a valid control context from cooperate syncrequires an unused strict observation from cooperate syncnavigate、evaluate、wheel均验证）② 一次 sync 只够一个非定向动作，失败也算消费。
同一 id 第二次使用报
The strict observation changed before this action，必须重新 sync。这条与 #547 说的「回复里有两个 observation_id、容易传错」叠加，很容易陷入 sync→报错→再 sync→再报错的循环。③ 传
observation.observation_id（ref 映射那个）会被拒，而提示不说明该用哪个。 正是 #547 要修的点，改成「用顶层 observation_id」就清楚了。另一个现象（可能与 #545 同源）
在带自动播放预览视频的页面（B 站热门页）上，滚轮报
The media source changed; synchronize and replan；换静态页面（Wikipedia）即正常，两个方向都能滚。另：
scroll-to对无可见区域的元素（Wikipedia 的 "Jump to content" 跳过链）报scroll-to target has no visible area是合理的，不算缺陷。NianJiuZst commentedon Nov 3, 2026
hecked against the 0.4.1 sources (b8f2d4f) and verified with unit tests:
Problem 1: the rule doesn't hold; the loop is version skew. Every sync, including unchanged, issues a new top-level observation_id (controller.ts#L717-L730), matching FenrirCait's result. The original setup was plugin 0.4.0 + CLI/extension 0.4.1: plugin 0.4.0 can't send observationId, while CLI 0.4.1 defaults to target policy (cooperate.rs#L89), so untargeted actions always get observation_required. The 0.4.1 upgrade order (CLI → extension → plugin) passes through this state. Suggestion: a dedicated error when the id is missing (check plugin ≥ 0.4.1), rather than the proposed doc change.
FenrirCait's notes: ① both context and top-level id are required — confirmed. ② one receipt per untargeted action, refusals consume it — confirmed, but reuse returns observation_required; observation_changed is the error when the page changed. ③ nested observation.observation_id is not the receipt — confirmed (#547). Also, a refused untargeted action revokes the whole context (controller.ts#L1236), so ref actions need a new sync too, which amplifies the loop.
"The media source changed": the pre-input media check (controller.ts#L1220-L1227); adding/removing an iframe triggers it too (data.reason: document_changed). Unrelated to #545. Workaround: pass a target ref to wheel; targeted actions skip this check. @FenrirCait, could you share the data.reason?
Problem 2: an implementation defect. In cooperation mode the bottom-right toolbar (300px wide, overlay.css#L51-L63) isn't covered by input passthrough (overlay.css#L18-L25), and scrollIntoViewIfNeeded doesn't move an already-visible target, so elements under the toolbar can't be clicked; the reported point (1707, 860) is inside it. Workaround: turn off "Control hints" in the extension popup.
SAXEM1997 commentedon Nov 3, 2026
补一个真实案例，供排查参考（全 0.4.1 对齐，排除版本错配）：
环境：bsk CLI/daemon 0.4.1 · 扩展 0.4.1 ·
@wxg-prc-cpg/browser-skill-dsh-plugin0.4.1 · protocol 1.8 · DSH；站点是内部 ATS（Moka 控制台，SPA，已登录）。现象：
bsk step --action click --params '{"ref":"@e1"}'返回{"code":"cdp_failed", "data":{"effect_state":"none","phase":"execution","pointer_moved":false,"reason":"input_not_ready"}, "exit_code":3,"message":"Could not clear the extension overlay from the click point"}, "elapsed_ms":134,"rpc_calls":1同一回合 VOM 是
@view 825x687+L1 mask cover=100%，但遮罩里只有站点自己的文本（"网络较慢,请耐心等待..."、用户水印）。按overlay-bridge.ts的约定 VOM 会跳过browser-skill-overlay宿主，所以 VOM 那层 mask 是站点自己的，点击报错那层是 bsk 的——两层叠在一起，回执里分不出是哪层挡住、在哪个点。和 Problem 2 的关系：很可能就是同一条（右下角 300px 工具栏不在 passthrough 覆盖内）。但回执没有点击坐标、也没有命中元素，我无法确认落点是否落在工具栏上；这正对应我另开的 #556（请求补 hit-test 诊断信息）。
额外一个坑：该站点在窄视口会弹「建议调整窗口大小」的全屏提示层，本想先放大窗口规避，但
bsk window resize --width 1600 --height 1000返回成功、@view仍为 825x687（另见 #557），这条路也堵死了。下次会先按 Problem 2 的 workaround（在扩展弹窗里关掉 Control hints）复验，结果回帖。