企业官网建设流程全解析

qwen-code 工作区会话实时状态活动时间戳（updatedAt）协议设计解析

【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code

本文围绕 qwen-code 工作区会话实时状态（live-state）协议的一次增量演进展开：为GET /workspaces/:workspace/sessions/live-state返回的每个实时会话追加可选的updatedAt活动时间戳，使客户端无需重新扫描持久化会话目录即可刷新已加载行的新旧程度。读完本文，你将理解该字段的语义边界（活动水印 vs 持久化确认）、单调性与因果顺序保证、与目录版本（generation + revision）的分工，以及服务端桥接层、TypeScript SDK 与后续 Web Shell 消费方的完整契约。

背景：live-state 协议遗留的“最后一公里”

原始的工作区会话实时状态协议（见 2026-08-16-workspace-session-live-state.md）把两个关注点彻底分离：

1. 易变的实时状态由廉价的纯内存端点返回；
2. 目录变更推进generation + revision版本号。

普通 turn 的完成刻意不推进目录 revision。因此第一个 Web Shell 消费方在每次 turn 结束后仍保留一个限速的全量目录对账（full catalog reconciliation），否则持久化的updatedAt与会话排序会一直冻结。

这个回退虽然被限速，但它依然把“普通 turn 生命周期事件”重新连接到 live-state 端点当初想要规避的高开销操作上。本设计文档的目标正是补齐这块缺口：为 live-state 条目增加一个活动时间戳，让客户端在 turn 结束后用一次纯内存请求即可完成已加载行的新旧度刷新，而不必扩大目录时钟（catalog clock）的推进范围。

值得注意的实现基础是：当前代码库已经具备这条语义路径的大部分——

• BridgeSessionSummary与DaemonSessionSummary已经声明了可选的updatedAt?: string；
• 持久化目录摘要从 transcript JSONL 文件的修改时间推导updatedAt；
• live/persisted 合并辅助函数已把 live 摘要的updatedAt视为更新鲜的值，所有基于活动的目录比较器读取updatedAt ?? createdAt；
• 桥接层通过publishPromptTerminal汇聚成功、失败、取消、deadline、teardown、传输终止等所有终态路径；
• publishPromptTerminal带有每个 prompt 的terminalPublished闩锁（latch），并能区分“已运行过的 prompt”与“从未离开队列的 prompt”。

缺失的部分仅是SessionEntry上的活动时间戳及其在摘要与 live-state 表面的投影。这可以从 acp-bridge/src/bridge.ts 与 acp-bridge/src/bridgeTypes.ts 的现有结构中直接印证。

术语与权威边界：水印而非持久化确认

协议首先明确一个关键定性：live-state 条目上的updatedAt是守护进程观测到的实时活动水印（daemon-observed live activity watermark），不是持久化确认。

权威的推进时刻是：一个其待处理条目处于running状态的 prompt 首次发布正式终态（formal terminal）。选择这个时刻优于一系列邻近信号，设计文档给出了明确取舍：

一个重要的工程事实：ACP 子进程在 prompt 调用落定之前就把 turn 结果记录入队，但记录服务使用串行化的异步写入器。因此 daemon 可以知道“某个运行中的 turn 到达了正式终态”，却不能声称“最后入队的记录已落盘”。协议显式命名这一事实，而不是把尽力而为的活动信号伪装成持久化保证——这正是后续诸多设计约束的根源。

公开 REST 契约

请求保持不变

GET /workspaces/:workspace/sessions/live-state

保留原有的 selected-runtime、workspace 作用域、仅信任（trusted-only）所有权语义，且无任何查询参数。

成功响应

{ "v": 1, "catalogVersion": { "generation": "7eca3164-bce1-4f50-94d8-c842c480f213", "revision": 17 }, "sessions": [ { "sessionId": "session-123", "clientCount": 1, "hasActivePrompt": false, "isWaitingForPermission": false, "isWaitingForUserQuestion": false, "updatedAt": "2026-08-18T08:12:30.123Z" } ] }

响应必须继续携带Cache-Control: no-store。

字段契约

