pi-langfuse 1.0.0

package/.agents/skills/langfuse/references/sdk-upgrade.md

@@ -0,0 +1,181 @@
+---
+name: langfuse-sdk-upgrade
+description: Upgrade Langfuse SDKs from older versions to the latest. Use when migrating Python SDK v2/v3 to v4, or JS/TS SDK v3/v4 to v5.
+---
+
+# Langfuse SDK Upgrade Guide
+
+Assist users in upgrading their Langfuse SDK to the latest version. The Python and JS/TS SDKs share the same architectural changes but differ in syntax.
+
+## When to Use
+
+- User asks to upgrade/migrate their Langfuse SDK
+- User is on an older SDK version and encounters deprecated APIs
+- User wants to adopt the latest Langfuse features
+
+## Migration Docs
+
+Always fetch the latest migration guide before starting — these pages are the source of truth:
+
+- **Python (v3 → v4):** https://langfuse.com/docs/observability/sdk/upgrade-path/python-v3-to-v4
+- **JS/TS (v4 → v5):** https://langfuse.com/docs/observability/sdk/upgrade-path/js-v4-to-v5
+
+Fetch the relevant page as markdown before implementing any changes:
+
+```bash
+curl -s "https://langfuse.com/docs/observability/sdk/upgrade-path/python-v3-to-v4.md"
+curl -s "https://langfuse.com/docs/observability/sdk/upgrade-path/js-v4-to-v5.md"
+```
+
+## Upgrade Checklist
+
+Work through each item in order. Skip items that don't apply to the user's codebase.
+
+### Both SDKs
+
+- [ ] **Update the SDK package** to the latest version
+- [ ] **Audit span filtering**: Non-LLM spans (HTTP, DB, queues) no longer export by default. If the user relied on these, configure a custom `should_export_span` / `shouldExportSpan` filter
+- [ ] **Replace `update_current_trace()` / `updateActiveTrace()`**: Split into three calls:
+  - `propagate_attributes()` / `propagateAttributes()` for correlating attributes (`user_id`, `session_id`, `tags`, `metadata`, `trace_name`)
+  - `set_current_trace_io()` / `setActiveTraceIO()` for input/output (deprecated — prefer setting I/O on root observation directly)
+  - `set_current_trace_as_public()` / `setActiveTraceAsPublic()` for public flag
+- [ ] **Replace `.update_trace()` / `.updateTrace()`** on observation objects (same decomposition as above)
+- [ ] **Update API namespace references**: `observations_v_2` / `observationsV2` → `observations`, `score_v_2` / `scoreV2` → `scores`, `metrics_v_2` / `metricsV2` → `metrics`. Legacy v1 APIs moved to `api.legacy.*`
+- [ ] **Validate metadata format**: Must be `dict[str, str]` / `Record<string, string>` with values ≤200 characters
+- [ ] **Move `release` and `environment`** from code parameters to environment variables (`LANGFUSE_RELEASE`, `LANGFUSE_TRACING_ENVIRONMENT`)
+- [ ] **Enable debug logging** during migration to catch issues (`debug=True` in Python, `LANGFUSE_DEBUG="true"` in JS/TS)
+- [ ] **Test trace hierarchies** to verify no spans are unexpectedly dropped
+
+### Python-specific
+
+- [ ] **Replace `start_span()` / `start_generation()`** with `start_observation()` (use `as_type="generation"` for generations)
+- [ ] **Replace `start_as_current_span()` / `start_as_current_generation()`** with `start_as_current_observation()`
+- [ ] **Replace dataset `item.run()`** with `dataset.run_experiment(name=..., task=...)`
+- [ ] **Remove `CallbackHandler(update_trace=...)`** parameter — use `propagate_attributes()` wrapper instead
+- [ ] **Upgrade to Pydantic v2** — the SDK now requires it. Use `pydantic.v1` compatibility shim if migrating gradually
+- [ ] **Update removed types**: `TraceMetadata`, `ObservationParams` removed from `langfuse.types`. Import `MapValue`, `ModelUsage`, `PromptClient` from `langfuse.model`
+
+### JS/TS-specific
+
+- [ ] **Update LangChain `CallbackHandler`** — `traceMetadata` now requires string values; internal behavior uses `propagateAttributes()` instead of direct trace updates
+- [ ] **Update OpenAI integration** — `traceMethod` wrapper now uses `propagateAttributes()` internally; wrap entire execution in `propagateAttributes()` if relying on parent attribute inheritance
+
+## Key API Changes Reference
+
+### Correlating attributes (both SDKs)
+
+**Before:**
+```python
+# Python
+langfuse.update_current_trace(name="trace-name", user_id="user-123", session_id="session-abc", tags=["tag1"])
+```
+```typescript
+// JS/TS
+updateActiveTrace({ name: "trace-name", userId: "user-123", sessionId: "session-456", tags: ["prod"] });
+```
+
+**After:**
+```python
+# Python
+from langfuse import propagate_attributes
+
+with propagate_attributes(trace_name="trace-name", user_id="user-123", session_id="session-abc", tags=["tag1"]):
+    result = call_llm("hello")
+```
+```typescript
+// JS/TS
+import { propagateAttributes } from "langfuse";
+
+await propagateAttributes(
+  { traceName: "trace-name", userId: "user-123", sessionId: "session-456", tags: ["prod"] },
+  async () => { /* traced code */ }
+);
+```
+
+### Span/Generation creation (Python)
+
+**Before:**
+```python
+langfuse.start_span(name="x")
+langfuse.start_generation(name="x", model="gpt-4")
+```
+
+**After:**
+```python
+langfuse.start_observation(name="x")
+langfuse.start_observation(name="x", as_type="generation", model="gpt-4")
+```
+
+### Dataset experiments (Python)
+
+**Before:**
+```python
+for item in dataset.items:
+    with item.run(run_name="my-run") as span:
+        result = my_llm(item.input)
+        span.update(output=result)
+```
+
+**After:**
+```python
+def my_task(*, item, **kwargs):
+    return my_llm(item.input)
+
+dataset.run_experiment(name="my-run", task=my_task)
+```
+
+### Span filtering (both SDKs)
+
+To restore pre-upgrade "export all" behavior:
+
+```python
+# Python
+langfuse = Langfuse(should_export_span=lambda span: True)
+```
+```typescript
+// JS/TS
+const spanProcessor = new LangfuseSpanProcessor({ shouldExportSpan: () => true });
+```
+
+To extend defaults with custom scopes:
+
+```python
+# Python
+from langfuse.span_filter import is_default_export_span
+
+langfuse = Langfuse(
+    should_export_span=lambda span: (
+        is_default_export_span(span)
+        or span.instrumentation_scope.name.startswith("my_framework")
+    )
+)
+```
+```typescript
+// JS/TS
+import { isDefaultExportSpan } from "@langfuse/otel";
+
+shouldExportSpan: ({ otelSpan }) =>
+  isDefaultExportSpan(otelSpan) || otelSpan.instrumentationScope.name.startsWith("my_framework")
+```
+
+## Common Pitfalls
+
+| Pitfall | Impact | Fix |
+| --- | --- | --- |
+| Dropping intermediate spans via filtering | Breaks trace trees — child spans become orphaned | Use `is_default_export_span` as base and only add/remove specific scopes |
+| Metadata with non-string values | Values silently coerced or dropped | Ensure all metadata values are strings ≤200 characters |
+| Setting attributes outside `propagate_attributes()` callback | Attributes don't attach to observations | Wrap all traced code inside the callback |
+| Using deprecated `set_current_trace_io()` for new code | Will be removed in future versions | Set input/output directly on the root observation |
+| Forgetting Pydantic v2 upgrade (Python) | Import errors or runtime failures | Upgrade Pydantic or use `pydantic.v1` shim |
+| `release`/`environment` still passed as parameters | Silently ignored | Use `LANGFUSE_RELEASE` and `LANGFUSE_TRACING_ENVIRONMENT` env vars |
+| LangChain/OpenAI attribute propagation direction changed | Attributes propagate downward only, not upward to parent traces | Wrap outer call in `propagate_attributes()` |
+
+## Best Practices
+
+1. **Always fetch the migration docs first** — they are the canonical source and may have been updated since this guide was written
+2. **Enable debug logging during migration** to surface dropped spans and trace hierarchy issues
+3. **Use `propagate_attributes()` as the primary mechanism** for setting trace-level correlating attributes
+4. **Set input/output on root observations directly** rather than using deprecated trace-level setters
+5. **Compose custom span filters** with `is_default_export_span` / `isDefaultExportSpan` to extend defaults rather than replacing them entirely
+6. **Test thoroughly** — run the application with debug logging, check the Langfuse UI for missing or orphaned spans, verify metadata appears correctly
+7. **Migrate incrementally** — upgrade the SDK first, fix breaking changes, then adopt new patterns

