oh-langfuse 0.1.19 → 0.1.21

package/README.md

@@ -1,175 +1,126 @@
 # oh-langfuse
 
-`oh-langfuse` 是用于配置 Langfuse 链路追踪的交互式命令行工具，支持
-Claude Code、OpenCode 和 Codex。它提供终端安装向导、直接 setup/check
-命令，以及不同工具所需的安装脚本和校验脚本。
+`oh-langfuse` 是用于给 Claude Code、OpenCode 和 Codex 配置 Langfuse 追踪的命令行工具。它提供交互式安装向导，也支持 `setup` / `check` 直接命令，方便在用户机器上安装、修复和校验配置。
 
-## 项目定位
+当前 npm 版本：`0.1.21`
 
-本仓是 AI Coding 工具链中的 Langfuse 能力包，负责：
+## 能做什么
 
-- 检查 Node.js、npm、Python、pip、OpenCode CLI 等本地依赖；
-- 收集 Langfuse 用户标识，必须匹配 `^[a-z](?:\d{8}|wx\d{7})$`，例如 `h00613222` 或 `hwx1234567`；
-- 安装或更新 hook 脚本、插件文件、Python 虚拟环境和用户级配置；
-- 校验 Claude Code、OpenCode、Codex 的 Langfuse 配置是否生效。
+- 给 Claude Code 安装 `Stop` hook，把会话事件写入 Langfuse。
+- 给 OpenCode 安装并 patch `opencode-plugin-langfuse`，开启 OpenTelemetry。
+- 给 Codex 安装 `notify` hook，增量读取 session JSONL 并写入 Langfuse。
+- 安装完成后自动执行对应 `check`，尽早发现配置缺失。
+- 校验员工号格式，必须匹配 `^[a-z](?:\d{8}|wx\d{7})$`，例如 `h00613222` 或 `hwx1234567`。
 
-本包发布到 npm 后暴露 `oh-langfuse` 命令，并被聚合安装器
-`oh-aicoding-tool` 调用。
+## 快速使用
 
-迁移期内，npm 包仍保留旧命令别名 `code-tool-langfuse`。
+建议始终带 `@latest`，避免 npx 使用本地旧缓存：
 
-## 环境要求
+```bash
+npx oh-langfuse@latest
+npx oh-langfuse@latest setup
+npx oh-langfuse@latest check
+```
 
-| 目标工具 | 依赖 |
-| --- | --- |
-| Claude Code | Node.js、npm、Python、pip |
-| OpenCode | Node.js、npm、OpenCode CLI |
-| Codex | Node.js、npm、Python、pip |
+也可以指定目标：
 
-Linux 环境如果创建 Python venv 失败，请先安装 `python3-venv`。
+```bash
+npx oh-langfuse@latest setup claude
+npx oh-langfuse@latest setup opencode
+npx oh-langfuse@latest setup codex
 
-## 使用方式
+npx oh-langfuse@latest check claude
+npx oh-langfuse@latest check opencode
+npx oh-langfuse@latest check codex
+```
 
-从当前仓库运行：
+本地开发运行：
 
 ```bash
 npm install
 npm start
 ```
 
-npm 发布后运行：
+## 交互式菜单
 
-```bash
-npx oh-langfuse@latest
-```
-
-建议始终带 `@latest` 运行，避免 npx 使用本地缓存里的旧版本。
+运行 `npx oh-langfuse@latest` 会打开交互式菜单：
 
-交互界面支持：
+- `Up` / `Down` 移动选项。
+- 数字键快速定位。
+- `Space` 勾选或取消。
+- `Enter` 确认。
+- `q` 或 `Esc` 退出。
 
-- `Up` / `Down`：移动选项；
-- 数字键：快速选择；
-- `Space`：多选切换；
-- `Enter`：确认；
-- `q` 或 `Esc`：退出。
+多选菜单默认不勾选任何目标，避免误装。终端不支持原始按键输入时，会自动降级为数字输入模式。
 
-在不支持 raw input 的终端中，会自动退回到数字输入模式。
+## OpenCode 说明
 
-## 命令
+OpenCode 安装会写入：
 
-```bash
-oh-langfuse
-oh-langfuse setup
-oh-langfuse setup claude
-oh-langfuse setup opencode
-oh-langfuse setup codex
-oh-langfuse check
-oh-langfuse check environment
-oh-langfuse check claude
-oh-langfuse check opencode
-oh-langfuse check codex
-```
+- `~/.config/opencode/opencode.json`
+- `~/.config/opencode/plugins/opencode-plugin-langfuse`
+- `~/.config/opencode-plugin-langfuse/config.json`
+- Windows 下的 `~/.config/opencode/launch-opencode-langfuse.cmd`
+- Linux/macOS 下的 `~/.config/opencode/launch-opencode-langfuse.sh`
 
-预览安装动作，不写文件、不安装依赖：
+Windows 下安装器会尝试写入用户级 `LANGFUSE_PUBLIC_KEY`、`LANGFUSE_SECRET_KEY`、`LANGFUSE_BASEURL`。这些变量对当前已经打开的终端不会立即生效，需要新开终端，或者使用生成的 launcher 启动 OpenCode。
 
-```bash
-oh-langfuse setup --dry-run
-```
+`check opencode` 已按实际情况处理 Windows：如果当前终端还看不到 `LANGFUSE_*`，但用户级环境变量已写入，或 launcher 已生成，会显示 OpenCode 仍有可用的 Langfuse 环境变量来源，不再把这种情况误判为安装失败。
 
-本仓内也可以直接运行脚本。面向用户排查时，推荐使用 `npx oh-langfuse@latest check ...`，这样不依赖源码目录：
+WSL 用户请直接在 WSL shell 中安装和检查：
 
 ```bash
-npm run claude:setup
-npm run opencode:setup
-npm run codex:setup
-npx oh-langfuse@latest check claude
+npx oh-langfuse@latest setup opencode --userId=h00613222 --yes
 npx oh-langfuse@latest check opencode
-npx oh-langfuse@latest check codex
 ```
 
-## 各目标工具写入的配置
-
-### Claude Code
+不会做 Windows 到 WSL 的转发；在 WSL 中运行时，配置写入 WSL 用户自己的 `$HOME/.config/opencode`。
 
-安装 `langfuse_hook.py`，创建 `~/.claude/langfuse-venv`，安装 Python 包
-`langfuse`，并把 Langfuse 环境变量和 `Stop` hook 合并写入
-`~/.claude/settings.json`。
+## Claude Code 说明
 
-### OpenCode
-
-安装并 patch `opencode-plugin-langfuse`，在
-`~/.config/opencode/opencode.json` 中启用 OpenTelemetry，写入插件用户配置，
-并可写入用户级 `LANGFUSE_*` 环境变量。Windows 下会生成
-`launch-opencode-langfuse.cmd`，Linux/macOS 下会生成
-`launch-opencode-langfuse.sh`，用于在 shell 环境变量未生效时显式带
-Langfuse 配置启动 OpenCode。安装器可以读取带注释或尾随逗号的
-`opencode.json`，合并配置后会写回标准 JSON。
-
-如果你在 WSL 里运行 OpenCode，就在 WSL shell 里直接执行安装和检查命令。
-此时配置会写入 WSL 用户自己的 `$HOME/.config/opencode`：
-
-```bash
-npx oh-langfuse@latest setup opencode --userId=h00613222 --yes
-npx oh-langfuse@latest check opencode
-```
+Claude Code 安装会：
 
-安装完成后会自动执行一次 `check opencode`。如果检查提示当前终端缺少
-`LANGFUSE_*`，请新开一个 WSL 终端，或执行安装器提示的 `source ~/.bashrc`
-/ `source ~/.zshrc`，也可以直接使用生成的
-`~/.config/opencode/launch-opencode-langfuse.sh` 启动 OpenCode。
+- 安装 `langfuse_hook.py`
+- 创建 `~/.claude/langfuse-venv`
+- 安装 Python 包 `langfuse`
+- 合并更新 `~/.claude/settings.json`
+- 配置 `Stop` hook
 
-如果 `opencode.json` 原本是 JSONC 风格（例如带注释或尾随逗号），安装器会先兼容读取，
-再写回标准 JSON。
+Linux 如果缺少 venv 支持，请根据提示安装 `python3-venv` 或对应 Python 版本的 venv 包。
 
-### Codex
+## Codex 说明
 
-安装 `codex_langfuse_notify.py`，创建 `~/.codex/langfuse-venv`，安装 Python
-包 `langfuse`，把 Langfuse 凭据写入 `~/.codex/langfuse/config.json`，并更新
-`~/.codex/config.toml` 顶层 `notify` 命令。安装后需要重启 Codex。
+Codex 安装会：
 
-Codex 集成通过 notify hook 实现：每次通知事件会增量读取对应的
-`~/.codex/sessions/**/*.jsonl`，把新增的 user、assistant、tool、token 事件转换成
-Langfuse observation，并把读取偏移记录到 `~/.codex/langfuse/state.json`。
+- 安装 `codex_langfuse_notify.py`
+- 创建 `~/.codex/langfuse-venv`
+- 写入 `~/.codex/langfuse/config.json`
+- 更新 `~/.codex/config.toml` 顶层 `notify`
 
-## 环境变量覆盖
+配置后需要重启 Codex。notify hook 会增量读取 `~/.codex/sessions/**/*.jsonl`，把新的 user、assistant、tool、token 事件转换为 Langfuse observation，并把读取偏移记录到 `~/.codex/langfuse/state.json`。
 
-工具内置了内部 Langfuse 服务的默认值，可通过以下变量覆盖：
+## 环境变量
 
 | 变量 | 作用 |
 | --- | --- |
 | `LANGFUSE_BASEURL` / `LANGFUSE_HOST` | Langfuse 服务地址 |
 | `LANGFUSE_PUBLIC_KEY` | Langfuse public key |
 | `LANGFUSE_SECRET_KEY` | Langfuse secret key |
-| `LANGFUSE_USER_ID` / `CC_USER_ID` | 用户标识或员工号 |
+| `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。
+| `OPENCODE_SKIP_PLUGIN_INSTALL` | 跳过 OpenCode npm 插件安装 |
+| `OPENCODE_NPM_REGISTRY` | OpenCode 插件 npm 安装源 |
 
-## 目录结构
+Secret key 不会在交互式界面中明文展示。
 
-| 路径 | 说明 |
-| --- | --- |
-| `bin/cli.js` | 交互式和直接命令入口 |
-| `scripts/langfuse-setup.mjs` | Claude Code Langfuse 安装 |
-| `scripts/opencode-langfuse-setup.mjs` | OpenCode Langfuse 安装 |
-| `scripts/codex-langfuse-setup.mjs` | Codex Langfuse 安装 |
-| `scripts/*-check.mjs` | 配置校验脚本 |
-| `langfuse_hook.py` | Claude Code hook exporter |
-| `codex_langfuse_notify.py` | Codex notify exporter |
-
-## 发布与维护
-
-- npm 包名：`oh-langfuse`
-- 主命令：`oh-langfuse`
-- 兼容命令：`code-tool-langfuse`
-- 发布前建议运行：
+## 常用维护命令
 
 ```bash
 npm run check
 npm pack --dry-run
 ```
 
-维护时请保持 README 命令列表、`bin/cli.js` 和 `package.json` 的 `bin/files`
-字段一致。
+发布包暴露两个命令：
+
+- `oh-langfuse`
+- `code-tool-langfuse`，兼容旧入口

package/langfuse_hook.py

@@ -15,10 +15,18 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
 # --- Langfuse import (fail-open) ---
-try:
-    from langfuse import Langfuse, propagate_attributes
-except Exception:
-    sys.exit(0)
+try:
+    from langfuse import Langfuse, propagate_attributes
+except Exception as e:
+    try:
+        state_dir = Path.home() / ".claude" / "state"
+        state_dir.mkdir(parents=True, exist_ok=True)
+        with open(state_dir / "langfuse_hook.log", "a", encoding="utf-8") as f:
+            ts = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+            f.write(f"{ts} [ERROR] Failed to import langfuse package: {e}\n")
+    except Exception:
+        pass
+    sys.exit(0)
 
 # --- Paths ---
 STATE_DIR = Path.home() / ".claude" / "state"
@@ -325,22 +333,32 @@ def read_new_jsonl(transcript_path: Path, ss: SessionState) -> Tuple[List[Dict[s
         text = chunk.decode(errors="replace")
 
     combined = ss.buffer + text
-    lines = combined.split("\n")
-    # last element may be incomplete
-    ss.buffer = lines[-1]
-    ss.offset = new_offset
-
-    msgs: List[Dict[str, Any]] = []
-    for line in lines[:-1]:
-        line = line.strip()
+    lines = combined.split("\n")
+    tail = lines[-1]
+    ss.offset = new_offset
+
+    msgs: List[Dict[str, Any]] = []
+    for line in lines[:-1]:
+        line = line.strip()
         if not line:
             continue
         try:
             msgs.append(json.loads(line))
-        except Exception:
-            continue
-
-    return msgs, ss
+        except Exception:
+            continue
+
+    tail = tail.strip()
+    if tail:
+        try:
+            msgs.append(json.loads(tail))
+            ss.buffer = ""
+        except Exception:
+            # Keep a genuinely partial final line for the next hook run.
+            ss.buffer = tail
+    else:
+        ss.buffer = ""
+
+    return msgs, ss
 
 # ----------------- Turn assembly -----------------
 @dataclass
@@ -520,32 +538,34 @@ def main() -> int:
     start = time.time()
     debug("Hook started")
 
-    if os.environ.get("TRACE_TO_LANGFUSE", "").lower() != "true":
-        return 0
-
-    public_key = os.environ.get("CC_LANGFUSE_PUBLIC_KEY") or os.environ.get("LANGFUSE_PUBLIC_KEY")
-    secret_key = os.environ.get("CC_LANGFUSE_SECRET_KEY") or os.environ.get("LANGFUSE_SECRET_KEY")
-    host = os.environ.get("CC_LANGFUSE_BASE_URL") or os.environ.get("LANGFUSE_BASEURL") or "https://cloud.langfuse.com"
-
-    if not public_key or not secret_key:
-        return 0
-
-    payload = read_hook_payload()
-    session_id, transcript_path, user_id = extract_session_transcript_and_user(payload)
-
-    if not session_id or not transcript_path:
-        # No structured payload; fail open (do not guess)
-        debug("Missing session_id or transcript_path from hook payload; exiting.")
-        return 0
-
-    if not transcript_path.exists():
-        debug(f"Transcript path does not exist: {transcript_path}")
-        return 0
-
-    try:
-        langfuse = Langfuse(public_key=public_key, secret_key=secret_key, host=host)
-    except Exception:
-        return 0
+    if os.environ.get("TRACE_TO_LANGFUSE", "").lower() != "true":
+        return 0
+
+    public_key = os.environ.get("CC_LANGFUSE_PUBLIC_KEY") or os.environ.get("LANGFUSE_PUBLIC_KEY")
+    secret_key = os.environ.get("CC_LANGFUSE_SECRET_KEY") or os.environ.get("LANGFUSE_SECRET_KEY")
+    host = os.environ.get("CC_LANGFUSE_BASE_URL") or os.environ.get("LANGFUSE_BASEURL") or "https://cloud.langfuse.com"
+
+    if not public_key or not secret_key:
+        warn("Missing Langfuse public/secret key in hook environment; exiting.")
+        return 0
+
+    payload = read_hook_payload()
+    session_id, transcript_path, user_id = extract_session_transcript_and_user(payload)
+
+    if not session_id or not transcript_path:
+        # No structured payload; fail open (do not guess)
+        warn("Missing session_id or transcript_path from hook payload; exiting.")
+        return 0
+
+    if not transcript_path.exists():
+        warn(f"Transcript path does not exist: {transcript_path}")
+        return 0
+
+    try:
+        langfuse = Langfuse(public_key=public_key, secret_key=secret_key, host=host)
+    except Exception as e:
+        warn(f"Langfuse init failed: {e}")
+        return 0
 
     try:
         with FileLock(LOCK_FILE):
@@ -570,20 +590,21 @@ def main() -> int:
             for t in turns:
                 emitted += 1
                 turn_num = ss.turn_count + emitted
-                try:
-                    emit_turn(langfuse, session_id, user_id, turn_num, t, transcript_path)
-                except Exception as e:
-                    debug(f"emit_turn failed: {e}")
-                    # continue emitting other turns
+                try:
+                    emit_turn(langfuse, session_id, user_id, turn_num, t, transcript_path)
+                except Exception as e:
+                    warn(f"emit_turn failed: {e}")
+                    # continue emitting other turns
 
             ss.turn_count += emitted
             write_session_state(state, key, ss)
             save_state(state)
 
-        try:
-            langfuse.flush()
-        except Exception:
-            pass
+        try:
+            langfuse.flush()
+        except Exception as e:
+            warn(f"Langfuse flush failed: {e}")
+            pass
 
         dur = time.time() - start
         info(f"Processed {emitted} turns in {dur:.2f}s (session={session_id})")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-langfuse",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "private": false,
   "type": "module",
   "description": "Use npm scripts to configure Claude Code / OpenCode / Codex with Langfuse tracing.",
@@ -10,7 +10,15 @@
   },
   "files": [
     "bin",
-    "scripts",
+    "scripts/codex-langfuse-check.mjs",
+    "scripts/codex-langfuse-setup.mjs",
+    "scripts/json-utils.mjs",
+    "scripts/langfuse-check.mjs",
+    "scripts/langfuse-setup.mjs",
+    "scripts/opencode-langfuse-check.mjs",
+    "scripts/opencode-langfuse-run.mjs",
+    "scripts/opencode-langfuse-setup.mjs",
+    "scripts/resolve-opencode-cli.mjs",
     "langfuse_hook.py",
     "codex_langfuse_notify.py",
     "README.md",
@@ -20,8 +28,9 @@
   ],
   "scripts": {
     "start": "node bin/cli.js",
-    "check": "node --check bin/cli.js",
-    "pack:check": "npm pack --dry-run",
+    "check": "node --check bin/cli.js",
+    "self:verify": "node scripts/real-self-verify.mjs",
+    "pack:check": "npm pack --dry-run",
     "claude:setup": "node scripts/langfuse-setup.mjs",
     "claude:check": "node scripts/langfuse-check.mjs",
     "langfuse:setup": "node scripts/langfuse-setup.mjs",

package/scripts/langfuse-check.mjs

@@ -1,90 +1,161 @@
-import fs from "node:fs";
-import path from "node:path";
-import os from "node:os";
-
-function readJsonIfExists(p) {
-  if (!fs.existsSync(p)) return null;
-  const txt = fs.readFileSync(p, "utf8");
-  if (!txt.trim()) return null;
-  return JSON.parse(txt);
-}
-
-function main() {
-  const userHome = os.homedir();
-  const claudeDir = path.join(userHome, ".claude");
-  const hooksDir = path.join(claudeDir, "hooks");
-  const settingsPath = path.join(claudeDir, "settings.json");
-
-  const results = [];
-
-  results.push({
-    item: "hooks 目录",
-    ok: fs.existsSync(hooksDir),
-    detail: hooksDir
-  });
-
-  const pyPath = path.join(hooksDir, "langfuse_hook.py");
-  results.push({
-    item: "hook 脚本",
-    ok: fs.existsSync(pyPath),
-    detail: pyPath
-  });
-
-  const settings = readJsonIfExists(settingsPath);
-  results.push({
-    item: "settings.json",
-    ok: !!settings,
-    detail: settingsPath
-  });
-
-  const env = settings?.env;
-  const neededEnv = [
-    "TRACE_TO_LANGFUSE",
-    "LANGFUSE_PUBLIC_KEY",
-    "LANGFUSE_SECRET_KEY",
-    "LANGFUSE_HOST",
-    "CC_LANGFUSE_BASE_URL",
-    "LANGFUSE_BASEURL"
-  ];
-
-  const missingEnv = neededEnv.filter((k) => !env || typeof env[k] === "undefined");
-  results.push({
-    item: "env 必要字段",
-    ok: missingEnv.length === 0,
-    detail: missingEnv.length ? `缺少：${missingEnv.join(", ")}` : "OK"
-  });
-
-  const stopHooks = settings?.hooks?.Stop;
-  let hasStop = false;
-  if (Array.isArray(stopHooks)) {
-    for (const entry of stopHooks) {
-      const hooks = entry?.hooks;
-      if (!Array.isArray(hooks)) continue;
-      for (const h of hooks) {
-        if (h?.type === "command" && typeof h?.command === "string" && h.command.includes("langfuse_hook.py")) {
-          hasStop = true;
-          break;
-        }
-      }
-      if (hasStop) break;
-    }
-  }
-  results.push({
-    item: "hooks.Stop 配置",
-    ok: hasStop,
-    detail: hasStop ? "OK" : "未找到指向 langfuse_hook.py 的 Stop hook"
-  });
-
-  const pad = (s, n) => (s.length >= n ? s : s + " ".repeat(n - s.length));
-  const w = Math.max(...results.map((r) => r.item.length)) + 2;
-  for (const r of results) {
-    const status = r.ok ? "OK " : "BAD";
-    console.log(`${status}  ${pad(r.item, w)} ${r.detail}`);
-  }
-
-  const failed = results.filter((r) => !r.ok);
-  process.exit(failed.length ? 2 : 0);
-}
-
-main();
-
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { spawnSync } from "node:child_process";
+
+function readJsonIfExists(p) {
+  if (!fs.existsSync(p)) return null;
+  const txt = fs.readFileSync(p, "utf8");
+  if (!txt.trim()) return null;
+  return JSON.parse(txt);
+}
+
+function addResult(results, item, ok, detail, fix = "") {
+  results.push({ item, ok, detail, fix });
+}
+
+function findLangfuseHook(settings) {
+  const stopHooks = settings?.hooks?.Stop;
+  if (!Array.isArray(stopHooks)) return null;
+  for (const entry of stopHooks) {
+    const hooks = entry?.hooks;
+    if (!Array.isArray(hooks)) continue;
+    for (const h of hooks) {
+      if (h?.type !== "command") continue;
+      const command = typeof h.command === "string" ? h.command : "";
+      const args = Array.isArray(h.args) ? h.args : [];
+      const joined = [command, ...args].join(" ");
+      if (joined.includes("langfuse_hook.py")) return { command, args };
+    }
+  }
+  return null;
+}
+
+function hookUsesExecForm(hook) {
+  return !!(hook?.command && Array.isArray(hook.args) && hook.args.some((arg) => String(arg).includes("langfuse_hook.py")));
+}
+
+function pathExists(p) {
+  return typeof p === "string" && p.length > 0 && fs.existsSync(p);
+}
+
+function checkPythonLangfuseImport(pythonPath) {
+  if (!pathExists(pythonPath)) return { ok: false, detail: "python executable missing" };
+  const result = spawnSync(pythonPath, ["-c", "import langfuse; print('OK')"], {
+    encoding: "utf8",
+    timeout: 15000,
+    windowsHide: true
+  });
+  if (result.status === 0) return { ok: true, detail: "OK" };
+  const err = `${result.stderr || result.stdout || result.error?.message || "unknown error"}`.trim();
+  return { ok: false, detail: err || "import failed" };
+}
+
+function main() {
+  const userHome = os.homedir();
+  const claudeDir = path.join(userHome, ".claude");
+  const hooksDir = path.join(claudeDir, "hooks");
+  const settingsPath = path.join(claudeDir, "settings.json");
+  const logPath = path.join(claudeDir, "state", "langfuse_hook.log");
+
+  const results = [];
+
+  addResult(results, "Claude config dir", fs.existsSync(claudeDir), claudeDir, "Run: npx oh-langfuse@latest setup claude");
+  addResult(results, "hooks dir", fs.existsSync(hooksDir), hooksDir, "Run setup again to install the hook script.");
+
+  const pyPath = path.join(hooksDir, "langfuse_hook.py");
+  addResult(results, "hook script", fs.existsSync(pyPath), pyPath, "Run setup again to copy langfuse_hook.py.");
+
+  const settings = readJsonIfExists(settingsPath);
+  addResult(results, "settings.json", !!settings, settingsPath, "Run setup again to write Claude settings.");
+
+  const env = settings?.env;
+  const neededEnv = [
+    "TRACE_TO_LANGFUSE",
+    "LANGFUSE_PUBLIC_KEY",
+    "LANGFUSE_SECRET_KEY",
+    "LANGFUSE_HOST",
+    "CC_LANGFUSE_BASE_URL",
+    "LANGFUSE_BASEURL"
+  ];
+
+  const missingEnv = neededEnv.filter((k) => !env || typeof env[k] === "undefined" || env[k] === "");
+  addResult(
+    results,
+    "Langfuse env fields",
+    missingEnv.length === 0,
+    missingEnv.length ? `missing: ${missingEnv.join(", ")}` : "OK",
+    "Run setup again so settings.json contains the Langfuse environment fields."
+  );
+
+  const userEnvOk = !!(
+    env?.CC_LANGFUSE_USER_ID ||
+    env?.CLAUDE_USER_ID ||
+    env?.CC_USER_ID ||
+    env?.LANGFUSE_USER_ID
+  );
+  addResult(results, "user id env field", userEnvOk, userEnvOk ? "OK" : "missing", "Run setup again and enter a valid employee id.");
+
+  const hook = findLangfuseHook(settings);
+  addResult(results, "hooks.Stop contains Langfuse", !!hook, hook ? "OK" : "missing", "Run setup again to register the Stop hook.");
+
+  const execFormOk = hookUsesExecForm(hook);
+  addResult(
+    results,
+    "hook command form",
+    process.platform === "win32" ? execFormOk : !!hook,
+    execFormOk ? "exec form command + args" : hook ? "legacy shell-form command" : "missing",
+    process.platform === "win32"
+      ? "Run setup again. Windows should use command plus args so paths are not parsed by Git Bash/PowerShell."
+      : "Run setup again to refresh the hook command."
+  );
+
+  if (hook) {
+    addResult(
+      results,
+      "hook python executable",
+      pathExists(hook.command),
+      hook.command || "missing",
+      "Run setup again to recreate the Python venv and write an absolute python path."
+    );
+    const hookScriptPath = execFormOk ? String(hook.args.find((arg) => String(arg).includes("langfuse_hook.py")) || "") : pyPath;
+    addResult(
+      results,
+      "hook args script",
+      pathExists(hookScriptPath),
+      hookScriptPath || "missing",
+      "Run setup again so the hook args point at langfuse_hook.py."
+    );
+    const importCheck = checkPythonLangfuseImport(hook.command);
+    addResult(
+      results,
+      "python package langfuse",
+      importCheck.ok,
+      importCheck.detail,
+      `Run: ${hook.command} -m pip install -U langfuse`
+    );
+  }
+
+  addResult(results, "hook log path", true, logPath);
+
+  const pad = (s, n) => (s.length >= n ? s : s + " ".repeat(n - s.length));
+  const w = Math.max(...results.map((r) => r.item.length)) + 2;
+  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/langfuse-setup.mjs

@@ -177,11 +177,13 @@ async function main() {
   }
   assertValidUserId(userId);
 
-  const langfuseHost =
-    args.langfuseHost ||
-    args.host ||
-    process.env.LANGFUSE_HOST ||
-    "http://120.46.221.227:3000";
+  const langfuseHost =
+    args.langfuseBaseUrl ||
+    args.langfuseHost ||
+    args.host ||
+    process.env.LANGFUSE_BASEURL ||
+    process.env.LANGFUSE_HOST ||
+    "http://120.46.221.227:3000";
 
   const publicKey =
     args.publicKey || process.env.LANGFUSE_PUBLIC_KEY || "pk-lf-da0c90a7-6e93-4eb7-bb86-c1047c8d187d";
@@ -246,10 +248,8 @@ async function main() {
   const settingsPath = path.join(claudeDir, "settings.json");
   const existing = readJsonIfExists(settingsPath) ?? {};
 
-  const pyCmdPath = normalizeWinPathForClaude(pyPath);
-  const pyExePath = normalizeWinPathForClaude(hookPython);
-  const desired = {
-    env: {
+  const desired = {
+    env: {
       TRACE_TO_LANGFUSE: "true",
       LANGFUSE_PUBLIC_KEY: publicKey,
       LANGFUSE_SECRET_KEY: secretKey,
@@ -265,12 +265,13 @@ async function main() {
       Stop: [
         {
           hooks: [
-            {
-              type: "command",
-              command: `${quoteCommandArg(pyExePath)} ${quoteCommandArg(pyCmdPath)}`
-            }
-          ]
-        }
+            {
+              type: "command",
+              command: hookPython,
+              args: [pyPath]
+            }
+          ]
+        }
       ]
     }
   };