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

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttmg/cli",
-  "version": "0.4.6-vibe-beta.11",
+  "version": "0.4.6-vibe-beta.14",
   "description": "TikTok Mini Game Command Line Tool",
   "license": "ISC",
   "bin": {
@@ -16,7 +16,8 @@
   },
   "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: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-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",
@@ -50,7 +51,7 @@
     "test:wasm": "node scripts/run-ts-test.js src/commands/native/wasm/wasm.test.ts && node scripts/acceptance-fixture.test.js",
     "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:wasm && 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 && node scripts/dev-workflow-smoke.js",
-    "publish:beta": "npm publish --registry=https://registry.npmjs.org/ --access public --tag vibe-beta",
+    "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",
     "dev:link": "npm run build && npm link",

package/dist/scripts/verify-agent-contract.js

@@ -126,6 +126,18 @@ const capabilitiesResult = runCli(['capabilities', '--format', 'json']);
 assertExit(capabilitiesResult, 0, 'capabilities');
 const capabilities = parseSingleJson(capabilitiesResult, 'capabilities');
 assert.equal(capabilities.command, 'capabilities');
+const gameCategories = runCli(['game', 'categories', '--format', 'json']);
+assertExit(gameCategories, 0, 'game categories');
+const categoryCatalog = parseSingleJson(gameCategories, 'game categories');
+assert.equal(categoryCatalog.platformWrite, false);
+assert.equal(categoryCatalog.categoryCount, 12);
+assert.equal(categoryCatalog.subcategoryCount, 114);
+assert.equal(capabilities.commands.gameCategories.catalogVersion, categoryCatalog.catalogVersion);
+assert.match(capabilities.commands.vibeUpload.command, /--vibe --web/);
+assert.equal(capabilities.commands.vibeUpload.skillWorkflow.keepUploadProcessRunning, true);
+assert.equal(capabilities.commands.vibeUpload.skillWorkflow.realUploadSuccess.simulation, false);
+assert.equal(capabilities.commands.vibeUpload.appInfoFields.defaultedByCli.includes('privacy_policy'), true);
+assert.equal(packageJson.files.includes('vibe-upload.md'), true);
 assert.equal(capabilities.structuredOutput.stdoutProtocolOnly, true);
 assert.equal(capabilities.commands.check.platformWrite, false);
 assert.equal(capabilities.commands.check.ai.option, '--ai');
@@ -388,6 +400,11 @@ const uploadHelp = runCli(['upload', '--help']);
 assert.doesNotMatch(uploadHelp.stdout, /--app-info/);
 assert.match(uploadHelp.stdout.replace(/\s+/g, ' '), /only title and icon|只收集标题和头像/);
 assertExit(uploadHelp, 0, 'upload help');
+assert.match(uploadHelp.stdout, /--vibe --web --dir/);
+assert.match(uploadHelp.stdout, /authorizationOpenCommand/);
+assert.match(uploadHelp.stdout, /simulation=false/);
+assert.match(uploadHelp.stdout, /--category <category>/);
+assert.match(uploadHelp.stdout, /--subcategory <subcategory>/);
 assert.match(uploadHelp.stdout, /--preview\b/);
 assert.match(uploadHelp.stdout, /--serve-preview-page\b/);
 assert.match(uploadHelp.stdout, /--no-open\b/);

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

@@ -30,6 +30,7 @@ let failStatus = false;
 let webMode = false;
 let webPolls = 0;
 let webFailureEndpoint;
