Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

39.4 KB
Raw Blame
import * as fs from "node:fs";
import * as os from "node:os";
import * as path from "node:path";
import * as readline from "node:readline";
import { fileURLToPath } from "node:url";
import { getEnv } from "../runtime-utils.js";
import {
  cleanOpenVikingRequestHeaders,
  type OpenVikingRequestHeaders,
} from "../request-headers.js";
import {
  createSetupNetworkProbes,
  type SetupApiKeyProbeResult,
  type SetupHealthResult,
} from "../services/setup/probe-service.js";

const HOME = os.homedir();
const OPENCLAW_DIR = getEnv("OPENCLAW_STATE_DIR") || path.join(HOME, ".openclaw");
const DEFAULT_REMOTE_URL = "http://127.0.0.1:1933";

function findPluginPackageRoot(fromDir = path.dirname(fileURLToPath(import.meta.url))): string | null {
  let current = path.resolve(fromDir);
  for (let depth = 0; depth < 5; depth += 1) {
    if (
      fs.existsSync(path.join(current, "package.json")) &&
      fs.existsSync(path.join(current, "openclaw.plugin.json"))
    ) {
      return current;
    }

    const parent = path.dirname(current);
    if (parent === current) break;
    current = parent;
  }
  return null;
}

function readPluginVersion(): string {
  try {
    const packageRoot = findPluginPackageRoot();
    if (!packageRoot) return "unknown";
    const pkgPath = path.join(packageRoot, "package.json");
    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
    return String(pkg.version ?? "unknown");
  } catch {
    return "unknown";
  }
}

function readCompatRangeFromManifest(): { min: string; max: string } {
  try {
    const packageRoot = findPluginPackageRoot();
    if (!packageRoot) return { min: "", max: "" };
    const manifestPath = path.join(packageRoot, "install-manifest.json");
    const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
    const compat = manifest?.compatibility ?? {};
    return {
      min: String(compat.minOpenvikingVersion ?? ""),
      max: String(compat.maxOpenvikingVersion ?? ""),
    };
  } catch {
    return { min: "", max: "" };
  }
}

const PLUGIN_VERSION = readPluginVersion();
const { min: COMPATIBLE_SERVER_MIN, max: COMPATIBLE_SERVER_MAX } = readCompatRangeFromManifest();
const CONFIG_KEYS_TO_PRESERVE = [
  "contextManagementMode",
  "targetUri",
  "headers",
  "timeoutMs",
  "autoCapture",
  "captureMode",
  "captureMaxLength",
  "autoRecall",
  "recallResources",
  "recallTargetTypes",
  "recallLimit",
  "recallScoreThreshold",
  "recallMaxInjectedChars",
  "recallMaxContentChars",
  "recallPreferAbstract",
  "recallTokenBudget",
  "commitTokenThresholdRatio",
  "commitRetentionMode",
  "commitKeepRecentCount",
  "bypassSessionPatterns",
  "emitStandardDiagnostics",
  "logFindRequests",
] as const;

type PeerRole = "none" | "assistant" | "sender";
const DEFAULT_SETUP_PEER_ROLE: PeerRole = "none";
type RecallTargetType = "resource" | "user" | "agent";
const ALLOWED_RECALL_TARGET_TYPES = ["resource", "user", "agent"] as const;

type CommandProgram = {
  command: (name: string) => CommandBuilder;
};

type CommandBuilder = {
  description: (desc: string) => CommandBuilder;
  option: (flags: string, desc: string) => CommandBuilder;
  command: (name: string) => CommandBuilder;
  action: (fn: (...args: unknown[]) => void | Promise<void>) => CommandBuilder;
};

type RegisterCliArgs = {
  program: CommandProgram;
};

function tr(langZh: boolean, en: string, zh: string): string {
  return langZh ? zh : en;
}

function maskKey(key: string): string {
  if (key.length <= 8) return "****";
  return `${key.slice(0, 4)}...${key.slice(-4)}`;
}

function nonEmptyOpenVikingRequestHeaders(value: unknown): OpenVikingRequestHeaders | undefined {
  const headers = cleanOpenVikingRequestHeaders(value);
  return Object.keys(headers).length > 0 ? headers : undefined;
}

function isValidPeerPrefixInput(value: string): boolean {
  const trimmed = value.trim();
  return !trimmed || /^[a-zA-Z0-9_-]+$/.test(trimmed);
}

function normalizePeerRole(value: unknown): PeerRole | undefined {
  if (typeof value !== "string") return undefined;
  const role = value.trim().toLowerCase();
  if (role === "person") return "sender";
  if (role === "none" || role === "assistant" || role === "sender") return role;
  return undefined;
}

// `person` survives only in existing configs; setup input must say `sender`.
function normalizePeerRoleInput(value: unknown): PeerRole | undefined {
  if (typeof value === "string" && value.trim().toLowerCase() === "person") return undefined;
  return normalizePeerRole(value);
}

function resolveExistingPeerRole(existing: Record<string, unknown> | null | undefined): PeerRole {
  const explicit = normalizePeerRole(existing?.peer_role);
  if (explicit) return explicit;
  return DEFAULT_SETUP_PEER_ROLE;
}

