@ttmg/cli 0.4.6-vibe-beta.5 → 0.4.6-vibe-beta.7

package/README.md

@@ -21,8 +21,24 @@ npm install @ttmg/cli --save-dev
 
 #### Login 登录
 
-Before running any `ttmg` commands, please log in with your TikTok account. Once logged in, the tool will automatically use your account for project initialization, development, debugging, and packaging.
-在首次使用 `ttmg` 命令前，请先登录你的 TikTok 账号。登录后，工具会自动使用该账号进行项目初始化、开发调试和打包构建。
+For the beta.7 trial, run `ttmg upload --vibe --mock` without environment setup.
+Task creation/polling use the built-in PPE lane; authorization and uploads remain
+simulated. Unlike beta.6, this is not offline: backend access is required and task
+creation is a real platform write. See [Vibe binding/upload](vibe-upload.md).
+beta.7 试用直接运行 `ttmg upload --vibe --mock`，不用登录或配置环境变量。
+创建／查询任务走 CLI 内置 PPE，授权／上传继续模拟；与 beta.6 不同，不再是全程离线。
+需要后端可访问，会创建真实任务，不上传游戏、不预览、不审核或发布。
+
+```sh
+npm install -g @ttmg/cli@0.4.6-vibe-beta.7
+ttmg upload --vibe --mock --dir ./game --title "My game" --icon ./avatar.png --format ndjson
+```
+
+PPE routing will be removed in a production release without Skill environment setup.
+上线时由 CLI 去掉 PPE 路由，不让 Skill 配置或切换环境。
+
+For the existing authenticated platform workflow, log in first; this does not apply to the local Vibe prototype above.
+原有需要平台鉴权的流程仍先登录；上述 Vibe 本地原型不需要此步骤。
 
 ```
 ttmg login
@@ -98,6 +114,36 @@ ttmg dev --client-key <client-key> --events ndjson --no-open
 ttmg dev --client-key <client-key> --events ndjson --no-open --timeout 120
 ```
 
+For an Agent-owned iOS client-preview session, opt in explicitly. TikTok must
+still be opened by a human scanning the generated QR code. The resident `ttmg
+dev` process then owns the Runtime Debug WebSocket and performs client setup,
+package upload, and metadata delivery without opening the browser IDE.
+Agent 真机预览需显式开启；仍由用户使用 TikTok 扫描生成的二维码。扫码后，常驻
+`ttmg dev` 进程会独占 Runtime Debug WebSocket，并在不打开浏览器 IDE 的情况下完成
+客户端初始化、包上传和 meta 下发。
+
+```
+ttmg dev --mode client-preview --client-key <client-key> --events ndjson --no-open --timeout 600
+```
+
+The lifecycle includes `READY_FOR_SCAN`, `DEVICE_DISCOVERED`,
+`RUNTIME_AUTHENTICATED`, `UPLOAD_START`, `UPLOAD_READY`, and `PREVIEW_READY`.
+The initial integration scope is iOS `native_runtime` and `structured_trace`,
+while the V1 record schema preserves open `source`, `kind`, and extension
+fields for Android and future runtimes. Runtime credentials remain in the
+owner process memory and are never written to the session manifest or event
+files.
+生命周期依次包含 `READY_FOR_SCAN`、`DEVICE_DISCOVERED`、
+`RUNTIME_AUTHENTICATED`、`UPLOAD_START`、`UPLOAD_READY` 和 `PREVIEW_READY`。
+
+真机预览模式会串行编译，并将每次成功编译的文件与包元数据保存为配套的临时快照。
+上传期间再次编译时，当前部署完成后会继续部署最新的一版；中间待部署版本可被合并。
+`PREVIEW_READY` 只在一版实际上传和 meta 请求完成后输出。旧快照在替换或 session
+关闭时清理；普通浏览器 `ttmg dev` 的编译与上传流程不变。
+首期接入范围仍是 iOS `native_runtime` 与 `structured_trace`，但 V1 记录模型会
+保留开放的 `source`、`kind` 和扩展字段，可兼容 Android 与后续 Runtime。
+Runtime 凭据仅保存在 owner 进程内存中，不会写入 manifest 或事件文件。
+
 The command writes `manifest.json`, `events.ndjson`, `actions.ndjson`,
 `screenshots/`, `summary.json`, and `launch.png` under
 `.ttmg/sessions/<session-id>/` by default. `launch.rawUrl` and
@@ -106,12 +152,14 @@ and client connection events. Compile events also include the normalized
 project diagnostics produced by the existing checker. The existing runtime
 `reportScene({ sceneId: 9999 })` signal is forwarded to the CLI as a
 `GAME_READY` lifecycle event; a stopped session is only marked `passed` after
