ZZD public AI gateway · zzd_public_ai_gateway_v3
Resource: 09 · Publish and maintain / 生命周期
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/

# Show lifecycle

For local source repositories, first read `capabilities.source_packages`.
Upload -> seal -> build (ready) -> activate the intended UUID with the
current generation -> GET the original Show and compare
`runtime.active_version` -> verify the canonical `links.blank` in a
browser. A successful upload/build is not a deployment. The stable
Show alias follows successful explicit activation; it must not follow
arbitrary experimental uploads. MCP exposes list/get/build/activate
source-version tools. Activation can atomically bind the real prompt,
outcome and parent release to the exact selected package. Read back
the returned release and delivery receipt, and display PK/public_id.
Selecting an old ready package with current generation is rollback.
This operation does not change publication/access or require a new
credential or recurring confirmation. Existing authorization applies.

## 单作品有限客户端 / Finite source example

Download the independent POSIX(macOS/Linux) Python3.9+ standard-library example from
__ORIGIN__/docs/ai/examples/source-package-client.py and verify its
SHA256/bytes against __ORIGIN__/docs/ai/examples/source-package-client.json.
No platform source checkout, new credential, CLI home or software ZIP
change is needed. Reuse an existing private bundle or ZZD_TOKEN.

```sh
python3 source-package-client.py plan --origin __ORIGIN__ --public-id WORK_ID --credential-file /private/connection.json --project /projects/demo
python3 source-package-client.py build --origin __ORIGIN__ --public-id WORK_ID --credential-file /private/connection.json --project /projects/demo --receipt /private/build.ndjson
python3 source-package-client.py select --origin __ORIGIN__ --public-id WORK_ID --credential-file /private/connection.json --version EXACT_READY_UUID --generation OBSERVED_GENERATION --prompt-file /private/prompt.txt --receipt /private/select.ndjson
```

The source directory contains engine.json with entry, dependencies
and actual provenance.source/license. Optional file_modes follow the
published exact-path/SHA/boolean contract. plan is read-only; build
prints skipped hidden/private/symlink entries before any writes and
never activates. select explicitly names one ready UUID and current
generation, pins the latest observed release parent (or an explicit
--parent-release-id), and verifies the real prompt/package/parent
receipt plus default readback. An old ready UUID uses the same select
command for rollback; stable work links do not change. Selecting the
already active UUID creates no new prompt checkpoint.

This small example inspects only the named directory: at most500
files,2000 entries,16 directory levels,32MiB total and one data frame
per file, capped by both8MiB and the advertised frame limit. These are
example bounds, not platform quotas; larger trees stop without
truncation. Hidden/private filename exclusions are not an exhaustive
secret detector; review the printed plan. Required entry/dependency
files excluded by that policy cause refusal. Files are read through
held no-follow directory handles; symlinks and hardlinks are not
uploaded. Existing receipt files are never overwritten; private
append-only NDJSON receipts contain identities/hashes, no bearer or
transfer proof. Keep credential and receipt files outside the source.
Existing credentials stay self-owned/private (for example0600);
their owned parent and a new receipt's parent need only be
non-writable by group/others, so0755 works without chmod. Prompt
input is ordinary bounded self-owned UTF8 text (0644 is fine), not
a secret-file permission ceremony; its body is not logged. Only
verified root-owned macOS/tmp→/private/tmp and/var→/private/var
aliases are normalized consistently for containment and held-FD
access. Arbitrary directory/file symlinks, writable-by-others
parents, public-readable credentials, hardlinks, FIFOs and races
remain rejected; existing files/parents are never chmodded.

No retries, repair/resume loop, daemon, subprocess executor,
publication, provider or fee call is included. An ambiguous write
causes bounded GET readback by immutable identity; it is never
blindly replayed. Use status --version EXACT_UUID for later readback.
403/404 stop under existing permissions;429 respects Retry-After;
413 never truncates;409 requires fresh explicit generation/review.
A failed build retains the previous default. A matching remote
manifest and ready state do not prove rendered or canonical runtime
bytes: private runtime files still need the existing authorized
browser. The helper never forwards bearer/cookies to Run or runtime
origins, never extracts a browser profile, and reports
browser_verified=false. Open its returned canonical Run in the
user's existing authorized browser and compare the expected original
bytes/behavior separately before claiming browser verification.

