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

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

@@ -0,0 +1,341 @@
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+const archiver = require('archiver');
+const http = require('node:http');
+
+const entry = path.resolve(__dirname, '../dist/index.js');
+const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'ttmg-vibe-process-'));
+const icon = path.join(temp, 'avatar.png');
+const zip = path.join(temp, 'game.zip');
+const input = [
+  'upload',
+  '--vibe',
+  '--title',
+  'Local test game',
+  '--icon',
+  icon,
+  '--package',
+  zip,
+  '--no-open',
+];
+const png =
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aXyoAAAAASUVORK5CYII=';
+const children = new Set();
+let fixtureServer;
+const requests = [];
+let failStatus = false;
+const env = {
+  ...process.env,
+  HOME: temp,
+  USERPROFILE: temp,
+  TTMGRC_PATH: path.join(temp, '.ttmgrc'),
+  TTMG_VIBE_PAGE_TTL_MS: '7000',
+  TTMG_VIBE_BACKEND: '',
+  TTMG_VIBE_API: '',
+  TTMG_VIBE_PPE: '',
+};
+
+function run(args, onEvent, extraEnv = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [entry, ...args], {
+      cwd: temp,
+      env: { ...env, ...extraEnv },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    children.add(child);
+    let stdout = '';
+    let stderr = '';
+    let pending = '';
+    let callbackError;
+    const callbacks = [];
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL');
+      reject(new Error('CLI process timed out'));
+    }, 12000);
+    child.stdout.on('data', chunk => {
+      stdout += chunk;
+      pending += chunk;
+      let newline;
+      while ((newline = pending.indexOf('\n')) >= 0) {
+        const line = pending.slice(0, newline);
+        pending = pending.slice(newline + 1);
+        if (onEvent && line.trim()) {
+          try {
+            callbacks.push(
+              Promise.resolve(onEvent(JSON.parse(line), child)).catch(error => {
+                callbackError = error;
+              }),
+            );
+          } catch (error) {
+            callbackError = error;
+          }
+        }
+      }
+    });
+    child.stderr.on('data', chunk => {
+      stderr += chunk;
+    });
+    child.once('error', reject);
+    child.once('close', async (code, signal) => {
+      clearTimeout(timer);
+      children.delete(child);
+      await Promise.all(callbacks);
+      if (callbackError) reject(callbackError);
+      else resolve({ code, signal, stdout, stderr });
+    });
+  });
+}
+function events(result) {
+  assert.doesNotMatch(
+    result.stdout,
+    /upload_uuid|upload_token|import_token|importToken|mock-secret|mock-authorization/,
+  );
+  return result.stdout
+    .trim()
+    .split('\n')
+    .map(line => JSON.parse(line));
+}
+async function main() {
+  fixtureServer = http.createServer((req, res) => {
+    const url = new URL(req.url, 'http://127.0.0.1');
+    requests.push({ path: url.pathname, method: req.method, headers: req.headers });
+    req.resume();
+    const create = url.pathname.endsWith('/create_minis_import_task_for_agent/');
+    const status = url.pathname.endsWith('/get_minis_import_task_status_for_agent/');
+    assert.ok(create || status, 'Unexpected real upload endpoint');
+    assert.equal(req.headers['x-use-ppe'], '1');
+    assert.equal(req.headers['x-tt-env'], 'ppe_op_vc');
+    assert.equal(req.headers.cookie, undefined);
+    if (status) {
+      assert.equal(url.searchParams.get('task_id'), '7684370037737553941');
+      assert.equal(url.searchParams.get('import_token'), 'process-test-secret');
+    }
+    const data = create ? {
+      task_id: '7684370037737553941', import_token: 'process-test-secret',
+      landing_url: 'https://developers.tiktok.com/portal_h5/minis_import?import_token=process-test-secret',
+      poll_interval_seconds: 0.01,
+    } : { status: 1, ready_for_input: false };
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ ...data, error_info: { code: failStatus && status ? 420500 : 0 } }));
+  });
+  await new Promise(resolve => fixtureServer.listen(0, '127.0.0.1', resolve));
+  env.TTMG_VIBE_TEST_PORT = String(fixtureServer.address().port);
+  env.NODE_OPTIONS = `--require ${JSON.stringify(path.join(__dirname, 'vibe-ppe-test-preload.cjs'))}`;
+  fs.writeFileSync(icon, Buffer.from(png, 'base64'));
+  await new Promise((resolve, reject) => {
+    const out = fs.createWriteStream(zip);
+    const archive = archiver('zip');
+    out.once('close', resolve);
+    out.once('error', reject);
+    archive.once('error', reject);
+    archive.pipe(out);
+    archive.append('console.log("local fixture")', { name: 'game.js' });
+    archive.finalize().catch(reject);
+  });
+
+  let bindingHtml;
+  const success = await run(
+    [...input, '--mock', '--format', 'ndjson', '--poll-interval', '0.2'],
+    async event => {
+      if (event.status === 'waiting_authorization')
+        bindingHtml = await (await fetch(event.pageUrl)).text();
+    },
+  );
+  assert.equal(success.code, 0, success.stderr);
+  assert.match(bindingHtml, /Upload to TikTok/);
+  assert.match(bindingHtml, /class="game-avatar"/);
+  assert.match(bindingHtml, /PPE \+ Mock/);
+  assert.match(bindingHtml, /data-phase="binding"/);
+  assert.match(bindingHtml, /Phone authorization is not required/);
+  assert.doesNotMatch(bindingHtml, /<form|<input/);
+  const sequence = events(success);
+  const final = sequence[sequence.length - 1];
+  assert.equal(final.schemaVersion, '2');
+  assert.equal(final.status, 'uploaded');
+  assert.equal(final.terminal, true);
+  assert.equal(final.nextAction, 'none');
+  assert.equal(sequence.filter(e => e.terminal).length, 1);
+  assert.equal(final.uploaded, true);
+  assert.equal(final.platformWrite, true);
+  assert.equal(final.backend, 'ppe-mock');
+  assert.equal(final.taskStatusRaw, 1);
+  assert.equal(final.readyForInput, false);
+  assert.equal(final.simulatedReadyForInput, true);
+  assert.equal(final.simulatedTaskStatusRaw, 3);
+  assert.equal(requests.length, 4);
+  assert.equal(requests[0].method, 'POST');
+  assert.ok(requests.slice(1).every(r => r.method === 'GET'));
+  assert.doesNotMatch(success.stdout, /process-test-secret/);
+  assert.equal(final.simulation, true);
+  const progress = sequence.filter(
+    e => e.status === 'uploading' && e.loadedBytes !== undefined,
+  );
+  assert.equal(progress[0].loadedBytes, 0);
+  assert.equal(
+    progress[progress.length - 1].loadedBytes,
+    progress[progress.length - 1].totalBytes,
+  );
+  assert.ok(progress.length >= 6);
+  assert.equal(
+    sequence.filter(e => e.status === 'waiting_authorization').length,
+    1,
+  );
+  const previewHtml = await (await fetch(final.pageUrl)).text();
+  assert.match(previewHtml, /Simulated upload complete/);
+  assert.match(previewHtml, /data-phase="complete"/);
+  assert.doesNotMatch(previewHtml, /QR|preview|review|Publish to TikTok/);
+
+  const json = await run(
+    [...input, '--format', 'json', '--poll-interval', '0.01'],
+    undefined,
+    { TTMG_VIBE_BACKEND: 'mock' },
+  );
+  assert.equal(json.code, 0, json.stderr);
+  assert.equal(events(json).length, 1);
+  assert.equal(JSON.parse(json.stdout).status, 'uploaded');
+  assert.equal(JSON.parse(json.stdout).simulation, true);
+  assert.match(json.stderr, /http:\/\/127\.0\.0\.1:/);
+
+  const missingPpe = await run([...input, '--format', 'json'], undefined, {
+    TTMG_VIBE_BACKEND: 'ppe',
+  });
+  assert.equal(missingPpe.code, 1);
+  assert.equal(events(missingPpe)[0].errorCode, 'VIBE_INVALID_PPE_ENV');
+  assert.equal(events(missingPpe)[0].platformWrite, false);
+  const dryPpe = await run([...input, '--dry-run', '--format', 'json'], undefined, {
+    TTMG_VIBE_BACKEND: 'ppe', TTMG_VIBE_PPE: 'ppe_op_vc',
+  });
+  assert.equal(dryPpe.code, 0, dryPpe.stderr);
+  assert.equal(events(dryPpe)[0].status, 'prepared');
+  assert.equal(events(dryPpe)[0].platformWrite, false);
+  const missingHybrid = await run([...input, '--format', 'json'], undefined, {
+    TTMG_VIBE_BACKEND: 'ppe-mock',
+  });
+  assert.equal(events(missingHybrid)[0].errorCode, 'VIBE_INVALID_PPE_ENV');
+  assert.equal(events(missingHybrid)[0].platformWrite, false);
+  const dryHybrid = await run([...input, '--dry-run', '--format', 'json'], undefined, {
+    TTMG_VIBE_BACKEND: 'ppe-mock', TTMG_VIBE_PPE: 'ppe_op_vc',
+  });
+  assert.equal(dryHybrid.code, 0, dryHybrid.stderr);
+  assert.equal(events(dryHybrid)[0].status, 'prepared');
+  assert.equal(events(dryHybrid)[0].platformWrite, false);
+  const hybridMockOverride = await run([...input, '--mock', '--poll-interval', '0.01', '--format', 'json'], undefined, {
+    TTMG_VIBE_BACKEND: 'ppe-mock', TTMG_VIBE_PPE: 'ppe_op_vc',
+  });
+  assert.equal(hybridMockOverride.code, 0, hybridMockOverride.stderr);
+  assert.equal(events(hybridMockOverride)[0].backend, 'ppe-mock');
+  assert.equal(events(hybridMockOverride)[0].platformWrite, true);
+
+  failStatus = true;
+  const realFailure = await run([...input, '--mock', '--format', 'json']);
+  assert.equal(realFailure.code, 1, realFailure.stderr);
+  assert.equal(events(realFailure)[0].errorCode, 'VIBE_BACKEND_REJECTED');
+  assert.equal(events(realFailure)[0].uploadAttempted, false);
+  assert.equal(events(realFailure)[0].uploaded, false);
+  failStatus = false;
+
+  for (const [scenario, errorCode, attempted] of [
+    ['denied', 'VIBE_AUTH_DENIED', false],
+    ['upload-failed', 'VIBE_BACKEND_REQUEST_FAILED', true],
+  ]) {
+    const failed = await run([
+      ...input,
+      '--mock',
+      '--mock-scenario',
+      scenario,
+      '--poll-interval',
+      '0.01',
+      '--format',
+      'json',
+    ]);
+    assert.equal(failed.code, 1, failed.stderr);
+    const result = events(failed)[0];
+    assert.equal(result.status, 'failed');
+    assert.equal(result.errorCode, errorCode);
+    assert.equal(result.uploadAttempted, attempted);
+    assert.equal(result.uploaded, false);
+    assert.equal(result.terminal, true);
+    const html = await (await fetch(result.pageUrl)).text();
+    assert.match(html, /data-phase="failed"/);
+    assert.doesNotMatch(html, /alt="Authorization QR"|data-phase="complete"/);
+  }
+
+  const dryRun = await run([...input, '--dry-run', '--format', 'json']);
+  assert.equal(dryRun.code, 0, dryRun.stderr);
+  const prepared = events(dryRun)[0];
+  assert.equal(prepared.status, 'prepared');
+  assert.equal(prepared.backend, 'none');
+  assert.equal(prepared.pageUrl, undefined);
+  assert.equal(prepared.uploadAttempted, false);
+  const beforeDryMock = requests.length;
+  const dryMock = await run([...input, '--mock', '--dry-run', '--format', 'json']);
+  assert.equal(dryMock.code, 0);
+  assert.equal(events(dryMock)[0].platformWrite, false);
+  assert.equal(requests.length, beforeDryMock);
+
+  const project = path.join(temp, 'project');
+  fs.mkdirSync(project);
+  fs.writeFileSync(path.join(project, 'game.js'), 'console.log("game");\n');
+  fs.writeFileSync(path.join(project, 'game.json'), '{}\n');
+  const projectRun = await run([
+    'upload',
+    '--vibe',
+    '--title',
+    'Source game',
+    '--icon',
+    icon,
+    '--dir',
+    project,
+    '--dry-run',
+    '--format',
+    'json',
+  ]);
+  assert.equal(projectRun.code, 0, projectRun.stdout + projectRun.stderr);
+  assert.equal(events(projectRun)[0].status, 'prepared');
+  assert.ok(events(projectRun)[0].packageSizeBytes > 0);
+
+  const missingBackend = await run([...input, '--format', 'json']);
+  assert.equal(missingBackend.code, 1);
+  assert.equal(
+    events(missingBackend)[0].errorCode,
+    'VIBE_BACKEND_NOT_CONFIGURED',
+  );
+  const badMode = await run(['upload', '--title', 'x', '--format', 'json']);
+  assert.equal(badMode.code, 1);
+  assert.equal(events(badMode)[0].errorCode, 'VIBE_OPTION_REQUIRES_VIBE');
+  const help = await run(['upload', '--help']);
+  assert.equal(help.code, 0);
+  assert.match(help.stdout, /--vibe/);
+  assert.match(help.stdout, /--client-key/);
+
+  let cancelledPage;
+  const cancelled = await run(
+    [...input, '--mock', '--mock-scenario', 'timeout', '--format', 'ndjson'],
+    (event, child) => {
+      if (event.status === 'waiting_authorization') {
+        cancelledPage = event.pageUrl;
+        child.kill('SIGINT');
+      }
+    },
+  );
+  assert.equal(cancelled.code, 130, cancelled.stderr);
+  assert.equal(events(cancelled).slice(-1)[0].status, 'cancelled');
+  await assert.rejects(fetch(cancelledPage));
+  // Detached success pages expire without leaving a permanent background worker.
+  await new Promise(resolve => setTimeout(resolve, 2600));
+  await assert.rejects(fetch(final.pageUrl));
+  console.log('vibe upload process smoke passed');
+}
+main()
+  .catch(error => {
+    console.error(error);
+    process.exitCode = 1;
+  })
+  .finally(() => {
+    for (const child of children) child.kill('SIGKILL');
+    fixtureServer?.close();
+    fs.rmSync(temp, { recursive: true, force: true });
+  });

package/package.json

@@ -1,19 +1,23 @@
 {
   "name": "@ttmg/cli",
-  "version": "0.4.6-vibe-beta.5",
+  "version": "0.4.6-vibe-beta.7",
   "description": "TikTok Mini Game Command Line Tool",
   "license": "ISC",
   "bin": {
     "ttmg": "dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "vibe-upload.md"
   ],
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
+    "demo:vibe": "npm run build && node scripts/vibe-upload-demo.js",
+    "test:vibe": "node scripts/run-ts-test.js src/commands/common/vibe/vibe.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",
     "verify:dist-version": "node scripts/verify-dist-version.js",
@@ -30,14 +34,20 @@
     "test:dev-session": "node scripts/run-ts-test.js src/commands/native/dev/agentSession.test.ts",
     "test:dev-session-command": "node scripts/run-ts-test.js src/commands/native/dev/session.test.ts",
     "test:dev-runtime-event": "node scripts/run-ts-test.js src/commands/native/dev/utils/scoket.test.ts",
+    "test:dev-runtime-client": "node scripts/run-ts-test.js src/commands/native/dev/runtime/runtime.test.ts",
+    "test:dev-session-control": "node scripts/run-ts-test.js src/commands/native/dev/runtime/sessionControl.test.ts",
+    "test:dev-runtime-session-follow": "node scripts/run-ts-test.js src/commands/native/dev/runtime/runtimeSessionFollow.test.ts",
+    "test:dev-client-preview-orchestrator": "node scripts/run-ts-test.js src/commands/native/dev/runtime/clientPreviewOrchestrator.test.ts",
+    "test:dev-watch-change": "node scripts/run-ts-test.js src/commands/native/dev/utils/watchChange.test.ts",
     "test:dev-game-ready-process": "npm run build && node scripts/dev-game-ready-smoke.js",
     "test:dev-default-process": "npm run build && node scripts/dev-default-smoke.js",
+    "test:dev-client-preview-control-process": "npm run build && node scripts/dev-client-preview-control-smoke.js",
     "test:check": "node scripts/run-ts-test.js src/commands/native/check/check.test.ts",
     "test:check-ai": "node scripts/run-ts-test.js src/commands/native/check/ai.test.ts",
     "test:build-structured": "node scripts/run-ts-test.js src/commands/native/build/build.test.ts",
     "test:doctor": "node scripts/run-ts-test.js src/commands/native/doctor/doctor.test.ts",
-    "test:agent-contract": "npm run test:login && npm run test:auth && npm run test:capabilities && npm run test:test-account && npm run test:upload-preview && npm run test:preview-page && npm run test:check && npm run test:check-ai && npm run test:build-structured && npm run test:doctor && npm run test:dev-session && npm run test:dev-session-command && npm run test:dev-runtime-event && npm run test:network && npx tsc --noEmit && npm run build && npm run test:preview-page-process && npm run test:preview-page-detached && npm run verify:dist-version && npm run verify:agent-contract",
-    "test:agent-contract:full": "npm run test:agent-contract && npm run test:dev-default-process && npm run test:dev-game-ready-process",
+    "test:agent-contract": "npm run test:login && npm run test:auth && npm run test:capabilities && npm run test:test-account && npm run test:upload-preview && npm run test:preview-page && npm run test:check && npm run test:check-ai && npm run test:build-structured && npm run test:doctor && npm run test:dev-session && npm run test:dev-session-command && npm run test:dev-runtime-event && npm run test:dev-runtime-client && npm run test:dev-session-control && npm run test:dev-runtime-session-follow && npm run test:dev-client-preview-orchestrator && npm run test:dev-watch-change && npm run test:network && npm run test:vibe && npx tsc --noEmit && npm run build && npm run test:vibe-process && npm run test:preview-page-process && npm run test:preview-page-detached && npm run verify:dist-version && npm run verify:agent-contract",
+    "test:agent-contract:full": "npm run test:agent-contract && npm run test:dev-default-process && npm run test:dev-game-ready-process && npm run test:dev-client-preview-control-process",
     "publish:beta": "npm publish --registry=https://registry.npmjs.org/ --access public --tag beta",
     "setup": "node scripts/setup.js",
     "reset:local-state": "node scripts/resetLocalState.js",

package/vibe-upload.md

@@ -0,0 +1,183 @@
+# Vibe Binding and Upload — Skill Integration
+
+## 中文
+
+本次范围：本地准备 → 扫码绑定 → 上传头像 → 提交名称和头像信息 → 上传代码包 → 上传完成。不包含预览、审核或正式发布。当前创建／查询接 PPE，授权和素材上传仍为模拟。
+
+### 博华如何接入
+
+继续使用 `--mock`，无需本地环境配置。CLI 内置 `ppe_op_vc` 创建任务，展示授权二维码，并查询三次真实状态；之后模拟授权和头像／信息／代码包上传。二维码可用于查看端内授权页，不要求完成授权。真实请求失败仍报错，素材不会上传到 PPE。上线时由 CLI 版本去掉 PPE 路由，Skill 不负责切换环境。
+
+Skill 只引导开发者准备游戏名称、本地头像和工程，然后调用 CLI、读取结构化状态。不调用平台接口、不保存 Token、不自行轮询、不增加名称头像表单。
+
+Skill 固定调用：
+
+```sh
+ttmg upload --vibe --mock --dir ./game --title "星环守卫" --icon ./avatar.png --format ndjson
+```
+
+未安装本地构建时，以 `node /绝对路径/cli/dist/index.js` 替换 `ttmg`。已调通的步骤接真实接口、未调通的步骤继续模拟，由 CLI 内部维护；Skill 不跟着 HTTP 字段和联调环境变化。
+
+可先检查素材，不创建 task、不打开页面：
+
+```sh
+ttmg upload --vibe --dir ./game --title "星环守卫" --icon ./avatar.png --dry-run --format json
+```
+
+已有 ZIP 时，用 `--package ./game.zip` 替换 `--dir ./game`。名称和头像必须由开发者提供；演示脚本中的临时样本不作为产品默认素材。
+
+### Skill 读取什么
+
+输出 schema 为 `"2"`。每行 NDJSON 是同一 `operationId` 的状态快照；只有最后一行 `terminal=true`。`--format json` 仅在结束时向 stdout 输出一个对象，等待授权的本地页面地址写到 stderr。不要解析中文／英文文案判断状态。
+
+| status                          | Skill 处理                                                                                |
+| ------------------------------- | ----------------------------------------------------------------------------------------- |
+| precheck / packaging / prepared | 正在检查或准备素材；dry-run 的 prepared 为终态                                            |
+| creating_task                   | 正在准备授权绑定                                                                          |
+| waiting_authorization           | 打开 pageUrl；nextAction=scan_qr 时提示使用 TikTok 扫码，nextAction=wait 时仅等待模拟推进 |
+| uploading                       | 根据 uploadStep 显示 avatar、app_info、package 的进度，不再询问授权                       |
+| uploaded                        | terminal=true 且 uploaded=true：本次上传完成；不是审核通过或正式发布                      |
+| failed / cancelled              | 根据 errorCode、message 和 nextAction 提示处理，不自动重传                                |
+
+固定字段：`schemaVersion`、`command`、`mode`、`operationId`、`ts`、`status`、`terminal`、`nextAction`、`message`、`backend`、`simulation`、`platformWrite`、`uploadAttempted`、`uploaded`、`errorCode`、`error`。
+
+从真实创建任务请求发起前开始 `platformWrite=true`，表示已尝试平台写入，不代表创建或上传成功。只有内部离线测试、本机 HTTP 和 dry-run 保持 `platformWrite=false`。
+
+`backend=ppe-mock` 时 `simulation=true`、`simulationStartsAt=authorization`；创建任务前开始 `platformWrite=true`。`taskStatusRaw`、`readyForInput` 始终保留最后一次真实查询值，模拟状态单独放在 `simulatedTaskStatusRaw`、`simulatedReadyForInput`。终态仍为 `uploaded`，但只表示模拟上传完成，不代表真实授权或上传成功；Skill 必须保留模拟提示。
+
+按阶段补充：`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 提示上传已完成但展示失败。
+
+退出码：成功／dry-run 为 0，失败为 1，Ctrl+C 为 130。进程或宿主意外终止导致没有终态时，不得认定上传成功。模拟必须显示为模拟：即使 `uploaded=true`，`simulation=true` 时也只表示模拟步骤完成。纯 Mock 的 `platformWrite=false`；混合联调创建过真实任务时为 true，但都不代表真实上传。
+
+### Mock 覆盖与演示
+
+`npm run demo:vibe` 会构建并用临时工程和头像运行 CLI；真实检查、ZIP 打包和 PPE 创建／查询，模拟授权与上传。需要后端可访问，无需完成手机授权。结果页在进程结束后继续保留至到期。
+
+```sh
+ttmg upload --vibe --package ./game.zip --title "测试游戏" --icon ./avatar.png --mock --format ndjson
+ttmg upload --vibe --package ./game.zip --title "测试游戏" --icon ./avatar.png --mock --mock-scenario denied --format ndjson
+ttmg upload --vibe --package ./game.zip --title "测试游戏" --icon ./avatar.png --mock --mock-scenario timeout --timeout 5 --format ndjson
+ttmg upload --vibe --package ./game.zip --title "测试游戏" --icon ./avatar.png --mock --mock-scenario upload-failed --format ndjson
+```
+
+| 场景                                      | 结果                                                                 |
+| ----------------------------------------- | -------------------------------------------------------------------- |
+| success                                   | 第三次轮询允许上传，头像／信息／代码包依次完成                       |
+| denied                                    | 授权取消，VIBE_AUTH_DENIED，不上传                                   |
+| expired                                   | 授权过期，VIBE_AUTH_EXPIRED，不上传                                  |
+| timeout                                   | 持续等待，直到整体超时 VIBE_TIMEOUT                                  |
+| icon-failed / info-failed / upload-failed | 在对应上传步骤失败，uploadStep 指明位置                              |
+| processing                                | 包已上传，后端状态仍为 PROCESSING；CLI 返回 uploaded，不等 SUCCEEDED |
+
+Mock 的 denied 是交互测试场景，真实端内拒绝授权如何映射错误仍待后端确认。Mock 不请求任何远端，不更改平台登录态，不创建真实应用。
+
+轮询间隔使用创建任务返回的 `poll_interval_seconds`，第三次真实查询后模拟授权。`--poll-interval` 仅用于覆盖测试间隔。`--timeout` 是整体超时，默认 300 秒。不自动重试写接口、不实现跨进程续传。
+
+### 页面与素材
+
+同一电脑本地页依次显示授权绑定码、上传进度、上传完成；失败时清除授权码并显示失败原因。没有完成后的预览码、发布按钮或名称头像表单。结构化输出不自动打开浏览器，Skill 用 pageUrl 打开 Codex 右侧预览或浏览器；文本输出默认打开，`--no-open` 可关闭。
+
+页面只监听 127.0.0.1，二维码才由手机扫描，手机不访问 pageUrl。默认 15 分钟后关闭，内容驻留内存；测试可设置 `TTMG_VIBE_PAGE_TTL_MS`（1—900000）。取消进程会关闭页面；成功与可显示的失败页面保留至到期。不要分享本地页面地址。
+
+真实执行的部分包括本地项目检查和 ZIP 打包。文件直接输入只检查非空、大小与文件头，不代表完整图像解码、ZIP 内容检查或平台审核。现有 10 MiB 头像、100 MiB ZIP 为本地保护阈值，不是后端已确认限制。图片识别 PNG/JPEG/WebP。
+
+准备完成后固定本次素材字节，授权期间不会重新读取。打包排除 .ttmg、.env\*、PEM 和 KEY 等文件，但不保证识别所有业务秘密。
+
+CLI 在工程目录的 `.ttmg/vibe-project.json` 保存并复用非敏感 source_project_id；使用 --package 时保存在 ZIP 所在目录。不要将多个独立游戏的 ZIP 放在同一身份目录。dry-run 不创建此文件。每次运行使用新的 task_idempotency_id，当前不支持中断续传。凭证只驻留进程内存，不进入事件、文件、日志或错误信息。
+
+### HTTP 适配边界
+
+Mock 与本地 HTTP 共用请求构造、业务响应校验及状态映射，基于 2026-09-12 的 Minis Import BFF IDL：
+
+| 方法 / 接口（统一前缀 /bff/app_info/minis_import/） | 请求                                                                        | 响应                                                      |
+| --------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------- |
+| 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                                   |
+| POST upload_minis_import_app_icon_for_agent/        | Multipart：task_id、import_token、file                                      | icon_uri                                                  |
+| POST submit_minis_import_info_for_agent/            | JSON：task_id、import_token、app_info.app_name、app_info.icon_uri           | error_info                                                |
+| 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 时无损编码。
+
+```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
+```
+
+维护者可使用 `--vibe-api http://127.0.0.1:3100` 验证本机 HTTP 合同，只接受回环 IP，不跟随重定向、不读取 Cookie；本地服务需实现上表协议。博华试用无需此选项，直接 `--mock`，PPE 路由由 CLI 内置。正式环境未开放。
+
+**v1 → v2 兼容性变化**：旧 UUID 换 Token 的三接口协议废弃，`--vibe-authorize-url` 返回明确错误；授权地址来自 landing_url。不再输出 preview_ready、game_preview、uploadId、reviewStatus。Skill 必须校验 schemaVersion=2，并按新终态处理。普通不带 --vibe 的 upload 不变。
+
+仍待真实联调确认：头像／代码包规则、Token 有效期与重试规则、真实拒绝授权映射、端内 PPE Cookie 问题。后端接口调整留在适配层处理；若用户动作或成功语义改变，应协商升级 CLI schema，不能承诺 Skill 永远无需调整。
+
+### 验证
+
+`npm run test:vibe`：Mock、HTTP 合同、请求顺序、i64、失败、取消、输入和页面测试。
+
+`npm run test:vibe-process`：构建后的真实命令、JSON/NDJSON、环境配置、页面生命周期与退出码。完整 CLI 回归仍为 `npm run test:agent-contract`。测试通过不等于真实绑定上传已验证。
+
+## English
+
+### Skill entry
+
+Scope: local preparation → authorization binding → avatar upload → app-info submission → package upload → **upload complete**. No preview, review or production release. Mock and loopback HTTP cover this contract. PPE additionally supports real task creation, polling and the authorization QR only; material upload and production access are not enabled.
+
+Keep the existing --mock command; no environment setup is required:
+
+```sh
+ttmg upload --vibe --mock --dir ./game --title "My game" --icon ./avatar.png --format ndjson
+```
+
+Use `--package ./game.zip` instead of --dir for a prepared ZIP. Use `--dry-run --format json` for local preparation only. When running a source build, replace ttmg with `node /absolute/path/cli/dist/index.js`. Explicit --mock or --vibe-api overrides environment selection; an unconfigured backend fails instead of silently simulating.
+
+The Skill gathers the title and user-selected local icon in conversation. It does not call backend APIs, store credentials, poll services, or introduce a metadata form. The CLI internally connects working steps to PPE and simulates the remaining steps. Removing PPE at production launch is a CLI release change, not a Skill configuration step.
+
+### Output and decisions
+
+Schema **2** provides NDJSON snapshots under one operationId, with exactly one final `terminal=true` event. JSON mode emits one final object on stdout and the authorization page address on stderr. Structured modes do not open the browser automatically; open pageUrl in the AI workspace preview or browser. Text mode opens it unless --no-open.
+
+| status                          | Skill action                                                                              |
+| ------------------------------- | ----------------------------------------------------------------------------------------- |
+| precheck / packaging / prepared | Wait for input preparation; prepared is terminal only for dry-run                         |
+| creating_task                   | Preparing binding                                                                         |
+| waiting_authorization           | Open pageUrl; scan_qr requests a phone scan, wait means simulation advances automatically |
+| uploading                       | Follow uploadStep: avatar, app_info, package                                              |
+| uploaded                        | terminal=true and uploaded=true mean upload complete, not release                         |
+| failed / cancelled              | Read errorCode, message and nextAction; do not blindly repeat uploads                     |
+
+Stable fields: schemaVersion, command, mode, operationId, ts, status, terminal, nextAction, message, backend, simulation, platformWrite, uploadAttempted, uploaded, errorCode, error. Optional evidence: taskId (string), taskStatusRaw (diagnostics only), pollIntervalSeconds, readyForInput, uploadStep, loadedBytes, totalBytes, pageUrl, qrPurpose=authorization_binding, sizes and packageSha256.
+
+platformWrite becomes true immediately before attempting real task creation, not as proof of successful creation or upload. Only injected offline tests, loopback HTTP and dry-run keep platformWrite=false.
+
+For backend=ppe-mock, simulation=true and simulationStartsAt=authorization. platformWrite becomes true before real task creation. taskStatusRaw and readyForInput retain the last real observation; simulatedTaskStatusRaw and simulatedReadyForInput describe the local demo separately. The uploaded terminal state means simulated completion only; the Skill must retain the simulation label.
+
+nextAction is wait, scan_qr, fix_input, restart_authorization, check_task or none. If upload was attempted, verify the task before retrying. If a result page fails after confirmed upload, uploaded remains true alongside the error. Progress at 100% is not a receipt. Missing terminal output after a killed process is not success. Exit codes: 0 success/dry-run, 1 failure, 130 cancellation.
+
+Pure Mock reports simulation=true and platformWrite=false. Hybrid PPE + Mock reports platformWrite=true once real task creation is attempted, but uploaded=true still means simulated completion only. No backend exposes credentials or raw HTTP errors. Backend integration must preserve this public contract; changes to user actions or completion semantics require an explicit schema migration.
+
+### Mock, UI and inputs
+
+Run `npm run demo:vibe` for the CLI with temporary game/icon fixtures. Local checking, ZIP creation and PPE task creation/polling are real; authorization and uploads are simulated. Backend access is required, phone authorization is not. Scenarios: success, denied, expired, timeout, upload-failed, processing, icon-failed, info-failed. Use --mock-scenario and --timeout to test failures. Denial is a mock interaction scenario, not a confirmed backend error mapping.
+
+The same local page changes from binding QR to upload progress and completion, without preview QR or metadata form. Failures clear the binding QR. It listens only on 127.0.0.1, retains content in memory, and expires after 15 minutes; the phone scans the QR rather than visiting pageUrl. Success/failure pages remain after CLI completion; cancellation closes the page. Test TTL: TTMG_VIBE_PAGE_TTL_MS=1..900000.
+
+The trial follows poll_interval_seconds and simulates input readiness after the third real query; --poll-interval is a testing override. The overall --timeout defaults to 300 seconds. No automatic write retries or cross-process resume.
+
+The supplied title/icon/package bytes are fixed before authorization. Direct files are checked for size and signatures, not decoded or fully inspected. PNG/JPEG/WebP and 10 MiB icon / 100 MiB ZIP limits are provisional local guards, not confirmed platform rules. Project packaging excludes .ttmg, .env\*, PEM and KEY files, not every possible secret.
+
+A non-secret source_project_id is persisted in .ttmg/vibe-project.json under the project, or the ZIP parent for --package. Keep distinct games in separate directories. Dry-run does not create identity metadata. Each invocation has a new task_idempotency_id; credentials are held only in memory.
+
+### Adapter and verification
+
+The five endpoint contracts are listed in the table above. Mock and loopback HTTP share request construction and response validation. The HTTP adapter implements POST create → GET status with task_id/import_token query parameters → Multipart icon → JSON app_info → Multipart package with asset_type=2 (Native). Multipart Content-Type includes its generated boundary; JSON i64 task IDs are encoded losslessly.
+
+A business-success response requires error_info.code=0. Package completion additionally requires package_uri and a valid non-failure status; no polling until SUCCEEDED. No platform Cookies or redirects are used. Configure TTMG_VIBE_BACKEND=local-http plus TTMG_VIBE_API=http://127.0.0.1:3100, or pass --vibe-api explicitly; this option rejects remote hosts.
+
+For internal PPE integration, set TTMG_VIBE_BACKEND=ppe and TTMG_VIBE_PPE=ppe_op_vc without changing the Skill command. This uses real creation/polling on developers.tiktok.com and encodes the QR as aweme://webview?url=<encodeURIComponent(landing_url)>. The phone must use the same lane. OAuth is not bypassed or simulated. Complete upload inputs are not integrated yet: after authorization, VIBE_REAL_UPLOAD_NOT_READY stops the flow before any material upload. Production is not enabled.
+
+The normal --mock trial internally uses ppe_op_vc without environment variables. Task creation, QR and three polls are real; authorization, icon, app-info and package uploads are simulated with separate in-memory credentials. This changes --mock from an offline run into a PPE integration trial: platformWrite becomes true when task creation is attempted, while simulation remains true. No real material-upload endpoint is called, and real request failures still fail. --mock-scenario controls only simulated steps. Offline unit/process tests use injected transports, not a separate developer configuration.
+
+Schema-v1 UUID endpoints, --vibe-authorize-url, preview_ready, game_preview, uploadId and reviewStatus are retired. The deprecated option returns an explicit error. Ordinary upload without --vibe is unchanged.
+
+Unconfirmed: platform file limits, token expiry/retry rules, actual denial mapping and in-client PPE Cookie behavior. Run test:vibe, built test:vibe-process, and test:agent-contract. Local contract tests do not establish real platform or device results.