English | 简体中文

DecayWatch 读取编码 Agent 的 JSONL 记录，按能力类别比较早期成功基线与后续窗口，并输出变化曲线、告警和可用于外部检查的退出码。

Python 3.12+ · MIT · GitHub · 网站

为什么需要它

整次运行成功与否容易掩盖某一种工具结果持续变差。按工具用途分类后，可以单独观察执行、读文件或测试的结果变化。DecayWatch 使用记录中的 is_error 信号，不通过模型猜测能力，也不把告警解释成模型能力衰退的因果证明。

架构

ClaudeCodeAdapter 按 tool_use_id 配对调用与结果，CapabilityMapper 将工具名和可选命令正则映射到类。baseline 取各类前 k 个已知结果，decay 计算滑窗与 Wilson 下界，report 输出 Rich 或 JSON。watch 当前一次读取文件并计算整条曲线，不持续 tail，也不会直接停止外部 Agent。

安装

需要 Python 3.12+。安装依赖可能联网，解析和示例运行不调用模型或外部服务。

git clone https://github.com/SuperMarioYL/decaywatch.git
cd decaywatch
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .

快速开始

python examples/presentation_demo.py

脚本创建两份各 40 个 Bash 结果的构造记录。健康输入全部成功，watch 退出 0；另一份在 20 次成功后开始失败，watch 退出 1，并在零起始 turn 20 首次发出 exec warning。脚本验证这两个预期退出码后自身退出 0。

用法

decaywatch baseline tests/fixtures/decayed.jsonl --json
decaywatch watch tests/fixtures/decayed.jsonl --json
decaywatch guard tests/fixtures/decayed.jsonl
decaywatch watch session.jsonl --k 30 --window 30 --margin 0.10
decaywatch baseline session.jsonl --output baseline.json

退出码契约（baseline / watch / guard 一致）：

exit code	含义
0	判定健康：没有能力类跌破基线
1	判定衰变：至少一类触发早停告警
2	无法判定：无类达到最小样本，或输入/配置错误

发现告警时 watch/guard 返回 1；样本不足或输入错误返回 2，两类结果不再混用同一退出码。guard 是 CI 守门命令：在 GitHub Actions（GITHUB_ACTIONS=true）下额外输出 ::error ::DecayWatch: ... 注记，告警内联显示在运行页。退出码可由你的 CI 或调度器消费，自动终止其他进程需要接入方实现。watch/guard 会从当前输入重新计算基线，不读取前一次 baseline 输出文件。

能力与集成

环节	当前支持
Transcript	Claude Code 风格 tool_use/tool_result JSONL
分类	工具名；Bash 可用 command_regex
基线/曲线	每类已知结果与 Wilson 下界
输出	Rich 表格、JSON、文件和退出码
外部调度	decaywatch guard CI 守门命令（0/1/2 退出码 + GitHub Actions 注记）

配置与边界

参数	默认
--k	每类前 20 个已知结果
--window	20
--min-sample	5
--margin	0.05
--config	自定义 YAML；未指定时可用内置分类
--output / --json	文件或 JSON stdout

详见 分类文件。命令正则规则优先于仅工具名规则，未匹配工具不贡献分类信号。告警要求完整滑窗、窗口 Wilson 下界低于基线下界减 margin，同时点成功率也下降。每类只保留首次告警；后续曲线可能继续恶化。

运行记录

v0.1.0 的真实 CLI 检测结果。JSON 是脚本从两个 watch 响应提取的告警与退出码；样例不证明真实长运行的告警准确率。

输入、命令和完整输出

保留的历史终端录屏 · 录制脚本。本轮示例以以上可重放记录为准。

路线图

• 调用/结果配对与能力分类。
• 早期基线、滑窗、JSON 告警及退出码。
• 外部早停集成：decaywatch guard CI 守门（0/1/2 退出码 + GitHub Actions 注记）。
• 持续监视运行中的会话（当前为事后读取完整 transcript）。
• 更多 transcript adapter 与跨运行汇总。

托管看板和付费服务不是当前实现。

开发与许可证

python -m pip install -e ".[dev]"
python -m pytest

适配器契约见 src/decaywatch/adapters/base.py。

MIT · Issues