AtomCode TUI 布局架构决策复盘:入日志的运行时状态与单一 Op 词汇表(ADR 0007)
AtomCode TUI 布局架构决策复盘:入日志的运行时状态与单一 Op 词汇表(ADR 0007)
本文以 docs/adr/0007-tui-layout-is-logged-state-with-one-op-vocabulary.md 为主体,结合
atomcode-tui当前源码(layout.rs、rows.rs、host.rs)与相关 ADR 文档展开。需要先说明的是:这篇 ADR 已于 2026-09-17 被标记为作废——「可调布局」整体移除,但文章核心论证的「区域树保留、布局 op 词汇表、屏幕可见即已记录」等思想仍在当前代码中存活并延续。本文既还原这份架构决策的完整论证过程,也说明它今天的实际走向。
导读
本篇技术指南围绕 AtomCode TUI 的一个关键架构决策展开:屏幕布局为什么必须是「入日志的运行时状态」,而不是「挂载期的静态配置」或「运行时整棵树替换」。文章完整还原了三条布局入口(快捷键、菜单命令、自然语言)如何收敛到一个 LayoutOp 词汇表与唯一的 apply(op) 落点,解释了为何「屏幕可见即已记录」会迫使布局变更进入会话事件日志,并逐一剖析了四个被放弃的备选方案及其代价。读完本文,你将掌握 AtomCode TUI 布局系统的设计推理、LayoutOp 词汇表与 LayoutError 失败语义的实现细节,以及这项决策最终被 ADR 0022 第 8 节作废后,哪些遗产仍然活在今天的代码里。
一、背景:三条入口与「屏幕可见即已记录」
ADR 0007 要解决的问题很具体:布局必须在运行时可调整,而且存在三种入口:
- 快捷键(keymap 绑定);
- 菜单命令(斜杠命令);
- 自然语言(模型感知布局后,通过工具调整)。
如果不做统一决策,后果可以预判:三条入口各写一份布局编辑实现,然后慢慢分叉——快捷键能做的命令做不了,模型描述的和实际渲染的说两样。这本质上是「同一件事有两个家」的架构病:三个实现迟早会对同一份布局状态给出三种不同的说法。
与此同时,TUI 有一条硬性要求——「屏幕可见即已记录」:屏幕上有什么,必须能从会话日志重建。而布局决定屏幕上有什么,所以布局变更天然属于"必须被记录"的范畴。这两条约束合在一起,指向同一个结论:布局不能是散落各处的私有状态,它必须是一等公民、被记录、被校验、可撤销。
这一背景与 docs/adr/0006-tui-is-full-screen-not-inline.md 一脉相承:TUI 选择全屏(alternate screen)而非流式,正是因为全屏下应用持有整条流的渲染缓冲,「自然语言调布局」这个入口才不会被流式的满宽置顶结构直接判死。
二、核心决策:布局是入日志的运行时状态
ADR 0007 的决策可以拆成四句话:
- 布局是状态,由配置初始化;
- 变更是
LayoutOp,不是整棵树替换——op 可以被校验、撤销、记录、描述; - 三条入口只是翻译器,落点是同一个
apply(op) -> Result<(), LayoutError>; - 布局变更入会话日志,且对模型不可见。
2.1 布局从配置初始化
区域树(Region tree)是一份配置值,它决定面板画在哪。这一点在 crates/atomcode-tui/src/host.rs 的 default_layout() 中体现得很直接:默认布局从上到下依次是会话滚动区(conversation)、composer(输入区)、status 状态栏,用 Region::split 组合而成。变体的初始布局仍是配置值(比如 code-review 变体带 findings 面板、longcode 不带),运行时 op 叠在其上。
2.2 Op 词汇表:九个变体
原始设计定义了九个 op 变体:
pub enum LayoutOp {
Split { at: Target, dir: Dir, size: Constraint, with: ModuleId },
Close { at: Target },
Swap { a: Target, b: Target },
Resize { at: Target, size: Constraint },
Show { module: ModuleId }, // 放到它声明的默认位置
Hide { module: ModuleId },
Focus { at: Target },
Preset { name: String },
Undo,
}
选择 op 而非整棵树替换的理由有三条(详见第四章「放弃了什么」):整棵树替换无法表达 Undo、无法给出可执行的失败原因(只能说"这棵树非法")、模型要输出整棵树而不是一个意图时出错率高得多。op 的代价是集合封闭——新的布局操作要加变体。
2.3 当前代码中的词汇表:Show / Hide 存活
ADR 0007 作废后,可调布局的七个变体(Split / Close / Swap / Resize / Focus / Preset / Undo)被整体移除,但 Show 与 Hide 作为"渲染装配"词汇保留了下来,并且正是它们在驱动今天的屏幕拼装。见 crates/atomcode-tui/src/layout.rs:
/// A panel putting itself on screen, or taking itself off.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum LayoutOp {
/// Put a module on screen, on this side of everything else.
Show {
module: String,
side: Side,
/// Rows or columns. `None` asks for a sensible default.
size: Option<u16>,
},
/// Take a module off screen. Its state is untouched.
Hide { module: String },
}
Side 枚举(Top / Bottom / Left / Right,见 layout.rs)决定模块挂到屏幕哪一侧,size: Option<u16> 用单元格数给出面板高度/宽度,None 表示按内容自适应。layout.rs 的模块注释写得很清楚:
A panel row puts itself on screen when it mounts and takes itself off when it unmounts, through
LayoutOp::ShowandLayoutOp::Hide. That is rendering assembly, not a person or a model rearranging the screen — the adjustable layout … was taken out until it is thought through (docs/adr/0022§8;docs/adr/0007is void).
也就是说:面板挂载时用 Show 把自己放上屏,卸载时用 Hide 把自己撤下屏——这是渲染装配,不是人或模型在调布局。这正是 ADR 0007 论证中"op 词汇表"思想在当前代码中存活的形态。
2.4 apply 的实现与失败语义
layout.rs 中的 Layout::apply 是当前词汇表的落点,它的 doc 注释直接继承了 ADR 0007 的失败约束:
Apply one op. Never panics, never leaves an invalid tree, and never silently does nothing — a refusal always says why.
其行为要点:
Show前先校验模块名是否在known列表里(不在则返回NoSuchModule,并列出可用模块),再检查是否已在屏上(已显示则返回AlreadyOnScreen,拒绝重复绘制);Hide检查模块是否在屏上(不在则返回NotOnScreen),然后通过current.prune(...)从区域树中剪掉;- 最终还要对将要安装的树做
named_twice检查——同一模块被两个位置命名会画出两遍,返回NamedTwice错误。
对应的错误类型定义在 layout.rs:
pub enum LayoutError {
NoSuchModule {
name: String,
available: Vec<String>,
},
NotOnScreen(String),
AlreadyOnScreen(String),
NamedTwice(String),
}
值得注意的设计细节:错误校验在"将要安装的树"上做、而不是在 op 上做——因为默认布局也是树的另一个来源,树的非法性是树本身的属性。NoSuchModule 携带 available 列表,正是 ADR 0007 要求的"失败必须带模型能用的原因(NoSuchModule 列出可用模块名等),不许 panic,不许静默无效"。
2.5 布局引擎必过的四条性质
docs/tui-composability.md §二 把布局引擎的验收标准浓缩成四条,每条都对应 ADR 0007 的决策动机:
| # | 性质 | 为什么 |
|---|---|---|
| 1 | 全函数:任意 op × 任意布局 → 合法布局或带原因的拒绝,永不 panic、永不产出非法树 | 模型会发垃圾 |
| 2 | 可逆:apply(op); undo() 回到逐字节相同的帧 |
Undo 是入口之一 |
| 3 | 不触碰模块状态:state_after == state_before、stream_after == stream_before |
空间变换与时间流正交——把 findings 从左挪到右,不许清空它 |
| 4 | 模块缺席可降级:布局引用未挂载的模块 → 该区收缩,不 panic | code-review 的布局在 longcode 下也要能用 |
其中第 3 条是两条约束交汇处的关键:它把「空间随意变换」与「时间不可逆」的正交性变成一条可断言的等式。今天的 layout.rs 测试 a_layout_change_never_touches_what_a_module_has_folded 正是这条性质的直接验证:对模块做 Hide 再 Show,模块的折叠状态逐字节不变。
三、三条入口,一个词汇表
ADR 0007 的关键论证是**「三条入口只是翻译器」**:它们必须产出同一个值,否则就是三份布局编辑实现:
快捷键 Keymap binding ──┐
菜单命令 /layout split right findings ─┼──> LayoutOp ──> apply()
自然语言 模型调 adjust_layout 工具 ──┘
由此带来的测试收益很实际:需要重测的只有 apply 的性质;三条入口各自只需一个薄翻译测试,外加一条防分叉闸门——同一个意图分别走键位 / 命令 / 工具,产出的 op 必须相等。对应在 tui-composability.md §五「布局」判据中:
prop apply 全函数:任意 op 序列,永不 panic,树永远合法
prop 可逆:∀ op. undo(apply(op)) == 原帧(逐字节)
prop 正交:∀ op. 模块的 State 与 Stream 逐字段不变
test 同一意图分别走 键位 / 命令 / 工具 → 三个 op 相等 ← 防三份实现分叉
test 布局引用未挂载的模块 → 该区收缩,其余逐字节不变
3.1 模型那条路:不新建机制
对模型入口,ADR 0007 定下一条铁律:不新建机制。感知与动作分别复用两个现成通道,且都由同一行提供、从同一份状态导出:
- 感知 = 布局行往
PromptRegistry贡献一个片段,每次请求现读,所以模型看到的永远是当前布局,不可能漂移:
## 屏幕布局
当前: transcript(流区) │ findings(视图 30%)
status(1 行) / input(3 行)
可用但未显示: usage、todo、diff
用 adjust_layout 调整。「把 findings 收起来」= Hide{module:"findings"}。
- 动作 = 往
ToolsSvc注册adjust_layout工具,风险Safe(不改任何持久物且可 Undo),不走审批。
两件事由同一行提供、从同一份布局状态导出,因此描述与渲染不可能说两样——这正是"模型描述的和实际渲染的说两样"这个原始风险的结构性解法。
四、布局变更必须入日志
「屏幕可见即已记录」把布局变更直接推进了会话日志:布局决定屏幕上有什么,不记录则恢复会话时看到的屏幕与之前不同——时间可组合性破了。
ADR 0007 定下的日志形态是:
SessionEvent::LayoutChanged { op: LayoutOp }
// is_model_visible() == false —— 与 Notice 同类:给屏幕看的事实,不给模型看
这条约束在 docs/tui-composability.md §二 中被称为"白送的四件事":
- 恢复会话自动还原布局;
- Undo = 重放到第 N 条,不需要单独的撤销栈;
- 场景构造器能构造任意布局状态;
- 连续
Resize同一目标由 fold 合并,不会撑爆日志。
is_model_visible() == false 的含义是:这类事实给屏幕看、不给模型看,与 Notice 同类。这与 AtomCode 会话日志的整体模型一致——crates/atomcode-harness/src/session.rs 中 Notice 事件(CompactionDegraded 等)就是同类先例:人需要知道发生了什么,模型不需要再收到一份关于界面的事实的描述。这也呼应了 docs/adr/0024-the-session-log-is-the-authority.md 确立的「会话日志是权威」原则:一切屏幕状态都以日志为唯一事实源。
五、放弃了什么:四个备选方案及其代价
ADR 0007 用一整章记录被放弃的方案——按这份文档的写作传统,只写选了什么的记录拦不住下一个人重走弯路,所以放弃项必须连同代价一起写清楚。
5.1 布局作为挂载期配置(不可运行时改)
最简单,而且和其它行一致。放弃是因为需求明确要求运行时可调。代价:布局成了状态,多一处需要持久化与恢复。
5.2 整棵树替换而非 op
接口更小(set_layout(tree))。放弃有三个理由:
- 无法表达 Undo(要另建撤销栈);
- 无法给出可执行的失败原因(只能说"这棵树非法");
- 模型要输出整棵树而不是一个意图——出错率高得多。
代价:op 的集合是封闭的,新的布局操作要加变体。
5.3 布局变更不入日志(单独偏好文件或内存)
日志更干净。放弃是因为恢复会话时屏幕会和之前不一样——时间可组合性破了。入日志白送的三件事(Undo 即重放、场景构造、连续 Resize 由 fold 合并)上一章已述。代价:日志里多一类非模型可见的事实。
5.4 给模型另建一套布局描述通道(不复用 PromptRegistry / ToolsSvc)
可以做得更精确。放弃是因为那会是第二个家,与渲染用的状态必然分叉——这正中"三条入口分叉"这一原始问题的下怀。
六、失效条件:什么时候要重新评估
ADR 0007 列出了三条失效条件,作为「定期复核,防止仪式活得比它的用途长」的依据:
- 若
LayoutOp的变体数量增长到难以让模型可靠选择——「一个封闭 op 集合」需要重新评估(可能要退回受限的树描述); - 若布局变更的频率高到污染日志(fold 合并不足以吸收)——「入日志」需要重新权衡;
- 若出现需要跨会话共享/同步布局的需求——会话日志不是正确的家。
第一条失效条件后来真的发生了:在 ADR 0022 的重新评估中,LayoutOp 全套词汇表连同 adjust_layout 工具、tui-layout 提示词片段一起被移除,见下文。
七、历史走向:ADR 0007 作废,区域树保留
这是阅读本文必须知道的结局。2026-09-17,docs/adr/0022-tui-and-agent-in-separate-apps.md 第 8 节「可调布局整体去掉,等想清楚再说」把可调布局的三层拆开处理:
屏幕布局分三层:① 给模型的——系统提示里的布局描述与
adjust_layout工具;② 给人的——tui-commands-layout行的/layout、/show、/hide、/undo-layout、/layout-set,键ctrl-f(专注预设)、ctrl-z(撤销布局)、ctrl-n与/mascot;③ 渲染本身——区域树决定面板画在哪。
- 去掉 ① 与 ②(含
ctrl-n与/mascot)。ADR 0007 作废。吉祥物显不显示只由--mascot决定——它打开的是tui-panel-mascot这一行,不经布局操作。- ③ 保留。 面板行挂载时自己用
LayoutOp::Show/Hide把自己放上 / 撤下屏幕——这是渲染装配,不是人或模型调布局。
作废的理由记录在 0022 中:"等想清楚再说"——即调整布局这一需求的实现代价(提示词每请求现读、工具通道、命令集、键位、布局操作日志)在当时不值得继续投入,但渲染用的区域树保留,因为它与"可调布局"是两个正交的东西。
这一转向被测试固化下来了。crates/atomcode-tui/tests/guards.rs 的 the_adjustable_layout_is_gone 直接扫描源码,断言 adjust_layout、LayoutOp::Undo、LayoutOp::Preset、tui-commands-layout、describe_for_model 这些词不再出现;同文件 guards.rs 的 no_key_rearranges_the_screen 则断言 ctrl-f 未绑定、ctrl-z 只绑定为 Suspend、ctrl-n 只绑定为历史前进——从键位层面保证"没有任何键能重排屏幕"。
八、今天的实现形态:面板行与布局服务
ADR 0007 作废后,它的词汇表思想通过 crates/atomcode-tui/src/rows.rs 的"每个面板一行"架构延续下来(详见 docs/adr/0010-every-panel-is-a-row.md):
rows.rs的SCREEN常量(rows.rs)用[[insert]]声明整块屏幕由哪些行组成:tui-panel-transcript、tui-panel-status、tui-panel-live、tui-panel-input、tui-panel-todo等,默认开启;tui-panel-mascot、tui-panel-team、tui-panel-raster默认disabled = true,按需开启;MascotPanel(rows.rs)是"行自己用LayoutOp::Show上屏"的样板:挂载时mods.add_view然后layout.apply(LayoutOp::Show { module, side: Side::Top, size: Some(1) }),卸载时在ctx.effect里apply(LayoutOp::Hide { module })再remove_view;TeamPanel(rows.rs)以Side::Bottom、size: None上屏——底部面板按内容自适应高度,随成员增删长高收缩;LayoutSvc作为 Core 服务暴露(plugin.rs),host.rs的Host持有它并在启动时注入(plugin.rs)。
端到端测试也印证了这一形态,crates/atomcode-tui/tests/e2e.rs 的注释写明:"the row put itself on screen, through the same LayoutOp everything else uses"。
九、总结:这份 ADR 留下的架构遗产
ADR 0007 虽然在 2026-09-17 作废,但它论证并固化了四条至今仍在 AtomCode TUI 中生效的原则:
- 布局是数据,不是代码:区域树是可组合的配置值(
Split / Stack / Leaf),由 host.rs 的default_layout()初始化; - Op 词汇表优于整树替换:即使可调布局被移除,
Show / Hide两个 op 仍是面板上屏/下屏的唯一通道,所有面板行共用同一个apply与同一套LayoutError语义(不 panic、不静默、拒绝必带原因); - 屏幕可见即已记录:布局属于"给屏幕看的事实"(
is_model_visible() == false),与Notice同类,会话日志是屏幕状态的权威来源; - 描述与渲染必须同源:宁可去掉一个入口,也不允许"模型描述的"与"实际渲染的"出现两个家——0022 第 8 节正是这一原则的最终执行。
对于想深入源码的读者,建议按此顺序阅读:layout.rs(op 与错误语义)→ rows.rs(面板行如何用 op 上屏)→ host.rs(默认区域树)→ guards.rs("可调布局已消失"的守卫测试),再回到 docs/tui-composability.md §二 补全完整的空间可组合性论证。