Swark：基于LLM与GitHub Copilot的代码架构图自动生成工具

1. 项目概述：当代码“开口说话”，架构图自动生成

在软件开发的日常里，我们常常面临一个经典困境：接手一个新项目，或者时隔数月再看自己的旧代码，面对满屏的文件和目录，第一反应往往是——“这项目的整体架构到底长什么样？” 传统的解决方案，要么是手动在绘图工具里拖拽方块和箭头，费时费力且极易过时；要么是依赖一些基于静态分析的代码可视化工具，但它们往往对语言和框架有严格要求，配置复杂，生成的图表也常常是冷冰冰的、过于细节的依赖图，而非我们大脑中理解的“架构”。

今天要聊的Swark，就是一把试图斩断这个“戈尔迪之结”的利剑。它是一个开源的 VS Code 扩展，核心功能如其口号所言：Automatic Architecture Diagrams from Code。最吸引人的一点是，它巧妙地利用了 GitHub Copilot 内置的大语言模型能力，让你无需配置任何额外的 API 密钥，就能让 LLM “读懂”你的代码，并生成一份可读性不错的架构图。

想象一下这个场景：你刚克隆了一个陌生的仓库，在 VS Code 里打开，按下快捷键，几十秒后，一份用 Mermaid 语法描述的架构图就呈现在你面前。模块如何划分、核心组件有哪些、它们之间如何交互，一目了然。这不仅仅是给新人看的“导航图”，更是老鸟快速回顾、发现设计债（比如循环依赖、模块边界模糊）的利器。对于当下 AI 生成代码日益普及的现状，Swark 也能帮你快速“可视化审查” AI 产出的代码结构是否合理。

2. 核心设计思路：为何是“LLM + Copilot”这条路？

Swark 的设计选择非常有意思，它没有走传统静态分析工具的老路，而是选择了一条更“智能”、但也更依赖现有生态的路径。理解这个选择背后的逻辑，能帮助我们更好地使用它，甚至预判它的局限。

2.1 传统工具的困境与 LLM 的破局点

经典的代码可视化工具，比如一些基于 AST（抽象语法树）的分析器，其工作原理是确定性的。它们需要为每一种编程语言编写特定的解析规则，来识别类、函数、导入语句等。这就带来了几个问题：

1. 语言支持滞后：每支持一种新语言或一个新框架，都需要投入大量开发精力。对于 Go、Java 这类静态语言还好，对于 Python（动态类型）、JavaScript（各种模块规范）或新兴语言，支持起来就非常麻烦。
2. 架构语义缺失：静态分析能告诉你A.py导入了B.py，但它很难判断这种导入是“核心服务调用数据访问层”，还是仅仅是“工具函数引用”。架构图的核心是表达逻辑关系和职责边界，而不仅仅是文件依赖。
3. 配置复杂：为了生成有意义的图，用户往往需要编写复杂的配置文件，指明哪些目录是“控制器”，哪些是“模型”，过滤掉测试文件、第三方库等。

LLM 的出现，提供了一种全新的可能性。它不依赖于硬编码的语法规则，而是通过在海量代码和文本上训练出的“理解能力”，直接从代码文本中推断出架构信息。Swark 正是利用了这一点：它将选中的代码文件作为上下文，抛给 LLM，并给出一个精心设计的指令（Prompt），要求 LLM 以 Mermaid 图表的形式输出对架构的理解。

2.2 无缝集成 GitHub Copilot：降低使用门槛的关键一招

Swark 另一个精妙的设计是直接集成 GitHub Copilot。这个选择带来了多重好处：

• 零配置启动：用户不需要去 OpenAI、Anthropic 等平台申请 API 密钥，也不需要处理复杂的计费和网络问题。只要你在 VS Code 里安装了 Copilot（并且处于登录和激活状态），Swark 就能直接工作。Copilot 目前提供的免费 tier 更是让这个工具的门槛降到了几乎为零。
• 隐私保障：你的源代码只会被发送给你已经授权并信任的 GitHub Copilot 服务。Swark 本身不设立任何中间服务器来中转你的代码，这消除了对第三方服务的隐私顾虑。项目也明确声明，其收集的遥测数据不包含任何源代码或个人信息。
• 利用成熟接口：VS Code 提供了官方的 Language Model API，Swark 通过这个标准接口与 Copilot 通信，避免了自行处理 HTTP 请求、认证、流式响应等复杂问题，让扩展本身更稳定、更轻量。

