oh-langfuse 0.1.11 → 0.1.12

package/README.md

@@ -43,6 +43,8 @@ npm 发布后运行：
 npx oh-langfuse@latest
 ```
 
+建议始终带 `@latest` 运行，避免 npx 使用本地缓存里的旧版本。
+
 交互界面支持：
 
 - `Up` / `Down`：移动选项；
@@ -74,15 +76,15 @@ oh-langfuse check codex
 oh-langfuse setup --dry-run
 ```
 
-本仓内也可以直接运行脚本：
+本仓内也可以直接运行脚本。面向用户排查时，推荐使用 `npx oh-langfuse@latest check ...`，这样不依赖源码目录：
 
 ```bash
 npm run claude:setup
 npm run opencode:setup
 npm run codex:setup
-npm run claude:check
-npm run opencode:check
-npm run codex:check
+npx oh-langfuse@latest check claude
+npx oh-langfuse@latest check opencode
+npx oh-langfuse@latest check codex
 ```
 
 ## 各目标工具写入的配置
@@ -97,8 +99,10 @@ npm run codex:check
 
 安装并 patch `opencode-plugin-langfuse`，在
 `~/.config/opencode/opencode.json` 中启用 OpenTelemetry，写入插件用户配置，
-并可写入用户级 `LANGFUSE_*` 环境变量。Windows 下还会生成
-`launch-opencode-langfuse.cmd`，用于带环境变量启动 OpenCode。
+并可写入用户级 `LANGFUSE_*` 环境变量。Windows 下会生成
+`launch-opencode-langfuse.cmd`，Linux/macOS 下会生成
+`launch-opencode-langfuse.sh`，用于在 shell 环境变量未生效时显式带
+Langfuse 配置启动 OpenCode。
 
 ### Codex
 
@@ -122,6 +126,7 @@ Langfuse observation，并把读取偏移记录到 `~/.codex/langfuse/state.json
 | `LANGFUSE_USER_ID` / `CC_USER_ID` | 用户标识或员工号 |
 | `CODEX_HOME` | 自定义 Codex home 目录 |
 | `OPENCODE_SKIP_PLUGIN_INSTALL` | OpenCode 插件已准备好时跳过 npm 安装 |
+| `OPENCODE_NPM_REGISTRY` | OpenCode 插件 npm 安装源，例如 `https://registry.npmmirror.com` |
 
 交互界面不会明文打印 secret key。
 

package/bin/cli.js

@@ -467,10 +467,10 @@ async function collectLangfuseConfig(rl, { requireUserId = false } = {}) {
     labelValue("Public Key", config.publicKey, t.blue),
     labelValue("Secret Key", "configured", t.teal)
   ]);
-  config.userId = await askText(rl, "User ID / employee number, for example h00613222", {
-    defaultValue: config.userId,
-    required: requireUserId
-  });
+  config.userId = await askText(rl, "User ID / employee number, for example h00613222", {
+    defaultValue: requireUserId ? "" : config.userId,
+    required: requireUserId
+  });
   return config;
 }
 
@@ -480,14 +480,18 @@ async function collectSharedConfig(rl, options) {
   return await collectLangfuseConfig(rl, { requireUserId: true });
 }
 
-function commonLangfuseArgs(config) {
-  return [
-    `--langfuseBaseUrl=${config.baseUrl}`,
-    `--publicKey=${config.publicKey}`,
-    `--secretKey=${config.secretKey}`,
-    ...(hasValue(config.userId) ? [`--userId=${config.userId}`] : [])
-  ];
-}
+function commonLangfuseArgs(config) {
+  return [
+    `--langfuseBaseUrl=${config.baseUrl}`,
+    `--publicKey=${config.publicKey}`,
+    `--secretKey=${config.secretKey}`,
+    ...(hasValue(config.userId) ? [`--userId=${config.userId}`] : [])
+  ];
+}
+
+function optionalInstallerArgs(options) {
+  return [...(hasValue(options.pipIndexUrl) ? [`--pipIndexUrl=${options.pipIndexUrl}`] : [])];
+}
 
 async function confirmAction(rl, title, rows, options) {
   clearScreen();
@@ -506,7 +510,7 @@ async function setupClaude(rl, options) {
   const defaultHook = path.join(rootDir, "langfuse_hook.py");
   const pyPath = fs.existsSync(defaultHook) ? defaultHook : path.join(rootDir, "langfuse_hook.py");
 
-  const args = [...commonLangfuseArgs(config), `--pyPath=${pyPath}`];
+  const args = [...commonLangfuseArgs(config), ...optionalInstallerArgs(options), `--pyPath=${pyPath}`];
   const ok = await confirmAction(
     rl,
     "Claude Code Langfuse Setup",
@@ -522,7 +526,7 @@ async function setupClaude(rl, options) {
   return runNodeScript("langfuse-setup.mjs", args, options);
 }
 
-async function setupOpenCode(rl, options) {
+async function setupOpenCode(rl, options) {
   while (!(await ensureEnvironment(rl, "opencode", options))) {}
   clearScreen();
   renderBrand(options);
@@ -531,9 +535,10 @@ async function setupOpenCode(rl, options) {
   const installPlugin = true;
   const cliPath = "";
 
-  const args = [
-    ...commonLangfuseArgs(config),
-    ...(!setEnv ? ["--no-set-env"] : []),
+  const args = [
+    ...commonLangfuseArgs(config),
+    ...(hasValue(options.npmRegistry) ? [`--npmRegistry=${options.npmRegistry}`] : []),
+    ...(!setEnv ? ["--no-set-env"] : []),
     ...(!installPlugin ? ["--skip-plugin-install"] : []),
     ...(hasValue(cliPath) ? [`--cmd=${cliPath}`] : [])
   ];
@@ -561,7 +566,7 @@ async function setupCodex(rl, options) {
   const defaultHook = path.join(rootDir, "codex_langfuse_notify.py");
   const pyPath = fs.existsSync(defaultHook) ? defaultHook : path.join(rootDir, "codex_langfuse_notify.py");
 
-  const args = [...commonLangfuseArgs(config), `--pyPath=${pyPath}`];
+  const args = [...commonLangfuseArgs(config), ...optionalInstallerArgs(options), `--pyPath=${pyPath}`];
   const ok = await confirmAction(
     rl,
     "Codex Langfuse Setup",
@@ -682,8 +687,10 @@ async function setupLangfuseMenu(rl, options) {
 
 function printHelp() {
   renderBrand({ dryRun: false });
-  console.log("");
-  renderSection("Usage", [
+  console.log("");
+  renderSection("Usage", [
+    "npx oh-langfuse@latest",
+    "npx oh-langfuse@latest check opencode",
     "oh-langfuse",
     "oh-langfuse setup",
     "oh-langfuse setup claude",
@@ -695,15 +702,21 @@ function printHelp() {
     "oh-langfuse check opencode",
     "oh-langfuse check codex"
   ]);
-  renderSection("Options", [
-    `${paint("--dry-run", t.gold)}  Preview actions without writing files or installing packages.`,
-    `${paint("--help", t.gold)}     Show this help.`
-  ]);
-}
+  renderSection("Options", [
+    `${paint("--dry-run", t.gold)}  Preview actions without writing files or installing packages.`,
+    `${paint("--npmRegistry=URL", t.gold)}  Use a specific npm registry when installing the OpenCode plugin.`,
+    `${paint("--pipIndexUrl=URL", t.gold)}  Use a specific pip index for Python Langfuse installs.`,
+    `${paint("--help", t.gold)}     Show this help.`
+  ]);
+}
 
-async function main() {
-  const args = parseArgs(process.argv.slice(2));
-  const options = { dryRun: !!args["dry-run"] };
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const options = {
+    dryRun: !!args["dry-run"],
+    npmRegistry: args.npmRegistry || "",
+    pipIndexUrl: args.pipIndexUrl || ""
+  };
   const [cmd, target] = args._;
 
   if (args.help || args.h) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-langfuse",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "private": false,
   "type": "module",
   "description": "Use npm scripts to configure Claude Code / OpenCode / Codex with Langfuse tracing.",

package/scripts/codex-langfuse-check.mjs

@@ -49,9 +49,13 @@ function venvPython(codexHome) {
     : path.join(codexHome, "langfuse-venv", "bin", "python");
 }
 
-function configHasNotify(configText) {
-  return /^\s*notify\s*=.*codex_langfuse_notify\.py/m.test(configText);
-}
+function configHasNotify(configText) {
+  return /^\s*notify\s*=.*codex_langfuse_notify\.py/m.test(configText);
+}
+
+function addResult(results, item, ok, detail, fix = "") {
+  results.push({ item, ok, detail, fix });
+}
 
 function main() {
   const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
@@ -66,36 +70,66 @@ function main() {
   const python = commandOk(process.platform === "win32" ? "python" : "python3", ["--version"]);
   const langfuseImport = commandOk(hookPython, ["-c", "import langfuse; print('langfuse ok')"]);
 
-  const results = [
-    { item: "Codex home", ok: fs.existsSync(codexHome), detail: codexHome },
-    { item: "config.toml", ok: fs.existsSync(configPath), detail: configPath },
-    {
-      item: "notify hook configured",
-      ok: configHasNotify(configText),
-      detail: configHasNotify(configText) ? "OK" : "missing notify entry for codex_langfuse_notify.py",
-    },
-    { item: "hook script", ok: fs.existsSync(hookPath), detail: hookPath },
-    { item: "Langfuse config", ok: !!langfuseConfig, detail: langfuseConfigPath },
-    {
-      item: "Langfuse keys",
-      ok: !!(langfuseConfig?.publicKey && langfuseConfig?.secretKey),
-      detail: langfuseConfig?.publicKey ? "configured" : "missing",
-    },
-    { item: "sessions directory", ok: fs.existsSync(sessionsDir), detail: sessionsDir },
-    { item: "latest session JSONL", ok: !!latestSession, detail: latestSession || "not found" },
-    { item: "Python", ok: python.ok, detail: python.detail || "not found" },
-    { item: "Langfuse venv Python", ok: fs.existsSync(hookPython), detail: hookPython },
-    { item: "Python langfuse package", ok: langfuseImport.ok, detail: langfuseImport.detail || "not importable from venv" },
-  ];
+  const logPath = path.join(codexHome, "langfuse", "codex_langfuse_notify.log");
+  const logText = fs.existsSync(logPath) ? stripBom(fs.readFileSync(logPath, "utf8")) : "";
+  const recentLogHasError = /Traceback|ERROR|Exception|Failed/i.test(logText.slice(-4000));
+
+  const results = [];
+  addResult(results, "Codex home", fs.existsSync(codexHome), codexHome, "Run: npx oh-langfuse@latest setup codex");
+  addResult(results, "config.toml", fs.existsSync(configPath), configPath, "Run setup again to update Codex config.");
+  addResult(
+    results,
+    "notify hook configured",
+    configHasNotify(configText),
+    configHasNotify(configText) ? "OK" : "missing notify entry for codex_langfuse_notify.py",
+    "Run setup again, then restart Codex."
+  );
+  addResult(results, "hook script", fs.existsSync(hookPath), hookPath, "Run setup again to install the notify hook.");
+  addResult(results, "Langfuse config", !!langfuseConfig, langfuseConfigPath, "Run setup again to write Langfuse credentials.");
+  addResult(
+    results,
+    "Langfuse keys",
+    !!(langfuseConfig?.publicKey && langfuseConfig?.secretKey),
+    langfuseConfig?.publicKey ? "configured" : "missing",
+    "Provide publicKey/secretKey or use the defaults from the installer."
+  );
+  addResult(results, "sessions directory", fs.existsSync(sessionsDir), sessionsDir, "Start Codex once so session JSONL files are created.");
+  addResult(results, "latest session JSONL", !!latestSession, latestSession || "not found", "Start a Codex conversation, then check again.");
+  addResult(results, "Python", python.ok, python.detail || "not found", "Install Python and pip, then rerun setup.");
+  addResult(results, "Langfuse venv Python", fs.existsSync(hookPython), hookPython, "Run setup again; on Linux install python3-venv if venv creation fails.");
+  addResult(
+    results,
+    "Python langfuse package",
+    langfuseImport.ok,
+    langfuseImport.detail || "not importable from venv",
+    "Run setup again, or pass --pipIndexUrl=https://pypi.tuna.tsinghua.edu.cn/simple."
+  );
+  addResult(
+    results,
+    "notify log recent errors",
+    !recentLogHasError,
+    fs.existsSync(logPath) ? logPath : "log not created yet",
+    "Open the log path above and inspect the newest error after running Codex."
+  );
 
   const w = Math.max(...results.map((r) => r.item.length)) + 2;
   const pad = (s, n) => (s.length >= n ? s : s + " ".repeat(n - s.length));
-  for (const r of results) {
-    const status = r.ok ? "OK " : "BAD";
-    console.log(`${status}  ${pad(r.item, w)} ${r.detail}`);
-  }
-
-  process.exit(results.some((r) => !r.ok) ? 2 : 0);
-}
+  const failed = [];
+  for (const r of results) {
+    const status = r.ok ? "OK " : "BAD";
+    console.log(`${status}  ${pad(r.item, w)} ${r.detail}`);
+    if (!r.ok) failed.push(r);
+  }
+
+  if (failed.length) {
+    console.log("");
+    console.log("Fix suggestions:");
+    for (const r of failed) {
+      if (r.fix) console.log(`- ${r.item}: ${r.fix}`);
+    }
+  }
+
+  process.exit(failed.length ? 2 : 0);
+}
 
 main();

package/scripts/codex-langfuse-setup.mjs

@@ -50,7 +50,7 @@ function pythonExecutableInVenv(venvDir) {
     : path.join(venvDir, "bin", "python");
 }
 
-function createOrUpdateLangfuseVenv({ baseDir }) {
+function createOrUpdateLangfuseVenv({ baseDir, pipIndexUrl = "https://pypi.tuna.tsinghua.edu.cn/simple" }) {
   const venvDir = path.join(baseDir, "langfuse-venv");
   const pythonCmd = process.platform === "win32" ? "python" : "python3";
   const venvPython = pythonExecutableInVenv(venvDir);
@@ -71,12 +71,12 @@ function createOrUpdateLangfuseVenv({ baseDir }) {
   try {
     execFileSync(
       venvPython,
-      ["-m", "pip", "install", "-U", "langfuse", "-i", "https://pypi.tuna.tsinghua.edu.cn/simple"],
-      { stdio: "inherit" }
-    );
-  } catch (e) {
-    throw new Error(`Failed to install langfuse in venv: ${venvPython} -m pip install -U langfuse -i https://pypi.tuna.tsinghua.edu.cn/simple`);
-  }
+      ["-m", "pip", "install", "-U", "langfuse", "-i", pipIndexUrl],
+      { stdio: "inherit" }
+    );
+  } catch (e) {
+    throw new Error(`Failed to install langfuse in venv: ${venvPython} -m pip install -U langfuse -i ${pipIndexUrl}`);
+  }
 
   return venvPython;
 }
@@ -128,7 +128,11 @@ async function main() {
     process.env.LANGFUSE_BASEURL ||
     process.env.LANGFUSE_HOST ||
     "http://120.46.221.227:3000";
-  const userId = args.userId || args.userid || process.env.LANGFUSE_USER_ID || process.env.CC_USER_ID || "";
+  const userId = args.userId || args.userid || "";
+  if (!userId || typeof userId !== "string") {
+    throw new Error("缺少参数：--userId=你的工号");
+  }
+  const pipIndexUrl = args.pipIndexUrl || process.env.LANGFUSE_PIP_INDEX_URL || "https://pypi.tuna.tsinghua.edu.cn/simple";
 
   if (!publicKey || !secretKey) {
     throw new Error("Missing Langfuse keys: provide --publicKey and --secretKey or set LANGFUSE_PUBLIC_KEY/LANGFUSE_SECRET_KEY.");
@@ -159,9 +163,9 @@ async function main() {
   });
 
   const pythonCmd = process.platform === "win32" ? "python" : "python3";
-  const notifyPython = args["skip-pip-install"]
-    ? pythonCmd
-    : createOrUpdateLangfuseVenv({ baseDir: codexHome });
+  const notifyPython = args["skip-pip-install"]
+    ? pythonCmd
+    : createOrUpdateLangfuseVenv({ baseDir: codexHome, pipIndexUrl });
   updateCodexNotify(configPath, [notifyPython, destHook]);
 
   console.log(`Updated Codex notify hook: ${configPath}`);

package/scripts/langfuse-setup.mjs

@@ -124,7 +124,7 @@ function pythonExecutableInVenv(venvDir) {
     : path.join(venvDir, "bin", "python");
 }
 
-function createOrUpdateLangfuseVenv({ baseDir }) {
+function createOrUpdateLangfuseVenv({ baseDir, pipIndexUrl = "https://pypi.tuna.tsinghua.edu.cn/simple" }) {
   const venvDir = path.join(baseDir, "langfuse-venv");
   const pythonCmd = process.platform === "win32" ? "python" : "python3";
   const venvPython = pythonExecutableInVenv(venvDir);
@@ -145,12 +145,12 @@ function createOrUpdateLangfuseVenv({ baseDir }) {
   try {
     execFileSync(
       venvPython,
-      ["-m", "pip", "install", "-U", "langfuse", "-i", "https://pypi.tuna.tsinghua.edu.cn/simple"],
-      { stdio: "inherit" }
-    );
-  } catch (e) {
-    throw new Error(`Failed to install langfuse in venv: ${venvPython} -m pip install -U langfuse -i https://pypi.tuna.tsinghua.edu.cn/simple`);
-  }
+      ["-m", "pip", "install", "-U", "langfuse", "-i", pipIndexUrl],
+      { stdio: "inherit" }
+    );
+  } catch (e) {
+    throw new Error(`Failed to install langfuse in venv: ${venvPython} -m pip install -U langfuse -i ${pipIndexUrl}`);
+  }
 
   return venvPython;
 }
@@ -158,10 +158,10 @@ function createOrUpdateLangfuseVenv({ baseDir }) {
 async function main() {
   const args = parseArgs(process.argv.slice(2));
 
-  const userId = args.userId || args.userid || process.env.CC_USER_ID;
-  if (!userId || typeof userId !== "string") {
-    throw new Error("缺少参数：--userId=你的工号（或设置环境变量 CC_USER_ID）");
-  }
+  const userId = args.userId || args.userid;
+  if (!userId || typeof userId !== "string") {
+    throw new Error("缺少参数：--userId=你的工号");
+  }
 
   const langfuseHost =
     args.langfuseHost ||
@@ -171,8 +171,9 @@ async function main() {
 
   const publicKey =
     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 secretKey =
+    args.secretKey || process.env.LANGFUSE_SECRET_KEY || "sk-lf-0269b85d-bfdc-442c-bfa3-e737954e3315";
+  const pipIndexUrl = args.pipIndexUrl || process.env.LANGFUSE_PIP_INDEX_URL || "https://pypi.tuna.tsinghua.edu.cn/simple";
   if (!publicKey || !secretKey) {
     throw new Error("缺少 Langfuse Key：请提供 --publicKey=... --secretKey=...（或设置环境变量 LANGFUSE_PUBLIC_KEY/LANGFUSE_SECRET_KEY）");
   }
@@ -225,7 +226,7 @@ async function main() {
   if (nextPyText !== pyText) {
     await fsp.writeFile(pyPath, nextPyText, "utf8");
   }
-  const hookPython = createOrUpdateLangfuseVenv({ baseDir: claudeDir });
+  const hookPython = createOrUpdateLangfuseVenv({ baseDir: claudeDir, pipIndexUrl });
 
   // 4) 合并写入 settings.json
   const settingsPath = path.join(claudeDir, "settings.json");

package/scripts/opencode-langfuse-check.mjs

@@ -1,95 +1,197 @@
-import fs from "node:fs";
-import path from "node:path";
-import os from "node:os";
-
-function stripBom(s) {
-  if (typeof s !== "string" || s.length === 0) return s;
-  return s.charCodeAt(0) === 0xfeff ? s.slice(1) : s;
-}
-
-function readJsonIfExists(p) {
-  if (!fs.existsSync(p)) return null;
-  const txt = stripBom(fs.readFileSync(p, "utf8"));
-  if (!txt.trim()) return null;
-  return JSON.parse(txt);
-}
-
-function hasPlugin(pluginField, name) {
-  if (Array.isArray(pluginField)) return pluginField.includes(name);
-  if (typeof pluginField === "string") return pluginField === name;
-  return false;
-}
-
-function main() {
-  const home = os.homedir();
-  const opencodeDir = path.join(home, ".config", "opencode");
-  const pkgDir = path.join(opencodeDir, "node_modules", "opencode-plugin-langfuse");
-  const pluginDest = path.join(opencodeDir, "plugins", "opencode-plugin-langfuse");
-  const langfusePluginPath = "./plugins/opencode-plugin-langfuse";
-  const opencodeJsonPath = path.join(opencodeDir, "opencode.json");
-
-  const results = [];
-
-  results.push({ item: "OpenCode 配置目录", ok: fs.existsSync(opencodeDir), detail: opencodeDir });
-
-  const settings = readJsonIfExists(opencodeJsonPath);
-  results.push({
-    item: "opencode.json",
-    ok: !!settings,
-    detail: opencodeJsonPath
-  });
-
-  const otOk = !!(settings?.experimental?.openTelemetry === true);
-  results.push({
-    item: "experimental.openTelemetry",
-    ok: otOk,
-    detail: otOk ? "true" : String(settings?.experimental?.openTelemetry ?? "缺失")
-  });
-
-  const plOk = hasPlugin(settings?.plugin, langfusePluginPath);
-  results.push({
-    item: `plugin 包含 ${langfusePluginPath}`,
-    ok: plOk,
-    detail: JSON.stringify(settings?.plugin ?? null)
-  });
-
-  results.push({
-    item: "npm 包目录 node_modules/opencode-plugin-langfuse",
-    ok: fs.existsSync(pkgDir),
-    detail: pkgDir
-  });
-
-  results.push({
-    item: "plugins 目录本地插件",
-    ok: fs.existsSync(path.join(pluginDest, "package.json")),
-    detail: pluginDest
-  });
-
-  const launcherPath = path.join(opencodeDir, "launch-opencode-langfuse.cmd");
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+function stripBom(s) {
+  if (typeof s !== "string" || s.length === 0) return s;
+  return s.charCodeAt(0) === 0xfeff ? s.slice(1) : s;
+}
+
+function readTextIfExists(p) {
+  if (!fs.existsSync(p)) return "";
+  return stripBom(fs.readFileSync(p, "utf8"));
+}
+
+function readJsonIfExists(p) {
+  const txt = readTextIfExists(p);
+  if (!txt.trim()) return null;
+  return JSON.parse(txt);
+}
+
+function hasPlugin(pluginField, name) {
+  if (Array.isArray(pluginField)) return pluginField.includes(name);
+  if (typeof pluginField === "string") return pluginField === name;
+  return false;
+}
+
+function shellConfigPath() {
+  const shell = process.env.SHELL || "/bin/bash";
+  return path.join(os.homedir(), shell.includes("zsh") ? ".zshrc" : ".bashrc");
+}
+
+function isPatchedPlugin(distIndexPath) {
+  const code = readTextIfExists(distIndexPath);
+  return (
+    code.includes("LangfuseSpanProcessor") &&
+    code.includes("LANGFUSE_PUBLIC_KEY") &&
+    code.includes("createUserIdSpanProcessor")
+  );
+}
+
+function addResult(results, item, ok, detail, fix = "") {
+  results.push({ item, ok, detail, fix });
+}
+
+function main() {
+  const home = os.homedir();
+  const opencodeDir = path.join(home, ".config", "opencode");
+  const pkgDir = path.join(opencodeDir, "node_modules", "opencode-plugin-langfuse");
+  const pluginDest = path.join(opencodeDir, "plugins", "opencode-plugin-langfuse");
+  const langfusePluginPath = "./plugins/opencode-plugin-langfuse";
+  const opencodeJsonPath = path.join(opencodeDir, "opencode.json");
+  const pluginDistIndex = path.join(pluginDest, "dist", "index.js");
+  const nodeModulesDistIndex = path.join(pkgDir, "dist", "index.js");
+  const userConfigPath = path.join(home, ".config", "opencode-plugin-langfuse", "config.json");
+  const windowsLauncherPath = path.join(opencodeDir, "launch-opencode-langfuse.cmd");
+  const unixLauncherPath = path.join(opencodeDir, "launch-opencode-langfuse.sh");
+
+  const results = [];
+
+  addResult(
+    results,
+    "OpenCode config dir",
+    fs.existsSync(opencodeDir),
+    opencodeDir,
+    "Run: npx oh-langfuse@latest setup opencode"
+  );
+
+  const settings = readJsonIfExists(opencodeJsonPath);
+  addResult(results, "opencode.json", !!settings, opencodeJsonPath, "Run setup again to create OpenCode config.");
+
+  const otOk = !!(settings?.experimental?.openTelemetry === true);
+  addResult(
+    results,
+    "experimental.openTelemetry",
+    otOk,
+    otOk ? "true" : String(settings?.experimental?.openTelemetry ?? "missing"),
+    "Run: npx oh-langfuse@latest setup opencode"
+  );
+
+  const plOk = hasPlugin(settings?.plugin, langfusePluginPath);
+  addResult(
+    results,
+    `plugin contains ${langfusePluginPath}`,
+    plOk,
+    JSON.stringify(settings?.plugin ?? null),
+    "Run setup again so opencode.json points at the local plugin copy."
+  );
+
+  addResult(
+    results,
+    "npm package",
+    fs.existsSync(path.join(pkgDir, "package.json")),
+    pkgDir,
+    "Install may have failed. Try: npx oh-langfuse@latest setup opencode --npmRegistry=https://registry.npmmirror.com"
+  );
+
+  addResult(
+    results,
+    "local plugin copy",
+    fs.existsSync(path.join(pluginDest, "package.json")),
+    pluginDest,
+    "Run setup again; OpenCode loads ./plugins/opencode-plugin-langfuse from opencode.json."
+  );
+
+  addResult(
+    results,
+    "local plugin patch",
+    isPatchedPlugin(pluginDistIndex),
+    pluginDistIndex,
+    "Run setup again to patch Langfuse credentials/userId injection into the plugin."
+  );
+
+  addResult(
+    results,
+    "node_modules plugin patch",
+    isPatchedPlugin(nodeModulesDistIndex),
+    nodeModulesDistIndex,
+    "Run setup again to patch the installed npm package before copying it."
+  );
+
+  const userConfig = readJsonIfExists(userConfigPath);
+  addResult(
+    results,
+    "OpenCode Langfuse user config",
+    !!(userConfig?.userId || userConfig?.usrid),
+    userConfigPath,
+    "Run setup again and enter userId when prompted."
+  );
+
+  const hasPublicKey = !!process.env.LANGFUSE_PUBLIC_KEY;
+  const hasSecretKey = !!process.env.LANGFUSE_SECRET_KEY;
+  const hasBaseUrl = !!process.env.LANGFUSE_BASEURL;
+  addResult(
+    results,
+    "current terminal LANGFUSE_*",
+    hasPublicKey && hasSecretKey && hasBaseUrl,
+    `publicKey=${hasPublicKey ? "set" : "missing"}, secretKey=${hasSecretKey ? "set" : "missing"}, baseUrl=${
+      hasBaseUrl ? process.env.LANGFUSE_BASEURL : "missing"
+    }`,
+    process.platform === "win32"
+      ? "Open a new terminal or launch with ~/.config/opencode/launch-opencode-langfuse.cmd."
+      : "Open a new terminal, source your shell rc file, or launch with ~/.config/opencode/launch-opencode-langfuse.sh."
+  );
+
   if (process.platform === "win32") {
-    results.push({
-      item: "启动脚本 launch-opencode-langfuse.cmd",
-      ok: fs.existsSync(launcherPath),
-      detail: launcherPath
-    });
-  }
-
-  const hasPk = !!process.env.LANGFUSE_PUBLIC_KEY;
-  results.push({
-    item: "当前进程 LANGFUSE_PUBLIC_KEY（任选终端验证）",
-    ok: hasPk,
-    detail: hasPk ? "已设置（本终端可见）" : "未设置：若你只从桌面打开 OpenCode，请先运行 npm run opencode:langfuse:setup 或使用 launch-opencode-langfuse.cmd"
-  });
-
-  const w = Math.max(...results.map((r) => r.item.length)) + 2;
-  for (const r of results) {
-    const status = r.ok ? "OK " : "BAD";
-    const pad = (s, n) => (s.length >= n ? s : s + " ".repeat(n - s.length));
-    console.log(`${status}  ${pad(r.item, w)} ${r.detail}`);
-  }
-
-  const failed = results.filter((r) => !r.ok);
-  process.exit(failed.length ? 2 : 0);
-}
-
-main();
+    addResult(
+      results,
+      "launcher cmd",
+      fs.existsSync(windowsLauncherPath),
+      windowsLauncherPath,
+      "Run setup again to create a launcher with LANGFUSE_* variables."
+    );
+  } else {
+    const shellRc = shellConfigPath();
+    const shellRcText = readTextIfExists(shellRc);
+    addResult(
+      results,
+      "shell rc LANGFUSE_* block",
+      shellRcText.includes("# === Langfuse OpenCode Setup ===") && shellRcText.includes("LANGFUSE_PUBLIC_KEY"),
+      shellRc,
+      "Run setup again, then open a new terminal or source the shown shell rc file."
+    );
+    addResult(
+      results,
+      "launcher sh",
+      fs.existsSync(unixLauncherPath),
+      unixLauncherPath,
+      "Run setup again to create a launcher with LANGFUSE_* variables."
+    );
+  }
+
+  const w = Math.max(...results.map((r) => r.item.length)) + 2;
+  const failed = [];
+  for (const r of results) {
+    const status = r.ok ? "OK " : "BAD";
+    const pad = (s, n) => (s.length >= n ? s : s + " ".repeat(n - s.length));
+    console.log(`${status}  ${pad(r.item, w)} ${r.detail}`);
+    if (!r.ok) failed.push(r);
+  }
+
+  if (failed.length) {
+    console.log("");
+    console.log("Fix suggestions:");
+    for (const r of failed) {
+      if (r.fix) console.log(`- ${r.item}: ${r.fix}`);
+    }
+  }
+
+  process.exit(failed.length ? 2 : 0);
+}
+
+try {
+  main();
+} catch (e) {
+  console.error(e?.message || String(e));
+  process.exit(1);
+}

package/scripts/opencode-langfuse-run.mjs

@@ -29,8 +29,11 @@ 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 = args.userId || args.userid || process.env.LANGFUSE_USER_ID || "";
+  const baseUrl = args.langfuseBaseUrl || process.env.LANGFUSE_BASEURL || "http://120.46.221.227:3000";
+  const userId = args.userId || args.userid || "";
+  if (!userId) {
+    throw new Error("Missing userId. Run with --userId=your-id.");
+  }
 
   // 1) 先执行 setup：默认会写入 Windows 用户级 LANGFUSE_*（从桌面/开始菜单启动 OpenCode 也能读到）
   const scriptsDir = path.dirname(fileURLToPath(import.meta.url));

package/scripts/opencode-langfuse-setup.mjs

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 
 function parseArgs(argv) {
   const args = {};
@@ -202,9 +202,9 @@ function syncPluginPackageToLocalPlugins({ pkgDir, pluginDest, pluginsDir }) {
   fs.cpSync(pkgDir, pluginDest, { recursive: true });
 }
 
-function writeWindowsLauncherCmd(opencodeDir, { publicKey, secretKey, baseUrl, userId }) {
-  if (process.platform !== "win32") return null;
-  const p = path.join(opencodeDir, "launch-opencode-langfuse.cmd");
+function writeWindowsLauncherCmd(opencodeDir, { publicKey, secretKey, baseUrl, userId }) {
+  if (process.platform !== "win32") return null;
+  const p = path.join(opencodeDir, "launch-opencode-langfuse.cmd");
   const cmd = ["@echo off", "REM Auto-generated by scripts/opencode-langfuse-setup.mjs"];
   cmd.push(`set LANGFUSE_PUBLIC_KEY=${publicKey}`);
   cmd.push(`set LANGFUSE_SECRET_KEY=${secretKey}`);
@@ -215,9 +215,35 @@ 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");
-  return p;
-}
+  fs.writeFileSync(p, cmd.join("\r\n") + "\r\n", "utf8");
+  return p;
+}
+
+function shQuote(s) {
+  return `'${String(s).replace(/'/g, "'\"'\"'")}'`;
+}
+
+function writeUnixLauncherSh(opencodeDir, { publicKey, secretKey, baseUrl, userId }) {
+  if (process.platform === "win32") return null;
+  const p = path.join(opencodeDir, "launch-opencode-langfuse.sh");
+  const lines = [
+    "#!/usr/bin/env sh",
+    "# Auto-generated by scripts/opencode-langfuse-setup.mjs",
+    "set -eu",
+    `export LANGFUSE_PUBLIC_KEY=${shQuote(publicKey)}`,
+    `export LANGFUSE_SECRET_KEY=${shQuote(secretKey)}`,
+    `export LANGFUSE_BASEURL=${shQuote(baseUrl)}`,
+    userId ? `export LANGFUSE_USER_ID=${shQuote(userId)}` : null,
+    'if [ -x "$HOME/.opencode/bin/opencode" ]; then',
+    '  exec "$HOME/.opencode/bin/opencode" "$@"',
+    "fi",
+    'exec opencode "$@"',
+    ""
+  ].filter(Boolean);
+  fs.writeFileSync(p, lines.join("\n"), "utf8");
+  fs.chmodSync(p, 0o755);
+  return p;
+}
 
 function getNpmExecutable() {
   if (process.platform === "win32") {
@@ -278,14 +304,54 @@ function printNpmDiagnostics() {
   } catch (_) {}
 }
 
-function runNpmInstallOrThrow({ opencodeDir, pkgName = "opencode-plugin-langfuse" }) {
-  const npmArgs = ["install", pkgName, "--prefix", opencodeDir];
-  const cliJs = getNpmCliJsPath();
-  console.log(`使用 npm：${fs.existsSync(cliJs) ? `node ${cliJs}` : getNpmExecutable()}`);
-  const r = runNpmCapture(npmArgs);
-  if (r.stdout) process.stdout.write(r.stdout);
-  if (r.stderr) process.stderr.write(r.stderr);
-  if (!r.error && r.status === 0) return;
+function runNpmInstallCapture(npmArgs) {
+  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 child = spawn(command, args, {
+      encoding: "utf8",
+      shell: useShell,
+      windowsHide: true
+    });
+    let stdout = "";
+    let stderr = "";
+    const started = Date.now();
+    const timer = setInterval(() => {
+      const secs = Math.round((Date.now() - started) / 1000);
+      console.error(`npm install still running (${secs}s). Slow networks can take a few minutes...`);
+    }, 15000);
+    child.stdout?.on("data", (chunk) => {
+      const text = String(chunk);
+      stdout += text;
+      process.stdout.write(text);
+    });
+    child.stderr?.on("data", (chunk) => {
+      const text = String(chunk);
+      stderr += text;
+      process.stderr.write(text);
+    });
+    child.on("error", (error) => {
+      clearInterval(timer);
+      resolve({ status: null, stdout, stderr, error });
+    });
+    child.on("close", (status) => {
+      clearInterval(timer);
+      resolve({ status, stdout, stderr });
+    });
+  });
+}
+
+async function runNpmInstallOrThrow({ opencodeDir, pkgName = "opencode-plugin-langfuse", npmRegistry = "" }) {
+  const npmArgs = ["install", pkgName, "--prefix", opencodeDir];
+  if (npmRegistry) npmArgs.push("--registry", npmRegistry);
+  const cliJs = getNpmCliJsPath();
+  console.log(`使用 npm：${fs.existsSync(cliJs) ? `node ${cliJs}` : getNpmExecutable()}`);
+  console.log("Installing OpenCode Langfuse plugin. This can take a few minutes on slow networks...");
+  const r = await runNpmInstallCapture(npmArgs);
+  if (!r.error && r.status === 0) return;
   printNpmDiagnostics();
   const npmLabel = fs.existsSync(cliJs) ? `node ${cliJs}` : getNpmExecutable();
   throw new Error(
@@ -353,7 +419,7 @@ function updateShellConfig({ publicKey, secretKey, baseUrl, userId }) {
   return configPath;
 }
 
-function main() {
+async function main() {
   const args = parseArgs(process.argv.slice(2));
   const setEnv = !args["no-set-env"];
   const skipPluginInstall =
@@ -363,32 +429,37 @@ 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 = args.userId || args.userid || process.env.LANGFUSE_USER_ID || process.env.OPENCODE_USER_ID || "";
+  const baseUrl =
+    args.langfuseBaseUrl || process.env.LANGFUSE_BASEURL || "http://120.46.221.227:3000";
+  const userId = args.userId || args.userid || "";
+  if (!userId || typeof userId !== "string") {
+    throw new Error("缺少参数：--userId=你的工号");
+  }
+  const npmRegistry = args.npmRegistry || process.env.OPENCODE_NPM_REGISTRY || process.env.NPM_CONFIG_REGISTRY || "";
 
   const home = os.homedir();
-  const opencodeDir = path.join(home, ".config", "opencode");
-  const pluginsDir = path.join(opencodeDir, "plugins");
-  const pkgDir = path.join(opencodeDir, "node_modules", "opencode-plugin-langfuse");
-  const pluginDest = path.join(pluginsDir, "opencode-plugin-langfuse");
+  const opencodeDir = path.join(home, ".config", "opencode");
+  const pluginsDir = path.join(opencodeDir, "plugins");
+  const pkgDir = path.join(opencodeDir, "node_modules", "opencode-plugin-langfuse");
+  const pkgJsonPath = path.join(pkgDir, "package.json");
+  const pluginDest = path.join(pluginsDir, "opencode-plugin-langfuse");
   const opencodeJsonPath = path.join(opencodeDir, "opencode.json");
 
   ensureDir(opencodeDir);
 
   console.log(`OpenCode 配置目录：${opencodeDir}`);
 
-  if (skipPluginInstall && fs.existsSync(pkgDir)) {
-    console.log(`已跳过 npm install（--skip-plugin-install 且已存在）：${pkgDir}`);
-  } else {
-    console.log("安装 npm 包：opencode-plugin-langfuse …");
-    runNpmInstallOrThrow({ opencodeDir });
-  }
+  if (skipPluginInstall && fs.existsSync(pkgJsonPath)) {
+    console.log(`已跳过 npm install（--skip-plugin-install 且已存在）：${pkgDir}`);
+  } else {
+    console.log("安装 npm 包：opencode-plugin-langfuse …");
+    await runNpmInstallOrThrow({ opencodeDir, npmRegistry });
+  }
 
-  if (!fs.existsSync(pkgDir)) {
-    throw new Error(
-      `未找到已安装包目录：${pkgDir}。请先解决上方 npm 报错，或手动在此目录执行 npm install opencode-plugin-langfuse。`
-    );
+  if (!fs.existsSync(pkgJsonPath)) {
+    throw new Error(
+      `未找到已安装包目录：${pkgDir}。请先解决上方 npm 报错，或手动在此目录执行 npm install opencode-plugin-langfuse。`
+    );
   }
 
   const existing = readJsonIfExists(opencodeJsonPath) ?? {};
@@ -429,11 +500,16 @@ function main() {
   writeJsonPretty(opencodeJsonPath, merged);
   console.log(`已更新：${opencodeJsonPath}`);
 
-  const launcher = writeWindowsLauncherCmd(opencodeDir, { publicKey, secretKey, baseUrl, userId });
-  if (launcher) {
+  const launcher = writeWindowsLauncherCmd(opencodeDir, { publicKey, secretKey, baseUrl, userId });
+  if (launcher) {
     console.log(`已生成快捷启动脚本（含 LANGFUSE 环境变量）：${launcher}`);
     console.log("若不从当前终端启动，也可双击或用该脚本启动 OpenCode（避免插件读不到密钥）。");
-  }
+  }
+  const unixLauncher = writeUnixLauncherSh(opencodeDir, { publicKey, secretKey, baseUrl, userId });
+  if (unixLauncher) {
+    console.log(`已生成启动脚本（含 LANGFUSE 环境变量）：${unixLauncher}`);
+    console.log(`如果新终端仍读不到环境变量，可运行：${unixLauncher}`);
+  }
 
   if (setEnv) {
     if (process.platform === "win32") {
@@ -468,12 +544,12 @@ function main() {
     }
   }
 
-  console.log("完成。可运行：`npm run opencode:langfuse:check` 校验。");
-}
+  console.log("完成。可运行：`npx oh-langfuse@latest check opencode` 校验。");
+}
 
 try {
-  main();
-} catch (e) {
+  await main();
+} catch (e) {
   console.error(e?.message || String(e));
   process.exit(1);
 }

package/setup-langfuse.bat

@@ -57,9 +57,9 @@ echo.
 call npm run claude:setup -- --userId=%USER_ID% --pyPath=%PY_PATH%
 if errorlevel 1 exit /b 1
 
-echo.
-echo Check:
-call npm run claude:check
+echo.
+echo Check:
+call npx oh-langfuse@latest check claude
 exit /b %errorlevel%
 
 :OPENCODE
@@ -72,7 +72,11 @@ echo   - NO auto-launch: open opencode in a NEW terminal afterwards
 echo.
 
 set "OC_USER_ID="
-set /p OC_USER_ID=Enter userId (optional; press Enter to skip) ^>
+set /p OC_USER_ID=Enter userId (required) ^>
+if "%OC_USER_ID%"=="" (
+  echo [ERROR] userId is required.
+  exit /b 1
+)
 
 echo.
 echo Write LANGFUSE_* to Windows user env vars (HKCU)?
@@ -94,7 +98,7 @@ set "OC_CMD="
 set /p OC_CMD=OpenCode CLI path (optional; press Enter to auto-detect) ^>
 
 set "SETUP_ARGS="
-if not "%OC_USER_ID%"=="" set "SETUP_ARGS=%SETUP_ARGS% --userId=%OC_USER_ID%"
+set "SETUP_ARGS=%SETUP_ARGS% --userId=%OC_USER_ID%"
 if /i "%OC_SET_ENV%"=="n" set "SETUP_ARGS=%SETUP_ARGS% --no-set-env"
 if /i "%OC_SET_ENV%"=="no" set "SETUP_ARGS=%SETUP_ARGS% --no-set-env"
 if /i "%OC_SKIP_INSTALL%"=="y" set "SETUP_ARGS=%SETUP_ARGS% --skip-plugin-install"
@@ -116,12 +120,13 @@ if errorlevel 1 goto :OPENCODE_FAIL
 echo.
 echo ============================================
 echo OpenCode setup finished.
-echo Next:
-echo   1) Open a NEW terminal (HKCU env vars take effect).
-echo   2) Run: opencode
-echo      Optional launcher:
-echo      %USERPROFILE%\.config\opencode\launch-opencode-langfuse.cmd
-echo ============================================
+echo Next:
+echo   1) Open a NEW terminal (HKCU env vars take effect).
+echo   2) Run: opencode
+echo      Optional launcher:
+echo      %USERPROFILE%\.config\opencode\launch-opencode-langfuse.cmd
+echo   3) Check: npx oh-langfuse@latest check opencode
+echo ============================================
 exit /b 0
 
 :CODEX
@@ -145,9 +150,9 @@ echo.
 call npm run codex:setup -- --userId=%CODEX_USER_ID% --pyPath=%CODEX_PY_PATH%
 if errorlevel 1 exit /b 1
 
-echo.
-echo Check:
-call npm run codex:check
+echo.
+echo Check:
+call npx oh-langfuse@latest check codex
 exit /b %errorlevel%
 
 :NO_NPM

package/setup-langfuse.sh

@@ -44,8 +44,8 @@ case "$choice" in
     echo "Running: npm run claude:setup -- --userId=${user_id} --pyPath=${py_path}"
     npm run claude:setup -- --userId="${user_id}" --pyPath="${py_path}"
     echo
-    echo "Check: npm run claude:check"
-    npm run claude:check
+    echo "Check: npx oh-langfuse@latest check claude"
+    npx oh-langfuse@latest check claude
     ;;
 
   2)
@@ -56,8 +56,12 @@ case "$choice" in
     echo "  - NO auto-launch: you will open opencode in a NEW terminal afterwards"
     echo
 
-    printf "Enter userId (optional; press Enter to skip) > "
-    IFS= read -r user_id || true
+    printf "Enter userId (required) > "
+    IFS= read -r user_id || true
+    if [ -z "${user_id:-}" ]; then
+      echo "[ERROR] userId is required."
+      exit 1
+    fi
 
     echo
     echo "Skip plugin install (npm install opencode-plugin-langfuse)?"
@@ -71,9 +75,7 @@ case "$choice" in
     IFS= read -r oc_cmd || true
 
     run_args=""
-    if [ -n "${user_id:-}" ]; then
-      run_args="${run_args} --userId=${user_id}"
-    fi
+    run_args="${run_args} --userId=${user_id}"
     case "${skip_install:-}" in
       y|Y|yes|YES|Yes)
         run_args="${run_args} --skip-plugin-install"
@@ -94,11 +96,14 @@ case "$choice" in
 
     echo
     echo "============================================"
-    echo "OpenCode setup finished."
-    echo "Next:"
-    echo "  1) Open a NEW terminal."
-    echo "  2) Run: opencode"
-    echo "============================================"
+    echo "OpenCode setup finished."
+    echo "Next:"
+    echo "  1) Open a NEW terminal."
+    echo "  2) Run: opencode"
+    echo "  3) Check: npx oh-langfuse@latest check opencode"
+    echo "     If LANGFUSE_* is not visible in the new terminal, run:"
+    echo "     ~/.config/opencode/launch-opencode-langfuse.sh"
+    echo "============================================"
     ;;
 
   3)
@@ -119,8 +124,8 @@ case "$choice" in
     echo "Running: npm run codex:setup -- --userId=${user_id} --pyPath=${py_path}"
     npm run codex:setup -- --userId="${user_id}" --pyPath="${py_path}"
     echo
-    echo "Check: npm run codex:check"
-    npm run codex:check
+    echo "Check: npx oh-langfuse@latest check codex"
+    npx oh-langfuse@latest check codex
     ;;
 
   *)