ziniao-assistant（紫鸟助手）

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).

1. 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.

1. 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).

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

1. 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.

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):

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):

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, suggest code changes, or continue the task. Connection or tool failure means the task is not executable—stop only. (User-facing messages for unreachable bridge are handled by the software.)

Hard Constraints

• Stop on blocker: If the bridge is unreachable or a required tool call fails, stop and end the turn; do not retry, read code, or create templates or follow-up plans. See "Stop on Blocker" above.
• Invoke must include API key: Every POST /zclaw/tools/invoke request must include API key credentials (X-ZClaw-Api-Key preferred; or body apiKey; or Authorization: Bearer <key>). Do not generate keyless invoke commands.
• No script files: Do not create or run any scripts (.sh/.js/.py or other code files) to execute tasks; use only the tools in Core Tools via POST /zclaw/tools/invoke. Temporary files are allowed (e.g. intermediate data, content for download_file); script/executable files are not.
• All browser actions must stay inside Ziniao Browser or a Ziniao store exposed by the bridge. Do not open system browser, Chrome, Safari, Edge, Firefox, or use Playwright/Puppeteer/browser-use when the bridge fails.
• Use only the tools in Core Tools. Do NOT use: run_script (use execute_script), screenshot or get_screenshot (use take_screenshot), execute_automation (use run_automation), or any tool not listed there. Do NOT invent navigate, open_url, call_store_tool, or any name not in Core Tools.
• Prefer tool-based flow: open store (optionally with launchUrl) → visit_page for further URLs → get_page_content / query_elements / click_element / input_text / take_screenshot / download_file / run_automation. Use execute_script only for in-page JavaScript (e.g. DOM extraction), not for orchestration.

API Key: Configure via Conversation (Preferred)

The user can configure the API key by sending it in the conversation. When the user provides an API key (e.g. pastes it, or says “设置 API key 为 xxx”, “my API key is znoc_xxx”, “configure ZCLAW_API_KEY: xxx”), you MUST:

1. Write the key to the config file the skill reads from:

- macOS / Linux: ~/.zclaw/config.json - Windows: %USERPROFILE%\.zclaw\config.json (e.g. C:\Users\<YourName>\.zclaw\config.json) Create the .zclaw directory if it does not exist. File content: JSON with at least "ZCLAW_API_KEY": "<the key the user provided>". If the file already exists, merge: update ZCLAW_API_KEY and keep other keys (e.g. ZCLAW_BASE_URL) unchanged.

1. Immediately use this new API key for all subsequent POST /zclaw/tools/invoke requests in this conversation. Do not wait for a reload; treat the key you just wrote as the current key. If the user provides a new key again later, write again and switch to the new key for the rest of the conversation.

Writing the config file is allowed for API key setup only (creating/updating ~/.zclaw/config.json). Do not create or run scripts; use normal file write to that path.

API Key: Read into Context (Required)

When this skill is used, load the API key into the conversation context so every request (including the first) can authenticate. Use this order (Ziniao and ZClaw both use ZCLAW_API_KEY):

1. User just provided in this conversation — if you have just written the key to the config per “API Key: Configure via Conversation”, use that key for all requests.
2. Environment variable ZCLAW_API_KEY — use if set.
3. Config file ~/.zclaw/config.json — if the key is not in env and not set in conversation, read ZCLAW_API_KEY from this JSON file (e.g. { "ZCLAW_API_KEY": "your-key" }).

