cloudflared-manager 0.1.0

package/cloudflared_manager.mjs

@@ -0,0 +1,2080 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { emitKeypressEvents } from "node:readline";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const SHELL_SCRIPT = path.join(SCRIPT_DIR, "cloudflared_manager.sh");
+const INTERACTIVE_FLAGS = new Set(["interactive", "--interactive"]);
+const BACK_KEYWORDS = new Set(["back", "返回", ".."]);
+
+// 统一规范化交互输入，便于判断返回命令等关键字。
+function normalizeInput(value) {
+  return (value ?? "").trim().toLowerCase();
+}
+
+// 判断单次输入是否明确表示“返回”。
+function isBackKeyword(value) {
+  return BACK_KEYWORDS.has(normalizeInput(value));
+}
+
+// 判断当前累计文本是否已经匹配到返回关键字。
+function endsWithBackKeyword(value) {
+  const normalized = normalizeInput(value);
+  return Array.from(BACK_KEYWORDS).some((keyword) => normalized.endsWith(keyword));
+}
+const COLORS = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  cyan: "\x1b[36m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+  blue: "\x1b[34m",
+  gray: "\x1b[90m",
+  white: "\x1b[37m",
+  brightWhite: "\x1b[97m",
+  selectedBg: "\x1b[104m",
+  inverse: "\x1b[7m",
+};
+const MAIN_MENU_KEY = "main";
+const MENUS = {
+  main: {
+    title: "主菜单",
+    subtitle: "先选操作分类，再进入二级菜单。",
+    items: [
+      {
+        value: "1",
+        label: "环境与登录",
+        hint: "检查环境、初始化目录、登录和证书管理",
+        kind: "primary",
+        next: "env",
+      },
+      {
+        value: "2",
+        label: "新建与接管",
+        hint: "创建新 Tunnel，或接管已有 Tunnel",
+        kind: "primary",
+        next: "setup",
+      },
+      {
+        value: "3",
+        label: "现有应用管理",
+        hint: "按应用执行查看、运行、Ingress 和删除操作",
+        kind: "secondary",
+        next: "app_picker",
+      },
+      {
+        value: "4",
+        label: "远端与高级",
+        hint: "查看远端 Tunnel，或执行原始命令",
+        kind: "assist",
+        next: "advanced",
+      },
+      {
+        value: "0",
+        label: "退出",
+        hint: "离开交互模式",
+        kind: "danger",
+        exit: true,
+      },
+    ],
+  },
+  env: {
+    title: "环境与登录",
+    subtitle: "路径、初始化、登录和证书操作。",
+    items: [
+      { value: "1", label: "环境检查", hint: "查看路径、配置和 cloudflared 状态 (doctor)", kind: "primary", action: "1", group: "环境" },
+      { value: "2", label: "初始化目录", hint: "创建管理目录，并可选执行登录 (init)", kind: "primary", action: "17", group: "环境" },
+      { value: "3", label: "保存当前路径", hint: "保存当前 profile 解析结果 (use)", kind: "secondary", action: "18", group: "环境" },
+      { value: "4", label: "登录 Cloudflare", hint: "执行 tunnel login 并同步证书 (login)", kind: "primary", action: "19", group: "登录与证书" },
+      { value: "5", label: "导入证书", hint: "把已有 cert.pem 导入当前路径 (import-cert)", kind: "assist", action: "20", group: "登录与证书" },
+      { value: "0", label: "返回主菜单", hint: "回到一级菜单", kind: "back", back: true },
+    ],
+  },
+  setup: {
+    title: "新建与接管",
+    subtitle: "创建新的 tunnel，或接管已有 tunnel。",
+    items: [
+      { value: "1", label: "创建新 tunnel", hint: "创建新 Tunnel 并写入本地受管配置 (add)", kind: "primary", action: "5", group: "创建与接管" },
+      { value: "2", label: "接管已有 tunnel", hint: "把远端 Tunnel 纳入本地受管目录 (adopt)", kind: "primary", action: "6", group: "创建与接管" },
+      { value: "0", label: "返回主菜单", hint: "回到一级菜单", kind: "back", back: true },
+    ],
+  },
+  advanced: {
+    title: "远端与高级",
+    subtitle: "远端 tunnel 查询与自定义命令。",
+    items: [
+      { value: "1", label: "查看远端 tunnels", hint: "列出当前账号下的远端 Tunnel (tunnels)", kind: "secondary", action: "3", group: "远端信息" },
+      { value: "2", label: "执行自定义命令", hint: "原样透传到底层 shell 脚本", kind: "assist", action: "21", group: "高级" },
+      { value: "0", label: "返回主菜单", hint: "回到一级菜单", kind: "back", back: true },
+    ],
+  },
+};
+
+// 用于表示当前交互流程应立即返回主菜单。
+class BackToMenuError extends Error {
+  constructor() {
+    super("返回主菜单");
+  }
+}
+
+// 输出错误并退出。
+function fail(message, code = 1) {
+  console.error(`错误: ${message}`);
+  process.exit(code);
+}
+
+// 判断当前终端是否适合启用 ANSI 颜色。
+function supportsColor() {
+  return process.stdout.isTTY && !("NO_COLOR" in process.env);
+}
+
+// 给文本应用 ANSI 颜色。
+function colorize(text, ...codes) {
+  if (!supportsColor()) {
+    return text;
+  }
+  return `${codes.join("")}${text}${COLORS.reset}`;
+}
+
+// 获取当前终端列宽，无法判断时回退到 80。
+function terminalColumns() {
+  return process.stdout.columns && process.stdout.columns > 0 ? process.stdout.columns : 80;
+}
+
+// 估算终端显示宽度，中文等宽字符按 2 处理。
+function displayWidth(text) {
+  return Array.from(text).reduce((width, char) => width + (char.charCodeAt(0) > 0xff ? 2 : 1), 0);
+}
+
+// 按显示宽度裁剪文本，避免单行信息过长。
+function truncateDisplayText(text, maxWidth) {
+  if (displayWidth(text) <= maxWidth) {
+    return text;
+  }
+  const ellipsis = "…";
+  const limit = Math.max(1, maxWidth - displayWidth(ellipsis));
+  let current = "";
+  let width = 0;
+  for (const char of Array.from(text)) {
+    const nextWidth = width + (char.charCodeAt(0) > 0xff ? 2 : 1);
+    if (nextWidth > limit) {
+      break;
+    }
+    current += char;
+    width = nextWidth;
+  }
+  return `${current}${ellipsis}`;
+}
+
+// 按显示宽度把文本居中到指定宽度。
+function centerText(text, width) {
+  const visibleWidth = displayWidth(text);
+  const padding = Math.max(0, width - visibleWidth);
+  const left = Math.floor(padding / 2);
+  const right = padding - left;
+  return `${" ".repeat(left)}${text}${" ".repeat(right)}`;
+}
+
+// 渲染交互菜单顶部品牌标题框。
+function renderBanner(title, subtitle) {
+  const maxInnerWidth = Math.max(28, terminalColumns() - 2);
+  const desiredWidth = Math.max(34, displayWidth(title) + 10, displayWidth(subtitle) + 10);
+  const innerWidth = Math.min(desiredWidth, maxInnerWidth);
+  const fittedTitle = truncateDisplayText(title, innerWidth);
+  const fittedSubtitle = truncateDisplayText(subtitle, innerWidth);
+  const top = `╭${"─".repeat(innerWidth)}╮`;
+  const bottom = `╰${"─".repeat(innerWidth)}╯`;
+
+  return [
+    colorize(top, COLORS.bold, COLORS.cyan),
+    `${colorize("│", COLORS.bold, COLORS.cyan)}${colorize(centerText(fittedTitle, innerWidth), COLORS.bold, COLORS.white)}${colorize("│", COLORS.bold, COLORS.cyan)}`,
+    `${colorize("│", COLORS.bold, COLORS.cyan)}${colorize(centerText(fittedSubtitle, innerWidth), COLORS.white)}${colorize("│", COLORS.bold, COLORS.cyan)}`,
+    colorize(bottom, COLORS.bold, COLORS.cyan),
+  ];
+}
+
+// 把菜单编号格式化为两位数，保证纵向对齐。
+function formatMenuValue(value) {
+  return /^[0-9]+$/.test(value) ? value.padStart(2, "0") : value;
+}
+
+// 把菜单输入编号规范化，允许 01/00 这类带前导零的写法。
+function normalizeMenuChoice(value) {
+  if (!/^[0-9]+$/.test(value)) {
+    return value;
+  }
+  return String(Number.parseInt(value, 10));
+}
+
+// 把布尔值渲染为中文状态。
+function formatEnabled(value) {
+  return value ? "是" : "否";
+}
+
+// 根据当前菜单生成顶部面包屑路径。
+function buildBreadcrumb(menuKey, appName = "") {
+  switch (menuKey) {
+    case MAIN_MENU_KEY:
+      return "";
+    case "env":
+      return "主菜单";
+    case "setup":
+      return "主菜单";
+    case "advanced":
+      return "主菜单";
+    case "app_picker":
+      return "主菜单 / 现有应用管理";
+    case "app_detail":
+      return "主菜单 / 现有应用管理";
+    default:
+      return "主菜单";
+  }
+}
+
+// 根据语义类型决定菜单项颜色。
+function itemColors(kind) {
+  switch (kind) {
+    case "primary":
+      return [COLORS.bold, COLORS.cyan];
+    case "secondary":
+      return [COLORS.bold, COLORS.green];
+    case "assist":
+      return [COLORS.bold, COLORS.yellow];
+    case "danger":
+      return [COLORS.bold, COLORS.red];
+    case "back":
+      return [COLORS.bold, COLORS.blue];
+    default:
+      return [COLORS.bold, COLORS.white];
+  }
+}
+
+// 执行底层 shell 脚本，可选捕获输出。
+function runShell(baseArgs, commandArgs, options = {}) {
+  const args = [SHELL_SCRIPT, ...baseArgs, ...commandArgs];
+  const result = spawnSync("bash", args, {
+    stdio: options.capture ? ["inherit", "pipe", "pipe"] : "inherit",
+    encoding: "utf8",
+  });
+
+  if (options.capture) {
+    return {
+      code: result.status ?? 1,
+      stdout: result.stdout ?? "",
+      stderr: result.stderr ?? "",
+      error: result.error,
+    };
+  }
+
+  if (result.error) {
+    fail(result.error.message);
+  }
+  if (options.exitOnComplete === true) {
+    process.exit(result.status ?? 1);
+  }
+  return {
+    code: result.status ?? 1,
+  };
+}
+
+// 读取一行输入，可选提供默认值。
+async function ask(rl, label, options = {}) {
+  const suffix =
+    options.defaultValue && options.defaultValue.length > 0
+      ? ` [默认: ${options.defaultValue}]`
+      : "";
+  const answer = (await rl.question(`${label}${suffix}: `)).trim();
+  if (isBackKeyword(answer)) {
+    throw new BackToMenuError();
+  }
+  if (answer.length === 0) {
+    return options.defaultValue ?? "";
+  }
+  return answer;
+}
+
+// 读取是/否输入。
+async function askYesNo(rl, label, defaultValue = false) {
+  const hint = defaultValue ? "Y/n" : "y/N";
+  while (true) {
+    const answer = (await rl.question(`${label} [${hint}]: `)).trim().toLowerCase();
+    if (isBackKeyword(answer)) {
+      throw new BackToMenuError();
+    }
+    if (!answer) {
+      return defaultValue;
+    }
+    if (["y", "yes"].includes(answer)) {
+      return true;
+    }
+    if (["n", "no"].includes(answer)) {
+      return false;
+    }
+    console.log("请输入 y 或 n。");
+  }
+}
+
+// 循环读取并校验单项输入；空输入会直接返回空字符串。
+async function askValidated(rl, label, validator, options = {}) {
+  while (true) {
+    const answer = await ask(rl, label, options);
+    if (!answer) {
+      return "";
+    }
+    const result = validator(answer);
+    if (result.ok) {
+      return result.value;
+    }
+    console.log(`输入有误: ${result.error}`);
+    if (options.example) {
+      console.log(`示例: ${options.example}`);
+    }
+  }
+}
+
+// 校验应用名称，规则与 shell 主脚本保持一致。
+function validateAppNameInput(name) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(name)) {
+    return {
+      ok: false,
+      error: "应用名只允许字母、数字、点、下划线、短横线，且必须以字母或数字开头。",
+    };
+  }
+  return { ok: true, value: name };
+}
+
+// 校验“新的本地应用名”，避免与已有受管应用重名。
+function validateNewAppName(baseArgs, name) {
+  const basic = validateAppNameInput(name);
+  if (!basic.ok) {
+    return basic;
+  }
+  if (listManagedApps(baseArgs).includes(name)) {
+    return { ok: false, error: `受管应用已存在: ${name}` };
+  }
+  return { ok: true, value: name };
+}
+
+// 规范化并校验 hostname，规则尽量与 shell 主脚本保持一致。
+function normalizeHostnameInput(hostname) {
+  const normalized = hostname.replace(/\.+$/, "").toLowerCase();
+  if (!/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+$/.test(normalized)) {
+    return { ok: false, error: `主机名非法: ${hostname}` };
+  }
+  return { ok: true, value: normalized };
+}
+
+// 规范化并校验 service，尽量与 shell 主脚本保持一致。
+function normalizeServiceInput(service) {
+  if (service === "hello_world" || service.startsWith("http_status:")) {
+    return { ok: true, value: service };
+  }
+  if (service.startsWith("unix:")) {
+    return service.length > "unix:".length
+      ? { ok: true, value: service }
+      : { ok: false, error: "unix: 后面必须跟 socket 路径。" };
+  }
+
+  let normalized = service;
+  if (!normalized.includes("://")) {
+    if (normalized.includes(":")) {
+      normalized = `http://${normalized}`;
+    } else {
+      return { ok: false, error: "服务地址必须包含协议，或使用 host:port 形式，例如 http://localhost:5173" };
+    }
+  }
+
+  const match = normalized.match(/^([A-Za-z][A-Za-z0-9+.-]*):\/\/(\[[^\]]+\]|[^/:?#]+)(?::([0-9]+))?/);
+  if (!match) {
+    return { ok: false, error: `服务地址格式非法: ${service}` };
+  }
+
+  const scheme = match[1];
+  const host = match[2];
+  if (!["http", "https", "tcp", "ssh", "rdp"].includes(scheme)) {
+    return {
+      ok: false,
+      error: `不支持的服务协议: ${scheme}。支持 http、https、tcp、ssh、rdp、unix:、hello_world、http_status:*`,
+    };
+  }
+  if (!host) {
+    return { ok: false, error: `服务地址缺少主机名: ${service}` };
+  }
+  return { ok: true, value: normalized };
+}
+
+// 校验单条 ingress 规则，并返回规范化后的 hostname=service。
+function validateIngressSpecInput(spec) {
+  if (!spec.includes("=")) {
+    return { ok: false, error: `ingress 规则格式非法: ${spec}。请使用 hostname=service` };
+  }
+  const hostname = spec.slice(0, spec.indexOf("="));
+  const service = spec.slice(spec.indexOf("=") + 1);
+  if (!hostname) {
+    return { ok: false, error: `ingress 规则缺少 hostname: ${spec}` };
+  }
+  if (!service) {
+    return { ok: false, error: `ingress 规则缺少 service: ${spec}` };
+  }
+  const hostResult = normalizeHostnameInput(hostname);
+  if (!hostResult.ok) {
+    return hostResult;
+  }
+  const serviceResult = normalizeServiceInput(service);
+  if (!serviceResult.ok) {
+    return serviceResult;
+  }
+  return { ok: true, value: `${hostResult.value}=${serviceResult.value}` };
+}
+
+// 校验批量修改格式，并返回规范化后的 N:hostname=service。
+function validateModifySpecInput(spec) {
+  if (!spec.includes(":") || !spec.includes("=")) {
+    return { ok: false, error: `批量修改格式非法: ${spec}。请使用 N:hostname=service` };
+  }
+  const indexPart = spec.slice(0, spec.indexOf(":"));
+  const ingressPart = spec.slice(spec.indexOf(":") + 1);
+  if (!/^[1-9][0-9]*$/.test(indexPart)) {
+    return { ok: false, error: `批量修改序号非法: ${spec}` };
+  }
+  const ingressResult = validateIngressSpecInput(ingressPart);
+  if (!ingressResult.ok) {
+    return ingressResult;
+  }
+  return { ok: true, value: `${indexPart}:${ingressResult.value}` };
+}
+
+// 校验 ingress-remove 使用的单项输入。
+function validateRemoveSpecInput(spec) {
+  if (/^[1-9][0-9]*$/.test(spec)) {
+    return { ok: true, value: spec };
+  }
+  return normalizeHostnameInput(spec);
+}
+
+// 收集多条 ingress 规则。
+async function collectIngressSpecs(rl) {
+  const specs = [];
+  const usedHosts = new Set();
+  console.log("请输入 ingress 规则，格式为 hostname=service。直接回车结束。");
+  while (true) {
+    const spec = await askValidated(rl, `规则 ${specs.length + 1}`, validateIngressSpecInput, {
+      example: "admin.example.com=http://localhost:5173",
+    });
+    if (!spec) {
+      break;
+    }
+    const hostname = spec.slice(0, spec.indexOf("="));
+    if (usedHosts.has(hostname)) {
+      console.log(`输入有误: 本次录入中已经存在主机名 ${hostname}`);
+      continue;
+    }
+    usedHosts.add(hostname);
+    specs.push(spec);
+  }
+  return specs;
+}
+
+// 收集至少一条 ingress 规则；直接回车不会结束，而是继续提示。
+async function collectRequiredIngressSpecs(rl) {
+  while (true) {
+    const specs = await collectIngressSpecs(rl);
+    if (specs.length > 0) {
+      return specs;
+    }
+    console.log("至少需要提供一条 ingress 规则。输入 back 可取消当前流程。");
+  }
+}
+
+// 收集多条批量修改规则。
+async function collectModifySpecs(rl) {
+  const specs = [];
+  const usedIndexes = new Set();
+  console.log("请输入批量修改规则，格式为 N:hostname=service。直接回车结束。");
+  while (true) {
+    const spec = await askValidated(rl, `修改 ${specs.length + 1}`, validateModifySpecInput, {
+      example: "1:admin.example.com=http://localhost:5173",
+    });
+    if (!spec) {
+      break;
+    }
+    const indexPart = spec.slice(0, spec.indexOf(":"));
+    if (usedIndexes.has(indexPart)) {
+      console.log(`输入有误: 本次录入中已经存在序号 ${indexPart}`);
+      continue;
+    }
+    usedIndexes.add(indexPart);
+    specs.push(spec);
+  }
+  return specs;
+}
+
+// 收集批量删除规则。
+async function collectRemoveSpecs(rl) {
+  const specs = [];
+  const dedupe = new Set();
+  console.log("请输入要删除的规则。输入纯数字表示序号，其他内容按 hostname 处理。直接回车结束。");
+  while (true) {
+    const spec = await askValidated(rl, `删除 ${specs.length + 1}`, validateRemoveSpecInput, {
+      example: "2 或 admin.example.com",
+    });
+    if (!spec) {
+      break;
+    }
+    if (dedupe.has(spec)) {
+      console.log(`输入有误: 本次录入中已经存在 ${spec}`);
+      continue;
+    }
+    dedupe.add(spec);
+    specs.push(spec);
+  }
+  return specs;
+}
+
+// 简单分词，支持单引号和双引号。
+function splitCommandLine(input) {
+  const tokens = [];
+  let current = "";
+  let quote = "";
+
+  for (let i = 0; i < input.length; i += 1) {
+    const ch = input[i];
+    if (quote) {
+      if (ch === quote) {
+        quote = "";
+      } else if (ch === "\\" && quote === '"' && i + 1 < input.length) {
+        current += input[i + 1];
+        i += 1;
+      } else {
+        current += ch;
+      }
+      continue;
+    }
+
+    if (ch === "'" || ch === '"') {
+      quote = ch;
+      continue;
+    }
+    if (/\s/.test(ch)) {
+      if (current.length > 0) {
+        tokens.push(current);
+        current = "";
+      }
+      continue;
+    }
+    if (ch === "\\" && i + 1 < input.length) {
+      current += input[i + 1];
+      i += 1;
+      continue;
+    }
+    current += ch;
+  }
+
+  if (quote) {
+    throw new Error("命令行中存在未闭合的引号");
+  }
+  if (current.length > 0) {
+    tokens.push(current);
+  }
+  return tokens;
+}
+
+// 从 shell 的 list 输出中提取受管应用名称。
+function parseManagedApps(output) {
+  const names = [];
+  for (const line of output.split(/\r?\n/)) {
+    const match = line.match(/^([^:]+):\s*状态=/);
+    if (match) {
+      names.push(match[1].trim());
+    }
+  }
+  return names;
+}
+
+// 从 shell 的 tunnels 输出中提取远端 tunnel 名称。
+function parseRemoteTunnels(output) {
+  const names = [];
+  for (const line of output.split(/\r?\n/)) {
+    const match = line.match(/^(.+?)\s+\| ID=/);
+    if (match) {
+      names.push(match[1].trim());
+    }
+  }
+  return names;
+}
+
+// 获取当前环境下的全部受管应用名称。
+function listManagedApps(baseArgs) {
+  const result = runShell(baseArgs, ["list"], { capture: true });
+  if (result.error || result.code !== 0) {
+    return [];
+  }
+  return parseManagedApps(result.stdout);
+}
+
+// 获取当前账号下的远端 tunnel 名称。
+function listRemoteTunnels(baseArgs) {
+  const result = runShell(baseArgs, ["tunnels"], { capture: true });
+  if (result.error || result.code !== 0) {
+    return [];
+  }
+  return parseRemoteTunnels(result.stdout);
+}
+
+// 生成“选择应用”的动态菜单。
+function buildAppPickerMenu(baseArgs) {
+  const appNames = listManagedApps(baseArgs);
+  const items = appNames.map((appName, index) => ({
+    value: String(index + 1),
+    label: appName,
+    hint: "进入该应用的专属子菜单",
+    kind: "secondary",
+    appName,
+  }));
+
+  if (items.length === 0) {
+    items.push({
+      value: "1",
+      label: "暂无受管应用",
+      hint: "可先去“新建与接管”创建或接管一个应用",
+      kind: "assist",
+      disabled: true,
+    });
+  }
+
+  items.push({
+    value: "0",
+    label: "返回主菜单",
+    hint: "回到一级菜单",
+    kind: "back",
+    back: true,
+  });
+
+  return {
+    key: "app_picker",
+    title: "选择应用",
+    subtitle: items.length > 1 ? "先选一个受管应用，再进入专属操作菜单。" : "当前还没有受管应用。",
+    breadcrumb: buildBreadcrumb("app_picker"),
+    items,
+  };
+}
+
+// 生成“当前应用”的动态菜单。
+function buildAppDetailMenu(appName) {
+  return {
+    key: "app_detail",
+    title: `应用：${appName}`,
+    subtitle: "围绕当前应用执行查看、运行、配置和 ingress 操作。",
+    breadcrumb: buildBreadcrumb("app_detail"),
+    items: [
+      { value: "1", label: "查看应用概览", hint: "查看当前应用的元数据和配置 (show)", kind: "secondary", action: "4", group: "查看" },
+      { value: "2", label: "查看运行状态", hint: "查看当前应用或 Tunnel 的运行状态 (status)", kind: "secondary", action: "13", group: "查看" },
+      { value: "3", label: "查看日志", hint: "查看或跟随当前应用日志 (logs)", kind: "assist", action: "14", group: "查看" },
+      { value: "4", label: "启动应用", hint: "启动当前应用对应的 cloudflared 进程 (start)", kind: "primary", action: "10", group: "运行" },
+      { value: "5", label: "停止应用", hint: "停止当前应用对应的 cloudflared 进程 (stop)", kind: "danger", action: "11", group: "运行" },
+      { value: "6", label: "重启应用", hint: "重启当前应用对应的 cloudflared 进程 (restart)", kind: "primary", action: "12", group: "运行" },
+      { value: "7", label: "查看 ingress 列表", hint: "列出当前应用的所有 ingress 规则 (ingress-list)", kind: "secondary", action: "22", group: "Ingress" },
+      { value: "8", label: "新增 ingress", hint: "为当前应用追加 ingress 规则 (ingress-add)", kind: "primary", action: "8", group: "Ingress" },
+      { value: "9", label: "修改 ingress", hint: "按序号批量修改 ingress 规则 (modify)", kind: "primary", action: "7", group: "Ingress" },
+      { value: "10", label: "删除 ingress", hint: "按序号或主机名删除 ingress 规则 (ingress-remove)", kind: "danger", action: "9", group: "Ingress" },
+      { value: "11", label: "激活为默认配置", hint: "把当前应用配置复制为默认 config.yml (activate)", kind: "assist", action: "15", group: "配置与管理" },
+      { value: "12", label: "删除应用", hint: "归档当前应用，可选同时删除远端 Tunnel (delete)", kind: "danger", action: "16", group: "配置与管理" },
+      { value: "0", label: "返回应用列表", hint: "切换到其他应用", kind: "back", back: true },
+    ],
+  };
+}
+
+// 生成当前菜单对象。
+function buildMenu(baseArgs, menuKey, appName = "") {
+  if (menuKey === "app_picker") {
+    return buildAppPickerMenu(baseArgs);
+  }
+  if (menuKey === "app_detail") {
+    return buildAppDetailMenu(appName);
+  }
+  return { ...MENUS[menuKey], key: menuKey, breadcrumb: buildBreadcrumb(menuKey, appName) };
+}
+
+// 把 ingress 规则渲染成适合预览的多行文本。
+function renderIngressPreview(specs) {
+  if (specs.length === 0) {
+    return ["  (未填写)"];
+  }
+  return specs.map((spec, index) => {
+    const separatorIndex = spec.indexOf("=");
+    const hostname = spec.slice(0, separatorIndex);
+    const service = spec.slice(separatorIndex + 1);
+    return `  ${index + 1}. ${hostname} -> ${service}`;
+  });
+}
+
+// 解析 ingress-list 输出为结构化规则数组。
+function parseIngressRules(output) {
+  const rules = [];
+  for (const line of output.split(/\r?\n/)) {
+    const match = line.match(/^\s*([0-9]+)\.\s+(.+?)\s+->\s+(.+)$/);
+    if (match) {
+      rules.push({
+        index: Number(match[1]),
+        hostname: match[2].trim(),
+        service: match[3].trim(),
+      });
+    }
+  }
+  return rules;
+}
+
+// 读取某个应用当前的 ingress 规则。
+function loadCurrentIngressRules(baseArgs, name) {
+  const result = runShell(baseArgs, ["ingress-list", name], { capture: true });
+  if (result.error || result.code !== 0) {
+    const message = (result.stderr || result.stdout || "无法读取 ingress 规则").trim();
+    console.log(message);
+    return null;
+  }
+  return parseIngressRules(result.stdout);
+}
+
+// 将 hostname=service 规格转成结构化规则。
+function rulesFromIngressSpecs(specs) {
+  return specs.map((spec) => {
+    const separatorIndex = spec.indexOf("=");
+    return {
+      hostname: spec.slice(0, separatorIndex),
+      service: spec.slice(separatorIndex + 1),
+    };
+  });
+}
+
+// 预演 modify 后的规则集合，并返回预览信息。
+function previewModifyRules(currentRules, specs) {
+  const nextRules = currentRules.map((rule) => ({ ...rule }));
+
+  for (const spec of specs) {
+    const separatorIndex = spec.indexOf(":");
+    const index = Number(spec.slice(0, separatorIndex));
+    const ingressSpec = spec.slice(separatorIndex + 1);
+    const nextRule = rulesFromIngressSpecs([ingressSpec])[0];
+    if (index < 1 || index > nextRules.length) {
+      return { ok: false, error: `修改序号超出范围: ${index}。当前共有 ${nextRules.length} 条规则。` };
+    }
+    nextRules[index - 1] = { index, ...nextRule };
+  }
+
+  const seenHosts = new Set();
+  for (const rule of nextRules) {
+    if (seenHosts.has(rule.hostname)) {
+      return { ok: false, error: `修改后出现重复主机名: ${rule.hostname}` };
+    }
+    seenHosts.add(rule.hostname);
+  }
+
+  return { ok: true, nextRules };
+}
+
+// 预演 ingress-add 后的规则集合，并返回预览信息。
+function previewAddRules(currentRules, specs) {
+  const nextRules = currentRules.map((rule) => ({ ...rule }));
+  const additions = rulesFromIngressSpecs(specs);
+  const seenHosts = new Set(currentRules.map((rule) => rule.hostname));
+
+  for (const addition of additions) {
+    if (seenHosts.has(addition.hostname)) {
+      return { ok: false, error: `主机名已存在，无法重复新增: ${addition.hostname}` };
+    }
+    seenHosts.add(addition.hostname);
+    nextRules.push({ index: nextRules.length + 1, ...addition });
+  }
+
+  return { ok: true, nextRules, additions };
+}
+
+// 预演 ingress-remove 后的规则集合，并返回预览信息。
+function previewRemoveRules(currentRules, specs) {
+  const removeIndexes = new Set();
+
+  for (const spec of specs) {
+    if (/^[1-9][0-9]*$/.test(spec)) {
+      const index = Number(spec);
+      if (index < 1 || index > currentRules.length) {
+        return { ok: false, error: `删除序号超出范围: ${index}。当前共有 ${currentRules.length} 条规则。` };
+      }
+      removeIndexes.add(index);
+      continue;
+    }
+
+    const target = currentRules.find((rule) => rule.hostname === spec);
+    if (!target) {
+      return { ok: false, error: `找不到要删除的主机名: ${spec}` };
+    }
+    removeIndexes.add(target.index);
+  }
+
+  const removedRules = currentRules.filter((rule) => removeIndexes.has(rule.index));
+  const nextRules = currentRules
+    .filter((rule) => !removeIndexes.has(rule.index))
+    .map((rule, index) => ({ ...rule, index: index + 1 }));
+
+  if (nextRules.length === 0) {
+    return { ok: false, error: "不能删除全部 ingress 规则。" };
+  }
+
+  return { ok: true, nextRules, removedRules };
+}
+
+// 渲染结构化规则列表。
+function renderRuleObjects(rules) {
+  if (!rules || rules.length === 0) {
+    return ["  (无)"];
+  }
+  return rules.map((rule) => `  ${rule.index}. ${rule.hostname} -> ${rule.service}`);
+}
+
+// 把单个 shell 参数渲染为可直接复制执行的形式。
+function shellEscapeArg(value) {
+  if (/^[A-Za-z0-9_./:=+-]+$/.test(value)) {
+    return value;
+  }
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+// 渲染命令预览。
+function renderCommandPreview(baseArgs, commandArgs) {
+  const parts = ["./cloudflared_manager.sh", ...baseArgs, ...commandArgs].map(shellEscapeArg);
+  return [`  ${parts.join(" ")}`];
+}
+
+// 渲染 modify 的差异摘要。
+function renderModifyDiffLines(currentRules, nextRules) {
+  const lines = [];
+  for (let i = 0; i < currentRules.length; i += 1) {
+    const current = currentRules[i];
+    const next = nextRules[i];
+    if (!next) {
+      continue;
+    }
+    if (current.hostname !== next.hostname || current.service !== next.service) {
+      lines.push(colorize(`  [修改前] ~ ${current.index}. ${current.hostname} -> ${current.service}`, COLORS.bold, COLORS.yellow));
+      lines.push(colorize(`  [修改后] ~ ${next.index}. ${next.hostname} -> ${next.service}`, COLORS.bold, COLORS.yellow));
+    }
+  }
+  if (lines.length === 0) {
+    lines.push(colorize("  (本次修改不会改变现有规则)", COLORS.dim, COLORS.gray));
+  }
+  return lines;
+}
+
+// 渲染新增规则摘要。
+function renderAddDiffLines(additions, startIndex) {
+  if (!additions || additions.length === 0) {
+    return [colorize("  (本次没有新增规则)", COLORS.dim, COLORS.gray)];
+  }
+  return additions.map((rule, index) =>
+    colorize(`  [新增] + ${startIndex + index}. ${rule.hostname} -> ${rule.service}`, COLORS.bold, COLORS.green),
+  );
+}
+
+// 渲染删除规则摘要。
+function renderRemoveDiffLines(removedRules) {
+  if (!removedRules || removedRules.length === 0) {
+    return [colorize("  (本次没有删除规则)", COLORS.dim, COLORS.gray)];
+  }
+  return removedRules.map((rule) =>
+    colorize(`  [删除] - ${rule.index}. ${rule.hostname} -> ${rule.service}`, COLORS.bold, COLORS.red),
+  );
+}
+
+// 构造 add/adopt 的汇总确认菜单。
+function buildSetupReviewMenu(type, baseArgs, state) {
+  const isAdd = type === "add";
+  const title = isAdd ? "确认创建新 Tunnel" : "确认接管现有 Tunnel";
+  const subtitle = "先核对当前表单内容，再决定执行、修改或取消。";
+  const ingressLines = renderIngressPreview(state.specs);
+  const commandArgs = isAdd
+    ? ["add", state.name, "--tunnel-name", state.tunnelName, ...buildIngressArgs(state.specs)]
+    : ["adopt", state.name, "--tunnel-name", state.tunnelName, ...buildIngressArgs(state.specs)];
+  const prelude = [
+    colorize(`本地应用名: ${state.name}`, COLORS.bold, COLORS.white),
+    colorize(`远端 Tunnel 名称: ${state.tunnelName}`, COLORS.bold, COLORS.white),
+    colorize(`ingress 规则数: ${state.specs.length}`, COLORS.bold, COLORS.white),
+    ...ingressLines.map((line) => colorize(line, COLORS.dim, COLORS.gray)),
+  ];
+
+  if (isAdd) {
+    prelude.push(colorize(`立即启动: ${formatEnabled(state.start)}`, COLORS.dim, COLORS.gray));
+    prelude.push(colorize(`激活为默认配置: ${formatEnabled(state.activate)}`, COLORS.dim, COLORS.gray));
+    if (state.start) commandArgs.push("--start");
+  } else {
+    prelude.push(colorize(`同时确保 DNS 路由存在: ${formatEnabled(state.ensureDns)}`, COLORS.dim, COLORS.gray));
+    prelude.push(colorize(`激活为默认配置: ${formatEnabled(state.activate)}`, COLORS.dim, COLORS.gray));
+    if (state.ensureDns) commandArgs.push("--ensure-dns");
+  }
+  if (state.activate) commandArgs.push("--activate");
+
+  prelude.push(colorize("命令预览：", COLORS.bold, COLORS.cyan));
+  prelude.push(...renderCommandPreview(baseArgs, commandArgs).map((line) => colorize(line, COLORS.dim, COLORS.gray)));
+
+  const items = [
+    { value: "1", label: isAdd ? "执行创建" : "执行接管", hint: "调用底层 shell 脚本真正落地", kind: "primary" },
+    { value: "2", label: "重新填写本地应用名", hint: `当前: ${state.name}`, kind: "secondary" },
+    { value: "3", label: "重新填写远端 Tunnel 名称", hint: `当前: ${state.tunnelName}`, kind: "secondary" },
+    { value: "4", label: "重新录入 ingress 规则", hint: `当前共 ${state.specs.length} 条`, kind: "secondary" },
+    {
+      value: "5",
+      label: isAdd ? "切换“立即启动”" : "切换“确保 DNS 路由存在”",
+      hint: `当前: ${isAdd ? formatEnabled(state.start) : formatEnabled(state.ensureDns)}`,
+      kind: "assist",
+    },
+    {
+      value: "6",
+      label: "切换“激活为默认配置”",
+      hint: `当前: ${formatEnabled(state.activate)}`,
+      kind: "assist",
+    },
+    { value: "0", label: "取消当前流程", hint: "不执行这次 add/adopt", kind: "danger", back: true },
+  ];
+
+  return {
+    key: `${type}_review`,
+    title,
+    subtitle,
+    breadcrumb: "主菜单 / 新建与接管",
+    prelude,
+    items,
+  };
+}
+
+// 收集至少一条批量修改规则。
+async function collectRequiredModifySpecs(rl) {
+  while (true) {
+    const specs = await collectModifySpecs(rl);
+    if (specs.length > 0) {
+      return specs;
+    }
+    console.log("至少需要提供一条修改规则。输入 back 可取消当前流程。");
+  }
+}
+
+// 收集至少一条删除规则。
+async function collectRequiredRemoveSpecs(rl) {
+  while (true) {
+    const specs = await collectRemoveSpecs(rl);
+    if (specs.length > 0) {
+      return specs;
+    }
+    console.log("至少需要提供一条删除规则。输入 back 可取消当前流程。");
+  }
+}
+
+// 构造 ingress 变更确认菜单。
+function buildIngressChangeReviewMenu(type, baseArgs, state, preview) {
+  const actionLabelMap = {
+    modify: "确认修改 ingress",
+    add: "确认新增 ingress",
+    remove: "确认删除 ingress",
+  };
+  const specLabelMap = {
+    modify: "本次修改规则",
+    add: "本次新增规则",
+    remove: "本次删除规则",
+  };
+
+  const prelude = [
+    colorize(`目标应用: ${state.name}`, COLORS.bold, COLORS.white),
+    colorize("当前 ingress：", COLORS.bold, COLORS.white),
+    ...renderRuleObjects(state.currentRules).map((line) => colorize(line, COLORS.dim, COLORS.gray)),
+    colorize(specLabelMap[type], COLORS.bold, COLORS.white),
+  ];
+
+  if (type === "modify" || type === "add") {
+    prelude.push(...renderIngressPreview(state.specs).map((line) => colorize(line, COLORS.dim, COLORS.gray)));
+  } else {
+    prelude.push(...state.specs.map((spec) => colorize(`  - ${spec}`, COLORS.dim, COLORS.gray)));
+  }
+
+  prelude.push(colorize("变更摘要：", COLORS.bold, COLORS.cyan));
+  if (type === "remove") {
+    prelude.push(...renderRemoveDiffLines(preview.removedRules));
+  } else if (type === "add") {
+    prelude.push(...renderAddDiffLines(preview.additions, state.currentRules.length + 1));
+  } else {
+    prelude.push(...renderModifyDiffLines(state.currentRules, preview.nextRules));
+  }
+
+  prelude.push(colorize("变更后：", COLORS.bold, COLORS.white));
+  prelude.push(...renderRuleObjects(preview.nextRules).map((line) => colorize(line, COLORS.dim, COLORS.gray)));
+  prelude.push(colorize(`暂不重启: ${formatEnabled(state.noRestart)}`, COLORS.dim, COLORS.gray));
+
+  let commandArgs;
+  if (type === "modify") {
+    commandArgs = ["modify", state.name];
+    for (const spec of state.specs) {
+      commandArgs.push("--set", spec);
+    }
+  } else if (type === "add") {
+    commandArgs = ["ingress-add", state.name, ...buildIngressArgs(state.specs)];
+  } else {
+    commandArgs = ["ingress-remove", state.name, ...buildRemoveArgs(state.specs)];
+  }
+  if (state.noRestart) {
+    commandArgs.push("--no-restart");
+  }
+
+  prelude.push(colorize("命令预览：", COLORS.bold, COLORS.cyan));
+  prelude.push(...renderCommandPreview(baseArgs, commandArgs).map((line) => colorize(line, COLORS.dim, COLORS.gray)));
+
+  const items = [
+    { value: "1", label: "执行变更", hint: "调用底层 shell 脚本真正落地", kind: "primary" },
+    {
+      value: "2",
+      label: type === "modify" ? "重新录入修改规则" : type === "add" ? "重新录入新增规则" : "重新录入删除规则",
+      hint: `当前共 ${state.specs.length} 条`,
+      kind: "secondary",
+    },
+    { value: "3", label: "切换“暂不重启”", hint: `当前: ${formatEnabled(state.noRestart)}`, kind: "assist" },
+    { value: "0", label: "取消当前流程", hint: "不执行这次变更", kind: "danger", back: true },
+  ];
+
+  return {
+    key: `${type}_ingress_review`,
+    title: actionLabelMap[type],
+    subtitle: "先预览变更前后差异，再决定是否执行。",
+    breadcrumb: `主菜单 / 现有应用管理 / ${state.name}`,
+    prelude,
+    items,
+  };
+}
+
+// 交互式执行 modify 表单，先预演变更，再决定是否执行。
+async function runModifyWizard(rl, baseArgs, name) {
+  const currentRules = loadCurrentIngressRules(baseArgs, name);
+  if (!currentRules) {
+    return null;
+  }
+
+  const state = {
+    name,
+    currentRules,
+    specs: await collectRequiredModifySpecs(rl),
+    noRestart: true,
+  };
+
+  while (true) {
+    const preview = previewModifyRules(state.currentRules, state.specs);
+    if (!preview.ok) {
+      console.log(`输入有误: ${preview.error}`);
+      state.specs = await collectRequiredModifySpecs(rl);
+      continue;
+    }
+
+    const selection = await chooseMenuItem(rl, baseArgs, buildIngressChangeReviewMenu("modify", baseArgs, state, preview));
+    switch (selection) {
+      case "1":
+        return state;
+      case "2":
+        state.specs = await collectRequiredModifySpecs(rl);
+        break;
+      case "3":
+        state.noRestart = !state.noRestart;
+        break;
+      case "0":
+        return null;
+      default:
+        console.log("无效选项，请重新输入。");
+        break;
+    }
+  }
+}
+
+// 交互式执行 ingress-add 表单，先预演变更，再决定是否执行。
+async function runIngressAddWizard(rl, baseArgs, name) {
+  const currentRules = loadCurrentIngressRules(baseArgs, name);
+  if (!currentRules) {
+    return null;
+  }
+
+  const state = {
+    name,
+    currentRules,
+    specs: await collectRequiredIngressSpecs(rl),
+    noRestart: true,
+  };
+
+  while (true) {
+    const preview = previewAddRules(state.currentRules, state.specs);
+    if (!preview.ok) {
+      console.log(`输入有误: ${preview.error}`);
+      state.specs = await collectRequiredIngressSpecs(rl);
+      continue;
+    }
+
+    const selection = await chooseMenuItem(rl, baseArgs, buildIngressChangeReviewMenu("add", baseArgs, state, preview));
+    switch (selection) {
+      case "1":
+        return state;
+      case "2":
+        state.specs = await collectRequiredIngressSpecs(rl);
+        break;
+      case "3":
+        state.noRestart = !state.noRestart;
+        break;
+      case "0":
+        return null;
+      default:
+        console.log("无效选项，请重新输入。");
+        break;
+    }
+  }
+}
+
+// 交互式执行 ingress-remove 表单，先预演变更，再决定是否执行。
+async function runIngressRemoveWizard(rl, baseArgs, name) {
+  const currentRules = loadCurrentIngressRules(baseArgs, name);
+  if (!currentRules) {
+    return null;
+  }
+
+  const state = {
+    name,
+    currentRules,
+    specs: await collectRequiredRemoveSpecs(rl),
+    noRestart: true,
+  };
+
+  while (true) {
+    const preview = previewRemoveRules(state.currentRules, state.specs);
+    if (!preview.ok) {
+      console.log(`输入有误: ${preview.error}`);
+      state.specs = await collectRequiredRemoveSpecs(rl);
+      continue;
+    }
+
+    const selection = await chooseMenuItem(rl, baseArgs, buildIngressChangeReviewMenu("remove", baseArgs, state, preview));
+    switch (selection) {
+      case "1":
+        return state;
+      case "2":
+        state.specs = await collectRequiredRemoveSpecs(rl);
+        break;
+      case "3":
+        state.noRestart = !state.noRestart;
+        break;
+      case "0":
+        return null;
+      default:
+        console.log("无效选项，请重新输入。");
+        break;
+    }
+  }
+}
+
+// 生成菜单各行文本，可用于普通输出或方向键模式。
+function menuLines(baseArgs, menu, selectedIndex = -1, numberBuffer = "", pendingG = false, commandBuffer = "") {
+  const menuSubtitle = colorize(truncateDisplayText(menu.subtitle, terminalColumns() - 1), COLORS.bold, COLORS.white);
+  const baseLine = baseArgs.length > 0
+    ? colorize(truncateDisplayText(`设置: ${baseArgs.join(" ")}`, terminalColumns() - 1), COLORS.dim, COLORS.white)
+    : "";
+  const lines = ["", ...renderBanner("cloudflared-manager", menu.title), ""];
+
+  if (menu.breadcrumb) {
+    lines.push(colorize(menu.breadcrumb, COLORS.bold, COLORS.blue));
+  }
+
+  lines.push(menuSubtitle);
+  if (baseLine) {
+    lines.push(baseLine);
+  }
+
+  if (Array.isArray(menu.prelude) && menu.prelude.length > 0) {
+    lines.push("");
+    lines.push(...menu.prelude);
+  }
+
+  let lastGroup = "";
+  menu.items.forEach((item, index) => {
+    if (item.back && index > 0 && lines[lines.length - 1] !== "") {
+      lines.push("");
+    }
+    if (item.group && item.group !== lastGroup) {
+      lines.push("");
+      lines.push(colorize(item.group, COLORS.dim, COLORS.cyan));
+      lastGroup = item.group;
+    }
+    const isSelected = selectedIndex === index;
+    const displayValue = formatMenuValue(item.value);
+    const lineText = `${isSelected ? "›" : " "} ${displayValue}. ${item.label}`;
+
+    if (isSelected && supportsColor()) {
+      lines.push(colorize(lineText, COLORS.selectedBg, COLORS.brightWhite, COLORS.bold));
+    } else {
+      lines.push(`${isSelected ? "›" : " "} ${colorize(`${displayValue}.`, COLORS.dim, COLORS.gray)} ${colorize(item.label, ...itemColors(item.kind))}`);
+    }
+  });
+
+  if (selectedIndex >= 0) {
+    const currentItem = menu.items[selectedIndex];
+    lines.push("");
+    const statusText = numberBuffer
+      ? `输入 · ${numberBuffer} · 回车确认`
+      : commandBuffer
+        ? `返回 · ${commandBuffer} · 匹配 back / 返回 / .. 后返回上一级`
+        : pendingG
+          ? `说明 · ${currentItem.hint} · 再按一次 g 到首项`
+          : `说明 · ${currentItem.hint} · ↑↓/j/k · Enter · back · 数字/01`;
+    const fittedStatusText = truncateDisplayText(statusText, terminalColumns() - 1);
+    const statusLine = numberBuffer || commandBuffer || pendingG
+      ? colorize(fittedStatusText, COLORS.bold, COLORS.yellow)
+      : colorize(fittedStatusText, COLORS.dim, COLORS.white);
+    lines.push(statusLine);
+  }
+
+  return lines;
+}
+
+// 交互式执行 add 表单，先收集，再给出汇总确认。
+async function runAddWizard(rl, baseArgs) {
+  const state = {
+    name: "",
+    tunnelName: "",
+    specs: [],
+    start: false,
+    activate: false,
+  };
+
+  state.name = await askValidated(rl, "新应用名称", (value) => validateNewAppName(baseArgs, value), {
+    example: "wchros-admin-dev",
+  });
+  if (!state.name) {
+    return null;
+  }
+  state.tunnelName = await ask(rl, "远端 tunnel 名称", { defaultValue: state.name });
+  state.specs = await collectRequiredIngressSpecs(rl);
+
+  while (true) {
+    const selection = await chooseMenuItem(rl, baseArgs, buildSetupReviewMenu("add", baseArgs, state));
+    switch (selection) {
+      case "1":
+        return state;
+      case "2":
+        state.name = await askValidated(rl, "新应用名称", (value) => validateNewAppName(baseArgs, value), {
+          defaultValue: state.name,
+          example: "wchros-admin-dev",
+        });
+        if (!state.name) {
+          return null;
+        }
+        break;
+      case "3":
+        state.tunnelName = await ask(rl, "远端 tunnel 名称", { defaultValue: state.tunnelName || state.name });
+        break;
+      case "4":
+        state.specs = await collectRequiredIngressSpecs(rl);
+        break;
+      case "5":
+        state.start = !state.start;
+        break;
+      case "6":
+        state.activate = !state.activate;
+        break;
+      case "0":
+        return null;
+      default:
+        console.log("无效选项，请重新输入。");
+        break;
+    }
+  }
+}
+
+// 交互式执行 adopt 表单，先收集，再给出汇总确认。
+async function runAdoptWizard(rl, baseArgs) {
+  const state = {
+    name: "",
+    tunnelName: "",
+    specs: [],
+    ensureDns: false,
+    activate: false,
+  };
+
+  state.name = await askValidated(rl, "本地应用名称", (value) => validateNewAppName(baseArgs, value), {
+    example: "wchros-admin-dev",
+  });
+  if (!state.name) {
+    return null;
+  }
+  state.tunnelName = await chooseRemoteTunnelName(rl, baseArgs);
+  if (!state.tunnelName) {
+    return null;
+  }
+  state.specs = await collectRequiredIngressSpecs(rl);
+
+  while (true) {
+    const selection = await chooseMenuItem(rl, baseArgs, buildSetupReviewMenu("adopt", baseArgs, state));
+    switch (selection) {
+      case "1":
+        return state;
+      case "2":
+        state.name = await askValidated(rl, "本地应用名称", (value) => validateNewAppName(baseArgs, value), {
+          defaultValue: state.name,
+          example: "wchros-admin-dev",
+        });
+        if (!state.name) {
+          return null;
+        }
+        break;
+      case "3":
+        state.tunnelName = await chooseRemoteTunnelName(rl, baseArgs);
+        if (!state.tunnelName) {
+          return null;
+        }
+        break;
+      case "4":
+        state.specs = await collectRequiredIngressSpecs(rl);
+        break;
+      case "5":
+        state.ensureDns = !state.ensureDns;
+        break;
+      case "6":
+        state.activate = !state.activate;
+        break;
+      case "0":
+        return null;
+      default:
+        console.log("无效选项，请重新输入。");
+        break;
+    }
+  }
+}
+
+// 渲染主菜单。
+function printMenu(baseArgs, menu) {
+  console.log(menuLines(baseArgs, menu).join("\n"));
+}
+
+// 通过方向键或数字在当前菜单中选择一个动作。
+async function chooseMenuItem(rl, baseArgs, menu) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY || typeof process.stdin.setRawMode !== "function") {
+    printMenu(baseArgs, menu);
+    const answer = await ask(rl, "请选择操作");
+    return isBackKeyword(answer) ? "0" : answer;
+  }
+
+  emitKeypressEvents(process.stdin);
+  rl.pause();
+
+  return new Promise((resolve, reject) => {
+    let selectedIndex = 0;
+    let numberBuffer = "";
+    let pendingG = false;
+    let commandBuffer = "";
+    let renderedLineCount = 0;
+    const pageStep = Math.max(1, Math.floor(menu.items.length / 2));
+
+    const render = () => {
+      const lines = menuLines(baseArgs, menu, selectedIndex, numberBuffer, pendingG, commandBuffer);
+      if (renderedLineCount > 0) {
+        process.stdout.write(`\x1b[${renderedLineCount}F`);
+        process.stdout.write("\x1b[0J");
+      }
+      process.stdout.write(`${lines.join("\n")}\n`);
+      renderedLineCount = lines.length;
+    };
+
+    const cleanup = () => {
+      process.stdin.off("keypress", onKeypress);
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      rl.resume();
+    };
+
+    const resolveSelection = (value) => {
+      cleanup();
+      process.stdout.write("\n");
+      resolve(value);
+    };
+
+    const onKeypress = (str, key) => {
+      if (key?.ctrl && key.name === "c") {
+        cleanup();
+        reject(new Error("Aborted with Ctrl+C"));
+        return;
+      }
+      if (key?.ctrl && key.name === "u") {
+        selectedIndex = Math.max(0, selectedIndex - pageStep);
+        numberBuffer = "";
+        pendingG = false;
+        commandBuffer = "";
+        render();
+        return;
+      }
+      if (key?.ctrl && key.name === "d") {
+        selectedIndex = Math.min(menu.items.length - 1, selectedIndex + pageStep);
+        numberBuffer = "";
+        pendingG = false;
+        commandBuffer = "";
+        render();
+        return;
+      }
+      if (str !== "g") {
+        pendingG = false;
+      }
+      if (str === "k" && commandBuffer.length > 0) {
+          commandBuffer += str;
+          if (endsWithBackKeyword(commandBuffer)) {
+            resolveSelection("0");
+            return;
+          }
+          render();
+          return;
+      }
+      if (key?.name === "up" || str === "k") {
+        selectedIndex = (selectedIndex - 1 + menu.items.length) % menu.items.length;
+        numberBuffer = "";
+        commandBuffer = "";
+        render();
+        return;
+      }
+      if (key?.name === "down" || str === "j") {
+        selectedIndex = (selectedIndex + 1) % menu.items.length;
+        numberBuffer = "";
+        commandBuffer = "";
+        render();
+        return;
+      }
+      if (key?.name === "escape" || key?.name === "left" || str === "h") {
+        if (menu.key !== MAIN_MENU_KEY) {
+          resolveSelection("0");
+        }
+        return;
+      }
+      if (key?.name === "backspace") {
+        if (numberBuffer.length > 0) {
+          numberBuffer = numberBuffer.slice(0, -1);
+        } else {
+          commandBuffer = commandBuffer.slice(0, -1);
+        }
+        render();
+        return;
+      }
+      if (key?.name === "return" || key?.name === "enter") {
+        if (numberBuffer.length > 0) {
+          const normalizedChoice = normalizeMenuChoice(numberBuffer);
+          const item = menu.items.find((entry) => entry.value === normalizedChoice);
+          if (item) {
+            resolveSelection(item.value);
+            return;
+          }
+          numberBuffer = "";
+          render();
+          return;
+        }
+        if (commandBuffer.length > 0) {
+          if (endsWithBackKeyword(commandBuffer)) {
+            resolveSelection("0");
+            return;
+          }
+          commandBuffer = "";
+          render();
+          return;
+        }
+        resolveSelection(menu.items[selectedIndex].value);
+        return;
+      }
+      if (str === "l") {
+        resolveSelection(menu.items[selectedIndex].value);
+        return;
+      }
+      if (str === "G") {
+        selectedIndex = menu.items.length - 1;
+        numberBuffer = "";
+        commandBuffer = "";
+        render();
+        return;
+      }
+      if (str === "g") {
+        if (pendingG) {
+          selectedIndex = 0;
+          numberBuffer = "";
+          pendingG = false;
+          commandBuffer = "";
+        } else {
+          pendingG = true;
+        }
+        render();
+        return;
+      }
+      if (/^[0-9]$/.test(str)) {
+        numberBuffer += str;
+        commandBuffer = "";
+        render();
+        return;
+      }
+      if (str && !key?.ctrl && !key?.meta) {
+        const shouldStartCommand =
+          commandBuffer.length > 0 ||
+          str === "." ||
+          /^[bB]$/.test(str) ||
+          str === "返";
+        if (shouldStartCommand) {
+          commandBuffer += str;
+          numberBuffer = "";
+          if (endsWithBackKeyword(commandBuffer)) {
+            resolveSelection("0");
+            return;
+          }
+          render();
+          return;
+        }
+      }
+      if (str && ["q", "Q"].includes(str)) {
+        resolveSelection(menu.key === MAIN_MENU_KEY ? "0" : "0");
+      }
+    };
+
+    process.stdin.on("keypress", onKeypress);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    render();
+  });
+}
+
+// 在命名资源列表中选择一个项，可附加“手动输入”入口。
+async function chooseNamedOption(rl, baseArgs, options) {
+  const items = options.names.map((name, index) => ({
+    value: String(index + 1),
+    label: name,
+    hint: options.itemHint ?? "选择这个项目",
+    kind: options.itemKind ?? "secondary",
+    pickedName: name,
+  }));
+
+  if (options.allowManual) {
+    items.push({
+      value: String(items.length + 1),
+      label: options.manualLabel ?? "手动输入",
+      hint: options.manualHint ?? "输入未列出的名称",
+      kind: "assist",
+      manual: true,
+    });
+  }
+
+  items.push({
+    value: "0",
+    label: options.backLabel ?? "返回上一级",
+    hint: "不进行本次选择",
+    kind: "back",
+    back: true,
+  });
+
+  const menu = {
+    key: options.key,
+    title: options.title,
+    subtitle: options.subtitle,
+    breadcrumb: options.breadcrumb ?? "主菜单",
+    items,
+  };
+
+  const selection = await chooseMenuItem(rl, baseArgs, menu);
+  const item = menu.items.find((entry) => entry.value === selection);
+  if (!item || item.back) {
+    return "";
+  }
+  if (item.manual) {
+    return ask(rl, options.manualPrompt ?? "请输入名称");
+  }
+  return item.pickedName ?? "";
+}
+
+// 交互式选择受管应用名称，优先展示当前 profile 下已有应用。
+async function chooseManagedAppName(rl, baseArgs, options = {}) {
+  const appNames = listManagedApps(baseArgs);
+  if (appNames.length === 0) {
+    const typedName = await ask(rl, options.manualPrompt ?? "应用名称");
+    if (!typedName) {
+      return "";
+    }
+    console.log(`提示: 当前还没有受管应用记录，将尝试按默认 config.yml 自动接管“${typedName}”；如果失败，请先执行 add 或 adopt。`);
+    return typedName;
+  }
+  const selectedName = await chooseNamedOption(rl, baseArgs, {
+    key: options.key ?? "managed_app_picker",
+    title: options.title ?? "选择应用",
+    subtitle: options.subtitle ?? "优先从当前 profile 下已有的受管应用中选择。",
+    breadcrumb: options.breadcrumb ?? "主菜单 / 现有应用管理",
+    names: appNames,
+    itemHint: options.itemHint ?? "对这个应用继续操作",
+    itemKind: options.itemKind ?? "secondary",
+    allowManual: options.allowManual ?? true,
+    manualLabel: options.manualLabel ?? "手动输入其他应用名称",
+    manualHint: options.manualHint ?? "输入未列出的应用名称",
+    manualPrompt: options.manualPrompt ?? "应用名称",
+    backLabel: options.backLabel ?? "返回上一级",
+  });
+  if (!selectedName) {
+    return "";
+  }
+  if (appNames.includes(selectedName)) {
+    return selectedName;
+  }
+  console.log(`提示: “${selectedName}”不在当前受管应用列表中。将继续尝试按默认 config.yml 自动接管；如果失败，请先执行 add 或 adopt。`);
+  return selectedName;
+}
+
+// 为 status 选择应用目标，支持“查看全部应用”。
+async function chooseStatusTarget(rl, baseArgs) {
+  const appNames = listManagedApps(baseArgs);
+  const items = appNames.map((appName, index) => ({
+    value: String(index + 1),
+    label: appName,
+    hint: "只查看这个应用的状态",
+    kind: "secondary",
+    pickedName: appName,
+  }));
+
+  items.push({
+    value: String(items.length + 1),
+    label: "查看全部应用",
+    hint: "执行 status，不限定单个应用",
+    kind: "assist",
+    all: true,
+  });
+
+  items.push({
+    value: String(items.length + 1),
+    label: "手动输入应用名称",
+    hint: "输入未列出的应用名称",
+    kind: "assist",
+    manual: true,
+  });
+
+  items.push({
+    value: "0",
+    label: "返回上一级",
+    hint: "不进行本次选择",
+    kind: "back",
+    back: true,
+  });
+
+  const menu = {
+    key: "status_target_picker",
+    title: "选择状态查看范围",
+    subtitle: "可以查看单个应用，也可以查看全部应用。",
+    breadcrumb: "主菜单 / 现有应用管理 / 查看状态",
+    items,
+  };
+
+  const selection = await chooseMenuItem(rl, baseArgs, menu);
+  const item = menu.items.find((entry) => entry.value === selection);
+  if (!item || item.back) {
+    return { name: "", all: false, cancelled: true };
+  }
+  if (item.all) {
+    return { name: "", all: true, cancelled: false };
+  }
+  if (item.manual) {
+    const typedName = await ask(rl, "应用名称");
+    if (!typedName) {
+      return { name: "", all: false, cancelled: true };
+    }
+    if (!appNames.includes(typedName)) {
+      console.log(`提示: “${typedName}”不在当前受管应用列表中。将继续尝试按默认 config.yml 自动接管；如果失败，请先执行 add 或 adopt。`);
+    }
+    return { name: typedName, all: false, cancelled: false };
+  }
+  return { name: item.pickedName ?? "", all: false, cancelled: false };
+}
+
+// 交互式选择远端 tunnel 名称，优先展示当前账号的远端列表。
+async function chooseRemoteTunnelName(rl, baseArgs) {
+  const tunnelNames = listRemoteTunnels(baseArgs);
+  if (tunnelNames.length === 0) {
+    return ask(rl, "已有远端 tunnel 名称");
+  }
+  return chooseNamedOption(rl, baseArgs, {
+    key: "remote_tunnel_picker",
+    title: "选择远端 Tunnel",
+    subtitle: "优先从当前账号下已有的远端 tunnels 中选择。",
+    breadcrumb: "主菜单 / 新建与接管",
+    names: tunnelNames,
+    itemHint: "使用这个远端 tunnel",
+    allowManual: true,
+    manualLabel: "手动输入其他 tunnel 名称",
+    manualHint: "输入未列出的远端 tunnel 名称",
+    manualPrompt: "已有远端 tunnel 名称",
+    backLabel: "返回上一级",
+  });
+}
+
+// 构造 add/adopt 使用的 ingress 参数。
+function buildIngressArgs(specs) {
+  const args = [];
+  for (const spec of specs) {
+    args.push("--ingress", spec);
+  }
+  return args;
+}
+
+// 根据输入构造 ingress-remove 参数。
+function buildRemoveArgs(specs) {
+  const args = [];
+  for (const spec of specs) {
+    if (/^[1-9][0-9]*$/.test(spec)) {
+      args.push("--index", spec);
+    } else {
+      args.push("--hostname", spec);
+    }
+  }
+  return args;
+}
+
+// 交互式处理一次菜单动作。
+async function handleAction(rl, baseArgs, action, context = {}) {
+  let name = context.appName ?? "";
+  let tunnelName = "";
+  let specs = [];
+  let args = [];
+  let follow = false;
+
+  try {
+    switch (action) {
+      case "1":
+        runShell(baseArgs, ["doctor"]);
+        return { keepRunning: true };
+      case "2":
+        runShell(baseArgs, ["list"]);
+        return { keepRunning: true };
+      case "3":
+        runShell(baseArgs, ["tunnels"]);
+        return { keepRunning: true };
+      case "4":
+        if (!name) {
+          name = await chooseManagedAppName(rl, baseArgs, {
+            key: "show_app_picker",
+            title: "选择要查看详情的应用",
+            itemHint: "查看这个应用的详情",
+          });
+        }
+        if (!name) return { keepRunning: true };
+        runShell(baseArgs, ["show", name]);
+        return { keepRunning: true };
+      case "5":
+        {
+          const addState = await runAddWizard(rl, baseArgs);
+          if (!addState) {
+            console.log("已取消创建新 tunnel。");
+            return { keepRunning: true };
+          }
+          args = ["add", addState.name, "--tunnel-name", addState.tunnelName, ...buildIngressArgs(addState.specs)];
+          if (addState.start) args.push("--start");
+          if (addState.activate) args.push("--activate");
+          runShell(baseArgs, args);
+          return { keepRunning: true };
+        }
+      case "6":
+        {
+          const adoptState = await runAdoptWizard(rl, baseArgs);
+          if (!adoptState) {
+            console.log("已取消接管已有 tunnel。");
+            return { keepRunning: true };
+          }
+          args = ["adopt", adoptState.name, "--tunnel-name", adoptState.tunnelName, ...buildIngressArgs(adoptState.specs)];
+          if (adoptState.ensureDns) args.push("--ensure-dns");
+          if (adoptState.activate) args.push("--activate");
+          runShell(baseArgs, args);
+          return { keepRunning: true };
+        }
+      case "7":
+        if (!name) {
+          name = await chooseManagedAppName(rl, baseArgs, {
+            key: "modify_app_picker",
+            title: "选择要修改 ingress 的应用",
+            itemHint: "修改这个应用的 ingress 规则",
+          });
+        }
+        if (!name) return { keepRunning: true };
+        {
+          const modifyState = await runModifyWizard(rl, baseArgs, name);
+          if (!modifyState) {
+            console.log("已取消修改 ingress。");
+            return { keepRunning: true };
+          }
+          args = ["modify", name];
+          for (const spec of modifyState.specs) {
+            args.push("--set", spec);
+          }
+          if (modifyState.noRestart) args.push("--no-restart");
+          runShell(baseArgs, args);
+          return { keepRunning: true };
+        }
+      case "8":
+        if (!name) {
+          name = await chooseManagedAppName(rl, baseArgs, {
+            key: "ingress_add_app_picker",
+            title: "选择要新增 ingress 的应用",
+            itemHint: "为这个应用新增 ingress 规则",
+          });
+        }
+        if (!name) return { keepRunning: true };
+        {
+          const addState = await runIngressAddWizard(rl, baseArgs, name);
+          if (!addState) {
+            console.log("已取消新增 ingress。");
+            return { keepRunning: true };
+          }
+          args = ["ingress-add", name, ...buildIngressArgs(addState.specs)];
+          if (addState.noRestart) args.push("--no-restart");
+          runShell(baseArgs, args);
+          return { keepRunning: true };
+        }
+      case "9":
+        if (!name) {
+          name = await chooseManagedAppName(rl, baseArgs, {
+            key: "ingress_remove_app_picker",
+            title: "选择要删除 ingress 的应用",
+            itemHint: "删除这个应用的 ingress 规则",
+          });
+        }
+        if (!name) return { keepRunning: true };
+        {
+          const removeState = await runIngressRemoveWizard(rl, baseArgs, name);
+          if (!removeState) {
+            console.log("已取消删除 ingress。");
+            return { keepRunning: true };
+          }
+          args = ["ingress-remove", name, ...buildRemoveArgs(removeState.specs)];
+          if (removeState.noRestart) args.push("--no-restart");
+          runShell(baseArgs, args);
+          return { keepRunning: true };
+        }
+      case "10":
+        if (!name) {
+          name = await chooseManagedAppName(rl, baseArgs, {
+            key: "start_app_picker",
+            title: "选择要启动的应用",
+            itemHint: "启动这个应用",
+          });
+        }
+        if (!name) return { keepRunning: true };
+        runShell(baseArgs, ["start", name]);
+        return { keepRunning: true };
+      case "11":
+        if (!name) {
+          name = await chooseManagedAppName(rl, baseArgs, {
+            key: "stop_app_picker",
+            title: "选择要停止的应用",
+            itemHint: "停止这个应用",
+          });
+        }
+        if (!name) return { keepRunning: true };
+        runShell(baseArgs, ["stop", name]);
+        return { keepRunning: true };
+      case "12":
+        if (!name) {
+          name = await chooseManagedAppName(rl, baseArgs, {
+            key: "restart_app_picker",
+            title: "选择要重启的应用",
+            itemHint: "重启这个应用",
+          });
+        }
+        if (!name) return { keepRunning: true };
+        runShell(baseArgs, ["restart", name]);
+        return { keepRunning: true };
+      case "13":
+        if (!name) {
+          const target = await chooseStatusTarget(rl, baseArgs);
+          if (target.cancelled) return { keepRunning: true };
+          if (!target.all) {
+            name = target.name;
+          }
+        }
+        runShell(baseArgs, name ? ["status", name] : ["status"]);
+        return { keepRunning: true };
+      case "14":
+        if (!name) {
+          name = await chooseManagedAppName(rl, baseArgs, {
+            key: "logs_app_picker",
+            title: "选择要查看日志的应用",
+            itemHint: "查看这个应用的日志",
+          });
+        }
+        if (!name) return { keepRunning: true };
+        follow = await askYesNo(rl, "是否持续跟随日志", false);
+        runShell(baseArgs, follow ? ["logs", name, "-f"] : ["logs", name]);
+        return { keepRunning: true };
+      case "15":
+        if (!name) {
+          name = await chooseManagedAppName(rl, baseArgs, {
+            key: "activate_app_picker",
+            title: "选择要激活的应用",
+            itemHint: "把这个应用激活为默认配置",
+          });
+        }
+        if (!name) return { keepRunning: true };
+        runShell(baseArgs, ["activate", name]);
+        return { keepRunning: true };
+      case "16":
+        if (!name) {
+          name = await chooseManagedAppName(rl, baseArgs, {
+            key: "delete_app_picker",
+            title: "选择要删除的应用",
+            itemHint: "删除这个受管应用",
+          });
+        }
+        if (!name) return { keepRunning: true };
+        args = ["delete", name];
+        if (await askYesNo(rl, "是否同时删除远端 tunnel", false)) args.push("--delete-tunnel");
+        runShell(baseArgs, args);
+        return { keepRunning: true, nextMenuKey: "app_picker", clearAppName: true };
+      case "17":
+        args = ["init"];
+        if (await askYesNo(rl, "是否同时执行 login", false)) args.push("--login");
+        runShell(baseArgs, args);
+        return { keepRunning: true };
+      case "18":
+        runShell(baseArgs, ["use"]);
+        return { keepRunning: true };
+      case "19":
+        runShell(baseArgs, ["login"]);
+        return { keepRunning: true };
+      case "20": {
+        const source = await ask(rl, "证书来源路径，留空则使用默认 cert.pem");
+        runShell(baseArgs, source ? ["import-cert", source] : ["import-cert"]);
+        return { keepRunning: true };
+      }
+      case "21": {
+        const raw = await ask(rl, "输入脚本参数，例如 doctor 或 start demo");
+        if (!raw) return { keepRunning: true };
+        try {
+          runShell(baseArgs, splitCommandLine(raw));
+        } catch (error) {
+          console.error(`错误: ${error.message}`);
+        }
+        return { keepRunning: true };
+      }
+      case "22": {
+        if (!name) {
+          name = await chooseManagedAppName(rl, baseArgs, {
+            key: "ingress_list_app_picker",
+            title: "选择要查看 ingress 的应用",
+            itemHint: "查看这个应用的 ingress 列表",
+          });
+        }
+        if (!name) return { keepRunning: true };
+        runShell(baseArgs, ["ingress-list", name]);
+        return { keepRunning: true };
+      }
+      case "0":
+      case "q":
+      case "quit":
+      case "exit":
+        return { keepRunning: false };
+      default:
+        console.log("无效选项，请重新输入。");
+        return { keepRunning: true };
+    }
+  } catch (error) {
+    if (error instanceof BackToMenuError) {
+      console.log("已取消当前操作，返回主菜单。");
+      return { keepRunning: true, nextMenuKey: MAIN_MENU_KEY, clearAppName: true };
+    }
+    throw error;
+  }
+}
+
+// 运行交互式菜单。
+async function runInteractive(baseArgs) {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    let keepRunning = true;
+    let currentMenuKey = MAIN_MENU_KEY;
+    let currentAppName = "";
+    while (keepRunning) {
+      const menu = buildMenu(baseArgs, currentMenuKey, currentAppName);
+      const selection = await chooseMenuItem(rl, baseArgs, menu);
+      const item = menu.items.find((entry) => entry.value === selection);
+
+      if (!item) {
+        console.log("无效选项，请重新输入。");
+        continue;
+      }
+
+      if (item.exit) {
+        keepRunning = false;
+        continue;
+      }
+
+      if (item.disabled) {
+        console.log("当前没有可选项目。");
+        continue;
+      }
+
+      if (item.back) {
+        if (currentMenuKey === "app_detail") {
+          currentMenuKey = "app_picker";
+          currentAppName = "";
+        } else {
+          currentMenuKey = MAIN_MENU_KEY;
+        }
+        continue;
+      }
+
+      if (item.appName) {
+        currentAppName = item.appName;
+        currentMenuKey = "app_detail";
+        continue;
+      }
+
+      if (item.next) {
+        currentMenuKey = item.next;
+        continue;
+      }
+
+      if (item.action) {
+        const result = await handleAction(rl, baseArgs, item.action, { appName: currentAppName });
+        keepRunning = result.keepRunning;
+        if (result.clearAppName) {
+          currentAppName = "";
+        }
+        if (result.nextMenuKey) {
+          currentMenuKey = result.nextMenuKey;
+        }
+      }
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+// 主入口，决定转发模式还是交互模式。
+async function main() {
+  if (!existsSync(SHELL_SCRIPT)) {
+    fail(`找不到底层脚本: ${SHELL_SCRIPT}`);
+  }
+
+  const rawArgs = process.argv.slice(2);
+  const wantsInteractive =
+    rawArgs.length === 0 || rawArgs.some((arg) => INTERACTIVE_FLAGS.has(arg));
+  const baseArgs = rawArgs.filter((arg) => !INTERACTIVE_FLAGS.has(arg));
+
+  if (!wantsInteractive) {
+    runShell([], rawArgs, { exitOnComplete: true });
+    return;
+  }
+
+  await runInteractive(baseArgs);
+}
+
+main().catch((error) => {
+  fail(error.message);
+});