让 AI 架构图可复盘，我会把 D2 放进文档流
AI 很擅长快速整理服务边界、数据流和异常路径，但它生成的架构图如果只停在一张截图里，很快就会变成难维护的附件。我的做法是让 AI 先产出结构化说明，再把图源落到 D2 文件中。这样图的核心信息进入版本库，评审时能看到真实变更，发布时也能由 CI 渲染成 SVG、PNG 或 PDF。
原创示意图：把 AI 草图、D2 图源、团队评审、渲染产物和文档 CI 串成可复盘链路。 来源：Codex image generation
为什么选 D2
D2 是一个开源的 declarative diagramming language，官方定位很直接：用文本生成图。它适合软件架构图，是因为语法贴近工程师的表达习惯，容器、连接、表格、Markdown、代码片段、变量和导入都能覆盖常见文档场景。D2 官方文档还强调了本地 CLI、watch mode、VSCode 与 Vim 支持、多种 layout engine、autoformatter，以及在 CLI 中导出 SVG、PNG、PDF 的能力。对团队来说，这些特性意味着图源可以和代码一起提交，渲染产物可以交给自动化处理。
把 AI 放在草图层
我通常不给 AI 直接决定最终图形样式，而是让它回答四个问题：系统里有哪些节点，节点之间通过什么协议连接，哪些边界属于外部依赖，哪些路径需要标注失败或降级。这个输出可以是 Markdown 表格，也可以是简短清单。随后再让 AI 生成第一版 .d2，例如：
frontend: Web App
api: API Gateway
worker: Background Worker
db: PostgreSQL
frontend -> api: HTTPS
api -> worker: queue job
worker -> db: write result这一步的重点是把讨论对象从模糊图片变成文本。架构师可以改节点命名，后端同学可以补协议，前端同学可以指出用户可见路径，运维同学可以补监控和告警入口。每一次修改都会出现在 diff 里，评审成本比反复替换截图低很多。
让评审看事实
D2 图源进入仓库后，我会给文档流加三条轻量规则。第一，图里只保留稳定事实，例如服务名、边界、协议、存储和关键异步链路，避免把临时排期、个人判断和未确认指标写进去。第二，渲染产物由 CI 生成，减少手工导出造成的版本漂移。第三，PR 中同时展示 .d2 变更和渲染图，评审者先看结构差异，再看视觉结果。
D2 的另一个好处是离线工作流友好。官方 GitHub README 给出的 quickstart 就是用 CLI 监听输入文件并输出 SVG，本地浏览器会随着源文件变化刷新。对于内部架构文档，这种反馈速度足够快，也不依赖在线白板服务。
小团队落地清单
最小可行方案很简单。先在 docs/diagrams/ 放 .d2 源文件，把导出的图片放进站点静态目录。再增加一个脚本，统一执行格式化和渲染。接着在 PR 模板里要求说明图源改动的原因，以及是否影响外部接口、数据持久化或部署拓扑。最后给 CI 加一个 freshness check，发现 .d2 比渲染图更新时直接失败。
这套流程不会让架构文档自动保持正确，但能把错误暴露得更早。AI 负责把复杂上下文整理成初稿，D2 负责让图源可维护，评审流程负责确认事实。对 CorianderLab 这类经常写 AI 工具、开源实践和云服务笔记的站点来说，它也适合用来沉淀可复用的系统图模板，让每一篇技术文章的配图都能被后续文章继续演化。