Skip to content

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

104 KB
Raw Blame
#!/usr/bin/env node
/**
 * OpenClaw OpenViking plugin installer (remote OpenViking server — does not install Python/OpenViking server).
 *
 * One-liner (after npm publish; use package name + bin name):
 *   npx -p openclaw-openviking-setup-helper ov-install [ --base-url URL ] [ --api-key KEY ] [ --zh ] [ --workdir PATH ]
 * Or install globally then run:
 *   npm i -g openclaw-openviking-setup-helper
 *   ov-install
 *   openclaw-openviking-install
 *
 * Direct run:
 *   node install.js [ --base-url URL ] [ --api-key KEY ] [ --zh ] [ --workdir PATH ] [ --upgrade-plugin ]
 *                   [ --plugin-version=VERSION ] [ --plugin-source=npm|github ]
 *
 * Environment variables:
 *   PLUGIN_SOURCE, PLUGIN_NPM_PACKAGE, REPO, PLUGIN_VERSION (or BRANCH),
 *   OPENVIKING_BASE_URL, OPENVIKING_API_KEY, SKIP_OPENCLAW, NPM_REGISTRY
 */

import { spawn } from "node:child_process";
import { cp, mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
import { existsSync, readdirSync } from "node:fs";
import { basename, dirname, join } from "node:path";
import { tmpdir } from "node:os";
import { createInterface } from "node:readline";
import { fileURLToPath } from "node:url";

const __dirname = dirname(fileURLToPath(import.meta.url));

let REPO = process.env.REPO || "volcengine/OpenViking";
const DEFAULT_PLUGIN_NPM_PACKAGE = "@openviking/openclaw-plugin";
let pluginNpmPackage = (process.env.PLUGIN_NPM_PACKAGE || DEFAULT_PLUGIN_NPM_PACKAGE).trim();
let pluginSource = (process.env.PLUGIN_SOURCE || "npm").trim().toLowerCase();
let pluginSourceExplicit = Boolean(process.env.PLUGIN_SOURCE);
// PLUGIN_VERSION takes precedence over BRANCH (legacy). If omitted, resolve the latest npm dist-tag or GitHub tag.
const pluginVersionEnv = (process.env.PLUGIN_VERSION || process.env.BRANCH || "").trim();
let PLUGIN_VERSION = pluginVersionEnv;
let pluginVersionExplicit = Boolean(pluginVersionEnv);
const NPM_REGISTRY = process.env.NPM_REGISTRY || "https://registry.npmmirror.com";
const DEFAULT_NPM_BUILD_MIN_OPENCLAW_VERSION = "2026.5.3";
const OPENCLAW_SHORT_VERSION_YEAR = 2026;

const IS_WIN = process.platform === "win32";
const HOME = process.env.HOME || process.env.USERPROFILE || "";

const DEFAULT_OPENCLAW_DIR = join(HOME, ".openclaw");
let OPENCLAW_DIR = DEFAULT_OPENCLAW_DIR;
let PLUGIN_DEST = "";  // Will be set after resolving plugin config

// Fallback configs for old versions without manifest
const FALLBACK_LEGACY = {
  dir: "openclaw-memory-plugin",
  id: "memory-openviking",
  kind: "memory",
  slot: "memory",
  minOpenclawVersion: "2026.3.7",
  required: ["index.ts", "config.ts", "client.ts", "openclaw.plugin.json", "package.json"],
  optional: ["package-lock.json", ".gitignore", "memory-ranking.ts", "text-utils.ts", "process-manager.ts", "tsconfig.json"],
};

// Must match examples/openclaw-plugin/install-manifest.json (npm only installs package deps, not these .ts files).
const FALLBACK_CURRENT = {
  dir: "openclaw-plugin",
  id: "openviking",
  kind: "context-engine",
  slot: "contextEngine",
  minOpenclawVersion: "2026.4.8",
  required: ["index.ts", "config.ts", "package.json", "openclaw.plugin.json"],
  optional: [
    "context-engine.ts",
    "auto-recall.ts",
    "client.ts",
    "process-manager.ts",
    "memory-ranking.ts",
    "text-utils.ts",
    "tool-call-id.ts",
    "session-transcript-repair.ts",
    "runtime-utils.ts",
    "commands/setup.ts",
    "tsconfig.json",
    "package-lock.json",
    ".gitignore",
  ],
};

const PLUGIN_VARIANTS = [
  { ...FALLBACK_LEGACY, generation: "legacy", slotFallback: "none" },
  { ...FALLBACK_CURRENT, generation: "current", slotFallback: "legacy" },
];

// Resolved plugin config (set by resolvePluginConfig)
let resolvedPluginDir = "";
let resolvedPluginId = "";
let resolvedPluginKind = "";
let resolvedPluginSlot = "";
let resolvedFilesRequired = [];
let resolvedFilesOptional = [];
let resolvedNpmOmitDev = true;
let resolvedNpmBuild = false;
let resolvedNpmBuildMinOpenclawVersion = DEFAULT_NPM_BUILD_MIN_OPENCLAW_VERSION;
let resolvedNpmBuildScript = "build";
let resolvedNpmPruneAfterBuild = true;
let resolvedMinOpenclawVersion = "";
let resolvedMinOpenvikingVersion = "";
let resolvedPluginReleaseId = "";
let detectedOpenClawVersion = "";
let npmPackageTempDir = "";
let npmPackageExtractDir = "";

let nonInteractive = false;
let langZh = false;
let workdirExplicit = false;
let upgradePluginOnly = false;
let rollbackLastUpgrade = false;
let showCurrentVersion = false;
let uninstallPlugin = false;
let forceSlotExplicit = false;
let allowOfflineExplicit = false;

const selectedMode = "remote";
const baseUrlFromEnv = !!process.env.OPENVIKING_BASE_URL;
let remoteBaseUrl = (process.env.OPENVIKING_BASE_URL || "http://127.0.0.1:1933").trim();
let remoteApiKey = (process.env.OPENVIKING_API_KEY || "").trim();
let remotePeerRole = (process.env.OPENVIKING_PEER_ROLE || "").trim().toLowerCase();
let remotePeerPrefix = (process.env.OPENVIKING_PEER_PREFIX || "").trim();
let peerRoleExplicit = !!process.env.OPENVIKING_PEER_ROLE;
if (!remotePeerRole) remotePeerRole = "none";
let remoteAccountId = (process.env.OPENVIKING_ACCOUNT_ID || "").trim();
let remoteUserId = (process.env.OPENVIKING_USER_ID || "").trim();
let baseUrlExplicit = baseUrlFromEnv;
let upgradeRuntimeConfig = null;
let installedUpgradeState = null;
let upgradeAudit = null;

const argv = process.argv.slice(2);
for (let i = 0; i < argv.length; i++) {
  const arg = argv[i];
  if (arg === "-y" || arg === "--yes") {
    err(tr(
      "-y/--yes has been removed. Use --base-url <URL> [--api-key <KEY>] for non-interactive mode.",
      "-y/--yes 已移除。使用 --base-url <URL> [--api-key <KEY>] 进入非交互模式。",
    ));
    process.exit(1);
  }
  if (arg === "--zh") {
    langZh = true;
    continue;
  }
  if (arg === "--current-version") {
    showCurrentVersion = true;
    continue;
  }
  if (arg === "--upgrade-plugin" || arg === "--update" || arg === "--upgrade") {
    upgradePluginOnly = true;
    continue;
  }
  if (arg === "--rollback" || arg === "--rollback-last-upgrade") {
    rollbackLastUpgrade = true;
    continue;
  }
  if (arg === "--uninstall" || arg === "--remove") {
    uninstallPlugin = true;
    continue;
  }
  if (arg === "--force-slot") {
    forceSlotExplicit = true;
    continue;
  }
  if (arg === "--allow-offline") {
    allowOfflineExplicit = true;
    continue;
  }
  if (arg === "--workdir") {
    const workdir = argv[i + 1]?.trim();
    if (!workdir) {
      console.error("--workdir requires a path");
      process.exit(1);
    }
    setOpenClawDir(workdir);
    workdirExplicit = true;
    i += 1;
    continue;
  }
  if (arg.startsWith("--plugin-version=")) {
    const version = arg.slice("--plugin-version=".length).trim();
    if (!version) {
      console.error("--plugin-version requires a value");
      process.exit(1);
    }
    PLUGIN_VERSION = version;
    pluginVersionExplicit = true;
    continue;
  }
  if (arg === "--plugin-version") {
    const version = argv[i + 1]?.trim();
    if (!version) {
      console.error("--plugin-version requires a value");
      process.exit(1);
    }
    PLUGIN_VERSION = version;
    pluginVersionExplicit = true;
    i += 1;
    continue;
  }
  if (arg.startsWith("--github-repo=")) {
    REPO = arg.slice("--github-repo=".length).trim();
    if (!pluginSourceExplicit) {
      pluginSource = "github";
    }
    continue;
  }
  if (arg === "--github-repo") {
    const repo = argv[i + 1]?.trim();
    if (!repo) {
      console.error("--github-repo requires a value (e.g. owner/repo)");
      process.exit(1);
    }
    REPO = repo;
    if (!pluginSourceExplicit) {
      pluginSource = "github";
    }
    i += 1;
    continue;
  }
  if (arg.startsWith("--plugin-source=") || arg.startsWith("--source=")) {
    const value = arg.includes("--plugin-source=")
      ? arg.slice("--plugin-source=".length).trim()
      : arg.slice("--source=".length).trim();
    pluginSource = value.toLowerCase();
    pluginSourceExplicit = true;
    continue;
  }
  if (arg === "--plugin-source" || arg === "--source") {
    const value = argv[i + 1]?.trim();
    if (!value) {
      console.error(`${arg} requires a value (npm or github)`);
      process.exit(1);
    }
    pluginSource = value.toLowerCase();
    pluginSourceExplicit = true;
    i += 1;
    continue;
  }
  if (arg.startsWith("--plugin-package=") || arg.startsWith("--npm-package=")) {
    const value = arg.includes("--plugin-package=")
      ? arg.slice("--plugin-package=".length).trim()
      : arg.slice("--npm-package=".length).trim();
    if (!value) {
      console.error("--plugin-package requires a package name");
      process.exit(1);
    }
    pluginNpmPackage = value;
    continue;
  }
  if (arg === "--plugin-package" || arg === "--npm-package") {
    const value = argv[i + 1]?.trim();
    if (!value) {
      console.error(`${arg} requires a package name`);
      process.exit(1);
    }
    pluginNpmPackage = value;
    i += 1;
    continue;
  }
  if (arg === "--base-url") {
    const val = argv[i + 1]?.trim();
    if (!val) { console.error("--base-url requires a URL"); process.exit(1); }
    remoteBaseUrl = val;
    baseUrlExplicit = true;
    i += 1;
    continue;
  }
  if (arg.startsWith("--base-url=")) {
    remoteBaseUrl = arg.slice("--base-url=".length).trim();
    baseUrlExplicit = true;
    continue;
  }
  if (arg === "--api-key") {
    const val = argv[i + 1]?.trim();
    if (!val) { console.error("--api-key requires a value"); process.exit(1); }
    remoteApiKey = val;
    i += 1;
    continue;
  }
  if (arg.startsWith("--api-key=")) {
    remoteApiKey = arg.slice("--api-key=".length).trim();
    continue;
  }
  if (arg === "--peer-role") {
    const val = argv[i + 1]?.trim();
    if (!val) { console.error("--peer-role requires a value"); process.exit(1); }
    const role = normalizePeerRoleInput(val);
    if (!role) { console.error('--peer-role must be "none", "assistant", or "sender" ("person" was renamed to "sender")'); process.exit(1); }
    remotePeerRole = role;
    peerRoleExplicit = true;
    i += 1;
    continue;
  }
  if (arg.startsWith("--peer-role=")) {
    const role = normalizePeerRoleInput(arg.slice("--peer-role=".length));
    if (!role) { console.error('--peer-role must be "none", "assistant", or "sender" ("person" was renamed to "sender")'); process.exit(1); }
    remotePeerRole = role;
    peerRoleExplicit = true;
    continue;
  }
  if (arg === "--peer-prefix") {
    const val = argv[i + 1]?.trim();
    if (!val) { console.error("--peer-prefix requires a value"); process.exit(1); }
    remotePeerPrefix = val;
    i += 1;
    continue;
  }
  if (arg.startsWith("--peer-prefix=")) {
    remotePeerPrefix = arg.slice("--peer-prefix=".length).trim();
    continue;
  }
  if (arg === "--account-id") {
    const val = argv[i + 1]?.trim();
    if (!val) { console.error("--account-id requires a value"); process.exit(1); }
    remoteAccountId = val;
    i += 1;
    continue;
  }
  if (arg.startsWith("--account-id=")) {
    remoteAccountId = arg.slice("--account-id=".length).trim();
    continue;
  }
  if (arg === "--user-id") {
    const val = argv[i + 1]?.trim();
    if (!val) { console.error("--user-id requires a value"); process.exit(1); }
    remoteUserId = val;
    i += 1;
    continue;
  }
  if (arg.startsWith("--user-id=")) {
    remoteUserId = arg.slice("--user-id=".length).trim();
    continue;
  }
  if (arg === "-h" || arg === "--help") {
    printHelp();
    process.exit(0);
  }
}

if (remotePeerRole === "person") {
  console.error('OPENVIKING_PEER_ROLE must be "none", "assistant", or "sender" ("person" was renamed to "sender")');
  process.exit(1);
}
remotePeerRole = normalizePeerRole(remotePeerRole) || "none";
if (!isValidPeerPrefixInput(remotePeerPrefix)) {
  console.error("--peer-prefix may only contain letters, digits, underscores, and hyphens");
  process.exit(1);
}

nonInteractive = baseUrlExplicit;

function setOpenClawDir(dir) {
  OPENCLAW_DIR = dir;
}

function printHelp() {
  console.log("Usage: node install.js [ OPTIONS ]");
  console.log("");
  console.log("Options:");
  console.log("  --plugin-source=npm|github");
  console.log("                           Plugin download source (default: npm)");
  console.log("  --plugin-package=NAME    npm plugin package (default: @openviking/openclaw-plugin)");
  console.log("  --github-repo=OWNER/REPO GitHub repository (implies --plugin-source=github unless source is set)");
  console.log("  --plugin-version=VERSION Plugin version (npm version/tag or Git tag; default: npm latest)");
  console.log("  --workdir PATH           OpenClaw config directory (default: ~/.openclaw)");
  console.log("  --current-version        Print installed plugin version and exit");
  console.log("  --update, --upgrade-plugin");
  console.log("                           Upgrade only the plugin to the requested --plugin-version; keeps existing plugin runtime config");
  console.log("  --rollback, --rollback-last-upgrade");
  console.log("                           Roll back the last plugin upgrade using the saved audit/backup files");
  console.log("  --uninstall, --remove    Uninstall OpenViking plugin from OpenClaw (backup config, remove plugin entries)");
  console.log("  --base-url=URL           OpenViking server URL (default: $OPENVIKING_BASE_URL or http://127.0.0.1:1933)");
  console.log("  --api-key=KEY            OpenViking API key (default: $OPENVIKING_API_KEY)");
  console.log("  --peer-role=ROLE         Memory scope: none (shared), assistant (per assistant), sender (per sender) (default: $OPENVIKING_PEER_ROLE or none)");
  console.log("  --peer-prefix=PREFIX     Prefix for assistant peer_id values (default: $OPENVIKING_PEER_PREFIX)");
  console.log("  --account-id=ID          Account ID for root API key (default: $OPENVIKING_ACCOUNT_ID)");
  console.log("  --user-id=ID             User ID for root API key (default: $OPENVIKING_USER_ID)");
  console.log("  --force-slot             Explicitly replace an existing contextEngine slot owner");
  console.log("  --allow-offline          Explicitly save config when the OpenViking server is unreachable");
  console.log("  --zh                     Chinese prompts");
  console.log("  -h, --help               This help");
  console.log("");
  console.log("Examples:");
  console.log("  # Install latest version");
  console.log("  node install.js");
  console.log("");
  console.log("  # Show installed versions");
  console.log("  node install.js --current-version");
  console.log("");
  console.log("  # Install a specific release version");
  console.log("  node install.js --plugin-version=2026.6.18");
  console.log("");
  console.log("  # Install from a fork repository");
  console.log("  node install.js --github-repo=yourname/OpenViking --plugin-version=dev-branch");
  console.log("");
  console.log("  # Install specific plugin version");
  console.log("  node install.js --plugin-version=v0.2.8");
  console.log("");
  console.log("  # Upgrade only the plugin files from main branch");
  console.log("  node install.js --update --plugin-version=main");
  console.log("");
  console.log("  # Roll back the last plugin upgrade");
  console.log("  node install.js --rollback");
  console.log("");
  console.log("Env: PLUGIN_SOURCE, PLUGIN_NPM_PACKAGE, REPO, PLUGIN_VERSION, SKIP_OPENCLAW, NPM_REGISTRY");
}

function formatCliArg(value) {
  if (!value) {
    return "";
  }
  return /[\s"]/u.test(value) ? JSON.stringify(value) : value;
}

function getLegacyInstallCommandHint() {
  const override = process.env.OPENVIKING_INSTALL_LEGACY_HINT?.trim();
  if (override) {
    return override;
  }

  const invokedScript = process.argv[1] ? basename(process.argv[1]) : "";
  const args = ["--plugin-version", "<legacy-version>"];
  if (workdirExplicit || OPENCLAW_DIR !== DEFAULT_OPENCLAW_DIR) {
    args.push("--workdir", formatCliArg(OPENCLAW_DIR));
  }
  if (REPO !== "volcengine/OpenViking") {
    args.push("--github-repo", formatCliArg(REPO));
  }
  if (langZh) {
    args.push("--zh");
  }

  if (invokedScript === "install.js") {
    return `node install.js ${args.join(" ")}`;
  }

  return `ov-install ${args.join(" ")}`;
}

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

function info(msg) {
  console.log(`[INFO] ${msg}`);
}

function warn(msg) {
  console.log(`[WARN] ${msg}`);
}

function err(msg) {
  console.log(`[ERROR] ${msg}`);
}

function bold(msg) {
  console.log(msg);
}

function run(cmd, args, opts = {}) {
  return new Promise((resolve, reject) => {
    const child = spawn(cmd, args, {
      stdio: opts.silent ? "pipe" : "inherit",
      shell: opts.shell ?? true,
      ...opts,
    });
    child.on("error", reject);
    child.on("close", (code) => {
      if (code === 0) resolve();
      else reject(new Error(`exit ${code}`));
    });
  });
}

function runCapture(cmd, args, opts = {}) {
  return new Promise((resolve) => {
    const child = spawn(cmd, args, {
      stdio: ["ignore", "pipe", "pipe"],
      shell: opts.shell ?? false,
      ...opts,
    });
    let out = "";
    let errOut = "";
    child.stdout?.on("data", (chunk) => {
      out += String(chunk);
    });
    child.stderr?.on("data", (chunk) => {
      errOut += String(chunk);
    });
    child.on("error", (error) => {
      resolve({ code: -1, out: "", err: String(error) });
    });
    child.on("close", (code) => {
      resolve({ code, out: out.trim(), err: errOut.trim() });
    });
  });
}

function question(prompt, defaultValue = "") {
  const rl = createInterface({ input: process.stdin, output: process.stdout });
  const suffix = defaultValue ? ` [${defaultValue}]` : "";
  return new Promise((resolve) => {
    rl.question(`${prompt}${suffix}: `, (answer) => {
      rl.close();
      resolve((answer ?? defaultValue).trim() || defaultValue);
    });
  });
}

function isYes(answer) {
  const normalized = String(answer || "").trim().toLowerCase();
  return normalized === "y" || normalized === "yes";
}

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

function normalizePeerRole(value) {
  const role = String(value || "").trim().toLowerCase();
  if (role === "person") return "sender";
  return role === "none" || role === "assistant" || role === "sender" ? role : null;
}

// `person` survives only in existing configs; installer input must say `sender`.
function normalizePeerRoleInput(value) {
  const role = String(value || "").trim().toLowerCase();
  return role === "person" ? null : normalizePeerRole(role);
}

function parseJsonObjectFromOutput(output) {
  const text = String(output || "").trim();
  if (!text) return null;
  try {
    return JSON.parse(text);
  } catch {
    // OpenClaw may print plugin registration logs before --json output.
  }
  for (let index = text.lastIndexOf("{"); index >= 0; index = text.lastIndexOf("{", index - 1)) {
    try {
      const parsed = JSON.parse(text.slice(index).trim());
      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
        return parsed;
      }
    } catch {
      // Keep scanning earlier braces until the outer JSON object is found.
    }
  }
  return null;
}

async function questionPeerRole(defaultValue = "none") {
  info(tr(
    "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 answer = await question(
      tr("Memory scope (none/assistant/sender)", "记忆归属(none/assistant/sender)"),
      defaultValue,
    );
    const role = normalizePeerRoleInput(answer);
    if (role) return role;
    warn(tr(
      'Memory scope must be "none", "assistant", or "sender" ("person" was renamed to "sender").',
      '记忆归属必须是 "none"、"assistant" 或 "sender"("person" 已更名为 "sender")。',
    ));
  }
}

async function questionPeerPrefix(defaultValue = "") {
  while (true) {
    const answer = (await question(
      tr("Peer Prefix (optional)", "Peer Prefix(可选)"),
      defaultValue,
    )).trim();
    if (isValidPeerPrefixInput(answer)) {
      return answer;
    }
    warn(tr(
      "Peer Prefix may only contain letters, digits, underscores, and hyphens, or be empty.",
      "Peer Prefix 只能包含字母、数字、下划线和连字符,或留空。",
    ));
  }
}

function detectOpenClawInstances() {
  const instances = [];
  try {
    const entries = readdirSync(HOME, { withFileTypes: true });
    for (const entry of entries) {
      if (!entry.isDirectory()) continue;
      if (entry.name === ".openclaw" || entry.name.startsWith(".openclaw-")) {
        instances.push(join(HOME, entry.name));
      }
    }
  } catch {}
  return instances.sort();
}

async function selectWorkdir() {
  if (workdirExplicit) return;

  const instances = detectOpenClawInstances();
  if (instances.length <= 1) return;
  if (showCurrentVersion) {
    setOpenClawDir(instances[0]);
    return;
  }
  if (nonInteractive) return;

  console.log("");
  bold(tr("Found multiple OpenClaw instances:", "发现多个 OpenClaw 实例:"));
  for (let i = 0; i < instances.length; i++) {
    console.log(`  ${i + 1}) ${instances[i]}`);
  }
  console.log("");

  const answer = await question(tr("Select instance number", "选择实例编号"), "1");
  const index = Number.parseInt(answer, 10) - 1;
  if (index >= 0 && index < instances.length) {
    setOpenClawDir(instances[index]);
  } else {
    warn(tr("Invalid selection, using default", "无效选择,使用默认"));
    setOpenClawDir(instances[0]);
  }
}

async function collectRemoteConfig() {
  if (nonInteractive) return;
  remoteBaseUrl = await question(tr("OpenViking server URL", "OpenViking 服务器地址"), remoteBaseUrl);
  remoteApiKey = await question(tr("API Key (optional)", "API Key(可选)"), remoteApiKey);
  remotePeerRole = await questionPeerRole(remotePeerRole);
  remotePeerPrefix = remotePeerRole === "assistant"
    ? await questionPeerPrefix(remotePeerPrefix)
    : "";
}

async function checkOpenClaw() {
  if (process.env.SKIP_OPENCLAW === "1") {
    info(tr("Skipping OpenClaw check (SKIP_OPENCLAW=1)", "跳过 OpenClaw 校验 (SKIP_OPENCLAW=1)"));
    return;
  }

  info(tr("Checking OpenClaw...", "正在校验 OpenClaw..."));
  const result = await runCapture("openclaw", ["--version"], { shell: IS_WIN });
  if (result.code === 0) {
    info(tr("OpenClaw detected ✓", "OpenClaw 已安装 ✓"));
    return;
  }

  err(tr("OpenClaw not found. Install it manually, then rerun this script.", "未检测到 OpenClaw,请先手动安装后再执行本脚本"));
  console.log("");
  console.log(tr("Recommended command:", "推荐命令:"));
  console.log(`  npm install -g openclaw --registry ${NPM_REGISTRY}`);
  console.log("");
  console.log("  openclaw --version");
  console.log("  openclaw onboard");
  console.log("");
  process.exit(1);
}

// Compare versions: returns true if v1 >= v2
function versionGte(v1, v2) {
  const parseVersion = (v) => {
    const cleaned = v.replace(/^v/, "").replace(/-.*$/, "");
    const parts = cleaned.split(".").map((p) => Number.parseInt(p, 10) || 0);
    while (parts.length < 3) parts.push(0);
    return parts;
  };
  const [a1, a2, a3] = parseVersion(v1);
  const [b1, b2, b3] = parseVersion(v2);
  if (a1 !== b1) return a1 > b1;
  if (a2 !== b2) return a2 > b2;
  return a3 >= b3;
}

function parseOpenClawPolicyVersion(value) {
  const parts = String(value || "")
    .match(/\d+/g)
    ?.map((part) => Number.parseInt(part, 10) || 0) || [];
  if (parts.length === 0) return [0, 0, 0];
  if (parts[0] >= 2000) {
    return [parts[0], parts[1] || 0, parts[2] || 0];
  }
  return [OPENCLAW_SHORT_VERSION_YEAR, parts[0] || 0, parts[1] || 0];
}

function openClawPolicyVersionGte(v1, v2) {
  const a = parseOpenClawPolicyVersion(v1);
  const b = parseOpenClawPolicyVersion(v2);
  for (let i = 0; i < 3; i++) {
    if (a[i] !== b[i]) return a[i] > b[i];
  }
  return true;
}

function applyOpenClawBuildPolicy(openClawVersion) {
  if (!resolvedNpmBuild || !resolvedNpmBuildMinOpenclawVersion) {
    return;
  }
  if (!openClawVersion || openClawVersion === "0.0.0") {
    warn(tr(
      "Could not determine OpenClaw version; keeping plugin source build enabled.",
      "无法确定 OpenClaw 版本,保持插件源码构建开启。",
    ));
    return;
  }
  if (openClawPolicyVersionGte(openClawVersion, resolvedNpmBuildMinOpenclawVersion)) {
    info(tr(
      `OpenClaw ${openClawVersion} requires plugin source build (>= ${resolvedNpmBuildMinOpenclawVersion})`,
      `OpenClaw ${openClawVersion} 需要插件源码构建(>= ${resolvedNpmBuildMinOpenclawVersion})`,
    ));
    return;
  }
  resolvedNpmBuild = false;
  info(tr(
    `OpenClaw ${openClawVersion} is below ${resolvedNpmBuildMinOpenclawVersion}; skipping plugin source build`,
    `OpenClaw ${openClawVersion} 低于 ${resolvedNpmBuildMinOpenclawVersion},跳过插件源码构建`,
  ));
}

function isSemverLike(value) {
  return /^v?\d+(\.\d+){1,2}$/.test(value);
}

function validateRequestedPluginVersion() {
  if (!isSemverLike(PLUGIN_VERSION)) return;
  if (versionGte(PLUGIN_VERSION, "v0.2.7") && !versionGte(PLUGIN_VERSION, "v0.2.8")) {
    err(tr("Plugin version v0.2.7 does not exist.", "插件版本 v0.2.7 不存在。"));
    process.exit(1);
  }
}

if (upgradePluginOnly && rollbackLastUpgrade) {
  console.error("--update/--upgrade-plugin and --rollback cannot be used together");
  process.exit(1);
}

if (uninstallPlugin && (upgradePluginOnly || rollbackLastUpgrade)) {
  console.error("--uninstall cannot be used with --upgrade-plugin or --rollback");
  process.exit(1);
}

if (!["npm", "github"].includes(pluginSource)) {
  console.error("--plugin-source must be either npm or github");
  process.exit(1);
}

function looksLikeLegacyGitHubRef(value) {
  const ref = String(value || "").trim();
  if (!ref) return false;
  if (/^v\d+(\.\d+){1,2}([-.].*)?$/i.test(ref)) return true;
  if (["main", "master"].includes(ref.toLowerCase())) return true;
  return false;
}

if (!pluginSourceExplicit && pluginVersionExplicit && looksLikeLegacyGitHubRef(PLUGIN_VERSION)) {
  pluginSource = "github";
}

// Detect OpenClaw version
async function detectOpenClawVersion() {
  if (detectedOpenClawVersion) {
    return detectedOpenClawVersion;
  }
  try {
    const result = await runCapture("openclaw", ["--version"], { shell: IS_WIN });
    const output = `${result.out || ""}\n${result.err || ""}`;
    if (result.code === 0 && output) {
      const match = output.match(/\d+\.\d+(\.\d+)?/);
      if (match) {
        detectedOpenClawVersion = match[0];
        return detectedOpenClawVersion;
      }
    }
  } catch {}
  detectedOpenClawVersion = "0.0.0";
  return detectedOpenClawVersion;
}

// Try to fetch a URL, return response text or null
async function tryFetch(url, timeout = 15000) {
  try {
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), timeout);
    const response = await fetch(url, { signal: controller.signal });
    clearTimeout(timeoutId);
    if (response.ok) {
      return await response.text();
    }
  } catch {}
  return null;
}

