oh-langfuse 0.1.60 → 0.1.61

package/README.md

@@ -1,245 +1,245 @@
-# oh-langfuse
-
-`oh-langfuse` 是用于给 Claude Code、OpenCode、Codex 配置 Langfuse 追踪的命令行工具。它既提供交互式安装向导，也支持 `setup`、`check`、`update`、`auto-update` 等直接命令。
-
-当前 npm 版本：`0.1.60`
-
-## 能做什么
-
-- 为 Claude Code 安装 `Stop` hook，把会话事件写入 Langfuse。
-- 为 OpenCode 安装并 patch `opencode-plugin-langfuse`，开启 OpenTelemetry，并输出 `OpenCode Agent Turn` 指标。
-- 为 Codex 安装 `notify` hook，增量读取 session JSONL 并写入 Langfuse。
-- 记录本地 runtime 版本，支持启动前更新检查和手动更新。
-- 校验员工号、环境变量、插件、hook、launcher、命令 shim 是否安装完整。
-
-员工号必须匹配：
-
-```text
-^[a-z](?:\d{8}|wx\d{7})$
-```
-
-示例：`h00613222`、`hwx1234567`。
-
-## 快速使用
-
-建议始终带 `@latest`：
-
-```bash
-npx oh-langfuse@latest
-npx oh-langfuse@latest setup
-npx oh-langfuse@latest check
-```
-
-指定目标：
-
-```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
-npx oh-langfuse@latest update all
-npx oh-langfuse@latest update claude
-npx oh-langfuse@latest update opencode
-npx oh-langfuse@latest update codex
-```
-
-确认是否已经更新到 npm 最新版本：
-
-```bash
-npx oh-langfuse@latest verify-update all
-npx oh-langfuse@latest verify-update opencode
-```
-
-## 交互式菜单
-
-运行 `npx oh-langfuse@latest` 会打开菜单：
-
-- `Setup Langfuse`：选择 Claude Code、OpenCode、Codex 中的一个或多个目标安装。
-- `Update Installed Runtimes`：刷新已安装目标的 hook、plugin、launcher、命令 shim 和 runtime 版本记录。
-- `Check Environment`：检查 Node.js、npm、Python、pip、OpenCode CLI 等基础依赖。
-- `Check Configuration`：检查已写入的目标配置。
-
-多选菜单默认不选中任何目标，避免误写本地配置。
-
-## 自动更新
-
-安装或更新 runtime 后，工具会在：
-
-```text
-~/.config/oh-langfuse/runtime.json
-```
-
-记录 Claude Code / OpenCode / Codex 当前写入本机 runtime 的包名和版本。
-
-`verify-update` 会读取这份记录，并对比 npm `oh-langfuse@latest`：
-
-```bash
-npx oh-langfuse@latest verify-update all
-```
-
-输出示例：
-
-```text
-[OK] OpenCode Langfuse runtime is current: 0.1.60
-[FAIL] Codex Langfuse runtime is outdated: installed 0.1.59, latest 0.1.60
-[FIX] Run: npx oh-langfuse@latest update codex
-[SKIP] Claude not installed
-```
-
-`check` 用于检查配置完整性；`verify-update` 才用于确认本机 runtime 是否已经更新到 npm 最新版本。
-
-OpenCode setup 会生成直接命令 shim：
-
-- Windows：`~/.config/opencode/bin/opencode.cmd`
-- Linux/macOS：`~/.config/opencode/bin/opencode`
-
-新开终端后直接运行 `opencode`，会先做轻量更新检查，再转发到真实 OpenCode CLI。为了避免在 agent 启动链路里嵌套运行完整 installer，shim 默认只提示更新命令；需要更新时关闭 agent 后运行：
-
-```bash
-npx oh-langfuse@latest update opencode
-```
-
-Claude Code 和 Codex 也会生成 launcher：
-
-- `~/.claude/launch-claude-langfuse.cmd` / `~/.claude/launch-claude-langfuse.sh`
-- `~/.codex/launch-codex-langfuse.cmd` / `~/.codex/launch-codex-langfuse.sh`
-
-也可以手动触发轻量检查：
-
-```bash
-npx oh-langfuse@latest auto-update opencode
-npx oh-langfuse@latest auto-update claude
-npx oh-langfuse@latest auto-update codex
-```
-
-## Skill 使用统计
-
-当前版本把 skill 使用汇总写入每次交互的 agent-specific `Agent Turn` observation，不再额外生成独立 `Skill Use` observation。
-
-Agent Turn 的 observation name 会带上来源，方便在 Langfuse 后台直接区分：
-
-- `Claude Agent Turn`
-- `OpenCode Agent Turn`
-- `Codex Agent Turn`
-
-常见字段：
-
-```text
-metadata.skill_use_count
-metadata.unique_skill_count
-metadata.repeated_skill_count
-metadata.skill_names
-metadata.skill_names_all
-metadata.skill_invocation_modes
-metadata.skill_agent_paths
-```
-
-Dashboard 统计建议：
-
-```text
-View: Observations
-Filter: Observation Name contains Agent Turn
-Metric: Sum skill_use_count
-```
-
-如果 Langfuse Dashboard 支持 metadata 维度，可用 `metadata.skill_names` 聚合；导出数据时可用 `metadata.skill_names_all` 保留重复调用顺序。
-
-## 各目标写入内容
-
-### OpenCode
-
-写入或更新：
-
-- `~/.config/opencode/opencode.json`
-- `~/.config/opencode/plugins/opencode-plugin-langfuse`
-- `~/.config/opencode-plugin-langfuse/config.json`
-- `~/.config/opencode/launch-opencode-langfuse.cmd` 或 `.sh`
-- `~/.config/opencode/bin/opencode.cmd` 或 `opencode`
-
-Windows 下会尝试写入用户级 `LANGFUSE_PUBLIC_KEY`、`LANGFUSE_SECRET_KEY`、`LANGFUSE_BASEURL`、`LANGFUSE_USER_ID`。当前终端不会立即继承用户级环境变量，新开终端或使用 launcher 即可生效。
-
-### Claude Code
-
-写入或更新：
-
-- `~/.claude/hooks/langfuse_hook.py`
-- `~/.claude/langfuse-venv`
-- `~/.claude/settings.json`
-- `~/.claude/bin/claude.cmd` 或 `claude`
-- `~/.claude/launch-claude-langfuse.cmd` 或 `.sh`
-
-Linux 环境缺少 `python3-venv/ensurepip` 时，安装器会降级尝试 `python3 -m pip --user`、`pip3 --user`、`pip --user` 安装 `langfuse`。
-
-### Codex
-
-写入或更新：
-
-- `~/.codex/hooks/codex_langfuse_notify.py`
-- `~/.codex/langfuse-venv`
-- `~/.codex/langfuse/config.json`
-- `~/.codex/config.toml` 顶层 `notify`
-- `~/.codex/bin/codex.cmd` 或 `codex`
-- `~/.codex/launch-codex-langfuse.cmd` 或 `.sh`
-
-配置后需要重启 Codex，让新的 notify 命令加载。notify hook 会增量读取 `~/.codex/sessions/**/*.jsonl`，并把读取偏移记录到 `~/.codex/langfuse/state.json`。
-
-notify hook 会读取 `~/.codex/langfuse/config.json`（或 `CODEX_HOME/langfuse/config.json`）中的 `baseUrl` / `host`，并把该主机补入 `NO_PROXY`，避免自建 Langfuse 服务被代理干扰。
-
-## 环境变量
-
-| 变量 | 作用 |
-| --- | --- |
-| `LANGFUSE_BASEURL` / `LANGFUSE_HOST` | Langfuse 服务地址 |
-| `LANGFUSE_PUBLIC_KEY` | Langfuse public key |
-| `LANGFUSE_SECRET_KEY` | Langfuse secret key |
-| `LANGFUSE_USER_ID` / `CC_USER_ID` | 用户标识，必须匹配员工号规则 |
-| `CODEX_HOME` | 自定义 Codex home 目录 |
-| `OPENCODE_SKIP_PLUGIN_INSTALL` | 跳过 OpenCode npm 插件安装 |
-| `OPENCODE_NPM_REGISTRY` | OpenCode 插件 npm 安装 registry |
-| `LANGFUSE_PIP_INDEX_URL` | Python `langfuse` 安装 index |
-
-Secret key 不会在交互式界面中明文展示。
-
-## WSL
-
-WSL 用户请在 WSL shell 中直接安装和检查：
-
-```bash
-npx oh-langfuse@latest setup opencode --userId=h00613222 --yes
-npx oh-langfuse@latest check opencode
-```
-
-工具不会做 Windows 到 WSL 的转发；在 WSL 中运行时，配置写入 WSL 用户自己的 `$HOME/.config/opencode`。
-
-## 开发与验证
-
-```bash
-npm run check
-npm test
-npm pack --dry-run
-```
-
-涉及安装、hook、CLI、OpenCode、Claude Code、Codex、Langfuse、packaging 或 verification 行为的修改，应运行真实闭环验证：
-
-```bash
-npm run self:verify -- --targets=opencode --userId=h00613222
-```
-
-完整覆盖可运行：
-
-```bash
-npm run self:verify -- --targets=claude,opencode,codex --userId=h00613222
-```
-
-发布包暴露两个命令：
-
-- `oh-langfuse`
-- `code-tool-langfuse`
+# oh-langfuse
+
+`oh-langfuse` 是用于给 Claude Code、OpenCode、Codex 配置 Langfuse 追踪的命令行工具。它既提供交互式安装向导，也支持 `setup`、`check`、`update`、`auto-update` 等直接命令。
+
+当前 npm 版本：`0.1.60`
+
+## 能做什么
+
+- 为 Claude Code 安装 `Stop` hook，把会话事件写入 Langfuse。
+- 为 OpenCode 安装并 patch `opencode-plugin-langfuse`，开启 OpenTelemetry，并输出 `OpenCode Agent Turn` 指标。
+- 为 Codex 安装 `notify` hook，增量读取 session JSONL 并写入 Langfuse。
+- 记录本地 runtime 版本，支持启动前更新检查和手动更新。
+- 校验员工号、环境变量、插件、hook、launcher、命令 shim 是否安装完整。
+
+员工号必须匹配：
+
+```text
+^[a-z](?:\d{8}|wx\d{7})$
+```
+
+示例：`h00613222`、`hwx1234567`。
+
+## 快速使用
+
+建议始终带 `@latest`：
+
+```bash
+npx oh-langfuse@latest
+npx oh-langfuse@latest setup
+npx oh-langfuse@latest check
+```
+
+指定目标：
+
+```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
+npx oh-langfuse@latest update all
+npx oh-langfuse@latest update claude
+npx oh-langfuse@latest update opencode
+npx oh-langfuse@latest update codex
+```
+
+确认是否已经更新到 npm 最新版本：
+
+```bash
+npx oh-langfuse@latest verify-update all
+npx oh-langfuse@latest verify-update opencode
+```
+
+## 交互式菜单
+
+运行 `npx oh-langfuse@latest` 会打开菜单：
+
+- `Setup Langfuse`：选择 Claude Code、OpenCode、Codex 中的一个或多个目标安装。
+- `Update Installed Runtimes`：刷新已安装目标的 hook、plugin、launcher、命令 shim 和 runtime 版本记录。
+- `Check Environment`：检查 Node.js、npm、Python、pip、OpenCode CLI 等基础依赖。
+- `Check Configuration`：检查已写入的目标配置。
+
+多选菜单默认不选中任何目标，避免误写本地配置。
+
+## 自动更新
+
+安装或更新 runtime 后，工具会在：
+
+```text
+~/.config/oh-langfuse/runtime.json
+```
+
+记录 Claude Code / OpenCode / Codex 当前写入本机 runtime 的包名和版本。
+
+`verify-update` 会读取这份记录，并对比 npm `oh-langfuse@latest`：
+
+```bash
+npx oh-langfuse@latest verify-update all
+```
+
+输出示例：
+
+```text
+[OK] OpenCode Langfuse runtime is current: 0.1.60
+[FAIL] Codex Langfuse runtime is outdated: installed 0.1.59, latest 0.1.60
+[FIX] Run: npx oh-langfuse@latest update codex
+[SKIP] Claude not installed
+```
+
+`check` 用于检查配置完整性；`verify-update` 才用于确认本机 runtime 是否已经更新到 npm 最新版本。
+
+OpenCode setup 会生成直接命令 shim：
+
+- Windows：`~/.config/opencode/bin/opencode.cmd`
+- Linux/macOS：`~/.config/opencode/bin/opencode`
+
+新开终端后直接运行 `opencode`，会先做轻量更新检查，再转发到真实 OpenCode CLI。为了避免在 agent 启动链路里嵌套运行完整 installer，shim 默认只提示更新命令；需要更新时关闭 agent 后运行：
+
+```bash
+npx oh-langfuse@latest update opencode
+```
+
+Claude Code 和 Codex 也会生成 launcher：
+
+- `~/.claude/launch-claude-langfuse.cmd` / `~/.claude/launch-claude-langfuse.sh`
+- `~/.codex/launch-codex-langfuse.cmd` / `~/.codex/launch-codex-langfuse.sh`
+
+也可以手动触发轻量检查：
+
+```bash
+npx oh-langfuse@latest auto-update opencode
+npx oh-langfuse@latest auto-update claude
+npx oh-langfuse@latest auto-update codex
+```
+
+## Skill 使用统计
+
+当前版本把 skill 使用汇总写入每次交互的 agent-specific `Agent Turn` observation，不再额外生成独立 `Skill Use` observation。
+
+Agent Turn 的 observation name 会带上来源，方便在 Langfuse 后台直接区分：
+
+- `Claude Agent Turn`
+- `OpenCode Agent Turn`
+- `Codex Agent Turn`
+
+常见字段：
+
+```text
+metadata.skill_use_count
+metadata.unique_skill_count
+metadata.repeated_skill_count
+metadata.skill_names
+metadata.skill_names_all
+metadata.skill_invocation_modes
+metadata.skill_agent_paths
+```
+
+Dashboard 统计建议：
+
+```text
+View: Observations
+Filter: Observation Name contains Agent Turn
+Metric: Sum skill_use_count
+```
+
+如果 Langfuse Dashboard 支持 metadata 维度，可用 `metadata.skill_names` 聚合；导出数据时可用 `metadata.skill_names_all` 保留重复调用顺序。
+
+## 各目标写入内容
+
+### OpenCode
+
+写入或更新：
+
+- `~/.config/opencode/opencode.json`
+- `~/.config/opencode/plugins/opencode-plugin-langfuse`
+- `~/.config/opencode-plugin-langfuse/config.json`
+- `~/.config/opencode/launch-opencode-langfuse.cmd` 或 `.sh`
+- `~/.config/opencode/bin/opencode.cmd` 或 `opencode`
+
+Windows 下会尝试写入用户级 `LANGFUSE_PUBLIC_KEY`、`LANGFUSE_SECRET_KEY`、`LANGFUSE_BASEURL`、`LANGFUSE_USER_ID`。当前终端不会立即继承用户级环境变量，新开终端或使用 launcher 即可生效。
+
+### Claude Code
+
+写入或更新：
+
+- `~/.claude/hooks/langfuse_hook.py`
+- `~/.claude/langfuse-venv`
+- `~/.claude/settings.json`
+- `~/.claude/bin/claude.cmd` 或 `claude`
+- `~/.claude/launch-claude-langfuse.cmd` 或 `.sh`
+
+Linux 环境缺少 `python3-venv/ensurepip` 时，安装器会降级尝试 `python3 -m pip --user`、`pip3 --user`、`pip --user` 安装 `langfuse`。
+
+### Codex
+
+写入或更新：
+
+- `~/.codex/hooks/codex_langfuse_notify.py`
+- `~/.codex/langfuse-venv`
+- `~/.codex/langfuse/config.json`
+- `~/.codex/config.toml` 顶层 `notify`
+- `~/.codex/bin/codex.cmd` 或 `codex`
+- `~/.codex/launch-codex-langfuse.cmd` 或 `.sh`
+
+配置后需要重启 Codex，让新的 notify 命令加载。notify hook 会增量读取 `~/.codex/sessions/**/*.jsonl`，并把读取偏移记录到 `~/.codex/langfuse/state.json`。
+
+notify hook 会读取 `~/.codex/langfuse/config.json`（或 `CODEX_HOME/langfuse/config.json`）中的 `baseUrl` / `host`，并把该主机补入 `NO_PROXY`，避免自建 Langfuse 服务被代理干扰。
+
+## 环境变量
+
+| 变量 | 作用 |
+| --- | --- |
+| `LANGFUSE_BASEURL` / `LANGFUSE_HOST` | Langfuse 服务地址 |
+| `LANGFUSE_PUBLIC_KEY` | Langfuse public key |
+| `LANGFUSE_SECRET_KEY` | Langfuse secret key |
+| `LANGFUSE_USER_ID` / `CC_USER_ID` | 用户标识，必须匹配员工号规则 |
+| `CODEX_HOME` | 自定义 Codex home 目录 |
+| `OPENCODE_SKIP_PLUGIN_INSTALL` | 跳过 OpenCode npm 插件安装 |
+| `OPENCODE_NPM_REGISTRY` | OpenCode 插件 npm 安装 registry |
+| `LANGFUSE_PIP_INDEX_URL` | Python `langfuse` 安装 index |
+
+Secret key 不会在交互式界面中明文展示。
+
+## WSL
+
+WSL 用户请在 WSL shell 中直接安装和检查：
+
+```bash
+npx oh-langfuse@latest setup opencode --userId=h00613222 --yes
+npx oh-langfuse@latest check opencode
+```
+
+工具不会做 Windows 到 WSL 的转发；在 WSL 中运行时，配置写入 WSL 用户自己的 `$HOME/.config/opencode`。
+
+## 开发与验证
+
+```bash
+npm run check
+npm test
+npm pack --dry-run
+```
+
+涉及安装、hook、CLI、OpenCode、Claude Code、Codex、Langfuse、packaging 或 verification 行为的修改，应运行真实闭环验证：
+
+```bash
+npm run self:verify -- --targets=opencode --userId=h00613222
+```
+
+完整覆盖可运行：
+
+```bash
+npm run self:verify -- --targets=claude,opencode,codex --userId=h00613222
+```
+
+发布包暴露两个命令：
+
+- `oh-langfuse`
+- `code-tool-langfuse`

package/bin/cli.js

@@ -794,13 +794,13 @@ function printHelp() {
     "oh-langfuse check codex",
     "oh-langfuse update",
     "oh-langfuse update all",
-    "oh-langfuse update claude",
-    "oh-langfuse update opencode",
-    "oh-langfuse update codex",
-    "oh-langfuse verify-update all",
-    "oh-langfuse verify-update opencode",
-    "oh-langfuse auto-update opencode"
-  ]);
+    "oh-langfuse update claude",
+    "oh-langfuse update opencode",
+    "oh-langfuse update codex",
+    "oh-langfuse verify-update all",
+    "oh-langfuse verify-update opencode",
+    "oh-langfuse auto-update opencode"
+  ]);
   renderSection("Options", [
     `${paint("--dry-run", t.gold)}  Preview actions without writing files or installing packages.`,
     `${paint("--userId=ID", t.gold)}  Provide the Langfuse user id without prompting.`,
@@ -867,23 +867,23 @@ async function main() {
       ];
       return runNodeScript("update-langfuse-runtime.mjs", updateArgs, options);
     }
-    if (cmd === "auto-update") {
-      return runNodeScript("auto-update-runtime.mjs", [
-        target || "all",
-        ...(hasValue(options.npmRegistry) ? [`--npmRegistry=${options.npmRegistry}`] : []),
-        ...(hasValue(options.pipIndexUrl) ? [`--pipIndexUrl=${options.pipIndexUrl}`] : []),
+    if (cmd === "auto-update") {
+      return runNodeScript("auto-update-runtime.mjs", [
+        target || "all",
+        ...(hasValue(options.npmRegistry) ? [`--npmRegistry=${options.npmRegistry}`] : []),
+        ...(hasValue(options.pipIndexUrl) ? [`--pipIndexUrl=${options.pipIndexUrl}`] : []),
         ...(options.skipCheck ? ["--skip-check"] : []),
         ...(options.startupStatus ? ["--startup-status"] : []),
-        ...(options.yes ? ["--yes"] : []),
-      ], { ...options, quiet: true });
-    }
-    if (cmd === "verify-update") {
-      return runNodeScript("verify-update-runtime.mjs", [
-        target || "all",
-        ...(hasValue(options.npmRegistry) ? [`--npmRegistry=${options.npmRegistry}`] : []),
-      ], { ...options, quiet: true });
-    }
-    if (cmd === "check" && target === "claude") return checkClaude(options);
+        ...(options.yes ? ["--yes"] : []),
+      ], { ...options, quiet: true });
+    }
+    if (cmd === "verify-update") {
+      return runNodeScript("verify-update-runtime.mjs", [
+        target || "all",
+        ...(hasValue(options.npmRegistry) ? [`--npmRegistry=${options.npmRegistry}`] : []),
+      ], { ...options, quiet: true });
+    }
+    if (cmd === "check" && target === "claude") return checkClaude(options);
     if (cmd === "check" && target === "opencode") return checkOpenCode(options);
     if (cmd === "check" && target === "codex") return checkCodex(options);
     if (cmd === "check" && target === "environment") {