类型化 Daemon 事件 Schema v1

概述

Daemon 在 GET /session/:id/events 上发出的每个 SSE 帧格式为 { id, v, type, data, originatorClientId?, _meta? }。v: 1 是当前的 EVENT_SCHEMA_VERSION。type 来自 packages/sdk-typescript/src/daemon/events.ts 中封闭的、版本固定的 DAEMON_KNOWN_EVENT_TYPE_VALUES 集合，当前集合包含 43 种已知事件类型。信封 _meta 字段由 server.ts 中的 formatSseFrame() 在 SSE 写入边界处标记；参见信封级别元数据。

SDK 暴露了 asKnownDaemonEvent(evt)。对于已知事件类型，它返回一个可判别的 KnownDaemonEvent；对于其他类型，返回 undefined。因此，SDK 消费者可以在不要求同步升级 SDK 的情况下处理向前兼容性——当较新的 daemon 新增事件类型时，session reducer 会将这些事件记录为 unrecognizedKnownEventCount。

Wire 格式位于 ../qwen-serve-protocol.md。本页是每个事件的 payload 契约。

职责

• 提供事件词汇表（DAEMON_KNOWN_EVENT_TYPE_VALUES）的唯一可信来源。
• 为每种事件类型提供类型化信封（DaemonEventEnvelope<TType, TData>）。
• 提供纯 reducer（reduceDaemonSessionEvent、reduceDaemonAuthEvent），将事件流投影为 SDK 视图状态。
• 广播 typed_event_schema 能力标签作为信息性信号。若该标签缺失，asKnownDaemonEvent 仍会回退到 unknown。

事件词汇表（43 种已知类型）

按领域分组。

核心 session

订阅者级别合成帧

权限（F3 + base）

模型

MCP 安全护栏（PR 14b + F2）

变更控制（Wave 4 PR 16+17）

Auth 设备流（PR 21）

这些事件以工作区为键，而非以 session 为键。session reducer 将其视为无操作；reduceDaemonAuthEvent 将其投影为工作区级别状态。

MCP 运行时变更

轮次生命周期 / 助手推送

架构

DaemonSessionViewState

reduceDaemonSessionEvent 填充此视图状态。CLI TUI 适配器、DaemonChannelBridge 和 VS Code IDE 均消费它。关键字段：

• alive: boolean - 在终止帧（session_died、session_closed、client_evicted、stream_error）后变为 false。
• currentModelId?: string - 来自 model_switched。
• displayName?: string - 来自 session_metadata_updated。
• pendingPermissions: Record<string, DaemonPermissionRequestData> - 以 requestId 为键的待处理请求；由 permission_resolved / permission_already_resolved 清除。
• lastSessionUpdate?: DaemonSessionUpdateData - 最新的 session_update。
• lastModelSwitchFailure?: DaemonModelSwitchFailedData - 来自 model_switch_failed。
• terminalEvent? - 原始终止事件。
• streamError?: DaemonStreamErrorData - 最新的 stream_error payload。
• unrecognizedKnownEventCount、lastUnrecognizedKnownEvent? - 事件被 asKnownDaemonEvent 识别但 reducer 尚无专用状态。
• droppedPermissionRequestCount、lastDroppedPermissionRequestId? - 格式错误的权限请求无法进入待处理映射。
• unmatchedPermissionResolutionCount、lastUnmatchedPermissionResolutionId? - 权限解析没有匹配的待处理请求。
• slowClientWarningCount、lastSlowClientWarning? - 来自 slow_client_warning。
• mcpBudgetWarningCount、lastMcpBudgetWarning? - 来自 mcp_budget_warning。
• mcpChildRefusedBatchCount、lastMcpChildRefusedBatch? - 来自 mcp_child_refused_batch。
• lastWorkspaceMutation?、lastWorkspaceMutationType? - 来自 memory_changed / agent_changed。
• approvalMode?、approvalModeChangedCount、lastApprovalModeChange? - 来自 approval_mode_changed。
• toolToggleCount、lastToolToggle? - 来自 tool_toggled。
• workspaceInitCount、lastWorkspaceInit? - 来自 workspace_initialized。
• mcpRestartCount、lastMcpRestart? - 来自 mcp_server_restarted。
• mcpRestartRefusedCount、lastMcpRestartRefused? - 来自 mcp_server_restart_refused。
• settings_changed / settings_reloaded - 被 asKnownDaemonEvent 识别；session reducer 不维护专用视图状态字段，UI 通常将其视为刷新信号。
• permissionVoteProgress: Record<string, DaemonPermissionPartialVoteData> - 共识投票进度。
• forbiddenVotes: DaemonPermissionForbiddenData[]、forbiddenVoteCount - 策略拒绝的投票记录，上限 32 条。
• awaitingResync: boolean - 由 state_resync_required 设置；消费者重置视图状态时清除。
• resyncRequiredCount、lastResyncRequired? - resync 可观测性。
• lastFollowupSuggestion?: DaemonFollowupSuggestionData - daemon 推送的最新后续建议。
• lastTurnComplete?: DaemonTurnCompleteData - 最新成功的轮次完成。
• lastTurnError?: DaemonTurnErrorData - 最新的轮次错误。
• rewindCount、lastRewind?、lastBranch? - 最新的回退/分支事件。

DaemonAuthState

每个 providerId 对应一个条目，由 auth_device_flow_* 驱动。每个流暴露 { deviceFlowId, status, providerId, expiresAt?, lastThrottleIntervalMs?, lastError? }。

流程

生产者侧

消费者侧（SDK）

信封级别元数据

除每个事件的 data payload 外，daemon 还会标记两个信封级别字段。

_meta.serverTimestamp - daemon 时钟

