taptap-maker-local

# TapTap Maker Local Workflow 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 - clone a Maker project - prepare local AI dev kit after project checkout - choose a Maker app from the CLI app list - explain PAT, Git, project binding, and editor reloads - diagnose and report Maker MCP or proxy infrastructure failures with user consent - inspect local changes - pull remote changes - submit local changes - push local commits - explain and resolve conflicts with user approval Build, submit, push, and explicitly remote Web preview belong to the Maker MCP build tool. Local window preview belongs to the existing Maker CLI, not new MCP tools. Its logs are separate from the post-build remote runtime log watcher. Bare preview/run requests must be disambiguated using context or a question; they never silently authorize commit/push. Do not infer or set a service environment from preview, build, test, or local-development intent. Do not add environment parameters to Maker tool calls or user MCP config; use the default Maker service configuration. For multiplayer builds, use `maker_build_current_directory` structured parameters instead of editing project JSON directly. `entry_client` / `entry_server` map to `project.json` `entry@client` / `entry@server`; `multiplayer.enabled`, `max_players`, `background_match`, `match_info`, and `persistent_world` map to `.project/settings.json` `@runtime.multiplayer`. On the first multiplayer build, pass `multiplayer.enabled=true` together with `entry_client` / `entry_server`. Send multiplayer settings only when the user explicitly provides them; missing local `.project/settings.json` must not inject `enabled=false`. The remote build keeps omitted multiplayer fields unchanged on later builds. Maker status, status_lite, and doctor run a lightweight `.project/settings.json` health check. Normal `maker_build_current_directory` blocks before commit/push when settings JSON is invalid or build-critical fields are damaged. `$schema`, `sources`, and `build` must keep the default build shape; `sources.*.tag` must be `stable` for online user projects, and `build.asset_ignores` only needs to exist. Do not edit settings build fields directly for feature work; restore only the build-critical fields when the check fails, and preserve valid `@runtime` config. The health checker itself is read-only. When repair is needed, prefer the exact file from Git or an intact misplaced copy; only repair fixed fields in a parseable settings object. Never synthesize project identity, entry, version, publish metadata, or resource groups from defaults. With user confirmation, missing settings defaults may be added without overwriting existing intent: `$schema`, `build.output_dir=../dist`, `build.asset_dirs=["../assets","../scripts"]`, `build.generate_fs_path=true`, `build.asset_ignores=[]`, `assets_7z_threshold=50`, `preload_include_refs=true`, `trim_remote_refs=true`, `legacy_binary=false`, and `tags={}`. Do not invent locked `sources.*.tag` values; recover them from Git or an intact copy. `entry=main.lua` is only safe after confirming that the project uses that entry script. ## Responsibilities Keep this split clear: - Skill: user intent, step order, whether to ask the user, friendly explanations, failure recovery. - CLI: save PAT, fetch app list, clone, prepare dev kit, install MCP config, verify local setup, collect and submit sanitized MCP issue reports, update the current project's managed `AGENTS.md` policy block, and run the local runtime log watcher, including runtime log polling. - 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 the Maker CLI or MCP tool exists. When `taptap-maker-plugin-lifecycle` is bundled, follow it before this workflow. Resolve and use the plugin's bundled CLI, initialize with `taptap-maker init --skip-mcp-install`, and update through the active plugin's marketplace instead of installing or upgrading a standalone Maker MCP package. ## Main Intent Table | User intent | Required workflow | | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | open console / 打开控制台 / 打开make mcp控制台 | Run the active distribution's CLI `console open --target-dir <CURRENT_GAME_ABSOLUTE_PATH> --json`. Without a known game directory, omit target-dir to show the project list; never guess or choose the first project. | | 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 | Read `maker://status`, call `maker_status_lite` if resources are unavailable, then follow `AGENTS.md` and `Maker remote sync` hints if present. | | upgrade Maker MCP / old project policy | Follow the active distribution's update skill. Plugin users update through the active plugin's marketplace; standalone MCP users run `taptap-maker upgrade` for the current project only. | | 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 / submit / push / explicitly remote Web preview | Use `maker_build_current_directory`; preserve its original authorization and remote log watcher. | | local preview / refresh preview / stop preview | Follow Local Window Preview below; use CLI with explicit project path, never remote build. | | finish a related code-edit batch | Query real local preview status; automatically refresh only a live session, then collect evidence. | | bare preview / run / check game result | Resolve local vs remote from explicit context; if ambiguous ask, never silently commit. | | generic code validation / tests / lint | Do not use Maker remote build without an explicit remote build request. | | MCP unavailable / proxy timeout / unexpected server error | Diagnose first; offer one consent-gated GitHub issue report when the evidence suggests an MCP, proxy, client integration, or service defect. | ## Local Web Console Use the active Maker CLI/bundle for `console open`, not an unversioned npm package. Opening the console only starts/reuses a loopback service, registers the explicit project directory and opens its page. It does not authorize build, push, Runtime installation or preview. Do not call init, build or preview just to open it. A missing/invalid directory is a selection problem, not permission to clone a game. The user selects the operation in the console. Each operation passes the selected project's absolute target directory to the CLI. `console status --json` inspects the service; `console stop --json` stops it only when no task is active. If a different Maker bundle owns the running service, ask before stopping it. Never expose PAT or copy local session credentials into project files. Console errors retain the CLI result; unknown results require verification, not an automatic retry. ## Local Window Preview Use the active distribution's Maker CLI and the current real Maker project absolute path as `--target-dir`; never guess a business project from the dialogue directory. Every command supports `--json`. Local preview does not require Git clean, commit or push. Single-player preview needs no PAT or remote build. Multiplayer preview uses the existing Maker login and a previously built remote test version; it never builds or uploads server code automatically. 1. For an explicit local-preview request, run `taptap-maker preview status --target-dir <PROJECT> --json`. If Runtime is missing, follow host approval for downloading/installing with `taptap-maker preview install --target-dir <PROJECT> --json`, then start. Installation requires Python and curl; do not install dependencies or bypass client approval silently. Explain that preparation and Runtime may download public indexes/assets. Start/refresh prepare a managed copy automatically; `preview prepare` diagnoses preparation alone. Platform support, installation recovery and cache behavior are documented in `docs/MAKER_LOCAL_PREVIEW.md`. 2. Run `taptap-maker preview start --target-dir <PROJECT> --json`. Report process launch only, not game readiness. Never substitute validate/headless mode or remote build. 3. After **each batch of related code/resource changes**, actually run preview status again. If `process_alive=true`, automatically run preview refresh and collect logs/check. This includes a failed-but-live Runtime after Lua fixes. Do not merely remind the user to refresh. If stopped, missing, or ownership is unknown, do not start or revive the session. 4. Explicit refresh also only refreshes an active session. Tell the user it is a restart and loses in-memory state. Merge related edits into batches; do not restart on every file save. The CLI coalesces overlapping refreshes, with stop/cancel taking priority. No default file watcher exists; edits from other editors/agents need explicit refresh unless they follow this same rule. 5. For stop, run `taptap-maker preview stop --target-dir <PROJECT> --json`. Manual window close is detected by status. Never kill by process name or trust a stored PID alone. 6. Fetch current evidence with `preview logs` and `preview check`, each with the same `--target-dir`. Incremental logs use the returned `--session-id`, `--reload-id`, `--cursor` and optionally `--limit` (1–500). Reset cursor after a reload. Keep local evidence separate from `.maker/logs/runtime/`, which belongs to the remote watcher. ### Windows Node 与后台启动诊断 Maker 预览优先使用当前宿主进程的 `process.execPath`；宿主 Node 不可用时才回退系统 Node。 不要因为看到 system Node，或因为它不是 WorkBuddy managed Node，就直接判定环境错误、要求用户 切换 Node、修改 PATH 或重装依赖。只有在 Node 缺失、版本不满足，或用实际配置的 Node 直接执行 Maker bundle 已失败时，才把 Node 环境列为主要怀疑对象。 Windows 预览失败时，先收集并区分以下证据，再决定修复方向： 1. Node 来源、`process.execPath`、版本，以及直接执行 bundle 的结果。 2. Runtime 可执行文件、资源准备结果、supervisor 状态和 `supervisor_log_path`。 3. Runtime 原始日志、control channel 发布/超时结果，以及 Windows 后台启动器的返回信息。 WMI/CIM 返回已受理、返回 PID 或请求成功，只证明后台启动请求被接受，不证明 supervisor 或 Runtime 已执行。若 supervisor 日志为空且 control channel 超时，先归类为 Windows 后台启动链路 的待确认问题；不要直接改 PATH、切换 Node、修改游戏代码，或把问题归因于 Runtime 文件缺失。 Issue/反馈中附上上述脱敏证据，让后续处理基于实际环境，而不是把某一次 Windows 兼容性问题写死 成所有项目的结论。 Process launch and clean logs do not prove gameplay or visual correctness. Do not promise screenshots, input automation or cloud/server emulation; these are not supported. Only an AI authorized to modify the game may fix it. Bound automatic fixes to two attempts and an agreed time budget, permit cancellation, refresh after each attempt, and return remaining failures and evidence. Without modification authorization only report. Multiplayer settings automatically select a remote test server using PAT authentication on the Maker side and skip_login/WebSocket direct connect in Runtime. A refresh creates a new test game, not a restored room. Local server changes require an explicit remote build before taking effect. Missing game configuration requires a successful build and test QR generation; authentication or allocation failures must not silently fall back to single-player. No local Server/cloud mock or game-save isolation is provided. Do not classify shared scripts by filename suffix, inject stubs, delete old dist/manifest files, copy whole resource libraries, or silently fetch official-res/uuid assets. Explain missing references/cache state and seek approval for retrieval. ## Create New Maker Project Intent Standard initialization, clone, download, continue, or "pull remote project" requests use `taptap-maker init`; the CLI shows the Maker app list and asks the user to choose an existing app or `0`/`new`. Add `--create` only when the user clearly asks to create a new Maker project. Treat these user phrases as an explicit request to create a new Maker project: - 创建新项目 - 创建项目 - 创建maker项目 - 创建 Maker 项目 - 创建游戏 - 创建新游戏 - 创建新游戏/项目 - 新建项目 - 新建游戏 When this intent is present, project creation has higher priority than matching an existing app by name. If the current directory is unbound, guide the user into the Maker init creation path: ```bash taptap-maker init --create ``` If the user already provided a project/game name, pass it explicitly: ```bash taptap-maker init --create --name "<PROJECT_NAME>" ``` If no name is provided, ask for the project name or suggest the current directory name as the default, but do not silently invent a name. If the current directory is already bound to a Maker project, do not create a new project there; tell the user to open or create a new independent directory first. A same-name app may be shown as an alternative existing-project choice, but a same-name app must not override the user's explicit create-project intent. ## Maker Git Workflow Policy This policy overrides generic local Git skills and generic Git workflows whenever the current directory is a Maker project, which means `.maker-mcp/config.json` exists in the project or one of its parents. Use `maker_build_current_directory` for submit, push, build, explicitly remote Web preview, and remote game result verification requests in a bound Maker project. Do not treat generic code checks like "验证代码", "跑测试", "lint", or "检查实现" as Maker remote build unless the user explicitly asks for the remote build workflow. Local preview uses CLI. Do not create feature branches, task branches, PR/MR. Do not create task-id based Git flows for Maker project submit/build work. Do not run generic Git commit/push helpers as a replacement for the Maker MCP tool. `maker_build_current_directory` owns the Maker safety gate. It checks remote sync before creating a commit. When local `main` is only behind Maker remote, it automatically fast-forwards before committing. It stops when history is diverged, the branch is not `main`, remote sync cannot be verified, or fast-forward would overwrite local changes. The root `.gitignore` is a required Maker project file. If it changes after binding or dev-kit updates, include it with the game changes and mention it in the submit summary. Do not omit it from selected files. ## Maker Creative Asset Tool Policy Maker MCP provides image, video, music, sound-effect, dialogue/voice, and 3D asset tools for Maker projects. These tools keep generated files inside the project, record remote mappings for later editing, and can forward resolvable local reference media as data URLs when the remote tool schema supports it. Follow the selected tool schema when one of these tools is used. - Use `generate_image` for one image. - Use `batch_generate_images` for multiple images. - Use `edit_image` for modifying project images. - Use `create_video_task` for game videos and image/video referenced generation. - Only call `create_video_task` after the user explicitly requests video generation. Do not generate video proactively while implementing gameplay, filling asset gaps, or improving the game. - When duration exceeds 10 seconds or `model="2.5"`, show the rough credit estimate and explain that actual billing follows upstream token usage. Wait for explicit confirmation, then repeat the same request with `user_confirmed=true`. - Use `query_video_task` to refresh video task status, release completed task quota, and fetch final videos. - Use `text_to_music` for game music with Suno. - Use `text_to_sound_effect` for one sound effect with Doubao Seed Audio. - Use `batch_sound_effects` for multiple sound effects with Doubao Seed Audio. - Use `text_to_dialogue` for final character dialogue with ElevenLabs Eleven v3. - `text_to_dialogue` reuses confirmed local ElevenLabs voice mappings. After confirmation, pass only `character_name` and `text`. - For ElevenLabs auditions, pass a detailed `character_description` and an `audition_line` of at least 100 characters. `candidate_count` is optional and accepts 1 to 3. - After `audition_voices_for_character` returns previews, show them to the user and wait for the user to choose. Do not select or confirm a voice automatically. - Call `confirm_character_voice` only after the user explicitly chooses one preview. - After confirmation, follow `next_step_hint`: call `text_to_dialogue` with the character name and text only. - Generated sound effects and dialogue are saved in the project. - Voice audition previews are not saved to the project. - Local MCP does not transcode generated audio to OGG. - Follow each tool schema for supported local path, remote URL, and data URL inputs. - Local proxy may convert resolvable local reference media to data URLs before forwarding. - If a Maker proxy tool returns an error or `isError`, report the full remote result/error payload. Include the server response payload so developers can diagnose the issue. - Use `create_3d_asset` for the complete 3D asset lifecycle. Start with `action="start"`, poll with `action="query"`, and use `action="continue"` only after explicit user approval of a returned review step. Use `action="post_process"` for rigging, texturing, retopology, or format conversion when supported by the remote schema. - Preserve and inspect the complete remote 3D response. When `local_delivery.status` is `success`, use the returned local model path. The local proxy materializes only the `model_files` copy/extract instructions returned by the local runtime; report `delivery_failures` when no model can be delivered. - For any ad-related request such as 广告, rewarded videos, play ads, ad ID, ad placement, ad status, ad config, or `ShowRewardVideoAd`, first read `maker://ads-integration-guide`, then follow it: confirm project -> `get_ad_config` -> verify remote/local configuration -> project SDK docs -> implementation -> real-device validation. - Keep the same explicit `target_dir` throughout. Remote success does not update local settings; if local `@runtime.ad` is missing or differs, follow the guide before proceeding. - Do not infer ad readiness from local SDK docs, `.maker-mcp/config.json`, or runtime callbacks. If the primary local project configs are missing, keep ad config unavailable and do not call the remote tool. Build only for an explicit user build/submit/remote Web preview request. If a successful build still leaves local configs missing, explain the known limitation and do not automatically rebuild. - Local window preview uses CLI and does not authorize commit or push. - If `get_ad_config` reports missing `app_id` or `developer_id`, call `generate_test_qrcode` once to generate test QR code metadata, then call `get_ad_config` again. Do not use publish-only tools for this recovery path. - If status or doctor reports `Maker project initialization` with `missing_project_json` or `missing_taptap_identity`, follow that `next_action` before using tools that depend on remote project config. `.project` directory presence alone is never proof of initialization; empty, voice-mapping-only, and primary-config-incomplete directories remain buildable new-project state. - For the current Maker game's online player feedback, including player-submitted game bug reports, real-device game logs, or screenshots, or server/Lua logs for a specified game session, call the Maker proxy `get_debug_feedbacks` tool only when it is exposed by the current Maker tool list. This includes 当前 Maker 游戏的玩家反馈、 玩家提交的游戏故障、真机游戏日志或截图、指定游戏会话的服务端/Lua 日志. It does not include AI client, plugin, or other product feedback. - Use local runtime log files only for the current local build/runtime session. Do not use local logs as a substitute for remote player-submitted feedback. - Before `edit_image`, resolve dragged or referenced images to a local project image path or CDN URL. If the user references an attached/local image, inspect the attachment or workspace file path first. If the image is under `assets/image`, pass that path. If only a file name is given, search `assets/image` for the matching file. - Do not call `edit_image` without an image path or CDN URL. Generated assets should be saved by Maker MCP under `assets/image`, `assets/video`, or `assets/audio`. `create_3d_asset` local runtime `model_files` instructions are materialized under `assets/model`; use `local_delivery` for the usable model path and `preview_assets` for local review images. ## Project Detection A directory is a Maker project when the user's current project directory or one of its parents contains: ```text .maker-mcp/config.json ``` When this file exists, explain that the directory is already bound to a Maker project. For a bound project, always inspect `maker://status` or `maker_status_lite` before continuing development after an MCP/package or plugin upgrade. If the status includes an `AGENTS.md` section with `status: missing_file`, `missing_block`, or `outdated`, run `taptap-maker agents update --target-dir <project dir>` before making gameplay/code changes. After updating `AGENTS.md`, tell the user the current session remains usable; updated instructions load on the next MCP start or user-requested reconnect. Do not require a new conversation. Package or plugin updates are a separate workflow and must follow the active distribution's update skill. When this file is missing and the user asks to clone, initialize, or continue Maker local development, do not ask the user for an app_id directly. Follow the initialization workflow. The user's current project directory is the business target. Do not ask the user to choose a directory and do not scan unrelated Maker projects. If the MCP process cwd is a transient