博客 - Archyl

软件架构文档的教程和最佳实践。

按频道限定 Archyl 机器人：对的房间，对的项目

一个 Slack 或 Teams 工作区，几个团队，一个对所有项目都作答的机器人。现在你可以把一个频道限定到某个团队或一组项目，让 #payments 不再回答关于贷款平台的问题。由管理员生成的一次性代码来应用，并在每次工具调用时强制执行，而不是交给提示词。

给 AI 编码代理的 memory：存下来是简单的那一半

代理的 memory 通常就是一堆只增不减的笔记，而里面没有任何东西能告诉你哪些还是真的。Archyl 把 memory 挂在架构上，而不是挂在某次对话上，按含义排序，从代理自己声明用过的东西里学习，并在某个元素背后的代码发生漂移时把对应的 memory…

Archyl Harness：在动手之前先声明自己要干什么的编码代理

上周我们写过三个代理开出三个 pull request，每一个单独看都对，合在一起却错了，并且承认我们自己的配置里没有任何东西能把这件事拦下来。Harness 就是我们交付出来的答案：代理对着已记录的架构做计划，声明这次工作，在自己要碰的元素上取得咨询式租约，并在写下第一行代码之前拿到一个 gate…

很多代理，一个架构：当其中两个改动同一个系统时会发生什么

让三个编码代理跑在同一个代码库上，你会拿到三个 pull request，每一个单独看都没错，合在一起却把系统变成了三种不同的东西。一份规则文件仲裁不了这件事。这里写清楚共享的架构模型能做什么、仍然做不到什么，以及当我们发现自己的产品会让第二个代理一声不吭地覆盖第一个代理时，我们不得不加上的那道检查。

你的 AI 代理有一份规则文件。它们没有你系统的模型。

每个编码代理都会读一份规则文件：CLAUDE.md、AGENTS.md、.cursor/rules。这些文件承载着约定，而约定的保质期很长。它们同时也承载着关于你系统的断言，却没有任何东西去核对这些断言是否还成立。这篇文章讲我们自己的那份文件里什么已经过期，以及为什么把文件写得更长解决不了问题。

Structurizr Cloud 将于 9 月 30 日关停：先把你的模型导出来

Structurizr 的云服务自 2026 年 7 月 1 日起已变为只读，并将在 9 月 30 日终止服务。你用来导出工作区的那个 DSL 标签页本身就是这项服务的一部分——服务关停，它也就跟着消失。这篇文章讲清楚本周就能把模型取出来的做法，以及对四个落脚点的一份诚实评估，其中三个不是我们。

架构延时影片：30 秒看完你的架构演进史

你的架构自有一部历史——每个版本都被捕捉，每次变更都有记录。延时影片把它变成一部电影：元素自己画出来，镜头追着每一次变更跑，退役的服务被红线划掉，片尾字幕滚出你的统计数据。最后还能把整部影片导出为 MP4，全程在你的浏览器里渲染。

用 MCP 把代码、Terraform 和图表变成 C4 模型

空白画布是个谎言：你的架构早就写在 Structurizr 文件、Terraform 模块、Mermaid 图和 README 里了。把 AI 代理接上 Archyl 的 MCP 服务器，把这一切变成一个活的 C4 模型——一个框都不用重画。

Transfer 的解剖学:用 Archyl 以 C4 建模 Revolut

巴黎时间 19:47,Léa 点下 Send,450 英镑在她放下手机之前就到了伦敦的一个银行账户。这三秒钟背后:一个没有 Kafka 的事件驱动骨干、一个 50 毫秒内的欺诈裁决,以及一个建立在 PostgreSQL 上的 ledger。这就是这趟旅程,跨四个 C4 层级建模。

Reality：让你的架构图真正活起来

每一张架构图都只是一张快照——画下来的那天是对的，之后就一路偏移。Reality 接入你的生产系统，让架构图映照出真正在运行的样子。只读、无需 Agent，每一处改动都由你拍板。

MCP Playground：在文档中实时运行你的智能体工具

文档告诉你一个 MCP 工具声称能做什么。全新的 MCP Playground 让你真正调用它——选择一个工具，填写由其 schema 自动生成的表单，点击运行，实时查看结果。直接在你的架构文档里，直接在你的浏览器中。

我们从零重做了每一个 C4 元素

新的 node、新的 edge、新的画布。Archyl 的图现在一眼就能读懂,而不是逼你去解读。按层级配色、focus 模式、有动画的关系线 — 全部上线。

