ZZD public AI gateway · zzd_public_ai_gateway_v3
Resource: 04 · Show and Piece contract / 字段
Canonical map: https://zzd.show/docs/ai/map.json
Full handbook: https://zzd.show/llms-full.txt
REST capabilities: https://zzd.show/api/v1/capabilities/

# Public Show contract

Treat the fields below as the author-facing contract. The signed-in
editor and scoped REST v1 expose different safe subsets.

## Show fields an AI may prepare

- `title` — required; at most 50 characters.
- `desc` — concise public description; at most 255 characters.
- `prompt` — a procedural brief for a future AI editing this Show.
  Describe composition, editable content/media roles, motion and
  state behavior, responsive constraints, and acceptance checks.
  Do not put provenance, source URLs, worker notes, audit evidence,
  secrets, or private reasoning here.
- `context` — short application context; at most 255 characters.
- `category` — bounded lowercase platform slug when using REST v1.
- `tags` — accurate discovery labels; never keyword spam.
- `cdns` — pinned shared browser-library dependencies.
- `esm` — explicit ES module/import configuration when needed.
- `pieces[]` — the live editable source.
- `thumbnail` — a fresh image of the final usable state.
- `favicon` — optional supported image/icon file.
- `visibility` — canonical lifecycle authority with exactly
  `private` or `public`. AI clients may read it but only the explicit
  publication operation can make it public.
- `is_component` — only when the Show is intentionally reusable as
  a component.

REST v1 metadata create/PATCH currently accepts only `title`,
`desc`, `prompt`, `context`, `category`, `tags`, `cdns`, and `esm`.
Pieces use the dedicated whole-tree PUT. Assets and bounded BaaS use
their own routes. A verified thumbnail uses the dedicated multipart
POST and owner-scoped content GET. Favicon editing and component
controls remain signed-in UI actions. REST clients cannot write
visibility through metadata: draft-producing mutations force
`visibility="private"`; only the confirmed publication route can set
`visibility="public"`. Responses may temporarily include deprecated
read-only `private` and `hidden` aliases as exact synchronized mirrors.
Do not infer a public-unlisted or link-only state from those aliases;
no such independent state exists in this contract.

Author, ownership, IDs, timestamps, counters, buyers, audit status,
compiled output, backend binding internals, and generated URLs are
platform-managed/read-only unless a specific capability says
otherwise.

## Piece fields

Each Piece has:

- `name` — meaningful, unique within the Show; at most 30 characters;
- language/type — HTML, CSS, or JavaScript;
- `raw` — formatted, readable, authoritative live source;
- module/import-map settings only when the runtime needs them.

The platform may derive or cache compiled output. Never make compiled
output the only source. After changing raw source, ensure the editor
intentionally rebuilds or clears stale compiled output and reopen all
preview environments.

There is no mandatory one-file-per-concept schema. Split by real
responsibility when useful: semantic structure, design tokens/styles,
content/data, media roles, state/routes, motion/timelines, and safety
adapters. The readable Piece that claims to own a behavior must
causally control the rendered behavior.

Suggested metadata example:

```json
{
  "title": "城市回声",
  "desc": "一个可交互的声音与地图叙事体验",
  "prompt": "保持三段叙事顺序；地点卡片可编辑；滚轮推进时间线；移动端改为纵向滚动；验证静音与无定位权限状态。",
  "context": "面向移动端与桌面的互动故事",
  "tags": ["互动叙事", "地图", "音频"],
  "private": true,
  "hidden": true
}
```

Do not paste this example blindly. Use the user's actual product,
language, accessibility needs, and distribution intent.

每次围绕具体作品的普通用户进度、部署、修复、回退和最终回复，都显式给出作品名称、PK（真实id）、UID/作品号（真实public_id）、API返回的正式打开链接和实际状态。优先复制 data.delivery.feedback_line；英文用 feedback_line_en。PK与作品号须是可复制文本，不能只藏在Run/Edit链接中，也不能只回复名称和链接。缺字段时沿用原身份GET同一已有作品补取，不造号、不建替代作品、不重领或注册worker、不额外向用户要授权。尚未创建就明确标识尚未取得，取得后立即补回；批量逐项给出，修复沿用原标识。私有作品注明需原有访问权限；普通链接和作品号不授予访问权，不附凭据、share token或runtime ticket。不得把计划/保存/清单核验冒称已部署或页面验收通过。交付表中分别写新站点名称与原站/原模板具体名称，未知原站写待核实，不猜测。reply_instruction/delivery仅用于普通回复，不回填manifest或严格JSON工具契约，也不在严格JSON输出前添加自然语言。漏报就补齐回复，不增加服务端拒绝、设备确认或审批流程。
In every normal user-facing progress update, deployment, repair, rollback and final handoff about a Show, explicitly display its title, PK (id), Work ID (public_id), API-returned canonical open link and actual state. Prefer data.delivery.feedback_line_en (feedback_line for Chinese). Both identifiers must be copyable text, not only part of a Run/Edit URL. Retrieve missing fields with the existing authorized GET for the same Show; do not invent IDs, create a replacement, register/claim again or ask for extra authorization. Report each Show separately and retain its identity across revisions. Note when original private access is required. Never append credentials, share tokens or runtime tickets. Distinguish planning, saving, manifest verification and actual browser/deployment results. Name the new site and the specific original site/template separately when tabulating; mark unknown source names unverified. delivery/reply_instruction are presentation guidance, not manifest or strict JSON input fields. Remedy an omitted identifier in the reply without adding a deployment gate.