@ttmg/cli 0.4.1-beta.wasm1 → 0.4.2

package/dist/scripts/docs/scenarios/devtool-guide.mjs

@@ -0,0 +1,802 @@
+export const schemaVersion = 1;
+
+export const locales = ['zh-CN', 'en-US'];
+
+export const guideTitle = 'TikTok Mini Games DevTool Usage Guide';
+
+export const guideSource = {
+  type: 'lark-wiki',
+  title: 'DevTool 使用指南',
+  url: 'https://bytedance.larkoffice.com/wiki/Pu01wnThsiyCl2kff2mcvDaannc',
+  token: 'Pu01wnThsiyCl2kff2mcvDaannc',
+  documentId: 'EDxrdwTxfoekL0x3c1xlNj2ygRe',
+  observedRevisionId: 2821,
+  outline: [
+    '中文 / English',
+    '开始之前 / Before You Start',
+    '使用链路 / Usage Flow',
+    '关键模块 / Key Modules',
+    '模式边界 / Mode Boundaries',
+    '常见问题 / FAQ',
+    '更多参考 / More References',
+  ],
+};
+
+export const docVersion = {
+  id: 'ttmg-devtool-usage-guide',
+  status: 'draft',
+  ownerReviewRequired: true,
+  sourceOfTruth: 'DevTool UI + scenario manifest + latest captured screenshots',
+  publishTiming: 'before a DevTool release or when screenshots in the public guide are refreshed',
+};
+
+export const documentationContract = {
+  audience: 'external mini-game developers using DevTool',
+  intent: [
+    'Help developers finish debugging and release tasks with the current UI.',
+    'Expose only developer-visible behavior, not internal architecture or implementation details.',
+    'Keep screenshots, UI copy, commands, and troubleshooting guidance synchronized.',
+  ],
+  writingRules: [
+    'Start from the developer task or visible symptom.',
+    'Explain what to do next before adding background.',
+    'Keep commands contextual; do not turn the guide into a CLI reference.',
+    'Separate permission, proxy/network, and project-configuration issues.',
+    'Do not publish screenshots that depend on private accounts, tokens, or real QR payloads.',
+  ],
+  screenshotRules: [
+    'Use docMode fixtures and stable data-doc-shot anchors whenever possible.',
+    'Capture both zh-CN and en-US for every published screenshot.',
+    'Refresh screenshots after layout, copy, permission-state, or network-state changes.',
+  ],
+};
+
+export const guideReleaseChecks = [
+  'The generated guide draft matches the latest scenario manifest.',
+  'Every published screenshot has zh-CN and en-US variants.',
+  'capture-report.json matches the current scenario fingerprint.',
+  'Permission and proxy/network fallback states are covered in FAQ or page notes.',
+  'No internal-only route, account, token, or private QR payload is visible.',
+];
+
+export const screenshotInventory = [
+  {
+    id: 'start-debug.qr-idle',
+    recipeId: 'home',
+    guideSection: 'Start debugging',
+    publishInGuide: true,
+    purpose: 'QR entry, launch-mode switch, and local Node status',
+  },
+  {
+    id: 'launch-mode.default',
+    recipeId: 'launch-mode',
+    guideSection: 'Start debugging',
+    publishInGuide: true,
+    purpose: 'custom launch package, scene, and launch parameters',
+  },
+  {
+    id: 'project.ready',
+    recipeId: 'project-detail',
+    guideSection: 'Project overview',
+    publishInGuide: true,
+    purpose: 'project metadata, package status, Trust Domain, Terms, and Privacy',
+  },
+  {
+    id: 'integration.map',
+    recipeId: 'integration-assistant-map',
+    guideSection: 'Integration assistant',
+    publishInGuide: true,
+    purpose: 'business-model choice and capability grouping',
+  },
+  {
+    id: 'upload.precheck',
+    recipeId: 'upload-publish',
+    guideSection: 'Upload & publish',
+    publishInGuide: true,
+    purpose: 'precheck summary, version note, upload action, and preview history',
+  },
+  {
+    id: 'upload.permission-restricted',
+    recipeId: 'upload-game-restricted',
+    guideSection: 'Upload & publish',
+    publishInGuide: true,
+    purpose: 'account permission fallback for platform-dependent modules',
+  },
+  {
+    id: 'network.client-unreachable',
+    recipeId: 'network-diagnostics',
+    guideSection: 'FAQ / troubleshooting',
+    publishInGuide: true,
+    purpose: 'client HTTP and WS unreachable guidance',
+  },
+  {
+    id: 'subpackage.collect-ready',
+    recipeId: 'subpackage-collect',
+    guideSection: 'Performance optimization',
+    publishInGuide: false,
+    purpose: 'non-Unity subpackage collection prerequisites and flow',
+  },
+  {
+    id: 'wasm.prepare',
+    recipeId: 'wasm-split',
+    guideSection: 'Performance optimization',
+    publishInGuide: false,
+    purpose: 'Unity Wasm split prerequisites and flow',
+  },
+];
+
+export const defaultLocalStorage = {
+  TTMG_DOCS_CAPTURE: '1',
+};
+
+const desktopViewport = { width: 1440, height: 1200 };
+const tallViewport = { width: 1440, height: 1600 };
+
+const zhFaqs = [
+  {
+    question: '扫码后没有连接上怎么办？',
+    answer: [
+      '先确认手机和电脑在同一网络，TikTok 页面停留在调试加载页。',
+      '如果公司网络、VPN 或代理比较复杂，可以进入网络诊断查看 HTTP 与 WS 链路。',
+      '仍然无法自动连接时，使用手动指定客户端地址填写 Client IP、HTTP 端口和 WS 端口。',
+    ],
+  },
+  {
+    question: '为什么项目概览没有平台配置？',
+    answer: [
+      '通常是当前账号没有目标游戏的开发权限，或本地终端代理没有正确生效。',
+      '先确认 `ttmg login` 使用的是目标游戏的开发者账号。',
+      '如果账号没问题，再检查 CLI 代理配置和公司网络访问。',
+    ],
+  },
+  {
+    question: '什么时候需要看上传发布？',
+    answer: [
+      '准备生成预览版本、测试构建结果或提交平台审核前，都应该先看上传发布。',
+      '这里会集中展示包体、配置、API 与性能预检结果，并提供上传后的预览版本记录。',
+    ],
+  },
+  {
+    question: 'Trust Domain 没拉到或平台配置为空时怎么办？',
+    answer: [
+      '先区分账号权限和终端代理：没有游戏权限时需要去开发者平台申请权限；账号有权限但配置为空时，多半是终端代理或公司网络没有生效。',
+      '确认代理后重新运行 `ttmg dev`，再回到项目概览检查 Trust Domain、Terms URL 和 Privacy URL。',
+    ],
+  },
+  {
+    question: 'Unity 和非 Unity 的分包能力有什么区别？',
+    answer: [
+      '非 Unity 小游戏使用“子包收集”采集启动阶段预下载的子包；Unity 小游戏使用 Wasm 分包链路。',
+      'Unity 由于 wasmcode 形态暂不能完整预先检查，当前仍需要继续调研并关注页面里的 Wasm Code Split 提示。',
+    ],
+  },
+];
+
+const enFaqs = [
+  {
+    question: 'What should I do if scanning the QR code does not connect?',
+    answer: [
+      'Make sure the phone and computer are on the same network and TikTok stays on the debug loading page.',
+      'If your office network, VPN, or proxy is complex, open Network diagnostics to inspect HTTP and WS connectivity.',
+      'If automatic connection still fails, use manual client address setup with Client IP, HTTP port, and WS port.',
+    ],
+  },
+  {
+    question: 'Why is platform configuration missing in Project Overview?',
+    answer: [
+      'The usual causes are missing developer permission for the target game or a terminal proxy that is not active.',
+      'First confirm that `ttmg login` uses the developer account for the target game.',
+      'If the account is correct, check CLI proxy configuration and company network access.',
+    ],
+  },
+  {
+    question: 'When should I use Upload & Publish?',
+    answer: [
+      'Use it before generating a preview build, validating a build result, or submitting to platform review.',
+      'It centralizes package, configuration, API, and performance prechecks, then keeps preview-build records after upload.',
+    ],
+  },
+  {
+    question: 'What should I do if Trust Domain or platform configuration is missing?',
+    answer: [
+      'Separate permission issues from terminal proxy issues first. Missing game permission should be fixed in the developer platform. Empty configuration with the right account usually means the terminal proxy or company network is not active.',
+      'After fixing the proxy, rerun `ttmg dev` and check Trust Domain, Terms URL, and Privacy URL in Project Overview again.',
+    ],
+  },
+  {
+    question: 'How are Unity and non-Unity subpackage flows different?',
+    answer: [
+      'Non-Unity mini-games use Subpackage Collection to collect subpackages downloaded during startup. Unity mini-games use the Wasm Split flow.',
+      'Because Unity uses wasmcode, full precheck is not available yet and still needs investigation. Watch the Wasm Code Split prompts on the page.',
+    ],
+  },
+];
+
+export const guideFaqs = {
+  'zh-CN': zhFaqs,
+  'en-US': enFaqs,
+};
+
+export const guideSections = {
+  'zh-CN': [
+    '开始之前',
+    '开始调试',
+    '项目概览',
+    '接入助手',
+    '上传发布',
+    '网络诊断',
+    '性能优化',
+  ],
+  'en-US': [
+    'Before you start',
+    'Start debugging',
+    'Project overview',
+    'Integration assistant',
+    'Upload & publish',
+    'Network diagnostics',
+    'Performance optimization',
+  ],
+};
+
+function notes(zh, en) {
+  return {
+    'zh-CN': zh,
+    'en-US': en,
+  };
+}
+
+function recipe(config) {
+  return {
+    captureMode: 'fullPage',
+    capture: {
+      selector: config.selector,
+      viewport: config.viewport || desktopViewport,
+      mode: 'fullPage',
+    },
+    waitFor: {
+      selector: config.selector,
+      timeoutMs: config.timeoutMs || 20000,
+    },
+    privacy: {
+      masks: [
+        'account avatar',
+        'developer email',
+        'session token',
+        'preview QR payload',
+      ],
+    },
+    updatePolicy: {
+      owner: 'DevTool',
+      refreshWhen: [
+        'page layout changes',
+        'core workflow copy changes',
+        'permission or network state changes',
+      ],
+    },
+    ...config,
+  };
+}
+
+export const recipes = [
+  recipe({
+    id: 'home',
+    title: 'Start debugging QR code',
+    page: 'Start Debugging',
+    productArea: 'debug',
+    route: '/?docMode=1&docScenario=start-debug.qr-idle',
+    selector: '[data-doc-shot="start-debug-qr-idle"]',
+    fixture: {
+      kind: 'local',
+      scenario: 'node-connected-device-disconnected',
+      required: ['localNodeConfig', 'qrCode'],
+    },
+    doc: {
+      section: 'Start debugging',
+      anchor: 'start-debugging',
+      intent: 'show launch mode selection and QR entry',
+    },
+    acceptance: [
+      'status banner shows local Node service state',
+      'QR card is visible without page scroll pressure',
+      'remote debug and client preview mode switch is clear',
+    ],
+    notes: notes(
+      {
+        title: '开始调试',
+        purpose: '从本地 Node 调试服务生成二维码，让 TikTok 客户端扫码进入调试或真机预览。',
+        whenToUse: '第一次启动项目、切换设备、验证远程调试或真机预览时使用。',
+        steps: [
+          '确认本地调试服务已启动。',
+          '选择需要的启动模式。',
+          '用 TikTok 客户端扫码进入游戏。',
+        ],
+        keyChecks: [
+          '二维码下方的远程调试 / 真机预览选择是否符合当前目标。',
+          '扫码无响应时是否能进入网络诊断。',
+        ],
+      },
+      {
+        title: 'Start Debugging',
+        purpose: 'Generate a QR code from the local Node debugging service so the TikTok client can open debugging or device preview.',
+        whenToUse: 'Use it when starting a project, switching devices, or validating remote debugging and device preview.',
+        steps: [
+          'Confirm that the local debugging service is running.',
+          'Select the launch mode you need.',
+          'Scan the QR code with the TikTok client to open the game.',
+        ],
+        keyChecks: [
+          'Remote debug and client preview options match the current goal.',
+          'Network diagnostics is reachable when scanning does not respond.',
+        ],
+      },
+    ),
+  }),
+  recipe({
+    id: 'launch-mode',
+    title: 'Launch mode configuration',
+    page: 'Launch Mode',
+    productArea: 'debug',
+    route: '/launch_mode?docMode=1&docScenario=launch-mode.default',
+    selector: '.launch-mode-page',
+    fixture: {
+      kind: 'local',
+      scenario: 'default-launch-mode',
+      required: ['launchModeList', 'packageList', 'sceneList'],
+    },
+    doc: {
+      section: 'Start debugging',
+      anchor: 'launch-mode',
+      intent: 'configure package, scene and startup parameters before scanning',
+    },
+    acceptance: [
+      'current mode and custom mode are visually separated',
+      'required fields are scannable',
+      'primary action does not dominate the form',
+    ],
+    notes: notes(
+      {
+        title: '启动模式',
+        purpose: '配置启动包、进入场景和启动参数，保证扫码后进入预期游戏状态。',
+        whenToUse: '需要复现指定入口、投流参数、分包路径或测试场景时使用。',
+        steps: [
+          '选择已有启动模式，或创建一个新的自定义模式。',
+          '补充启动包、进入场景和启动参数。',
+          '保存后回到开始调试页扫码。',
+        ],
+        keyChecks: [
+          '启动包是否与测试目标一致。',
+          '进入场景和启动参数是否覆盖本次调试 case。',
+        ],
+      },
+      {
+        title: 'Launch Mode',
+        purpose: 'Configure package, entry scene, and launch parameters so scanning opens the expected game state.',
+        whenToUse: 'Use it to reproduce a specific entry, campaign parameter, subpackage path, or test scenario.',
+        steps: [
+          'Select an existing launch mode or create a custom one.',
+          'Fill in package, entry scene, and launch parameters.',
+          'Save it and return to Start Debugging to scan.',
+        ],
+        keyChecks: [
+          'The launch package matches the target scenario.',
+          'Entry scene and launch parameters cover the test case.',
+        ],
+      },
+    ),
+  }),
+  recipe({
+    id: 'project-detail',
+    title: 'Project overview',
+    page: 'Project Overview',
+    productArea: 'project',
+    route: '/project_overview?docMode=1&docScenario=project.ready',
+    selector: '[data-doc-shot="project-ready"]',
+    viewport: tallViewport,
+    capture: {
+      selector: '[data-doc-shot="project-ready"]',
+      viewport: tallViewport,
+      mode: 'fullPage',
+    },
+    fixture: {
+      kind: 'platform',
+      scenario: 'permissioned-project-with-partial-platform-config',
+      required: ['gameDetail', 'packageSize', 'trustDomain', 'termsPrivacy'],
+    },
+    doc: {
+      section: 'Project overview',
+      anchor: 'project-overview',
+      intent: 'show project metadata and platform configuration health',
+    },
+    acceptance: [
+      'basic information, package status and platform configuration use the same section rhythm',
+      'missing platform configuration is shown as actionable guidance',
+      'network proxy and permission states are distinguishable',
+    ],
+    notes: notes(
+      {
+        title: '项目概览',
+        purpose: '核对项目基础信息、包体状态、信任域名、用户协议和隐私政策。',
+        whenToUse: '上传发布前、能力调试异常或怀疑平台配置缺失时使用。',
+        steps: [
+          '确认基础信息和 Client Key 是否匹配当前项目。',
+          '查看包体大小是否超限。',
+          '检查 Trust Domain、Terms URL 和 Privacy URL 是否齐全。',
+        ],
+        keyChecks: [
+          '账号无权限和终端代理异常需要给出不同提示。',
+          '缺失配置要说明影响和下一步补齐方式。',
+        ],
+      },
+      {
+        title: 'Project Overview',
+        purpose: 'Check project metadata, package status, trusted domains, Terms URL, and Privacy URL.',
+        whenToUse: 'Use it before upload, when capability debugging fails, or when platform configuration may be missing.',
+        steps: [
+          'Confirm that project metadata and Client Key match the current project.',
+          'Check whether package size exceeds limits.',
+          'Verify Trust Domain, Terms URL, and Privacy URL.',
+        ],
+        keyChecks: [
+          'Missing permission and terminal proxy issues use different guidance.',
+          'Missing configuration explains impact and next action.',
+        ],
+      },
+    ),
+  }),
+  recipe({
+    id: 'integration-assistant-map',
+    title: 'Integration assistant overview',
+    page: 'Integration Assistant',
+    productArea: 'capability',
+    route: '/integration_assistant?docMode=1&docScenario=integration.map',
+    selector: '.ia-page',
+    viewport: tallViewport,
+    capture: {
+      selector: '.ia-page',
+      viewport: tallViewport,
+      mode: 'fullPage',
+    },
+    fixture: {
+      kind: 'static',
+      scenario: 'capability-map',
+      required: ['monetizationModes', 'capabilitySections'],
+    },
+    doc: {
+      section: 'Integration assistant',
+      anchor: 'integration-assistant',
+      intent: 'explain capability grouping and business model selection',
+    },
+    acceptance: [
+      'monetization mode cards are lighter than primary task buttons',
+      'expand actions are low-pressure secondary controls',
+      'capability grouping is scannable without dense blue emphasis',
+    ],
+    notes: notes(
+      {
+        title: '接入助手',
+        purpose: '按变现模式和能力类别给出接入建议，帮助判断当前项目应该先接哪些能力。',
+        whenToUse: '规划登录、授权、广告、支付、分享、复访等能力接入时使用。',
+        steps: [
+          '先选择更接近当前项目的变现模式。',
+          '查看必接、推荐和配套能力。',
+          '进入具体能力详情确认调试路径。',
+        ],
+        keyChecks: [
+          '按钮视觉不能压过内容层级。',
+          '能力文案需要说明为什么接，而不是只列 API。',
+        ],
+      },
+      {
+        title: 'Integration Assistant',
+        purpose: 'Recommend capabilities by monetization model and capability group so teams know what to integrate first.',
+        whenToUse: 'Use it when planning login, authorization, ads, payment, sharing, revisit, or other capability work.',
+        steps: [
+          'Choose the monetization model closest to the current game.',
+          'Review required, recommended, and supporting capabilities.',
+          'Open a capability detail page to confirm the debugging path.',
+        ],
+        keyChecks: [
+          'Buttons do not visually overpower the content hierarchy.',
+          'Capability copy explains why to integrate, not only which API to call.',
+        ],
+      },
+    ),
+  }),
+  recipe({
+    id: 'upload-publish',
+    title: 'Upload and publish',
+    page: 'Upload & Publish',
+    productArea: 'release',
+    route: '/upload_publish?docMode=1&docScenario=upload.precheck',
+    selector: '.upload-game-page',
+    viewport: tallViewport,
+    capture: {
+      selector: '.upload-game-page',
+      viewport: tallViewport,
+      mode: 'fullPage',
+    },
+    fixture: {
+      kind: 'hybrid',
+      scenario: 'precheck-warning-upload-ready',
+      required: ['precheckSummary', 'uploadPermission', 'previewHistory'],
+    },
+    doc: {
+      section: 'Upload & publish',
+      anchor: 'upload-publish',
+      intent: 'show precheck, version note and preview build history',
+    },
+    acceptance: [
+      'precheck warning is above the workflow, not buried inside the form',
+      'upload action is a clear primary task but not oversized',
+      'version note and preview records are separate modules',
+    ],
+    notes: notes(
+      {
+        title: '上传发布',
+        purpose: '在上传前集中处理代码预检、版本说明、上传动作和预览版本记录。',
+        whenToUse: '准备生成平台预览版本或提审前验证构建结果时使用。',
+        steps: [
+          '先查看预检提示和关键摘要。',
+          '展开详情处理阻塞项。',
+          '填写版本说明后上传至平台。',
+          '上传完成后在预览版本记录中继续扫码验证。',
+        ],
+        keyChecks: [
+          '性能类风险如果顶部已经提示，详情区避免重复制造压力。',
+          '分割线和重边框不应打断主流程。',
+        ],
+      },
+      {
+        title: 'Upload & Publish',
+        purpose: 'Handle code precheck, version note, upload action, and preview-build records before release.',
+        whenToUse: 'Use it before generating a platform preview build or validating a build before review.',
+        steps: [
+          'Review the precheck prompt and key summary first.',
+          'Expand details to resolve blockers.',
+          'Enter a version note and upload to the platform.',
+          'After upload, continue validation from preview-build records.',
+        ],
+        keyChecks: [
+          'Performance risks are not repeated heavily when already shown in the top summary.',
+          'Dividers and heavy borders do not interrupt the main workflow.',
+        ],
+      },
+    ),
+  }),
+  recipe({
+    id: 'upload-game-restricted',
+    title: 'Upload restricted state',
+    page: 'Upload & Publish',
+    productArea: 'release',
+    route: '/upload_publish?docMode=1&docScenario=upload.permission-restricted',
+    selector: '.upload-game-page',
+    viewport: tallViewport,
+    capture: {
+      selector: '.upload-game-page',
+      viewport: tallViewport,
+      mode: 'fullPage',
+    },
+    fixture: {
+      kind: 'platform',
+      scenario: 'account-without-upload-permission',
+      required: ['gameDetailAccessState', 'uploadPermission'],
+    },
+    doc: {
+      section: 'Upload & publish',
+      anchor: 'upload-permission',
+      intent: 'explain how upload behaves when platform permission is missing',
+    },
+    acceptance: [
+      'permission issue uses warning color, not primary theme color',
+      'copy says the module cannot be operated, not merely cannot be viewed',
+      'recovery steps point to account and developer-platform permission',
+    ],
+    notes: notes(
+      {
+        title: '上传权限受限',
+        purpose: '说明当前账号没有目标游戏权限时，上传发布模块为什么不能继续操作。',
+        whenToUse: '账号能启动本地项目，但无法读取平台配置或执行上传发布时使用。',
+        steps: [
+          '确认 `ttmg login` 的账号是否属于目标游戏。',
+          '在开发者平台申请或补齐该游戏的开发权限。',
+          '权限开通后重新运行 `ttmg dev` 进入新会话。',
+        ],
+        keyChecks: [
+          '标题要表达“无法操作当前模块”。',
+          '提示需要说明这通常不是本地工程问题。',
+        ],
+      },
+      {
+        title: 'Upload Permission Restricted',
+        purpose: 'Explain why Upload & Publish cannot continue when the current account lacks permission for the target game.',
+        whenToUse: 'Use it when the local project can start but platform configuration or upload actions are blocked.',
+        steps: [
+          'Confirm whether the `ttmg login` account belongs to the target game.',
+          'Request or restore developer permission for the game in the developer platform.',
+          'After permission is granted, rerun `ttmg dev` to start a new session.',
+        ],
+        keyChecks: [
+          'The title says the module cannot be operated.',
+          'The guidance explains that this is usually not a local project issue.',
+        ],
+      },
+    ),
+  }),
+  recipe({
+    id: 'network-diagnostics',
+    title: 'Network diagnostics',
+    page: 'Network Diagnostics',
+    productArea: 'debug',
+    route: '/network_diagnostics?docMode=1&docScenario=network.client-unreachable',
+    selector: '.check-network-container',
+    viewport: tallViewport,
+    capture: {
+      selector: '.check-network-container',
+      viewport: tallViewport,
+      mode: 'fullPage',
+    },
+    fixture: {
+      kind: 'runtime',
+      scenario: 'client-http-and-ws-unreachable',
+      required: ['nodeStatus', 'clientAddress', 'connectivityResults'],
+    },
+    doc: {
+      section: 'Network diagnostics',
+      anchor: 'network-diagnostics',
+      intent: 'guide developers when QR scan stalls or client connection fails',
+    },
+    acceptance: [
+      'current conclusion comes before raw link evidence',
+      'manual address entry is a separate action, not a long inline form',
+      'proxy-to-computer-network suggestion is visible for hard network cases',
+    ],
+    notes: notes(
+      {
+        title: '网络诊断',
+        purpose: '定位扫码卡住、连接失败、HTTP/WS 端口不可达等本地网络问题。',
+        whenToUse: '扫码没有返回客户端地址、远程调试连不上或多网卡/VPN 环境复杂时使用。',
+        steps: [
+          '先看当前结论，确认问题发生在本机、客户端还是二者之间。',
+          '按建议处理网络、VPN、代理、防火墙或端口监听问题。',
+          '必要时手动填写客户端地址并重新检测。',
+        ],
+        keyChecks: [
+          '检测结果要保留证据，但不能压过处理建议。',
+          '实在连不上时提示可将手机网络代理到电脑网络后再扫码。',
+        ],
+      },
+      {
+        title: 'Network Diagnostics',
+        purpose: 'Diagnose local network issues such as stalled scanning, connection failure, and unreachable HTTP or WS ports.',
+        whenToUse: 'Use it when scanning does not return a client address, remote debugging cannot connect, or VPN / multi-network setup is complex.',
+        steps: [
+          'Read the current conclusion first to locate whether the issue is on the computer, client, or path between them.',
+          'Follow the suggestion for network, VPN, proxy, firewall, or port listener issues.',
+          'Enter the client address manually and rerun detection when needed.',
+        ],
+        keyChecks: [
+          'Raw detection evidence remains available without overwhelming the guidance.',
+          'For hard network cases, suggest proxying the phone network to the computer network and scanning again.',
+        ],
+      },
+    ),
+  }),
+  recipe({
+    id: 'subpackage-collect',
+    title: 'Subpackage collection',
+    page: 'Subpackage Collection',
+    productArea: 'performance',
+    route: '/subpackage_collect?docMode=1&docScenario=subpackage.collect-ready',
+    selector: '.subpkg-page',
+    viewport: tallViewport,
+    capture: {
+      selector: '.subpkg-page',
+      viewport: tallViewport,
+      mode: 'fullPage',
+    },
+    fixture: {
+      kind: 'runtime',
+      scenario: 'non-unity-game-collect-ready',
+      required: ['subpackageEntries', 'clientVersion', 'tiktokRegion'],
+    },
+    doc: {
+      section: 'Performance optimization',
+      anchor: 'subpackage-collection',
+      intent: 'collect startup subpackages for preload configuration',
+    },
+    acceptance: [
+      'Unity projects do not show the collection operation area',
+      'requirements mention non-US TikTok account and client support version',
+      'collection status and upload progress stay in the same state module',
+    ],
+    notes: notes(
+      {
+        title: '子包收集',
+        purpose: '采集启动阶段被预下载的子包，并转换为预加载配置。',
+        whenToUse: '非 Unity 小游戏需要优化首屏冷启动、沉淀预加载配置时使用。',
+        steps: [
+          '确认 TikTok 客户端版本和账号地区满足要求。',
+          '扫码后按真实启动路径操作游戏。',
+          '进入可交互后触发 `reportScene({sceneId:9999})` 完成收集。',
+        ],
+        keyChecks: [
+          'US 账号无法收集函数，需要直接提示。',
+          'Unity 小游戏不支持该收集链路。',
+        ],
+      },
+      {
+        title: 'Subpackage Collection',
+        purpose: 'Collect subpackages downloaded during startup and convert them into preload configuration.',
+        whenToUse: 'Use it for non-Unity mini-games that need to optimize cold start and generate preload configuration.',
+        steps: [
+          'Confirm that the TikTok client version and account region meet the requirement.',
+          'Scan and operate the game through the real startup path.',
+          'After the game becomes interactive, call `reportScene({sceneId:9999})` to finish collection.',
+        ],
+        keyChecks: [
+          'US accounts cannot collect functions and must be called out directly.',
+          'Unity mini-games are not supported by this collection flow.',
+        ],
+      },
+    ),
+  }),
+  recipe({
+    id: 'wasm-split',
+    title: 'Wasm split',
+    page: 'Wasm Split',
+    productArea: 'performance',
+    route: '/wasm_split?docMode=1&docScenario=wasm.prepare',
+    selector: '.tt-wasm-split-page',
+    viewport: tallViewport,
+    capture: {
+      selector: '.tt-wasm-split-page',
+      viewport: tallViewport,
+      mode: 'fullPage',
+    },
+    fixture: {
+      kind: 'local',
+      scenario: 'unity-wasm-split-ready',
+      required: ['unityPluginVersion', 'wasmArchive', 'collectResult'],
+    },
+    doc: {
+      section: 'Performance optimization',
+      anchor: 'wasm-split',
+      intent: 'split Unity Wasm code into load-on-demand subpackages',
+    },
+    acceptance: [
+      'requirements are above the main workflow',
+      'Unity plugin update is visible as a prerequisite',
+      'collection and split stages are visually distinct',
+    ],
+    notes: notes(
+      {
+        title: 'Wasm 分包',
+        purpose: '将 Unity Wasm 代码拆成按需加载的子包，降低首屏体积。',
+        whenToUse: 'Unity 小游戏需要优化冷启动或 Wasm 函数数量过多时使用。',
+        steps: [
+          '先更新 Unity 最新插件。',
+          '按页面要求完成函数收集。',
+          '生成分包配置后写回项目。',
+        ],
+        keyChecks: [
+          'Unity 由于 wasmcode 形态暂不能完整预先检查，需要继续调研。',
+          '插件版本、客户端版本和入口配置要作为前置条件展示。',
+        ],
+      },
+      {
+        title: 'Wasm Split',
+        purpose: 'Split Unity Wasm code into on-demand subpackages to reduce first-screen size.',
+        whenToUse: 'Use it when Unity mini-games need cold-start optimization or have too many Wasm functions.',
+        steps: [
+          'Update to the latest Unity plugin first.',
+          'Complete function collection as required on the page.',
+          'Generate subpackage configuration and write it back to the project.',
+        ],
+        keyChecks: [
+          'Unity wasmcode cannot be fully prechecked yet and still needs investigation.',
+          'Plugin version, client version, and entry configuration are visible prerequisites.',
+        ],
+      },
+    ),
+  }),
+];