Langfuse 遥测 Yuntwo/dsh-langfuse-plugin

dsh-langfuse-plugin

DeepSeek Harness 的 Langfuse 遥测 sidecar 包。它监听官方 session-telemetry 接缝，不接管 sessionTelemetry 服务键，把会话遥测投射成 Langfuse 的 traces、observations、scores 和 dataset items，脱敏与同意时机仍由 harness 采集侧负责。

[!NOTE]
这是 host-only 的 DSH 包，不附带 dsh.client Web 包。

安装

需要已有 DeepSeek Harness 安装。

1. 用 dsh plugin 安装已发布的插件

这是 DSH 包的标准工作流。想让 DSH 直接从已发布的包、tarball、本地路径或 git spec 管理插件时，用它。

dsh plugin --profile web add @yuntwoyuntwo/dsh-langfuse-plugin

确认组装后的配置档已读到该包，然后重启 DSH：

dsh --profile web --dump-config
dsh web

要移除：

dsh plugin --profile web remove @yuntwoyuntwo/dsh-langfuse-plugin

这条路径下，配置由环境变量驱动，走包内发布的 cordis.patch.yml。

2. 全局 npm 安装 + install 辅助命令

想要一个全局辅助命令、由安装器管理配置档补丁时，用这条便捷路径。GUI 启动的 DSH 尤其适用，因为 shell 环境变量可能继承不到。

npm install -g @yuntwoyuntwo/dsh-langfuse-plugin

在同一个 shell 里导出 Langfuse 的值，然后运行安装器：

export LANGFUSE_PUBLIC_KEY=pk-lf-...
export LANGFUSE_SECRET_KEY=sk-lf-...
export LANGFUSE_BASE_URL=https://cloud.langfuse.com
export LANGFUSE_ENV=local-verify
export LANGFUSE_RELEASE=dsh-langfuse-plugin-web-check

dsh-langfuse-plugin install --profile web

它会做这些事：

1. 运行 dsh plugin --profile web add <this-package>
2. 往 $DSH_HOME/profiles/web/cordis.patch.yml 写入一个由安装器管理的块
3. 在该块里存下 Langfuse 的字面值，这样 GUI 启动的 DSH 会话就不依赖你当前 shell 的环境

验证并启动：

dsh --profile web --dump-config
dsh web

要移除辅助命令管理的安装：

dsh-langfuse-plugin uninstall --profile web

这条命令只从目标配置档移除插件依赖，以及本工具管理的补丁块。它不会碰无关的插件行或用户配置。

什么时候要重跑 install

以下情况请重新运行 dsh-langfuse-plugin install：

- 改了 LANGFUSE_* 的值
- 升级了全局安装的包
- 换到了别的 DSH_HOME
- 新建了配置档，也要加载该插件

安装器会改哪些文件

对每个目标配置档，辅助命令可能更新：

- $DSH_HOME/profiles/<profile>/cordis.patch.yml

包依赖本身仍通过 dsh plugin --profile <profile> add ... 安装。

3. 从源码构建

本地开发，或者直接改插件源码反复调试时，用这个流程。

git clone <your-repo-url>
cd dsh-langfuse-plugin
pnpm install
pnpm build
dsh plugin --profile web add .

这样会把目标配置档链接到本地检出目录。改完源码后，重新跑一遍 pnpm build 再测试。这和已发布包的流程不一样：配置档指向你的工作区，而不是 registry 里的产物。

要移除这种源码链接方式的安装：

dsh plugin --profile web remove @yuntwoyuntwo/dsh-langfuse-plugin

验证

1. 验证包的安装路径

发布之后，值得站在真实用户的角度验证一遍安装。

标准 bundle 安装

dsh plugin --profile web add @yuntwoyuntwo/dsh-langfuse-plugin
dsh --profile web --dump-config

你应该能看到一行 session-telemetry-langfuse，它的 name 是 @yuntwoyuntwo/dsh-langfuse-plugin。

全局 helper 安装

npm install -g @yuntwoyuntwo/dsh-langfuse-plugin
dsh-langfuse-plugin help

如果你想让 helper 直接给某个配置档打补丁，运行：

dsh-langfuse-plugin install --profile web
dsh --profile web --dump-config

2. Web 端到端验证（推荐）