function resolveExistingPeerPrefix(existing: Record<string, unknown> | null | undefined): string {
  const value = existing?.peer_prefix;
  if (typeof value !== "string" || !value.trim()) return "";
  const trimmed = value.trim();
  return trimmed === "default" ? "" : trimmed;
}

function resolveSetupPeerRole(value: unknown): PeerRole {
  if (value === undefined) return DEFAULT_SETUP_PEER_ROLE;
  const role = normalizePeerRoleInput(value);
  if (role) return role;
  throw new Error('peer_role must be "none", "assistant", or "sender" ("person" was renamed to "sender")');
}

function normalizeSetupRecallTargetTypes(value: unknown): RecallTargetType[] | undefined {
  if (value === undefined || value === null || value === "") {
    return undefined;
  }
  const entries = Array.isArray(value)
    ? value
    : typeof value === "string"
      ? value.split(/[,\n]/)
      : [];
  const seen = new Set<RecallTargetType>();
  const normalized: RecallTargetType[] = [];
  const unknown: string[] = [];

  for (const raw of entries) {
    if (typeof raw !== "string") {
      continue;
    }
    const entry = raw.trim();
    if (!entry) {
      continue;
    }
    if ((ALLOWED_RECALL_TARGET_TYPES as readonly string[]).includes(entry)) {
      const typed = entry as RecallTargetType;
      if (!seen.has(typed)) {
        seen.add(typed);
        normalized.push(typed);
      }
    } else {
      unknown.push(entry);
    }
  }

  if (unknown.length > 0) {
    throw new Error(`recall-target-types contains unknown resource types: ${unknown.join(", ")}`);
  }
  return normalized.length > 0 ? normalized : undefined;
}

function preserveCurrentConfig(existing: Record<string, unknown> | null | undefined) {
  const config: Record<string, unknown> = {};
  if (!existing) {
    return config;
  }
  for (const key of CONFIG_KEYS_TO_PRESERVE) {
    if (key in existing) {
      config[key] = existing[key];
    }
  }
  return config;
}

async function askPeerRole(
  zh: boolean,
  q: (prompt: string, def?: string) => Promise<string>,
  defaultValue: PeerRole,
): Promise<PeerRole> {
  console.log(
    `  ${tr(
      zh,
      "Memory scope — none (default): viking://user/<user_id>/memories, shared across all conversations; " +
        "assistant: viking://user/<user_id>/peers/<assistant_id>/memories; " +
        "sender: viking://user/<user_id>/peers/<sender_id>/memories.",
      "记忆归属 —— none(默认):viking://user/<user_id>/memories,所有对话共享;" +
        "assistant:viking://user/<user_id>/peers/<assistant_id>/memories;" +
        "sender:viking://user/<user_id>/peers/<sender_id>/memories。",
    )}`,
  );
  while (true) {
    const value = await q(
      tr(zh, "Memory scope (none/assistant/sender)", "记忆归属(none/assistant/sender)"),
      defaultValue,
    );
    const role = normalizePeerRoleInput(value);
    if (role) return role;
    console.log(
      `  ✗ ${tr(
        zh,
        'Memory scope must be "none", "assistant", or "sender" ("person" was renamed to "sender").',
        '记忆归属必须是 "none"、"assistant" 或 "sender"("person" 已更名为 "sender")。',
      )}`,
    );
  }
}

async function askPeerPrefix(
  zh: boolean,
  q: (prompt: string, def?: string) => Promise<string>,
  defaultValue: string,
): Promise<string> {
  while (true) {
    const value = (await q(
      tr(zh, "Peer Prefix (optional)", "Peer Prefix(可选)"),
      defaultValue,
    )).trim();
    if (isValidPeerPrefixInput(value)) {
      return value;
    }
    console.log(
      `  ✗ ${tr(
        zh,
        "Peer Prefix may only contain letters, digits, underscores, and hyphens, or be empty.",
        "Peer Prefix 只能包含字母、数字、下划线和连字符,或留空。",
      )}`,
    );
  }
}

function ask(rl: readline.Interface, prompt: string, defaultValue = ""): Promise<string> {
  const suffix = defaultValue ? ` [${defaultValue}]` : "";
  return new Promise((resolve) => {
    rl.question(`${prompt}${suffix}: `, (answer) => {
      resolve((answer ?? "").trim() || defaultValue);
    });
  });
}

type VersionCompatibility = "compatible" | "server_too_old" | "server_too_new" | "unknown";

type HealthResult = SetupHealthResult;

function parseVersionTuple(v: string): number[] | null {
  const cleaned = v.replace(/^v/i, "").split("-")[0];
  const parts = cleaned.split(".").map(Number);
  if (parts.some(isNaN)) return null;
  return parts;
}

function compareVersions(a: number[], b: number[]): number {
  const len = Math.max(a.length, b.length);
  for (let i = 0; i < len; i++) {
    const diff = (a[i] ?? 0) - (b[i] ?? 0);
    if (diff !== 0) return diff;
  }
  return 0;
}

function checkVersionCompatibility(serverVersion: string): VersionCompatibility {
  if (!serverVersion) return "unknown";
  const sv = parseVersionTuple(serverVersion);
  if (!sv) return "unknown";

  if (COMPATIBLE_SERVER_MIN) {
    const minV = parseVersionTuple(COMPATIBLE_SERVER_MIN);
    if (minV && compareVersions(sv, minV) < 0) return "server_too_old";
  }
  if (COMPATIBLE_SERVER_MAX) {
    const maxV = parseVersionTuple(COMPATIBLE_SERVER_MAX);
    if (maxV && compareVersions(sv, maxV) > 0) return "server_too_new";
  }
  return "compatible";
}

