AtomCode TUI 布局架构决策复盘:入日志的运行时状态与单一 Op 词汇表(ADR 0007)

原创2026-10-14 18:17:391,950 阅读
文章标签:代码智能体AI Agent人工智能大模型CLIMCP Clients工具调用开发工具Agent 工作流

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 要解决的问题很具体:布局必须在运行时可调整,而且存在三种入口:

  1. 快捷键(keymap 绑定);
  2. 菜单命令(斜杠命令);
  3. 自然语言(模型感知布局后,通过工具调整)。

如果不做统一决策,后果可以预判:三条入口各写一份布局编辑实现,然后慢慢分叉——快捷键能做的命令做不了,模型描述的和实际渲染的说两样。这本质上是「同一件事有两个家」的架构病:三个实现迟早会对同一份布局状态给出三种不同的说法。

与此同时,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::Show and LayoutOp::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/0007 is 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 §二 中被称为"白送的四件事":

  1. 恢复会话自动还原布局;
  2. Undo = 重放到第 N 条,不需要单独的撤销栈;
  3. 场景构造器能构造任意布局状态;
  4. 连续 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 列出了三条失效条件,作为「定期复核,防止仪式活得比它的用途长」的依据:

  1. 若 LayoutOp 的变体数量增长到难以让模型可靠选择——「一个封闭 op 集合」需要重新评估(可能要退回受限的树描述);
  2. 若布局变更的频率高到污染日志(fold 合并不足以吸收)——「入日志」需要重新权衡;
  3. 若出现需要跨会话共享/同步布局的需求——会话日志不是正确的家。

第一条失效条件后来真的发生了:在 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 中生效的原则:

  1. 布局是数据,不是代码:区域树是可组合的配置值(Split / Stack / Leaf),由 host.rs 的 default_layout() 初始化;
  2. Op 词汇表优于整树替换:即使可调布局被移除,Show / Hide 两个 op 仍是面板上屏/下屏的唯一通道,所有面板行共用同一个 apply 与同一套 LayoutError 语义(不 panic、不静默、拒绝必带原因);
  3. 屏幕可见即已记录:布局属于"给屏幕看的事实"(is_model_visible() == false),与 Notice 同类,会话日志是屏幕状态的权威来源;
  4. 描述与渲染必须同源:宁可去掉一个入口,也不允许"模型描述的"与"实际渲染的"出现两个家——0022 第 8 节正是这一原则的最终执行。

对于想深入源码的读者,建议按此顺序阅读:layout.rs(op 与错误语义)→ rows.rs(面板行如何用 op 上屏)→ host.rs(默认区域树)→ guards.rs("可调布局已消失"的守卫测试),再回到 docs/tui-composability.md §二 补全完整的空间可组合性论证。

登录后查看全文
atomcode