npm - @omniaibot/win-x64 - Versions diffs - 1.6.5 → 1.6.7 - Mend

@omniaibot/win-x64 1.6.5 → 1.6.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (46) hide show

package/bin/omnibot-windows-x64/omnibot/skills/omnibot/references/operation-patterns.md CHANGED Viewed

@@ -1,432 +1,432 @@
-# Operation Patterns
-Use this file to choose behavior by task. Every page-state workflow must set `OMNIBOT_SESSION_TOKEN=<workflow-name>` and pass `--tab-id <TAB_ID>` on each page-state command.
-## Read
-### When to use
-Use Read when the agent needs clean rendered page content: article text, search results, feed items, long pages, lazy-loaded text, or a human-readable summary source.
-Use targeted state commands when the agent needs one value, visibility, enabled/checked state, layout box, or computed styles. Use `snapshot -i` when the agent needs current visible UI structure for deciding the next action.
-### Preferred sequence
-1. `read --tab-id <TAB_ID>` for clean page text on an existing tab.
-2. `read --screens N --tab-id <TAB_ID>` for longer or lazy-loaded pages.
-3. `read <URL>` when opening a temporary tab only for reading that URL.
-4. `get title/url/text/html/value/attr/count/box/styles` for narrow evidence.
-5. `is visible/enabled/checked` for boolean state.
-5. `snapshot -i` when actionable refs are needed.
-6. `dom visible` or `execute-js` fallback only after standard reads cannot access the state.
-### Example
-```bash
-OMNIBOT_SESSION_TOKEN=research omnibot read --screens 5 --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot read --screens 3 https://example.com/article
-```
-### Verification
-Use the narrowest read that proves the claim:
-```bash
-OMNIBOT_SESSION_TOKEN=research omnibot get title --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot is visible "#main" --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot get count ".result" --tab-id <TAB_ID>
-```
-### Fallback entry point
-If `read` or targeted reads omit needed runtime state, go to `fallback-operations.md#fallback-tier-model`. Start with DOM fallback before JavaScript.
-## Click
-### When to use
-Use Click for buttons, links, menu items, cards, checkouts, modal actions, and any user-like click target.
-### Preferred sequence
-1. `find role/text/testid --action click`
-2. `snapshot -i` -> `click @eN`
-3. `click selector`
-4. `dom click`
-5. `mouse click`
-6. `execute-js` click
-7. `cdp` fallback
-### Example
-```bash
-OMNIBOT_SESSION_TOKEN=checkout omnibot snapshot -i --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=checkout omnibot find role button --name "Submit" --action click --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=checkout omnibot wait --url "/dashboard" --tab-id <TAB_ID>
-```
-If semantic find is ambiguous, use refs from the same tab:
-```bash
-OMNIBOT_SESSION_TOKEN=checkout omnibot snapshot -i --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=checkout omnibot click --tab-id <TAB_ID> @e4
-OMNIBOT_SESSION_TOKEN=checkout omnibot snapshot -i --tab-id <TAB_ID>
-```
-### Verification
-Verify the expected state, not just command success:
-```bash
-OMNIBOT_SESSION_TOKEN=checkout omnibot get url --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=checkout omnibot is visible ".success" --tab-id <TAB_ID>
-```
-### Fallback entry point
-If semantic and refs fail, document why and continue at `fallback-operations.md#selector-fallback`.
-### Static-text refs
-When `snapshot -i` shows only `StaticText` for a visible control label, do not assume the text ref itself is clickable. Prefer, in order:
-1. `find role button --name "<label>" --action click`.
-2. `click "text=<label>"`.
-3. `get box "text=<label>"` followed by `mouse click <center-x> <center-y>`.
-4. CDP/JS fallback only after verifying the semantic and coordinate paths failed.
-## Fill
-### When to use
-Use Fill for text inputs, textareas, search boxes, login fields, form fields where the final value must be controlled, and rich text article body editors (contenteditable ProseMirror/Quill/Draft.js/Slate/Toutiao article body).
-### Preferred sequence
-1. `find label/placeholder --action fill`
-2. `snapshot -i` -> `fill @eN`
-3. `fill selector`
-4. `focus` + `type`
-5. `execute-js` set value and dispatch `input`/`change` events
-### Example
-```bash
-OMNIBOT_SESSION_TOKEN=checkout omnibot find label "Email" --action fill --action-value "a@b.com" --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=checkout omnibot get value "input[name=email]" --tab-id <TAB_ID>
-```
-With refs:
-```bash
-OMNIBOT_SESSION_TOKEN=checkout omnibot snapshot -i --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=checkout omnibot fill --tab-id <TAB_ID> @e2 "a@b.com"
-OMNIBOT_SESSION_TOKEN=checkout omnibot get value "input[name=email]" --tab-id <TAB_ID>
-```
-### Rich text article body
-For article body editors exposed as `@eN [richtext] "..." [contenteditable=true]` under `# DOM Rich Text Editors`:
-```bash
-OMNIBOT_SESSION_TOKEN=editor omnibot snapshot -i --tab-id <TAB_ID>
-# Body appears under "# DOM Rich Text Editors": @eN [richtext] "..."
-OMNIBOT_SESSION_TOKEN=editor omnibot fill --tab-id <TAB_ID> @eN "First paragraph.\n\nSecond paragraph."
-OMNIBOT_SESSION_TOKEN=editor omnibot snapshot -i --tab-id <TAB_ID>  # verify body content replaced
-```
-- `\n\n` splits paragraphs; previous content is cleared.
-- `type @richtext " text"` appends at the cursor (click the ref first to focus).
-- Do NOT write the article body into a `[textbox]` title field. Title and richtext body are separate refs.
-### Verification
-Use `get value`, visible validation text, enabled state, or submit readiness:
-```bash
-OMNIBOT_SESSION_TOKEN=checkout omnibot get value "input[name=email]" --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=checkout omnibot is enabled "button[type=submit]" --tab-id <TAB_ID>
-```
-For richtext bodies, re-run `snapshot -i` and confirm the `@eN [richtext]` name matches the intended content.
-### Cursor positioning and inline image insertion
-For `contenteditable` article bodies (ProseMirror/Quill/Draft.js/Slate/Toutiao article body), `find text "<anchor phrase>" --action click` collapses the editor selection at the end of the matched phrase and focuses the editor. Use this to place the caret at a specific paragraph before inserting an image, typing, or pressing keys. Do not rely on a bare `click` of the editor followed by `press End`, because the caret would stay on the first line.
-Insert an image after a specific paragraph:
-```bash
-OMNIBOT_SESSION_TOKEN=editor omnibot find text "第二段锚点文字" --action click --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=editor omnibot click ".syl-toolbar-tool.image .syl-toolbar-button" --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=editor omnibot wait --selector ".upload-image-panel input[type=file]" --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=editor omnibot upload ".upload-image-panel input[type=file]" "/path/to/image.png" --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=editor omnibot find role button --name "确定" --action click --tab-id <TAB_ID>
-```
-Verify the inserted image by counting visible image cards, not raw `<img>` nodes. Toutiao/ProseMirror image cards keep a hidden `<templ>` template and a visible `<mask>` copy of the same `<img>`, so `.ProseMirror img` returns 2 for one logical image. Count the image card container instead (e.g. `.ProseMirror [__syl_tag=true]` or `.ProseMirror .pgc-image`), which reports one per inserted image.
-### Fallback entry point
-If fill does not update the application state, use `fallback-operations.md#javascript-fallback` only after selector/focus/type attempts fail. JavaScript must dispatch real `input` and `change` events.
-## Select / Check
-### When to use
-Use this pattern for dropdowns, comboboxes, checkboxes, toggles, agreement boxes, filters, and boolean controls.
-### Preferred sequence
-1. Use `snapshot -i` first; visible comboboxes may include auto-probed option refs.
-2. Use `click @option` if `snapshot -i` lists auto-probed combobox option refs.
-3. Use `select @combobox "value"` for native selects or simple select-like controls.
-4. Use `check` / `uncheck` for boolean controls.
-5. Verify selected label, value, URL query, result count, or dependent page state.
-`snapshot -i` can list options for visible custom comboboxes even though the dropdown closes during observation. These refs are still actionable because Omnibot stores the option's `openerSelector` and can reopen the owning combobox before clicking the option.
-### Example
-```bash
-OMNIBOT_SESSION_TOKEN=form omnibot snapshot -i --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=form omnibot click @e22 --tab-id <TAB_ID>  # @e22 [option] "OpenAI Chat"
-OMNIBOT_SESSION_TOKEN=form omnibot get url --tab-id <TAB_ID>
-```
-Checkbox example:
-```bash
-OMNIBOT_SESSION_TOKEN=form omnibot is checked "#agree" --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=form omnibot check "#agree" --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=form omnibot is checked "#agree" --tab-id <TAB_ID>
-```
-### Verification
-For checkboxes, verify boolean state. For selects, verify value or dependent page state.
-### CSS-only dropdowns and custom menus
-Some dropdowns, hover menus, tooltips, and custom selects are CSS-only or portal-based widgets. The visible trigger may be accessible, while the option nodes are hidden `<div>` elements without `role`, accessible name, or stable refs. Start with `snapshot -i`; visible comboboxes may include auto-probed option refs before any manual dropdown opening.
-Escalation order:
-1. Run `snapshot -i` and look for `[option]` refs near the combobox.
-2. If an option ref exists, click the option ref directly and verify.
-3. If options are absent, click/hover the trigger once, run `snapshot -i` again, then click the option ref if it appears.
-4. If trigger interaction works but options remain absent or option refs fail verification, use `fallback-operations.md#css-only-dropdown-javascript-fallback`.
-Do not loop on manual open -> snapshot -> open -> snapshot when `snapshot -i` already lists auto-probed combobox options.
-### Fallback entry point
-If native select/check fails, use `fallback-operations.md#selector-fallback`. Use JavaScript only if events must be synthesized or if evidence shows a CSS-only multi-step widget cannot be completed through semantic, snapshot, selector, DOM, or mouse tiers.
-## Navigation
-### When to use
-Use Navigation to open pages, create tabs, change history, reload, close tabs, move between pages, create windows, or select frames.
-### Preferred sequence
-1. Create or discover a tab with `tabs`, `tab list`, `tab new`, `open`, or `navigate`.
-2. Save the returned tab id.
-3. Verify with `get url --tab-id <TAB_ID>`.
-4. Run all later page-state commands with `--tab-id <TAB_ID>`.
-### Example
-```bash
-OMNIBOT_SESSION_TOKEN=research omnibot tab new https://example.com --label research
-OMNIBOT_SESSION_TOKEN=research omnibot get url --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot snapshot -i --tab-id <TAB_ID>
-```
-History and lifecycle:
-```bash
-OMNIBOT_SESSION_TOKEN=research omnibot back --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot get url --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot forward --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot get url --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot reload --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot wait --load domcontentloaded --tab-id <TAB_ID>
-```
-Other navigation commands:
-```bash
-OMNIBOT_SESSION_TOKEN=research omnibot navigate https://example.com
-OMNIBOT_SESSION_TOKEN=research omnibot navigate https://example.com --same-tab --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot open https://example.com
-OMNIBOT_SESSION_TOKEN=research omnibot goto https://example.com --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot pushstate /dashboard --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot close <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot tab list
-OMNIBOT_SESSION_TOKEN=research omnibot tab close research
-OMNIBOT_SESSION_TOKEN=research omnibot window new
-OMNIBOT_SESSION_TOKEN=research omnibot frame main
-```
-### Verification
-Always verify the final target:
-```bash
-OMNIBOT_SESSION_TOKEN=research omnibot get url --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot wait --load networkidle --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot snapshot -i --tab-id <TAB_ID>
-```
-### Fallback entry point
-Same-tab navigation must include `--tab-id <TAB_ID>`. If the target tab id is unknown, run `omnibot tabs` first and choose the intended tab explicitly.
-## Wait
-### When to use
-Use Wait after navigation, clicks, form submissions, reloads, dynamic rendering, lazy loading, or any action that changes asynchronous state.
-### Preferred sequence
-1. Wait for selector visibility or hidden state.
-2. Wait for text.
-3. Wait for URL.
-4. Wait for load state.
-5. Wait for a JavaScript condition with `--fn`.
-6. Avoid shell sleep.
-### Example
-```bash
-OMNIBOT_SESSION_TOKEN=checkout omnibot click --tab-id <TAB_ID> @e4
-OMNIBOT_SESSION_TOKEN=checkout omnibot wait "#spinner" --state hidden --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=checkout omnibot wait --text "Welcome" --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=checkout omnibot get text "#main" --tab-id <TAB_ID>
-```
-Other waits:
-```bash
-OMNIBOT_SESSION_TOKEN=checkout omnibot wait --url "/dashboard" --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=checkout omnibot wait --load domcontentloaded --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=checkout omnibot wait --load networkidle --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=checkout omnibot wait --fn "window.appReady === true" --tab-id <TAB_ID>
-```
-### Verification
-After waiting, read the final condition with `get`, `is`, `wait`, or `snapshot`.
-### Fallback entry point
-If waits time out, collect evidence with `debugging-and-evidence.md`; do not replace them with shell sleep.
-## Extraction
-### When to use
-Use Extraction for retrieving page text, HTML fragments, links, counts, assets, or clipboard data.
-### Preferred sequence
-1. `get text/html/attr/count` for targeted extraction.
-2. `read --screens N` for clean page text, long pages, or lazy-loaded content.
-3. `snapshot -i` for structured page observation before action planning.
-4. `assets list/export` for resources.
-5. `clipboard read` only when clipboard content is part of the task.
-### Example
-```bash
-OMNIBOT_SESSION_TOKEN=extract omnibot get text "#article" --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=extract omnibot get attr "a.next" href --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=extract omnibot get count ".result" --tab-id <TAB_ID>
-```
-Long page example:
-```bash
-OMNIBOT_SESSION_TOKEN=extract omnibot read --screens 5 --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=extract omnibot assets list --tab-id <TAB_ID>
-```
-### Verification
-Verify extraction completeness with expected markers in `read`, element counts, or targeted reads for known selectors.
-### Fallback entry point
-If content exists only in runtime objects, use `fallback-operations.md#javascript-fallback` after explaining why `read`, `snapshot`, and `get` could not access it.
-## Upload
-### When to use
-Use `omnibot upload` to attach a local file to an `<input type="file">` element. The command speaks CDP (`DOM.setFileInputFiles`) through the extension debugger transport, with a JS `DataTransfer` fallback for pages that reject programmatic file assignment.
-### Preferred sequence
-1. Observe the upload UI and confirm the task requires a local file.
-2. Locate the file input via `snapshot -i` or a CSS selector.
-3. Run `omnibot upload <selector> <local-file> --tab-id <TAB_ID>`.
-4. Verify the file was accepted (filename, count, enabled submit state, or application-specific confirmation).
-### Example
-```bash
-OMNIBOT_SESSION_TOKEN=form omnibot snapshot -i --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=form omnibot upload "input[type=file]" /path/to/cover.png --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=form omnibot is enabled "button[type=submit]" --tab-id <TAB_ID>
-```
-### Verification
-Confirm the input accepted the file:
-```bash
-OMNIBOT_SESSION_TOKEN=form omnibot get "input[type=file]" attr value --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=form omnibot is enabled "button[type=submit]" --tab-id <TAB_ID>
-```
-### Fallback entry point
-The CLI already falls back from CDP `DOM.setFileInputFiles` (by objectId, then nodeId) to a JS `DataTransfer` assignment. Do not add further JavaScript fallbacks on top; file inputs are security-sensitive and page-specific. If all three transports fail, report the failure to the user instead of scripting around it.
-## Batch
-### When to use
-Use Batch for short, known-safe extension/CDP command chains where the target tab and verification are already explicit. Batch is not a wrapper for normal CLI commands such as `snapshot` or `click`.
-### Preferred sequence
-1. Keep batches short.
-2. Include only deterministic operations.
-3. Verify after the batch with a separate command.
-4. Use `--file` for complex JSON quoting.
-### Example
-```bash
-OMNIBOT_SESSION_TOKEN=research omnibot batch '[{"cmd":"cdp","method":"Runtime.evaluate","params":{"expression":"document.title","returnByValue":true}}]' --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot get title --tab-id <TAB_ID>
-```
-File example:
-```bash
-OMNIBOT_SESSION_TOKEN=research omnibot batch --file /tmp/omnibot-batch.json --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot get url --tab-id <TAB_ID>
-```
-### Verification
-Do not treat batch success as task success. Verify final page state separately.
-### Fallback entry point
-Batch is not a fallback tier. If a batched operation fails, re-run the workflow step-by-step and enter the normal fallback model.
+# Operation Patterns
+Use this file to choose behavior by task. Every page-state workflow must set `OMNIBOT_SESSION_TOKEN=<workflow-name>` and pass `--tab-id <TAB_ID>` on each page-state command.
+## Read
+### When to use
+Use Read when the agent needs clean rendered page content: article text, search results, feed items, long pages, lazy-loaded text, or a human-readable summary source.
+Use targeted state commands when the agent needs one value, visibility, enabled/checked state, layout box, or computed styles. Use `snapshot -i` when the agent needs current visible UI structure for deciding the next action.
+### Preferred sequence
+1. `read --tab-id <TAB_ID>` for clean page text on an existing tab.
+2. `read --screens N --tab-id <TAB_ID>` for longer or lazy-loaded pages.
+3. `read <URL>` when opening a temporary tab only for reading that URL.
+4. `get title/url/text/html/value/attr/count/box/styles` for narrow evidence.
+5. `is visible/enabled/checked` for boolean state.
+5. `snapshot -i` when actionable refs are needed.
+6. `dom visible` or `execute-js` fallback only after standard reads cannot access the state.
+### Example
+```bash
+OMNIBOT_SESSION_TOKEN=research omnibot read --screens 5 --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot read --screens 3 https://example.com/article
+```
+### Verification
+Use the narrowest read that proves the claim:
+```bash
+OMNIBOT_SESSION_TOKEN=research omnibot get title --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot is visible "#main" --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot get count ".result" --tab-id <TAB_ID>
+```
+### Fallback entry point
+If `read` or targeted reads omit needed runtime state, go to `fallback-operations.md#fallback-tier-model`. Start with DOM fallback before JavaScript.
+## Click
+### When to use
+Use Click for buttons, links, menu items, cards, checkouts, modal actions, and any user-like click target.
+### Preferred sequence
+1. `find role/text/testid --action click`
+2. `snapshot -i` -> `click @eN`
+3. `click selector`
+4. `dom click`
+5. `mouse click`
+6. `execute-js` click
+7. `cdp` fallback
+### Example
+```bash
+OMNIBOT_SESSION_TOKEN=checkout omnibot snapshot -i --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot find role button --name "Submit" --action click --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot wait --url "/dashboard" --tab-id <TAB_ID>
+```
+If semantic find is ambiguous, use refs from the same tab:
+```bash
+OMNIBOT_SESSION_TOKEN=checkout omnibot snapshot -i --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot click --tab-id <TAB_ID> @e4
+OMNIBOT_SESSION_TOKEN=checkout omnibot snapshot -i --tab-id <TAB_ID>
+```
+### Verification
+Verify the expected state, not just command success:
+```bash
+OMNIBOT_SESSION_TOKEN=checkout omnibot get url --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot is visible ".success" --tab-id <TAB_ID>
+```
+### Fallback entry point
+If semantic and refs fail, document why and continue at `fallback-operations.md#selector-fallback`.
+### Static-text refs
+When `snapshot -i` shows only `StaticText` for a visible control label, do not assume the text ref itself is clickable. Prefer, in order:
+1. `find role button --name "<label>" --action click`.
+2. `click "text=<label>"`.
+3. `get box "text=<label>"` followed by `mouse click <center-x> <center-y>`.
+4. CDP/JS fallback only after verifying the semantic and coordinate paths failed.
+## Fill
+### When to use
+Use Fill for text inputs, textareas, search boxes, login fields, form fields where the final value must be controlled, and rich text article body editors (contenteditable ProseMirror/Quill/Draft.js/Slate/Toutiao article body).
+### Preferred sequence
+1. `find label/placeholder --action fill`
+2. `snapshot -i` -> `fill @eN`
+3. `fill selector`
+4. `focus` + `type`
+5. `execute-js` set value and dispatch `input`/`change` events
+### Example
+```bash
+OMNIBOT_SESSION_TOKEN=checkout omnibot find label "Email" --action fill --action-value "a@b.com" --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot get value "input[name=email]" --tab-id <TAB_ID>
+```
+With refs:
+```bash
+OMNIBOT_SESSION_TOKEN=checkout omnibot snapshot -i --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot fill --tab-id <TAB_ID> @e2 "a@b.com"
+OMNIBOT_SESSION_TOKEN=checkout omnibot get value "input[name=email]" --tab-id <TAB_ID>
+```
+### Rich text article body
+For article body editors exposed as `@eN [richtext] "..." [contenteditable=true]` under `# DOM Rich Text Editors`:
+```bash
+OMNIBOT_SESSION_TOKEN=editor omnibot snapshot -i --tab-id <TAB_ID>
+# Body appears under "# DOM Rich Text Editors": @eN [richtext] "..."
+OMNIBOT_SESSION_TOKEN=editor omnibot fill --tab-id <TAB_ID> @eN "First paragraph.\n\nSecond paragraph."
+OMNIBOT_SESSION_TOKEN=editor omnibot snapshot -i --tab-id <TAB_ID>  # verify body content replaced
+```
+- `\n\n` splits paragraphs; previous content is cleared.
+- `type @richtext " text"` appends at the cursor (click the ref first to focus).
+- Do NOT write the article body into a `[textbox]` title field. Title and richtext body are separate refs.
+### Verification
+Use `get value`, visible validation text, enabled state, or submit readiness:
+```bash
+OMNIBOT_SESSION_TOKEN=checkout omnibot get value "input[name=email]" --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot is enabled "button[type=submit]" --tab-id <TAB_ID>
+```
+For richtext bodies, re-run `snapshot -i` and confirm the `@eN [richtext]` name matches the intended content.
+### Cursor positioning and inline image insertion
+For `contenteditable` article bodies (ProseMirror/Quill/Draft.js/Slate/Toutiao article body), `find text "<anchor phrase>" --action click` collapses the editor selection at the end of the matched phrase and focuses the editor. Use this to place the caret at a specific paragraph before inserting an image, typing, or pressing keys. Do not rely on a bare `click` of the editor followed by `press End`, because the caret would stay on the first line.
+Insert an image after a specific paragraph:
+```bash
+OMNIBOT_SESSION_TOKEN=editor omnibot find text "第二段锚点文字" --action click --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=editor omnibot click ".syl-toolbar-tool.image .syl-toolbar-button" --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=editor omnibot wait --selector ".upload-image-panel input[type=file]" --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=editor omnibot upload ".upload-image-panel input[type=file]" "/path/to/image.png" --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=editor omnibot find role button --name "确定" --action click --tab-id <TAB_ID>
+```
+Verify the inserted image by counting visible image cards, not raw `<img>` nodes. Toutiao/ProseMirror image cards keep a hidden `<templ>` template and a visible `<mask>` copy of the same `<img>`, so `.ProseMirror img` returns 2 for one logical image. Count the image card container instead (e.g. `.ProseMirror [__syl_tag=true]` or `.ProseMirror .pgc-image`), which reports one per inserted image.
+### Fallback entry point
+If fill does not update the application state, use `fallback-operations.md#javascript-fallback` only after selector/focus/type attempts fail. JavaScript must dispatch real `input` and `change` events.
+## Select / Check
+### When to use
+Use this pattern for dropdowns, comboboxes, checkboxes, toggles, agreement boxes, filters, and boolean controls.
+### Preferred sequence
+1. Use `snapshot -i` first; visible comboboxes may include auto-probed option refs.
+2. Use `click @option` if `snapshot -i` lists auto-probed combobox option refs.
+3. Use `select @combobox "value"` for native selects or simple select-like controls.
+4. Use `check` / `uncheck` for boolean controls.
+5. Verify selected label, value, URL query, result count, or dependent page state.
+`snapshot -i` can list options for visible custom comboboxes even though the dropdown closes during observation. These refs are still actionable because Omnibot stores the option's `openerSelector` and can reopen the owning combobox before clicking the option.
+### Example
+```bash
+OMNIBOT_SESSION_TOKEN=form omnibot snapshot -i --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=form omnibot click @e22 --tab-id <TAB_ID>  # @e22 [option] "OpenAI Chat"
+OMNIBOT_SESSION_TOKEN=form omnibot get url --tab-id <TAB_ID>
+```
+Checkbox example:
+```bash
+OMNIBOT_SESSION_TOKEN=form omnibot is checked "#agree" --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=form omnibot check "#agree" --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=form omnibot is checked "#agree" --tab-id <TAB_ID>
+```
+### Verification
+For checkboxes, verify boolean state. For selects, verify value or dependent page state.
+### CSS-only dropdowns and custom menus
+Some dropdowns, hover menus, tooltips, and custom selects are CSS-only or portal-based widgets. The visible trigger may be accessible, while the option nodes are hidden `<div>` elements without `role`, accessible name, or stable refs. Start with `snapshot -i`; visible comboboxes may include auto-probed option refs before any manual dropdown opening.
+Escalation order:
+1. Run `snapshot -i` and look for `[option]` refs near the combobox.
+2. If an option ref exists, click the option ref directly and verify.
+3. If options are absent, click/hover the trigger once, run `snapshot -i` again, then click the option ref if it appears.
+4. If trigger interaction works but options remain absent or option refs fail verification, use `fallback-operations.md#css-only-dropdown-javascript-fallback`.
+Do not loop on manual open -> snapshot -> open -> snapshot when `snapshot -i` already lists auto-probed combobox options.
+### Fallback entry point
+If native select/check fails, use `fallback-operations.md#selector-fallback`. Use JavaScript only if events must be synthesized or if evidence shows a CSS-only multi-step widget cannot be completed through semantic, snapshot, selector, DOM, or mouse tiers.
+## Navigation
+### When to use
+Use Navigation to open pages, create tabs, change history, reload, close tabs, move between pages, create windows, or select frames.
+### Preferred sequence
+1. Create or discover a tab with `tabs`, `tab list`, `tab new`, `open`, or `navigate`.
+2. Save the returned tab id.
+3. Verify with `get url --tab-id <TAB_ID>`.
+4. Run all later page-state commands with `--tab-id <TAB_ID>`.
+### Example
+```bash
+OMNIBOT_SESSION_TOKEN=research omnibot tab new https://example.com --label research
+OMNIBOT_SESSION_TOKEN=research omnibot get url --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot snapshot -i --tab-id <TAB_ID>
+```
+History and lifecycle:
+```bash
+OMNIBOT_SESSION_TOKEN=research omnibot back --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot get url --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot forward --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot get url --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot reload --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot wait --load domcontentloaded --tab-id <TAB_ID>
+```
+Other navigation commands:
+```bash
+OMNIBOT_SESSION_TOKEN=research omnibot navigate https://example.com
+OMNIBOT_SESSION_TOKEN=research omnibot navigate https://example.com --same-tab --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot open https://example.com
+OMNIBOT_SESSION_TOKEN=research omnibot goto https://example.com --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot pushstate /dashboard --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot close <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot tab list
+OMNIBOT_SESSION_TOKEN=research omnibot tab close research
+OMNIBOT_SESSION_TOKEN=research omnibot window new
+OMNIBOT_SESSION_TOKEN=research omnibot frame main
+```
+### Verification
+Always verify the final target:
+```bash
+OMNIBOT_SESSION_TOKEN=research omnibot get url --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot wait --load networkidle --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot snapshot -i --tab-id <TAB_ID>
+```
+### Fallback entry point
+Same-tab navigation must include `--tab-id <TAB_ID>`. If the target tab id is unknown, run `omnibot tabs` first and choose the intended tab explicitly.
+## Wait
+### When to use
+Use Wait after navigation, clicks, form submissions, reloads, dynamic rendering, lazy loading, or any action that changes asynchronous state.
+### Preferred sequence
+1. Wait for selector visibility or hidden state.
+2. Wait for text.
+3. Wait for URL.
+4. Wait for load state.
+5. Wait for a JavaScript condition with `--fn`.
+6. Avoid shell sleep.
+### Example
+```bash
+OMNIBOT_SESSION_TOKEN=checkout omnibot click --tab-id <TAB_ID> @e4
+OMNIBOT_SESSION_TOKEN=checkout omnibot wait "#spinner" --state hidden --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot wait --text "Welcome" --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot get text "#main" --tab-id <TAB_ID>
+```
+Other waits:
+```bash
+OMNIBOT_SESSION_TOKEN=checkout omnibot wait --url "/dashboard" --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot wait --load domcontentloaded --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot wait --load networkidle --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot wait --fn "window.appReady === true" --tab-id <TAB_ID>
+```
+### Verification
+After waiting, read the final condition with `get`, `is`, `wait`, or `snapshot`.
+### Fallback entry point
+If waits time out, collect evidence with `debugging-and-evidence.md`; do not replace them with shell sleep.
+## Extraction
+### When to use
+Use Extraction for retrieving page text, HTML fragments, links, counts, assets, or clipboard data.
+### Preferred sequence
+1. `get text/html/attr/count` for targeted extraction.
+2. `read --screens N` for clean page text, long pages, or lazy-loaded content.
+3. `snapshot -i` for structured page observation before action planning.
+4. `assets list/export` for resources.
+5. `clipboard read` only when clipboard content is part of the task.
+### Example
+```bash
+OMNIBOT_SESSION_TOKEN=extract omnibot get text "#article" --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=extract omnibot get attr "a.next" href --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=extract omnibot get count ".result" --tab-id <TAB_ID>
+```
+Long page example:
+```bash
+OMNIBOT_SESSION_TOKEN=extract omnibot read --screens 5 --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=extract omnibot assets list --tab-id <TAB_ID>
+```
+### Verification
+Verify extraction completeness with expected markers in `read`, element counts, or targeted reads for known selectors.
+### Fallback entry point
+If content exists only in runtime objects, use `fallback-operations.md#javascript-fallback` after explaining why `read`, `snapshot`, and `get` could not access it.
+## Upload
+### When to use
+Use `omnibot upload` to attach a local file to an `<input type="file">` element. The command speaks CDP (`DOM.setFileInputFiles`) through the extension debugger transport, with a JS `DataTransfer` fallback for pages that reject programmatic file assignment.
+### Preferred sequence
+1. Observe the upload UI and confirm the task requires a local file.
+2. Locate the file input via `snapshot -i` or a CSS selector.
+3. Run `omnibot upload <selector> <local-file> --tab-id <TAB_ID>`.
+4. Verify the file was accepted (filename, count, enabled submit state, or application-specific confirmation).
+### Example
+```bash
+OMNIBOT_SESSION_TOKEN=form omnibot snapshot -i --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=form omnibot upload "input[type=file]" /path/to/cover.png --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=form omnibot is enabled "button[type=submit]" --tab-id <TAB_ID>
+```
+### Verification
+Confirm the input accepted the file:
+```bash
+OMNIBOT_SESSION_TOKEN=form omnibot get "input[type=file]" attr value --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=form omnibot is enabled "button[type=submit]" --tab-id <TAB_ID>
+```
+### Fallback entry point
+The CLI already falls back from CDP `DOM.setFileInputFiles` (by objectId, then nodeId) to a JS `DataTransfer` assignment. Do not add further JavaScript fallbacks on top; file inputs are security-sensitive and page-specific. If all three transports fail, report the failure to the user instead of scripting around it.
+## Batch
+### When to use
+Use Batch for short, known-safe extension/CDP command chains where the target tab and verification are already explicit. Batch is not a wrapper for normal CLI commands such as `snapshot` or `click`.
+### Preferred sequence
+1. Keep batches short.
+2. Include only deterministic operations.
+3. Verify after the batch with a separate command.
+4. Use `--file` for complex JSON quoting.
+### Example
+```bash
+OMNIBOT_SESSION_TOKEN=research omnibot batch '[{"cmd":"cdp","method":"Runtime.evaluate","params":{"expression":"document.title","returnByValue":true}}]' --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot get title --tab-id <TAB_ID>
+```
+File example:
+```bash
+OMNIBOT_SESSION_TOKEN=research omnibot batch --file /tmp/omnibot-batch.json --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot get url --tab-id <TAB_ID>
+```
+### Verification
+Do not treat batch success as task success. Verify final page state separately.
+### Fallback entry point
+Batch is not a fallback tier. If a batched operation fails, re-run the workflow step-by-step and enter the normal fallback model.