ZZD public AI gateway · zzd_public_ai_gateway_v3
Resource: Current client access / 当前客户端接入
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/

# Current client access / 当前客户端接入

Discovery revision: 2026-10-20.1 (documentation only).

## 查看已有作品 / View an existing Show

只查看用户已有权的作品无需开发凭据。已知 PK 时，直接用用户授权且已登录的原 Safari/Chrome 打开 https://zzd.show/shows/detail/{pk}/；已知作品号时打开 https://zzd.show/s/{public_id}/。从实际跳转读取正式作品号和运行/编辑入口，反馈名称、PK、作品号和正式链接，权限保持原样。
公开搜索无结果不代表作品不存在，不能因此先要求用户补贴完整分享链接。匿名网页抓取、搜索工具和新隔离浏览器不会继承原浏览器登录；应先使用实际有权的原浏览器。若工具无法接入原浏览器，准确说明工具限制，不把它说成作品找不到，也不提取、复制cookie/token、不改权限、不为只读访问新建凭据。只有实际尝试后仍遇到登录或访问拒绝，才按真实结果说明缺项。旧整数PK blank和隔离runtime直链不是替代入口；编辑/部署继续使用各自原有授权。


Portable private Pack source client: https://zzd.show/pack/source-client/ (Python 3.9+, no source checkout; original permission and explicit publication/binding review required).

REST protocol: 2026-08-20 (stable; independent of software releases).
Public human documentation: https://zzd.show/docs/ai/ . The legacy /mcp/ directory is blocked at the public gateway.
MCP transport: POST https://zzd.show/mcp/v1/ ; a GET is rejected with 405. This is a separate scoped control endpoint.
Machine software: 0.12.6 / release 0.12.6-permanent-access.
Connection format: zzd-client-connection-1.
Hightopo guard: 2026-10-18.2; quality protocol: 2026-09-09.2.

## Read the original worker state / 原机器只读诊断

- Independent doctor 2026-10-18.2: https://zzd.show/collaboration/worker-doctor.json . Verify the version, byte_size and SHA-256, then download the exact versioned file from that manifest.
- Instructions: https://zzd.show/collaboration/recovery/ . Run `python3 worker-doctor.py diagnose --root ORIGINAL_ROOT --context CURRENT_HOST_TASK_ID --bundle ORIGINAL_CONNECTION_FILE` with Python 3.10+ on the original installation.
- Keep the original guard 2026-10-18.2, installed client, connection, identity, home and pending file. This tool diagnoses once and returns one authorized next step; it does not register, claim, renew, repair local state, replay or acknowledge commands. Authentication accounting remains normal; business data is read-only.

## Software and private connection are separate

- Owner browser workspace: https://zzd.show/machines/ ; software catalogue: https://zzd.show/machines/software/ .
- Current software: POST https://zzd.show/machines/software/0.12.6-permanent-access/download/ from the signed-in owner browser with CSRF. ZIP SHA-256: b815e41a69923a286b8556286cc623a3dce7aba8d94398bc474ad7dfa1b218a7. This is zzd-machine, macOS, Python 3.9+; it is not a local stdio MCP bridge or a public PyPI installation instruction.
- Reuse the existing user-approved local connection first. Only first access with no usable authorization calls for explicit connection generation via the existing machine UI. POST https://zzd.show/machines/versions/{version_id}/download/ returns the same stored ZIP bytes; downloading does not create, rotate or revoke credentials. Retain old software and original connection bytes; software compatibility is separate from live credential validity.
- Keep connection.json mode 0600 in a private 0700 directory outside source/chat. Share only its local path with your authorized local agent. Never print its token, copy another task identity, or automatically switch software/home.
- Old .zzdmcp/PEM generation POSTs return 410; existing issued files retain their original identities and scopes. Current authenticated authorization determines permanent or finite lifetime, and explicit revocation/account controls still apply. There is no secret recovery from a stored hash.
- Existing 0.12.5 and earlier machine software needs one normal official upgrade to support permanent metadata. Use the current official software's ordinary upgrade plan with the original home, installation, context, credential and worker state; preserve old software and finish or explicitly reconcile pending work before switching. NULL expiry alone never requires credential reissue or a new connection ZIP.
- Python/Node SDK source candidates are distinct from the platform ZIP. This discovery does not advertise unpublished client candidates, public PyPI packages or unreleased owner-workflow APIs.