export interface DaemonSessionLiveState { sessionId: string; clientCount: number; hasActivePrompt: boolean; isWaitingForPermission: boolean; isWaitingForUserQuestion: boolean; updatedAt?: string; }

当updatedAt存在时，它：

• 是合法 ISO 8601 时间戳；
• 标识当前桥接层（bridge）对该会话观测到的最新 running prompt 终态；
• 在该实时SessionEntry生命周期内严格递增；
• 在对应正式终态事件变得可见之前写入；
• 在当前桥接层代际中首个 running turn 落定之前可能缺失；
• 在 daemon 或工作区运行时替换桥接层时可能丢失；
• 不得被解释为 transcript 刷新成功的证明。

响应 schema 保持v: 1。增加一个可选对象属性是 wire-additive 的，不会改变现有字段的解码方式。字段缺失不能作为全局能力探测信号——因为一个支持该特性的 daemon 在“新代际内尚无观测到终态”的 live 条目上合法地省略它。

在 TypeScript SDK 中，该字段已随本协议落地：DaemonSessionLiveState.updatedAt带注释“Daemon-observed activity watermark ... Absent before the first such terminal and after a bridge or runtime replacement. It is not proof that the transcript was flushed”，见 sdk-typescript/src/daemon/types.ts。SDK 的调用方法是WorkspaceDaemonClient.getSessionLiveState()，实现为单次原生 REST 请求GET /workspaces/:workspace/sessions/live-state，刻意不做每次轮询前的能力探测（否则请求量翻倍），见 sdk-typescript/src/daemon/DaemonClient.ts。

转换矩阵：什么推进、什么不推进

错误或 deadline 即使 transcript 持久化降级、子进程未正常结束时也可能推进活动时间——这是刻意为之：该字段代表 daemon 观测到的运行尝试与正式终态，而非持久化结果。

单调性与因果顺序：为什么是 epoch 毫秒

SessionEntry把水印存储为 epoch 毫秒而非字符串：

lastTurnEndedAtMs?: number;

首个被接受的 running 终态按如下逻辑推进：

const createdAtMs = Date.parse(entry.createdAt); const floor = Number.isFinite(createdAtMs) ? createdAtMs : Number.NEGATIVE_INFINITY; const next = Math.max(Date.now(), (entry.lastTurnEndedAtMs ?? floor) + 1); entry.lastTurnEndedAtMs = next;

（具体实现可以为了可读性避免Number.NEGATIVE_INFINITY，但必须保留相同行为。）附加的+1ms是逻辑平局决胜符，用于墙钟时间未前进的场景，不是耗时度量。

createdAt下限至关重要：无水印的行以createdAt为键，且 live-only 游标不携带已发射身份列表。如果首个水印落后于createdAt——即创建与首个终态之间存在墙钟回拨——就会在遍历中途把已发射行的键向后移动，使“严格更旧”过滤器把它重复返回。

publishPromptTerminal必须依次：判断待处理 prompt 是否曾运行、通过重复闩锁、推进水印、记住终态状态，然后才广播turn_complete或turn_error。由此建立 happens-before 关系：

terminal latch wins -> live activity watermark advances -> formal terminal is published -> client observes terminal -> client starts live-state request -> live-state includes the new watermark

最后一步仅在该 live 条目仍存在于同一桥接层代际时成立。close 或运行时替换可能让行消失或返回新代际；协议从不跨生命周期边界携带退役的桥接本地水印。settleActivePromptState的所有权门与终态闩锁继续保护下一个 prompt 免受迟到结果影响，时间戳更新不得新增第二条独立的 settle 路径。

目录版本契约：updatedAt 不参与 generation + revision

updatedAt不参与generation + revision。版本号仍然是目录成员与静态元数据的相等性令牌。若每个 turn 都推进 revision，两秒一次的 live-state 轮询将观测到不匹配并重新触发本扩展想要消除的全量目录扫描。

客户端像合并hasActivePrompt与等待标志一样，直接从快照合并updatedAt。updatedAt变化而目录版本不变是合法且符合预期的。

持久化与全量目录合并：双权威与“取更新”

持久化会话摘要继续从 JSONL mtime 推导updatedAt。两个时间戳权威不同：

