Skip to content

feat(terminal): 添加静态快照与本地输出存储基础 - #235

Merged
Kuddev merged 38 commits into
Kuddev:review/static-output-snapshots-1119from
galact-byte:feat/recent-output-restore
Nov 20, 2026
Merged

Kuddev merged 38 commits into
Kuddev:review/static-output-snapshots-1119from
galact-byte:feat/recent-output-restore

Conversation

@galact-byte

@galact-byte galact-byte commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

本次复审

当前差异以 #1041 的静态网格快照为基础,保留应用侧最近命令输出和本地归档实现。当前提交在读取时限制窗格和命令记录数,拒绝重复窗格引用和嵌套交接代次。窗口采集和会话接入由 #308、#309 跟进,#160 保持打开。

Linux CI 在此版本执行了 3,752 项测试,全部通过,另有 42 项跳过。发布时并发清除、旧引用交接及逐项解码回归均通过。Linux 运行

用户结果

为 #160 提供主屏静态快照与有界输出存储基础。后续 #308 接入窗格采集和本机会话引用,#309 接入设置与窗口保存、恢复,按 #235 → #308 → #309 合入。本项不关闭 #160。

设计边界

  • nebula_terminal 负责快照及序列化。解码时逐行、逐单元格计数,超出行、单元格或组合字符预算即停止,不先建完整对象再校验;JSON 字段顺序无关。捕获与导入共用宽字符标志规范化,孤立或互斥的标志被清除,行首孤立占位不会进入文本提取。静态恢复不执行命令,活终端不变。
  • recent_output 复用原子写入,按真实落盘结果确认发布,并保留交接数据。同一存储的发布与清除共用写锁串行执行;发布期间排队的清除会在其后执行,旧输出不会复活。关闭保存时的串行收尾在 feat(session): 接入最近命令输出的保存、清除与启动恢复 #309。
  • 本机会话引用与主屏捕获接口随实际使用它们的 feat(terminal): 添加逐窗格命令输出采集与本机会话映射 #308 交付。
  • 无新增依赖。设计依据:architecture/notes/nebula_app/recent_output/2026-09-21-bounded-local-output.md、
    architecture/notes/nebula_terminal/grid/2026-09-28-bounded-display-snapshot-decoding.md。

基线 8087306:7 个源码文件及 2 份设计说明,门禁计入 1499 行;123 行 Markdown 按既有规则排除。

验证依据

  • Windows 本地测试通过:终端 352 项及 1 项文档测试(cargo test --offline --locked -p nebula_terminal --features serde,含 ConPTY 生命周期);应用存储、会话与启动恢复 128 项(gpui-test-support 测试程序分组运行)。
  • 新增的解码预算与孤立宽字符测试在原解码器上失败,修正后通过;真实解析器覆盖中文半字符删除、插入、擦除后在多种列宽下重排的正常快照不被改动。
  • 正常 gpui-shell 构建、cargo fmt --all -- --check、python scripts/check_architecture.py --base 8087306 及差
    异检查通过。

跨平台 CI 状态见 Checks;未做 Linux/macOS 实机交互验收。本项无 UI 改动,尚未接入实时输入和绘制路径。

必须确认

  • 遵循 CONTRIBUTING.md、架构文档和项目约束。
  • 按职责划分范围,没有按行数机械拆文件或新增重复行为实现。
  • 架构检查通过,没有抬高预算。
  • 测试覆盖成功及失败路径,平台验证限制已说明。
  • 无新增 UI 文案,国际化条目不适用。
  • 无治理规则修改,治理变更审查条目不适用。

@galact-byte
galact-byte requested a review from Kuddev as a code owner September 21, 2026 05:39
galact-byte added a commit to galact-byte/pebrel that referenced this pull request Sep 21, 2026
galact-byte added a commit to galact-byte/pebrel that referenced this pull request Sep 23, 2026
@galact-byte

Copy link
Copy Markdown
Contributor Author

这些改动主要围绕 #160 的同一条功能链:按 pane 采集有界的命令与输出、保存到本地,并在恢复会话时显示。改动还包含设置入口和相应的回归测试。如果仅按代码文件或模块拆分,拆出的 PR 会相互依赖,单独看也无法验证完整的恢复行为。不好拆开

@Kuddev Kuddev left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

感谢这份实现。已按 head 02caa35614b1dce01c1396ce106c5ea7f38e7121 分别审核命令捕获/静态恢复和持久化/退出生命周期。静态显示而非 VT 回放、精确 pane 引用、容量限制、sidecar 先于 session 发布的总体方向合理。

