前言¶
在 DeepSeek Harness（DSH）里跑多步智能体时，常见情况是工具被反复调用、同类错误堆叠，或模型在「略改参数」的同一工具上打转——人眼要事后翻日志才能发现。社区插件 dsh-agent-flight-recorder（维护者 MathieuPortmann，GitHub：MathieuPortmann/dsh-agent-flight-recorder）只做观测与标注：基于会话持久日志推导状态，不联网、不启 shell、不写文件、不拦截工具调用，并在界面与模型侧同时给出简短健康信号。
这是什么¶
一句话：为 DSH Web 智能体提供实时运行时健康能力，包括循环检测、runtime_health 只读工具、Live 告警、每轮摘要，以及 Runtime Health 面板与会话报告。
分类上属于 DSH 社区目录中的工作流类插件；维护策略为 best-effort，Issues 可能无人回复，欢迎 fork。与 DeepSeek / 幻方无官方从属；目录页见 SkillHub 插件页，源码与说明见 GitHub 仓库。
核心功能¶
循环检测（最近 100 次工具调用窗口）¶
插件在最近若干次工具调用上应用规则（默认保留 100 次，可通过配置 windowSize 调整），识别例如：
- 同一工具连续多次调用（参数略有不同时也能发现，避免「完全相同调用」类检测的盲区）；
- 同一归一化错误反复出现；
- 错误率过高。
具体阈值与 loopRisk 计算公式见仓库内 SPEC.md。
runtime_health 工具¶
模型在怀疑「卡住」时可主动调用该只读工具，返回统计与建议，包括：调用次数、错误率、平均延迟、最常用工具、状态（healthy / warning / critical）、0..1 的 loopRisk 估计、原因与 recommendation。
Live 告警与每轮摘要¶
- Live alerts： crossing 阈值时，在工具结果中追加约 40 token 的简短提示（可通过
liveAlerts关闭）。 - Per-turn summary：每轮结束后向模型发送约 20 token 量级的健康摘要（健康时更短；可通过
turnSummaryToModel控制）。
Web UI¶
- 输入框下方 Runtime Health 芯片，点开健康面板；
- 每条已完成轮次下方一行摘要；
- 会话级详细报告（token、工具使用、「待核实点」——例如写到意外路径的文件、未搜索却引用来源等）。
- 界面支持英语与法语。
可选配套插件 @beibeihk/dsh-agent-observability（持久化 per-session 录制、/observe 报告）；本插件不依赖它。
安装与启用¶
环境要求（来自 README / package.json）：
| 组件 | 版本 |
|---|---|
| Node.js | ^22.19.0 \|\| >=24.0.0 |
| DSH | >=0.2.0-rc.2 <0.3.0 |
README 在 Linux 上测试；插件为纯 JavaScript，无 native addon。官方验证示例使用 DSH 0.2.0-rc.2、Node 22.23。
安装到 web profile 并重启 profile：
dsh plugin --profile web add dsh-agent-flight-recorder
# or straight from GitHub:
dsh plugin --profile web add github:MathieuPortmann/dsh-agent-flight-recorder
安装后需重启对应 profile，插件才会加载。
配置¶
在 profile 的 cordis.patch.yml 中配置行 agent-flight-recorder；各键均为可选：
| Key | Default | Meaning |
|---|---|---|
windowSize |
100 | tool calls kept for the rules |
sameToolWarning / sameToolCritical |
4 / 6 | consecutive calls of one tool |
sameErrorWarning / sameErrorCritical |
2 / 3 | same normalized error repeated |
errorRateWarning / errorRateCritical |
0.2 / 0.3 | error rate (after errorRateMinCalls, default 10) |
shellTools |
[bash, pwsh] |
tools treated as shell commands |
turnSummaryToModel |
true | send the per-turn summary to the model |
liveAlerts |
true | add alerts to tool results |
状态全部来自 DSH durable session log，页面刷新后仍可恢复；卸载插件后相关 UI 与 derived 状态消失。
典型用法¶
- 按上文命令安装并重启 web profile，在对话界面确认出现 Runtime Health 入口。
- 正常让智能体多步调用工具；当连续同工具、重复错误或高错误率触发规则时，工具结果中会出现 Live 告警，面板与轮次摘要同步更新。
- 若希望在对话中让模型自检，可依赖其调用
runtime_health（插件注册的唯一新增工具），根据返回的status、loopRisk与 recommendation 调整策略。
开发侧可在仓库根目录运行：
npm test
npm test 可在无 DSH 安装的情况下跑大部分测试；依赖 DSH 的 load 测试在无 DSH 时会 skip。
权限、兼容性与使用注意¶
插件声明的能力边界（README Permissions and external services）：
| Capability | Used? | Detail |
|---|---|---|
| Files | no | 插件自身不读写磁盘；状态在 session log |
| Network | no | 不发任何请求 |
| Commands | no | 不启动进程 |
| Dynamic module loading | yes | 从当前 DSH 安装加载 zod、@deepseek-ai/dsh-tools、@deepseek-ai/schemastery；DSH 未提供则加载失败 |
插件以当前 dsh 进程权限运行；安装前建议自行查看源码与 MIT 许可证。它不修改或阻塞工具调用，仅在 liveAlerts 开启时向工具结果追加短告警。
适合谁：需要在 DSH Web 里实时发现「打转」、错误风暴，并同时给人（面板）和模型（摘要 / runtime_health）反馈的开发者。不适合期望插件代你改代码、杀进程或阻断调用的场景。
当前 package 版本为 0.1.0；DSH 生态理念是「一切皆插件」，社区目录为独立站点，并非官方应用商店。
