前言¶
在 DeepSeek Harness（DSH）插件開發中，ctx.logger 是標準的日誌輸出接口。然而，默認的配置往往不掛載日誌接收器。DSH 內置了一個 1000 條記錄的內存緩衝區，但它有一個隱藏行爲：靜默丟棄 warn 和 debug 級別的日誌。這導致插件發出的警告無法被查看。dsh-logbook 旨在解決這個問題，它通過提供 /logs 命令和默認開啓的 stderr 導出器，讓日誌輸出變得可見。
插件簡介¶
dsh-logbook 是一個 DeepSeek Harness 插件。插件由開發者 d3vmeh 維護，採用 MIT 許可證。它依賴 @deepseek-ai/schemastery 和 @deepseek-ai/cordis 庫，運行環境需要 Node.js 22 及以上。
安裝與啓用¶
安裝過程非常直接，只需在終端執行以下命令即可啓用插件：
dsh plugin --profile web add dsh-logbook
安裝完成後，插件會自動開啓一個 stderr 導出器。若需調整日誌的保留數量、輸出級別或靜音特定記錄器，需要在配置文件 cordis.patch.yml 中進行修改。
核心功能¶
該插件主要解決 DSH 默認日誌不可見的問題，提供以下能力：
- 使
ctx.logger輸出可見。 - 提供內置的
/logs命令，用於在聊天界面查看日誌。 - 默認開啓 stderr 導出器，將日誌輸出到標準錯誤流。
- 支持
/logs過濾，可按級別、記錄器名稱或正則匹配過濾日誌。 - 支持靜音特定日誌記錄器。
典型用法與配置¶
安裝後，可以直接在聊天框使用 /logs 查看日誌。支持多種參數組合：
/logs
/logs --level warn
/logs --name llm-gate --grep queue
/logs --since 10m --limit 100
若要控制 stderr 的輸出級別或靜音特定記錄器，需編輯 cordis.patch.yml。例如：
- id: logs
config:
ring: 2000 # 記錄保留數量
stderr:
enabled: true
types:
default: warn # error | warn | info | debug | off
llm-gate: debug # 某個插件輸出所有級別
hmr: off # 完全靜音某個記錄器
配置中的值代表“該級別及更嚴重”的日誌，順序爲 error > warn > info > debug。
注意事項¶
使用時需注意以下幾點：
- 緩衝區行爲：DSH 內置緩衝區會靜默丟棄
warn和debug記錄，只有/logs命令能讀取到完整的歷史記錄。 - 管道穩定性：stderr 導出器經過特殊處理，不會因爲管道關閉而崩潰。
- 已知 Bug：Cordis 存在已知 bug，
ctx.logger.exporter()的 dispose 方法會移除最近註冊的導出器而非自身。這可能導致插件重載時丟失其他插件的日誌接收器。dsh-logbook通過內部標誌避免了重複報告，但若同時存在多個日誌插件，需注意可能互相干擾。
總結¶
dsh-logbook 提供了一種無需依賴 Web 界面的輕量級日誌查看方案。它不輸出到 stdout，避免了干擾 SDK 和 ACP 協議流量。對於需要在終端和聊天界面中排查問題的開發者，這是一個實用的工具。