package/.agents/skills/langfuse/references/skill-feedback.md

@@ -0,0 +1,52 @@
+---
+name: langfuse-skill-feedback
+description: Submit feedback about the Langfuse skill to its maintainers via GitHub Discussions. Use when the user indicates the skill gave incorrect guidance, is missing information, or could be improved.
+---
+
+# Skill Feedback
+
+Follow these steps exactly:
+
+1. **Ask permission**: Ask the user if they'd like you to submit feedback to the skill maintainers. Make it clear this is about the skill (the agent instructions), not about Langfuse the product. If they decline, move on.
+2. **Draft feedback**: Write the feedback using the form structure below. Present the draft to the user and ask if they'd like to change anything before submitting.
+3. **Submit**: Once approved, submit via `gh` CLI as described below. Share the resulting discussion URL with the user.
+
+## Feedback Form Structure
+
+Draft the feedback using these two fields:
+
+**Describe your idea or feedback** (required)
+A clear description of what went wrong or what could be improved. Include:
+- What the user was trying to do
+- What the skill did vs what was expected
+- Any specific instructions that were incorrect or missing
+
+**What would the ideal outcome look like?** (optional)
+What the correct behavior or guidance should be.
+
+Format the body as markdown with the two field labels as headings.
+
+## Submitting
+
+Create a GitHub Discussion on the `langfuse/skills` repository using the GraphQL API:
+
+```bash
+gh api graphql -f query='
+mutation($repoId: ID!, $categoryId: ID!, $title: String!, $body: String!) {
+  createDiscussion(input: {repositoryId: $repoId, categoryId: $categoryId, title: $title, body: $body}) {
+    discussion { url }
+  }
+}' \
+  -f repoId="$(gh api graphql -f query='{ repository(owner: "langfuse", name: "skills") { id } }' --jq '.data.repository.id')" \
+  -f categoryId="$(gh api graphql -f query='{ repository(owner: "langfuse", name: "skills") { discussionCategories(first: 10) { nodes { id name } } } }' --jq '.data.repository.discussionCategories.nodes[] | select(.name == "Ideas & Improvements") | .id')" \
+  -f title="<concise title>" \
+  -f body="<formatted feedback>"
+```
+
+If the `gh` CLI is not authenticated or the request fails, give the user this link to create the discussion manually:
+
+```
+https://github.com/langfuse/skills/discussions/new?category=ideas-improvements
+```
+
+After submission, share the discussion URL with the user.