// Check if a remote file exists
async function testRemoteFile(url) {
  try {
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), 10000);
    const response = await fetch(url, { method: "HEAD", signal: controller.signal });
    clearTimeout(timeoutId);
    return response.ok;
  } catch {}
  return false;
}

function compareSemverDesc(a, b) {
  if (versionGte(a, b) && versionGte(b, a)) {
    return 0;
  }
  return versionGte(a, b) ? -1 : 1;
}

function pickLatestPluginTag(tagNames) {
  const normalized = tagNames
    .map((tag) => String(tag ?? "").trim())
    .filter(Boolean);

  const semverTags = normalized
    .filter((tag) => isSemverLike(tag))
    .sort(compareSemverDesc);

  if (semverTags.length > 0) {
    return semverTags[0];
  }

  return normalized[0] || "";
}

function npmPackageSpec(version = PLUGIN_VERSION) {
  return version ? `${pluginNpmPackage}@${version}` : pluginNpmPackage;
}

function parseNpmJsonOutput(output) {
  const text = String(output || "").trim();
  if (!text) return null;
  try {
    return JSON.parse(text);
  } catch {
    const firstArray = text.indexOf("[");
    const lastArray = text.lastIndexOf("]");
    if (firstArray >= 0 && lastArray > firstArray) {
      try {
        return JSON.parse(text.slice(firstArray, lastArray + 1));
      } catch {}
    }
    const firstObject = text.indexOf("{");
    const lastObject = text.lastIndexOf("}");
    if (firstObject >= 0 && lastObject > firstObject) {
      try {
        return JSON.parse(text.slice(firstObject, lastObject + 1));
      } catch {}
    }
  }
  return null;
}

