@taptap/instant-games-open-mcp 1.22.0-beta.5 → 1.22.0-beta.7

package/README.md

@@ -66,23 +66,35 @@ maker_push_current_directory
 说明：
 
 - Maker MCP 依赖用户本机已有 Git。工具只检测并给出安装引导，不会代替用户安装 Git。
+- 用户说“更新 mcp / 更新 taptap mcp / 刷新 mcp 缓存 / tap mcp 有新版本”时，应调用 `maker_get_mcp_update_guide`。该工具只返回 Windows 或 macOS/Linux 的更新引导、安装检查、配置位置提醒和重启提示，不直接执行更新命令；由用户本地 AI 客户端按返回命令操作。
 - 用户说“我要开发maker游戏 / 本地maker开发 / 拉取maker游戏到本地 / 把maker游戏代码拉到本地 / clone maker项目 / 下载maker游戏代码 / 初始化maker开发目录 / 配置maker本地开发 / 继续开发maker项目”时，应触发 Maker 本地开发初始化流程。
 - 如果 `maker_status` 或 `maker_check_environment` 显示 Git 缺失，必须持续提示用户自行安装 Git；在 `git --version` 可用前，不执行 clone、fetch、commit 或 push。
 - Maker API、git 和 TapTap token 默认走 PAT-first：如果用户还没有 PAT，引导用户打开临时 PAT 页面 `https://fuping.agnt.xd.com/pat-tokens` 新建 PAT；用户提供 PAT 后调用 `maker_exchange_pat(manual_pat)` 保存。
 - 保存 PAT 后会自动列出 app；`maker_status` 如果发现本地已有 PAT 且当前目录未绑定，也会自动列出 app，无需用户额外要求。
 - 保存 PAT 后会自动调用 `GET /api/v1/user/taptap-token` 获取并保存 TapTap MAC token；Tap OAuth 登录只作为 legacy fallback。
 - `maker_list_apps` 和 `maker_clone_to_current_directory` 不再要求先完成 Tap 登录。
+- `maker_clone_to_current_directory` 不要求当前目录为空；clone 前会检查本地目录，忽略 `.claude`、`.mcp`、`.skill`、`.config`、`.ini` 等点开头配置项，只对普通本地文件输出提醒。clone 最终结果固定包含 `Pre-clone local directory check` 区块；已有本地文件会保留，若与 Maker 项目文件同路径冲突则失败并列出冲突文件。
+- `maker_list_apps` 会解析 Maker `/apps` 返回的创建时间、最近会话时间、游戏类型、阶段、图标、置顶/归档/删除时间等字段，并保留原始 `raw` 数据。
 - Maker Tap 登录只需要 client id；`rnd` 环境或 npm `@beta` 包会使用内置 Maker client id 兜底，不要求产品配置 `TAPTAP_MCP_CLIENT_SECRET`。
 - PAT 会保存到 `~/.taptap-maker/pat.json`，并兼容旧的 `~/.maker-pat`、`PAT` / `MAKER_PAT` 环境变量。
 - JWT 仅作为 legacy fallback 保留：`maker_exchange_jwt(manual_jwt)`、`JWT` / `MAKER_JWT` 仍可用于旧后端或创建新 PAT。
 - Maker app 必须先通过 `maker_list_apps` 展示给用户选择，再调用 clone。
 - Maker 后端地址按 `TAPTAP_MCP_ENV` 从 `src/maker/config.ts` 的环境配置表读取，本地 MCP 配置只需要切 `rnd` / `production`。
-- 如果用户直接说“构建 / build / 重新构建游戏”，本地 Maker MCP 应调用 `maker_build_current_directory` 转发到远端 `build` tool。
+- 如果用户直接说“构建 / build / 重新构建游戏”，本地 Maker MCP 应调用 `maker_build_current_directory`。该工具会强制检查本地 Maker 项目是否有未提交改动。
+- 如果构建前发现本地有改动且尚未保存自动提交偏好，工具会停止并提示用户选择：`提交本地改动并触发构建（以后都是如此）`，或明确不提交、只构建云端已有版本。
+- 用户选择 `提交本地改动并触发构建（以后都是如此）` 后，应调用 `maker_submit_current_directory` 并传入 `remember_build_submit_preference=true`；提交成功后会在当前项目 `.maker-mcp/config.json` 记住偏好。
+- 保存偏好后，后续用户说“构建”且本地有改动时，`maker_build_current_directory` 会默认自动提交并依赖 Maker 自动构建，不再重复询问。
+- 只有当用户明确说“不提交 / 直接构建云端版本”时，才可再次调用 `maker_build_current_directory` 并传入 `confirm_remote_build_without_submit=true`。
+- 用户说“查看结果 / 预览 / 跑一下 / 验证一下 / 看看效果”时，也按构建流程处理；如果本地有改动，先提醒提交后自动构建。
+- 构建转发会从 MCP 包自身定位 `dist/proxy.js`；`cwd` / `target_dir` 只用于识别 Maker 游戏项目，不要求游戏目录存在 MCP 的 `dist/proxy.js`。
+- 用户未指定构建入口且本地存在 `scripts/main.lua` 时，Maker MCP 默认向远端 build 传 `scriptsPath="scripts"` 和 `entry="main.lua"`，避免第一次构建多一轮“入口配置缺失”的提示；用户显式传入口或多人入口时优先生效。
 - 如需在当前游戏项目里直接暴露远端全量 `taptap-proxy` tools，再使用 `maker_configure_remote_proxy` 写入 `.mcp.json` 并重启 MCP 会话。
-- 用户说“帮我提交/提交代码”时使用 `maker_submit_current_directory`，会对当前 Maker 项目执行 commit + push。
+- `maker_get_mcp_update_guide` 默认生成 `@taptap/instant-games-open-mcp@beta` 和 `taptap-maker` 的 npx 缓存更新步骤；更新后当前 MCP 会话通常不会热加载，必须重启 MCP 客户端或新开 Claude Code / Codex / Cursor 窗口，再调用 `maker_status` 验证。
+- 用户说“帮我提交/提交代码”时使用 `maker_submit_current_directory`，会对当前 Maker 项目执行 commit + push；Maker 提交成功后会自动触发构建，不需要再手动调用构建工具。
 - “帮我提交代码到maker / taptap制造 / tap制造 / tap”也应触发 `maker_submit_current_directory`。
 - Maker 项目提交不走通用 Git skill 的任务号、新分支规则；冲突时先和用户确认 pull/rebase 流程。
 - 如果 commit 已完成但 push 失败，Maker MCP 会返回 commit hash、ahead 状态、exit code、stderr/stdout 和下一步建议，便于开发期排查。
+- clone/fetch、push 和远端 build 属于慢操作；工具会尽量发送 MCP progress notification，Git 阶段会解析 stderr 百分比，最终返回会包含耗时和最近进度。
 
 Git 引导：