qwen-code 会话回放有界窗口设计：基于字节上限的 Replay 内存治理与 history_truncated 状态标记

qwen-code 会话回放有界窗口设计基于字节上限的 Replay 内存治理与 history_truncated 状态标记【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code导读qwen-code 的守护进程daemon在内存中保留会话回放replay历史用于支持POST /session/:id/load对后加入客户端的回放注入。本篇技术文章基于 docs/design/2026-07-07-bounded-replay-snapshot-window.md 设计文档结合仓库源码compactionEngine.ts、replayWindowLimits.ts、serve.ts 等详细讲解如何以序列化字节数为独立于 SSE 环形缓冲ring的回放窗口上限如何通过分段segment化存储实现按字节淘汰以及history_truncated状态标记的线缆形态、过滤规则与客户端投影。读完本文你将掌握 qwen-code 会话回放内存治理的完整设计脉络、CLI 配置项与校验规则以及回放截断时客户端如何安全降级。问题背景回放保留必须独立于 SSE 环形缓冲做字节级约束守护进程为每个 live 会话在内存中保留回放历史目的是让POST /session/:id/load能在客户端晚加入late attach时注入回放数据。设计文档明确指出回放保留不能与 SSE 环形缓冲ring共用一套上限原因有二response-mode 恢复可以批量灌入大量历史更新POST /load的响应模式response-mode restore可能一次性 seed 大量历史回放事件这些事件没有 live 边界已完成的 live turn 会在长会话中无限累积每个完成的 turn 都会被压实compaction成一个回放段会话运行越久段越多内存占用无上界。同时文档强调磁盘会话历史仍然是权威完整转录源authoritative full transcript source本次设计PR-1只约束 daemon 的 live 内存回放窗口不新增完整转录端点。设计目标与非目标目标按序列化字节数为每个 live 会话的回放事件设置上限默认4 MiB非法配置在启动时拒绝上限同时作用于两类回放已完成 live-turn 的回放段与response-mode / stream-mode 恢复的历史回放保持既有快照线缆形态compactedReplay、liveJournal、lastEventId即使单个回放单元超过上限也至少保留一个真实回放事件或一个已完成 live-turn 段截断发生时在compactedReplay开头放置无 id 的history_truncated标记history_truncated只作为状态呈现不得触发state_resync_required、不得引发 reload 循环、不得回写进回放窗口。非目标及后续演进单个 in-flight live turn 不做上限该限制已由 DAEMON-009PR #7622补上——liveJournal现在受maxJournalEvents默认 10 000与maxJournalBytes默认 8 MiB约束可通过--max-journal-events/--max-journal-bytes配置不做 turn 数量上限turn 数仅作为诊断信息不为该增量事件添加/capabilities特性标签解析后的上限在 daemon status 中暴露不提供完整转录端点PR-2 必须设计分页或流式的转录读取禁止一次性返回完整数组。核心设计分段存储 字节上限淘汰从无界扁平数组到有序分段TurnBoundaryCompactionEnginepackages/acp-bridge/src/compactionEngine.ts将保留的回放存储为有序段ordered segments取代原本无界的扁平数组一个已完成的 live turn构成一个段turn segment由turn_complete/turn_error边界事件触发压实后入队restore / bulk seed 回放按事件级分段event-level segments这样当字节上限被突破时最旧的 restore 事件可以被独立丢弃。从源码看段的数据结构为interface ReplaySegment { events: BridgeEvent[]; bytes: number; turnCount: number; }引擎维护replaySegments数组、replaySegmentStart游标指向首个存活段与replayBytes累计字节数。activeReplaySegmentCount()通过replaySegments.length - replaySegmentStart计算存活段数量当被丢弃的段数累积超过REPLAY_SEGMENT_COMPACT_THRESHOLD64时通过compactReplaySegmentQueueIfNeeded()做数组前部裁剪避免游标无限增长。字节计量复用 EventBus 的安全序列化语义段字节数通过serializedBridgeEventByteLength(event)计算与 EventBus 的安全 JSON 序列化共用同一套语义。关键设计决策是计量失败不抛异常——当某个事件无法序列化时记录诊断日志并把该事件按 0 字节计数从而让 publish 与 seed 路径保持never-throws契约源码中addReplaySegment的注释明确说明live 事件已通过发布时序列化检查而 seed 路径持久化转录绕过了该检查因此单个不可序列化记录不能卡死回放窗口记账。淘汰算法与统计当replayBytes maxReplayBytes时引擎在存活段多于 1 个的前提下从最旧段开始丢弃循环执行递增truncatedEvents丢弃的事件总数仅当丢弃的是 live-turn 段时递增truncatedTurns记录最近一次被丢弃段的 recordId用于分页锚点见下文每次淘汰都会回调onReplayWindowEviction携带ReplayWindowEviction统计droppedBytes、droppedEvents、droppedSegments、droppedTurns、maxBytes、retainedBytes、retainedEvents。enforceReplayWindow()的 while 条件replayBytes maxReplayBytes activeReplaySegmentCount() 1正是至少保留最新一段这一目标的实现——即使最新段单独就超过上限也绝不把回放清空。snapshot 的线缆形态与 history_truncated 标记snapshot()将存活段扁平化flattenReplaySegments()得到compactedTurns若发生过截断truncatedEvents 0则在最前面插入合成标记事件{ type: history_truncated, data: { reason: replay_window_exceeded, truncatedEvents: 12, retainedEvents: 8, maxBytes: 4194304, truncatedTurns: 3, fullTranscriptAvailable: true } }标记的特征与约束源码makeHistoryTruncatedEvent()与TRANSIENT_TYPES集合合成且无 idid字段不出现因此不参与字节记账、不进入临时回放保留属于 transient 类型ingest()、seed(snapshot)、seedReplayEvents()都会过滤它避免加载一个有界快照后再次产生标记的叠加问题fullTranscriptAvailable: true表明磁盘完整转录仍然可用当存在分页锚点时标记会额外携带recordId字段——该锚点取自首次淘汰时第一个保留段的 recordId即淘汰边界这样客户端用beforeRecordId做转录分页时能精确取回被丢弃的记录且与保留窗口无重叠。源码注释明确指出不能使用activeRecordId因为它会被后续ingest()推进锚点可能落入保留窗口内导致客户端重复拉取已展示的转录块。EventBus.seedReplayEvents 与 liveJournal 的隔离EventBus.seedReplayEvents()packages/acp-bridge/src/eventBus.ts负责 bulk restore 回放为每个 restore 事件分配id与时间戳serverTimestamp调用压实引擎的专用 seed 方法seedReplayEvents()清空 SSE ringthis.ring.length 0保持 ring 始终是已产生 id 的连续后缀捕获引擎异常并标记压缩降级markCompactionDegraded保持 never-throws 契约。引擎的seedReplayEvents()与seed(snapshot)都会先resetReplayWindow()再按段入队并调用resetJournal()清空 in-flight journal——这就保证了 bulk restore 回放不会追加进liveJournal。liveJournal只容纳自上个 turn 边界以来的事件liveJournalSnapshot()注释二者在内存中严格隔离。配置校验与 fail-closed回放字节上限通过normalizeCompactedReplayMaxBytes()packages/acp-bridge/src/replayWindowLimits.ts校验非法值在启动时抛TypeError拒绝启动fail closed配置项默认值合法范围compactedReplayMaxBytes回放快照字节上限4 MiBDEFAULT_COMPACTED_REPLAY_MAX_BYTES正整数[1, 256 MiB]MAX_COMPACTED_REPLAY_MAX_BYTESmaxJournalEventslive journal 事件数基线10 000DEFAULT_MAX_JOURNAL_EVENTS正整数maxJournalByteslive journal 源事件字节基线8 MiBDEFAULT_MAX_JOURNAL_BYTES正整数journalGrowthPoolBytes自适应增长池可选未配置则禁用自适应增长正整数非法输入包括0、负数、非整数、NaN、Infinity以及超过 256 MiB 的取值。校验逻辑使用Number.isSafeInteger保证安全整数语义。CLI 与全链路传递CLI 侧packages/cli/src/commands/serve.ts通过 yargs 暴露以下选项--compacted-replay-max-bytesper-session 内存压实回放快照字节上限服务于POST /session/:id/load的 late attach默认 4 MiB最大 256 MiB--max-journal-eventsin-flight live journal当前未完成 turn的回放条目基线上限兼容的文本/思考块共享有界条目超出后 daemon 先尝试自适应增长无授权则丢弃最旧条目--max-journal-byteslive journal 的源事件字节基线上限超出时自适应增长会在 daemon 内存预算--memory-budget-mb派生的增长池内提高会话上限per-session 硬上限 256 MiB即JOURNAL_GROWTH_HARD_CAP_BYTES无授权则整体丢弃最旧条目至少保留一条注意固定指定--max-journal-events或--max-journal-bytes会禁用自适应增长不固定时runQwenServe从 daemon 内存预算派生增长池增长池 有效预算的固定比例上限MAX_JOURNAL_GROWTH_POOL_MB有效预算低于最小阈值时增长池为 0即禁用增长。该解析结果沿yargs→ 快速路径解析器fast-path parser→ServeOptions→ 服务端装配server wiring→BridgeOptions→ bridge 状态 → daemon status 渲染完整传递fast-path.ts、run-qwen-serve.ts、daemon-status.ts、server.ts最终在 daemon status 的 limits 区域对外暴露。内存上限的两条边界replayWindowLimits.ts的注释提供了一个重要的内存规划提醒一次 in-flight turn 会保留两个共享相同上限的 journal——fulljournal 与面向 summary-mode 加载的summary投影——因此单个会话 live journal 的堆占用上界是有效上限的 2 倍基线 2 倍或自适应增长后的 2 倍。运维人员按maxJournalBytes × live 会话数估算 daemon 内存时必须将 journal 项翻倍。此外JOURNAL_GROWTH_HARD_CAP_BYTES256 MiB与MAX_COMPACTED_REPLAY_MAX_BYTES对齐二者共同约束单个会话回放状态在 daemon 堆中的保留量。客户端侧SDK 与 WebUI 的 history_truncated 投影history_truncated对客户端而言不是未知/调试事件也不参与 resync 门控resync gating。仓库中 SDK 与 WebUI 的相关实现包括packages/sdk-typescript/src/daemon/events.ts 与 packages/sdk-typescript/src/daemon/types.ts已知事件类型定义与载荷校验packages/sdk-typescript/src/daemon/ui/normalizer.tsnormalizer 要求reason replay_window_exceeded否则将该帧降级为未知/调试事件liveJournalSnapshot()中 journal 截断标记复用同一reason并以scope: live_journal区分来源额外字段可通过两侧校验器packages/sdk-typescript/src/daemon/DaemonSessionClient.ts客户端加载流程对compactedReplay中标记的处理packages/web-shell/client/daemon/session/live-journal-repair.tsWebUI 侧回放注入与修复逻辑。客户端行为概括为识别history_truncated→ 校验其载荷 → 投影为视图状态计数器与转录状态 → 在终端状态行渲染截断提示truncated 事件数、保留事件数、上限字节数等让用户明确知道当前视图是有界窗口而非完整历史。审计要点五轮设计修正的演进逻辑设计文档记录了五轮评审修正这些修正直接塑造了最终实现Round 1为何必须做事件级 seed 段仅对已完成 live turn 设上限是不够的因为 response-mode restore 可以灌入没有 live 边界的大量历史回放因此补充seedReplayEvents()与事件级历史段Round 2为何不能用 state_resync_required复用state_resync_required表达截断会引发 reload 循环——/load会一直返回同一个有界窗口客户端反复 resync 永远追不上因此改用独立的history_truncated状态标记且绝不设置awaitingResyncRound 3为何不用 turn 数上限单个 turn 可能包含超大工具输出turn 数上限无法约束内存PR-1 采用纯字节强制active-turn 上限留待 DAEMON-009Round 4为何不返回完整转录数组请求时一次性返回完整转录数组会在读取端复现同样的峰值内存问题PR-2 被明确约束为分页或流式Round 5为何截断后仍保留最新段截断后如果回放为空客户端会丢失全部可见状态因此引擎在超限时也保留最新一段activeReplaySegmentCount() 1条件。验证计划与可复现路径设计文档要求并通过仓库中的测试用例覆盖以下行为单元测试live turn 裁剪、restore seed 裁剪、标记放置、transient 标记过滤、超限最新段保留、安全计量失败、EventBus never-throws见 compactionEngine.test.ts 与 bridge.test.tsbridge 层response-mode restore 与 live-session load 在有界窗口下的行为CLI 层yargs 解析、快速路径解析、runQwenServe校验、server bridge 装配与 daemon status 上限展示见 serve.test.ts、run-qwen-serve.test.ts、daemon-status.test.tsSDK / WebUI 层已知事件校验、reducer 状态、UI normalizer、转录状态、终端渲染与 WebUI 回放注入见 daemonEvents.test.ts、daemonUi.test.ts、DaemonSessionProvider.test.tsx最终验证统一走npm run build、npm run typecheck、npm run lint。结论与运维启示bounded replay snapshot window设计为 qwen-code 的 live 会话回放提供了独立于 SSE ring 的字节级内存上限以段为单位的有序存储让已完成的 turn与bulk restore 的历史回放可以被独立、按需地淘汰合成且无 id 的history_truncated标记在保持既有快照线缆形态的同时把截断如实呈现给 SDK/WebUI且刻意避开 resync 循环与回放窗口回写启动期 fail-closed 校验保证非法配置0、负数、非整数、NaN、Infinity、超过 256 MiB不会进入运行期。对运维和二次开发者的直接启示长会话 大工具输出的场景通过--compacted-replay-max-bytes控制/load快照的堆占用通过--max-journal-bytes/--max-journal-events控制 in-flight turn 的 journal 占用需要自适应增长时不要固定这两个 journal 旗标并留意--memory-budget-mb派生的增长池估算单会话回放堆占用时journal 项按有效上限 × 2full summary计算客户端侧务必以reason replay_window_exceeded作为history_truncated的合法判定并将recordId锚点用于beforeRecordId转录分页即可在截断后无缝衔接磁盘完整转录。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考