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

package/README.md

@@ -1,10 +1,40 @@
 ### @ttmg/cli
 
+Vibe 试用安装：`npm install -g @ttmg/cli@0.4.6-vibe-beta.8`。独立升级标签：`vibe-beta`；包内保留当前 AI Friendly 代码。
+
+Vibe trial: install `@ttmg/cli@0.4.6-vibe-beta.8`. Updates use `vibe-beta`; current AI Friendly code is included.
+
+Vibe 真实网页授权：`ttmg upload --vibe --web --dir ./game --title "My game" --icon ./avatar.png --format ndjson`。内置 PPE 创建任务后打开系统浏览器，持续查询真实绑定状态，不模拟授权；当前真实素材上传仍受限制。`--web` 不能与 `--mock` 或 `--no-open` 同用，原 `--mock` 链路不变。详见 [Vibe 接入说明](vibe-upload.md)。
+
+Vibe real web authorization: use `--web` without `--mock`. It creates a PPE task, opens the system browser and polls real binding status; real material upload remains gated. It conflicts with `--mock` and `--no-open`. The original Mock workflow is unchanged. See [Vibe integration](vibe-upload.md).
+
 `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 安装
 
+For Agent, Monetization and Vibe Coding workflows, install the published beta:
+Agent、商业化和 Vibe Coding 流程请安装已发布的 beta 版本：
+
+```bash
+npm install -g @ttmg/cli@0.4.6-agent-beta.2
+ttmg --version
+ttmg capabilities --format json
+```
+
+This version uses `ttmg-pack@0.4.13`. The unversioned installation below uses
+the stable `latest` release and does not select this beta.
+本版依赖正式版 `ttmg-pack@0.4.13`。下方不指定版本的安装命令使用稳定版
+`latest`，不会安装本次 beta。
+
+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`：
 
@@ -21,21 +51,30 @@ npm install @ttmg/cli --save-dev
 
 #### Login 登录
 
-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 不同，不再是全程离线。
-需要后端可访问，会创建真实任务，不上传游戏、不预览、不审核或发布。
+To open an existing Vibe task in the system browser, use the `pageUrl` from its
+`waiting_authorization` event: `ttmg auth open --page-url <pageUrl> --format json`.
+Keep the upload process running; this command creates no task and reports only
+`open_requested`, not authorization success. It runs on the CLI computer.
 
-```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
-```
+Skill 如需手动打开网页授权，读取上传进程 `waiting_authorization` 事件的 `pageUrl`，
+执行 `ttmg auth open --page-url <pageUrl> --format json`。保持原上传进程运行；
+新命令在 CLI 所在电脑打开系统浏览器，不新建任务，`open_requested` 不代表授权成功。
+该功能需使用包含新命令的本地构建；已发布旧版不会因此自动增加命令。
 
-PPE routing will be removed in a production release without Skill environment setup.
-上线时由 CLI 去掉 PPE 路由，不让 Skill 配置或切换环境。
+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 本地原型不需要此步骤。
@@ -114,6 +153,121 @@ 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,
@@ -151,15 +305,17 @@ The command writes `manifest.json`, `events.ndjson`, `actions.ndjson`,
 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 and remote actions remain unavailable.
+`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`。设备直开和远程操作仍不可用；运行时日志与截图已提供实验性的 iOS/V1 协议入口，但真实设备验收完成前，顶层 capabilities 仍保持 `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`。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
@@ -174,14 +330,109 @@ 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.
+Keep custom evidence outside the project or under its root `.ttmg` directory;
+other in-project destinations fail before the session starts. CLI state is
+excluded from game builds, package-size checks and directory uploads.
+快捷命令自动找到当前工程（含子目录）唯一的运行中真机预览会话；多个会话时列出
+候选，需用 `--session <session-id>` 明确选择，不会自动连接任意设备。
+自定义证据目录使用 `--sessions-dir <path>`，可以指定会话集合目录或启动时的
+`--evidence-dir`。截图完成后输出本地保存路径，支持 `--output <path>`。
+`logs --follow` 默认读取 30 秒后退出，不停止预览；主终端持续输出日志，Ctrl+C
+停止预览。日志和截图均需要客户端支持对应协议。
+自定义证据目录须位于工程外或工程根目录的 `.ttmg` 下；其他工程内目录会在启动前
+被拒绝。CLI 状态目录不进入游戏构建、包体积检查和目录上传。
+
+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.
-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
+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。日志只在
+或请求截图。Runtime cursor 是十进制字符串，不应转换为 JavaScript Number。默认日志只在
 有界内存中保留，不写入 `events.ndjson` 或额外日志文件；截图 stdout 只返回元数据，
 图片写入磁盘，且不会覆盖显式指定的已有文件。
 
@@ -204,10 +455,163 @@ ttmg dev session screenshot <session-id> --image-format jpeg --quality 0.8 --out
 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.
+`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`，不会从
-磁盘伪造历史日志。
+`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 项目检查