@ttmg/cli 0.4.6-vibe-beta.14 → 0.4.6-vibe-beta.16

package/README.md

@@ -1,36 +1,32 @@
 ### @ttmg/cli
 
-Vibe 真实网页授权与上传：`ttmg upload --vibe --web --dir ./game --title "My game" --icon ./avatar.png --format ndjson`。只向用户收集标题和本地头像，并使用游戏目录或代码包；其他应用资料由 CLI 使用既有 PPE 试用默认值补齐，不需要用户填写。网页授权后，CLI 自动继续上传。见 [Vibe 接入说明](vibe-upload.md)。
+Vibe 手机扫码授权与上传：`ttmg upload --vibe --dir ./game --title "My game" --icon ./avatar.png --format ndjson`。用户在手机 TikTok 扫码授权后，原命令自动上传。只收集标题和本地头像，并使用游戏目录或代码包；其他应用资料由 CLI 补齐。页面展示标题、头像、描述、类型和子类型。见 [Vibe 接入说明](vibe-upload.md)。
 
-Vibe real web authorization and upload: use `--web` with the title, local icon and game directory or ZIP. Collect only the title and icon from the user; the CLI fills other app metadata with existing PPE trial defaults. Upload continues after browser authorization. See [Vibe integration](vibe-upload.md).
+扫码上传使用 `0.4.6-vibe-beta.16`，安装后核对版本与能力声明。扫码链路已用 PPE 测试素材完成真实上传；正式环境未开放。
 
 `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 安装
 
-`0.4.6-vibe-beta.14` 支持分类查询与可选上传分类参数。Skill 可用 `ttmg game categories --format json` 查询，再向 Vibe 上传传入 `--category Puzzle --subcategory Physics`。两个参数都省略时保留 Other/Other；详见 [分类用法](vibe-upload.md)。
+Vibe 版本支持手机扫码授权上传、可选 `--description`、分类查询及 `--category / --subcategory`。默认描述为 `Discover the fun of TikTok Mini Games.`，默认分类为 Other/Other。完整流程见 [Quick Start](vibe-upload.md)。
 
-`0.4.6-vibe-beta.14` supports category discovery and optional upload classification. Query `ttmg game categories --format json`, then pass `--category Puzzle --subcategory Physics` to Vibe upload. Omitting both preserves Other/Other. See [category usage](vibe-upload.md).
-
-For Vibe Web authorization and upload, install the `vibe-beta` release:
-Vibe 网页授权上传安装 `vibe-beta` 版本：
+固定版本安装（发布标签为 `vibe-beta`）：
 
 ```bash
-npm install -g @ttmg/cli@vibe-beta
+npm install -g @ttmg/cli@0.4.6-vibe-beta.16
 ttmg --version
 ttmg capabilities --format json
 ttmg upload --help
 ```
 
-The package includes [vibe-upload.md](vibe-upload.md). Keep the Web upload process running during authorization and read NDJSON until a terminal event. The `beta` and `vibe-beta` tags point to different published versions.
-安装包包含 [vibe-upload.md](vibe-upload.md)。授权期间保持原 Web 上传进程运行，持续读取 NDJSON，直到收到终态。`beta` 与 `vibe-beta` 指向不同发布版本。
+安装包包含 [vibe-upload.md](vibe-upload.md)。授权期间保持原上传进程运行，持续读取 NDJSON，直到收到终态。`beta` 与 `vibe-beta` 指向不同发布版本。
 
 For Agent and Monetization workflows, the published beta is:
 Agent、商业化流程的已发布 beta 为：
 
 ```bash
-npm install -g @ttmg/cli@0.4.6-agent-beta.2
+npm install -g @ttmg/cli@0.4.6-agent-beta.3
 ttmg --version
 ttmg capabilities --format json
 ```
@@ -64,29 +60,17 @@ npm install @ttmg/cli --save-dev
 
 #### Login 登录
 
-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.
-
-Skill 如需手动打开网页授权，读取上传进程 `waiting_authorization` 事件的 `pageUrl`，
+Skill 如需重新打开二维码页，读取上传进程 `waiting_authorization` 事件的 `pageUrl`，
 执行 `ttmg auth open --page-url <pageUrl> --format json`。保持原上传进程运行；
 新命令在 CLI 所在电脑打开系统浏览器，不新建任务，`open_requested` 不代表授权成功。
-`--web` 已自动打开授权页；上述辅助命令只用于重新打开同一任务的授权页。
+该命令只打开同一任务的本地二维码页，用户仍需手机扫码。
 
-`ttmg upload --vibe --web` uses real browser authorization and uploads to PPE without a prior platform login or environment setup. `--mock` is a separate demo: task creation/polling are real, but authorization and material uploads are simulated. See [Vibe binding/upload](vibe-upload.md) for schema-v2 results.
-`ttmg upload --vibe --web` 无需预先平台登录或配置环境，使用真实浏览器授权并上传到 PPE。`--mock` 是独立演示：真实创建／查询任务，模拟授权和素材上传。详见 [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.
+`ttmg upload --vibe` 无需预先平台登录或配置环境，使用手机 TikTok 扫码授权并上传到 PPE。详见 [Vibe 绑定上传](vibe-upload.md)。
 
 当前上传只需要标题、头像和游戏目录或代码包，其他应用资料由 CLI 使用既有 PPE 试用默认值补齐。Skill 读取 `inputRequirements`，不向用户索要额外资料；本地预检使用 `--dry-run`。
 Current uploads need only the title, icon and game directory or ZIP. The CLI fills other metadata with existing PPE trial defaults. Read `inputRequirements` and do not request extra fields. Use `--dry-run` for local preparation.
 
-For the existing authenticated platform workflow, log in first; Vibe Web upload uses its own browser authorization.
-原有需要平台鉴权的流程仍先登录；Vibe Web 上传使用本次任务的浏览器授权。
+原有需要平台鉴权的流程仍先登录；Vibe 上传使用本次任务的手机扫码授权。
 
 ```
 ttmg login
