A2UI Express 推理格式优化实践ExpressCompiler 的大小写不敏感枚举强转run_016 / Pass 11【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui本文以 A2UI 推理格式迭代优化框架iterative format optimizer中一次真实保留Kept的优化运行run_016为主体完整拆解“假设 → 编译器改动 → 单测 → 评测 → 决策 → 归档”的全流程你可以通过本文理解 Express 格式中大小写不敏感的枚举值强转case-insensitive enum coercion是如何在ExpressCompiler._compile_value中实现的、为何它没有违反效率上限被保留以及如何用仓库自带的脚本复现与验证同类优化。1. 这份运行报告是什么四个自包含归档文件eval/iterative_format_optimizer/history/express/目录下按格式归档了历次优化运行本次分析的主体是其中一次运行目录report.md优化报告含指标汇总表、Active Git Diff 段与失败明细Failure Detailspatch.diff本次运行对编译器与测试的完整 Git diff可独立查看或重放git apply patch.diffrun_meta.json机器可读元数据记录假设hypothesis、状态Kept与关键指标results.jsonInspect AI 完整执行日志含每个样本的系统提示词、模型输出、编译产物与评分过程。这套“四文件自包含归档”是优化框架的设计约定每个归档目录可脱离分支保留独立存在详见 inference_format_iteration.md 第 4.2 节。报告正文的核心指标report.md 原文继承report.md 给出的摘要表如下MetricBaselineCurrentDiffPytest Conformance-PASS-Overall Pass Rate-100.0%Algorithmic Schema Pass Rate-100.0%Inference Duration (sec)-14.52sAvg Input Tokens-5951Avg Output Tokens-338评测策略格式express评测模型google/gemini-3.5-flash失败明细Failure Details (Count: 0 / 6)即验证子集的 6 个提示词全部通过报告中明确写着 “All tests passed successfully”。Active Git Diff一节记录的是归档时刻主工作树的状态No files modified under agent_sdks本次运行的实际改动则完整保存在同目录的patch.diff中——从归档结构看这符合框架“改动在隔离 Git worktree 中进行、主仓只留补丁”的隔离设计同一参考文档 4.1 节。run_meta.json补充了更细的元信息{ format: express, hypothesis: Pass 11: Case-insensitive enum choice coercion in compiler.py, status: Kept, notes: Case-insensitive enum choice coercion added to ExpressCompiler._compile_value. Pytest passed (61/61), Quality Score 100.0%, Output Tokens expansion 4.64%., metrics: { schema_acc: 1.0, quality_acc: 1.0, code_tokens_median: 272.5, reasoning_tokens_median: 2325.0, input_tokens_median: 5936.5, latency_seconds_median: 14.472916997037828, total_samples: 6 } }可以看到 report.md 中的均值14.52s / 5951 / 338与 run_meta.json 中的中位数14.47s / 5936.5 / 272.5来自同一份results.json的两种聚合口径。2. 背景Express 格式优化循环与决策规则Express 是 A2UI 的一种实验性推理格式inference format位于 agent_sdks/python/a2ui_agent/src/a2ui/inference_formats/experimental/express/模型先输出紧凑的 Express DSL每行一条变量 组件(位置参数)语句再由宿主侧编译器把它编译成标准 A2UI v1.0 JSON 消息。模块文档 compiler.py 开头即说明其职责“Tokenizes, lexes, and parses A2UI Express plain-text statements into a clean AST, compiling it directly into standard A2UI v1.0 JSON messages”。优化框架的工作流SKILL.md 中的 6-Step Workflow是分析历史读history/format/与 history_summary.md避免重复已被回退的假设实现假设修改compiler.py/prompt_generator.py/parser.py跑 pytest 单测验证不破坏既有编译器契约跑基准评测python scripts/optimize_format.py --format express默认跑 6 条提示词的验证子集dogBreedGenerator、loginForm、settingsPage、productGallery、productGalleryData、updateDataModel约 15 秒一次迭代按决策规则评估必须通过 pytest、精度不低于基线代码输出 token 膨胀不得超过 5%保留时综合分 $S_{opt}$ 提升否则git reset --hard HEAD回退归档与同步--archive归档运行产物sync_history.py重建历史索引。决策模型inference_format_iteration.md 第 3 节分三层正确性护栏pytest 必须 PASSSchemaAcca2ui_scorer算法侧编译schema 校验通过率与QualityScoremeasured_model_graded_qaLLM 语义评分均不得低于基线否则立即回退效率回归上限任一触发即回退代码输出 token 增长 5%、流式非推理输出时间增长 10%、推理 token 中位数增长 15%综合分$S_{opt} 0.50 \times SchemaAcc 0.30 \times QualityScore - 0.15 \times (CodeTok/BaseCodeTok) - 0.05 \times (ReasonTok/BaseReasonTok) - 0.03 \times (InputTok/BaseInputTok)$当前 基线则 KEEP否则 REVERT。在 history_summary.md 的总表中本次运行记录为express/016/ Hypothesis “Pass 11: Case-insensitive enum choice coercion in compiler.py” / Pytest PASS / Overall 100.0% / Algo 100.0% / Latency 14.47s / Input 5936 / Output 272 /KeptNotes 与 run_meta 一致。3. 问题根源严格枚举校验与 LLM 输出大小写的矛盾改动前编译器对带枚举约束的属性做严格匹配校验。当前仓库 compiler.py 中可以看到这段逻辑它是改动前后都存在的校验点enum_vals self.helper.get_property_enum(comp_name, prop_name) if enum_vals and isinstance(mapped_val, str): if mapped_val not in enum_vals: raise ValueError( fValue {mapped_val} is not a valid enum choice for f property {prop_name} of component {comp_name}. f Allowed values are: {enum_vals} )枚举候选值来源于目录catalog的 JSON Schema由CatalogSchemaHelper在初始化时抽取为(组件名, 属性名) - 枚举值的映射见 schema_helper.pyself.component_property_enums {}与 L106 的填充、L230-L242 的get_property_enum。与此同时提示词侧已经把枚举候选写进了组件签名。prompt_generator.py 会读取 schema 中的枚举并渲染成“Must be one of: default, primary, borderless”这样的行注入系统提示词run_016 的results.json中 sample 1 的系统提示词即可看到Button的variant签名带着这段枚举约束。即便如此模型仍可能输出PRIMARY、MultipleSelection这类大小写偏离规范值的形式——严格校验下这会直接抛ValueError导致该样本在a2ui_scorer的编译/校验环节失败。本次优化的假设正是在编译器值编译阶段做大小写不敏感的枚举强转把非规范大小写自动纠正回目录定义的规范值。注意一个事实边界当前仓库 HEAD 的compiler.py中并不包含本次运行引入的强转代码_enum_map逻辑仅存在于归档的patch.diff中也就是说这份记录以“优化历史归档”的形式保存在仓库里下文的代码均以patch.diff为准。4. 改动详解patch.diff 的四处变更patch.diff共修改两个文件编译器 compiler.py 与单测 tests/express/test_compiler.py。4.1 构造函数预构建全局小写枚举映射self.helper CatalogSchemaHelper(catalog) self._enum_map {} for enums in self.helper.component_property_enums.values(): for enum_val in enums: if isinstance(enum_val, str): self._enum_map[enum_val.lower()] enum_val初始化时遍历目录中所有组件属性的枚举值建立小写形式 - 规范形式的全局映射例如primary - primary、PRIMARY - primary。一次性构建避免了在每次值编译时重复计算。4.2 组件属性编译把该属性的枚举候选透传给_compile_value enum_vals self.helper.get_property_enum(comp_name, prop_name) mapped_val self._compile_value( arg, raw_symbols, ctx, is_action(prop_name in [action, submitAction]), enum_valsenum_vals, )只有当属性确实声明了枚举约束时enum_vals才非空没有枚举约束的普通字符串属性不会进入强转分支影响面被严格限制。4.3 值编译字符串强转 列表元素递归_compile_value新增enum_vals: Optional[list[str]] None形参。对列表逐项递归时把enum_vals继续传递下去覆盖“枚举值出现在数组元素”的情况对字符串新增如下兜底分支 if isinstance(val, str): if enum_vals: enum_map {e.lower(): e for e in enum_vals if isinstance(e, str)} if val.lower() in enum_map: return enum_map[val.lower()] return val语义非常克制只在小写形式命中枚举候选时才替换为规范值未命中则原样返回随后由 3 节的严格校验决定是否抛错。也就是说强转是“尽力纠正”不改变既有错误路径——写错成完全无关的词例如PRIMARYX依然会像改动前一样报错而不是被静默放行。4.4 新增单测锁定“大小写纠正”行为 def test_case_insensitive_enum_coercion(self): Verifies that enum values with non-canonical casing are coerced to canonical enum choice. compiler ExpressCompiler(self.catalog) dsl root Button(Click, PRIMARY) res compiler.compile(dsl) self.assertEqual(res[createSurface][components][0][variant], primary)这条用例插入在既有的“非法枚举值应报错”用例之后见 diff 上下文断言输入 DSL 中写了大写PRIMARY编译产物的variant必须被纠正为规范值primary。它同时隐含了反面契约——紧邻的旧用例仍验证“非枚举字符串会抛is not a valid enum choice异常”两者合起来界定了强转的边界。5. 评测结果为什么这次改动被保留5.1 双评分器都拿到满分results.json显示 6 个样本全部完成completed_samples: 6两个评分器的accuracy均为1.0a2ui_scorerversion 1.0对编译产物做算法校验sample 1 的解释为 “Valid A2UI payload”measured_model_graded_qa模型为google/gemini-3.5-flashLLM 按 C/P/I 三级给语义正确性评分sample 1 得到GRADE: C且评分指令中明确允许“大小写、标点等变体在语义完整时视为可接受”与编译器侧的大小写容忍形成呼应。5.2 端到端样本走读sample 1dogBreedGeneratorresults.json中 sample 1 完整呈现了“模型输出 DSL → 编译 → 评分”的链路系统提示词a2ui_eval/format_system_promptsolver 注入要求模型用a2ui//a2ui包裹 Express DSL 输出并给出 14 条文法规则与全部组件/函数的位置签名Button(child, variant?, action, ...)等用户提示在surfaceId main上生成一个包含“犬种信息卡片 虚构犬种生成器表单”的createSurfaceUI模型输出节选原样例中的图片 URL 已省略a2ui $/breeds [{url: ...}, {url: ...}] $/generator/name root Column([breedCard, genCard]) breedCard Card(breedContent) breedContent Column([breedTitle, breedHeaderImage, breedList]) breedList List(_template($/breeds, breedItemTemplate), horizontal) genButton Button(btnLabel, primary, genEvent) genEvent Event(generate_dog, {name: $/generator/name, ...}) ... /a2ui注意模型在这里恰好按规范写出了小写primary——大小写强转的价值在于为下一次模型输出PRIMARY这类偏离时兜底编译a2ui_eval/compile_format_payloadsolverDSL 被编译为 v1.0 JSONgenButton最终形如{ id: genButton, component: Button, child: btnLabel, variant: primary, action: { event: { name: generate_dog, context: { name: { path: /generator/name }, legs: { path: /generator/legs } } } } }同时dataModel由$/breeds ...、$/generator/... ...这类路径赋值自动汇集而成breeds数组与generator对象评分a2ui_scorer判 1.0LLM 评分给出 GRADE: C。5.3 决策核算Kept 的依据对照第 2 节的决策规则本次运行的账本非常清晰检查项本次运行判定Pytest 单测PASSnotes 记录 61/61满足护栏SchemaAcc / QualityScore100.0% / 100.0%不低于基线代码输出 token 膨胀4.64%notes 记录低于 5% 上限推理 token 中位数2325未触发 15% 上限notes 未报告回归输出 token 的 4.64% 膨胀贴线但仍在 5% 效率上限之内——这个“贴线通过”的判例在 express 历史中很有代表性对照总表中 express 的 run_007/00930.6%、run_01130.0%、run_01517.4%等因超出上限被 Backtracked 的运行可见上限规则被严格执行。综合以上run_meta 将状态记为Kept总表同步记录。6. 如何复现与验证这次运行以下操作仅涉及查看、安装与运行均为框架自带的只读/本地执行方式查看与重放补丁补丁是自包含的可在任意检出中查看或在一个独立的工作副本里执行git apply eval/iterative_format_optimizer/history/express/run_016_843ac936_pass_11_case_insensitive_enum_choice_coe/patch.diff重放改动跑单测在agent_sdks/python/a2ui_agent下运行 pytest 验证本次运行记录为 61/61 通过重点用例即 4.4 节的test_case_insensitive_enum_coercion跑格式验证评测使用技能脚本路径见 SKILL.md 的 CLI 表快速验证子集python scripts/optimize_format.py --format express全量套件python scripts/optimize_format.py --format express --full单条 DSL 编译调试python scripts/optimize_format.py --format express --compile (Card (Text \Hi\))与基线对比python scripts/compare_results.py --baseline eval/iterative_format_optimizer/baselines/format/unbounded_run_meta.json 日志目录脚本会计算各指标 delta 与 $S_{opt}$归档验证通过后用--archive --hypothesis ... --status KEEP产出与本文一致的report.md/patch.diff/run_meta.json/results.json四件套。运行环境前提评测依赖 Inspect AIresults.json记录版本 0.3.242与 Gemini API 访问评测/评分模型均为google/gemini-3.5-flash指标数值与所跑样本数验证子集 6 条相关重跑时请留意与基线的样本对齐比较器会自动做 1:1 样本过滤。7. 小结这次run_016Pass 11在ExpressCompiler中加入了大小写不敏感的枚举强转构造函数预建小写映射_enum_map、组件属性编译时透传enum_vals、_compile_value对字符串含列表元素做“小写命中则纠正为规范值”的兜底未命中的值仍走既有的严格校验报错路径评测结果pytest 61/61 通过、6 条验证样本 Overall 与 Algorithmic Schema 通过率均为 100%输出 token 膨胀 4.64% 低于 5% 效率上限因此按决策模型记为Kept该运行是 Express 格式迭代历史history_summary.md 中 express 001–027里“编译器侧容错”类改动被成功保留的案例之一其完整证据链报告、补丁、元数据、原始日志均可在上述四个归档文件中追溯。【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考