# RFC：停止将持久化边界镜像为 agent 事件

Status: implemented

[English](2026-06-20-remove-agent-boundary-mirror-events.md) | 中文

## 问题

agent loop（智能体循环）曾通过可回放的 `SessionEvent` 日志和实时 `agent/*` 镜像两条路径暴露持久化的轮次与步骤边界。消费方不得不在两个表达同一事实的来源之间做选择，并协调二者的时序。ACP（Agent Client Protocol）和持久化层已经使用事件日志；stdio UI 是唯一仍在消费镜像事件的组件，而它也已经从 `session/event` 渲染工具调用和工具结果。

这种重复并非零成本。每次生命周期变更都要同时更新会话事件、镜像事件、文档、不变式、测试和快照预期。重复的边界事件还使失败排序变得微妙：一个轮次可能在实时 `agent/turn-end` 监听器运行之前就已被持久化关闭，因此边界之后的监听器失败在日志中已没有合法的位置可插入，只能带外报告。

## 决策

让 `session/event` 成为唯一的实时边界/transcript（文本记录）流。需要渲染轮次、工具调用、工具结果、助手消息和持久化边界的消费方统一订阅 `session/event`，从持久化层使用的同一套事件词汇派生 UI。

移除 `agent/turn-start`、`agent/turn-end`、`agent/step-start` 和 `agent/step-end`。边界消费方改为订阅 `session/event`。需要 agent 标签的 UI 通过 `agent/created` 和 `agent/disposed` 维护一份 session 到 agent 的映射，因为持久化的 `turn/start` 携带轮次编号但不携带 agent id。

步骤镜像没有消费方，已由 [event-domain-semantics RFC](../architecture/2026-06-30-event-domain-semantics.md) 率先移除。该决策保留了轮次镜像供 stdio UI 使用；本 RFC 在将测试 REPL 迁移到 `session/event` 加 id 映射之后，将轮次镜像也一并移除。

## 范围：移除什么、不移除什么

本决策仅涉及持久化的轮次与步骤边界。`agent/steering` 镜像的是一条控制记录，`agent/stream-chunk` 镜像的是 token 流，因此各自单独处理：见 [steering](2026-07-04-remove-agent-steering-mirror.md) 和 [stream chunks](2026-07-02-remove-stream-chunk-mirror.md)。`agent/created`、`agent/disposed`、`agent/status`、`agent/error` 和 `agent/queued` 仍作为实时生命周期或控制事件保留，而非 transcript 镜像；排队的输入可能在任何持久化事件产生之前就被取消。

## 曾考虑的替代方案

- **在同一个变更中移除 `agent/steering`**：否决，因为它镜像的是控制记录而非边界。
- **为 stdio UI 保留轮次镜像**：否决，因为 UI 可以渲染 `session/event` 并从 id 映射中恢复 agent 标签。

## 后果

插件不再能从便捷的 `Agent` 优先事件中观察轮次/步骤边界。它必须订阅 `session/event` 或自行维护 session 到 agent 的关联。这是可接受的取舍：边界消费方不应依赖一条可能与持久化日志产生漂移的第二事件源。