@ttmg/cli 0.4.5 → 0.4.6-agent-beta.1

package/README.md

@@ -1,8 +1,18 @@
 ### @ttmg/cli
+
 `ttmg` is a command-line tool designed for managing and developing mini-game projects. It supports initialization, development, debugging, and packaging for both H5 and native mini-games.
 `ttmg` 是一款专为小游戏项目管理与开发设计的命令行工具，支持 H5 小游戏和原生小游戏的初始化、开发调试及打包构建。
+
 #### Installation 安装
 
+The Wasm split binding loads only when preparing or splitting Unity Wasm. A
+missing platform binding does not block CLI startup or unrelated commands.
+The split dependency `@anrans001/ttmg-wasmtool@0.3.3` provides Linux x64/arm64
+bindings for GNU and musl. CLI execution on Linux still needs validation.
+Unity Wasm 原生分包依赖仅在 prepare / split 时加载，缺少对应平台二进制不会阻断
+CLI 启动及其他命令；`@anrans001/ttmg-wasmtool@0.3.3` 已提供 Linux x64/arm64
+的 GNU、musl 原生包，CLI 在实际 Linux 环境的运行仍待验证。
+
 You can install `ttmg` globally or as a project dependency via npm:
 你可以通过 npm 全局或本地安装 `ttmg`：
 
@@ -19,13 +29,77 @@ 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 账号。登录后，工具会自动使用该账号进行项目初始化、开发调试和打包构建。
+The experimental `upload --vibe` local prototype does not require platform login.
+Use `ttmg upload --vibe --mock` for the integration trial. No environment setup:
+task creation/polling use the built-in PPE lane; authorization and uploads are
+simulated. See [Vibe binding/upload](vibe-upload.md) for schema-v2 results.
+实验性 `upload --vibe --mock` 不要求平台登录或环境配置。CLI 内置 PPE 创建／查询任务，
+模拟授权和上传；本次结束于模拟上传完成，不含预览和发布。详见 [Vibe 绑定上传](vibe-upload.md)。
+
+`--mock` 现在会真实创建 PPE 任务，不再表示全程离线；真实请求失败仍报错。
+上线时由 CLI 发布版本去掉 PPE 路由，Skill 无需承担环境切换。
+`--mock` now creates real PPE tasks, not a fully offline run. Real request failures
+still fail. Production routing is a future CLI release change, not Skill configuration.
+
+维护者可用 `--app-info ./app-info.json --dry-run` 校验完整应用信息和平台头像要求；文件字段见 [Vibe 绑定上传](vibe-upload.md)。不传此选项时，现有 Mock 输入保持不变。真实上传仍未开放。
+Maintainers can add `--app-info ./app-info.json --dry-run` to validate complete metadata and platform icon requirements; see [Vibe binding/upload](vibe-upload.md). Existing Mock inputs remain unchanged without this option. Real upload remains disabled.
+
+For the existing authenticated platform workflow, log in first; this does not apply to the local Vibe prototype above.
+原有需要平台鉴权的流程仍先登录；上述 Vibe 本地原型不需要此步骤。
 
 ```
 ttmg login
 ```
 
+For Agent usage, implicit mode accepts credentials without terminal prompts,
+keeps the existing `~/.ttmgrc` write behavior, and returns one JSON result on
+stdout. The result never contains the password or session Cookie.
+Agent 可使用 implicit 模式传入账号密码，无需终端交互；登录成功后继续按原逻辑写入 `~/.ttmgrc`，stdout 返回一个 JSON 结果，结果中不包含密码或会话 Cookie。
+
+```
+ttmg login --implicit --email <email> --password <password>
+```
+
+`TTMG_LOGIN_EMAIL` and `TTMG_LOGIN_PASSWORD` can replace the two credential
+options when credentials are provided by the execution environment.
+执行环境也可以通过 `TTMG_LOGIN_EMAIL` 和 `TTMG_LOGIN_PASSWORD` 提供凭据。
+
+Inspect the reusable local session without exposing its Cookie. The status is
+local-only; it does not make a network request. `--require-auth` is useful for
+Agent preflight because it exits non-zero when login is missing.
+可在不暴露 Cookie 的情况下读取本地会话是否可复用。该状态只检查本地配置，不发起网络请求；Agent 预检可增加 `--require-auth`，未登录时以非零状态退出。
+
+```
+ttmg auth status --format json
+ttmg auth status --format json --require-auth
+```
+
+Agents can discover the exact command and runtime capability surface before
+acting. Unsupported device and Runtime features are explicitly reported as
+`false`; commands that create a platform version are marked with
+`platformWrite: true`.
+Agent 可在执行前读取当前 CLI 的准确能力；尚未支持的设备和 Runtime 能力明确返回 `false`，会创建平台版本的命令明确标记 `platformWrite: true`。
+
+```
+ttmg capabilities --format json
+```
+
+#### Test Account 测试账号
+
+Generate the TikTok authorization link and QR code for a Mini Game test account.
+This command does not write to Developer Platform automatically; verify the
+account in the project's Test User list after scanning.
+为小游戏生成 TikTok 测试账号授权链接和二维码。该命令不会自动写入 Developer Platform；扫码后仍需在项目 Test User 列表确认账号状态。
+
+```
+ttmg test-account add --client-key <client-key>
+ttmg test-account add --client-key <client-key> --format json
+```
+
+The QR code is written to `.ttmg/test-account-<client-key>.png` by default. Use
+`--qr-output <path>` to choose another path.
+二维码默认写入 `.ttmg/test-account-<client-key>.png`，可通过 `--qr-output <path>` 指定其他路径。
+
 #### Debugging 调试
 
 - By default, debug native mini-games:
