AtomCode `request_user_input` 交互面板改造:`custom` 自定义答案开关与 Submit 间隔的实现方案

原创2026-10-14 12:27:131,706 阅读
文章标签:人工智能AI 应用AI Agent代码智能体CLIAI 评测

AtomCode request_user_input 交互面板改造:custom 自定义答案开关与 Submit 间隔的实现方案

request_user_input 是 AtomCode 中让模型向用户提出结构化问题(单选 / 多选 / 自由文本)并暂停回合等待回答的核心工具。本篇文章围绕其 custom 标志(控制是否自动附加"输入自己的答案"自由文本行)与多选模式 Submit 按钮上方空白间隔两项改造,从实现计划出发,逐层对照 atomcode-capabilities、atomcode-tuix、atomcode-daemon 与 webui 的落地源码,讲解字段设计、状态索引、渲染门控与事件处理的完整调用链,并指出计划设想与最终实现之间的关键差异。读完你将理解该面板的"Other 行"是如何被精确控制存在与否的,以及如何在 TUI 与 webui 两种驱动中保持一致的行为。

一、改造目标与总体架构

目标

在原 2026-07-22 实现计划 中,本次改造有两个明确目标:

  1. 为每个问题增加 custom 标志(默认 true):当 custom == false 时,隐藏自动附加的"type your own answer"自由文本行(下文简称 Other 行)。当模型给出的 options 已经覆盖所有可能答案(即选项是穷尽的)时,用户不应再被提示去"自己输入"一个选项里不存在的答案。
  2. 在多选(multiple)模式的 Submit 行上方增加一个空白间隔行:避免提交按钮与最后一个选项/Other 行视觉上挤在一起,提升可读性。

架构

计划的总体设计是"字段下沉 + 多点门控":

  • custom 是 UserInputRequest 上的新字段(serde 默认 true),从工具层一路穿透到 UserInputPanel(TUI 状态)与 UserInputPanelView(渲染视图);
  • Other 行的"存在性"横跨四层被统一门控:状态索引数学(submit_index / last_row / is_other_row / checked 长度)、渲染器(行构造与行数统计)、事件循环的数字键处理(数字键不能跳到一个不存在的 Other 行);
  • Submit 空白间隔是纯渲染层改动;
  • 内核(kernel)零改动——这只是一次请求/响应载荷与驱动 UI 的协同调整。

技术栈涉及 Rust 侧 atomcode-capabilities(工具定义)、atomcode-tuix(TUI 状态与渲染)、atomcode-daemon(webui 事件转发),以及 React/TS 侧的 webui。

二、全局约束:保证零回归的不变量

计划在 Global Constraints 中确立了四条必须遵守的约束,它们是理解全部改动的钥匙:

  1. custom 默认 true(#[serde(default = ...)])——字段缺失时保持现有行为,对既有调用方零回归。
  2. Other 行存在当且仅当 custom == true——所有曾经把 Other 行计入的索引(other_index、submit_index、last_row、checked 向量长度、渲染行、行数统计、数字键处理)都必须以 custom 为门控条件。
  3. 行数不变量:user_input_panel_row_count(view) == build_user_input_rows(view).len() 必须对 custom 的两种取值以及新增的 multiple 空白行同时成立——渲染器生成的每一行都必须被行数统计精确预测,否则 TUI 的 footer 高度计算会错位。
  4. Submit 空白仅存在于 multiple 模式(single 模式没有 Submit 行,自然也没有空白)。
  5. 附带工程约束:提交信息需附 Co-Authored-By trailer,且由于 crates/atomcode-tuix/src/{state.rs, event_loop/mod.rs} 可能携带无关的未提交改动,必须用 git add -p 只暂存本变更的 hunks,绝不把无关 WIP 一起提交。

三、Task 1:工具层 —— 在 request_user_input 中引入 custom 字段

计划中的设计

计划为 crates/atomcode-capabilities/src/tools/request_user_input.rs 规划了四步:先写失败测试、再添加带 serde 默认值的字段、更新 schema 与描述、跑通测试并提交。

字段定义按计划应为:

fn default_true() -> bool {
    true
}

#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct UserInputRequest {
    pub header: String,
    pub question: String,
    pub mode: UserInputMode,
    #[serde(default)]
    pub options: Vec<UserInputOption>,
    /// Whether the auto "type your own answer" free-text row is offered
    /// (single/multiple). Default true (absent ⇒ true) — backward compatible.
    /// Set false when `options` are exhaustive.
    #[serde(default = "default_true")]
    pub custom: bool,
}

对应的失败测试(先验证"缺省为 true、显式 false 可解析"):

