返回目錄

dsh-observe

精選清單收錄維護狀態: 活躍

perrylink/dsh-observe

可觀測性匯出外掛,將輪次、工具與 LLM 呼叫跨度及費用指標匯出至 OpenTelemetry/Langfuse。

前往 GitHub專案首頁
$ dsh plugin --profile web add dsh-observe

16

星數

2

Fork

TypeScript

語言

Apache-2.0

授權條款

2026-08-16

建立於

2026-11-18

最近推送

Apache-2.0 的 TypeScript 外掛(dsh 0.2.x、Node ^22.19 || >=24.9):被動把 DeepSeek Harness 工作階段匯出成 OTLP trace/指標與 Langfuse observations,內建外送前脫敏、有界離線緩衝與退避重試。

DSH 整合

原生執行環境

作者聲明

安全稽核

未稽核

最後核實

2026-11-20

授權條款

Apache-2.0

01它能幫你完成什麼?

  • 把 DeepSeek Harness 的每個工作階段接進既有的可觀測性平台,變成標準 trace 與指標

    一個 turn 一條 trace,底下掛 step、工具呼叫(耗時、狀態、重試推導)與 LLM 生成的 span;另有依 provider/model 的 token 計數、USD 成本計數與選用的上下文壓力 gauge

    需要在 OpenTelemetry 或 Langfuse 上看清楚工作階段延遲、工具使用與花費的 Agent/平台工程師

  • 開啟 prompt/completion 層級的觀測,同時不把金鑰與原文送出去

    在進佇列、進緩衝、外送之前就完成鍵名脫敏、金鑰樣式清理與字元預算截斷的紀錄;只要體積時還能只送大小與計數

    有資料合規要求、但仍想拿到 LLM 層級追蹤的團隊

  • 後端不穩或斷網時既不丟觀測資料,也不拖住 harness

    非同步批次投遞加上確定性指數退避重試,重試用盡後落到有界持久緩衝;重新啟動後未送達批次仍在

    不能接受「觀測後端一掛就卡住工作階段」的維運與 SRE 人員

02如何將外掛接入 DeepSeek Harness?

先決條件

  • Node `^22.19.0 || >=24.9.0`——純 ESM 套件,執行期相依只有 `zod`
  • DeepSeek Harness CLI 的 engines 落在 `>=0.2.1-0 <0.3.0` 或 `>=0.2.2-0 <0.3.0`(外掛以 `@deepseek-ai/dsh@0.2.2-rc.1` 開發與測試)
  • 至少一個後端:OTLP/HTTP 位址(`/v1/traces` 與 `/v1/metrics` 由外掛附加),或 Langfuse 的 `baseUrl` + `publicKey` + `secretKey`

安裝步驟

  1. 01

    裝進 profile:npm 已發佈版本用 `dsh plugin --profile web add dsh-observe`;要最新 main 用 `dsh plugin --profile web add github:PerryLink/dsh-observe`;本倉庫 `pnpm pack` 出來的 tarball 用 `dsh plugin --profile web add ./dsh-observe-<version>.tgz`。

    $ dsh plugin --profile web add dsh-observe

  2. 02

    如果 pnpm 回報 `ERR_PNPM_IGNORED_BUILDS`(esbuild 平台二進位的無害檢查),在 `pnpm-workspace.yaml` 加上 `allowBuilds: { esbuild: true }`,dsh CLI 會印出確切片段。

  3. 03

    在 profile patch 裡打開:`cordis.patch.yml` 那一行預設是關的,需要設 `enabled: true` 並配好 `otlp.endpoint` 或 `langfuse.baseUrl` + `langfuse.publicKey` + `langfuse.secretKey`,兩個後端可以同時開。

驗證整合成功

  • `dsh --profile web --dump-config | grep -A2 'id: dsh-observe'`,確認外掛那一行與你填的值都進了 profile。
  • 沒有 `/observe` 之類的指令可以手動觸發:看後端是否收到第一條 trace 與指標(Langfuse 端是 observations);把 `remote.enabled` 設成 `true` 後,`observe/status` 能讀到已設定的後端、佇列深度與離線緩衝佔用。

復原

  • `dsh plugin --profile web remove dsh-observe`;或直接從 profile patch 刪掉那一行。

03DSH 整合程度與能力邊界

