前言¶

用 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）¶

詞彙與同意語義與官方 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

說明：

1. bundle 層與環境變量在進程啓動時讀取；已運行的實例需在已 export 變量的 shell 裏重啓後才生效。
2. LANGFUSE_HOST 決定數據落入哪個區域的 Langfuse 控制檯；項目密鑰與區域綁定，US 項目的 trace 不會出現在 EU 控制檯。
3. 可用 dsh --profile web --dump-config 查看合成配置，應出現 # == dsh-plugin-langfuse 層及 session-telemetry-langfuse 條目。
4. 下一輪對話結束後，trace 應出現在對應區域控制檯。
5. 卸載：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