当前需要修改的事项:

  1. [P2] 关闭保存与会话发布之间的取消竞态。 具体代码与复现见 inline review。代次在 publish() 中途失效时,返回 Ok(false) 不等于磁盘提交被撤销;当前关闭设置路径也没有排队一个等待完成的持久化收尾,留下被取消的新引用/输出,直到另一次成功保存才能修正。这里讨论的是关闭时在途的新快照,不是要求“关闭开关必须删除此前所有合法历史”;后者与单独的清除按钮是不同产品语义。

  2. pr-size 必需门禁实际失败。 job 107540763104 日志为 counted 3801 lines (78 ignored) in 45 files -> size/XL,上限 1500。请按行为/生命周期边界组织可独立审核、各自可运行验证的提交 PR;保留相应测试及完整功能,不通过删测试、压缩格式、改预算或机械拆文件过门禁。

  3. 最新 main 已产生内容冲突。 GitHub 报告 dirty,本地 merge-tree 确认 workspace.rs 和 workspace/closing.rs 冲突。整合时保留最新窗口关闭/保存语义,并重新核验文档在等待保存期间被编辑的保护。

验证边界:本轮对原始存储代码做了定点取消复现;并审阅现有测试/CI。PR note 已明确 1948 个应用测试来自叠加了另一补全修复的组合,不将其写成此独立 head 的全量本地通过结果。#160 保持打开。

@Kuddev

Kuddev commented Sep 26, 2026

Copy link
Copy Markdown
Owner

本轮维护范围限定为已有功能的 Bug 修复。#235 新增每窗格命令输出持久化、存储格式与设置入口,属于功能 PR,因此单独保留,不纳入本轮修复合并,也不把标题改成 fix 来改变性质。此前关于取消竞态、PR 规模和整合冲突的审核要求仍保留;#160 保持打开。

@galact-byte galact-byte changed the title feat(terminal): restore bounded recent command output per pane feat(terminal): 添加静态快照与本地输出存储基础 Sep 26, 2026
@galact-byte

Copy link
Copy Markdown
Contributor Author

感谢这份实现。已按 head 02caa35614b1dce01c1396ce106c5ea7f38e7121 分别审核命令捕获/静态恢复和持久化/退出生命周期。静态显示而非 VT 回放、精确 pane 引用、容量限制、sidecar 先于 session 发布的总体方向合理。

当前需要修改的事项:

  1. [P2] 关闭保存与会话发布之间的取消竞态。 具体代码与复现见 inline review。代次在 publish() 中途失效时,返回 Ok(false) 不等于磁盘提交被撤销;当前关闭设置路径也没有排队一个等待完成的持久化收尾,留下被取消的新引用/输出,直到另一次成功保存才能修正。这里讨论的是关闭时在途的新快照,不是要求“关闭开关必须删除此前所有合法历史”;后者与单独的清除按钮是不同产品语义。
  2. pr-size 必需门禁实际失败。 job 107540763104 日志为 counted 3801 lines (78 ignored) in 45 files -> size/XL,上限 1500。请按行为/生命周期边界组织可独立审核、各自可运行验证的提交 PR;保留相应测试及完整功能,不通过删测试、压缩格式、改预算或机械拆文件过门禁。
  3. 最新 main 已产生内容冲突。 GitHub 报告 dirty,本地 merge-tree 确认 workspace.rs 和 workspace/closing.rs 冲突。整合时保留最新窗口关闭/保存语义,并重新核验文档在等待保存期间被编辑的保护。

验证边界:本轮对原始存储代码做了定点取消复现;并审阅现有测试/CI。PR note 已明确 1948 个应用测试来自叠加了另一补全修复的组合,不将其写成此独立 head 的全量本地通过结果。#160 保持打开。

重新梳理后,已按职责拆为三项,并处理了审查中指出的问题:

  1. 本 PR 收窄为静态快照、输出存储和本机会话引用格式,当前计入 1480 行,pr-size 已通过。窗格采集放在 feat(terminal): 添加逐窗格命令输出采集与本机会话映射 #308,设置与窗口保存恢复放在 feat(session): 接入最近命令输出的保存、清除与启动恢复 #309。后两项暂为 Draft,仍包含前置代码、规模尚未达标,将按 feat(terminal): 添加静态快照与本地输出存储基础 #235 → feat(terminal): 添加逐窗格命令输出采集与本机会话映射 #308 → feat(session): 接入最近命令输出的保存、清除与启动恢复 #309 的顺序,在前项合入后同步并重新验证。

  2. 已补充 publish 内部失效的确定性回归。本 PR 修正存储层的真实提交结果及交接数据保护;feat(session): 接入最近命令输出的保存、清除与启动恢复 #309 补齐关闭保存时同一队列中的持久化收尾。完整修复需要两部分配合,关闭开关仍不等同于清除既有历史。

  3. 已整合当前 main(7b0cedb),本 PR 的冲突已消除。等待保存期间新增文档编辑的保护保留在 feat(session): 接入最近命令输出的保存、清除与启动恢复 #309,普通关闭和 Runtime关闭的回归均已通过。