+let expectedWebCategory = { category: 'Other', subcategory: 'Other' };
 const env = {
   ...process.env,
   HOME: temp,
@@ -194,9 +195,9 @@ async function main() {
         assert.equal(info.app_info.app_name, input[input.indexOf('--title') + 1]);
         assert.deepEqual(info.app_info, {
           description: 'DevTool PPE integration test fixture. Not a production game.',
-          category: 'Other', subcategory: 'Other',
-          terms_of_service: 'https://example.invalid/devtool-ppe-test/terms',
-          privacy_policy: 'https://example.invalid/devtool-ppe-test/privacy',
+          ...expectedWebCategory,
+          terms_of_service: 'https://www.tiktok.com',
+          privacy_policy: 'https://www.tiktok.com',
           copyright_confirmation: true, contact_email: 'devtool-test@example.invalid',
           app_name: input[input.indexOf('--title') + 1], icon_uri: 'web-icon-receipt',
         }, 'CLI must send complete PPE trial defaults without asking the user for them');
@@ -261,6 +262,14 @@ async function main() {
   const completeDry = await run([...input, '--app-info', appInfoPath, '--dry-run', '--format', 'json']);
   assert.equal(completeDry.code, 0, completeDry.stderr);
   assert.equal(events(completeDry)[0].status, 'prepared');
+  assert.equal(events(completeDry)[0].classification.category, 'Casual');
+  assert.equal(events(completeDry)[0].classification.subcategory, 'Puzzle');
+  assert.equal(events(completeDry)[0].classification.source, 'app-info');
+  const overrideDry = await run([...input, '--app-info', appInfoPath, '--category', 'Puzzle', '--subcategory', 'Physics', '--dry-run', '--format', 'json']);
+  assert.equal(overrideDry.code, 0, overrideDry.stderr);
+  assert.equal(events(overrideDry)[0].classification.category, 'Puzzle');
+  assert.equal(events(overrideDry)[0].classification.subcategory, 'Physics');
+  assert.equal(events(overrideDry)[0].classification.source, 'arguments');
   assert.equal(requests.length, 0);
   fs.writeFileSync(appInfoPath, '{private-token');
   const badInfo = await run([...input, '--mock', '--app-info', appInfoPath, '--format', 'json']);
@@ -370,11 +379,32 @@ async function main() {
   const legacyWeb = await run(['upload', '--web', '--format', 'json']);
   assert.equal(events(legacyWeb)[0].errorCode, 'VIBE_OPTION_REQUIRES_VIBE');
   assert.equal(requests.length, beforeWeb);
+  for (const [args, code] of [
+    [['--category', 'Puzzle'], 'VIBE_CATEGORY_PAIR_REQUIRED'],
+    [['--subcategory', 'Physics'], 'VIBE_CATEGORY_PAIR_REQUIRED'],
+    [['--category', 'Other', '--subcategory', 'Physics'], 'VIBE_INVALID_CATEGORY'],
+    [['--category', 'Unknown', '--subcategory', 'Other'], 'VIBE_INVALID_CATEGORY'],
+    [['--category', '', '--subcategory', ''], 'VIBE_INVALID_CATEGORY'],
+  ]) {
+    const invalid = await run([...input.filter(v => v !== '--no-open'), '--web', ...args, '--format', 'json']);
+    assert.equal(invalid.code, 1);
+    const result = events(invalid)[0];
+    assert.equal(result.errorCode, code);
+    assert.equal(result.platformWrite, false);
+    assert.equal(result.taskId, undefined);
+    assert.equal(result.pageUrl, undefined);
+  }
+  assert.equal(requests.length, beforeWeb, 'Invalid classification must not create tasks or upload');
   webMode = true;
   for (const format of ['json', 'ndjson']) {
+    expectedWebCategory = format === 'json' ? {category: 'Other', subcategory: 'Other'} : {category: 'Puzzle', subcategory: 'Physics'};
+    const categoryArgs = format === 'json' ? [] : ['--category', 'Puzzle', '--subcategory', 'Physics'];
     const receipt = path.join(temp, `upload-web-${format}.ndjson`);
     const requestStart = requests.length;
-    const web = await run([...input.filter(v => v !== '--no-open'), '--web', '--format', format, '--poll-interval', '0.2'], async event => {
+    const web = await run([...input.filter(v => v !== '--no-open'), '--web', ...categoryArgs, '--format', format, '--poll-interval', '0.2'], async event => {
+      if (event.status === 'prepared') assert.deepEqual(
+        {category: event.classification.category, subcategory: event.classification.subcategory},
+        expectedWebCategory);
       if (event.status === 'waiting_authorization') {
         assert.equal(event.authorizationMode, 'web');
         assert.equal(event.browserOpenRequested, true);
@@ -403,6 +433,10 @@ async function main() {
     assert.equal(output.at(-1).readyForInput, true);
     assert.equal(output.at(-1).uploadAttempted, true);
     assert.equal(output.at(-1).uploaded, true);
+    assert.deepEqual(
+      { category: output.at(-1).classification.category, subcategory: output.at(-1).classification.subcategory },
+      expectedWebCategory);
+    assert.equal(output.at(-1).classification.source, format === 'json' ? 'defaults' : 'arguments');
     assert.equal(output.at(-1).taskStatusRaw, 3);
     assert.equal(output.filter(e => e.terminal).length, 1);
     assert.equal(webPolls, 5, 'Only true backend readiness unlocks authorization');
@@ -416,6 +450,7 @@ async function main() {
     assert.ok(opens[0].args.some(arg => /^http:\/\/127\.0\.0\.1:\d+\/[a-f0-9]{48}\/authorize$/.test(arg)));
     assert.doesNotMatch(JSON.stringify(opens) + web.stdout + web.stderr, /process-test-secret|import_token|web-icon-receipt|web-package-receipt|aweme:\/\//);
   }
+  expectedWebCategory = {category: 'Other', subcategory: 'Other'};
   webFailureEndpoint = '/bff/app_info/minis_import/submit_minis_import_info_for_agent/';
   const failedStart = requests.length;
   const webUploadFailure = await run([...input.filter(v => v !== '--no-open'), '--web', '--format', 'json'], undefined, {
@@ -552,6 +587,29 @@ async function main() {
   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 badCategoryMode = await run(['upload', '--category', 'Puzzle', '--subcategory', 'Physics', '--format', 'json']);
+  assert.equal(events(badCategoryMode)[0].errorCode, 'VIBE_OPTION_REQUIRES_VIBE');
+  const beforeCatalog = requests.length;
+  const catalog = await run(['game', 'categories', '--format', 'json']);
+  assert.equal(catalog.code, 0, catalog.stderr);
+  assert.equal(events(catalog).length, 1);
+  assert.equal(events(catalog)[0].categoryCount, 12);
+  assert.equal(events(catalog)[0].subcategoryCount, 114);
+  assert.equal(events(catalog)[0].platformWrite, false);
+  const filtered = await run(['game', 'categories', '--category', 'Puzzle', '--format', 'ndjson']);
+  assert.equal(filtered.code, 0);
+  assert.deepEqual(events(filtered)[0].categories.map(item => item.value), ['Puzzle']);
+  assert.ok(events(filtered)[0].categories[0].subcategories.every(item => item.description));
+  for (const [args, code] of [
+    [['--category', 'unknown'], 'GAME_CATEGORY_UNKNOWN'],
+    [['--format', 'xml'], 'GAME_CATEGORIES_INVALID_FORMAT'],
+  ]) {
+    const invalid = await run(['game', 'categories', '--format', 'json', ...args]);
+    assert.equal(invalid.code, 1);
+    assert.equal(events(invalid)[0].errorCode, code);
+    assert.equal(events(invalid)[0].platformWrite, false);
+  }
+  assert.equal(requests.length, beforeCatalog, 'Catalog commands must remain offline');
   const help = await run(['upload', '--help']);
   assert.equal(help.code, 0);
   assert.match(help.stdout, /--vibe/);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttmg/cli",
-  "version": "0.4.6-vibe-beta.11",
+  "version": "0.4.6-vibe-beta.14",
   "description": "TikTok Mini Game Command Line Tool",
   "license": "ISC",
   "bin": {
@@ -16,7 +16,8 @@
   },
   "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: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-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",
@@ -50,7 +51,7 @@
     "test:wasm": "node scripts/run-ts-test.js src/commands/native/wasm/wasm.test.ts && node scripts/acceptance-fixture.test.js",
     "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:wasm && 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 && node scripts/dev-workflow-smoke.js",
-    "publish:beta": "npm publish --registry=https://registry.npmjs.org/ --access public --tag vibe-beta",
+    "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",
     "dev:link": "npm run build && npm link",

package/vibe-upload.md

@@ -6,34 +6,76 @@
 
 本次范围：本地准备 → 授权绑定 → 上传头像 → 提交应用信息 → 上传代码包 → 上传完成。不包含预览、审核或正式发布。`--web` 使用真实 PPE 授权和上传；`--mock` 的授权与素材上传仍为模拟。网页授权后自动上传的修复已在 `0.4.6-vibe-beta.9` 发布；用户输入要求已在 `0.4.6-vibe-beta.10` 修正。
 
-### 博华如何接入
+### Web 上传入口
 
-继续使用 `--mock`，无需本地环境配置。CLI 内置 `ppe_op_vc` 创建任务，展示授权二维码，并查询三次真实状态；之后模拟授权和头像／信息／代码包上传。二维码可用于查看端内授权页，不要求完成授权。真实请求失败仍报错，素材不会上传到 PPE。上线时由 CLI 版本去掉 PPE 路由，Skill 不负责切换环境。
+真实授权和上传使用 `--web`。安装 `vibe-beta` 标签对应的版本，再用 `ttmg --version` 核对实际执行版本。`beta` 是另一个发布标签，不能用它判断 Web 链路是否包含最新修复。无需设置 PPE 环境变量或预先执行 `ttmg login`；用户在本次浏览器授权页完成授权。
 
 Skill 只引导开发者准备游戏名称、本地头像和工程，然后调用 CLI、读取结构化状态。不调用平台接口、不保存 Token、不自行轮询、不增加名称头像表单。
 
 Skill 固定调用：
 
 ```sh
-ttmg upload --vibe --mock --dir ./game --title "星环守卫" --icon ./avatar.png --format ndjson
+npm install -g @ttmg/cli@vibe-beta
+ttmg --version
+ttmg capabilities --format json
+ttmg upload --vibe --web --dir ./game --title "星环守卫" --icon ./avatar.png --format ndjson
 ```
 
-未安装本地构建时，以 `node /绝对路径/cli/dist/index.js` 替换 `ttmg`。已调通的步骤接真实接口、未调通的步骤继续模拟，由 CLI 内部维护；Skill 不跟着 HTTP 字段和联调环境变化。
+Skill 启动一次命令并持续读取 NDJSON。宿主工具返回会话 ID 时，继续读取同一进程；等待用户授权期间不终止、不重启，也不再调用第二次上传。`--web` 全程使用真实授权和上传；`--mock` 仅用于下方单独列出的演示。
 
 可先检查素材，不创建 task、不打开页面：
 
 ```sh
-ttmg upload --vibe --dir ./game --title "星环守卫" --icon ./avatar.png --dry-run --format json
+ttmg upload --vibe --web --dir ./game --title "星环守卫" --icon ./avatar.png --dry-run --format json
 ```
 
 已有 ZIP 时，用 `--package ./game.zip` 替换 `--dir ./game`。名称和头像必须由开发者提供；演示脚本中的临时样本不作为产品默认素材。
 
 ### 用户需要提供什么
 
-**只收集游戏标题和本地头像，并使用当前游戏目录或代码包。** 描述、分类、服务条款、隐私政策、版权确认及其他应用资料由 CLI 使用既有 PPE 试用默认值补齐，Skill 不向用户索要，也不生成资料表单或自行补值。
+**只向用户收集游戏标题和本地头像，并使用当前游戏目录或代码包。** 描述、服务条款、隐私政策、版权确认及其他应用资料由 CLI 使用既有 PPE 试用默认值补齐。分类可由 Skill 按下方目录选择，未选择时仍使用默认值；不向用户索要额外资料或增加填写表单。
 
 能力查询和上传事件均返回 `inputRequirements`：`requiredUserInputs=["title","icon"]`、`additionalMetadataSource="cli-defaults"`、`requestAdditionalMetadata=false`。`--app-info` 仅兼容旧调用，当前流程不使用。
 
+CLI 在 `app_info` 请求中自动带上 `description`、`category`、`subcategory`、`terms_of_service`、`privacy_policy`、`copyright_confirmation`、`contact_email`，再填入用户标题和真实上传头像 URI。默认资料标识为 `ppe-trial`；命令中没有这些参数，不代表请求里没传。能力查询的 `appInfoFields.defaultedByCli` 列出默认字段。
+
+### 查询并推荐游戏分类
+
+以下命令和参数从 `0.4.6-vibe-beta.14` 开始提供。查询离线执行，不登录、不创建任务、不写平台：
+
+```sh
+ttmg game categories --format json
+ttmg game categories --category Puzzle --format json
+```
+
+返回 `schemaVersion="1"`、`catalogVersion`、`source=bundled`、`platformWrite=false`，以及 `categories[].value` 和 `subcategories[].value/description`。当前为 12 个类型、114 个子类型，玩法说明为英文；按精确英文值筛选。`catalogVersion` 标识随 CLI 打包的快照，不表示实时拉取线上配置。
+
+Skill 根据生成游戏的核心玩法和胜负条件选择组合，给用户一句推荐理由；用户已指定分类时优先保留。不增加必填表单；无法匹配时可使用 Other/Other。
+
+```sh
+ttmg upload --vibe --web --dir ./game --title "星环守卫" --icon ./avatar.png --category Puzzle --subcategory Physics --format ndjson
+```
+
+
+- 两个分类参数都不传：仍为 `Other / Other`，旧 Skill 命令无需修改。
+
+- 两个都传：校验通过后仅覆盖分类，其他默认资料继续自动补齐。
+
+- 只传一个：`VIBE_CATEGORY_PAIR_REQUIRED`；值无效或归属不匹配：`VIBE_INVALID_CATEGORY`。均在创建任务和打开浏览器前失败，不静默改成 Other。
+
+- 旧 `--app-info` 调用未传新参数时，保留文件分类与原校验行为；显式分类参数覆盖文件分类。新流程不需要该文件。
+
+- `prepared` 和后续终态返回 `classification={category, subcategory, source, catalogVersion}`，来源为 `arguments / defaults / app-info`。`--dry-run` 可核对最终选值。
+
+- 查询类型不存在：`GAME_CATEGORY_UNKNOWN`；格式无效：`GAME_CATEGORIES_INVALID_FORMAT`。返回非零退出码。
+
+### Skill 执行顺序
+
+1. 调用上方 `--web --format ndjson` 命令；本地预检可先加 `--dry-run`。
+2. 收到 `waiting_authorization`，提示用户在系统浏览器完成授权，保持原进程运行。
+3. 收到 `uploading`，按 `uploadStep` 展示 `avatar`、`app_info`、`package` 进度。授权轮询和上传由 CLI 完成。
+4. 收到 `terminal=true`、`status=uploaded`、`uploaded=true`、`simulation=false`，确认真实上传完成。`failed`、`cancelled` 或进程中断按下方失败说明处理。
+
 ### Skill 读取什么
 
 #### 上传时直接使用网页授权
@@ -58,6 +100,8 @@ ttmg auth open --page-url <pageUrl> --format json
 
 命令通过临时本地页面跳转到后端原始 `landing_url`，不使用 `aweme://`，不新建任务或上传文件。凭证只留在上传进程与页面服务中，不输出到 Skill 或放进命令参数。原上传进程继续轮询，授权成功与否以其 `readyForInput` 为准。
 
+`pageUrl` 是本机绑定／上传进度页，不是平台原始授权页。`authorizationOpenCommand` 是重新打开同一任务授权页的入口；正常情况下 `--web` 已经自动打开，无需重复执行。`browserOpenRequested=true` 只代表发起打开浏览器，不能据此判定授权成功。两种页面入口都依赖原上传进程，不能把本机链接发给另一台电脑使用。
+
 成功返回 `status=open_requested`、`browserOpenRequested=true`、`platformWrite=false`，只表示已请求系统浏览器打开。页面过期、流程结束或没有可用真实授权地址时，返回 `VIBE_AUTH_PAGE_UNAVAILABLE`；URL 输入错误返回 `VIBE_INVALID_PAGE_URL`，浏览器启动失败返回 `VIBE_BROWSER_OPEN_FAILED`。不得因打开失败而自动创建新任务。
 
 命令在 CLI 所在电脑执行；远程机器不会打开开发者电脑的浏览器。二维码原路径和 `--mock` 自动推进逻辑保持不变；真实网页授权与上传使用 `--web`。
@@ -105,13 +149,13 @@ ttmg upload --vibe --package ./game.zip --title "测试游戏" --icon ./avatar.p
 | icon-failed / info-failed / upload-failed | 在对应上传步骤失败，uploadStep 指明位置                              |
 | processing                                | 包已上传，后端状态仍为 PROCESSING；CLI 返回 uploaded，不等 SUCCEEDED |
 
-Mock 的 denied 是交互测试场景，真实端内拒绝授权如何映射错误仍待后端确认。Mock 不请求任何远端，不更改平台登录态，不创建真实应用。
+Mock 的 denied 是交互测试场景，真实端内拒绝授权如何映射错误仍待后端确认。独立离线测试通过注入传输实现；用户执行的 `--mock` 会真实创建并查询 PPE 任务，但不调用真实素材上传接口。
 
 轮询间隔使用创建任务返回的 `poll_interval_seconds`，第三次真实查询后模拟授权。`--poll-interval` 仅用于覆盖测试间隔。`--timeout` 是整体超时，默认 300 秒。不自动重试写接口、不实现跨进程续传。
 
 ### 页面与素材
 
-同一电脑本地页依次显示授权绑定码、上传进度、上传完成；失败时清除授权码并显示失败原因。没有完成后的预览码、发布按钮或名称头像表单。结构化输出不自动打开浏览器，Skill 用 pageUrl 打开 Codex 右侧预览或浏览器；文本输出默认打开，`--no-open` 可关闭。
+同一电脑本地页显示绑定状态、上传进度、上传完成；二维码模式显示授权绑定码，Web 模式在系统浏览器完成授权。失败时清除授权码并显示失败原因。`--web` 在 text、JSON、NDJSON 格式下均自动打开授权页；其他模式只有 text 默认打开本地页，可用 `--no-open` 关闭。Skill 可用 `pageUrl` 展示本地进度页。
 
 页面只监听 127.0.0.1，二维码才由手机扫描，手机不访问 pageUrl。默认 15 分钟后关闭，内容驻留内存；测试可设置 `TTMG_VIBE_PAGE_TTL_MS`（1—900000）。取消进程会关闭页面；成功与可显示的失败页面保留至到期。不要分享本地页面地址。
 
@@ -143,7 +187,7 @@ TTMG_VIBE_BACKEND=local-http TTMG_VIBE_API=http://127.0.0.1:3100 ttmg upload --v
 
 **v1 → v2 兼容性变化**：旧 UUID 换 Token 的三接口协议废弃，`--vibe-authorize-url` 返回明确错误；授权地址来自 landing_url。不再输出 preview_ready、game_preview、uploadId、reviewStatus。Skill 必须校验 schemaVersion=2，并按新终态处理。普通不带 --vibe 的 upload 不变。
 
-2026-09-14 已核对 BFF 源码：头像 PNG/JPEG、1024×1024、5 MiB；Native ZIP 和解压总大小上限 100 MiB。本地暂未实现完整 ZIP 内容及解压总大小校验。待真实联调验证：网关包体透传、TOS 权限、手机 OAuth 授权与上传回执。后端接口调整留在适配层处理；若用户动作或成功语义改变，应协商升级 CLI schema。
+2026-09-14 已核对 BFF 源码：头像 PNG/JPEG、1024×1024、5 MiB；Native ZIP 和解压总大小上限 100 MiB。本地暂未实现完整 ZIP 内容及解压总大小校验。2026-09-15 修复构建使用自有测试素材跑通真实 PPE 网页授权、头像、默认资料和代码包上传；该验证不覆盖全部游戏、手机授权或正式环境。后端接口调整留在适配层处理；若用户动作或成功语义改变，应协商升级 CLI schema。
 
 ### 验证
 
@@ -153,33 +197,77 @@ TTMG_VIBE_BACKEND=local-http TTMG_VIBE_API=http://127.0.0.1:3100 ttmg upload --v
 
 ## English
 
-The default-metadata fix ships in `0.4.6-vibe-beta.11`. CLI now fills the existing PPE trial metadata automatically; users provide only title and icon. Beta.10 changed input guidance without filling the fields, and its real app-info submission was rejected.
+The default-metadata fix shipped in `0.4.6-vibe-beta.11`. The CLI fills the existing PPE trial metadata automatically; users provide only title and icon. Beta.10 changed input guidance without filling the fields, and its real app-info submission was rejected.
 
-### Skill entry
+### Web upload entry
 
 Scope: local preparation → authorization binding → avatar upload → app-info submission → package upload → **upload complete**. No preview, review or production release. `--web` uses real PPE authorization and uploads; `--mock` still simulates authorization and material uploads.
 
 Automatic upload was fixed in `0.4.6-vibe-beta.9`; the user-input clarification ships in `0.4.6-vibe-beta.10`.
 
-Keep the existing --mock command; no environment setup is required:
+Use `--web` for real authorization and upload. Install `vibe-beta` and check the executable with `ttmg --version`. The separate `beta` tag does not identify the latest Web fixes. No PPE environment variables or prior `ttmg login` are required; the user authorizes in the browser for this task.
 
 ```sh
-ttmg upload --vibe --mock --dir ./game --title "My game" --icon ./avatar.png --format ndjson
+npm install -g @ttmg/cli@vibe-beta
+ttmg --version
+ttmg capabilities --format json
+ttmg upload --vibe --web --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.
+Use `--package ./game.zip` instead of `--dir` for an existing ZIP. Add `--dry-run --format json` to the Web command for local preparation only; it creates no task and opens no browser.
 
-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.
+Start one command and keep reading its NDJSON. If the host tool returns a session ID, keep reading that same process while the user authorizes. Do not stop, restart or launch another upload. `--web` uses real authorization and uploads throughout; `--mock` is the separate demo mode below. The Skill does not call platform APIs, store credentials or add a metadata form.
 
 ### User inputs
 
-**Collect only the game title and local icon, using the current game directory or ZIP.** The CLI fills other app metadata with existing PPE trial defaults. Do not request extra fields, add a form or invent values.
+**Collect only the game title and local icon, using the current game directory or ZIP.** The CLI fills other app metadata with existing PPE trial defaults. The Skill may select a category pair from the catalog below; omission keeps the defaults. Do not ask the user for extra fields or add a form.
 
 Capabilities and upload events include `inputRequirements` with `requiredUserInputs=["title","icon"]`, `additionalMetadataSource="cli-defaults"` and `requestAdditionalMetadata=false`.
 
 The `--app-info` option remains for legacy callers only; the current workflow does not use it.
 
-Source checked on 2026-09-14: BFF enforces these icon limits and a 100 MiB Native ZIP/uncompressed-size limit. Full local ZIP-content/uncompressed-size validation is not implemented. Gateway transport, TOS access, phone OAuth and upload receipts still require real integration testing.
+The CLI submits `description`, `category`, `subcategory`, `terms_of_service`, `privacy_policy`, `copyright_confirmation` and `contact_email` inside `app_info`, together with the user title and uploaded icon URI. The profile is `ppe-trial`; missing command-line arguments do not mean missing request fields. Capabilities list the defaults under `appInfoFields.defaultedByCli`.
+
+Source checked on 2026-09-14: BFF enforces PNG/JPEG, 1024×1024, 5 MiB icons and a 100 MiB Native ZIP/uncompressed-size limit. Full local ZIP-content/uncompressed-size validation is not implemented. On 2026-09-15, a corrected build completed real PPE web authorization and icon, default app-info and package uploads with owned test fixtures. This does not cover every game, phone authorization or production.
+
+### Query and recommend game categories
+
+These commands and options are available from `0.4.6-vibe-beta.14`. Queries run offline without login, task creation or platform writes:
+
+```sh
+ttmg game categories --format json
+ttmg game categories --category Puzzle --format json
+```
+
+The result includes `schemaVersion="1"`, `catalogVersion`, `source=bundled`, `platformWrite=false`, `categories[].value` and `subcategories[].value/description`.
+
+There are 12 categories and 114 subcategories with English gameplay descriptions. Filtering uses the exact category value. The version identifies a bundled snapshot, not a live platform fetch.
+
+The Skill selects a valid pair from the generated game's core gameplay and win conditions and gives a short reason. Preserve a user's explicit choice. Do not add a required form; use Other/Other when no category matches.
+
+```sh
+ttmg upload --vibe --web --dir ./game --title "My game" --icon ./avatar.png --category Puzzle --subcategory Physics --format ndjson
+```
+
+
+- Omit both: keep `Other / Other`; existing Skill commands work unchanged.
+
+- Supply both: override only category fields after validation; other metadata defaults remain.
+
+- Supply one: `VIBE_CATEGORY_PAIR_REQUIRED`. Invalid values or a mismatched pair: `VIBE_INVALID_CATEGORY`. Fail before task creation or browser opening, without a silent fallback.
+
+- Legacy `--app-info` calls retain file values and existing validation when new options are absent. Explicit category options override file category fields. New callers need no metadata file.
+
+- The `prepared` and subsequent terminal events return `classification={category, subcategory, source, catalogVersion}`, with source `arguments / defaults / app-info`. Use `--dry-run` to inspect the effective selection.
+
+- Unknown query category: `GAME_CATEGORY_UNKNOWN`. Invalid format: `GAME_CATEGORIES_INVALID_FORMAT`. Both return nonzero exit codes.
+
+### Skill execution order
+
+1. Run the `--web --format ndjson` command above; optionally precheck with `--dry-run`.
+2. At `waiting_authorization`, ask the user to authorize in the system browser and keep the process running.
+3. At `uploading`, display `uploadStep`: `avatar`, `app_info`, then `package`. The CLI owns polling and uploads.
+4. Confirm real completion only when `terminal=true`, `status=uploaded`, `uploaded=true`, `simulation=false`. Handle failure, cancellation or interruption as described below.
 
 ### Output and decisions
 
@@ -210,6 +298,8 @@ Credentials stay inside the uploader/page worker, not in Skill output or command
 arguments. The original uploader keeps polling; its `readyForInput` determines
 authorization readiness.
 
+`pageUrl` is the local binding/upload-progress page, not the original platform authorization URL. To reopen authorization for the same task, execute `authorizationOpenCommand`. Normally `--web` has already opened it. `browserOpenRequested=true` only confirms the open request, not authorization. Both page entry points depend on the original uploader and the CLI computer; do not send localhost links to another computer.
+
 Success reports `status=open_requested`, `browserOpenRequested=true`, and
 `platformWrite=false`; it does not mean authorization succeeded. Expired,
 completed, or unavailable authorization pages return `VIBE_AUTH_PAGE_UNAVAILABLE`;
@@ -265,4 +355,4 @@ The normal --mock trial internally uses ppe_op_vc without environment variables.
 
 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.
+Unconfirmed: 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; the PPE test-fixture result above is recorded separately.