第 42 章：Agent 超时与 Watchdog
Watchdog 衡量的是已知阶段中缺失的进展，不只是墙上时间。
公开源码快照：实现细节取自 Kocoro 公开仓库
origin/main的4ec6772提交，复核日期为 2026-07-27。章节讲的是不变量；具体常量应以当前源码为准。
42.1 问题是什么
“Agent 超时”可能表示 Provider 没有返回 Chunk、工具确实很慢、本地正在压缩，或 Loop 丢失了阶段所有权。一个全局 Timer 要么误杀正常工作，要么对死请求等待太久。
42.2 设计原则
显式追踪 Phase，只在“无活动确实异常”的阶段启动 Timer。Soft Idle 发状态并给恢复逻辑机会；Hard Idle 在 Transport 到期前预留清理时间并取消；Stream Idle 独立监视 Chunk 间隔。Phase 所有权丢失时怎么办，要有意识地选。快照 Runtime 的做法是：此后整段运行静默停用 Watchdog，而不是拿不可信的计时数据去行动；同时向 stderr 打一条「tracker 已在本次运行中停用」的告警——在测试或严格模式下这条告警会升级为 panic。这是拿「可能挂住」换「绝不因坏数据取消正当工作」——如果你偏好相反的取舍，那就把它做成一个显式选择，而不是一次意外。
42.3 快照证据
| 源码快照 | 观察 |
|---|---|
4ec6772 | 快照默认值：Soft Idle 90 秒，Hard Idle 540 秒 |
4ec6772 | Stream Idle 间隔：90 秒 |
4ec6772 | Phase Tracker 区分等待 LLM、工具执行、压缩与终止工作 |
以上数值描述的是一个有日期的实现快照，不是普遍契约。
42.4 实现检查表
- 用 Fake Clock 测试时间边界。
- 超时遥测必须包含活动 Phase。
- 验证取消传播到 Provider、工具、持久层与调用方。
42.5 本章结论
Watchdog 衡量的是已知阶段中缺失的进展，不只是墙上时间。
这些章节应作为一个系统阅读：上下文、工具 Schema、持久化、操控、时间纪律、循环检测和并发会彼此影响。