tt-a1i/archify 是一套面向 Agent 的架构图生成与校验工具。它的切入点不是让模型随手输出一张漂亮示意图，而是先把系统描述表达为有类型约束的 JSON 中间表示，再用确定性的渲染和校验流程交付 HTML、SVG 与静态或动态图片。对于需要把代码库、服务边界、数据流和变更方案讲清楚的团队，这种结构比一次性的图像生成更容易复查、迭代和纳入版本管理。

架构图的价值在于压缩沟通成本，而不在于替代工程事实。图上的节点、关系和边界仍然需要来自明确的系统说明、文件证据或人工确认；布局通过校验，只能说明表达产物符合既定规则，不能证明线上服务一定按图运行，更不能自动判断修改是否安全。把这两个层次分开，才能让图成为可靠的工程交付物。

一、架构图为什么常在复杂系统中失效

小型示意图很容易画，复杂系统却会迅速暴露问题：模块增加后节点相互挤压，箭头穿过文字，重复关系改变方向，读者无法判断主路径与辅助路径的优先级。更麻烦的是，代码或方案每次变化后，团队常常只能把两张截图放在一起找差异，既难确认新增与删除，也难保留变更的解释。

这类问题不是单纯的配色问题。它反映出图形数据、版式规则、阅读方式和导出结果没有被当成同一个工程对象管理。若图只有最终像素而没有可检查的来源，任何修订都会重新依赖人工排版；若图只有结构数据却没有交付质量门，读者面对的仍可能是一份难以阅读的关系网。

二、先用有类型的 JSON 固定系统描述

Archify 让 Agent 先输出描述节点、关系、分组、路径和说明的 JSON IR。节点可以代表组件、服务、存储或外部依赖，关系表达明确方向与含义，分组则承担边界和层次。这样做的重要意义是把“系统是什么”和“系统怎样呈现”分离：前者可以被审阅和修改，后者由稳定的渲染器处理。

有类型的中间表示也让局部修改更可控。增加缓存、拆分认证服务或调整一条数据通路时，执行者能够只修改受影响的对象与关系，再重跑校验，而不是让模型重新生成整张图。对于需要长期维护的文档，这种可定位性比一次生成的惊艳效果更有价值。

三、五种图对应五类工程问题

Architecture 图适合说明组件、服务、存储与信任边界；Workflow 图适合 CI/CD、审批、工具调用和运行手册；Sequence 图按时间展开请求与返回；Data Flow 图强调数据来源、转换、存储和消费方；Lifecycle 图则用来描述状态、等待、重试与终止条件。选择图形类型时，先确定读者要回答的问题，比把所有细节塞进同一个画布更重要。

例如，浏览器访问 API、缓存未命中后回源数据库的主路径，适合用 Architecture 或 Sequence 解释；一次发布包含检查、批准、部署和回滚分支，则更适合 Workflow。数据合规审查通常需要 Data Flow，异步任务和故障恢复则需要 Lifecycle。一个图只承担一个主要阅读任务，才不会把结构说明变成无从下手的连线集合。

四、确定性渲染让结果可以重复比较

JSON IR 进入渲染器后会被编译为独立 HTML 和 SVG，读者可以直接打开交付文件，不依赖一个长期运行的应用服务。独立文件既适合评审和归档，也能降低“环境消失后图无法再打开”的风险。需要嵌入文档或演示时，还可导出 PNG、SVG、WebM 和固定尺寸的分享卡片。

确定性并不意味着内容自动正确，而是指同一份输入在相同版本的规则下能够产生可比较的输出。团队应同时保存 JSON、生成器版本和关联的代码提交版本。这样发生差异时，才能先判断是结构数据变了、渲染规则变了，还是阅读焦点被调整了，而不是把所有变化混成一张新截图。

五、把图形质量变成可执行的检查

校验流程覆盖 schema、布局、HTML/SVG、路径与标签间距等问题。典型检查包括节点是否缺少必要字段、连线是否与无关卡片交叉、文本是否靠近路径、路由是否符合可读性规则。失败结果以结构化诊断返回具体对象、度量证据和支持的修正方向，使 Agent 可以针对问题位置修复后再次检查。

这种反馈机制避免了“整张推倒重画”的循环，但它有清晰边界：它校验的是图的来源与呈现契约，而不是业务系统的真实状态。即使所有布局检查都通过，团队仍需要用测试、日志、配置、基础设施清单和人工评审确认服务依赖、数据流向和权限边界。

六、最后一个通过校验的版本应保持可用

