helloloop 0.1.2 → 0.2.1

package/src/cli_support.mjs

@@ -0,0 +1,327 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
+
+import { analyzeExecution, summarizeBacklog } from "./backlog.mjs";
+import { fileExists, readJson } from "./common.mjs";
+import { resolveCliInvocation, resolveCodexInvocation } from "./shell_invocation.mjs";
+
+function probeCodexVersion() {
+  const invocation = resolveCodexInvocation();
+  if (invocation.error) {
+    return {
+      ok: false,
+      detail: invocation.error,
+    };
+  }
+
+  const codexVersion = spawnSync(invocation.command, [...invocation.argsPrefix, "--version"], {
+    encoding: "utf8",
+    shell: invocation.shell,
+  });
+  const ok = codexVersion.status === 0;
+  return {
+    ok,
+    detail: ok
+      ? String(codexVersion.stdout || "").trim()
+      : String(codexVersion.stderr || codexVersion.error || "无法执行 codex --version").trim(),
+  };
+}
+
+export function collectDoctorChecks(context) {
+  const codexVersion = probeCodexVersion();
+  return [
+    {
+      name: "codex CLI",
+      ok: codexVersion.ok,
+      detail: codexVersion.detail,
+    },
+    {
+      name: "backlog.json",
+      ok: fileExists(context.backlogFile),
+      detail: context.backlogFile,
+    },
+    {
+      name: "policy.json",
+      ok: fileExists(context.policyFile),
+      detail: context.policyFile,
+    },
+    {
+      name: "verify.yaml",
+      ok: fileExists(context.repoVerifyFile),
+      detail: context.repoVerifyFile,
+    },
+    {
+      name: "project.json",
+      ok: fileExists(context.projectFile),
+      detail: context.projectFile,
+    },
+    {
+      name: "plugin manifest",
+      ok: fileExists(context.pluginManifestFile),
+      detail: context.pluginManifestFile,
+    },
+    {
+      name: "plugin skill",
+      ok: fileExists(context.skillFile),
+      detail: context.skillFile,
+    },
+    {
+      name: "install script",
+      ok: fileExists(context.installScriptFile),
+      detail: context.installScriptFile,
+    },
+  ];
+}
+
+function probeNamedCliVersion(commandName, toolDisplayName) {
+  const invocation = resolveCliInvocation({
+    commandName,
+    toolDisplayName,
+  });
+  if (invocation.error) {
+    return {
+      ok: false,
+      detail: invocation.error,
+    };
+  }
+
+  const result = spawnSync(invocation.command, [...invocation.argsPrefix, "--version"], {
+    encoding: "utf8",
+    shell: invocation.shell,
+  });
+  const ok = result.status === 0;
+  return {
+    ok,
+    detail: ok
+      ? String(result.stdout || "").trim()
+      : String(result.stderr || result.error || `无法执行 ${commandName} --version`).trim(),
+  };
+}
+
+function normalizeDoctorHosts(hostOption) {
+  const normalized = String(hostOption || "codex").trim().toLowerCase();
+  if (normalized === "all") {
+    return ["codex", "claude", "gemini"];
+  }
+  return [normalized];
+}
+
+function collectCodexDoctorChecks(context, options = {}) {
+  const checks = collectDoctorChecks(context);
+  if (options.codexHome) {
+    checks.push({
+      name: "codex installed plugin",
+      ok: fileExists(path.join(options.codexHome, "plugins", "helloloop", ".codex-plugin", "plugin.json")),
+      detail: path.join(options.codexHome, "plugins", "helloloop", ".codex-plugin", "plugin.json"),
+    });
+    checks.push({
+      name: "codex marketplace",
+      ok: fileExists(path.join(options.codexHome, ".agents", "plugins", "marketplace.json")),
+      detail: path.join(options.codexHome, ".agents", "plugins", "marketplace.json"),
+    });
+  }
+  return checks;
+}
+
+function collectClaudeDoctorChecks(context, options = {}) {
+  const claudeVersion = probeNamedCliVersion("claude", "Claude");
+  const checks = [
+    {
+      name: "claude CLI",
+      ok: claudeVersion.ok,
+      detail: claudeVersion.detail,
+    },
+    {
+      name: "claude plugin manifest",
+      ok: fileExists(path.join(context.bundleRoot, ".claude-plugin", "plugin.json")),
+      detail: path.join(context.bundleRoot, ".claude-plugin", "plugin.json"),
+    },
+    {
+      name: "claude marketplace manifest",
+      ok: fileExists(path.join(context.bundleRoot, "hosts", "claude", "marketplace", ".claude-plugin", "marketplace.json")),
+      detail: path.join(context.bundleRoot, "hosts", "claude", "marketplace", ".claude-plugin", "marketplace.json"),
+    },
+    {
+      name: "claude command",
+      ok: fileExists(path.join(context.bundleRoot, "hosts", "claude", "marketplace", "plugins", "helloloop", "commands", "helloloop.md")),
+      detail: path.join(context.bundleRoot, "hosts", "claude", "marketplace", "plugins", "helloloop", "commands", "helloloop.md"),
+    },
+  ];
+
+  if (options.claudeHome) {
+    const settingsFile = path.join(options.claudeHome, "settings.json");
+    const knownMarketplacesFile = path.join(options.claudeHome, "plugins", "known_marketplaces.json");
+    const installedPluginsFile = path.join(options.claudeHome, "plugins", "installed_plugins.json");
+    const settings = fileExists(settingsFile) ? readJson(settingsFile) : {};
+    const installedPlugins = fileExists(installedPluginsFile) ? readJson(installedPluginsFile) : {};
+    const installs = Array.isArray(installedPlugins?.plugins?.["helloloop@helloloop-local"])
+      ? installedPlugins.plugins["helloloop@helloloop-local"]
+      : [];
+    const installedPluginRoot = installs[0]?.installPath
+      ? String(installs[0].installPath)
+      : path.join(options.claudeHome, "plugins", "cache", "helloloop-local", "helloloop");
+
+    checks.push({
+      name: "claude installed marketplace",
+      ok: fileExists(path.join(options.claudeHome, "plugins", "marketplaces", "helloloop-local", ".claude-plugin", "marketplace.json")),
+      detail: path.join(options.claudeHome, "plugins", "marketplaces", "helloloop-local", ".claude-plugin", "marketplace.json"),
+    });
+    checks.push({
+      name: "claude marketplace registry",
+      ok: fileExists(knownMarketplacesFile),
+      detail: knownMarketplacesFile,
+    });
+    checks.push({
+      name: "claude installed plugin index",
+      ok: fileExists(installedPluginsFile),
+      detail: installedPluginsFile,
+    });
+    checks.push({
+      name: "claude installed plugin",
+      ok: fileExists(path.join(installedPluginRoot, ".claude-plugin", "plugin.json")),
+      detail: path.join(installedPluginRoot, ".claude-plugin", "plugin.json"),
+    });
+    checks.push({
+      name: "claude settings enabled",
+      ok: settings?.enabledPlugins?.["helloloop@helloloop-local"] === true,
+      detail: settingsFile,
+    });
+  }
+
+  return checks;
+}
+
+function collectGeminiDoctorChecks(context, options = {}) {
+  const geminiVersion = probeNamedCliVersion("gemini", "Gemini");
+  const checks = [
+    {
+      name: "gemini CLI",
+      ok: geminiVersion.ok,
+      detail: geminiVersion.detail,
+    },
+    {
+      name: "gemini extension manifest",
+      ok: fileExists(path.join(context.bundleRoot, "hosts", "gemini", "extension", "gemini-extension.json")),
+      detail: path.join(context.bundleRoot, "hosts", "gemini", "extension", "gemini-extension.json"),
+    },
+    {
+      name: "gemini command",
+      ok: fileExists(path.join(context.bundleRoot, "hosts", "gemini", "extension", "commands", "helloloop.toml")),
+      detail: path.join(context.bundleRoot, "hosts", "gemini", "extension", "commands", "helloloop.toml"),
+    },
+    {
+      name: "gemini context file",
+      ok: fileExists(path.join(context.bundleRoot, "hosts", "gemini", "extension", "GEMINI.md")),
+      detail: path.join(context.bundleRoot, "hosts", "gemini", "extension", "GEMINI.md"),
+    },
+  ];
+
+  if (options.geminiHome) {
+    checks.push({
+      name: "gemini installed extension",
+      ok: fileExists(path.join(options.geminiHome, "extensions", "helloloop", "gemini-extension.json")),
+      detail: path.join(options.geminiHome, "extensions", "helloloop", "gemini-extension.json"),
+    });
+  }
+
+  return checks;
+}
+
+export async function runDoctor(context, options = {}) {
+  const hosts = normalizeDoctorHosts(options.host);
+  const checks = hosts.flatMap((host) => {
+    if (host === "codex") return collectCodexDoctorChecks(context, options);
+    if (host === "claude") return collectClaudeDoctorChecks(context, options);
+    if (host === "gemini") return collectGeminiDoctorChecks(context, options);
+    return [];
+  });
+
+  for (const item of checks) {
+    console.log(`${item.ok ? "OK" : "FAIL"}  ${item.name}  ${item.detail}`);
+  }
+
+  if (checks.every((item) => item.ok)) {
+    console.log("\nDoctor 结论：当前 HelloLoop 所选宿主与目标仓库已具备基本运行条件。");
+  }
+
+  if (checks.some((item) => !item.ok)) {
+    process.exitCode = 1;
+  }
+}
+
+function isAffirmativeAnswer(answer) {
+  const raw = String(answer || "").trim();
+  const normalized = raw.toLowerCase();
+  return [
+    "y",
+    "yes",
+    "ok",
+    "确认",
+    "是",
+    "继续",
+    "好的",
+  ].includes(normalized) || ["确认", "是", "继续", "好的"].includes(raw);
+}
+
+export async function confirmAutoExecution() {
+  const readline = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    const answer = await readline.question("是否开始自动接续执行？输入 y / yes / 确认 继续，其它任意输入取消：");
+    return isAffirmativeAnswer(answer);
+  } finally {
+    readline.close();
+  }
+}
+
+export function renderAnalyzeStopMessage(reason) {
+  return reason || "当前没有可自动执行的任务。";
+}
+
+export function renderAutoRunSummary(context, backlog, results, options = {}) {
+  const summary = summarizeBacklog(backlog);
+  const execution = analyzeExecution(backlog, options);
+  const lines = [
+    "自动执行结果",
+    "============",
+  ];
+
+  if (!results.length) {
+    lines.push("- 本轮未执行任何任务");
+  } else {
+    for (const item of results) {
+      if (!item.task) {
+        lines.push(`- 已停止：${item.summary || item.kind || "没有更多任务"}`);
+        continue;
+      }
+      lines.push(`- ${item.ok ? "完成任务" : "失败任务"}：${item.task.title}`);
+      if (!item.ok && item.summary) {
+        lines.push(item.summary);
+      }
+    }
+  }
+
+  lines.push("");
+  lines.push("当前统计：");
+  lines.push(`- 已完成：${summary.done}`);
+  lines.push(`- 待处理：${summary.pending}`);
+  lines.push(`- 进行中：${summary.inProgress}`);
+  lines.push(`- 阻塞：${summary.blocked}`);
+  lines.push(`- 失败：${summary.failed}`);
+  lines.push(`- 状态文件：${context.statusFile.replaceAll("\\", "/")}`);
+  lines.push("");
+  lines.push("结论：");
+  if (execution.state === "done") {
+    lines.push("- backlog 已全部完成");
+  } else if (execution.blockedReason) {
+    lines.push(`- 当前停止原因：${execution.blockedReason}`);
+  } else {
+    lines.push("- 当前轮次已结束，可继续查看 status 或下一任务");
+  }
+
+  return lines.join("\n");
+}

