有 Mermaid 和 Structurizr 还不够吗？Birdview 在 AI Coding 中补上了什么

摘要如果一个团队已经在 Markdown 中维护 Mermaid 图或者用 Structurizr DSL 建立了正式的 C4 架构模型再引入 Birdview 很容易被理解成重复建设不都是用节点和连线描述系统吗我认为这个问题必须从“谁维护什么、在什么时候使用”来回答。Mermaid 是成熟的文本绘图工具它让流程图、时序图、类图、状态图和架构图能够和文档、代码一起版本化Structurizr 是面向 C4 模型的 models-as-code 工具团队可以从一个架构模型生成系统上下文、容器、组件、动态和部署等多类视图。它们非常适合表达团队希望长期维护的系统知识。Birdview 的职责更短暂当 AI Agent 即将执行某次修改时它要求 Agent 基于当前源码和项目规则声明自己看到的模块、归属、关系和证据再将本次任务的范围、目标、文件和验证计划覆盖到同一张地图上。用户确认方案后才实施结束时记录实际检查。因此Birdview 不应替换 Mermaid 的绘图生态也不应自称 Structurizr 的完整 C4 替代品它补充的是“权威架构文档”和“真实代码修改”之间容易被忽略的一层Agent 此刻究竟怎样理解系统它计划在哪些边界内行动。本文从模型来源、视图目标、证据、更新责任、任务状态和组合使用方式展开对比说明三者怎样共存以及为什么在 AI Coding 场景中多一张任务级变更地图并不等于重复画图。一、Mermaid 解决的是“怎样用文本画图”Mermaid 官方将其描述为基于 JavaScript、使用类似 Markdown 的文本定义创建和修改图表的工具主要目标是帮助文档跟上开发。它支持大量图表类型并能集成到 GitHub 和其他文档系统。一个简单的软件调用关系可以写成图 1使用 Mermaid 文本描述的简单调用关系。Mermaid 的优势很明确文本易于版本控制和代码审查图表类型丰富Markdown 生态支持广修改成本低适合局部流程和时序说明不绑定特定架构方法。但 Mermaid 不负责读取仓库并决定 Web UI、API 和数据库是否真的存在也不会检查一个 Agent 计划修改的文件是否属于图中的 API 模块。图表内容是否准确由作者和评审者负责。二、Structurizr 解决的是“怎样维护一个架构模型”Structurizr 官方文档将其定义为面向 C4 模型的 models-as-code 工具开发者使用 Structurizr DSL 定义软件架构模型再从一个模型创建多个架构视图。一个简化的 DSL 示例如下workspace { model { user person User system softwareSystem Shop { web container Web application api container API } user - web Uses web - api Calls } }这类模型比一组彼此独立的图更有约束力。系统元素只有一个身份不同视图引用同一模型团队还可以维护文档、架构决策、部署视图和动态视图。Structurizr 最适合回答我们认可的软件系统、容器和组件是什么同一模型需要展示哪些层级和视角哪些架构知识需要长期维护如何让架构图进入版本控制和自动化流程这是一种团队拥有的权威模型而不是某一次 Agent 任务的临时计划。三、Birdview 解决的是“Agent 这次准备怎样动手”Birdview 的architecture.json看起来也像架构模型但它与 Structurizr 的关注点不同。它重点记录模块职责、文件归属、源码证据、关系、状态和不确定问题并通过activity.jsonl描述当前任务。图 2Birdview 的完整架构视图保留模块职责、关系和统一布局。截图来自本地.birdview静态产物活动与架构由 Agent 声明不是对生产环境的实时自动监控。图 3Mermaid 和 Structurizr主要表达长期知识Birdview 将当前源码理解连接到本次 Agent 任务。这里的关键词是“这次”。Birdview 不要求团队先把整个企业架构维护成完整 C4 模型而是让正在工作的 Agent 对当前相关范围负责哪些模块与任务有关哪些文件属于这些模块源码中的什么位置支持该判断当前只编辑哪些目标范围扩大时是否重新计划最终运行了什么检查。四、三种工具的数据责任不同维度MermaidStructurizrBirdview核心对象单张或多张文本图表统一的软件架构模型证据化项目地图与任务活动主要作者文档作者、开发者架构师与开发团队执行当前任务的 Agent用户复核主要时间尺度文档需要更新时架构模型演进时每次相关任务前后源码证据由作者自行组织可通过文档、模型与扩展关联模块和关系契约显式携带证据文件归属无内置语义取决于团队建模方式本地模块显式声明文件/目录归属任务范围需要自行绘制可用动态视图表达交互planned活动直接声明范围、目标和文件检查结果需要自行记录不是核心任务活动记录支持命令、状态、退出码和摘要用户确认不涉及取决于团队流程技能工作流要求展示方案后确认Birdview 的价值不是图形语法而是这一套数据责任。如果只把 Birdview 页面截图后删除 JSON、证据和活动流它就会退化成另一张普通架构图优势也随之消失。图 4Birdview 的约束面板展示本次适用规则、来源和核对状态把“项目规则是否影响这次修改”纳入可见范围。五、权威架构模型与 Agent 地图发生冲突时怎么办假设团队的 Structurizr 模型认为“订单 API”只能访问订单数据库但 Agent 从当前源码中发现它还直接调用了库存服务。这时不应该为了让两张图一致而偷偷修改其中一张。更合理的处理是将 Structurizr 视为团队声明的目标或权威架构。将 Birdview 中的源码关系视为当前实现证据。核对是否为模型过时、实现违规、临时迁移还是误判。在没有结论时将 Birdview 关系标记为uncertain并记录问题。经团队确认后再决定更新架构模型还是修复实现。图 5长期架构模型与当前源码证据冲突时应把差异变成复核对象而不是强行抹平。这种组合还能发现普通“文档漂移”权威图描述的是团队希望系统保持的边界Birdview 描述的是 Agent 在当前源码中找到的关系。差异本身就是有价值的信息。六、为什么只让 Agent 输出 Mermaid 还不够让 Agent 阅读仓库并直接输出一段 Mermaid当然也能得到架构图而且实现成本很低。问题是 Mermaid 语法只约束图能否渲染不约束这些架构语义节点是否对应真实、内聚的模块本地模块拥有哪些文件每条关系由什么源码支持不确定判断是否被明确暴露本次修改范围是否只包含已知模块活动文件是否属于当前目标检查状态与退出码是否矛盾。Birdview 使用 TypeBox 维护结构契约、生成 JSON Schema并在运行时执行跨记录语义校验。下面是一段简化后的关系Agent 判断 - architecture.json - Schema 校验 - 跨记录语义校验 - 独立 HTML因此“让 Agent 画 Mermaid”和“让 Agent 运行 Birdview 工作流”最大的区别不是渲染器而是是否存在一份可检查的中间数据契约。七、Birdview 是否应该导出 Mermaid 或 Structurizr从产品演进角度看导出能力可能有价值但不应该用导出来替代 Birdview 自己的数据模型。如果未来导出 Mermaid它适合将简化架构嵌入 README在支持 Mermaid 的平台快速分享对图形样式进行二次加工。如果未来与 Structurizr 集成它更适合将已有 C4 模型作为架构候选来源对比权威模型和源码调查结果将已确认的稳定关系回写到长期模型。但 Birdview 的任务范围、活动阶段、检查结果和确认流程无法被普通 Mermaid 图完整表达也不应被强行塞进 C4 元素属性中。八、推荐的组合工作流一个同时使用三者的团队可以这样分工阶段工具产物架构设计与长期治理StructurizrC4 模型、系统与容器视图、决策文档局部流程和技术说明Mermaid时序图、状态图、流程图、README 图表AI 任务开始前Birdview当前源码证据、相关模块、本次修改范围AI 任务执行后Birdview Git检查记录、活动页面、真实 diff架构发生稳定变化后Structurizr / Mermaid更新长期模型和文档这套流程避免了两个极端既不要求 Agent 每次修改都重建企业级架构模型也不让长期架构文档在真实代码变化时完全失去反馈来源。九、Birdview 仍然不能替代什么Birdview 当前没有 Mermaid 那样丰富的图表语法也没有 Structurizr 对 C4、架构决策和多类视图的完整支持。它的模块角色和分组角色是为 Birdview 查看器服务的分类并不等价于 C4 的 Person、Software System、Container 和 Component。此外Birdview 的地图由 Agent 根据已检查源码声明。校验器可以发现引用、范围和状态不一致却不能证明 Agent 的架构抽象一定正确。团队仍然需要权威架构责任人、代码评审和真实测试。总结在我看来Mermaid、Structurizr 和 Birdview 分别对应三个不同的问题这张图怎样用文本表达这个系统的权威架构模型是什么以及这个 Agent 在当前任务里准备怎样理解并修改系统。Mermaid 胜在轻量、图表丰富和文档生态Structurizr 胜在围绕 C4 建立统一模型并生成多层视图Birdview 没有必要在这些成熟领域重复竞争。它真正补上的是长期架构知识进入 AI Coding 执行现场时的断层。团队的 C4 图可能是正确但较高层的README 中的 Mermaid 可能解释了关键流程但 Agent 仍然需要说明这次具体涉及哪些模块、哪些文件属于这些模块、源码证据在哪里、哪些判断仍不确定以及它准备如何验证结果。Birdview 将这些回答组织成架构 JSON 和活动 JSONL经过一致性校验后放到同一个 HTML 页面并在实施前要求用户确认已经展示的方案。最合理的采用方式不是用 Birdview 删除现有图表而是让三者各守边界Structurizr 保存长期架构模型Mermaid服务局部技术表达Birdview 负责当前 Agent 变更的证据、范围和检查。如果三份材料出现冲突不要把它视为工具失败而应把差异当作一次架构复核的入口。这种分工比争论“哪种图最好”更接近工程实践也更能体现 Birdview 在 AI 编码时代的独特位置。我会在重大变更后把已经确认的长期架构事实回写到团队模型和文档但不会把每次任务活动都塞进长期模型也不会指望一段文本绘图语法自动核对文件归属与检查结果。让长期知识和短期任务各自保持清楚的维护责任才能让三种工具相互补充。系列延伸阅读AI 生成架构图的可信度与校验边界Birdview 约束可视化实战参考资料Mermaid 官方介绍Mermaid GitHub 仓库Structurizr 官方文档Structurizr DSL 文档Birdview GitHub 仓库Birdview 数据契约