前言¶
在 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 协议流量。对于需要在终端和聊天界面中排查问题的开发者，这是一个实用的工具。