@@ -35,6 +109,574 @@ ttmg login
 ttmg dev
 ```
 
+For Agent usage, pass the Client Key explicitly, suppress the browser, and
+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 --no-open
+ttmg dev --client-key <client-key> --events ndjson --no-open
+ttmg dev --client-key <client-key> --events ndjson --no-open --timeout 120
+```
+
+### Manual iteration workflow / 按轮更新与验证
+
+Use a converted Native game project and an existing Client Key. The following
+commands run on the same executor, which must be reachable from the phone and
+able to reach the phone. The first command returns while the preview runs in
+the background; it reuses a compatible owner in the current project. Scan the
+returned QR once, then submit and observe each update.
+
+在已转换的 Native 游戏工程目录调用，使用已有 Client Key。命令在同一执行机
+运行，执行机与手机须双向可达。启动命令返回后，预览进程继续在后台运行；同一
+工程有配置匹配的预览时会复用。首次扫描返回的二维码，然后逐轮提交更新与读取结果。
+
+```bash
+ttmg dev --mode client-preview --update-mode manual --background --client-key <CLIENT_KEY> --record-logs --format json
+ttmg dev sync --request-id round-1 --format json
+ttmg dev observe --iteration round-1 --timeout 30 --format json
+ttmg dev session stop <SESSION_ID> --format json
+```
+
+- `sync` freezes project inputs before compilation and returns an iteration ID
+  and build ID. Reusing a request ID returns that same iteration, even if files
+  changed; use a new ID for new code. Keys are retained for the owner lifetime,
+  up to 1000 updates. Wait for an update to settle before editing the next one.
+- `observe` waits up to `--timeout` seconds (0–300, default 30) for deployment.
+  It then collects at most five log pages (200 records by default, at most 1000
+  records / 1 MiB) and one JPEG screenshot, with a separate 65-second IPC limit.
+  Each observation starts at the deployment window; repeated calls overlap.
+- Results are `pending` (query again; timeout does not resubmit), `needs_action`
+  (connect the phone using `launch`), `observed`, `partial` (inspect gaps/issues),
+  `superseded`, or `failed`. `partial` exits 2; failures exit 1; other states exit 0.
+  A truncated log result includes `nextLogQuery` for the existing `dev logs` command.
+- A deployment has a 120-second deadline; shutdown or a new Runtime cancels its
+  network requests. Connecting a new Runtime can redeploy the same captured build
+  without a new request ID or compilation. Query that iteration again afterward.
+- Log/screenshot results identify the deployment and Runtime and reject changes
+  during collection. The client has no active-build acknowledgment:
+  `runtimeBuildVerified: false`, `attribution: deployment_window`, and
+  `gameplayValidation: not_evaluated` remain explicit. Logs can include records
+  from the previous game during delivery; the Agent must inspect gameplay.
+- Manual owners pin their Client Key without changing global configuration and
+  use a session-specific build directory. Concurrent update/observation requests
+  return busy. Project symlinks and special files are rejected; `.git`, `.ttmg`,
+  `node_modules` and `__TTMG_TEMP__` are excluded from source snapshots.
+- Background mode defaults to a 1800-second lifetime (`--timeout`, max 86400).
+  It requires the default evidence directory; custom directories and external
+  supervisors can use foreground `--update-mode manual`. Startup waits at most
+  60 seconds. Reuse does not renew an owner's lifetime. A crashed start leaves
+  `.ttmg/preview-start.lock`; verify the starter has exited before removing it.
+
+- `sync` 固定工程输入后构建，返回本轮与构建标识。相同请求标识始终返回同一轮，
+  即使文件已经改变；新代码使用新标识。标识在进程存活期间保留，最多 1000 轮。
+  等本轮完成后再编辑下一轮代码。
+- `observe` 等待部署 0–300 秒，默认 30 秒；之后最多读取 5 页日志和一张 JPEG
+  截图，采集另有 65 秒 IPC 上限。默认 200 条日志，上限 1000 条 / 1 MiB。
+  每次从该次部署的观察窗口读取，重复调用会有重叠日志。
+- `pending` 继续查询；超时不重新提交。`needs_action` 使用 `launch` 连接手机。
+  `observed` 可读取结果；`partial` 检查缺失与错误；`superseded` 选择新轮次；
+  `failed` 按原因修复。`partial` 退出码为 2，失败为 1，其余为 0。
+  日志截断时，可将 `nextLogQuery` 交给已有 `dev logs` 命令续读。
+- 部署设有 120 秒超时；停止会话或切换 Runtime 会取消部署中的网络请求。
+  连接新的 Runtime 可继续部署同一份构建，无须换请求标识或重新编译；之后查询原轮次。
+- 结果关联部署与 Runtime，采集中发生变化会拒绝返回。客户端尚无已激活构建确认，
+  因此明确返回 `runtimeBuildVerified: false`、`attribution: deployment_window`
+  和 `gameplayValidation: not_evaluated`。日志可能含部署期间的旧游戏记录，仍需
+  Agent 判断画面与玩法。
+- 手动更新模式固定本进程的 Client Key，不修改全局配置；每个会话独立存放构建
+  产物。更新或观察期间的并发请求返回忙碌。输入不支持符号链接和特殊文件；快照
+  排除 `.git`、`.ttmg`、`node_modules` 和 `__TTMG_TEMP__`。
+- 后台默认存活 1800 秒，可通过 `--timeout` 指定，最大 86400 秒；复用不延长
+  原进程寿命。后台使用默认结果目录，启动最多等待 60 秒。自定义目录或已有进程
+  托管器可直接使用前台 `--update-mode manual`。启动器崩溃遗留
+  `.ttmg/preview-start.lock` 时，确认启动器已退出后再删除锁。
+
+### Wasm prepare and split / Wasm 准备与分包
+
+```bash
+ttmg wasm prepare --input original.wasm.br --output prepared --format json
+ttmg wasm split --input original.wasm.br --collection collection.json --output split --format json
+```
+
+These experimental commands create artifacts in a new directory; they do not
+rewrite the original Wasm, `game.json` or Unity plugin configuration. Supply
+collection JSON with `schemaVersion: "1"`, `wasmSha256` from prepare's
+`input.wasmSha256`, nonempty `funcIds`, and optional `bootFuncIds`. The hash is
+for the uncompressed original Wasm, never the instrumented file. Collection must
+come from running the corresponding instrumented project.
+
+`--dry-run` validates inputs without loading the native library or writing final
+outputs. Native work has a 300-second default deadline (`--timeout`, 1–3600).
+Existing output directories are rejected. Successful results include artifact
+sizes, SHA256 hashes and a `manifest.json` completion marker; they leave
+`gameValidation: not_evaluated`. Binary validation uses the current Node.js
+WebAssembly engine. Version 0.3.3 provides Linux bindings; Linux execution remains unverified;
+an unavailable binding returns `WASM_BINDING_UNAVAILABLE` for this operation.
+
+命令把产物写入新目录，不改写原始 Wasm、`game.json` 或 Unity 插件配置。
+采集 JSON 包含 `schemaVersion: "1"`、prepare 返回的 `input.wasmSha256`、
+非空 `funcIds` 和可选 `bootFuncIds`。哈希对应解压后的原始 Wasm，不能使用
+插桩文件的哈希；函数数据来自对应插桩工程的玩法采集。
+
+`--dry-run` 校验输入，不加载原生库或写入最终产物。原生操作默认超时 300 秒，
+`--timeout` 范围 1–3600 秒。已有输出目录会被拒绝。成功结果含文件大小、SHA256
+与完成标记 `manifest.json`，`gameValidation` 仍为 `not_evaluated`。二进制结构
+使用当前 Node.js 的 WebAssembly 引擎校验。0.3.3 已提供 Linux 原生包，实际 Linux 运行仍待验证；
+原生库不可用时，此操作返回 `WASM_BINDING_UNAVAILABLE`。
+
+Native `ttmg build` now performs the same local debug build in text and JSON
+modes. This replaces the former text-mode placeholder; the JSON schema remains
+version 1. It does not create a platform version. Existing watch-mode `dev` and
+atomic log/screenshot commands retain their behavior.
+
+Native `ttmg build` 的 text 与 JSON 模式现执行相同本地调试构建，取代原来的
+text 占位提示；JSON schema 保持版本 1，不创建平台版本。原有自动监听 `dev`
+和单独日志、截图命令保持可用。
+
+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
+`launch.qrPayload` are identical. This beta exposes the local DevTool session
+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; an ordinary browser session is only marked `passed`
+after that signal is observed. A client-preview session uses `PREVIEW_READY`
+instead: this confirms package and metadata delivery, not gameplay acceptance.
+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`。client-preview 会话使用 `PREVIEW_READY` 判断，只表示包和元数据下发完成，不代表玩法验收通过。设备直开和远程操作仍不可用；运行时日志与截图已提供实验性的 iOS/V1 协议入口，但真实设备验收完成前，顶层 capabilities 仍保持 `false`，不伪造已完成状态。真实设备联调完成前，manifest 保持 `gameReady=false`，仅用 `gameReadyProtocol=true` 表示本地协议已经接通。
+编译事件会同时包含现有检查器产生的标准化项目诊断，Agent 不需要再从拼接后的错误文本反推问题位置。
+
+Structured sessions can be discovered, inspected, and safely stopped from a
+new CLI process. Stop verifies that the recorded PID is a `ttmg dev` process
+before sending SIGTERM.
+结构化会话可以由新的 CLI 进程列出、查询和安全停止；停止前会确认 manifest 中记录的 PID 确实属于 `ttmg dev`，不会直接终止无法验证的进程。
+
+```
+ttmg dev session list --format json
+ttmg dev session inspect <session-id> --format json
+ttmg dev session events <session-id> --after <seq> --limit <count> --format json
+ttmg dev session stop <session-id> --format json
+```
+
+For terminal development, start client preview from the game project. Scan the
+QR on the automatically opened local scan page or in the terminal with TikTok;
+compilation, connection status, and live Runtime logs
+appear in the same terminal. Code changes deploy to the connected device. This
+mode does not open the browser IDE; ordinary `ttmg dev` remains unchanged.
+在游戏工程目录启动真机预览，用 TikTok 扫描自动打开的本地网页或终端二维码，
+在同一终端查看编译、
+连接状态和实时 Runtime 日志；代码修改后更新到已连接设备。这个模式不打开浏览器
+IDE，普通 `ttmg dev` 的行为不变。
+
+```bash
+ttmg dev --mode client-preview --client-key <CLIENT_KEY>
+# Keep both QR options without opening a browser / 保留两种扫码方式，但不自动打开浏览器
+ttmg dev --mode client-preview --client-key <CLIENT_KEY> --no-open
+# Another terminal in the same project / 在同一工程的另一个终端
+ttmg dev screenshot
+ttmg dev logs
+ttmg dev logs --follow --timeout 30
+```
+
+The scan page shows the project and QR, compile/connection/upload/update stages,
+upload percentage and the last completed delivery. Manual sessions also show the
+current `request-id`, matching the `iterationId` returned by `dev sync`; before the
+first sync they show “No update submitted”. Agents generate a new ID per update
+and reuse it when retrying the same update. It shows whether updates are
+manual (`dev sync`) or automatic. Developer options cover request-domain checks,
+mock ads/purchases, vConsole and the developer info panel. Save explicitly;
+preferences last for this preview session. Before connecting, saving prepares the
+next launch. When connected, “Save and reload game” reinitializes the game, sends
+the options, uploads the current compiled build and sends game metadata. Changes
+saved during loading queue another setup with the latest options. This reuses the
+build and request ID without recompiling. The `reload` status is `pending`,
+`reloading`, `delivered` or `failed`; `delivered` confirms redelivery, not game activation.
+Agents can read the same values and delivery state from `developerOptions` at
+`<launch.scanPageUrl>/status` (or `debugSettings` in IPC `session.status`).
+The page is computer-local and served by the same CLI process;
+refreshing it never establishes another Runtime connection. Both QR forms carry
+the same device launch URL. The page link is for the computer, not the phone.
+`--no-open` and `TTMG_DEV_NO_OPEN=1` suppress automatic opening. JSON/NDJSON modes
+never open a browser or draw a terminal QR; they expose `launch.scanPageUrl` in
+the manifest and `scanPageUrl` in `READY_FOR_SCAN`, retaining the PNG path and
+raw launch URL. If browser opening fails, use the printed page link or PNG.
+When the CLI stops, the page detects the unavailable service and hides the QR.
+扫码页展示工程、二维码、编译／连接／上传／配置下发状态、上传百分比和最近下发完成时间，
+并区分手动 `dev sync` 与自动更新。
+手动模式显示当前 `request-id`，与 `dev sync` 返回的 `iterationId` 对应；首次 sync
+前显示“尚未提交更新”。每轮 ID 由 Agent 生成，同一轮重试复用原 ID。
+开发者选项支持请求域名校验、广告和内购模拟、vConsole、开发者信息面板；点击保存后
+仅保留在本次会话。连接前保存供下次启动使用；连接后点击“保存并重新加载”，
+会重新初始化游戏、发送配置、上传当前编译包并下发游戏信息。加载中再次保存会排队，
+随后按最新配置重新执行；复用当前构建和 request-id，不重新编译。
+`reload` 分别为 `pending`、`reloading`、`delivered`、`failed`；
+下发完成后仍需在手机确认游戏结果。Agent 可读取
+`<launch.scanPageUrl>/status` 的 `developerOptions`，或 IPC `session.status`
+的 `debugSettings`，取得相同配置及发送状态。
+页面由同一 CLI 进程提供，仅允许本机访问；刷新网页不会另建 Runtime 连接。
+两种二维码使用同一个真机启动链接，
+网页地址供电脑打开，不是让手机访问 localhost。`--no-open` 和
+`TTMG_DEV_NO_OPEN=1` 禁止自动打开。JSON/NDJSON 模式不打开浏览器、不绘制终端
+二维码，通过 manifest 的 `launch.scanPageUrl` 和 `READY_FOR_SCAN` 的
+`scanPageUrl` 返回网页地址，原 PNG 路径与启动链接保留。浏览器打开失败时可手动
+打开输出链接或 PNG。CLI 停止后，网页检测到服务不可用并隐藏二维码。
+
+These shortcuts find the unique running client-preview session in this project,
+including from a subdirectory. If multiple sessions are running, the command
+lists them and requires `--session <session-id>`; it never silently picks one.
+Use `--sessions-dir <path>` for a custom session collection or the exact directory
+specified with `--evidence-dir`. Screenshot output prints the saved file path;
+use `--output <path>` for a custom destination. Log follow ends after 30 seconds
+by default without stopping preview; the owner terminal streams logs until you
+stop preview with Ctrl+C. Both logs and screenshots require a compatible client.
+快捷命令自动找到当前工程（含子目录）唯一的运行中真机预览会话；多个会话时列出
+候选，需用 `--session <session-id>` 明确选择，不会自动连接任意设备。
+自定义证据目录使用 `--sessions-dir <path>`，可以指定会话集合目录或启动时的
+`--evidence-dir`。截图完成后输出本地保存路径，支持 `--output <path>`。
+`logs --follow` 默认读取 30 秒后退出，不停止预览；主终端持续输出日志，Ctrl+C
+停止预览。日志和截图均需要客户端支持对应协议。
+
+For automation, use `dev logs --format json`, `dev logs --follow --format ndjson`,
+or `dev screenshot --format json`. Successful results reuse the existing
+`dev.session.logs` / `dev.session.screenshot` schema and command names. Session
+selection failures return `DEV_SESSION_NOT_RUNNING` or `DEV_SESSION_AMBIGUOUS`
+with a non-zero exit code. The explicit `dev session ...` commands below remain
+available without changing their default output format.
+自动化可用 `dev logs --format json`、`dev logs --follow --format ndjson` 或
+`dev screenshot --format json`，成功结果沿用原有 `dev.session.logs` /
+`dev.session.screenshot` 的 schema 和 command 字段。未找到运行中会话或存在多个
+会话时返回 `DEV_SESSION_NOT_RUNNING` / `DEV_SESSION_AMBIGUOUS`，并以非零状态退出。
+下方显式 `dev session ...` 命令及默认输出格式保持兼容。
+
+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.
+By default 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` for live reads; explicit archive reads are described below.
+旧客户端未声明 Runtime Debug V1 时，原预览链路保持兼容，新 session 命令返回
+`RUNTIME_DEBUG_UNSUPPORTED`。owner 退出后实时查询返回 `DEV_SESSION_NOT_RUNNING`；
+本地留存日志必须显式选择 archive，不会冒充实时结果。
+
+### Agent log retrieval / AI 日志读取
+
+#### Capture screen and session logs / 一次获取画面和会话日志
+
+```bash
+ttmg dev capture --format json
+```
+
+English: In a project with a connected client-preview session, this command
+captures the current game screen and automatically exports retained logs from
+the current Runtime session start to a fixed query snapshot.
+
+No iteration ID is required. Use `--session` when multiple preview sessions are running.
+
+The single JSON result contains `screenshot.path`, `logs.path`, `logs.records`,
+`logs.severityCounts`, `logs.complete`, and a manifest path.
+
+Logs are written as NDJSON under the session's `captures/` directory. The command leaves the
+game source unchanged. Exit codes are 0 for success, 2 for partial results,
+and 1 for failure.
+
+Collection is capped at 64 MiB and defaults to a 120-second budget
+(`--timeout`, 1–300; an in-flight request may add up to 10 seconds).
+
+Expired device history and interrupted exports are explicit partial results;
+`nextQuery` supplies log-resume parameters when collection stops early.
+
+The command does not merge saved archives or recover already discarded logs.
+Record content retains the Runtime's own truncation and redaction.
+
+Screenshots and logs share a Runtime identity but are not an atomic snapshot:
+the screenshot shows the current view, while logs cover the whole session,
+including earlier views.
+
+Runtime replacement rejects the capture. A screenshot
+failure can retain a complete log file; inspect both `status` and `logs.complete`.
+
+中文：在已连接 client-preview 的工程中执行该命令，即可截取当前游戏画面，并自动
+分页导出当前 Runtime 会话开始至查询快照的保留日志，无须提供轮次编号。
+多个预览同时运行时，用 `--session` 选择会话。
+
+结果只输出一个 JSON，包含截图路径 `screenshot.path`、日志文件 `logs.path`、
+条数 `logs.records`、分级统计 `logs.severityCounts`、完整性 `logs.complete`
+及 manifest 路径。日志按 NDJSON 写入会话的 `captures/`，不修改游戏源码。
+成功退出码为 0，部分成功为 2，失败为 1。
+
+导出上限为 64 MiB，默认收集预算 120 秒。`--timeout` 可设为 1–300 秒，在途请求
+最多额外等待 10 秒。历史淘汰或中途停止会明确返回部分结果，未读完时可按
+`nextQuery` 继续取日志。本命令不合并本地归档，也不能恢复已丢弃日志。
+日志内容保留 Runtime 自身的截断和脱敏处理。
+
+截图和日志绑定同一 Runtime，但不是同一时刻的原子快照。截图显示当前页面，日志
+覆盖当前会话，包括此前页面。会话切换会拒绝本次采集；截图失败仍可保留完整日志，
+因此须同时检查 `status` 和 `logs.complete`。
+
+```bash
+# Opt in to local recording when starting preview; keep this process running.
+ttmg dev --mode client-preview --client-key <CLIENT_KEY> --record-logs --format json --no-open
+
+# Read a finite snapshot from another process in the same project.
+ttmg dev logs --format json --limit 200
+
+# Follow the returned nextQuery fields. Pin both CLI and Runtime sessions.
+ttmg dev logs --session <session-id> --runtime-session <runtime-id> --after <cursor> --format json
+
+# Capture the same Runtime session as the logs.
+ttmg dev screenshot --session <session-id> --runtime-session <runtime-id> --format json
+
+# After the owner exits, read saved evidence through the same command.
+ttmg dev logs --session <session-id> --source archive --runtime-session <runtime-id> --format json
+```
+
+English: Start the long-running preview once, retain the returned `sessionId`, and
+let the user scan the QR. Use finite JSON snapshots for Agent work, not terminal
+scraping or an unbounded follow. Snapshot results include `source`,
+`runtimeSessionId`, `cursor`, and `nextQuery` (option values for the next call;
+not a shell string), including `sessionsDir`, `format`, and the bounded `limit`.
+For pagination, carry `until` while `hasMore=true`; the next query drops it once
+that snapshot is drained so subsequent logs can be read. `--runtime-session`
+rejects stale cursors with `RUNTIME_SESSION_MISMATCH`, including a replacement
+during the request. On mismatch, read a fresh snapshot without old cursors and
+confirm the new session. Follow frames also carry the Runtime identity.
+
+中文：启动一次常驻预览，保留返回的 `sessionId`，由用户扫码连接设备。AI 按需读取
+有限条数的 JSON 快照，不抓取终端内容，也不依赖持续阻塞的 follow。结果包含来源
+`source`、设备会话 `runtimeSessionId`、游标 `cursor` 和下一次调用的参数 `nextQuery`
+（参数对象，不是可执行 shell 字符串），同时带回证据目录、JSON 格式和条数上限。
+`hasMore=true` 时带上 `until` 翻页；读完当前快照后，下一次参数会移除 `until`，以读取
+后续新增日志。使用 `--runtime-session` 时，设备在两次查询间或请求中途切换都会返回
+`RUNTIME_SESSION_MISMATCH`；此时不再沿用旧游标，重新读取快照并确认新设备会话。
+follow 输出帧也携带设备会话标识。
+
+English: Screenshots return `runtimeSessionId` alongside the absolute image
+`path`. Pass the ID from your log snapshot through `--runtime-session` to either
+`dev screenshot` or `dev session screenshot`.
+
+A stale selector fails before capture. Replacement during capture fails before
+saving. Older owners without a matching identity fail pinned requests.
+Omitting the option keeps the existing behavior.
+
+中文：截图结果同时返回 `runtimeSessionId` 和图片绝对路径 `path`。将日志快照中的
+设备会话 ID 通过 `--runtime-session` 传给任一截图命令，即可校验日志与画面是否属于
+同一 Runtime 会话。旧会话参数在截图前被拒绝，截图中途切换会话时不保存图片；旧版本
+常驻进程无法返回匹配标识时，绑定请求也会报错。不传该参数仍可按原方式截图。
+
+English: Wait for the initial `PREVIEW_READY` through `dev session events` before
+capturing. After changing code, read events after your last `seq` and wait for the
+new compile and its `PREVIEW_READY`. Then read incremental logs and capture again.
+
+That event confirms package and metadata delivery. Verify actual game behavior
+with the screenshot, logs and game checkpoints.
+
+中文：首次截图前通过 `dev session events` 等待 `PREVIEW_READY`。修改代码后从上次
+`seq` 继续读事件，等待新编译及其 `PREVIEW_READY`，再取增量日志和截图。该事件只证明
+包和 meta 已送达；游戏行为是否正确仍需通过画面、日志和游戏检查点验证。
+
+English: `--record-logs` is off by default and only valid for client-preview.
+The manifest exposes `evidence.runtimeLogs`, normally
+`.ttmg/sessions/<session-id>/runtime-logs/`. It records only logs actually received
+by the CLI, after credential redaction; it cannot recover unseen device logs.
+Keep at most two 5 MiB NDJSON segments per CLI session; rotation discards the
+oldest segment. Each retained record is at most 64 KiB; oversized records are
+counted as dropped, not silently truncated. Archive results report
+`retentionLimited`, `droppedRecords`, `partialTail`, and recording state. Treat
+these as evidence gaps, not an all-clear. A recording state of `recording` after
+the owner exits means it did not close cleanly. A write failure emits
+`LOG_ARCHIVE_FAILED` and stops recording without stopping live preview. Files
+are local, not uploaded, and persist until the developer removes the session's
+evidence. Redaction is best effort; do not log secrets or share evidence blindly.
+
+中文：`--record-logs` 默认关闭，仅支持 client-preview。manifest 通过
+`evidence.runtimeLogs` 给出目录，默认是 `.ttmg/sessions/<session-id>/runtime-logs/`。
+只留存 CLI 实际收到并脱敏后的日志，不代表已收全客户端日志。每个 CLI 会话最多保留
+两个 5 MiB 的 NDJSON 分段，超限轮转丢弃最旧分段；单条超过 64 KiB 时计入丢弃数量。
+查询返回 `retentionLimited`、`droppedRecords`、`partialTail` 和留存状态，有缺口不能
+判断为“没有问题”。CLI 已退出但状态仍为 `recording` 表示未正常关闭。写入失败会发出
+`LOG_ARCHIVE_FAILED` 并停止留存，不停止实时预览。文件不会上传，开发者删除该会话
+证据前持续保留。脱敏不能替代安全日志规范，不要主动打印凭据或直接分享原始证据。
+
+English: Archive reads require an explicit CLI session, do not connect to a device,
+and do not support `--follow`. Multiple retained Runtime sessions return
+`RUNTIME_SESSION_AMBIGUOUS` with `runtimeSessions`; choose one explicitly rather
+than mixing identical cursors. Missing recordings return `DEV_LOG_ARCHIVE_NOT_FOUND`;
+corrupt data returns `DEV_LOG_ARCHIVE_READ_FAILED`. Snapshot reads during active
+rotation may return `DEV_LOG_ARCHIVE_BUSY`; retry that same query. These are local
+protocol guarantees, not real-device log-coverage acceptance.
+
+中文：archive 查询必须指定 CLI 会话，不连接设备，不支持 `--follow`。同一 CLI 会话
+包含多次设备运行时，返回 `RUNTIME_SESSION_AMBIGUOUS` 和候选 `runtimeSessions`，需
+明确选择，不混用相同数值的游标。未开启留存返回 `DEV_LOG_ARCHIVE_NOT_FOUND`，文件
+损坏返回 `DEV_LOG_ARCHIVE_READ_FAILED`；读取遇到持续轮转返回 `DEV_LOG_ARCHIVE_BUSY`，
+可按原参数重试。这些保证只覆盖本地协议，客户端日志收集完整性仍需真机验收。
+
+#### Project Check 项目检查
+
+Run the existing project, package-size, subpackage, path, and API checks without
+starting DevTool or writing to Developer Platform. Text remains the default for
+developers; Agents should request one JSON report.
+无需启动 DevTool 或写入 Developer Platform，即可执行现有的项目配置、包体、分包、路径和 API 检查。开发者默认读取文本结果；Agent 使用单个 JSON 报告。
+
+```
+ttmg check
+ttmg check --dir <game-dir> --format json
+ttmg check --dir <game-dir> --format json --include-passed
+ttmg check --dir <game-dir> --format json --fail-on warning
+```
+
+The JSON result includes a stable operation ID, overall status, counts, stable
+diagnostic codes, severity, file locations, byte sizes, and help links. Errors
+exit non-zero. Warnings do not block by default; use `--fail-on warning` in a
+strict Agent or CI workflow.
+JSON 结果包含稳定 operation ID、整体状态、数量汇总、稳定诊断码、严重级别、文件位置、字节数和帮助链接。错误默认以非零状态退出；warning 默认不阻断，严格的 Agent 或 CI 流程可增加 `--fail-on warning`。
+
+Use the `--ai` option to add static Agent-debug readiness checks to the existing
+checks. It currently detects a direct
+`reportScene({ sceneId: 9999 })` checkpoint, reports the matching file and scan
+coverage, and keeps `platformWrite: false`. Static detection proves integration
+evidence only; real-device `GAME_READY` is still required.
+使用 `--ai` option 可在现有检查之外增加 Agent 调试准备度检查。目前会静态识别直接的 `reportScene({ sceneId: 9999 })` 检查点，返回命中文件和扫描范围，并保持 `platformWrite: false`。静态检出只证明代码已接入，最终仍需真机收到 `GAME_READY`。
+
+```
+ttmg check --ai --dir <game-dir> --format json
+ttmg check --ai --dir <game-dir> --format json --fail-on warning
+```
+
+Use the read-only doctor before debugging to inspect the CLI and Node version,
+project detection, reusable local login, selected LAN hosts, and whether proxy
+environment variables are present. Proxy values and session Cookies are never
+returned.
+调试前可执行只读 doctor，检查 CLI 与 Node 版本、工程识别、本地登录是否可复用、选中的局域网地址以及是否存在代理环境变量；结果不返回代理值或会话 Cookie。
+
+```
+ttmg doctor --dir <game-dir> --format json
+ttmg doctor --dir <game-dir> --format json --fail-on warning
+```
+
+#### Structured Build 结构化构建
+
+The existing native `ttmg build` default behavior is unchanged. Agents can
+explicitly request a local structured build; artifacts are written outside the
+game project under `~/__TTMG__/build/<operation-id>/`, and no platform write is
+performed.
+现有 Native `ttmg build` 默认行为不变。Agent 可显式执行本地结构化构建；产物写入游戏工程外的 `~/__TTMG__/build/<operation-id>/`，不会写入平台。
+
+```
+ttmg build --dir <game-dir> --format json
+ttmg build --dir <game-dir> --format json --include-passed
+```
+
+The report includes duration, engine, source size, package summaries, output
+directory, package manifest, normalized diagnostics, and
+`platformWrite: false`.
+结果包含耗时、引擎、源码大小、各包摘要、产物目录、package manifest、标准化诊断以及 `platformWrite: false`。
+
+#### Platform Preview Upload 平台预览版本上传
+
+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 `.agents`, `.claude`, and `.trae` directories.
+上传 ZIP 不包含项目根目录下的 `.agents`、`.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`,
+`processing`, and `ready` or `failed`. A ready result includes `previewUrl`,
+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:
   ttmg dev --h5