dsh-tool-failure-journal：异常工具调用的持久化与聚合日志

前言¶

编码智能体不仅会失败，还会反复以相同的方式失败。在证据被折叠、压缩，或者仅仅是被后续的尝试覆盖到上下文窗口之外之前，没人能看到这种模式。DSH 的会话日志是模型的上下文，它会被重写、折叠和修剪，不适合作为失败历史的存储介质。

本插件提供了一个独立的记录机制，将异常退出的工具调用写入磁盘上的 JSONL 文件，并在进程生命周期之外保存这些数据。

功能概览¶

这是一个 DeepSeek Harness（DSH）主机插件。它监听 tools/result 事件，捕获工具调用中出现的异常、输出 schema 违规、未知工具名、被拒绝的调用或被取消的调用。所有记录都会被追加到磁盘日志中，并通过算法将高度相似的失败折叠为唯一的“签名”和计数。

核心能力包括：

• 签名折叠：将工具名称、错误代码和规范化后的错误信息哈希，将多次相似失败合并为一条记录，便于分析。
• 回归检测：标记在会话早期成功过，但在后续失败的工具调用。
• 内置修复建议：针对特定错误类型（如 COMMAND_NOT_FOUND、EDIT_NO_MATCH 等），记录中会附带明确的修复建议。
• 持久化存储：日志文件持久化存储在 <DSH_HOME>/failure-journal/sessions/ 目录下。

安装与启用¶

安装过程与 DSH 的其他插件一致，通过 dsh plugin 命令将包添加到指定配置文件中。

dsh plugin --profile web add github:catsenior507/dsh-tool-failure-journal

安装完成后需要重启主机以使配置生效，然后通过以下命令验证插件是否正确挂载：

failure_journal action=selftest

selftest 操作会检查观察者是否已挂载，并在日志目录中写入一个测试文件以验证写入权限。

配置项¶

如果需要修改默认行为，可以通过编辑配置文件中的 config 字段来调整。配置文件通常位于 profile 目录下的 cordis.patch.yml 中：

- insert:
    - id: tool-failure-journal
      name: '@dsh-external/dsh-tool-failure-journal'
      config:
        maxBytes: 4194304
        clusterThreshold: 3
        excludeTools: ['todo_write']
        recordSuccesses: false
        exposeTool: true

• maxBytes：单个日志文件的最大字节数（默认 4MB）。
• clusterThreshold：触发签名折叠的相似度阈值。
• excludeTools：需要排除记录的工具列表。
• recordSuccesses：是否记录成功调用的日志（默认为 false，设为 true 可追踪命令的实际执行结果）。
• exposeTool：是否将 failure_journal 工具暴露给 agent。

使用方式¶

插件通过 failure_journal 工具暴露给智能体，支持以下操作：

示例用法：

failure_journal action=stats
failure_journal action=list
failure_journal action=show 9f2c1ab73e04
failure_journal action=sessions
failure_journal action=clear

存储与设计¶

• 文件存储：日志以 JSONL 格式存储，每个会话对应一个文件（<sessionId>.jsonl）。
• 日志保留：文件按大小轮转，但轮转后的旧文件会被保留，不会被删除。这确保了当智能体陷入循环错误时，历史数据仍然可用。
• 运行机制：观察者运行在进程内，执行同步的追加写入操作，不阻塞主流程。它不依赖构建步骤、原生代码或运行时的网络请求。

注意事项¶

• 依赖环境：插件需要 Node.js 版本 >= 20。
• 权限要求：插件以当前 DSH 进程的权限运行，请确保目录可写。
• 许可证：MIT 许可证。

链接¶

• GitHub 仓库
• DSH 生态目录