function formatCompatRange(): string {
  if (COMPATIBLE_SERVER_MIN && COMPATIBLE_SERVER_MAX) return `${COMPATIBLE_SERVER_MIN} ~ ${COMPATIBLE_SERVER_MAX}`;
  if (COMPATIBLE_SERVER_MIN) return `>= ${COMPATIBLE_SERVER_MIN}`;
  if (COMPATIBLE_SERVER_MAX) return `<= ${COMPATIBLE_SERVER_MAX}`;
  return "any";
}

type ApiKeyProbeResult = SetupApiKeyProbeResult;

const setupProbes = createSetupNetworkProbes({
  pluginVersion: PLUGIN_VERSION,
  compatRange: formatCompatRange(),
  checkVersionCompatibility,
});

function readOpenClawConfig(configPath: string): Record<string, unknown> {
  if (!fs.existsSync(configPath)) return {};
  try {
    return JSON.parse(fs.readFileSync(configPath, "utf-8"));
  } catch {
    return {};
  }
}

function getExistingPluginConfig(config: Record<string, unknown>): Record<string, unknown> | null {
  const plugins = config.plugins as Record<string, unknown> | undefined;
  if (!plugins) return null;
  const entries = plugins.entries as Record<string, unknown> | undefined;
  if (!entries) return null;
  const entry = entries.openviking as Record<string, unknown> | undefined;
  if (!entry) return null;
  const cfg = entry.config as Record<string, unknown> | undefined;
  return cfg && cfg.mode ? cfg : null;
}

function backupConfig(configPath: string): string | null {
  if (!fs.existsSync(configPath)) return null;
  const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
  const backupPath = `${configPath}.bak.${timestamp}`;
  try {
    fs.copyFileSync(configPath, backupPath);
    return backupPath;
  } catch {
    return null;
  }
}

function ensureInstallRecord(plugins: Record<string, unknown>): void {
  const installs = plugins.installs as Record<string, unknown> | undefined;
  if (installs && typeof installs === "object") {
    delete installs.openviking;
  }

  if (!plugins.allow) plugins.allow = [];
  const allow = plugins.allow as string[];
  if (!allow.includes("openviking")) {
    allow.push("openviking");
  }
}

function writeConfig(
  configPath: string,
  pluginCfg: Record<string, unknown>,
): void {
  const configDir = path.dirname(configPath);
  if (!fs.existsSync(configDir)) fs.mkdirSync(configDir, { recursive: true });

  backupConfig(configPath);

  const config = readOpenClawConfig(configPath);

  if (!config.plugins) config.plugins = {};
  const plugins = config.plugins as Record<string, unknown>;
  if (!plugins.entries) plugins.entries = {};
  const entries = plugins.entries as Record<string, unknown>;

  const existingEntry = (entries.openviking as Record<string, unknown>) ?? {};
  entries.openviking = { ...existingEntry, config: pluginCfg };

  ensureInstallRecord(plugins);

  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
}

function detectLangZh(options: Record<string, unknown>): boolean {
  if (options.zh) return true;
  const lang = getEnv("LANG") || getEnv("LC_ALL") || "";
  return /^zh/i.test(lang);
}

function isLegacyLocalMode(existing: Record<string, unknown>): boolean {
  const mode = existing.mode;
  return mode !== "remote";
}

type SetupResult = {
  success: boolean;
  action: "configured" | "existing" | "error" | "slot_blocked";
  config?: {
    mode: string;
    baseUrl: string;
    apiKey?: string;
    peer_role?: PeerRole;
    peer_prefix?: string;
    accountId?: string;
    userId?: string;
    recallTargetTypes?: string[];
  };
  health?: HealthResult;
  keyProbe?: ApiKeyProbeResult;
  slot: SlotActivationResult;
  error?: string;
};

function setExitCodeOnFailure(result: { success: boolean }): void {
  if (!result.success) {
    process.exitCode = 1;
  }
}

type StatusResult = {
  configured: boolean;
  config?: {
    mode: string;
    baseUrl: string;
    hasApiKey: boolean;
    peer_role: PeerRole;
    peer_prefix?: string;
    hasAccountId: boolean;
    hasUserId: boolean;
  };
  health?: HealthResult;
  keyProbe?: ApiKeyProbeResult;
  slotActive: boolean;
};

type SlotActivationResult = {
  activated: boolean;
  previousOwner?: string;
  replaced: boolean;
};

function activateContextEngineSlot(configPath: string, force = false): SlotActivationResult {
  const config = readOpenClawConfig(configPath);
  if (!config.plugins) config.plugins = {};
  const plugins = config.plugins as Record<string, unknown>;
  if (!plugins.slots) plugins.slots = {};
  const slots = plugins.slots as Record<string, unknown>;

  const current = slots.contextEngine as string | undefined;

  if (current === "openviking") return { activated: false, replaced: false };

  if (current && current !== "openviking" && !force) {
    return { activated: false, previousOwner: current, replaced: false };
  }

  slots.contextEngine = "openviking";
  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
  return { activated: true, previousOwner: current || undefined, replaced: !!current };
}

