From 5ed9eb9c7601af5da1418f9e52b0f654af6680ac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E6=A2=93=E5=B3=B0?= <1805827169@qq.com> Date: Tue, 3 Nov 2026 23:38:31 +0800 Subject: [PATCH] docs(skill): clarify observation and overlay recovery --- crates/bsk-cli/skill/references/cooperation.md | 3 +++ crates/bsk-cli/skill/references/help-and-recovery.md | 1 + 2 files changed, 4 insertions(+) diff --git a/crates/bsk-cli/skill/references/cooperation.md b/crates/bsk-cli/skill/references/cooperation.md index 23b8aa8d3..36a108f73 100644 --- a/crates/bsk-cli/skill/references/cooperation.md +++ b/crates/bsk-cli/skill/references/cooperation.md @@ -32,6 +32,9 @@ is replayed to wait for success. Untargeted keys, visual clicks and other action retain strict observation checks. For these, pass `--observation ID` from the sync alongside `--context ID`. Supplementary reads do not replace that strict baseline. Read the returned evidence before choosing the operation; sync again for the next strict action. +Under target policy, every successful sync returns a new top-level receipt, including +`kind: "unchanged"`. Sync again after a refused or failed untargeted attempt too, and +inspect the new evidence before choosing the next action. Prefer a targeted key, such as `press Enter --ref @e3`, when the intended recipient is known. Scripts have their own rules; see [Scripts](#scripts). diff --git a/crates/bsk-cli/skill/references/help-and-recovery.md b/crates/bsk-cli/skill/references/help-and-recovery.md index 7c4d04576..8ed6b8675 100644 --- a/crates/bsk-cli/skill/references/help-and-recovery.md +++ b/crates/bsk-cli/skill/references/help-and-recovery.md @@ -30,6 +30,7 @@ substring is enough. | Help `cancelled` / `timed_out` | Respect rejection or the blocker; do not repeat the request. | | Help `disabled` | No human action was confirmed. Re-observe and follow the disabled-help rules below. | | Stale ref or target failure | Inspect the live target and choose the appropriate action. A missing, hidden or covered target is not evidence of human takeover. | +| `Could not clear the extension overlay from the click point` | The extension's control UI may cover the intended target. Temporarily turn off **Control hints** in the extension popup, then sync and inspect that same target before retrying. A page mask reported by VOM is separate from the extension overlay and may still block the action. | | `precondition_failed` | Compare `target`, `field`, `expected` and `actual`, then reconsider the decision. A new context does not make the expected value true. | | Control revoked | Wait while the person is active, then sync and reconcile completed steps. | | Unknown tab/session | List current tabs/sessions; never guess IDs or use another task's session. |