2.3 Mermaid.js：将“图表即代码”进行到底

Swark 选择 Mermaid.js 作为输出格式，是一个兼顾了实用性和开放性的决定。Mermaid 是一种基于文本的图表定义语言，你可以用写代码的方式画流程图、时序图、类图、架构图等。

• 可编辑、可版本控制：生成的.md文件是纯文本，你可以直接打开修改 Mermaid 语法来调整图表布局、修正 LLM 理解的小偏差，或者增补说明。这个文件可以像其他源代码一样被git管理，架构图的变更历史一目了然。
• 生态友好：VS Code 有优秀的 Mermaid 预览插件（如 Markdown Preview Mermaid Support），GitHub/GitLab 的 Markdown 渲染器也原生支持 Mermaid，这意味着你生成的图表可以无缝嵌入到项目的 README 或文档中，保持文档的即时可读性和一致性。
• 轻量级输出：相比于输出一张 PNG 或 SVG 图片，输出文本格式的 Mermaid 代码在 LLM 的 token 消耗上更经济，响应更快。

注意：LLM 生成的 Mermaid 代码有时可能会包含导致渲染失败的语法错误，比如非法的循环依赖。Swark 提供了一个设置项swark.fixMermaidCycles，可以尝试自动修复这些问题，但复杂情况下可能仍需手动调整。

3. 从安装到生成：手把手实操指南

了解了背后的理念，我们来实际操练一遍，看看如何从零开始，让 Swark 为你的项目画出一张架构图。

3.1 环境准备与安装

首先，确保你的工作环境满足以下两个核心条件：

1. Visual Studio Code：这是基础，建议使用较新的版本。
2. GitHub Copilot 扩展：这是 Swark 的“发动机”。前往 VS Code 扩展市场搜索 “GitHub Copilot” 并安装。安装后，你需要用 GitHub 账号登录并授权。重要提示：即使你不订阅 Copilot 的付费计划，其免费版本也足以支持 Swark 的基本功能，这几乎是零成本。

接下来，安装 Swark 扩展本身。同样在 VS Code 扩展市场中搜索 “Swark”，找到由 “swark-io” 发布的扩展，点击安装即可。整个过程没有任何需要填写的 API 密钥或复杂配置。

3.2 首次运行与核心操作

安装完成后，找一个你想分析的项目，在 VS Code 中打开其根目录。然后，你可以通过以下两种方式启动 Swark：

• 命令面板（推荐）：按下Cmd+Shift+P(Mac) 或Ctrl+Shift+P(Windows/Linux)，打开命令面板，输入 “Swark: Create Architecture Diagram”，然后回车。
• 快捷键：Swark 设置了默认快捷键Cmd+Shift+R(Mac) 或Ctrl+Shift+R(Windows/Linux)。如果快捷键冲突，你可以在 VS Code 的键盘快捷方式设置中修改。

执行命令后，Swark 会首先让你选择一个文件夹作为分析范围。通常，选择项目的根目录即可。如果你只想分析某个子模块（比如src/services/），也可以导航到那个子文件夹。

点击确认后，Swark 就开始工作了。你会看到 VS Code 底部状态栏有提示，扩展正在读取文件、构建提示词、调用 Copilot。这个过程通常需要 10 到 30 秒，取决于项目大小和网络状况。

3.3 理解输出结果

运行成功后，VS Code 会自动打开一个新的标签页，里面就是生成的架构图。这个文件保存在你工作区根目录下的swark-output文件夹里。

每次运行都会生成两个文件，用时间戳区分，例如：

your-project/ ├── src/ ├── ... └── swark-output/ ├── 2025-01-09__20-18-38__diagram.md └── 2025-01-09__20-18-38__log.md

