DeepSeek Harness (DSH) 擁有官方的 Session 日誌用於審計，但在日常開發中，調試 Agent 運行時通常需要更細粒度的指標（如 Token 使用量、工具調用耗時）或可視化的瀑布圖。該插件將 Session 事件轉換爲運行時追蹤記錄，並生成本地文件，配合查看器進行快速分析。
這是一個 DeepSeek Harness 插件，用於寫入緊湊的本地 JSONL 追蹤文件，並提供一個實時的只讀查看器。它由 bluefateludi 維護，旨在將會話事件轉換爲運行、步驟、模型和工具計時記錄，而不替換官方的 Session 日誌。
核心功能¶
該插件主要提供以下能力：
- 本地 JSONL 追蹤：將 Session 事件轉換爲緊湊的本地 JSONL 追蹤文件。
- 實時查看器：提供一個本地運行的、只讀的 Web 查看器。
- 詳細記錄：記錄 Agent 運行、模型步驟、工具調用、計時、結果和 Token 使用量。
- 可視化展示：在查看器中呈現會話譜系、瀑布圖、事件詳情、失敗情況、Token 使用量、時間間隙和截斷值。
安裝與啓用¶
首先安裝該插件包：
npm install dsh-agent-run-logger
將插件添加到 DeepSeek Harness 的 Profile 中：
dsh plugin --profile trace-demo add dsh-agent-run-logger
dsh --profile trace-demo --dump-config
dsh --profile trace-demo
插件會默認增加以下配置行（可通過 Profile Patch 覆蓋）：
- id: agent-run-logger
name: dsh-agent-run-logger
config:
outputDir: .dsh/traces
includeContent: false
maxContentBytes: 65536
maxPendingBytes: 4194304
redactSensitiveContent: true
redactKeys: []
其中 outputDir 可爲絕對路徑或相對於 Session 工作目錄的路徑。redactKeys 可用於添加自定義的敏感字段名（不區分大小寫）。
典型用法¶
安裝並配置完成後，啓動 DeepSeek Harness 即可開始記錄。要查看生成的追蹤數據，在項目根目錄（即包含 .dsh/traces 的目錄）下運行查看器命令：
npx dsh-agent-run-logger view
該命令默認綁定到 127.0.0.1，端口從 4318 開始，並在瀏覽器中打開儀表板。它不接受遠程連接。
常用查看器選項如下：
--trace-dir <path> 追蹤目錄（默認：.dsh/traces）
--port <number> 偏好的迴環端口（默認：4318）
--poll-ms <number> 刷新間隔（默認：750）
--page-size <number> 每頁返回的記錄數（默認：500）
--no-open 打印 URL 而不打開瀏覽器
--retention-days <days> 啓動時刪除舊的 JSONL 文件（默認不刪除）
適用場景與注意事項¶
適用場景：
* 需要分析 Agent 運行時 Token 使用情況。
* 需要調試工具調用的耗時和結果。
* 需要可視化的瀑布圖來理解事件執行順序。
注意事項：
* 內容捕獲默認關閉：爲避免泄露敏感信息，默認不記錄 Prompt、回覆、工具參數和結果。如果確實需要，需設置 includeContent: true，但插件會在記錄前對包含憑證特徵的值進行脫敏，並限制每個值的 UTF-8 字節長度。
* 僅記錄激活後的事件：插件只觀察激活後的提交事件，不會回填官方 Session 歷史記錄。
* 子會話處理：子 Agent 會話會生成單獨的文件。查看器在兩個文件都存在時，可以通過 parentSessionId 關係導航，但不會合並它們的時間軸。
* 查看器侷限性：查看器僅限本地訪問，不提供認證、遠程導出、追蹤上傳、數據庫或 OpenTelemetry 集成功能。
* 文件性質：追蹤文件是診斷工具，不能替代官方的 DeepSeek Harness Session 日誌。
* 數據安全：操作系統或電源故障仍可能導致未同步尾部的數據丟失。
總結¶
dsh-agent-run-logger 提供了一種輕量級的方案，讓開發者能夠將 DSH 會話數據轉換爲本地 JSONL 追蹤，並利用內置查看器快速定位運行時問題。它適合在開發階段對 Agent 的執行細節和性能指標進行觀測。
