@ttmg/cli 0.4.6-vibe-beta.22 → 0.4.6-vibe-beta.23

package/CHANGELOG.md

@@ -0,0 +1,516 @@
+## 0.4.6-vibe-beta.23
+
+- `upload --vibe` 每次创建上传任务前独立生成新的请求幂等 ID；保留同一游戏的 `source_project_id`，后续轮询和素材上传只使用本次平台返回的 `task_id`。
+- `upload --vibe --format ndjson` 到达扫码授权时，向 stderr 输出 `page: <url>`；stdout 仍保持纯 NDJSON，方便 Skill 将事件写入文件后让开发者在控制台找到二维码页。
+- `upload --vibe --verbose` 向 stderr 输出脱敏后的 HTTP 请求、响应和错误诊断，覆盖创建任务、授权轮询、素材上传和预览轮询，便于核对每次请求的幂等 ID 与后端返回的任务 ID。
+
+## 0.4.6-vibe-beta.17
+
+- `upload --vibe` 改用 Agent Detail 查询接口。上传后保留任务凭据并继续轮询，拿到有效 `preview_url` 后在原页面显示游戏预览二维码，返回游戏、代码版本和预览记录标识。
+- 新增 `waiting_preview` 进度状态和 `previewReady` 字段，终态继续使用 `uploaded`。等待超时、取消或查询失败保留 `uploaded=true`，提示检查任务，不重新上传。Mock 保持原模拟上传行为。
+- 统一扫码、上传、预览和失败状态的页面布局：整块内容居中，头像与游戏名同排，描述和分类逐行展示字段和值；预览就绪后所有步骤显示完成状态。
+
+## 0.4.6-vibe-beta.16
+
+- `upload --vibe` 开放手机 TikTok 扫码授权上传，二维码直接使用后端 `landing_url`。PPE 测试素材已完成真实手机授权、头像／应用资料／代码包上传，命令退出 0。
+- 关闭 `--web`，旧调用在创建任务前返回 `VIBE_WEB_DISABLED`；`auth open` 改为重开同一任务的二维码页，网页授权跳转关闭。保留原有描述、分类、资料默认值、目录／ZIP、预检、工程绑定和结构化进度。
+- 扫码、上传和结果页面改为全页居中，去掉顶部品牌栏与卡片，展示本次实际提交的标题、头像、描述、类型和子类型。后台查询仅更新变化内容，完成后停止，不再整页刷新。
+
+## 0.4.6-vibe-beta.15
+
+- Vibe 上传默认描述改为 `Discover the fun of TikTok Mini Games.`；新增可选 `--description` 供 Skill 覆盖。省略时保留旧资料文件描述或使用默认值，空白和无效 Unicode 输入在创建任务前报错。结构化输出返回实际描述及来源。
+- 更新 Quick Start，串联能力查询、分类选择、可选描述、网页授权和上传结果判断。
+
+## 0.4.6-agent-beta.3
+
+- 新增 `ttmg wasm collect start`，CLI 复用本机登录态开启采集窗口；默认保留已有采集，`--reset` 清空当前游戏与 Wasm 的历史函数 ID。
+- 新增 `ttmg wasm collect export`，校验原始 Wasm 后导出 `collection.json`，可直接交给 `ttmg wasm split --collection`；Agent 无需读取 Cookie 或调用 DevTool 本地路由。
+
+## 0.4.6-vibe-beta.14
+
+- 新增离线只读的 `ttmg game categories --format json`，返回游戏类型、子类型与玩法说明，可按类型筛选。Vibe 上传支持成对的 `--category / --subcategory`，校验后覆盖分类；均不传保留 Other/Other，旧资料文件保持原行为。预检与终态返回实际分类和来源，无效组合在创建任务前失败。
+
+- 统一 Web 上传的 Skill 入口：能力查询首选 `--vibe --web`，帮助和中英文指南写清默认资料、授权链接、原进程轮询、自动上传及终态判断；Mock 作为独立演示模式说明。npm 包包含 `vibe-upload.md`，PPE 真实验证与正式环境验证分开标注。
+
+## 0.4.6-vibe-beta.13
+
+- 将 PPE 试用默认资料中的服务条款和隐私政策链接更新为 `https://www.tiktok.com`。
+
+## 0.4.6-vibe-beta.11
+
+- 修复 beta.10 只传标题和头像 URI 导致基础信息提交被拒绝的问题：CLI 自动带上此前跑通的 PPE 试用资料默认值，用户仍只提供标题和头像；输入要求中的资料来源更正为 `cli-defaults`。
+
+## 0.4.6-vibe-beta.10
+
+- 修正 Vibe 上传对 Skill 的资料要求：只向用户收集标题和头像，其他应用资料由平台默认处理。能力查询和上传事件返回明确的输入要求，帮助与示例不再引导填写完整资料；旧 `--app-info` 仅保留兼容。
+
+## 0.4.6-vibe-beta.9
+
+- 修复真实素材上传成功后 CLI 进程未退出的问题：终态后清理本次操作持有的上传连接，保留结果页。
+- 修复 `upload --vibe --web` 在网页授权就绪后错误停止的问题：CLI 继续使用同一任务上传头像、提交应用信息和上传代码包，根据后端回执返回结果；失败不自动重传或降级模拟，原 Mock 链路不变。
+
+## 0.4.6-vibe-beta.8
+
+- 新增真实网页授权入口，内置 PPE 创建任务后打开系统浏览器，持续查询真实授权状态；浏览器打开失败可复用原任务重试。
+- 已知问题：授权就绪后仍错误返回 `VIBE_REAL_UPLOAD_NOT_READY`，未继续上传。已在 `0.4.6-vibe-beta.9` 修复。
+
+## 0.4.6-agent-beta.2
+- 新增 `ttmg auth open --page-url <pageUrl>`，供 Skill 在系统浏览器打开已有 Vibe 任务的网页授权入口。复用原任务，原上传进程继续轮询；过期或已结束页面明确报错，任务凭证不进入命令参数和结构化输出。
+- 修复真机调试后，日志、截图和旧构建被带入普通编译及上传、导致包体积统计失真的问题。
+- 自定义调试记录可保存在工程外或根目录 `.ttmg` 下；放入游戏资源目录时会在启动前提示调整路径。
+
+## 0.4.6-agent-beta.1
+
+- 新增真机扫码页，展示编译、设备连接、上传进度、下发结果和当前更新的 request-id。
+- 支持后台预览、手动更新，以及通过命令获取当前截图和会话日志。
+- 开发者选项支持保存并重新加载，修改配置后可重试加载失败的游戏。
+- 新增 Wasm 插桩与分包命令，提供 Linux 原生依赖。
+- 修复已有调试记录时再次启动预览失败的问题。
+
+**1. 启动并扫码**
+
+在已转换的 Native 小游戏目录运行，使用已有 Client Key、支持日志和截图的 TikTok 测试包。手机与执行机须双向网络可达，采集期间保持游戏前台。
+
+```bash
+ttmg dev --mode client-preview --update-mode manual --background \
+  --client-key <CLIENT_KEY> --record-logs --timeout 14400 --format json
+```
+
+保存返回的 `sessionId`，后文 `<SESSION_ID>` 均使用它。打开 `launch.scanPageUrl`，在电脑页面配置选项并用手机扫码；远程执行时，可读取 `launch.qrPngPath` 展示二维码。示例会话保留 4 小时，命令返回后后台进程继续运行。
+
+**2. 修改代码并验证这一轮更新**
+
+```bash
+ttmg dev sync --session <SESSION_ID> --request-id round-1 --format json
+ttmg dev observe --session <SESSION_ID> --iteration round-1 --format json
+```
+
+`request-id` 由 Agent 生成，`sync` 返回对应的 `iterationId` 和 `buildId`，扫码页显示当前轮次。**同一轮重试复用 ID，新代码使用新 ID**。`observe` 等待该轮下发，并采集有限日志和截图；返回 `pending` 时继续查询，`needs_action` 时按提示连接手机，`partial` 时查看 `issues`。包下发完成不等于游戏运行正常，需检查画面和日志。
+
+**3. 随时获取当前截图和日志**
+
+```bash
+ttmg dev capture --session <SESSION_ID> --format json
+```
+
+不修改代码、不需要 request-id。命令截取当前画面，并自动分页导出当前 Runtime 会话中手机仍保留的日志，区间固定到本次查询时刻。
+
+- `screenshot.path`：Agent 读取该图片文件。截图失败时查看 `issues`。
+- `logs.path`：Agent 读取 NDJSON 日志，按 `severity` 区分 info / warn / error。
+- `manifest`：本次采集记录。`runtimeSessionId` 用于核对截图和日志所属设备会话。
+- `logs.complete`：本次日志区间是否完整。`false` 时查看 `issues` 和 `nextQuery`，不要直接当成全部日志。
+
+**路径均位于 CLI 执行机，不是下载 URL。** 同机 Agent 直接读取；远程 Agent 通过已有文件通道取回。扫码页当前只展示连接、上传和配置，日志及截图通过上述命令获取。
+
+采集默认最多 120 秒、64 MiB。未取完时，将 `nextQuery` 的参数传给 `dev logs` 续读，保留相同 Runtime 和 `until`；再按返回的 `cursor.hasMore` 与 `nextQuery` 继续：
+
+```bash
+ttmg dev logs --session <SESSION_ID> --runtime-session <RUNTIME_ID> \
+  --after <AFTER> --until <UNTIL> --limit 500 --format json
+```
+
+手机已清掉的旧日志无法补回。设备断开时先恢复连接；若 Runtime 会话已改变，重新采集，不复用旧游标。`capture` 退出码：成功 `0`、部分结果 `2`、失败 `1`；部分结果中已返回的文件仍可读取。
+
+**4. 单独读取、持续监听与结束**
+
+```bash
+# 单独截图 / 最近一页日志 / 持续监听 30 秒
+ttmg dev screenshot --session <SESSION_ID> --format json
+ttmg dev logs --session <SESSION_ID> --format json
+ttmg dev logs --session <SESSION_ID> --follow --timeout 30 --format ndjson
+
+# 读取启动时 --record-logs 留存在本机的日志，会话结束后仍可用
+ttmg dev logs --session <SESSION_ID> --source archive --format json
+
+# 结束预览
+ttmg dev session stop <SESSION_ID> --format json
+```
+
+`logs` 单次只读一页，`--follow` 不自动补齐全部历史；本地留存也有容量限制，长期保存需及时导出。
+
+**开发者选项**：支持域名校验、广告／内购模拟、vConsole 和开发者信息。连接前保存供启动使用；连接后点击“保存并重新加载”，重新初始化并按新配置下发当前游戏包。加载中再次保存会排队执行，复用当前构建与 request-id；页面区分等待、重新加载中、重新下发完成和失败。
+
+### 其他变更
+
+- 修复 Vibe 代码包上传返回 `code=0`、非空 `package_uri` 且任务仍为 `status=2` 时被误判失败的问题。保留失败、过期、未知状态和缺少回执的校验；上传完成不等待整个任务结束。
+- 修复上传结束后的迟到进度回调覆盖最终状态的问题，避免 Skill 已收到完成结果后又收到“上传中”。
+
+- 新增 Vibe `--app-info` 本地 JSON 入口，按最新 IDL 传递简介、分类、条款等应用信息；名称和头像 URI 仍由 CLI 填入，不接受文件覆盖。提供完整信息时，在创建任务前校验名称长度、头像格式、尺寸和大小。版权确认须显式提供，不自动补默认值。保留现有 `--mock` 用法和真实上传限制；本次完成本地契约接入，尚未验证真实素材上传。
+
+- Keep `upload --vibe --mock` as the single trial command, with no environment
+  setup. It now creates/queries real tasks in the built-in PPE lane, then simulates
+  authorization and material uploads. Unlike the previous offline Mock, it requires
+  backend access and reports `platformWrite: true` when task creation is attempted.
+  Simulation stays explicit and separate from real task status. Real request
+  failures remain failures; no materials are sent to PPE. PPE routing will be
+  removed in the production release, without a Skill environment-switch step.
+
+- Add explicit `TTMG_VIBE_BACKEND=ppe` plus `TTMG_VIBE_PPE` configuration for
+  real task creation, status polling and the client authorization QR. Never
+  fall back to Mock or production. Events mark real task creation as a platform
+  write. Upload stays blocked with `VIBE_REAL_UPLOAD_NOT_READY` until complete
+  app-info inputs are integrated; authorization is not reported as upload success.
+
+- Encode Vibe authorization QR codes as `aweme://webview?url=<encoded landing_url>`
+  to open the task landing page in the TikTok client. Keep credentials out of
+  structured output; backend task URLs and polling requests remain unchanged.
+
+- Upgrade the opt-in Vibe prototype to output schema `2`: task-based binding,
+  avatar upload, app-info submission and package upload share the same Mock/local
+  HTTP adapter contract. Finish at `uploaded`; remove preview/review output.
+  Add `terminal`, `nextAction`, `message`, `taskId` and `uploadStep` for Skills.
+  `TTMG_VIBE_BACKEND=mock` lets Skills keep backend selection outside the command.
+  Persist non-secret source identity in `.ttmg/vibe-project.json`; dry-run does
+  not create it. The old UUID endpoints and `--vibe-authorize-url` are retired.
+  Add icon/info failure cases, terminal failure pages, i64-safe requests and
+  credential-redaction tests. Real platform upload is not enabled or verified.
+
+- Compatibility change approved in the CLI design review: Native `ttmg build`
+  now performs a local debug build in text mode too, replacing its placeholder.
+  JSON schema 1 and platform side effects are unchanged. Neither format uploads.
+
+- Load the Unity Wasm native binding only for prepare/split operations. A missing
+  platform binary no longer prevents CLI startup or unrelated commands; this
+  change does not add Linux Wasm splitting support.
+
+- Frame the authorization page as “Publish to TikTok”: show the chosen local game icon and title, ask users to scan with TikTok, and explain that publishing continues after phone authorization. Keep upload-complete and review states distinct from going live.
+- Replace the Vibe diagnostic-looking page with a compact, single-language binding/upload/result card. The binding screen explicitly asks users to scan with TikTok and authorize before automatic upload; a game-preview QR appears only in the completed state. Keep Mock notices small but explicit.
+- Make `upload --vibe --mock` visibly auto-advance without backend or phone interaction: mock-specific instructions, staged upload progress and the final placeholder preview QR. Add `npm run demo:vibe` using temporary local fixtures and the real command.
+- Add opt-in `upload --vibe` local preparation, bounded authorization polling, automatic upload and two-purpose QR presentation. Existing Cookie/Client Key upload stays unchanged.
+- Add explicit in-memory Mock scenarios and a loopback-only HTTP adapter using a provisional three-endpoint contract. No real TikTok authorization, upload, review or release has been verified.
+- Add JSON/NDJSON lifecycle output, cancellation, dry-run, credential-safe errors and regression/process tests. Skill supplies metadata in conversation; no metadata form is added.
+
+## 0.1.0
+
+发布正式版本，支持 H5 小游戏和原生小游戏的初始化、开发调试和打包构建。支持 Windows 系统
+
+## 0.1.0-beta.1
+
+移除 Client WS 端口和 Http 端口默认 -1 的配置，变成通过和 Node CLI 通信显示发端口
+
+## 0.1.0-beta.8
+
+支持自动打开浏览器，且聚焦在 devTools 窗口
+
+## 0.1.0-beta.9
+
+1. 支持文件上传进度显示
+2. 支持自动打开浏览器调试模式
+
+## 0.1.0-beta.10
+
+fix: 修复还未完成新编译就直接上传了的问题
+
+## 0.1.0-beta.11
+
+feat: 先关闭自动上传能力
+
+## 0.1.0-beta.12
+
+feat: 支持文件变更监听，告知浏览器文件变更，提醒开发者重新加载游戏
+
+## 0.1.0-beta.13
+
+1. 支持 sourcemap
+2. 优化上传环节产物，过滤 sourcemap 文件，提高上传效率
+
+## 0.1.0-beta.14
+
+1. 修复 client key 未成功写入 mock meta 的问题，导致不一致
+
+## 0.1.0-beta.15
+
+1. 还原 open url 历史方法
+
+## 0.1.1
+
+发布最新版本，提醒开发者升级最新版本
+
+## 0.1.2
+
+发布最新版本，支持 sourcemap
+
+## 0.1.3-beta.1
+
+优化显示二维码问题
+
+## 0.1.3-beta.2
+
+彻底修复二维码兼容问题
+
+## 0.1.3-beta.3
+
+修复 sourcemap 错乱问题
+
+## 0.1.3-beta.4
+
+修复循环依赖问题
+
+## 0.1.3-beta.5
+
+修复监听文件变化报错问题
+
+## 0.1.3
+
+发布优化版本 CLI
+
+## 0.1.4
+
+优化页面交互
+
+## 0.1.5
+
+1.fix: 控制台报错问题 2. feat: 优化
+
+## 0.1.6
+
+1. 优化控制台报错日志
+2. 优化调试启动环节耗时
+
+## 0.1.7
+
+- 修复 Windows 调试资源加载失败问题
+
+## 0.1.8
+
+优化 DevTool 网页端启动时间
+
+## 0.1.9-beta.1
+
+发布测试版本，供客户端调试使用
+
+## 0.1.9-beta.2
+
+发布测试版本，用于 Windows 测试
+
+## 0.1.9
+
+发布正式版本，支持
+
+- login
+- 支持上传游戏包
+- 支持启动模式
+- 支持 Debug Settings
+
+## 0.2.0-beta.1
+
+发布测试版本，用于 Windows 测试 login 登录异常逻辑
+
+## 0.2.0
+
+发布正式版本，支持 Windows 登录加载报错提示
+
+## 0.2.1
+
+1. 移除项目详情部分，比较冗余，不常用，融合到代码预检中
+2. 打开调试页面地址增加 version 参数，来规避新老版本缓存问题和不同网页之间的隔离（未来支持）
+3. 优化登录失败提示，增加网络检查提示，并给出如何修改网络设置的文档链接
+4. 补充发送 meta 至客户端链路，增加调试链路日志信息，便于排查问题
+
+## 0.2.2
+
+1. 修复访问无权限的小游戏，顶部报错问题
+
+## 0.2.3
+
+优化扫码连接不上问题，支持手动绑定电脑本地 IP 地址
+
+## 0.2.4
+
+支持新的 DevTool 平台
+
+## 0.2.5
+
+1. 增加不在游戏根目录启动调试校验
+2. 支持手动绑定客户端 IP 地址和端口
+3. 调整启动模式中的场景列表表达文案
+4. 修复文件上传问题，避免偶现上传失败
+5. 支持展示游戏详情模块，支持开发者查看当前小游戏基本信息
+6. 支持调试环节消费平台配置的域名
+7. 升级 ttmg-pack 0.1.7，修复构建环节对开发者 JS 代码降级的问题
+8. 文档新增常见问题部分，替换原有的开发文档
+
+## 0.2.6
+
+修复启动模式中场景列表展示问题，重复展示默认启动模式
+
+## 0.2.7
+
+1. 升级 ttmg-pack 0.2.3，调整 esbuild 配置，目标 es2020
+2. 支持校验子包配置文件名是否符合规范，对于非法文件名，提示开发者修改
+3. 调整域名校验默认逻辑，默认开启，校验失败时，提示开发者修改
+
+## 0.2.8
+
+1. 升级 ttmg-pack 0.2.4，修复 open data context 文件丢失问题
+
+## 0.2.9
+
+1. 升级 ttmg-pack 0.2.5，修复 open data context 打包问题
+
+## 0.3.0
+
+新增/优化功能适用 TikTok 版本 iOS >=43.1 | Android>=43.1
+支持了开发信息蒙层，打开后可以查看游戏 FPS、设备信息、调试开关等信息，便于查看游戏运行状态 了解如何使用
+支持删除历史启动模式，便于管理历史启动模式
+调整调试设置模块名称为开发选项，和客户端内调开发者选项保持一致 了解如何使用
+调试设置新增定义 vConsole 和 开发信息浮层设置
+支持了变更日志，用户可以在调试环境下查看游戏的变更记录，部分新功能可通过更多信息查看使用
+支持了调试设置开关本地缓存，避免每次都需要重新设置
+修复上传名称为中文的游戏时，平台展示乱码的问题
+修复启动模式模块，自定义query 参数无法持久化的问题
+修复扫描二维码模块，内容过多，纵向无法滚动问题
+
+## 0.3.1
+
+- 支持 unity 小游戏本地一些列调试功能，如 Wasm 分包、包大小校验、一键上传代码包至平台等 了解如何使用
+- 增加用户登录过期的异常提示，提醒开发者重新登录
+- 优化上传代码包至平台功能，开发者只用添加描述后点击上传便可自动压缩当前目录下的代码包上传至开发者平台
+- 优化 ttmg login 终端网络代理异常导致无法登录的报错引导，提示用户检查网络设置
+
+## 0.3.2-beta.1
+
+支持 cocos 2.0 openDataContext 相关适配
+
+## 0.3.2
+
+- 小游戏详情查询升级到 TikTok DevPortal v4 `devtool/info` 接口，字段映射更完整
+- 支持一键打包当前目录并上传代码包到开发者平台；上传失败提示更明确，文件名非法字符自动处理
+- Unity Wasm 分包：更新 `game.json` 子包配置写入逻辑（兼容 `subpackages`/`subPackages` 字段），Android/iOS main/sub 配置去重合并
+- 启动校验增强：检查是否在小游戏根目录执行，并提示 `subPackages` 拼写错误
+  增加对 unity 是否需要分包的检查，对于需要分包的 unity 项目，给出明确提示
+  支持通过 `ttmg setup` 配置 CLI 语言，调试环境会跟随语言设置展示文案，首次调试时会自动同步默认语言，后续 CLI 与 IDE 语言保持一致，减少反复切换
+  调试与预检支持多语言展示，关键提示与校验信息更易理解
+  支持 Cocos 2.0 openDataContext 配置
+  变更记录新增提醒功能，当有新版本发布时，会通过弹窗提醒开发者更新
+  ttmg login 支持 ttmg login --verbose 参数，打印更多登录信息
+  API 预检建议文案统一收敛，避免重复提示，阅读更清晰
+  顶部区域透出项目预检错误与警告信息，便于开发者及时发现问题并修复
+  语言选择策略优化：优先使用 CLI 本地设置，未设置时自动回退浏览器语言
+  启动校验增强：检查是否在小游戏根目录执行，对于分包配置 subPackages 给出明确报错，引导开发者修改为 subpackages
+  修复项目详情中展示的主包大小限制和代码预检不一致的情况
+
+## 0.3.3
+
+升级 ttmg-pack 到 0.4.5，解决安卓无法调试 unity 项目问题
+
+## 0.3.4
+
+优化校验逻辑，给出提示
+
+## 0.3.5
+
+优化连接和代理，帮助开发者自助解决问题
+
+## 0.3.6
+
+修复分包过程超时问题
+
+## 0.3.7
+
+新增/优化功能适用 TikTok 版本 iOS >=43.1 | Android >=43.1
+
+1. 新增能力接入助手，帮助开发者基于小游戏变现类型获取关键能力的接入引导。
+2. 优化上传发布环节，将代码预检与代码上传整合为完整的上传发布流程。
+3. 扩充包体大小预检说明，补充整包、主包、独立分包限制规则与详细文档入口，便于开发者理解和处理包体超限问题。
+
+## 0.3.8
+
+修复 `ttmg login` 后接口鉴权异常的问题：
+
+1. 登录时把 `Set-Cookie` 响应头中的 `Path / Domain / Max-Age / Expires / Secure / HttpOnly / SameSite` 等属性被当成 cookie 拼接到 `Cookie` 字段，导致 CLI 发请求时把属性当成"假 cookie"一并带上。
+2. 同一域名下同名 cookie（例如服务端用 `Max-Age=0` 显式删除的占位 cookie）也会被一起发送，污染掉真正有效的同名 cookie，浏览器会自动过滤这种情况，CLI 不会，造成登录态接口异常。
+3. 修复后与浏览器行为保持一致：剥离 cookie 属性、过滤 `Max-Age<=0` 或 `Expires` 已过期的 cookie，仅保留 `name=value` 用于请求。
+4. 已登录用户无需重新登录，下次发起请求时会自动清洗 rc 中已存的脏数据。
+
+## 0.3.9
+
+本次主要优化调试 IDE 的视觉、交互与多语言一致性：
+
+1. 调试 IDE 默认使用浅色主题，暗色模式改为开发者手动开启并记忆选择，避免跟随系统强制进入暗色导致不适应。
+2. 优化暗色模式下二维码显示，调整背景避免过亮刺眼，同时保证扫码识别率。
+3. Wasm 分包页面及相关组件补齐多语言，修复此前页面文案中英文混排的问题。
+4. 能力接入助手页面视觉升级：变现模式卡片新增图标与强调色，关键能力标签按「必需 / 可选 / 实验」分级展示，信息层级更清晰。
+5. 完成扫码连接后，首页标题与说明文案会切换为「已连接」状态，状态反馈更明确。
+6. 新版本提示由红点改为「有更新」文字标签，含义更直观。
+7. 上传游戏包按钮配色与产品主题色统一。
+8. 修复多个页面中标题与正文内容未对齐的问题，整体排版更整齐。
+9. 文案细节调整：「身份与授权」更名为「登录与授权」；移除侧边栏冗余的「查看文档」入口。
+
+## 0.3.9-beta.1
+
+本次测试版本主要补充启动模式场景能力，并优化场景命名可理解性：
+
+1. 启动模式新增 `inbox` 场景，支持在调试链路中模拟消息入口启动小游戏。
+
+## 0.4.0
+
+修复游戏无开发权限时提示信息展示异常的问题，引导更准确。
+
+## 0.4.1
+
+优化上传代码包流程：
+
+1. 上传后的平台处理提示改为更易理解的文案，不再向开发者暴露平台内部状态码及 asset / ready 等技术字段，进度与失败原因表达更清晰。
+2. 重构上传成功卡片布局：二维码与版本信息分区展示并以分隔线区隔，新增成功状态标识，排版更紧凑协调。
+
+## 0.4.4-beta.1
+
+支持版本：TikTok iOS 46.0+、TikTok Android 45.9+。
+
+新增子包收集能力：通过真机预览记录启动阶段实际预下载的子包，并生成预加载配置，帮助减少后续资源加载等待。当前仅支持非 Unity 小游戏。
+
+使用指南：https://bytedance.my.larkoffice.com/docx/MIyMdmzb0oOQAKxNHGNmR5hDyAh
+
+## 0.4.4
+
+支持版本：TikTok iOS 46.0+、TikTok Android 45.9+。
+
+正式开放子包收集能力：通过真机预览记录启动阶段实际预下载的子包，并生成预加载配置，帮助减少后续资源加载等待。当前仅支持非 Unity 小游戏。
+
+子包收集使用指南：https://bytedance.my.larkoffice.com/docx/MIyMdmzb0oOQAKxNHGNmR5hDyAh
+
+修复部分企业网络使用非标准局域网网段时，可扫码地址被误判为不可用的问题。
+
+提升本地调试连接稳定性：启动阶段短暂断连会自动恢复，刷新调试页面后可继续使用已连接设备。
+
+## 0.4.5
+
+支持版本：TikTok iOS 46.0+、TikTok Android 45.9+。
+
+1. 优化调试会话信息展示：开发者选项以独立状态标签呈现，便于快速确认域名校验、vConsole 和开发信息面板的启用状态。
+2. 优化扫码网络异常提示：未检测到可用局域网地址时不再展示无效二维码，并引导设置连接地址。
+3. 修复子包收集页面在部分环境下无法打开的问题。
+
+## 0.4.6-vibe-beta.2
+
+1. `ttmg login --implicit` 支持 Agent 使用账号密码非交互登录；成功后继续按原逻辑写入 `~/.ttmgrc`，stdout 返回包含稳定 operation ID、状态和错误码的 JSON，不输出密码或会话 Cookie。
+2. 登录成功前校验可复用 Cookie，避免把缺少会话凭证的响应误报为成功。
+3. 新增 `ttmg test-account add`，输出测试账号授权链接、二维码文件和 Developer Portal 核对入口；命令本身不执行平台写入。
+4. `test-account` 支持 `--format json`，成功与失败使用相同结构化结果字段。
+5. `ttmg upload --preview` 支持等待平台处理并输出预览地址；JSON/NDJSON 会返回从预检、打包、上传、处理中到预览就绪或失败的结构化状态，平台数字枚举会归一化为可理解的 `pending`、`processing`、`success`、`failed` 等字符串。
+6. `ttmg dev` 增加兼容的 Agent 旁路：可关闭浏览器，选择输出单份 session manifest 或 NDJSON 生命周期事件流，并在本地保存原始启动链接、二维码文件和会话证据；两种 stdout 输出模式互斥，原有人工调试入口保持不变。
+7. 新增只读的 `ttmg check --format json`，复用现有项目配置、路径、包体、分包和 API 检查，返回稳定诊断码、位置、大小、帮助链接和可配置退出阈值；同一批标准化诊断会进入 Agent dev 的编译事件，默认人工文本输出不变。
+8. 新增只读的 `ttmg auth status --format json`，只返回本地会话是否可复用和脱敏账号信息；`--require-auth` 可用于 Agent 前置检查。
+9. `ttmg build --format json` 增加显式的本地结构化构建旁路，返回引擎、源码大小、各包摘要、产物目录、package manifest、耗时和标准化诊断；原 Native build 默认输出不变。
+10. 结构化 dev 支持 `--timeout`，并新增 `dev session list/inspect/events/stop`；events 可按 seq 增量读取，stop 只终止经过命令行校验的 `ttmg dev` PID，人工 dev 默认流程不变。
+11. 新增 `ttmg capabilities --format json`，供 Agent 在执行前发现已支持的结构化命令、平台写入边界及尚未实现的设备和 Runtime 能力。
+12. 新增只读 `ttmg doctor --format json`，检查 Node 版本、工程入口、本地登录和局域网地址，并只返回代理环境是否存在，不返回代理值或 Cookie。
+13. 复用现有 `reportScene({ sceneId: 9999 })` 可交互信号，增加 Runtime → DevTool IDE → CLI 的旁路转发和 `GAME_READY` 会话事件；只有收到该证据后 summary 才会写为 passed。真实设备联调完成前 capability 仍保持 `gameReady=false`，不改变原有调试页面消费该信号的逻辑。
+14. 新增只读 `ttmg check --ai --format json` option，在原 check 结果上静态检查 Agent 调试准备度；首项检查识别 `reportScene({ sceneId: 9999 })`、返回命中文件和有界扫描范围。默认 `ttmg check` 不变，静态通过不替代真机 GAME_READY。
+
+## 0.4.6-vibe-beta.3
+
+`ttmg upload` 和调试上传生成 ZIP 时排除项目根目录的 `.agent`、`.claude`、`.trae`，不上传 Agent 本地配置。
+
+## 0.4.6-vibe-beta.4
+
+1. `ttmg upload --preview --serve-preview-page` 在平台预览就绪后启动响应式本地页面，通过两个二维码和直接链接依次承接测试账号授权与预览启动。
+2. 页面 HTML 和二维码只驻留内存，不写入项目或磁盘；服务监听 `127.0.0.1`，页面有效期为 1 小时。到期后清除二维码并显示重新执行提示，提示再保留 1 小时后服务退出。
+3. 每次成功上传都会生成新的随机地址；同一个 Client Key 复用一个 localhost 服务，新地址立即替换旧页面并重置 1 小时有效期，不同 Client Key 使用独立服务。
+4. 默认文本模式打印浏览器展示信息并自动打开页面，`--no-open` 可关闭；JSON 和 NDJSON 增加 `purpose`、`presentation` 和 `latestOnly` 字段，明确 Agent 应使用浏览器打开，纯终端降级为可点击链接。
+5. 本地页面启动失败不会把已经成功的平台上传误报为失败。
+
+## 0.4.6-vibe-beta.5
+
+修正 Agent 目录名称：`ttmg upload` 和调试上传生成 ZIP 时排除项目根目录的 `.agents`、`.claude`、`.trae`；`.agent` 不在新增过滤范围内。

