openclaw-openviking-setup-helper 0.2.8 → 0.2.9-dev.1

package/install.js

@@ -11,10 +11,10 @@
  *
  * Direct run:
  *   node install.js [ -y | --yes ] [ --zh ] [ --workdir PATH ]
- *                   [ --openviking-version=V ] [ --repo=PATH ]
+ *                   [ --plugin-version=TAG ] [ --openviking-version=V ] [ --repo=PATH ]
  *
  * Environment variables:
- *   REPO, BRANCH, OPENVIKING_INSTALL_YES, SKIP_OPENCLAW, SKIP_OPENVIKING
+ *   REPO, PLUGIN_VERSION (or BRANCH), OPENVIKING_INSTALL_YES, SKIP_OPENCLAW, SKIP_OPENVIKING
  *   OPENVIKING_VERSION       Pip install openviking==VERSION (omit for latest)
  *   OPENVIKING_REPO          Repo path: source install (pip -e) + local plugin (default: off)
  *   NPM_REGISTRY, PIP_INDEX_URL
@@ -23,26 +23,26 @@
  */
 
 import { spawn } from "node:child_process";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { cp, mkdir, rm, writeFile } from "node:fs/promises";
 import { existsSync, readdirSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, relative } from "node:path";
 import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-const REPO = process.env.REPO || "volcengine/OpenViking";
-const BRANCH = process.env.BRANCH || "main";
-const GH_RAW = `https://raw.githubusercontent.com/${REPO}/${BRANCH}`;
+let REPO = process.env.REPO || "volcengine/OpenViking";
+// PLUGIN_VERSION takes precedence over BRANCH (legacy)
+let PLUGIN_VERSION = process.env.PLUGIN_VERSION || process.env.BRANCH || "main";
 const NPM_REGISTRY = process.env.NPM_REGISTRY || "https://registry.npmmirror.com";
-const PIP_INDEX_URL = process.env.PIP_INDEX_URL || "https://pypi.tuna.tsinghua.edu.cn/simple";
+const PIP_INDEX_URL = process.env.PIP_INDEX_URL || "https://mirrors.volces.com/pypi/simple/";
 
 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 = join(OPENCLAW_DIR, "extensions", "memory-openviking");
+let PLUGIN_DEST = "";  // Will be set after resolving plugin config
 
 const OPENVIKING_DIR = join(HOME, ".openviking");
 
@@ -51,21 +51,35 @@ const DEFAULT_AGFS_PORT = 1833;
 const DEFAULT_VLM_MODEL = "doubao-seed-2-0-pro-260215";
 const DEFAULT_EMBED_MODEL = "doubao-embedding-vision-251215";
 
-const REQUIRED_PLUGIN_FILES = [
-  "examples/openclaw-memory-plugin/index.ts",
-  "examples/openclaw-memory-plugin/config.ts",
-  "examples/openclaw-memory-plugin/openclaw.plugin.json",
-  "examples/openclaw-memory-plugin/package.json",
-  "examples/openclaw-memory-plugin/package-lock.json",
-  "examples/openclaw-memory-plugin/.gitignore",
-];
-
-const OPTIONAL_PLUGIN_FILES = [
-  "examples/openclaw-memory-plugin/client.ts",
-  "examples/openclaw-memory-plugin/process-manager.ts",
-  "examples/openclaw-memory-plugin/memory-ranking.ts",
-  "examples/openclaw-memory-plugin/text-utils.ts",
-];
+// Fallback configs for old versions without manifest
+const FALLBACK_LEGACY = {
+  dir: "openclaw-memory-plugin",
+  id: "memory-openviking",
+  kind: "memory",
+  slot: "memory",
+  required: ["index.ts", "config.ts", "openclaw.plugin.json", "package.json"],
+  optional: ["package-lock.json", ".gitignore"],
+};
+
+const FALLBACK_CURRENT = {
+  dir: "openclaw-plugin",
+  id: "openviking",
+  kind: "context-engine",
+  slot: "contextEngine",
+  required: ["index.ts", "config.ts", "openclaw.plugin.json", "package.json"],
+  optional: ["context-engine.ts", "client.ts", "process-manager.ts", "memory-ranking.ts", "text-utils.ts", "session-transcript-repair.ts", "tool-call-id.ts", "tsconfig.json", "package-lock.json", ".gitignore"],
+};
+
+// Resolved plugin config (set by resolvePluginConfig)
+let resolvedPluginDir = "";
+let resolvedPluginId = "";
+let resolvedPluginKind = "";
+let resolvedPluginSlot = "";
+let resolvedFilesRequired = [];
+let resolvedFilesOptional = [];
+let resolvedNpmOmitDev = true;
+let resolvedMinOpenclawVersion = "";
+let resolvedMinOpenvikingVersion = "";
 
 let installYes = process.env.OPENVIKING_INSTALL_YES === "1";
 let langZh = false;
@@ -102,38 +116,86 @@ for (let i = 0; i < argv.length; i++) {
     i += 1;
     continue;
   }
+  if (arg.startsWith("--plugin-version=")) {
+    PLUGIN_VERSION = arg.slice("--plugin-version=".length).trim();
+    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;
+    i += 1;
+    continue;
+  }
   if (arg.startsWith("--openviking-version=")) {
     openvikingVersion = arg.slice("--openviking-version=".length).trim();
     continue;
   }
+  if (arg === "--openviking-version") {
+    const version = argv[i + 1]?.trim();
+    if (!version) {
+      console.error("--openviking-version requires a value");
+      process.exit(1);
+    }
+    openvikingVersion = version;
+    i += 1;
+    continue;
+  }
   if (arg.startsWith("--repo=")) {
     openvikingRepo = arg.slice("--repo=".length).trim();
     continue;
   }
+  if (arg.startsWith("--github-repo=")) {
+    REPO = arg.slice("--github-repo=".length).trim();
+    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;
+    i += 1;
+    continue;
+  }
   if (arg === "-h" || arg === "--help") {
     printHelp();
     process.exit(0);
   }
 }
 
-const OPENVIKING_PIP_SPEC = openvikingVersion ? `openviking==${openvikingVersion}` : "openviking";
-
 function setOpenClawDir(dir) {
   OPENCLAW_DIR = dir;
-  PLUGIN_DEST = join(OPENCLAW_DIR, "extensions", "memory-openviking");
 }
 
 function printHelp() {
-  console.log("Usage: node install.js [ -y | --yes ] [ --zh ] [ --workdir PATH ] [ --openviking-version=V ] [ --repo=PATH ]");
+  console.log("Usage: node install.js [ OPTIONS ]");
+  console.log("");
+  console.log("Options:");
+  console.log("  --github-repo=OWNER/REPO GitHub repository (default: volcengine/OpenViking)");
+  console.log("  --plugin-version=TAG     Plugin version (Git tag, e.g. v0.2.9, default: main)");
+  console.log("  --openviking-version=V   OpenViking PyPI version (e.g. 0.2.9, default: latest)");
+  console.log("  --workdir PATH           OpenClaw config directory (default: ~/.openclaw)");
+  console.log("  --repo=PATH              Use local OpenViking repo at PATH (pip -e + local plugin)");
+  console.log("  -y, --yes                Non-interactive (use defaults)");
+  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("  # Install from a fork repository");
+  console.log("  node install.js --github-repo=yourname/OpenViking --plugin-version=dev-branch");
   console.log("");
-  console.log("  -y, --yes   Non-interactive (use defaults)");
-  console.log("  --zh        Chinese prompts");
-  console.log("  --workdir   OpenClaw config directory (default: ~/.openclaw)");
-  console.log("  --openviking-version=VERSION   Pip install openviking==VERSION (default: latest)");
-  console.log("  --repo=PATH   Use OpenViking repo at PATH: pip install -e PATH, plugin from repo (default: off)");
-  console.log("  -h, --help  This help");
+  console.log("  # Install specific plugin version");
+  console.log("  node install.js --plugin-version=v0.2.8");
   console.log("");
-  console.log("Env: OPENVIKING_REPO, REPO, BRANCH, SKIP_OPENCLAW, SKIP_OPENVIKING, OPENVIKING_VERSION, NPM_REGISTRY, PIP_INDEX_URL");
+  console.log("Env: REPO, PLUGIN_VERSION, OPENVIKING_VERSION, SKIP_OPENCLAW, SKIP_OPENVIKING, NPM_REGISTRY, PIP_INDEX_URL");
 }
 
 function tr(en, zh) {
@@ -234,8 +296,19 @@ function question(prompt, defaultValue = "") {
   });
 }
 
+async function resolveAbsoluteCommand(cmd) {
+  if (cmd.startsWith("/") || (IS_WIN && /^[A-Za-z]:[/\\]/.test(cmd))) return cmd;
+  if (IS_WIN) {
+    const r = await runCapture("where", [cmd], { shell: true });
+    return r.out.split(/\r?\n/)[0]?.trim() || cmd;
+  }
+  const r = await runCapture("which", [cmd], { shell: false });
+  return r.out.trim() || cmd;
+}
+
 async function checkPython() {
-  const py = process.env.OPENVIKING_PYTHON || (IS_WIN ? "python" : "python3");
+  const raw = process.env.OPENVIKING_PYTHON || (IS_WIN ? "python" : "python3");
+  const py = await resolveAbsoluteCommand(raw);
   const result = await runCapture(py, ["-c", "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')"]);
   if (result.code !== 0 || !result.out) {
     return {
@@ -389,6 +462,222 @@ async function checkOpenClaw() {
   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 isSemverLike(value) {
+  return /^v?\d+(\.\d+){1,2}$/.test(value);
+}
+
+// Detect OpenClaw version
+async function detectOpenClawVersion() {
+  try {
+    const result = await runCapture("openclaw", ["--version"], { shell: IS_WIN });
+    if (result.code === 0 && result.out) {
+      const match = result.out.match(/\d+\.\d+(\.\d+)?/);
+      if (match) return match[0];
+    }
+  } catch {}
+  return "0.0.0";
+}
+
+// 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;
+}
+
+// Resolve plugin configuration from manifest or fallback
+async function resolvePluginConfig() {
+  const ghRaw = `https://raw.githubusercontent.com/${REPO}/${PLUGIN_VERSION}`;
+
+  info(tr(`Resolving plugin configuration for version: ${PLUGIN_VERSION}`, `正在解析插件配置，版本: ${PLUGIN_VERSION}`));
+
+  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;
+
+  if (manifestData) {
+    resolvedPluginId = manifestData.plugin?.id || "";
+    resolvedPluginKind = manifestData.plugin?.kind || "";
+    resolvedPluginSlot = manifestData.plugin?.slot || "";
+    resolvedMinOpenclawVersion = manifestData.compatibility?.minOpenclawVersion || "";
+    resolvedMinOpenvikingVersion = manifestData.compatibility?.minOpenvikingVersion || "";
+    resolvedNpmOmitDev = manifestData.npm?.omitDev !== 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 || "";
+        if (pkgName && pkgName !== "@openclaw/openviking") {
+          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;
+
+    // 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 || "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}`));
+
+  // If no minimum version required, pass
+  if (!resolvedMinOpenclawVersion) {
+    return;
+  }
+
+  // If user explicitly requested an old version, pass
+  if (PLUGIN_VERSION !== "main" && isSemverLike(PLUGIN_VERSION) && !versionGte(PLUGIN_VERSION, "v0.2.9")) {
+    return;
+  }
+
+  // Check compatibility
+  if (!versionGte(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 legacy plugin (v0.2.8)", "方案 2：安装旧版插件 (v0.2.8)")}`);
+    console.log(`    node install.js --plugin-version=v0.2.8${langZh ? " --zh" : ""}`);
+    console.log("");
+    process.exit(1);
+  }
+}
+
+function checkRequestedOpenVikingCompatibility() {
+  if (!resolvedMinOpenvikingVersion || !openvikingVersion) return;
+  if (versionGte(openvikingVersion, resolvedMinOpenvikingVersion)) return;
+
+  err(tr(
+    `OpenViking ${openvikingVersion} does not support this plugin (requires >= ${resolvedMinOpenvikingVersion})`,
+    `OpenViking ${openvikingVersion} 不支持此插件（需要 >= ${resolvedMinOpenvikingVersion}）`,
+  ));
+  console.log("");
+  console.log(tr(
+    "Use a newer OpenViking version, or omit --openviking-version to install the latest release.",
+    "请使用更新版本的 OpenViking，或省略 --openviking-version 以安装最新版本。",
+  ));
+  process.exit(1);
+}
+
 async function installOpenViking() {
   if (process.env.SKIP_OPENVIKING === "1") {
     info(tr("Skipping OpenViking install (SKIP_OPENVIKING=1)", "跳过 OpenViking 安装 (SKIP_OPENVIKING=1)"));
@@ -400,6 +689,12 @@ async function installOpenViking() {
     err(tr("Python check failed.", "Python 校验失败"));
     process.exit(1);
   }
+  if (!python.ok) {
+    warn(tr(
+      `${python.detail}. Will attempt to find a suitable Python for pip install.`,
+      `${python.detail}。将尝试查找合适的 Python 进行 pip 安装。`,
+    ));
+  }
 
   const py = python.cmd;
 
@@ -412,14 +707,20 @@ async function installOpenViking() {
     return;
   }
 
-  info(tr("Installing OpenViking from PyPI...", "正在安装 OpenViking (PyPI)..."));
+  // Determine package spec
+  const pkgSpec = openvikingVersion ? `openviking==${openvikingVersion}` : "openviking";
+  if (openvikingVersion) {
+    info(tr(`Installing OpenViking ${openvikingVersion} from PyPI...`, `正在安装 OpenViking ${openvikingVersion} (PyPI)...`));
+  } else {
+    info(tr("Installing OpenViking (latest) from PyPI...", "正在安装 OpenViking (最新版) (PyPI)..."));
+  }
   info(tr(`Using pip index: ${PIP_INDEX_URL}`, `使用 pip 镜像源: ${PIP_INDEX_URL}`));
 
-  info(`Package: ${OPENVIKING_PIP_SPEC}`);
+  info(`Package: ${pkgSpec}`);
   await runCapture(py, ["-m", "pip", "install", "--upgrade", "pip", "-q", "-i", PIP_INDEX_URL], { shell: false });
   const installResult = await runLiveCapture(
     py,
-    ["-m", "pip", "install", "--progress-bar", "on", OPENVIKING_PIP_SPEC, "-i", PIP_INDEX_URL],
+    ["-m", "pip", "install", "--progress-bar", "on", pkgSpec, "-i", PIP_INDEX_URL],
     { shell: false },
   );
   if (installResult.code === 0) {
@@ -439,7 +740,7 @@ async function installOpenViking() {
       if (reuseCheck.code === 0) {
         await runLiveCapture(
           venvPy,
-          ["-m", "pip", "install", "--progress-bar", "on", "-U", OPENVIKING_PIP_SPEC, "-i", PIP_INDEX_URL],
+          ["-m", "pip", "install", "--progress-bar", "on", "-U", pkgSpec, "-i", PIP_INDEX_URL],
           { shell: false },
         );
         openvikingPythonPath = venvPy;
@@ -475,7 +776,7 @@ async function installOpenViking() {
     await runCapture(venvPy, ["-m", "pip", "install", "--upgrade", "pip", "-q", "-i", PIP_INDEX_URL], { shell: false });
     const venvInstall = await runLiveCapture(
       venvPy,
-      ["-m", "pip", "install", "--progress-bar", "on", OPENVIKING_PIP_SPEC, "-i", PIP_INDEX_URL],
+      ["-m", "pip", "install", "--progress-bar", "on", pkgSpec, "-i", PIP_INDEX_URL],
       { shell: false },
     );
     if (venvInstall.code === 0) {
@@ -492,7 +793,7 @@ async function installOpenViking() {
   if (process.env.OPENVIKING_ALLOW_BREAK_SYSTEM_PACKAGES === "1") {
     const systemInstall = await runLiveCapture(
       py,
-      ["-m", "pip", "install", "--progress-bar", "on", "--break-system-packages", OPENVIKING_PIP_SPEC, "-i", PIP_INDEX_URL],
+      ["-m", "pip", "install", "--progress-bar", "on", "--break-system-packages", pkgSpec, "-i", PIP_INDEX_URL],
       { shell: false },
     );
     if (systemInstall.code === 0) {
@@ -549,9 +850,17 @@ async function configureOvConf() {
       vectordb: { name: "context", backend: "local", project: "default" },
       agfs: { port: agfsPortNum, log_level: "warn", backend: "local", timeout: 10, retry_times: 3 },
     },
+    log: {
+      level: "WARNING",
+      format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+      output: "file",
+      rotation: true,
+      rotation_days: 3,
+      rotation_interval: "midnight",
+    },
     embedding: {
       dense: {
-        backend: "volcengine",
+        provider: "volcengine",
         api_key: embeddingApiKey || null,
         model: embeddingModel,
         api_base: "https://ark.cn-beijing.volces.com/api/v3",
@@ -560,7 +869,7 @@ async function configureOvConf() {
       },
     },
     vlm: {
-      backend: "volcengine",
+      provider: "volcengine",
       api_key: vlmApiKey || null,
       model: vlmModel,
       api_base: "https://ark.cn-beijing.volces.com/api/v3",
@@ -574,9 +883,7 @@ async function configureOvConf() {
   info(tr(`Config generated: ${configPath}`, `已生成配置: ${configPath}`));
 }
 
-async function downloadPluginFile(relPath, required, index, total) {
-  const fileName = relPath.split("/").pop();
-  const url = `${GH_RAW}/${relPath}`;
+async function downloadPluginFile(fileName, url, required, index, total) {
   const maxRetries = 3;
 
   process.stdout.write(`  [${index}/${total}] ${fileName} `);
@@ -591,7 +898,7 @@ async function downloadPluginFile(relPath, required, index, total) {
         return;
       }
       if (!required && response.status === 404) {
-        console.log(tr("(not present in target branch, skipped)", "（目标分支不存在，已跳过）"));
+        console.log(tr("(skipped)", "（跳过）"));
         return;
       }
     } catch {}
@@ -607,98 +914,188 @@ async function downloadPluginFile(relPath, required, index, total) {
     return;
   }
 
+  if (!required) {
+    console.log(tr("(skipped)", "（跳过）"));
+    return;
+  }
+
   console.log("");
   err(tr(`Download failed: ${url}`, `下载失败: ${url}`));
   process.exit(1);
 }
 
 async function downloadPlugin() {
+  const ghRaw = `https://raw.githubusercontent.com/${REPO}/${PLUGIN_VERSION}`;
+  const pluginDir = resolvedPluginDir;
+  const total = resolvedFilesRequired.length + resolvedFilesOptional.length;
+
   await mkdir(PLUGIN_DEST, { recursive: true });
-  const files = [
-    ...REQUIRED_PLUGIN_FILES.map((relPath) => ({ relPath, required: true })),
-    ...OPTIONAL_PLUGIN_FILES.map((relPath) => ({ relPath, required: false })),
-  ];
 
-  info(tr(`Downloading memory-openviking plugin from ${REPO}@${BRANCH}...`, `正在从 ${REPO}@${BRANCH} 下载 memory-openviking 插件...`));
-  for (let i = 0; i < files.length; i++) {
-    const file = files[i];
-    await downloadPluginFile(file.relPath, file.required, i + 1, files.length);
+  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++;
+    const url = `${ghRaw}/examples/${pluginDir}/${name}`;
+    await downloadPluginFile(name, url, true, i, total);
+  }
+
+  // Download optional files
+  for (const name of resolvedFilesOptional) {
+    if (!name) continue;
+    i++;
+    const url = `${ghRaw}/examples/${pluginDir}/${name}`;
+    await downloadPluginFile(name, url, false, i, total);
   }
 
+  // npm install
   info(tr("Installing plugin npm dependencies...", "正在安装插件 npm 依赖..."));
-  await run("npm", ["install", "--no-audit", "--no-fund"], { cwd: PLUGIN_DEST, silent: false });
+  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: PLUGIN_DEST, silent: false });
   info(tr(`Plugin deployed: ${PLUGIN_DEST}`, `插件部署完成: ${PLUGIN_DEST}`));
 }
 
-async function configureOpenClawPlugin(pluginPath = PLUGIN_DEST) {
+async function deployLocalPlugin(localPluginDir) {
+  await rm(PLUGIN_DEST, { recursive: true, force: true });
+  await mkdir(PLUGIN_DEST, { recursive: true });
+  await cp(localPluginDir, PLUGIN_DEST, {
+    recursive: true,
+    force: true,
+    filter: (sourcePath) => {
+      const rel = relative(localPluginDir, sourcePath);
+      if (!rel) return true;
+      const firstSegment = rel.split(/[\\/]/)[0];
+      return firstSegment !== "node_modules" && firstSegment !== ".git";
+    },
+  });
+}
+
+async function configureOpenClawPlugin() {
   info(tr("Configuring OpenClaw plugin...", "正在配置 OpenClaw 插件..."));
 
-  const configPath = join(OPENCLAW_DIR, "openclaw.json");
-  let config = {};
+  const pluginId = resolvedPluginId;
+  const pluginSlot = resolvedPluginSlot;
 
-  if (existsSync(configPath)) {
-    try {
-      const raw = await readFile(configPath, "utf8");
-      if (raw.trim()) config = JSON.parse(raw);
-    } catch {
-      warn(tr("Existing openclaw.json invalid. Rebuilding required sections.", "已有 openclaw.json 非法，将重建相关配置节点。"));
-    }
+  const ocEnv = { ...process.env };
+  if (OPENCLAW_DIR !== DEFAULT_OPENCLAW_DIR) {
+    ocEnv.OPENCLAW_STATE_DIR = OPENCLAW_DIR;
   }
 
-  if (!config.plugins) config.plugins = {};
-  if (!config.gateway) config.gateway = {};
-  if (!config.plugins.slots) config.plugins.slots = {};
-  if (!config.plugins.load) config.plugins.load = {};
-  if (!config.plugins.entries) config.plugins.entries = {};
+  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;
+  };
 
-  const existingPaths = Array.isArray(config.plugins.load.paths) ? config.plugins.load.paths : [];
-  config.plugins.enabled = true;
-  config.plugins.allow = ["memory-openviking"];
-  config.plugins.slots.memory = "memory-openviking";
-  config.plugins.load.paths = [...new Set([...existingPaths, pluginPath])];
+  // Enable plugin (files already deployed to extensions dir by deployPlugin)
+  await oc(["plugins", "enable", pluginId]);
+  await oc(["config", "set", `plugins.slots.${pluginSlot}`, pluginId]);
 
-  const pluginConfig = {
-    mode: selectedMode,
-    targetUri: "viking://user/memories",
-    autoRecall: true,
-    autoCapture: true,
-  };
+  // Set gateway mode
+  await oc(["config", "set", "gateway.mode", "local"]);
 
+  // Set plugin config for the selected mode
   if (selectedMode === "local") {
-    pluginConfig.configPath = join(OPENVIKING_DIR, "ov.conf");
-    pluginConfig.port = selectedServerPort;
+    const ovConfPath = join(OPENVIKING_DIR, "ov.conf");
+    await oc(["config", "set", `plugins.entries.${pluginId}.config.mode`, "local"]);
+    await oc(["config", "set", `plugins.entries.${pluginId}.config.configPath`, ovConfPath]);
+    await oc(["config", "set", `plugins.entries.${pluginId}.config.port`, String(selectedServerPort)]);
   } else {
-    pluginConfig.baseUrl = remoteBaseUrl;
-    if (remoteApiKey) pluginConfig.apiKey = remoteApiKey;
-    if (remoteAgentId) pluginConfig.agentId = remoteAgentId;
+    await oc(["config", "set", `plugins.entries.${pluginId}.config.mode`, "remote"]);
+    await oc(["config", "set", `plugins.entries.${pluginId}.config.baseUrl`, remoteBaseUrl]);
+    if (remoteApiKey) {
+      await oc(["config", "set", `plugins.entries.${pluginId}.config.apiKey`, remoteApiKey]);
+    }
+    if (remoteAgentId) {
+      await oc(["config", "set", `plugins.entries.${pluginId}.config.agentId`, remoteAgentId]);
+    }
   }
 
-  config.plugins.entries["memory-openviking"] = { config: pluginConfig };
-  config.gateway.mode = "local";
+  // Legacy (memory) plugins need explicit targetUri/autoRecall/autoCapture (new version has defaults in config.ts)
+  if (resolvedPluginKind === "memory") {
+    await oc(["config", "set", `plugins.entries.${pluginId}.config.targetUri`, "viking://user/memories"]);
+    await oc(["config", "set", `plugins.entries.${pluginId}.config.autoRecall`, "true", "--json"]);
+    await oc(["config", "set", `plugins.entries.${pluginId}.config.autoCapture`, "true", "--json"]);
+  }
 
-  await mkdir(OPENCLAW_DIR, { recursive: true });
-  await writeFile(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
   info(tr("OpenClaw plugin configured", "OpenClaw 插件配置完成"));
 }
 
+async function discoverOpenvikingPython(failedPy) {
+  const candidates = IS_WIN
+    ? ["python3", "python", "py -3"]
+    : ["python3.13", "python3.12", "python3.11", "python3.10", "python3", "python"];
+  for (const candidate of candidates) {
+    if (candidate === failedPy) continue;
+    const resolved = await resolveAbsoluteCommand(candidate);
+    if (!resolved || resolved === candidate || resolved === failedPy) continue;
+    const check = await runCapture(resolved, ["-c", "import openviking"], { shell: false });
+    if (check.code === 0) return resolved;
+  }
+  return "";
+}
+
 async function resolvePythonPath() {
   if (openvikingPythonPath) return openvikingPythonPath;
   const python = await checkPython();
-  const py = python.cmd;
-  if (!py) return "";
-
-  if (IS_WIN) {
-    const result = await runCapture("where", [py], { shell: true });
-    return result.out.split(/\r?\n/)[0]?.trim() || py;
-  }
-
-  const result = await runCapture("which", [py], { shell: false });
-  return result.out.trim() || py;
+  return python.cmd || "";
 }
 
 async function writeOpenvikingEnv({ includePython }) {
   const needStateDir = OPENCLAW_DIR !== DEFAULT_OPENCLAW_DIR;
-  const pythonPath = includePython ? await resolvePythonPath() : "";
+  let pythonPath = "";
+  if (includePython) {
+    pythonPath = await resolvePythonPath();
+    if (!pythonPath) {
+      pythonPath = (process.env.OPENVIKING_PYTHON || "").trim() || (IS_WIN ? "python" : "python3");
+      warn(
+        tr(
+          "Could not resolve absolute Python path; wrote fallback OPENVIKING_PYTHON to openviking.env. Edit that file if OpenViking fails to start.",
+          "未能解析 Python 绝对路径，已在 openviking.env 中写入后备值。若启动失败请手动修改为虚拟环境中的 python 可执行文件路径。",
+        ),
+      );
+    }
+
+    // Verify the resolved Python can actually import openviking
+    if (pythonPath) {
+      const verify = await runCapture(pythonPath, ["-c", "import openviking"], { shell: false });
+      if (verify.code !== 0) {
+        warn(
+          tr(
+            `Resolved Python (${pythonPath}) cannot import openviking. The pip install target may differ from the runtime python3.`,
+            `解析到的 Python（${pythonPath}）无法 import openviking。pip 安装目标可能与运行时的 python3 不一致。`,
+          ),
+        );
+        // Try to discover the correct Python via pip show
+        const corrected = await discoverOpenvikingPython(pythonPath);
+        if (corrected) {
+          info(
+            tr(
+              `Auto-corrected OPENVIKING_PYTHON to ${corrected}`,
+              `已自动修正 OPENVIKING_PYTHON 为 ${corrected}`,
+            ),
+          );
+          pythonPath = corrected;
+        } else {
+          warn(
+            tr(
+              `Could not auto-detect the correct Python. Edit OPENVIKING_PYTHON in the env file manually.`,
+              `无法自动检测正确的 Python。请手动修改 env 文件中的 OPENVIKING_PYTHON。`,
+            ),
+          );
+        }
+      }
+    }
+  }
+
+  // Remote mode + default state dir + no python line → nothing to persist
   if (!needStateDir && !pythonPath) return null;
 
   await mkdir(OPENCLAW_DIR, { recursive: true });
@@ -752,6 +1149,11 @@ async function main() {
 
   await selectWorkdir();
   info(tr(`Target: ${OPENCLAW_DIR}`, `目标实例: ${OPENCLAW_DIR}`));
+  info(tr(`Repository: ${REPO}`, `仓库: ${REPO}`));
+  info(tr(`Plugin version: ${PLUGIN_VERSION}`, `插件版本: ${PLUGIN_VERSION}`));
+  if (openvikingVersion) {
+    info(tr(`OpenViking version: ${openvikingVersion}`, `OpenViking 版本: ${openvikingVersion}`));
+  }
 
   await selectMode();
   info(tr(`Mode: ${selectedMode}`, `模式: ${selectedMode}`));
@@ -759,28 +1161,38 @@ async function main() {
   if (selectedMode === "local") {
     await validateEnvironment();
     await checkOpenClaw();
+    // Resolve plugin config after OpenClaw is available (for version detection)
+    await resolvePluginConfig();
+    await checkOpenClawCompatibility();
+    checkRequestedOpenVikingCompatibility();
     await installOpenViking();
     await configureOvConf();
   } else {
     await checkOpenClaw();
+    await resolvePluginConfig();
+    await checkOpenClawCompatibility();
     await collectRemoteConfig();
   }
 
   let pluginPath;
-  const localPluginDir = openvikingRepo ? join(openvikingRepo, "examples", "openclaw-memory-plugin") : "";
+  const localPluginDir = openvikingRepo ? join(openvikingRepo, "examples", resolvedPluginDir || "openclaw-plugin") : "";
   if (openvikingRepo && existsSync(join(localPluginDir, "index.ts"))) {
     pluginPath = localPluginDir;
+    PLUGIN_DEST = join(OPENCLAW_DIR, "extensions", resolvedPluginId || "openviking");
     info(tr(`Using local plugin from repo: ${pluginPath}`, `使用仓库内插件: ${pluginPath}`));
-    if (!existsSync(join(pluginPath, "node_modules"))) {
+    await deployLocalPlugin(pluginPath);
       info(tr("Installing plugin npm dependencies...", "正在安装插件 npm 依赖..."));
-      await run("npm", ["install", "--no-audit", "--no-fund"], { cwd: pluginPath, silent: false });
-    }
+    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: PLUGIN_DEST, silent: false });
+    pluginPath = PLUGIN_DEST;
   } else {
     await downloadPlugin();
     pluginPath = PLUGIN_DEST;
   }
 
-  await configureOpenClawPlugin(pluginPath);
+  await configureOpenClawPlugin();
   const envFiles = await writeOpenvikingEnv({
     includePython: selectedMode === "local",
   });
@@ -803,6 +1215,14 @@ async function main() {
   console.log("");
 
   if (selectedMode === "local") {
+    if (envFiles?.shellPath && !IS_WIN) {
+      info(
+        tr(
+          'If source fails, set: export OPENVIKING_PYTHON="$(command -v python3)"',
+          '若 source 失败，可执行: export OPENVIKING_PYTHON="$(command -v python3)"',
+        ),
+      );
+    }
     info(tr(`You can edit the config freely: ${OPENVIKING_DIR}/ov.conf`, `你可以按需自由修改配置文件: ${OPENVIKING_DIR}/ov.conf`));
   } else {
     info(tr(`Remote server: ${remoteBaseUrl}`, `远程服务器: ${remoteBaseUrl}`));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-openviking-setup-helper",
-  "version": "0.2.8",
+  "version": "0.2.9-dev.1",
   "description": "Setup helper for installing OpenViking memory plugin into OpenClaw",
   "type": "module",
   "bin": {
@@ -21,7 +21,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/volcengine/OpenViking.git",
-    "directory": "examples/openclaw-memory-plugin/setup-helper"
+    "directory": "examples/openclaw-plugin/setup-helper"
   },
   "files": [
     "install.js"