@taptap/instant-games-open-mcp 1.23.2 → 1.23.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taptap/instant-games-open-mcp",
-  "version": "1.23.2",
+  "version": "1.23.4",
   "type": "module",
   "description": "TapTap Open API MCP Server - Documentation and Management APIs for TapTap Minigame and H5 Games (Leaderboard, and more features coming)",
   "main": "dist/server.js",

package/skills/taptap-maker-dev-kit-guide/SKILL.md

@@ -5,8 +5,8 @@ description: Explain the local TapTap Maker AI dev kit installed during Maker pr
 
 # TapTap Maker AI Dev Kit
 
-Use this skill to orient the local AI/Agent after `maker_clone_to_current_directory` installs the
-AI dev kit into a Maker project directory.
+Use this skill to orient the local AI/Agent after `taptap-maker init` installs the AI dev kit into a
+Maker project directory.
 
 ## What To Tell The Local Agent
 
@@ -30,9 +30,11 @@ When a user asks to develop or modify a Maker project after clone:
 4. Use `templates/` when creating new game files or scaffolding.
 5. Use `urhox-libs/` when engine API behavior or capability names are needed.
 
-If these entries are missing in a bound Maker project, call `maker_status` with the actual project
-directory as `target_dir`. The status tool will report dev-kit state and restore missing local
-dev-kit entries when possible.
+If these entries are missing in a bound Maker project, read `maker://status` or call
+`maker_status_lite` with the actual project directory as `target_dir` to confirm state, then run
+`taptap-maker dev-kit update` in that project directory to restore missing local dev-kit entries.
+If status includes `Maker remote sync`, follow that section before editing: pull first only when the
+workspace is clean, otherwise let the local AI help the user submit, stash, or cancel before pulling.
 
 These files are local development aids. Do not submit them to Maker Git unless the user explicitly
 asks and understands they are local environment files.
@@ -41,10 +43,12 @@ asks and understands they are local environment files.
 
 Keep validation simple for Maker users. 用户可以直接说“提交”或“构建”:
 
-- If the user says “提交”, use the Maker submit flow so local changes are committed, pushed, and
-  built by the Maker MCP tools.
-- If the user says “构建”, use the Maker build flow. If the tool reports local changes, follow the
-  options returned by the tool instead of inventing a separate build script.
+- If the user says “提交”, “推送”, “构建”, “预览”, or “跑一下”, use
+  `maker_build_current_directory`. The tool commits when needed, pushes to Maker remote, and then
+  runs the remote build.
+- If push fails, do not start a separate build or generic Git push. Explain the returned recovery
+  details, follow the returned classification-specific recovery (`remote_rejected`,
+  `branch_not_allowed`, `forbidden_path`, or `auth`), then retry `maker_build_current_directory`.
 - After submit or build finishes, tell the user to open the TapMaker 网页端查看结果.
 
 Do not create local-only test scripts just to verify Maker changes. The expected validation path is

package/skills/taptap-maker-local/SKILL.md

@@ -5,18 +5,19 @@ description: Guide TapTap Maker local development workflows. Use when a user ask
 
 # TapTap Maker Local Workflow
 
-Use this skill as the workflow layer for Maker local development. MCP tools provide machine
-capabilities; this skill decides the sequence, asks the user for choices, and explains local
-state in plain language.
+Use this skill as the workflow layer for Maker local development. The Maker CLI owns one-time
+initialization; MCP tools own the high-frequency development loop. This skill decides the sequence,
+asks the user for choices, and explains local state in plain language.
 
 ## Scope
 
 This skill covers:
 
 - initialize local Maker development
+- run the Maker CLI initialization flow
 - prepare local AI dev kit before project binding
 - clone a Maker project
-- choose a Maker app from the app list
+- choose a Maker app from the CLI app list
 - explain PAT, Git, project binding, and editor reloads
 - inspect local changes
 - pull remote changes
@@ -24,30 +25,30 @@ This skill covers:
 - push local commits
 - explain and resolve conflicts with user approval
 
