# pi-langfuse

[![npm version](https://img.shields.io/npm/v/pi-langfuse)](https://www.npmjs.com/package/pi-langfuse)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[**English**](./README.md) | [**简体中文**](./README_CN.md)

[Pi Coding Agent](https://github.com/earendil-works/pi-coding-agent) 的 Langfuse 可观测性扩展。它会将完整的 Pi 运行发送到 [Langfuse](https://langfuse.com)，在一个 trace 中展示提示词、代理工作流、LLM 生成、工具调用、最终回复、用量、成本和健康分数。

## 这个插件提供什么

- 每个用户提示词对应一个 Langfuse trace，并按 Pi 会话分组。
- 为根代理创建 `agent` 观察节点，为每次模型请求创建 `generation`，为每次工具调用创建 `tool`。
- 记录最终助手输出、工具错误状态和追踪级别分数。
- 提供输入、输出、工具 I/O、system prompt 和 cwd 的隐私采集开关。
- 上传前脱敏常见密钥，并对本地绝对路径做 hash。
- 针对自托管 Langfuse 提供 REST 兜底，覆盖 OTel span 已到达但 trace 未可见的场景。

## 前提条件

- **Node.js** >= 22
- **Pi Coding Agent** 已安装并完成基础配置
- **Langfuse** 账户，支持 [云服务](https://cloud.langfuse.com) 和自托管

## 快速开始

1. 安装扩展：

   ```bash
   pi install npm:pi-langfuse
   ```

2. 首次运行 Pi 时，如果尚未配置凭据，Pi 会提示输入：
   - Langfuse 公钥，以 `pk-lf-...` 开头
   - Langfuse 密钥，以 `sk-lf-...` 开头
   - Langfuse 主机地址，默认 `https://cloud.langfuse.com`

3. 正常运行 Pi：

   ```bash
   pi "解释 Redis 的架构"
   ```

4. 打开 Langfuse，查看新生成的 trace。

## 配置

Langfuse API 密钥可在 **Langfuse Cloud** -> **Settings** -> **API Keys** 中获取。

### 方式 1：交互式设置

加载扩展后运行任意 `pi` 命令。首次运行且未配置时，Pi 会在 CLI 或 TUI 中提示输入，并将结果保存到 `~/.pi/agent/pi-langfuse/config.json`。

如需重新执行设置：

```text
/langfuse-setup
```

如需查看当前配置状态且不泄漏密钥：

```text
/langfuse-status
```

状态命令会显示配置来源、主机地址、脱敏后的公钥、采集策略、是否有活跃运行、配置文件路径，以及最近一次运行时错误。

### 方式 2：环境变量

在启动 Pi 前设置：

```bash
export LANGFUSE_PUBLIC_KEY="pk-lf-xxxx"
export LANGFUSE_SECRET_KEY="sk-lf-xxxx"
export LANGFUSE_BASE_URL="https://cloud.langfuse.com"  # 可选；也支持 LANGFUSE_HOST
```

保存的配置优先级更高。只有当 `~/.pi/agent/pi-langfuse/config.json` 缺失或不完整时，扩展才会使用环境变量。

隐私采集策略也可以通过环境变量设置：

```bash
export LANGFUSE_PRIVACY_PRESET="full-debug"
```

可用预设：

| 预设 | 采集内容 |
|------|----------|
| `metadata-only` | 仅采集元数据；不采集输入、输出、工具 I/O、system prompt 和 cwd |
| `prompts-only` | 采集提示词或提供商输入，以及元数据 |
| `conversations` | 采集输入和助手输出，但不采集工具 I/O、system prompt 和 cwd |
| `full-debug` | 完整追踪细节；默认值 |

细粒度开关会覆盖预设：

```bash
export LANGFUSE_CAPTURE_INPUTS=true
export LANGFUSE_CAPTURE_OUTPUTS=true
export LANGFUSE_CAPTURE_TOOL_IO=false
export LANGFUSE_CAPTURE_SYSTEM_PROMPT=false
export LANGFUSE_CAPTURE_CWD=false
```

所有被采集的负载在上传前仍会脱敏。扩展会隐藏常见 API key、Bearer token、密码、Cookie、私钥、Langfuse key、GitHub/npm/AWS 风格 token，并对本地绝对路径做 hash。

### 方式 3：持久化 `config.json`

创建或更新 `~/.pi/agent/pi-langfuse/config.json`：

```json
{
  "publicKey": "pk-lf-xxxx",
  "secretKey": "sk-lf-xxxx",
  "host": "https://cloud.langfuse.com",
  "privacyPreset": "conversations"
}
```

也可以持久化细粒度采集开关：

```json
{
  "publicKey": "pk-lf-xxxx",
  "secretKey": "sk-lf-xxxx",
  "host": "https://cloud.langfuse.com",
  "capture": {
    "LANGFUSE_PRIVACY_PRESET": "metadata-only",
    "LANGFUSE_CAPTURE_INPUTS": "true"
  }
}
```

> **安全提醒**：`~/.pi/agent/pi-langfuse/config.json` 包含敏感信息，不应提交到版本控制。
> 扩展自行写入该文件时，会在支持 POSIX 权限的文件系统上使用 `0700` 创建配置目录，并使用 `0600` 写入配置文件。

## 验证扩展是否已加载

执行：

```bash
pi list
```

已安装包列表中应出现 `pi-langfuse`。

如需在 Pi 内验证 Langfuse 主机地址和 API key：

```text
/langfuse-test
```

该命令会先发起一次带超时的认证请求；认证通过后，再发送一条小的测试 trace。

## 在 Langfuse 中会看到什么

- 每个 Pi 会话对应一个独立的 Langfuse session ID。
- 该会话中的每个用户提示词都会生成一个独立 trace。
- trace 中会包含 Pi 实际显示的最终助手回复。
- 工具执行会以工具观察节点展示参数、结果和错误状态。
- 模型请求会以生成观察节点展示；如果提供商暴露相关信息，还会包含用量和成本。
- trace 级别会记录工具调用次数、工具成功率和是否出现错误。

此包还包含一个内置 Langfuse 技能，可直接在 Pi 中查询 Langfuse 数据：

```text
/pi-langfuse-langfuse <查询内容>
```

## 故障排除

### 没有看到 trace

- 先检查 API 密钥是否正确，必要时重新执行 `/langfuse-setup`。
- 执行 `/langfuse-status`，确认当前加载的主机、配置来源、隐私模式和最近一次运行时错误。
- 确认 Langfuse 项目处于可写状态。
- 确认密钥具备写权限。
- 在 Pi 输出中查找 `📊 Langfuse:` 日志。

### 扩展未加载

```bash
pi list
pi install npm:pi-langfuse
```

### 启动时显示 `Missing config`

- 执行 `/langfuse-setup`。
- 或在启动 Pi 前设置 `LANGFUSE_PUBLIC_KEY` 和 `LANGFUSE_SECRET_KEY`。

### 模型或成本未显示

- 并非所有提供商都会返回成本信息。
- 可在 Langfuse trace 中查看原始观察数据。
- `model` 字段可能来自提供商事件、已定型的助手消息、`model_select` 或 `ctx.model`。

### API 密钥错误

- 公钥以 `pk-lf-` 开头。
- 密钥以 `sk-lf-` 开头。
- 使用自托管时，还需要确认主机地址是否正确。

## 开发文档

源码安装、开发流程、运行时架构、追踪模型、字段明细和验证步骤已迁移到 [DEVELOPMENT.md](./DEVELOPMENT.md) 与 [DEVELOPMENT_CN.md](./DEVELOPMENT_CN.md)。

## 许可证

MIT