• *__diagram.md：这是核心输出，一个 Markdown 文件，内容主要是用 Mermaid 语法编写的图表代码。如果安装了 Mermaid 预览插件，你可以右键选择“打开预览”来查看渲染后的图形。
• *__log.md：这是日志文件，记录了本次运行的详细信息，非常有用。它包括：
  • Swark 的配置（使用了哪些文件扩展名、排除了哪些模式等）。
  • 实际扫描并最终选择了哪些文件进行分析（受maxFiles和 token 限制影响）。
  • 发送给 LLM 的提示词（Prompt）内容。
  • LLM 的原始响应。
  • 其他诊断信息。当图表生成不理想或出错时，首先查看这个日志文件是排查问题的关键。

3.4 配置调优：让结果更精准

默认配置适用于大多数项目，但通过调整设置，你可以让 Swark 的输出更贴合你的需求。打开 VS Code 设置 (Ctrl+,)，搜索 “swark” 可以看到所有相关配置：

实操心得：对于第一次使用的项目，建议先保持默认设置运行一次。如果生成的图表过于笼统或遗漏了关键模块，再去查看log.md，看看它到底分析了哪些文件。通常，通过调整excludePatterns排除掉无关的构建产物、第三方库，再结合maxFiles限制，让 Swark 的“注意力”集中在核心业务代码上，效果会显著提升。

4. 深入原理：Swark 是如何工作的？

要更好地驾驭一个工具，有必要了解它的工作流程。Swark 的内部运作可以清晰地分为四个步骤，下图展示了这个完整流程：

flowchart TD A[用户启动 Swark] --> B[选择目标文件夹] B --> C{文件检索与筛选} C --> D[根据配置<br>（扩展名、排除模式）扫描文件] D --> E[按文件大小排序<br>并受 maxFiles 与 LLM Token 限制] E --> F[构建 LLM 提示词<br>包含指令与选中的代码] F --> G[通过 VS Code API<br>调用 GitHub Copilot] G --> H{LLM 生成<br>Mermaid 代码} H --> I[成功] I --> J[创建并预览 Diagram.md] H --> K[失败或需修复] K --> L[尝试修复循环依赖<br>（如配置开启）] L --> J K --> M[输出错误信息至 Log.md]

下面我们来拆解图中的几个关键环节：

4.1 文件检索的智能策略

Swark 不是简单地把文件夹里所有文件都扔给 LLM。它有一套策略来最大化利用有限的 LLM 上下文窗口：

1. 初步过滤：首先根据fileExtensions和excludePatterns设置，过滤出候选文件。
2. 排序与精选：然后，默认情况下，Swark 会按文件大小从小到大对候选文件进行排序。这个策略非常聪明：它优先包含那些小的、可能是核心的配置文件（如package.json,docker-compose.yml）、定义文件（如*.d.ts）或关键的入口文件。大的文件（通常是打包后的代码或资源）会被放在后面，如果 token 不够，就会被舍弃。这保证了有限的上下文里能塞进更多有“信息密度”的内容。
3. Token 计算与截断：Swark 会估算每个文件内容加上系统提示词所占的 token 数。它从文件列表的头部（小文件）开始累加，直到接近 Copilot 模型的上下文上限。此时，即使maxFiles的设置值还没达到，也会停止添加文件。

注意事项：这种按文件大小排序的策略在大多数情况下有效，但并非完美。有时，一个非常大的、但却是架构核心的源文件（比如一个庞大的main.go）可能会因为太大而被排除在外。如果你怀疑关键文件被漏掉了，查看log.md中的Selected files部分是第一步。

4.2 提示词工程：如何与 LLM 沟通

Swark 发送给 Copilot 的提示词是生成高质量图表的关键。虽然我们看不到完整的内部模板，但从日志和其目标可以推断，它至少包含了以下部分：

