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

package/README.md

@@ -1,10 +1,45 @@
 ### @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 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).
+
 `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)。
+
+`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` 版本：
+
+```bash
+npm install -g @ttmg/cli@vibe-beta
+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` 指向不同发布版本。
+
+For Agent and Monetization workflows, the published beta is:
+Agent、商业化流程的已发布 beta 为：
+
+```bash
+npm install -g @ttmg/cli@0.4.6-agent-beta.3
+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
@@ -29,23 +64,29 @@ npm install @ttmg/cli --save-dev
 
 #### Login 登录
 
-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)。
+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`，
+执行 `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.
 
-维护者可用 `--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.
+当前上传只需要标题、头像和游戏目录或代码包，其他应用资料由 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; this does not apply to the local Vibe prototype above.
-原有需要平台鉴权的流程仍先登录；上述 Vibe 本地原型不需要此步骤。
+For the existing authenticated platform workflow, log in first; Vibe Web upload uses its own browser authorization.
+原有需要平台鉴权的流程仍先登录；Vibe Web 上传使用本次任务的浏览器授权。
 
 ```
 ttmg login
@@ -196,9 +237,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
@@ -369,12 +471,17 @@ 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