@taptap/instant-games-open-mcp 1.23.7-beta.1 → 1.23.7-beta.3

package/README.md

@@ -133,9 +133,9 @@ Maker 现在同时内置三个工作流 skill：
 
 初始化流程里，PAT 验证通过、用户选择 app 后，`taptap-maker init` 会自动准备本地 AI dev kit。
 
-CLI 会根据 `TAPTAP_MCP_ENV` 自动选择下载源：`production`（默认）使用 `https://urhox-demo-platform.spark.xd.com/ai-dev-kit/pd/stable/ai-dev-kit.zip`，`rnd` 使用 `https://urhox-demo-platform.spark.xd.com/ai-dev-kit/rnd/latest/ai-dev-kit.zip`，解压开发环境文档、引擎 API、demo 和本地 AI skills 到当前目录；会跳过 ZIP 里的顶层 `scripts` 目录并删除下载 ZIP，避免和 Maker 项目代码冲突。clone 前会先生成 `.gitignore.dev-kit-before-clone` 临时 block，clone 成功后自动合并到远端 `.gitignore`，防止这些本地开发环境文件和 `.maker/` 本地运行状态被提交到 Maker Git。
+CLI 会根据 `TAPTAP_MCP_ENV` 自动选择下载源：`production`（默认）使用 `https://urhox-demo-platform.spark.xd.com/ai-dev-kit/pd/stable/ai-dev-kit.zip`，`rnd` 使用 `https://urhox-demo-platform.spark.xd.com/ai-dev-kit/rnd/latest/ai-dev-kit.zip`，解压开发环境文档、引擎 API、demo、Lua 工具和本地 AI skills 到当前目录；解压复制完成后会自动运行 `tools/install-skills.sh all`（Linux/macOS）或 `tools/install-skills.ps1 all`（Windows），把 dev kit skills 安装到各 Agent 的发现目录。CLI 会先输出 `AI skills install started: <script>`，完成后输出 `AI skills install result: claude=N, codex=N, cursor=N, gemini=N`；脚本缺失、跳过或失败时也会输出原因，失败会带上平台、脚本、命令、stdout 和 stderr，方便 AI 与用户直接判断安装情况。流程会跳过 ZIP 里的顶层 `scripts` 目录并删除下载 ZIP，避免和 Maker 项目代码冲突。clone 前会先生成 `.gitignore.dev-kit-before-clone` 临时 block，clone 成功后自动合并到远端 `.gitignore`，防止这些本地开发环境文件、Agent skill 目录和 `.maker/` 本地运行状态被提交到 Maker Git。
 
-`maker://status` 和 `maker_status_lite` 会输出已随包内置的 skill 名称和文档路径：`taptap-maker-local`、`taptap-maker-dev-kit-guide` 与 `update-taptap-mcp`。Maker 操作目标是用户当前项目目录；若 MCP 进程 cwd 是临时对话目录，Agent 应把用户当前项目目录作为 `target_dir` 传入，不扫描其他项目。已绑定项目会检查 `CLAUDE.md`、`examples/`、`templates/`、`urhox-libs/`，缺失时用 `taptap-maker dev-kit update` 恢复本地 AI dev kit 并刷新 `.gitignore` 管理块。
+`maker://status` 和 `maker_status_lite` 会输出已随包内置的 skill 名称和文档路径：`taptap-maker-local`、`taptap-maker-dev-kit-guide` 与 `update-taptap-mcp`。Maker 操作目标是用户当前项目目录；若 MCP 进程 cwd 是临时对话目录，Agent 应把用户当前项目目录作为 `target_dir` 传入，不扫描其他项目。已绑定项目会检查 `CLAUDE.md`、`examples/`、`templates/`、`urhox-libs/`，并输出 `skill_install_status` 和 `skill_install_summary` 说明 `.claude/.codex/.cursor/.gemini` 下的 skill 安装状态；缺失时用 `taptap-maker dev-kit update` 恢复本地 AI dev kit 并刷新 `.gitignore` 管理块。
 
 Git 引导：
 

package/dist/maker.js

