AtomCode `request_user_input` 交互面板改造:`custom` 自定义答案开关与 Submit 间隔的实现方案
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 实现计划 中,本次改造有两个明确目标:
- 为每个问题增加
custom标志(默认true):当custom == false时,隐藏自动附加的"type your own answer"自由文本行(下文简称 Other 行)。当模型给出的options已经覆盖所有可能答案(即选项是穷尽的)时,用户不应再被提示去"自己输入"一个选项里不存在的答案。 - 在多选(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 中确立了四条必须遵守的约束,它们是理解全部改动的钥匙:
custom默认true(#[serde(default = ...)])——字段缺失时保持现有行为,对既有调用方零回归。- Other 行存在当且仅当
custom == true——所有曾经把 Other 行计入的索引(other_index、submit_index、last_row、checked向量长度、渲染行、行数统计、数字键处理)都必须以custom为门控条件。 - 行数不变量:
user_input_panel_row_count(view) == build_user_input_rows(view).len()必须对custom的两种取值以及新增的 multiple 空白行同时成立——渲染器生成的每一行都必须被行数统计精确预测,否则 TUI 的 footer 高度计算会错位。 - Submit 空白仅存在于 multiple 模式(single 模式没有 Submit 行,自然也没有空白)。
- 附带工程约束:提交信息需附
Co-Authored-Bytrailer,且由于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。计划要求:
UserInputPanelView增加pub custom: bool字段;build_user_input_rows中,把整个"Always-appended custom-answer row"代码块包进if panel.custom { ... };- multiple 模式在 Submit 行之前
blank_row(&mut out)推入一个空白行,Submit 行的on_cursor索引改为panel.options.len() + panel.custom as usize(原先写作other_index + 1); - 行数统计同步: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 中两处改动:
- 单题路径
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 行;否则该数字被忽略; - 两处
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 遵循——均与计划一致落地。
十、对使用者与二次开发者的实际影响
- 模型侧:
request_user_input的描述明确要求"自由文本行会自动添加,不要自行添加 Other/catch-all 选项"。调用方只需保证options完整即可,不必(也无法)通过custom:false干预 UI。 - 内部面板作者:若要在 TUI 中构造"选项即答案"的固定选择器(如轮次上限、输出截断),参考
round_cap_view/output_truncation_view直接构造UserInputPanelView { custom: false, .. },渲染器会正确省略 Other 行并同步行数。 - 驱动开发者:webui 只需让
custom !== false决定 Other 行可见性;缺失字段按true处理,与 daemon 投影的unwrap_or(true)保持一致,不会出现新旧事件格式的渲染差异。 - 回归关注点:任何改动触及
build_user_input_rows或行数统计时,必须同时验证custom两值与 multiple 空白的行数不变量,否则 TUI footer 高度将错位。
该改造的核心价值在于:把"是否允许自由输入"从模型的不可控表述,收敛为驱动侧可精确控制的开关,同时通过统一的索引公式与行数不变量,让 TUI 与 webui 两种驱动在穷尽选项场景下呈现一致的、整洁的交互面板。