@@ -237,9 +221,70 @@ ttmg dev session stop <SESSION_ID> --format json
 
 ### Wasm prepare and split / Wasm 准备与分包
 
+#### Platform collection commands (agent-beta.3) / 平台采集命令
+
+Install `0.4.6-agent-beta.3` and check `commands.wasmCollect` in `ttmg capabilities`.
+The CLI uses its own `ttmg login` session; do not pass or read Cookie values in
+Agent prompts, arguments or local HTTP requests. No running DevTool server is required.
+
+```bash
+ttmg wasm prepare --input original.wasm.br --output .ttmg/wasm/prepared --format json
+# Use prepare's input.wasmMd5 for <MD5> and configure the instrumented game
+# to report that same original MD5 and Client Key.
+ttmg wasm collect start --client-key <CLIENT_KEY> --wasm-md5 <MD5> --format json
+# Integrate the prepared copy, scan, clear device storage and play the game.
+ttmg wasm collect export --client-key <CLIENT_KEY> --wasm-md5 <MD5> \
+  --input original.wasm.br --output .ttmg/wasm/collection.json --format json
+ttmg wasm split --input original.wasm.br --collection .ttmg/wasm/collection.json --output .ttmg/wasm/split --format json
+```
+
+Run these examples at the game project root. Keep collection and temporary
+artifacts outside the project or under its root `.ttmg`; an ordinary JSON file
+in game assets can be included in future builds and uploads.
+`start` opens or resumes a window and preserves existing IDs by default.
+`--reset` clears platform collection for this game and MD5; it does not clear
+phone storage. On an uncertain start or timeout, retry without `--reset`.
+`export` reads a union snapshot without closing the window. It needs the original
+Wasm, validates the collection MD5 against its file bytes or uncompressed bytes,
+and writes schema 1 with the uncompressed `wasmSha256`, `funcIds` and `bootFuncIds`.
+Read the file at the returned `collection.path`. Existing files are rejected;
+use a new output name for each snapshot. Credentials and raw API responses are
+omitted even with `--verbose`.
+
+Only `start` writes platform state. `export` only reads collection and writes a
+local file. Neither command changes Unity files or clears device storage.
+Platform requests default to 30 seconds (`--timeout`, 1–300). Missing or expired
+login returns `WASM_AUTH_REQUIRED`; empty collection returns `WASM_COLLECTION_EMPTY`;
+an unmatched original returns `WASM_COLLECTION_MISMATCH`. No file is published on
+these failures. A nonempty collection does not prove gameplay coverage.
+The commands reuse the existing platform request environment; local fixture
+tests do not establish real platform or device acceptance.
+
+安装 `0.4.6-agent-beta.3`，通过 `ttmg capabilities` 中的 `commands.wasmCollect` 确认支持。
+CLI 内部复用 `ttmg login` 登录态，无需运行 DevTool 本地服务，Agent 不读取或传递 Cookie。
+按上方命令执行：prepare → 开采集窗口 → 接入插桩副本并扫码、清存储、玩游戏 → export → split。
+`<MD5>` 使用 prepare 返回的 `input.wasmMd5`，插桩游戏须上报相同的原始 MD5 和 Client Key。
+
+示例在游戏工程根目录执行。采集文件和临时产物应放工程外或根目录 `.ttmg` 下；
+放在普通游戏资源目录的 JSON 会参与后续构建和上传。
+`start` 默认保留已有函数 ID；只有 `--reset` 清空平台上此游戏、此 MD5 的历史采集，
+不会清理手机存储。超时或不确定是否成功时，不带 `--reset` 重试。
+`export` 读取当前合集快照，不关闭采集窗口；必须提供原始 Wasm，命令校验文件字节或
+解压后字节的 MD5，再写入 schema 1、解压后原始 `wasmSha256`、`funcIds` 和 `bootFuncIds`。
+从返回的 `collection.path` 读取文件；已有文件不覆盖，每轮快照使用新文件名。
+即使开启 `--verbose`，也不输出登录凭证或原始接口响应。
+
+仅 `start` 写平台状态；`export` 只读平台并写本地文件。两者均不写回 Unity 工程或清理手机存储。
+请求默认超时 30 秒，`--timeout` 范围为 1–300 秒。未登录或登录过期返回 `WASM_AUTH_REQUIRED`，
+空采集返回 `WASM_COLLECTION_EMPTY`，原始文件不匹配返回 `WASM_COLLECTION_MISMATCH`；
+这些失败不会生成采集文件。非空结果不等于玩法覆盖完整。
+命令沿用现有平台请求环境；本地模拟测试不代表真实平台或真机验收。
+
+#### Local artifacts / 本地产物
+
 ```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
+ttmg wasm prepare --input original.wasm.br --output .ttmg/wasm/prepared --format json
+ttmg wasm split --input original.wasm.br --collection .ttmg/wasm/collection.json --output .ttmg/wasm/split --format json
 ```
 
 These experimental commands create artifacts in a new directory; they do not