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

package/README.md

@@ -1,6 +1,8 @@
 ### @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 安装
 
 You can install `ttmg` globally or as a project dependency via npm:
@@ -26,6 +28,55 @@ Before running any `ttmg` commands, please log in with your TikTok account. Once
 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 +86,124 @@ ttmg login
 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` 流程保持不变。
+
+```
+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
+```
+
+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; 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
+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` 表示本地协议已经接通。
+编译事件会同时包含现有检查器产生的标准化项目诊断，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
+```
+
+#### 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` 后还会等待平台处理完成并返回预览地址。
+
+```
+ttmg upload --preview --client-key <client-key> --dir <game-dir> --format ndjson
+```
+
+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.
+NDJSON 状态依次为 `precheck`、`packaging`、`uploading`、`processing`，最终进入 `ready` 或 `failed`。平台处理阶段的 `platformStatus` 使用 `waiting_for_asset`、`pending`、`processing`、`success`、`failed` 等可读值；可选的 `platformStatusRaw` 仅保留平台原始枚举用于排障。成功结果包含 `previewUrl`、与其一致的 `qrPayload`、平台版本地址和 `platformWrite: true`。
+
 - 调试 H5 小游戏：
 - To debug H5 mini-games:
   ttmg dev --h5