-Build behavior still belongs to the existing Maker MCP build tool. Do not remove or bypass the
-current MCP tools.
+Build, submit, push, preview, and verify behavior belongs to the single Maker MCP build tool.
 
 ## Responsibilities
 
 Keep this split clear:
 
 - Skill: user intent, step order, whether to ask the user, friendly explanations, failure recovery.
-- MCP tools: save PAT, fetch app list, clone, submit, build, inspect Maker status.
-- CLI: install MCP config and install bundled skills.
+- CLI: save PAT, fetch app list, prepare dev kit, clone, install MCP config, verify local setup.
+- MCP tools/resources: inspect Maker status and run the combined commit/push/build path.
 
-Do not reimplement Maker API calls or Git authentication in shell when a Maker MCP tool exists.
+Do not reimplement Maker API calls or Git authentication in shell when the Maker CLI or MCP tool
+exists.
 
 ## Main Intent Table
 
 | User intent                                               | Required workflow                                                                                                                  |
 | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| initialize / configure / continue Maker local development | Follow "Initialization Workflow".                                                                                                  |
+| initialize / configure / continue Maker local development | Run the Maker CLI initialization workflow.                                                                                         |
 | clone / download Maker project locally                    | Follow "Initialization Workflow"; do not ask for app_id directly.                                                                  |
-| status / is Maker ready                                   | Call `maker_status` for the user's current project directory, then explain missing prerequisites and dev-kit status.               |
-| submit / commit / push to Maker                           | Inspect local Git state, summarize changed files, then call `maker_submit_current_directory` unless blocked.                       |
+| status / is Maker ready                                   | Read `maker://status`, call `maker_status_lite` if resources are unavailable, then follow `Maker remote sync` if present.          |
+| submit / commit / push to Maker                           | Inspect local Git state, summarize changed files, then call `maker_build_current_directory` unless blocked.                        |
 | pull / update from remote                                 | Inspect local changes first; if dirty, explain options before pulling.                                                             |
 | conflict / merge failed                                   | Explain why the conflict happened, list conflict files, inspect conflict hunks, propose a resolution plan, and ask before editing. |
-| build / preview / run / verify                            | Use `maker_build_current_directory`; if it reports local changes, ask using the exact options returned by the tool.                |
+| build / preview / run / verify                            | Use `maker_build_current_directory`; it commits/pushes before build unless the user explicitly requests remote-only build.         |
 
 ## Project Detection
 
@@ -81,8 +82,9 @@ calling Maker tools. If there are multiple attached workspaces, show the paths a
 which one is the Maker project directory. Do not treat the dialogue/session directory as the Maker
 project directory, and do not ask the user to clone an app into that directory.
 
-If `maker_status` returns `AI client workspace selection`, follow that hint: choose an attached
-workspace first, then call `maker_status(target_dir="<attached project directory>")`.
+If status output returns `AI client workspace selection`, follow that hint: choose an attached
+workspace first, then read `maker://status` or call `maker_status_lite` with the attached project
+directory.
 
 ## Initialization Workflow
 
@@ -100,43 +102,43 @@ Trigger phrases include:
 
 Workflow:
 
-1. Call `maker_status`. If the MCP process cwd differs from the user's current project directory,
-   pass the user's current project directory as `target_dir`.
-2. If `maker_status` reports the current directory is already bound to a Maker project, stop the
+1. Run `taptap-maker doctor` for the user's intended Maker directory, or read `maker://status` when
+   the MCP server is already available.
+2. If the status reports the current directory is already bound to a Maker project, stop the
    initialization/clone path. Continue with the user's current intent in that bound project. Do not
    ask which app to clone unless the user explicitly asks to switch or re-clone.
 3. If Git is missing, stop. Tell the user Git is required for clone/submit/build-side Git work.
