Skill

# Movies API – Latest merged list (cache; agent-ready)

## When to use

- User wants **current movie listings** (Maoyan + TMDB merged cache), “what’s playing”, “top movies”, “movie list from this site”.
- This endpoint **does not** live-fetch TMDB/Maoyan per request — safe to call when a **cached list** is enough.
- **Do not** call for plot-only questions that need a different tool, or unrelated domains.
- **Do not overuse:** unrelated chat → do not call.

## Hard boundaries (must check before call)

- This module returns **cached merged list** only; do not imply real-time box-office/live upstream fetch per request.
- If a title is not in `data.movies`, state “not in current cache” instead of fabricating entries.

## Pre-check (before tool call)

- Confirm user request is compatible with cached list retrieval.
- Confirm optional filters (e.g. year/top-N) can be derived from returned movie fields.

## Fallback (when not suitable)

- If user requires real-time upstream freshness, explain that this endpoint is cache-backed.
- If no rows are returned, explicitly report empty cache state rather than guessing.

## Retry policy

- Retry once on transient **500/5xx**.
- Do not loop retries for persistent empty cache or unsupported filter requests.

## Multi-turn / Missing parameters

- **No query or body** required for `GET /api/movies`. If the user wants **one specific title** not in the list, answer from the returned list or say it is not in the cached set — **do not** invent movies.

## Parameters

- None for `GET /api/movies`.

## Steps

0. **Conversation cache:** If `GET /api/movies` already returned **200** in this conversation and the user asks again without needing fresher data, **reuse** `data`.
1. **Call** `GET /api/movies`.
2. **Check HTTP status** and envelope `{ code, message, data }`.
3. **Extract** `data.movies`, `data.cachedAt` (ms timestamp when cache updated).
4. **Format** a compact list or top N titles with scores/sources as the user asked.

## Request

`GET /api/movies` — read-only; **does not** trigger upstream writes.

## Response

**Envelope:** HTTP **200** with `{ code: 0, message: "ok", data: { movies, cachedAt } }`.

- **`data.movies`** — **array** of merged movie objects (may be **empty** if cache has no rows yet). Do not invent titles not present in this array.
- **`data.cachedAt`** — number (typically **Unix ms**) when the list was last updated in cache — useful to mention if the user asks how fresh the list is.

**Typical fields on each item** (subset may be missing; use only what exists): `name`, `score`, `sources`, poster/image URLs, links — **prefer quoting** fields from the payload over guessing.

**Provider mix:** Maoyan + TMDB merge may mean **partial** `sources`; missing optional fields are normal, not an error.

## Say to the user (one line)

- Summarize a few titles or filter by user criteria from **returned** items only.

## Output language

- **User’s language** for commentary; keep **titles** as returned.

## Idempotency & cache (conversation)

- Reuse prior **200** body in the same conversation when appropriate.

## Examples

- User: “List trending movies from the API” → GET `/api/movies` → summarize `data.movies` (verify live).
- User: “Top 5 by score” → same GET → sort/filter **client-side** from `data.movies`.
- User: “What’s the CNY rate?” → **Do not call this API**.

## Agent rules

Single **GET**; follow **Steps**; do not call external TMDB/Maoyan if this list suffices.

## Error handling (HTTP)

| Status  | Agent behavior                                                                                |
| ------- | --------------------------------------------------------------------------------------------- |
| **200** | Success — `data.movies` may be **[]**; explain “no cached list” instead of fabricating films. |
| **500** | Server error — report briefly; **one** retry later is OK; **do not** spam retries.            |
| **4xx** | Rare — **do not** blind retry; pass through `message` from JSON if present.                   |