package/.agents/skills/langfuse/references/user-feedback.md

@@ -0,0 +1,88 @@
+---
+name: langfuse-user-feedback
+description: Wires up user feedback (thumbs up/down, ratings, comments) from an application's frontend to Langfuse scores. Use when user wants to capture end-user feedback, add ratings to traces, or connect user complaints to Langfuse.
+---
+
+# User Feedback
+
+Tracing must already be set up — feedback is stored as scores on traces.
+
+Docs: https://langfuse.com/docs/observability/features/user-feedback
+
+## Workflow
+
+### 1. Determine What Feedback to Capture
+
+If the user has asked for something specific, go with that. Otherwise, look at the application and **present a few UX options** for how feedback could work, then ask the user which they prefer before implementing.
+
+Common UX patterns to suggest:
+
+| UX Pattern | Best for | How it works |
+|------------|----------|--------------|
+| Thumbs up/down | Chat apps, Q&A | Simple binary buttons next to each response |
+| Star rating (1–5) | Content generation, summaries | Star row or dropdown after each output |
+| "Was this helpful?" banner | Search, documentation assistants | Single yes/no prompt at the bottom of a response |
+| Regenerate / copy tracking | Any app with these actions | Implicit — log when users retry (negative signal) or copy output (positive signal) |
+| Free-text comment | Complex outputs, internal tools | Optional text field alongside a rating |
+| Report button | Any user-facing app | Flag icon to report bad/harmful responses |
+
+This table is not exhaustive — if the application suggests a different feedback pattern that fits better, propose that instead. Present 2–3 options that match the application's use case and ask the user which approach they'd like. This decision shapes everything downstream (score names, data types, frontend components), so it's important to align early.
+
+Feedback can be **explicit** (user rates via thumbs, stars, etc.) or **implicit** (derived from behavior like copying output, retrying, or escalating to support). Both are stored as scores. Explicit feedback requires the trace ID to reach the frontend; implicit feedback is logged server-side where the event already happens.
+
+### 2. Choose Score Names
+
+Name reflects the signal source, not what you hope it measures (e.g., `user-thumbs` not `response-quality` — a thumbs down doesn't tell you *what* was wrong). Avoid generic names like `feedback` or `score`.
+
+Rules:
+- Lowercase with hyphens
+- One consistent name per feedback type across the entire app
+- If capturing multiple signals, each gets its own distinct name
+
+### 3. Implement Score Creation
+
+**For implicit feedback (server-side):** Use `langfuse.create_score()` / `langfuse.score.create()` wherever the event is already handled in application code. Fetch SDK docs for current API: https://langfuse.com/docs/evaluation/evaluation-methods/scores-via-sdk
+
+**For explicit feedback (frontend):** Use `LangfuseWeb` in the browser. It uses the public key only — no secret key exposed.
+
+```typescript
+import { LangfuseWeb } from "langfuse";
+
+const langfuse = new LangfuseWeb({
+  publicKey: process.env.NEXT_PUBLIC_LANGFUSE_PUBLIC_KEY!,
+  baseUrl: process.env.NEXT_PUBLIC_LANGFUSE_HOST,
+});
+
+langfuse.score({
+  traceId,
+  name: "user-thumbs",
+  value: 1, // 1 = positive, 0 = negative
+  dataType: "BOOLEAN",
+  comment: optionalUserComment,
+});
+```
+
+The trace ID must be available in the frontend for this to work. For Vercel AI SDK, the non-obvious pattern is using `generateMessageId`:
+
+```typescript
+import { getActiveTraceId } from "@langfuse/tracing";
+
+// Inside route handler wrapped with observe()
+return result.toUIMessageStreamResponse({
+  generateMessageId: () => getActiveTraceId() || crypto.randomUUID(),
+});
+```
+
+### 4. Verify
+
+Trigger a feedback action and check the trace's Scores tab in Langfuse. Confirm the score name, value, and data type are correct.
+
+Point users to what they can do with feedback data: filter traces by low scores, use score analytics for trends, build annotation queues for team review.
+
+## Common Mistakes
+
+| Mistake | Problem | Fix |
+|---------|---------|-----|
+| Secret key in frontend code | Security risk | Use `LangfuseWeb` with public key only |
+| Missing `dataType` on boolean scores | Value `1` inferred as `NUMERIC` | Always pass `dataType: "BOOLEAN"` explicitly |
+| Inconsistent score names across the app | Can't aggregate or filter reliably | Pick one name per feedback type, use it everywhere |

package/AGENTS.md

@@ -0,0 +1,57 @@
+# AGENTS.md
+
+## Project Overview
+
+This repository contains a Pi Coding Agent extension that forwards session activity to Langfuse for observability. The runtime is intentionally small:
+
+- `index.ts`: extension entrypoint, event listeners, trace/span/generation lifecycle, and scoring
+- `package.json`: package metadata for Pi/NPM
+- `config.json`: local credentials file for manual development only, ignored by git
+- `.agents/skills/langfuse/SKILL.md`: local skill instructions for Langfuse-related workflows
+
+## How The Extension Works
+
+The extension listens to Pi lifecycle events and maps them into Langfuse objects:
+
+1. `session_start` captures a stable session id
+2. `before_agent_start` creates a trace for the user prompt
+3. `tool_call` / `tool_result` create and close tool spans
+4. `turn_end` records LLM usage/cost metadata as a generation
+5. `agent_end` finalizes the trace and publishes aggregate evaluation scores
+6. `session_shutdown` flushes any remaining state
+
+The code is stateful by design. Changes to trace/session bookkeeping should be reviewed carefully because multiple Pi hooks share the same module-level state.
+
+## Local Development
+
+Recommended environment:
+
+- Node.js `>=22` as declared in `package.json`
+- A local `config.json` with Langfuse credentials
+
+Typical workflow:
+
+```bash
+npm install
+pi "test prompt"
+```
+
+There is currently no dedicated test suite or `npm` script. When changing behavior, validate by running Pi with the extension enabled and confirming traces, spans, generations, and scores appear in Langfuse.
+
+## Editing Guidance
+
+- Prefer small, behavior-preserving changes in `index.ts`; most bugs here are lifecycle or observability-shape bugs rather than UI issues.
+- Keep credential material out of version control. `config.json` should stay local.
+- When logging tool input/output, be mindful of payload size and serialization failures.
+- If you add new Langfuse fields, verify them against current official docs because the SDK surface evolves.
+- Avoid hard-coding install-layout assumptions when importing SDK files unless Pi requires it.
+
+## Review Focus Areas
+
+When reviewing or extending this project, pay extra attention to:
+
+- Trace lifecycle consistency across `before_agent_start`, `agent_end`, and `session_shutdown`
+- Correct score attribution at trace level vs observation level
+- Defensive handling of unexpected event payload shapes
+- Truncation/redaction strategy for large tool payloads
+- Compatibility between the installed Langfuse SDK version and any manually declared local TypeScript interfaces

package/AGENTS_CN.md

@@ -0,0 +1,57 @@
+# AGENTS.md
+
+## 项目概述
+
+此仓库包含一个 Pi Coding Agent 扩展，将会话活动转发到 Langfuse 进行可观测性监控。运行时设计得尽可能精简：
+
+- `index.ts`：扩展入口点、事件监听器、跟踪/跨度/生成生命周期和评分
+- `package.json`：Pi/NPM 的包元数据
+- `config.json`：仅用于手动开发的本地凭据文件，被 git 忽略
+- `.agents/skills/langfuse/SKILL.md`：Langfuse 相关工作流的本地技能说明
+
+## 扩展工作原理
+
+该扩展监听 Pi 生命周期事件，并将它们映射到 Langfuse 对象：
+
+1. `session_start` 捕获稳定的会话 ID
+2. `before_agent_start` 为用户提示创建跟踪
+3. `tool_call` / `tool_result` 创建和关闭工具跨度
+4. `turn_end` 将 LLM 使用/成本元数据记录为生成
+5. `agent_end` 完成跟踪并发布聚合评估分数
+6. `session_shutdown` 刷新任何剩余状态
+
+代码设计为有状态的。对跟踪/会话簿记的更改应仔细审查，因为多个 Pi 钩子共享相同的模块级状态。
+
+## 本地开发
+
+推荐环境：
+
+- Node.js `>=22`（如 `package.json` 中声明）
+- 包含 Langfuse 凭据的本地 `config.json`
+
+典型工作流程：
+
+```bash
+npm install
+pi "test prompt"
+```
+
+目前没有专门的测试套件或 `npm` 脚本。更改行为时，通过启用扩展运行 Pi 并确认跟踪、跨度、生成和分数出现在 Langfuse 中来验证。
+
+## 编辑指南
+
+- 优先在 `index.ts` 中进行小的、保持行为的更改；这里的错误大多是生命周期或可观测性形状错误，而不是 UI 问题。
+- 将凭据材料排除在版本控制之外。`config.json` 应保持本地。
+- 记录工具输入/输出时，注意有效负载大小和序列化失败。
+- 如果添加新的 Langfuse 字段，请根据当前官方文档验证，因为 SDK 表面会演变。
+- 除非 Pi 要求，否则避免在导入 SDK 文件时硬编码安装布局假设。
+
+## 审查重点领域
+
+审查或扩展此项目时，请特别注意：
+
+- 跨 `before_agent_start`、`agent_end` 和 `session_shutdown` 的跟踪生命周期一致性
+- 跟踪级别与观察级别的正确分数归属
+- 对意外事件负载形状的防御性处理
+- 大型工具有效负载的截断/编辑策略
+- 已安装的 Langfuse SDK 版本与任何手动声明的本地 TypeScript 接口之间的兼容性

package/README.md

@@ -0,0 +1,121 @@
+# pi-langfuse
+
+Langfuse observability extension for [Pi Coding Agent](https://github.com/earendil-works/pi-coding-agent). Sends traces to [Langfuse](https://langfuse.com) for monitoring tokens, costs, latency, and tool calls.
+
+## Why Langfuse?
+
+Langfuse provides open-source observability for LLM applications. This extension allows you to **trace**, **monitor**, and **debug** your Pi sessions with production-grade detail, helping you understand exactly how your agent is performing, what it's costing you, and where it might be failing.
+
+## Features
+
+- **Hierarchical Tracing**: Maps user prompts to per-turn spans and nested tool executions for deep visibility.
+- **LLM Metadata**: Automatically records model name, provider, token usage, and API costs per turn.
+- **Tool Observability**: Detailed logs for every tool call, including arguments, results, and error states.
+- **Session Correlation**: Groups all prompts from the same Pi session into a single Langfuse session.
+- **Cost Tracking**: Records input/output/total costs in USD per generation.
+- **Token Usage**: Tracks input and output tokens per turn.
+
+## Quick Install
+
+### Via npm (recommended)
+```bash
+pi install npm:pi-langfuse
+```
+
+## Configuration
+
+Get your keys from [Langfuse Cloud](https://cloud.langfuse.com) → Settings → API Keys.
+
+On first run, Pi will prompt in the CLI/TUI for:
+
+- `LANGFUSE_PUBLIC_KEY`
+- `LANGFUSE_SECRET_KEY`
+- `LANGFUSE_HOST` (optional, defaults to `https://cloud.langfuse.com`)
+
+The extension stores this locally in its own `config.json`, which is ignored by git.
+
+You can also preconfigure it with environment variables instead of using the interactive prompt.
+
+To rerun setup later, use:
+
+```bash
+/langfuse-setup
+```
+
+## Usage
+
+### Run pi with tracing enabled
+
+```bash
+pi "your prompt"
+```
+
+Pi auto-loads the extension. All sessions will be traced to Langfuse.
+
+## Trace Model
+
+```
+Trace (name: "pi-agent")
+├── Session ID: <pi-session-id>
+├── Metadata: model, provider, cwd
+└── Span (name: "tool:<name>")
+    └── Input/Output logs
+
+Generation (name: "llm-response")
+├── Model: MiniMax-M2.7
+├── Usage: input/output tokens
+└── Cost: input/output/total USD
+```
+
+## What Gets Tracked
+
+### Trace Level
+- `input` - User prompt
+- `output` - Assistant response
+- `sessionId` - Pi session identifier
+- `metadata` - Model, provider, cwd
+
+### Generation Observations (LLM Calls)
+- `model` - Model identifier (e.g., "MiniMax-M2.7")
+- `usage` - Token counts (input/output/total)
+- `costDetails` - Cost breakdown in USD
+
+### Span Observations (Tool Calls)
+- `name` - Tool name (e.g., "tool:bash")
+- `input` - Tool parameters (JSON)
+- `output` - Tool result
+- `metadata.isError` - Whether tool failed
+
+## Langfuse Dashboard
+
+After running, check your Langfuse project for:
+
+1. **Traces** - All pi agent runs with I/O
+2. **Sessions** - Traces grouped by session ID
+3. **Observations** - Tool calls and LLM generations
+4. **Scores** - Evaluation metrics such as tool errors and success rate
+5. **Model Usage** - Usage breakdown by model
+
+## Troubleshooting
+
+**No traces appearing?**
+- Verify API keys are correct in `config.json`
+- Check Langfuse project is active
+- Ensure API keys have write permissions
+
+**Extension not loading?**
+- Run `pi list` to check installed packages
+- Try restarting pi
+
+**Model/cost not showing?**
+- Not all providers expose cost info
+- Check Langfuse traces API for raw observation data
+
+## Dependencies
+
+- [langfuse](https://www.npmjs.com/package/langfuse) - Langfuse SDK
+- [@earendil-works/pi-coding-agent](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) - Pi extension API
+
+## License
+
+MIT

package/README_CN.md

@@ -0,0 +1,120 @@
+# pi-langfuse
+
+[Pi Coding Agent](https://github.com/earendil-works/pi-coding-agent) 的 Langfuse 可观测性扩展。将跟踪发送到 [Langfuse](https://langfuse.com) 以监控令牌、成本、延迟和工具调用。
+
+## 为什么选择 Langfuse？
+
+Langfuse 为 LLM 应用程序提供开源的可观测性。此扩展允许您以生产级细节**跟踪**、**监控**和**调试**您的 Pi 会话，帮助您准确了解代理的性能、成本以及可能失败的地方。
+
+## 功能
+
+- **分层跟踪**：将用户提示映射到每轮跨度和嵌套工具执行，实现深度可见性。
+- **LLM 元数据**：自动记录每轮的模型名称、提供商、令牌使用情况和 API 成本。
+- **工具可观测性**：每个工具调用的详细日志，包括参数、结果和错误状态。
+- **会话关联**：将同一 Pi 会话中的所有提示分组到单个 Langfuse 会话中。
+- **成本跟踪**：记录每代输入/输出/总成本（美元）。
+- **令牌使用**：跟踪每轮的输入和输出令牌。
+
+## 快速安装
+
+### 通过 npm（推荐）
+```bash
+pi install npm:pi-langfuse
+```
+
+## 配置
+
+从 [Langfuse Cloud](https://cloud.langfuse.com) → 设置 → API 密钥获取您的密钥。
+
+在扩展目录中创建 `config.json`：
+
+```json
+{
+  "publicKey": "pk-lf-xxxx",
+  "secretKey": "sk-lf-xxxx",
+  "host": "https://cloud.langfuse.com"
+}
+```
+
+对于 npm 安装，扩展位于：
+```
+~/.pi/agent/npm/@ravan08/pi-langfuse/index.ts
+```
+
+## 使用
+
+### 启用跟踪运行 pi
+
+```bash
+pi "your prompt"
+```
+
+Pi 自动加载扩展。所有会话都将被跟踪到 Langfuse。
+
+## 跟踪模型
+
+```
+跟踪（名称："pi-agent"）
+├── 会话 ID：<pi-session-id>
+├── 元数据：模型、提供商、cwd
+└── 跨度（名称："tool:<name>"）
+    └── 输入/输出日志
+
+生成（名称："llm-response"）
+├── 模型：MiniMax-M2.7
+├── 使用：输入/输出令牌
+└── 成本：输入/输出/总美元
+```
+
+## 跟踪内容
+
+### 跟踪级别
+- `input` - 用户提示
+- `output` - 助手响应
+- `sessionId` - Pi 会话标识符
+- `metadata` - 模型、提供商、cwd
+
+### 生成观察（LLM 调用）
+- `model` - 模型标识符（例如，"MiniMax-M2.7"）
+- `usage` - 令牌计数（输入/输出/总计）
+- `costDetails` - 成本细分（美元）
+
+### 跨度观察（工具调用）
+- `name` - 工具名称（例如，"tool:bash"）
+- `input` - 工具参数（JSON）
+- `output` - 工具结果
+- `metadata.isError` - 工具是否失败
+
+## Langfuse 仪表板
+
+运行后，在您的 Langfuse 项目中检查：
+
+1. **跟踪** - 所有 pi 代理运行及其 I/O
+2. **会话** - 按会话 ID 分组的跟踪
+3. **观察** - 工具调用和 LLM 生成
+4. **分数** - 评估指标，如工具错误和成功率
+5. **模型使用** - 按模型划分的使用情况细分
+
+## 故障排除
+
+**没有跟踪出现？**
+- 验证 `config.json` 中的 API 密钥是否正确
+- 检查 Langfuse 项目是否活跃
+- 确保 API 密钥具有写入权限
+
+**扩展未加载？**
+- 运行 `pi list` 检查已安装的包
+- 尝试重启 pi
+
+**模型/成本未显示？**
+- 并非所有提供商都公开成本信息
+- 检查 Langfuse 跟踪 API 获取原始观察数据
+
+## 依赖项
+
+- [langfuse](https://www.npmjs.com/package/langfuse) - Langfuse SDK
+- [@earendil-works/pi-coding-agent](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) - Pi 扩展 API
+
+## 许可证
+
+MIT