一次行程的解剖:用 Archyl 通过 C4 建模 Uber

下雨的 NYC 晚上 7 点 23 分,乘客点击呼叫 UberX。八秒后,0.4 英里外的司机已接受,ETA 出现在屏幕上,费用已锁定,实时通道已打开。这是这段旅程,通过四个 C4 层级建模 — 以及帮助一个 4000 服务栈保持可读的每个 Archyl 功能巡览。

Charge 的解剖学:用 Archyl 以 C4 建模 Stripe

黑色星期五凌晨 3 点,一个 POST 请求打到 Stripe。二十秒后,商家被入账,持卡人的发卡行已扣款,商家服务器收到了签名的 webhook。这就是这趟旅程,跨四个 C4 层级建模。

收件箱里的架构:每周团队摘要正式发布

架构洞察活在仪表板里。最需要它们的人活在收件箱里。我们用按团队定制的邮件摘要来弥合这个鸿沟 — drift、ADR、合规性、讨论 — 按团队选择的节奏推送。

C4 组件图（Component）：完整指南与示例

C4 组件图（C4 模型第 3 层）放大到单个容器内部，展示其中的组件。本指南讲解什么是组件图、它何时值得维护、一个完整的实战示例、常见错误，以及如何在不背负维护负担的前提下保持第 3 层的准确。

C4 容器图（Container）：完整指南与示例

C4 容器图（C4 模型第 2 层）展示系统中可部署的构建块：Web 应用、API、数据库、队列。本指南讲解什么是容器图、它应该包含什么、一个完整的实战示例、常见错误，以及如何让它与代码保持同步。

C4 模型 vs UML：你的团队该用哪个？

C4 模型 vs UML 是团队在挑选软件架构图标准时最常问的问题之一。这篇诚实的对比讲解 UML 在哪些地方依然胜出、C4 为何成为现代的 UML 替代方案，以及如何决定哪一个适合你的团队。

C4 系统上下文图（System Context）：完整指南与示例

系统上下文图（System Context）是 C4 模型的第 1 层——它是团队所能绘制的最重要的一张架构图。本指南讲解一张 C4 上下文图应该包含什么内容，完整演示一个上下文图示例，并展示如何手工绘制，或直接从代码生成它。

什么是 API 契约（API Contracts）？定义、示例与最佳实践

API 契约是对一个 API 接口正式、经各方约定的规约：操作、模式（schema）、错误以及版本规则。本指南讲解什么是 API 契约，REST、gRPC、GraphQL、事件和 MCP 工具所用的格式，契约优先（contract-first）与代码优先（code-first）开发，以及在实践中如何测试和维护契约。

Play 的解剖学:用 Archyl 以 C4 建模 Netflix

在 Netflix 上按下 Play,~50 个服务在 200 毫秒以内协作。这就是当你跨四个 C4 层级建模整个技术栈 — Member Experience、Streaming Platform、Open Connect、Cosmos — 时的样子。

托管 Agent 运行：在你休息时自主处理架构工作的 AI Agent

部署可按计划运行的自主 AI Agent，连接 GitHub、Linear、Slack 及任何兼容 MCP 的服务，在完整架构上下文中处理你的代码库。今天我们正式推出托管 Agent 运行 —— Agent Hub 中的全新功能，让你可以直接从 Archyl 调度、安排和监控 AI Agent。

面向 AI 原生团队的 Architecture Intelligence

AI 智能体现在编写了大部分代码。但谁来确保它们遵守架构？今天我们发布 10 个智能体技能、6 个 GitHub Actions、合规规则包、SDK 以及三个全新的 AI 驱动 API —— 让你的智能体能够自动理解、验证和演进架构所需的一切。

成熟度评分：用一个等级衡量你的架构健康状况

漂移分数告诉你文档是否准确。合规性告诉你规则是否被遵守。洞察告诉你哪里出了问题。DORA 告诉你能否顺利交付。但它们都无法告诉你全貌。成熟度评分可以——一个等级，四个维度，零猜测。

编码代理插件：无需离开终端即可管理你的架构

我们刚刚开源了一个插件，它让 Claude Code、Codex 及其他编码代理能够完全访问 Archyl 的 200 多个 MCP 工具。创建系统、编写 ADR、检查漂移、执行合规性检查——一切都可以在终端中通过自然语言对话完成。

Architecture Drift Score：你的文档在说实话吗？

