ZZD public AI gateway · zzd_public_ai_gateway_v3
Resource: 13 · Agent capability contract / REST 与 MCP 边界
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/

# ZZD external-agent capability contract

Capability maturity must remain explicit.

## Available now

- this public, unauthenticated documentation/resource graph and REST
  adoption specification;
- public machine-readable REST discovery at
  `GET /api/v1/capabilities/`;
- authenticated HTTPS REST v1 draft, Piece, asset, bounded BaaS,
  collection, verified-thumbnail, and publication operations using
  a scoped, revocable ZZD developer bearer credential;
- authenticated stateless Streamable HTTP MCP at `POST /mcp/v1/`
  with bounded tools that reuse the REST control plane;
- signed-in browser use of the normal Web AI IDE and product UI;
- Show runtime APIs such as `AppRuntime` and `SpaceClient` inside an
  appropriately bound Show.

Public documentation and capabilities need no credential. Every
private REST resource operation enforces bearer authentication,
scope, active owner, and ownership. REST never falls back to a
browser session cookie or legacy CLI token. Both the developer API
and signed-in credential control plane accept only the exact
canonical `zzd.show` Host.

## MCP transport boundary

There is no public unauthenticated mutation endpoint. `/docs/ai/` is the
public human-readable discovery page; `/mcp/v1/` is the authenticated,
stateless Streamable HTTP protocol endpoint with a bounded `zzd_*`
tool catalog. Its mutating tools reuse REST v1 ownership, scope,
validation, quota and publication checks rather than opening a
second privileged path. Client/domain approval remains controlled by
Codex, Claude Code, the browser, proxy or organization.

## Stable resource names for MCP-compatible ingestion

- `zzd://docs/platform`
- `zzd://docs/quickstart`
- `zzd://docs/deployment-api`
- `zzd://docs/show-contract`
- `zzd://docs/quality`
- `zzd://docs/assets`
- `zzd://docs/baas`
- `zzd://docs/lifecycle`
- `zzd://docs/distribution`
- `zzd://docs/safety`
- `zzd://docs/handoff`

## REST boundary

REST v1 intentionally exposes a bounded subset of ZZD. It supports
owned Show listing/creation/detail/update, authoritative Piece-tree
replacement, safe byte assets, one isolated runtime-identity BaaS
profile, owned collection creation/attachment, and confirmed
publish/unpublish. It also supports verified thumbnail replacement
and owner-scoped private thumbnail streaming. It does not expose
arbitrary BaaS, generic upload-from-URL, browser validation, favicon
mutation, Sale management, destructive deletion, asset replacement/
deletion, thumbnail deletion, collection detach/deletion, shell,
SQL, staff tools, internal lifecycle orchestration, or another
user's resources.

The capability response reports exact methods, routes, scopes,
examples, limits, idempotency behavior, source policy, and response
envelopes. Unknown fields and server-controlled fields are rejected.
Source and presentation mutations clear compiled state where
applicable and return the Show to `visibility="private"`. Draft
developer bytes remain private; publication promotes public copies,
and re-drafting removes those public copies while retaining private
sources. Publication is separate, scoped, confirmed, and preflighted.
These properties are security contracts, not hints.

## Reuse authorized access / 复用已有授权接入

用户提供项目和部署意图即可。AI先复用用户已经批准的本机连接/私有路径与原身份；新Demo或新线程不等于新token。不要搜索环境中的其它账号秘密，不借用其它worker/claim，不自动选择未知旧安装或扩大scope。

1. 读取 GET https://zzd.show/api/v1/capabilities/，使用实际已有本机凭据 GET https://zzd.show/api/v1/me/（identity:read）核对账号和当前权限。秘密留在0700私有目录/0600文件，不进入prompt、源码或输出。
2. 若已有正常本人网页登录，可 GET https://zzd.show/api/v1/developer-credentials/ 获取本人的非秘密metadata；保留旧credentials字段，并读取reuse.stored_zip_version。遵循pagination.next，has_more=true时不能把首100项称作全库。代理browser session不能管理凭据。
3. 根据已有scopes和用户批准的明确版本选择原ZIP：仅向返回的 /machines/versions/{version_id}/download/ 发送本人session+CSRF的POST，下载原保存字节，不调用create/generate。下载仍检验owner/active/package，metadata不证明本机持有秘密或包必然可下载。没有保存ZIP的旧手工token只可使用已保留的本机秘密，不能从哈希回取。
4. 具有shows:write的原凭据可 POST https://zzd.show/api/v1/shows/ 建立服务端强制visibility="private"草稿；维护使用已有作品及plan/CAS契约。tasks-only不能部署Show；原hightopo可读写本人私有Show/source/assets，但不含shows:publish或browser:login。公开发布仍需独立scope和既有明确发布授权，部署意图本身不等于公开意图。
5. 确无可用授权接入时才走现有登录/明确授权流程。缺少实际本机秘密或权限时准确说明这一缺口，不声称可部署、不为了每个项目重新创建连接。默认长期有效，可由本人单独撤销；显式有限期限凭据仍按本人所选期限，到期后由本人管理原连接，不由本文自动续权。

REST bearer只发精确canonical https://zzd.show/api/v1/（或获准的POST https://zzd.show/mcp/v1/），不跟随redirect转发；session/CSRF下载与bearer REST互不充当认证fallback。已有BaaS绑定仅按目标读取baas/space-sdk契约，不增加匿名BaaS、任意model/provider或外机/费用权利。


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