packages/cli/src/serve/server.ts 中的 formatSseFrame() 在 SSE 写入边界处标记此字段，不是在 EventBus.publish 内部。内存中的 BridgeEvent 类型保持不变；daemon 内部消费者不会看到 _meta，而 wire SSE 帧会包含它。

{
  "id": 47,
  "v": 1,
  "type": "session_update",
  "data": { ... },
  "_meta": { "serverTimestamp": 1716287345123 }
}

合并会保留所有现有的 _meta 键 （{...existingMeta, serverTimestamp: Date.now()}）。当前没有任何 daemon 生产者 写入信封级别的 _meta。顶层合并是一个向前兼容的 逃生舱口。

为何重要：渲染相对时间或对对话块排序的多客户端 UI 应使用服务器时间，而不是各个浏览器/标签页/手机的本地时钟。服务器端标记使跨客户端的排序保持一致。

SDK 访问方式：优先使用 event._meta?.serverTimestamp。兼容路径也可以探测 event.serverTimestamp 或 event.data._meta.serverTimestamp。不要混淆 ACP payload 的 data._meta 与 daemon 信封的 _meta。

originatorClientId

由携带已注册 X-Qwen-Client-Id 的请求触发的事件可能会标记此字段。参见 08-session-lifecycle.md。

工具调用 _meta（来源 / serverId）

这与信封 _meta 是独立的：ACP session/update payload 可以在 event.data._meta 中携带自己的 _meta。ToolCallEmitter（packages/cli/src/acp-integration/session/emitters/ToolCallEmitter.ts）在 emitStart、emitResult 和 emitError 时标记两个字段：

现有的 _meta.toolName 显示名称得以保留。UI 使用这些字段来渲染 builtin / MCP 服务器 / subagent 徽章，无需重新解析工具名称。

SDK reducer 行为

packages/sdk-typescript/src/daemon/events.ts 中的 reduceDaemonSessionEvent(state, evt) 将事件流投影为 DaemonSessionViewState。与 resync 相关的字段：

• awaitingResync: boolean - 由 state_resync_required 设置；调用者清除，通常在 POST /session/:id/load 重置视图状态后。
• resyncRequiredCount: number - 可观测性计数器。
• lastResyncRequired?: DaemonStateResyncRequiredData - 最新 payload。

当 awaitingResync = true 时，reducer 跳过 delta 应用，只允许封闭的 RESYNC_PASSTHROUGH_TYPES 集合：

lastEventId 在 resync 期间仍通过 advanceLastEventId(base) 单调递增。调用者重置并清除 awaitingResync 后，后续 delta 将与正确的游标对齐。

reduceDaemonAuthEvent 将设备流事件投影为工作区级别的 auth 状态条目，概念上形如 {deviceFlowId, status, providerId, expiresAt?, lastThrottleIntervalMs?, lastError?}。在代码中，reducer 将 status、errorKind、hint、 intervalMs、lastSeenEventId、authorizedExpiresAt 和 accountAlias 存储在 DaemonDeviceFlowReducerState 上；daemon 事件 payload 本身保持上述每个事件的形状。

状态与向前兼容性

• 通过向 DAEMON_KNOWN_EVENT_TYPE_VALUES 末尾追加来新增已知事件类型。旧 SDK 通过回退路径对未识别的事件类型返回 undefined 并递增 unrecognizedKnownEventCount；新 SDK 依赖可判别联合。
• 向现有 payload 添加可选字段是安全的，因为 payload 是开放的（{ [key: string]: unknown }）。
• 更改现有 payload 结构是破坏性变更，必须升级 EVENT_SCHEMA_VERSION 并广播兼容的能力标签，如 caps.features.typed_event_schema_v2。
• id 在每个 session 内单调递增。订阅者级别的合成帧（client_evicted、slow_client_warning、stream_error、state_resync_required、replay_complete、session_snapshot）有意不带 id，这样其他订阅者就不会看到间隔。
• originatorClientId 位于信封而非 data 上。F3 的 partial-vote / forbidden payload 也通过 mergeOriginator 将其合并到 data 中，这样视图状态消费者就不需要保留信封。

依赖

• 10-event-bus.md - 投递通道。
• 11-capabilities-versioning.md - SDK 如何预检 typed_event_schema、mcp_guardrail_events 和 permission_mediation。
• 04-permission-mediation.md - 权限事件如何产生。
• 13-sdk-daemon-client.md - asKnownDaemonEvent、reducer 和视图状态结构。

配置

• 始终广播：typed_event_schema、mcp_guardrail_events 和 permission_mediation（含支持的策略模式）。
• 没有环境变量或标志直接控制 schema 本身。QWEN_SERVE_NO_MCP_POOL=1 会将 MCP 事件的 scope 从 'workspace' 更改为缺失或 'session'。

注意事项与已知限制

• 六种合成帧类型有意不带 id；SDK 代码不能假设每个事件都有 id。
• permission_partial_vote 仅出现在 consensus 策略下。permission_forbidden 出现在 designated、consensus 和 local-only 下，但不出现在 first-responder 下。
• mcp_child_refused_batch 仅出现在 mode: 'enforce' 时；warn 模式从不拒绝。
• auth_device_flow_* 事件不以 session 为键。通过 DaemonSessionClient 消费时，应使用 reduceDaemonAuthEvent 处理这些事件，而非 session reducer。

参考

• packages/sdk-typescript/src/daemon/events.ts
• packages/acp-bridge/src/eventBus.ts（EVENT_SCHEMA_VERSION）
• packages/cli/src/serve/capabilities.ts（typed_event_schema、mcp_guardrail_events、permission_mediation）
• Wire 参考：../qwen-serve-protocol.md