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 的执行细节和性能指标进行观测。