Architecture Drift Score 是一个 0 到 100 的数字，衡量你文档化的架构还有多少仍存在于代码库中。本文讲的是它的机制：公式、什么进入分母、什么被刻意排除、这项检查看不到什么，以及如何在 CI 中强制执行。

Agent Hub：为自主 AI 代理设定架构护栏

AI 编程代理写代码很快，但如果没有护栏，架构漂移也同样迅速。今天我们推出 Agent Hub —— Archyl 中全新的功能模块，让你定义合规规则、浏览包含 96 条预设护栏的目录，并在 AI 代理写下第一行代码之前，为它提供所需的完整架构上下文。

内置小组件：无需外部集成的架构仪表板

并非每个团队都使用 Datadog 或 PagerDuty，但每个团队都有架构洞察、DORA 指标、发布记录、ADR 和技术栈。今天我们推出了 14 个内置小组件，将您的 Archyl 工作区转变为实时架构仪表板——无需 API 密钥、无需连接、无需配置。只需添加一个小组件。

Ownership Map：可视化架构中每个部分的负责人

每个架构都存在归属权问题。服务不断被构建，团队持续变动，人员陆续离开——突然之间，没人知道谁该为什么负责。Archyl 全新的 Ownership Map 让团队责任归属变得可视化、可交互且无法忽视。

DORA 指标：衡量整个架构的工程效能

您追踪了部署。但您知道团队是否在变快吗？Archyl 现在可以直接从发布历史中计算 DORA 指标 — 部署频率、变更前置时间、变更失败率和平均恢复时间 — 支持项目和组织级别。

Webhooks：架构变更的实时通知

你的架构在不断变化——系统被添加，组件在演进，ADR被编写，版本在发布。现在你可以在任何变更发生的那一刻收到通知。Archyl的新webhook通知功能让你将架构事件实时推送到任何HTTP端点。

技术雷达：一目了然地可视化你的技术版图

Archyl 现在可以追踪驱动你架构的技术。将语言、框架、数据库和工具附加到任何 C4 元素上，然后在交互式雷达上探索你的整个技术版图——按采用程度过滤、按象限分类，并深度链接回使用它们的每个元素。

自动布局：即时整理你的架构图

在C4图上手动定位数十个节点是繁琐的工作，不增加任何架构价值。自动布局使用ELK.js图算法为图表中的每个元素、覆盖层和关系计算最优位置——只需一键即可将所有内容动画移动到位。

影响雷达：在做出变更之前理解变更

每一个架构变更都会产生涟漪效应。影响雷达让你在提交之前准确地看到这些涟漪会到达哪里。右键点击C4模型中的任何元素，即可立即可视化上游依赖方、下游依赖、受影响的流程和跨项目风险。

Backstage vs Archyl：两种架构文档方案的对比

Backstage是一个碰巧包含C4插件的开发者门户。Archyl是一个从底层围绕C4模型构建的架构文档平台。两者都声称解决架构可见性问题——但方式截然不同。以下是一个诚实的对比。

本地部署：架构文档就在你的代码所在之处

并非每个组织都能将架构数据发送到云端。受监管行业、政府机构和注重安全的团队需要工具在自己的围墙内运行。Archyl 现在提供可在你自己基础设施上运行的自托管部署——相同的功能、你的网络、你的规则。

Marketplace集成：在架构上展示工具的实时数据

架构图告诉你存在什么。仪表板告诉你运行状况如何。这两件事一直存在于不同的工具中。今天我们将它们合并。Archyl的新Marketplace让你连接Datadog、GitHub、SonarQube、Prometheus、ArgoCD、GitLab和PagerDuty——并将它们的数据作为实时小部件直接显示在你的架构工作区…

发布管理：追踪架构中的每一次部署

你的架构图表展示了存在的事物。现在它们还能展示已发布的内容。Archyl 全新的发布管理功能让你可以跨系统和环境追踪部署，支持从 GitHub Actions、Webhooks 和 REST API 接入数据。

API契约：与架构关联的API规范

API规范是代码库中最有价值的产物之一，但它们几乎从未出现在架构文档中。我们正在改变这一点。Archyl现在支持导入OpenAPI、gRPC、GraphQL和AsyncAPI契约，并将它们直接关联到你的C4模型。

架构变更请求：C4模型的Pull Request

架构在不断演进。现在它可以像代码一样以严谨的方式演进。我们推出了架构变更请求——一种用于提议、审查和合并C4模型变更的Pull Request工作流。

企业SSO：Custom计划的SAML和OIDC认证

