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

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttmg/cli",
-  "version": "0.4.6-vibe-beta.16",
+  "version": "0.4.6-vibe-beta.17",
   "description": "TikTok Mini Game Command Line Tool",
   "license": "ISC",
   "bin": {
@@ -17,7 +17,7 @@
   "scripts": {
     "demo:vibe": "npm run build && node scripts/vibe-upload-demo.js",
     "test:game-categories": "node scripts/run-ts-test.js src/commands/common/game/categories.test.ts",
-    "test:vibe": "npm run test:game-categories && node scripts/run-ts-test.js src/commands/common/vibe/vibe.test.ts",
+    "test:vibe": "npm run test:game-categories && node scripts/run-ts-test.js src/commands/common/vibe/vibe.test.ts && node scripts/run-ts-test.js src/commands/common/vibe/preview.test.ts",
     "test:vibe-process": "node scripts/vibe-upload-smoke.js",
     "prepack": "npm run build && npm run verify:dist-version && npm run verify:agent-contract",
     "build": "node scripts/build.js",

package/dist/scripts/vibe-ppe-test-preload.cjs

@@ -10,7 +10,7 @@ https.request = (options, callback) => {
   assert.equal(typeof options, 'object');
   assert.equal(options.hostname, 'developers.tiktok.com');
   assert.equal(options.protocol, 'https:');
-  assert.match(options.path, /^\/bff\/app_info\/minis_import\/(create_minis_import_task_for_agent|get_minis_import_task_status_for_agent|upload_minis_import_app_icon_for_agent|submit_minis_import_info_for_agent|upload_minis_import_package_for_agent)\//);
+  assert.match(options.path, /^\/bff\/app_info\/minis_import\/(create_minis_import_task_for_agent|get_minis_import_task_detail_for_agent|upload_minis_import_app_icon_for_agent|submit_minis_import_info_for_agent|upload_minis_import_package_for_agent)\//);
   const request = http.request({
     ...options,
     protocol: 'http:', hostname: '127.0.0.1', host: undefined, port,

package/dist/scripts/vibe-upload-smoke.js

@@ -171,7 +171,7 @@ async function main() {
     for await (const chunk of req) chunks.push(chunk);
     const body = Buffer.concat(chunks);
     const create = url.pathname.endsWith('/create_minis_import_task_for_agent/');
-    const status = url.pathname.endsWith('/get_minis_import_task_status_for_agent/');
+    const status = url.pathname.endsWith('/get_minis_import_task_detail_for_agent/');
     const iconUpload = url.pathname.endsWith('/upload_minis_import_app_icon_for_agent/');
     const infoUpload = url.pathname.endsWith('/submit_minis_import_info_for_agent/');
     const packageUpload = url.pathname.endsWith('/upload_minis_import_package_for_agent/');
@@ -217,7 +217,11 @@ async function main() {
     } : iconUpload ? {icon_uri: 'web-icon-receipt'}
       : infoUpload ? {}
       : packageUpload ? {status: 3, package_uri: 'web-package-receipt'}
-      : { status: webMode && webPolls >= 5 ? 2 : 1, ready_for_input: webMode && webPolls >= 5 };
+      : { status: webMode && webPolls > 5 ? 6 : webMode && webPolls === 5 ? 2 : 1,
+          ready_for_input: webMode && webPolls === 5,
+          ...(webMode && webPolls >= 7 ? { preview_url: 'https://www.tiktok.com/minis/process-preview',
+            app_id: '7686101169281894417', code_asset_id: '7686101169281894418',
+            client_key: 'process-client', minis_center_history_id: '7686101169281894419' } : {}) };
     res.writeHead(200, { 'Content-Type': 'application/json' });
     res.end(JSON.stringify({ ...data, error_info: { code: (failStatus && status) || url.pathname === webFailureEndpoint ? 420500 : 0 } }));
   });
@@ -306,7 +310,7 @@ async function main() {
         task_id: '7684370037737619477', import_token: 'receipt-test-secret',
         landing_url: 'https://example.invalid/auth', poll_interval_seconds: 0.01,
       },
-      get_minis_import_task_status_for_agent: { status: 2, ready_for_input: true },
+      get_minis_import_task_detail_for_agent: { status: 2, ready_for_input: true, preview_url: 'https://www.tiktok.com/minis/receipt-preview' },
       upload_minis_import_app_icon_for_agent: { icon_uri: 'test-icon' },
       submit_minis_import_info_for_agent: {},
       upload_minis_import_package_for_agent: { status: 2, package_uri: 'test-package' },
@@ -328,9 +332,10 @@ async function main() {
     assert.equal(savedFinal.taskStatusRaw, 2);
     assert.equal(savedEvents.filter(e => e.terminal).length, 1);
     assert.deepEqual(uploadPaths, [
-      'create_minis_import_task_for_agent', 'get_minis_import_task_status_for_agent',
+      'create_minis_import_task_for_agent', 'get_minis_import_task_detail_for_agent',
       'upload_minis_import_app_icon_for_agent', 'submit_minis_import_info_for_agent',
       'upload_minis_import_package_for_agent',
+      'get_minis_import_task_detail_for_agent',
     ]);
     assert.doesNotMatch(saved.stdout + saved.stderr, /receipt-test-secret|test-package/);
   } finally {
@@ -468,12 +473,20 @@ async function main() {
     assert.equal(output.at(-1).classification.source, format === 'json' ? 'defaults' : 'arguments');
     assert.equal(output.at(-1).description, expectedWebDescription);
     assert.equal(output.at(-1).descriptionSource, format === 'json' ? 'defaults' : 'arguments');
-    assert.equal(output.at(-1).taskStatusRaw, 3);
+    assert.equal(output.at(-1).taskStatusRaw, 6);
+    assert.equal(output.at(-1).previewReady, true);
+    assert.equal(output.at(-1).previewUrl, 'https://www.tiktok.com/minis/process-preview');
+    assert.equal(output.at(-1).codeAssetId, '7686101169281894418');
+    assert.equal(output.at(-1).qrPurpose, 'game_preview');
+    const readyPage = await (await fetch(output.at(-1).pageUrl)).text();
+    assert.match(readyPage, /Game preview QR/);
+    assert.match(readyPage, /data-phase="preview"/);
     assert.equal(output.filter(e => e.terminal).length, 1);
-    assert.equal(webPolls, 5, 'Only true backend readiness unlocks authorization');
+    assert.equal(webPolls, 7, 'Keep polling the same task until preview URL is available');
     assert.deepEqual(requests.slice(requestStart).map(r => r.path.split('/').filter(Boolean).at(-1)), [
-      'create_minis_import_task_for_agent', ...Array(5).fill('get_minis_import_task_status_for_agent'),
+      'create_minis_import_task_for_agent', ...Array(5).fill('get_minis_import_task_detail_for_agent'),
       'upload_minis_import_app_icon_for_agent', 'submit_minis_import_info_for_agent', 'upload_minis_import_package_for_agent',
+      'get_minis_import_task_detail_for_agent', 'get_minis_import_task_detail_for_agent',
     ]);
     if (format === 'json') assert.equal(output.length, 1);
     const opens = fs.readFileSync(receipt, 'utf8').trim().split('\n').map(line => JSON.parse(line));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttmg/cli",
-  "version": "0.4.6-vibe-beta.16",
+  "version": "0.4.6-vibe-beta.17",
   "description": "TikTok Mini Game Command Line Tool",
   "license": "ISC",
   "bin": {
@@ -17,7 +17,7 @@
   "scripts": {
     "demo:vibe": "npm run build && node scripts/vibe-upload-demo.js",
     "test:game-categories": "node scripts/run-ts-test.js src/commands/common/game/categories.test.ts",
-    "test:vibe": "npm run test:game-categories && node scripts/run-ts-test.js src/commands/common/vibe/vibe.test.ts",
+    "test:vibe": "npm run test:game-categories && node scripts/run-ts-test.js src/commands/common/vibe/vibe.test.ts && node scripts/run-ts-test.js src/commands/common/vibe/preview.test.ts",
     "test:vibe-process": "node scripts/vibe-upload-smoke.js",
     "prepack": "npm run build && npm run verify:dist-version && npm run verify:agent-contract",
     "build": "node scripts/build.js",

package/vibe-upload.md

@@ -3,7 +3,7 @@
 
 `ttmg upload --vibe` 将本地小游戏上传到 TikTok Mini Games。用户提供游戏标题和头像，在手机 TikTok 扫码授权后，CLI 自动完成头像、应用资料和代码包上传。Skill 负责准备工程、调用命令和读取结果；CLI 负责素材校验、打包、授权轮询及上传。
 
-适用版本：`0.4.6-vibe-beta.16`。手机授权与真实上传已使用 PPE 测试素材验证；正式环境未开放。上传完成不代表审核通过或正式发布。
+`0.4.6-vibe-beta.17` 支持手机授权、上传后持续轮询和扫码预览。Snow Crew 已在 PPE 完成真实上传并取得预览链接，用户确认扫码预览跑通。正式环境未开放，上传完成不代表审核通过或正式发布。
 
 ## Quick Start
 
@@ -18,18 +18,23 @@ ttmg upload --vibe --dir ./game --title "星环守卫" --icon ./avatar.png --for
 ```
 
 1. 启动命令，CLI 检查素材并自动打开电脑上的二维码页。
+
 2. 用户使用手机 TikTok 扫码授权，保持原命令运行。
+
 3. CLI 自动上传头像、应用资料和代码包，页面展示进度与结果。
-4. Skill 收到 `terminal=true`、`status=uploaded`、`uploaded=true`、`simulation=false` 且退出码为 0 后，报告上传完成。
+
+4. 上传后保持原进程运行，CLI 继续查询同一任务；拿到 `previewUrl` 后，原页面自动显示游戏预览二维码，使用手机 TikTok 扫码预览。
+
+5. Skill 收到 `terminal=true`、`status=uploaded`、`uploaded=true`、`previewReady=true`、`simulation=false` 且退出码为 0 后，报告上传完成且可扫码预览。
 
 已有 ZIP 时，用 `--package ./game.zip` 替换 `--dir ./game`。无需预先执行 `ttmg login` 或配置 PPE 环境。描述和分类可省略，CLI 使用默认资料；完整参数见下文。
 
 ## 安装与本地预检
 
-安装后确认版本为 `0.4.6-vibe-beta.16`，能力查询中 `authorizationMode` 为 `qr`。支持 Node.js 20.19.1–20.x 或 22 及以上版本。
+安装后确认版本为 `0.4.6-vibe-beta.17`，能力查询中 `authorizationMode` 为 `qr`、`previewQr` 为 `true`。支持 Node.js 20.19.1–20.x 或 22 及以上版本。
 
 ```sh
-npm install -g @ttmg/cli@0.4.6-vibe-beta.16
+npm install -g @ttmg/cli@0.4.6-vibe-beta.17
 ttmg --version
 ttmg capabilities --format json
 ```
@@ -113,7 +118,8 @@ ttmg upload --vibe --dir ./game --title "星环守卫" --icon ./avatar.png --cat
 
 3. 收到 `uploading`，按 `uploadStep` 展示 `avatar`、`app_info`、`package` 进度。授权轮询和上传由 CLI 完成。
 
-4. 收到 `terminal=true`、`status=uploaded`、`uploaded=true`、`simulation=false`，确认真实上传完成。`failed`、`cancelled` 或进程中断按下方失败说明处理。
+4. 收到 `waiting_preview` 时，素材已上传，保持原进程运行。CLI 使用同一任务继续查询；状态已完成但尚无预览链接时也继续等待。
+5. 终态仍为 `status=uploaded`。`previewReady=true`、`qrPurpose=game_preview` 表示预览二维码已就绪，`previewUrl` 是二维码内容，`pageUrl` 是展示二维码的本地页面。等待失败时保留 `uploaded=true`，同时返回错误和 `nextAction=check_task`，不要重新上传。
 
 ## 扫码授权与自动上传
 
@@ -147,7 +153,8 @@ ttmg auth open --page-url <pageUrl> --format json
 
 - `uploading`：根据 uploadStep 显示 avatar、app_info、package 的进度，不再询问授权。
 
-- `uploaded`：terminal=true、uploaded=true、simulation=false 且退出码 0：本次上传完成；不是审核通过或正式发布。
+- `waiting_preview`：uploaded=true、terminal=false，正在查询后端处理结果，等待预览链接。
+- `uploaded`：terminal=true、uploaded=true、simulation=false 且退出码 0：上传完成，previewReady=true 时可扫码预览；不是审核通过或正式发布。
 
 - `failed / cancelled`：根据 errorCode、message 和 nextAction 提示处理，不自动重传。
 
@@ -158,15 +165,17 @@ ttmg auth open --page-url <pageUrl> --format json
 
 按阶段补充：`taskId`（字符串，禁止转成 JS Number）、`pollIntervalSeconds`、`readyForInput`、`taskStatusRaw`（仅诊断）、`uploadStep`、`loadedBytes`、`totalBytes`、`pageUrl`、`qrPurpose=authorization_binding`、素材大小和包 SHA256。代码包字节进度达到 100% 不代表成功，必须等待最终上传回执。
 
-`nextAction` 取值：`wait`、`scan_qr`、`fix_input`、`restart_authorization`、`check_task`、`none`。已开始上传后发生失败／超时，先检查 task，不能直接再次创建并重传。若上传已完成但页面失败，仍保留 `uploaded=true`，同时返回错误；Skill 提示上传已完成但展示失败。
+`nextAction` 取值：`wait`、`scan_qr`、`fix_input`、`restart_authorization`、`check_task`、`none`。已开始上传后发生失败／超时，先检查 task，不能直接再次创建并重传。预览等待超时返回 `VIBE_PREVIEW_TIMEOUT`；查询失败、取消或页面失败均保留 `uploaded=true`，并返回错误及 `nextAction=check_task`。
+
+新结果字段：`previewUrl`、`previewReady`、`clientKey`、`appId`、`codeAssetId`、`minisCenterHistoryId`。业务 ID 使用字符串，后端尚未返回时省略；只有有效的非空 preview_url 才触发预览就绪。Mock 保持模拟上传终态，不返回真实预览二维码。
 
 退出码：成功／dry-run 为 0，失败为 1，Ctrl+C 为 130。进程或宿主意外终止导致没有终态时，不得认定上传成功。
 
-轮询间隔使用创建任务返回的 `poll_interval_seconds`。`--timeout` 是整体超时，默认 300 秒。不自动重试写接口、不实现跨进程续传。
+轮询间隔使用创建任务返回的 `poll_interval_seconds`。`--timeout` 是包括授权、上传和等待预览的整体超时，默认 300 秒。不自动重试写接口、不实现跨进程续传。
 
 ## 页面与素材
 
-本地页在扫码、上传、成功或失败时均展示本次资料。后台查询状态，只更新变化内容，不整页刷新；完成或失败后停止查询。授权完成或失败后移除二维码。Skill 可用 `pageUrl` 重新打开同一页面。
+本地页在扫码、上传、等待预览、成功或失败时均展示本次资料。后台查询状态，只更新变化内容，不整页刷新；预览就绪或终态失败后停止查询。授权完成后移除授权二维码；preview_url 就绪后显示游戏预览二维码，直接使用后端 URL。Skill 可用 `pageUrl` 重新打开同一页面。
 
 页面只监听 127.0.0.1，二维码才由手机扫描，手机不访问 pageUrl。默认 15 分钟后关闭，内容驻留内存；测试可设置 `TTMG_VIBE_PAGE_TTL_MS`（1—900000）。取消进程会关闭页面；成功与可显示的失败页面保留至到期。不要分享本地页面地址。
 
@@ -182,7 +191,7 @@ CLI 在工程目录的 `.ttmg/vibe-project.json` 保存并复用非敏感 source
 
 - `POST create_minis_import_task_for_agent/`：请求 source_type=1、source_project_id、task_idempotency_id、minis_type=MINI_GAME。响应 task_id、import_token、landing_url、poll_interval_seconds。
 
-- `GET get_minis_import_task_status_for_agent/`：请求 Query：task_id、import_token。响应 status、ready_for_input。
+- `GET get_minis_import_task_detail_for_agent/`：请求 Query：task_id、import_token。响应 status、ready_for_input，以及可选的 client_key、app_id、code_asset_id、minis_center_history_id、preview_url；授权和上传后的轮询均使用此接口。
 
 - `POST upload_minis_import_app_icon_for_agent/`：请求 Multipart：task_id、import_token、file。响应 icon_uri。
 
@@ -191,7 +200,7 @@ CLI 在工程目录的 `.ttmg/vibe-project.json` 保存并复用非敏感 source
 - `POST upload_minis_import_package_for_agent/`：请求 Multipart：task_id、import_token、asset_type=2、file。响应 package_uri、status。
 
 
-所有响应必须业务 `error_info.code=0`。最后一步还要求非空 package_uri 和合法非失败状态；完成后不再轮询。HTTP 200、进度100% 都不能单独作为成功判定。19位 task_id 在 CLI 内保留字符串，提交 i64 JSON 时无损编码。
+所有响应必须业务 `error_info.code=0`。上传回执还要求非空 package_uri 和合法非失败状态；收到回执后继续查询 Detail，直到拿到有效 preview_url。HTTP 200、进度100% 都不能单独作为成功判定。19位 task_id 在 CLI 内保留字符串，提交 i64 JSON 时无损编码。任务凭据只在当前进程内保留，终态后清除。
 
 ```sh
 TTMG_VIBE_BACKEND=local-http TTMG_VIBE_API=http://127.0.0.1:3100 ttmg upload --vibe --package ./game.zip --title "测试游戏" --icon ./avatar.png --format ndjson
@@ -199,7 +208,9 @@ TTMG_VIBE_BACKEND=local-http TTMG_VIBE_API=http://127.0.0.1:3100 ttmg upload --v
 
 维护者可使用 `--vibe-api http://127.0.0.1:3100` 验证本机 HTTP 合同，只接受回环 IP，不跟随重定向、不读取 Cookie；本地服务需实现上表协议。Skill 使用 `--vibe`，PPE 路由由 CLI 内置。正式环境未开放。
 
-**v1 → v2 兼容性变化**：旧 UUID 换 Token 的三接口协议废弃，`--vibe-authorize-url` 返回明确错误；授权地址来自 landing_url。不再输出 preview_ready、game_preview、uploadId、reviewStatus。Skill 必须校验 schemaVersion=2，并按新终态处理。普通不带 --vibe 的 upload 不变。
+**v1 → v2 兼容性变化**：旧 UUID 换 Token 的三接口协议废弃，`--vibe-authorize-url` 返回明确错误；授权地址来自 landing_url。不再输出旧 preview_ready 状态、uploadId、reviewStatus。
+
+当前版本新增 waiting_preview 状态，终态保留 uploaded；game_preview 作为预览二维码用途。Skill 必须校验 schemaVersion=2，并按终态、previewReady 和 errorCode 处理。普通不带 --vibe 的 upload 不变。
 
 2026-09-14 已核对 BFF 源码：头像 PNG/JPEG、1024×1024、5 MiB；Native ZIP 和解压总大小上限 100 MiB。本地暂未实现完整 ZIP 内容及解压总大小校验。2026-09-16 本地构建使用自有测试素材跑通真实 PPE 手机扫码授权、头像、默认资料和代码包上传。该验证不覆盖全部游戏或正式环境。后端接口调整留在适配层处理；若用户动作或成功语义改变，应协商升级 CLI schema。