编辑 JSON 时，文件可能处于尚未写完或暂时不合法的中间状态。面向桌面预览的模式会在候选版本通过全部质量门之前保留上一个可用结果，这比每次保存都用一个半成品覆盖读者正在查看的图更适合演示和协作。它把“可编辑”与“可交付”分开处理。

同样的原则应扩展到自动化流程：生成候选、验证候选、在通过后原子替换目标文件，并把失败诊断保留给下一轮修复。无论输出对象是图、网页、报告还是部署包，最后已知正确版本不应被未经验证的中间产物覆盖。

七、交互功能必须仍然基于已写明的关系

独立页面支持节点搜索、上游与下游关系查看、两点之间的有向最短路径、角色对比和分章节的引导阅读。这些功能的正确使用方式是帮助读者筛选已声明的节点与边，而不是在交互时猜测未写入图中的依赖。路径高亮应解释“图中作者声明的关系”，不能夸大为对线上影响的自动推断。

对于大型图，角色过滤和有限的阅读故事尤其有用。后端、数据存储、外部系统或安全边界可以被单独观察，主路径可以按段展开。这样读者先建立整体模型，再进入局部关系，避免第一眼就被所有细节淹没。

八、用 Before、Delta、After 审阅架构变更

Architecture Delta 将两份已验证的架构快照组织成 Before、Delta、After 视图，标示新增、删除、修改、移动和改线的事实。它适合设计评审和合并前说明：评审者不必在两张静态图间来回寻找差异，而可以先阅读变更清单，再回到完整关系中确认上下文。

这项能力同样不能替代风险评估。两份 JSON 的差异只能说明作者在图中声明了什么变化，不能自动得出性能、可用性、安全性或迁移风险的结论。提交者仍应附上测试范围、回滚方案、配置变动和未验证假设，让图和工程证据共同构成评审材料。

九、需要事实依据时，把证据钉到版本

当架构图来自代码库分析时，关键节点可以关联到公开仓库中特定提交、文件和行范围。这样读者能从图回到可核验的源代码，而不是接受无出处的概括。证据应按需添加：高层沟通图不必假装覆盖每个实现细节，要求强可追溯性的设计说明则应明确证据范围与缺口。

最稳妥的工作顺序是先锁定分析对象的提交版本，再让 Agent 读取限定范围的文件，产出初始 JSON，由领域负责人确认主要模块、入口、存储和外部边界，最后把已确认对象与必要证据写进图中。这样生成效率不会掩盖来源不足的问题。

十、从系统描述到可交付图的实用流程

第一步先写清目标读者和主问题，例如“解释请求链路”或“审阅发布回滚”。第二步限制高层架构的核心组件在 8 到 12 个左右，只突出一条主要路径，将解释性细节放入说明卡片。第三步生成 JSON 后先审阅对象与关系，再运行校验与预览。第四步把通过检查的 HTML、SVG 和 JSON 一起纳入评审或文档。

对于持续变化的系统，可在每个重要设计点保存快照，并在变更时生成 Delta。对于固定演示场景，可保留命名视图和有限故事。无论哪种方式，都应给产物标注所依据的代码版本、生成时间和适用范围，避免陈旧图在没有提示的情况下继续影响决策。

十一、明确边界，避免把图形工具当成事实引擎

Archify 不是自由拖拽的绘图软件，也不是通用 Mermaid 解析器。它强调通过受约束的数据与渲染规则获得一致的技术表达，因此并不覆盖所有临时手绘需求。面对探索性草图、需要大量手工调整的品牌插画或既有 Mermaid 资产，团队应评估更合适的工具，而不是强行套用同一种工作流。

更重要的是，任何自动生成的架构图都不应成为无证据断言的放大器。把它用于表达经过审阅的结构、辅助寻找差异、组织评审材料和交付可打开的文档，能够显著提升沟通质量；把它当作系统运行事实、风险判断或合并安全性的替代品，则会掩盖真正需要验证的工程问题。

十二、可靠的架构图是可追溯的沟通契约

Archify 的核心价值在于把架构图从一次性图片变成由结构数据、确定性渲染、质量检查、可读交互和可比较快照组成的交付链。Agent 可以更快地产出候选，校验器可以更早发现表达缺陷，而人仍然负责确认结构事实、证据范围与变更风险。

当图能够回答“描述的对象是什么、关系从哪里来、依据哪个版本、哪些检查已经通过、哪些结论仍待人工确认”时，它才真正成为工程协作的共同语言。先把这条验证链建立起来，再追求更丰富的视觉表达，才能让架构图随系统一起演进而不是迅速失效。