#[test]
fn parse_custom_defaults_true_and_reads_false() {
    let r = parse_args(
        r#"{"header":"H","question":"Q?","mode":"single","options":[{"label":"A"}]}"#,
    )
    .unwrap();
    assert!(r.custom, "custom absent → defaults true");
    let r2 = parse_args(
        r#"{"header":"H","question":"Q?","mode":"single","options":[{"label":"A"}],"custom":false}"#,
    )
    .unwrap();
    assert!(!r2.custom, "custom:false parsed");
}

计划还要求在 parameters_schema 的共享 question 对象 properties 中加入 custom({"type": "boolean", "description": "Offer a free-text 'type your own answer' row (default true). Set false when your options are exhaustive."}),并在工具 description 末尾追加提示:自由文本行会自动添加,模型不要自行添加 "Other"/catch-all 选项,选项已穷尽时用 custom:false 表达。

源码落地与计划的关键差异

字段本身已按计划落地。在 request_user_input.rs 中可以看到 default_true() 辅助函数与 pub custom: bool 字段(带 #[serde(default = "default_true")] 和文档注释)。

但最终实现收紧了对模型输入的信任,这是计划与落地之间最重要的差异:

  • 在 parse_args 中,解析后紧跟一行 req.custom = true;,注释写明:"Keep accepting the legacy field for wire compatibility, but a human-facing question must always leave the user a free-form escape hatch."
  • 批量路径 parse_batch 对每个 questions[] 项同样执行 req.custom = true; 归一化。
  • schema 中不暴露 custom 字段。测试 legacy_custom_false_is_accepted_but_normalized_true 直接断言了两件事:遗留 custom:false 载荷被接受但归一化为 true("legacy custom:false must not remove the user's free-form escape hatch"),且模型面对的 schema 中没有 custom 键。

也就是说:计划设想"模型可通过 custom:false 声明选项已穷尽",落地时演变为面向人类的问题永远保留自由文本逃生舱口;真正使用 custom:false 的是 TUI 内部构造的固定 checkpoint 面板(见第六节),而非模型传来的载荷。custom 字段在 wire 层仍保留 serde 默认 true,保证旧载荷兼容。

四、Task 2:TUI 状态层 —— 让索引数学感知 custom

计划中的设计

计划为 crates/atomcode-tuix/src/state.rs 的 UserInputPanel 增加 pub custom: bool,并在 new() 中按 options.len() + r.custom as usize 初始化 checked 向量(每个具体选项一个槽位,外加 Other 行一个槽位,仅当开启自定义时)。随后把三个索引辅助函数全部门控:

pub fn submit_index(&self) -> Option<usize> {
    if matches!(self.mode, UserInputMode::Multiple) {
        Some(self.options.len() + self.custom as usize)
    } else {
        None
    }
}

pub(crate) fn last_row(&self) -> usize {
    match self.mode {
        UserInputMode::Multiple => self.submit_index().unwrap(),
        _ => {
            if self.custom {
                self.other_index()
            } else {
                self.options.len().saturating_sub(1)
            }
        }
    }
}

pub fn is_other_row(&self) -> bool {
    self.custom && self.cursor == self.other_index()
}

计划同时给出了针对性的单测:single 模式 custom=false 时 last_row 回到最后一个具体选项(而非 Other 行);multiple 模式 custom=false 时 submit_index 从 3(other@2 + submit@3)前移到 2,checked.len() 从 3 变为 2。

源码落地

UserInputPanel 确实新增了 pub custom: bool 字段(state.rs),submit_index、last_row、is_other_row 的实现与计划一致(state.rs),且 last_row 按计划的注记改成了 pub(crate) 可见性以便测试直接断言。

又一个计划与落地的差异点出现在 UserInputPanel::new:落地版本不再直接读取 r.custom,而是由模式推断——

let custom = matches!(
    r.mode,
    UserInputMode::Single | UserInputMode::Multiple
);
let checked = vec![false; options.len() + custom as usize];

对应注释(state.rs)解释了原因:人类面向的选择题始终保留自由表单行;custom:false 在旧 wire 载荷上被接受,但不再授予模型移除该逃生舱口的权限;内部固定 checkpoint 因为直接构造 renderer 视图而不受影响。这与此前工具层 req.custom = true 的归一化策略完全呼应——两条路径共同把"模型不可关闭自由文本"落成一致的事实。

五、Task 3:TUI 渲染层 —— 门控 Other 行、插入 Submit 空白、对齐行数

计划中的设计

渲染层涉及两个文件:视图结构在 crates/atomcode-tuix/src/render/mod.rs,行构造在 crates/atomcode-tuix/src/render/retained.rs。计划要求:

  1. UserInputPanelView 增加 pub custom: bool 字段;
  2. build_user_input_rows 中,把整个"Always-appended custom-answer row"代码块包进 if panel.custom { ... };
  3. multiple 模式在 Submit 行之前 blank_row(&mut out) 推入一个空白行,Submit 行的 on_cursor 索引改为 panel.options.len() + panel.custom as usize(原先写作 other_index + 1);
  4. 行数统计同步:single/multiple 分支中 Other 行的 n += 1 改为 if panel.custom { n += 1; },multiple 的 Submit 贡献从 +1 改为 +2(空白 + Submit)。

计划还给出了一个具体的行数核算示例,展示 single/multiple 分支的完整统计逻辑:

UserInputMode::Single | UserInputMode::Multiple => {
    let mut n = 4; // header chip + blank + question + blank
    for (_, desc) in &panel.options {
        n += 1;
        if desc.as_deref().map(|d| !d.trim().is_empty()).unwrap_or(false) {
            n += 1;
        }
    }
    if panel.custom {
        n += 1; // the Other row
    }
    if matches!(panel.mode, UserInputMode::Multiple) {
        n += 2; // blank spacer + Submit row
    }
    n += 2; // blank + hint
    n
}

源码落地

视图结构已含 pub custom: bool(render/mod.rs,注释明确"mirrors UserInputPanel.custom")。行构造在 retained.rs:

  • Other 行整体包裹在 if panel.custom { ... } 中,占位符为 输入自己的答案…(unicode 终端)或 ASCII 后备;复选框状态由 custom_text.trim() 是否非空推导,而非 checked[other_index],避免 Enter 在 Other 行上的 no-op 造成勾选失步;
  • multiple 分支在 retained.rs 中先 blank_row(&mut out),再以 let submit_index = panel.options.len() + panel.custom as usize; 计算 Submit 行的光标索引,与状态层 submit_index() 的公式完全一致(计划 Self-Review 特意强调这一类型/公式一致性)。

关于行数统计:落地源码中的函数名为 user_input_panel_view_row_count(retained.rs),其实现方式不是手写公式,而是直接调用 build_user_input_panel_view(...).len()——以"真的构建一遍再数"来保证与 build_user_input_rows 永不脱节。这与计划命名的 user_input_panel_row_count 是同一职责的两种实现路径,目标都是守住那条行数不变量。

六、Task 4:事件层 —— 数字键不能跳到不存在的 Other 行

计划中的设计

计划要求 crates/atomcode-tuix/src/event_loop/mod.rs 中两处改动:

  1. 单题路径 handle_user_input_key 与批量路径 handle_user_input_batch_key 的数字键分支,把 if idx == p.other_index() 改为 else if idx == p.other_index() && p.custom——即只有开启自定义时,N+1 号数字键才把光标移到 Other 行;否则该数字被忽略;
  2. 两处 UserInputPanelView { .. } 构造点(单题的 .map(|p| ...) 与批量的当前题)传入 custom: p.custom。

源码落地

数字键处理在 event_loop/mod.rs 中确实按计划实现:if idx < p.options.len() { ... } else if idx == p.other_index() && p.custom { p.cursor = p.other_index(); }。视图构造则在 event_loop/mod.rs 的单题与批量两处均写入 custom: p.custom。

事件层还有一些计划未逐条展开、但实际源码中与 custom 协同的交互细节,可以佐证门控的完整性:

  • multiple 模式下 Enter 在 Other 行是 no-op(用户通过打字加入自定义答案,再导航到 Submit 确认),见 event_loop/mod.rs;
  • Left/Right 只有在 is_other_row() 时才编辑 custom_text 缓冲区(event_loop/mod.rs);
  • 粘贴图片到用户输入面板时,非 text 模式会把光标强制移到 other_index()(event_loop/mod.rs),这一行为在 custom=false 的面板上不会触发,因为内部 checkpoint 不接收图片粘贴路径。

七、Task 5:daemon 与 webui —— 转发并尊重 custom

计划中的设计

  • daemon:在 live_api.rs 的 LiveWireEvent::UserInputRequest 投影中增加 custom: bool 字段,从 request.payload.get("custom").and_then(Value::as_bool).unwrap_or(true) 读取;批量路径的 questions[] 每项已天然携带 custom;
  • webui 类型:api.ts 的 UserInputQuestion 与 UserInputRequestEvent 增加 custom?: boolean;
  • webui 渲染:UserInputCard.tsx 中计算 const showOther = q.custom !== false;,single 的 Other radio 与 multiple 的 Other checkbox + 自由文本输入框都只在 showOther 时渲染;单题卡片读 req.custom,批量步进器读 req.questions[step].custom;
  • 最后运行 cd webui && npx tsc --noEmit 做类型检查。

源码落地

  • daemon 的 LiveWireEvent::UserInputRequest 枚举已含 custom: bool(live_api.rs,注释"Whether to offer the 'type your own answer' row (single question). Default true.");投影器按计划读取 payload,缺失时 unwrap_or(true)(live_api.rs);
  • api.ts 中两个接口均声明 custom?: boolean,注释明确"Absent ⇒ true";
  • UserInputCard.tsx 中 const showOther = q.custom !== false; 与计划一致;single 的 Other radio 渲染于 UserInputCard.tsx、multiple 的 Other checkbox 于 UserInputCard.tsx,自由文本输入框在选中 Other 后出现(singleOtherActive / multiOtherActive);单题卡片在 UserInputCard.tsx 组装 q 时透传 custom: req.custom。

值得注意的细节:webui 的 buildAnswer 在 multiple 模式下只有 otherChecked && freeText.trim() 非空时才把自由文本并入 selected,且 hydrate 把不在选项集合里的已提交标签还原为 Other 输入——即使 custom:false,这类解析逻辑也天然安全,因为 showOther=false 时用户根本没有入口产生这类状态。

八、自检清单与验证方式

计划的 Self-Review 逐项核对了规格覆盖:字段 + serde 默认 + schema + 描述(Task 1)、状态层索引门控(Task 2)、渲染门控 + 空白 + 行数(Task 3)、事件层数字键与视图字段(Task 4)、daemon 转发 + webui 遵循(Task 5)、两种 custom 取值与新增空白的行数不变量(Task 3)、既有 multiple 行数测试随 +1 空白更新、WIP 暂存约束等,均标注完成。计划还强调 custom: bool 在 UserInputRequest、UserInputPanel、UserInputPanelView、webui 类型间类型一致,submit_index = options.len() + custom as usize 在状态层与渲染层公式相同。

验证手段包括:

  • cargo test -p atomcode-capabilities --lib request_user_input(工具层解析与序列化测试);
  • cargo test -p atomcode-tuix --lib user_input(渲染行数与门控测试);
  • cargo build -p atomcode-tuix && cargo test -p atomcode-tuix(全量回归);
  • cd webui && npx tsc --noEmit(webui 类型检查);
  • 真机视觉验证:在真实终端 / webui 中分别提问 custom:false(穷尽选项)的多选题,确认 Other 行消失、Submit 上方出现空白间隔。

九、计划与最终实现的差异小结

维度 计划设想 仓库实际落地
模型能否用 custom:false 关闭自由文本 可以:schema 暴露 custom,description 提示模型对穷尽选项设置 custom:false 不可以:parse_args/parse_batch 强制 req.custom = true,schema 不暴露 custom;人类面对的问题始终保留自由表单逃生舱口
TUI 面板 custom 的来源 直接读取 UserInputRequest.custom 由 mode 推断:Single/Multiple → true,Text → false;r.custom 仅在 wire 兼容层面被接受
真正使用 custom:false 的调用方 (计划未展开) 内部固定 checkpoint 面板:轮次上限面板 round_cap_view(render/mod.rs)与输出截断恢复面板 output_truncation_view(render/mod.rs)均构造 custom: false,它们是驱动自有的选择器,不开放自由输入
行数统计函数 计划命名 user_input_panel_row_count,手写公式 落地为 user_input_panel_view_row_count,通过 build_user_input_panel_view(...).len() 实算,守同一不变量

其余部分——serde 默认 true、状态索引门控、渲染门控与 multiple 空白、事件层数字键门控、daemon 转发与 webui 遵循——均与计划一致落地。

十、对使用者与二次开发者的实际影响

  1. 模型侧:request_user_input 的描述明确要求"自由文本行会自动添加,不要自行添加 Other/catch-all 选项"。调用方只需保证 options 完整即可,不必(也无法)通过 custom:false 干预 UI。
  2. 内部面板作者:若要在 TUI 中构造"选项即答案"的固定选择器(如轮次上限、输出截断),参考 round_cap_view / output_truncation_view 直接构造 UserInputPanelView { custom: false, .. },渲染器会正确省略 Other 行并同步行数。
  3. 驱动开发者:webui 只需让 custom !== false 决定 Other 行可见性;缺失字段按 true 处理,与 daemon 投影的 unwrap_or(true) 保持一致,不会出现新旧事件格式的渲染差异。
  4. 回归关注点:任何改动触及 build_user_input_rows 或行数统计时,必须同时验证 custom 两值与 multiple 空白的行数不变量,否则 TUI footer 高度将错位。

该改造的核心价值在于:把"是否允许自由输入"从模型的不可控表述,收敛为驱动侧可精确控制的开关,同时通过统一的索引公式与行数不变量,让 TUI 与 webui 两种驱动在穷尽选项场景下呈现一致的、整洁的交互面板。

登录后查看全文
atomcode