推荐走这条验证路径，因为它和真实的安装目标一致：把插件挂载到 web 配置档，打开 DeepSeek Harness Web UI，发一条消息，确认产生的会话遥测数据出现在 Langfuse 里。

1. 在启动 DSH 的 shell 里导出 Langfuse 凭据和真实的 DeepSeek API key。
2. 如果想做隔离运行，安装插件前先从一个全新的 DSH_HOME 开始。
3. 把这个 bundle 装进 web 配置档，用 dsh plugin ... add ... 或 dsh-langfuse-plugin install 都行。
4. 启动 dsh web，打开 UI，创建一个会话，发一条简短消息。
5. 到 Langfuse 里查看上报的 trace。

用已发布包的示例：

export DEEPSEEK_API_KEY=sk-...
export LANGFUSE_PUBLIC_KEY=pk-lf-...
export LANGFUSE_SECRET_KEY=sk-lf-...
export LANGFUSE_BASE_URL=https://cloud.langfuse.com
export LANGFUSE_ENV=local-verify
export LANGFUSE_RELEASE=dsh-langfuse-plugin-web-check

export DSH_HOME="$(mktemp -d)"

dsh plugin --profile web add @yuntwoyuntwo/dsh-langfuse-plugin
dsh --profile web --dump-config
dsh web

然后打开 Web UI，发一条提示词，确认 Langfuse 收到了新的 trace，且它的 metadata 指回当前工作区/会话。

如果你更想验证源码安装，把 add 命令换成你的本地检出路径即可。

Langfuse 视图示例

你可以在 Langfuse UI 里查看导出的 trace：<https://cloud.langfuse.com/>。下面的截图展示了一条成功的 DeepSeek Harness trace，在 observation 详情面板里能看到预期的 environment、release、session.id 和 cwd metadata。

Langfuse trace UI example
在验证过的运行中，导出的 trace 带有这些字段：

- environment: local-verify
- release: dsh-langfuse-plugin-web-check 或 dsh-langfuse-plugin-live-check
- 标签包含 channel:ledger、channel:ops、mode:full 和 source:deepseek-harness

如果凭据缺失，而 bundle 行仍停留在 mode: FULL，配置档启动会快速失败，报错 publicKey is required outside DISABLED mode。这个失败是预期行为，说明插件在导出开始前就校验了必需的运行时配置。

无头一次性验证

headless 是非 Web 的命令行配置档：它跑一个任务，打印助手回复，然后退出。不需要浏览器 UI 时，用它做快速冒烟测试。

export DEEPSEEK_API_KEY=sk-...
export LANGFUSE_PUBLIC_KEY=pk-lf-...
export LANGFUSE_SECRET_KEY=sk-lf-...
export LANGFUSE_BASE_URL=https://cloud.langfuse.com
export LANGFUSE_ENV=local-verify
export LANGFUSE_RELEASE=dsh-langfuse-plugin-live-check

export DSH_HOME="$(mktemp -d)"

dsh plugin --profile headless add /Users/bytedance/go/src/yuntwo/dsh-langfuse-plugin
dsh --profile headless "Reply exactly: LANGFUSE_LIVE_VERIFY_OK"

无头验证成功时，会在本地打印出预期回复，同时为同一个会话发出一条 Langfuse trace。

说明

- 自带的 web 和 headless 配置档可以保留内置的 session-telemetry-otel 行。这个插件作为额外的 exporter 组合进来，不会替换官方后端。
- 在不同配置档或 DSH 版本之间切换时，用全新的 DSH_HOME 是避免旧会话持久化格式不匹配的最简单办法。
- 要做反馈门控导出，把该行改成 mode: FEEDBACK_ONLY，在会话里记录反馈，然后确认 Langfuse 收到了释放的前缀，以及任何已配置的 score 或 dataset 写入。

配置

把 bundle 加到 DSH 配置档，然后配置 sidecar exporter 行：

- id: session-telemetry-langfuse
name: '@yuntwoyuntwo/dsh-langfuse-plugin'
config:
mode: FULL
publicKey: !!js process.env.LANGFUSE_PUBLIC_KEY
secretKey: !!js process.env.LANGFUSE_SECRET_KEY
baseUrl: !!js process.env.LANGFUSE_BASE_URL ?? 'https://cloud.langfuse.com'
environment: !!js process.env.LANGFUSE_ENV
release: !!js process.env.LANGFUSE_RELEASE
flushAt: 20
flushInterval: 1000
requestTimeout: 5000
shutdownTimeoutMillis: 3000
dataset:
enabled: true
name: deepseek-harness-feedback
runName: feedback-run
scores:
enabled: true
name: feedback

| mode | 行为 |
| FULL | 实时捕获：每条投影记录一追加就交给 Langfuse。 |
| FEEDBACK_ONLY | 反馈门控捕获：只释放到已记录的 feedback/record 事件为止的规范前缀。 |
| DISABLED | 默认的仅本地模式。插件不构造 Langfuse 客户端，也不导出任何内容。 |
publicKey 和 secretKey 在 DISABLED 之外都是必填项。baseUrl 必须是合法的 http(s) URL。shutdownTimeoutMillis 是后端持有的外层上限，用来在拆除阶段排空排队中的 Langfuse 工作。dataset.enabled 和 scores.enabled 都是可选开启；trace 导出与这些后续写入相互独立。

什么数据会离开本机

插件导出的是 session-telemetry/record 瀑布流之后、遥测接缝交出的全部内容。/feedback 的共享披露仍归官方挂载的 sessionTelemetry 后端所有（如果有的话）；这个 sidecar 导出器不会取代那个服务。没有挂载脱敏规则时，导出的内容包含原始会话内容，例如用户提示词、助手消息、工具参数与结果、请求头、命令输出、文件内容、反馈文本，以及会话工作目录。本插件不会再加一层脱敏。

服务商凭据不来自会话日志。它们是构造函数配置，始终留在导出的遥测记录之外。

字段映射

插件为每个 DSH 会话使用一条 Langfuse trace。稳定的 trace id 由 session.id 推导而来。

投影出的 observation：
- 每个 (turn, step) 一条 generation
- 每个工具调用/结果对一条 span
- 不开启也不关闭 generation/span 的 ledger 记录，各一条 event
- agent-error、shutdown 这类 ops 记录，各一条 trace 级 event

插件为 trace、generation、span、dataset item 以及由反馈导出的内容保留确定性 id，这样重放或重新加载产生的重复项，可以靠远端去重或人工检查容忍。插件保留接缝的尽力投递模型：交接发生在后端边界，而不是等 Langfuse 确认持久化。

Dataset 与 score 行为

scores.enabled 为 true 时，每条记录下来的反馈条目都会在所属 trace 上发出一个分类 Langfuse score。

dataset.enabled 为 true 时，每条记录下来的反馈条目还会：
- upsert 配置的 dataset，
- upsert 一个由已释放会话前缀推导出的 dataset item，
- 写入一个 dataset run item，绑定到配置的 run 名称。

第一版刻意把范围收得很窄。Dataset item 由最近可见的用户与助手记录，加上已释放前缀的元数据推导而来；插件不运行本地评估器，也不合成额外判断。

模型体验

无。本插件只观察会话遥测，并把脱敏后的副本转发给 Langfuse；它从不参与模型请求。

KV Cache 影响

无；本插件既不组装也不发送服务商请求。

已知限制与后续工作

- 事件到 observation 的投影是近似的 —— 插件把当前 DSH 事件词汇映射到 Langfuse 的 trace、generation、span 和 event，并不声称对未来的每个会话事件都能做到语义上的完全同构。
- 没有内置的脱敏规则 —— 只要导出范围超出可信边界，部署方就必须自己挂载 session-telemetry/record 规则集。
- 只导出由反馈衍生的数据集 —— 数据集条目和运行条目都来自记录下来的反馈，而不是每一个成功轮次，并且目前还没有本地评估器流水线。
- 关闭时限只做尽力而为 —— 如果 Langfuse 传输任务在 shutdownTimeoutMillis 之前没有结束，拆除流程就不再等待，尾部记录可能丢失。

附录

插件开发辅助技能

如果你正在构建或迭代 DeepSeek Harness 插件，可以用 dsh-plugin-development 技能作为一份引导式清单，覆盖 bundle/profile 契约、宿主与客户端边界、测试，以及真实组合验证。

参考：

- <https://github.com/NanmiCoder/dsh-agent-teams/tree/main/skills/dsh-plugin-development>