@@ -28814,14 +28814,24 @@ var DEV_KIT_GITIGNORE_STAGING_FILE = ".gitignore.dev-kit-before-clone";
 var DEV_KIT_REQUIRED_ENTRIES = ["CLAUDE.md", "examples", "templates", "urhox-libs"];
 var ALWAYS_IGNORED_LOCAL_ENTRIES = [".DS_Store", ".maker"];
 var DEV_KIT_MANAGED_ENTRY_CANDIDATES = [
+  ".claude",
+  ".cli",
+  ".codex",
+  ".cursor",
   ".emmylua",
+  ".gemini",
+  "AGENTS.md",
   "CLAUDE.md",
   "engine-docs",
   "examples",
+  "schemas",
+  "skills",
   "templates",
+  "tools",
   "urhox-libs"
 ];
 var SKIPPED_TOP_LEVEL_ENTRIES = /* @__PURE__ */ new Set(["scripts", ".DS_Store", "ai-dev-kit.zip"]);
+var SKILL_INSTALLER_OUTPUT_ENTRIES = [".claude", ".codex", ".cursor", ".gemini"];
 function inspectAiDevKit(targetDir) {
   const resolvedTargetDir = path4.resolve(targetDir);
   const presentEntries = DEV_KIT_REQUIRED_ENTRIES.filter(
@@ -28862,15 +28872,43 @@ async function installAiDevKit(options = {}) {
     });
     installedEntries.push(entry.name);
   }
+  const skillInstaller = runDevKitSkillInstallerForInstall(targetDir, {
+    onStart: options.onSkillInstallerStart
+  });
   const stagedGitignorePath = path4.join(targetDir, DEV_KIT_GITIGNORE_STAGING_FILE);
-  writeDevKitStagedGitignore(stagedGitignorePath, installedEntries);
+  writeDevKitStagedGitignore(stagedGitignorePath, [
+    ...installedEntries,
+    ...listPresentSkillInstallerOutputEntries(targetDir)
+  ]);
   return {
     targetDir,
     sourceDir,
     installedEntries: installedEntries.sort(),
     skippedEntries: skippedEntries.sort(),
     gitignorePath: path4.join(targetDir, ".gitignore"),
-    stagedGitignorePath
+    stagedGitignorePath,
+    skillInstaller
+  };
+}
+function inspectAiDevKitSkillInstallStatus(targetDir) {
+  const resolvedTargetDir = path4.resolve(targetDir);
+  const targets = SKILL_INSTALLER_OUTPUT_ENTRIES.map((entry) => {
+    const skillsDir = path4.join(resolvedTargetDir, entry, "skills");
+    const present = fs3.existsSync(skillsDir) && fs3.statSync(skillsDir).isDirectory();
+    const skillCount = present ? fs3.readdirSync(skillsDir, { withFileTypes: true }).filter((item) => item.isDirectory() || item.isSymbolicLink()).length : 0;
+    return {
+      name: entry.replace(/^\./, ""),
+      path: skillsDir,
+      present,
+      skillCount
+    };
+  });
+  const installedCount = targets.filter((target) => target.present && target.skillCount > 0).length;
+  const status = installedCount === targets.length ? "installed" : installedCount > 0 ? "partial" : "missing";
+  return {
+    status,
+    summary: targets.map((target) => `${target.name}=${target.skillCount}`).join(", "),
+    targets
   };
 }
 function createDevKitGitignoreBlock(entries) {
@@ -28927,6 +28965,87 @@ function copyEntry(source, target, options = {}) {
     fs3.copyFileSync(source, target);
   }
 }
