ziniao-assistant

Control Ziniao Browser via the local Ziniao bridge. On skill load or before first invoke, GET /zclaw/tools and treat returned name list as the only allowed tool strings; then POST /zclaw/tools/invoke. API key for invoke via ~/.zclaw/config.json or ZCLAW_API_KEY. On bridge failure stop the turn per skill.

# Ziniao Assistant

## Session tool allowlist (Mandatory — fetch first)

**Goal:** Put the **authoritative** tool names into context before any `invoke`, so every `tool` field is chosen from that set only (reduces hallucinated names).

1. **First HTTP call** when handling a ZClaw task (or immediately after this skill is loaded):  
   **`GET {baseUrl}/zclaw/tools`**  
   Same `baseUrl` as invoke (`ZCLAW_BASE_URL` / `ZINIAO_ZCLAW_BASE_URL`, default `http://127.0.0.1:9481`).  
   **No `X-ZClaw-Api-Key` and no Ziniao login are required** for this GET (public registry on the bridge).

2. **Parse the response:** JSON shape `{ ret, data }` where `data` is an array of `{ name, description, inputSchema }`. Build  
   **`allowedTools = data.map((t) => t.name)`**  
   and **retain it in working memory** for the session. Optionally keep `description` / `inputSchema` next to each name when choosing args.

3. **Before every `POST {baseUrl}/zclaw/tools/invoke`:** ensure **`allowedTools.includes(tool)`**. If the name you intend is not in `allowedTools`, **do not send the request**—map the user’s intent to a real name from `allowedTools` (e.g. open URL → `visit_page` or `open_store` + `launchUrl`).

4. **If `invoke` returns an error** like unsupported / unknown tool: re-run **`GET /zclaw/tools`**, refresh `allowedTools`, and retry with a valid `name`.

5. **If `GET /zclaw/tools` fails** (connection refused, timeout): follow **Stop on Blocker** for unreachable bridge; if you must proceed with static knowledge only, use the **Static fallback allowlist** below—still **no** invented names.

### Static fallback allowlist (when GET is impossible)

Comma-separated `tool` names that match a healthy bridge (re-sync when GET works):

`list_stores`, `resolve_store`, `open_store`, `close_store`, `visit_page`, `get_page_content`, `query_elements`, `click_element`, `input_text`, `scroll_page`, `take_screenshot`, `wait_for_element`, `wait_for_navigation`, `execute_script`, `run_automation`, `extract_data`, `prepare_agent`, `get_logs`, `download_file`, `debug_compare_lists`

---

## Available Capabilities

All **`invoke`** operations use `POST {baseUrl}/zclaw/tools/invoke` with `tool` + `args`. **Authoritative names** come from **`GET /zclaw/tools`** (see above); the table below is documentation aligned with that registry.

| Category | Tool | Description |
|----------|------|-------------|
| **Store** | `list_stores` | List stores (storeId, storeName, platformName, ip). Call once; no loop. |
| | `resolve_store` | Resolve store by storeId or storeName. |
| | `open_store` | Open store (by storeId/storeName from list or resolve). Call once. |
| | `close_store` | Close store by storeId. |
| **Page** | `visit_page` | Navigate to URL, optional waitUntil/timeout. |
| | `get_page_content` | Read page content (text/html/structured). |
| **Interaction** | `query_elements` | Query DOM by selector. |
| | `click_element` | Click element by selector, optional waitForNavigation. |
| | `input_text` | Type into element; optional clear, submit. |
| | `scroll_page` | Scroll page or element. |
| | `take_screenshot` | Screenshot (full page or viewport). |
| **Waiting** | `wait_for_element` | Wait for selector. |
| | `wait_for_navigation` | Wait for navigation. |
| **Automation** | `execute_script` | Run JavaScript in page. |
| | `run_automation` | Multi-step automation (steps array). |
| | `extract_data` | Extract metadata / page state; mode=running lists launched stores. |
| **Utilities** | `prepare_agent` | Prepare agent resources. |
| | `download_file` | Write content to Downloads (content, filename). |
| | `get_logs` | Get bridge logs. |
| **Debug** | `debug_compare_lists` | Debug: compare account/list vs store/list (optional; in GET /zclaw/tools registry). |

**Do not use:** `run_script` → use `execute_script`; `screenshot` / `get_screenshot` → use `take_screenshot`; `execute_automation` → use `run_automation`.