• 持久化 mtime 描述存储中可见的最新修改；
• liveupdatedAt描述桥接层可见的最新 running turn 终态。

当 live 会话与持久化摘要合并时，响应应使用两者中更晚的有效时间戳，而不是盲目偏爱某一来源——这防止异步 transcript 写入在几毫秒后获得 mtime 时，把终态时间戳所在的行向后移动。

比较辅助函数必须在另一候选缺失或非法时保留有效值。不新增任何文件系统读取：两个候选字符串在现有合并路径中都已驻留内存。

所有同时持有两个候选的表面积都应用同一规则，包括 Live Task 的读与等待路径（它们直接读桥接摘要而非经由列表合并）——否则同一任务会因查询工具不同而报告两种不同新旧度，且仅以 live 值键控的等待游标在只有 transcript 推进时不会变化。活动型全量目录响应与 live-only 会话列表因此在会话存活期间使用相同的有效新旧度。live 条目消失后，持久化 mtime 重新成为唯一权威，且可能比原 live 水印更旧——崩溃、降级写入、正常关闭后+1ms平局决胜或墙钟回拨都可能造成此现象，协议不制造持久化、不保留退役水印。

活动维度上的新移动模式与游标防护

现有游标路由不是快照隔离的：并发会话活动本就可以在调用方翻页时改变集合。填充 liveupdatedAt使这种移动在活动排序中可观测，但不引入更强的分页保证。

有一个新出现的移动模式值得注意：此前活动键的游标分量只来自 transcript mtime，只能前进；而 live 水印领先 mtime 时并非持久——live 条目在遍历中途退役，行的键回落到 mtime，那么以更高水印编码游标的页会再次接纳该行。live-only 行在遍历中途持久化同理。

因此活动游标要携带已按 live 派生键发射过的行身份，after-cursor 过滤器在本轮剩余过程中排除它们，保证 live 派生键移动的会话每轮至多返回一次。携带机制只覆盖机制见过的行：纯持久化行在 pin 状态变化前发射的不会被携带，未 pin 在两次拉取之间仍保留组织视图既有的重复模式；累积分页的调用方以sessionId键行。第三个活动键游标（live-only 列表）无需携带：首个水印推进以createdAt为下限，live 键永不移回，列表保持有界与自剪枝——缺失身份的保留（短 TTL 持久化快照或中途分组移动下的瞬态缺失），行存在且其持久化键在两种 pin 状态下都无法通过“严格更旧”过滤器的则丢弃；超过 64 身份上限后，持久化键最高（最接近离开重接纳窗口）的身份先被丢弃，被丢弃身份降级为至多一次的重复而非失败。字段存在前铸造的游标保持有效，字段为空时省略，因此未发射 live 派生键时游标形状不变。跨轮次保证不变：新轮次即新快照。

桥接层与路由实现：最小改动清单

服务端实现应做最小改动：

1. 给SessionEntry增加lastTurnEndedAtMs?: number；
2. 增加一个内部辅助函数单调推进该字段，首个推进以条目createdAt为下限；
3. 在publishPromptTerminal中，在广播前计算既有 running 状态门，且仅在重复闩锁成功后推进；
4. 从toSessionSummary把new Date(lastTurnEndedAtMs).toISOString()投影为已声明的BridgeSessionSummary.updatedAt；
5. 从工作区 live-state 路由投影该可选摘要字段；
6. 修改 live/persisted 合并选择逻辑，保留更晚的有效时间戳。

无需新增桥接方法——listWorkspaceSessions与getSessionSummary已返回BridgeSessionSummary，其公开类型已携带可选字段。实现横跨 ACP bridge、CLI serve 与 TypeScript SDK 三个包，属于小特性而非重构，但仓库策略要求跨包架构变更需维护者知晓；PR 的风险小节应完整列出下文的“下游消费者审计”。

live-state 路由继续坚持：解析选定工作区运行时（无主运行时回退）、按现有语义拒绝不受信任或不可用运行时、只读桥接版本与内存摘要、仅暴露新目录版本时使持久化目录缓存失效、不做任何会话存储/settings/外部命令/ACP 请求、返回Cache-Control: no-store。纯活动变化不得从 live-state 路由使持久化列表缓存失效——缓存快照包含持久化事实，请求时既有 live 合并会在目录被服务时套用当前内存时间戳。

下游消费者审计：可选的加性影响

填充既有BridgeSessionSummary.updatedAt字段的影响比投影路由本地值更广，但均为刻意的加性变化：

GET /session/:id/status直接返回桥接摘要，其updatedAt可能早于合并列表响应中选中的更晚持久化 mtime——各响应表面之间不保证相等。实现 PR 必须更新受影响公开摘要表面的 exact-object 测试，同时保留证明无关所有权与状态决策不开始依赖时间戳的测试。

TypeScript SDK 与能力声明

TypeScript SDK 的变更仅限于DaemonSessionLiveState上的可选字段（DaemonSessionSummary.updatedAt已存在）。SDK 传输保持类型化原生 REST 调用，不增加运行时 schema 转换，也不在每次轮询时做能力请求。

不新增、不修改任何能力：

workspace_session_live_state: { since: 'v1'; }

该能力继续只表示“端点存在”，不承诺每个 live 条目都有updatedAt——因为该值依赖生命周期。不新增 Java SDK 或 ACP 方法。

兼容性矩阵

响应 schema 保持v: 1。新 schema 版本会迫使客户端对一个原本加性的属性分支，且无法解决新代际首个终态前时间戳合理缺失的问题。

后续 Web Shell 消费契约

服务端 PR 不改变 Web Shell 行为，但协议为后续消费者设计了如下规则：

1. turnCompleted同时携带工作区 cwd 与 session id；
2. 客户端仅对已知到达 running 状态的 turn 记录每会话完成序列；纯排队终态无需新旧度对账；
3. live-state 请求在发起时快照待处理序列；
4. 只有“在序列记录之后发起”的请求响应才能满足该序列；
5. 匹配行上的有效updatedAt按服务端比较器修补新旧度并重排已加载的活动页；
6. 归档页永不接受 live 活动时间戳；
7. 时间戳缺失/非法或目标行不在已加载活动目录中时，保留既有版本围栏（version-fenced）、限速的目录回退。

序列是必需的：一个 live-state 请求在途时第二个 turn 可能完成，若只记 session id 集合，旧响应会清除更新的完成事件。无法区分“仅排队终态”的消费者可保守保留现有限速目录回退，但协议不要求为“未产生活动水印的事件”提供回退。客户端应保留目录与 live 时间戳中较晚者，仅当有效值变化时才重排；不得把未知 live 会话插入按 source/group/archive 过滤的页面——live-state 不携带证明成员资格的静态元数据。这使常见路径免扫描，同时保留旧服务端、分页边界与缺页会话的正确性。

失败语义

路由的 HTTP 失败语义完全不变。

高频路由不新增日志；既有路由延迟与请求计数遥测已足够。实现不得增加每终态成功日志——那会给普通生命周期路径带来高基数噪音。墙钟前跳是接受的桥接本地水印行为：向下校正会违反严格单调；条目存活期间，取更晚值的合并可能让未来水印领先正确持久化 mtime；条目移除或桥接替换终结该范围。

测试计划要点

桥接单元测试

• 新建或恢复的 live 条目在首个 running 终态前省略updatedAt；
• 成功 running 终态产生合法 ISO 时间戳；
• running 成功、结构化错误、传输错误、取消、deadline 各终态路径各推进一次；teardown 路径（会话 close、kill、channel 退出、daemon 关闭）经同一辅助函数推进，但在同一操作中移除 live 条目，故推进值无读取者、测试不断言；
• 排队移除/取消/deadline 不推进；
• deadline 路径发布两次终态（expiry 一次、竞态拒绝到达 settle 处理器一次）仍只推进一次；更晚到达的 agent 结果落在竞态 promise 落定之后，既不增加终态也不推进；
• 固定Date.now()下两个 running 终态产生严格递增值；
• 墙钟前跳后校正，水印永不下降；桥接本地值仅随条目或桥接替换重置；
• 心跳、attach/detach、交互等待、流式更新不改变值；
• 终态订阅者被同步通知时，摘要已含新时间戳；
• turn 活动不改变目录 generation 与 revision。