-4. If `maker_status` lists bundled skill documents, just tell the user which skills are available.
-   Do not run editor-specific CLI install commands.
-5. If PAT is missing, ask the user to open the PAT page shown by `maker_status`, create a PAT, and send it back.
-6. When the user provides PAT, call `maker_exchange_pat(manual_pat)`.
-7. If the current directory is still unbound, show every returned Maker app entry to the user and
-   ask the user to choose. Do not summarize the list as only a count, category, or stage. Do not
-   auto-select, even if there is only one app.
-8. Run the working directory compliance check below, including the parent Git repository warning.
-9. After the user chooses an app, call `maker_clone_to_current_directory(app_id)`. The clone
-   tool prepares the AI dev kit automatically before project checkout.
-10. After clone succeeds, call `maker_status` again or explain that `.maker-mcp/config.json` now binds the directory to the Maker project.
-11. Tell the local AI/Agent to use the `taptap-maker-dev-kit-guide` skill for the installed dev-kit
-    resources, especially `CLAUDE.md`, `examples/`, `templates/`, and `urhox-libs/`.
+4. Run `taptap-maker init` in the user's intended Maker directory. The CLI will request PAT if
+   missing, fetch TapTap token, show a paged app preview, ask the user to choose, prepare the AI dev
+   kit, clone the Maker project, and install/verify MCP config.
+   Tell the user that the first Maker clone can take 20+ seconds because the server may be
+   preparing the repository, and that they should keep the command running while the CLI retries
+   transient 503/5xx failures.
+5. If the CLI reports ordinary local files or parent Git repository risk, explain the warning and
+   ask whether the user wants to continue in this directory or switch to a clean independent one.
+6. After clone succeeds, run `taptap-maker doctor` again or explain that `.maker-mcp/config.json`
+   now binds the directory to the Maker project.
+7. Tell the local AI/Agent to use the `taptap-maker-dev-kit-guide` skill for the installed dev-kit
+   resources, especially `CLAUDE.md`, `examples/`, `templates/`, and `urhox-libs/`.
 
 Keep the user-facing explanation short:
 
 ```text
-我会先检查本机 Git、PAT 和当前目录是否已绑定 Maker 项目。
-如果还没有 PAT，我会让你去页面创建一个；拿到项目列表后你选游戏，我再拉代码。
+我会先用 Maker CLI 检查本机 Git、PAT 和当前目录是否已绑定 Maker 项目。
+如果还没有 PAT，CLI 会让你去页面创建一个；拿到项目列表后你选游戏，我再拉代码。
 ```
 
 ## AI Dev Kit Preparation
 
-`maker_clone_to_current_directory` prepares local development environment files in the current
-working directory before it checks out the Maker project.
+`taptap-maker init` prepares local development environment files in the current working directory
+before it checks out the Maker project.
 
-`maker_status` checks the dev-kit top-level entries for an already bound Maker project. If
-`CLAUDE.md`, `examples/`, `templates/`, or `urhox-libs/` are missing, the tool restores the dev kit
-without overwriting existing local files and refreshes the managed `.gitignore` block.
+`taptap-maker doctor` and `maker://status` check the dev-kit top-level entries for an already bound
+Maker project. If `CLAUDE.md`, `examples/`, `templates/`, or `urhox-libs/` are missing, run
+`taptap-maker dev-kit update` to restore the dev kit without overwriting existing local files and
+refresh the managed `.gitignore` block.
 