---

## Tool names: no hallucination (Mandatory)

The bridge **only** accepts the `tool` strings listed in **Core Tools** below. There is no separate “navigate API”, “browser API”, or “store tool” namespace—everything is one `POST .../zclaw/tools/invoke` body field `tool`.

**You MUST NOT** invent or guess tool names from general automation habits (Playwright, Selenium, browser-use, etc.). If a name is not in Core Tools, it **does not exist**.

**These and similar names are INVALID** (will fail or be rejected): `navigate`, `navigation`, `go_to`, `goto`, `open_url`, `openUrl`, `goto_url`, `load_url`, `browse`, `open_page`, `openPage`, `call_store_tool`, `store_tool`, `browser_navigate`, `visit`, `goto_tab`, `switch_tab` (as a tool name—use `visit_page` / `open_store` instead).

**Opening a URL in a store—only two supported ways:**

1. **`visit_page`** — args: `storeId`, `url` (and optional `waitUntil`, `timeoutMs`, `targetId`). Use after the store is already open.
2. **`open_store`** — args: `storeId` or `storeName`, and optional **`launchUrl`** so the first tab opens that URL when the store starts.

Do not chain imaginary tools before trying `visit_page` or `open_store` + `launchUrl`.

---

## API: How to Invoke Tools (Required)

**All tools are invoked through one endpoint only.** Do not call other paths.

- **Discover tools (no auth):** `GET {baseUrl}/zclaw/tools` — use first; see **Session tool allowlist**.
- **Method and path:** `POST {baseUrl}/zclaw/tools/invoke` (e.g. `POST http://127.0.0.1:9481/zclaw/tools/invoke`). Base URL from `ZCLAW_BASE_URL` or `ZINIAO_ZCLAW_BASE_URL` (default `http://127.0.0.1:9481`).
- **Auth is mandatory for invoke:** Every `POST {baseUrl}/zclaw/tools/invoke` **must carry API key credentials**. Preferred header: `X-ZClaw-Api-Key: <key>`. Also accepted: body `apiKey`, or `Authorization: Bearer <key>` (compatibility only). **Never send invoke without key.**
- **Request body (JSON):** `{ "tool": "<name>", "args": { ... } }`. Optional: `"action": "json"`.
- **`tool`** must be exactly one of the tool names in the **Core Tools** list below (e.g. `list_stores`, `visit_page`, `get_page_content`, `click_element`, `take_screenshot`, `execute_script`, `run_automation`). Wrong names (e.g. `run_script`, `screenshot`) or custom paths will fail.
- **Do not** call paths like `/zclaw/page/execute`, `/zclaw/page/visit`, `/zclaw/page/click`, etc. Every tool call must be `POST /zclaw/tools/invoke` with the correct `tool` name in the body.

### Invoke Auth Examples (Mandatory)

**Correct (preferred):**

```bash
curl -X POST http://127.0.0.1:9481/zclaw/tools/invoke \
  -H "Content-Type: application/json" \
  -H "X-ZClaw-Api-Key: <ZCLAW_API_KEY>" \
  -d '{"tool":"open_store","args":{"storeName":"Rosehut"}}'
```

**Also accepted (compatibility):**

```bash
curl -X POST http://127.0.0.1:9481/zclaw/tools/invoke \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ZCLAW_API_KEY>" \
  -d '{"tool":"open_store","args":{"storeName":"Rosehut"}}'
```

**Invalid (must not generate):** no API key in header/body.

## When To Use

Use when the user wants to operate Ziniao Browser or configure the Ziniao bridge (list stores, open store, visit pages, read content, click, input, screenshot, export, automation). When a task has multiple similar sub-items (e.g. several order types or reports), visit or check each one separately before concluding; do not infer from a subset.

## Stop on Blocker (Mandatory — Enforced First)

**Trigger:** Any of: (a) `POST {baseUrl}/zclaw/tools/invoke` fails with connection refused, timeout, or no response; (b) a required tool call returns an error that makes the task impossible; (c) a required resource (e.g. store not found, API key missing) is missing.

**You MUST:**

1. **Stop immediately.** Do not retry the same request. Do not read more code, grep, or open other files to "diagnose" or "work around". Do not design or write "run these steps when the bridge is up" or any follow-up plan.
2. **End the turn.** Do not speculate on other causes, sugges