ln-75-architecture-diagram-builder

架构图构建器

目标： 创建数量尽可能少、易于理解且有证据支撑的图表，以说明当前或拟议的架构。仅修改获准的架构文档；不得编造关系、进行产品视觉设计、用图表替代文字证据、审计架构是否适用，或编辑实现。

执行约定： 按顺序排列的复选框即为完成定义。内部将每项标记为 PENDING、有具体证据支撑的 PROVEN、有证据证明条件不存在的 CLEARED，或标明缺口的 UNPROVEN；阅读、委派或工具故障均不构成证明。每完成一个部分后核对各项。返回前，解决所有 PENDING 项，只统计 PROVEN 和 CLEARED；对每个缺口应用本技能的判定和审批规则。 保留用户意图、范围和现有授权。继续已获授权的工作；仅针对尚未解决且影响重大的选择或所需的外部审批进行询问。根据实质风险调整深度，不得悄然跳过检查。保留依赖关系和安全顺序；除此之外，针对每项义务选择适当的验证方法。

工具路由

需求	首选能力	后备方案
架构证据	仓库文件、运行时接线、IaC、契约和获准的制品	用户提供的模型，并标记为 UNVERIFIED
关系追踪	语言智能、依赖工具和有针对性的搜索	直接检查生产者、消费者和注册项
图表格式	仓库现有约定和渲染器	Markdown 中的 Mermaid，其次为纯 ASCII
语法验证	仓库渲染器、解析器或预览	手动检查代码围栏、标识符和关系
文档修改	对获准的图表制品进行最小化补丁	若路径或证据边界不安全，则返回 BLOCKED

图表用于传达模型；对于当前状态，以可执行行为为准。当前、目标和过渡视图必须清晰区分。

制品规则

• 沿用现有图表约定，或使用 docs/architecture/diagrams/<view>.md。
• 优先使用 Markdown 和 Mermaid，以便审阅文本源；若不支持 Mermaid，则使用 ASCII。
• 对于静态结构，选择能回答所提问题的上下文、容器或组件层级；如果现有上下文视图已足够，不要创建前置概览图。
• 将图表源文件保留在版本控制中，便于审阅。
• 如果一个图表需要讲述多个互不相关的内容，则拆分视图。
• 绝不能仅用颜色来传达含义。
• 使用稳定的元素标识符和简洁的显示标签，使修订产生的差异便于审阅。
• 将详细证据放在图表旁边，不要让节点和关系过于拥挤。
• 保留易于理解的现有表示法；仅当新表示法能更好地回答受众的问题时才引入。

检查清单

1. 确立图表约定

• 确定受众、问题、当前或目标状态、范围、获准的目标位置以及所需的表示法。
• 阅读仓库说明、相关架构制品和现有图表约定。
• 选择最少但有用的视图；舍弃不能让关系更清晰的图表。
• 界定证据边界，并单独标注用户提供或拟议的元素。
• 除获准的架构图表文档外，本次运行保持只读。

2. 构建架构模型

• 识别相关人员、系统、应用程序／数据存储（使用 C4 时为 C4 容器）、组件、队列和外部依赖项；区分逻辑容器与操作系统／容器运行时部署单元。
• 记录每个元素的职责、类型、在决策相关时记录技术、已知时记录负责人，以及当前／目标状态。
• 明确关系的方向、标签、协议或数据、同步性，以及相关的信任边界或网络边界。
• 在纳入当前状态的路由、处理程序、作业、插件或使用方之前，追踪运行时发现和注册过程。
• 将不确定的元素或关系标记为 UNKNOWN，而不是为了让图看起来完整而补全信息。

3. 选择并绘制视图

• 当读者需要了解系统范围和外部参与者时，创建系统上下文视图。
• 当需要展示职责、可部署性、存储或运维拓扑时，创建容器或部署视图；在与受众的问题相关时，纳入节点、区域、网络、扩缩容和故障转移。
• 仅当复杂区域的内部边界会影响理解时，才创建组件视图。
• 为关键的成功、失败、重试、超时、恢复或迁移交互创建序列或动态视图。
• 当安全、隐私、数据驻留或系统记录来源相关的问题需要时，创建数据流或信任边界视图。
• 除非明确说明且确有必要，否则避免在同一视图中混合不同抽象层级。

4. 让图表能够自我说明

• 添加标题、图表类型、范围、当前／目标标记、预期受众，以及观察或提案日期。
• 为形状、颜色、线条样式、缩写和不确定性标记添加图例。
• 为每条关系标注意图或数据；避免使用含义笼统的箭头和未解释的缩写。
• 确保名称与代码、契约和共享架构文档保持一致。
• 添加简洁的证据说明或链接，以便追溯当前状态的声明。

5. 验证并报告

• 使用仓库渲染器验证语法，或完整地手动检查语法。
• 在有预览时检查渲染后的可读性；与其缩小标签，不如拆分信息过载的视图。没有渲染器时，将视觉可读性记录为 UNPROVEN；手动语法检查不等于渲染验证。
• 根据实现证据验证当前状态的元素和关系，并根据已声明的提案或明确标注的假设验证目标状态的元素。
• 当图表有效、范围明确且有证据支持时，使用 READY；当重要关系仍未知时，使用 INCONCLUSIVE；当范围、证据、格式或目标位置妨碍绘制可信图表时，使用 BLOCKED。

自检

• 返回前核对。 检查各项证据、需求覆盖情况、矛盾、范围、结论和适用的清理工作。更正报告或经授权的产物。复用有效证据；不要自动重新扫描仓库或重跑已成功的命令。仅在相关变更、失败或证据尚未解决时重复检查。披露仍存在的差距。

输出约定

按用户使用的语言报告，并按以下顺序排列；保留全部五个字段，每项事实只陈述一次。结果较少时，每个字段可用一行；省略空表格，不要复制已链接的产物：

1. **结果：**针对技能的结论，以及有依据支持的结果。
2. **范围：**已审查/更改的范围、排除项、基线和重要假设。
3. **证据：**下方针对技能的字段；区分事实、推断和未经验证的声明。链接产物；适用时使用表格。
4. **验证：**检查/结果、无法获取的证据，以及适用的清理/外部状态。
5. 完成情况：Checklist: X/Y complete；Incomplete: None，或逐项列出每个 UNPROVEN 项目的原因、对结果的影响及确切的后续操作；列出剩余风险和需要作出的决定。

**针对技能的证据：**产物路径；每个视图的当前/目标状态、面向的问题，以及证据依据。报告语法/渲染验证、当前状态关系检查、未知关系，以及会影响解读的渲染限制。