openclaw-openviking-setup-helper 0.3.1-beta.0 → 2026.6.18

package/install.js

@@ -9,34 +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=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
- */
+ * 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";
+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);
+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;
@@ -102,27 +102,30 @@ 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 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;
+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 remoteAgentPrefix = (process.env.OPENVIKING_AGENT_PREFIX || "").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 = "assistant";
 let remoteAccountId = (process.env.OPENVIKING_ACCOUNT_ID || "").trim();
 let remoteUserId = (process.env.OPENVIKING_USER_ID || "").trim();
 let baseUrlExplicit = baseUrlFromEnv;
@@ -156,19 +159,19 @@ for (let i = 0; i < argv.length; i++) {
     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") {
+  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");
@@ -185,81 +188,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();
-    if (!pluginSourceExplicit) {
-      pluginSource = "github";
-    }
-    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;
-    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;
-  }
+    }
+    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); }
@@ -284,15 +287,32 @@ for (let i = 0; i < argv.length; i++) {
     remoteApiKey = arg.slice("--api-key=".length).trim();
     continue;
   }
-  if (arg === "--agent-prefix") {
+  if (arg === "--peer-role") {
+    const val = argv[i + 1]?.trim();
+    if (!val) { console.error("--peer-role requires a value"); process.exit(1); }
+    const role = normalizePeerRole(val);
+    if (!role) { console.error('--peer-role must be "none", "assistant", or "person"'); process.exit(1); }
+    remotePeerRole = role;
+    peerRoleExplicit = true;
+    i += 1;
+    continue;
+  }
+  if (arg.startsWith("--peer-role=")) {
+    const role = normalizePeerRole(arg.slice("--peer-role=".length));
+    if (!role) { console.error('--peer-role must be "none", "assistant", or "person"'); process.exit(1); }
+    remotePeerRole = role;
+    peerRoleExplicit = true;
+    continue;
+  }
+  if (arg === "--peer-prefix") {
     const val = argv[i + 1]?.trim();
-    if (!val) { console.error("--agent-prefix requires a value"); process.exit(1); }
-    remoteAgentPrefix = val;
+    if (!val) { console.error("--peer-prefix requires a value"); process.exit(1); }
+    remotePeerPrefix = val;
     i += 1;
     continue;
   }
-  if (arg.startsWith("--agent-prefix=")) {
-    remoteAgentPrefix = arg.slice("--agent-prefix=".length).trim();
+  if (arg.startsWith("--peer-prefix=")) {
+    remotePeerPrefix = arg.slice("--peer-prefix=".length).trim();
     continue;
   }
   if (arg === "--account-id") {
@@ -323,6 +343,12 @@ for (let i = 0; i < argv.length; i++) {
   }
 }
 
+remotePeerRole = normalizePeerRole(remotePeerRole) || "assistant";
+if (!isValidPeerPrefixInput(remotePeerPrefix)) {
+  console.error("--peer-prefix may only contain letters, digits, underscores, and hyphens");
+  process.exit(1);
+}
+
 nonInteractive = baseUrlExplicit;
 
 function setOpenClawDir(dir) {
@@ -331,13 +357,13 @@ function setOpenClawDir(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("");
+  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");
@@ -347,12 +373,13 @@ function printHelp() {
   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("  --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("  --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("  --peer-role=ROLE         Peer role: none, assistant, or person (default: $OPENVIKING_PEER_ROLE or assistant)");
+  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:");
@@ -362,11 +389,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=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("  # 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");
@@ -377,8 +404,8 @@ function printHelp() {
   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");
-}
+  console.log("Env: PLUGIN_SOURCE, PLUGIN_NPM_PACKAGE, REPO, PLUGIN_VERSION, SKIP_OPENCLAW, NPM_REGISTRY");
+}
 
 function formatCliArg(value) {
   if (!value) {
@@ -471,27 +498,32 @@ 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 isYes(answer) {
-  const normalized = String(answer || "").trim().toLowerCase();
-  return normalized === "y" || normalized === "yes";
-}
-
-function isValidAgentPrefixInput(value) {
+  });
+}
+
+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();
+  return role === "none" || role === "assistant" || role === "person" ? role : null;
+}
+
 function parseJsonObjectFromOutput(output) {
   const text = String(output || "").trim();
   if (!text) return null;
@@ -513,18 +545,33 @@ function parseJsonObjectFromOutput(output) {
   return null;
 }
 
-async function questionAgentPrefix(defaultValue = "") {
+async function questionPeerRole(defaultValue = "assistant") {
+  while (true) {
+    const answer = await question(
+      tr("Peer Role (none/assistant/person)", "Peer Role（none/assistant/person）"),
+      defaultValue,
+    );
+    const role = normalizePeerRole(answer);
+    if (role) return role;
+    warn(tr(
+      'Peer Role must be "none", "assistant", or "person".',
+      'Peer Role 必须是 "none"、"assistant" 或 "person"。',
+    ));
+  }
+}
+
+async function questionPeerPrefix(defaultValue = "") {
   while (true) {
     const answer = (await question(
-      tr("Agent Prefix (optional)", "Agent Prefix（可选）"),
+      tr("Peer Prefix (optional)", "Peer Prefix（可选）"),
       defaultValue,
     )).trim();
-    if (isValidAgentPrefixInput(answer)) {
+    if (isValidPeerPrefixInput(answer)) {
       return answer;
     }
     warn(tr(
-      "Agent Prefix may only contain letters, digits, underscores, and hyphens, or be empty.",
-      "Agent Prefix 只能包含字母、数字、下划线和连字符，或留空。",
+      "Peer Prefix may only contain letters, digits, underscores, and hyphens, or be empty.",
+      "Peer Prefix 只能包含字母、数字、下划线和连字符，或留空。",
     ));
   }
 }
@@ -575,7 +622,10 @@ 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);
-  remoteAgentPrefix = await questionAgentPrefix(remoteAgentPrefix);
+  remotePeerRole = await questionPeerRole(remotePeerRole);
+  remotePeerPrefix = remotePeerRole === "assistant"
+    ? await questionPeerPrefix(remotePeerPrefix)
+    : "";
 }
 
 async function checkOpenClaw() {
@@ -679,30 +729,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);
-}
-
-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 (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;
   }
@@ -754,10 +804,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))
@@ -766,118 +816,118 @@ function pickLatestPluginTag(tagNames) {
   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;
-}
+
+  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 ?? "")
@@ -889,23 +939,23 @@ function parseGitLsRemoteTags(output) {
     .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}...`,
+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...`,
   ));
 
@@ -977,117 +1027,117 @@ async function resolveDefaultPluginVersion() {
   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}`;
+  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}`));
 
@@ -1164,7 +1214,8 @@ async function resolvePluginConfig() {
         const pkg = JSON.parse(pkgJson);
         const pkgName = pkg.name || "";
         resolvedPluginReleaseId = pkg.version || "";
-        if (pkgName && pkgName !== "@openclaw/openviking") {
+        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) {
@@ -1399,18 +1450,22 @@ function extractRuntimeConfigFromPluginEntry(entryConfig) {
   if (typeof entryConfig.apiKey === "string" && entryConfig.apiKey.trim()) {
     runtime.apiKey = entryConfig.apiKey;
   }
-  const prefix = entryConfig.agent_prefix || entryConfig.agentId;
-  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;
-}
+  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 });
@@ -1700,12 +1755,13 @@ async function prepareStrongPluginUpgrade() {
       `检测到已安装 OpenViking 插件状态: ${installedState.generation}`,
     ),
   );
-  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 服务）`));
+  remoteBaseUrl = upgradeRuntimeConfig.baseUrl || remoteBaseUrl;
+  remoteApiKey = upgradeRuntimeConfig.apiKey || "";
+  remotePeerRole = upgradeRuntimeConfig.peer_role || remotePeerRole || "assistant";
+  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}`));
 
@@ -1803,6 +1859,96 @@ async function downloadPluginFile(destDir, fileName, url, required, index, total
   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")) {
@@ -1859,7 +2005,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
@@ -1897,40 +2043,40 @@ async function installPluginNpmDependencies(destDir) {
       "--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;
+  }
+}
+
+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 });
@@ -1942,6 +2088,10 @@ async function downloadPlugin(destDir) {
   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);
   }
@@ -1950,6 +2100,10 @@ async function downloadPlugin(destDir) {
   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);
   }
@@ -1987,18 +2141,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;
-  } finally {
-    await cleanupNpmPackageTemp();
-  }
-}
+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() {
@@ -2272,7 +2426,8 @@ async function configureOpenClawPlugin({
     const effectiveRuntimeConfig = runtimeConfig || {
       baseUrl: remoteBaseUrl,
       apiKey: remoteApiKey,
-      agent_prefix: remoteAgentPrefix,
+      peer_role: remotePeerRole,
+      peer_prefix: remotePeerPrefix,
     };
 
     let allowedPropsLegacy = null;
@@ -2287,7 +2442,7 @@ async function configureOpenClawPlugin({
       }
     } catch { /* ignore parse errors */ }
 
-    const agentVal = effectiveRuntimeConfig.agent_prefix || "";
+    const peerVal = effectiveRuntimeConfig.peer_prefix || "";
     const candidates = {
       mode: "remote",
       baseUrl: effectiveRuntimeConfig.baseUrl || remoteBaseUrl,
@@ -2295,7 +2450,7 @@ async function configureOpenClawPlugin({
       autoRecall: true,
       autoCapture: true,
       apiKey: effectiveRuntimeConfig.apiKey || undefined,
-      agentId: agentVal || undefined,
+      peer_prefix: peerVal || undefined,
     };
 
     const pluginConfig = {};
@@ -2317,7 +2472,8 @@ async function configureOpenClawPlugin({
   const effectiveRuntimeConfig = runtimeConfig || {
     baseUrl: remoteBaseUrl,
     apiKey: remoteApiKey,
-    agent_prefix: remoteAgentPrefix,
+    peer_role: remotePeerRole,
+    peer_prefix: remotePeerPrefix,
     accountId: remoteAccountId,
     userId: remoteUserId,
   };
@@ -2332,82 +2488,85 @@ async function configureOpenClawPlugin({
     }
   } 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);
+  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.agent_prefix) {
-      setupArgs.push("--agent-prefix", effectiveRuntimeConfig.agent_prefix);
+    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 (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) {
@@ -2425,37 +2584,37 @@ async function configureOpenClawPlugin({
       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) {
+    } 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.
@@ -2471,8 +2630,9 @@ async function configureOpenClawPlugin({
       }
     } catch { /* ignore parse errors, write all fields */ }
 
-    const agentVal = effectiveRuntimeConfig.agent_prefix || "";
-    const useAgentPrefix = !allowedProps || allowedProps.has("agent_prefix");
+    const peerRole = normalizePeerRole(effectiveRuntimeConfig.peer_role) || "assistant";
+    const peerVal = effectiveRuntimeConfig.peer_prefix || "";
+    const usePeerFields = !allowedProps || allowedProps.has("peer_role") || allowedProps.has("peer_prefix");
     const candidates = {
       mode: "remote",
       baseUrl: effectiveRuntimeConfig.baseUrl || remoteBaseUrl,
@@ -2480,10 +2640,9 @@ async function configureOpenClawPlugin({
       accountId: effectiveRuntimeConfig.accountId || undefined,
       userId: effectiveRuntimeConfig.userId || undefined,
     };
-    if (useAgentPrefix) {
-      candidates.agent_prefix = agentVal;
-    } else {
-      candidates.agentId = agentVal;
+    if (usePeerFields) {
+      candidates.peer_role = peerRole;
+      if (peerVal) candidates.peer_prefix = peerVal;
     }
 
     const pluginConfig = {};
@@ -2592,7 +2751,7 @@ async function performUninstall() {
       tr("Confirm uninstall? (y/N)", "确认卸载？(y/N)"),
       "N",
     );
-    if (!isYes(answer)) {
+    if (!isYes(answer)) {
       info(tr("Cancelled.", "已取消。"));
       return;
     }
@@ -2701,16 +2860,16 @@ async function main() {
     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}`));
+  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", "模式: 仅升级插件"));