-The clone tool downloads and installs:
+The CLI downloads and installs:
 
 ```text
 https://urhox-demo-platform.spark.xd.com/ai-dev-kit/pd/stable/ai-dev-kit.zip
@@ -150,7 +152,7 @@ resources to the local AI/Agent:
 - `templates/` contains reusable templates.
 - `urhox-libs/` contains engine APIs and capability references.
 
-The clone tool is responsible for deterministic file operations:
+The CLI is responsible for deterministic file operations:
 
 - extract the ZIP into the current directory
 - skip the ZIP top-level `scripts` directory because it conflicts with Maker project code
@@ -159,18 +161,29 @@ The clone tool is responsible for deterministic file operations:
 - after Maker clone succeeds, merge that block into the checked-out `.gitignore`
 - keep the dev-kit files local-only so they are not submitted to Maker Git
 
-Do not hand-write a custom download/unzip script while this MCP clone tool is available.
+Do not hand-write a custom download/unzip script while this CLI command is available.
 
 If clone fails because dev-kit network access is unavailable, explain that the Maker project can
 still be cloned, but local AI development docs/API/demo support may be incomplete. Ask whether
 the user wants to retry or continue without the dev kit.
 
+If clone or fetch fails with Maker Git output, inspect the returned error fields instead of asking
+the user to delete local files immediately. Treat `retryable: yes`, `classification:
+remote_transient`, or retry reasons such as `remote_http_5xx`, `network_or_timeout`, and
+`connection_interrupted` as temporary service/network failures. For first clone, explain that 503
+often means the Maker server is still preparing the repository and can take more than 20 seconds.
+The CLI already retried these automatically; if it still fails, tell the user they can retry
+`taptap-maker init` later or switch to a cleaner independent directory after repeated failures. Do
+not retry for auth, permission, repository-not-found, remote-rejected, local file conflict, or local
+permission errors until the reported cause is fixed.
+
 ## PAT Handling
 
-If the user pastes a token-like string while the initialization flow is waiting for PAT, call
-`maker_exchange_pat(manual_pat)` and continue only if the current directory is unbound. Do not just
-say "received". If the directory is already bound, treat the returned app list as account reference
-only and continue the user's current bound-project task.
+If the user pastes a token-like string while the initialization flow is waiting for PAT, let the
+running `taptap-maker init` prompt consume it, or run `taptap-maker pat set` and paste the PAT into
+the prompt. Do not put PAT directly in argv unless the user explicitly accepts the ps/shell-history
+exposure. Do not just say "received". If the directory is already bound, treat `taptap-maker apps`
+output as account reference only and continue the user's current bound-project task.
 
 If PAT exchange fails:
 
@@ -183,12 +196,16 @@ If PAT exchange fails:
 Use app selection only when the current directory is unbound and the user is initializing or cloning
 a Maker project, or when the user explicitly asks to switch or re-clone.
 
-If the current directory is already bound, app lists from `maker_exchange_pat`, `maker_list_apps`, or
-`maker_status` are reference only. Do not ask which app to clone. Continue operating on the current
-bound project unless the user explicitly requests a different project.
+If the current directory is already bound, app lists from `taptap-maker apps` are reference only. Do
+not ask which app to clone. Continue operating on the current bound project unless the user
+explicitly requests a different project.
 
-When app selection is needed, display every app entry from the tool result and ask the user to
-choose by index, app id, or name. Do not replace the list with a summary such as "10 apps are
+When app selection is needed, show the returned app preview and total count, then ask the user to
+choose by index, app id, or name. The default preview shows 40 apps and `limit` is capped at 100.
+If the target is not visible, ask the user to type `next`, provide app id/name keywords, or run
+`taptap-maker apps --offset 40 --limit 40` / `taptap-maker apps --json`. If the chat/client width
+is enough, you may present the preview as a compact two-column layout; otherwise keep a single
+column. Do not omit app_id, and do not replace the preview with only a summary such as "40 apps are
 available".
 
 Do not auto-select:
@@ -197,17 +214,18 @@ Do not auto-select:
 - the most recent app
 - the only app
 
-After the user chooses, pass the concrete `app_id` to `maker_clone_to_current_directory`.
+After the user chooses, let `taptap-maker init` continue with the selected app. Do not ask the user
+to manually provide app_id unless the CLI is being run non-interactively.
 
 ## Working Directory Compliance Check
 
-Before every clone attempt, call `maker_status(target_dir)` for the user's intended Maker
-development directory. Use that result as the source of truth for Git availability, existing Maker
-binding, outer Git repository detection, and AI dev-kit status.
+Before every clone attempt, run `taptap-maker doctor` for the user's intended Maker development
+directory. Use that result as the source of truth for Git availability, existing Maker binding,
+outer Git repository detection, and AI dev-kit status.
 
 ### Directory Suitability Decision
 
-After `maker_status(target_dir)`, decide whether the directory is suitable for clone:
+After `taptap-maker doctor`, decide whether the directory is suitable for clone:
 
 - If the directory is already bound to a Maker project, do not clone again unless the user
   explicitly asks to switch or re-clone.
@@ -244,16 +262,16 @@ user before clone:
 - A Maker project can live under that directory only if the Maker directory gets its own `.git`.
 - Recommend a completely independent directory, such as `~/MakerProjects/<game-name>`, for safer
   local development.
-- If the user explicitly continues, call `maker_clone_to_current_directory`; the MCP clone tool
-  must initialize an independent Maker Git repository in the target directory and must not modify
-  the outer repository remote.
+- If the user explicitly continues, continue `taptap-maker init`; the CLI must initialize an
+  independent Maker Git repository in the target directory and must not modify the outer repository
+  remote.
 
 Do not delete, move, or overwrite user files during this check.
 
 ## Clone Directory Safety
 
-Before clone, the Maker MCP clone tool checks local files and reports conflicts. The AI dev kit
-may create local-only files before clone, so explain this in non-technical terms:
+Before clone, the Maker CLI checks local files and reports conflicts. The AI dev kit may create
+local-only files before clone, so explain this in non-technical terms:
 
 - existing local config folders such as `.claude`, `.mcp`, `.skill`, `.config`, `.ini` are kept
 - normal local files are kept unless they conflict with files from the Maker project
@@ -262,15 +280,14 @@ may create local-only files before clone, so explain this in non-technical terms
 
 Do not delete or overwrite user files to make clone work unless the user explicitly asks.
 
-If `maker_clone_to_current_directory` fails and the tool returns `partial_state`, explain the
-state in plain language:
+If `taptap-maker init` fails and returns `partial_state`, explain the state in plain language:
 
 - `project_bound: no` usually means clone did not finish; retrying clone is allowed.
 - `git_initialized: yes` with `project_bound: no` means the directory may contain a partial local
   Git setup; retry once, and if it fails again recommend a fresh independent directory.
 - `ai_dev_kit_present: yes` means local AI docs/examples may already be present even though Maker
   project checkout failed.
-- `project_bound: yes` means the directory already has Maker binding; run `maker_status` before
+- `project_bound: yes` means the directory already has Maker binding; run `taptap-maker doctor` before
   attempting anything else.
 
 Do not delete partial files automatically. For novice users, prefer recommending a new independent
@@ -278,9 +295,9 @@ directory over manual cleanup.
 
 ### `.gitignore` Merge During Clone
 
-The Maker clone tool stages the dev-kit managed ignore block in
+The Maker CLI stages the dev-kit managed ignore block in
 `.gitignore.dev-kit-before-clone` instead of writing `.gitignore` before checkout. After Maker
-clone succeeds, the clone tool merges that managed block into the checked-out `.gitignore` and
+clone succeeds, the CLI merges that managed block into the checked-out `.gitignore` and
 removes the temporary file.
 
 If clone still reports conflicts for files other than `.gitignore.dev-kit-before-clone`, do not
@@ -292,8 +309,8 @@ submitted to Maker Git.
 
 ## Bundled Skills
 
-When `maker_status` reports TapTap bundled workflow skills, show the skill names and document
-paths. Do not install or register skills automatically.
+When `taptap-maker doctor`, `maker://status`, or `maker_status_lite` reports TapTap bundled workflow
+skills, show the skill names and document paths. Do not install or register skills automatically.
 
 `taptap-maker-local` covers Maker local workflow. `taptap-maker-dev-kit-guide` explains the local
 AI dev-kit resources installed during clone. `update-taptap-mcp` covers local TapTap MCP cache
@@ -303,6 +320,26 @@ Prefer user/global scope for Maker MCP installation. If a project/local config a
 do not block the workflow; just explain that user/global scope is recommended to avoid config
 being tied to a specific project folder.
 
+## Remote Sync Status
+
+For a bound Maker project, `maker://status` and `maker_status_lite` include `Maker remote sync`.
+Read this section before the user starts editing in a fresh conversation:
+
+- For frequent polling or quick local-only status checks, call `maker_status_lite` with
+  `skip_remote_sync: true` to avoid a `git fetch origin` network round trip on every status read.
+- `up_to_date`: continue development.
+- `needs_pull` with `local_changes: no`: tell the user the workspace is clean and the local AI can
+  run `git pull --ff-only origin main` before editing.
+- `needs_pull` with `local_changes: yes`: do not pull immediately. Explain that remote changes exist
+  and local edits are present; ask the local AI to inspect `git status` and help the user choose
+  submit current changes, stash then pull and restore, or cancel.
+- `diverged`: do not push or blindly pull. Ask the local AI to plan a rebase or merge of current
+  Maker remote changes.
+- `branch_not_allowed`: Maker only accepts `main`; switch/migrate local commits to `main` before
+  build or submit.
+- `remote_unavailable`: follow the failure classification and retry later only for temporary
+  5xx/network/timeout failures.
+
 ## Local Change Review
 
 Before submitting, run local Git inspection when available:
@@ -330,28 +367,37 @@ mean:
 commit + push + Maker build
 ```
 
-Use `maker_submit_current_directory` for this path. Do not use generic Git task-id,
+Use `maker_build_current_directory` for this path. Do not use generic Git task-id,
 branch-creation, or PR rules inside Maker project repositories.
 
-If `maker_submit_current_directory` returns a build failure after a successful push, report both:
+If `maker_build_current_directory` returns a build failure after a successful push, report both:
 
 - submit/push succeeded
 - build failed, with the concrete build error
 
 If submit created a local commit but push failed because the Maker remote was temporarily
-unavailable, do not run a manual generic `git push`. Tell the user to retry
-`maker_submit_current_directory`, or use `maker_build_current_directory` with
-`submit_local_changes_before_build=true` when the user is retrying build. Maker MCP will detect
-committed-but-unpushed local commits and push them before build.
+unavailable, do not run a manual generic `git push`. Fix the reported cause if needed, then retry
+`maker_build_current_directory`. Maker MCP will detect committed-but-unpushed local commits and push
+them before build.
+
+For push failures, use the returned `classification`, `retryable`, `retry_reason`, and
+`retry_attempts` fields. Temporary 5xx/network/timeout failures may be retried with the Maker build
+tool; `remote_rejected` means remote updates require pull/rebase first; `auth` means refreshing PAT;
+`branch_not_allowed` means Maker remote only accepts `main`; `forbidden_path` means the remote
+pre-receive hook rejected one or more paths/directories and the forbidden pattern from stderr must
+be removed from the unpushed commit before retrying.
 
 When a Maker tool output contains `push_recovery`, follow it exactly:
 
 - Tell the user the local commit is preserved but not yet on Maker remote.
 - Do not ask for permission to run a generic `git push`.
-- Retry with `maker_submit_current_directory` for submit requests.
-- Retry with `maker_build_current_directory(submit_local_changes_before_build=true)` for build
-  requests.
+- Retry with `maker_build_current_directory` for submit and build requests.
 - If the failure is `remote_rejected`, ask before pull/rebase; do not create a new branch or PR.
+- If the failure is `branch_not_allowed`, do not pull/rebase. Tell the user Maker only accepts
+  `main`, switch back to `main`, cherry-pick the preserved local commit there, then retry.
+- If the failure is `forbidden_path`, do not refresh PAT. Read the forbidden pattern in stderr,
+  remove those paths from the unpushed commit while keeping local files, then retry after
+  `git status` is clean for them.
 
 ## Pull And Conflict Handling
 

package/skills/update-taptap-mcp/SKILL.md

@@ -75,7 +75,7 @@ foreach ($f in $projectConfigPaths) {
 ## Step 1：对比远端和本地版本
 
 ```powershell
