运行时健康监测 MathieuPortmann/dsh-agent-flight-recorder

dsh-agent-flight-recorder

为 DeepSeek Harness（DSH）智能体提供实时运行时健康监测。
它实时观察工具调用，当智能体开始原地打转时，同时通知你（面板）和模型（简短提示）。

维护说明： 尽力维护。Issue 可能无人回复；欢迎 fork。

功能

- 循环检测：观察最近 100 次工具调用，识别同一工具连续调用多次（即使参数略有不同，也能识别——这类情况会让「完全相同调用」检测器失效）、同一错误反复出现、错误率偏高。
- runtime_health 工具：模型怀疑自己卡住时可以调用。返回调用次数、错误率、平均延迟、最常用工具、状态（healthy / warning / critical）、loopRisk 估计值（0..1）、原因和建议。
- 实时告警：越过阈值时，在工具结果里追加约 40 token 的提示。
- 每轮摘要：每轮结束后发给模型（健康时约 20 token）。
- Web UI：输入框下方有 Runtime Health 标签，点开是面板；每轮完成后显示一行摘要；还有详细对话报告（token、工具、「待核实点」，比如文件写到了意料之外的路径，或引用了来源却没做任何搜索）。
- 界面支持英文和法文。

它只观察和标注：不联网、不执行 shell、不写文件、不阻塞。
所有状态都从持久会话日志推导，因此刷新页面不会丢，卸载插件后自动消失。规则和 loopRisk 公式见 SPEC.md。

安装

dsh plugin --profile web add dsh-agent-flight-recorder
or straight from GitHub:
dsh plugin --profile web add github:MathieuPortmann/dsh-agent-flight-recorder

装完重启配置档。需要 Node ^22.19.0 || >=24 和 DSH >=0.2.0-rc.2 <0.3.0（见兼容性）。

可选配套插件：@beibeihk/dsh-agent-observability （按会话持久记录，/observe 报告）。本插件不依赖它。

配置

在配置档的 cordis.patch.yml 里找到 agent-flight-recorder 行；所有键都可选。

| 键 | 默认值 | 含义 |
| windowSize | 100 | 规则保留的工具调用数 |
| sameToolWarning / sameToolCritical | 4 / 6 | 同一工具连续调用次数 |
| sameErrorWarning / sameErrorCritical | 2 / 3 | 同一归一化错误重复次数 |
| errorRateWarning / errorRateCritical | 0.2 / 0.3 | 错误率（在 errorRateMinCalls 之后计算，默认 10） |
| shellTools | [bash, pwsh] | 视为 shell 命令的工具 |
| turnSummaryToModel | true | 把每轮摘要发给模型 |
| liveAlerts | true | 在工具结果里追加告警 |

兼容性

| 组件 | 支持范围 |
| Node.js | ^22.19.0 \|\| >=24.0.0（engines.node） |
| DSH | >=0.2.0-rc.2 <0.3.0；在 @deepseek-ai/dsh-tools、@deepseek-ai/schemastery（>=3.18.0 <4.0.0）和 zod（>=4.0.0 <5.0.0）上声明为可选 peerDependencies，这几个包由插件从 DSH 安装目录加载 |
| 平台 | Linux（已测试）；纯 JavaScript，无原生扩展 |

已在 Node 22.23 上用 DSH 0.2.0-rc.2 测试（见验证）。

权限与外部服务

| 能力 | 是否使用 | 说明 |
| 文件 | 否 | 插件本身不读写磁盘；状态保存在 DSH 会话日志中 |
| 网络 | 否 | 不发起任何请求 |
| 命令 | 否 | 不启动任何进程 |
| 动态模块加载 | 是 | index.js（importFromDsh）从运行插件的 DSH 安装目录加载 zod、@deepseek-ai/dsh-tools 和 @deepseek-ai/schemastery（在 Node 22 上同步 require 一个 ES 模块会失败）。不下载任何内容，也不从文本求值代码（未使用 eval / new Function）。如果 DSH 不提供这些包，插件加载失败 |

它新增一个只读工具（runtime_health）；开启 liveAlerts 时，还会在工具结果后追加简短告警。它从不阻塞或修改工具调用。

验证

在一个一次性配置档上验证过（DSH_HOME 指向临时目录，配置档用 dsh <name> --from-default-profile web 克隆，因此真实配置档不受影响）：

npm pack
dsh plugin --profile t add file:$PWD/dsh-agent-flight-recorder-0.1.0.tgz # install
dsh --profile t --no-open --port 3095 # start: plugin loads, no error
dsh plugin --profile t remove dsh-agent-flight-recorder # uninstall

npm test 运行独立测试，无需安装 DSH；只有加载测试例外，DSH 不存在时会跳过。

开发

npm test

许可证

MIT