@lasting-beauty/chat-hub 0.1.0-beta.1

package/bin/chat-hub.mjs

@@ -0,0 +1,1794 @@
+#!/usr/bin/env node
+import { execFileSync, spawn } from 'node:child_process';
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { createRequire } from 'node:module';
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  mkdtempSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { homedir, networkInterfaces, tmpdir } from 'node:os';
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { createServer, isIP } from 'node:net';
+import {
+  alinuxCaddyRelease,
+  alinuxCaddySystemdUnit,
+  assertSupportedDeploymentHost,
+  createDeploymentPlan,
+  detectDeploymentHost,
+  deploymentPaths,
+  stageAdministratorReset,
+  stageDeployment,
+  verifiedPlatformCliVersionPatterns,
+} from '../cli/deploy.mjs';
+import {
+  createStoppedBackup,
+  pruneUpgradeBackups,
+  stageRestore,
+  validateBackup,
+} from '../cli/data-lifecycle.mjs';
+import { verifyExternalDeployment } from '../cli/external-verification.mjs';
+import {
+  consumePurgeConfirmation,
+  createPurgeConfirmation,
+  stageUninstall,
+  validatePurgeConfirmation,
+} from '../cli/server-maintenance.mjs';
+import { fetchInternalGateway, verifyServerDeployment } from '../cli/server-verification.mjs';
+import { migrateLegacyWindowsData } from '../cli/windows-data-migration.mjs';
+import { PlatformCommandError, runPlatformCommand } from '../cli/platform.mjs';
+import {
+  certbotIssueArguments,
+  certbotVersionSupported,
+  ipCertificateAutomationPaths,
+  stageIpCertificateAutomation,
+  stageIpCertificateChallenge,
+} from '../cli/ip-certificate.mjs';
+
+const packageRoot = realpathSync(resolve(import.meta.dirname, '..'));
+const packageRequire = createRequire(import.meta.url);
+const help = `Chat Hub 命令行
+
+用法：chat-hub <doctor|diagnose|platform|start|status|stop|restart|logs|deploy|verify-server|verify-external|admin-reset|backup|restore|upgrade|uninstall|purge> [选项]
+
+  doctor               只读检查运行环境与平台 CLI
+  diagnose             输出不含凭证和业务正文的本地诊断
+  platform login/status 以 chat-hub 服务用户完成平台授权或查看脱敏状态
+  start [--lan]         后台启动；默认仅本机回环访问
+  status               查看当前实例状态
+  stop                 停止本命令管理的健康实例并保留数据
+  restart [--lan]       显式重启并应用新参数
+  logs                 显示日志文件位置
+  deploy --domain <域名> 输出域名 HTTPS 计划；无域名正式入口使用 --ip <公网IPv4>
+  verify-server         只读验收已部署的 Linux 服务、权限、端口和公网入口
+  verify-external       从另一网络验收公网入口和内部端口公网阻断
+  admin-reset          服务器上重置管理员密码并立即撤销全部旧会话
+  backup               停止服务器服务后创建一致性本地备份
+  restore <备份目录名>  校验备份、可回滚恢复并重置管理员会话
+  upgrade [--to <版本>] 用当前安装包升级服务器，升级前备份并保留最近 3 份
+  uninstall            移除服务器服务和代理配置，保留数据、凭证与备份
+  purge                显示删除路径并生成 10 分钟二次确认令牌
+
+选项：
+  --data-dir <目录>      数据目录（必须位于安装包外）
+  --runtime-dir <目录>   运行状态目录（必须位于安装包外）
+  --lan                  启用可信局域网 HTTP 与一次性配对
+  --lan-ip <IPv4>        多网卡时指定可信局域网地址
+  --api-port <端口>      内部应用端口，默认 4310
+  --http-port <端口>     本机/LAN 入口端口，默认 8080
+  --domain <域名>        公网部署域名
+  --ip <公网IPv4>        使用 Certbot 5.4+ shortlived 证书部署正式 IP HTTPS
+  --email <邮箱>         IP HTTPS 证书到期联系邮箱（apply 时必填）
+  --http-ip <公网IPv4>   显式启用不加密的临时公网 HTTP 部署（高风险）
+  --new-app             飞书首次登录时明确创建新应用
+  --app-id <App ID>     飞书首次登录时绑定已有应用；Secret 从 stdin 读取
+  --origin <IP>          外部验收时指定 ECS 公网 IP（域名经过 CDN 时使用）
+  --apply                确认并应用受支持 Linux 的 systemd/Caddy 部署计划
+  --install-dependencies 在部署计划中包含受控系统依赖安装
+  --to <版本>           断言当前执行包的精确版本，用于受控服务器升级
+  --confirm <令牌>      执行 purge 首次调用生成的二次确认
+
+默认不自动安装依赖或更新。deploy --apply、upgrade、uninstall 和确认后的 purge 会修改受支持的 Linux 系统。`;
+
+const { command, options, positionals } = parseArguments(process.argv.slice(2));
+
+if (!command || command === 'help') {
+  console.log(help);
+  process.exit(0);
+}
+
+main().catch((error) => {
+  console.error(
+    JSON.stringify(
+      {
+        ok: false,
+        ...(typeof error?.code === 'string' ? { code: error.code } : {}),
+        error: error instanceof Error ? error.message : '命令执行失败',
+      },
+      null,
+      2,
+    ),
+  );
+  process.exitCode = 1;
+});
+
+async function main() {
+  if (
+    ![
+      'doctor',
+      'diagnose',
+      'platform',
+      'start',
+      'status',
+      'stop',
+      'restart',
+      'logs',
+      'deploy',
+      'verify-server',
+      'verify-external',
+      'admin-reset',
+      'backup',
+      'restore',
+      'upgrade',
+      'uninstall',
+      'purge',
+    ].includes(command)
+  ) {
+    throw new Error('未知命令，请运行 chat-hub --help');
+  }
+  assertCommandOptions();
+  assertSupportedNode();
+  if (command !== 'restore' && command !== 'platform' && positionals.length > 0)
+    throw new Error('当前命令不接受位置参数');
+  if (command === 'platform') return report(platformCommand());
+  if (command === 'deploy') return report(await deploy());
+  if (command === 'verify-server') {
+    const result = await verifyServer();
+    report({ ok: result.passed, ...result });
+    if (!result.passed) process.exitCode = 1;
+    return;
+  }
+  if (command === 'verify-external') {
+    const result = await verifyExternal();
+    report({ ok: result.passed, ...result });
+    if (!result.passed) process.exitCode = 1;
+    return;
+  }
+  if (command === 'admin-reset') return report(await resetAdministrator());
+  if (command === 'backup') return report(await backupServerData());
+  if (command === 'upgrade') return report(await upgradeServer());
+  if (command === 'uninstall') return report(await uninstallServer());
+  if (command === 'purge') return report(await purgeServer());
+  if (command === 'restore') {
+    if (positionals.length !== 1) throw new Error('restore 必须提供一个备份目录名');
+    return report(await restoreServerData(positionals[0]));
+  }
+  const runtimeDirectory = checkedExternalDirectory(
+    options['--runtime-dir'] ?? defaultRuntimeDirectory(),
+  );
+  const configPath = join(runtimeDirectory, 'config.json');
+  const statePath = join(runtimeDirectory, 'state.json');
+  const saved = readJson(configPath);
+
+  if (command === 'doctor') return report(runDoctor(runtimeDirectory));
+  if (command === 'diagnose') return report(runDiagnosis(runtimeDirectory));
+  if (command === 'logs') {
+    return report({
+      runtimeDirectory,
+      stdout: join(runtimeDirectory, 'chat-hub.log'),
+      bootstrapErrors: join(runtimeDirectory, 'bootstrap-error.log'),
+    });
+  }
+  if (command === 'status') return report(await currentStatus(saved, statePath));
+  if (command === 'stop') return report(await stop(saved, statePath));
+
+  if (command === 'restart' && saved) await stop(saved, statePath);
+  if (command === 'start' && saved) {
+    const status = await currentStatus(saved, statePath);
+    if (status.running && status.healthy) {
+      if (hasRuntimeChanges(saved)) {
+        throw new Error('运行参数有变化，请显式使用 chat-hub restart');
+      }
+      return report({
+        reused: true,
+        localUrl: `http://127.0.0.1:${saved.httpPort}`,
+        phoneUrl: phoneUrl(saved),
+        runtimeDirectory,
+      });
+    }
+    if (status.running) {
+      throw new Error('已有进程但健康检查失败；不会停止未知状态进程，请先检查日志');
+    }
+  }
+
+  assertPackagedRuntime();
+  const dataDirectory = checkedExternalDirectory(
+    options['--data-dir'] ?? saved?.dataDirectory ?? (await defaultDataDirectory()),
+  );
+  if (saved?.dataDirectory && saved.dataDirectory !== dataDirectory) {
+    throw new Error('已有实例的数据目录不能在启动时更换；请先执行受控迁移');
+  }
+  mkdirSecure(runtimeDirectory);
+  mkdirSecure(dataDirectory);
+  const apiPort = parsePort('--api-port', saved?.apiPort ?? 4310);
+  const httpPort = parsePort('--http-port', saved?.httpPort ?? 8080);
+  if (apiPort === httpPort) throw new Error('内部应用端口和入口端口必须不同');
+  await freePort(apiPort, '127.0.0.1');
+  await freePort(httpPort, '127.0.0.1');
+
+  const lan = selectLan(saved);
+  if (lan) await freePort(httpPort, lan.address);
+  const masterKeyFile =
+    process.platform === 'linux' ? ensureLocalLinuxMasterKey(runtimeDirectory) : undefined;
+  const larkCliPath = process.env.LARK_CLI_PATH ?? packagedPlatformCliEntry('lark-cli');
+  const dingtalkCliPath = process.env.DINGTALK_CLI_PATH ?? packagedPlatformCliEntry('dws');
+  const id = createHash('sha256').update(dataDirectory).digest('hex').slice(0, 16);
+  const config = {
+    id,
+    runId: randomUUID(),
+    packageRoot,
+    runtimeDirectory,
+    dataDirectory,
+    apiPort,
+    httpPort,
+    frontendPort: apiPort,
+    phoneProtocol: 'http',
+    lanIp: lan?.address,
+    netmask: lan?.netmask,
+    environment: {
+      CHAT_HUB_HOST: '127.0.0.1',
+      CHAT_HUB_PORT: String(apiPort),
+      CHAT_HUB_DATA_DIR: dataDirectory,
+      CHAT_HUB_STATIC_DIR: join(packageRoot, 'dist'),
+      ...(masterKeyFile ? { CHAT_HUB_MASTER_KEY_FILE: masterKeyFile } : {}),
+      ...(process.env.CHAT_HUB_ACCOUNT_KEY
+        ? { CHAT_HUB_ACCOUNT_KEY: process.env.CHAT_HUB_ACCOUNT_KEY }
+        : {}),
+      ...(larkCliPath ? { LARK_CLI_PATH: larkCliPath } : {}),
+      ...(dingtalkCliPath ? { DINGTALK_CLI_PATH: dingtalkCliPath } : {}),
+    },
+  };
+  writeJson(configPath, config);
+  const log = openSync(join(runtimeDirectory, 'chat-hub.log'), 'a', 0o600);
+  const errorLog = openSync(join(runtimeDirectory, 'bootstrap-error.log'), 'a', 0o600);
+  try {
+    const child = spawn(process.execPath, [join(packageRoot, 'cli', 'runtime.mjs'), configPath], {
+      cwd: runtimeDirectory,
+      detached: true,
+      windowsHide: true,
+      stdio: ['ignore', log, errorLog],
+    });
+    child.unref();
+  } finally {
+    closeSync(log);
+    closeSync(errorLog);
+  }
+  const deadline = Date.now() + 45_000;
+  while (Date.now() < deadline) {
+    if (await probe(config)) {
+      return report({
+        started: true,
+        localUrl: `http://127.0.0.1:${httpPort}`,
+        phoneUrl: phoneUrl(config),
+        pairingPage: lan ? `http://127.0.0.1:${httpPort}/__setup/phone` : undefined,
+        runtimeDirectory,
+        autoStartAtLogin: false,
+      });
+    }
+    const state = readJson(statePath);
+    if (state?.runId === config.runId && state.status === 'failed') break;
+    await delay(250);
+  }
+  throw new Error('启动未通过健康检查，请运行 chat-hub logs 查看原因');
+}
+
+function assertCommandOptions() {
+  const commonRuntime = new Set(['--runtime-dir']);
+  const allowedByCommand = {
+    doctor: commonRuntime,
+    diagnose: commonRuntime,
+    platform: new Set(['--new-app', '--app-id', '--device']),
+    logs: commonRuntime,
+    status: commonRuntime,
+    stop: commonRuntime,
+    start: new Set([
+      '--runtime-dir',
+      '--data-dir',
+      '--lan',
+      '--lan-ip',
+      '--api-port',
+      '--http-port',
+    ]),
+    restart: new Set([
+      '--runtime-dir',
+      '--data-dir',
+      '--lan',
+      '--lan-ip',
+      '--api-port',
+      '--http-port',
+    ]),
+    deploy: new Set([
+      '--domain',
+      '--ip',
+      '--email',
+      '--http-ip',
+      '--apply',
+      '--install-dependencies',
+    ]),
+    'verify-server': new Set(),
+    'verify-external': new Set(['--domain', '--ip', '--http-ip', '--origin']),
+    'admin-reset': new Set(),
+    backup: new Set(),
+    restore: new Set(),
+    upgrade: new Set(['--to']),
+    uninstall: new Set(),
+    purge: new Set(['--confirm']),
+  };
+  const allowed = allowedByCommand[command];
+  if (!allowed) return;
+  const invalid = Object.keys(options).find((option) => !allowed.has(option));
+  if (invalid) throw new Error(`${command} 不支持选项 ${invalid}`);
+}
+
+function parseArguments(values) {
+  if (values.length === 0 || values.includes('--help') || values.includes('-h')) {
+    return { command: 'help', options: {}, positionals: [] };
+  }
+  const command = values.shift();
+  const options = {};
+  const positionals = [];
+  const supported = new Set([
+    '--data-dir',
+    '--runtime-dir',
+    '--lan',
+    '--lan-ip',
+    '--api-port',
+    '--http-port',
+    '--domain',
+    '--ip',
+    '--email',
+    '--http-ip',
+    '--new-app',
+    '--app-id',
+    '--device',
+    '--origin',
+    '--apply',
+    '--install-dependencies',
+    '--to',
+    '--confirm',
+  ]);
+  for (let index = 0; index < values.length; index++) {
+    const key = values[index];
+    if (!key.startsWith('--')) {
+      positionals.push(key);
+      continue;
+    }
+    if (!supported.has(key) || key in options) throw new Error('未知或重复的选项，请查看 --help');
+    if (
+      key === '--lan' ||
+      key === '--apply' ||
+      key === '--install-dependencies' ||
+      key === '--new-app' ||
+      key === '--device'
+    )
+      options[key] = true;
+    else {
+      const value = values[++index];
+      if (!value || value.startsWith('--')) throw new Error(`${key} 缺少值`);
+      options[key] = value;
+    }
+  }
+  return { command, options, positionals };
+}
+
+async function defaultDataDirectory() {
+  if (process.platform === 'darwin')
+    return join(homedir(), 'Library', 'Application Support', 'Chat Hub');
+  if (process.platform === 'win32') {
+    const current = join(
+      process.env.LOCALAPPDATA ?? join(homedir(), 'AppData', 'Local'),
+      'Chat Hub',
+    );
+    const legacy = join(homedir(), 'Library', 'Application Support', 'Chat Hub');
+    if (!existsSync(legacy)) return current;
+    const { default: Database } = await import('better-sqlite3');
+    return migrateLegacyWindowsData({
+      legacyDirectory: legacy,
+      currentDirectory: current,
+      backupRoot: join(dirname(current), 'Chat Hub Migration Backups'),
+      verifyCopy(directory) {
+        const databasePath = join(directory, 'chat-hub.sqlite');
+        if (!existsSync(databasePath)) return;
+        const database = new Database(databasePath, { readonly: true, fileMustExist: true });
+        try {
+          const result = database.pragma('quick_check', { simple: true });
+          if (result !== 'ok') throw new Error(`SQLite 快速完整性检查失败：${String(result)}`);
+        } finally {
+          database.close();
+        }
+      },
+    }).currentDirectory;
+  }
+  return join(process.env.XDG_STATE_HOME ?? join(homedir(), '.local', 'state'), 'chat-hub');
+}
+
+function defaultRuntimeDirectory() {
+  if (process.platform === 'win32') {
+    return join(
+      process.env.LOCALAPPDATA ?? join(homedir(), 'AppData', 'Local'),
+      'Chat Hub',
+      'runtime',
+    );
+  }
+  return join(process.env.XDG_RUNTIME_DIR ?? join(homedir(), '.chat-hub'), 'chat-hub');
+}
+
+function checkedExternalDirectory(value) {
+  const directory = resolve(value);
+  const pathFromPackage = relative(packageRoot, directory);
+  if (
+    pathFromPackage === '' ||
+    (pathFromPackage !== '..' &&
+      !pathFromPackage.startsWith(`..${sep}`) &&
+      !isAbsolute(pathFromPackage))
+  ) {
+    throw new Error('数据和运行目录必须位于 Chat Hub 安装包之外');
+  }
+  return directory;
+}
+
+function assertSupportedNode() {
+  const [major, minor, patch] = process.versions.node.split('.').map(Number);
+  const supported22 = major === 22 && (minor > 22 || (minor === 22 && patch >= 2));
+  const supported24 = major === 24 && minor >= 15;
+  if (!(supported22 || supported24)) {
+    throw new Error('首个 beta 需要 Node.js 22.22.2+ 的 22.x 或 24.15+ 的 24.x');
+  }
+}
+
+function assertPackagedRuntime() {
+  for (const path of [
+    join(packageRoot, 'dist', 'index.html'),
+    join(packageRoot, 'dist', 'server', 'index.js'),
+    join(packageRoot, 'cli', 'runtime.mjs'),
+    join(packageRoot, 'skills', 'chat-hub-setup', 'scripts', 'gateway.mjs'),
+    packagedPlatformCliEntry('lark-cli'),
+    packagedPlatformCliEntry('dws'),
+  ]) {
+    if (!path || !existsSync(path)) {
+      throw new Error(`安装包缺少生产文件：${path ? relative(packageRoot, path) : '平台 CLI'}`);
+    }
+  }
+}
+
+function runDoctor(runtimeDirectory) {
+  const versions = {};
+  for (const executable of ['npm', 'lark-cli', 'dws']) {
+    try {
+      const selected =
+        executable === 'npm'
+          ? process.env.npm_execpath
+            ? { executable: process.execPath, prefixArgs: [process.env.npm_execpath] }
+            : { executable: 'npm', prefixArgs: [] }
+          : executableInvocation(selectedPlatformCli(executable));
+      versions[executable] = execFileSync(
+        selected.executable,
+        [...selected.prefixArgs, '--version'],
+        {
+          encoding: 'utf8',
+          timeout: 10_000,
+          stdio: 'pipe',
+          windowsHide: true,
+        },
+      )
+        .trim()
+        .split(/\r?\n/)[0];
+    } catch {
+      versions[executable] = '不可执行';
+    }
+  }
+  return {
+    platform: process.platform,
+    architecture: process.arch,
+    serverDeploymentHost: detectDeploymentHost(),
+    node: process.version,
+    packageVersion: readCurrentPackageVersion(),
+    packageRoot,
+    packageReady: [
+      join(packageRoot, 'dist', 'index.html'),
+      join(packageRoot, 'dist', 'server', 'index.js'),
+      packagedPlatformCliEntry('lark-cli'),
+      packagedPlatformCliEntry('dws'),
+    ].every((path) => Boolean(path && existsSync(path))),
+    runtimeDirectory,
+    stableCommand: stableCommandStatus(),
+    lanAddresses: lanAddresses(),
+    versions,
+  };
+}
+
+function runDiagnosis(runtimeDirectory) {
+  const doctor = runDoctor(runtimeDirectory);
+  const manifest = existsSync(deploymentPaths.manifest) ? readDeploymentManifest() : undefined;
+  const runtimeConfig = readJson(join(runtimeDirectory, 'config.json'));
+  const runtimeState = readJson(join(runtimeDirectory, 'state.json'));
+  return {
+    generatedAt: new Date().toISOString(),
+    redacted: true,
+    includesBusinessContent: false,
+    includesCredentials: false,
+    environment: doctor,
+    localRuntime: {
+      configured: Boolean(runtimeConfig),
+      processRunning: Boolean(runtimeState?.pid && isProcessAlive(runtimeState.pid)),
+      lastCode: typeof runtimeState?.code === 'string' ? runtimeState.code : undefined,
+    },
+    server: manifest
+      ? {
+          installed: true,
+          publicScheme: manifest.publicScheme,
+          publicHost: manifest.publicHost,
+          chatHubService: systemServiceActive('chat-hub.service') ? 'active' : 'inactive',
+          caddyService: systemServiceActive('caddy.service') ? 'active' : 'inactive',
+          certificateRenewalTimer: systemServiceActive('chat-hub-cert-renew.timer')
+            ? 'active'
+            : manifest.certificateMode === 'ip-shortlived'
+              ? 'inactive'
+              : 'not_applicable',
+        }
+      : { installed: false },
+  };
+}
+
+function stableCommandStatus() {
+  const expected = realpathSync(join(packageRoot, 'bin', 'chat-hub.mjs'));
+  let detected;
+  try {
+    const output = execFileSync(
+      process.platform === 'win32' ? 'where.exe' : 'which',
+      ['chat-hub'],
+      {
+        encoding: 'utf8',
+        timeout: 10_000,
+        stdio: 'pipe',
+      },
+    );
+    detected = output.trim().split(/\r?\n/)[0];
+  } catch {
+    return {
+      ready: false,
+      code: 'chat_hub_not_on_path',
+      expected,
+      nextStep: '使用安装器建立 /usr/local/bin/chat-hub，或把 npm 全局 bin 加入 PATH',
+    };
+  }
+  return {
+    ready: true,
+    detected,
+    expected,
+    currentPackage:
+      resolve(detected) === expected || resolve(detected) === join(packageRoot, 'bin', 'chat-hub'),
+  };
+}
+
+function platformCommand() {
+  assertSupportedDeploymentHost({ commandName: 'platform' });
+  if (positionals.length < 1 || positionals.length > 2) {
+    throw new PlatformCommandError(
+      'platform_usage_invalid',
+      '用法：chat-hub platform status [lark|dingtalk]，或 chat-hub platform login <lark|dingtalk>',
+    );
+  }
+  const [action, requestedPlatform] = positionals;
+  if (!['status', 'login'].includes(action)) {
+    throw new PlatformCommandError('platform_action_invalid', 'platform 只支持 login 或 status');
+  }
+  const targets = requestedPlatform ? [requestedPlatform] : ['lark', 'dingtalk'];
+  if (targets.some((platform) => !['lark', 'dingtalk'].includes(platform))) {
+    throw new PlatformCommandError('platform_invalid', '平台必须是 lark 或 dingtalk');
+  }
+  if (action === 'login' && targets.length !== 1) {
+    throw new PlatformCommandError('platform_required', 'platform login 必须指定 lark 或 dingtalk');
+  }
+  if (Boolean(options['--new-app']) && Boolean(options['--app-id'])) {
+    throw new PlatformCommandError(
+      'lark_initialization_choice_conflict',
+      '--new-app 与 --app-id 只能选择一个',
+    );
+  }
+  const resolveInvocation = (platform) => {
+    const executable = platform === 'lark' ? 'lark-cli' : 'dws';
+    const pattern = verifiedPlatformCliVersionPatterns[executable];
+    return executableInvocation(compatibleCli(executable, pattern));
+  };
+  const status = (platform) =>
+    runPlatformCommand({ platform, action: 'status', resolveInvocation });
+  if (action === 'status') {
+    return {
+      platforms: targets.map((platform) => {
+        try {
+          return status(platform);
+        } catch (error) {
+          return {
+            platform,
+            configured: false,
+            authenticated: false,
+            status: 'unavailable',
+            code: error instanceof PlatformCommandError ? error.code : 'platform_status_failed',
+          };
+        }
+      }),
+    };
+  }
+  const platform = targets[0];
+  let larkMode;
+  if (platform === 'lark') {
+    if (options['--new-app']) larkMode = 'new';
+    else if (options['--app-id']) larkMode = 'existing';
+    else {
+      try {
+        if (status('lark').configured) larkMode = 'configured';
+      } catch {
+        // platformCliSteps returns an actionable first-run choice error below.
+      }
+    }
+  }
+  runPlatformCommand({
+    platform,
+    action: 'login',
+    larkMode,
+    appId: options['--app-id'],
+    device: options['--device'] !== false,
+    resolveInvocation,
+  });
+  return { loginCompleted: true, ...status(platform) };
+}
+
+async function deploy() {
+  const endpoint = normalizedPublicEndpoint(options);
+  const domain = endpoint.publicHost;
+  const installDependencies = Boolean(options['--install-dependencies']);
+  const detectedHost = detectDeploymentHost();
+  const plan = createDeploymentPlan(
+    domain,
+    installDependencies,
+    process.platform,
+    process.arch,
+    detectedHost,
+    endpoint.publicScheme,
+    endpoint.certificateMode,
+  );
+  if (!options['--apply']) return plan;
+
+  const deploymentHost = assertSupportedDeploymentHost();
+  assertPackagedRuntime();
+  if (
+    resolve(packageRoot).startsWith('/root/') ||
+    realpathSync(process.execPath).startsWith('/root/')
+  ) {
+    throw new Error(
+      'npm 包或 Node.js 安装在 /root 下，专用服务用户无法安全读取；请安装到 /usr/local',
+    );
+  }
+  if (installDependencies && !findExecutable('caddy')) {
+    await installOfficialCaddyPackage(deploymentHost);
+  }
+  for (const executable of [
+    'systemctl',
+    'systemd-analyze',
+    'caddy',
+    'useradd',
+    'chown',
+    'chmod',
+    'install',
+  ]) {
+    if (!findExecutable(executable)) throw new Error(`部署依赖不可用：${executable}`);
+  }
+  const caddyPath = findExecutable('caddy');
+  if (!caddyPath) throw new Error('部署依赖不可用：caddy');
+  const installPath = findExecutable('install');
+  if (!installPath) throw new Error('部署依赖不可用：install');
+  const larkCliPath = compatibleCli('lark-cli', verifiedPlatformCliVersionPatterns['lark-cli']);
+  const dingtalkCliPath = compatibleCli('dws', verifiedPlatformCliVersionPatterns.dws);
+  ensureSystemUser();
+
+  let certificateChallenge;
+  let certbotPath;
+  if (endpoint.certificateMode === 'ip-shortlived') {
+    if (typeof options['--email'] !== 'string') {
+      throw new Error('deploy --ip --apply 必须提供 --email 作为证书到期联系人');
+    }
+    certbotPath = compatibleCertbot();
+    certificateChallenge = stageIpCertificateChallenge({ publicIp: endpoint.publicHost });
+    try {
+      runSystem('caddy', [
+        'validate',
+        '--config',
+        deploymentPaths.caddyfile,
+        '--adapter',
+        'caddyfile',
+      ]);
+      runSystem('systemctl', ['enable', 'caddy.service']);
+      if (systemServiceActive('caddy.service')) runSystem('systemctl', ['reload', 'caddy.service']);
+      else runSystem('systemctl', ['start', 'caddy.service']);
+      runSystem(
+        certbotPath,
+        certbotIssueArguments({
+          publicIp: endpoint.publicHost,
+          email: options['--email'],
+        }),
+      );
+    } catch (error) {
+      certificateChallenge.rollback();
+      runSystem('systemctl', ['reload', 'caddy.service'], true);
+      throw error;
+    }
+  }
+
+  const staged = stageDeployment({
+    publicHost: endpoint.publicHost,
+    publicScheme: endpoint.publicScheme,
+    certificateMode: endpoint.certificateMode,
+    packageRoot,
+    nodePath: realpathSync(process.execPath),
+    larkCliPath,
+    dingtalkCliPath,
+  });
+  const certificateAutomation = certbotPath
+    ? stageIpCertificateAutomation({
+        publicIp: endpoint.publicHost,
+        certbotPath,
+        caddyPath,
+        installPath,
+        nodePath: realpathSync(process.execPath),
+      })
+    : undefined;
+  try {
+    runSystem('chown', ['-R', 'chat-hub:chat-hub', deploymentPaths.data, deploymentPaths.backups]);
+    runSystem('chown', ['root:chat-hub', deploymentPaths.configuration]);
+    runSystem('chmod', ['0750', deploymentPaths.configuration]);
+    runSystem('chown', ['root:chat-hub', deploymentPaths.runtimeConfig]);
+    runSystem('chmod', ['0640', deploymentPaths.runtimeConfig]);
+    runSystem('systemd-analyze', ['verify', deploymentPaths.service]);
+    if (certificateAutomation) {
+      runSystem('systemd-analyze', ['verify', ipCertificateAutomationPaths.service]);
+      runSystem(ipCertificateAutomationPaths.deployHook, []);
+    }
+    runSystem('caddy', [
+      'validate',
+      '--config',
+      deploymentPaths.caddyfile,
+      '--adapter',
+      'caddyfile',
+    ]);
+    runSystem('systemctl', ['daemon-reload']);
+    runSystem('systemctl', ['enable', 'chat-hub.service']);
+    runSystem('systemctl', ['restart', 'chat-hub.service']);
+    await waitForPublicGateway(endpoint);
+    runSystem('systemctl', ['enable', 'caddy.service']);
+    if (systemServiceActive('caddy.service')) runSystem('systemctl', ['reload', 'caddy.service']);
+    else runSystem('systemctl', ['start', 'caddy.service']);
+    if (certbotPath) {
+      runSystem(certbotPath, [
+        'renew',
+        '--cert-name',
+        endpoint.publicHost,
+        '--dry-run',
+        '--run-deploy-hooks',
+      ]);
+      runSystem(ipCertificateAutomationPaths.renewRunner, []);
+      runSystem('systemctl', ['enable', '--now', 'chat-hub-cert-renew.timer']);
+    }
+  } catch (error) {
+    certificateAutomation?.rollback();
+    staged.rollback();
+    certificateChallenge?.rollback();
+    try {
+      runSystem('systemctl', ['daemon-reload']);
+      runSystem('systemctl', ['restart', 'chat-hub.service'], true);
+      runSystem('systemctl', ['reload', 'caddy.service'], true);
+    } catch {
+      // The original error is more actionable; retained data and credentials are never removed.
+    }
+    throw error;
+  }
+
+  const sessionConfig = await fetchPublicGateway(endpoint, '/api/session/config');
+  const initialized = sessionConfig?.data?.initialized === true;
+  return {
+    ...plan,
+    mode: 'applied',
+    applied: true,
+    initializationUrl: initialized ? undefined : staged.initializationUrl,
+    initializationExpiresAt: initialized ? undefined : new Date(staged.expiresAt).toISOString(),
+    administratorInitialized: initialized,
+    service: 'active',
+    publicUrl: `${endpoint.publicScheme}://${endpoint.publicHost}`,
+  };
+}
+
+async function verifyServer() {
+  assertSupportedDeploymentHost({ commandName: 'verify-server' });
+  const manifest = readDeploymentManifest();
+  const larkCliPath = packagedPlatformCliEntry('lark-cli');
+  const dingtalkCliPath = packagedPlatformCliEntry('dws');
+  if (!larkCliPath || !dingtalkCliPath) {
+    throw new Error('安装包缺少固定版本平台 CLI，不能完成服务器验收');
+  }
+  return verifyServerDeployment({
+    domain: manifest.publicHost,
+    publicHost: manifest.publicHost,
+    publicScheme: manifest.publicScheme,
+    certificateMode: manifest.certificateMode,
+    larkCliPath,
+    dingtalkCliPath,
+    nodePath: process.execPath,
+  });
+}
+
+async function verifyExternal() {
+  const endpoint = normalizedPublicEndpoint(options);
+  return verifyExternalDeployment({
+    domain: endpoint.publicHost,
+    publicHost: endpoint.publicHost,
+    publicScheme: endpoint.publicScheme,
+    origin: options['--origin'],
+  });
+}
+
+async function resetAdministrator() {
+  assertSupportedDeploymentHost({ commandName: 'admin-reset' });
+  const manifest = readDeploymentManifest();
+  if (!systemServiceActive('chat-hub.service')) {
+    throw new Error('Chat Hub systemd 服务当前未运行；先修复服务再重置管理员');
+  }
+  const reset = stageAdministratorReset({
+    publicHost: manifest.publicHost,
+    publicScheme: manifest.publicScheme,
+  });
+  runSystem('systemctl', ['restart', 'chat-hub.service']);
+  await waitForPublicGateway(manifest);
+  const sessionConfig = await fetchPublicGateway(manifest, '/api/session/config');
+  if (sessionConfig?.data?.initialized !== false) {
+    throw new Error('管理员重置未进入初始化状态，请查看 Chat Hub 服务日志');
+  }
+  return {
+    command: 'admin-reset',
+    reset: true,
+    previousSessionsRevoked: true,
+    initializationUrl: reset.initializationUrl,
+    initializationExpiresAt: new Date(reset.expiresAt).toISOString(),
+  };
+}
+
+async function backupServerData() {
+  assertSupportedDeploymentHost({ commandName: 'backup' });
+  const manifest = readDeploymentManifest();
+  const wasActive = systemServiceActive('chat-hub.service');
+  if (wasActive) runSystem('systemctl', ['stop', 'chat-hub.service']);
+  try {
+    const backup = createStoppedBackup({ kind: 'manual' });
+    await validateSqliteBackup(backup.backupDirectory);
+    return {
+      command: 'backup',
+      created: true,
+      backupDirectory: backup.backupDirectory,
+      includesMasterKey: false,
+      serviceRestarted: wasActive,
+    };
+  } finally {
+    if (wasActive) {
+      runSystem('systemctl', ['start', 'chat-hub.service']);
+      await waitForPublicGateway(manifest);
+    }
+  }
+}
+
+async function restoreServerData(backup) {
+  assertSupportedDeploymentHost({ commandName: 'restore' });
+  const manifest = readDeploymentManifest();
+  const validated = validateBackup(backup);
+  await validateSqliteBackup(validated.backupDirectory);
+  const wasActive = systemServiceActive('chat-hub.service');
+  if (wasActive) runSystem('systemctl', ['stop', 'chat-hub.service']);
+  let safety;
+  let restored;
+  let previousBootstrap;
+  try {
+    safety = createStoppedBackup({ kind: 'restore-safety' });
+    previousBootstrap = existsSync(deploymentPaths.adminBootstrap)
+      ? readFileSync(deploymentPaths.adminBootstrap)
+      : undefined;
+    restored = stageRestore({ backup: validated.backupDirectory });
+    runSystem('chown', ['-R', 'chat-hub:chat-hub', deploymentPaths.data]);
+    const reset = stageAdministratorReset({
+      publicHost: manifest.publicHost,
+      publicScheme: manifest.publicScheme,
+    });
+    runSystem('systemctl', ['start', 'chat-hub.service']);
+    await waitForPublicGateway(manifest);
+    const sessionConfig = await fetchPublicGateway(manifest, '/api/session/config');
+    if (sessionConfig?.data?.initialized !== false) {
+      throw new Error('恢复后管理员会话没有进入强制重置状态');
+    }
+    restored.commit();
+    return {
+      command: 'restore',
+      restored: true,
+      backupDirectory: validated.backupDirectory,
+      safetyBackupDirectory: safety.backupDirectory,
+      previousSessionsRevoked: true,
+      initializationUrl: reset.initializationUrl,
+      initializationExpiresAt: new Date(reset.expiresAt).toISOString(),
+      service: 'active',
+    };
+  } catch (error) {
+    runSystem('systemctl', ['stop', 'chat-hub.service'], true);
+    if (restored) {
+      restored.rollback();
+      runSystem('chown', ['-R', 'chat-hub:chat-hub', deploymentPaths.data], true);
+      if (previousBootstrap) {
+        writeFileSync(deploymentPaths.adminBootstrap, previousBootstrap, { mode: 0o600 });
+        chmodSync(deploymentPaths.adminBootstrap, 0o600);
+      } else if (existsSync(deploymentPaths.adminBootstrap)) {
+        unlinkSync(deploymentPaths.adminBootstrap);
+      }
+    }
+    if (wasActive) runSystem('systemctl', ['start', 'chat-hub.service'], true);
+    throw error;
+  }
+}
+
+async function upgradeServer() {
+  assertSupportedDeploymentHost({ commandName: 'upgrade' });
+  assertPackagedRuntime();
+  const manifest = readDeploymentManifest();
+  const currentVersion = readCurrentPackageVersion();
+  const requestedVersion = options['--to'];
+  if (requestedVersion) {
+    if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(requestedVersion)) {
+      throw new Error('--to 必须是精确的语义版本，不能使用 latest、next 或版本范围');
+    }
+    if (requestedVersion !== currentVersion) {
+      throw new Error(
+        `当前执行包版本是 ${currentVersion}，不是请求的 ${requestedVersion}；请先通过 npm 安装目标版本，再运行 upgrade`,
+      );
+    }
+  }
+  for (const executable of ['systemctl', 'systemd-analyze', 'caddy', 'chown', 'chmod']) {
+    if (!findExecutable(executable)) throw new Error(`升级依赖不可用：${executable}`);
+  }
+  if (
+    resolve(packageRoot).startsWith('/root/') ||
+    realpathSync(process.execPath).startsWith('/root/')
+  ) {
+    throw new Error('npm 包或 Node.js 安装在 /root 下，专用服务用户无法安全读取');
+  }
+  const larkCliPath = compatibleCli('lark-cli', verifiedPlatformCliVersionPatterns['lark-cli']);
+  const dingtalkCliPath = compatibleCli('dws', verifiedPlatformCliVersionPatterns.dws);
+  const wasActive = systemServiceActive('chat-hub.service');
+  if (!wasActive) throw new Error('Chat Hub 服务未运行；先恢复现有服务再执行升级');
+  runSystem('systemctl', ['stop', 'chat-hub.service']);
+  let backup;
+  let staged;
+  try {
+    backup = createStoppedBackup({ kind: 'upgrade' });
+    await validateSqliteBackup(backup.backupDirectory);
+    staged = stageDeployment({
+      publicHost: manifest.publicHost,
+      publicScheme: manifest.publicScheme,
+      packageRoot,
+      nodePath: realpathSync(process.execPath),
+      larkCliPath,
+      dingtalkCliPath,
+      preserveAdministratorCredential: true,
+    });
+    runSystem('chown', ['-R', 'chat-hub:chat-hub', deploymentPaths.data, deploymentPaths.backups]);
+    runSystem('chown', ['root:chat-hub', deploymentPaths.configuration]);
+    runSystem('chmod', ['0750', deploymentPaths.configuration]);
+    runSystem('chown', ['root:chat-hub', deploymentPaths.runtimeConfig]);
+    runSystem('chmod', ['0640', deploymentPaths.runtimeConfig]);
+    runSystem('systemd-analyze', ['verify', deploymentPaths.service]);
+    runSystem('caddy', [
+      'validate',
+      '--config',
+      deploymentPaths.caddyfile,
+      '--adapter',
+      'caddyfile',
+    ]);
+    runSystem('systemctl', ['daemon-reload']);
+    runSystem('systemctl', ['start', 'chat-hub.service']);
+    await waitForPublicGateway(manifest);
+    if (systemServiceActive('caddy.service')) runSystem('systemctl', ['reload', 'caddy.service']);
+    const removedBackups = pruneUpgradeBackups('/', 3);
+    return {
+      command: 'upgrade',
+      upgraded: true,
+      version: currentVersion,
+      previousPackageRoot: manifest.packageRoot,
+      packageRoot,
+      backupDirectory: backup.backupDirectory,
+      prunedUpgradeBackups: removedBackups,
+      service: 'active',
+    };
+  } catch (error) {
+    runSystem('systemctl', ['stop', 'chat-hub.service'], true);
+    try {
+      if (backup && staged) {
+        try {
+          const restored = stageRestore({ backup: backup.backupDirectory });
+          restored.commit();
+          runSystem('chown', ['-R', 'chat-hub:chat-hub', deploymentPaths.data], true);
+        } finally {
+          staged.rollback();
+        }
+      }
+    } finally {
+      runSystem('systemctl', ['daemon-reload'], true);
+      runSystem('systemctl', ['start', 'chat-hub.service'], true);
+    }
+    throw error;
+  }
+}
+
+async function uninstallServer() {
+  assertSupportedDeploymentHost({ commandName: 'uninstall' });
+  const manifest = existsSync(deploymentPaths.manifest) ? readDeploymentManifest() : undefined;
+  const wasActive = systemServiceActive('chat-hub.service');
+  const hadCertificateTimer = manifest?.certificateMode === 'ip-shortlived';
+  runSystem('systemctl', ['stop', 'chat-hub-cert-renew.timer'], true);
+  runSystem('systemctl', ['disable', 'chat-hub-cert-renew.timer'], true);
+  runSystem('systemctl', ['stop', 'chat-hub-cert-renew.service'], true);
+  runSystem('systemctl', ['stop', 'chat-hub.service'], true);
+  runSystem('systemctl', ['disable', 'chat-hub.service'], true);
+  let staged;
+  try {
+    staged = stageUninstall();
+    runSystem('systemctl', ['daemon-reload']);
+    if (findExecutable('caddy')) {
+      runSystem('caddy', [
+        'validate',
+        '--config',
+        deploymentPaths.caddyfile,
+        '--adapter',
+        'caddyfile',
+      ]);
+      if (systemServiceActive('caddy.service')) runSystem('systemctl', ['reload', 'caddy.service']);
+    }
+    staged.commit();
+    return {
+      command: 'uninstall',
+      uninstalled: true,
+      previousDomain: manifest?.domain,
+      serviceWasActive: wasActive,
+      preservedPaths: staged.preservedPaths,
+      packageRemoval: '请使用安装该版本时采用的 npm 方式移除全局包；数据不会随之删除',
+    };
+  } catch (error) {
+    staged?.rollback();
+    runSystem('systemctl', ['daemon-reload'], true);
+    if (wasActive) {
+      runSystem('systemctl', ['enable', 'chat-hub.service'], true);
+      runSystem('systemctl', ['start', 'chat-hub.service'], true);
+    }
+    if (hadCertificateTimer) {
+      runSystem('systemctl', ['enable', '--now', 'chat-hub-cert-renew.timer'], true);
+    }
+    throw error;
+  }
+}
+
+async function purgeServer() {
+  assertSupportedDeploymentHost({ commandName: 'purge' });
+  const confirmationToken = options['--confirm'];
+  if (!confirmationToken) {
+    const confirmation = createPurgeConfirmation();
+    return {
+      command: 'purge',
+      purged: false,
+      confirmationRequired: true,
+      warning: '以下数据、凭证和备份将永久删除，且不会自动创建备份',
+      paths: confirmation.paths,
+      confirmBefore: new Date(confirmation.expiresAt).toISOString(),
+      confirmCommand: `sudo chat-hub purge --confirm ${confirmation.token}`,
+    };
+  }
+
+  validatePurgeConfirmation({ token: confirmationToken });
+  const wasActive = systemServiceActive('chat-hub.service');
+  const manifest = existsSync(deploymentPaths.manifest) ? readDeploymentManifest() : undefined;
+  const hadCertificateTimer = manifest?.certificateMode === 'ip-shortlived';
+  runSystem('systemctl', ['stop', 'chat-hub-cert-renew.timer'], true);
+  runSystem('systemctl', ['disable', 'chat-hub-cert-renew.timer'], true);
+  runSystem('systemctl', ['stop', 'chat-hub-cert-renew.service'], true);
+  runSystem('systemctl', ['stop', 'chat-hub.service'], true);
+  runSystem('systemctl', ['disable', 'chat-hub.service'], true);
+  let staged;
+  try {
+    staged = stageUninstall();
+    runSystem('systemctl', ['daemon-reload']);
+    if (findExecutable('caddy')) {
+      runSystem('caddy', [
+        'validate',
+        '--config',
+        deploymentPaths.caddyfile,
+        '--adapter',
+        'caddyfile',
+      ]);
+      if (systemServiceActive('caddy.service')) runSystem('systemctl', ['reload', 'caddy.service']);
+    }
+    const result = consumePurgeConfirmation({ token: confirmationToken });
+    staged.commit();
+    if (findExecutable('userdel')) runSystem('userdel', ['chat-hub'], true);
+    return {
+      command: 'purge',
+      purged: true,
+      removedPaths: result.removedPaths,
+      serviceWasActive: wasActive,
+    };
+  } catch (error) {
+    staged?.rollback();
+    runSystem('systemctl', ['daemon-reload'], true);
+    if (wasActive) {
+      runSystem('systemctl', ['enable', 'chat-hub.service'], true);
+      runSystem('systemctl', ['start', 'chat-hub.service'], true);
+    }
+    if (hadCertificateTimer) {
+      runSystem('systemctl', ['enable', '--now', 'chat-hub-cert-renew.timer'], true);
+    }
+    throw error;
+  }
+}
+
+function readCurrentPackageVersion() {
+  const value = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'));
+  if (!value || typeof value.version !== 'string') throw new Error('安装包版本信息无效');
+  return value.version;
+}
+
+function readDeploymentManifest() {
+  if (!existsSync(deploymentPaths.manifest)) {
+    throw new Error('Chat Hub 尚未通过 deploy --apply 安装');
+  }
+  const manifest = JSON.parse(readFileSync(deploymentPaths.manifest, 'utf8'));
+  if (!manifest || typeof manifest.packageRoot !== 'string' || !isAbsolute(manifest.packageRoot)) {
+    throw new Error('Chat Hub 安装清单无效');
+  }
+  if (manifest.version === 1) {
+    const publicHost = normalizedDomain(manifest.domain);
+    return { ...manifest, domain: publicHost, publicHost, publicScheme: 'https' };
+  }
+  if (manifest.version !== 2 || !['http', 'https'].includes(manifest.publicScheme)) {
+    throw new Error('Chat Hub 安装清单无效');
+  }
+  const publicHost =
+    manifest.publicScheme === 'https'
+      ? normalizedDomain(manifest.publicHost)
+      : normalizedPublicIpv4(manifest.publicHost);
+  return { ...manifest, domain: publicHost, publicHost };
+}
+
+async function validateSqliteBackup(backupDirectory) {
+  const validated = validateBackup(backupDirectory);
+  if (!validated.manifest.database) return;
+  const databasePath = join(backupDirectory, validated.manifest.database.relativePath);
+  const { default: Database } = await import('better-sqlite3');
+  const database = new Database(databasePath, { readonly: true, fileMustExist: true });
+  try {
+    const result = database.pragma('quick_check', { simple: true });
+    if (result !== 'ok') throw new Error(`SQLite 快速完整性检查失败：${String(result)}`);
+  } finally {
+    database.close();
+  }
+}
+
+function ensureSystemUser() {
+  try {
+    execFileSync('id', ['-u', 'chat-hub'], { stdio: 'ignore' });
+  } catch {
+    runSystem('useradd', [
+      '--system',
+      '--user-group',
+      '--home-dir',
+      deploymentPaths.data,
+      '--shell',
+      '/usr/sbin/nologin',
+      'chat-hub',
+    ]);
+  }
+}
+
+function compatibleCli(executable, pattern) {
+  const path = selectedPlatformCli(executable);
+  if (!path) throw new Error(`缺少固定版本平台 CLI：${executable}`);
+  const invocation = executableInvocation(path);
+  let version;
+  try {
+    version = execFileSync(invocation.executable, [...invocation.prefixArgs, '--version'], {
+      encoding: 'utf8',
+      timeout: 10_000,
+      stdio: 'pipe',
+    }).trim();
+  } catch {
+    throw new Error(`固定版本平台 CLI 不可执行：${executable}`);
+  }
+  if (!pattern.test(version)) throw new Error(`${executable} 版本未经验证：${version}`);
+  return path;
+}
+
+function compatibleCertbot() {
+  const selected = process.env.CHAT_HUB_CERTBOT_PATH
+    ? realpathSync(process.env.CHAT_HUB_CERTBOT_PATH)
+    : findExecutable('certbot');
+  if (!selected) {
+    throw new Error(
+      'IP HTTPS 需要 Certbot 5.4+；当前未找到。请通过受控安装器安装后重试，不会降级为 HTTP',
+    );
+  }
+  let version;
+  try {
+    version = execFileSync(selected, ['--version'], {
+      encoding: 'utf8',
+      timeout: 10_000,
+      stdio: 'pipe',
+    }).trim();
+  } catch {
+    throw new Error('Certbot 不可执行；请修复受控安装后重试');
+  }
+  if (!certbotVersionSupported(version)) {
+    throw new Error(`IP HTTPS 需要 Certbot 5.4+；当前为 ${version || '未知版本'}`);
+  }
+  return selected;
+}
+
+function selectedPlatformCli(executable) {
+  const override =
+    executable === 'lark-cli' ? process.env.LARK_CLI_PATH : process.env.DINGTALK_CLI_PATH;
+  if (override)
+    return isAbsolute(override) && existsSync(override) ? override : findExecutable(override);
+  return packagedPlatformCliEntry(executable) ?? findExecutable(executable);
+}
+
+function packagedPlatformCliEntry(executable) {
+  const specification =
+    executable === 'lark-cli'
+      ? { packageJson: '@larksuite/cli/package.json', entry: ['scripts', 'run.js'] }
+      : executable === 'dws'
+        ? { packageJson: 'dingtalk-workspace-cli/package.json', entry: ['bin', 'dws.js'] }
+        : undefined;
+  if (!specification) return undefined;
+  try {
+    const packageJson = packageRequire.resolve(specification.packageJson);
+    const entry = join(dirname(packageJson), ...specification.entry);
+    return existsSync(entry) ? entry : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function executableInvocation(executable) {
+  if (!executable) throw new Error('平台 CLI 不可执行');
+  return extname(executable).toLowerCase() === '.js'
+    ? { executable: process.execPath, prefixArgs: [executable] }
+    : { executable, prefixArgs: [] };
+}
+
+function findExecutable(executable) {
+  try {
+    const result = execFileSync('which', [executable], {
+      encoding: 'utf8',
+      timeout: 10_000,
+      stdio: 'pipe',
+    }).trim();
+    return result && isAbsolute(result) ? realpathSync(result) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function runSystem(executable, args, ignoreFailure = false) {
+  try {
+    execFileSync(executable, args, {
+      timeout: 5 * 60_000,
+      windowsHide: true,
+      stdio: ['ignore', 'inherit', 'inherit'],
+    });
+  } catch (error) {
+    if (!ignoreFailure) throw error;
+  }
+}
+
+function systemServiceActive(service) {
+  try {
+    execFileSync('systemctl', ['is-active', '--quiet', service], {
+      timeout: 10_000,
+      stdio: 'ignore',
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function installOfficialCaddyPackage(host) {
+  if (host.caddyInstaller === 'apt') return installOfficialCaddyAptPackage();
+  if (host.caddyInstaller === 'verified-static') return installVerifiedStaticCaddy();
+  throw new Error(`当前系统没有受支持的 Caddy 安装方式：${host.label}`);
+}
+
+async function installOfficialCaddyAptPackage() {
+  runSystem('apt-get', ['update']);
+  runSystem('apt-get', [
+    'install',
+    '-y',
+    'debian-keyring',
+    'debian-archive-keyring',
+    'apt-transport-https',
+    'curl',
+    'gpg',
+  ]);
+  const keyUrl = 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key';
+  const listUrl = 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt';
+  const keyTemporary = '/usr/share/keyrings/caddy-stable-archive-keyring.gpg.chat-hub.asc';
+  const keyTarget = '/usr/share/keyrings/caddy-stable-archive-keyring.gpg';
+  const keyNew = `${keyTarget}.chat-hub.new`;
+  const listTarget = '/etc/apt/sources.list.d/caddy-stable.list';
+  const listNew = `${listTarget}.chat-hub.new`;
+  try {
+    writeFileSync(keyTemporary, await downloadFixedDependency(keyUrl), { mode: 0o600 });
+    runSystem('gpg', ['--batch', '--yes', '--dearmor', '--output', keyNew, keyTemporary]);
+    writeFileSync(listNew, await downloadFixedDependency(listUrl), { mode: 0o644 });
+    renameSync(keyNew, keyTarget);
+    renameSync(listNew, listTarget);
+    runSystem('chmod', ['o+r', keyTarget, listTarget]);
+  } finally {
+    for (const path of [keyTemporary, keyNew, listNew]) {
+      if (existsSync(path)) unlinkSync(path);
+    }
+  }
+  runSystem('apt-get', ['update']);
+  runSystem('apt-get', ['install', '-y', 'caddy']);
+}
+
+async function installVerifiedStaticCaddy() {
+  if (!findExecutable('tar')) throw new Error('安装 Caddy 需要系统提供 tar');
+  if (existsSync(alinuxCaddyRelease.binaryPath)) {
+    throw new Error(`${alinuxCaddyRelease.binaryPath} 已存在但不在 PATH；不会覆盖未知文件`);
+  }
+  const temporaryDirectory = mkdtempSync(join(tmpdir(), 'chat-hub-caddy-'));
+  const archivePath = join(temporaryDirectory, 'caddy.tar.gz');
+  const extractedBinary = join(temporaryDirectory, 'caddy');
+  const stagedBinary = `${alinuxCaddyRelease.binaryPath}.chat-hub.new`;
+  let installedBinary = false;
+  try {
+    const archive = await downloadFixedDependency(
+      alinuxCaddyRelease.archiveUrl,
+      64 * 1024 * 1024,
+      120_000,
+    );
+    const digest = createHash('sha256').update(archive).digest('hex');
+    if (digest !== alinuxCaddyRelease.archiveSha256) {
+      throw new Error(`Caddy ${alinuxCaddyRelease.version} 安装包 SHA-256 校验失败；不会安装`);
+    }
+    writeFileSync(archivePath, archive, { flag: 'wx', mode: 0o600 });
+    runSystem('tar', ['-xzf', archivePath, '-C', temporaryDirectory, 'caddy']);
+    if (!existsSync(extractedBinary) || !statSync(extractedBinary).isFile()) {
+      throw new Error('Caddy 官方安装包没有包含普通文件 caddy');
+    }
+    if (existsSync(stagedBinary)) unlinkSync(stagedBinary);
+    writeFileSync(stagedBinary, readFileSync(extractedBinary), { flag: 'wx', mode: 0o755 });
+    chmodSync(stagedBinary, 0o755);
+    const version = execFileSync(stagedBinary, ['version'], {
+      encoding: 'utf8',
+      timeout: 10_000,
+      stdio: 'pipe',
+    }).trim();
+    if (!version.startsWith(`v${alinuxCaddyRelease.version} `)) {
+      throw new Error(`Caddy 可执行文件版本异常：${version}`);
+    }
+    renameSync(stagedBinary, alinuxCaddyRelease.binaryPath);
+    installedBinary = true;
+    ensureCaddySystemUser();
+    installCaddySystemdUnit();
+  } catch (error) {
+    if (existsSync(stagedBinary)) unlinkSync(stagedBinary);
+    if (installedBinary && existsSync(alinuxCaddyRelease.binaryPath)) {
+      unlinkSync(alinuxCaddyRelease.binaryPath);
+    }
+    throw error;
+  } finally {
+    rmSync(temporaryDirectory, { recursive: true, force: true });
+  }
+}
+
+function ensureCaddySystemUser() {
+  try {
+    execFileSync('id', ['-u', 'caddy'], { stdio: 'ignore' });
+  } catch {
+    runSystem('useradd', [
+      '--system',
+      '--user-group',
+      '--home-dir',
+      '/var/lib/caddy',
+      '--create-home',
+      '--shell',
+      '/usr/sbin/nologin',
+      'caddy',
+    ]);
+  }
+  mkdirSync('/var/lib/caddy', { recursive: true, mode: 0o750 });
+  mkdirSync('/etc/caddy', { recursive: true, mode: 0o755 });
+  runSystem('chown', ['-R', 'caddy:caddy', '/var/lib/caddy']);
+  runSystem('chmod', ['0750', '/var/lib/caddy']);
+  runSystem('chmod', ['0755', '/etc/caddy']);
+}
+
+function installCaddySystemdUnit() {
+  const content = alinuxCaddySystemdUnit();
+  if (existsSync(alinuxCaddyRelease.servicePath)) {
+    if (readFileSync(alinuxCaddyRelease.servicePath, 'utf8') !== content) {
+      throw new Error(
+        `${alinuxCaddyRelease.servicePath} 已存在且不是 Chat Hub 管理的版本；不会覆盖`,
+      );
+    }
+    return;
+  }
+  const staged = `${alinuxCaddyRelease.servicePath}.chat-hub.new`;
+  try {
+    writeFileSync(staged, content, { flag: 'wx', mode: 0o644 });
+    chmodSync(staged, 0o644);
+    renameSync(staged, alinuxCaddyRelease.servicePath);
+  } finally {
+    if (existsSync(staged)) unlinkSync(staged);
+  }
+}
+
+async function downloadFixedDependency(url, maximumBytes = 1024 * 1024, timeout = 30_000) {
+  const response = await fetch(url, { signal: AbortSignal.timeout(timeout) });
+  if (!response.ok) throw new Error(`下载官方 Caddy 依赖失败：HTTP ${response.status}`);
+  const declaredLength = Number(response.headers.get('content-length'));
+  if (Number.isFinite(declaredLength) && declaredLength > maximumBytes) {
+    throw new Error(`下载官方 Caddy 依赖超过 ${maximumBytes} 字节限制`);
+  }
+  if (!response.body) throw new Error('下载官方 Caddy 依赖没有响应正文');
+  const reader = response.body.getReader();
+  const chunks = [];
+  let total = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > maximumBytes) {
+      await reader.cancel();
+      throw new Error(`下载官方 Caddy 依赖超过 ${maximumBytes} 字节限制`);
+    }
+    chunks.push(Buffer.from(value));
+  }
+  return Buffer.concat(chunks, total);
+}
+
+async function waitForPublicGateway(endpoint) {
+  const deadline = Date.now() + 45_000;
+  let lastError = '健康接口尚未就绪';
+  while (Date.now() < deadline) {
+    try {
+      const result = await fetchPublicGateway(endpoint, '/api/health');
+      if (result?.ok === true && result.data?.status === 'ready') return;
+      lastError = `健康状态为 ${String(result?.data?.status ?? 'unknown')}`;
+    } catch (error) {
+      // systemd may still be starting SQLite, the app process, and the gateway.
+      lastError = safeDiagnosticText(error instanceof Error ? error.message : String(error));
+    }
+    await delay(250);
+  }
+  const service = safeServiceFailureSummary();
+  throw new Error(
+    `systemd 服务未在 45 秒内通过内部健康检查；最后错误：${lastError}${service ? `；脱敏摘要：${service}` : ''}`,
+  );
+}
+
+function safeServiceFailureSummary() {
+  const parts = [];
+  try {
+    const properties = execFileSync(
+      'systemctl',
+      [
+        'show',
+        'chat-hub.service',
+        '--property=ActiveState,SubState,Result,ExecMainCode,ExecMainStatus',
+      ],
+      { encoding: 'utf8', timeout: 10_000, stdio: 'pipe' },
+    )
+      .trim()
+      .replace(/\r?\n/g, ',');
+    if (properties) parts.push(properties);
+  } catch {
+    // Keep the primary health failure when systemd metadata is unavailable.
+  }
+  try {
+    const journal = execFileSync(
+      'journalctl',
+      ['-u', 'chat-hub.service', '-n', '5', '--no-pager', '--output=cat'],
+      { encoding: 'utf8', timeout: 10_000, stdio: 'pipe', maxBuffer: 64 * 1024 },
+    )
+      .split(/\r?\n/)
+      .map(safeDiagnosticText)
+      .filter(Boolean)
+      .slice(-5)
+      .join(' | ');
+    if (journal) parts.push(journal);
+  } catch {
+    // Journal access is optional; do not hide the original failure.
+  }
+  return parts.join('；').slice(0, 1_200);
+}
+
+function safeDiagnosticText(value) {
+  return String(value)
+    .replace(/([?&](?:token|key|secret|code)=)[^\s&]+/giu, '$1[REDACTED]')
+    .replace(/(authorization|api[_-]?key|secret|token)\s*[:=]\s*\S+/giu, '$1=[REDACTED]')
+    .replace(/[A-Za-z0-9_-]{40,}/g, '[REDACTED]')
+    .replace(/[\r\n]+/g, ' ')
+    .trim()
+    .slice(0, 240);
+}
+
+async function fetchPublicGateway(endpoint, path) {
+  const publicHost = typeof endpoint === 'string' ? endpoint : endpoint.publicHost;
+  const publicScheme = typeof endpoint === 'string' ? 'https' : endpoint.publicScheme;
+  const response = await fetchInternalGateway(`http://127.0.0.1:8080${path}`, {
+    headers: {
+      host: publicHost,
+      'x-forwarded-proto': publicScheme,
+      'x-forwarded-for': '127.0.0.1',
+    },
+    signal: AbortSignal.timeout(2_000),
+  });
+  if (!response.ok) throw new Error(`内部安全网关返回 HTTP ${response.status}`);
+  return response.json();
+}
+
+function normalizedDomain(value) {
+  if (!value || typeof value !== 'string') throw new Error('deploy 必须提供 --domain');
+  const domain = value.trim().toLowerCase();
+  if (
+    domain.length > 253 ||
+    !domain.includes('.') ||
+    !/^[a-z0-9.-]+$/.test(domain) ||
+    domain
+      .split('.')
+      .some(
+        (label) => !label || label.length > 63 || label.startsWith('-') || label.endsWith('-'),
+      ) ||
+    domain === 'localhost' ||
+    /^\d+(?:\.\d+){3}$/.test(domain)
+  ) {
+    throw new Error('domain 必须是有效的公网 DNS 域名，不能使用 IP 或 localhost');
+  }
+  return domain;
+}
+
+function normalizedPublicIpv4(value) {
+  if (!value || typeof value !== 'string') throw new Error('必须提供有效的公网 IPv4');
+  const address = value.trim();
+  if (isIP(address) !== 4) throw new Error('--http-ip 必须是有效的公网 IPv4');
+  const [first, second, third] = address.split('.').map(Number);
+  const nonPublic =
+    first === 0 ||
+    first === 10 ||
+    first === 127 ||
+    (first === 100 && second >= 64 && second <= 127) ||
+    (first === 169 && second === 254) ||
+    (first === 172 && second >= 16 && second <= 31) ||
+    (first === 192 && second === 168) ||
+    (first === 192 && second === 0 && third === 2) ||
+    (first === 198 && (second === 18 || second === 19 || (second === 51 && third === 100))) ||
+    (first === 203 && second === 0 && third === 113) ||
+    first >= 224;
+  if (nonPublic) throw new Error('--http-ip 必须是可路由的公网 IPv4，不能使用内网或保留地址');
+  return address;
+}
+
+function normalizedPublicEndpoint(optionValues) {
+  const hasDomain = typeof optionValues['--domain'] === 'string';
+  const hasHttpsIp = typeof optionValues['--ip'] === 'string';
+  const hasHttpIp = typeof optionValues['--http-ip'] === 'string';
+  if ([hasDomain, hasHttpsIp, hasHttpIp].filter(Boolean).length !== 1) {
+    throw new Error('必须且只能提供 --domain、--ip 或 --http-ip 其中一个');
+  }
+  if (hasDomain) {
+    return {
+      publicHost: normalizedDomain(optionValues['--domain']),
+      publicScheme: 'https',
+      certificateMode: 'managed-domain',
+    };
+  }
+  if (hasHttpsIp) {
+    return {
+      publicHost: normalizedPublicIpv4(optionValues['--ip']),
+      publicScheme: 'https',
+      certificateMode: 'ip-shortlived',
+    };
+  }
+  return {
+    publicHost: normalizedPublicIpv4(optionValues['--http-ip']),
+    publicScheme: 'http',
+    certificateMode: 'none',
+  };
+}
+
+async function currentStatus(config, statePath) {
+  const state = readJson(statePath);
+  const processExists = Boolean(state?.pid && isProcessAlive(state.pid));
+  const healthy = Boolean(config && processExists && (await probe(config)));
+  return {
+    installed: Boolean(config),
+    running: processExists,
+    healthy,
+    localUrl: config ? `http://127.0.0.1:${config.httpPort}` : undefined,
+    phoneUrl: phoneUrl(config),
+    state,
+  };
+}
+
+async function stop(config, statePath) {
+  if (!config) return { stopped: true, alreadyStopped: true, dataPreserved: true };
+  const state = readJson(statePath);
+  if (!state?.pid || !isProcessAlive(state.pid)) {
+    return { stopped: true, alreadyStopped: true, dataPreserved: true };
+  }
+  if (state.id !== config.id || state.runId !== config.runId || !(await probe(config))) {
+    throw new Error('实例身份或健康状态无法确认；不会终止可能不属于 Chat Hub 的进程');
+  }
+  if (process.platform === 'win32' && state.appPid && isProcessAlive(state.appPid)) {
+    process.kill(state.appPid, 'SIGTERM');
+  }
+  process.kill(state.pid, 'SIGTERM');
+  const deadline = Date.now() + 15_000;
+  while (
+    Date.now() < deadline &&
+    (isProcessAlive(state.pid) ||
+      (process.platform === 'win32' && state.appPid && isProcessAlive(state.appPid)))
+  ) {
+    await delay(200);
+  }
+  if (
+    isProcessAlive(state.pid) ||
+    (process.platform === 'win32' && state.appPid && isProcessAlive(state.appPid))
+  ) {
+    throw new Error('服务未在超时内停止，请检查日志');
+  }
+  writeJson(statePath, {
+    ...state,
+    status: 'stopped',
+    code: 'stopped_by_cli',
+    updatedAt: new Date().toISOString(),
+  });
+  return { stopped: true, dataPreserved: true };
+}
+
+function hasRuntimeChanges(saved) {
+  return (
+    (options['--data-dir'] && resolve(options['--data-dir']) !== saved.dataDirectory) ||
+    (options['--api-port'] && Number(options['--api-port']) !== saved.apiPort) ||
+    (options['--http-port'] && Number(options['--http-port']) !== saved.httpPort) ||
+    (options['--lan-ip'] && options['--lan-ip'] !== saved.lanIp) ||
+    (options['--lan'] && !saved.lanIp)
+  );
+}
+
+function selectLan(saved) {
+  const requested = options['--lan-ip'] ?? (options['--lan'] ? undefined : saved?.lanIp);
+  const candidates = lanAddresses();
+  if (requested) {
+    const selected = candidates.find((entry) => entry.address === requested);
+    if (!selected) throw new Error('指定或已保存的局域网地址当前不可用，请运行 doctor');
+    return selected;
+  }
+  if (!options['--lan']) return undefined;
+  if (candidates.length !== 1) throw new Error('局域网地址不唯一，请用 --lan-ip 明确指定');
+  return candidates[0];
+}
+
+function lanAddresses() {
+  return Object.entries(networkInterfaces()).flatMap(([name, entries]) =>
+    (entries ?? [])
+      .filter(
+        (entry) =>
+          !entry.internal &&
+          entry.family === 'IPv4' &&
+          /^(10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.)/.test(entry.address),
+      )
+      .map((entry) => ({ name, address: entry.address, netmask: entry.netmask })),
+  );
+}
+
+function ensureLocalLinuxMasterKey(runtimeDirectory) {
+  const path = join(runtimeDirectory, 'local-master-key');
+  if (!existsSync(path)) writeFileSync(path, randomBytes(32), { flag: 'wx', mode: 0o600 });
+  chmodSync(path, 0o600);
+  return path;
+}
+
+function mkdirSecure(directory) {
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  if (process.platform !== 'win32') chmodSync(directory, 0o700);
+}
+
+function writeJson(path, value) {
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  if (process.platform !== 'win32') chmodSync(path, 0o600);
+}
+
+function readJson(path) {
+  if (!existsSync(path)) return undefined;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    throw new Error(`运行状态文件损坏：${path}`);
+  }
+}
+
+function parsePort(name, fallback) {
+  const value = Number(options[name] ?? fallback);
+  if (!Number.isInteger(value) || value < 1024 || value > 65_535) {
+    throw new Error(`${name} 必须是 1024–65535 的整数`);
+  }
+  return value;
+}
+
+async function freePort(port, host) {
+  await new Promise((resolvePromise, rejectPromise) => {
+    const server = createServer();
+    server.once('error', () => rejectPromise(new Error(`${host}:${port} 已被占用或不可绑定`)));
+    server.listen(port, host, () => server.close(resolvePromise));
+  });
+}
+
+async function probe(config) {
+  try {
+    const setup = await fetch(`http://127.0.0.1:${config.httpPort}/__setup/status`, {
+      signal: AbortSignal.timeout(1_000),
+    });
+    const setupBody = await setup.json();
+    if (!setup.ok || setupBody.id !== config.id) return false;
+    const health = await fetch(`http://127.0.0.1:${config.httpPort}/api/health`, {
+      signal: AbortSignal.timeout(1_000),
+    });
+    const healthBody = await health.json();
+    return health.ok && healthBody.ok === true && healthBody.data?.status === 'ready';
+  } catch {
+    return false;
+  }
+}
+
+function phoneUrl(config) {
+  return config?.lanIp ? `http://${config.lanIp}:${config.httpPort}` : undefined;
+}
+
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function delay(milliseconds) {
+  return new Promise((resolvePromise) => setTimeout(resolvePromise, milliseconds));
+}
+
+function report(value) {
+  console.log(JSON.stringify({ ok: true, ...value }, null, 2));
+}