Use the resolved key for all POST /zclaw/tools/invoke requests (e.g. header X-ZClaw-Api-Key or body apiKey). Optionally ZCLAW_BASE_URL or ZINIAO_ZCLAW_BASE_URL (default http://127.0.0.1:9481).

Do this at skill load or at the start of the conversation so the key is available and the first tool call does not fail with "Missing bearer token". After the user configures a new key via conversation, update to the new key immediately for the rest of the turn.

Environment & Setup

• API key: Env ZCLAW_API_KEY, or ZCLAW_API_KEY in ~/.zclaw/config.json (see path note below). The bridge also accepts the key via header X-ZClaw-Api-Key or body apiKey.
• Base URL: ZCLAW_BASE_URL or ZINIAO_ZCLAW_BASE_URL (default http://127.0.0.1:9481).
• First time / Rotate key: Obtain a ZClaw API key from your server or Ziniao Ecosystem Center (there is no API key generation in the app settings). You can (1) configure via conversation — tell the assistant your API key and it will write it to ~/.zclaw/config.json and use it immediately; or (2) set ZCLAW_API_KEY in your environment or in ~/.zclaw/config.json; or (3) run bash ziniao-skills/install-ziniao-openclaw-skill.sh "YOUR_API_KEY" (Windows: use install-ziniao-openclaw-skill.ps1 with -ApiKey). After configuring via conversation, the assistant uses the new key for all subsequent requests in that conversation.

Reading the key: The bridge uses process.env.ZCLAW_API_KEY, which works on Windows, macOS, and Linux. The variable must be present in the environment of the process that runs the app (Ziniao/Electron). If the app is started from the GUI (e.g. Dock, Start menu), only system/user environment variables are visible; shell-only exports (e.g. in a terminal) are not. To ensure the key is always available on all platforms, you can use the config file instead of env.

Setting ZCLAW_API_KEY by OS:

• macOS / Linux: (1) Config file (recommended): ~/.zclaw/config.json with { "ZCLAW_API_KEY": "your-key" } (same path on both). (2) Env: In the same shell that starts the app: export ZCLAW_API_KEY=your-key. For GUI launches, add export ZCLAW_API_KEY=... to ~/.bashrc, ~/.zshrc, or ~/.profile, or set it system-wide (e.g. /etc/environment on Linux).
• Windows: (1) Config file (recommended): %USERPROFILE%\.zclaw\config.json (e.g. C:\Users\YourName\.zclaw\config.json) with { "ZCLAW_API_KEY": "your-key" }. (2) Env: System Properties → Environment Variables → add User or System variable ZCLAW_API_KEY; or in PowerShell (current user): [Environment]::SetUserVariable("ZCLAW_API_KEY","your-key"). Restart the app after changing system env.

Invocation: This skill is designed for use with the ZClaw framework (recommended). The Ziniao bridge is an HTTP API; any client that can send requests with a valid API key can call the same tools.

Store Resolution and Opening: Validation and Response Contract

Getting and opening stores follows Ziniao’s existing validation and launch flow: store detail (e.g. default_browser, platform) is fetched via store/detail when launching; the browser is then started using the same logic as the client.

ZClaw responses are filtered by convention and do not expose full Ziniao store details: open_store returns only storeId, name, debugPort, reused, etc.; list_stores returns only storeId, storeName, platformName, ip. ZClaw does not expose full store detail; it only exposes status for stores launched via ZClaw. The running-stores list (e.g. extract_data with mode=running or the running-stores API) contains only storeId, storeName, debugPort, wsUrl.

If open_store or visit_page returns 400 "Store detail not found", the backend store/detail API or its response shape may be failing; the bridge tries several response paths and, when present, includes the server’s msg in the error.

No Extra Scripts (Mandatory)

You must not create or use any scripts to execute tasks. All actions must be performed only through the tools listed in Core Tools. Do not:

• Create or run Node.js, shell, Python, or other script files (e.g. .sh, .js, .py) to accomplish the task.
• Invoke external commands or scripts for steps that the tools can do (list stores, open store, visit page, click, input, screenshot, download_file, run_automation, etc.).

Temporary files are allowed during the run (e.g. temporary data files, intermediate content to pass to download_file, or scratch files). Script files are not allowed — do not create or execute any file intended to be run as code. Use only POST /zclaw/tools/invoke with the tool names and args from Core Tools. If something cannot be done with the existing tools, report the limitation instead of scripting around it.

Store List and Opening (Mandatory)

• No looping: Call list_stores at most once to get data; then call open_store once. Do not repeatedly call list in a cycle.
• To open a store: (1) Get storeId — either from one list_stores (use the item whose storeName matches the user’s store) or from one resolve_store(storeName); (2) Call open_store once with that storeId or with storeName (exact string from the list).
• list_stores response: Each item has exactly: storeId, storeName, platformName, ip. Use storeName when calling resolve_store or open_store (exact match). Do not use other fields as the store name.

Recommended Workflow

1. Allowlist: GET /zclaw/tools → keep allowedTools (and schemas) in context; every invoke uses tool ∈ allowedTools.

0.5. Auth: Resolve API key first (conversation-provided > env ZCLAW_API_KEY > ~/.zclaw/config.json) and include it in every invoke request.

1. Store: One list_stores or one resolve_store → get storeId / storeName → one open_store (pass launchUrl if the user gave a target URL up front—avoids a second navigation step). Match by storeName from list; if ambiguous, ask user or use exact storeId. No fuzzy/substring matching.
2. Page: If the store is open and you need a URL: visit_page only (storeId + url). Never use navigate, open_url, or other non-listed tool names. Then use get_page_content, query_elements, click_element, input_text, take_screenshot, download_file as needed; prefer run_automation for multi-step flows.
3. Errors: Use get_logs on failure; after API key rotation, update config and refresh skills.
4. Multiple similar items: When a task involves multiple similar sub-items (e.g. several order types, several reports), visit or check each item separately before drawing a conclusion; do not infer "all have no data" or "all behave the same" from only a subset.

Core Tools

Only these tools exist. Use exactly these names as the tool field in POST /zclaw/tools/invoke; put parameters in args. Do not use or invent other tool names or other URLs.

Pass one arguments object per call (as args); required keys must be present. When running ZClaw tasks, the bridge operates on the correct tab but does not bring the browser window to the front, so your other windows and work are not interrupted.

Store Management

• list_stores — List stores (call once; no loop). Response: { page, limit, total, items } where each item has storeId, storeName, platformName, ip. Use storeName for resolve/open. Args: page?, limit?, all?, filterKeyword?, storeListType?.
• resolve_store — Resolve by exact storeId or storeName. Args: storeId?, storeName?, expectedName?. Returns storeId and name for open_store.
• open_store — Open store (need storeId from list_stores or resolve_store). Uses store/detail + launch. Returns (filtered): storeId, name, debugPort, reused, and optionally status, windowHandler, launchUrl. Call once. Args: storeId?, storeName? (use list item storeName), expectedName?, launchUrl?, isHeadless?, privacyMode?, windowRatio?.
• close_store — Close store. Args: storeId (required).

Page Navigation & Content

• visit_page — Navigate and wait. Args: storeId, url; optional waitUntil (domcontentloaded|load|networkidle), timeoutMs, targetId.
• get_page_content — Read page content. Args: storeId; optional format (text|html|structured), timeoutMs, targetId.

Page Interaction

• query_elements — DOM by selector. Args: storeId, selector; optional timeoutMs, targetId.
• click_element — Click. Args: storeId, selector; optional waitForNavigation, timeoutMs, targetId.
• input_text — Type into element. Args: storeId, selector, text; optional clear, submit, timeoutMs, targetId.
• scroll_page — Scroll. Args: storeId; optional x, y, selector, behavior (auto|smooth), timeoutMs, targetId.
• take_screenshot — Screenshot (not screenshot). Args: storeId; optional fullPage, path, timeoutMs, targetId.

Page Waiting

• wait_for_element — Wait for selector. Args: storeId, selector; optional timeoutMs, targetId.
• wait_for_navigation — Wait for navigation. Args: storeId; optional timeoutMs, targetId.

Automation & Scripting

• execute_script — Run JS in page (not run_script). Args: storeId, script; optional timeoutMs, targetId.
• run_automation — Multi-step flow. Args: steps (array of { type, ... }).
• extract_data — Extract metadata or page state. Use mode=running to list launched stores (returns only storeId, storeName, debugPort, wsUrl); mode=store returns that store’s launch status only (no store detail). Args: mode? (store|running|plugin|page), storeId?, payload?.

Utilities

• prepare_agent — Prepare agent resources.
• download_file — Write to Downloads. Args: content, filename.
• get_logs — Bridge logs.

Debug

• debug_compare_lists — Compare account/list vs store/list (debug). Args: limit?.

Invalid tool names (will fail): run_script, screenshot, get_screenshot, execute_automation — use execute_script and take_screenshot, run_automation instead. Also invalid: any name in Tool names: no hallucination (e.g. navigate, open_url, call_store_tool).