function isContextEngineSlotActive(configPath: string): boolean {
  const config = readOpenClawConfig(configPath);
  const plugins = config.plugins as Record<string, unknown> | undefined;
  if (!plugins) return false;
  const slots = plugins.slots as Record<string, unknown> | undefined;
  return slots?.contextEngine === "openviking";
}

// eslint-disable-next-line @typescript-eslint/no-explicit-any
export function registerSetupCli(api: any): void {
  if (!api.registerCli) {
    api.logger.info("openviking: registerCli not available, setup command skipped");
    return;
  }

  api.registerCli(
    ({ program }: RegisterCliArgs) => {
      const ovCmd = program.command("openviking").description("OpenViking plugin commands");

      ovCmd
        .command("setup")
        .description("Setup OpenViking plugin (supports both interactive and non-interactive modes)")
        .option("--reconfigure", "Force re-entry of all configuration values")
        .option("--zh", "Chinese prompts")
        .option("--base-url <url>", "OpenViking server URL (enables non-interactive mode)")
        .option("--api-key <key>", "API key for authentication")
        .option("--peer-role <role>", "Memory scope: none (shared), assistant (per assistant), or sender (per sender)")
        .option("--peer-prefix <prefix>", "Prefix for assistant peer_id values")
        .option("--account-id <id>", "Account ID (required for root API keys)")
        .option("--user-id <id>", "User ID (required for root API keys)")
        .option("--recall-target-types <types>", "Comma-separated recall target types: user, agent, resource")
        .option("--allow-offline", "Allow config write even if server is unreachable")
        .option("--force-slot", "Replace existing contextEngine slot even if owned by another plugin")
        .option("--json", "Output result as JSON (machine-readable)")
        .action(async (...args: unknown[]) => {
          const options = (args[0] ?? {}) as Record<string, unknown>;
          const {
            reconfigure, zh: zhOpt, baseUrl, apiKey, peerRole, peerPrefix,
            accountId, userId, recallTargetTypes, allowOffline, forceSlot, json: jsonOpt,
          } = options as {
            reconfigure?: boolean; zh?: boolean; baseUrl?: string;
            apiKey?: string; peerRole?: string; peerPrefix?: string; accountId?: string;
            userId?: string; recallTargetTypes?: string; allowOffline?: boolean; forceSlot?: boolean;
            json?: boolean;
          };
          const zh = detectLangZh(options);
          const configPath = path.join(OPENCLAW_DIR, "openclaw.json");
          const jsonMode = !!jsonOpt;
          const nonInteractive = !!baseUrl;

          if (nonInteractive) {
            const result = await setupNonInteractive(configPath, {
              baseUrl: baseUrl!,
              apiKey,
              peerRole,
              peerPrefix,
              accountId,
              userId,
              recallTargetTypes: normalizeSetupRecallTargetTypes(recallTargetTypes),
              allowOffline: !!allowOffline,
              forceSlot: !!forceSlot,
            });
            if (jsonMode) {
              console.log(JSON.stringify(result, null, 2));
            } else {
              printSetupResult(zh, result);
            }
            setExitCodeOnFailure(result);
            return;
          }

          if (jsonMode && !nonInteractive) {
            const result: SetupResult = {
              success: false,
              action: "error",
              slot: { activated: false, replaced: false },
              error: "--json requires --base-url for non-interactive mode",
            };
            console.log(JSON.stringify(result, null, 2));
            setExitCodeOnFailure(result);
            return;
          }

          console.log("");
          console.log(`🦣 ${tr(zh, "OpenViking Plugin Setup", "OpenViking 插件配置向导")}`);
          console.log("");

          const config = readOpenClawConfig(configPath);
          const existing = getExistingPluginConfig(config);

          const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
          const q = (prompt: string, def = "") => ask(rl, prompt, def);

          try {
            if (existing && !reconfigure) {
              if (isLegacyLocalMode(existing)) {
                console.log(tr(
                  zh,
                  "Existing configuration uses local mode, which is no longer supported.",
                  "当前配置为本地模式,已不再支持。",
                ));
                console.log(tr(
                  zh,
                  "Run `openclaw openviking setup --reconfigure` to configure a remote OpenViking server.",
                  "请运行 `openclaw openviking setup --reconfigure` 以配置远程 OpenViking 服务。",
                ));
                console.log("");
                return;
              }

              console.log(tr(zh, "Existing configuration found:", "已找到现有配置:"));
              console.log(`  mode:    ${existing.mode}`);
              console.log(`  baseUrl: ${existing.baseUrl ?? DEFAULT_REMOTE_URL}`);
              if (existing.apiKey) console.log(`  apiKey:  ${maskKey(String(existing.apiKey))}`);
              console.log(`  peer_role: ${resolveExistingPeerRole(existing)}`);
              const existingPeerPrefix = resolveExistingPeerPrefix(existing);
              if (existingPeerPrefix) console.log(`  peer_prefix: ${existingPeerPrefix}`);
              console.log("");
              console.log(tr(
                zh,
                "Press Enter to keep existing values, or use --reconfigure to change.",
                "按 Enter 保留现有配置,或使用 --reconfigure 重新配置。",
              ));
              console.log("");
              console.log(tr(zh, "✓ Using existing configuration", "✓ 使用现有配置"));
              console.log("");

              await runRemoteCheck(zh, existing);

              const slotResult = activateContextEngineSlot(configPath);
              printSlotResult(zh, slotResult);

              console.log(tr(zh,
                "✓ Plugin is ready. Run `openclaw gateway --force` to activate.",
                "✓ 插件已就绪。运行 `openclaw gateway --force` 以激活。",
              ));
              console.log("");
              return;
            }

            if (existing && options.reconfigure) {
              console.log(tr(zh, "Existing configuration found:", "已找到现有配置:"));
              if (isLegacyLocalMode(existing)) {
                console.log(tr(zh,
                  "(Previous local-mode settings will be replaced with remote settings.)",
                  "(将用远程模式设置替换此前的本地模式配置。)",
                ));
              } else {
                console.log(`  mode:    ${existing.mode}`);
                console.log(`  baseUrl: ${existing.baseUrl ?? DEFAULT_REMOTE_URL}`);
                if (existing.apiKey) console.log(`  apiKey:  ${maskKey(String(existing.apiKey))}`);
              }
              console.log("");
              console.log(tr(zh, "Reconfiguring...", "重新配置中..."));
              console.log("");
            } else {
              console.log(tr(zh,
                "No existing configuration found. Starting setup wizard.",
                "未找到现有配置,开始配置向导。",
              ));
              console.log("");
            }

            await setupRemote(zh, configPath, existing, q);
          } finally {
            rl.close();
          }
        });

      ovCmd
        .command("status")
        .description("Show current OpenViking plugin status and connectivity")
        .option("--zh", "Chinese prompts")
        .option("--json", "Output result as JSON (machine-readable)")
        .action(async (...args: unknown[]) => {
          const options = (args[0] ?? {}) as Record<string, unknown>;
          const { zh: zhOpt, json: jsonOpt } = options as { zh?: boolean; json?: boolean };
          const zh = detectLangZh(options);
          const configPath = path.join(OPENCLAW_DIR, "openclaw.json");
          const jsonMode = !!jsonOpt;

          const result = await getStatus(configPath);

          if (jsonMode) {
            console.log(JSON.stringify(result, null, 2));
            return;
          }

          printStatus(zh, result);
        });
    },
    { commands: ["openviking"] },
  );
}

function printCompatibilityWarning(zh: boolean, health: HealthResult): void {
  if (health.compatibility === "server_too_old") {
    console.log(`  ⚠ ${tr(zh,
      `Server version ${health.version} is older than recommended (${health.compatRange}). Some features may not work. Please upgrade OpenViking server.`,
      `服务端版本 ${health.version} 低于推荐范围(${health.compatRange})。部分功能可能不可用,请升级 OpenViking 服务端。`,
    )}`);
  } else if (health.compatibility === "server_too_new") {
    console.log(`  ⚠ ${tr(zh,
      `Server version ${health.version} is newer than supported (${health.compatRange}). Please upgrade the OpenViking plugin.`,
      `服务端版本 ${health.version} 高于插件支持范围(${health.compatRange})。请升级 OpenViking 插件。`,
    )}`);
  } else if (health.compatibility === "unknown" && health.ok) {
    console.log(`  ⚠ ${tr(zh,
      "Could not determine server version. Compatibility check skipped.",
      "无法获取服务端版本,已跳过兼容性检查。",
    )}`);
  }
}

async function runRemoteCheck(
  zh: boolean,
  existing: Record<string, unknown>,
): Promise<void> {
  const baseUrl = String(existing.baseUrl ?? DEFAULT_REMOTE_URL);
  const apiKey = existing.apiKey ? String(existing.apiKey) : undefined;
  const headers = nonEmptyOpenVikingRequestHeaders(existing.headers);
  console.log(tr(zh, `Testing connectivity to ${baseUrl}...`, `正在测试连接 ${baseUrl}...`));
  const health = await setupProbes.checkServiceHealth(baseUrl, apiKey, headers);
  if (health.ok) {
    const ver = health.version ? ` (version: ${health.version})` : "";
    console.log(`  ✓ ${tr(zh, `Connected successfully${ver}`, `连接成功${ver}`)}`);
    printCompatibilityWarning(zh, health);
  } else {
    console.log(`  ✗ ${tr(zh, `Connection failed: ${health.error}`, `连接失败: ${health.error}`)}`);
  }
  console.log("");
}

async function setupNonInteractive(
  configPath: string,
  params: {
    baseUrl: string;
    apiKey?: string;
    peerRole?: string;
    peerPrefix?: string;
    accountId?: string;
    userId?: string;
    recallTargetTypes?: string[];
    allowOffline?: boolean;
    forceSlot?: boolean;
  },
): Promise<SetupResult> {
  try {
    const { baseUrl, apiKey, peerPrefix, accountId, userId, recallTargetTypes, allowOffline, forceSlot } = params;
    const resolvedPeerRole = resolveSetupPeerRole(params.peerRole);
    const resolvedPeerPrefix = (peerPrefix ?? "").trim();
    if (!isValidPeerPrefixInput(resolvedPeerPrefix)) {
      throw new Error("peer_prefix may only contain letters, digits, underscores, and hyphens, or be empty");
    }

    // Phase 1: validate connectivity and key type BEFORE writing config
    const health = await setupProbes.checkServiceHealth(baseUrl, apiKey);

    if (!health.ok && !allowOffline) {
      return {
        success: false,
        action: "error",
        config: { mode: "remote", baseUrl },
        health,
        slot: { activated: false, replaced: false },
        error: `Server unreachable: ${health.error}. Use --allow-offline to save config anyway.`,
      };
    }

    const keyProbe = health.ok ? await setupProbes.probeApiKeyType(baseUrl, apiKey) : undefined;

    if (keyProbe?.keyType === "root_key" && (!accountId || !userId)) {
      const missing: string[] = [];
      if (!accountId) missing.push("--account-id");
      if (!userId) missing.push("--user-id");
      return {
        success: false,
        action: "error",
        config: {
          mode: "remote",
          baseUrl,
          ...(apiKey ? { apiKey: maskKey(apiKey) } : {}),
        },
        health,
        keyProbe,
        slot: { activated: false, replaced: false },
        error: `Root API key detected. Missing: ${missing.join(", ")}. Re-run with: ${missing.map(f => `${f} <value>`).join(" ")}`,
      };
    }

    // Phase 2: all checks passed (or --allow-offline), write config and activate slot
    const pluginCfg: Record<string, unknown> = { mode: "remote", baseUrl };
    if (apiKey) pluginCfg.apiKey = apiKey;
    pluginCfg.peer_role = resolvedPeerRole;
    if (resolvedPeerPrefix) pluginCfg.peer_prefix = resolvedPeerPrefix;
    if (accountId) pluginCfg.accountId = accountId;
    if (userId) pluginCfg.userId = userId;
    if (recallTargetTypes && recallTargetTypes.length > 0) {
      pluginCfg.recallTargetTypes = recallTargetTypes;
    }

    writeConfig(configPath, pluginCfg);
    const slot = activateContextEngineSlot(configPath, !!forceSlot);

    if (!slot.activated && slot.previousOwner) {
      return {
        success: false,
        action: "slot_blocked",
        config: {
          mode: "remote",
          baseUrl,
          ...(apiKey ? { apiKey: maskKey(apiKey) } : {}),
          peer_role: resolvedPeerRole,
          ...(resolvedPeerPrefix ? { peer_prefix: resolvedPeerPrefix } : {}),
          ...(accountId ? { accountId } : {}),
          ...(userId ? { userId } : {}),
          ...(recallTargetTypes && recallTargetTypes.length > 0 ? { recallTargetTypes } : {}),
        },
        health,
        keyProbe,
        slot,
        error: `contextEngine slot is owned by "${slot.previousOwner}". Config was saved but slot was NOT changed. Use --force-slot to replace.`,
      };
    }

    return {
      success: true,
      action: "configured",
      config: {
        mode: "remote",
        baseUrl,
        ...(apiKey ? { apiKey: maskKey(apiKey) } : {}),
        peer_role: resolvedPeerRole,
        ...(resolvedPeerPrefix ? { peer_prefix: resolvedPeerPrefix } : {}),
        ...(accountId ? { accountId } : {}),
        ...(userId ? { userId } : {}),
        ...(recallTargetTypes && recallTargetTypes.length > 0 ? { recallTargetTypes } : {}),
      },
      health,
      keyProbe,
      slot,
    };
  } catch (err) {
    return {
      success: false,
      action: "error",
      slot: { activated: false, replaced: false },
      error: String(err instanceof Error ? err.message : err),
    };
  }
}

function printSetupResult(zh: boolean, result: SetupResult): void {
  console.log("");
  if (result.success) {
    console.log(`🦣 ${tr(zh, "OpenViking Plugin Setup Complete", "OpenViking 插件配置完成")}`);
    console.log("");
    if (result.config) {
      console.log(`  mode:    ${result.config.mode}`);
      console.log(`  baseUrl: ${result.config.baseUrl}`);
      if (result.config.apiKey) console.log(`  apiKey:  ${result.config.apiKey}`);
      console.log(`  peer_role: ${result.config.peer_role ?? DEFAULT_SETUP_PEER_ROLE}`);
      if (result.config.peer_prefix) console.log(`  peer_prefix: ${result.config.peer_prefix}`);
      if (result.config.accountId) console.log(`  accountId: ${result.config.accountId}`);
      if (result.config.userId) console.log(`  userId:  ${result.config.userId}`);
      if (result.config.recallTargetTypes) console.log(`  recallTargetTypes: ${result.config.recallTargetTypes.join(",")}`);
    }
    console.log("");
    if (result.health?.ok) {
      const ver = result.health.version ? ` (version: ${result.health.version})` : "";
      console.log(`  ✓ ${tr(zh, `Connected successfully${ver}`, `连接成功${ver}`)}`);
      printCompatibilityWarning(zh, result.health);
    } else if (result.health) {
      console.log(`  ✗ ${tr(zh, `Connection failed: ${result.health.error}`, `连接失败: ${result.health.error}`)}`);
    }
    if (result.keyProbe) {
      printKeyProbeWarning(zh, result.keyProbe);
    }
    printSlotResult(zh, result.slot);
    console.log("");
    console.log(tr(zh,
      "Run `openclaw gateway --force` to activate the plugin.",
      "运行 `openclaw gateway --force` 以激活插件。",
    ));
  } else {
    console.log(`✗ ${tr(zh, "Setup failed", "配置失败")}: ${result.error}`);
    if (result.keyProbe?.keyType === "root_key") {
      printKeyProbeWarning(zh, result.keyProbe);
    }
  }
  console.log("");
}

async function getStatus(configPath: string): Promise<StatusResult> {
  const config = readOpenClawConfig(configPath);
  const existing = getExistingPluginConfig(config);
  const slotActive = isContextEngineSlotActive(configPath);

  if (!existing) {
    return { configured: false, slotActive };
  }

  const baseUrl = String(existing.baseUrl ?? DEFAULT_REMOTE_URL);
  const apiKey = existing.apiKey ? String(existing.apiKey) : undefined;
  const headers = nonEmptyOpenVikingRequestHeaders(existing.headers);
  const health = await setupProbes.checkServiceHealth(baseUrl, apiKey, headers);
  const keyProbe = health.ok ? await setupProbes.probeApiKeyType(baseUrl, apiKey, headers) : undefined;

  const peerPrefix = resolveExistingPeerPrefix(existing);
  return {
    configured: true,
    config: {
      mode: String(existing.mode ?? "remote"),
      baseUrl,
      hasApiKey: !!existing.apiKey,
      peer_role: resolveExistingPeerRole(existing),
      ...(peerPrefix ? { peer_prefix: peerPrefix } : {}),
      hasAccountId: !!existing.accountId,
      hasUserId: !!existing.userId,
    },
    health,
    keyProbe,
    slotActive,
  };
}

function printSlotResult(zh: boolean, slot: SlotActivationResult): void {
  if (slot.activated && slot.replaced) {
    console.log(`  ⚠ ${tr(zh,
      `Replaced context-engine slot: ${slot.previousOwner} → openviking`,
      `已替换 context-engine 插槽: ${slot.previousOwner} → openviking`,
    )}`);
  } else if (slot.activated) {
    console.log(`  ✓ ${tr(zh, "Activated context-engine slot: openviking", "已激活 context-engine 插槽: openviking")}`);
  } else if (slot.previousOwner && slot.previousOwner !== "openviking") {
    console.log(`  ⚠ ${tr(zh,
      `Context-engine slot is owned by "${slot.previousOwner}". Run: openclaw config set plugins.slots.contextEngine openviking`,
      `context-engine 插槽当前由 "${slot.previousOwner}" 占用。运行: openclaw config set plugins.slots.contextEngine openviking`,
    )}`);
  }
}

function printKeyProbeWarning(zh: boolean, probe: ApiKeyProbeResult): void {
  if (probe.keyType === "root_key") {
    console.log(`  ⚠ ${tr(zh,
      "Root API key detected. accountId and userId are required for this key type.",
      "检测到 Root API Key,此类型密钥需要提供 accountId 和 userId。",
    )}`);
    if (probe.needsAccountId) {
      console.log(`    ${tr(zh,
        "→ Missing: accountId (use --account-id or set in config)",
        "→ 缺少: accountId(使用 --account-id 或在配置中设置)",
      )}`);
    }
    if (probe.needsUserId) {
      console.log(`    ${tr(zh,
        "→ Missing: userId (use --user-id or set in config)",
        "→ 缺少: userId(使用 --user-id 或在配置中设置)",
      )}`);
    }
  }
}

function printStatus(zh: boolean, result: StatusResult): void {
  console.log("");
  console.log(`🦣 ${tr(zh, "OpenViking Plugin Status", "OpenViking 插件状态")}`);
  console.log("");

  if (!result.configured) {
    console.log(`  ${tr(zh, "Status: Not configured", "状态: 未配置")}`);
    console.log(`  ${tr(zh, "Run `openclaw openviking setup` to configure.", "运行 `openclaw openviking setup` 进行配置。")}`);
    console.log("");
    return;
  }

  console.log(`  ${tr(zh, "Status: Configured", "状态: 已配置")}`);
  if (result.config) {
    console.log(`  mode:      ${result.config.mode}`);
    console.log(`  baseUrl:   ${result.config.baseUrl}`);
    console.log(`  apiKey:    ${result.config.hasApiKey ? "set" : "not set"}`);
    console.log(`  peer_role: ${result.config.peer_role}`);
    if (result.config.peer_prefix) console.log(`  peer_prefix: ${result.config.peer_prefix}`);
    console.log(`  accountId: ${result.config.hasAccountId ? "set" : "not set"}`);
    console.log(`  userId:    ${result.config.hasUserId ? "set" : "not set"}`);
  }
  console.log(`  slot:      ${result.slotActive ? "active" : "inactive"}`);
  console.log("");

  if (result.health?.ok) {
    const ver = result.health.version ? ` (version: ${result.health.version})` : "";
    console.log(`  ✓ ${tr(zh, `Server reachable${ver}`, `服务器可达${ver}`)}`);
    printCompatibilityWarning(zh, result.health);
  } else if (result.health) {
    console.log(`  ✗ ${tr(zh, `Server unreachable: ${result.health.error}`, `服务器不可达: ${result.health.error}`)}`);
  }

  if (result.keyProbe) {
    printKeyProbeWarning(zh, result.keyProbe);
  }
  console.log("");
}

