docs: 补充 strict observation 的发放条件与扩展悬浮层遮挡的排查说明

Aperta Adatta ai principianti
  • Qualcosa non va?
#551 3 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

@Wang-MuFF ci sta già lavorando.

Dal 3/11/2026.

  • #564 di @Wang-MuFF — aperta

Valutazione

Difficoltà
2/5
Tempo stimato
1-3 ore
Idoneità per principianti
75/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Ambito
documentation

Direzione di ricerca

Inizia da references/cooperation.md, dove si trova la frase sulle osservazioni strict, e da references/help-and-recovery.md, la cui lista Recover non ha alcuna voce relativa all'overlay dell'estensione. Riproduci la sequenza di sincronizzazione baseline/unchanged descritta nell'issue per confermare la formulazione. Il lavoro è completo quando in ciascun file è aggiunta una frase che indica quando vengono emesse le osservazioni strict e cosa fare in caso di errore nel clic sull'overlay.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

环境
  • @wxg-prc-cpg/browser-skill-dsh-plugin 0.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 ...)

复现步骤：

  1. bsk_session start → sync（baseline，拿到可用凭证）
  2. 任意 ref 点击（消耗凭证）
  3. 再 sync → 返回 kind: "unchanged" + 新的 observation_id
  4. 把步骤 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 句应能显著减少无效重试。

Lingua principale
TypeScript
Stelle
10.1k
Fork
732
Merge medio
2g 2h
PR unite (30g)
92

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di Tencent/BrowserSkill

Tutte le issue di Tencent/BrowserSkill

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.