路由与所有权测试

• live-state 响应仅在桥接摘要提供时包含updatedAt；
• 既有五个必填 live-state 字段保持存在；
• v、catalogVersion、Cache-Control、selector、信任、运行时代际行为不变；
• 路由仍不做文件系统、settings、命令或 ACP 子进程工作；
• 主/次运行时测试证明时间戳只来自被选桥接。

全量列表与下游测试

• 比持久化 mtime 更新的 live 时间戳胜出并改变活动顺序；
• 比 live 终态值更新的持久化时间戳胜出，防止回归；
• 非法或缺失候选保留另一有效值；
• live-only 列表排序与游标键使用填充时间戳；
• 会话状态暴露可选字段且不改变无关状态值；
• Live Task 游标在 running 终态后变化、跨心跳保持稳定；
• Goals、所有者解析、准入测试保持不变或显式忽略新字段。

SDK 与兼容性测试

• 公开 daemon 导出包含可选字段；
• 既有 live-state 方法恰好执行一次原生 REST 请求、无能力探测；
• 无updatedAt的旧形状响应仍可赋值、可用；
• 精确请求 URL、超时、客户端身份、错误行为不变。

E2E 与故障注入

1. 启动真实 daemon 并创建会话；
2. prompt 终态前读 live-state，允许updatedAt缺失；
3. 完成一个 prompt，断言后续读取返回有效时间戳且catalogVersion不变；
4. 以最小延迟完成第二个 prompt，断言时间戳更大；
5. 发送心跳，断言时间戳不变；
6. 执行 running 取消或 deadline，断言推进一次；
7. 重启 daemon，断言目录 generation 变化且 live 时间戳在下一个终态前缺失；
8. 阻塞或放大持久化目录扫描，确认直接 live-state 延迟与其无关。

后续 Web Shell PR 增加请求计数 E2E 覆盖，证明已加载行上的重复 turn 不再产生额外全量目录请求。

验收标准

• 客户端观测到的 running prompt 终态事件，在同一 live 条目仍存在于同一桥接代际时，因果先于后续启动的 live-state 响应中的水印；
• 水印每个 running prompt 终态恰好推进一次，从不因仅排队终态或心跳推进；
• 同一墙钟毫秒内多个终态保持严格有序；
• turn 活动不改变目录 generation/revision，不使持久化列表缓存失效；
• 直接 live-state 工作与持久化会话数量、transcript 大小无关；
• 同会话 live 与持久化摘要合并时，在 live 条目存在期间使用更晚的有效活动时间，不把行向后移动；
• 既有状态、信任、运行时所有权、能力、错误契约保持不变；
• 旧客户端忽略该字段，字段缺失对新客户端仍合法。

发布与回滚

服务端字段是加性的，经正常 daemon 发布路径分发，无需特性开关。金丝雀遥测应对比：改动前后 live-state 延迟与错误率、普通 prompt 终态间的目录 revision 稳定性、live 会话列表或 Live Task 排序的意外变化。定向金丝雀冒烟测试单独验证“每个 running 终态一次独立时间戳推进”，直接读端点即可，无需新增每终态生产日志或指标。

协议 PR 单独不降低 Web Shell 目录请求量——该指标只在后续消费者上线后变化。回滚即普通服务端二进制回滚，无配置、数据或迁移状态。

被否决的备选方案（要点）

延伸阅读

• 上游协议基座：docs/design/2026-08-16-workspace-session-live-state.md（live-state 端点、目录版本时钟、客户端一致性握手）
• SDK 类型实现：packages/sdk-typescript/src/daemon/types.ts
• SDK 调用实现：packages/sdk-typescript/src/daemon/DaemonClient.ts
• 桥接层核心（publishPromptTerminal、BridgeSessionSummary）：packages/acp-bridge/src/bridge.ts、packages/acp-bridge/src/bridgeTypes.ts
• 相关设计上下文：docs/design/2026-08-16-workspace-session-live-state.md 与 docs/design/2026-08-18-workspace-session-live-state-updated-at.md

【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code