Prompt checkpoint parents are a history graph. Named branch heads,
merge and checkout are not implemented. Classic Piece saves and
source-package builds are separate source formats: when
`runtime.renderer=source_package`, a classic-only save does not
replace the selected package. Do not report it as updating default Run.


Canonical state flow:

`authorized -> visibility=private draft -> built_pending_validation ->
validated -> visibility=public -> maintained or unpublished`

## Create

- `POST /api/v1/shows/` always begins `visibility="private"`;
  clients cannot override that draft state.
- Save accurate metadata and readable authoritative Pieces.
- Upload/bind assets and configure dependencies.
- Configure BaaS only when the product needs it.
- Keep a known-good baseline and validation matrix.

## Validate

Pass rendered-experience, live-source-quality, and environment-parity
checks. A build is only `built_pending_validation` until browser
evidence passes. Capture a fresh final-state screenshot, upload it
through `POST /api/v1/shows/{show_id}/thumbnail/`, and verify its
owner-scoped content route. REST verifies image bytes but does not
automate or prove the browser evidence.

## Publish

Reuse the user's existing explicit publication intent for this same
work and scope. Only if it is missing, obtain that decision after
presenting the reviewed result; then call
`POST /api/v1/shows/{show_id}/publication/` with
`{"action":"publish","confirm":true}` and `shows:publish`:

- server preflight checks required metadata, prompt, thumbnail, and
  safe source structure;
- private developer assets and the verified thumbnail are promoted
  to public presentation copies only as publication succeeds;
- successful publication sets `visibility="public"`;
- reopen detail, blank, editor preview, and embed;
- report the verified PK (`id`), Work ID (`public_id`), actual status,
  stable returned URLs and remaining dependencies in the user reply.

Server preflight does not run the browser validation matrix. The
canonical contract deliberately has no separate public-hidden/link-only
visibility combination.

## Maintain the same owned Show

A task's assistance history is not an unconditional resume command.
Read current `task.next_steps` and `assistance.current_guidance`.
Resume is a conditional request only for needs_input/in_progress
with the current real question answered; the same worker/session/
credential and complete current claim or lease-recovery fence are
still required. Seven other task states offer no resume action.
Never requeue a resource/licence blocker or recreate the task to
obtain a write permission.

Ordinary continuation of an existing owned Show is independent:
authenticate the current intended account at `/api/v1/me/`, inspect
`GET /api/v1/shows/{show_id}/` and the current source/assets, then use
the existing plan -> sync_assets -> apply -> verify -> finalize
transaction sequence. Apply the exact manifest and original signed
plan token; changed/stale state must be read and reconciled again.
A direct PUT to `/pieces/` replaces the whole readable source tree
and is not a version compare-and-swap. Never submit a partial tree.
Existing scopes, owner, revocation/expiry, source/resource rights,
quotas and uncertainty checks remain authoritative. Use the same
original credential and Show; a closed Task/worker neither grants
nor blocks these independently authorized draft writes. Publication
remains the existing explicit authorized/preflight operation, not
an effect of assistance. Technical updates use the existing feedback
channel and original identity; a closed task claim cannot take new
lifecycle evidence.

On every edit:

1. identify affected metadata, Pieces, assets, bindings, BaaS schema,
   and states;
2. preserve or record a last known-good version/duplicate before a
   risky change;
3. PATCH only intended metadata and PUT the complete intended Piece
   tree; Piece replacement is atomic, destructive replacement;
4. note that Piece replacement recreates authoritative rows with
   empty compiled state; draft-producing Show mutations set
   `visibility="private"` and remove promoted public asset/
   thumbnail copies while retaining private sources;
5. rerun the same state matrix in all environments;
6. POST a replacement verified thumbnail if the visible result changed;
7. summarize change, evidence, migration impact, and rollback path.

For BaaS schema changes, use additive/backward-compatible migration
when possible and protect existing user data. For dependency
upgrades, pin versions and compare timing, layout, render output, and
bundle behavior with the known-good version.

## Unpublish

Ask for confirmation before changing a public Show. REST v1 accepts
`{"action":"unpublish","confirm":true}` at the same publication
endpoint and sets `visibility="private"`. Recheck Sale/buyer impact
before restricting a bundled Show.

Deletion is destructive and is not part of the default deploy flow.
REST v1 exposes no deletion route.
Never delete a Show, asset, collection, or Sale without exact target
resolution, impact review, explicit user confirmation, and a
recoverable path where available.

每次围绕具体作品的普通用户进度、部署、修复、回退和最终回复，都显式给出作品名称、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.