async function setupRemote(
  zh: boolean,
  configPath: string,
  existing: Record<string, unknown> | null,
  q: (prompt: string, def?: string) => Promise<string>,
): Promise<void> {
  console.log("");
  console.log(tr(zh, "── Remote Mode Configuration ──", "── 远程模式配置 ──"));
  console.log("");

  const defaultUrl = existing?.baseUrl && String(existing.baseUrl).trim()
    ? String(existing.baseUrl)
    : DEFAULT_REMOTE_URL;
  const defaultApiKey = existing?.apiKey ? String(existing.apiKey) : "";
  const defaultPeerRole = resolveExistingPeerRole(existing);
  const defaultPeerPrefix = resolveExistingPeerPrefix(existing);
  const headers = nonEmptyOpenVikingRequestHeaders(existing?.headers);

  const baseUrl = await q(tr(zh, "OpenViking server URL", "OpenViking 服务器地址"), defaultUrl);
  const apiKey = await q(tr(zh, "API Key (optional)", "API Key(可选)"), defaultApiKey);

  let accountId = existing?.accountId ? String(existing.accountId) : "";
  let userId = existing?.userId ? String(existing.userId) : "";

  if (apiKey) {
    console.log(tr(zh, "  Detecting API key type...", "  正在检测 API Key 类型..."));
    const probe = await setupProbes.probeApiKeyType(baseUrl, apiKey, headers);
    if (probe.keyType === "root_key") {
      console.log(tr(zh,
        "  ⚠ Root API key detected. accountId and userId are required.",
        "  ⚠ 检测到 Root API Key,需要提供 accountId 和 userId。",
      ));
      accountId = await q(tr(zh, "Account ID (required for root key)", "Account ID(root key 必填)"), accountId);
      userId = await q(tr(zh, "User ID (required for root key)", "User ID(root key 必填)"), userId);
    } else if (probe.keyType === "user_key") {
      console.log(tr(zh, "  ✓ User key verified", "  ✓ User key 已验证"));
    }
  }

  const peerRole = await askPeerRole(zh, q, defaultPeerRole);
  const peerPrefix = peerRole === "assistant"
    ? await askPeerPrefix(zh, q, defaultPeerPrefix)
    : "";

  console.log("");

  console.log(tr(zh, `Testing connectivity to ${baseUrl}...`, `正在测试连接 ${baseUrl}...`));
  const health = await setupProbes.checkServiceHealth(baseUrl, apiKey || undefined, headers);
  if (health.ok) {
    const ver = health.version ? ` (version: ${health.version})` : "";
    console.log(`  ✓ ${tr(zh, `Connected successfully${ver}`, `连接成功${ver}`)}`);
    printCompatibilityWarning(zh, health);
  } else {
    console.log(`  ✗ ${tr(zh, `Connection failed: ${health.error}`, `连接失败: ${health.error}`)}`);
    console.log("");
    console.log(tr(zh,
      "  The configuration will still be saved. Make sure the server is reachable\n  before starting the gateway.",
      "  配置仍会保存。请确保服务器在启动 gateway 前可达。",
    ));
  }
  console.log("");

  const pluginCfg: Record<string, unknown> = {
    ...preserveCurrentConfig(existing),
    mode: "remote",
    baseUrl,
  };
  if (apiKey) pluginCfg.apiKey = apiKey;
  else delete pluginCfg.apiKey;
  pluginCfg.peer_role = peerRole;
  if (peerPrefix) pluginCfg.peer_prefix = peerPrefix;
  else delete pluginCfg.peer_prefix;
  if (accountId) pluginCfg.accountId = accountId;
  else delete pluginCfg.accountId;
  if (userId) pluginCfg.userId = userId;
  else delete pluginCfg.userId;

  writeConfig(configPath, pluginCfg);

  const slotResult = activateContextEngineSlot(configPath);

  console.log("");
  console.log(`  ${tr(zh, "mode:", "模式:")}    remote`);
  console.log(`  baseUrl: ${baseUrl}`);
  if (apiKey) console.log(`  apiKey:  ${maskKey(apiKey)}`);
  console.log(`  peer_role: ${peerRole}`);
  if (peerPrefix) console.log(`  peer_prefix: ${peerPrefix}`);
  if (accountId) console.log(`  accountId: ${accountId}`);
  if (userId) console.log(`  userId:  ${userId}`);
  printSlotResult(zh, slotResult);
  console.log("");
  console.log(tr(zh,
    "Run `openclaw gateway --force` to activate the plugin.",
    "运行 `openclaw gateway --force` 以激活插件。",
  ));
  console.log("");
}

export const __test__ = {
  isLegacyLocalMode,
  isValidPeerPrefixInput,
  normalizePeerRole,
  resolveSetupPeerRole,
  normalizeSetupRecallTargetTypes,
  activateContextEngineSlot,
  isContextEngineSlotActive,
  getStatus,
  setupNonInteractive,
  checkVersionCompatibility,
  parseVersionTuple,
  compareVersions,
  ensureInstallRecord,
  findPluginPackageRoot,
  readCompatRangeFromManifest,
  readPluginVersion,
  setExitCodeOnFailure,
};