package/README.md

@@ -1,20 +1,12 @@
 ### @ttmg/cli
 
-`0.4.6-vibe-beta.22`：`--format ndjson` 扫码授权页就绪时，stderr 会输出一次 `page: <url>`；即使 Skill 将 stdout 保存为 `vibe.ndjson`，开发者仍能在控制台看到页面地址。授权、上传和双二维码预览流程与 beta.21 一致。
+`0.4.6-vibe-beta.17` 支持上传后扫码预览：`ttmg upload --vibe` 上传完成后继续查询同一任务，收到 `preview_url` 后在原页面显示预览二维码。等待期间保持进程运行；超时或查询失败仍保留上传成功状态，请勿直接重传。详见 [Vibe 接入说明](vibe-upload.md)。
 
-Version `0.4.6-vibe-beta.22`: when the authorization page is ready, `--format ndjson` writes one `page: <url>` line to stderr. Developers can see the page address in the console even when the Skill saves stdout to `vibe.ndjson`. The authorization, upload and two-QR preview flow remains the same as beta.21.
+Version `0.4.6-vibe-beta.17`: `ttmg upload --vibe` keeps polling the same task after upload and shows a game preview QR on the original page when `preview_url` arrives. Keep the process running. A preview timeout or lookup failure preserves the upload receipt; do not upload again.
 
