前言¶

用 DeepSeek Harness（DSH）跑智能体时，一轮对话里往往交织着模型调用、工具执行、子代理分叉。出了问题要回溯「哪一步慢了、哪次工具返回异常」，单靠终端日志很难串成完整链路。官方 harness 自带基于 OpenTelemetry 的 session telemetry 接缝，默认可走 OTLP logs 导出；若你已经在用 Langfuse 做 LLM 可观测性，更希望 trace 直接落到 Langfuse 控制台，就需要一个对接该接缝的后端。

下面介绍社区插件 dsh-plugin-langfuse（维护者 linyp）：它实现 harness 公开的 @deepseek-ai/dsh-session-telemetry 接口，把每个 turn 导出为 OpenTelemetry trace，并按 GenAI 语义约定映射到 Langfuse 的 OTLP 端点。插件归类为 SkillHub 目录中的「联网工具」，当前 GitHub 星标 11，许可证 MIT，最新版本 0.5.1。

这是什么¶

dsh-plugin-langfuse 是 DSH 的社区插件（带 dsh-plugin topic），不属于官方 deepseek-harness 仓库。它的定位可以概括为：

Langfuse observability for DeepSeek Harness：将 agent 会话导出为 OpenTelemetry trace 树（GenAI semconv），写入 Langfuse OTLP endpoint。

具体行为包括：

每一轮（turn）对应一条 trace：模型步骤映射为 generation span，工具调用映射为 tool span。
按 session 聚合多轮对话。
将规范化的用户反馈记录为 Langfuse Scores。
保留 fork / subagent 血缘关系。

它是官方 OTLP-logs exporter 的替代后端；telemetry 接缝在同一上下文中只能挂载一个后端，重复加载会抛错。

核心功能¶

Trace 结构与语义¶

插件把 harness 会话事件翻译成 OpenTelemetry trace，遵循 GenAI 相关约定，经 OTLP/HTTP 发往 Langfuse。默认在 exporter 上附带 x-langfuse-ingestion-version: 4 头，以适配 Langfuse v4 数据模型；若你在配置里显式提供同名 header，则以你的配置为准。

导出模式（mode）¶

模式	含义
`FULL`	实时导出每一次会话
`FEEDBACK_ONLY`	仅在用户记录反馈时，回放并导出规范会话日志
`DISABLED`	默认；不构造导出器，进程内无数据外发

词汇与同意语义与官方 telemetry 后端一致。通过 profile bundle 安装且配置了 Langfuse 密钥时，bundle 层会在有 key 时启用 FULL，否则为 DISABLED。设置 LANGFUSE_TELEMETRY_MODE=FEEDBACK_ONLY 可收窄为仅反馈触发导出。

反馈 Scores¶

可选地将 canonical feedback/record 事件导出为 Langfuse 的 TEXT Score。bundle 安装路径下，当 LANGFUSE_PUBLIC_KEY 与 LANGFUSE_SECRET_KEY 均存在时会自动启用；在显式 cordis.yml 行里需自行打开 feedbackScores.enabled。

内容与隐私控制¶

content 段可限制导出字段：

turnInputMode：none | user（默认，仅聚合人类消息）| user-and-context（含插件注入上下文）
cwdMode：omit（默认）| basename | full
toolMetaAllowlist：白名单方式导出 tool/result.meta 顶层键

另有 maxAttributeChars（默认 32768）对 span 属性做截断，完整字节仍保留在 canonical session log。

与宿主关联（correlation）¶

若 DSH 嵌入在其他宿主里，可通过 correlation 把 userId / sessionId 写入 langfuse.user.id / langfuse.session.id，便于在 Langfuse 侧与宿主 trace 归并。

投递状态¶

LangfuseSessionTelemetryBackend.status() 返回同步快照，包含整体与各通道状态（disabled / starting / healthy / degraded / stopped）、trace 批次数、连续失败次数、Score 队列统计等，便于在运行中判断导出是否降级。

安装与启用¶

下面假设已安装 dsh CLI。若从 deepseek-harness 源码运行，在 checkout 根目录执行 pnpm run build 后，将命令中的 dsh 换为 pnpm dsh，profile 仍为 web。

作为 profile bundle 安装（推荐）¶

插件自带 cordis.patch.yml，会禁用 base profile 的 session-telemetry-otel 行，并挂载本后端：

dsh plugin --profile web add dsh-plugin-langfuse
export LANGFUSE_PUBLIC_KEY=pk-lf-…
export LANGFUSE_SECRET_KEY=sk-lf-…
# 可选，默认 https://cloud.langfuse.com（EU）；插件读取 LANGFUSE_HOST，而非 SDK 的 LANGFUSE_BASE_URL
export LANGFUSE_HOST=https://us.cloud.langfuse.com
dsh web

说明：

