oh-langfuse 0.1.60 → 0.1.62

package/scripts/langfuse-setup.mjs

@@ -81,7 +81,7 @@ function extractZipWithPowerShell({ zipPath, destDir }) {
   const cmd = cmdParts.join(" ");
 
   try {
-    execFileSync("powershell", ["-NoProfile", "-Command", cmd], { stdio: "inherit" });
+    execFileSync("powershell", ["-NoProfile", "-Command", cmd], { stdio: "inherit", encoding: "utf8" });
   } catch {
     throw new Error("解压 hooks zip 失败：请确认 zip 文件存在，且 PowerShell 支持 Expand-Archive。");
   }
@@ -97,7 +97,7 @@ function downloadAndExtractZipWithPowerShell({ zipUrl, destDir }) {
   ].join(" ");
 
   try {
-    execFileSync("powershell", ["-NoProfile", "-Command", cmd], { stdio: "inherit" });
+    execFileSync("powershell", ["-NoProfile", "-Command", cmd], { stdio: "inherit", encoding: "utf8" });
   } catch (e) {
     const msg = e?.message ? String(e.message) : "";
     if (msg.includes("(401)") || msg.toLowerCase().includes("unauthorized")) {
@@ -176,7 +176,7 @@ function writeAutoUpdateHelper(target) {
       "exit /b 0",
       ""
     ];
-    fs.writeFileSync(helper, lines.join(os.EOL), "utf8");
+    fs.writeFileSync(helper, "\ufeff" + lines.join(os.EOL), "utf8");
     return helper;
   }
 
@@ -263,7 +263,7 @@ function prependWindowsUserPath(dir) {
     "  [Environment]::SetEnvironmentVariable('Path', $next, 'User');",
     "}"
   ].join(" ");
-  const result = spawnSync("powershell", ["-NoProfile", "-Command", cmd], { stdio: "inherit", windowsHide: true });
+  const result = spawnSync("powershell", ["-NoProfile", "-Command", cmd], { stdio: "inherit", windowsHide: true, encoding: "utf8" });
   if (result.status !== 0) throw new Error("Failed to prepend Claude Langfuse shim to the user PATH.");
 
   const currentParts = String(process.env.PATH || "").split(path.delimiter);
@@ -294,7 +294,7 @@ function writeAgentCommandShim({ baseDir, target, executable, realCli, publicKey
       "exit /b %ERRORLEVEL%",
       ""
     ].filter(Boolean).join(os.EOL);
-    fs.writeFileSync(shim, content, "utf8");
+    fs.writeFileSync(shim, "\ufeff" + content, "utf8");
     return { shim, shimDir };
   }
 
@@ -326,7 +326,7 @@ function createAgentLauncher({ baseDir, target, executable }) {
       `${executable} %*`,
       ""
     ].join(os.EOL);
-    fs.writeFileSync(launcher, content, "utf8");
+    fs.writeFileSync(launcher, "\ufeff" + content, "utf8");
     return launcher;
   }
 
@@ -343,54 +343,54 @@ function createAgentLauncher({ baseDir, target, executable }) {
   return launcher;
 }
 
-function pythonExecutableInVenv(venvDir) {
-  return process.platform === "win32"
-    ? path.join(venvDir, "Scripts", "python.exe")
-    : path.join(venvDir, "bin", "python");
-}
-
-function pythonCanImport(pythonCmd, moduleName) {
-  try {
-    execFileSync(pythonCmd, ["-c", `import ${moduleName}`], { stdio: "ignore" });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function runPipInstallWithFallback({ pythonCmd, pipIndexUrl }) {
-  const attempts = [
-    { command: pythonCmd, args: ["-m", "pip", "install", "--user", "-U", "langfuse", "-i", pipIndexUrl] },
-    { command: "pip3", args: ["install", "--user", "-U", "langfuse", "-i", pipIndexUrl] },
-    { command: "pip", args: ["install", "--user", "-U", "langfuse", "-i", pipIndexUrl] }
-  ];
-
-  const errors = [];
-  for (const attempt of attempts) {
-    try {
-      console.log(`Trying Python package install: ${attempt.command} ${attempt.args.join(" ")}`);
-      execFileSync(attempt.command, attempt.args, { stdio: "inherit" });
-      return;
-    } catch (error) {
-      errors.push(`${attempt.command}: ${error?.message || error}`);
-    }
-  }
-
-  throw new Error(
-    `Failed to install langfuse with system Python/pip. Tried python -m pip, pip3, and pip. Last errors: ${errors.join(" | ")}`
-  );
-}
-
-function installLangfuseWithSystemPython({ pythonCmd, pipIndexUrl }) {
-  console.log("Python venv is unavailable; falling back to system Python user install for langfuse.");
-  runPipInstallWithFallback({ pythonCmd, pipIndexUrl });
-  if (!pythonCanImport(pythonCmd, "langfuse")) {
-    throw new Error("langfuse was installed with pip, but python3 still cannot import it. Install python3-venv and rerun setup, for example: sudo apt install python3-venv");
-  }
-  return pythonCmd;
-}
-
-async function createHookLauncher({ hooksDir, hookPython, pyPath }) {
+function pythonExecutableInVenv(venvDir) {
+  return process.platform === "win32"
+    ? path.join(venvDir, "Scripts", "python.exe")
+    : path.join(venvDir, "bin", "python");
+}
+
+function pythonCanImport(pythonCmd, moduleName) {
+  try {
+    execFileSync(pythonCmd, ["-c", `import ${moduleName}`], { stdio: "ignore", encoding: "utf8", env: { ...process.env, PYTHONUTF8: "1" } });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function runPipInstallWithFallback({ pythonCmd, pipIndexUrl }) {
+  const attempts = [
+    { command: pythonCmd, args: ["-m", "pip", "install", "--user", "-U", "langfuse", "-i", pipIndexUrl] },
+    { command: "pip3", args: ["install", "--user", "-U", "langfuse", "-i", pipIndexUrl] },
+    { command: "pip", args: ["install", "--user", "-U", "langfuse", "-i", pipIndexUrl] }
+  ];
+
+  const errors = [];
+  for (const attempt of attempts) {
+    try {
+      console.log(`Trying Python package install: ${attempt.command} ${attempt.args.join(" ")}`);
+      execFileSync(attempt.command, attempt.args, { stdio: "inherit", encoding: "utf8", env: { ...process.env, PYTHONUTF8: "1" } });
+      return;
+    } catch (error) {
+      errors.push(`${attempt.command}: ${error?.message || error}`);
+    }
+  }
+
+  throw new Error(
+    `Failed to install langfuse with system Python/pip. Tried python -m pip, pip3, and pip. Last errors: ${errors.join(" | ")}`
+  );
+}
+
+function installLangfuseWithSystemPython({ pythonCmd, pipIndexUrl }) {
+  console.log("Python venv is unavailable; falling back to system Python user install for langfuse.");
+  runPipInstallWithFallback({ pythonCmd, pipIndexUrl });
+  if (!pythonCanImport(pythonCmd, "langfuse")) {
+    throw new Error("langfuse was installed with pip, but python3 still cannot import it. Install python3-venv and rerun setup, for example: sudo apt install python3-venv");
+  }
+  return pythonCmd;
+}
+
+async function createHookLauncher({ hooksDir, hookPython, pyPath }) {
   if (process.platform === "win32") {
     const launcher = path.join(hooksDir, "run-langfuse-hook.cmd");
     const content = [
@@ -398,7 +398,7 @@ async function createHookLauncher({ hooksDir, hookPython, pyPath }) {
       `${cmdQuote(hookPython)} ${cmdQuote(pyPath)}`,
       ""
     ].join(os.EOL);
-    await fsp.writeFile(launcher, content, "utf8");
+    await fsp.writeFile(launcher, "\ufeff" + content, "utf8");
     return launcher;
   }
 
@@ -420,14 +420,14 @@ function createOrUpdateLangfuseVenv({ baseDir, pipIndexUrl = "https://pypi.tuna.
 
   if (!fs.existsSync(venvPython)) {
     console.log(`Creating Python virtual environment: ${venvDir}`);
-    try {
-      execFileSync(pythonCmd, ["-m", "venv", venvDir], { stdio: "inherit" });
-    } catch (e) {
-      if (process.platform !== "win32") {
-        return installLangfuseWithSystemPython({ pythonCmd, pipIndexUrl });
-      }
-      throw new Error("Failed to create Python venv. Please confirm Python venv support is available.");
-    }
+    try {
+      execFileSync(pythonCmd, ["-m", "venv", venvDir], { stdio: "inherit", encoding: "utf8", env: { ...process.env, PYTHONUTF8: "1" } });
+    } catch (e) {
+      if (process.platform !== "win32") {
+        return installLangfuseWithSystemPython({ pythonCmd, pipIndexUrl });
+      }
+      throw new Error("Failed to create Python venv. Please confirm Python venv support is available.");
+    }
   }
 
   console.log("Installing/updating Python package in venv: langfuse");
@@ -435,14 +435,14 @@ function createOrUpdateLangfuseVenv({ baseDir, pipIndexUrl = "https://pypi.tuna.
     execFileSync(
       venvPython,
       ["-m", "pip", "install", "-U", "langfuse", "-i", pipIndexUrl],
-      { stdio: "inherit" }
-    );
-  } catch (e) {
-    if (process.platform !== "win32") {
-      return installLangfuseWithSystemPython({ pythonCmd, pipIndexUrl });
-    }
-    throw new Error(`Failed to install langfuse in venv: ${venvPython} -m pip install -U langfuse -i ${pipIndexUrl}`);
-  }
+      { stdio: "inherit", encoding: "utf8", env: { ...process.env, PYTHONUTF8: "1" } }
+    );
+  } catch (e) {
+    if (process.platform !== "win32") {
+      return installLangfuseWithSystemPython({ pythonCmd, pipIndexUrl });
+    }
+    throw new Error(`Failed to install langfuse in venv: ${venvPython} -m pip install -U langfuse -i ${pipIndexUrl}`);
+  }
 
   return venvPython;
 }

package/scripts/opencode-langfuse-run.mjs

@@ -1,20 +1,20 @@
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { spawnSync } from "node:child_process";
-import { resolveOpencodeCli } from "./resolve-opencode-cli.mjs";
-
-const USER_ID_PATTERN = /^[a-z](?:\d{8}|wx\d{7})$/;
-const USER_ID_PATTERN_TEXT = "^[a-z](?:\\d{8}|wx\\d{7})$";
-
-function normalizeUserId(v) {
-  return String(v || "").trim();
-}
-
-function assertValidUserId(userId) {
-  if (!USER_ID_PATTERN.test(normalizeUserId(userId))) {
-    throw new Error(`User ID must match ${USER_ID_PATTERN_TEXT}, for example h00613222 or hwx1234567.`);
-  }
-}
+import { spawnSync } from "node:child_process";
+import { resolveOpencodeCli } from "./resolve-opencode-cli.mjs";
+
+const USER_ID_PATTERN = /^[a-z](?:\d{8}|wx\d{7})$/;
+const USER_ID_PATTERN_TEXT = "^[a-z](?:\\d{8}|wx\\d{7})$";
+
+function normalizeUserId(v) {
+  return String(v || "").trim();
+}
+
+function assertValidUserId(userId) {
+  if (!USER_ID_PATTERN.test(normalizeUserId(userId))) {
+    throw new Error(`User ID must match ${USER_ID_PATTERN_TEXT}, for example h00613222 or hwx1234567.`);
+  }
+}
 
 function parseArgs(argv) {
   const args = {};
@@ -31,7 +31,7 @@ function parseArgs(argv) {
 }
 
 function runNodeScript(scriptPath, extraArgs = []) {
-  const r = spawnSync(process.execPath, [scriptPath, ...extraArgs], { stdio: "inherit" });
+  const r = spawnSync(process.execPath, [scriptPath, ...extraArgs], { stdio: "inherit", encoding: "utf8" });
   if (r.status !== 0) process.exit(r.status ?? 1);
 }
 
@@ -42,12 +42,12 @@ function main() {
     args.publicKey || process.env.LANGFUSE_PUBLIC_KEY || "pk-lf-da0c90a7-6e93-4eb7-bb86-c1047c8d187d";
   const secretKey =
     args.secretKey || process.env.LANGFUSE_SECRET_KEY || "sk-lf-0269b85d-bfdc-442c-bfa3-e737954e3315";
-  const baseUrl = args.langfuseBaseUrl || process.env.LANGFUSE_BASEURL || "http://120.46.221.227:3000";
-  const userId = normalizeUserId(args.userId || args.userid || "");
-  if (!userId) {
-    throw new Error("Missing userId. Run with --userId=your-id.");
-  }
-  assertValidUserId(userId);
+  const baseUrl = args.langfuseBaseUrl || process.env.LANGFUSE_BASEURL || "http://120.46.221.227:3000";
+  const userId = normalizeUserId(args.userId || args.userid || "");
+  if (!userId) {
+    throw new Error("Missing userId. Run with --userId=your-id.");
+  }
+  assertValidUserId(userId);
 
   // 1) 先执行 setup：默认会写入 Windows 用户级 LANGFUSE_*（从桌面/开始菜单启动 OpenCode 也能读到）
   const scriptsDir = path.dirname(fileURLToPath(import.meta.url));
@@ -89,7 +89,7 @@ function main() {
 
   console.log(`启动 OpenCode：${resolved} ${cmdArgs.join(" ")}`.trim() + ". userId: " + (userId || "<none>"));
   const useShell = process.platform === "win32" && /\.(cmd|bat)$/i.test(resolved);
-  const r = spawnSync(resolved, cmdArgs, { stdio: "inherit", env, shell: useShell });
+  const r = spawnSync(resolved, cmdArgs, { stdio: "inherit", encoding: "utf8", env, shell: useShell });
   if (r.error?.code === "ENOENT") {
     console.error(
       `无法执行 "${resolved}"。若这是 .cmd，请尝试：npm run opencode:langfuse:run -- --cmd=${path.join(

package/scripts/opencode-langfuse-setup.mjs

@@ -510,45 +510,45 @@ function getPatchedLangfuseDistIndexJs() {
     "  const processor = new LangfuseSpanProcessor({ publicKey, secretKey, baseUrl, environment });",
     "  const spanProcessors = [processor, createMetricsSpanProcessor(userId)];",
     "  if (userId) spanProcessors.push(createUserIdSpanProcessor(userId));",
-    "",
-    "  const sdk = new NodeSDK({ spanProcessors });",
-    "  const sdkStartPromise = Promise.resolve().then(() => sdk.start()).catch((err) => {",
-    '    log("warn", `OTEL SDK start failed: ${err?.message ?? err}`);',
-    "  });",
-    "  const getMetricsTracer = () => trace.getTracer('oh-langfuse-opencode-metrics');",
-    "  const knownSkillNames = await collectKnownSkillNames();",
-    "  const startupSkillUsages = detectOpencodeSkillUsages(process.argv.join('\\n'), knownSkillNames);",
+    "",
+    "  const sdk = new NodeSDK({ spanProcessors });",
+    "  const sdkStartPromise = Promise.resolve().then(() => sdk.start()).catch((err) => {",
+    '    log("warn", `OTEL SDK start failed: ${err?.message ?? err}`);',
+    "  });",
+    "  const getMetricsTracer = () => trace.getTracer('oh-langfuse-opencode-metrics');",
+    "  const knownSkillNames = await collectKnownSkillNames();",
+    "  const startupSkillUsages = detectOpencodeSkillUsages(process.argv.join('\\n'), knownSkillNames);",
     "  const messageTextById = new Map();",
     "  const skillUsagesByMessageId = new Map();",
     "  const skillUsagesBySessionId = new Map();",
     "  const startupSkillSessionIds = new Set();",
     "  const toolCallIdsByMessageId = new Map();",
     "  const toolCallIdsBySessionId = new Map();",
-    "  const toolResultIdsByMessageId = new Map();",
-    "  const toolResultIdsBySessionId = new Map();",
-    "  const emittedMessageIds = new Set();",
-    "",
+    "  const toolResultIdsByMessageId = new Map();",
+    "  const toolResultIdsBySessionId = new Map();",
+    "  const emittedMessageIds = new Set();",
+    "",
     '  log("info", `OTEL tracing initialized -> ${baseUrl}`);',
     '  if (userId) log("info", `LANGFUSE userId configured -> ${userId}`);',
     '  if (knownSkillNames.length) log("info", `OpenCode skills discovered -> ${knownSkillNames.length}`);',
     "",
-    "  let shutdownStarted = false;",
-    "  const flush = async (reason) => {",
-    "    try {",
-    '      log("info", `Flushing OTEL spans on ${reason}`);',
-    "      await sdkStartPromise;",
-    "      await processor.forceFlush();",
+    "  let shutdownStarted = false;",
+    "  const flush = async (reason) => {",
+    "    try {",
+    '      log("info", `Flushing OTEL spans on ${reason}`);',
+    "      await sdkStartPromise;",
+    "      await processor.forceFlush();",
     "    } catch (error) {",
     '      log("warn", `OTEL forceFlush failed on ${reason}: ${error?.message ?? error}`);',
     "    }",
     "  };",
     "  const shutdown = async (reason) => {",
-    "    if (shutdownStarted) return;",
-    "    shutdownStarted = true;",
-    "    try {",
-    '      log("info", `Shutting down OTEL SDK on ${reason}`);',
-    "      await sdkStartPromise;",
-    "      await sdk.shutdown();",
+    "    if (shutdownStarted) return;",
+    "    shutdownStarted = true;",
+    "    try {",
+    '      log("info", `Shutting down OTEL SDK on ${reason}`);',
+    "      await sdkStartPromise;",
+    "      await sdk.shutdown();",
     "    } catch (error) {",
     '      log("warn", `OTEL shutdown failed on ${reason}: ${error?.message ?? error}`);',
     "    }",
@@ -586,7 +586,7 @@ function getPatchedLangfuseDistIndexJs() {
     "    }",
     "    set.add(activity.toolCallId || `${kind}:${set.size + 1}`);",
     "  };",
-    "  const recordInteractionMetric = async (event) => {",
+    "  const recordInteractionMetric = async (event) => {",
     "    const payload = eventPayload(event);",
     "    const part = eventPart(event);",
     "    const partType = part?.type ?? '';",
@@ -617,8 +617,8 @@ function getPatchedLangfuseDistIndexJs() {
     "    const tokenMetrics = tokenMetricsFromPart(part);",
     "    const total = tokenMetrics.total ?? (tokenMetrics.input !== undefined && tokenMetrics.output !== undefined ? tokenMetrics.input + tokenMetrics.output : undefined);",
     "    const tokenAvailable = [tokenMetrics.input, tokenMetrics.output, total, tokenMetrics.cacheRead, tokenMetrics.reasoning].some((value) => value !== undefined);",
-    "    await sdkStartPromise;",
-    "    const span = getMetricsTracer().startSpan('OpenCode Agent Turn');",
+    "    await sdkStartPromise;",
+    "    const span = getMetricsTracer().startSpan('OpenCode Agent Turn');",
     "    const text = messageTextById.get(messageId) || '';",
     "    const skillUsages = dedupeSkillUsages([...(skillUsagesByMessageId.get(messageId) ?? []), ...(skillUsagesBySessionId.get(sessionId) ?? [])]);",
     "    const interactionId = `opencode:${userId || \"unknown\"}:${sessionId || \"unknown\"}:${messageId}`;",
@@ -674,9 +674,9 @@ function getPatchedLangfuseDistIndexJs() {
     '        log("warn", "OpenTelemetry experimental feature is disabled in Opencode config - tracing disabled");',
     "      }",
     "    },",
-    "    event: async ({ event }) => {",
-    "      const eventType = pickEventString(event?.name, event?.type, eventPayload(event)?.name, eventPayload(event)?.type);",
-    "      await recordInteractionMetric(event);",
+    "    event: async ({ event }) => {",
+    "      const eventType = pickEventString(event?.name, event?.type, eventPayload(event)?.name, eventPayload(event)?.type);",
+    "      await recordInteractionMetric(event);",
     '      if (eventType === "session.idle" || eventType === "message.updated" || eventType === "message.part.updated" || eventType === "session.updated" || eventType === "session.idle.1" || eventType === "message.updated.1" || eventType === "message.part.updated.1" || eventType === "session.updated.1") {',
     "        await flush(eventType);",
     "      }",
@@ -719,7 +719,7 @@ function writeWindowsLauncherCmd(opencodeDir, { publicKey, secretKey, baseUrl, u
   cmd.push("  exit /b %ERRORLEVEL%");
   cmd.push(")");
   cmd.push("opencode %*");
-  fs.writeFileSync(p, cmd.join("\r\n") + "\r\n", "utf8");
+  fs.writeFileSync(p, "\ufeff" + cmd.join("\r\n") + "\r\n", "utf8");
   return p;
 }
 
@@ -754,7 +754,7 @@ function writeAutoUpdateHelper(target) {
       "exit /b 0",
       ""
     ];
-    fs.writeFileSync(helper, lines.join(os.EOL), "utf8");
+    fs.writeFileSync(helper, "\ufeff" + lines.join(os.EOL), "utf8");
     return helper;
   }
 
@@ -802,7 +802,7 @@ function writeWindowsUpdateCheckScript(dir) {
     "}",
     ""
   ].join("\r\n");
-  fs.writeFileSync(p, ps, "utf8");
+  fs.writeFileSync(p, "\ufeff" + ps, "utf8");
   return p;
 }
 
@@ -820,7 +820,7 @@ function writeOpencodeCommandShim(opencodeDir, { publicKey, secretKey, baseUrl,
     cmd.push(windowsAutoUpdateCommand("opencode"));
     cmd.push(`call ${cmdQuote(realOpencodeCli)} %*`);
     cmd.push("exit /b %ERRORLEVEL%");
-    fs.writeFileSync(shim, cmd.join("\r\n") + "\r\n", "utf8");
+    fs.writeFileSync(shim, "\ufeff" + cmd.join("\r\n") + "\r\n", "utf8");
     return { shim, shimDir };
   }
 
@@ -925,17 +925,32 @@ function printNpmDiagnostics() {
   } catch (_) {}
 }
 
-function runNpmInstallCapture(npmArgs) {
+/**
+ * 重置终端状态，防止子进程异常退出后遗留 ANSI 转义序列。
+ */
+function resetTerminalState() {
+  if (process.stdout.isTTY) {
+    // \x1b[0m    - 重置所有颜色和属性
+    // \x1b[?25h  - 显示光标（防止 npm 隐藏光标后未恢复）
+    // \x1b[r     - 重置滚动区域
+    process.stdout.write('\x1b[0m\x1b[?25h\x1b[r');
+  }
+}
+
+function runNpmInstallCapture(npmArgs, options = {}) {
   return new Promise((resolve) => {
     const cliJs = getNpmCliJsPath();
     const npmExe = getNpmExecutable();
     const command = fs.existsSync(cliJs) ? process.execPath : npmExe;
     const args = fs.existsSync(cliJs) ? [cliJs, ...npmArgs] : npmArgs;
     const useShell = process.platform === "win32" && !fs.existsSync(cliJs) && /\.(cmd|bat)$/i.test(npmExe);
+    const timeoutMs = options.timeoutMs ?? 600000; // 默认 10 分钟超时
+
     const child = spawn(command, args, {
       encoding: "utf8",
       shell: useShell,
-      windowsHide: true
+      windowsHide: true,
+      timeout: timeoutMs
     });
     let stdout = "";
     let stderr = "";
@@ -960,12 +975,23 @@ function runNpmInstallCapture(npmArgs) {
     });
     child.on("error", (error) => {
       clearInterval(timer);
+      resetTerminalState();
       resolve({ status: null, stdout, stderr, error });
     });
     child.on("close", (status) => {
       clearInterval(timer);
+      if (status !== 0) {
+        resetTerminalState();
+      }
       resolve({ status, stdout, stderr });
     });
+    child.on("timeout", () => {
+      clearInterval(timer);
+      console.error("");
+      console.error(`npm install timed out after ${Math.round(timeoutMs / 1000)}s, killing process...`);
+      resetTerminalState();
+      child.kill('SIGTERM');
+    });
   });
 }
 
@@ -974,29 +1000,78 @@ function npmInstallLooksLikeMissingVersion(result) {
   return text.includes("etarget") || text.includes("notarget") || text.includes("no matching version found");
 }
 
-function isOfficialNpmRegistry(registry) {
-  return /^https?:\/\/registry\.npmjs\.org\/?$/i.test(String(registry || "").trim());
-}
-
-const OFFICIAL_NPM_REGISTRY = "https://registry.npmjs.org/";
-
-async function runNpmInstallOrThrow({ opencodeDir, pkgName = "opencode-plugin-langfuse", npmRegistry = "" }) {
-  const npmArgs = ["install", pkgName, "--prefix", opencodeDir, "--package-lock=false", "--no-save", "--audit=false", "--fund=false"];
-  const effectiveRegistry = npmRegistry || OFFICIAL_NPM_REGISTRY;
-  npmArgs.push("--registry", effectiveRegistry);
-  const cliJs = getNpmCliJsPath();
-  console.log(`使用 npm：${fs.existsSync(cliJs) ? `node ${cliJs}` : getNpmExecutable()}`);
-  console.log(`使用 npm registry：${effectiveRegistry}`);
-  console.log("Installing OpenCode Langfuse plugin. This can take a few minutes on slow networks...");
-  let r = await runNpmInstallCapture(npmArgs);
-  if (!r.error && r.status !== 0 && npmInstallLooksLikeMissingVersion(r) && !isOfficialNpmRegistry(effectiveRegistry)) {
-    console.error("");
-    console.error(`npm registry appears to be missing a package version. Retrying with ${OFFICIAL_NPM_REGISTRY} ...`);
-    const retryArgs = ["install", pkgName, "--prefix", opencodeDir, "--package-lock=false", "--no-save", "--audit=false", "--fund=false", "--registry", OFFICIAL_NPM_REGISTRY];
-    r = await runNpmInstallCapture(retryArgs);
-    if (!r.error && r.status === 0) return;
-  }
+function isOfficialNpmRegistry(registry) {
+  return /^https?:\/\/registry\.npmjs\.org\/?$/i.test(String(registry || "").trim());
+}
+
+const OFFICIAL_NPM_REGISTRY = "https://registry.npmjs.org/";
+const DEFAULT_NPM_REGISTRY = "https://registry.npmmirror.com/";
+
+function isChinaNetwork() {
+  const tz = Intl.DateTimeFormat().resolvedOptions().timeZone || "";
+  return tz.includes("Shanghai") || tz.includes("Chongqing") || tz.includes("Harbin");
+}
+
+async function checkInstalledVersion(opencodeDir, pkgName) {
+  const pkgJsonPath = path.join(opencodeDir, "node_modules", pkgName, "package.json");
+  if (!fs.existsSync(pkgJsonPath)) return null;
+  try {
+    const txt = stripBom(fs.readFileSync(pkgJsonPath, "utf8"));
+    if (!txt.trim()) return null;
+    const installed = parseJsonRelaxed(txt, pkgJsonPath);
+    return installed?.version || null;
+  } catch {
+    return null;
+  }
+}
+
+async function runNpmInstallOrThrow({ opencodeDir, pkgName = "opencode-plugin-langfuse", npmRegistry = "" }) {
+  const installedVersion = await checkInstalledVersion(opencodeDir, pkgName);
+  const currentVersion = packageJson.version;
+
+  if (installedVersion === currentVersion) {
+    console.log(`插件版本 ${currentVersion} 已安装，跳过 npm install ...`);
+    return;
+  }
+
+  if (installedVersion) {
+    console.log(`插件版本 ${installedVersion} 已安装，升级到 ${currentVersion} ...`);
+  }
+
+  const isOfficial = npmRegistry && isOfficialNpmRegistry(npmRegistry);
+  const effectiveRegistry = npmRegistry || (isChinaNetwork() ? DEFAULT_NPM_REGISTRY : OFFICIAL_NPM_REGISTRY);
+
+  const npmArgs = [
+    "install", pkgName, "--prefix", opencodeDir,
+    "--package-lock=false", "--no-save",
+    "--audit=false", "--fund=false",
+    "--prefer-offline",
+    "--registry", effectiveRegistry
+  ];
+
+  const cliJs = getNpmCliJsPath();
+  console.log(`使用 npm：${fs.existsSync(cliJs) ? `node ${cliJs}` : getNpmExecutable()}`);
+  console.log(`使用 npm registry：${effectiveRegistry}`);
+  console.log("Installing OpenCode Langfuse plugin. This can take a few minutes on slow networks...");
+
+  let r = await runNpmInstallCapture(npmArgs, { timeoutMs: 600000 });
+
+  if (!r.error && r.status !== 0 && npmInstallLooksLikeMissingVersion(r) && !isOfficialNpmRegistry(effectiveRegistry)) {
+    console.error("");
+    console.error(`npm registry appears to be missing a package version. Retrying with ${OFFICIAL_NPM_REGISTRY} ...`);
+    const retryArgs = [
+      "install", pkgName, "--prefix", opencodeDir,
+      "--package-lock=false", "--no-save",
+      "--audit=false", "--fund=false",
+      "--prefer-offline",
+      "--registry", OFFICIAL_NPM_REGISTRY
+    ];
+    r = await runNpmInstallCapture(retryArgs, { timeoutMs: 600000 });
+    if (!r.error && r.status === 0) return;
+  }
+
   if (!r.error && r.status === 0) return;
+
   printNpmDiagnostics();
   const npmLabel = fs.existsSync(cliJs) ? `node ${cliJs}` : getNpmExecutable();
   throw new Error(
@@ -1005,20 +1080,20 @@ async function runNpmInstallOrThrow({ opencodeDir, pkgName = "opencode-plugin-la
   );
 }
 
-function setWindowsUserEnv({ publicKey, secretKey, baseUrl }) {
+function setWindowsUserEnv({ publicKey, secretKey, baseUrl }) {
   const cmd = [
     "$ErrorActionPreference = 'Stop';",
     `[Environment]::SetEnvironmentVariable('LANGFUSE_PUBLIC_KEY', ${psQuote(publicKey)}, 'User');`,
     `[Environment]::SetEnvironmentVariable('LANGFUSE_SECRET_KEY', ${psQuote(secretKey)}, 'User');`,
     `[Environment]::SetEnvironmentVariable('LANGFUSE_BASEURL', ${psQuote(baseUrl)}, 'User');`
-  ].join(" ");
-  const r = spawnSync("powershell", ["-NoProfile", "-Command", cmd], { stdio: "inherit" });
+].join(" ");
+  const r = spawnSync("powershell", ["-NoProfile", "-Command", cmd], { stdio: "inherit", encoding: "utf8" });
   if (r.status !== 0) {
-    throw new Error("写入用户级环境变量失败（PowerShell SetEnvironmentVariable）。");
-  }
-}
-
-function prependWindowsUserPath(dir) {
+    throw new Error("写入用户级环境变量失败。");
+  }
+}
+
+function prependWindowsUserPath(dir) {
   if (process.platform !== "win32") return false;
   const cmd = [
     "$ErrorActionPreference = 'Stop';",
@@ -1033,7 +1108,7 @@ function prependWindowsUserPath(dir) {
     "  [Environment]::SetEnvironmentVariable('Path', $next, 'User');",
     "}"
   ].join(" ");
-  const r = spawnSync("powershell", ["-NoProfile", "-Command", cmd], { stdio: "inherit" });
+  const r = spawnSync("powershell", ["-NoProfile", "-Command", cmd], { stdio: "inherit", encoding: "utf8" });
   if (r.status !== 0) {
     throw new Error("写入用户 PATH 失败：无法把 OpenCode Langfuse shim 加入 PATH。");
   }
@@ -1110,7 +1185,7 @@ async function main() {
     throw new Error("缺少参数：--userId=你的工号");
   }
   assertValidUserId(userId);
-  const npmRegistry = args.npmRegistry || process.env.OPENCODE_NPM_REGISTRY || "";
+  const npmRegistry = args.npmRegistry || process.env.OPENCODE_NPM_REGISTRY || "";
 
   const home = os.homedir();
   const opencodeDir = path.join(home, ".config", "opencode");
@@ -1213,7 +1288,7 @@ async function main() {
           "$ErrorActionPreference = 'Stop';",
           `[Environment]::SetEnvironmentVariable('LANGFUSE_USER_ID', ${psQuote(userId)}, 'User');`
         ].join(" ");
-        spawnSync("powershell", ["-NoProfile", "-Command", cmd], { stdio: "inherit" });
+        spawnSync("powershell", ["-NoProfile", "-Command", cmd], { stdio: "inherit", encoding: "utf8" });
       }
       if (opencodeShim?.shimDir) {
         prependWindowsUserPath(opencodeShim.shimDir);