类型化 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 集合；当前集合包含 47 种已知事件类型。envelope 的 _meta 字段由 packages/cli/src/serve/routes/sse-events.ts 中的 formatSseFrame() 在 SSE 写入边界处注入；请参阅 Envelope-level metadata。

SDK 暴露了 asKnownDaemonEvent(evt)。它为已知事件类型返回一个可区分的 KnownDaemonEvent，为其他类型返回 undefined。因此，当较新的 daemon 添加新事件类型时，SDK 使用者可以处理向前兼容性，而无需 SDK 同步升级；session reducer 会将这些事件记录为 unrecognizedKnownEventCount。

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

职责

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

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

按领域分组。

核心 session

订阅者级别的合成帧

权限（F3 + base）

模型

MCP 护栏（PR 14b + F2）

变更控制 (Wave 4 PR 16+17)

memory_changed 还涵盖无会话的托管内存任务。对于这些 payload，scope 为 "managed"，source 为 "workspace_memory_remember"、"workspace_memory_forget" 或 "workspace_memory_dream" 之一，taskId 是排队的任务 ID，touchedScopes 列出已变更的托管内存作用域（"user" 和/或 "project"）。当 remember/forget/dream 任务完成但未触及托管内存时，不会发出任何事件。

设备授权流程 (PR 21)

这些事件以工作区为键（workspace-keyed），而非以会话为键。会话 reducer 将它们视为无操作（no-ops）；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 识别；会话 reducer 不维护专用的视图状态字段，UI 通常将它们视为刷新信号。
• permissionVoteProgress: Record<string, DaemonPermissionPartialVoteData> - 共识投票进度。
• forbiddenVotes: DaemonPermissionForbiddenData[], forbiddenVoteCount - 被策略拒绝的投票记录，上限为 32。
• awaitingResync: boolean - 由 state_resync_required 设置；当消费者重置视图状态时清除。
• resyncRequiredCount, lastResyncRequired? - 重新同步可观测性。
• lastFollowupSuggestion?: DaemonFollowupSuggestionData - Daemon 推送的最新后续建议。
• lastTurnComplete?: DaemonTurnCompleteData - 最新的成功轮次完成。
• lastTurnError?: DaemonTurnErrorData - 最新的轮次错误。
• rewindCount, lastRewind?, lastBranch? - 最新的回退（rewind）/ 分支（branch）事件。

DaemonAuthState

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

流程

生产者侧

消费者侧 (SDK)

信封级元数据

除了每个事件的 data 负载外，daemon 还会注入两个信封级字段。

_meta.serverTimestamp - daemon 时钟

packages/acp-bridge/src/eventBus.ts 中的 EventBus.publish() 会在事件进入 bus 时打上 _meta.serverTimestamp 时间戳。BridgeEvent 类型包含 _meta?: Record<string, unknown>，因此内部 daemon 消费者确实能在每个通过 bus 发布的事件中看到 _meta。packages/cli/src/serve/routes/sse-events.ts 中的 formatSseFrame() 仅为绕过 EventBus.publish 的合成帧（例如 stream_error）提供回退时间戳。

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

合并操作会保留输入事件中已有的 _meta 键（{...input._meta, serverTimestamp: Date.now()}）。生产者可以附加额外的信封级 _meta 键；EventBus.publish 会将它们与时间戳合并，而不是覆盖。

为什么这很重要：渲染相对时间或对 transcript 块进行排序的多客户端 UI 应该使用服务器时间，而不是每个浏览器/标签页/手机的本地时钟。服务器打时间戳可确保跨客户端的排序一致性。

SDK 访问方式：优先使用 event._meta?.serverTimestamp。兼容路径可能也会探测 event.serverTimestamp 或 event.data._meta.serverTimestamp。请勿将 ACP 负载的 data._meta 与 daemon 信封的 _meta 混淆。

originatorClientId

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

工具调用 _meta（provenance / serverId）

这与信封 _meta 不同：ACP session/update 负载可以在 event.data._meta 中携带自己的 _meta。ToolCallEmitter（packages/cli/src/acp-integration/session/emitters/ToolCallEmitter.ts）在 emitStart、emitResult 和 emitError 时打上两个字段：

现有的 _meta.toolName 显示名称会被保留。UI 使用这些字段来渲染 builtin / MCP server / 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 - 最新的负载。

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

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

reduceDaemonAuthEvent 在概念上将 device-flow 事件投影到工作区级别的 auth 状态条目中，其形状类似于 {deviceFlowId, status, providerId, expiresAt?, lastThrottleIntervalMs?, lastError?}。在代码中，reducer 将 status、errorKind、hint、intervalMs、lastSeenEventId、authorizedExpiresAt 和 accountAlias 存储在 DaemonDeviceFlowReducerState 上；daemon 事件负载本身则保持为上面列出的每个事件的形状。

状态与向前兼容性

• 通过追加到 DAEMON_KNOWN_EVENT_TYPE_VALUES 来添加已知事件类型。旧版 SDK 通过回退路径对无法识别的事件类型返回 undefined 并递增 unrecognizedKnownEventCount；新版 SDK 则依赖可辨识联合类型（discriminated union）。
• 向现有负载添加可选字段是安全的，因为负载是开放的（{ [key: string]: unknown }）。
• 更改现有负载的形状属于破坏性变更，必须提升 EVENT_SCHEMA_VERSION，并广播兼容的 capability 标签，例如 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 负载也会通过 mergeOriginator 将其合并到 data 中，因此视图状态消费者无需保留信封。

依赖项

• 10-event-bus.md - 传输通道。
• 11-capabilities-versioning.md - SDK 如何预检 typed_event_schema、mcp_guardrail_events 和 permission_mediation。
• 04-permission-mediation.md - 如何生成 permission 事件。
• 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）
• 协议参考：../qwen-serve-protocol.md