bundle 层与环境变量在进程启动时读取；已运行的实例需在已 export 变量的 shell 里重启后才生效。
LANGFUSE_HOST 决定数据落入哪个区域的 Langfuse 控制台；项目密钥与区域绑定，US 项目的 trace 不会出现在 EU 控制台。
可用 dsh --profile web --dump-config 查看合成配置，应出现 # == dsh-plugin-langfuse 层及 session-telemetry-langfuse 条目。
下一轮对话结束后，trace 应出现在对应区域控制台。
卸载：dsh plugin --profile web remove dsh-plugin-langfuse，会同时移除依赖与 patch 层。

显式 cordis.yml 配置¶

若不用 bundle，可在 cordis.yml 增加一行（节选）：

- id: session-telemetry-langfuse
  name: dsh-plugin-langfuse
  config:
    mode: FULL
    exporter:
      url: https://cloud.langfuse.com/api/public/otel/v1/traces
    auth:
      publicKey: !!js process.env.LANGFUSE_PUBLIC_KEY
      secretKey: !!js process.env.LANGFUSE_SECRET_KEY
    feedbackScores:
      enabled: true
      url: https://cloud.langfuse.com/api/public/scores

exporter.url 须为完整的 traces 路径（…/api/public/otel/v1/traces）；auth 与显式 exporter.headers 里的 Authorization 互斥。配置错误（缺 URL、凭证冲突、非法 mode 等）会在插件加载阶段直接抛错，避免静默失败。

典型用法¶

最小闭环：安装 → 配密钥 → 跑 web¶

dsh plugin --profile web add dsh-plugin-langfuse
export LANGFUSE_PUBLIC_KEY=pk-lf-…
export LANGFUSE_SECRET_KEY=sk-lf-…
dsh web

在 web 界面完成一两轮对话后，打开 Langfuse 项目查看 trace 树：应能看到 generation、tool span 及 session 分组。

仅在有用户反馈时导出¶

适合对实时外发更谨慎的场景：

export LANGFUSE_TELEMETRY_MODE=FEEDBACK_ONLY
dsh web

用户通过 harness 记录 canonical feedback 后，插件回放会话日志并导出。

检查合成配置（不启动实例）¶

dsh --profile web --dump-config

确认 session-telemetry-langfuse 的 mode 与 exporter 地址符合预期。

适用场景与注意¶

适合谁

已在生产或预发环境使用 Langfuse 做 LLM trace、评分与调试的团队。
需要把 DSH 多轮 agent 会话与工具调用串成可查询链路，并关心 fork / subagent 血缘的开发者。
希望复用 harness 官方 telemetry 接缝、但不想自建 OTLP 管道的用户。

运行环境与权限

插件以当前 dsh 进程的权限运行；导出请求携带你配置的 Langfuse 密钥，并可能包含会话输入、工具元数据（取决于 content 策略）。安装前建议阅读源码与 MIT 许可证，确认外发范围符合组织合规要求。
要求 Node.js ^22.19 || >=24（见 package.json engines）。

区域与密钥

务必让 LANGFUSE_HOST（或 exporter.url）与密钥所属 Langfuse 区域一致。

与官方后端的关系

本插件与官方 session-telemetry-otel 互斥；bundle 会自动关掉后者。不要手动同时挂载两个 telemetry 后端。

生态说明

DSH 奉行「一切皆插件」；SkillHub 上的插件目录由社区维护，与 DeepSeek / 幻方无官方从属关系。本文介绍的安装命令以 README 与目录登记为准，请勿自行拼接未文档化的 dsh plugin add github:… 形式。

结尾¶

dsh-plugin-langfuse 把 DSH 会话 telemetry 接缝接到 Langfuse：OpenTelemetry trace、反馈 Scores、会话聚合与分叉血缘，一条链路可在 Langfuse 控制台查看。若你已在用 Langfuse，按 profile bundle 安装、配置区域对应的密钥并重启 dsh web 即可验证。

SkillHub 目录页：https://www.skillhub.cn/plugins/linyp/dsh-plugin-langfuse
GitHub 仓库：https://github.com/linyp/dsh-plugin-langfuse

dsh-plugin-langfuse：把 DSH 智能体会话导出到 Langfuse

前言¶

这是什么¶

核心功能¶

Trace 结构与语义¶

导出模式（mode）¶

反馈 Scores¶

内容与隐私控制¶

与宿主关联（correlation）¶

投递状态¶

安装与启用¶

作为 profile bundle 安装（推荐）¶

显式 cordis.yml 配置¶

典型用法¶

最小闭环：安装 → 配密钥 → 跑 web¶

仅在有用户反馈时导出¶

检查合成配置（不启动实例）¶

适用场景与注意¶

结尾¶

精选优惠券

dsh-plugin-langfuse：把 DSH 智能体会话导出到 Langfuse

前言¶

这是什么¶

核心功能¶

Trace 结构与语义¶

导出模式（mode）¶

反馈 Scores¶

内容与隐私控制¶

与宿主关联（correlation）¶

投递状态¶

安装与启用¶

作为 profile bundle 安装（推荐）¶

显式 cordis.yml 配置¶

典型用法¶

最小闭环：安装 → 配密钥 → 跑 web¶

仅在有用户反馈时导出¶

检查合成配置（不启动实例）¶

适用场景与注意¶

结尾¶

精选优惠券

相关文章