-npm view '@taptap/instant-games-open-mcp@beta' version
+npm view '@taptap/instant-games-open-mcp' version
 $NpxDir = Join-Path (npm config get cache) '_npx'
 Get-ChildItem $NpxDir -Directory -ErrorAction SilentlyContinue | ForEach-Object {
   $p = Join-Path $_.FullName 'node_modules\@taptap\instant-games-open-mcp\package.json'
@@ -98,17 +98,11 @@ Get-ChildItem $NpxDir -Directory -ErrorAction SilentlyContinue | ForEach-Object
 
 ## Step 3：预热下载
 
-根据用户 MCP 配置选默认 bin 或指定 bin（`taptap-maker`）。下例以 `taptap-maker` 为例，默认 bin 去掉 `'-p','@taptap/instant-games-open-mcp@beta','taptap-maker'`，改成单独一个 `'@taptap/instant-games-open-mcp@beta'`。
+预热正式 npm 包，并验证 `taptap-maker` binary 可以启动。
 
 ```powershell
-$env:TAPTAP_MCP_ENV = 'rnd'
 $log = Join-Path $env:TEMP 'taptap-mcp-warmup.log'
-$proc = Start-Process -FilePath npx `
-  -ArgumentList '-y','-p','@taptap/instant-games-open-mcp@beta','taptap-maker' `
-  -RedirectStandardOutput $log -RedirectStandardError "$log.err" `
-  -WindowStyle Hidden -PassThru
-Start-Sleep -Seconds 25
-Stop-Process -Id $proc.Id -Force -ErrorAction SilentlyContinue
+npx -y -p '@taptap/instant-games-open-mcp' taptap-maker help > $log 2> "$log.err"
 ```
 
 ## Step 4：验证
@@ -124,7 +118,7 @@ claude mcp list 2>&1 | Select-String -Pattern 'taptap|Warning'
 
 ## Step 5：提示用户重启客户端
 
-更新完成后提醒用户重启 MCP 客户端，或新开 Claude Code / Codex / Cursor 窗口。当前会话通常不会热加载新 MCP；重启后以 `maker_status` 是否可调用作为最终生效标准。
+更新完成后提醒用户重启 MCP 客户端，或新开 Claude Code / Codex / Cursor 窗口。当前会话通常不会热加载新 MCP；重启后以能读取 `maker://status` 作为首选生效标准；如果客户端不支持 MCP Resources，则以 `maker_status_lite` 是否可调用作为兜底标准。
 
 ---
 
@@ -165,7 +159,7 @@ done
 ## Step 1：对比远端和本地版本
 
 ```bash
-npm view @taptap/instant-games-open-mcp@beta version
+npm view @taptap/instant-games-open-mcp version
 NPX_DIR="$(npm config get cache)/_npx"
 for d in "$NPX_DIR"/*/; do
   p="$d/node_modules/@taptap/instant-games-open-mcp/package.json"
@@ -186,12 +180,11 @@ done
 
 ## Step 3：预热下载
 
-根据用户 MCP 配置选默认 bin 或指定 bin（`taptap-maker`）。下例以 `taptap-maker` 为例，默认 bin 去掉 `-p ... taptap-maker`，直接写 `@taptap/instant-games-open-mcp@beta`。
+预热正式 npm 包，并验证 `taptap-maker` binary 可以启动。
 
 ```bash
-TAPTAP_MCP_ENV=rnd npx -y -p @taptap/instant-games-open-mcp@beta taptap-maker \
-  < /dev/null > /tmp/taptap-mcp-warmup.log 2>&1 &
-PID=$!; sleep 25; kill $PID 2>/dev/null; wait 2>/dev/null
+npx -y -p @taptap/instant-games-open-mcp taptap-maker help \
+  > /tmp/taptap-mcp-warmup.log 2>&1
 ```
 
 ## Step 4：验证
@@ -207,4 +200,4 @@ claude mcp list 2>&1 | grep -E "taptap|Warning"
 
 ## Step 5：提示用户重启客户端
 
-更新完成后提醒用户重启 MCP 客户端，或新开 Claude Code / Codex / Cursor 窗口。当前会话通常不会热加载新 MCP；重启后以 `maker_status` 是否可调用作为最终生效标准。
+更新完成后提醒用户重启 MCP 客户端，或新开 Claude Code / Codex / Cursor 窗口。当前会话通常不会热加载新 MCP；重启后以能读取 `maker://status` 作为首选生效标准；如果客户端不支持 MCP Resources，则以 `maker_status_lite` 是否可调用作为兜底标准。