## 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或外机/费用权利。


## Access and runtime domains

Public docs, agent discovery, capabilities, initializer and guard metadata need no credential. Discovery does not expand client origin trust, scopes or export rights. REST v1 uses a scoped bearer at the exact advertised API origin, never across a redirect; browser control actions use the owner's session and CSRF. Neither is the other's credential fallback. Remote MCP uses the same scope/ownership rules and still needs host/organization approval.

Show source, assets, write operations and Pack exports require their existing scopes, ownership/grants and license rules. A tasks-only connection does not grant Show access; the explicit Hightopo profile adds owned private draft/source/assets access and grants neither publication nor browser login.

Normal Show navigation is https://zzd.show/s/{public_id}/run/ using the returned public_id and current access. The isolated runtime's one-time POST bootstrap is issued by authorized navigation: do not bookmark/replay it or substitute a GET. Do not put a bearer, main-site cookie, lease or bootstrap token into shared links, prompts or Show code. Runtime root and old integer-PK blank paths are not public alternatives.

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

## Continue an existing Hightopo worker

Read https://zzd.show/collaboration/start/, https://zzd.show/collaboration/protocol/hightopo/ and https://zzd.show/collaboration/protocol/hightopo.json; verify https://zzd.show/collaboration/worker-guard.json against the downloaded guard bytes. Keep the original worker/session/claim, host context, private credential, working directory, pending request and lease state. The machine software workflow does not import or adopt old Hightopo guard identities. Use guard check before continuing; expired or mismatched identities follow existing recovery, not re-registration or a replacement Show.

The 15 original Packs still need source/license confirmation. Physical external-machine and real-provider acceptance is not established by documentation, synthetic fixtures or installing software. Do not install unknown HT packages, imply a vendor license, forward chats, read ambient model accounts, authorize fees or upload local unsynced Shows.

The original ZIP/file lifetime fields are immutable historical issuance metadata, including an old finite date, and cannot override verified live authorization. The current independent guard uses normal authenticated same-origin HTTPS to verify the same owner/account and credential, original v2 key where present, all original scopes, active unrevoked status and an enabled account; the server continues to verify the original secret hash. Accept live expires_at:null only together with permanent:true. A live finite expiry must remain a valid timezone-aware future timestamp. Missing, malformed or contradictory lifetime metadata is not proof of permanence. A server expiry/revocation rejection still stops writes; an expired bearer cannot renew itself. Task leases, execution approvals and runtime tickets keep their separate finite deadlines. Explicitly download and verify the updated independent helper when an old embedded guard rejects valid lifetime metadata; this does not update historical software ZIPs or require changing the original private connection, home, context or worker state.

### Codex continuation prompt

在当前已授权的 Codex 会话接续原任务。原任务=<任务UUID>；私有连接=<原文件绝对路径>；工作目录=<原绝对路径>；宿主上下文=codex:<当前任务ID>。先读 https://zzd.show/docs/ai/branch/quickstart-resume/，按原身份和状态继续。不重新注册、自动升级或复制其他任务身份；秘密留在本机，只报告实际结果。作品反馈明示PK/id、作品号public_id、正式链接和状态，优先复制data.delivery.feedback_line；缺项GET原作品，不新建或另问授权。回复要求不是manifest字段。

### Claude continuation prompt

在当前已授权的 Claude 会话接续原任务。原任务=<任务UUID>；私有连接=<原文件绝对路径>；工作目录=<原绝对路径>；宿主上下文=claude:<当前任务ID>。先读 https://zzd.show/docs/ai/branch/quickstart-resume/，按原身份和状态继续。不重新注册、自动升级或复制其他任务身份；秘密留在本机，只报告实际结果。作品反馈明示PK/id、作品号public_id、正式链接和状态，优先复制data.delivery.feedback_line；缺项GET原作品，不新建或另问授权。回复要求不是manifest字段。