@taptap/instant-games-open-mcp 1.24.11 → 1.24.12

package/README.md

@@ -10,6 +10,7 @@
 - **📖 完整 API 文档** - 6 个排行榜 API + 详细代码示例
 - **⚙️ 服务端管理** - 创建/管理排行榜，自动处理 ID
 - **🎮 H5 游戏支持** - 上传、发布、状态查询
+- **📺 广告接入闭环** - 仅用于 TapTap 小游戏/H5，自动查询广告状态和广告位 ID，不与 Maker MCP 混用
 - **🧭 当前游戏 DC 能力** - 商店/评价/社区统计概览、商店快照、论坛内容、评价列表、评价点赞、官方回复
 - **🦞 OpenClaw Plugin** - 提供一个原生 OpenClaw plugin 子包，内部复用 TapTap MCP 运行时并暴露 raw JSON 工具 + bundled skill
 - **🚀 三种传输模式** - stdio（本地）、SSE（远程/实时）、HTTP（兼容）
@@ -20,6 +21,75 @@
 **NPM**: [@taptap/instant-games-open-mcp](https://www.npmjs.com/package/@taptap/instant-games-open-mcp)
 **Maker NPM**: [@taptap/maker](https://www.npmjs.com/package/@taptap/maker)
 
+## TapTap Maker 客户端插件
+
+[`plugins/taptap-maker`](plugins/taptap-maker) 是插件专属安装与下载页面。Codex 和 WorkBuddy
+插件共用独立插件版本，当前值读取 `config/maker-plugin-version.json`；内置 Maker MCP 版本读取
+`config/maker-version-policy.json`，两条版本线互不覆盖。插件内置 Maker MCP 单文件运行时、CLI、
+Skills 和排障文档，不通过 npm/npx 下载或启动 Maker。
+
+对外安装应把对应渠道的 GitHub Release 页面交给 AI，由页面中的统一安装指南选择客户端 ZIP、
+校验并执行安装前后的旧 MCP 兼容检查。下面的仓库 marketplace 命令仅用于维护者从源码验证；
+执行 `marketplace add` 前，必须用刚生成的插件 CLI 完成下文同样的安装前检查和迁移。
+
+```bash
+npm run maker:codex-plugin:prepare
+node plugins/taptap-maker/dist/maker.js plugin inspect --client codex --json
+node plugins/taptap-maker/dist/maker.js plugin migrate --client codex --confirm --json
+node plugins/taptap-maker/dist/maker.js plugin inspect --client codex --json
+codex plugin marketplace add taptap/instant-games-open-mcp --ref main \
+  --sparse .agents/plugins --sparse plugins/taptap-maker
+codex plugin add taptap-maker@taptap-maker
+node plugins/taptap-maker/dist/maker.js plugin migrate --client codex --confirm --json
+node plugins/taptap-maker/dist/maker.js plugin inspect --client codex --json
+```
+
+插件 manifest 和 marketplace 版本读取 `config/maker-plugin-version.json`；bundle 运行时身份继续读取
+`config/maker-version-policy.json`。运行 GitHub Actions 中的 `Prepare Maker Plugin Release` 会自动把
+插件 patch 加一、重新生成两端产物并创建 PR；合并后 `Publish Maker Plugin` 自动发布两份 ZIP、
+`INSTALL.md`、`SHA256SUMS` 和机器可读发布清单，不触发 npm 发布。
+
+旧用户安装插件前，先用 ZIP 解压目录或本地生成目录中的插件 CLI 执行
+`taptap-maker plugin inspect --client codex --json`。如果旧的独立 Maker MCP 仍启用，向用户说明
+已发现重复注册并直接执行
+`taptap-maker plugin migrate --client codex --confirm --json`。迁移只写入 `enabled = false`，保留
+原配置、最近备份、PAT、项目绑定和游戏文件；插件安装请求即为这次兼容迁移的授权，不再单独询问，
+重复执行也是幂等的。检查返回 `ambiguous` 时必须在安装前停止；安装完成后必须再次迁移并检查，
+只有状态为 `disabled` 或 `not_found` 才能报告插件可用。需要卸载插件并恢复旧 MCP 时，仍要先取得明确确认，再执行
+`taptap-maker plugin restore --client codex --confirm --json`。
+如果本次安装中任一次迁移实际禁用了旧注册，但插件安装或验证失败，则用同一 restore 命令自动回滚；
+回滚前先移除本次已安装的插件并确认其不再启用，不能在插件仍启用时恢复旧 MCP。原本已禁用、未找到
+或不是本次迁移的注册不恢复。安装前迁移失败时立即停止，不进入插件安装。
+
+插件模式初始化使用 `taptap-maker init --skip-mcp-install`，避免 CLI 再写一份独立 MCP 配置。
+插件更新通过插件内专用 `update-taptap-mcp` Skill 和 Codex marketplace 完成，不执行 npm/npx
+或独立 `taptap-maker upgrade`。旧 MCP 恢复前会核对迁移时记录的注册指纹，同名注册已被替换时
+保持禁用并返回 `not_owned`。插件故障上报读取插件自己的 `.mcp.json` 并验证当前 bundle；独立
+Maker MCP 仍沿用原有用户配置和 self runtime 诊断。
+
+WorkBuddy 插件是独立产物，位于
+[`plugins/workbuddy/taptap-maker`](plugins/workbuddy/taptap-maker)，通过共享的 CodeBuddy 插件
+规范聚合 Maker MCP、CLI、Skills 和两个快捷命令：
+
+```text
+/taptap-maker:create-project
+/taptap-maker:sync-project
+```
+
+两个入口都要求当前 WorkBuddy workspace 为空目录。插件启动器优先解析 WorkBuddy managed
+Node.js（包括 Windows 上未加入 PATH 的 `node.exe`），必要时才回退系统 Node.js；运行插件内
+`${CODEBUDDY_PLUGIN_ROOT}/dist/maker.js`，不依赖 npm/npx。仓库 marketplace 位于
+`.codebuddy-plugin/marketplace.json`：
+
+```text
+/plugin marketplace add <REPOSITORY_ROOT>
+/plugin install taptap-maker@taptap-maker
+/reload-plugins
+```
+
+WorkBuddy 旧独立 MCP 的迁移使用 `--client workbuddy`，只把旧注册的 `disabled` 设为 `true`，
+同时支持幂等检查和确认式恢复。插件更新通过 WorkBuddy `/plugin` 完成。
+
 ## 🦞 OpenClaw Plugin（实验中）
 
 仓库内提供了一个可独立使用的 OpenClaw plugin 子包：
@@ -51,10 +121,13 @@ Maker 本地开发独立发布为 `@taptap/maker`。首次配置推荐直接运
 npx -y @taptap/maker init
 ```
 
-CLI 负责一次性流程：Git 检查、CLI 登录、TapTap token 换取、app 列表选择、Maker Git
-clone、AI dev kit 准备、MCP 配置写入与基础验证。安装或修改 MCP 配置后，Claude Code /
-Codex / Cursor 通常需要重启会话、刷新 MCP 或新开窗口才会出现新的 MCP tools；但当前终端
-里的 CLI 初始化流程可以继续完成到 PAT 鉴权和项目绑定。
+CLI 负责一次性流程：Git 检查、Python 和 maker-lua-lsp 本地 Lua 诊断环境检查、CLI 登录、
+TapTap token 换取、app 列表选择或新建 Maker 项目、Maker Git clone、AI dev kit 准备、MCP 配置写入与基础验证。Python 环境准备连续 3 次失败时，
+初始化会暂停在登录、项目拉取和 MCP 配置之前；修复后重新运行 `taptap-maker init`。首次安装，或 Maker MCP 包/
+静态工具 schema 发生变化后，Claude Code / Codex / Cursor / Trae / OpenCode / WorkBuddy 通常需要重连或刷新一次 MCP，
+才能加载新的 MCP tools；DeepSeek Harness（DSH）会监听用户补丁并热重载，不要求重启 IDE。单纯绑定或切换 Maker 项目
+不会修改用户级 MCP 配置，也不需要重启会话或新开对话。当前终端里的
+CLI 初始化流程可以继续完成到 PAT 鉴权和项目绑定。
 
 常用 CLI：
 
@@ -63,49 +136,189 @@ taptap-maker init
 taptap-maker login
 taptap-maker doctor
 taptap-maker apps --json
-taptap-maker install --ide codex,cursor,claude
+taptap-maker install
+taptap-maker agents update
+taptap-maker upgrade
 taptap-maker mcp verify
+npx -y --package @taptap/maker@<exact-version> taptap-maker mcp report --ide <client> --target-dir <project> --context-stdin --consent --json
 taptap-maker dev-kit update
 ```
 
+普通初始化、clone、下载或拉取远端项目的标准命令是 `taptap-maker init`，CLI 会展示 app 列表，
+让用户选择已有 app 或 `0`/`new`。`--create` 只用于用户明确要求创建新 Maker 项目的场景。
+如果需要创建新 Maker 项目，仍从 `taptap-maker init` 进入。app 列表底部会固定显示
+`0. Create a new Maker project`，输入 `0` 或 `new` 后填写项目名称；自动化场景可用
+`taptap-maker init --create --name "my-local-game"`。当前目录已绑定 Maker 项目时，不允许在同一目录
+创建并覆盖绑定；请先切到一个新的独立目录再运行 `taptap-maker init`。
+
 `taptap-maker login` 是 CLI 登录入口；它会按需打开 Maker 授权页，CLI 轮询授权结果并完成本地鉴权配置。
 `taptap-maker init` 缺 PAT 时会自动进入该流程。`taptap-maker pat set` 保留为兼容入口；
 自动化场景可用 `--pat-stdin` 从标准输入读取。`taptap-maker install` 是
-`taptap-maker mcp install` 的快捷别名，二者都会写入 AI 客户端 MCP 配置。
+`taptap-maker mcp install` 的快捷别名。二者都会先用最终启动命令完成 MCP
+`initialize` 和 `tools/list`，验证成功后才写入 AI 客户端 MCP 配置；失败不会改动配置或备份。
+默认 launcher 会把当前精确版本的 Maker bundle、skills 和排障文档复制到用户 Maker 目录下的
+版本化 `mcp-runtime`，配置使用绝对 Node 路径直接启动，不依赖 npx 缓存、网络或客户端 PATH。
+只有明确需要 npm 启动链路时才使用 `--launcher npx`；该模式固定当前包版本并使用专用可写缓存。
+`taptap-maker init` 写入多个客户端配置时会继续尝试其余目标；只要任一目标失败，init 就记录
+`mcp_install_failed`、以非零状态结束且不报告初始化完成。已经成功写入的客户端配置会保留，
+修复失败项后重新运行 `taptap-maker install` 即可自动检测并幂等重试。
+默认会写入 Codex、Cursor、Claude，并自动检测本机已有的 Trae、OpenCode、WorkBuddy、DSH
+配置文件；命中后会合并安装 `taptap-maker`。Trae Solo 是重点支持目标，CLI 会在 Solo
+或 Solo CN 的 `User/` 目录存在时创建或合并 `User/mcp.json`；普通 Trae/Trae CN 仍作为
+候选路径保留，但只有 `mcp.json` 已存在时才合并写入。WorkBuddy 在 macOS 和 Windows 都优先检测
+并合并用户目录下已有的 `.workbuddy/mcp.json`。legacy `.workbuddy/.mcp.json` 仅在官方配置文件不存在且
+自身已存在时作为 fallback 合并；写入的 WorkBuddy MCP server 会包含 `disabled: false`。
+WorkBuddy 账号维度的启用/信任状态在 `.workbuddy/connectors/<account-id>/connector-states.json`
+中维护，不在 `mcp.json` 中；CLI 只做只读诊断，并在安装结果中提示用户到 WorkBuddy MCP 设置里
+启用/信任 `taptap-maker`，不会自动修改账号信任状态。
+普通 `doctor` 不会因为发现 `.workbuddy` 就输出 WorkBuddy 诊断。OpenCode 只在
+`~/.config/opencode/opencode.jsonc` 已存在时写入。
+DSH 使用 `@deepseek-ai/dsh-mcp-client` 插件，不使用 `mcp.json`。检测到 `$DSH_HOME`
+（默认 `~/.dsh`）后，普通 `taptap-maker install` 会自动创建或合并用户级 `cordis.patch.yml`，
+写入稳定 self launcher、`failOnStartupError: true` 和 1 小时 `toolCallTimeoutMs`，并保留其它插件。
+新增项使用 DSH Cordis `insert` patch；若已经存在 profile 级 Maker registration，CLI 会就地更新
+对应 profile，避免全局和 profile 出现重复 `serverName`。
+默认 home 级补丁适用于 DSH 的不同 profile；检测到已有 profile 级注册时则只更新对应 profile。
+两者都可由 DSH HMR 热重载。配置不写项目 `cwd`；DSH 当前
+不广播 MCP Roots，因此 AI 必须在具体 Maker tool 调用中把当前游戏项目作为 `target_dir` 传入。
+需要把 Maker 技能（工作流 + 广告/云存档/排行榜指南）一并打包进 DSH 时，可用 bundle 插件
+`@taptap/dsh-maker`（源码 `packages/dsh-maker/`），通过 1024Store 对应的公开 npm 包一键安装，
+详见 [docs/DSH_PLUGIN.md](docs/DSH_PLUGIN.md)。稳定版从 npm 获取；`dsh-maker-v*` GitHub Release
+继续提供预览版和离线安装 tarball。该插件与 L1 的裸 MCP 行不要同时启用。
+其它 AI 编辑器应优先让本地 AI 复用 `taptap-maker mcp install` 已验证的绝对 command/args。
+只有无法复用安装器时，才使用下面固定精确版本的 npx 兼容片段：
+
+```json
+{
+  "mcpServers": {
+    "taptap-maker": {
+      "command": "npx",
+      "args": ["-y", "-p", "@taptap/maker@<exact-version>", "taptap-maker"]
+    }
+  }
+}
+```
+
+TapTap Maker 的用户配置不需要设置服务环境。预览、构建、测试二维码和本地开发都使用官方服务配置。
+
+`taptap-maker init`、`mcp install` 和 `upgrade` 写入的用户级 MCP 配置永远不包含项目 `cwd`，
+避免多个客户端、对话或 Maker 项目争用同一个全局路径。支持 MCP Roots 的客户端会用当前
+workspace root 识别项目；不支持 Roots 时，由 Agent 在具体 Maker tool 调用中传入 `target_dir`。
+MCP 进程自身的 cwd 只作为最后兜底和诊断信息，不应通过重写用户配置来切换项目。
+若 cwd fallback 没有绑定项目，Maker MCP 仍正常启动并保留 status/tools/list，但项目相关 proxy tool
+会快速失败，明确返回实际评估目录和上下文来源，避免把其它目录的 `not_initialized` 当成当前项目状态。
+安装器会先比较现有 `taptap-maker` 条目；内容一致时不写文件，Claude 也不会重复执行
+`claude mcp add`。因此后续项目 `init` 或无配置变化的 `upgrade` 不会触发配置重载。
+从旧 beta 升级时，安装器会移除现有 `taptap-maker` 条目中的历史 `cwd`，同时保留配置里的
+其它 MCP server；这次必要迁移完成后，切换项目不再修改用户级配置。
+`taptap-maker upgrade` 会刷新当前机器的 Maker MCP 配置，并在当前目录已绑定 Maker 项目时
+同步项目 `AGENTS.md` 的 TapTap Maker 受管策略块。`maker://status`、`maker_status_lite`
+和 `taptap-maker doctor` 会检查老项目 `AGENTS.md` 是否缺失或过期，并提示运行
+`taptap-maker agents update` 或 `taptap-maker upgrade`。
 `taptap-maker dev-kit update` 会检查当前环境可用的最新 AI dev kit 并更新当前目录。
 
+如果 Maker MCP tools 缺失或出现 `-32000` / `Connection closed`，先按
+[TapTap Maker MCP 本地连接自检与修复指引](docs/MAKER_MCP_CONNECTION_TROUBLESHOOTING.md)
+检查本地客户端配置、信任状态、cwd、Node/npm/npx 和启动日志。MCP 未连接时不要依赖 MCP tools 自检。
+
+如果证据指向 Maker MCP、proxy、客户端集成或服务端基础设施异常，`taptap-maker-local` Skill
+会在当前会话对同一种故障只询问一次是否上报。用户同意后，AI 才通过 stdin 调用
+上报优先复用当前客户端 Maker MCP 配置中的原始 command 和有序 args，并追加
+`mcp report --ide <client> --target-dir <project> --context-stdin --consent --json`。只有确认当前精确版本时才 fallback 到
+`npx -y --package @taptap/maker@<exact-version> taptap-maker mcp report ...`，不要使用无版本包名误启 npm `latest`；
+Windows 无法从 PATH 找到 `npx` 时继续使用配置中的绝对 `node.exe` 和 `npm-cli.js`，
+收集当前客户端的 Maker 配置项、MCP launcher 验证、项目上下文和已脱敏的会话错误，并尽力创建
+GitHub Issue。报告不包含完整聊天、项目源码、其它 MCP server、PAT/token 或完整环境变量；用户主目录
+统一显示为 `~`。GitHub 不可达、未登录或提交失败时返回 `manual_required`，AI 会展示脱敏报告和手动
+Issue 地址，然后继续原任务，不把上报失败当作 Maker 故障。
+
 Maker MCP 精简为开发循环里的高频能力：
 
 ```text
 maker://status                  # Resource，读取本地 Maker 状态
+maker://ads-integration-guide   # Resource，广告接入入口与项目引擎文档索引
 maker_status_lite               # Resource 不可用时的兼容 tool
 maker_build_current_directory   # commit/push/build 合并入口
 ```
 
-`maker_build_current_directory` 同时覆盖“构建 / 预览 / 跑一下 / 验证一下 / 提交 / 推送”。
+Maker MCP 初始化时会通过标准 `initialize.instructions` 向 AI 客户端提供一份精简能力路由，
+标出状态、构建、Tap 流程和游戏资源生成入口。新项目初始化或执行
+`taptap-maker agents update` / `taptap-maker upgrade` 时，同一份路由也会写入目标 Maker
+项目 `AGENTS.md` 的受管策略块，供后续会话继续使用；用户自己编写的内容保持不变。升级
+`@taptap/maker` 后，当前 MCP 会话不会被 `taptap-maker upgrade` 主动中断，已有 proxy tools
+继续可用；新版本和新的初始化提示会在下一次 MCP 启动或用户主动 reconnect 后生效。
+
+在已绑定 Maker 项目中，`maker_build_current_directory` 同时覆盖“构建 / 预览 / 跑一下 /
+查看结果 / 看看效果 / 验证游戏效果 / 提交 / 推送”。普通“验证代码 / 跑测试 / lint /
+检查实现”不应自动触发 Maker 远端构建，除非用户明确要求构建、运行或预览 Maker 游戏。
 普通构建会先 push 到 Maker 远端再触发远端 build：本地有改动时提交改动，已有未推送 commit 时
 直接 push，本地干净且没有未推送 commit 时创建 `chore: wake maker build server` 空提交来唤醒远端
 服务。push 失败时不会继续 build，会返回本地 commit、ahead 状态、stderr/stdout 和下一步建议，
 交给本地 Agent/skill 处理 pull、rebase 或冲突；push 成功但 build 失败时，会明确说明代码已到
 Maker 远端但构建失败。只有用户明确说“不提交，只构建云端版本”时，才传
-`confirm_remote_build_without_submit=true`；该模式会先打开并返回 Maker 页面链接，方便用户查看远端
-项目并避免服务休眠导致构建失败。
+`confirm_remote_build_without_submit=true`；该模式只构建 Maker 远端已提交版本，不会自动打开
+Maker 页面。
+
+`code_submit` 或无法分类的构建执行失败会附带 `local_execution_check`，提醒检查 Windows PowerShell、
+CLI、Git 或 MCP 命令是否被 AI 客户端沙盒拦截。只有明确的本地 PowerShell/进程拦截证据才会标记
+`restriction_signal: detected`；远端 Git 返回的 `sandbox` 文本不会被当成本地信号。远端构建失败
+优先检查代码和资源诊断，只有本地命令也被拦截时才检查沙盒；已知项目配置、鉴权/上下文或结构错误
+不提示 Full Access。
+Maker MCP 无法读取客户端访问模式，因此该检查不是根因结论。可信项目可开启 Full Access
+（“完全访问模式”）、重连 MCP 后再重试本地命令。
+本地 Tap auth 或 `user_id` 上下文准备失败会返回 `failure_stage: local_build_context` 和
+`remote_build_status: not_started`，应直接按 login/init 提示恢复，不会描述成远端构建失败。
+
+远端 Lua/LSP 编译失败属于构建业务错误，MCP 会以工具结果 `isError: true` 返回，并在
+`content`/`remote_result` 中保留原始诊断（包括文件、行号和编译器消息）。只有连接断开、会话失效等
+传输故障才使用 MCP 协议错误；排查构建失败时应优先查看工具结果中的 `remote_result`，不要把
+`-32603` 直接当作服务不可用。Maker 本地重试只针对连接类故障；带结构化 `remote_result` 的业务错误
+不会重复发起构建。明确的 proxy unavailable、连接关闭、请求超时和 HTTP 5xx 会按退避策略重试；
+重连后重放请求若再次断线，会保留未完成队列并继续下一轮重连。
 
 构建成功后，Maker MCP 会刷新 Maker Web 预览，并启动本地 runtime log watcher。后续如果用户询问
 游戏运行结果、Lua 报错或调试问题，本地 AI Agent 应优先读取构建返回中的
 `runtime_logs.local_file`；如需判断 watcher 是否正常，读取 `runtime_logs.state_file`。
 
-Maker MCP 也提供部分生成类能力，当前包括 `generate_image`、`batch_generate_images`、
-`edit_image`、`create_video_task` 和 `text_to_music`；具体参数以 MCP 客户端展示的 tool
-schema 为准。代理转发和白名单细节见 [TapTap Maker 本地开发](docs/MAKER.md)。
-
-Windows 是默认优先级：CLI 写 MCP 配置时会在 Windows 使用 `npx.cmd`，Git 引导优先提示
-Git for Windows，并要求安装选项允许命令行和第三方工具通过 PATH 找到 Git。macOS 用户可通过
-`git --version` 触发 Xcode Command Line Tools，或安装官方 Git。
+Maker MCP 也提供部分远端 proxy 能力，当前包括 `generate_image`、`batch_generate_images`、
+`edit_image`、`create_video_task`、`query_video_task`、`text_to_music`、
+`text_to_sound_effect`、`batch_sound_effects`、`text_to_dialogue`、
+`audition_voices_for_character`、`confirm_character_voice`、`create_3d_asset`、
+`generate_test_qrcode`、`add_test_whitelist`、`get_ad_config` 和 `get_debug_feedbacks`；具体参数以 MCP 客户端展示的
+tool schema 为准。
+这些 proxy tools 为 Maker 项目提供素材生成和平台工作流能力；其中 `get_debug_feedbacks` 会拉取线上玩家反馈，
+并在可下载附件存在时保存日志和截图到当前 Maker 项目的 `logs/feed_back/feedback_<id>/`，
+返回 `local_dir` / `local_log_paths` / `local_screenshot_paths` 等本地路径。代理转发、错误透出和白名单细节见
+[TapTap Maker 本地开发](docs/MAKER.md)。
+`create_video_task` 仅响应用户明确的视频生成请求；长于 10 秒或使用 Seedance 2.5 时，会先返回积分粗估，
+用户明确确认后才携带 `user_confirmed=true` 创建任务。
+音频 tools 支持音效、角色试听、音色确认和配音；生成音频以及确认后的参考音频会保存到
+当前本地 Maker 项目。
+
+生成测试二维码时，Agent 应先直接调用 `generate_test_qrcode`。如果 `.project/project.json` 已有
+`taptap_publish.screen_orientation`，本地 MCP 会直接沿用，不能重复设置，也不应再次询问用户。只有该字段
+从未设置时，Agent 才必须单独询问用户选择横屏（`landscape`）或竖屏（`portrait`），并在重试时通过本地私有参数
+`confirmed_screen_orientation` 传入首次选择；本地 MCP 会写入该值，且不会转发给远端 proxy tool。
+二维码生成并建立应用身份后，可使用
+`add_test_whitelist` 将用户明确提供的 TapTap `user_id` 加入测试白名单。
+
+Windows 是默认优先级：CLI 只把当前进程可用的绝对 `node.exe` 与 `npm-cli.js` 写入所有
+客户端配置；找不到该组合时安装失败，不会持久化 `.cmd` shell 命令或依赖客户端 PATH 的裸
+`npx.cmd`。OpenCode 使用相同已验证 launcher 的 command 数组。用户级 MCP 配置不会写入项目
+目录，也禁止生成 `cd && npx.cmd`；Git 引导优先提示 Git for Windows，
+并要求安装选项允许命令行和第三方工具通过 PATH 找到 Git。macOS 用户可通过 `git --version`
+触发 Xcode Command Line Tools，或安装官方 Git。
 
 详见：[TapTap Maker 本地开发](docs/MAKER.md)。面向团队介绍的功能总览见
 [Maker CLI + MCP + Skill Rework Overview](docs/MAKER_CLI_MCP_SKILL_REWORK_OVERVIEW.md)。
 
+本地 Maker MCP 会透明上报本地开发活跃事件，复用 `tapmaker_mcp_call` 并在
+`args.source` 写入 `local_mcp`，在 `args.mcp_version` 写入当前 `@taptap/maker`
+版本；普通开发构建使用 `dev`，不会使用主包版本代替。事件只使用当前绑定项目配置中的
+`user_id` 和 `project_id`；任一关键字段缺失或项目上下文无法准确解析时跳过上报，不使用
+默认值或其它账号信息代替。Tool、`maker://status` Resource 和 MCP 启动事件均可作为
+活跃行为，上报失败不会影响 MCP 工具结果。
+
 ## 🧩 Codex Skills（运营简报）
 
 本仓库内置一个面向运营/工作室的 Codex Skill：`taptap-dc-ops-brief`，用于把“当前游戏 DC 数据”整理成 30 秒可读的结论简报，并在你确认后执行评价点赞/官方回复等动作。
@@ -338,7 +551,8 @@ npm test
 
 ### Maker 本地开发预览
 
-Maker 本地开发现在以 CLI-first 为准。初始化、PAT、app 选择、dev-kit 和 clone 都走 CLI；MCP 只保留状态和同步构建：
+Maker 本地开发现在以 CLI-first 为准。初始化、PAT、app 选择/创建、dev-kit 和 clone 都走 CLI；MCP
+保留状态、同步构建和审核过的 proxy tools：
 
 ```text
 taptap-maker init
@@ -350,11 +564,45 @@ maker_status_lite
 maker_build_current_directory
 ```
 
-`taptap-maker doctor` 会检查 Git、PAT、TapTap token、项目绑定、AI dev kit 版本和 MCP 配置。若 Git 不可用，clone/push 会直接停止，直到用户自行安装 Git 并通过 `git --version` 验证。
-`taptap-maker mcp verify` 默认跑一次实际 MCP 配置使用的 npx 包命令；本地 dist 自测可用 `--mode self`。如果失败结果显示 `failure_type` 或 `status: null`，优先按本地 Node/npm/npx 启动问题处理，Maker MCP server 此时尚未启动，不要误判为 PAT 或 Maker 服务报错。
+远端 proxy tools 使用版本化的本地完整定义在首次 `tools/list` 时立即注册，不等待 cwd、Maker 项目绑定、
+PAT/TapTap token 或远端 proxy 连接。项目定位和鉴权只在实际调用 tool 时校验；远端 schema 不会在运行时
+替换本地定义。schema 变更通过本地 MCP 版本更新发布，远端不可用不会让 proxy tools 从当前会话消失。
+Maker 内嵌代理不打开可选的 standalone SSE GET，远端 RPC 响应和构建进度统一通过 POST SSE 返回；
+这避免 Node.js 26 中长连接占用后续 `tools/list` 请求而触发固定 60 秒超时。普通 MCP Proxy 默认仍保留
+standalone SSE，只有显式设置 `disable_standalone_sse` 才会关闭。
+
+`taptap-maker doctor` 会检查 Git、Python 环境、maker-lua-lsp、PAT、TapTap token、项目绑定、
+AI dev kit 版本和 MCP 配置。`maker://status` 和 `maker_status_lite` 会输出
+`MCP client roots` 与 `project_context_source`，用于确认当前项目来自客户端 workspace roots
+还是 MCP cwd fallback。默认 status 只输出快速本地摘要；需要远端同步、proxy、dev-kit 或完整维护
+诊断时，调用 `maker_status_lite({ detail: true })`。若 Git 不可用，clone/push 会直接停止，直到用户自行安装 Git 并通过
+`git --version` 验证。
+已绑定项目还会执行轻量的统一项目结构检查：分别检查 `.project/project.json`、
+`.project/resources.json`、`.project/settings.json`，识别实际存在的配置被 AI 写坏或移动到项目根目录、
+以及已知 `assets/project.json` 错位的情况。根目录候选只有在匹配 Maker `$schema` 或完整的
+`project.json` 发布字段组合时才会判定为错位；普通同名业务文件不会阻断构建。`.project` 目录
+是否存在不代表项目已经初始化；目录为空、只含本地音色 mapping/其它辅助文件，或主配置不完整时，
+项目保持 `not_initialized` 且允许显式构建。`dist` 是构建产物，不参与源配置有效性判断。
+构建会在 commit/push 前阻断实际存在配置的明确路径或 JSON 错误，`generate_test_qrcode`、
+`get_ad_config` 和测试白名单会在远端调用前检查主配置，但不会自动搬运或覆盖本地文件。
+健康检查本身保持只读；需要修复时，AI 应优先从 Git 或完整的错位副本恢复文件。只有在
+`settings.json` 仍是可解析 object 时，才可恢复 `$schema` 和构建固定字段（资源 tag 仅从完整副本恢复），
+并保留 `@runtime` 与未知字段；不要凭默认值重建 `project_id`、入口、版本、发布信息或资源分组。
+在用户确认后，可以只补入缺失且不会覆盖意图的 settings 默认字段：`output_dir=../dist`、
+`asset_dirs=["../assets","../scripts"]`、`generate_fs_path=true`、`asset_ignores=[]`，
+以及 schema 中的 `assets_7z_threshold=50`、`preload_include_refs=true`、
+`trim_remote_refs=true`、`legacy_binary=false`、`tags={}`；已有非默认值不得覆盖。
+`sources.*.tag`、项目身份、版本、入口、发布信息和 resources 分组只允许从完整副本恢复。
+`taptap-maker mcp verify` 默认使用安装器的稳定 self runtime 完成 MCP `initialize` 和
+`tools/list`；显式 `--mode npx` 才验证精确版本 npm launcher。失败结果会标明 `stage`、`failure_type`、
+最终 command 和 stderr，并返回非零退出码；不要把本地启动或 stdio 握手失败误判为 PAT 或
+Maker 业务接口错误。
 
 测试时优先运行 `taptap-maker login`；CLI 会按需打开 Maker 授权页，授权完成后自动完成本地鉴权配置。
-当前目录未绑定时，APP_ID 应通过 `taptap-maker init` 或 `taptap-maker apps` 返回的 app 列表让用户选择；当前目录已绑定时不要再次引导 clone。
+当前目录未绑定时，APP_ID 应通过 `taptap-maker init` 或 `taptap-maker apps` 返回的 app 列表让用户选择；
+创建新项目时使用 `taptap-maker init` 列表底部的 `0. Create a new Maker project`，或运行
+`taptap-maker init --create --name "my-local-game"`；checkout 完成后会补齐 `assets/image`、
+`assets/sprites`、`assets/video`、`assets/audio` 和 `scripts` 基础目录；当前目录已绑定时不要再次引导 clone 或创建新项目。
 
 ```bash
 npm run build
@@ -494,6 +742,16 @@ graph LR
 - **[docs/PROXY.md](docs/PROXY.md)** - MCP Proxy 开发指南（面向 TapCode 等平台）
 - **[docs/PATH_RESOLUTION.md](docs/PATH_RESOLUTION.md)** - 路径解析系统
 
+## Maker 持久化 Proxy 与多项目
+
+Maker MCP 在本地 server 进程内按活动项目维护一个 embedded proxy 和远端 MCP session。
+多个本地 Maker 项目可以并行使用，项目、环境和授权上下文彼此隔离；一个项目断线只会
+触发该项目的自动恢复，不需要重新安装或重启 Maker MCP。MCP 包版本升级或本地 proxy
+工具白名单/schema 变化后，需要重新连接本地 MCP 以加载新的本地定义。同项目认证或环境变化时，新连接立即接管，
+旧连接会在已开始的请求结束后关闭，不会中断正在执行的构建或远端工具。proxy tools 不依赖运行时
+`tools/list_changed` 刷新。runtime-log watcher 保持独立的
+轮询连接生命周期，不与远端 proxy session 共享。
+
 ## 🤝 贡献
 
 欢迎贡献！请遵循：