VliveCLI

Core Rules

• Require the user to provide both Access Key and Secret Key before making API calls.
• Keep keys local only. Never paste keys into source code, docs, prompts, logs, tickets, public URLs, screenshots, or committed files.
• Prefer the bundled local helper scripts/vlebo_api.py for credentials, signing, and requests.
• Use references/api-doc.md as the source of truth for endpoint paths, request fields, enum meanings, and response shapes.
• Sign requests with the URL path only, not the full URL and not the query string.
• Use timestamps in seconds. If requests fail unexpectedly, check local clock drift first because 微乐播 rejects signatures with more than 2 minutes of timestamp skew.

Local Credential Setup

Use one of these local-only credential sources:

1. Environment variables for one-off work:

export VLEBO_ACCESS_KEY="..."
export VLEBO_SECRET_KEY="..."

2. Local credentials file for repeated work:

python scripts/vlebo_api.py configure

This writes ~/.config/vlebo/credentials.json with owner-only permissions. Do not copy this file into any project.

Request Workflow

1. Identify the target capability in references/api-doc.md.
2. Confirm the endpoint host:
   - Customer/viewer sync APIs use https://c-api.vlebo.cn.
   - Business/management APIs use https://b-api.vlebo.cn.
3. Only ask the user for fields marked ✅（必填）in the API doc. Fields marked ❌（非必填）are optional — the user can skip them, and you MUST NOT require or repeatedly ask for them. Build the request body with only the fields the user provides.
4. Call with scripts/vlebo_api.py request, passing method, path, optional query, and optional JSON body.
5. Inspect the JSON response. Treat non-200 code values as API-level failures even when HTTP succeeds.

Example:

python scripts/vlebo_api.py request \
  --method POST \
  --base-url https://b-api.vlebo.cn \
  --path /v1/developer/live/create \
  --json '{"liveMode":1,"screenType":1,"name":"demo","startTime":1780000000,"endTime":1780003600,"cover":"https://example.com/cover.jpg","lowLatency":2,"playback":2}'

Capability Map

Load references/api-doc.md when implementing or calling any endpoint. Main documented capabilities include:

• Live rooms: create, update, status, list, batch delete, fetch comments.
• Products: create, update, delete, bind/unbind live rooms, sales rankings, transaction stats.
• Audience and analytics: live audience data, merchant audience data, live overview.
• Commerce: order list, order detail, batch shipment, after-sales records.
• Marketing: points query/log/change, coupon list/receipts/send/invalidate, promoter list.

Analytics Dashboard Template

Use the reusable static template in assets/live-analytics-dashboard/ when the user asks for a live analytics page, dashboard, or private-domain live review screen.

• Start from assets/live-analytics-dashboard/index.html.
• Read references/live-analytics-page.md for metric definitions, module guidance, empty states, and API mapping.
• Keep the current template scoped to only three data sources unless the user expands scope: GET /v1/developer/live/overview, GET /v1/developer/live/list-product-sale, and GET /v1/developer/live/get-product-count.
• Persist each report as a local snapshot keyed by liveId before analysis so repeated reviews of the same live session stay consistent.
• Keep the UI in a dark tech data-report style: compact, neon-accented, low-radius, table-and-metric oriented, and free of marketing landing-page hero sections.
• Keep sample data fake. Replace it with signed local API calls only after the user configures local credentials, then write the fetched payloads into the local snapshot before rendering.
• Preserve key security rules from this skill when connecting real data.

Implementation Notes

• For GET endpoints, put documented URL parameters in the query string.
• For POST endpoints, send JSON request bodies.
• Preserve numeric timestamp units exactly as documented: seconds unless the API says otherwise.
• For price fields, use cents when documented as 单位：分.
• Do not invent undocumented enum values or optional behavior.
• Field rules: only ✅（必填）fields are mandatory — ask the user for those. ❌（非必填）fields are optional and can be omitted entirely from the request body. If the user doesn't provide an optional field, do not keep asking.
• Product create defaults: when calling POST /v1/developer/product/create, the server may still validate certain ❌ fields. If the user doesn't provide jumpType, send 1; for productType, send 1 (实物商品) unless specified; for wxaOriginId, wxaAppId, and wxaUrl, send empty strings "". Do not ask the user for these — just fill and send silently.
• Live ID resolution: when a target endpoint requires only a liveId (e.g. get live status, overview, product ranking), and the user hasn't provided one, call the live list API (GET /v1/developer/live/list) first to look up available live IDs — by name if the user mentioned one, otherwise present the list and let the user pick.
• List/search semantics: list endpoints often accept ❌（非必填）filter fields. Treat these as search filters — include the field to narrow results, omit it to return all records for that dimension. For example, omitting liveId from the live list means "list all lives"; including a name filters by name.

Verification

• Generate a signature locally with python scripts/vlebo_api.py sign --path /v1/developer/live/status before making the first request.
• For live calls, start with a read-only GET endpoint when possible, such as live status/list, to verify credentials.
• When modifying production data, summarize the exact endpoint, method, and body for user confirmation before sending.