DSH 整合原生執行環境

以 `dsh plugin --profile <name> add dsh-observe` 裝進 profile 的原生外掛;只訂閱 harness 的 session/event 事件流,把它匯出成 OTLP trace/指標與 Langfuse observations,不註冊任何工具或指令。

  • turn/step/工具/LLM span

    harness 的 session/event 事件流→一個 turn 一條 trace,底下是 step、工具呼叫(耗時、狀態、重試推導)與 LLM 生成 span;span 與 trace 的 id 確定性可重現

  • token/成本/上下文指標

    工作階段事件裡的 provider/model 屬性,以及選用的 `pricing` 價格表→依 provider/model 的 token 計數、USD 成本計數(第一筆符合的價格規則生效),以及依賴 `ctx.tokenMeter` 的上下文壓力 gauge

    沒有 `pricing` 規則命中模型時不會產生成本指標
  • 外送前脫敏與截斷

    prompt、completion、工具參數與工具結果→結構性鍵名脫敏、內建金鑰樣式加自訂正規表示式、字元預算(prompt/completion 各 4000,工具參數與結果各 2000,span 屬性 512)處理後的紀錄

    正文會被截斷,超長的 prompt/completion 不會原樣保留
  • 非同步批次與持久緩衝

    已進佇列的 span 與指標紀錄→依數量(256 筆)或定時(5000ms)flush,失敗以 5 次嘗試、1000ms×2 確定性退避(上限 60000ms)重試,最後溢到有界持久 spool(10000 筆、最舊優先淘汰),每 30000ms 回灌一次且重新啟動後仍在

    緩衝會佔用儲存空間;容量有界,超出後淘汰最舊紀錄從儲存讀回的紀錄在交給 sink 前會再校驗一次
  • 執行期總開關

    `observe/setEnabled`,僅在 `remote.enabled: true` 時可用→不解除安裝也能停止/恢復匯出;`observe/status` 回傳總開關狀態、已設定後端、佇列深度與緩衝佔用

    會向 profile 註冊一個名為 `observe` 的 remote 服務,同一個 profile 裡不要重複註冊同名服務

04適合誰?何時不該用?

適合

  • 需要在 OpenTelemetry 或 Langfuse 上看清楚工作階段延遲、工具使用與花費的 Agent/平台工程師
  • 有資料合規要求、但仍想拿到 LLM 層級追蹤的團隊
  • 不能接受「觀測後端一掛就卡住工作階段」的維運與 SRE 人員

不適合

  • 兩邊都綁版本:`engines.dsh` 為 `>=0.2.1-0 <0.3.0 || >=0.2.2-0 <0.3.0`,目前基準是 `@deepseek-ai/dsh@0.2.2-rc.1`;套件本身要求 Node `^22.19.0 || >=24.9.0` 且為純 ESM。對應的是工作階段格式 V4(工具結果成為 `role: 'tool'` 的一等訊息),因此定位在 0.2.x 這條 harness 線上。
  • Langfuse 公鑰/私鑰與 OTLP 請求標頭只送往你自己設定的端點,外掛本身不儲存任何憑證;README 明確要求用憑證引用或環境注入,不要把金鑰寫進 profile patch 一起提交。

05相容性、維護與安全提醒

  • 兩邊都綁版本:`engines.dsh` 為 `>=0.2.1-0 <0.3.0 || >=0.2.2-0 <0.3.0`,目前基準是 `@deepseek-ai/dsh@0.2.2-rc.1`;套件本身要求 Node `^22.19.0 || >=24.9.0` 且為純 ESM。對應的是工作階段格式 V4(工具結果成為 `role: 'tool'` 的一等訊息),因此定位在 0.2.x 這條 harness 線上。
  • Langfuse 公鑰/私鑰與 OTLP 請求標頭只送往你自己設定的端點,外掛本身不儲存任何憑證;README 明確要求用憑證引用或環境注入,不要把金鑰寫進 profile patch 一起提交。
  • 只申請三項權限:對你設定的端點出網、讀取工作階段事件流、寫入離線緩衝。沒有原生程式碼、不存取檔案系統,也不註冊模型工具、使用者可見指令或 client slot,只消費即時事件流而不讀取工作階段日誌檔。
  • 沒有取樣:每個啟用的 span 家族都會匯出,高流量設定得自行調整 `capture.*` 開關與 `batch.maxBufferRecords`。另外 OTLP metrics 依設計不走重試/緩衝路徑,漏掉一次 flush 會在下一次累計聚合時自癒。
2026-08-162026-11-13v0.2.29

Apache-2.0 · 活躍維護(最新 release v0.2.29,2026-11-18 發佈)

06常見問題

prompt 與工具參數會照原文送到後端嗎?

不會照原文送出。每筆紀錄在進佇列之前先做三層處理:結構性鍵名脫敏(key/token/secret/password/authorization/credential/apiKey 恆在名單內,可用 `sanitize.redactKeys` 追加子字串)、內建金鑰樣式(API key、GitHub token、AWS key、bearer 憑證、私鑰)加上 `sanitize.redactPatterns` 自訂正規表示式,以及字元預算截斷——prompt 與 completion 各 4000 字元,工具參數與結果各 2000,span 屬性 512。只要體積不要正文時,把 `llm.prompt` 與 `llm.completion` 設為 `false`,紀錄裡只剩大小與計數。

後端掛掉或網路中斷會丟資料嗎?

一般 span 與指標走「重試 → 溢出到離線緩衝」這條鏈:批次依 `retry.maxAttempts`(預設 5 次)與 `retry.baseDelayMs × retry.factor` 的確定性指數退避重試,重試用盡或記憶體佇列超過 `batch.maxQueueRecords` 時溢到有界持久 spool(`batch.maxBufferRecords` 預設 10000,最舊優先淘汰),每 `batch.bufferRetryIntervalMs`(預設 30000ms)回灌一次,重新啟動後未送達批次仍在。OTLP metrics 是 README 寫明的例外:它按累計聚合,漏一次 flush 會在下一次自癒。

思維鏈(reasoning)也會被匯出嗎?

預設會。`llm.reasoning` 是開著的,reasoning 以獨立的 `gen_ai.completion.reasoning` 屬性外送,絕不混進 `gen_ai.completion`;在 Langfuse 裡放在 generation 的 metadata。README 提醒:思維鏈可能包含使用者原文,或模型逐字複述的上下文,外送前請評估合規要求;不需要時設 `llm.reasoning: false`,而 `llm.completion: false` 會同時關掉正文與 reasoning。

會不會拖慢工作階段?

採集與脫敏在事件處理裡同步完成,但傳送全部是非同步的:佇列依數量或定時 flush,`session/flush` 只是一次盡力而為的 kick——持久化檢查點絕不等待遠端後端。匯出失敗會告警、計數(`observe.export_failures`)、重試並最後進緩衝;工作階段事件處理器拋錯會被攔截並記錄,可觀測性不會壓在 harness 的熱路徑上。

同一個 profile 裡會跟其他外掛搶資源嗎?

註冊面很窄:只注入 `storageDomain` 一個服務鍵,只監聽 `session/event`、`session/flush`、`session/disposed` 三個事件,不註冊工具、指令、client slot 或 waterfall。唯一要留意的是選用的 `observe` remote 服務(`remote.enabled`,預設關閉)——同一個 profile 裡若已有其他外掛佔用同名服務,只開其中一個。再裝一個可觀測性外掛本身沒問題(Cordis 的廣播語意不會互相餓死),但你會拿到兩份 trace。

08資料與來源

  • 作者聲明github.com2491014f11d1…

    把每次会话变成标准 OTLP trace 与 Langfuse 观测——发出去之前先脱敏,默认什么都不发。

  • 作者聲明github.com2491014f11d1…

    它只做导出——不注册任何模型工具、不注册用户可见命令,全部行为由配置决定

此頁面根據專案公開文件、儲存庫中繼資料與 DSH Plugins 的結構化解析所產生;最後核實於 2026-11-20。發現錯誤?提交更正。

🏆

最佳 DeepSeek Harness 外掛

從全目錄挑出的 12 個值得優先安裝的外掛,涵蓋各個分類。

DSH Plugins 是獨立的 DeepSeek Harness 外掛目錄,與 DeepSeek 官方無關,也不代表官方背書。第三方外掛未經安全稽核,安裝前請審查原始碼。

每週取得最新的 DeepSeek Harness 外掛,絕不濫發。