leungBH/dsh-langfuse

dsh-langfuse

这是一个社区版 DeepSeek Harness Bundle，每个 agent turn 导出一条 Langfuse Trace。Trace 以 session.turn 为根，LLM 请求作为直接 GENERATION 子节点，工具执行作为直接 TOOL 子节点；同时通过 OTLP/HTTP 导出 LLM、工具和活跃 Session 指标。

从 GitHub 安装

安装时固定已经审查过的发布标签：

dsh plugin --profile headless add github:leungBH/dsh-langfuse#v0.1.0

Git 安装会从源码构建该 TypeScript 包。pnpm 10 及以上版本第一次安装时可能要求授权 prepare 脚本。把 pnpm 报告的准确包名写入 $DSH_HOME/profiles/headless/pnpm-workspace.yaml：

allowBuilds:
dsh-langfuse: true

然后重新安装并检查 Bundle 层：

dsh plugin --profile headless add github:leungBH/dsh-langfuse#v0.1.0
dsh --profile headless --dump-config

有效配置中应出现 dsh-langfuse Bundle 层，以及 dsh-langfuse-tracing、dsh-langfuse-metrics、dsh-langfuse-instrumentation 三行。

配置 Langfuse

插件不会保存凭据，也不会修改 DSH 当前选择的模型。先通过正常 DSH settings 配置可用模型，再填写 Langfuse 凭据：

cp .env.example .env
填写 LANGFUSE_PUBLIC_KEY 和 LANGFUSE_SECRET_KEY。

运行脚本会在内存中构造标准 OTLP Basic authorization header，并启用两个 exporter：

./examples/run-demo.sh "列出当前目录前三个文件"
Windows PowerShell：
./examples/run-demo.ps1 "列出当前目录前三个文件"

DSH_TRACE_CONTENT 默认为 OFF。只有确认可以向目标项目上传 prompt、回复、工具参数和工具结果时，才将它设为 FULL。

数据模型

- 一个 DSH Session 通过 langfuse.session.id 映射到一个 Langfuse Session。
- 每个 DSH turn 映射为一条 Langfuse Trace。
- session.turn 是根 SPAN。
- LLM 调用是直接 GENERATION 子节点，携带模型、token、TTFT、时长和结果状态。
- 工具执行是直接 TOOL 子节点，携带工具名、时长和结果状态。
- 成功、失败、Session 释放或插件卸载时，子节点都先于根节点关闭。

环境变量

| 变量 | 用途 |
|---|---|
| LANGFUSE_PUBLIC_KEY | 示例脚本使用的项目级 Langfuse public key |
| LANGFUSE_SECRET_KEY | 示例脚本使用的项目级 Langfuse secret key |
| LANGFUSE_BASE_URL | Cloud 区域或自托管地址；默认 https://cloud.langfuse.com |
| DSH_TRACE_MODE | FULL 启用 Trace 导出；Bundle 出厂默认 DISABLED |
| DSH_METRICS_MODE | FULL 启用指标导出；Bundle 出厂默认 DISABLED |
| DSH_TRACE_CONTENT | OFF 或 FULL；默认只上传 metadata |
| DSH_OTEL_EXPORTER_OTLP_TRACES_ENDPOINT | 显式 OTLP Trace endpoint |
| DSH_OTEL_EXPORTER_OTLP_METRICS_ENDPOINT | 显式 OTLP Metric endpoint |
| OTEL_EXPORTER_OTLP_HEADERS | 标准 OTel exporter header；示例脚本在此设置 Basic authorization |

兼容性与限制

首个版本面向尚未内置 sessionTracing 和 sessionMetrics 服务的 DSH 官方版本。DSH 仍处于预发布阶段，每次升级后都应重新验证固定的插件 commit。不要在已经挂载这些服务的 DSH 版本中同时安装该社区 Bundle；应先禁用或移除社区 Bundle。

独立版暂不保证 active trace context 穿过 provider HTTP 请求、本地 subprocess 或 subagent fork。这些路径需要稳定的上游扩展点。插件自身产生的 turn Trace 仍然结构完整，不包含孤儿 observation parent。

Langfuse Cloud 接受 OTLP traces 和 metrics，但不接受 OTLP logs。Collector 导出失败由 OTel SDK 报告，不会替代 agent 结果。

开发

pnpm install
pnpm run build
pnpm run typecheck
pnpm test
pnpm pack --pack-destination .artifacts

本项目包含从 MIT 许可的 DeepSeek Harness observability packages 派生的代码，详见 LICENSE。