TRANSCRIPT_PROJECTION.zh-CN.md - DeepSeek-Reasonix

TRANSCRIPT_PROJECTION.zh-CN.md

1	# 会话显示投影
2
3	[English](TRANSCRIPT_PROJECTION.md)
4
5	本地 Desktop 与当前 Serve 共享 `internal/transcript`。控制器先持久化事件，
6	再提交显示投影，最后在提交锁外发布事件。规划器、执行器、交互提示和终态都经过
7	这个边界。模型请求仍只使用规范历史，显示记录不会回流到模型上下文。
8
9	Desktop 使用 Electron 宿主契约。新增方法与所有权元数据一起生成，生成的 DTO
10	名称不能遮蔽契约使用的 TypeScript 内置辅助类型。
11
12	## 身份与恢复
13
14	控制器在规划开始前分配用户消息 ID。前端在正式记录安装前，将本地发送回显独立于
15	持久 transcript 管理：`submissionId` 关联一次发送，`messageId` 标识正式消息，
16	展示 key 只负责在交接时保持已挂载的 DOM 节点。正式用户记录始终使用
17	`m:<messageId>`；历史增删、正文查询和持久化不得使用展示 key。正文相同不代表
18	同一条记录。每次采样在首个片段前分配助手消息 ID，成功保存时沿用该 ID；丢弃采样
19	只移除它拥有的记录。工具卡使用 tool call ID。
20
21	本地提交的交接独立于当前历史窗口。Follower 在窗口过滤前提取正式用户身份，
22	与可见投影通过同一个 reducer action 提交。窗口外的正式记录可以结算回显，
23	但不向读者所在旧页插入条目，也不触发跟随到底部。已绑定回显优先按 messageId
24	匹配；仅未绑定回显允许按 submissionId 匹配。冲突绑定和不同正式消息不得合并。
25
26	同一事务为最终窗口内的正式用户记录写入 `visibleSubmissionHandoffs`。
27	即使 React 跳过中间的身份绑定渲染，ChatSource 也能继承此前实际展示的回显 key，
28	用户行、过程区和尾部共用稳定的轮次 key。交接提示随正式消息离开窗口而清理，
29	展示映射随分组退出而清理；更换会话时不保留，回收后重载也不恢复旧回显。
30	发送锚点缺失时，只能依据原发送边界或明确轮次身份定位，不能插到无关历史之前。
31
32	迟到的 messageId 绑定先与驻留记录结算。正式消息已经不在窗口时，所属 follower
33	可以复用已有的按消息查询接口确认身份，但不安装该历史页。查询受 generation
34	约束，按未结算提交合并在途请求，只在正式覆盖推进或重连后重试；无法确认时保留
35	回显。身份事件本身不会发起查询：必须先有正式覆盖范围超过该提交首次被观察时的
36	水位；水位记录随提交结算清理。同步引擎在首次跟随时按需加载，加载期间停止会取消启动。
37	RPC 接受、失败和未知结果属于本地提交，运行态另由请求归属控制。
38	只有显式新发送才增加滚动使用的提交 revision。
39	同一正式会话 ID 的恢复快照保留未结算回显；快照所属会话改变时清理回显与交接映射，
40	并推进会话 generation。远程回调始终读取所属标签的状态，不能沿用上一个标签的渲染状态。
41
42	历史窗口和正文读取按需加载，在异步模块加载前捕获路由身份，Store 的 generation
43	检查继续丢弃失效结果。首屏代码保持在原有包体预算内。
44
45	`bench/submission-handoff.mjs` 用 1,000 轮确定性历史和 20 次往返分页，验证真实
46	follower、有界 Store、reducer、Composer 与 Transcript；增加 `--electron` 可在
47	隔离的 Electron 宿主执行。JSON 记录节点连续性、浏览器原生选择、阅读位置偏移、
48	滚动写入、驻留条目和展示映射数量。Linux CI 的 `--electron --native-input`
49	模式在隔离 Xvfb 中通过 `xdotool` 的 X11 XTest 输入测试滚轮、键盘和原生滚动条，
50	记录滚动范围、空白帧及确认时的阅读位置。该模式只能在隔离图形会话中运行。
51	Electron 脚本输入不能充当操作系统原生输入
52	验收，报告分别记录这两类证据。
53
54	终态检查点保存在会话的 `.transcript-projection.json` 旁文件中，记录规范历史的
55	前缀条数与摘要、会话头和重写身份、显示记录、运行态及已覆盖事件序号。写入失败时
56	保留 WAL 投影确认，恢复时安装匹配的检查点，再回放保留的后缀，不执行工具。
57	自动保存的进行中尾部不会先作为基线安装、随后又被事件追加一次。
58	旧显示文件仍可迁移，只有旧格式迁移允许使用原有的用户正文哈希和出现次数映射。
59
60	终态记录保留协议恢复令牌、读取未完成与验收缺口、已接受的部分读取回执，以及取消
61	和失败诊断。开始新回合后旧恢复动作失效。捕获检查点时只复制可变元数据，共享不可变
62	正文字符串；写盘所需的编码在投影锁外完成。
63
64	## 快照协议
65
66	Desktop 提供 `TranscriptSnapshotForTab`、`TranscriptPageForTab`、
67	`TranscriptContentForTab` 和 `TranscriptReplayForTab`。Serve 在现有认证和
68	主机检查下提供对应的 GET `/transcript/snapshot`、`/transcript/page`、
69	`/transcript/content`、`/transcript/replay`。
70
71	`ResumeTranscriptSessionForTab` 和 `OpenChannelTranscriptSessionForTab` 在绑定后
72	返回切换阶段诊断，不生成旧历史页。前端只在对应快照提交后记录这些数据，并单独统计
73	快照安装耗时。旧宿主不返回诊断时，`duplicateLoadCount` 为 `null`（未知），不能
74	将缺失测量当作零次重复读取。旧分页调用只有在预载摘要与控制器捕获的历史一致时才复用；
75	运行时已完成并保存了更新内容时，会重新读取持久化历史。
76
77	快照携带协议版本、快照 ID、会话／会话头／重写代次／运行时代次、投影修订号、
78	已覆盖事件序号、显示记录、活动记录及待处理提示。分页和正文请求绑定同一个
79	快照 ID；回放绑定完整身份和最后提交的序号。快照被回收时返回 `stale`，身份或
80	保留范围不匹配时要求重新安装快照。异步读取结束后还会复查标签页及远程连接代次。
81
82	前端在发起读取前暂停有序事件入口。活动记录引用的完整前缀解析后，一次 reducer
83	事务安装显示、运行态和采样状态，再推进覆盖序号。实时队列与回放使用同一提交入口。
84	状态轮询只提示事件缺口及后台任务数，不能另行替换显示或运行态前缀。
85
86	旧分页按记录身份和后端顺序合并，保留位于最新页之前的活动用户消息。正文延迟返回
87	时复查快照及其间发生的修改；旧分页不能重新引入已丢弃的采样记录。
88
89	正文解析只使用正式消息身份。展示层可以在本地回显交接为正式消息时沿用展示 key，
90	但不能用它替换条目的 `m:<messageId>` 身份。延迟补丁只更新当前仍存在的正式条目，
91	替换预览前检查期间修改；已被分页回收的条目不能被迟到补丁重新创建。
92
93	## 大小边界与旧版兼容
94
95	默认每页 120 条记录、512 KiB，响应上限 2 MiB。大字符串使用 4 KiB 预览和按
96	UTF-8 边界切分的 64 KiB 正文块；读取块时直接访问字段，不序列化整个工具载荷。
97	完整回放响应也受同一 2 MiB 上限约束，包含 JSON 转义和信封开销。超限时要求新快照，
98	正文继续通过分块读取，不能推进客户端尚未收到的事件序号。
99	服务端最多保留三个快照，估算缓存预算为 64 MiB。当前快照固定保留，超大会话会
100	回收旧快照而不是拒绝读取；已完成的字符串共享存储，元数据与活动前缀保持不可变。
101
102	客户端只缓存尚未展开的预览，展开完成后释放该记录缓存。活动及运行中的标签页固定
103	保留；非活动缓存限制为三个标签页、32 MiB。实时缺口队列限制为 1,024 个事件和
104	8 MiB，溢出保留最高接收序号，由 WAL 回补。
105
106	旧 Serve 的端点或协议不支持、或返回旧 HTML 首页时，继续使用旧路径，并在界面
107	明确提示同步受限、重连可能缺失或重复内容。能力探测不会升级或重启 Serve。
108	现代路径仅获取附属元数据，不再同时下载旧版完整 `/history`。
109
110	## 验证
111
112	根模块测试覆盖采样身份、检查点落盘失败、自动保存恢复、不可变快照、嵌套正文引用、
113	超大会话及 HTTP 会话绑定。Desktop 测试覆盖规划阶段取消、旧 Serve 探测、远程
114	迟到响应及纯元数据读取。前端通过真实 reducer 验证前后缀交错、乐观气泡键、分页
115	顺序、工具配对、丢弃记录及过期正文写入。
116
117	根模块和 Desktop Go 测试须分别运行。前端运行 `test:typecheck`、
118	`test:transcript`、`test:remote`、`test:stream` 和生产构建。浏览器会话与
119	App 内存检查、原生 Electron 回放是独立验收项；单元测试或交叉编译
120	不能替代原生证据。
121

121 lines MARKDOWN