企业团队需要集中身份管理。Archyl现在支持SAML 2.0和OpenID Connect的自定义SSO连接，让你的团队通过公司的身份提供商登录——无需单独的密码，无需手动配置。

C4 图表和全局架构上的实时协作

架构协作不应停留在白板上。我们正在将实时在线状态、实时光标和元素聚焦跟踪扩展到你的项目 C4 图表和全局架构视图——让你的整个团队可以同时在同一架构上工作。

基于 C4 模型的事件驱动架构文档

事件驱动架构功能强大，但以难以记录著称。事件天然是不可见的、异步的，且在设计上是解耦的。本指南展示如何使用 C4 模型记录事件流、Event Channel 和异步模式——以及 Archyl 如何让事件驱动系统变得可见。

活文档架构：让你的文档始终保持最新

活文档架构是一种工作方式，不是一种格式。模型从代码派生，更新与变更搭乘同一个 Pull Request，并且有东西负责检查它是否奏效。以下是支撑它的五种实践、每一种的代价，以及每一种会在哪里失效。

面向软件架构团队的 DORA 指标

DORA 指标衡量工程效能，但大多数团队在跟踪时将其与架构割裂开来。本指南解释如何将 DORA 指标与架构决策联系起来，如何用它们指导系统设计，以及如何利用 Archyl 的 DORA 集成实现架构感知的性能跟踪。

如何使用 MCP Server 进行架构文档管理

AI 助手正在改变开发者的工作方式，但它们看不到你的架构文档。MCP Server 弥合了这一差距。本指南涵盖了 MCP 是什么、为什么它对架构至关重要，以及 Archyl 的 181 个 MCP 工具如何让你直接从 Claude 或 Cursor 中查询、创建和验证架构。

Architecture as Code：以编程方式定义你的系统设计

Architecture as Code 为架构文档带来了与 Infrastructure-as-Code 为运维带来的同等严谨性。本指南涵盖了 AaC 是什么、为什么它优于纯可视化方法、YAML 和 DSL 的实际示例、版本控制工作流、CI/CD 集成，以及 Archyl 如何让它切实可行。

如何记录微服务架构：实用指南

微服务功能强大，但以难以记录著称。本实用指南涵盖了常见挑战，展示如何将 C4 模型应用于微服务，并通过 Archyl 的实际示例详细讲解服务边界、通信模式等内容。

架构漂移检测：保持代码与设计的一致性

架构漂移是你所记录的系统与你实际拥有的系统之间的落差。关于它的常规建议（把文档放在代码旁边、在同一个 Pull Request 里评审）都是好建议，但没有一条能告诉你这些做法是否奏效了。本指南讲清楚漂移是什么、有哪些检测方式，以及如何给你早已存在的这道落差一个数字。

AI驱动的架构文档：未来已来

手动架构文档是一场必败之战。代码每天都在变化；图表每季度更新一次。AI正在改变这个等式——从代码中发现架构、自动检测偏移，并赋予AI代理架构感知能力。以下是它如何运作及未来走向。

架构决策记录（ADR）：完全指南

架构决策记录捕获技术选择背后的原因。这份完全指南涵盖ADR格式、模板、最佳实践、工具，以及如何将ADR集成到团队工作流中，让决策不再丢失。

2026年5款最佳C4模型工具：完整对比

在寻找合适的工具来创建和维护C4架构图？我们从功能、定价和实际可用性方面比较了2026年五款最佳C4模型工具——Archyl、Structurizr、IcePanel、Visual C4和Draw.io。

什么是C4模型？软件团队完全指南

C4模型是可视化软件架构最实用的框架。这份完全指南涵盖了所有四个层级、每个层级的使用时机、真实案例，以及现代团队如何使用Archyl等工具实施C4。

自定义洞察规则：你的架构，你的标准

每个组织都有独特的架构标准。通用的检查能发现一些问题，但会遗漏对你的团队最重要的内容。我们推出了可定制的洞察规则——调整阈值、禁用不相关的检查，让Archyl执行对你的代码库真正重要的标准。

软件架构C4模型入门

在多年绘制令人困惑的架构图之后，我发现了C4模型。以下是它如何改变了我们团队沟通系统的方式。

架构决策记录（ADR）最佳实践

我们花了两周时间争论一个一年前就已经做出并否决的数据库选择。那时我发现了ADR，从此它为我们节省了无数时间。

在软件架构中记录用户流程

我们的架构图看起来完美无缺。然后一个bug报告来了，我们才意识到没有人真正理解用户是如何在系统中移动的。以下是我们如何解决这个问题的。