d3vmeh/dsh-logbook

dsh-logbook

一个 DeepSeek Harness 插件，让 ctx.logger 的输出变得可见：聊天中的 /logs 命令，以及一个默认对警告和错误开启的 stderr 导出器。

它解决的问题

每个 dsh 插件都通过 ctx.logger 记录日志，但没有任何随附的 profile 挂载日志接收器。唯一的默认目标是 1000 条记录的内存缓冲区，而这个缓冲区有一个意外之处：它会静默丢弃 warn 和 debug 记录。Cordis 将其级别排序为 error=0、info=1、warn=2、debug=3，而缓冲区导出器会回退到每个 logger 的默认级别 1，因此警告永远无法进入。插件可以就真实问题发出警告，但无论实时还是事后都无从查看（讨论 #2905、#1241、#4994）。

dsh-logbook 注册一个全量捕获导出器（它向 cordis 请求一切，然后自行过滤），并为你提供两种视图：

1. stderr，实时。 默认仅警告和错误，因此健康的会话保持静默。可通过配置映射按插件开放。绝不写入 stdout，stdout 保持空闲以供 SDK 和 ACP 协议流量使用。
2. 聊天中的 /logs。 最近历史（默认环形缓冲区 2000 条记录，所有级别），带过滤器：

/logs
/logs --level warn
/logs --name llm-gate --grep queue
/logs --since 10m --limit 100

logs: 3 of 41 records shown (ring 2000, buffer seeded 12)
14:01:59 llm-gate info llm-gate: llamacpp session=059a680f queued (depth 1)
14:02:03 llm-gate info llm-gate: llamacpp session=059a680f dispatched after 4012ms
14:02:11 llm-gate warn llm-gate: llamacpp session=059a680f queue full, rejecting

安装

dsh plugin --profile web add dsh-logbook

这就足够了。要调整它，请添加到你的 profile 的 cordis.patch.yml：

- id: logs
config:
ring: 2000            # records kept for /logs
stderr:
enabled: true
types:
default: warn     # error | warn | info | debug | off
llm-gate: debug   # everything from one plugin
hmr: off          # silence one logger entirely

一个值意味着“此类型及更严重的任何类型”，顺序为 error、warn、info、debug。这有意区别于 cordis 的数字级别，在后者中 info 位于 warn 之下，且“仅警告和错误”无法表达。

你应该知道的事

- 环形缓冲区从插件挂载那一刻起捕获所有级别，并从内置缓冲区为更早的任何内容进行播种。挂载之前的记录只能是 error 和 info，原因就是上述缓冲区行为。
- stderr 写入器附加了一个错误监听器，因此关闭的管道（例如正在终止的 tee）不会导致 dsh 崩溃，并且它绝不会向日志路径抛出异常。
- 上游说明：cordis 的 ctx.logger.exporter() 清理器目前移除的是最近注册的导出器，而不是它自己的，因此任何插件重载都可能分离掉其他插件的日志接收器。dsh-logbook 保留一个内部标志，使其导出器的过期副本变为惰性，而不是重复上报。
- 相关工作：dsh-logger-panel 是一个带有轮转 JSONL 文件的 Web 设置页面；dsh-boot-doctor 挂载了一个针对启动问题的最小控制台接收器；dsh-o11y-plugin 导出到 OpenTelemetry。dsh-logbook 是终端和聊天选项：过滤器、stderr、无 Web 依赖、可在无头环境下工作。

许可证

MIT