OpenBrep运行时架构审计：意图路由、任务管道与可观测性对照Agent Builder四维共识

OpenBrep 将 GDL 生成链路重构为完整的 runtime 体系：IntentRouter 实现意图分流、TaskPipeline 负责执行调度、Tracer 完成全程留痕，底层数据源基于 HSF 目录。本文结合源码、架构文档与 ADR，从 runtime 维度进行系统审计，并以当下 Agent Builder 领域的四项核心共识为参照，厘清已落地的最佳实践与仍须补足的差距。

一、意图路由器：非关键词匹配器，而是分层仲裁器

Agent Builder 共识强调“自主性需受控”与“灵活与安全的平衡”，OpenBrep 的 runtime/router.py 用 172 行轻量代码将其落地，风格克制清晰。

路由器以固定优先级执行仲裁：纯聊天 → ArchiCAD 错误日志正则锁定 DEBUG → modify/check 关键词 → create 关键词 → GDL 通用词 → 图像 → 是否加载项目 → LLM 兜底。每一步在前一步能判定时即短路，避免将简单请求丢给模型做不必要的模糊判断。最终 LLM 调用被 try/except 包裹，一旦模型异常，分类器会回退至 CHAT 状态，不会让流程崩溃。

●　确定性优先： 正则能判定则走正则，关键词能识别就走关键词，LLM 仅充当下游兜底，而非默认仲裁者。
●　上下文敏感： has_project 决定模糊输入降级为修改而非创建，has_image 将图像优先解释为参考建模。
●　故障安全： 分类器调用 LLM 失败不会导致系统性异常，系统回退到聊天状态，而非直接抛出错误。

核心判断： 让轻量信号吃下大部分分类任务，仅将 LLM 当作理解意图的辅助耳朵，而非决策大脑。共识中“低成本执行”的落点，正与“高优先级硬规则 + 软兜底”的高度结构化路由策略完全同构。

二、任务管道：不是简单的函数链，而是 Agent 生命周期容器

pipeline.py 全文 1132 行，充当 OpenBrep 的全量执行引擎。它将“agent 循环 + 工具调度 + 仲裁 + 留痕”融合进基于 dataclass 的契约（TaskRequest/TaskResult），使得 CLI、测试及未来 API server 等不同入口均可复现相同逻辑，避免流程被 Streamlit 等单一界面绑定。

管道启动后先进行意图分类（未指定 intent 时由路由器输出结论），接着按意图分派至五个 handler：CHAT、MODIFY/DEBUG/_handle_script_update、REPAIR、CREATE/IMAGE。其中 _handle_script_update 被 MODIFY/DEBUG/REPAIR 共享，因为它们都遵循“最小改动 + 静态检查 + 编译验证”的同一路线，差异仅在于指令的构造方式。

这里可以拆解出若干与 Agent Builder 共识高度对齐的具体设计：

▸　三重裁判门控： 每条生成路径都串联 Linter、StaticChecker 与 Compile 三道闸门。Linter 负责轻量错误自动修复（GDLLinter.fix），StaticChecker 捕获未定义符号与前向声明等问题并触发自动修复，Compile 若失败则重试一次自修复。Agent Builder 共识提倡的“只做微改，不经重生成”从一开始就融入项目，这与 SKILL.md 中 _MODIFY_SKILLS_PROMPT 的要求完全对应。

▸　分层注入与嵌套上下文： CREATE 路径注入受影响的脚本（affected_scripts），MODIFY 注入全部脚本。这正是 GDLAgent 上下文手术的核心策略：HSF 目录天然分散为多个文件，Agent 相应地将其拆分为“编辑上下文”与“只读背景”，与上下文手术理念高度一致。

▸　视觉前分析： CREATE/IMAGE 任务先用 analyze_reference_image 将图片转化为结构化描述，再与指令合并调用 LLM。分析失败则降级为直接传入图像，不会阻塞主流程。

▸　上下文类型分离： knowledge、skills、learned_error_skill 与 assistant_settings 作为四种独立注入源。knowledge 仅缓存一次，SkillsLoader 依指令检索，error learning 则从 work_dir 反向积累提示。这种设计与共识中“区分记忆类型”完全对应：程序性记忆（skills、editor settings）、语义性记忆（knowledge）、情景性记忆（error learning）各自独立可追踪。

三、追踪器：不是日志堆砌，而是观测基线

tracer.py 仅 57 行，但对照共识中“强化可观测性、透明、可审计、可回溯”的要求，其分量清晰可见：每次任务生成独立 JSON 文件，文件名携带微秒精度时间戳，task_id、intent、input_summary、success、scripts_generated、compile_pass 以及 error 全部在一次原子写入中落盘。

