sam/pi-config

Fork 0

Files

Sam Rolfe bc91a15905 Add pi-langfuse extension (Langfuse LLM observability for pi) — vendored from npm 1.5.8

2026-08-03 20:09:58 +10:00

6.5 KiB

Raw Blame History

pi-langfuse

English | 简体中文

Pi Coding Agent 的 Langfuse 可观测性扩展。它会将完整的 Pi 运行发送到 Langfuse，在一个 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 账户，支持云服务和自托管

快速开始

安装扩展：
```
pi install npm:pi-langfuse
```
首次运行 Pi 时，如果尚未配置凭据，Pi 会提示输入：
- Langfuse 公钥，以 pk-lf-... 开头
- Langfuse 密钥，以 sk-lf-... 开头
- Langfuse 主机地址，默认 https://cloud.langfuse.com
正常运行 Pi：
```
pi "解释 Redis 的架构"
```
打开 Langfuse，查看新生成的 trace。

配置

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

方式 1：交互式设置

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

如需重新执行设置：

/langfuse-setup

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

/langfuse-status

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

方式 2：环境变量

在启动 Pi 前设置：

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 缺失或不完整时，扩展才会使用环境变量。

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

export LANGFUSE_PRIVACY_PRESET="full-debug"

可用预设：

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

细粒度开关会覆盖预设：

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：

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

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

{
  "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 写入配置文件。

验证扩展是否已加载

执行：

pi list

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

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

/langfuse-test

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

在 Langfuse 中会看到什么

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

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

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

故障排除

没有看到 trace

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

扩展未加载

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_CN.md。

许可证

MIT

6.5 KiB Raw Blame History Unescape Escape