这次我们来看一个架构图方向的 AI 项目Archify。它目前在 GitHub 上已经积累了 3.5 万 Star关注点不是“AI 能不能画出好看的架构图”而是画出来的架构图能不能验证、能不能追踪来源。也就是说Archify 生成的微服务架构图、业务架构图、系统架构图不是一次性 PPT 素材而是可以作为架构评审、代码重构、技术对接时的可信依据。提到 AI 生成架构图很多人第一反应是丢给大模型一句话让它吐一张 Mermaid 代码或 PNG 图片。这个方案的问题很明显生成的图“看起来合理”但图中每个节点和连线对应的到底是哪段代码、哪个服务、哪条真实依赖往往说不清楚。Archify 要解决的就是这一类准确性和可追溯性缺口让 AI 在生成架构视图的同时保留从原始输入到最终输出的追踪路径让每条关系都能回到原始来源再通过验证机制确认生成结果和真实系统之间的差距。这篇文章会围绕 Archify 展开完整的使用路径核心能力、适合场景、环境准备、安装部署、功能测试、接口调用、资源占用、常见问题与最佳实践。关心“AI 架构图工具怎么选”“Archify 怎么用”“能不能接入自己团队的架构治理流程”的人可以直接按章节操作。1. Archify 核心能力速览在动手安装之前先把 Archify 的关键属性过一遍。下面这张表把项目类型、能力边界、使用门槛和扩展方式集中列出来方便你快速判断它适不适合当前团队。能力项说明项目类型AI 辅助架构图生成与分析工具开源热度GitHub Star 约 3.5 万属于架构图方向高关注度项目核心卖点可验证、可追踪路径的架构图生成不是单纯“AI 画图”主要输入代码仓库、项目文档、需求描述、既有系统信息主要输出架构图、架构视图、架构说明文本、溯源记录架构图类型可覆盖微服务架构图、业务架构图、系统架构图、技术架构图等扩展能力从社区关注度看如 officiating Skill 或自定义技能机制可将通用架构能力定制到团队技术栈是否支持 API多数同类工具会提供接口服务具体路径以项目官方文档为准是否支持批量任务需要按项目文档确认可重点看其命令行或服务端是否支持多个仓库批量扫描典型显存需求如果使用云端大模型 API本地显存压力很小如果接入本地大模型需根据模型规模单独评估显存适合场景微服务梳理、系统架构图绘制、架构评审、代码迁移前分析、架构文档自动化更新从项目定位看Archify 最值得关注的是它把“架构图生成”和“验证机制”绑在一起。传统工具画图之后图和代码是两套东西改代码后图就过期了Archify 的思路更像是用 AI Agent 自动扫描项目结构再把扫描结果映射成架构视图每一步都有来源依据。这样画出来的图至少能在“哪些关系来自代码扫描”“哪些关系来自模型推断”“哪些关系需要人工确认”之间做区分。需要说明的是目前公开材料里没有给出 Archify 完整的硬件参数和接口文档所以“API 路径”“批量上限”“最小环境要求”这些信息最稳妥的方式是直接看项目 README 和官方文档。下面的部署与测试流程我会按通用 AI 工具实践给出可执行模板实际操作时把路径和字段替换成你自己项目的真实配置即可。2. 适用场景与使用边界2.1 适合谁用Archify 这一类工具最适合三类人。第一类是后端架构师和技术负责人。微服务拆到十几个模块后靠人工维护一张架构图成本很高用 AI 工具自动扫描代码仓库并生成依赖关系视图能大幅缩短架构梳理时间。第二类是正在做技术重构的团队。重构前需要先搞清楚现有系统到底有哪些服务、哪些调用了没接网关、哪些模块存在循环依赖这些信息如果能由 AI 自动扫出来比肉眼翻代码可靠得多。第三类是技术文档写作者。架构文档中需要系统架构图、技术架构图、业务架构图配图传统方式是手工画而 Archify 能把“生成配图”这步自动化。从搜热词来看很多人在关注“微服务架构图”“系统架构图”“技术架构图”这几个方向说明架构图并不仅仅是给汇报用的更多是开发过程里的真实工作产物。Archify 这类生成可验证架构图的工具正好踩中了这个需求点。2.2 什么时候没必要用如果项目很小一个模块几百行代码手工画图反而更快如果团队文档纪律差代码结构和实际情况严重脱节任何 AI 工具都很难自动恢复出可信架构图如果只想要一张好看但不追求准确的架构图用于对外展示那传统绘图软件的效果可能更可控。Archify 的优势在于“可验证”这也就意味着它会对准确性负责反过来也会要求输入质量不能太差。2.3 使用边界与合规提醒架构图往往涉及企业内部核心代码结构、服务依赖、中间件选型等敏感信息。在使用 Archify 时要注意不要直接上传未脱敏的私有仓库到公共大模型服务尽量使用私有化部署或企业内部模型网关生成结果如果包含人脸、个人信息、版权素材等非架构图内容必须清除后再做后续处理团队内部做架构评审时应把 AI 生成的图作为辅助材料关键决策仍需人工确认不能完全依赖 AI 输出。3. Archify 本地部署环境准备Archify 的部署方式需要根据项目官方文档确认但绝大多数 AI 架构图工具都会提供命令行工具或本地服务两种使用方式。下面先给出一份通用的环境检查清单避免装到一半才发现缺依赖。3.1 硬件与操作系统操作系统Windows 10/11、macOS、Linux 均可优先选择开发者日常使用的系统。CPU架构图生成主要涉及代码解析和大模型请求CPU 要求不高双核以上即可。内存解析大型仓库时建议至少 8GB如果仓库包含大量依赖文件16GB 更稳妥。GPU如果使用云端大模型 APIGPU 不是必需如果本地跑推理模型按模型实际显存需求评估。磁盘项目本体占用通常不大主要预留仓库扫描和输出结果的空间建议至少 10GB。3.2 依赖与运行环境Node.js 或 Python 环境取决于项目具体实现建议先按官方 README 确定主语言。Git用于克隆项目仓库。大模型 API KeyArchify 通常需要一个可访问的大模型服务作为生成引擎准备一个有权限的 Key。如果项目提供 Docker 镜像安装 Docker Desktop 或 Docker Engine 可简化环境隔离。如果项目支持 IDE 集成可以根据官方文档配置 Trae、VS Code 等开发工具的插件或外部命令。# 通用检查命令示例实际版本要求以项目文档为准 node -v npm -v python --version git --version docker --version3.3 网络与鉴权准备调用大模型 API 需要在配置文件中填入密钥。不要明文硬编码在代码仓库里建议使用环境变量或本地配置文件并把密钥文件加入.gitignore。# 环境变量示例实际变量名以项目文档为准 export LLM_API_KEYyour-api-key-here export LLM_BASE_URLhttps://your-llm-gateway.example.com如果使用企业内部模型网关还需要确认网关的鉴权方式、模型名称、超时时间等参数。这一步在批量任务场景中尤其重要因为批量扫描会持续调用大模型鉴权不通过会导致任务中断。4. Archify 安装部署与启动方式4.1 通过命令行工具安装如果 Archify 以 npm 包或 Python 包形式发布可以通过包管理器安装。下面给出通用命令模板实际包名和安装方式需要替换为项目 README 中的真实信息。# npm 方式示例以官方文档为准 npm install -g archify # 或使用 npx 直接运行 npx archify --version # Python 方式示例以官方文档为准 pip install archify archify --help安装完成后建议先执行--version或--help检查命令是否可用。如果命令不存在可能是因为全局 bin 目录没有加入 PATH此时需要找到安装路径并手动配置环境变量。4.2 通过 Docker 启动如果项目提供 Docker 镜像可以使用 Docker 启动服务。这种方式的好处是依赖隔离不会污染本机环境也方便在服务器上部署。# Docker 启动示例镜像名和端口以官方文档为准 docker pull archify/archify:latest docker run -d \ --name archify \ -p 3000:3000 \ -e LLM_API_KEYyour-api-key-here \ -v $(pwd)/outputs:/app/outputs \ archify/archify:latest启动后通过浏览器访问http://localhost:3000查看 Web 界面。如果页面打不开先检查容器是否正常运行docker ps docker logs archify --tail 1004.3 配置文件准备大部分 AI 架构图工具都会提供一个配置文件用来指定模型信息、仓库扫描路径、输出目录和批量任务参数。下面是一份通用 YAML 配置示例字段路径需要根据实际项目调整。# config.yaml 示例 llm: provider: openai-compatible base_url: ${LLM_BASE_URL} api_key: ${LLM_API_KEY} model: gpt-4o-mini temperature: 0.2 input: repo_path: ./example-project include: - **/*.ts - **/*.py - **/*.java exclude: - **/node_modules/** - **/vendor/** output: format: mermaid diagram_dir: ./diagrams verification_report: ./reports/verify.json配置文件中比较关键的是include和exclude规则。扫描大型仓库时如果不过滤node_modules、vendor、dist等目录扫描时间会很长也会把无关文件当成架构节点引入图里。4.4 启动服务并验证命令行模式下可以通过一个简单的命令生成架构图。# 命令行使用示例实际参数以项目文档为准 archify scan --repo ./example-project --output ./diagrams/service-arch.md服务模式下先启动本地 API 服务再通过浏览器或 HTTP 请求访问。# 启动本地 API 服务示例 archify serve --host 127.0.0.1 --port 3000启动后看到类似Server is running at http://127.0.0.1:3000的日志说明服务已经起来。接下来就可以进入功能测试环节。5. Archify 功能测试与效果验证功能测试的目标不是“把图生成出来”而是验证三个核心能力架构图是否能反映真实代码结构。图中关键关系和节点是否有来源路径。验证结果能不能帮助我们发现不一致。如果 Archify 真的实现了“可验证、可追踪路径”这两个卖点那么下面这组测试可以帮你把它测明白。5.1 测试准备准备一个最小项目建议先用一个公开的演示项目或团队内部小型开源项目测试不要一上来就扫描大型微服务仓库。这里用一个小型仓库结构作为示例说明。example-project/ ├── src/ │ ├── services/ │ │ ├── order-service/ │ │ │ ├── main.py │ │ │ └── api.py │ │ └── user-service/ │ │ ├── main.py │ │ └── api.py │ ├── gateway/ │ │ └── gateway.py │ └── shared/ │ ├── models.py │ └── utils.py ├── docs/ │ └── README.md └── config/ └── service-config.yml这种规模的项目生成速度快结果也容易人工核对。测试时先把配置里的repo_path指向这个目录再运行扫描命令。5.2 功能测试用例表测试项输入操作预期结果判断标准微服务架构图生成小型仓库扫描结果执行扫描并请求生成微服务架构图输出包含服务节点和调用关系图中服务名称与仓库模块一致业务架构图生成项目说明文档 代码扫描结果使用业务视角生成架构图输出按业务域分组或标注边界能判断该图是业务视角而不是纯技术视角架构图准确性验证生成结果运行验证命令或查看验证报告报告中标出已验证关系和未验证关系没有把模型推断当成代码事实溯源路径检查生成结果中的任意连线点击节点或查看溯源记录能看到这条连线来自哪个文件、哪个函数声明溯源路径能定位到具体代码位置批量任务多个待分析项目列表运行批量扫描脚本多个项目依次生成架构图每个项目都有独立输出目录和日志Skill 定制自定义架构规范配置加载团队自定义 Skill 后重新生成图输出符合团队规范如分层、命名规则架构图风格与团队定义一致5.3 测试微服务架构图生成以“微服务架构图”为例完整的执行步骤可以这样设计。确认扫描目录已配置到该项目。执行扫描命令等待代码解析完成。生成微服务架构图输出为 Mermaid 或 PNG。打开生成的架构图检查服务节点数量是否和src/services目录中的服务对应。检查gateway到各个服务之间的调用关系是否和代码里的实际调用一致。如果图中出现代码里不存在的节点说明模型产生了误判需要在验证报告中标记。# 生成微服务架构图示例 archify generate \ --view microservice \ --repo ./example-project \ --output ./diagrams/microservice-arch.md5.4 测试架构图验证机制架构图的验证是 Archify 区别于普通 AI 画图工具的核心模块。测试时重点观察生成的验证报告中是否区分了以下三种状态confirmed已扫描确认的关系依据是代码实现。inferred由模型推断的关系没有直接代码证据。conflict发现的不一致关系例如代码有调用但扫描未识别到。如果验证报告能清晰区分三类状态说明“可验证”不是停留在包装层而是有实际数据结构支撑。如果全部关系都显示inferred那就要小心了说明工具只是在「看起来分析过代码」实际上还是让大模型猜测。5.5 测试溯源路径溯源路径是架构图可追踪能力的具体体现。测试方法很简单找一个你熟悉的模块查看它生成的架构图中某条关系然后顺着溯源路径回到代码里确认。预期中的溯源信息至少包含来源文件路径。来源代码行号。定义该关系的类、函数或配置文件。关系类型比如 HTTP 调用、函数调用、数据库依赖、消息队列订阅等。如果溯源只能定位到“某个模块大概有调用”而定位不到具体文件和行号说明追踪能力还很粗不适合作为架构评审依据。6. Archify 接口 API 与批量任务如果 Archify 提供了 API 服务那么它就能很方便地接入你自己的运维平台、CI 流水线或文档生成系统。下面给出一个通用 HTTP API 调用示例字段路径需要按照实际项目的 API 文档调整。6.1 启动 API 服务先确保服务已经启动。如果架构图服务默认端口是 3000可以通过http://127.0.0.1:3000访问健康检查接口。curl http://127.0.0.1:3000/health如果返回 JSON 格式的{status: ok}说明服务可用。6.2 Python 调用示例import requests BASE_URL http://127.0.0.1:3000 payload { repo_path: /path/to/example-project, view: microservice, output_format: mermaid, include: [**/*.py, **/*.java], exclude: [**/node_modules/**, **/vendor/**] } response requests.post(f{BASE_URL}/api/generate, jsonpayload, timeout600) if response.status_code 200: data response.json() print(diagram_path:, data.get(diagram_path)) print(verification_report:, data.get(verification_report)) else: print(error:, response.status_code, response.text)注意架构图生成通常不是秒级任务仓库越大耗时越长。调用接口时要把timeout配置到足够大避免等待过程中连接被切断。6.3 批量任务设计Archify 适合做批量任务的场景包括一个微服务仓库里有多个子项目需要按项目分别生成架构图。定期刷新架构文档每天或每次 CI 构建后自动更新架构图。架构评审前对多个候选方案生成对比图。批量模式建议用目录驱动方式# 批量处理示例目录结构为 projects/ 下每个子目录是一个独立项目 archify batch \ --projects-dir ./projects \ --output-dir ./outputs \ --view microservice \ --parallel 2--parallel用于控制并发任务数。并发数过高可能触发大模型服务的限流建议从 1 或 2 开始测试逐步调大。批量任务建议加日志。每个项目生成结束后在日志中记录成功或失败状态。失败任务要有重试机制一般重试 3 次每次间隔 10 秒。# 批量任务日志示例 archify batch --log-level info --retry 3 --retry-interval 107. 资源占用与性能观察架构图生成任务的资源消耗主要集中在三个阶段仓库解析、大模型推理、图渲染。每个阶段观察重点不同。7.1 仓库解析阶段这个阶段主要消耗 CPU、内存和磁盘 IO。大仓库扫描时如果配置了递归扫描且没有排除依赖目录内存占用会快速上升。观察方式# Linux / macOS 下实时观察资源占用 top -pid archify_pid如果内存占用持续增长并接近系统上限优先检查是否扫进了node_modules、.git、dist等目录。在配置文件的exclude中把不需要的目录排除掉能显著加快扫描速度。7.2 大模型推理阶段这部分消耗取决于你使用的是云端 API 还是本地模型。云端 API主要观察 token 消耗和请求延迟。架构图生成不是单次请求往往需要多次模型调用来分析不同模块token 成本可能超出预期。本地模型需要观察显存和内存占用具体数值取决于模型规模、上下文长度和并发任务数。增量生成如果工具支持增量模式尽量使用增量生成只处理变更部分避免每次都全量扫描和全量推理。没有进行实际压力测试前不要轻信某个固定的显存数字。稳妥的做法是先在小型仓库上跑通记录首次扫描的资源消耗再估算大型仓库的峰值。7.3 图渲染阶段图渲染阶段主要消耗 CPU。节点数量多时浏览器或渲染器可能出现卡顿。如果生成的微服务架构图节点超过几百个建议开启分组或折叠模式优先展示服务级关系再下钻到接口级关系。7.4 降低资源占用的建议扫描阶段排除依赖目录和生成文件目录。模型阶段降低 temperature 参数关闭并行请求减少上下文传递。渲染阶段不要一次性渲染全量大图按系统、模块、服务三级拆分视图。任务调度错开批量任务执行时间避免同一小时内打满模型 API 配额。8. Archify 常见问题与排查方法下面按实际使用中的频率列出常见问题。由于缺少具体项目的日志样本这里给的是通用排查思路。问题现象可能原因排查方式解决方案安装命令执行失败包名不对、Node/Python 版本不兼容查看 README 中的安装命令和版本要求按官方文档安装指定版本依赖命令执行后提示找不到archify安装目录未加入 PATH执行which archify或npm list -g把安装 bin 目录加入 PATH扫描时内存持续升高没有排除依赖目录递归扫描了无关文件查看日志中扫描文件数量在配置中添加exclude规则生成的架构图与代码不一致模型推断权重过高验证逻辑未生效查看验证报告中的确认状态增加代码解析规则减少纯 LLM 推断溯源路径模糊无法定位到具体文件解析器没有抓到精确调用关系检查某个被调用的服务是否有真实代码引用补充语言解析插件或调整扫描策略API 调用超时仓库太大单次请求时间过长查看服务端日志使用批量模式拆分为多个子任务调用大模型 API 返回限流错误并发请求过多或配额不足查看 API 服务返回的rate limit字段降低并发数增加重试间隔端口被占用本机已有服务使用同一端口执行lsof -i:3000查看占用进程更换启动端口--port 3001批量任务中途卡住某个项目扫描异常或 API 长时间无响应查看批量任务日志定位卡住项目在批量脚本中增加超时终止逻辑输出结果文件不完整生成过程被中断或写入失败检查输出目录权限和磁盘空间修复权限、释放磁盘后重跑排查时优先看日志。如果工具没有提供调试模式可以先用--log-level debug或DEBUGtrue环境变量尝试打开更详细的输出。9. Archify 最佳实践与使用建议9.1 从小项目开始验证第一次使用 Archify 时不要直接扫描公司最大的仓库。选一个小型项目先生成一张图再人工核对几个关键节点和连线。这一步通过后再逐步扩大到真实业务系统。9.2 把验证报告当成核心交付物使用 Archify 时不要只保存架构图。verification_report有时比图本身更有价值因为它能指出哪些关系是代码确认过的哪些是模型推测的哪些存在冲突。架构评审时把验证报告作为附件能让评审人快速聚焦风险点。9.3 与 CI 集成保持架构图不老化架构图最大的问题是容易过期。如果 Archify 支持命令行或 API 调用可以把它接到 CI 流程中每次合并代码后自动重新扫描受影响模块重新生成局部架构图并和上一次版本对比。这样架构文档不是一次性交付物而是持续更新的资产。9.4 用 Skill 定制团队规范很多人关注 Archify 的一个重要原因是它可能支持 Skill 扩展。通过 Skill 可以把团队特有的分层规范、命名规范、安全约束注入到生成过程中。例如要求所有外部请求必须经过网关所有数据访问必须走仓库层。如果项目支持这类定制建议第一批尝试。9.5 注意数据和隐私边界架构图生成依赖代码扫描和大模型推理。对于商业敏感项目最安全的做法是使用私有化模型或企业内部网关。如果只能使用外部 API要在上传前做代码脱敏替换真实服务名、数据库地址、域名等敏感信息。不要在架构图中暴露未脱敏的内部网络结构。10. 总结与下一步Archify 这类项目的意义不在于“AI 会画架构图”而在于它尝试把架构图从“画着看看”变成“可验证、可追踪”的工程资产。如果你所在的团队正在做微服务架构梳理、服务迁移、或架构文档自动化更新Archify 值得你花一个下午安装并跑通一个 Demo。最先要验证的不是它能画多好看的图而是它能不能给出一条可信的验证路径生成结果中哪些关系有代码依据、哪些是模型推断、哪些存在冲突。这个能力直接决定了架构图能不能用于评审和决策。最容易踩的坑有三个一是安装时依赖版本不匹配二是大仓库扫描时没有排除依赖目录导致内存暴涨三是把模型推断结果当成代码事实忽略验证报告中的inferred和conflict状态。后续可以延伸的方向包括将 Archify 接入 CI 实现架构漂移检测、为团队定制架构规范 Skill、把生成的架构图同步到内部 Wiki。架构图只是第一步基于它的治理和自动化才是这笔投入真正回本的地方。建议先收藏这篇文章等安装时可以对照操作。 Archify：可验证、可追踪的AI架构图生成工具
这次我们来看一个架构图方向的 AI 项目Archify。它目前在 GitHub 上已经积累了 3.5 万 Star关注点不是“AI 能不能画出好看的架构图”而是画出来的架构图能不能验证、能不能追踪来源。也就是说Archify 生成的微服务架构图、业务架构图、系统架构图不是一次性 PPT 素材而是可以作为架构评审、代码重构、技术对接时的可信依据。提到 AI 生成架构图很多人第一反应是丢给大模型一句话让它吐一张 Mermaid 代码或 PNG 图片。这个方案的问题很明显生成的图“看起来合理”但图中每个节点和连线对应的到底是哪段代码、哪个服务、哪条真实依赖往往说不清楚。Archify 要解决的就是这一类准确性和可追溯性缺口让 AI 在生成架构视图的同时保留从原始输入到最终输出的追踪路径让每条关系都能回到原始来源再通过验证机制确认生成结果和真实系统之间的差距。这篇文章会围绕 Archify 展开完整的使用路径核心能力、适合场景、环境准备、安装部署、功能测试、接口调用、资源占用、常见问题与最佳实践。关心“AI 架构图工具怎么选”“Archify 怎么用”“能不能接入自己团队的架构治理流程”的人可以直接按章节操作。1. Archify 核心能力速览在动手安装之前先把 Archify 的关键属性过一遍。下面这张表把项目类型、能力边界、使用门槛和扩展方式集中列出来方便你快速判断它适不适合当前团队。能力项说明项目类型AI 辅助架构图生成与分析工具开源热度GitHub Star 约 3.5 万属于架构图方向高关注度项目核心卖点可验证、可追踪路径的架构图生成不是单纯“AI 画图”主要输入代码仓库、项目文档、需求描述、既有系统信息主要输出架构图、架构视图、架构说明文本、溯源记录架构图类型可覆盖微服务架构图、业务架构图、系统架构图、技术架构图等扩展能力从社区关注度看如 officiating Skill 或自定义技能机制可将通用架构能力定制到团队技术栈是否支持 API多数同类工具会提供接口服务具体路径以项目官方文档为准是否支持批量任务需要按项目文档确认可重点看其命令行或服务端是否支持多个仓库批量扫描典型显存需求如果使用云端大模型 API本地显存压力很小如果接入本地大模型需根据模型规模单独评估显存适合场景微服务梳理、系统架构图绘制、架构评审、代码迁移前分析、架构文档自动化更新从项目定位看Archify 最值得关注的是它把“架构图生成”和“验证机制”绑在一起。传统工具画图之后图和代码是两套东西改代码后图就过期了Archify 的思路更像是用 AI Agent 自动扫描项目结构再把扫描结果映射成架构视图每一步都有来源依据。这样画出来的图至少能在“哪些关系来自代码扫描”“哪些关系来自模型推断”“哪些关系需要人工确认”之间做区分。需要说明的是目前公开材料里没有给出 Archify 完整的硬件参数和接口文档所以“API 路径”“批量上限”“最小环境要求”这些信息最稳妥的方式是直接看项目 README 和官方文档。下面的部署与测试流程我会按通用 AI 工具实践给出可执行模板实际操作时把路径和字段替换成你自己项目的真实配置即可。2. 适用场景与使用边界2.1 适合谁用Archify 这一类工具最适合三类人。第一类是后端架构师和技术负责人。微服务拆到十几个模块后靠人工维护一张架构图成本很高用 AI 工具自动扫描代码仓库并生成依赖关系视图能大幅缩短架构梳理时间。第二类是正在做技术重构的团队。重构前需要先搞清楚现有系统到底有哪些服务、哪些调用了没接网关、哪些模块存在循环依赖这些信息如果能由 AI 自动扫出来比肉眼翻代码可靠得多。第三类是技术文档写作者。架构文档中需要系统架构图、技术架构图、业务架构图配图传统方式是手工画而 Archify 能把“生成配图”这步自动化。从搜热词来看很多人在关注“微服务架构图”“系统架构图”“技术架构图”这几个方向说明架构图并不仅仅是给汇报用的更多是开发过程里的真实工作产物。Archify 这类生成可验证架构图的工具正好踩中了这个需求点。2.2 什么时候没必要用如果项目很小一个模块几百行代码手工画图反而更快如果团队文档纪律差代码结构和实际情况严重脱节任何 AI 工具都很难自动恢复出可信架构图如果只想要一张好看但不追求准确的架构图用于对外展示那传统绘图软件的效果可能更可控。Archify 的优势在于“可验证”这也就意味着它会对准确性负责反过来也会要求输入质量不能太差。2.3 使用边界与合规提醒架构图往往涉及企业内部核心代码结构、服务依赖、中间件选型等敏感信息。在使用 Archify 时要注意不要直接上传未脱敏的私有仓库到公共大模型服务尽量使用私有化部署或企业内部模型网关生成结果如果包含人脸、个人信息、版权素材等非架构图内容必须清除后再做后续处理团队内部做架构评审时应把 AI 生成的图作为辅助材料关键决策仍需人工确认不能完全依赖 AI 输出。3. Archify 本地部署环境准备Archify 的部署方式需要根据项目官方文档确认但绝大多数 AI 架构图工具都会提供命令行工具或本地服务两种使用方式。下面先给出一份通用的环境检查清单避免装到一半才发现缺依赖。3.1 硬件与操作系统操作系统Windows 10/11、macOS、Linux 均可优先选择开发者日常使用的系统。CPU架构图生成主要涉及代码解析和大模型请求CPU 要求不高双核以上即可。内存解析大型仓库时建议至少 8GB如果仓库包含大量依赖文件16GB 更稳妥。GPU如果使用云端大模型 APIGPU 不是必需如果本地跑推理模型按模型实际显存需求评估。磁盘项目本体占用通常不大主要预留仓库扫描和输出结果的空间建议至少 10GB。3.2 依赖与运行环境Node.js 或 Python 环境取决于项目具体实现建议先按官方 README 确定主语言。Git用于克隆项目仓库。大模型 API KeyArchify 通常需要一个可访问的大模型服务作为生成引擎准备一个有权限的 Key。如果项目提供 Docker 镜像安装 Docker Desktop 或 Docker Engine 可简化环境隔离。如果项目支持 IDE 集成可以根据官方文档配置 Trae、VS Code 等开发工具的插件或外部命令。# 通用检查命令示例实际版本要求以项目文档为准 node -v npm -v python --version git --version docker --version3.3 网络与鉴权准备调用大模型 API 需要在配置文件中填入密钥。不要明文硬编码在代码仓库里建议使用环境变量或本地配置文件并把密钥文件加入.gitignore。# 环境变量示例实际变量名以项目文档为准 export LLM_API_KEYyour-api-key-here export LLM_BASE_URLhttps://your-llm-gateway.example.com如果使用企业内部模型网关还需要确认网关的鉴权方式、模型名称、超时时间等参数。这一步在批量任务场景中尤其重要因为批量扫描会持续调用大模型鉴权不通过会导致任务中断。4. Archify 安装部署与启动方式4.1 通过命令行工具安装如果 Archify 以 npm 包或 Python 包形式发布可以通过包管理器安装。下面给出通用命令模板实际包名和安装方式需要替换为项目 README 中的真实信息。# npm 方式示例以官方文档为准 npm install -g archify # 或使用 npx 直接运行 npx archify --version # Python 方式示例以官方文档为准 pip install archify archify --help安装完成后建议先执行--version或--help检查命令是否可用。如果命令不存在可能是因为全局 bin 目录没有加入 PATH此时需要找到安装路径并手动配置环境变量。4.2 通过 Docker 启动如果项目提供 Docker 镜像可以使用 Docker 启动服务。这种方式的好处是依赖隔离不会污染本机环境也方便在服务器上部署。# Docker 启动示例镜像名和端口以官方文档为准 docker pull archify/archify:latest docker run -d \ --name archify \ -p 3000:3000 \ -e LLM_API_KEYyour-api-key-here \ -v $(pwd)/outputs:/app/outputs \ archify/archify:latest启动后通过浏览器访问http://localhost:3000查看 Web 界面。如果页面打不开先检查容器是否正常运行docker ps docker logs archify --tail 1004.3 配置文件准备大部分 AI 架构图工具都会提供一个配置文件用来指定模型信息、仓库扫描路径、输出目录和批量任务参数。下面是一份通用 YAML 配置示例字段路径需要根据实际项目调整。# config.yaml 示例 llm: provider: openai-compatible base_url: ${LLM_BASE_URL} api_key: ${LLM_API_KEY} model: gpt-4o-mini temperature: 0.2 input: repo_path: ./example-project include: - **/*.ts - **/*.py - **/*.java exclude: - **/node_modules/** - **/vendor/** output: format: mermaid diagram_dir: ./diagrams verification_report: ./reports/verify.json配置文件中比较关键的是include和exclude规则。扫描大型仓库时如果不过滤node_modules、vendor、dist等目录扫描时间会很长也会把无关文件当成架构节点引入图里。4.4 启动服务并验证命令行模式下可以通过一个简单的命令生成架构图。# 命令行使用示例实际参数以项目文档为准 archify scan --repo ./example-project --output ./diagrams/service-arch.md服务模式下先启动本地 API 服务再通过浏览器或 HTTP 请求访问。# 启动本地 API 服务示例 archify serve --host 127.0.0.1 --port 3000启动后看到类似Server is running at http://127.0.0.1:3000的日志说明服务已经起来。接下来就可以进入功能测试环节。5. Archify 功能测试与效果验证功能测试的目标不是“把图生成出来”而是验证三个核心能力架构图是否能反映真实代码结构。图中关键关系和节点是否有来源路径。验证结果能不能帮助我们发现不一致。如果 Archify 真的实现了“可验证、可追踪路径”这两个卖点那么下面这组测试可以帮你把它测明白。5.1 测试准备准备一个最小项目建议先用一个公开的演示项目或团队内部小型开源项目测试不要一上来就扫描大型微服务仓库。这里用一个小型仓库结构作为示例说明。example-project/ ├── src/ │ ├── services/ │ │ ├── order-service/ │ │ │ ├── main.py │ │ │ └── api.py │ │ └── user-service/ │ │ ├── main.py │ │ └── api.py │ ├── gateway/ │ │ └── gateway.py │ └── shared/ │ ├── models.py │ └── utils.py ├── docs/ │ └── README.md └── config/ └── service-config.yml这种规模的项目生成速度快结果也容易人工核对。测试时先把配置里的repo_path指向这个目录再运行扫描命令。5.2 功能测试用例表测试项输入操作预期结果判断标准微服务架构图生成小型仓库扫描结果执行扫描并请求生成微服务架构图输出包含服务节点和调用关系图中服务名称与仓库模块一致业务架构图生成项目说明文档 代码扫描结果使用业务视角生成架构图输出按业务域分组或标注边界能判断该图是业务视角而不是纯技术视角架构图准确性验证生成结果运行验证命令或查看验证报告报告中标出已验证关系和未验证关系没有把模型推断当成代码事实溯源路径检查生成结果中的任意连线点击节点或查看溯源记录能看到这条连线来自哪个文件、哪个函数声明溯源路径能定位到具体代码位置批量任务多个待分析项目列表运行批量扫描脚本多个项目依次生成架构图每个项目都有独立输出目录和日志Skill 定制自定义架构规范配置加载团队自定义 Skill 后重新生成图输出符合团队规范如分层、命名规则架构图风格与团队定义一致5.3 测试微服务架构图生成以“微服务架构图”为例完整的执行步骤可以这样设计。确认扫描目录已配置到该项目。执行扫描命令等待代码解析完成。生成微服务架构图输出为 Mermaid 或 PNG。打开生成的架构图检查服务节点数量是否和src/services目录中的服务对应。检查gateway到各个服务之间的调用关系是否和代码里的实际调用一致。如果图中出现代码里不存在的节点说明模型产生了误判需要在验证报告中标记。# 生成微服务架构图示例 archify generate \ --view microservice \ --repo ./example-project \ --output ./diagrams/microservice-arch.md5.4 测试架构图验证机制架构图的验证是 Archify 区别于普通 AI 画图工具的核心模块。测试时重点观察生成的验证报告中是否区分了以下三种状态confirmed已扫描确认的关系依据是代码实现。inferred由模型推断的关系没有直接代码证据。conflict发现的不一致关系例如代码有调用但扫描未识别到。如果验证报告能清晰区分三类状态说明“可验证”不是停留在包装层而是有实际数据结构支撑。如果全部关系都显示inferred那就要小心了说明工具只是在「看起来分析过代码」实际上还是让大模型猜测。5.5 测试溯源路径溯源路径是架构图可追踪能力的具体体现。测试方法很简单找一个你熟悉的模块查看它生成的架构图中某条关系然后顺着溯源路径回到代码里确认。预期中的溯源信息至少包含来源文件路径。来源代码行号。定义该关系的类、函数或配置文件。关系类型比如 HTTP 调用、函数调用、数据库依赖、消息队列订阅等。如果溯源只能定位到“某个模块大概有调用”而定位不到具体文件和行号说明追踪能力还很粗不适合作为架构评审依据。6. Archify 接口 API 与批量任务如果 Archify 提供了 API 服务那么它就能很方便地接入你自己的运维平台、CI 流水线或文档生成系统。下面给出一个通用 HTTP API 调用示例字段路径需要按照实际项目的 API 文档调整。6.1 启动 API 服务先确保服务已经启动。如果架构图服务默认端口是 3000可以通过http://127.0.0.1:3000访问健康检查接口。curl http://127.0.0.1:3000/health如果返回 JSON 格式的{status: ok}说明服务可用。6.2 Python 调用示例import requests BASE_URL http://127.0.0.1:3000 payload { repo_path: /path/to/example-project, view: microservice, output_format: mermaid, include: [**/*.py, **/*.java], exclude: [**/node_modules/**, **/vendor/**] } response requests.post(f{BASE_URL}/api/generate, jsonpayload, timeout600) if response.status_code 200: data response.json() print(diagram_path:, data.get(diagram_path)) print(verification_report:, data.get(verification_report)) else: print(error:, response.status_code, response.text)注意架构图生成通常不是秒级任务仓库越大耗时越长。调用接口时要把timeout配置到足够大避免等待过程中连接被切断。6.3 批量任务设计Archify 适合做批量任务的场景包括一个微服务仓库里有多个子项目需要按项目分别生成架构图。定期刷新架构文档每天或每次 CI 构建后自动更新架构图。架构评审前对多个候选方案生成对比图。批量模式建议用目录驱动方式# 批量处理示例目录结构为 projects/ 下每个子目录是一个独立项目 archify batch \ --projects-dir ./projects \ --output-dir ./outputs \ --view microservice \ --parallel 2--parallel用于控制并发任务数。并发数过高可能触发大模型服务的限流建议从 1 或 2 开始测试逐步调大。批量任务建议加日志。每个项目生成结束后在日志中记录成功或失败状态。失败任务要有重试机制一般重试 3 次每次间隔 10 秒。# 批量任务日志示例 archify batch --log-level info --retry 3 --retry-interval 107. 资源占用与性能观察架构图生成任务的资源消耗主要集中在三个阶段仓库解析、大模型推理、图渲染。每个阶段观察重点不同。7.1 仓库解析阶段这个阶段主要消耗 CPU、内存和磁盘 IO。大仓库扫描时如果配置了递归扫描且没有排除依赖目录内存占用会快速上升。观察方式# Linux / macOS 下实时观察资源占用 top -pid archify_pid如果内存占用持续增长并接近系统上限优先检查是否扫进了node_modules、.git、dist等目录。在配置文件的exclude中把不需要的目录排除掉能显著加快扫描速度。7.2 大模型推理阶段这部分消耗取决于你使用的是云端 API 还是本地模型。云端 API主要观察 token 消耗和请求延迟。架构图生成不是单次请求往往需要多次模型调用来分析不同模块token 成本可能超出预期。本地模型需要观察显存和内存占用具体数值取决于模型规模、上下文长度和并发任务数。增量生成如果工具支持增量模式尽量使用增量生成只处理变更部分避免每次都全量扫描和全量推理。没有进行实际压力测试前不要轻信某个固定的显存数字。稳妥的做法是先在小型仓库上跑通记录首次扫描的资源消耗再估算大型仓库的峰值。7.3 图渲染阶段图渲染阶段主要消耗 CPU。节点数量多时浏览器或渲染器可能出现卡顿。如果生成的微服务架构图节点超过几百个建议开启分组或折叠模式优先展示服务级关系再下钻到接口级关系。7.4 降低资源占用的建议扫描阶段排除依赖目录和生成文件目录。模型阶段降低 temperature 参数关闭并行请求减少上下文传递。渲染阶段不要一次性渲染全量大图按系统、模块、服务三级拆分视图。任务调度错开批量任务执行时间避免同一小时内打满模型 API 配额。8. Archify 常见问题与排查方法下面按实际使用中的频率列出常见问题。由于缺少具体项目的日志样本这里给的是通用排查思路。问题现象可能原因排查方式解决方案安装命令执行失败包名不对、Node/Python 版本不兼容查看 README 中的安装命令和版本要求按官方文档安装指定版本依赖命令执行后提示找不到archify安装目录未加入 PATH执行which archify或npm list -g把安装 bin 目录加入 PATH扫描时内存持续升高没有排除依赖目录递归扫描了无关文件查看日志中扫描文件数量在配置中添加exclude规则生成的架构图与代码不一致模型推断权重过高验证逻辑未生效查看验证报告中的确认状态增加代码解析规则减少纯 LLM 推断溯源路径模糊无法定位到具体文件解析器没有抓到精确调用关系检查某个被调用的服务是否有真实代码引用补充语言解析插件或调整扫描策略API 调用超时仓库太大单次请求时间过长查看服务端日志使用批量模式拆分为多个子任务调用大模型 API 返回限流错误并发请求过多或配额不足查看 API 服务返回的rate limit字段降低并发数增加重试间隔端口被占用本机已有服务使用同一端口执行lsof -i:3000查看占用进程更换启动端口--port 3001批量任务中途卡住某个项目扫描异常或 API 长时间无响应查看批量任务日志定位卡住项目在批量脚本中增加超时终止逻辑输出结果文件不完整生成过程被中断或写入失败检查输出目录权限和磁盘空间修复权限、释放磁盘后重跑排查时优先看日志。如果工具没有提供调试模式可以先用--log-level debug或DEBUGtrue环境变量尝试打开更详细的输出。9. Archify 最佳实践与使用建议9.1 从小项目开始验证第一次使用 Archify 时不要直接扫描公司最大的仓库。选一个小型项目先生成一张图再人工核对几个关键节点和连线。这一步通过后再逐步扩大到真实业务系统。9.2 把验证报告当成核心交付物使用 Archify 时不要只保存架构图。verification_report有时比图本身更有价值因为它能指出哪些关系是代码确认过的哪些是模型推测的哪些存在冲突。架构评审时把验证报告作为附件能让评审人快速聚焦风险点。9.3 与 CI 集成保持架构图不老化架构图最大的问题是容易过期。如果 Archify 支持命令行或 API 调用可以把它接到 CI 流程中每次合并代码后自动重新扫描受影响模块重新生成局部架构图并和上一次版本对比。这样架构文档不是一次性交付物而是持续更新的资产。9.4 用 Skill 定制团队规范很多人关注 Archify 的一个重要原因是它可能支持 Skill 扩展。通过 Skill 可以把团队特有的分层规范、命名规范、安全约束注入到生成过程中。例如要求所有外部请求必须经过网关所有数据访问必须走仓库层。如果项目支持这类定制建议第一批尝试。9.5 注意数据和隐私边界架构图生成依赖代码扫描和大模型推理。对于商业敏感项目最安全的做法是使用私有化模型或企业内部网关。如果只能使用外部 API要在上传前做代码脱敏替换真实服务名、数据库地址、域名等敏感信息。不要在架构图中暴露未脱敏的内部网络结构。10. 总结与下一步Archify 这类项目的意义不在于“AI 会画架构图”而在于它尝试把架构图从“画着看看”变成“可验证、可追踪”的工程资产。如果你所在的团队正在做微服务架构梳理、服务迁移、或架构文档自动化更新Archify 值得你花一个下午安装并跑通一个 Demo。最先要验证的不是它能画多好看的图而是它能不能给出一条可信的验证路径生成结果中哪些关系有代码依据、哪些是模型推断、哪些存在冲突。这个能力直接决定了架构图能不能用于评审和决策。最容易踩的坑有三个一是安装时依赖版本不匹配二是大仓库扫描时没有排除依赖目录导致内存暴涨三是把模型推断结果当成代码事实忽略验证报告中的inferred和conflict状态。后续可以延伸的方向包括将 Archify 接入 CI 实现架构漂移检测、为团队定制架构规范 Skill、把生成的架构图同步到内部 Wiki。架构图只是第一步基于它的治理和自动化才是这笔投入真正回本的地方。建议先收藏这篇文章等安装时可以对照操作。