代码明确写有“never blocks execution”，trace 写入磁盘失败不影响任务返回结果。Tracer 与业务执行完全解耦，是“观测≠主流程”这一原则的落地实现。

此外，input_summary 截断为 200 字符，scripts_generated 只记录路径，plain_text 仅保留布尔标记，表明 Tracer 的定位是“索引＋关键字段回放”，而非全量 dump。配合 benchmark/ 目录，这些 trace 数据已经具备从生产环境提取后离线重放评测的潜质。

判断： 当前 Tracer 仅存入 task_id 与关键 flags，未保留完整 LLM I/O。若要进一步支持效果评估或 prompt 回归，必须将 request/response 摘要落盘。这是 OpenBrep 从“够用”迈向“可评测”的必经升级。

四、四维共识下的总体评估

以 Agent Builder 共识的四条主线——“记忆即系统 / 自主性需受控 / 架构即组织学 / 体验即生产力”——逐一对照打分：

▸　记忆即系统： HSF 目录是事实文件，ADR 0003 将 Skills 提升为可追踪输入，error learning 从 skills_text 增量聚合。此项对齐度高。

▸　自主性需受控： Router 优先级链 + GDL 三道门控（linter/static/compile）+ Tracer 不阻塞。完全对齐。

▸　架构即组织学： View/Controller/Service/Domain 分层明确；App.py 虽仍有 1588 行，但定位为兼容性薄层。整体对齐，但 App.py 体量偏大仍属技术债。

▸　体验即生产力： Streamlit GUI 作为主界面，所有逻辑都挂在 runtime 之后。对专业用户足够，但对零基础用户尚不够友好，仅部分对齐。

五、现存的缺口

第一处：ui/app.py 已膨胀至 1588 行。架构文档将其定义为“薄 wrapper + 兼容层”，但兼容层本身在持续增长。尽管 AGENTS.md 明确要求不要向 app.py 增加新逻辑，鲁棒性仍取决于团队是否能始终守住这条边界。

第二处：MockHSFCompiler 默认开启。Pipeline 的 _make_compiler 只有显式传入 HSFCompiler(Path) 时才会走真实编译器，其余场景全部返回 Mock，这意味着默认状态下 CompileResult 几乎总是 pass，导致裁判机制的最后一跳被轻易绕过。

第三处：LLM 的 I/O 未纳入 trace。当前 trace 仅包含 intent、脚本清单、编译结果标志，若要复盘“某个意图被 LLM 如何处理、为何选择了这一路径”，只能回看现场 prompt。共识所要求的“完整执行轨迹追踪”，在此粒度上尚显不足。

这三项问题并非同时爆发，但都属于“路由够轻、分层够严”之后的进阶水位：将 MockHSFCompiler 下沉为真实可执行验证，为 Trace 加入可配置的 LLM I/O 快照，并对 App.py 进行持续拆分、抽取出可独立启动的 Service。

六、给 Agent Builder 实践者的启示

▸　意图分类不要全部交给 LLM。 能用正则定义的就用正则完成，正则规则本身就是可测试的知识资产；LLM 只做兜底，不担任默认裁判。

▸　将领域环境转化为业务上下文类型。 HSF 文件天然具有“上层逻辑 + 下层实现”的层次，将它们拆成只读背景与可编辑上下文。映射到其他领域：文档项目可拆成只读参考与可编辑架构，代码项目同理。

▸　构建独立的观测路径。 Tracer 与主流程解耦，写入失败亦不抛错，这是从探针升级为可回放评测的起点。

▸　领域型 Agent 不可跳过真实裁判。 hsf2libpart 决定了 OpenBrep 能否真正交付，跳过它，Agent 就退化成了对话工具。在代码 Agent 中对应单元测试/类型检查，在写作 Agent 中对应目标读者的反谏机制。

七、下一步

本次审计仍属静态观察。要补完对 Agent Builder 的全面评估，还需完成三项动态验证：

▸　提取 trace 样本复演： 采集 50 个成功＋20 个失败样本，验证路由器路径频率与意图选择的一致性是否与架构文档结论吻合。

▸　在真实 HSFCompiler 配置下完成一轮编译报表。 Mock 环境下 trace 中的 compile_pass 几乎全部为 True，无法反验“编译路径”的实战价值。

▸　阅读 ui/app_shell 与 chat_render，从 GUI 侧证伪架构文档中“View 不实例化业务逻辑”的承诺。

三项补完动作之后，OpenBrep 才能从“实践的声音”跃迁为“可学习的案例”。共识强调“从静态设计到动态演进”，也正是此意：一个项目是否走在 Agent OS 的路径上，不看它宣称了什么架构，而看它是否能被他人复用、重构乃至推倒重建。

架构，终究是由那 1132 行之外的 run()、classify()、record() 推上去的。