+function installAiDevKitSkills(targetDir, options = {}) {
+  var _a2;
+  const toolsDir = path4.join(targetDir, "tools");
+  if (!fs3.existsSync(toolsDir) || !fs3.statSync(toolsDir).isDirectory()) {
+    return {
+      ok: false,
+      status: "skipped",
+      stdout: "",
+      stderr: "",
+      summary: "skipped: tools directory not found",
+      reason: "tools_not_found"
+    };
+  }
+  const isWindows = process.platform === "win32";
+  const scriptName = isWindows ? "install-skills.ps1" : "install-skills.sh";
+  const scriptPath = path4.join(toolsDir, scriptName);
+  if (!fs3.existsSync(scriptPath)) {
+    return {
+      ok: false,
+      status: "skipped",
+      script: scriptPath,
+      stdout: "",
+      stderr: "",
+      summary: `skipped: ${scriptName} not found`,
+      reason: "script_not_found"
+    };
+  }
+  const command = isWindows ? ["powershell.exe", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", scriptPath, "all"] : ["bash", scriptPath, "all"];
+  (_a2 = options.onStart) == null ? void 0 : _a2.call(options, {
+    platform: process.platform,
+    script: scriptPath,
+    cwd: toolsDir,
+    command
+  });
+  const result = spawnSync2(command[0], command.slice(1), { cwd: toolsDir, encoding: "utf8" });
+  if (result.status !== 0) {
+    throw new AiDevKitSkillInstallerError(
+      formatFailedSkillInstallerResult({
+        platform: process.platform,
+        scriptPath,
+        toolsDir,
+        command,
+        result
+      })
+    );
+  }
+  const stdout = String(result.stdout || "");
+  const stderr = String(result.stderr || "");
+  return {
+    ok: true,
+    status: "installed",
+    script: scriptPath,
+    stdout,
+    stderr,
+    summary: summarizeSkillInstallerOutput(stdout)
+  };
+}
+function runDevKitSkillInstallerForInstall(targetDir, options = {}) {
+  try {
+    return installAiDevKitSkills(targetDir, options);
+  } catch (error2) {
+    if (error2 instanceof AiDevKitSkillInstallerError) {
+      return error2.result;
+    }
+    const message = error2 instanceof Error ? error2.message : String(error2);
+    return {
+      ok: false,
+      status: "failed",
+      stdout: "",
+      stderr: "",
+      summary: "failed",
+      reason: "installer_failed",
+      error: message
+    };
+  }
+}
+function listPresentSkillInstallerOutputEntries(targetDir) {
+  return SKILL_INSTALLER_OUTPUT_ENTRIES.filter(
+    (entry) => fs3.existsSync(path4.join(targetDir, entry))
+  );
+}
 async function downloadAndExtractDevKit(url2) {
   const tempDir = fs3.mkdtempSync(path4.join(os3.tmpdir(), "taptap-maker-ai-dev-kit-"));
   const zipPath = path4.join(tempDir, "ai-dev-kit.zip");
@@ -29003,6 +29122,67 @@ function formatSpawnFailure(result) {
   var _a2;
   return ((_a2 = result.error) == null ? void 0 : _a2.message) || String(result.stderr || "").trim() || String(result.stdout || "").trim() || `exit status ${result.status ?? "unknown"}`;
 }
+function formatDevKitSkillInstallerFailure(options) {
+  return [
+    "Failed to install AI dev kit skills",
+    `platform: ${options.platform}`,
+    `script: ${options.scriptPath}`,
+    `cwd: ${options.toolsDir}`,
+    `command: ${options.command.map(shellQuote).join(" ")}`,
+    `exit_status: ${options.result.status ?? "unknown"}`,
+    options.result.signal ? `signal: ${options.result.signal}` : "",
+    options.result.error ? `spawn_error: ${options.result.error.message}` : "",
+    "stdout:",
+    formatSpawnOutput(options.result.stdout),
+    "stderr:",
+    formatSpawnOutput(options.result.stderr)
+  ].filter((line) => line.length > 0).join("\n");
+}
+function formatFailedSkillInstallerResult(options) {
+  return {
+    ok: false,
+    status: "failed",
+    script: options.scriptPath,
+    stdout: String(options.result.stdout || ""),
+    stderr: String(options.result.stderr || ""),
+    summary: summarizeSkillInstallerFailure(options.result),
+    reason: "installer_failed",
+    error: formatDevKitSkillInstallerFailure(options)
+  };
+}
+function summarizeSkillInstallerFailure(result) {
+  if (typeof result.status === "number") {
+    return `failed: exit_status=${result.status}`;
+  }
+  if (result.signal) {
+    return `failed: signal=${result.signal}`;
+  }
+  if (result.error) {
+    return `failed: ${result.error.message}`;
+  }
+  return "failed";
+}
+var AiDevKitSkillInstallerError = class extends Error {
+  constructor(result) {
+    super(result.error || result.summary);
+    this.result = result;
+    this.name = "AiDevKitSkillInstallerError";
+  }
+};
+function formatSpawnOutput(value) {
+  const text = String(value || "").trim();
+  return text.length > 0 ? text : "(empty)";
+}
+function summarizeSkillInstallerOutput(stdout) {
+  const entries = stdout.split(/\r?\n/).map((line) => line.match(/\[install-skills\]\s+([^:]+):\s+installed=(\d+)/)).filter((match) => Boolean(match)).map((match) => `${match[1]}=${match[2]}`);
+  return entries.length > 0 ? entries.join(", ") : "completed";
+}
+function shellQuote(value) {
+  if (/^[A-Za-z0-9_./:=@-]+$/.test(value)) {
+    return value;
+  }
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
 function resolveDevKitRoot(sourceDir) {
   const directEntries = fs3.existsSync(sourceDir) ? fs3.readdirSync(sourceDir) : [];
   if (looksLikeDevKitRoot(sourceDir)) {
@@ -29524,7 +29704,7 @@ async function inspectMakerRemoteSyncStatus(cwd) {
 }
 function getMakerRemoteSyncFailureNextAction(failure) {
   if (failure.classification === "auth") {
-    return "暂时无法检查 Maker 远端是否有新提交：Git 鉴权失败。请先运行 `taptap-maker pat set` 并粘贴新的 Maker PAT 后，再重新读取 maker://status。";
+    return `暂时无法检查 Maker 远端是否有新提交：Git 鉴权失败。PAT 页面：${getMakerPatTokensUrl()}。请在该页面创建新的 Maker PAT，然后运行 \`taptap-maker pat set\` 并粘贴 PAT 后，再重新读取 maker://status。`;
   }
   return "暂时无法检查 Maker 远端是否有新提交。请把 failure 信息反馈给用户；如果只是 503、5xx、超时或网络中断，可稍后重新读取 maker://status。";
 }
@@ -29745,7 +29925,7 @@ function nextActionForFailure(classification) {
     case "git_missing":
       return "本机未检测到可用的 Git。请用户自行安装 Git，并在 `git --version` 可用后重启 MCP 客户端再重试；安装前不要执行 clone、fetch、commit 或 push。";
     case "auth":
-      return "运行 `taptap-maker pat set` 并粘贴新的 Maker PAT 后，再重试 maker_build_current_directory；如果仍失败，请确认 PAT 是否过期或缺少 Maker git 权限。";
+      return `Maker Git 鉴权失败。PAT 页面：${getMakerPatTokensUrl()}。请在该页面创建新的 Maker PAT，然后运行 \`taptap-maker pat set\` 并粘贴 PAT 后重试。`;
     case "remote_transient":
       return "远端 Maker git 服务临时不可用。本地 commit 会保留；不要手动执行通用 git push，稍后直接重试 maker_build_current_directory。";
     case "branch_not_allowed":
@@ -30547,11 +30727,13 @@ function formatMakerSkillStatus(_options = {}) {
     path: path6.join(resolveMakerSkillSourceDir(skill.name), "SKILL.md")
   }));
   return [
-    "TapTap bundled workflow skills",
+    "TapTap Maker workflow guide documents",
     "",
     ...skillDocuments.map((skill) => `- ${skill.name}: ${skill.path}`),
     "",
-    "These skill documents are bundled in the package. Let the current AI client decide whether and how to load them."
+    "Use these documents as reading references for Maker local workflows.",
+    "Maker initialization next_step: execute `taptap-maker init`.",
+    "Load these documents when the current AI client supports reading local guide files."
   ].join("\n");
 }
 function resolveMakerSkillSourceDir(skillName = MAKER_LOCAL_SKILL_NAME) {
@@ -30951,7 +31133,7 @@ function compactRuntimeLogEntry(entry) {
 }
 
 // src/maker/server/mcp.ts
-var VERSION = true ? "1.23.7-beta.1" : "dev";
+var VERSION = true ? "1.23.7-beta.3" : "dev";
 var DEFAULT_PROXY_PACKAGE = "@taptap/instant-games-open-mcp@1.22.0";
 var DEFAULT_BUILD_TIMEOUT_MS = 10 * 60 * 1e3;
 var PREVIEW_REFRESH_TIMEOUT_MS = 15 * 1e3;
@@ -30970,7 +31152,7 @@ var MakerCloneFailedError = class extends Error {
 var tools = [
   {
     name: "maker_status_lite",
-    description: "Compatibility fallback for clients that cannot read the maker://status resource. Prefer reading maker://status when resources are available. Shows local Maker status for the user current working directory, including Git, PAT/TapTap auth, project binding, AI dev kit status, and bundled workflow skill document paths.",
+    description: "Compatibility status surface for clients using tool output instead of the maker://status resource. Prefer reading maker://status when resources are available. Shows local Maker status for the user current working directory, including Git, PAT/TapTap auth, project binding, AI dev kit status, and bundled workflow guide document paths. Maker initialization next_step: taptap-maker init.",
     inputSchema: {
       type: "object",
       properties: {
@@ -31087,7 +31269,7 @@ var resources = [
   {
     uri: "maker://status",
     name: "Maker status",
-    description: "Local TapTap Maker project status, including Git, PAT/TapTap auth, project binding, AI dev kit status, and bundled workflow skill document paths.",
+    description: "Local TapTap Maker project status, including Git, PAT/TapTap auth, project binding, AI dev kit status, and bundled workflow guide document paths. Maker initialization next_step: taptap-maker init.",
     mimeType: "text/plain"
   }
 ];
@@ -31248,8 +31430,8 @@ async function formatStatus(options = {}) {
   const git = checkGitEnvironment();
   const projectSection = identify.projectId ? [
     "目标目录已绑定 Maker 项目。",
-    "请继续在当前绑定项目上执行状态、提交、构建等操作；不要再引导用户 clone，除非用户明确要求切换或重新拉取项目。",
-    "本地 Maker 工作流请优先参考 taptap-maker-local skill；CLI 负责初始化/PAT/app/clone，MCP 只保留状态和同步构建。"
+    "请继续在当前绑定项目上执行状态、提交、构建等操作；用户明确要求切换或重新拉取项目时，再进入项目选择流程。",
+    "本地 Maker 工作流请参考 taptap-maker-local workflow guide document；CLI 负责初始化/PAT/app/clone，MCP 只保留状态和同步构建。"
   ].join("\n") : isLikelyAiDialogueDirectory(targetDir) ? formatAiDialogueDirectoryHint(targetDir) : pat ? await formatAutoProjectListFromPat() : formatIdentifyHint();
   return [
     "TapTap Maker MCP status",
@@ -31287,7 +31469,7 @@ function formatMakerRemoteSyncSkipped() {
     "Maker remote sync",
     "",
     "- status: skipped",
-    "- next_action: 已跳过远端同步检查；如需确认是否需要 pull，请重新读取 maker_status_lite 且不要设置 skip_remote_sync。"
+    "- next_action: 已跳过远端同步检查；如需确认是否需要 pull，请重新读取 maker_status_lite 并启用远端同步检查。"
   ].join("\n");
 }
 async function formatMakerRemoteSyncStatus(projectRoot) {
@@ -31387,13 +31569,16 @@ async function formatAiDevKitStatus(projectRoot) {
   ].join("\n");
 }
 function formatAiDevKitStatusLines(status, devKitStatus) {
+  const skillStatus = inspectAiDevKitSkillInstallStatus(devKitStatus.targetDir);
   return [
     "AI dev kit",
     "",
     `- status: ${status}`,
     `- required_entries: ${devKitStatus.requiredEntries.join(", ")}`,
     `- present_entries: ${devKitStatus.presentEntries.join(", ") || "(none)"}`,
-    `- missing_entries: ${devKitStatus.missingEntries.join(", ") || "(none)"}`
+    `- missing_entries: ${devKitStatus.missingEntries.join(", ") || "(none)"}`,
+    `- skill_install_status: ${skillStatus.status}`,
+    `- skill_install_summary: ${skillStatus.summary}`
   ];
 }
 async function formatAutoProjectListFromPat() {
@@ -31401,7 +31586,8 @@ async function formatAutoProjectListFromPat() {
     const projects = await listMakerProjects();
     return [
       "本地已有 Maker PAT，当前目录尚未绑定 Maker 项目。",
-      "当前目录未绑定时，先展示下面的 Maker Apps 预览和总数，避免长列表刷屏；选择、解释和 clone 顺序请参考 taptap-maker-local skill。",
+      "当前目录未绑定时，先展示下面的 Maker Apps 预览和总数；选择、解释和 clone 顺序请参考 taptap-maker-local workflow guide document。",
+      "用户选择 app 后，next_step: 执行 `taptap-maker init`。",
       "",
       formatStatusProjectList(projects)
     ].join("\n");
@@ -31446,14 +31632,15 @@ function formatStatusProjectList(projects) {
     "",
     hiddenCount > 0 ? `为了保持友好的可读性，默认最多展示 ${visibleProjects.length} 个 app；如需完整列表，可以选择显示全部。` : "已显示全部 app；请询问用户选择。",
     hiddenCount > 0 ? "如需完整列表，请运行 taptap-maker apps --json 查看全部 app。" : void 0,
-    "AI 展示建议：如果聊天或客户端宽度足够，可把 app 预览整理成两列紧凑布局；每个 app 保留序号、app_id、名称，以及可用的最近活跃时间或 user_id。窄屏保持单列。不要省略 app_id，也不要在用户确认前自动选择 app。",
+    "AI 展示建议：如果聊天或客户端宽度足够，可把 app 预览整理成两列紧凑布局；每个 app 保留序号、app_id、名称，以及可用的最近活跃时间或 user_id。窄屏保持单列。选择 app 前先获取用户确认。",
     "",
     ...visibleProjects.map(
       (project, index) => `${index + 1}. ${project.id}${project.name ? `  ${project.name}` : ""}${project.user_id ? `  user_id=${project.user_id}` : ""}${project.gameType ? `  gameType=${project.gameType}` : ""}${project.stage ? `  stage=${project.stage}` : ""}${project.createdAt ? `  createdAt=${project.createdAt}` : ""}${project.lastConversationAt ? `  lastConversationAt=${project.lastConversationAt}` : ""}`
     ),
     "",
-    "仅当当前目录未绑定且用户要初始化或 clone 时，才让用户选择 app 并继续 taptap-maker init。",
-    "如果当前目录已绑定 Maker 项目，这个列表仅作账号项目参考；请继续当前项目，除非用户明确要求切换或重新 clone。"
+    "当前目录未绑定且用户要初始化或 clone 时，让用户选择 app 并继续 taptap-maker init。",
+    "用户回复序号或 app_id 后，next_step: 执行 `taptap-maker init`，或让已经启动的 `taptap-maker init` 交互继续读取该选择。",
+    "如果当前目录已绑定 Maker 项目，这个列表仅作账号项目参考；请继续当前项目。用户明确要求切换或重新 clone 时，再进入项目选择流程。"
   ].filter((line) => line !== void 0).join("\n");
 }
 function formatClonePartialStateLines(targetDir) {
@@ -31480,7 +31667,7 @@ function formatClonePartialStateLines(targetDir) {
     `- ai_dev_kit_missing_entries: ${devKitStatus.missingEntries.join(", ") || "(none)"}`,
     `- staged_dev_kit_gitignore: ${fs7.existsSync(stagedDevKitGitignorePath) ? "yes" : "no"}`,
     `- safe_to_retry: ${safeToRetry ? "yes" : "no"}`,
-    safeToRetry ? "- next_step: 可以直接重试 taptap-maker init；如果连续失败，建议换一个全新的独立目录重新 clone。" : "- next_step: 当前目录已经有 Maker 绑定信息；先运行 taptap-maker doctor 或读取 maker://status 确认状态，不要重复 clone。"
+    safeToRetry ? "- next_step: 可以直接重试 taptap-maker init；如果连续失败，建议换一个全新的独立目录重新 clone。" : "- next_step: 当前目录已经有 Maker 绑定信息；先运行 taptap-maker doctor 或读取 maker://status 确认状态。"
   ].filter(Boolean);
 }
 function createRemoteProxyContext(options) {
@@ -32638,12 +32825,16 @@ async function runInit(parsed, ctx) {
   emit(ctx, "doctor", "Git is available", { version: git.version });
   const pat = await resolvePat(parsed, ctx);
   emit(ctx, "pat", "Maker PAT ready", { saved: getPatPath() });
-  const tapAuth = await requestTapAuthWithPat(pat);
+  const tapAuth = await requestTapAuthWithPat(pat).catch((error2) => {
+    throw appendPatRecoveryUrl(error2, parsed);
+  });
   emit(ctx, "tap_auth", "TapTap token exchanged and saved", {
     kid: mask(tapAuth.kid),
     saved: getTapAuthPath()
   });
-  const projects = await listMakerProjects({ pat });
+  const projects = await listMakerProjects({ pat }).catch((error2) => {
+    throw appendPatRecoveryUrl(error2, parsed);
+  });
   const selected = await resolveProjectSelection(parsed, projects, {
     skipConfirm
   });
@@ -32666,6 +32857,8 @@ async function runInit(parsed, ctx) {
     userId: selected.user_id,
     sceEndpoint: selected.sce_endpoint || process.env.SCE_MCP_URL,
     onProgress: (progress) => emitProgress(ctx, "clone", progress)
+  }).catch((error2) => {
+    throw appendPatRecoveryUrl(error2, parsed);
   });
   emit(ctx, "clone", "Maker project cloned or fetched", cloneResult);
   if (!skipMcpInstall) {
@@ -32744,7 +32937,9 @@ async function runApps(parsed, ctx) {
     warnPatArgExposure();
   }
   const showAll = booleanOption(parsed, "all");
-  const projects = await listMakerProjects({ pat });
+  const projects = await listMakerProjects({ pat }).catch((error2) => {
+    throw appendPatRecoveryUrl(error2, parsed);
+  });
   if (ctx.json) {
     writeJson(projects);
     return;
@@ -32755,7 +32950,9 @@ async function runApps(parsed, ctx) {
 async function runPatSet(parsed, ctx) {
   const pat = await resolvePatSet(parsed, ctx);
   saveManualMakerPat(pat);
-  const tapAuth = await requestTapAuthWithPat(pat);
+  const tapAuth = await requestTapAuthWithPat(pat).catch((error2) => {
+    throw appendPatRecoveryUrl(error2, parsed);
+  });
   emit(ctx, "pat", "Maker PAT and TapTap token saved", {
     pat_path: getPatPath(),
     tap_auth_path: getTapAuthPath(),
@@ -32897,7 +33094,8 @@ async function runDevKitUpdate(parsed, ctx) {
     preserveExisting: true
   });
   finalizeStagedDevKitGitignore(targetDir);
-  emit(ctx, "dev_kit", "AI dev kit updated", result);
+  emit(ctx, "dev_kit", formatDevKitInstallMessage("AI dev kit updated", result), result);
+  emitDevKitSkillInstallerFailure(ctx, result.skillInstaller, "AI skills install failed");
 }
 async function runLogsWatch(parsed, ctx) {
   const targetDir = path9.resolve(stringOption(parsed, "target_dir") || process.cwd());
@@ -33085,18 +33283,87 @@ async function prepareDevKit(targetDir, ctx) {
       path9.join(targetDir, DEV_KIT_GITIGNORE_STAGING_FILE),
       listPresentDevKitManagedEntries(targetDir)
     );
-    emit(ctx, "dev_kit", "AI dev kit already present", before);
+    try {
+      const skillInstaller = installAiDevKitSkills(targetDir, {
+        onStart: (event) => emitSkillInstallerStart(ctx, event)
+      });
+      emit(
+        ctx,
+        "dev_kit",
+        formatDevKitInstallMessage("AI dev kit already present", { skillInstaller }),
+        {
+          ...before,
+          skillInstaller
+        }
+      );
+    } catch (error2) {
+      const detail = error2 instanceof Error ? error2.message : String(error2);
+      emit(ctx, "dev_kit_warning", `AI skills install failed; clone will continue
+${detail}`, {
+        error: detail
+      });
+    }
     return;
   }
   try {
-    const result = await installAiDevKit({ targetDir });
-    emit(ctx, "dev_kit", "AI dev kit prepared", result);
+    const result = await installAiDevKit({
+      targetDir,
+      onSkillInstallerStart: (event) => emitSkillInstallerStart(ctx, event)
+    });
+    emit(ctx, "dev_kit", formatDevKitInstallMessage("AI dev kit prepared", result), result);
+    emitDevKitSkillInstallerFailure(
+      ctx,
+      result.skillInstaller,
+      "AI skills install failed; clone will continue"
+    );
   } catch (error2) {
-    emit(ctx, "dev_kit_warning", "AI dev kit preparation failed; clone will continue", {
-      error: error2 instanceof Error ? error2.message : String(error2)
+    const detail = error2 instanceof Error ? error2.message : String(error2);
+    emit(ctx, "dev_kit_warning", `AI dev kit preparation failed; clone will continue
+${detail}`, {
+      error: detail
     });
   }
 }
+function formatDevKitInstallMessage(message, result) {
+  if (!result.skillInstaller) {
+    return message;
+  }
+  return `${message}
+AI skills install result: ${result.skillInstaller.summary}`;
+}
+function emitSkillInstallerStart(ctx, event) {
+  emit(ctx, "dev_kit_skill_install_start", `AI skills install started: ${event.script}`, event);
+}
+function emitDevKitSkillInstallerFailure(ctx, result, message) {
+  if (!result || result.ok || result.status !== "failed") {
+    return;
+  }
+  const detail = result.error || "unknown installer failure";
+  emit(ctx, "dev_kit_warning", `${message}
+${detail}`, {
+    error: detail
+  });
+}
+function appendPatRecoveryUrl(error2, parsed) {
+  const message = error2 instanceof Error ? error2.message : String(error2);
+  if (!isPatValidationFailure(message) || message.includes("/pat-tokens")) {
+    return error2 instanceof Error ? error2 : new Error(message);
+  }
+  const patPage = getMakerPatTokensUrl(makerEnvOption(parsed));
+  return new Error(
+    [
+      message,
+      "",
+      `PAT 页面：${patPage}`,
+      "请在该页面创建新的 Maker PAT，然后运行 `taptap-maker pat set` 并粘贴 PAT。"
+    ].join("\n")
+  );
+}
+function isPatValidationFailure(message) {
+  return /\b(?:PAT_INVALID|HTTP\s*40[13]|40[13]|unauthori[sz]ed|invalid\s+PAT|PAT\s+invalid|expired)\b/i.test(
+    message
+  ) || /(?:过期|失效)/.test(message);
+}
 function installMcpConfigs(options) {
   return options.ides.map((ide) => installMcpConfig(ide, options));
 }

package/dist/proxy.js

@@ -29137,7 +29137,8 @@ var LogWriter = class {
 };
 
 // src/mcp-proxy/proxy.ts
-var VERSION = true ? "1.23.7-beta.1" : "dev";
+var VERSION = true ? "1.23.7-beta.3" : "dev";
+var LOCAL_PROXY_TAG = "local";
 var TapTapMCPProxy = class {
   constructor(config2) {
     this.connected = false;
@@ -29243,9 +29244,11 @@ var TapTapMCPProxy = class {
    * - X-TapTap-Project-Path: 项目路径
    * - X-TapTap-Mac-Token: MAC 认证令牌（JSON）
    * - X-TapTap-Custom-Fields: 业务自定义字段（JSON）
+   * - X-TapTap-Tag: 调用来源标记，固定为 "local"
    */
   buildSessionHeaders() {
     const headers = {};
+    headers["X-TapTap-Tag"] = LOCAL_PROXY_TAG;
     if (this.config.tenant.user_id) {
       headers["X-TapTap-User-Id"] = this.config.tenant.user_id;
     }
@@ -29273,10 +29276,12 @@ var TapTapMCPProxy = class {
    * - _project_id: 项目标识（可选）
    * - _project_path: 项目路径（可选）
    * - _custom_fields: 业务自定义字段（可选）
+   * - _tag: 调用来源标记，固定为 "local"
    */
   injectPrivateParams(args) {
     const injected = { ...args || {} };
     injected._mac_token = this.config.auth;
+    injected._tag = LOCAL_PROXY_TAG;
     if (this.config.tenant.user_id) {
       injected._user_id = this.config.tenant.user_id;
     }