-默认总等待时间为 30 分钟，`--timeout <seconds>` 最长可设 60 分钟。页面在任务进行中保持可用，CLI 结束后再保留 30 分钟；失败仍保留上传回执，勿直接重传。页面随浏览器语言显示中英文。
+Vibe 手机扫码授权与上传：`ttmg upload --vibe --dir ./game --title "My game" --icon ./avatar.png --format ndjson`。用户在手机 TikTok 扫码授权后，原命令自动上传。只收集标题和本地头像，并使用游戏目录或代码包；其他应用资料由 CLI 补齐。页面展示标题、头像、描述、类型和子类型。见 [Vibe 接入说明](vibe-upload.md)。
 
-The default operation deadline is 30 minutes, configurable up to 60 minutes with `--timeout <seconds>`. The page stays available during the operation and for 30 minutes after the CLI finishes. Failures preserve the upload receipt; do not upload again automatically. Page language follows the browser.
-
-Quick Start：`ttmg upload --vibe`。Skill 传入游戏标题、用户头像与 Native 工程或 ZIP；详细步骤见 [Vibe 接入说明](vibe-upload.md)。当前为 PPE 测试链路，上传成功不代表审核通过或正式发布。
-
-Quick Start: `ttmg upload --vibe`. Supply the game title, user-provided icon, and Native project or ZIP through the Skill. See the [Vibe guide](vibe-upload.md). This is a PPE trial; upload success does not mean review approval or production release.
-
-Tool 试用使用 `--minis-type MINI_TOOL`，仅支持 Native 包、效率办公分类、US 和 SDK 1.0.0。Tool 使用独立工程目录，默认游戏流程保持 `MINI_GAME`。
-
-For the Tool trial, use `--minis-type MINI_TOOL` in a separate project directory. It supports Native packages, Efficiency & Office, US and SDK 1.0.0. Games remain the default (`MINI_GAME`).
+扫码上传使用 `0.4.6-vibe-beta.17`，安装后核对版本与能力声明。Snow Crew 已在 PPE 完成真实上传并取得预览链接，用户确认扫码预览跑通；正式环境未开放。
 
 `ttmg` is a command-line tool designed for managing and developing mini-game projects. It supports initialization, development, debugging, and packaging for both H5 and native mini-games.
 `ttmg` 是一款专为小游戏项目管理与开发设计的命令行工具，支持 H5 小游戏和原生小游戏的初始化、开发调试及打包构建。
@@ -26,7 +18,7 @@ Vibe 版本支持手机扫码授权上传、可选 `--description`、分类查
 固定版本安装（发布标签为 `vibe-beta`）：
 
 ```bash
-npm install -g @ttmg/cli@0.4.6-vibe-beta.22
+npm install -g @ttmg/cli@0.4.6-vibe-beta.17
 ttmg --version
 ttmg capabilities --format json
 ttmg upload --help