Documentation
¶
Overview ¶
Package events 实现结构化事件协议（自 hexclaw 下沉，v0.5.0 去 feature-flag）。
目标：把散落各处的 logger.Info/Warn 升级成可观测、可远程上报的结构化事件。 不替换现有 logger 调用 —— 而是并存：调用方在关键路径主动 Emit(ctx, evt)， 同时保留 logger 用于人类可读日志。
协议：每个 Event 有 Type / Severity / Source / Timestamp / Data；编码为 JSON， 通过 Sink 投递（本地 JSONL 文件 / 远程 HTTP collector / 测试用 InMemory / NoopSink）。
投递语义：包级 Emit 透传到注入 ctx 的 Emitter（WithEmitter 注入）；ctx 中无 Emitter 时退化为 no-op。是否真正落盘 / 上报由 Emitter 持有的 Sink 决定 —— 默认建议 NoopSink（静默），需要观测时切 FileSink / HTTPSink / MultiSink。
注：下沉前本包受 hexclaw feature flag `events.transport.v1`（alpha 默认 OFF） 门控；下沉到框架层后去除该 flag（框架层不依赖 hexclaw/featureflag），改由 Sink 选择控制是否静默 —— 默认 NoopSink 等价于原 flag OFF 的"默认静默"语义。
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Emitter ¶
type Emitter struct {
// contains filtered or unexported fields
}
Emitter 是事件发射器，持有 Sink + 默认 Source 标签。
func NewEmitter ¶
NewEmitter 构造一个 Emitter。sink 为 nil 时退化为 NoopSink。
type Event ¶
type Event struct {
Type string `json:"type"` // 事件类型，如 "tool.call.completed"、"llm.failover"
Severity Severity `json:"severity"` // 严重级别
Source string `json:"source"` // 事件来源模块，如 "engine.tool_executor"
Timestamp time.Time `json:"timestamp"` // 发出时刻（UTC）
TraceID string `json:"trace_id,omitempty"`
SessionID string `json:"session_id,omitempty"`
Data map[string]any `json:"data,omitempty"`
}
Event 是单条结构化事件。所有字段都有 JSON tag，可被 Sink 直接 marshal。
Data 是任意 key → value（值可序列化为 JSON）；用 map 而非 typed struct 是为了 兼容现有点位（trace_id、tool_name、duration_ms 等异质字段不必引入新类型）。
type FileSink ¶
type FileSink struct {
// contains filtered or unexported fields
}
FileSink 把事件以 JSON Lines 写入文件。每次 Submit 一行。
func NewFileSink ¶
NewFileSink 打开（或创建）path 对应的文件以 append 模式。失败返回 error。
type HTTPSink ¶
type HTTPSink struct {
// contains filtered or unexported fields
}
HTTPSink POST 单条事件 JSON 到远端 collector。
设计取舍：
- 同步 POST：实现简单；不阻塞由调用方决定是否在 goroutine 里调 Emit
- 不带本地 buffer / retry：远端不可达时 Submit 返回 error，Emitter 会记录 fallback 不会丢失现有 logger 输出。要做高可靠投递的留给 v0.4.1+ 的 BatchSink
func NewHTTPSink ¶
NewHTTPSink 构造一个 HTTPSink。timeout <= 0 时取 5s。
type MemorySink ¶
type MemorySink struct {
// contains filtered or unexported fields
}
MemorySink 把事件累计到内存里，用于测试 / 本地调试。线程安全。
type MultiSink ¶
type MultiSink struct {
// contains filtered or unexported fields
}
MultiSink 把事件 fan-out 到多个底层 Sink。任一 Sink Submit 失败不影响其它。 Close 会顺序调用底层每个 Sink.Close。
func NewMultiSink ¶
NewMultiSink 把多个 sink 组合成一个。nil sink 会被跳过。
Source Files