openclaw-openviking-setup-helper 0.3.0 → 0.3.1

package/install.js

@@ -9,29 +9,34 @@
  *   ov-install
  *   openclaw-openviking-install
  *
- * Direct run:
- *   node install.js [ --base-url URL ] [ --api-key KEY ] [ --zh ] [ --workdir PATH ] [ --upgrade-plugin ]
- *                   [ --plugin-version=TAG ]
- *
- * Environment variables:
- *   REPO, PLUGIN_VERSION (or BRANCH), OPENVIKING_BASE_URL, OPENVIKING_API_KEY, SKIP_OPENCLAW
- *   NPM_REGISTRY
- */
+ * 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, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { existsSync, readdirSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
-import { createInterface } from "node:readline";
-import { fileURLToPath } from "node:url";
+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";
-// PLUGIN_VERSION takes precedence over BRANCH (legacy). If omitted, resolve the latest tag from GitHub.
-const pluginVersionEnv = (process.env.PLUGIN_VERSION || process.env.BRANCH || "").trim();
-let PLUGIN_VERSION = pluginVersionEnv;
-let pluginVersionExplicit = Boolean(pluginVersionEnv);
+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;
@@ -97,17 +102,21 @@ let resolvedNpmBuildMinOpenclawVersion = DEFAULT_NPM_BUILD_MIN_OPENCLAW_VERSION;
 let resolvedNpmBuildScript = "build";
 let resolvedNpmPruneAfterBuild = true;
 let resolvedMinOpenclawVersion = "";
-let resolvedMinOpenvikingVersion = "";
-let resolvedPluginReleaseId = "";
-let detectedOpenClawVersion = "";
+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 showCurrentVersion = false;
+let uninstallPlugin = false;
+let forceSlotExplicit = false;
+let allowOfflineExplicit = false;
 
 const selectedMode = "remote";
 const baseUrlFromEnv = !!process.env.OPENVIKING_BASE_URL;
@@ -147,11 +156,19 @@ for (let i = 0; i < argv.length; i++) {
     rollbackLastUpgrade = true;
     continue;
   }
-  if (arg === "--uninstall" || arg === "--remove") {
-    uninstallPlugin = true;
-    continue;
-  }
-  if (arg === "--workdir") {
+  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");
@@ -168,35 +185,81 @@ for (let i = 0; i < argv.length; i++) {
       console.error("--plugin-version requires a value");
       process.exit(1);
     }
-    PLUGIN_VERSION = version;
-    pluginVersionExplicit = true;
-    continue;
-  }
+    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();
-    continue;
-  }
-  if (arg === "--github-repo") {
+    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;
-    i += 1;
-    continue;
-  }
+    }
+    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); }
@@ -268,10 +331,13 @@ function setOpenClawDir(dir) {
 
 function printHelp() {
   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: latest tag)");
+  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");
@@ -282,9 +348,11 @@ function printHelp() {
   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("  --agent-prefix=PREFIX    Agent routing prefix (default: $OPENVIKING_AGENT_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("  --zh                     Chinese prompts");
+  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:");
@@ -294,11 +362,11 @@ function printHelp() {
   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=v0.2.9");
-  console.log("");
-  console.log("  # Install from a fork repository");
-  console.log("  node install.js --github-repo=yourname/OpenViking --plugin-version=dev-branch");
+  console.log("  # Install a specific release version");
+  console.log("  node install.js --plugin-version=2026.5.8");
+  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");
@@ -309,8 +377,8 @@ function printHelp() {
   console.log("  # Roll back the last plugin upgrade");
   console.log("  node install.js --rollback");
   console.log("");
-  console.log("Env: REPO, PLUGIN_VERSION, SKIP_OPENCLAW, NPM_REGISTRY");
-}
+  console.log("Env: PLUGIN_SOURCE, PLUGIN_NPM_PACKAGE, REPO, PLUGIN_VERSION, SKIP_OPENCLAW, NPM_REGISTRY");
+}
 
 function formatCliArg(value) {
   if (!value) {
@@ -403,18 +471,23 @@ function runCapture(cmd, args, opts = {}) {
   });
 }
 
-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) => {
+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 isValidAgentPrefixInput(value) {
+  });
+}
+
+function isYes(answer) {
+  const normalized = String(answer || "").trim().toLowerCase();
+  return normalized === "y" || normalized === "yes";
+}
+
+function isValidAgentPrefixInput(value) {
   const trimmed = String(value || "").trim();
   return !trimmed || /^[a-zA-Z0-9_-]+$/.test(trimmed);
 }
@@ -606,13 +679,30 @@ if (upgradePluginOnly && rollbackLastUpgrade) {
   process.exit(1);
 }
 
-if (uninstallPlugin && (upgradePluginOnly || rollbackLastUpgrade)) {
-  console.error("--uninstall cannot be used with --upgrade-plugin or --rollback");
-  process.exit(1);
-}
-
-// Detect OpenClaw version
-async function detectOpenClawVersion() {
+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;
   }
@@ -664,10 +754,10 @@ function compareSemverDesc(a, b) {
   return versionGte(a, b) ? -1 : 1;
 }
 
-function pickLatestPluginTag(tagNames) {
-  const normalized = tagNames
-    .map((tag) => String(tag ?? "").trim())
-    .filter(Boolean);
+function pickLatestPluginTag(tagNames) {
+  const normalized = tagNames
+    .map((tag) => String(tag ?? "").trim())
+    .filter(Boolean);
 
   const semverTags = normalized
     .filter((tag) => isSemverLike(tag))
@@ -676,9 +766,118 @@ function pickLatestPluginTag(tagNames) {
   if (semverTags.length > 0) {
     return semverTags[0];
   }
-
-  return normalized[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 ?? "")
@@ -690,13 +889,23 @@ function parseGitLsRemoteTags(output) {
     .filter(Boolean);
 }
 
-async function resolveDefaultPluginVersion() {
-  if (PLUGIN_VERSION) {
-    return;
-  }
-
-  info(tr(
-    `No plugin version specified; resolving latest tag from ${REPO}...`,
+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...`,
   ));
 
@@ -768,12 +977,117 @@ async function resolveDefaultPluginVersion() {
   if (failures.length > 0) {
     warn(failures.join(" | "));
   }
-  process.exit(1);
-}
-
-// Resolve plugin configuration from manifest or fallback
-async function resolvePluginConfig() {
-  const ghRaw = `https://raw.githubusercontent.com/${REPO}/${PLUGIN_VERSION}`;
+  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}`));
 
@@ -1086,11 +1400,17 @@ function extractRuntimeConfigFromPluginEntry(entryConfig) {
     runtime.apiKey = entryConfig.apiKey;
   }
   const prefix = entryConfig.agent_prefix || entryConfig.agentId;
-  if (typeof prefix === "string" && prefix.trim()) {
-    runtime.agent_prefix = prefix.trim();
-  }
-  return runtime;
-}
+  if (typeof prefix === "string" && prefix.trim()) {
+    runtime.agent_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 });
@@ -1380,10 +1700,12 @@ async function prepareStrongPluginUpgrade() {
       `检测到已安装 OpenViking 插件状态: ${installedState.generation}`,
     ),
   );
-  remoteBaseUrl = upgradeRuntimeConfig.baseUrl || remoteBaseUrl;
-  remoteApiKey = upgradeRuntimeConfig.apiKey || "";
-  remoteAgentPrefix = upgradeRuntimeConfig.agent_prefix || "";
-  info(tr(`Upgrade runtime mode: ${selectedMode} (remote OpenViking server)`, `升级运行模式: ${selectedMode}（远程 OpenViking 服务）`));
+  remoteBaseUrl = upgradeRuntimeConfig.baseUrl || remoteBaseUrl;
+  remoteApiKey = upgradeRuntimeConfig.apiKey || "";
+  remoteAgentPrefix = upgradeRuntimeConfig.agent_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}`));
 
@@ -1537,7 +1859,7 @@ async function assertBuiltRuntimeOutputs(destDir) {
   process.exit(1);
 }
 
-async function installPluginNpmDependencies(destDir) {
+async function installPluginNpmDependencies(destDir) {
   if (!resolvedNpmBuild) {
     info(tr("Installing plugin npm dependencies...", "正在安装插件 npm 依赖..."));
     const npmArgs = resolvedNpmOmitDev
@@ -1575,12 +1897,40 @@ async function installPluginNpmDependencies(destDir) {
       "--no-audit",
       "--no-fund",
     ], { cwd: destDir, silent: false });
-  }
-}
-
-async function downloadPlugin(destDir) {
-  const ghRaw = `https://raw.githubusercontent.com/${REPO}/${PLUGIN_VERSION}`;
-  const pluginDir = resolvedPluginDir;
+  }
+}
+
+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 });
@@ -1637,16 +1987,18 @@ async function finalizePluginDeployment(stagingDir) {
   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;
-  }
-}
+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() {
@@ -1768,6 +2120,53 @@ async function cleanupConflictingPluginVariants() {
   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,
@@ -1821,6 +2220,8 @@ async function configureOpenClawPlugin({
     await scrubStaleOpenClawPluginRegistration();
   }
 
+  await ensureOpenClawPluginLoadPath();
+
   // Enable plugin: try CLI first (default path), fall back to direct file for --workdir
   if (!needWorkdirFlag) {
     try {
@@ -1931,13 +2332,14 @@ async function configureOpenClawPlugin({
     }
   } catch { /* ignore read errors */ }
 
-  let setupResult = null;
-  if (setupJsonSupported) {
-    const setupArgs = ["openviking", "setup"];
-    setupArgs.push("--base-url", effectiveRuntimeConfig.baseUrl || remoteBaseUrl);
-    setupArgs.push("--json");
-    if (effectiveRuntimeConfig.apiKey) {
-      setupArgs.push("--api-key", effectiveRuntimeConfig.apiKey);
+  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.agent_prefix) {
       setupArgs.push("--agent-prefix", effectiveRuntimeConfig.agent_prefix);
@@ -1945,35 +2347,67 @@ async function configureOpenClawPlugin({
     if (effectiveRuntimeConfig.accountId) {
       setupArgs.push("--account-id", effectiveRuntimeConfig.accountId);
     }
-    if (effectiveRuntimeConfig.userId) {
-      setupArgs.push("--user-id", effectiveRuntimeConfig.userId);
-    }
-    if (claimSlot) {
-      setupArgs.push("--force-slot");
-    }
-    if (nonInteractive) {
-      setupArgs.push("--allow-offline");
-    }
-
-    info(tr(
-      "Delegating configuration to: openclaw openviking setup --json",
-      "委托配置给: openclaw openviking setup --json",
-    ));
-
-    setupResult = await runCapture("openclaw", setupArgs, { env: ocEnv, shell: IS_WIN });
-  } else {
-    info(tr(
-      "Installed plugin does not support setup --json, using direct config write",
-      "已安装的插件不支持 setup --json，使用直接配置写入",
-    ));
-  }
-
-  let parsed = null;
-  if (setupResult) {
-    parsed = parseJsonObjectFromOutput(`${setupResult.out || ""}\n${setupResult.err || ""}`);
-  }
-
-  if (parsed) {
+    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) {
@@ -1991,32 +2425,37 @@ async function configureOpenClawPlugin({
       if (parsed.slot?.activated) {
         info(tr(`contextEngine slot activated`, `contextEngine slot 已激活`));
       }
-    } else {
-      // Setup returned success: false
-      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: ${parsed.error || "unknown error"}`,
-          `配置失败: ${parsed.error || "未知错误"}`,
-        ));
-        return {
-          runtimeConfigOk: false,
-          error: parsed.error || parsed.action || "unknown error",
-        };
-      }
-    }
-  } else if (setupResult && setupResult.code !== 0) {
-    warn(tr(
-      `openclaw openviking setup exited with code ${setupResult.code}. Falling back to direct JSON config write.`,
-      `openclaw openviking setup 退出码 ${setupResult.code}，回退到直接写入 JSON 配置。`,
-    ));
-  }
-
-  if (!parsed) {
+    } 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.
@@ -2153,7 +2592,7 @@ async function performUninstall() {
       tr("Confirm uninstall? (y/N)", "确认卸载？(y/N)"),
       "N",
     );
-    if (answer.toLowerCase() !== "y" && answer.toLowerCase() !== "yes") {
+    if (!isYes(answer)) {
       info(tr("Cancelled.", "已取消。"));
       return;
     }
@@ -2262,11 +2701,16 @@ async function main() {
     await rollbackLastUpgradeOperation();
     return;
   }
-  await resolveDefaultPluginVersion();
-  validateRequestedPluginVersion();
-  info(tr(`Target: ${OPENCLAW_DIR}`, `目标实例: ${OPENCLAW_DIR}`));
-  info(tr(`Repository: ${REPO}`, `仓库: ${REPO}`));
-  info(tr(`Plugin version: ${PLUGIN_VERSION}`, `插件版本: ${PLUGIN_VERSION}`));
+  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", "模式: 仅升级插件"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-openviking-setup-helper",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Setup helper for installing OpenViking memory plugin into OpenClaw",
   "type": "module",
   "bin": {