尧图网页设计 
A2UI 推理格式优化器Inference Format Optimizer基于 6 步优化工作流与 S_opt 决策模型迭代改进 LLM 推理格式【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui本文以eval/iterative_format_optimizer/skills/inference-format-optimizer/SKILL.md为核心系统讲解 A2UI 开源仓库中面向 LLM 推理格式Express、Atom、Elemental 等的迭代式评测与优化框架。你将掌握其 CLI 编排命令、6 步优化工作流、以S_opt复合评分为核心的决策护栏以及基于 Git Worktree 的多智能体并行优化协议可直接复用到你自己的格式迭代实验中。一、框架定位为什么要优化推理格式A2UI 是一套面向 Agent 的 UI 描述协议模型需要把用户意图翻译成符合目录catalogschema 的 UI 载荷。不同的推理格式inference format——例如 S-表达式风格的 Atom、类 DSL 的 Express、结构化的 Elemental——在 LLM 的生成准确率、延迟与 token 开销上差异显著。inference-format-optimizer这个 Skill 提供了一套可重复、可度量、可存档的程序化流程把改格式、跑评测、看指标、决定保留还是回退固化成 CLI 编排器 数学决策模型 子智能体协议从而让格式优化不再是拍脑袋的试错。从仓库源码结构看该框架由四层组成Skill 主文档SKILL.md本文核心提供 CLI 速查与 6 步工作流决策模型与协议references/下的 scoring_model.md、subagent_protocol.md、agent_instructions.mdCLI 编排脚本scripts/下的 optimize_format.py、compare_results.py、sync_history.py历史记忆库history_summary.md 与eval/iterative_format_optimizer/history/format/下的归档运行目录。优化目标对象位于agent_sdks/python/a2ui_agent/src/a2ui/inference_formats/experimental/每个格式目录下都包含compiler.py、parser.py、decompiler.py、prompt_generator.py、format.py等核心模块例如 atom/compiler.py、express/parser.py。二、Quick-Start统一 CLI 速查表所有执行脚本都位于 Skill 的scripts/目录下。SKILL.md 给出了一张可直接照抄的速查表动作可执行命令运行快速验证评测python scripts/optimize_format.py --format format运行完整评测套件python scripts/optimize_format.py --format format --full测试解析 / 编译python scripts/optimize_format.py --format format --compile (Card (Text \Hi\))与基线对比python scripts/compare_results.py --baseline eval/iterative_format_optimizer/baselines/format/unbounded_run_meta.json eval/iterative_format_optimizer/logs/temp_optimization/归档运行产物python scripts/optimize_format.py --format format --archive --hypothesis ... --status KEEP [--history-dir path]同步多 Worktree 历史python scripts/sync_history.py [--history-dir path]其中format的合法取值由 optimize_format.py 的--format参数校验限定为direct_json、express、elemental、atom四种策略。2.1 编排器optimize_format.py的完整参数从源码main()的 argparse 定义可见编排器支持以下参数参数默认值说明--format必填目标推理格式direct_json/express/elemental/atom--modelgoogle/gemini-3.8-flash评测模型标识--prompt无可多次传入只评测指定 prompt 子集用于针对性调试--sanityFalse快速冒烟检查2 个样本--fullFalse运行完整评测套件--save-baselineFalse把当前运行保存为该格式的基线--baseline-dir自动推导基线的读写目录--compile无测试编译一段格式载荷片段--decompile无测试反编译 A2UI v1.0 JSON 载荷--parse无测试把格式片段解析为原始 AST--archiveFalse把当前运行产物原子化归档到history/--hypothesis无归档运行的假设描述--statusKEEP决策状态KEEP/REVERT/Backtracked/Kept/Pending--notes无归档运行的定性说明--history-dir自动推导自定义历史目录--thinking-budget无推理模型的思考预算约束--epochs无每个 prompt 样本的评测轮次--temperature0.0评测模型的生成温度几个关键实现细节默认走快速子集而非全量当未指定--full、--sanity且无--prompt时默认只评测 5 个代表性 promptdogBreedGenerator、loginForm、settingsPage、productGallery、updateDataModel见 optimize_format.py以控制成本与迭代周期。并发上限脚本启动时设置os.environ[INSPECT_MAX_CONNECTIONS] 10对应 10 个并发评测任务optimize_format.py。评测调用链--compile/--parse/--decompile会短路退出直接调用 utils/format_tools.py 中的test_compile_snippet/test_parse_ast/test_decompile_payload常规评测则依次执行 pytest 单元测试utils/runner.py 的run_unit_tests、Inspect AI 评测run_evaluation、日志解析load_log_data、git diff 收集get_git_diff最终由 utils/reporter.py 生成 Markdown 优化报告。基线保存--save-baseline会把指标与逐样本数据写入baselines/format/budget_run_meta.json例如baselines/atom/unbounded_run_meta.json该文件包含schema_acc、quality_acc、code_tokens_median、reasoning_tokens_median、input_tokens_median、latency_seconds_median、epochs、total_samples及逐样本明细。2.2 速查命令的仓库级完整形态SKILL.md 的速查表使用了相对路径写法在实际仓库中从仓库根目录执行时请使用以下等价形式以 Atom 为例出自 references/agent_instructions.md 的 Quick-Command Cheatsheet# 测试 S-表达式编译 uv run python eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/optimize_format.py --format atom --compile (Card (Text \Hi\)) # 测试 S-表达式 AST 解析 uv run python eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/optimize_format.py --format atom --parse (Card (Text \Hi\)) # 测试反编译 uv run python eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/optimize_format.py --format atom --decompile {version:v1.0,...} # 快速子集评测 uv run python eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/optimize_format.py --format atom # 定向 prompt 评测 uv run python eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/optimize_format.py --format atom --prompt loginForm # 与基线对比 uv run python eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/compare_results.py --baseline eval/iterative_format_optimizer/baselines/atom/unbounded_run_meta.json eval/iterative_format_optimizer/logs/temp_optimization/ # 原子化归档 uv run python eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/optimize_format.py --format atom --archive --hypothesis ... --status KEEP # 里程碑完整校验 uv run python eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/optimize_format.py --format atom --full三、决策模型正确性护栏、效率上限与 S_opt 复合评分任何格式迭代都不能只看能不能跑通还必须回答两个问题准确率有没有掉效率有没有恶化该框架用三级决策模型来回答详见 references/scoring_model.md。3.1 正确性护栏不可协商每一个候选格式迭代都必须通过全部正确性护栏任何一条失败都必须回退Pytest 单元一致性必须PASS100% 单元测试通过算法 schema 通过率SchemaAcc输出载荷对目标目录 JSON schema 的通过率评分器为a2ui_scorer必须 $\ge$ 基线质量分QualityScore模型评分的语义意图匹配度measured_model_graded_qa必须 $\ge$ 基线。3.2 效率回归上限不可协商的回退触发器即使准确率持平甚至达到 100%只要以下任一上限被突破必须回退代码输出 token相对基线/上一轮增长 5%防止格式膨胀流式延迟Non-reasoning Output Time增长 10%防止代码流式输出成为瓶颈推理 token增长 15%防止 prompt 指令搜索空间模糊。3.3 复合优化分 $S_{\text{opt}}$$S_{\text{opt}}$ 在准确率收益与 token、延迟开销之间取平衡其公式为$$ S_{\text{opt}} 0.50 \cdot \text{SchemaAcc} 0.30 \cdot \text{QualityScore} - 0.15 \cdot \left(\frac{\text{CodeTok}}{\text{BaseCodeTok}}\right) - 0.05 \cdot \left(\frac{\text{ReasonTok}}{\text{BaseReasonTok}}\right) - 0.03 \cdot \left(\frac{\text{InputTok}}{\text{BaseInputTok}}\right) $$决策规则若 $S_{\text{opt}}(\text{Current}) S_{\text{opt}}(\text{Baseline})$ →保留改动--status KEEP若 $S_{\text{opt}}(\text{Current}) \le S_{\text{opt}}(\text{Baseline})$ →回退改动--status REVERT。从源码看该公式在 compare_results.py 的compute_s_opt()中实现准确率以 0.50/0.30 加权贡献正分三组 token 比值以 0.15/0.05/0.03 权重作为负项结果保留三位小数。对比表格的生成逻辑generate_markdown_table会输出 Baseline 行与每个对比运行行包含Score (S_opt)、Schema Acc (Delta)、Quality Score (Delta)、Parallel Wall Latency (Delta)、Non-reasoning Output Time、Input/Reasoning/Code Output Tok等列并附带详细的 Metric Definitions Derivation Key 说明compare_results.py。3.4 对比器的两大细节1:1 基线样本过滤当用验证子集对比全量基线时compare_results.py会自动把基线指标过滤到与当前运行样本 ID 完全匹配的子集保证 1:1 可比对应 compare_results.py 的filter_sample_ids机制。中位数 vs 均值默认统计中位数对离群更稳健传入--average可切换为均值。--output path可把生成的 Markdown 对比表保存为文件。四、6 步优化工作流SKILL.md 核心流程SKILL.md 定义的标准优化循环如下分析历史检查eval/iterative_format_optimizer/history/format/下的历史运行并阅读eval/iterative_format_optimizer/history_summary.md避免重复尝试已被回退的假设实现假设修改agent_sdks/python/a2ui_agent/src/a2ui/inference_formats/experimental/format/下的compiler.py、prompt_generator.py或parser.py运行单元一致性测试验证改动通过 pytest 单元测试执行基准评测运行python scripts/optimize_format.py --format format评估决策规则必须通过 Pytest 并保持基线准确率代码输出 token 不得膨胀 5%若复合分 $S_{\text{opt}}$ 提升则保留改动否则回退git reset --hard HEAD归档与同步用--archive归档运行并用python scripts/sync_history.py更新历史索引。4.1 展开每一步的实操细节references/agent_instructions.md 把这 6 步扩展为带明确命令的完整循环其中几个关键点值得单独展开Step 1分析历史与提出假设先读eval/iterative_format_optimizer/history_summary.md并扫描eval/iterative_format_optimizer/history/下最近的run_meta.json了解每个实验的假设、状态KEEP vs REVERT与代码 diff反重复约束严禁重试已被测试并回退过的假设、prompt 规则改动或代码修改建议同时查看eval/baselines/{format}/results.json中的基线失败日志定位未解决的失败模式如嵌套布局错误、悬空字符串引用、缺失可选属性提出最小化假设例如用显式关键字语法替代位置参数占位符可消除容器嵌套歧义。Step 2实现与验证代码改动集中在三类文件系统 prompt 与格式规则prompt_generator.py、parser/compiler/decompiler 代码experimental/format/下先本地跑uv run pytest agent_sdks/python/a2ui_agent/tests/失败分类处理Prompt 回归只改了 prompt/template 导致测试挂 → 立即回退 prompt 改动Parser/Compiler 回归破坏了既有编译器行为 → 修复代码或回退格式能力演进有意扩展语法导致旧测试失败 → 更新对应测试以覆盖新能力。Step 3运行评测uv run python eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/optimize_format.py --format format --model model默认在 5 个代表性 prompt 的验证子集上运行针对特定失败可加--prompt prompt_name缩小范围。Step 4评估指标并与基线对比uv run python eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/compare_results.py --baseline eval/iterative_format_optimizer/baselines/format/unbounded_run_meta.json current_run_dir_or_eval_log逐项核对生成的 Markdown 表Pytest 一致性必须PASSSchema Acc (Delta)与Quality Score (Delta)不得回退Median Code Output Tok、Non-reasoning Output Time (Median)、Median Input Tok、Parallel Wall Latency (Delta)用于效率评估。Step 5晋级或回滚决策按 4 条规则决策对应 agent_instructions.mdRule 1正确性不可协商Schema Acc与Quality Score不得低于基线否则立即用optimize_format.py --format format --revert回滚Rule 2效率上限不可协商Median Code Output Tok增长 5%、Non-reasoning Output Time增长 10%、Median Reasoning Tok增长 15% 时必回退Rule 3复合分 $S_{\text{opt}}$当前 $S_{\text{opt}}$ 基线则 KEEP否则 REVERTRule 4 隐含在归档流程中KEEP 时提交代码与测试。Step 6归档迭代运行推荐直接使用--archive原子化归档目录命名run_三位索引_commit_sha_slugified_summary例如run_003_a8f9c1b_fix_brackets。归档目录包含 4 个自包含产物见 references/inference_format_iteration.mdpatch.diff所有 compiler/decompiler/prompt 改动的完整 git diff可随时git apply patch.diff复现report.md带代码 diff、通过/失败表格与错误堆栈的 Markdown 优化报告run_meta.json机器可读元数据假设、状态 KEEP/REVERT、commit SHA、定性说明results.json完整 Inspect AI 执行日志数据。五、Catalog 无关性约束优化绝不能写死组件名这是该框架最重要的硬性工程约束之一agent_instructions.md所有 compiler / decompiler / prompt generator / 系统 prompt 指令模板必须 100% catalog 无关代码中禁止硬编码组件名如Card、Column、Row、List、Button或目录专属属性名如children、child、trigger、content、template、items禁止目录专属的 prompt 规则或示例ATOM_RULES、EXPRESS_RULES、ELEMENTAL_RULES等指令块不得假设特定组件/属性的规则必须保持格式文法本位使用通用语法占位符如(ComponentName :key val child1 ...)动态 schema 检视必须通过CatalogSchemaHelper动态检视目录 schema 的$ref类型如common_types.json#/$defs/ChildList、#/$defs/Child、#/$defs/Action并动态生成签名合成目录验证所有改动必须通过 fuzz 合成目录单元测试test_fuzzed_synthetic_catalog_agnosticism证明其在自定义/fuzz 目录上同样可用。这条约束对应源码中每个格式模块都带独立prompt_generator.py与compiler.py的设计例如 atom/prompt_generator.py 负责按目录 schema 动态生成组件签名提示atom/compiler.py 的_compile_component/_compile_event/_compile_template/_resolve_val等私有方法在编译期做 AST 规范化但都不绑定具体组件名。六、多智能体并行Git Worktree 隔离与子智能体协议当多个优化 pass 需要并行推进时单线程串行显然太慢。该框架通过 references/subagent_protocol.md 定义了完整的子智能体工作树协议。6.1 工作树隔离与命名为避免代码冲突与竞态每个优化 pass 在独立的 Git worktree 分支中运行分支名模式opt-format-passN例如opt-express-pass6目录位置worktrees/opt-format-passN创建命令git worktree add -b opt-express-pass6 /path/to/a2ui/worktrees/opt-express-pass6 optimize_express6.2 子智能体启动与 5 步执行序列父智能体通过invoke_subagent串行启动子智能体TypeNameselfRoleExpress Pass N OptimizerWorkspaceinherit。每个子智能体在自己的 worktree 内必须执行 5 步序列实现假设编辑目标compiler.py/prompt_generator.py/parser.py跑 pytestPYTHONPATHagent_sdks/python/a2ui_agent/src:agent_sdks/python/a2ui_core/src venv/bin/python -m pytest agent_sdks/python/a2ui_agent/tests/format/跑评测基准optimize_format.py --format format评估决策规则并归档若单元测试失败 / Quality Score 回退 / 输出 token 膨胀 5%git reset --hard HEAD optimize_format.py --format format --archive --hypothesis ... --status REVERT --notes reason否则optimize_format.py --format format --archive --hypothesis ... --status KEEP --notes summary同步历史索引sync_history.py。templates/subagent_prompt.md提供了可直接套用的子智能体 prompt 模板含{{PASS_NUM}}、{{FORMAT}}、{{WORKTREE_PATH}}、{{TARGET_FILE}}、{{HYPOTHESIS}}占位符。6.3 父智能体的生命周期管理子智能体完成 pass 后父智能体需要合并与提交若 pass 被 KEEP把修改的源码与单元测试拷回主分支并立即提交git commit -m feat(format): Pass N summary同时提交更新的历史日志与汇总表终止子智能体调用manage_subagents(Actionkill, ConversationIds[...])防止后台资源累积清理 worktreegit worktree remove --force ...并删除临时分支git branch -D ...。6.4 两层级验证与无冲突合并agent_instructions.md 定义了两层级晋级路径Tier 1子智能体快速内环子智能体在快速验证子集上做快速假设迭代达到决策规则后归档并提交分支作为Milestone Candidate同步多 worktree 历史sync_history.py收集各并行 worktree 的归档运行到主历史Tier 2外环里程碑全量校验合入main前用optimize_format.py --format format --model model --full跑全量套件PR 合入把 worktree 分支提 PR 合并回主仓库。由于归档运行目录自包含分支合并时历史运行目录可无冲突合并后续从main启动的 Agent 会自动继承全体历史记忆。sync_history.py的核心价值在于两个机制见 sync_history.py零冲突 ID 重索引检测并行 worktree 间的 run ID 冲突并自动顺序重排_get_max_run_id 冲突时max_id1重新编号主索引重建通过regenerate_master_index自动重建eval/iterative_format_optimizer/history_summary.md维护全体历史实验的集体记忆。七、终止条件什么时候停止迭代agent_instructions.md 定义了 4 个终止触发条件达成目标全量套件达到 100% 通过率平台期连续 3 轮不同假设均无准确率提升达到最大迭代次数已完成 10 轮卡住/受阻遇到基础设施错误或 prompt/编译器调优无法解决的冲突需求时停止并向人类操作者报告。八、实战佐证历史运行库是如何说话的eval/iterative_format_optimizer/history_summary.md是这套框架运转结果的直接证据。以 Atom 格式为例历史表记录了数十轮假设的完整生命周期例如atom/003KEEP精简ATOM_RULES语法规则后推理 token 较 run_002 减少 13.3%整体 42.6%代码输出 token 减少 31.6%延迟降低 16.0%$S_{\text{opt}}$ 从 0.600 提升到 0.654atom/013Backtracked自动包装字面量字符串虽使 Quality Score 保持 100%、推理 token 减少 25.7%但代码输出 token 增长 23.8%触发 Rule 2 效率上限被回退atom/014Backtracked精简签名描述虽让输入 token 减少 46.3%但 Schema Acc 与 Quality Score 从 100% 回退到 75%触发 Rule 1 正确性护栏被回退atom/031KEEP编译器侧事件上下文参数规范化后推理 token 减少 9.7%、代码输出 token 减少 14.9%、非推理输出时间减少 21.9%$S_{\text{opt}}$ 从 0.600 提升到 0.627express/001~005早期 Express 假设因 Quality Score 回退或单元测试失败而全部 Backtracked说明先看历史、再提假设的反重复约束在实际运行中的价值。这些历史条目与 baselines/atom/unbounded_run_meta.json 中的数值如schema_acc: 0.937、quality_acc: 0.831、code_tokens_median: 242.0、total_samples: 255共同构成了可追溯、可复算的集体记忆是后续迭代的决策依据。九、反模式与操作护栏agent_instructions.md 明确禁止三类反模式禁止写临时python -c脚本去 importAtomCompiler或测试 S-表达式——请改用--compile/--parse禁止手工 5 步 shell 归档mkdir、cp、git diff patch.diff的手工组合——请用optimize_format.py --archive禁止重试已回退的假设——请先查看eval/iterative_format_optimizer/history_summary.md。这三条护栏的共同目的是让优化过程可复现、可审计、可增量继承而不是依赖临时脚本与手工操作。十、架构全景与进一步阅读整个框架的运行时拓扑可概括为自主子智能体 → 独立 worktree → 修改 prompt/compiler 代码 → pytest →optimize_format.py评测 →compare_results.py计算 delta 与 $S_{\text{opt}}$ → 决策 KEEP/REVERT →--archive归档 →sync_history.py同步主历史索引具体流程图见 references/inference_format_iteration.md 中的 mermaid 图表。按主题继续深入仓库推荐以下入口Skill 主文档与子文档SKILL.md、scoring_model.md、subagent_protocol.md、agent_instructions.md、inference_format_iteration.md、subagent_prompt.mdCLI 脚本optimize_format.py、compare_results.py、sync_history.py、utils/runner.py、utils/archiver.py、utils/reporter.py、utils/format_tools.py被优化的格式实现experimental/atom、experimental/express、experimental/elemental历史记忆与基线history_summary.md、eval/iterative_format_optimizer/history/format/、eval/iterative_format_optimizer/baselines/format/Skill 单元测试scripts/tests/覆盖optimize_format.py、compare_results.py、sync_history.py与utils的核心逻辑。提示本文所述命令均以查看、安装、运行、配置为前提仓库为只读实际执行评测前请先确认已安装uv、pytest 与 Inspect AI 等依赖并准备好目标格式的单元测试与基线文件。【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 A2UI 推理格式优化器（Inference Format Optimizer）：基于 6 步优化工作流与 S_opt 决策模型迭代改进 LLM 推理格式
A2UI 推理格式优化器Inference Format Optimizer基于 6 步优化工作流与 S_opt 决策模型迭代改进 LLM 推理格式【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui本文以eval/iterative_format_optimizer/skills/inference-format-optimizer/SKILL.md为核心系统讲解 A2UI 开源仓库中面向 LLM 推理格式Express、Atom、Elemental 等的迭代式评测与优化框架。你将掌握其 CLI 编排命令、6 步优化工作流、以S_opt复合评分为核心的决策护栏以及基于 Git Worktree 的多智能体并行优化协议可直接复用到你自己的格式迭代实验中。一、框架定位为什么要优化推理格式A2UI 是一套面向 Agent 的 UI 描述协议模型需要把用户意图翻译成符合目录catalogschema 的 UI 载荷。不同的推理格式inference format——例如 S-表达式风格的 Atom、类 DSL 的 Express、结构化的 Elemental——在 LLM 的生成准确率、延迟与 token 开销上差异显著。inference-format-optimizer这个 Skill 提供了一套可重复、可度量、可存档的程序化流程把改格式、跑评测、看指标、决定保留还是回退固化成 CLI 编排器 数学决策模型 子智能体协议从而让格式优化不再是拍脑袋的试错。从仓库源码结构看该框架由四层组成Skill 主文档SKILL.md本文核心提供 CLI 速查与 6 步工作流决策模型与协议references/下的 scoring_model.md、subagent_protocol.md、agent_instructions.mdCLI 编排脚本scripts/下的 optimize_format.py、compare_results.py、sync_history.py历史记忆库history_summary.md 与eval/iterative_format_optimizer/history/format/下的归档运行目录。优化目标对象位于agent_sdks/python/a2ui_agent/src/a2ui/inference_formats/experimental/每个格式目录下都包含compiler.py、parser.py、decompiler.py、prompt_generator.py、format.py等核心模块例如 atom/compiler.py、express/parser.py。二、Quick-Start统一 CLI 速查表所有执行脚本都位于 Skill 的scripts/目录下。SKILL.md 给出了一张可直接照抄的速查表动作可执行命令运行快速验证评测python scripts/optimize_format.py --format format运行完整评测套件python scripts/optimize_format.py --format format --full测试解析 / 编译python scripts/optimize_format.py --format format --compile (Card (Text \Hi\))与基线对比python scripts/compare_results.py --baseline eval/iterative_format_optimizer/baselines/format/unbounded_run_meta.json eval/iterative_format_optimizer/logs/temp_optimization/归档运行产物python scripts/optimize_format.py --format format --archive --hypothesis ... --status KEEP [--history-dir path]同步多 Worktree 历史python scripts/sync_history.py [--history-dir path]其中format的合法取值由 optimize_format.py 的--format参数校验限定为direct_json、express、elemental、atom四种策略。2.1 编排器optimize_format.py的完整参数从源码main()的 argparse 定义可见编排器支持以下参数参数默认值说明--format必填目标推理格式direct_json/express/elemental/atom--modelgoogle/gemini-3.8-flash评测模型标识--prompt无可多次传入只评测指定 prompt 子集用于针对性调试--sanityFalse快速冒烟检查2 个样本--fullFalse运行完整评测套件--save-baselineFalse把当前运行保存为该格式的基线--baseline-dir自动推导基线的读写目录--compile无测试编译一段格式载荷片段--decompile无测试反编译 A2UI v1.0 JSON 载荷--parse无测试把格式片段解析为原始 AST--archiveFalse把当前运行产物原子化归档到history/--hypothesis无归档运行的假设描述--statusKEEP决策状态KEEP/REVERT/Backtracked/Kept/Pending--notes无归档运行的定性说明--history-dir自动推导自定义历史目录--thinking-budget无推理模型的思考预算约束--epochs无每个 prompt 样本的评测轮次--temperature0.0评测模型的生成温度几个关键实现细节默认走快速子集而非全量当未指定--full、--sanity且无--prompt时默认只评测 5 个代表性 promptdogBreedGenerator、loginForm、settingsPage、productGallery、updateDataModel见 optimize_format.py以控制成本与迭代周期。并发上限脚本启动时设置os.environ[INSPECT_MAX_CONNECTIONS] 10对应 10 个并发评测任务optimize_format.py。评测调用链--compile/--parse/--decompile会短路退出直接调用 utils/format_tools.py 中的test_compile_snippet/test_parse_ast/test_decompile_payload常规评测则依次执行 pytest 单元测试utils/runner.py 的run_unit_tests、Inspect AI 评测run_evaluation、日志解析load_log_data、git diff 收集get_git_diff最终由 utils/reporter.py 生成 Markdown 优化报告。基线保存--save-baseline会把指标与逐样本数据写入baselines/format/budget_run_meta.json例如baselines/atom/unbounded_run_meta.json该文件包含schema_acc、quality_acc、code_tokens_median、reasoning_tokens_median、input_tokens_median、latency_seconds_median、epochs、total_samples及逐样本明细。2.2 速查命令的仓库级完整形态SKILL.md 的速查表使用了相对路径写法在实际仓库中从仓库根目录执行时请使用以下等价形式以 Atom 为例出自 references/agent_instructions.md 的 Quick-Command Cheatsheet# 测试 S-表达式编译 uv run python eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/optimize_format.py --format atom --compile (Card (Text \Hi\)) # 测试 S-表达式 AST 解析 uv run python eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/optimize_format.py --format atom --parse (Card (Text \Hi\)) # 测试反编译 uv run python eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/optimize_format.py --format atom --decompile {version:v1.0,...} # 快速子集评测 uv run python eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/optimize_format.py --format atom # 定向 prompt 评测 uv run python eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/optimize_format.py --format atom --prompt loginForm # 与基线对比 uv run python eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/compare_results.py --baseline eval/iterative_format_optimizer/baselines/atom/unbounded_run_meta.json eval/iterative_format_optimizer/logs/temp_optimization/ # 原子化归档 uv run python eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/optimize_format.py --format atom --archive --hypothesis ... --status KEEP # 里程碑完整校验 uv run python eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/optimize_format.py --format atom --full三、决策模型正确性护栏、效率上限与 S_opt 复合评分任何格式迭代都不能只看能不能跑通还必须回答两个问题准确率有没有掉效率有没有恶化该框架用三级决策模型来回答详见 references/scoring_model.md。3.1 正确性护栏不可协商每一个候选格式迭代都必须通过全部正确性护栏任何一条失败都必须回退Pytest 单元一致性必须PASS100% 单元测试通过算法 schema 通过率SchemaAcc输出载荷对目标目录 JSON schema 的通过率评分器为a2ui_scorer必须 $\ge$ 基线质量分QualityScore模型评分的语义意图匹配度measured_model_graded_qa必须 $\ge$ 基线。3.2 效率回归上限不可协商的回退触发器即使准确率持平甚至达到 100%只要以下任一上限被突破必须回退代码输出 token相对基线/上一轮增长 5%防止格式膨胀流式延迟Non-reasoning Output Time增长 10%防止代码流式输出成为瓶颈推理 token增长 15%防止 prompt 指令搜索空间模糊。3.3 复合优化分 $S_{\text{opt}}$$S_{\text{opt}}$ 在准确率收益与 token、延迟开销之间取平衡其公式为$$ S_{\text{opt}} 0.50 \cdot \text{SchemaAcc} 0.30 \cdot \text{QualityScore} - 0.15 \cdot \left(\frac{\text{CodeTok}}{\text{BaseCodeTok}}\right) - 0.05 \cdot \left(\frac{\text{ReasonTok}}{\text{BaseReasonTok}}\right) - 0.03 \cdot \left(\frac{\text{InputTok}}{\text{BaseInputTok}}\right) $$决策规则若 $S_{\text{opt}}(\text{Current}) S_{\text{opt}}(\text{Baseline})$ →保留改动--status KEEP若 $S_{\text{opt}}(\text{Current}) \le S_{\text{opt}}(\text{Baseline})$ →回退改动--status REVERT。从源码看该公式在 compare_results.py 的compute_s_opt()中实现准确率以 0.50/0.30 加权贡献正分三组 token 比值以 0.15/0.05/0.03 权重作为负项结果保留三位小数。对比表格的生成逻辑generate_markdown_table会输出 Baseline 行与每个对比运行行包含Score (S_opt)、Schema Acc (Delta)、Quality Score (Delta)、Parallel Wall Latency (Delta)、Non-reasoning Output Time、Input/Reasoning/Code Output Tok等列并附带详细的 Metric Definitions Derivation Key 说明compare_results.py。3.4 对比器的两大细节1:1 基线样本过滤当用验证子集对比全量基线时compare_results.py会自动把基线指标过滤到与当前运行样本 ID 完全匹配的子集保证 1:1 可比对应 compare_results.py 的filter_sample_ids机制。中位数 vs 均值默认统计中位数对离群更稳健传入--average可切换为均值。--output path可把生成的 Markdown 对比表保存为文件。四、6 步优化工作流SKILL.md 核心流程SKILL.md 定义的标准优化循环如下分析历史检查eval/iterative_format_optimizer/history/format/下的历史运行并阅读eval/iterative_format_optimizer/history_summary.md避免重复尝试已被回退的假设实现假设修改agent_sdks/python/a2ui_agent/src/a2ui/inference_formats/experimental/format/下的compiler.py、prompt_generator.py或parser.py运行单元一致性测试验证改动通过 pytest 单元测试执行基准评测运行python scripts/optimize_format.py --format format评估决策规则必须通过 Pytest 并保持基线准确率代码输出 token 不得膨胀 5%若复合分 $S_{\text{opt}}$ 提升则保留改动否则回退git reset --hard HEAD归档与同步用--archive归档运行并用python scripts/sync_history.py更新历史索引。4.1 展开每一步的实操细节references/agent_instructions.md 把这 6 步扩展为带明确命令的完整循环其中几个关键点值得单独展开Step 1分析历史与提出假设先读eval/iterative_format_optimizer/history_summary.md并扫描eval/iterative_format_optimizer/history/下最近的run_meta.json了解每个实验的假设、状态KEEP vs REVERT与代码 diff反重复约束严禁重试已被测试并回退过的假设、prompt 规则改动或代码修改建议同时查看eval/baselines/{format}/results.json中的基线失败日志定位未解决的失败模式如嵌套布局错误、悬空字符串引用、缺失可选属性提出最小化假设例如用显式关键字语法替代位置参数占位符可消除容器嵌套歧义。Step 2实现与验证代码改动集中在三类文件系统 prompt 与格式规则prompt_generator.py、parser/compiler/decompiler 代码experimental/format/下先本地跑uv run pytest agent_sdks/python/a2ui_agent/tests/失败分类处理Prompt 回归只改了 prompt/template 导致测试挂 → 立即回退 prompt 改动Parser/Compiler 回归破坏了既有编译器行为 → 修复代码或回退格式能力演进有意扩展语法导致旧测试失败 → 更新对应测试以覆盖新能力。Step 3运行评测uv run python eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/optimize_format.py --format format --model model默认在 5 个代表性 prompt 的验证子集上运行针对特定失败可加--prompt prompt_name缩小范围。Step 4评估指标并与基线对比uv run python eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/compare_results.py --baseline eval/iterative_format_optimizer/baselines/format/unbounded_run_meta.json current_run_dir_or_eval_log逐项核对生成的 Markdown 表Pytest 一致性必须PASSSchema Acc (Delta)与Quality Score (Delta)不得回退Median Code Output Tok、Non-reasoning Output Time (Median)、Median Input Tok、Parallel Wall Latency (Delta)用于效率评估。Step 5晋级或回滚决策按 4 条规则决策对应 agent_instructions.mdRule 1正确性不可协商Schema Acc与Quality Score不得低于基线否则立即用optimize_format.py --format format --revert回滚Rule 2效率上限不可协商Median Code Output Tok增长 5%、Non-reasoning Output Time增长 10%、Median Reasoning Tok增长 15% 时必回退Rule 3复合分 $S_{\text{opt}}$当前 $S_{\text{opt}}$ 基线则 KEEP否则 REVERTRule 4 隐含在归档流程中KEEP 时提交代码与测试。Step 6归档迭代运行推荐直接使用--archive原子化归档目录命名run_三位索引_commit_sha_slugified_summary例如run_003_a8f9c1b_fix_brackets。归档目录包含 4 个自包含产物见 references/inference_format_iteration.mdpatch.diff所有 compiler/decompiler/prompt 改动的完整 git diff可随时git apply patch.diff复现report.md带代码 diff、通过/失败表格与错误堆栈的 Markdown 优化报告run_meta.json机器可读元数据假设、状态 KEEP/REVERT、commit SHA、定性说明results.json完整 Inspect AI 执行日志数据。五、Catalog 无关性约束优化绝不能写死组件名这是该框架最重要的硬性工程约束之一agent_instructions.md所有 compiler / decompiler / prompt generator / 系统 prompt 指令模板必须 100% catalog 无关代码中禁止硬编码组件名如Card、Column、Row、List、Button或目录专属属性名如children、child、trigger、content、template、items禁止目录专属的 prompt 规则或示例ATOM_RULES、EXPRESS_RULES、ELEMENTAL_RULES等指令块不得假设特定组件/属性的规则必须保持格式文法本位使用通用语法占位符如(ComponentName :key val child1 ...)动态 schema 检视必须通过CatalogSchemaHelper动态检视目录 schema 的$ref类型如common_types.json#/$defs/ChildList、#/$defs/Child、#/$defs/Action并动态生成签名合成目录验证所有改动必须通过 fuzz 合成目录单元测试test_fuzzed_synthetic_catalog_agnosticism证明其在自定义/fuzz 目录上同样可用。这条约束对应源码中每个格式模块都带独立prompt_generator.py与compiler.py的设计例如 atom/prompt_generator.py 负责按目录 schema 动态生成组件签名提示atom/compiler.py 的_compile_component/_compile_event/_compile_template/_resolve_val等私有方法在编译期做 AST 规范化但都不绑定具体组件名。六、多智能体并行Git Worktree 隔离与子智能体协议当多个优化 pass 需要并行推进时单线程串行显然太慢。该框架通过 references/subagent_protocol.md 定义了完整的子智能体工作树协议。6.1 工作树隔离与命名为避免代码冲突与竞态每个优化 pass 在独立的 Git worktree 分支中运行分支名模式opt-format-passN例如opt-express-pass6目录位置worktrees/opt-format-passN创建命令git worktree add -b opt-express-pass6 /path/to/a2ui/worktrees/opt-express-pass6 optimize_express6.2 子智能体启动与 5 步执行序列父智能体通过invoke_subagent串行启动子智能体TypeNameselfRoleExpress Pass N OptimizerWorkspaceinherit。每个子智能体在自己的 worktree 内必须执行 5 步序列实现假设编辑目标compiler.py/prompt_generator.py/parser.py跑 pytestPYTHONPATHagent_sdks/python/a2ui_agent/src:agent_sdks/python/a2ui_core/src venv/bin/python -m pytest agent_sdks/python/a2ui_agent/tests/format/跑评测基准optimize_format.py --format format评估决策规则并归档若单元测试失败 / Quality Score 回退 / 输出 token 膨胀 5%git reset --hard HEAD optimize_format.py --format format --archive --hypothesis ... --status REVERT --notes reason否则optimize_format.py --format format --archive --hypothesis ... --status KEEP --notes summary同步历史索引sync_history.py。templates/subagent_prompt.md提供了可直接套用的子智能体 prompt 模板含{{PASS_NUM}}、{{FORMAT}}、{{WORKTREE_PATH}}、{{TARGET_FILE}}、{{HYPOTHESIS}}占位符。6.3 父智能体的生命周期管理子智能体完成 pass 后父智能体需要合并与提交若 pass 被 KEEP把修改的源码与单元测试拷回主分支并立即提交git commit -m feat(format): Pass N summary同时提交更新的历史日志与汇总表终止子智能体调用manage_subagents(Actionkill, ConversationIds[...])防止后台资源累积清理 worktreegit worktree remove --force ...并删除临时分支git branch -D ...。6.4 两层级验证与无冲突合并agent_instructions.md 定义了两层级晋级路径Tier 1子智能体快速内环子智能体在快速验证子集上做快速假设迭代达到决策规则后归档并提交分支作为Milestone Candidate同步多 worktree 历史sync_history.py收集各并行 worktree 的归档运行到主历史Tier 2外环里程碑全量校验合入main前用optimize_format.py --format format --model model --full跑全量套件PR 合入把 worktree 分支提 PR 合并回主仓库。由于归档运行目录自包含分支合并时历史运行目录可无冲突合并后续从main启动的 Agent 会自动继承全体历史记忆。sync_history.py的核心价值在于两个机制见 sync_history.py零冲突 ID 重索引检测并行 worktree 间的 run ID 冲突并自动顺序重排_get_max_run_id 冲突时max_id1重新编号主索引重建通过regenerate_master_index自动重建eval/iterative_format_optimizer/history_summary.md维护全体历史实验的集体记忆。七、终止条件什么时候停止迭代agent_instructions.md 定义了 4 个终止触发条件达成目标全量套件达到 100% 通过率平台期连续 3 轮不同假设均无准确率提升达到最大迭代次数已完成 10 轮卡住/受阻遇到基础设施错误或 prompt/编译器调优无法解决的冲突需求时停止并向人类操作者报告。八、实战佐证历史运行库是如何说话的eval/iterative_format_optimizer/history_summary.md是这套框架运转结果的直接证据。以 Atom 格式为例历史表记录了数十轮假设的完整生命周期例如atom/003KEEP精简ATOM_RULES语法规则后推理 token 较 run_002 减少 13.3%整体 42.6%代码输出 token 减少 31.6%延迟降低 16.0%$S_{\text{opt}}$ 从 0.600 提升到 0.654atom/013Backtracked自动包装字面量字符串虽使 Quality Score 保持 100%、推理 token 减少 25.7%但代码输出 token 增长 23.8%触发 Rule 2 效率上限被回退atom/014Backtracked精简签名描述虽让输入 token 减少 46.3%但 Schema Acc 与 Quality Score 从 100% 回退到 75%触发 Rule 1 正确性护栏被回退atom/031KEEP编译器侧事件上下文参数规范化后推理 token 减少 9.7%、代码输出 token 减少 14.9%、非推理输出时间减少 21.9%$S_{\text{opt}}$ 从 0.600 提升到 0.627express/001~005早期 Express 假设因 Quality Score 回退或单元测试失败而全部 Backtracked说明先看历史、再提假设的反重复约束在实际运行中的价值。这些历史条目与 baselines/atom/unbounded_run_meta.json 中的数值如schema_acc: 0.937、quality_acc: 0.831、code_tokens_median: 242.0、total_samples: 255共同构成了可追溯、可复算的集体记忆是后续迭代的决策依据。九、反模式与操作护栏agent_instructions.md 明确禁止三类反模式禁止写临时python -c脚本去 importAtomCompiler或测试 S-表达式——请改用--compile/--parse禁止手工 5 步 shell 归档mkdir、cp、git diff patch.diff的手工组合——请用optimize_format.py --archive禁止重试已回退的假设——请先查看eval/iterative_format_optimizer/history_summary.md。这三条护栏的共同目的是让优化过程可复现、可审计、可增量继承而不是依赖临时脚本与手工操作。十、架构全景与进一步阅读整个框架的运行时拓扑可概括为自主子智能体 → 独立 worktree → 修改 prompt/compiler 代码 → pytest →optimize_format.py评测 →compare_results.py计算 delta 与 $S_{\text{opt}}$ → 决策 KEEP/REVERT →--archive归档 →sync_history.py同步主历史索引具体流程图见 references/inference_format_iteration.md 中的 mermaid 图表。按主题继续深入仓库推荐以下入口Skill 主文档与子文档SKILL.md、scoring_model.md、subagent_protocol.md、agent_instructions.md、inference_format_iteration.md、subagent_prompt.mdCLI 脚本optimize_format.py、compare_results.py、sync_history.py、utils/runner.py、utils/archiver.py、utils/reporter.py、utils/format_tools.py被优化的格式实现experimental/atom、experimental/express、experimental/elemental历史记忆与基线history_summary.md、eval/iterative_format_optimizer/history/format/、eval/iterative_format_optimizer/baselines/format/Skill 单元测试scripts/tests/覆盖optimize_format.py、compare_results.py、sync_history.py与utils的核心逻辑。提示本文所述命令均以查看、安装、运行、配置为前提仓库为只读实际执行评测前请先确认已安装uv、pytest 与 Inspect AI 等依赖并准备好目标格式的单元测试与基线文件。【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考