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() 推上去的。