企业官网建设流程全解析

摘要

如果一个团队已经在 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描述当前任务。

图 2：Birdview 的完整架构视图保留模块职责、关系和统一布局。截图来自本地.birdview静态产物，活动与架构由 Agent 声明，不是对生产环境的实时自动监控。

图 3：Mermaid 和 Structurizr主要表达长期知识，Birdview 将当前源码理解连接到本次 Agent 任务。

这里的关键词是“这次”。Birdview 不要求团队先把整个企业架构维护成完整 C4 模型，而是让正在工作的 Agent 对当前相关范围负责：

• 哪些模块与任务有关；

• 哪些文件属于这些模块；

• 源码中的什么位置支持该判断；

• 当前只编辑哪些目标；

• 范围扩大时是否重新计划；

• 最终运行了什么检查。

四、三种工具的数据责任不同

Birdview 的价值不是图形语法，而是这一套数据责任。如果只把 Birdview 页面截图后删除 JSON、证据和活动流，它就会退化成另一张普通架构图，优势也随之消失。

图 4：Birdview 的约束面板展示本次适用规则、来源和核对状态，把“项目规则是否影响这次修改”纳入可见范围。

五、权威架构模型与 Agent 地图发生冲突时怎么办

假设团队的 Structurizr 模型认为“订单 API”只能访问订单数据库，但 Agent 从当前源码中发现它还直接调用了库存服务。这时不应该为了让两张图一致而偷偷修改其中一张。

更合理的处理是：

1. 将 Structurizr 视为团队声明的目标或权威架构。

2. 将 Birdview 中的源码关系视为当前实现证据。

3. 核对是否为模型过时、实现违规、临时迁移还是误判。

4. 在没有结论时将 Birdview 关系标记为uncertain并记录问题。

5. 经团队确认后，再决定更新架构模型还是修复实现。
   

图 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 元素属性中。

八、推荐的组合工作流

一个同时使用三者的团队，可以这样分工：

这套流程避免了两个极端：既不要求 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 约束可视化实战

参考资料

1. Mermaid 官方介绍

2. Mermaid GitHub 仓库

3. Structurizr 官方文档

4. Structurizr DSL 文档

5. Birdview GitHub 仓库

6. Birdview 数据契约