
A2UI Atom 推理格式迭代优化实战run_014「精简目录签名描述」实验记录与源码解读【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui本文以 A2UI 仓库中一次真实的推理格式优化实验记录atom格式 run_014为主体完整解读该次优化假设、评测指标、Git Diff 内容及其在 Agent SDK 源码中的落点并结合优化器技能文档中的评分模型与决策规则说明为什么一次快验 100% 通过的改动最终仍被判定回退以及如何复现同类实验。1. 背景A2UI 的推理格式迭代优化体系A2UI 是一个让 Agent 以结构化 UI 描述驱动渲染的协议项目。为了让 LLM 生成 UI 载荷时更省 token、更稳定Agent SDKPython内置了多种推理格式inference formats位于 inference_formats 目录下direct_json直接输出 JSON 消息的基线格式experimental/atom、experimental/express、experimental/elemental三种实验性紧凑格式其中本文聚焦的Atom采用 S-Expression括号表达式记法由 format.py、parser.py、compiler.py、prompt_generator.py 等模块组成提示词生成器负责把组件目录catalog的 JSON Schema 编译成 LLM 可读的签名文本编译器则把 LLM 输出的 S-Expression 编译回标准 A2UI 消息。围绕这些格式仓库内置了一套名为Inference Format Optimizer的技能与脚本SKILL.md其核心是一套 6 步迭代工作流分析历史读取eval/iterative_format_optimizer/history/format/与 history_summary.md避免重复已被回退的假设实现假设修改compiler.py、prompt_generator.py或parser.py跑单元一致性测试pytest执行基准评测python scripts/optimize_format.py --format format按决策规则评估必须通过 pytest 且不劣于基线准确率代码输出 token 膨胀不得超过 5%否则回退git reset --hard HEAD归档与同步--archive归档运行产物并用 sync_history.py 更新历史索引。每次运行的产物report.md、patch.diff、run_meta.json按run_XXX_commit短哈希_假设slug命名归档到eval/iterative_format_optimizer/history/下本文主角即是 atom/run_014 目录 中的 report.md。2. run_014 实验假设与评测结果2.1 实验元信息该次运行使用atom格式策略/格式字段为atom评测模型为google/gemini-3.5-flash预算档位为 Unbounded。其假设hypothesis原文见 run_meta.json为Streamline catalog component signature property detail descriptions to minimize input token overhead and reasoning search space. 精简目录组件签名中的属性详情描述以最小化输入 token 开销与推理搜索空间。换句话说本次实验的靶点是prompt_generator.py 中组件目录签名的生成逻辑签名文本里每个属性会附带一段来自 Schema 的description描述假设是把这些描述删掉、只保留枚举约束可以显著降低 LLM 的输入 token且不会伤害准确率。2.2 快验报告摘要表report.md 原文数据report.md 记录了本次运行的快验Fast Validation结果共 6 个样本MetricBaselineCurrentDiffPytest ConformancePASSPASS-Overall Pass Rate83.3%100.0%16.7%Algorithmic Schema Pass Rate100.0%100.0%0.0%Inference Duration (sec)8.45s8.78s3.9%Avg Input Tokens00-Avg Output Tokens00-报告尾部明确写着Failure Details (Count: 0 / 6)All tests passed successfully!。需要注意两个细节快验模式下 Input/Output Tokens 记为 0即该模式不采集 token 计数token 对比在完整评测中才产生见第 5 节这里的 Baseline83.3%是优化器工作树当前基线的快验通过率与 unbounded 基线全量数据255 样本不是同一口径。2.3 report.md 中的 Active Git Diff报告核心是一份 Git Diff。结合 patch.diff 与 history_summary.md 对照可以确认report.md 里的 Active Git Diff 是优化器工作树相对上一个已提交基线的累计差异包含此前多个 run 对ATOM_RULES提示词规则的修改而本次 run 自己的补丁是patch.diff。下面分两部分解读。1累计差异ATOM_RULES 提示词规则的精简该 diff 作用于 prompt_generator.py 中的ATOM_RULES常量Atom 格式的系统提示词核心主要变化有五处哨兵标签指令去重原来三行重复强调必须用a2ui//a2ui包裹、禁止输出裸 JSON合并为一行You MUST surround the entire A2UI Atom block with the sentinel tags a2ui and /a2ui. Do NOT output raw JSON messages.数据模型填充规则扩展Rule 6从仅支持(data $/path1 val1 $/path2 123)的扁平路径-值序列扩展为支持 S-Expression 地图写法(data $/map_path (:key1 val1 :key2 val2))动作事件规则收紧Rule 8新增带 action 属性的交互控件必须提供 action 表达式并给出示例(ActionComponent :child (ChildComponent Text) :action (Event click_action))示例对齐Example 1/2:onPress改为与规则一致的:action属性名数据模型示例从内嵌 JSON 数组(data $/items [{id: 1, ...}])改为纯 S-Expression 项映射(data $/items [(:id 1 :name Item 1)])消除JSON 混入 S-Expression的歧义规则 11 改名为 Strict Catalog Adherence Conciseness删去严格遵循签名中属性名与枚举值的表述替换为Output minimal properties required to satisfy the user request只输出满足请求所需的最少属性。这些改动当前已在仓库源码中生效可以对照 prompt_generator.py 第 25-84 行 的现文例如第 26 行的合并后哨兵指令、第 51-52 行的 Rule 6、第 76 行的 S-Expression 数据项示例。2本次 run 自身的补丁patch.diff签名描述精简patch.diff 才是 run_014 假设的直接实现改动集中在AtomPromptGenerator的两个方法_generate_component_signatures与_generate_function_signatures中生成属性详情行的代码块。改动前的逻辑if p_desc or enum_vals: p_line_parts [] if p_desc: p_line_parts.append(p_desc) if enum_vals: enum_vals_str , .join([f{v} for v in enum_vals]) p_line_parts.append(fMust be one of: {enum_vals_str}) prop_details.append(f - :{p}: { .join(p_line_parts)})改动后if enum_vals: enum_vals_str , .join([f{v} for v in enum_vals]) prop_details.append(f - :{p}: Must be one of: {enum_vals_str})即属性签名详情行只保留枚举约束Must be one of: ...彻底丢弃来自 JSON Schema 的属性description文本。组件与函数签名两处做了对称修改。3. 源码级解读目录签名是如何生成的理解上述补丁的影响需要先弄清签名文本的生成机制。在 prompt_generator.py 中AtomPromptGenerator.__init__通过CatalogSchemaHelper来自a2ui.schema.schema_helper导入失败时回退到 express 格式的同名助手类封装当前 catalog形成schema_helpergenerate()第 172-217 行组装最终系统提示词角色描述 ## Instructions:含ATOM_RULES与工作流说明## Component Catalog Signatures:## Function Signatures:_generate_component_signatures第 219-262 行遍历目录中每个组件为每个属性生成位置参数标签:property可选属性带?后缀跳过id/component保留字段随后拼接组件描述与属性详情行产出形如- (ColumnName :title :orientation?) - 组件描述... - :orientation: 属性 description Must be one of: horizontal, vertical枚举值的抽取由 _get_schema_enum 递归完成除直接读取enum键外还会深入oneOf/anyOf子 Schema 寻找枚举定义。这套机制决定了 run_014 补丁的实质属性description是 LLM 理解这个属性用来做什么的主要语义载体。枚举值属于硬约束选错即违反 Schema算法校验可拦截而自由文本属性的取值语义例如某个variant属性在何种场景该选哪个字符串完全依赖描述文本。这正是后文决策反转的根源。4. 评分模型与决策规则为什么 100% 快验仍会回退优化器不是看着通过率涨了就收工其决策模型定义在 scoring_model.md 中分两层正确性护栏不可妥协任一不满足必须回退pytest 单元一致性测试必须 100% 通过算法 Schema 通过率SchemaAcc输出载荷对目标 catalog JSON Schema 的校验必须不低于基线模型评分质量分QualityScoreLLM 判分的语义意图匹配必须不低于基线。效率回退上限任一超线必须回退代码输出 Token 增长 5%流式非推理输出时延增长 10%推理 Token 增长 15%。综合得分 $S_{\text{opt}}$S_opt 0.50·SchemaAcc 0.30·QualityScore - 0.15·(CodeTok/BaseCodeTok) - 0.05·(ReasonTok/BaseReasonTok) - 0.03·(InputTok/BaseInputTok)决策规则$S_{\text{opt}}$(当前) $S_{\text{opt}}$(基线) 则保留KEEP否则回退REVERT。5. run_014 的最终结局按 Rule 1 回退Backtrackedrun_014 是快验通过、全量评测翻车的典型案例。run_meta.json 中记录的最终状态为Backtracked其 notes 字段原文为Input Tokens reduced by -46.3% (2,389 vs 4,447) and Reasoning Tokens by -32.4% (3,212 vs 4,753), but Schema Acc and Quality Score regressed from 100.0% to 75.0% (-25.0%) due to missing property context. Reverted per Rule 1.history_summary.md 中 run 014 一行的记录与之完全一致Status: BacktrackedReverted per Rule 1。两个层面的信息假设前半部分被验证删除属性描述后输入 token 从 4,447 降到 2,389-46.3%推理 token 从 4,753 降到 3,212-32.4%token 效率收益远超预期正确性护栏被击穿Schema 通过率与质量分双双从 100% 跌到 75%-25%——正如第 3 节分析的失去属性描述这一语义上下文后LLM 在多属性组件上选错属性/取值触发 Rule 1正确性护栏必须回退。与之形成对照的是同批精简签名路线的兄弟实验均见 history_summary.mdrun 015仅对单属性基元组件截断描述因推理 token 超 15% 上限被回退run 019保留枚举、只删单字符串属性描述因 LLM 歧义导致推理 token 与时延上升被回退run 025紧凑签名参数类型提示、run 028签名提示 输出简洁指令、run 030布尔/枚举参数紧凑格式也都被回退其中 run 030 的教训记录最为直白——为短枚举/布尔省略描述行在多属性组件中制造了搜索空间歧义$S_{\text{opt}}$ 从 0.600 跌至 0.435。反复实验共同指向一条经验目录属性描述是高价值的上下文信息激进删减虽省 token却会破坏 LLM 的属性选择正确性有效的省 token 方向更多落在编译器侧的无损 AST 简化上如被保留的 run 016无损 AST 简化自动省略标准容器节点的默认 key 包装。6. 基线参照与复现方式6.1 全量基线数据Atom 格式的 unbounded 全量基线归档在 baselines/atom/unbounded_run_meta.json关键数字模型google/gemini-3.5-flashtemperature 0.0数据集core_v1_05 轮 × 51 样本 255 样本Schema 准确率约 93.73%质量分约 83.14%输入 token 中位数 4,443推理 token 中位数 4,316样本级明细覆盖deleteSurface、loginForm、productGallery、flightBooker、mcpAppProxy等 51 个用例可看到复杂用例如animalKingdomExplorer、clientSideValidation的 token 与时延显著高于简单用例。数据集定义位于 core_v1_0.yaml。6.2 复现命令优化器技能的 CLI 速查表见 SKILL.md脚本均位于eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/动作命令跑快验评测python scripts/optimize_format.py --format atom跑完整评测套件python scripts/optimize_format.py --format atom --full测试解析/编译python scripts/optimize_format.py --format atom --compile (Card (Text \Hi\))与基线对比python scripts/compare_results.py --baseline eval/iterative_format_optimizer/baselines/atom/unbounded_run_meta.json 运行日志目录归档运行产物python scripts/optimize_format.py --format atom --archive --hypothesis ... --status KEEP同步多 worktree 历史python scripts/sync_history.py若要阅读 run_014 的完整材料从归档目录 atom/run_014_e89102c_streamline_catalog_signature_descriptions 入手即可report.md快验报告与累计 diff、patch.diff本次假设补丁、run_meta.json假设、最终状态与 notes三件套配合 history_summary.md 的总索引可以完整还原假设 → 实现 → 快验 → 全量评测 → 回退的一次标准迭代闭环。7. 小结run_014 这份看似简短的优化报告实际上浓缩了 A2UI 推理格式工程化的完整方法论以 report.md 的指标表与 Git Diff 为做了什么的证据以 prompt_generator.py 的签名生成源码为为什么这样做的解释以 scoring_model.md 的护栏与 $S_{\text{opt}}$ 公式为该不该保留的裁决依据。它的结论对任何做 LLM 提示词/格式优化的人都具有参考价值token 收益必须让位于正确性护栏目录描述这类看似可删的上下文往往是 LLM 属性选择能力的隐性依赖。【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考