From 423f114db6a45a37159866947ca7509e2b4b6d3f Mon Sep 17 00:00:00 2001 From: claude-code-best Date: Sat, 11 Apr 2026 23:53:21 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20langfuse=20?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 17 ++- docs/features/langfuse-monitoring.md | 205 +++++++++++++++++++++++++++ mint.json | 21 ++- 3 files changed, 236 insertions(+), 7 deletions(-) create mode 100644 docs/features/langfuse-monitoring.md diff --git a/README.md b/README.md index 5ec20b770..f916877e2 100644 --- a/README.md +++ b/README.md @@ -14,8 +14,19 @@ [文档在这里, 支持投稿 PR](https://ccb.agent-aura.top/) | [留影文档在这里](./Friends.md) | [Discord 群组](https://discord.gg/qZU6zS7Q) -- ✅ [x] V4 — 测试补全、[Buddy](https://ccb.agent-aura.top/docs/features/buddy)、[Auto Mode](https://ccb.agent-aura.top/docs/safety/auto-mode)、环境变量 Feature 开关 -- ✅ [x] V5 — [Sentry](https://ccb.agent-aura.top/docs/internals/sentry-setup) / [GrowthBook](https://ccb.agent-aura.top/docs/internals/growthbook-adapter) 企业监控、[自定义 Login](https://ccb.agent-aura.top/docs/features/custom-platform-login)、[OpenAI 兼容](https://ccb.agent-aura.top/docs/plans/openai-compatibility)、[Web Search](https://ccb.agent-aura.top/docs/features/web-browser-tool)、[Computer Use](https://ccb.agent-aura.top/docs/features/computer-use) / [Chrome Use](https://ccb.agent-aura.top/docs/features/claude-in-chrome-mcp)、[Voice Mode](https://ccb.agent-aura.top/docs/features/voice-mode)、[Bridge Mode](https://ccb.agent-aura.top/docs/features/bridge-mode)、[Remote Control 私有部署](https://ccb.agent-aura.top/docs/features/remote-control-self-hosting)、[/dream 记忆整理](https://ccb.agent-aura.top/docs/features/auto-dream)、**全网独家支持 Claude 群控技术** — [Pipe IPC 多实例协作](https://ccb.agent-aura.top/docs/features/pipes-and-lan)（同机 main/sub 自动编排 + [LAN 跨机器零配置发现与通讯](https://ccb.agent-aura.top/docs/features/lan-pipes)，`/pipes` 选择面板 + `Shift+↓` 交互 + 消息广播路由） +| 特性 | 说明 | 文档 | +|------|------|------| +| **Claude 群控技术** | Pipe IPC 多实例协作：同机 main/sub 自动编排 + LAN 跨机器零配置发现与通讯，`/pipes` 选择面板 + `Shift+↓` 交互 + 消息广播路由 | [Pipe IPC](https://ccb.agent-aura.top/docs/features/pipes-and-lan) / [LAN](https://ccb.agent-aura.top/docs/features/lan-pipes) | +| Remote Control 私有部署 | Docker 自托管 RCS + Web UI | [文档](https://ccb.agent-aura.top/docs/features/remote-control-self-hosting) | +| /dream 记忆整理 | 自动整理和优化记忆文件 | [文档](https://ccb.agent-aura.top/docs/features/auto-dream) | +| Web Search | 内置网页搜索工具 | [文档](https://ccb.agent-aura.top/docs/features/web-browser-tool) | +| 自定义模型供应商 | OpenAI/Anthropic/Gemini/Grok 兼容 | [文档](https://ccb.agent-aura.top/docs/features/custom-platform-login) | +| Voice Mode | Push-to-Talk 语音输入 | [文档](https://ccb.agent-aura.top/docs/features/voice-mode) | +| Computer Use / Chrome Use | 截图、键鼠控制、浏览器操控 | [Computer Use](https://ccb.agent-aura.top/docs/features/computer-use)
[Chrome Use](https://ccb.agent-aura.top/docs/features/claude-in-chrome-mcp) | +| Sentry / GrowthBook 企业监控 | 企业级错误追踪与特性开关 | [Sentry](https://ccb.agent-aura.top/docs/internals/sentry-setup)
[GrowthBook](https://ccb.agent-aura.top/docs/internals/growthbook-adapter) | +| Langfuse 监控 | LLM 调用/工具执行/多 Agent 全链路追踪 | [文档](https://ccb.agent-aura.top/docs/features/langfuse-monitoring) | + + - 🔮 [ ] V6 — 大规模重构石山代码，全面模块分包（全新分支，main 封存为历史版本） - 🚀 [想要启动项目](#快速开始源码版) @@ -34,8 +45,6 @@ ccb # 直接打开 claude code CLAUDE_BRIDGE_BASE_URL=https://remote-control.claude-code-best.win/ CLAUDE_BRIDGE_OAUTH_TOKEN=test-my-key bun run dev --remote-control # 我们有自部署的远程控制 ``` -⚠️ 如果 GitHub 下载 ripgrep 失败，postinstall 会自动回退到 ghproxy.net 镜像，无需手动配置。 - ## ⚡ 快速开始(源码版) ### ⚙️ 环境要求 diff --git a/docs/features/langfuse-monitoring.md b/docs/features/langfuse-monitoring.md new file mode 100644 index 000000000..d917ea699 --- /dev/null +++ b/docs/features/langfuse-monitoring.md @@ -0,0 +1,205 @@ +# Langfuse 监控集成 + +> 实现状态：已完成，通过环境变量启用 +> 依赖：`@langfuse/otel`、`@langfuse/tracing`、`@opentelemetry/sdk-trace-base` + +## 一、功能概述 + +Langfuse 是一个开源的 LLM 可观测性平台，用于追踪、监控和调试 AI 应用的请求链路。CCB 通过 OpenTelemetry (OTel) 桥接层将 Langfuse 集成到查询流程中，实现： + +- **LLM 调用追踪** — 记录每次 API 请求的模型、Provider、输入/输出、Token 用量 +- **工具执行追踪** — 记录每个工具调用的名称、输入、输出、耗时和错误 +- **多 Agent 追踪** — 主 Agent 和子 Agent 各自独立的 Trace 链路 +- **数据脱敏** — 自动遮蔽敏感信息（API Key、文件内容、Shell 输出等） + +## 二、启用方式 + +Langfuse 是开源项目，你可以 **自部署**（Docker / Kubernetes），也可以使用官方提供的 **[Langfuse Cloud](https://cloud.langfuse.com)** 免费测试。注册后在 Project Settings → API Keys 页面获取密钥。 + +核心只需要三个环境变量： + +| 环境变量 | 说明 | +|---------|------| +| `LANGFUSE_PUBLIC_KEY` | Langfuse 公钥（必填） | +| `LANGFUSE_SECRET_KEY` | Langfuse 密钥（必填） | +| `LANGFUSE_BASE_URL` | 服务地址，默认 `https://cloud.langfuse.com`；自部署时改为你的地址（必填） | + +未配置时所有追踪函数为 no-op，零开销。 + +### 通过 settings.json 配置（推荐） + +在 `.claude/settings.json` 的 `env` 字段中添加，这样每次启动自动生效： + +```json +{ + "env": { + "LANGFUSE_PUBLIC_KEY": "pk-xxx", + "LANGFUSE_SECRET_KEY": "sk-xxx", + "LANGFUSE_BASE_URL": "https://cloud.langfuse.com" + } +} +``` + +### 其他可选参数 + +| 环境变量 | 默认值 | 说明 | +|---------|--------|------| +| `LANGFUSE_TRACING_ENVIRONMENT` | `development` | 环境标签，用于 Langfuse 面板筛选 | +| `LANGFUSE_FLUSH_AT` | `20` | 批量发送的 span 数量阈值 | +| `LANGFUSE_FLUSH_INTERVAL` | `10` | 定时刷新间隔（秒） | +| `LANGFUSE_EXPORT_MODE` | `batched` | 导出模式：`batched`（批量）或 `immediate`（即时） | +| `LANGFUSE_TIMEOUT` | `5` | 请求超时（秒） | + +## 四、架构 + +### 4.1 模块结构 + +``` +src/services/langfuse/ +├── index.ts # 统一导出 +├── client.ts # OTel Provider + LangfuseSpanProcessor 初始化 +├── tracing.ts # Trace/Span 创建、LLM 和工具观察记录 +├── convert.ts # 内部 Message 类型 → Langfuse OpenAI 兼容格式转换 +└── sanitize.ts # 数据脱敏（敏感字段、文件路径、工具输出） +``` + +### 4.2 追踪层级 + +``` +Trace (Agent Span) ← createTrace() / createSubagentTrace() + ├── Generation (LLM 调用) ← recordLLMObservation() + ├── Tool Observation (工具调用) ← recordToolObservation() + ├── Tool Observation (工具调用) ← recordToolObservation() + └── ... +``` + +### 4.3 数据流 + +``` +query.ts ──→ createTrace() # 每个 query turn 创建根 trace + │ + ├── claude.ts ──→ recordLLMObservation() # API 调用完成后记录 LLM 观察 + │ + ├── toolExecution.ts ──→ recordToolObservation() # 每个工具执行记录 + │ + └── query.ts ──→ endTrace() # turn 结束时关闭 trace + +runAgent.ts ──→ createSubagentTrace() # 子 Agent 有独立 trace +``` + +## 五、追踪详情 + +### 5.1 主 Agent Trace + +每次 `query()` 调用（即用户一次对话 turn）创建一个类型为 `agent` 的根 Span： + +- **名称**: `agent-run` 或 `agent-run:` +- **元数据**: `provider`、`model`、`agentType: "main"` +- **Session ID**: 关联到 Langfuse 的 Session 功能，支持按会话聚合 + +### 5.2 子 Agent Trace + +通过 `AgentTool` 启动的子 Agent 创建独立 Trace： + +- **名称**: `agent:` +- **元数据**: `provider`、`model`、`agentType`、`agentId` +- 独立于主 Trace，有自己的 Session 关联 + +### 5.3 LLM Generation + +每次 API 调用记录为一个 `generation` 类型的 Span： + +- **名称**: 按 Provider 映射（如 `ChatAnthropic`、`ChatOpenAI`、`ChatBedrockAnthropic` 等） +- **记录内容**: 输入消息、输出消息、Token 用量（input/output） +- **时间**: 精确记录 `startTime`、`endTime`、`completionStartTime`（TTFT 指标） + +Provider 名称映射： + +| Provider | Generation 名称 | +|----------|-----------------| +| `firstParty` | `ChatAnthropic` | +| `bedrock` | `ChatBedrockAnthropic` | +| `vertex` | `ChatVertexAnthropic` | +| `foundry` | `ChatFoundry` | +| `openai` | `ChatOpenAI` | +| `gemini` | `ChatGoogleGenerativeAI` | +| `grok` | `ChatXAI` | + +### 5.4 工具执行 + +每个工具调用记录为一个 `tool` 类型的 Span： + +- **名称**: 工具名（如 `FileEditTool`、`BashTool`） +- **记录内容**: 输入（经脱敏）、输出（经脱敏）、`toolUseId` +- **错误标记**: `isError` 标志 + `level: ERROR` + +## 六、数据脱敏 + +所有上传到 Langfuse 的数据都会经过脱敏处理（`sanitize.ts`），确保敏感信息不会泄露： + +### 6.1 全局脱敏（`sanitizeGlobal`） + +- **Home 路径替换** — `/Users/xxx` → `~` +- **敏感字段遮蔽** — 匹配 `api_key`、`token`、`secret`、`password`、`credential`、`auth_header` 等关键字的字段值替换为 `[REDACTED]` + +### 6.2 工具输入脱敏（`sanitizeToolInput`） + +- 敏感字段遮蔽（同全局） +- `file_path`、`path`、`directory` 路径中的 Home 目录替换 + +### 6.3 工具输出脱敏（`sanitizeToolOutput`） + +| 工具 | 脱敏策略 | +|------|---------| +| `FileReadTool`、`FileWriteTool`、`FileEditTool` | 完全遮蔽，仅保留字符数：`[file content redacted, N chars]` | +| `BashTool`、`PowerShellTool` | 截断至 500 字符 | +| `ConfigTool`、`MCPTool` | 完全遮蔽 | +| 其他工具 | 原样保留 | + +## 七、消息格式转换 + +`convert.ts` 将 CCB 内部的 Message 类型转换为 Langfuse 期望的 OpenAI 兼容格式： + +- **输入**: `UserMessage | AssistantMessage[]` + 可选 system prompt → `{ role, content }[]` +- **输出**: `AssistantMessage[]` → `{ role: 'assistant', content }` +- **Content Block 映射**: + - `text` → `{ type: 'text', text }` + - `thinking` / `redacted_thinking` → `{ type: 'thinking', thinking }` + - `tool_use` → `{ type: 'tool_use', id, name, input }` + - `tool_result` → `{ type: 'tool_result', tool_use_id, content }` + - `image` / `document` → 占位标记 `[image]` / `[document: name]` + +## 八、生命周期 + +1. **初始化** — `initLangfuse()` 在 `src/entrypoints/init.ts` 启动时调用，创建 `LangfuseSpanProcessor` 和 `BasicTracerProvider` +2. **运行时** — 各追踪函数通过 `isLangfuseEnabled()` 检查，未配置时直接返回 `null`/跳过 +3. **关闭** — `shutdownLangfuse()` 在进程退出时调用，强制 flush 并关闭 Processor + +## 九、自部署 Langfuse + +Langfuse 是开源项目，支持 Docker / Kubernetes 自部署： + +```bash +docker run -d \ + --name langfuse \ + -p 3000:3000 \ + -e DATABASE_URL=postgresql://... \ + langfuse/langfuse:latest +``` + +自部署后，将 `LANGFUSE_BASE_URL` 指向你的实例地址即可。详见 [Langfuse 自部署文档](https://langfuse.com/docs/deployment/self-host)。 + +如果没有自部署需求，可以直接使用 [Langfuse Cloud](https://cloud.langfuse.com)，提供免费额度可用于测试。 + +## 十、相关文件 + +| 文件 | 说明 | +|------|------| +| `src/services/langfuse/client.ts` | OTel Provider 初始化、生命周期管理 | +| `src/services/langfuse/tracing.ts` | Trace/Span 创建和观察记录 | +| `src/services/langfuse/convert.ts` | Message 格式转换 | +| `src/services/langfuse/sanitize.ts` | 数据脱敏 | +| `src/services/langfuse/__tests__/langfuse.test.ts` | 测试（568 行） | +| `src/query.ts` | 主查询流程中的 Trace 集成 | +| `src/services/tools/toolExecution.ts` | 工具执行中的观察记录 | +| `src/tools/AgentTool/runAgent.ts` | 子 Agent Trace 创建 | diff --git a/mint.json b/mint.json index 4f1764a0f..277167e1c 100644 --- a/mint.json +++ b/mint.json @@ -124,7 +124,10 @@ "docs/features/coordinator-mode", "docs/features/fork-subagent", "docs/features/daemon", - "docs/features/teammem" + "docs/features/teammem", + "docs/features/pipes-and-lan", + "docs/features/lan-pipes", + "docs/features/uds-inbox" ] }, { @@ -145,7 +148,11 @@ "docs/features/tree-sitter-bash", "docs/features/bash-classifier", "docs/features/web-browser-tool", - "docs/features/experimental-skill-search" + "docs/features/web-search-tool", + "docs/features/experimental-skill-search", + "docs/features/langfuse-monitoring", + "docs/features/computer-use", + "docs/features/claude-in-chrome-mcp" ] }, { @@ -175,7 +182,15 @@ "docs/testing-spec.md", "docs/REVISION-PLAN.md", "docs/feature-exploration-plan.md", - "docs/ultraplan-implementation.md" + "docs/ultraplan-implementation.md", + "docs/features/feature-flags-audit-complete.md", + "docs/features/feature-flags-codex-review.md", + "docs/features/growthbook-enablement-plan.md", + "docs/features/computer-use-architecture-v2.md", + "docs/features/computer-use-mcp-test-report.md", + "docs/features/computer-use-tools-reference.md", + "docs/features/computer-use-windows-enhancement.md", + "docs/features/lan-pipes-implementation.md" ], "footerSocials": { "github": "https://github.com/anthropics/claude-code"