-that evidence is observed. Device launch, runtime logs, screenshots, and
-actions remain unavailable and are reported as `false` capabilities. The
+that evidence is observed. Device launch and remote actions remain unavailable.
+Runtime logs and screenshots expose an experimental iOS/V1 protocol surface,
+but remain reported as unverified (`false`) top-level capabilities until
+real-device acceptance. The
 manifest keeps `gameReady=false` until this path completes real-device
 verification, while `gameReadyProtocol=true` only declares local protocol
 support.
-命令默认在 `.ttmg/sessions/<session-id>/` 写入 `manifest.json`、`events.ndjson`、`actions.ndjson`、`screenshots/`、`summary.json` 和 `launch.png`，其中 `launch.rawUrl` 与 `launch.qrPayload` 完全一致。本 beta 会把现有运行时 `reportScene({ sceneId: 9999 })` 信号旁路转发为 CLI 的 `GAME_READY` 生命周期事件；会话只有观察到该证据后才把 `summary.json` 写为 `passed`。设备直开、运行时日志、截图和操作仍返回 `false`，不伪造已支持状态。真实设备联调完成前，manifest 保持 `gameReady=false`，仅用 `gameReadyProtocol=true` 表示本地协议已经接通。
+命令默认在 `.ttmg/sessions/<session-id>/` 写入 `manifest.json`、`events.ndjson`、`actions.ndjson`、`screenshots/`、`summary.json` 和 `launch.png`，其中 `launch.rawUrl` 与 `launch.qrPayload` 完全一致。本 beta 会把现有运行时 `reportScene({ sceneId: 9999 })` 信号旁路转发为 CLI 的 `GAME_READY` 生命周期事件；会话只有观察到该证据后才把 `summary.json` 写为 `passed`。设备直开和远程操作仍不可用；运行时日志与截图已提供实验性的 iOS/V1 协议入口，但真实设备验收完成前，顶层 capabilities 仍保持 `false`，不伪造已完成状态。真实设备联调完成前，manifest 保持 `gameReady=false`，仅用 `gameReadyProtocol=true` 表示本地协议已经接通。
 编译事件会同时包含现有检查器产生的标准化项目诊断，Agent 不需要再从拼接后的错误文本反推问题位置。
 
 Structured sessions can be discovered, inspected, and safely stopped from a
@@ -126,6 +174,41 @@ ttmg dev session events <session-id> --after <seq> --limit <count> --format json
 ttmg dev session stop <session-id> --format json
 ```
 
+While a client-preview owner is running, another CLI process can read a bounded
+snapshot, follow logs for a bounded interval, or request a screenshot. Runtime
+cursor values are decimal strings and must not be parsed as JavaScript numbers.
+Logs remain in bounded memory and are not copied into `events.ndjson` or a log
+file. Screenshot stdout contains metadata only; the binary is written to disk
+without overwriting an existing explicit destination.
+真机预览 owner 运行期间，另一个 CLI 进程可读取有界日志快照、在有界时间内 follow，
+或请求截图。Runtime cursor 是十进制字符串，不应转换为 JavaScript Number。日志只在
+有界内存中保留，不写入 `events.ndjson` 或额外日志文件；截图 stdout 只返回元数据，
+图片写入磁盘，且不会覆盖显式指定的已有文件。
+
+`--follow` 先订阅再请求一次受 `--limit` 限制的历史快照，缓存请求期间到达的实时
+日志并排序去重后继续输出；不会自动分页全部历史（`hasMore` 表示仍有历史可补拉）。
+过渡缓存限制为 10000 条／10 MiB，超限返回明确错误，可从最后收到的 cursor 重试；
+等待初始快照也计入 follow 超时。中文和 emoji 的跨 IPC 分块传输保持完整。
+
+Runtime Session 切换（例如重新扫码）会使正在运行的 `--follow` 以
+`RUNTIME_SESSION_MISMATCH` 结束，包括仍在等待初始快照的监听。新会话就绪后，
+用同一个 CLI session-id 重新执行命令，但不要复用旧 Runtime 的 `--after`／`--until`
+游标；同一 Runtime Session 的普通断线重连不会终止 follow。
+
+```
+ttmg dev session logs <session-id> --after <cursor> --until <cursor> --limit 200 --format json
+ttmg dev session logs <session-id> --after <cursor> --follow --timeout 30 --format ndjson
+ttmg dev session screenshot <session-id> --image-format jpeg --quality 0.8 --output <path> --format json
+```
+
+If an older client does not advertise Runtime Debug V1, the original preview
+flow remains compatible, while the new session commands return
+`RUNTIME_DEBUG_UNSUPPORTED`. If the owner process has exited, they return
+`DEV_SESSION_NOT_RUNNING`; logs are never reconstructed from disk.
+旧客户端未声明 Runtime Debug V1 时，原预览链路保持兼容，新 session 命令返回
+`RUNTIME_DEBUG_UNSUPPORTED`。owner 退出后返回 `DEV_SESSION_NOT_RUNNING`，不会从
+磁盘伪造历史日志。
+
 #### Project Check 项目检查
 
 Run the existing project, package-size, subpackage, path, and API checks without