文档、ADR 和 API 合约的单一事实来源 — 现已在 Archyl 中可用
2026 年 3 月
软件架构不存在于一个地方。它存在于白板上画的图表中、埋在 Confluence 页面中的决策里、分散在 Swagger 文件中的 API 规范里，以及丢失在 GitHub Wiki 某处的入职文档中。如果你曾经花 30 分钟寻找"上个季度我们写的那个 ADR"，你就已经知道问题所在了。
今天，我们正在改变这一点。Archyl 现在将文档、**架构决策记录（ADR）**和 API 合约作为一等公民支持——全部集中在 C4 架构图表旁边。
问题
每个工程团队都会随着时间积累架构知识。挑战从来不是创建文档——而是保持它的可发现性、一致性，以及与它所描述的系统的关联性。
以下是通常发生的情况：
- 架构图表存在于 Miro、Lucidchart 或你代码仓库中某个落灰的 draw.io 文件中。
- ADR 是
/docs/adr文件夹中的 Markdown 文件，没人记得去更新。 - API 合约存在于独立的 Swagger UI 或 Stoplight 工作区中，与它们描述的服务断开了联系。
- 通用文档分散在 Confluence、Notion、README 文件和口口相传的知识中。
结果？上下文碎片化。新工程师从五个不同的工具中拼凑对系统的理解。决策丢失了原因。API 规范与现实脱节。架构图表变成了装饰品而不是文档。
我们构建了什么
Archyl 已经通过 AI 驱动的发现和交互式 C4 模型可视化来映射你的软件生态系统。现在，它将文档、决策和合约带入同一个工作区——直接链接到它们所描述的架构元素。
Archyl 中的每个文档、ADR 和 API 合约都与你的 C4 模型上下文关联。当你查看一个系统、容器或组件时，你不仅能看到它的关系和依赖，还能看到塑造它的决策、它暴露的 API 以及解释它的文档。
不再需要切换标签。不再有过期的链接。一切都在一个地方。
ADR 作为一等公民
架构决策记录捕获架构背后的为什么。在 Archyl 中，ADR 是具有适当生命周期跟踪的结构化文档——提议、已接受、已弃用或已取代。
使它们在这里变得强大的是链接。每个 ADR 都可以附加到特定的 C4 元素上。想知道你的支付服务为什么使用事件溯源？点击容器，找到 ADR。需要在重构之前了解一个已弃用的决策？它就在那里，链接到它所影响的组件。
Archyl 中的 ADR 遵循结构化格式——上下文、决策和后果——因此你的团队无需额外的流程开销就能构建一致的决策日志。
API 合约与 OpenAPI
Archyl 支持 OpenAPI、gRPC 和 GraphQL 合约定义。你可以直接在平台中定义 API 合约，或从代码仓库同步。
每个合约都链接到实现或消费它的 C4 元素。这意味着你的 API 文档不再是一个独立的产物——它是架构地图的一部分。当一个容器暴露 REST API 时，合约只需点击一下。当一个组件消费外部服务时，规范就在那里。
你还可以定义服务器条目、版本控制和端点元数据，保持合约文档结构化且保持最新。
活的文档
静态文档会衰退。这就是为什么 Archyl 将文档视为与架构模型绑定的活产物。
- 按项目组织，带有文件夹和拖放排序。
- 链接到 C4 元素，使文档保持上下文关联，不会成为孤立的内容。
- AI 驱动的洞察，在架构变化可能使现有文档过时时发出标记。
- 协作性 —— 团队成员可以对任何元素、文档或决策进行评论，支持线程讨论和解决追踪。
当你的架构演进时，文档也随之演进。Archyl 的 AI 生成洞察会发现图表、决策和文档之间的不一致，确保没有遗漏。
开始使用
如果你已经在使用 Archyl，文档、ADR 和 API 合约今天就可以在你的项目仪表板中使用。导航到任何项目，你会找到每个功能的专门区域。
如果你是 Archyl 的新用户，简单来说：连接你的 GitHub、GitLab 或 Bitbucket 代码仓库，让 AI 发现你的架构，然后开始构建你整个团队都可以依赖的单一事实来源。
不再有分散的文档。不再有被遗忘的决策。不再有 API 规范与它们描述的系统存在于不同的世界中。
你的架构值得拥有一个单一事实来源。立即试用 Archyl。