package/src/install.mjs

@@ -3,16 +3,18 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { ensureDir, fileExists, readJson, writeJson } from "./common.mjs";
+import { ensureDir, fileExists, nowIso, readJson, writeJson } from "./common.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
 export const runtimeBundleEntries = [
+  ".claude-plugin",
   ".codex-plugin",
   "LICENSE",
   "README.md",
   "bin",
+  "hosts",
   "package.json",
   "scripts",
   "skills",
@@ -20,8 +22,17 @@ export const runtimeBundleEntries = [
   "templates",
 ];
 
-function resolveCodexHome(codexHome) {
-  return path.resolve(codexHome || path.join(os.homedir(), ".codex"));
+const codexBundleEntries = runtimeBundleEntries.filter((entry) => ![
+  ".claude-plugin",
+  "hosts",
+].includes(entry));
+
+const supportedHosts = ["codex", "claude", "gemini"];
+const CLAUDE_MARKETPLACE_NAME = "helloloop-local";
+const CLAUDE_PLUGIN_KEY = "helloloop@helloloop-local";
+
+function resolveHomeDir(homeDir, defaultDirName) {
+  return path.resolve(homeDir || path.join(os.homedir(), defaultDirName));
 }
 
 function assertPathInside(parentDir, targetDir, label) {
@@ -31,21 +42,38 @@ function assertPathInside(parentDir, targetDir, label) {
   }
 }
 
-function copyBundleEntries(bundleRoot, targetPluginRoot) {
-  for (const entry of runtimeBundleEntries) {
+function removeTargetIfNeeded(targetPath, force) {
+  if (!fileExists(targetPath)) {
+    return;
+  }
+  if (!force) {
+    throw new Error(`目标目录已存在：${targetPath}。若要覆盖，请追加 --force。`);
+  }
+  fs.rmSync(targetPath, { recursive: true, force: true });
+}
+
+function copyBundleEntries(bundleRoot, targetRoot, entries) {
+  for (const entry of entries) {
     const sourcePath = path.join(bundleRoot, entry);
     if (!fileExists(sourcePath)) {
       continue;
     }
 
-    fs.cpSync(sourcePath, path.join(targetPluginRoot, entry), {
+    fs.cpSync(sourcePath, path.join(targetRoot, entry), {
       force: true,
       recursive: true,
     });
   }
 }
 
-function updateMarketplace(marketplaceFile) {
+function copyDirectory(sourceRoot, targetRoot) {
+  fs.cpSync(sourceRoot, targetRoot, {
+    force: true,
+    recursive: true,
+  });
+}
+
+function updateCodexMarketplace(marketplaceFile) {
   const marketplace = fileExists(marketplaceFile)
     ? readJson(marketplaceFile)
     : {
@@ -84,30 +112,82 @@ function updateMarketplace(marketplaceFile) {
   writeJson(marketplaceFile, marketplace);
 }
 
-export function installPluginBundle(options = {}) {
-  const bundleRoot = path.resolve(options.bundleRoot || path.join(__dirname, ".."));
-  const resolvedCodexHome = resolveCodexHome(options.codexHome);
+function updateClaudeSettings(settingsFile, marketplaceRoot) {
+  const settings = fileExists(settingsFile)
+    ? readJson(settingsFile)
+    : {};
+
+  settings.extraKnownMarketplaces = settings.extraKnownMarketplaces || {};
+  settings.enabledPlugins = settings.enabledPlugins || {};
+
+  settings.extraKnownMarketplaces[CLAUDE_MARKETPLACE_NAME] = {
+    source: {
+      source: "directory",
+      path: marketplaceRoot,
+    },
+  };
+  settings.enabledPlugins[CLAUDE_PLUGIN_KEY] = true;
+
+  writeJson(settingsFile, settings);
+}
+
+function updateClaudeKnownMarketplaces(knownMarketplacesFile, marketplaceRoot, updatedAt) {
+  const knownMarketplaces = fileExists(knownMarketplacesFile)
+    ? readJson(knownMarketplacesFile)
+    : {};
+
+  knownMarketplaces[CLAUDE_MARKETPLACE_NAME] = {
+    source: {
+      source: "directory",
+      path: marketplaceRoot,
+    },
+    installLocation: marketplaceRoot,
+    lastUpdated: updatedAt,
+  };
+
+  writeJson(knownMarketplacesFile, knownMarketplaces);
+}
+
+function updateClaudeInstalledPlugins(installedPluginsFile, pluginRoot, pluginVersion, updatedAt) {
+  const installedPlugins = fileExists(installedPluginsFile)
+    ? readJson(installedPluginsFile)
+    : {
+        version: 2,
+        plugins: {},
+      };
+
+  installedPlugins.version = 2;
+  installedPlugins.plugins = installedPlugins.plugins || {};
+  installedPlugins.plugins[CLAUDE_PLUGIN_KEY] = [
+    {
+      scope: "user",
+      installPath: pluginRoot,
+      version: pluginVersion,
+      installedAt: updatedAt,
+      lastUpdated: updatedAt,
+    },
+  ];
+
+  writeJson(installedPluginsFile, installedPlugins);
+}
+
+function installCodexHost(bundleRoot, options) {
+  const resolvedCodexHome = resolveHomeDir(options.codexHome, ".codex");
   const targetPluginsRoot = path.join(resolvedCodexHome, "plugins");
   const targetPluginRoot = path.join(targetPluginsRoot, "helloloop");
   const marketplaceFile = path.join(resolvedCodexHome, ".agents", "plugins", "marketplace.json");
   const manifestFile = path.join(bundleRoot, ".codex-plugin", "plugin.json");
 
   if (!fileExists(manifestFile)) {
-    throw new Error(`未找到插件 manifest：${manifestFile}`);
+    throw new Error(`未找到 Codex 插件 manifest：${manifestFile}`);
   }
 
-  assertPathInside(resolvedCodexHome, targetPluginRoot, "目标插件目录");
-
-  if (fileExists(targetPluginRoot)) {
-    if (!options.force) {
-      throw new Error(`目标插件目录已存在：${targetPluginRoot}。若要覆盖，请追加 --force。`);
-    }
-    fs.rmSync(targetPluginRoot, { recursive: true, force: true });
-  }
+  assertPathInside(resolvedCodexHome, targetPluginRoot, "Codex 目标插件目录");
+  removeTargetIfNeeded(targetPluginRoot, options.force);
 
   ensureDir(targetPluginsRoot);
   ensureDir(targetPluginRoot);
-  copyBundleEntries(bundleRoot, targetPluginRoot);
+  copyBundleEntries(bundleRoot, targetPluginRoot, codexBundleEntries);
 
   const gitMetadataPath = path.join(targetPluginRoot, ".git");
   if (fileExists(gitMetadataPath)) {
@@ -115,10 +195,108 @@ export function installPluginBundle(options = {}) {
   }
 
   ensureDir(path.dirname(marketplaceFile));
-  updateMarketplace(marketplaceFile);
+  updateCodexMarketplace(marketplaceFile);
 
   return {
-    targetPluginRoot,
+    host: "codex",
+    displayName: "Codex",
+    targetRoot: targetPluginRoot,
     marketplaceFile,
   };
 }
+
+function installClaudeHost(bundleRoot, options) {
+  const resolvedClaudeHome = resolveHomeDir(options.claudeHome, ".claude");
+  const sourceMarketplaceRoot = path.join(bundleRoot, "hosts", "claude", "marketplace");
+  const sourceManifest = path.join(bundleRoot, ".claude-plugin", "plugin.json");
+  const pluginVersion = readJson(sourceManifest).version || readJson(path.join(bundleRoot, "package.json")).version;
+  const targetPluginsRoot = path.join(resolvedClaudeHome, "plugins");
+  const targetMarketplaceRoot = path.join(targetPluginsRoot, "marketplaces", CLAUDE_MARKETPLACE_NAME);
+  const targetCachePluginsRoot = path.join(targetPluginsRoot, "cache", CLAUDE_MARKETPLACE_NAME, "helloloop");
+  const targetInstalledPluginRoot = path.join(targetCachePluginsRoot, pluginVersion);
+  const knownMarketplacesFile = path.join(targetPluginsRoot, "known_marketplaces.json");
+  const installedPluginsFile = path.join(targetPluginsRoot, "installed_plugins.json");
+  const settingsFile = path.join(resolvedClaudeHome, "settings.json");
+
+  if (!fileExists(sourceManifest)) {
+    throw new Error(`未找到 Claude 插件 manifest：${sourceManifest}`);
+  }
+  if (!fileExists(path.join(sourceMarketplaceRoot, ".claude-plugin", "marketplace.json"))) {
+    throw new Error(`未找到 Claude marketplace 模板：${sourceMarketplaceRoot}`);
+  }
+
+  assertPathInside(resolvedClaudeHome, targetMarketplaceRoot, "Claude marketplace 目录");
+  assertPathInside(resolvedClaudeHome, targetInstalledPluginRoot, "Claude 插件缓存目录");
+  removeTargetIfNeeded(targetMarketplaceRoot, options.force);
+  removeTargetIfNeeded(targetCachePluginsRoot, options.force);
+
+  ensureDir(path.dirname(targetMarketplaceRoot));
+  ensureDir(path.dirname(targetInstalledPluginRoot));
+  copyDirectory(sourceMarketplaceRoot, targetMarketplaceRoot);
+  copyDirectory(path.join(sourceMarketplaceRoot, "plugins", "helloloop"), targetInstalledPluginRoot);
+  ensureDir(targetPluginsRoot);
+  const updatedAt = nowIso();
+  updateClaudeSettings(settingsFile, targetMarketplaceRoot);
+  updateClaudeKnownMarketplaces(knownMarketplacesFile, targetMarketplaceRoot, updatedAt);
+  updateClaudeInstalledPlugins(installedPluginsFile, targetInstalledPluginRoot, pluginVersion, updatedAt);
+
+  return {
+    host: "claude",
+    displayName: "Claude",
+    targetRoot: targetInstalledPluginRoot,
+    marketplaceFile: path.join(targetMarketplaceRoot, ".claude-plugin", "marketplace.json"),
+    settingsFile,
+  };
+}
+
+function installGeminiHost(bundleRoot, options) {
+  const resolvedGeminiHome = resolveHomeDir(options.geminiHome, ".gemini");
+  const sourceExtensionRoot = path.join(bundleRoot, "hosts", "gemini", "extension");
+  const targetExtensionRoot = path.join(resolvedGeminiHome, "extensions", "helloloop");
+
+  if (!fileExists(path.join(sourceExtensionRoot, "gemini-extension.json"))) {
+    throw new Error(`未找到 Gemini 扩展清单：${sourceExtensionRoot}`);
+  }
+
+  assertPathInside(resolvedGeminiHome, targetExtensionRoot, "Gemini 扩展目录");
+  removeTargetIfNeeded(targetExtensionRoot, options.force);
+
+  ensureDir(path.dirname(targetExtensionRoot));
+  copyDirectory(sourceExtensionRoot, targetExtensionRoot);
+
+  return {
+    host: "gemini",
+    displayName: "Gemini",
+    targetRoot: targetExtensionRoot,
+  };
+}
+
+function resolveInstallHosts(hostOption) {
+  const normalized = String(hostOption || "codex").trim().toLowerCase();
+  if (normalized === "all") {
+    return [...supportedHosts];
+  }
+  if (!supportedHosts.includes(normalized)) {
+    throw new Error(`不支持的宿主：${hostOption}。可选值：codex、claude、gemini、all`);
+  }
+  return [normalized];
+}
+
+export function installPluginBundle(options = {}) {
+  const bundleRoot = path.resolve(options.bundleRoot || path.join(__dirname, ".."));
+  const selectedHosts = resolveInstallHosts(options.host);
+  const installers = {
+    codex: () => installCodexHost(bundleRoot, options),
+    claude: () => installClaudeHost(bundleRoot, options),
+    gemini: () => installGeminiHost(bundleRoot, options),
+  };
+
+  const installedHosts = selectedHosts.map((host) => installers[host]());
+  const codexResult = installedHosts.find((item) => item.host === "codex");
+
+  return {
+    installedHosts,
+    targetPluginRoot: codexResult?.targetRoot || "",
+    marketplaceFile: codexResult?.marketplaceFile || "",
+  };
+}

package/src/shell_invocation.mjs

@@ -125,7 +125,7 @@ function isCmdLikeExecutable(executable) {
   return /\.(cmd|bat)$/i.test(String(executable || ""));
 }
 
-function resolveWindowsCodexExecutable(options = {}) {
+function resolveWindowsNamedExecutable(toolName, options = {}) {
   const explicitExecutable = String(options.explicitExecutable || "").trim();
   const findCommandPaths = options.findCommandPaths || ((command) => findWindowsCommandPaths(command));
 
@@ -133,7 +133,7 @@ function resolveWindowsCodexExecutable(options = {}) {
     return explicitExecutable;
   }
 
-  const searchOrder = ["codex.ps1", "codex.exe", "codex"];
+  const searchOrder = [`${toolName}.ps1`, `${toolName}.exe`, toolName];
   for (const query of searchOrder) {
     const safeMatch = findCommandPaths(query).find((candidate) => !isCmdLikeExecutable(candidate));
     if (safeMatch) {
@@ -160,31 +160,37 @@ export function resolveVerifyShellInvocation(options = {}) {
   return resolvePosixCommandShell(options);
 }
 
-export function resolveCodexInvocation(options = {}) {
+export function resolveCliInvocation(options = {}) {
   const platform = options.platform || process.platform;
   const explicitExecutable = String(options.explicitExecutable || "").trim();
+  const commandName = String(options.commandName || "").trim();
+  const toolDisplayName = String(options.toolDisplayName || commandName || "CLI");
+
+  if (!commandName && !explicitExecutable) {
+    return createUnavailableInvocation("未提供 CLI 名称或显式可执行路径。");
+  }
 
   if (platform !== "win32") {
     return {
-      command: explicitExecutable || "codex",
+      command: explicitExecutable || commandName,
       argsPrefix: [],
       shell: false,
     };
   }
 
-  const executable = resolveWindowsCodexExecutable({
+  const executable = resolveWindowsNamedExecutable(commandName, {
     explicitExecutable,
     findCommandPaths: options.findCommandPaths,
   });
   if (!executable) {
     return createUnavailableInvocation(
-      "未找到可安全执行的 codex 入口。Windows 环境需要 codex.ps1、codex.exe 或其他非 cmd 的可执行入口。",
+      `未找到可安全执行的 ${toolDisplayName} 入口。Windows 环境需要 ${commandName}.ps1、${commandName}.exe 或其他非 cmd 的可执行入口。`,
     );
   }
 
   if (isCmdLikeExecutable(executable)) {
     return createUnavailableInvocation(
-      `HelloLoop 在 Windows 已禁止通过 cmd/bat 启动 Codex：${executable}`,
+      `HelloLoop 在 Windows 已禁止通过 cmd/bat 启动 ${toolDisplayName}：${executable}`,
     );
   }
 
@@ -209,3 +215,11 @@ export function resolveCodexInvocation(options = {}) {
     shell: false,
   };
 }
+
+export function resolveCodexInvocation(options = {}) {
+  return resolveCliInvocation({
+    ...options,
+    commandName: "codex",
+    toolDisplayName: "Codex",
+  });
+}