前言¶

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