Agent Run Logger

中文 | English

Agent Run Logger 是一个 DeepSeek Harness 插件，为每个正在运行的 Session 写入一份精简的本地 JSONL trace。它把底层 Session 事件整理成 run、step、模型和工具的计时记录，比直接阅读完整会话日志更方便。

默认情况下，每个 Session 分别写入 /.dsh/traces/。记录会在 Agent 运行期间持续追加；同一 Session 内严格保持源事件顺序，不同 Session 的写入队列相互独立，可以并行落盘。

默认只记录元数据、标识符、耗时、结果状态和 token 用量，不记录提示词、回复、工具参数或工具结果。设置 includeContent: true 后才会记录这些内容。每项内容默认最多保留 64 KiB；超限 JSON 会转换为 UTF-8 安全的头尾预览，原始 Session 日志不会被修改。

事件处理不会等待磁盘 I/O。每个 Session 默认拥有上限为 4 MiB 的独立队列。队列满时会丢弃新 trace 记录，并在之后通过 trace.gap 记录报告缺失的源事件序号范围。目录创建、写入或同步失败时，插件只警告一次并停用对应 Session 的 writer，不会影响 Agent 和其他 Session。

从 tarball 安装

构建并打包插件，然后把生成的压缩包安装到一个 profile：

pnpm install
pnpm pack
dsh plugin --profile trace-demo add ./dsh-agent-run-logger-0.1.0.tgz
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

outputDir 可以是绝对路径，也可以是相对于每个 Session 工作目录的路径。maxContentBytes 和 maxPendingBytes 必须是正整数，单位为字节。

记录类型

当前 schema 版本为 1。插件写入 session.meta、run.start、run.end、step.start、step.end、llm.first_token、llm.end、tool.start、tool.end 和 trace.gap。每条记录都包含 sessionId、sourceSeq 和 time。

限制

• 只观察插件启用后新提交的事件，不回填已有 Session 历史。
• 一个 turn 对应一个 run。Subagent Session 保持独立文件；parentSessionId 记录父子关系，但插件不会生成跨 Session 的完整调用树。
• 不提供查看器、查询 API、远程导出、OpenTelemetry 集成、文件轮转或保留策略。
• includeContent: true 可能把敏感信息写入磁盘。截断限制针对每项捕获内容，不限制整个 trace 文件大小。
• run.end 和插件卸载会请求文件系统同步，但操作系统崩溃或断电仍可能丢失尚未同步的尾部记录。
• trace 只用于诊断，不能替代 DeepSeek Harness 的权威 Session 日志。