async function resolveDefaultPluginVersionFromNpm() {
  info(tr(
    `No plugin version specified; resolving latest npm version from ${pluginNpmPackage}...`,
    `No plugin version specified; resolving latest npm version from ${pluginNpmPackage}...`,
  ));

  const result = await runCapture("npm", [
    "view",
    `${pluginNpmPackage}@latest`,
    "version",
    "--json",
    "--registry",
    NPM_REGISTRY,
  ], { shell: IS_WIN });

  if (result.code === 0) {
    const parsed = parseNpmJsonOutput(result.out);
    const version = typeof parsed === "string" ? parsed : String(result.out || "").trim().replace(/^"|"$/g, "");
    if (version) {
      PLUGIN_VERSION = version;
      info(tr(
        `Resolved default plugin version to npm latest: ${PLUGIN_VERSION}`,
        `Resolved default plugin version to npm latest: ${PLUGIN_VERSION}`,
      ));
      return true;
    }
  }

  warn(tr(
    `Could not resolve npm latest for ${pluginNpmPackage}${result.err ? `: ${result.err}` : ""}`,
    `Could not resolve npm latest for ${pluginNpmPackage}${result.err ? `: ${result.err}` : ""}`,
  ));
  return false;
}

async function ensureNpmPackageExtracted() {
  if (npmPackageExtractDir && existsSync(npmPackageExtractDir)) {
    return npmPackageExtractDir;
  }

  npmPackageTempDir = await mkdtemp(join(tmpdir(), "ov-plugin-npm-"));
  info(tr(
    `Downloading plugin package from npm: ${npmPackageSpec()}`,
    `Downloading plugin package from npm: ${npmPackageSpec()}`,
  ));

  const packResult = await runCapture("npm", [
    "pack",
    npmPackageSpec(),
    "--pack-destination",
    npmPackageTempDir,
    "--json",
    "--registry",
    NPM_REGISTRY,
  ], { shell: IS_WIN });

  if (packResult.code !== 0) {
    throw new Error(`npm pack failed for ${npmPackageSpec()}${packResult.err ? `: ${packResult.err}` : ""}`);
  }

  const parsed = parseNpmJsonOutput(packResult.out);
  const first = Array.isArray(parsed) ? parsed[0] : parsed;
  const filename = first?.filename || readdirSync(npmPackageTempDir).find((name) => name.endsWith(".tgz"));
  if (!filename) {
    throw new Error(`npm pack did not produce a tarball for ${npmPackageSpec()}`);
  }

  const tarballPath = join(npmPackageTempDir, filename);
  const extractRoot = join(npmPackageTempDir, "extract");
  await mkdir(extractRoot, { recursive: true });
  await run("tar", ["-xzf", tarballPath, "-C", extractRoot], { silent: true, shell: IS_WIN });

  const packageDir = join(extractRoot, "package");
  if (!existsSync(packageDir)) {
    throw new Error(`npm package ${npmPackageSpec()} did not contain the expected package directory`);
  }

  npmPackageExtractDir = packageDir;
  return npmPackageExtractDir;
}

function parseGitLsRemoteTags(output) {
  return String(output ?? "")
    .split(/\r?\n/)
    .map((line) => {
      const match = line.match(/refs\/tags\/(.+)$/);
      return match?.[1]?.trim() || "";
    })
    .filter(Boolean);
}

async function resolveDefaultPluginVersion() {
  if (PLUGIN_VERSION) {
    return;
  }

  if (pluginSource === "npm") {
    if (await resolveDefaultPluginVersionFromNpm()) {
      return;
    }
    warn(tr(
      "Falling back to GitHub tag resolution.",
      "Falling back to GitHub tag resolution.",
    ));
  }

  info(tr(
    `No plugin version specified; resolving latest tag from ${REPO}...`,
    `未指定插件版本,正在解析 ${REPO} 的最新 tag...`,
  ));

  const failures = [];
  const apiUrl = `https://api.github.com/repos/${REPO}/tags?per_page=100`;

  try {
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), 10000);
    const response = await fetch(apiUrl, {
      headers: {
        Accept: "application/vnd.github+json",
        "User-Agent": "openviking-setup-helper",
        "X-GitHub-Api-Version": "2022-11-28",
      },
      signal: controller.signal,
    });
    clearTimeout(timeoutId);

    if (response.ok) {
      const payload = await response.json().catch(() => null);
      if (Array.isArray(payload)) {
        const latestTag = pickLatestPluginTag(payload.map((item) => item?.name || ""));
        if (latestTag) {
          PLUGIN_VERSION = latestTag;
          info(tr(
            `Resolved default plugin version to latest tag: ${PLUGIN_VERSION}`,
            `已将默认插件版本解析为最新 tag: ${PLUGIN_VERSION}`,
          ));
          return;
        }
      } else {
        failures.push("GitHub tags API returned an unexpected payload");
      }
    } else {
      failures.push(`GitHub tags API returned HTTP ${response.status}`);
    }
  } catch (error) {
    failures.push(`GitHub tags API failed: ${String(error)}`);
  }

  const gitRef = `https://github.com/${REPO}.git`;
  const gitResult = await runCapture("git", ["ls-remote", "--tags", "--refs", gitRef], {
    shell: IS_WIN,
  });
  if (gitResult.code === 0 && gitResult.out) {
    const latestTag = pickLatestPluginTag(parseGitLsRemoteTags(gitResult.out));
    if (latestTag) {
      PLUGIN_VERSION = latestTag;
      info(tr(
        `Resolved default plugin version via git tags: ${PLUGIN_VERSION}`,
        `已通过 git tag 解析默认插件版本: ${PLUGIN_VERSION}`,
      ));
      return;
    }
    failures.push("git ls-remote returned no usable tags");
  } else {
    failures.push(`git ls-remote failed${gitResult.err ? `: ${gitResult.err}` : ""}`);
  }

  err(tr(
    `Could not resolve the latest tag for ${REPO}.`,
    `无法解析 ${REPO} 的最新 tag。`,
  ));
  console.log(tr(
    "Please rerun with --plugin-version <tag>, or use --plugin-version main to track the branch head explicitly.",
    "请使用 --plugin-version <tag> 重新执行;如果需要显式跟踪分支头,请使用 --plugin-version main。",
  ));
  if (failures.length > 0) {
    warn(failures.join(" | "));
  }
  process.exit(1);
}

function applyManifestConfig(manifestData) {
  resolvedPluginId = manifestData.plugin?.id || "";
  resolvedPluginKind = manifestData.plugin?.kind || "";
  resolvedPluginSlot = manifestData.plugin?.slot || "";
  resolvedMinOpenclawVersion = manifestData.compatibility?.minOpenclawVersion || "";
  resolvedMinOpenvikingVersion = manifestData.compatibility?.minOpenvikingVersion || "";
  resolvedPluginReleaseId = manifestData.pluginVersion || manifestData.release?.id || "";
  const npmConfig = manifestData.npm && typeof manifestData.npm === "object"
    ? manifestData.npm
    : {};
  resolvedNpmOmitDev = npmConfig.omitDev !== false;
  resolvedNpmBuild = npmConfig.build === true || npmConfig.buildFromSource === true;
  resolvedNpmBuildMinOpenclawVersion =
    typeof npmConfig.buildMinOpenclawVersion === "string" && npmConfig.buildMinOpenclawVersion.trim()
      ? npmConfig.buildMinOpenclawVersion.trim()
      : DEFAULT_NPM_BUILD_MIN_OPENCLAW_VERSION;
  resolvedNpmBuildScript = typeof npmConfig.buildScript === "string" && npmConfig.buildScript.trim()
    ? npmConfig.buildScript.trim()
    : "build";
  resolvedNpmPruneAfterBuild = npmConfig.pruneAfterBuild !== false;
  resolvedFilesRequired = manifestData.files?.required || [];
  resolvedFilesOptional = manifestData.files?.optional || [];
}

function hasPrebuiltRuntimeOutputs(packageDir) {
  return existsSync(join(packageDir, "dist", "index.js"));
}

async function resolvePluginConfigFromNpm() {
  info(tr(
    `Resolving plugin configuration from npm package: ${npmPackageSpec()}`,
    `Resolving plugin configuration from npm package: ${npmPackageSpec()}`,
  ));

  const packageDir = await ensureNpmPackageExtracted();
  const manifestPath = join(packageDir, "install-manifest.json");
  const packageJsonPath = join(packageDir, "package.json");
  let manifestData = null;
  let packageJson = null;

  if (existsSync(packageJsonPath)) {
    try {
      packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
      resolvedPluginReleaseId = packageJson.version || "";
    } catch {}
  }

  if (existsSync(manifestPath)) {
    try {
      manifestData = JSON.parse(await readFile(manifestPath, "utf8"));
      info(tr("Found manifest in npm package", "Found manifest in npm package"));
    } catch {}
  }

  resolvedPluginDir = ".";
  if (manifestData) {
    applyManifestConfig(manifestData);
  } else {
    const pkgName = packageJson?.name || "";
    const fallback = pkgName && pkgName !== DEFAULT_PLUGIN_NPM_PACKAGE ? FALLBACK_LEGACY : FALLBACK_CURRENT;
    resolvedPluginId = fallback.id;
    resolvedPluginKind = fallback.kind;
    resolvedPluginSlot = fallback.slot;
    resolvedFilesRequired = fallback.required;
    resolvedFilesOptional = fallback.optional;
    resolvedNpmOmitDev = true;
    resolvedNpmBuild = false;
    resolvedNpmBuildMinOpenclawVersion = DEFAULT_NPM_BUILD_MIN_OPENCLAW_VERSION;
    resolvedNpmBuildScript = "build";
    resolvedNpmPruneAfterBuild = true;
    resolvedMinOpenclawVersion = (packageJson?.engines?.openclaw || "").replace(/^>=?\s*/, "").trim()
      || fallback.minOpenclawVersion
      || "2026.3.7";
    resolvedMinOpenvikingVersion = "";
  }

  if (hasPrebuiltRuntimeOutputs(packageDir)) {
    resolvedNpmBuild = false;
    info(tr(
      "npm package contains prebuilt runtime output; skipping source build.",
      "npm package contains prebuilt runtime output; skipping source build.",
    ));
  }

  PLUGIN_DEST = join(OPENCLAW_DIR, "extensions", resolvedPluginId || "openviking");
  info(tr(`Plugin: ${resolvedPluginId} (${resolvedPluginKind})`, `Plugin: ${resolvedPluginId} (${resolvedPluginKind})`));
}

