前言¶

DSH 的理念是「一切皆插件」；插件目录是社区站点，与 DeepSeek / 幻方没有官方从属关系。调试 agent 会话时，常见需求是把一次 turn 中的模型调用、工具调用、token 用量、TTFT 和后续用户反馈放到同一个可追踪视图里。dsh-langfuse 就是为此准备的 DSH 插件：它把每个 agent session 整理成一棵 OpenTelemetry trace tree，并发送到 Langfuse。

下面介绍它的定位、能力、安装启用方式和注意事项。

这是什么¶

dsh-langfuse 是 TtTRz 维护的 DSH 插件，许可证为 MIT。它的一句话定位是：为 DeepSeek Harness 提供 Langfuse LLM observability——每个 agent session 一棵 OpenTelemetry trace tree，并带上 feedback scores 和 subagent lineage。

它不是替换 DSH 的日志系统，而是把已有会话事件整理成 Langfuse 里可查看的 trace、generation、tool span 和 score。默认模式下不导出数据；只有配置后才会启用。

核心功能¶

先说它覆盖的事件：turn、generation 和 tool call 都会进入 Langfuse，并带上 model、provider、usage（包含 cache-read 与 reasoning tokens）和 TTFT。

具体能力如下：

• Full session tracing：每个 turn、generation 和 tool call 都会落到 Langfuse。
• Content-Length transport：span 以单次写的方式发送，并带显式 Content-Length header，不做 chunked。
• Feedback scores：/feedback 记录会变成该 session 最新 turn trace 上的 TEXT score。
• Subagent lineage：子 session 的 turn trace 会链接到父 session 的 trace；这是同进程内的 best-effort。
• Three sharing modes：FULL 实时导出；FEEDBACK_ONLY 只在用户记录 feedback 后导出；DISABLED 是默认，内容不离开进程。
• Opt-in inputs：generation input（system prompt / tools / prompt）只在 includeGenerationInput 打开时导出。
• Fail-loud config：URL 错误、缺少 key、非法 bounds 会在插件加载时抛错，早于任何 transport 建立。

安装与启用¶

先确认运行环境满足插件要求：

Node engine: >=22.19
Peer dependency: @deepseek-ai/cordis >=4.0.1

添加插件：

dsh plugin --profile web add dsh-langfuse

配置 Langfuse key 和 host：

export LANGFUSE_PUBLIC_KEY=pk-lf-...
export LANGFUSE_SECRET_KEY=sk-lf-...
export LANGFUSE_HOST=https://langfuse.example.com

启动 Web 端：

dsh web

已核实的行为是：存在 key 时，backend 运行在 FULL 模式；没有 key 时，运行在 DISABLED 模式。

如果想收窄共享范围，可以使用：

LANGFUSE_TELEMETRY_MODE=FEEDBACK_ONLY
LANGFUSE_INCLUDE_GENERATION_INPUT=1

这里有两个容易忽略的默认值：includeGenerationInput 默认为 false；exporter.url 和 auth.publicKey / auth.secretKey 在 DISABLED 以外为必填项。

典型用法¶

默认开启实时导出¶

上面的环境变量示例就是最小路径：安装插件、设置 Langfuse key、启动 dsh web，然后再执行一个 turn。

只在记录反馈后导出¶

export LANGFUSE_PUBLIC_KEY=pk-lf-...
export LANGFUSE_SECRET_KEY=sk-lf-...
export LANGFUSE_HOST=https://langfuse.example.com
LANGFUSE_TELEMETRY_MODE=FEEDBACK_ONLY
dsh web

显式写入 cordis.yml¶

也可以把它写成一个明确的 cordis.yml row：

- id: session-telemetry-langfuse
  name: dsh-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
    processor: {}
    includeGenerationInput: false

mode 可取 FULL、FEEDBACK_ONLY、DISABLED，默认是 DISABLED。processor 是可选字段。如果属性 payload 超过 maxAttributeChars（默认 16384），会被截断并带 …[truncated] 标记。

适用场景与注意¶

适合以下情况：

• 已经使用 Langfuse，希望把 DSH 会话接入现有 observability 流程。
• 需要查看 model、provider、usage、TTFT 和 tool call。
• 希望把 /feedback 记录作为 TEXT score 挂在最新 turn trace 上。
• 需要同进程内子会话与父会话的 trace 关联。

使用前请注意：

• 插件以当前 DSH 进程权限运行。安装前应检查源码、依赖和许可证。
• 插件目录是社区目录，不是官方应用商店；它与 DeepSeek / 幻方无官方从属关系。
• 每个 context 只能有一个 backend；bundled patch 会禁用 base profile 的 session-telemetry-otel row。
• 没有 durable delivery（at-most-once）；score push 是 fire-and-forget，失败只记录日志。
• Subagent lineage 是同进程 best-effort；跨重启恢复父会话时，trace id 未知。
• 默认 DISABLED 不导出数据；选择 FULL 或 FEEDBACK_ONLY 前，确认共享边界。

结尾¶

dsh-langfuse 的价值在于把 DSH agent session 的 turn、generation、tool call、usage 和 feedback 放进同一棵 trace tree，方便排查与观察。

• 目录页：DSH 插件目录中的 dsh-langfuse 页面
• GitHub：https://github.com/TtTRz/dsh-langfuse