• 系统角色设定：指示 LLM 扮演一个“软件架构师”或“代码分析专家”的角色。
• 明确的任务指令：要求 LLM 分析提供的代码文件，推断出系统的高级架构，并用 Mermaid 的graph TD（自上而下图）或类似语法输出。
• 输出格式规范：严格规定输出的开始和结束标记（例如`），并要求只输出有效的 Mermaid 代码，不做额外解释。
• 架构指导原则：可能会鼓励 LLM 识别出诸如“前端”、“后端”、“API 层”、“数据库”、“服务”、“工具模块”、“第三方集成”等逻辑组件，而不是简单罗列文件名。
• 代码上下文：最后附上经过筛选的那些文件的实际内容。

这个精心构建的提示词，是 Swark 能从代码文本中提炼出架构语义的核心。

4.3 与 Copilot 的交互

Swark 通过 VS Code 的@vscode/language-modelAPI 与 Copilot 通信。这个 API 抽象了底层的模型调用，让扩展开发者无需关心具体的 HTTP 请求。Swark 只需要提供提示词和接收流式返回的文本。这种深度集成也意味着 Swark 的性能和稳定性与 Copilot 服务本身紧密相关。

5. 典型应用场景与实战技巧

Swark 不是一个“一次性”玩具，在软件开发的多个环节，它都能成为提升效率的帮手。

5.1 场景一：快速理解新项目或遗留代码

这是 Swark 最直接的价值。当你被扔进一个陌生的代码仓库，第一步不是漫无目的地阅读src下的每一个文件。

• 操作：在项目根目录运行 Swark。
• 技巧：首次运行后，如果图表过于庞大或杂乱，可以尝试分模块分析。例如，先对src/api/目录运行一次，生成 API 层的架构；再对src/services/运行一次。这样能得到更聚焦、更清晰的子架构图。
• 预期结果：你会得到一张展示主要组件（如UserController,AuthService,PostRepository）及其关系的图表。结合图表和日志里分析的文件列表，你能快速定位到核心的业务逻辑入口点。

5.2 场景二：审查与验证 AI 生成的代码结构

随着 GitHub Copilot、ChatGPT 等工具生成大量代码，如何快速评估这些代码的结构质量成了一个新问题。

• 操作：让 AI 生成一个功能模块后，立即用 Swark 对这个模块的目录进行分析。
• 技巧：关注生成的图表中，模块之间的连线是否清晰、单向。如果出现大量双向依赖或混乱的网状结构，可能提示 AI 生成的代码在职责分离上做得不够好，需要人工介入重构。
• 预期结果：一张能反映生成代码逻辑结构的图，帮助你判断其可维护性，避免“代码能跑，但是一团乱麻”的局面。

5.3 场景三：辅助文档与知识留存

架构图是项目文档不可或缺的部分，但手动维护的图总是容易过时。

• 操作：在编写或更新README.md时，运行 Swark 生成最新的架构图，将 Mermaid 代码块复制到文档中。
• 技巧：Swark 生成的 Mermaid 代码可能布局不够美观。你可以直接编辑生成的.md文件，调整 Mermaid 的语法，例如使用subgraph来分组，或者添加linkStyle来改变连线颜色，使其更符合文档要求。
• 预期结果：你的项目文档中始终有一张与代码同步的、可交互的（在支持 Mermaid 的平台）架构图，大大降低了文档的维护成本。

5.4 场景四：识别设计缺陷与优化点

架构图是一种强大的抽象工具，能帮你发现代码中不易察觉的设计问题。

• 操作：定期（如每个迭代结束时）为整个项目生成架构图，并花几分钟时间审视。
• 技巧：重点关注：
  1. 循环依赖：图表中是否有循环箭头？这通常是设计上的“坏味道”，可能导致编译问题或紧耦合。
  2. 中心化节点：是否有一个模块被几乎所有其他模块依赖？这可能是上帝对象（God Object）或单点故障的迹象。
  3. 孤立节点：是否有模块与其他部分毫无连接？这可能是 dead code，或者职责划分不清的遗留代码。
• 预期结果：将视觉化的架构问题转化为具体的重构任务，比如解耦循环依赖、拆分巨型服务等。

6. 常见问题、局限与排查手册

没有任何工具是银弹，Swark 也不例外。了解它的局限和常见问题，能让你更有效地使用它，并在遇到困难时快速解决。

6.1 图表质量不理想？可能的原因与对策

6.2 理解 Swark 的内在局限

1. 非确定性输出：由于依赖 LLM，每次运行的结果可能略有不同。它生成的是“对架构的理解”，而非“精确的依赖分析”。这既是优点（灵活、有语义），也是缺点（不完全可靠）。
2. 上下文窗口限制：受限于 Copilot 模型的 token 上限，它无法一次性分析超大型项目的所有代码。对于数百万行代码的仓库，它只能提供一个基于部分文件的、可能片面的视图。
3. 语言/框架理解深度：LLM 对常见语言（Python, JavaScript, Java）和流行框架（React, Spring）的理解较好，但对非常小众或新兴的技术栈，生成图表的准确性会下降。
4. 无法理解运行时行为：Swark 是静态分析（尽管是智能静态分析）。它无法获知代码的动态特性，比如依赖注入、运行时加载的模块、通过配置决定的流程分支等。

6.3 隐私与数据安全确认

这是一个合理的关切。根据其官方说明：

• 代码数据流向：你的源代码仅被发送至你已经授权和使用的GitHub Copilot 服务。Swark 扩展本身没有自己的后端服务器，不会将你的代码发送给任何第三方（如 OpenAI）。
• 遥测数据：Swark 会收集匿名的使用数据（如扩展激活次数、处理文件数、成功/失败事件），用于改进产品。这些数据明确不包含任何源代码、文件内容或个人身份信息。你可以在 VS Code 设置中全局关闭遥测 (telemetry.telemetryLevel)。

7. 进阶玩法与生态整合

当你熟悉了 Swark 的基本操作后，可以探索一些更进阶的用法，让它更好地融入你的工作流。

7.1 与版本控制系统结合

由于 Swark 的输出是纯文本的 Markdown 文件，你可以考虑将它纳入版本控制。

• 自动化生成：在项目的package.json或Makefile中定义一个脚本，在每次发布前或定期自动运行 Swark，更新架构图文档。这可以借助 VS Code 的命令行接口code --command来实现，虽然需要一些额外的编排。
• 架构变更追踪：将生成的diagram.md文件也提交到 Git。当代码架构发生重大变化时，通过git diff对比不同版本的架构图，可以直观地看到重构的影响范围。这比单纯看代码变更列表要清晰得多。

7.2 手动优化与定制 Mermaid 输出

Swark 生成的 Mermaid 代码是一个很好的起点，但你可以把它当作“草稿”来加工。

• 美化布局：Mermaid 允许你定义节点样式、连线样式和子图。你可以编辑生成的代码，添加style和classDef来让图表更美观。

  graph TD A[客户端] --> B(API网关) B --> C[用户服务] B --> D[订单服务] C --> E[(用户数据库)] D --> F[(订单数据库)] style A fill:#e1f5fe style B fill:#f3e5f5 style C fill:#c8e6c9 style D fill:#fff3e0 linkStyle 0 stroke:#2E86C1,stroke-width:2px; linkStyle 1 stroke:#7D3C98,stroke-width:2px;

• 增补信息：在图表中添加注释，说明某些设计决策、待办事项或风险点。Mermaid 支持在节点间添加%%注释，或者在图表外添加文本说明。

7.3 作为团队知识共享的工具

在团队 onboarding 或技术评审会议中，Swark 生成的图表可以作为一个高效的沟通媒介。

• 快速对齐：在讨论一个复杂模块时，先运行 Swark 生成当前状态的图，投屏给大家看。这确保了所有人对“现状”的理解是在同一张图上，避免各说各话。
• 设计讨论：基于当前架构图，用画笔工具在上面直接勾画提议的改动（比如：“我们在这里加一个缓存层”），让设计讨论更加具象和高效。

在我个人的使用体验中，Swark 最大的价值在于它极大地降低了获取代码全景图的心理和操作成本。以前需要半天甚至更长时间梳理的代码结构，现在几分钟就能得到一个八十分的可视化结果。它当然不能完全替代深入的代码阅读和设计文档，但它是一个绝佳的“第一眼”工具和持续性的“全景雷达”。把它当作一个随时可以咨询的、能快速画草图的搭档，而不是一个全知全能的架构师，你会收获更多惊喜。最后一个小建议是，不要追求一次生成完美的图，把它当成一个迭代的起点——生成、审视、调整代码、再生成，这个循环本身就能驱动你对代码结构进行持续的反思和优化。