// Resolve plugin configuration from manifest or fallback
async function resolvePluginConfig() {
  if (pluginSource === "npm") {
    try {
      await resolvePluginConfigFromNpm();
      return;
    } catch (error) {
      warn(tr(
        `npm plugin resolution failed: ${error?.message || error}`,
        `npm plugin resolution failed: ${error?.message || error}`,
      ));
      warn(tr(
        "Falling back to GitHub plugin download.",
        "Falling back to GitHub plugin download.",
      ));
      pluginSource = "github";
    }
  }

  const ghRaw = `https://raw.githubusercontent.com/${REPO}/${PLUGIN_VERSION}`;

  info(tr(`Resolving plugin configuration for version: ${PLUGIN_VERSION}`, `正在解析插件配置,版本: ${PLUGIN_VERSION}`));

  resolvedNpmOmitDev = true;
  resolvedNpmBuild = false;
  resolvedNpmBuildMinOpenclawVersion = DEFAULT_NPM_BUILD_MIN_OPENCLAW_VERSION;
  resolvedNpmBuildScript = "build";
  resolvedNpmPruneAfterBuild = true;

  let pluginDir = "";
  let manifestData = null;

  // Try to detect plugin directory and download manifest
  const manifestCurrent = await tryFetch(`${ghRaw}/examples/openclaw-plugin/install-manifest.json`);
  if (manifestCurrent) {
    pluginDir = "openclaw-plugin";
    try {
      manifestData = JSON.parse(manifestCurrent);
    } catch {}
    info(tr("Found manifest in openclaw-plugin", "在 openclaw-plugin 中找到 manifest"));
  } else {
    const manifestLegacy = await tryFetch(`${ghRaw}/examples/openclaw-memory-plugin/install-manifest.json`);
    if (manifestLegacy) {
      pluginDir = "openclaw-memory-plugin";
      try {
        manifestData = JSON.parse(manifestLegacy);
      } catch {}
      info(tr("Found manifest in openclaw-memory-plugin", "在 openclaw-memory-plugin 中找到 manifest"));
    } else if (await testRemoteFile(`${ghRaw}/examples/openclaw-plugin/index.ts`)) {
      pluginDir = "openclaw-plugin";
      info(tr("No manifest found, using fallback for openclaw-plugin", "未找到 manifest,使用 openclaw-plugin 回退配置"));
    } else if (await testRemoteFile(`${ghRaw}/examples/openclaw-memory-plugin/index.ts`)) {
      pluginDir = "openclaw-memory-plugin";
      info(tr("No manifest found, using fallback for openclaw-memory-plugin", "未找到 manifest,使用 openclaw-memory-plugin 回退配置"));
    } else {
      err(tr(`Cannot find plugin directory for version: ${PLUGIN_VERSION}`, `无法找到版本 ${PLUGIN_VERSION} 的插件目录`));
      process.exit(1);
    }
  }

  resolvedPluginDir = pluginDir;
  resolvedPluginReleaseId = "";

  if (manifestData) {
    resolvedPluginId = manifestData.plugin?.id || "";
    resolvedPluginKind = manifestData.plugin?.kind || "";
    resolvedPluginSlot = manifestData.plugin?.slot || "";
    resolvedMinOpenclawVersion = manifestData.compatibility?.minOpenclawVersion || "";
    resolvedMinOpenvikingVersion = manifestData.compatibility?.minOpenvikingVersion || "";
    resolvedPluginReleaseId = manifestData.pluginVersion || manifestData.release?.id || "";
    const npmConfig = manifestData.npm && typeof manifestData.npm === "object"
      ? manifestData.npm
      : {};
    resolvedNpmOmitDev = npmConfig.omitDev !== false;
    resolvedNpmBuild = npmConfig.build === true || npmConfig.buildFromSource === true;
    resolvedNpmBuildMinOpenclawVersion =
      typeof npmConfig.buildMinOpenclawVersion === "string" && npmConfig.buildMinOpenclawVersion.trim()
        ? npmConfig.buildMinOpenclawVersion.trim()
        : DEFAULT_NPM_BUILD_MIN_OPENCLAW_VERSION;
    resolvedNpmBuildScript = typeof npmConfig.buildScript === "string" && npmConfig.buildScript.trim()
      ? npmConfig.buildScript.trim()
      : "build";
    resolvedNpmPruneAfterBuild = npmConfig.pruneAfterBuild !== false;
    resolvedFilesRequired = manifestData.files?.required || [];
    resolvedFilesOptional = manifestData.files?.optional || [];
  } else {
    // No manifest — determine plugin identity by package.json name
    let fallbackKey = pluginDir === "openclaw-memory-plugin" ? "legacy" : "current";
    let compatVer = "";

    const pkgJson = await tryFetch(`${ghRaw}/examples/${pluginDir}/package.json`);
    if (pkgJson) {
      try {
        const pkg = JSON.parse(pkgJson);
        const pkgName = pkg.name || "";
        resolvedPluginReleaseId = pkg.version || "";
        const currentPackageNames = new Set(["@openviking/openclaw-plugin", "@openclaw/openviking"]);
        if (pkgName && !currentPackageNames.has(pkgName)) {
          fallbackKey = "legacy";
          info(tr(`Detected legacy plugin by package name: ${pkgName}`, `通过 package.json 名称检测到旧版插件: ${pkgName}`));
        } else if (pkgName) {
          fallbackKey = "current";
        }
        compatVer = (pkg.engines?.openclaw || "").replace(/^>=?\s*/, "").trim();
        if (compatVer) {
          info(tr(`Read minOpenclawVersion from package.json engines.openclaw: >=${compatVer}`, `从 package.json engines.openclaw 读取到最低版本: >=${compatVer}`));
        }
      } catch {}
    }

    const fallback = fallbackKey === "legacy" ? FALLBACK_LEGACY : FALLBACK_CURRENT;
    resolvedPluginDir = pluginDir;
    resolvedPluginId = fallback.id;
    resolvedPluginKind = fallback.kind;
    resolvedPluginSlot = fallback.slot;
    resolvedFilesRequired = fallback.required;
    resolvedFilesOptional = fallback.optional;
    resolvedNpmOmitDev = true;
    resolvedNpmBuild = false;
    resolvedNpmBuildMinOpenclawVersion = DEFAULT_NPM_BUILD_MIN_OPENCLAW_VERSION;
    resolvedNpmBuildScript = "build";
    resolvedNpmPruneAfterBuild = true;

    // If no compatVer from package.json, try main branch manifest
    if (!compatVer && PLUGIN_VERSION !== "main") {
      const mainRaw = `https://raw.githubusercontent.com/${REPO}/main`;
      const mainManifest = await tryFetch(`${mainRaw}/examples/openclaw-plugin/install-manifest.json`);
      if (mainManifest) {
        try {
          const m = JSON.parse(mainManifest);
          compatVer = m.compatibility?.minOpenclawVersion || "";
          if (compatVer) {
            info(tr(`Read minOpenclawVersion from main branch manifest: >=${compatVer}`, `从 main 分支 manifest 读取到最低版本: >=${compatVer}`));
          }
        } catch {}
      }
    }

    resolvedMinOpenclawVersion = compatVer || fallback.minOpenclawVersion || "2026.3.7";
    resolvedMinOpenvikingVersion = "";
  }

  // Set plugin destination
  PLUGIN_DEST = join(OPENCLAW_DIR, "extensions", resolvedPluginId);

  info(tr(`Plugin: ${resolvedPluginId} (${resolvedPluginKind})`, `插件: ${resolvedPluginId} (${resolvedPluginKind})`));
}

// Check OpenClaw version compatibility
async function checkOpenClawCompatibility() {
  if (process.env.SKIP_OPENCLAW === "1") {
    return;
  }

  const ocVersion = await detectOpenClawVersion();
  info(tr(`Detected OpenClaw version: ${ocVersion}`, `检测到 OpenClaw 版本: ${ocVersion}`));
  applyOpenClawBuildPolicy(ocVersion);

  // If no minimum version required, pass
  if (!resolvedMinOpenclawVersion) {
    return;
  }

  // If user explicitly requested an old version, pass
  if (isSemverLike(PLUGIN_VERSION) && !versionGte(PLUGIN_VERSION, "v0.2.8")) {
    return;
  }

  // Check compatibility
  if (!openClawPolicyVersionGte(ocVersion, resolvedMinOpenclawVersion)) {
    err(tr(
      `OpenClaw ${ocVersion} does not support this plugin (requires >= ${resolvedMinOpenclawVersion})`,
      `OpenClaw ${ocVersion} 不支持此插件(需要 >= ${resolvedMinOpenclawVersion})`
    ));
    console.log("");
    bold(tr("Please choose one of the following options:", "请选择以下方案之一:"));
    console.log("");
    console.log(`  ${tr("Option 1: Upgrade OpenClaw", "方案 1:升级 OpenClaw")}`);
    console.log(`    npm update -g openclaw --registry ${NPM_REGISTRY}`);
    console.log("");
    console.log(`  ${tr("Option 2: Install a legacy plugin release compatible with your current OpenClaw version", "方案 2:安装与当前 OpenClaw 版本兼容的旧版插件")}`);
    console.log(`    ${getLegacyInstallCommandHint()}`);
    console.log("");
    process.exit(1);
  }
}

function getOpenClawConfigPath() {
  return join(OPENCLAW_DIR, "openclaw.json");
}

function getOpenClawEnv() {
  if (OPENCLAW_DIR === DEFAULT_OPENCLAW_DIR) {
    return { ...process.env };
  }
  return { ...process.env, OPENCLAW_STATE_DIR: OPENCLAW_DIR };
}

async function readJsonFileIfExists(filePath) {
  if (!existsSync(filePath)) return null;
  const raw = await readFile(filePath, "utf8");
  return JSON.parse(raw);
}

function getInstallStatePathForPlugin(pluginId) {
  return join(OPENCLAW_DIR, "extensions", pluginId, ".ov-install-state.json");
}

async function printCurrentVersionInfo() {
  const state = await readJsonFileIfExists(getInstallStatePathForPlugin("openviking"));
  const pluginRequestedRef = state?.requestedRef || "";
  const pluginReleaseId = state?.releaseId || "";
  const pluginInstalledAt = state?.installedAt || "";

  console.log("");
  bold(tr("Installed versions", "当前已安装版本"));
  console.log("");
  console.log(`Target: ${OPENCLAW_DIR}`);
  console.log(`Plugin: ${pluginReleaseId || pluginRequestedRef || "not installed"}`);
  if (pluginRequestedRef && pluginReleaseId && pluginRequestedRef !== pluginReleaseId) {
    console.log(`Plugin requested ref: ${pluginRequestedRef}`);
  }
  console.log(tr("OpenViking server: not installed by this tool (use a remote URL in plugin config)", "OpenViking 服务端:本工具不安装;请在插件配置中填写远程服务地址"));
  if (pluginInstalledAt) {
    console.log(`Installed at: ${pluginInstalledAt}`);
  }
}

function getUpgradeAuditDir() {
  return join(OPENCLAW_DIR, ".openviking-upgrade-backup");
}

function getUpgradeAuditPath() {
  return join(getUpgradeAuditDir(), "last-upgrade.json");
}

function getOpenClawConfigBackupPath() {
  return join(getUpgradeAuditDir(), "openclaw.json.bak");
}

function getPluginVariantById(pluginId) {
  return PLUGIN_VARIANTS.find((variant) => variant.id === pluginId) || null;
}

function detectPluginPresence(config, variant) {
  const plugins = config?.plugins;
  const reasons = [];
  if (!plugins) {
    return { variant, present: false, reasons };
  }

  if (plugins.entries && Object.prototype.hasOwnProperty.call(plugins.entries, variant.id)) {
    reasons.push("entry");
  }
  if (plugins.slots?.[variant.slot] === variant.id) {
    reasons.push("slot");
  }
  if (Array.isArray(plugins.allow) && plugins.allow.includes(variant.id)) {
    reasons.push("allow");
  }
  if (
    Array.isArray(plugins.load?.paths)
    && plugins.load.paths.some((item) => typeof item === "string" && (item.includes(variant.id) || item.includes(variant.dir)))
  ) {
    reasons.push("loadPath");
  }
  if (existsSync(join(OPENCLAW_DIR, "extensions", variant.id))) {
    reasons.push("dir");
  }

  return { variant, present: reasons.length > 0, reasons };
}

async function detectInstalledPluginState() {
  const configPath = getOpenClawConfigPath();
  const config = await readJsonFileIfExists(configPath);
  const detections = [];
  for (const variant of PLUGIN_VARIANTS) {
    const detection = detectPluginPresence(config, variant);
    if (!detection.present) continue;
    detection.installState = await readJsonFileIfExists(getInstallStatePathForPlugin(variant.id));
    detections.push(detection);
  }

  let generation = "none";
  if (detections.length === 1) {
    generation = detections[0].variant.generation;
  } else if (detections.length > 1) {
    generation = "mixed";
  }

  return {
    config,
    configPath,
    detections,
    generation,
  };
}

function formatInstalledDetectionLabel(detection) {
  const requestedRef = detection.installState?.requestedRef;
  const releaseId = detection.installState?.releaseId;
  if (requestedRef) return `${detection.variant.id}@${requestedRef}`;
  if (releaseId) return `${detection.variant.id}#${releaseId}`;
  return `${detection.variant.id} (${detection.variant.generation}, exact version unknown)`;
}

function formatInstalledStateLabel(installedState) {
  if (!installedState?.detections?.length) {
    return "not-installed";
  }
  return installedState.detections.map(formatInstalledDetectionLabel).join(" + ");
}

function formatTargetVersionLabel() {
  const base = `${resolvedPluginId || "openviking"}@${PLUGIN_VERSION}`;
  if (resolvedPluginReleaseId && resolvedPluginReleaseId !== PLUGIN_VERSION) {
    return `${base} (${resolvedPluginReleaseId})`;
  }
  return base;
}

function extractRuntimeConfigFromPluginEntry(entryConfig) {
  if (!entryConfig || typeof entryConfig !== "object") return null;

  const runtime = {};
  if (typeof entryConfig.baseUrl === "string" && entryConfig.baseUrl.trim()) {
    runtime.baseUrl = entryConfig.baseUrl.trim();
  }
  if (typeof entryConfig.apiKey === "string" && entryConfig.apiKey.trim()) {
    runtime.apiKey = entryConfig.apiKey;
  }
  const role = normalizePeerRole(entryConfig.peer_role);
  if (role) {
    runtime.peer_role = role;
  }
  const prefix = entryConfig.peer_prefix;
  if (typeof prefix === "string" && prefix.trim()) {
    runtime.peer_prefix = prefix.trim();
  }
  if (typeof entryConfig.accountId === "string" && entryConfig.accountId.trim()) {
    runtime.accountId = entryConfig.accountId.trim();
  }
  if (typeof entryConfig.userId === "string" && entryConfig.userId.trim()) {
    runtime.userId = entryConfig.userId.trim();
  }
  return runtime;
}

async function backupOpenClawConfig(configPath) {
  await mkdir(getUpgradeAuditDir(), { recursive: true });
  const backupPath = getOpenClawConfigBackupPath();
  const configText = await readFile(configPath, "utf8");
  await writeFile(backupPath, configText, "utf8");
  return backupPath;
}

async function writeUpgradeAuditFile(data) {
  await mkdir(getUpgradeAuditDir(), { recursive: true });
  await writeFile(getUpgradeAuditPath(), `${JSON.stringify(data, null, 2)}\n`, "utf8");
}

async function writeInstallStateFile({ operation, fromVersion, configBackupPath, pluginBackups }) {
  const installStatePath = getInstallStatePathForPlugin(resolvedPluginId || "openviking");
  const state = {
    pluginId: resolvedPluginId || "openviking",
    generation: getPluginVariantById(resolvedPluginId || "openviking")?.generation || "unknown",
    requestedRef: PLUGIN_VERSION,
    releaseId: resolvedPluginReleaseId || "",
    operation,
    fromVersion: fromVersion || "",
    configBackupPath: configBackupPath || "",
    pluginBackups: pluginBackups || [],
    installedAt: new Date().toISOString(),
    repo: REPO,
  };
  await writeFile(installStatePath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
}

async function moveDirWithFallback(sourceDir, destDir) {
  try {
    await rename(sourceDir, destDir);
  } catch {
    await cp(sourceDir, destDir, { recursive: true, force: true });
    await rm(sourceDir, { recursive: true, force: true });
  }
}

async function rollbackLastUpgradeOperation() {
  const auditPath = getUpgradeAuditPath();
  const audit = await readJsonFileIfExists(auditPath);
  if (!audit) {
    err(
      tr(
        `No rollback audit file found at ${auditPath}.`,
        `未找到回滚审计文件: ${auditPath}`,
      ),
    );
    process.exit(1);
  }

  if (audit.rolledBackAt) {
    warn(
      tr(
        `The last recorded upgrade was already rolled back at ${audit.rolledBackAt}.`,
        `最近一次升级已在 ${audit.rolledBackAt} 回滚。`,
      ),
    );
  }

  const configBackupPath = audit.configBackupPath || getOpenClawConfigBackupPath();
  if (!existsSync(configBackupPath)) {
    err(
      tr(
        `Rollback config backup is missing: ${configBackupPath}`,
        `回滚配置备份缺失: ${configBackupPath}`,
      ),
    );
    process.exit(1);
  }

  const pluginBackups = Array.isArray(audit.pluginBackups) ? audit.pluginBackups : [];
  if (pluginBackups.length === 0) {
    err(tr("Rollback audit file contains no plugin backups.", "回滚审计文件中没有插件备份信息。"));
    process.exit(1);
  }
  for (const pluginBackup of pluginBackups) {
    if (!pluginBackup?.pluginId || !pluginBackup?.backupDir || !existsSync(pluginBackup.backupDir)) {
      err(
        tr(
          `Rollback plugin backup is missing: ${pluginBackup?.backupDir || "<unknown>"}`,
          `回滚插件备份缺失: ${pluginBackup?.backupDir || "<unknown>"}`,
        ),
      );
      process.exit(1);
    }
  }

  info(tr(`Rolling back last upgrade: ${audit.fromVersion || "unknown"} <- ${audit.toVersion || "unknown"}`, `开始回滚最近一次升级: ${audit.fromVersion || "unknown"} <- ${audit.toVersion || "unknown"}`));
  await stopOpenClawGatewayForUpgrade();

  const configText = await readFile(configBackupPath, "utf8");
  await writeFile(getOpenClawConfigPath(), configText, "utf8");
  info(tr(`Restored openclaw.json from backup: ${configBackupPath}`, `已从备份恢复 openclaw.json: ${configBackupPath}`));

  const extensionsDir = join(OPENCLAW_DIR, "extensions");
  await mkdir(extensionsDir, { recursive: true });
  for (const variant of PLUGIN_VARIANTS) {
    const liveDir = join(extensionsDir, variant.id);
    if (existsSync(liveDir)) {
      await rm(liveDir, { recursive: true, force: true });
    }
  }

  for (const pluginBackup of pluginBackups) {
    if (!pluginBackup?.pluginId || !pluginBackup?.backupDir) continue;
    if (!existsSync(pluginBackup.backupDir)) {
      err(
        tr(
          `Rollback plugin backup is missing: ${pluginBackup.backupDir}`,
          `回滚插件备份缺失: ${pluginBackup.backupDir}`,
        ),
      );
      process.exit(1);
    }
    const destDir = join(extensionsDir, pluginBackup.pluginId);
    await moveDirWithFallback(pluginBackup.backupDir, destDir);
    info(tr(`Restored plugin directory: ${destDir}`, `已恢复插件目录: ${destDir}`));
  }

  audit.rolledBackAt = new Date().toISOString();
  audit.rollbackConfigPath = configBackupPath;
  await writeUpgradeAuditFile(audit);

  console.log("");
  bold(tr("Rollback complete!", "回滚完成!"));
  console.log("");
  info(tr(`Rollback audit file: ${auditPath}`, `回滚审计文件: ${auditPath}`));
  info(tr("Run `openclaw gateway` and `openclaw status` to verify the restored plugin state.", "请运行 `openclaw gateway` 和 `openclaw status` 验证恢复后的插件状态。"));
}

function prepareUpgradeRuntimeConfig(installedState) {
  const plugins = installedState.config?.plugins ?? {};
  const candidateOrder = installedState.detections
    .map((item) => item.variant)
    .sort((left, right) => (right.generation === "current" ? 1 : 0) - (left.generation === "current" ? 1 : 0));

  let runtime = null;
  for (const variant of candidateOrder) {
    const entryConfig = extractRuntimeConfigFromPluginEntry(plugins.entries?.[variant.id]?.config);
    if (entryConfig) {
      runtime = entryConfig;
      break;
    }
  }

  if (!runtime) {
    runtime = {};
  }

  delete runtime.mode;
  runtime.baseUrl = runtime.baseUrl || remoteBaseUrl;
  return runtime;
}

function removePluginConfig(config, variant) {
  const plugins = config?.plugins;
  if (!plugins) return false;

  let changed = false;

  if (Array.isArray(plugins.allow)) {
    const nextAllow = plugins.allow.filter((item) => item !== variant.id);
    changed = changed || nextAllow.length !== plugins.allow.length;
    plugins.allow = nextAllow;
  }

  if (Array.isArray(plugins.load?.paths)) {
    const nextPaths = plugins.load.paths.filter(
      (item) => typeof item !== "string" || (!item.includes(variant.id) && !item.includes(variant.dir)),
    );
    changed = changed || nextPaths.length !== plugins.load.paths.length;
    plugins.load.paths = nextPaths;
  }

  if (plugins.entries && Object.prototype.hasOwnProperty.call(plugins.entries, variant.id)) {
    delete plugins.entries[variant.id];
    changed = true;
  }

  if (plugins.slots?.[variant.slot] === variant.id) {
    plugins.slots[variant.slot] = variant.slotFallback;
    changed = true;
  }

  return changed;
}

async function prunePreviousUpgradeBackups(disabledDir, variant, keepDir) {
  if (!existsSync(disabledDir)) return;

  const prefix = `${variant.id}-upgrade-backup-`;
  const keepName = keepDir ? keepDir.split(/[\\/]/).pop() : "";
  const entries = readdirSync(disabledDir, { withFileTypes: true });
  for (const entry of entries) {
    if (!entry.isDirectory()) continue;
    if (!entry.name.startsWith(prefix)) continue;
    if (keepName && entry.name === keepName) continue;
    await rm(join(disabledDir, entry.name), { recursive: true, force: true });
  }
}

async function backupPluginDirectory(variant) {
  const pluginDir = join(OPENCLAW_DIR, "extensions", variant.id);
  if (!existsSync(pluginDir)) return null;

  const disabledDir = join(OPENCLAW_DIR, "disabled-extensions");
  const backupDir = join(disabledDir, `${variant.id}-upgrade-backup-${Date.now()}`);
  await mkdir(disabledDir, { recursive: true });
  try {
    await rename(pluginDir, backupDir);
  } catch {
    await cp(pluginDir, backupDir, { recursive: true, force: true });
    await rm(pluginDir, { recursive: true, force: true });
  }
  info(tr(`Backed up plugin directory: ${backupDir}`, `已备份插件目录: ${backupDir}`));
  await prunePreviousUpgradeBackups(disabledDir, variant, backupDir);
  return backupDir;
}

async function stopOpenClawGatewayForUpgrade() {
  const result = await runCapture("openclaw", ["gateway", "stop"], {
    env: getOpenClawEnv(),
    shell: IS_WIN,
  });
  if (result.code === 0) {
    info(tr("Stopped OpenClaw gateway before plugin upgrade", "升级插件前已停止 OpenClaw gateway"));
  } else {
    warn(tr("OpenClaw gateway may not be running; continuing", "OpenClaw gateway 可能未在运行,继续执行"));
  }
}

function shouldClaimTargetSlot(installedState) {
  const currentOwner = installedState.config?.plugins?.slots?.[resolvedPluginSlot];
  if (!currentOwner || currentOwner === "none" || currentOwner === "legacy" || currentOwner === resolvedPluginId) {
    return true;
  }
  const currentOwnerVariant = getPluginVariantById(currentOwner);
  if (currentOwnerVariant && installedState.detections.some((item) => item.variant.id === currentOwnerVariant.id)) {
    return true;
  }
  return false;
}

async function cleanupInstalledPluginConfig(installedState) {
  if (!installedState.config || !installedState.config.plugins) {
    warn(tr("openclaw.json has no plugins section; skipped targeted plugin cleanup", "openclaw.json 中没有 plugins 配置,已跳过定向插件清理"));
    return;
  }

  const nextConfig = structuredClone(installedState.config);
  let changed = false;
  for (const detection of installedState.detections) {
    changed = removePluginConfig(nextConfig, detection.variant) || changed;
  }

  if (!changed) {
    info(tr("No OpenViking plugin config changes were required", "无需修改 OpenViking 插件配置"));
    return;
  }

  await writeFile(installedState.configPath, `${JSON.stringify(nextConfig, null, 2)}\n`, "utf8");
  info(tr("Cleaned existing OpenViking plugin config only", "已仅清理 OpenViking 自身插件配置"));
}

async function prepareStrongPluginUpgrade() {
  const installedState = await detectInstalledPluginState();
  if (installedState.generation === "none") {
    err(
      tr(
        "Plugin upgrade mode requires an existing OpenViking plugin entry in openclaw.json.",
        "插件升级模式要求 openclaw.json 中已经存在 OpenViking 插件记录。",
      ),
    );
    process.exit(1);
  }

  installedUpgradeState = installedState;
  upgradeRuntimeConfig = prepareUpgradeRuntimeConfig(installedState);
  const fromVersion = formatInstalledStateLabel(installedState);
  const toVersion = formatTargetVersionLabel();
  info(
    tr(
      `Detected installed OpenViking plugin state: ${installedState.generation}`,
      `检测到已安装 OpenViking 插件状态: ${installedState.generation}`,
    ),
  );
  remoteBaseUrl = upgradeRuntimeConfig.baseUrl || remoteBaseUrl;
  remoteApiKey = upgradeRuntimeConfig.apiKey || "";
  remotePeerRole = upgradeRuntimeConfig.peer_role || remotePeerRole || "none";
  remotePeerPrefix = upgradeRuntimeConfig.peer_prefix || "";
  remoteAccountId = upgradeRuntimeConfig.accountId || "";
  remoteUserId = upgradeRuntimeConfig.userId || "";
  info(tr(`Upgrade runtime mode: ${selectedMode} (remote OpenViking server)`, `升级运行模式: ${selectedMode}(远程 OpenViking 服务)`));

  info(tr(`Upgrade path: ${fromVersion} -> ${toVersion}`, `升级路径: ${fromVersion} -> ${toVersion}`));

  await stopOpenClawGatewayForUpgrade();
  const configBackupPath = await backupOpenClawConfig(installedState.configPath);
  info(tr(`Backed up openclaw.json: ${configBackupPath}`, `已备份 openclaw.json: ${configBackupPath}`));
  const pluginBackups = [];
  for (const detection of installedState.detections) {
    const backupDir = await backupPluginDirectory(detection.variant);
    if (backupDir) {
      pluginBackups.push({ pluginId: detection.variant.id, backupDir });
    }
  }
  upgradeAudit = {
    operation: "upgrade",
    createdAt: new Date().toISOString(),
    fromVersion,
    toVersion,
    configBackupPath,
    pluginBackups,
    runtimeMode: selectedMode,
  };
  await writeUpgradeAuditFile(upgradeAudit);
  await cleanupInstalledPluginConfig(installedState);

  info(
    tr(
      "Upgrade will preserve existing plugin server connection settings where possible and re-apply minimal remote plugin config.",
      "升级将尽可能保留已有的插件服务端连接信息,并只回填最少的远程插件配置。",
    ),
  );
  info(tr(`Upgrade audit file: ${getUpgradeAuditPath()}`, `升级审计文件: ${getUpgradeAuditPath()}`));
}

async function downloadPluginFile(destDir, fileName, url, required, index, total) {
  const maxRetries = 3;
  const destPath = join(destDir, fileName);

  process.stdout.write(`  [${index}/${total}] ${fileName} `);

  let lastStatus = 0;
  let saw404 = false;

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url);
      lastStatus = response.status;
      if (response.ok) {
        const buffer = Buffer.from(await response.arrayBuffer());
        if (buffer.length === 0) {
          lastStatus = 0;
        } else {
          await mkdir(dirname(destPath), { recursive: true });
          await writeFile(destPath, buffer);
          console.log(" OK");
          return;
        }
      } else if (!required && response.status === 404) {
        saw404 = true;
        break;
      }
    } catch {
      lastStatus = 0;
    }

    if (attempt < maxRetries) {
      await new Promise((resolve) => setTimeout(resolve, 2000));
    }
  }

  if (saw404 || lastStatus === 404) {
    if (fileName === ".gitignore") {
      await mkdir(dirname(destPath), { recursive: true });
      await writeFile(destPath, "node_modules/\n", "utf8");
      console.log(" OK");
      return;
    }
    console.log(tr(" skip", " 跳过"));
    return;
  }

  if (!required) {
    console.log("");
    err(
      tr(
        `Optional file failed after ${maxRetries} retries (HTTP ${lastStatus || "network"}): ${url}`,
        `可选文件已重试 ${maxRetries} 次仍失败(HTTP ${lastStatus || "网络错误"}): ${url}`,
      ),
    );
    process.exit(1);
  }

  console.log("");
  err(tr(`Download failed after ${maxRetries} retries: ${url}`, `下载失败(已重试 ${maxRetries} 次): ${url}`));
  process.exit(1);
}

function githubContentsUrl(pluginDir, fileName) {
  const path = `examples/${pluginDir}/${fileName}`.replace(/\/+$/u, "");
  const encodedPath = path.split("/").map((part) => encodeURIComponent(part)).join("/");
  return `https://api.github.com/repos/${REPO}/contents/${encodedPath}?ref=${encodeURIComponent(PLUGIN_VERSION)}`;
}

async function fetchGitHubDirectoryEntries(pluginDir, dirName, required) {
  const maxRetries = 3;
  const url = githubContentsUrl(pluginDir, dirName);
  let lastStatus = 0;

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, { headers: { "User-Agent": "openviking-setup-helper" } });
      lastStatus = response.status;
      if (response.ok) {
        const json = await response.json();
        if (Array.isArray(json)) return json;
        lastStatus = 0;
      } else if (!required && response.status === 404) {
        return null;
      }
    } catch {
      lastStatus = 0;
    }

    if (attempt < maxRetries) {
      await new Promise((resolve) => setTimeout(resolve, 2000));
    }
  }

  if (!required) {
    err(tr(
      `Optional directory failed after ${maxRetries} retries (HTTP ${lastStatus || "network"}): ${url}`,
      `可选目录已重试 ${maxRetries} 次仍失败(HTTP ${lastStatus || "网络错误"}): ${url}`,
    ));
    process.exit(1);
  }

  err(tr(
    `Directory download failed after ${maxRetries} retries (HTTP ${lastStatus || "network"}): ${url}`,
    `目录下载失败(已重试 ${maxRetries} 次,HTTP ${lastStatus || "网络错误"}): ${url}`,
  ));
  process.exit(1);
}

async function collectGitHubDirectoryFiles(pluginDir, dirName, required) {
  const entries = await fetchGitHubDirectoryEntries(pluginDir, dirName, required);
  if (!entries) return [];

  const prefix = `examples/${pluginDir}/`;
  const files = [];
  for (const entry of entries) {
    if (entry?.type === "file" && entry.download_url) {
      const relativePath = String(entry.path || "").startsWith(prefix)
        ? String(entry.path).slice(prefix.length)
        : `${dirName}${entry.name}`;
      files.push({ fileName: relativePath, url: entry.download_url });
      continue;
    }

    if (entry?.type === "dir" && entry.path) {
      const relativeDir = String(entry.path).startsWith(prefix)
        ? String(entry.path).slice(prefix.length)
        : `${dirName}${entry.name}/`;
      files.push(...await collectGitHubDirectoryFiles(pluginDir, `${relativeDir}/`, required));
    }
  }

  return files;
}

async function downloadPluginDirectory(destDir, pluginDir, dirName, required, index, total) {
  process.stdout.write(`  [${index}/${total}] ${dirName} `);
  const files = await collectGitHubDirectoryFiles(pluginDir, dirName, required);
  if (files.length === 0) {
    console.log(required ? " empty" : tr(" skip", " 跳过"));
    if (!required) return;
    err(tr(`Required directory is empty or unavailable: ${dirName}`, `必需目录为空或不可用: ${dirName}`));
    process.exit(1);
  }
  console.log(` OK (${files.length} files)`);

  let fileIndex = 0;
  for (const file of files) {
    fileIndex++;
    await downloadPluginFile(destDir, file.fileName, file.url, required, `${index}.${fileIndex}`, total);
  }
}

function runtimeOutputCandidatesForEntry(entry) {
  const normalized = String(entry || "").replace(/\\/g, "/").replace(/^\.\//, "");
  if (!normalized.endsWith(".ts")) {
    return [];
  }
  const withoutExt = normalized.slice(0, -3);
  return [
    `dist/${withoutExt}.js`,
    `dist/${withoutExt}.mjs`,
    `dist/${withoutExt}.cjs`,
    `${withoutExt}.js`,
    `${withoutExt}.mjs`,
    `${withoutExt}.cjs`,
  ];
}

async function assertBuiltRuntimeOutputs(destDir) {
  let pkg = null;
  try {
    pkg = JSON.parse(await readFile(join(destDir, "package.json"), "utf8"));
  } catch {
    return;
  }

  const entries = [];
  const extensions = pkg?.openclaw?.extensions;
  if (Array.isArray(extensions)) {
    for (const entry of extensions) {
      if (typeof entry === "string") entries.push(entry);
    }
  }
  if (typeof pkg?.openclaw?.setupEntry === "string") {
    entries.push(pkg.openclaw.setupEntry);
  }

  const missing = [];
  for (const entry of entries) {
    const candidates = runtimeOutputCandidatesForEntry(entry);
    if (candidates.length === 0) continue;
    const found = candidates.some((candidate) => existsSync(join(destDir, ...candidate.split("/"))));
    if (!found) {
      missing.push(`${entry} (expected one of: ${candidates.join(", ")})`);
    }
  }

  if (missing.length === 0) {
    return;
  }

  err(tr(
    `Plugin build did not create required runtime output:\n  - ${missing.join("\n  - ")}`,
    `插件构建未生成必需的运行时产物:\n  - ${missing.join("\n  - ")}`,
  ));
  process.exit(1);
}

async function installPluginNpmDependencies(destDir) {
  if (!resolvedNpmBuild) {
    info(tr("Installing plugin npm dependencies...", "正在安装插件 npm 依赖..."));
    const npmArgs = resolvedNpmOmitDev
      ? ["install", "--omit=dev", "--no-audit", "--no-fund", "--registry", NPM_REGISTRY]
      : ["install", "--no-audit", "--no-fund", "--registry", NPM_REGISTRY];
    await run("npm", npmArgs, { cwd: destDir, silent: false });
    return;
  }

  info(tr(
    "Installing plugin npm dependencies for source build...",
    "正在安装插件源码构建所需的 npm 依赖...",
  ));
  await run("npm", [
    "install",
    "--include=dev",
    "--no-audit",
    "--no-fund",
    "--registry",
    NPM_REGISTRY,
  ], { cwd: destDir, silent: false });

  info(tr(
    `Building plugin runtime output with npm run ${resolvedNpmBuildScript}...`,
    `正在执行 npm run ${resolvedNpmBuildScript} 构建插件运行时产物...`,
  ));
  await run("npm", ["run", resolvedNpmBuildScript], { cwd: destDir, silent: false });
  await assertBuiltRuntimeOutputs(destDir);

  if (resolvedNpmOmitDev && resolvedNpmPruneAfterBuild) {
    info(tr("Pruning plugin dev dependencies...", "正在裁剪插件开发依赖..."));
    await run("npm", [
      "prune",
      "--omit=dev",
      "--no-audit",
      "--no-fund",
    ], { cwd: destDir, silent: false });
  }
}

async function copyNpmPackageToDest(destDir) {
  const packageDir = await ensureNpmPackageExtracted();
  await mkdir(destDir, { recursive: true });
  const entries = readdirSync(packageDir, { withFileTypes: true });
  for (const entry of entries) {
    await cp(join(packageDir, entry.name), join(destDir, entry.name), { recursive: true, force: true });
  }
}

async function cleanupNpmPackageTemp() {
  if (!npmPackageTempDir) return;
  await rm(npmPackageTempDir, { recursive: true, force: true });
  npmPackageTempDir = "";
  npmPackageExtractDir = "";
}

async function downloadPlugin(destDir) {
  if (pluginSource === "npm") {
    await mkdir(destDir, { recursive: true });
    info(tr(
      `Installing plugin from npm package ${npmPackageSpec()}...`,
      `Installing plugin from npm package ${npmPackageSpec()}...`,
    ));
    await copyNpmPackageToDest(destDir);
    await installPluginNpmDependencies(destDir);
    info(tr(`Plugin deployed: ${PLUGIN_DEST}`, `Plugin deployed: ${PLUGIN_DEST}`));
    return;
  }

  const ghRaw = `https://raw.githubusercontent.com/${REPO}/${PLUGIN_VERSION}`;
  const pluginDir = resolvedPluginDir;
  const total = resolvedFilesRequired.length + resolvedFilesOptional.length;

  await mkdir(destDir, { recursive: true });

  info(tr(`Downloading plugin from ${REPO}@${PLUGIN_VERSION} (${total} files)...`, `正在从 ${REPO}@${PLUGIN_VERSION} 下载插件(共 ${total} 个文件)...`));

  let i = 0;
  // Download required files
  for (const name of resolvedFilesRequired) {
    if (!name) continue;
    i++;
    if (name.endsWith("/")) {
      await downloadPluginDirectory(destDir, pluginDir, name, true, i, total);
      continue;
    }
    const url = `${ghRaw}/examples/${pluginDir}/${name}`;
    await downloadPluginFile(destDir, name, url, true, i, total);
  }

  // Download optional files
  for (const name of resolvedFilesOptional) {
    if (!name) continue;
    i++;
    if (name.endsWith("/")) {
      await downloadPluginDirectory(destDir, pluginDir, name, false, i, total);
      continue;
    }
    const url = `${ghRaw}/examples/${pluginDir}/${name}`;
    await downloadPluginFile(destDir, name, url, false, i, total);
  }

  await installPluginNpmDependencies(destDir);
  info(tr(`Plugin deployed: ${PLUGIN_DEST}`, `插件部署完成: ${PLUGIN_DEST}`));
}

async function createPluginStagingDir() {
  const pluginId = resolvedPluginId || "openviking";
  const extensionsDir = join(OPENCLAW_DIR, "extensions");
  await mkdir(extensionsDir, { recursive: true });
  const stagingPrefix = `.${pluginId}.staging-`;
  try {
    const entries = readdirSync(extensionsDir, { withFileTypes: true });
    for (const entry of entries) {
      if (entry.isDirectory() && entry.name.startsWith(stagingPrefix)) {
        await rm(join(extensionsDir, entry.name), { recursive: true, force: true });
      }
    }
  } catch {}
  const stagingDir = join(extensionsDir, `${stagingPrefix}${process.pid}-${Date.now()}`);
  await mkdir(stagingDir, { recursive: true });
  return stagingDir;
}

async function finalizePluginDeployment(stagingDir) {
  await rm(PLUGIN_DEST, { recursive: true, force: true });
  try {
    await rename(stagingDir, PLUGIN_DEST);
  } catch {
    await cp(stagingDir, PLUGIN_DEST, { recursive: true, force: true });
    await rm(stagingDir, { recursive: true, force: true });
  }
  return info(tr(`Plugin deployed: ${PLUGIN_DEST}`, `插件部署完成: ${PLUGIN_DEST}`));
}

async function deployPluginFromRemote() {
  const stagingDir = await createPluginStagingDir();
  try {
    await downloadPlugin(stagingDir);
    await finalizePluginDeployment(stagingDir);
  } catch (error) {
    await rm(stagingDir, { recursive: true, force: true });
    throw error;
  } finally {
    await cleanupNpmPackageTemp();
  }
}

/** Same as INSTALL*.md manual cleanup: stale entries block `plugins.slots.*` validation after reinstall. */
function resolvedPluginSlotFallback() {
  if (resolvedPluginId === "memory-openviking") return "none";
  if (resolvedPluginId === "openviking") return "legacy";
  return "none";
}

async function scrubStaleOpenClawPluginRegistration() {
  const configPath = getOpenClawConfigPath();
  if (!existsSync(configPath)) return;
  const pluginId = resolvedPluginId;
  const slot = resolvedPluginSlot;
  const slotFallback = resolvedPluginSlotFallback();
  let raw;
  try {
    raw = await readFile(configPath, "utf8");
  } catch {
    return;
  }
  let cfg;
  try {
    cfg = JSON.parse(raw);
  } catch {
    return;
  }
  if (!cfg.plugins) return;
  const p = cfg.plugins;
  let changed = false;
  if (p.entries && Object.prototype.hasOwnProperty.call(p.entries, pluginId)) {
    delete p.entries[pluginId];
    changed = true;
  }
  if (Array.isArray(p.allow)) {
    const next = p.allow.filter((id) => id !== pluginId);
    if (next.length !== p.allow.length) {
      p.allow = next;
      changed = true;
    }
  }
  if (p.load && Array.isArray(p.load.paths)) {
    const norm = (s) => String(s).replace(/\\/g, "/");
    const extNeedle = `/extensions/${pluginId}`;
    const next = p.load.paths.filter((path) => {
      if (typeof path !== "string") return true;
      return !norm(path).includes(extNeedle);
    });
    if (next.length !== p.load.paths.length) {
      p.load.paths = next;
      changed = true;
    }
  }
  if (p.slots && p.slots[slot] === pluginId) {
    p.slots[slot] = slotFallback;
    changed = true;
  }
  if (!changed) return;
  const out = JSON.stringify(cfg, null, 2) + "\n";
  const tmp = `${configPath}.ov-install-tmp.${process.pid}`;
  await writeFile(tmp, out, "utf8");
  await rename(tmp, configPath);
}

async function cleanupConflictingPluginVariants() {
  const configPath = getOpenClawConfigPath();
  if (!existsSync(configPath)) return;
  let cfg;
  try {
    cfg = JSON.parse(await readFile(configPath, "utf8"));
  } catch { return; }
  if (!cfg.plugins) return;
  const p = cfg.plugins;
  let changed = false;
  for (const variant of PLUGIN_VARIANTS) {
    if (variant.id === resolvedPluginId) continue;
    if (p.entries && Object.prototype.hasOwnProperty.call(p.entries, variant.id)) {
      info(tr(`Removing conflicting plugin variant: ${variant.id}`, `正在移除冲突的插件变体: ${variant.id}`));
      delete p.entries[variant.id];
      changed = true;
    }
    if (Array.isArray(p.allow)) {
      const next = p.allow.filter((id) => id !== variant.id);
      if (next.length !== p.allow.length) {
        p.allow = next;
        changed = true;
      }
    }
    if (p.installs && Object.prototype.hasOwnProperty.call(p.installs, variant.id)) {
      delete p.installs[variant.id];
      changed = true;
    }
    if (p.slots && p.slots[variant.slot] === variant.id) {
      p.slots[variant.slot] = variant.slotFallback || "none";
      changed = true;
    }
    if (p.load && Array.isArray(p.load.paths)) {
      const norm = (s) => String(s).replace(/\\/g, "/");
      const extNeedle = `/extensions/${variant.id}`;
      const next = p.load.paths.filter((path) => {
        if (typeof path !== "string") return true;
        return !norm(path).includes(extNeedle);
      });
      if (next.length !== p.load.paths.length) {
        p.load.paths = next;
        changed = true;
      }
    }
    const variantDir = join(OPENCLAW_DIR, "extensions", variant.id);
    if (existsSync(variantDir)) {
      info(tr(`Removing conflicting plugin directory: ${variantDir}`, `正在移除冲突的插件目录: ${variantDir}`));
      await rm(variantDir, { recursive: true, force: true });
    }
  }
  if (!changed) return;
  const out = JSON.stringify(cfg, null, 2) + "\n";
  const tmp = `${configPath}.ov-install-tmp.${process.pid}`;
  await writeFile(tmp, out, "utf8");
  await rename(tmp, configPath);
  info(tr("Conflicting plugin variants cleaned up", "冲突的插件变体已清理"));
}

function normalizeOpenClawLoadPath(filePath) {
  return String(filePath || "")
    .replace(/\\/g, "/")
    .replace(/\/+$/g, "");
}

async function ensureOpenClawPluginLoadPath() {
  const configPath = getOpenClawConfigPath();
  let cfg = {};
  if (existsSync(configPath)) {
    try {
      cfg = JSON.parse(await readFile(configPath, "utf8"));
    } catch {
      return;
    }
  }

  const pluginPath = PLUGIN_DEST;
  const normalizedPluginPath = normalizeOpenClawLoadPath(pluginPath);
  const plugins = cfg.plugins && typeof cfg.plugins === "object" && !Array.isArray(cfg.plugins)
    ? cfg.plugins
    : {};
  const load = plugins.load && typeof plugins.load === "object" && !Array.isArray(plugins.load)
    ? plugins.load
    : {};
  const paths = Array.isArray(load.paths) ? load.paths : [];
  if (paths.some((item) => normalizeOpenClawLoadPath(item) === normalizedPluginPath)) {
    return;
  }

  const next = {
    ...cfg,
    plugins: {
      ...plugins,
      load: {
        ...load,
        paths: [...paths, pluginPath],
      },
    },
  };
  await mkdir(dirname(configPath), { recursive: true });
  const tmp = `${configPath}.ov-install-tmp.${process.pid}`;
  await writeFile(tmp, `${JSON.stringify(next, null, 2)}\n`, "utf8");
  await rename(tmp, configPath);
  info(tr(`Added OpenClaw plugin load path: ${pluginPath}`, `已添加 OpenClaw 插件加载路径: ${pluginPath}`));
}

async function configureOpenClawPlugin({
  preserveExistingConfig = false,
  runtimeConfig = null,
  claimSlot = true,
} = {}) {
  info(tr("Configuring OpenClaw plugin...", "正在配置 OpenClaw 插件..."));

  const pluginId = resolvedPluginId;
  const pluginSlot = resolvedPluginSlot;

  const ocEnv = getOpenClawEnv();
  const needWorkdirFlag = OPENCLAW_DIR !== DEFAULT_OPENCLAW_DIR;

  const oc = async (args) => {
    const result = await runCapture("openclaw", args, { env: ocEnv, shell: IS_WIN });
    if (result.code !== 0) {
      const detail = result.err || result.out;
      throw new Error(`openclaw ${args.join(" ")} failed (exit code ${result.code})${detail ? `: ${detail}` : ""}`);
    }
    return result;
  };

  // Direct file manipulation for config (reliable across all OpenClaw versions and --workdir scenarios).
  // OpenClaw CLI's --workdir / OPENCLAW_STATE_DIR support is inconsistent, so we read/write openclaw.json directly.
  const configPath = getOpenClawConfigPath();
  const readCfg = async () => {
    if (!existsSync(configPath)) return {};
    try { return JSON.parse(await readFile(configPath, "utf8")); } catch { return {}; }
  };
  const writeCfg = async (cfg) => {
    const out = JSON.stringify(cfg, null, 2) + "\n";
    const tmp = `${configPath}.ov-install-tmp.${process.pid}`;
    await writeFile(tmp, out, "utf8");
    await rename(tmp, configPath);
  };
  const ensurePluginRegistered = async (cfg) => {
    if (!cfg.plugins) cfg.plugins = {};
    const p = cfg.plugins;
    if (!p.entries) p.entries = {};
    if (!p.entries[pluginId]) p.entries[pluginId] = {};
    p.entries[pluginId].enabled = true;
    if (!p.entries[pluginId].config) p.entries[pluginId].config = {};
    if (!Array.isArray(p.allow)) p.allow = [];
    if (!p.allow.includes(pluginId)) p.allow.push(pluginId);
    return cfg;
  };

  await cleanupConflictingPluginVariants();

  if (!preserveExistingConfig) {
    await scrubStaleOpenClawPluginRegistration();
  }

  await ensureOpenClawPluginLoadPath();

  // Enable plugin: try CLI first (default path), fall back to direct file for --workdir
  if (!needWorkdirFlag) {
    try {
      await oc(["plugins", "enable", pluginId]);
    } catch (_e) {
      info(tr("plugins enable via CLI failed, registering directly", "CLI plugins enable 失败,直接注册"));
      const cfg = await readCfg();
      await ensurePluginRegistered(cfg);
      await writeCfg(cfg);
    }
  } else {
    info(tr("Using direct config write for non-default workdir", "非默认目录,使用直接配置写入"));
    const cfg = await readCfg();
    await ensurePluginRegistered(cfg);
    await writeCfg(cfg);
  }

  if (preserveExistingConfig) {
    if (claimSlot) {
      const cfg = await readCfg();
      if (!cfg.plugins) cfg.plugins = {};
      if (!cfg.plugins.slots) cfg.plugins.slots = {};
      cfg.plugins.slots[pluginSlot] = pluginId;
      await writeCfg(cfg);
    }
    info(
      tr(
        `Preserved existing plugin runtime config for ${pluginId}`,
        `已保留 ${pluginId} 的现有插件运行时配置`,
      ),
    );
    return { runtimeConfigOk: true };
  }

  const writeConfigDirect = async (pluginConfig, slotValue) => {
    const cfg = await readCfg();
    await ensurePluginRegistered(cfg);
    Object.assign(cfg.plugins.entries[pluginId].config, pluginConfig);
    if (slotValue) {
      if (!cfg.plugins.slots) cfg.plugins.slots = {};
      cfg.plugins.slots[pluginSlot] = slotValue;
    }
    await writeCfg(cfg);
  };

  // Legacy (memory) plugins: direct JSON write
  if (resolvedPluginKind === "memory") {
    const effectiveRuntimeConfig = runtimeConfig || {
      baseUrl: remoteBaseUrl,
      apiKey: remoteApiKey,
      peer_role: remotePeerRole,
      peer_prefix: remotePeerPrefix,
    };

    let allowedPropsLegacy = null;
    try {
      const manifestPath = join(PLUGIN_DEST, "openclaw.plugin.json");
      if (existsSync(manifestPath)) {
        const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
        const schema = manifest?.configSchema;
        if (schema?.properties && typeof schema.properties === "object") {
          allowedPropsLegacy = new Set(Object.keys(schema.properties));
        }
      }
    } catch { /* ignore parse errors */ }

    const peerVal = effectiveRuntimeConfig.peer_prefix || "";
    const candidates = {
      mode: "remote",
      baseUrl: effectiveRuntimeConfig.baseUrl || remoteBaseUrl,
      targetUri: "viking://~/memories",
      autoRecall: true,
      autoCapture: true,
      apiKey: effectiveRuntimeConfig.apiKey || undefined,
      peer_prefix: peerVal || undefined,
    };

    const pluginConfig = {};
    for (const [key, val] of Object.entries(candidates)) {
      if (val === undefined) continue;
      if (allowedPropsLegacy && !allowedPropsLegacy.has(key)) continue;
      pluginConfig[key] = val;
    }
    if (!pluginConfig.baseUrl) pluginConfig.baseUrl = effectiveRuntimeConfig.baseUrl || remoteBaseUrl;

    await writeConfigDirect(pluginConfig, claimSlot ? pluginId : null);
    info(tr("OpenClaw plugin configured (legacy mode, remote)", "OpenClaw 插件配置完成(旧版模式,远程连接)"));
    return { runtimeConfigOk: true };
  }

  // Current (context-engine) plugins: delegate to `openclaw openviking setup --json`
  // This reuses the same validation logic (health check, version compat, root key
  // detection, slot protection, ensureInstallRecord) from commands/setup.ts
  const effectiveRuntimeConfig = runtimeConfig || {
    baseUrl: remoteBaseUrl,
    apiKey: remoteApiKey,
    peer_role: remotePeerRole,
    peer_prefix: remotePeerPrefix,
    accountId: remoteAccountId,
    userId: remoteUserId,
  };

  // Detect if the installed plugin supports `setup --json` by checking the deployed setup.ts
  let setupJsonSupported = false;
  try {
    const setupTsPath = join(PLUGIN_DEST, "commands", "setup.ts");
    if (existsSync(setupTsPath)) {
      const setupSrc = await readFile(setupTsPath, "utf8");
      setupJsonSupported = setupSrc.includes('"--json"') || setupSrc.includes("'--json'");
    }
  } catch { /* ignore read errors */ }

  let setupResult = null;
  let parsed = null;
  const runSetupJson = async (extraArgs = []) => {
    const setupArgs = ["openviking", "setup"];
    setupArgs.push("--base-url", effectiveRuntimeConfig.baseUrl || remoteBaseUrl);
    setupArgs.push("--json");
    if (effectiveRuntimeConfig.apiKey) {
      setupArgs.push("--api-key", effectiveRuntimeConfig.apiKey);
    }
    if (effectiveRuntimeConfig.peer_role) {
      setupArgs.push("--peer-role", effectiveRuntimeConfig.peer_role);
    }
    if (effectiveRuntimeConfig.peer_prefix) {
      setupArgs.push("--peer-prefix", effectiveRuntimeConfig.peer_prefix);
    }
    if (effectiveRuntimeConfig.accountId) {
      setupArgs.push("--account-id", effectiveRuntimeConfig.accountId);
    }
    if (effectiveRuntimeConfig.userId) {
      setupArgs.push("--user-id", effectiveRuntimeConfig.userId);
    }
    if (forceSlotExplicit) {
      setupArgs.push("--force-slot");
    }
    if (allowOfflineExplicit) {
      setupArgs.push("--allow-offline");
    }
    setupArgs.push(...extraArgs);

    const result = await runCapture("openclaw", setupArgs, { env: ocEnv, shell: IS_WIN });
    return {
      result,
      parsed: parseJsonObjectFromOutput(`${result.out || ""}\n${result.err || ""}`),
    };
  };

  if (setupJsonSupported) {
    info(tr(
      "Delegating configuration to: openclaw openviking setup --json",
      "委托配置给: openclaw openviking setup --json",
    ));

    ({ result: setupResult, parsed } = await runSetupJson());
  } else {
    info(tr(
      "Installed plugin does not support setup --json, using direct config write",
      "已安装的插件不支持 setup --json,使用直接配置写入",
    ));
  }

  if (parsed && !parsed.success && !nonInteractive) {
    if (parsed.action === "slot_blocked" && !forceSlotExplicit) {
      const answer = await question(
        tr(
          `contextEngine slot is owned by "${parsed.slot?.previousOwner}". Replace it with OpenViking? (y/N)`,
          `contextEngine slot is owned by "${parsed.slot?.previousOwner}". Replace it with OpenViking? (y/N)`,
        ),
      );
      if (isYes(answer)) {
        ({ result: setupResult, parsed } = await runSetupJson(["--force-slot"]));
      }
    } else if (
      typeof parsed.error === "string" &&
      parsed.error.includes("Server unreachable") &&
      !allowOfflineExplicit
    ) {
      const answer = await question(
        tr(
          "OpenViking server is unreachable. Save config offline anyway? (y/N)",
          "OpenViking server is unreachable. Save config offline anyway? (y/N)",
        ),
      );
      if (isYes(answer)) {
        ({ result: setupResult, parsed } = await runSetupJson(["--allow-offline"]));
      }
    }
  }

  if (parsed) {
    if (parsed.success) {
      info(tr("OpenClaw plugin configured via setup", "OpenClaw 插件通过 setup 配置完成"));
      if (parsed.health?.ok) {
        info(tr(
          `Server health: OK${parsed.health.version ? ` (version: ${parsed.health.version})` : ""}`,
          `服务端健康: OK${parsed.health.version ? `(版本: ${parsed.health.version})` : ""}`,
        ));
      }
      if (parsed.health?.compatibility === "server_too_old") {
        warn(tr(
          "Server version may be too old for this plugin version",
          "服务端版本可能低于此插件版本要求",
        ));
      }
      if (parsed.slot?.activated) {
        info(tr(`contextEngine slot activated`, `contextEngine slot 已激活`));
      }
    } else {
      // Setup returned success: false
      const setupError = parsed.error || parsed.action || "unknown error";
      if (parsed.action === "slot_blocked") {
        warn(tr(
          `Config saved but contextEngine slot is owned by "${parsed.slot?.previousOwner}". Use --force-slot to override.`,
          `配置已保存,但 contextEngine slot 被 "${parsed.slot?.previousOwner}" 占用。使用 --force-slot 覆盖。`,
        ));
      } else {
        err(tr(
          `Setup failed: ${setupError}`,
          `配置失败: ${setupError}`,
        ));
      }
      return {
        runtimeConfigOk: false,
        error: setupError,
      };
    }
  } else if (setupJsonSupported) {
    const setupError = setupResult
      ? `openclaw openviking setup did not return JSON (exit code ${setupResult.code})`
      : "openclaw openviking setup did not run";
    err(tr(`Setup failed: ${setupError}`, `配置失败: ${setupError}`));
    return {
      runtimeConfigOk: false,
      error: setupError,
    };
  }

  if (!setupJsonSupported) {
    // Direct write: only used when the installed plugin doesn't support `setup --json` (old version).
    // Read the deployed configSchema to determine which fields are allowed, avoiding
    // "additionalProperties" validation failures when writing new fields to old schemas.
    let allowedProps = null;
    try {
      const manifestPath = join(PLUGIN_DEST, "openclaw.plugin.json");
      if (existsSync(manifestPath)) {
        const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
        const schema = manifest?.configSchema;
        if (schema?.properties && typeof schema.properties === "object") {
          allowedProps = new Set(Object.keys(schema.properties));
        }
      }
    } catch { /* ignore parse errors, write all fields */ }

    const peerRole = normalizePeerRole(effectiveRuntimeConfig.peer_role) || "none";
    const peerVal = effectiveRuntimeConfig.peer_prefix || "";
    const usePeerFields = !allowedProps || allowedProps.has("peer_role") || allowedProps.has("peer_prefix");
    const candidates = {
      mode: "remote",
      baseUrl: effectiveRuntimeConfig.baseUrl || remoteBaseUrl,
      apiKey: effectiveRuntimeConfig.apiKey || "",
      accountId: effectiveRuntimeConfig.accountId || undefined,
      userId: effectiveRuntimeConfig.userId || undefined,
    };
    if (usePeerFields) {
      candidates.peer_role = peerRole;
      if (peerVal) candidates.peer_prefix = peerVal;
    }

    const pluginConfig = {};
    for (const [key, val] of Object.entries(candidates)) {
      if (val === undefined) continue;
      if (allowedProps && !allowedProps.has(key)) continue;
      pluginConfig[key] = val;
    }
    if (!pluginConfig.baseUrl) pluginConfig.baseUrl = effectiveRuntimeConfig.baseUrl || remoteBaseUrl;
    if (!("apiKey" in pluginConfig)) pluginConfig.apiKey = effectiveRuntimeConfig.apiKey || "";

    await writeConfigDirect(pluginConfig, claimSlot ? pluginId : null);
    info(tr(
      `OpenClaw plugin configured (direct write): baseUrl=${pluginConfig.baseUrl}, apiKey=${pluginConfig.apiKey ? "***" : "(empty)"}`,
      `OpenClaw 插件配置完成(直接写入): baseUrl=${pluginConfig.baseUrl}, apiKey=${pluginConfig.apiKey ? "***" : "(空)"}`,
    ));
  }

  return { runtimeConfigOk: true };
}

async function writeOpenvikingEnv() {
  const needStateDir = OPENCLAW_DIR !== DEFAULT_OPENCLAW_DIR;
  if (!needStateDir) return null;

  await mkdir(OPENCLAW_DIR, { recursive: true });

  if (IS_WIN) {
    const batLines = ["@echo off"];
    const psLines = [];

    batLines.push(`set "OPENCLAW_STATE_DIR=${OPENCLAW_DIR.replace(/"/g, '""')}"`);
    psLines.push(`$env:OPENCLAW_STATE_DIR = "${OPENCLAW_DIR.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`);

    const batPath = join(OPENCLAW_DIR, "openviking.env.bat");
    const ps1Path = join(OPENCLAW_DIR, "openviking.env.ps1");
    await writeFile(batPath, `${batLines.join("\r\n")}\r\n`, "utf8");
    await writeFile(ps1Path, `${psLines.join("\n")}\n`, "utf8");

    info(tr(`Environment file generated: ${batPath}`, `已生成环境文件: ${batPath}`));
    return { shellPath: batPath, powershellPath: ps1Path };
  }

  const envPath = join(OPENCLAW_DIR, "openviking.env");
  await writeFile(
    envPath,
    `export OPENCLAW_STATE_DIR='${OPENCLAW_DIR.replace(/'/g, "'\"'\"'")}'\n`,
    "utf8",
  );
  info(tr(`Environment file generated: ${envPath}`, `已生成环境文件: ${envPath}`));
  return { shellPath: envPath };
}

function wrapCommand(command, envFiles) {
  if (!envFiles) return command;
  if (IS_WIN) return `call "${envFiles.shellPath}" && ${command}`;
  return `source '${envFiles.shellPath.replace(/'/g, "'\"'\"'")}' && ${command}`;
}

function getExistingEnvFiles() {
  if (IS_WIN) {
    const batPath = join(OPENCLAW_DIR, "openviking.env.bat");
    const ps1Path = join(OPENCLAW_DIR, "openviking.env.ps1");
    if (existsSync(batPath)) {
      return { shellPath: batPath, powershellPath: existsSync(ps1Path) ? ps1Path : undefined };
    }
    if (existsSync(ps1Path)) {
      return { shellPath: ps1Path, powershellPath: ps1Path };
    }
    return null;
  }

  const envPath = join(OPENCLAW_DIR, "openviking.env");
  return existsSync(envPath) ? { shellPath: envPath } : null;
}

async function performUninstall() {
  info(tr("Mode: uninstall plugin", "模式: 卸载插件"));
  info(tr(`Target: ${OPENCLAW_DIR}`, `目标实例: ${OPENCLAW_DIR}`));

  const configPath = getOpenClawConfigPath();
  if (!existsSync(configPath)) {
    info(tr(
      "No openclaw.json found. Nothing to uninstall.",
      "未找到 openclaw.json,无需卸载。",
    ));
    return;
  }

  const installedState = await detectInstalledPluginState();
  if (installedState.generation === "none") {
    info(tr(
      "No OpenViking plugin entries found in openclaw.json. Nothing to uninstall.",
      "openclaw.json 中未找到 OpenViking 插件配置,无需卸载。",
    ));
    return;
  }

  info(tr(
    `Detected installed plugin: ${formatInstalledStateLabel(installedState)}`,
    `检测到已安装插件: ${formatInstalledStateLabel(installedState)}`,
  ));

  if (!nonInteractive) {
    const answer = await question(
      tr("Confirm uninstall? (y/N)", "确认卸载?(y/N)"),
      "N",
    );
    if (!isYes(answer)) {
      info(tr("Cancelled.", "已取消。"));
      return;
    }
  }

  // Step 1: Stop gateway
  info(tr("Step 1: Stopping OpenClaw gateway...", "步骤 1: 停止 OpenClaw gateway..."));
  await stopOpenClawGatewayForUpgrade();

  // Step 2: Backup config
  info(tr("Step 2: Backing up configuration...", "步骤 2: 备份配置..."));
  const configBackupPath = await backupOpenClawConfig(configPath);
  info(tr(`Config backed up to: ${configBackupPath}`, `配置已备份至: ${configBackupPath}`));

  // Step 3: Clean plugin config from openclaw.json
  info(tr("Step 3: Cleaning plugin configuration...", "步骤 3: 清理插件配置..."));
  await cleanupInstalledPluginConfig(installedState);

  // Step 4: Backup and remove plugin directories
  info(tr("Step 4: Backing up plugin directories...", "步骤 4: 备份插件目录..."));
  const pluginBackups = [];
  for (const detection of installedState.detections) {
    const backupDir = await backupPluginDirectory(detection.variant);
    if (backupDir) {
      pluginBackups.push({ pluginId: detection.variant.id, backupDir });
    }
  }

  // Step 5: Remove env files
  info(tr("Step 5: Removing environment files...", "步骤 5: 移除环境文件..."));
  const envFilesToRemove = IS_WIN
    ? [
        join(OPENCLAW_DIR, "openviking.env.bat"),
        join(OPENCLAW_DIR, "openviking.env.ps1"),
      ]
    : [join(OPENCLAW_DIR, "openviking.env")];
  let removedEnvCount = 0;
  for (const f of envFilesToRemove) {
    if (existsSync(f)) {
      try {
        await rm(f);
        removedEnvCount++;
        info(tr(`Removed: ${f}`, `已移除: ${f}`));
      } catch { /* ignore */ }
    }
  }
  if (removedEnvCount === 0) {
    info(tr("No environment files found.", "未找到环境文件。"));
  }

  // Step 6: Write uninstall audit
  const auditDir = getUpgradeAuditDir();
  await mkdir(auditDir, { recursive: true });
  const auditData = {
    operation: "uninstall",
    createdAt: new Date().toISOString(),
    fromVersion: formatInstalledStateLabel(installedState),
    configBackupPath,
    pluginBackups,
  };
  await writeUpgradeAuditFile(auditData);

  // Done
  console.log("");
  bold("═══════════════════════════════════════════════════════════");
  bold(`  ${tr("Uninstall complete!", "卸载完成!")}`);
  bold("═══════════════════════════════════════════════════════════");
  console.log("");

  info(tr("OpenViking server/runtime is preserved (not uninstalled).", "OpenViking 服务端/运行时已保留(未卸载)。"));
  console.log("");

  info(tr("To restore the plugin configuration:", "如需恢复插件配置:"));
  console.log(`  1) ${tr("Stop gateway:", "停止 gateway:")} openclaw gateway stop`);
  console.log(`  2) ${tr("Restore config:", "恢复配置:")} ${IS_WIN ? "copy" : "cp"} "${configBackupPath}" "${configPath}"`);
  for (const pb of pluginBackups) {
    const liveDir = join(OPENCLAW_DIR, "extensions", pb.pluginId);
    console.log(`  3) ${tr("Restore plugin:", "恢复插件:")} ${IS_WIN ? "move" : "mv"} "${pb.backupDir}" "${liveDir}"`);
  }
  console.log("");

  info(tr("To reinstall:", "重新安装:"));
  console.log("  ov-install");
  console.log("");
}

async function main() {
  console.log("");
  bold(tr("🦣 OpenClaw OpenViking plugin installer", "🦣 OpenClaw OpenViking 插件安装"));
  console.log("");

  await selectWorkdir();
  if (showCurrentVersion) {
    await printCurrentVersionInfo();
    return;
  }
  if (uninstallPlugin) {
    await performUninstall();
    return;
  }
  if (rollbackLastUpgrade) {
    info(tr("Mode: rollback last plugin upgrade", "模式: 回滚最近一次插件升级"));
    if (pluginVersionExplicit) {
      warn("--plugin-version is ignored in --rollback mode.");
    }
    await rollbackLastUpgradeOperation();
    return;
  }
  await resolveDefaultPluginVersion();
  validateRequestedPluginVersion();
  info(tr(`Target: ${OPENCLAW_DIR}`, `目标实例: ${OPENCLAW_DIR}`));
  info(tr(`Plugin source: ${pluginSource}`, `Plugin source: ${pluginSource}`));
  if (pluginSource === "npm") {
    info(tr(`Plugin package: ${pluginNpmPackage}`, `Plugin package: ${pluginNpmPackage}`));
  } else {
    info(tr(`Repository: ${REPO}`, `仓库: ${REPO}`));
  }
  info(tr(`Plugin version: ${PLUGIN_VERSION}`, `插件版本: ${PLUGIN_VERSION}`));

  if (upgradePluginOnly) {
    info(tr("Mode: plugin upgrade only", "模式: 仅升级插件"));
  }
  info(tr(`Mode: ${selectedMode}`, `模式: ${selectedMode}`));

  if (upgradePluginOnly) {
    await checkOpenClaw();
    await resolvePluginConfig();
    await checkOpenClawCompatibility();
    await prepareStrongPluginUpgrade();
  } else {
    await checkOpenClaw();
    await resolvePluginConfig();
    await checkOpenClawCompatibility();
    await collectRemoteConfig();
  }

  await deployPluginFromRemote();

  const configResult = await configureOpenClawPlugin(
    upgradePluginOnly
      ? {
          runtimeConfig: upgradeRuntimeConfig,
          claimSlot: installedUpgradeState ? shouldClaimTargetSlot(installedUpgradeState) : true,
        }
      : { preserveExistingConfig: false },
  );
  const runtimeConfigOk = configResult?.runtimeConfigOk !== false;
  const runtimeConfigError = configResult?.error || "";

  // Only mark the install as completed (state file + upgrade audit) when the
  // runtime config was actually applied. Plugin files are already on disk
  // either way, so subsequent runs can pick up from here.
  if (runtimeConfigOk) {
    await writeInstallStateFile({
      operation: upgradePluginOnly ? "upgrade" : "install",
      fromVersion: upgradeAudit?.fromVersion || "",
      configBackupPath: upgradeAudit?.configBackupPath || "",
      pluginBackups: upgradeAudit?.pluginBackups || [],
    });
    if (upgradeAudit) {
      upgradeAudit.completedAt = new Date().toISOString();
      await writeUpgradeAuditFile(upgradeAudit);
    }
  }
  let envFiles = getExistingEnvFiles();
  if (!upgradePluginOnly) {
    envFiles = await writeOpenvikingEnv();
  } else if (!envFiles && OPENCLAW_DIR !== DEFAULT_OPENCLAW_DIR) {
    envFiles = await writeOpenvikingEnv();
  }

  console.log("");
  if (runtimeConfigOk) {
    bold("═══════════════════════════════════════════════════════════");
    bold(`  ${tr("Installation complete!", "安装完成!")}`);
    bold("═══════════════════════════════════════════════════════════");
    console.log("");

    if (upgradeAudit) {
      info(tr(`Upgrade path recorded: ${upgradeAudit.fromVersion} -> ${upgradeAudit.toVersion}`, `已记录升级路径: ${upgradeAudit.fromVersion} -> ${upgradeAudit.toVersion}`));
      info(tr(`Rollback config backup: ${upgradeAudit.configBackupPath}`, `回滚配置备份: ${upgradeAudit.configBackupPath}`));
      for (const pluginBackup of upgradeAudit.pluginBackups || []) {
        info(tr(`Rollback plugin backup: ${pluginBackup.backupDir}`, `回滚插件备份: ${pluginBackup.backupDir}`));
      }
      info(tr(`Rollback audit file: ${getUpgradeAuditPath()}`, `回滚审计文件: ${getUpgradeAuditPath()}`));
      console.log("");
    }
  } else {
    bold("═══════════════════════════════════════════════════════════");
    bold(`  ${tr(
      "Plugin files installed, but runtime configuration was NOT applied",
      "插件文件已安装,但运行时配置未生效",
    )}`);
    bold(`  ${tr(`Reason: ${runtimeConfigError}`, `原因: ${runtimeConfigError}`)}`);
    bold(`  ${tr(
      "Re-run: openclaw openviking setup --reconfigure",
      "重新运行: openclaw openviking setup --reconfigure",
    )}`);
    bold("═══════════════════════════════════════════════════════════");
    console.log("");
  }

  info(tr("Run these commands to start OpenClaw:", "请按以下命令启动 OpenClaw:"));
  console.log(`  1) ${wrapCommand("openclaw --version", envFiles)}`);
  console.log(`  2) ${wrapCommand("openclaw onboard", envFiles)}`);
  console.log(`  3) ${wrapCommand("openclaw gateway", envFiles)}`);
  console.log(`  4) ${wrapCommand("openclaw status", envFiles)}`);
  console.log("");

  info(tr(`OpenViking server URL (plugin): ${remoteBaseUrl}`, `OpenViking 服务地址(插件): ${remoteBaseUrl}`));
  console.log("");
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});