streamguard

type StreamGuard struct {
	// contains filtered or unexported fields
}

type StreamGuardConfig struct {
	// IdleTimeout 空闲超时:流中间多久无事件视为挂起(默认 90s).
	// 精妙之处(CLEVER): SDK 的 request timeout 只管初始连接,
	// 不管流中间断了.没有看门狗,静默断开的连接会让进程永远挂起.
	IdleTimeout time.Duration

	// IdleWarningAt 空闲警告时间点(默认 IdleTimeout/2).
	IdleWarningAt time.Duration

	// StallThreshold 停顿阈值(默认 30s).
	StallThreshold time.Duration

	// OnIdleWarning 空闲警告回调(可选)
	OnIdleWarning func(elapsed time.Duration)

	// OnIdleTimeout 空闲超时回调(可选)
	OnIdleTimeout func()

	// OnStall 停顿检测回调(可选)
	OnStall func(gap time.Duration, stallCount int, totalStallTime time.Duration)

	// OnStreamEnd 流结束回调(可选)
	OnStreamEnd func(stats *StreamStats)
}

type StreamStats struct {
	// HasContent 是否收到过内容事件(TextDelta / ToolUse / ThinkingDelta)
	HasContent bool
	// HasUsage 是否收到 UsageEvent(流正常结束的标志)
	HasUsage bool
	// StopReason 最终的 stop_reason(来自 UsageEvent)
	StopReason string
	// ContentBlockCount 完成的内容块数量(Text + ToolUse)
	ContentBlockCount int
	// EventCount 总事件数量
	EventCount int
	// StallCount 停顿次数
	StallCount int
	// TotalStallTime 累计停顿时间
	TotalStallTime time.Duration
	// Duration 流的总持续时间
	Duration time.Duration
	// IdleAborted 是否因空闲超时被中止
	IdleAborted bool
}