From f96bd72c3c3eb935466a88e0799e4285cd6810f9 Mon Sep 17 00:00:00 2001 From: xiyanjun <443951564@qq.com> Date: Fri, 28 Aug 2026 18:02:38 +0800 Subject: [PATCH] docs(skill): clarify bsk evaluate exit-code vs --json .ok semantics The exit code reflects RPC success only, not JS success. Document that programmatic callers must use --json and check the .ok field to detect JS errors. Addresses the discoverability gap raised in issue #133. --- crates/bsk-cli/skill/SKILL.md | 4 ++-- skill/SKILL.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/crates/bsk-cli/skill/SKILL.md b/crates/bsk-cli/skill/SKILL.md index d6dd1e2e..8b18ffbd 100644 --- a/crates/bsk-cli/skill/SKILL.md +++ b/crates/bsk-cli/skill/SKILL.md @@ -210,7 +210,7 @@ Both capture from the moment the tab is attached and read a bounded per-tab buff | Command | Summary | |---------|---------| -| `bsk evaluate ` | Run JS in agent tab (see red lines); JS throw → stderr, **exit 0** | +| `bsk evaluate ` | Run JS in agent tab (see red lines). JS throw → stderr, **exit 0** (RPC success); use `--json` and check `.ok` to detect JS errors | | `bsk wait-for-navigation` | Block until load/DOM idle/etc. (`--wait-until`, `--timeout`) | | `bsk wait-ms ` | Sleep (`500ms`, `2s`, `1m`; **no** `--session`) | @@ -294,7 +294,7 @@ bsk record stop [--output trace] # terminal fallback if the browser panel is u | Code | Meaning | What to do | |------|---------|------------| -| `0` | Success (including `evaluate` where JS threw but RPC succeeded) | Continue | +| `0` | Success (including `evaluate` where JS threw but RPC succeeded) | Continue; for `evaluate`, check `--json` `.ok` to distinguish JS success from RPC success | | `1` | User error — bad args, unknown session, tab not in Agent Window, stale ref | Fix args; `bsk session list`; re-snapshot | | `2` | Protocol / transport — service unreachable, IPC failure | `bsk doctor`; check extension connected; retry the command | | `3` | Browser / CDP execution failed | Retry; simplify selector; check tab still open | diff --git a/skill/SKILL.md b/skill/SKILL.md index d6dd1e2e..8b18ffbd 100644 --- a/skill/SKILL.md +++ b/skill/SKILL.md @@ -210,7 +210,7 @@ Both capture from the moment the tab is attached and read a bounded per-tab buff | Command | Summary | |---------|---------| -| `bsk evaluate ` | Run JS in agent tab (see red lines); JS throw → stderr, **exit 0** | +| `bsk evaluate ` | Run JS in agent tab (see red lines). JS throw → stderr, **exit 0** (RPC success); use `--json` and check `.ok` to detect JS errors | | `bsk wait-for-navigation` | Block until load/DOM idle/etc. (`--wait-until`, `--timeout`) | | `bsk wait-ms ` | Sleep (`500ms`, `2s`, `1m`; **no** `--session`) | @@ -294,7 +294,7 @@ bsk record stop [--output trace] # terminal fallback if the browser panel is u | Code | Meaning | What to do | |------|---------|------------| -| `0` | Success (including `evaluate` where JS threw but RPC succeeded) | Continue | +| `0` | Success (including `evaluate` where JS threw but RPC succeeded) | Continue; for `evaluate`, check `--json` `.ok` to distinguish JS success from RPC success | | `1` | User error — bad args, unknown session, tab not in Agent Window, stale ref | Fix args; `bsk session list`; re-snapshot | | `2` | Protocol / transport — service unreachable, IPC failure | `bsk doctor`; check extension connected; retry the command | | `3` | Browser / CDP execution failed | Retry; simplify selector; check tab still open |