Documentation
¶
Overview ¶
durable.go —— 持久化事件发布接缝(issue #160:宿主两份手写拷贝的下沉)。
为什么要有个 DurablePublisher ¶
宿主实证(bianque):「事件落库拿单调游标 → 广播;落库失败不广播」这条 次序不变量有两份同构手写拷贝——服务侧出口(internal/service/common/ systevent.go 的 InsertEvent→Broadcast)与引擎侧出口(internal/engine/ scheduler/publish/publisher.go 的 Pub)。两份拷贝承载的是同一条契约:
- SSE after 游标从此只有 bq_event ID 一个单调空间——广播帧必须携带 **存储铸造**的权威 ID(跨重启、跨副本都成立);
- 落库失败放弃广播——**宁可 SSE 少一帧,不伪造游标 ID**;
- 失败经 onDrop 回调留痕,不静默。
各宿主各写一遍必然各判一套(ctx/超时差异、失败口径、是否留痕全凭自觉), 正是本包「契约单源」定位要消除的漂移面——下沉之后,宿主只剩一份 Store 实现加一次装配。
纯内存章程的扩展边界(issue (e) 风险节,必须写死) ¶
本包章程是**纯内存事件面**;持久化发布以**可选 durable 面**扩展,边界三条:
- **包零 DB 依赖**:Store 接口由宿主实现,本包不 import 任何存储驱动、 不认任何 DB 方言、不出现任何 SQL——存储如何达成「单调唯一游标」 是宿主的事(DB 自增/序列天然成立);
- **可选**:不装配 DurablePublisher 的宿主,Bus/Hub 的纯内存语义 一字不变(本文件不给 Bus/Hub 加任何字段);
- **判定留包内、状态归存储**:次序不变量(先落库→取 ID→广播;失败 →不广播+留痕)收口在本文件,权威游标 ID 由存储铸造——与 #145 落的 commitgate「令牌由存储铸造」、ticket「TTL 判定留包内、票据状态归 Backend」同一条分工。
脱敏/字段裁剪等宿主差异不越界(issue (e) 风险节) ¶
两份宿主拷贝的 redaction 管线不同(publisher 多数值快照回填),下沉**只收 次序不变量**:事件内容(脱敏、裁剪、payload 补齐)在调用方构建 Event 时 完成,或经宿主自己的 Store 实现在 Insert 内部处理——本包不改写语义字段 (仅做 Level/OccurredAt 零值归一,与 Bus 既有缺省行为同口径,见 Publish)。
Package eventbus 事件单源双写(PHASE1_PLAN §2 决策 7):
生命周期: Stable(v0.33.0 定级)——只允许 additive 变更(新增导出符号 / 新增方法且给零值默认实现 / 新增错误值);改签名、改语义、改默认值、 删导出符号都算 breaking,判定规则与变更流程见 docs/api-compat.md, 逐包理由见 api-lifecycle.yaml。
引擎只向本总线 Publish 一次,订阅者分别落 bq_event(repo)与 SSE(handler)。
可选 durable 面(issue #160):包仍零存储依赖 ¶
本包章程是纯内存事件面;「持久化事件发布」以**可选接缝**扩展(durable.go 的 DurablePublisher):把「insert→取 ID→broadcast;失败→不广播+onDrop」 的次序不变量收进包内,但 Store 接口(Insert(ctx, ev) (uint64, error)) 由**宿主实现**——包内不 import 任何存储驱动、不认任何 DB 方言。不装配 DurablePublisher 的宿主,本包语义一字不变。接缝形态与 #145 落的 commitgate.Store / ticket.Backend 同风格:判定留包内、状态归存储、 进程内参考实现垫底。
可选 event-tail 面(issue #166):durable 写侧的对偶读侧 ¶
durable 面回答「本副本的事件怎么带 ID 落库」;tail 面(tail.go 的 Tailer) 回答「**他副本**的事件怎么进本进程的 Hub」——每副本一条轮询循环,读 id > 游标 的新事件回灌,初始化取 MaxID、读失败游标不动。同款边界: TailStore 接口由宿主实现、包零 DB 依赖、不装配则纯内存语义一字不变。 **scope:replica**:每副本各跑一条,套 leader 门会让非 leader 副本收不到 他副本事件(详见 tail.go 包头)。重复帧不归它去重,去重归订阅侧游标。
tail.go —— event-tail 跨副本补灌面(issue #166:SSE 单路桥接的 DB→Hub 读侧半边)。
为什么要有这个面 ¶
Hub 是进程内内存结构:本副本发布的事件经 pub 直投零延迟到达本副本订阅者, 但他副本发布的事件只在权威存储里,本地 Hub 永远收不到;pub 直投之前也还有 一个窗口缺口。任何「持久化事件 + 进程内 Hub 实时广播 + 游标回放」三件套的 宿主都缺这半边——写侧已由 DurablePublisher(#160)收编,**读侧此前各宿主 各写一份**(bianque background.go 的 event-tail 段),各判一套必然漂移。
本包把读侧四步收进包内:初始化游标 → 轮询 → 回灌 → 推进。判据与宿主无关: append-only id 游标、初始化取 MaxID(或经 CursorStore 续随上次停点)、读失败 游标不动(幂等补读)、回灌经 Hub.Publish。存储形状只有两个方法(TailStore), 包零 DB 依赖;游标持久化(CursorStore)与游标空洞告警(WithTailOnGap)是 可选面(issue #183)。
「读失败游标不动 ⇒ 不丢」的完整前提(issue #183,必须写死) ¶
「读失败游标不动 + append-only ⇒ 幂等补读,不丢不重」只在**「ID 序 == 提交可见序」**时成立。数据库自增/序列形态下有个经典缺口:A 事务拿到 id=10 尚未提交,B 事务拿到 id=11 先提交;读侧在 READ COMMITTED 下看到 11 并把游标推到 11——A 提交后 id=10 **永远读不到**,且是静默丢帧。这条 缺口不在调用方能修:它必须由 TailStore 实现按契约排除(见 TailStore 的 可见序硬要求),Tailer 侧的 WithTailOnGap 只是最后的哨兵,不是兜底。
scope:replica——每副本一条,**不套 leader 门**(AGENTS.md 门控教训的实弹对象) ¶
Hub 是进程内内存结构,每个副本的 SSE 连接只看得见**自己进程**的 Hub。若给 本循环套上 leader 门,非 leader 副本的事件尾随会整段停摆——那些副本的 SSE 连接从此收不到任何他副本事件,且**不报错、不告警**,只表现为「某些副本的 页面不动了」。leader 门适用于「全局只该做一次」的作业(清扫、外发游标); 本循环是**每副本自己的补灌桥**,跑的次数 = 副本数才是对的。
与既有两面的划界(三层各一层,互不替代) ¶
- 写侧 = DurablePublisher(#160):落库拿单调游标→广播、落库失败不广播。 本面是它的**对偶读侧**,同包互补、不重复;
- 连接侧 = oekit/pkg 的 SSE 游标回放应答器(#483):单连接 after-cursor 窗口应答,是 HTTP 层;本面是**副本级 存储→Hub 补灌桥**,在 Hub 层, 不碰 HTTP;
- 权威顺序与可靠面始终是存储游标,本面只是实时面的补达。
重复帧不归本面去重(与 #160「ID 由谁赋值」同一分工纪律) ¶
本副本实时帧由 pub 直投(零延迟),本面稍后又会从存储读回同一条事件—— 同一帧到达订阅者两次是**设计内**的。Tailer 不负责去重:去重归订阅侧游标 (`ev.ID <= after` 幂等吸收,SSE 连接既有语义)。本面唯一要做的是把 **存储铸造的权威 ID 原样带上**,让订阅侧的幂等判定有据可依。
Relay 交互(如实声明) ¶
回灌经 Publish(与宿主原实现同款):装配了 Relay 的宿主,本面读回的帧会 经 Relay 再外发一次——Relay 契约原文已写明「不得经 Relay 再次外发同一条 事件(回流即环,外发的去重是实现的责任)」,该去重归 Relay 实现,本面不 替它兜底。只用进程内 Hub 的宿主(缺省形态)无此问题。
Index ¶
Constants ¶
const ( EventSessionCreated = "session_created" EventIntentRouted = "intent_routed" EventDispatchDenied = "dispatch_denied" EventStepStarted = "step_started" EventStepFinished = "step_finished" EventReportValidated = "report_validated" EventVerdictJudged = "verdict_judged" // 结论合议裁决留痕(spec 2026-09-15-verdict-judge-design §8) EventReportViolation = "report_violation" EventApprovalRequested = "approval_requested" EventApprovalDecided = "approval_decided" EventApprovalExpired = "approval_expired" EventExecutionDryrun = "execution_dryrun" EventExecutionDegraded = "execution_degraded" // 执行面缺失(MCP 池未装配),已批准方案降级 DryRun 的显式留痕 EventRemediationExecuted = "remediation_executed" // 受审变更执行回执(批次九十四):批准→执行完成后的汇总留痕(executor/change_ref/host/步骤数) EventSessionFinished = "session_finished" // EventDecisionAnswered 判定面结果留痕(来源/置信语义/判定值/是否采纳)。 // 载荷键面见 protocol.DecisionEventPayload(扁平键,跨宿主聚合的共同底座)。 EventDecisionAnswered = "decision_answered" // EventDecisionEscalated 判定面升级/回落留痕(判定面 → 生成面 / 人工的移交原因)。 EventDecisionEscalated = "decision_escalated" // 轮次生命周期事件对(批次二百八十四,对标 DeepSeek harness turn 括号语义+「锁最后 // 释放」纪律):turn_started 在会话认领成功后立即落库,turn_ended 在收尾漏斗出口 // 落库——「有 start 无 end」的残留=中断轮的可检测孤儿态(发版重启/进程死亡不再依赖 // 事件静默启发式定性,时间线与诊断大脑可直接读出轮边界与中断点)。停机路径不落 // turn_ended(轮括号留给恢复循环/启动对账以 closed_by=recovery|boot-reconcile 关闭, // 谎报「正常收尾」比留开放括号更伤审计)。 EventTurnStarted = "turn_started" EventTurnEnded = "turn_ended" // EventReportSuperseded 终报覆写版本尾迹(批次一百三十七):成功收尾覆写 final_report // 前旧报告非空且不同时发布——bq_event 持久化留痕,控制台回放可拼历史版本链(载荷只 // 带头尾摘录防大字段;旧报告全文仍以折叠进压缩面的路径为准)。 EventReportSuperseded = "report_superseded" // 过程可观测事件(此前是调度器里的字符串字面量,收编进词表同源管理): // reasoning/text 为 agent 过程思考与中间答复;tool_call/tool_result 经 call_id 配对; // llm_usage 为单次 LLM 调用真实用量(DeepSeek harness 式 token 面板的数据源)。 // reasoning_delta/text_delta 为流式增量分片(agentkit v0.10.32 默认开流):生成过程 // 中按 ~400ms/200 字符节流发布(seq 单调、text=分片非快照),同轮权威 reasoning/ // text 快照到达即吸收——真流式渲染的数据源,回放/对账以权威快照为准。 EventReasoning = "reasoning" EventAgentText = "text" EventToolCall = "tool_call" EventToolResult = "tool_result" EventLLMUsage = "llm_usage" EventReasoningDelta = "reasoning_delta" EventTextDelta = "text_delta" // 报告增量流(SSE 真打字机):终态成功收尾时把定稿报告按 markdown 行边界分片、 // 节奏化发布(seq/total/text)。经 s.pub 落库保 bq_event 游标不变量;回放重放 // 无害(同 seq 同文,前端按 seq 归并、终态权威报告覆盖)。 EventReportDelta = "report_delta" // 用户输入事件(多轮对话的用户侧留痕):创建/注入时由 SessionSvc 经调度器出口发布, // 时间线可见,同时是下一轮对话历史(ListEventsByType)的数据源。 EventUserInput = "user_input" // 上下文构成事件(批次八十一,对标 Octop ContextWindowRing):每环节装配完成后 // 由 runner OnContext 回调发布,payload.segs=段名→字符数(soul/prompt/defense/ // skills/skills_list/memory/env_notes/todo/query/tools)——前端构成条的数据源。 // 批次二百八十七扩压力读数四字段(pressure_tokens/pressure_baseline/window_tokens/ // window_pct,dsh token-meter 对标:usage 锚定与启发式取大)。 EventContextComposition = "context_composition" // 上下文压力高水位告警(批次二百八十七,pressureHighWater=0.85):请求压力达窗口 // 高水位时 warn 级显形(压力是事实不是错误,不阻断);同时是压缩面预折叠闸的 // 触发信号(compact.go pressureHot)。 EventContextPressure = "context_pressure" // 协议级重试留痕(批次二百九十五,dsh assistant/attempt 等价物):首跑失败决定 // 回喂重试时 warn 级显形(payload.reason=失败原因摘要)——时间线可解释「两段近似 // 重复环节」(此前无标记,排障误读为模型重复劳动)。agentkit 内部 LLM 调用级重试 // 不在本面(实现侧在 agentkit,挂账)。 EventAttemptRetried = "attempt_retried" // EventPtcRun 程序化工具编排明细(批三百零五):一次 run_program 执行的账目面—— // bindings 调用清单/各预算余量/中断原因(程序把大输出「洗」成小结果时账目不缺)。 EventPtcRun = "ptc_run" // 任务清单事件(执行进程浮层,对标 ZCode 进程面板):todo_plan 全量替换成功后由 // runner OnTodos 回调发布,payload.todos=完整清单([{content,status}])、done/total // =完成数/总数——控制台会话页右上角进度浮层数据源;经 s.pub 落库,回放自水合。 EventTodoUpdated = "todo_updated" // 记忆召回事件(批次一百三十五,「诊断大脑」观测台一期缺口补齐):分层记忆召回 // 装配非空时由 runner OnMemoryRecall 回调发布,payload.chars=召回块字符数、 // preview=首 240 字——此前召回只有 DB Hits 滞后计数无事件,脑图海马区活跃度数据源。 EventMemoryRecalled = "memory_recalled" // 排队输入生命周期事件(真队列化 P1-1/P1-2/P2-3):abandoned=失败/预算禁续等收尾 // 未消费的明示留痕;removed=队列管理面单条移除(气泡「已移除」判定依据)。 EventQueueAbandoned = "queue_abandoned" EventQueueRemoved = "queue_removed" // 选模悬空回落事件(批次二百五十二,spec dialog-zcode-alignment §3):会话设了 // model_profile 但档案链已不在已装配快照(档案被删/停用/密钥摘除/mock 形态)—— // 本轮按平台角色路由继续(回落是设计行为,悬空不得炸会话),事件显形「你选的模型 // 已不可用」防静默换脑。payload=profile/returned_model。每轮一条(轮级判据)。 EventModelFallback = "model_fallback" // 目标驻留事件(P3-1/P3-2):set=目标绑定;verified=judge 完成验证器裁决留痕 // (passed/next_action/iteration 随 payload);completed=目标达成收敛。 EventGoalSet = "goal_set" EventGoalVerified = "goal_verified" EventGoalCompleted = "goal_completed" // 跨轮历史压缩事件(批次三十六,对标 ZCode CompactBoundary):【历史压缩】环节把 // 旧摘要+近轮结论折叠为结构化摘要后发布——before/after_tokens 为估算口径 // (EstimateTokens),summary_chars/pending_count 供时间线卡与排障。 EventHistoryCompacted = "history_compacted" // 跨副本取消控制事件(P2-1):Cancel API 在本副本信号未命中时发布,各副本监视器 // 轮询 bq_event 命中本副本取消句柄即协作中止(append-only 幂等:非执行副本 no-op)。 EventSessionCancelRequested = "session_cancel_requested" // 澄清反问观测事件(P3-5):反问轮此前仅 intent_routed 的 question 字段可辨, // 无独立可观测事件——补一条显式留痕(keyword/question 随 payload)。 EventClarifyAsked = "clarify_asked" // Spawn 原语生命周期事件(批次二百四十一 R4 笼子四补位):dispatch_agent 单派与 // dispatch_explore 各路勘探子任务的起止结构化留痕——spawn_id 配对两事件, // caller/target/mode/status/latency_ms 随 payload。此前 spawn 子任务只能靠父环节 // tool_call/tool_result 的文本痕迹观察,无结构化父子归因;本事件是前端「进行中 // spawn」进行式卡与审计面的数据源(StepID=父环节,落库/广播经调度器 pub 单源)。 EventSpawnStarted = "spawn_started" EventSpawnFinished = "spawn_finished" // 会话产物登记(批次八十六,spec COMPETENCE_UPLIFT_SPEC §5):版本化交付物 // 落库即发布(artifact_id/kind/title/seq/mime/size 随 payload)——时间线产物卡 // 与 SSE 实时刷新同一事件源。 EventArtifactRegistered = "artifact_registered" // 平台化插拔审计事件(spec §4 操作审计):无会话归属的系统级事件——启停/重载 // 的操作者/时间/slug 落台账,与决策树留痕同一套台账哲学。 EventExpertToggled = "expert_toggled" EventExpertsReloaded = "experts_reloaded" EventMcpToggled = "mcp_toggled" // MCP server 运行时启停(页面管理) EventMcpGovernance = "mcp_governance" // MCP 治理变更(批次一百八十七:包声明激活位/凭证绑定覆盖,热生效) EventMCPPoolError = "mcp_pool_error" // MCP 池建连/列举失败留痕(此前完全静默,agent 拿空工具表无从排查) // 凭证平面审计事件(spec 2026-09-11 §9.1):CRUD/启停/测试为操作留痕; // staged 为 MCP spawn 装载留痕(只记名字与键名,不记值)。 EventSkillUpdated = "skill_updated" // 技能编辑留痕(mode/正文写回;批次十补审计缺口) EventCredentialUsed = "credential_used" // 会话级凭证使用归因(host 命中凭证实例名时随会话发布) EventCredentialCreated = "credential_created" EventCredentialUpdated = "credential_updated" EventCredentialDeleted = "credential_deleted" EventCredentialToggled = "credential_toggled" EventCredentialTested = "credential_tested" EventCredentialOAuth = "credential_oauth" // OAuth2 授权流留痕(批次一百九十七 R8:authorized|failed|refreshed|refresh_failed) EventCredentialsStaged = "credentials_staged" // IM 通道审计事件(批次九十三 DB 化):通道 CRUD/启停/测试留痕(bq_event, // 经 /api/v1/audit?type=im_channel_ 前缀过滤可见;credentials 同款纪律)。 EventImChannelCreated = "im_channel_created" EventImChannelUpdated = "im_channel_updated" EventImChannelDeleted = "im_channel_deleted" EventImChannelToggled = "im_channel_toggled" EventImChannelTested = "im_channel_tested" // 自动化审计事件(spec 2026-09-11-automation):规则 CRUD/启停/触发留痕(bq_event, // 经 /api/v1/audit?type=automation_ 前缀过滤可见)。 EventAutomationCreated = "automation_created" EventAutomationUpdated = "automation_updated" EventAutomationDeleted = "automation_deleted" EventAutomationToggled = "automation_toggled" EventAutomationTriggered = "automation_triggered" EventAutomationFired = "automation_fired" // 排期拍到点实跑(与 TriggerNow 的 manual 区分) EventAutomationSuggested = "automation_suggested" // FR-11:巡检成功后建议定时化(进会话时间线,前端渲染建议卡) // 链模板审计事件(spec 2026-09-18-chain-v2-workflow §10):模板 CRUD/启停/触发留痕 //(bq_event,经 /api/v1/audit?type=chain_ 前缀过滤可见);节点级事件在 scheduler 侧。 EventChainCreated = "chain_created" EventChainUpdated = "chain_updated" EventChainDeleted = "chain_deleted" EventChainToggled = "chain_toggled" EventChainTriggered = "chain_triggered" EventChainCondition = "chain_condition" // 链内 condition 节点判定留痕(field/op/value/命中分支) EventChainGateRequested = "chain_gate_requested" // 链内 approval 节点提请人工闸门 EventChainNotifySkipped = "notify_skipped" // notify 节点降级(未配置/失败,观测有损不阻塞) EventChainExecuteBlocked = "chain_execute_blocked" // execute 节点被拦(平台总闸关/黑名单/主机缺失;降级不阻塞链) EventChainParallel = "chain_parallel" // 并行子图起跑标记(branches 名单随 payload) EventChainNode = "chain_node" // 链节点执行留痕(path/节点类型/状态;path 与控制台画布节点 id 同构,运行时拓扑据此高亮) // 操作审计门事件(spec 2026-09-14-policy-modes-audit-gate-design):方案提审裁决与 // 工具调用面逐次审计留痕——verdict/decider/rule_id 随 payload,审计可答「谁裁的、依据什么」。 EventOperationAudited = "operation_audited" // 告警驱动面事件(spec 2026-09-14-aiops-uplift-design §2):外部告警接入即留痕 // (fingerprint/severity/deduped/merged 随 payload),会话时间线渲染「来源告警」卡。 EventAlertReceived = "alert_received" // 告警路由规则面事件(批次一百一十一 DB 化管理面):CRUD/启停审计留痕。 EventAlertRouteCreated = "alert_route_created" EventAlertRouteUpdated = "alert_route_updated" EventAlertRouteToggled = "alert_route_toggled" EventAlertRouteDeleted = "alert_route_deleted" // 工具身份守卫事件(spec 2026-09-15-tool-identity-otel-guard-design P4): // violation 为热路径守卫实锤(requested/resolved/checksum/violation 随 payload); // pairing_leak 为被动 watcher 配对不变量告警(reason=declared_not_executed|duplicate_result)。 EventToolIdentityViolation = "tool_identity_violation" EventToolPairingLeak = "tool_pairing_leak" // 轮级括号不变量告警(watchdog INV3,issue #171):turn_started/turn_ended // 配对与归因校验的被动告警出口(warn 级)。与 tool_pairing_leak 同层—— // 一个是工具调用级配对,一个是轮级括号(外层),只告警不裁决。 // payload: reason=turn_end_unattributed|turn_end_unknown_status| // turn_end_unopened|turn_open_leak,附 status/closed_by/event 诊断字段。 EventTurnBracketViolation = "turn_bracket_violation" // 身份违规 IM 推送已处理标记(identity-watch 通知扫描兜底的幂等锚点;payload {"ref":<源事件ID>})。 EventIdentityViolationNotified = "identity_violation_notified" // 副作用轨迹事件(v0.33.0,issue #99):sideeffect 闸的生命周期留痕—— // trajectory 投影器据此产出 sideeffect 行,排障时「这个副作用到底施加了吗」 // (授予 / 施加 / 对账 / 裁决)在轨迹里可答。词表收在 eventbus 单源(与 // tool_call/tool_result 同一条纪律:另立一套事件词表必然漂)。 // // 发布方是宿主(内核只给词表与投影,不做投递);载荷键面见 trajectory 包 // 的映射说明:key/resource/fence/retry_safety/applied。**reason 不进轨迹行** // (自由文本、基数无界,与 payload 同一条禁区纪律)。 // // - granted:闸授予执行权(Acquire → OutcomeApplied)——开启一个 sideeffect 行; // - completed:施加并记账成功(Complete 被接受)——收口该行; // - abandoned:显式放弃本次尝试(确定未生效 / 下游按幂等键去重)——收口该行; // - uncertain:结果未知(施加失败 / 记账失败 / 租约过期未裁决)——收口该行, // 并开启该 Key 的「对账」段(等 resolved 收口); // - resolved:对账裁决落定(payload.applied=true|false)——收口对账段; // - replayed:动作早已完成、本次取回既有结果(Acquire → OutcomeReplayed)—— // 点事件(无括号段); // - contended:资源正被他人持有 / 有未裁决尝试(Acquire → OutcomeContended)—— // 点事件;双 Worker 争用的证据面(issue #98 的并发形态在此可见)。 EventSideEffectGranted = "sideeffect_granted" EventSideEffectCompleted = "sideeffect_completed" EventSideEffectAbandoned = "sideeffect_abandoned" EventSideEffectUncertain = "sideeffect_uncertain" EventSideEffectResolved = "sideeffect_resolved" EventSideEffectReplayed = "sideeffect_replayed" EventSideEffectContended = "sideeffect_contended" // EventCheckpointCommitted 快照提交留痕(v0.33.0,issue #99):编排进度快照 // 成功落库一次即发布——排障时「恢复点停在哪个序号」在轨迹里可答。点事件 // (无括号段)。载荷键面:run_id / seq / status / done(已完成步骤数)。 EventCheckpointCommitted = "checkpoint_committed" )
事件类型词表(bq_event.type 同源)。
const ( // DefaultTailInterval 缺省尾随间隔。他副本事件的补达上界 ≈ 本间隔。 DefaultTailInterval = time.Second // DefaultTailLimit 缺省单拍批量上限(超出部分下一拍续读,游标单调推进)。 DefaultTailLimit = 1000 )
尾随缺省参数(与宿主原实现同参:每秒一拍、单拍 1000 条)。
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Bus ¶
type Bus struct {
// contains filtered or unexported fields
}
Bus 进程内事件总线(单实例;cluster 多副本 Phase③ 换 NATS 扇出)。
func (*Bus) Broadcast ¶
Broadcast 广播一个已构建事件(发布路径先落库拿 bq_event 自增 ID,再由此广播; 该次序的生产收口见 DurablePublisher,issue #160——本方法只做广播面,不落库)。 SSE after 游标从此只有 bq_event ID 一个单调空间——跨重启、跨副本(PG 序列全局唯一)都成立, 取代旧的 NewWithSeq 启动播种方案(bus 内部序号与回放 ID 是两个空间,多副本下必然错位)。
func (*Bus) Publish ¶
func (b *Bus) Publish(sessionID, caseID string, stepID *uint64, typ, level string, payload map[string]any) Event
Publish 赋 ID/时间戳后广播(未落库的临时序号;生产路径改用 DurablePublisher)。
func (*Bus) Subscribe ¶
Subscribe 订阅事件流;cancel 释放订阅(SSE 断开/bq_event writer 停止时调用)。
契约:退订(cancel 或 ctx 取消)后 channel 会被**关闭** ¶
消费方必须写 `v, ok := <-ch` 并处理 ok==false。这不是可选风格:关闭的 channel 在 select 里**恒可就绪**并反复给出零值,于是 `case v := <-ch:` 不查 ok 的循环 会空转——CPU 打满、事件是假的、而且不报错。
本包曾按上游旧契约(runtime<v0.10.0 的「channel 永不关闭」,oagentkit/runtime#20) 承诺「不关」,并以此为由禁止消费方 range。上游 v0.10.0 推翻了那条理由 (runtime#32):Publish 与 unsubscribe 同锁互斥,不存在 send-on-closed 窗口, 故退订即 close。本仓随之上车——关闭换来的是 `for range ch` 能正常退出、 且不会把已缓冲事件挂在无人消费的 channel 上(旧形态每退订一次就漏一条 channel)。
注意 Hub 的 Subscribe **不**关 channel(见 hub.go 的说明):两个投递面在这里 有意分叉,判据由 hub_test.go 与 eventbus_test.go 各钉一侧。
type CursorStore ¶ added in v0.39.0
type CursorStore interface {
// LoadCursor 读上次保存的游标。found=false 表示从未存过(首次部署)
// ——此时 Tailer 回退既有初始化(显式起点 / MaxID)。
//
// error ⇒ Tailer 停摆重试(每拍再试),**绝不静默回退 MaxID**:回退
// 就会把停机窗口内的事件整个跳过——宁可停摆不可跳读。
LoadCursor(ctx context.Context) (cursor uint64, found bool, err error)
// SaveCursor 游标推进后保存(每拍至多一次,只在游标前进时调用)。
//
// 失败只 warn 不停摆:游标落后只会导致重启后**重读**(订阅侧游标幂等
// 吸收,不丢不重——重读方向安全),停摆反而把实时补灌桥拆了。
SaveCursor(ctx context.Context, cursor uint64) error
}
CursorStore 游标持久化接缝(宿主实现,可选;issue #183)。
Tailer 的游标是 Run 的局部状态,停机即失。缺省(不装配本接缝)重启后走 MaxID 初始化——**停机窗口内他副本发布的事件不会补灌**(从当前尾部起随, 是「补灌不是回放」的既有语义)。宿主要「重启后从上次停点续随」,就把 游标存进自己的存储并经 WithTailCursorStore 装配本接缝。
type DurableOption ¶ added in v0.36.0
type DurableOption func(*DurablePublisher)
DurableOption 发布器可选项(见 WithOnDrop)。
func WithOnDrop ¶ added in v0.36.0
func WithOnDrop(fn func(ev Event, cause error)) DurableOption
WithOnDrop 注入落库失败留痕钩子(缺省 nil ⇒ 静默丢弃,与宿主拷贝的 onDrop 可选形一致)。
同步调用、在发布锁内:不得阻塞、不得回调 Publish/Insert(Store 契约的 重入红线同款)。本包不重试——重试会把「失败不广播」变成「失败晚广播」, 次序不变量就破了;重试/死信/告警是留痕钩子宿主侧的事。
type DurablePublisher ¶ added in v0.36.0
type DurablePublisher struct {
// contains filtered or unexported fields
}
DurablePublisher 持久化事件发布的收口点:把「insert→取 ID→broadcast; insert 失败→不广播+onDrop」的次序不变量收进包内(issue #160)。
次序不变量(本包唯一收口的语义) ¶
- 先落库:Store.Insert 成功 ⇒ 拿到权威游标 ID;
- 再广播:广播帧携带存储铸造的 ID(不重编号、不预分配),且与落库行 **同一内容**——Level/OccurredAt 的零值归一发生在 Insert 之前, 订阅者看到的帧就是持久化的那行;
- 落库失败 ⇒ 放弃广播 + onDrop 留痕——宁可 SSE 少一帧,不伪造游标 ID。
并发序:广播序 == 游标序(比宿主拷贝强的一档,代价写明) ¶
发布全程持一把锁:并发 Publish 的广播顺序与游标顺序严格一致——每个订阅者 看到的 ID 严格递增,SSE after 游标的「唯一单调空间」在**实时面**同样成立 (宿主两份拷贝只能保证各自先 insert 后 broadcast,并发下广播序与游标序 可能交错:A insert=1 → B insert=2 → B 广播 → A 广播,订阅者先见 2 后见 1)。 代价是 Insert 被串行化:事件是人的可读留痕而非高频指标,串行不是瓶颈; 但 Insert 慢(DB 抖动)时全体发布排队等它——这是次序保证的固有代价, 不藏。广播本身非阻塞(满缓冲丢帧计数),持锁广播不会卡在慢订阅者上。
零值不可用,用 NewDurablePublisher 构造。
func NewDurablePublisher ¶ added in v0.36.0
func NewDurablePublisher(b *Bus, store Store, opts ...DurableOption) *DurablePublisher
NewDurablePublisher 构造:bus 是广播面,store 是持久化接缝,均必填。
store 为 nil ⇒ panic:没有存储的「持久化发布」只能广播一个非权威 ID—— 伪造游标正是本结构要防的事,fail fast 在装配点,不留到运行时。bus 为 nil 同理(没有广播面的落库是单向写库,不经本包——直接调宿主 Store 即可)。
func (*DurablePublisher) Publish ¶ added in v0.36.0
Publish 落库并广播一条事件:成功 ⇒ 返回广播帧(ID=权威游标,含零值归一), 供调用方直接用作 SSE 游标;失败 ⇒ 零值事件 + insert 错误,不广播 (onDrop 已留痕)。
字段口径(归一发生在 Insert 之前,落库行与广播帧同一内容):
- ev.ID 输入侧一律**清零忽略**——游标由存储铸造(Store 契约), 调用方拷贝里的陈旧 ID 不得流入广播帧;
- Level 空 ⇒ info,OccurredAt 零值 ⇒ 当前时刻——与 Bus.Publish 的 既有缺省行为同口径,本包不新增字段语义。
type Event ¶
type Event struct {
ID uint64 `json:"id"`
SessionID string `json:"session_id"`
CaseID string `json:"case_id,omitempty"`
StepID *uint64 `json:"step_id,omitempty"`
Type string `json:"type"`
Level string `json:"level"` // info|warn|error
Payload map[string]any `json:"payload,omitempty"`
OccurredAt time.Time `json:"occurred_at"`
}
Event 引擎事件(比 model.Event 多运行时字段;落库时转换)。
type Hub ¶
type Hub struct {
// contains filtered or unexported fields
}
Hub 按会话键控的事件分发器(SSE 单路桥接,2026-10-03 会话平面审计): 订阅时绑定 session_id,发布只投递该会话的订阅者——SSE 连接不再为无关会话的事件 做逐条过滤(旧形态每连接收全实例事件再自行丢弃,成本 = 连接数 × 全局事件数), 分发成本随活跃会话数而非连接总数增长。
投递语义的**缓冲面**与 progress.Bus 一致:订阅 channel 带缓冲,满即丢帧计数 (不阻塞发布方——编排热路径不可被慢连接拖住);丢帧由 SSE 的 DB 回放游标 + 全局 tail 兜底补达,不丢语义。零订阅者的发布成本 = 一次 map 读 + 空 slice 遍历。
与 eventbus.Bus 的**有意分叉**:退订时不关闭 channel ¶
上游 runtime v0.10.0 把 progress.Bus 改成了「退订即 close」(runtime#32), eventbus.Bus 随之关闭;Hub **不**跟:
- Hub 的消费方是宿主的 SSE 循环,内核看不到那些循环有没有写 `v, ok := <-ch`;
- 关闭一个「按旧契约写」的 channel,后果是循环**空转**——CPU 打满、拿到的 全是零值事件、且一声不响。这是个失败形态**变绿**的改动,不该在看不见 消费方的那一层单方面做。
所以关闭的时机留给能看见宿主代码的那一层决定;本包把「不关」写成声明而不是 遗漏,由 TestHubSubscribeDoesNotCloseChannel 钉住。
消费方约定:用 `select` + 自己的 done 信号退出(**禁用 `for range ch`**, 它在本包永不返回)。
跨实例面在 Relay 接缝之后(issue #145 多副本部署) ¶
缺省无 Relay = 进程内限定(本页描述的语义一字不变)。多副本宿主装配 Relay 把事件带出本进程(outbox 表 / 消息总线 / …),别处收到的事件经 Inject 注回本进程订阅者——分发逻辑仍只有这一份,跨实例投递归宿主实现。
func (*Hub) Inject ¶ added in v0.35.0
Inject 把从别处收到的事件投给本进程订阅者(issue #145 跨实例回注)。
只做本地分发、**不回流 Relay**——回流即环(A 外发 → B 注入 → B 再外发 → …)。与 Publish 同一分发语义(含空 SessionID 忽略、满缓冲丢帧计数)。
func (*Hub) Publish ¶
Publish 向会话订阅者投递(非阻塞;满缓冲丢帧计数),随后交给 Relay 外发。 SessionID 为空的系统级事件(expert_toggled 等)无会话受众,直接忽略—— 系统事件经 /audit 面,不走 SSE(Relay 同样不收:外发条件与本地受众一致)。
顺序:**本地先、Relay 后,且 Relay 在解锁之后调用**——本地分发是主契约 (Relay 故障不牵连本地),解锁后调用让 Relay 可以安全回调 Inject。 代价是并发 Publish 的 Relay 外发顺序不作保证(权威顺序是宿主落库游标)。
type MemoryStore ¶ added in v0.36.0
type MemoryStore struct {
// contains filtered or unexported fields
}
MemoryStore 进程内参考实现(并发安全):自增游标 + 内存留痕。
无持久化——重启即丢、跨进程不成立,**不得上生产**(生产宿主接 DB; 进程内也拿不出跨副本单调空间)。职责是把次序不变量垫在契约之下让契约 可测——与 ticket.NewMemoryBackend、commitgate.NewMemoryStore 同口径 (内核证契约,宿主接生产)。
func NewMemoryStore ¶ added in v0.36.0
func NewMemoryStore() *MemoryStore
NewMemoryStore 构造进程内参考实现(游标从 1 起)。
type Relay ¶ added in v0.35.0
type Relay interface {
// Publish 一条事件离开本进程(只在本地分发之后调用)。
Publish(ev Event)
}
Relay 跨实例事件中继(宿主实现;issue #145)。
契约三条:
- **不得阻塞**发布热路径(编排热路径不可被跨实例投递拖住;需要缓冲/ 重试的形态在实现内部做);
- **失败语义自担**:Relay 没有返回值,投递失败由实现自己记账 (丢帧计数/告警),本包不重试不回滚——权威事件顺序与可靠面是宿主 落库游标(bq_event),Relay 只是尽力而为的实时面;
- 实现**可以回调** Hub.Inject(收到远端事件注回本地)——Publish 在 解锁后才调 Relay,回调不会死锁;但不得经 Relay 再次外发同一条事件 (回流即环,外发的去重是实现的责任)。
type Store ¶ added in v0.36.0
type Store interface {
// Insert 持久化一条事件并返回权威游标 ID(语义同 SQL 的
// INSERT ... RETURNING id)。ctx 的超时/取消由实现自判(超时 ⇒ error,
// 走 drop 路径)。
Insert(ctx context.Context, ev Event) (uint64, error)
}
Store 持久化存储接缝(宿主实现;issue #160,形态与 #145 的 commitgate.Store / ticket.Backend 同风格)。
契约三条:
- **游标由存储铸造**:Insert 返回的 uint64 是权威游标 ID(bq_event 式 自增/序列),单调唯一由实现保证;传入事件的 ev.ID 是输入侧遗留值, 一律忽略(DurablePublisher 在入口已清零,防御陈旧游标流入)。
- **基础设施故障 ⇒ error**:本包收到 error 即放弃广播——「不广播 + onDrop」是契约的一部分,不是本包的实现选择;实现不得在 error 时 仍然写入了行(部分写入由实现的事务性负责)。
- **不得重入**:Insert 不得回调 DurablePublisher.Publish——发布全程 持锁(见 DurablePublisher 的并发序说明),重入即死锁;与 Hub.Relay 的「不得回流」同款红线。
type TailStore ¶ added in v0.38.0
type TailStore interface {
// MaxID 当前权威游标空间的最大 ID(空表 = 0)。只在初始化时调用一次。
MaxID(ctx context.Context) (uint64, error)
// ListAfter 列出 id > cursor 的事件(limit 为单拍上限,升序)。
//
// 返回段必须满足上面的「无空洞推进」硬要求:从 cursor+1 起连续可见,
// 有「已铸造未可见」的 ID 卡在中间时,只返回它之前的段(可以是空段)。
ListAfter(ctx context.Context, cursor uint64, limit int) ([]Event, error)
}
TailStore 尾随读侧存储接缝(宿主实现;issue #166,形态与 durable.go 的 Store 同风格:判定留包内、状态归存储、包零 DB 依赖)。
契约四条:
- **游标空间 append-only 且单调**:ListAfter 只回 id > cursor 的行, 且**必须按 ID 升序**——游标推进建立在这个序上(乱序返回会让游标 回退或跳号,两者都不在本包的观测面内);
- **「ID 序 == 提交可见序」(无空洞推进,硬要求;issue #183)**: ListAfter 返回的段从 cursor 之后第一条起必须**连续可见**——只要存在 「已铸造但本拍不可见」的 ID(典型:DB 序列下小 ID 的事务尚未提交), 就**不得返回比它大的行**。违反这条 ⇒ 迟到提交的小 ID 被永久跳过 (游标已越过它),且是静默丢帧——这正是「读失败游标不动 ⇒ 不丢」 的隐含前提,此前契约没写。实现口径两选一:① 读侧只推进到**无空洞的 最大 ID**(观测到空洞即截断返回段,下一拍重读);② Outbox 形态—— 事件行与业务状态同事务提交,铸造序天然等于可见序。Tailer 的 WithTailOnGap 是对违约的**哨兵**(响即实现已违约),不是兜底机制;
- **行→Event 的转换归实现**:ID 取存储铸造的权威游标,Payload 已是 解析好的载荷(与 DurablePublisher 的 Insert 入参转换对称——那边是 发布前构造,这边是读出后还原)。本包**不改写**回读到的字段(权威行 不是本包的产物,改写即篡改);
- **ctx 超时/取消由实现自判**:读失败返回 error 且**不得返回部分 结果**——本包收到 error 即游标不动,返回了一半会让「失败」与 「成功读到前半段」不可分。
type Tailer ¶ added in v0.38.0
type Tailer struct {
// contains filtered or unexported fields
}
Tailer 跨副本事件尾随器:每副本一条,把权威存储里 id > 游标 的新事件 回灌本进程 Hub(scope:replica,见包头「不套 leader 门」一节)。
零值不可用,用 NewTailer 构造。Run 同步阻塞到 ctx 取消(不另起 goroutine ——起 goroutine 归宿主的后台装配面,本包不碰 `harness-no-bare-goroutine` 的 判定面),故宿主在自己的后台任务里调它。
func NewTailer ¶ added in v0.38.0
func NewTailer(store TailStore, hub *Hub, opts ...TailerOption) *Tailer
NewTailer 构造:store 与 hub 均必填。
nil 即 panic——没有存储的「尾随」与没有 Hub 的「补灌」都不是半成品而是 空转,fail fast 在装配点,不留到运行时(与 NewDurablePublisher 同口径)。
func (*Tailer) Run ¶ added in v0.38.0
Run 尾随循环:每 interval 一拍,直到 ctx 取消(同步返回)。
五步语义:
- **初始化游标**:装配了 CursorStore ⇒ 先 LoadCursor——命中即从上次 停点起随(#183 重启续随);未命中回退显式起点 / MaxID;Load 失败 停摆重试,绝不静默回退 MaxID(那会跳过停机窗口)。未装配 CursorStore ⇒ 取 MaxID(首拍只读游标、不读存量——本面是**补灌**不是回放,存量 窗口回放归连接侧 after-cursor 应答);初始化失败下一拍重试,不推进 任何状态。初始化完成的游标立即落盘(#183)——不落盘,重启会重走 MaxID,而停机窗口里游标空间已前进,重走正好把窗口内的事件跳过;
- **读 id > 游标 的新事件回灌**,逐条 Publish 后推进游标;
- **空洞即哨兵响**(#183):段内出现跳号(首条 > 游标+1 或相邻不连续) 时告警——TailStore 违反「无空洞推进」契约,被跳的 ID 大概率永久丢失。 事件段照常投递(停摆只会让缺口更大),但失败必须响,不静默;
- **读失败游标不动**:瞬时存储抖动下,下一拍用同一个游标重读 (append-only + 无空洞推进契约 ⇒ 幂等补读,不丢不重——重的部分由 订阅侧游标吸收);
- **ctx 取消即退出**:select ctx.Done 是唯一退出式(`for range` 永不 返回的教训见 Hub 包注释),ticker 随 defer 停止,无泄漏。
游标前进后经 CursorStore.SaveCursor 落盘(每拍至多一次);保存失败只 warn——游标落后只会导致重启后重读(订阅侧幂等吸收),停摆反而拆了桥。
type TailerOption ¶ added in v0.38.0
type TailerOption func(*Tailer)
TailerOption 尾随器可选项。
func WithTailBatchLimit ¶ added in v0.38.0
func WithTailBatchLimit(n int) TailerOption
WithTailBatchLimit 覆盖单拍批量上限(n <= 0 归缺省 DefaultTailLimit)。
func WithTailCursorStore ¶ added in v0.39.0
func WithTailCursorStore(s CursorStore) TailerOption
WithTailCursorStore 装配游标持久化接缝(issue #183)。
装配后初始化顺序:LoadCursor 命中 ⇒ 从持久化游标起随(重启续随,停机 窗口内的事件仍被补灌);未命中 ⇒ 回退显式起点 / MaxID(首次部署); Load 失败 ⇒ 停摆重试,**绝不静默回退 MaxID**(那会跳过停机窗口)。 游标每前进一拍即 SaveCursor;保存失败只 warn 不停摆(游标落后只会 重读,订阅侧幂等吸收)。
func WithTailInterval ¶ added in v0.38.0
func WithTailInterval(d time.Duration) TailerOption
WithTailInterval 覆盖尾随间隔(d <= 0 归缺省 DefaultTailInterval)。
func WithTailOnGap ¶ added in v0.39.0
func WithTailOnGap(fn func(from, to uint64)) TailerOption
WithTailOnGap 注入游标空洞哨兵(issue #183):Tailer 观测到跳号—— 返回段的首条 ID 大于游标+1,或段内相邻两条不连续——即回调 fn(from, to)(from..to = 被跳过的 ID 闭区间)。缺省走包内 warn 日志。
哨兵响 = TailStore 违反「无空洞推进」契约(乱序提交漏防或行被删), 被跳的 ID 大概率**永久丢失**(游标已越过)——宿主该把它接告警/指标, 不是当正常路径。回调同步调用、在尾随拍内:不得阻塞、不得回调 Publish。
func WithTailStartCursor ¶ added in v0.38.0
func WithTailStartCursor(id uint64) TailerOption
WithTailStartCursor 显式起始游标:**跳过 MaxID 初始化**,直接从给定值起随。
缺省(不给本选项)走 MaxID 初始化——从当前尾部起随、不回放存量,那是 补灌面的常态。显式给游标用于宿主已知起点的形态(如从上次停机点续随); 给 0 即从头回放,回放量由宿主自己负责。
同时装配了 CursorStore 时,**已持久化的游标优先**:LoadCursor 命中 (found=true)就从持久化值起随;未命中(found=false,首次部署)才回退 到本选项的显式起点,再回退到 MaxID。