@ttmg/cli 0.4.6-vibe-beta.2 → 0.4.6-vibe-beta.4

package/README.md

@@ -87,13 +87,15 @@ ttmg dev
 ```
 
 For Agent usage, pass the Client Key explicitly, suppress the browser, and
-request the session manifest plus NDJSON lifecycle events. The existing
-interactive `ttmg dev` flow is unchanged.
-Agent 调用时需显式传入 Client Key、禁止自动打开浏览器，并读取会话描述和 NDJSON 生命周期事件；原有交互式 `ttmg dev` 流程保持不变。
+choose either one JSON session manifest or an NDJSON lifecycle event stream.
+The two stdout modes are mutually exclusive. The existing interactive `ttmg
+dev` flow is unchanged.
+Agent 调用时需显式传入 Client Key、禁止自动打开浏览器，并在单份 JSON 会话描述和 NDJSON 生命周期事件流中二选一；两种 stdout 模式不能同时使用。原有交互式 `ttmg dev` 流程保持不变。
 
 ```
-ttmg dev --client-key <client-key> --format json --events ndjson --no-open
-ttmg dev --client-key <client-key> --format json --events ndjson --no-open --timeout 120
+ttmg dev --client-key <client-key> --format json --no-open
+ttmg dev --client-key <client-key> --events ndjson --no-open
+ttmg dev --client-key <client-key> --events ndjson --no-open --timeout 120
 ```
 
 The command writes `manifest.json`, `events.ndjson`, `actions.ndjson`,
@@ -191,9 +193,13 @@ The upload command packages the project and creates a new Developer Platform
 version. With `--preview`, it also waits for platform processing and returns the
 preview payload.
 上传命令会打包项目并在 Developer Platform 创建新版本；增加 `--preview` 后还会等待平台处理完成并返回预览地址。
+The upload ZIP excludes the root `.agent`, `.claude`, and `.trae` directories.
+上传 ZIP 不包含项目根目录下的 `.agent`、`.claude` 和 `.trae`。
 
 ```
 ttmg upload --preview --client-key <client-key> --dir <game-dir> --format ndjson
+ttmg upload --preview --serve-preview-page --client-key <client-key> --dir <game-dir> --format ndjson
+ttmg upload --preview --serve-preview-page --client-key <client-key> --dir <game-dir>
 ```
 
 The NDJSON states are `precheck`, `packaging`, `uploading`,
@@ -202,7 +208,24 @@ the identical `qrPayload`, the platform version URL, and `platformWrite: true`.
 During platform processing, `platformStatus` uses readable values such as
 `waiting_for_asset`, `pending`, `processing`, `success`, and `failed`; the
 optional `platformStatusRaw` retains the original platform enum for debugging.
+With `--serve-preview-page`, every successful upload returns a new
+`previewPage.url`. The responsive local page guides users through test-account
+authorization and preview launch with two QR codes and direct links. Its HTML
+and QR images remain in memory. Repeated uploads for the same Client Key reuse
+one localhost service: the new URL replaces the previous page immediately and
+renews the one-hour TTL. When the page expires, its QR content is removed from
+memory and the same URL shows a retry command for one more hour before the
+service exits. Different Client Keys use independent services. In default text
+mode the CLI prints a browser-oriented result block and opens the page in the
+default browser; `--no-open` suppresses that action. JSON and NDJSON modes never
+open a system browser and instead return a `presentation` contract with
+`preferredAction: "open_url"` and a clickable-link fallback for Agents. Only
+minimal process-coordination metadata is stored in the operating system's temp
+directory; no page assets are written to the project or disk. If the local page
+fails, the platform upload remains `ready` and `previewPage.status` is `failed`,
+so callers must not retry the upload just to recreate the page.
 NDJSON 状态依次为 `precheck`、`packaging`、`uploading`、`processing`，最终进入 `ready` 或 `failed`。平台处理阶段的 `platformStatus` 使用 `waiting_for_asset`、`pending`、`processing`、`success`、`failed` 等可读值；可选的 `platformStatusRaw` 仅保留平台原始枚举用于排障。成功结果包含 `previewUrl`、与其一致的 `qrPayload`、平台版本地址和 `platformWrite: true`。
+增加 `--serve-preview-page` 后，每次成功上传都会返回新的 `previewPage.url`。响应式本地页面通过两个二维码和直接链接依次承接测试账号授权与预览启动；HTML 和二维码只驻留内存。同一个 Client Key 反复上传时复用同一个 localhost 服务，新地址会立即替换旧页面并重新计算 1 小时有效期；到期后清除内存中的二维码，原地址继续显示 1 小时的重新执行提示，随后服务退出。不同 Client Key 使用独立服务。默认文本模式会打印浏览器展示信息并自动打开页面，`--no-open` 可关闭自动打开；JSON 和 NDJSON 模式不会调用系统浏览器，而是返回 `preferredAction: "open_url"` 和链接降级方式供 Agent 执行。系统临时目录只保存最小进程协同信息，不写入页面资源或项目内容。如果本地页面失败，平台上传仍保持 `ready`，并通过 `previewPage.status=failed` 返回局部失败；调用方不能为重新生成页面而重复上传。
 
 - 调试 H5 小游戏：
 - To debug H5 mini-games: