oh-langfuse 0.1.7

package/CODEX_LANGFUSE_PLAN.md

@@ -0,0 +1,62 @@
+# Codex Langfuse implementation plan
+
+## Goal
+
+Add Codex support without depending on an unstable Codex plugin API. The first
+version uses Codex's `notify` lifecycle command to trigger an exporter after a
+turn, then the exporter reads Codex session JSONL files and sends the new events
+to Langfuse.
+
+## Architecture
+
+```text
+Codex turn ends
+  -> ~/.codex/config.toml notify command
+  -> ~/.codex/hooks/codex_langfuse_notify.py
+  -> incremental read of ~/.codex/sessions/**/*.jsonl
+  -> Langfuse trace / generation / tool observations
+  -> ~/.codex/langfuse/state.json stores offsets
+```
+
+## Files
+
+- `codex_langfuse_notify.py`: Python notify hook and JSONL exporter.
+- `scripts/codex-langfuse-setup.mjs`: installs the hook, writes Langfuse
+  config, creates `~/.codex/langfuse-venv`, updates `~/.codex/config.toml`,
+  and installs the Python SDK inside the venv.
+- `scripts/codex-langfuse-check.mjs`: validates hook/config/session/package
+  availability.
+- `bin/cli.js`: adds `setup codex` and `check codex`.
+- `package.json`: adds Codex npm scripts and publishes the hook file.
+
+## Commands
+
+```sh
+npm run codex:setup -- --userId=h00613222
+npm run codex:check
+```
+
+or:
+
+```sh
+node bin/cli.js setup codex
+node bin/cli.js check codex
+```
+
+Restart Codex after setup so it reloads `~/.codex/config.toml`.
+
+## Behavior
+
+- The exporter reads Langfuse keys from environment variables first, then from
+  `~/.codex/langfuse/config.json`.
+- It prefers a session path from the notify payload when Codex provides one.
+  If no path is present, it falls back to the latest session JSONL file.
+- It fails open. Errors are logged to
+  `~/.codex/langfuse/codex_langfuse_notify.log` and never block Codex.
+
+## Future improvements
+
+- If Codex exposes a stable OTEL or plugin trace API, add it as an optional
+  second backend.
+- Split shared Langfuse emit logic from the Claude and Codex Python hooks.
+- Add a redaction layer before sending tool output to Langfuse.

package/README.md

@@ -0,0 +1,153 @@
+# oh-langfuse
+
+`oh-langfuse` 是用于配置 Langfuse 链路追踪的交互式命令行工具，支持
+Claude Code、OpenCode 和 Codex。它提供终端安装向导、直接 setup/check
+命令，以及不同工具所需的安装脚本和校验脚本。
+
+## 项目定位
+
+本仓是 AI Coding 工具链中的 Langfuse 能力包，负责：
+
+- 检查 Node.js、npm、Python、pip、OpenCode CLI 等本地依赖；
+- 收集 Langfuse 用户标识，通常是员工号，例如 `h00613222`；
+- 安装或更新 hook 脚本、插件文件、Python 虚拟环境和用户级配置；
+- 校验 Claude Code、OpenCode、Codex 的 Langfuse 配置是否生效。
+
+本包发布到 npm 后暴露 `oh-langfuse` 命令，并被聚合安装器
+`oh-aicoding-tool` 调用。
+
+迁移期内，npm 包仍保留旧命令别名 `code-tool-langfuse`。
+
+## 环境要求
+
+| 目标工具 | 依赖 |
+| --- | --- |
+| 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
+npm install
+npm start
+```
+
+npm 发布后运行：
+
+```bash
+npx oh-langfuse
+```
+
+交互界面支持：
+
+- `Up` / `Down`：移动选项；
+- 数字键：快速选择；
+- `Space`：多选切换；
+- `Enter`：确认；
+- `q` 或 `Esc`：退出。
+
+在不支持 raw input 的终端中，会自动退回到数字输入模式。
+
+## 命令
+
+```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
+```
+
+预览安装动作，不写文件、不安装依赖：
+
+```bash
+oh-langfuse setup --dry-run
+```
+
+本仓内也可以直接运行脚本：
+
+```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
+```
+
+## 各目标工具写入的配置
+
+### Claude Code
+
+安装 `langfuse_hook.py`，创建 `~/.claude/langfuse-venv`，安装 Python 包
+`langfuse`，并把 Langfuse 环境变量和 `Stop` hook 合并写入
+`~/.claude/settings.json`。
+
+### OpenCode
+
+安装并 patch `opencode-plugin-langfuse`，在
+`~/.config/opencode/opencode.json` 中启用 OpenTelemetry，写入插件用户配置，
+并可写入用户级 `LANGFUSE_*` 环境变量。Windows 下还会生成
+`launch-opencode-langfuse.cmd`，用于带环境变量启动 OpenCode。
+
+### Codex
+
+安装 `codex_langfuse_notify.py`，创建 `~/.codex/langfuse-venv`，安装 Python
+包 `langfuse`，把 Langfuse 凭据写入 `~/.codex/langfuse/config.json`，并更新
+`~/.codex/config.toml` 顶层 `notify` 命令。安装后需要重启 Codex。
+
+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` | 用户标识或员工号 |
+| `CODEX_HOME` | 自定义 Codex home 目录 |
+| `OPENCODE_SKIP_PLUGIN_INSTALL` | 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`
+字段一致。