本 PR 的 Windows 本地 482 项测试及正常产品构建通过,各阶段验证范围已分别写入正文。

Count rows, cells and per-cell combining characters while decoding and stop as soon as a budget is exceeded; charge the shared combining budget per cell. Capture and import share one wide-char flag normalization so an orphan leading spacer can no longer reach text extraction. Add a barrier test showing a clear queued during publication runs after it and keeps the output cleared. Local session references and primary-screen capture move to the pane-capture stage that uses them.
@galact-byte

Copy link
Copy Markdown
Contributor Author

已按 Copilot 在 c1827da 上的 4 条意见处理,新提交 0c97754:

1. WireSnapshot::deserialize 先分配后校验(serialization.rs)
已修。解码时逐行、逐单元格计数,行数、单元格数、单格组合字符超出预算即停止,不再先建完整对象再 validate;累计组合字符在每个单元格读完时扣减。JSON 字段顺序无关性保持不变。测试
decoding_stops_at_budget_before_reading_malformed_tail 用超限元素后接畸形尾部,在原解码器上失败,修正后通过。

2. 宽字符标志缺少结构校验(snapshot.rs)
已修。捕获与导入共用同一规范化:清除互斥标志、未配对的宽字符/占位和位置错误的跨行前导占位,行首孤立占位不会再进入 line_to_string()。没有选择严格拒绝,因为终端删除半个中文字符后的正常重排也会留下孤立标志,拒绝会导致正常输出无法恢复。测试 strips_orphan_wide_flags_from_files_and_edited_screens 覆盖畸形输入,以及真实解析器下中文半字符删除、插入 、擦除后多种列宽的重排。

3、4. 代次检查与 publish() 之间的竞态(lifecycle.rs:108 / :137)
这个时间窗口确实存在,但不会产生“旧发布覆盖较新结果”的后果,所以没有改生产协议:

  • 同一个 OutputStore 的两个发布入口和 clear 共用 writer 锁串行执行。检查通过后才失效的发布会完整落盘,并如实返回
    true;之后排队的较新发布或 clear 在它之后执行,最终留下的是较新状态。
  • next_generation() 刻意不等待 writer,避免 UI 线程阻塞在磁盘 I/O 上。
  • 新增线程屏障测试 clear_queued_during_publication_runs_after_it_and_stays_cleared:在发布回调内部失效并排队
    clear,确认结束后输出被清除、不会复活。
  • 关闭保存开关时的串行无引用收尾由 feat(session): 接入最近命令输出的保存、清除与启动恢复 #309 负责。

本地验证:终端 352 项 + 1 项文档测试,应用存储/会话/启动恢复 128 项,正常 gpui-shell 构建、格式与架构检查通过。

@galact-byte
galact-byte force-pushed the feat/recent-output-restore branch from 61371fa to 4e2563e Compare October 2, 2026 14:11
@galact-byte
galact-byte requested a review from Kuddev October 3, 2026 08:32
Kuddev added a commit to galact-byte/pebrel that referenced this pull request Nov 19, 2026
Extract the terminal grid implementation and its tests contributed by galact-byte. The application archive and its publication lifecycle remain in their own change.
@Kuddev
Kuddev changed the base branch from main to review/static-output-snapshots-1119 November 19, 2026 07:22

@Kuddev Kuddev left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

已复审 c2548eb 对 #1041 的应用侧差异。读取阶段按窗格和记录预算逐项校验,归档的两代交接仅允许一层。存储在发布回调成功后记录已提交结果,并在同一写锁之后执行排队的清除;开关的收尾由接入层负责。当前范围解决了上次评审中的存储竞态和规模问题。Linux 原生 CI 实际通过 3,752 项,42 项跳过,其中包含逐项解码、发布期间清除和旧引用交接回归。其他必需检查仍须通过后才能合并。

@Kuddev
Kuddev merged commit e164130 into Kuddev:review/static-output-snapshots-1119 Nov 20, 2026
16 of 17 checks passed
@galact-byte
galact-byte deleted the feat/recent-output-restore branch November 20, 2026 06:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants