从代码自动生成架构图
免费 • 开源 • 基于大语言模型

Swark

Swark 是一款 VS Code 扩展，能够利用大型语言模型（LLMs）自动从代码中生成架构图。
Swark 与 GitHub Copilot 直接集成，无需任何身份验证或 API 密钥。

为什么选择 Swark？

• 🌟 免费且开源：你只需要 GitHub Copilot，而现在它已经可以免费使用。你可以查看 Swark 的源码来了解其工作原理，并为改进它做出贡献。
• 🌍 支持所有编程语言：传统的代码可视化工具通常是基于规则的，需要逐步添加对新语言或框架的支持。而 Swark 将所有“逻辑”封装在 LLM 中，因此天然支持所有语言。
• 🔑 无缝集成：Swark 直接与 GitHub Copilot 集成，无需额外设置、认证或 API 密钥。
• 🛡️ 隐私至上：你的源代码仅会共享给 GitHub Copilot——不会涉及任何其他外部 API 或服务提供商。
• 🧜‍♀️ Mermaid.js 格式：Swark 生成的图表采用 Mermaid.js 格式，这是一种流行的“代码即图表”框架。你可以根据需要编辑和优化这些图表。

使用场景

• 🔎 学习新代码库：快速生成架构图，帮助你从宏观层面理解不熟悉的代码仓库。非常适合新人入职和接手新项目。
• 🤖 审查 AI 生成的代码：随着 AI 生成代码的普及，Swark 可以帮助你快速可视化其结构，确保符合预期标准。
• 📕 完善文档：通过几分钟内生成的最新架构图，保持文档的新鲜度和详细性。
• 🕰️ 理解遗留代码：快速可视化并理解旧代码库的结构，便于维护和重构。
• 🧩 发现设计缺陷：通过可视化代码库的依赖关系图，识别不必要的依赖或可优化的部分。
• ✅ 测试覆盖率分析：将测试文件纳入 Swark 的输入，一目了然地查看测试覆盖率并填补空白。

系统要求

• GitHub Copilot：Swark 与 GitHub Copilot 集成，用于调用 LLM 查询。可通过 Visual Studio Marketplace 安装。请注意，GitHub Copilot 现已提供免费层级。
• [可选] Mermaid Markdown 预览：若要在 VS Code 中预览图表，可安装 Markdown Preview Mermaid Support 扩展。或者，也可以使用提供的链接在 Mermaid Live Editor 中打开。

安装

只需通过 VS Code 扩展市场 安装 Swark。

使用方法

1. 在 VS Code 中，打开 命令面板，运行：Swark: 创建架构图。
   或者，你也可以使用 Swark 的默认快捷键：cmd+shift+r（Mac）或 ctrl+shift+r（Windows）。
2. 选择一个文件夹作为 Swark 的文件搜索范围。
3. 几秒钟后，会打开一个标签页，显示你的架构图。

输出

Swark 会将输出保存到工作区根目录下的 swark-output 文件夹中。
每次运行时，Swark 会生成两个文件：

• 图表文件：包含 Mermaid 代码的图表文件。这是你在运行 Swark 时看到的文件。
  文件名：<日期>__<时间>__diagram.md
• 日志文件：包含本次运行的信息、配置以及用于生成图表的文件列表。可用于调试和问题报告。
  文件名：<日期>__<时间>__log.md

例如：

workspace-root
└── swark-output
    ├── 2025-01-09__20-18-38__diagram.md
    └── 2025-01-09__20-18-38__log.md

工作原理

1. 文件检索：Swark 会检索所选文件夹中的代码文件。Swark 会自动调整检索的文件数量，以适应 LLM 的最大 token 限制。
2. 构建提示词：根据检索到的文件，Swark 构建用于生成架构图的提示词。提示词中会包含代码文件以及如何构建图表的说明。
3. LLM 请求：Swark 通过 VS Code 的 语言模型 API 向 GitHub Copilot 发起 LLM 请求。
4. 图表预览：成功响应后，图表会被呈现出来。实现方式是创建一个包含 Mermaid 语法的 Markdown 文件，并进行预览。

源码访问与文件共享

需要注意的是，源代码仅会共享给 GitHub Copilot，不会与其他任何外部 API 或服务提供商共享。

扩展设置

此扩展提供了以下设置：

设置	描述
swark.maxFiles	最大读取文件数。 实际读取的文件数量还受 LLM 最大 token 限制的影响。
swark.fileExtensions	搜索时要包含的文件扩展名列表。
swark.excludePatterns	用于从文件搜索中排除的 glob 模式列表。 默认包括：**/.* 用于隐藏文件，**/node_modules/** 用于 node 模块。
swark.languageModel	用于生成图表的语言模型。
swark.fixMermaidCycles	自动修复生成的 Mermaid 图表中的循环，以防止渲染失败。

发行说明

请参阅 CHANGELOG.md。

贡献

Swark 欢迎社区贡献。 有关如何贡献的详细信息，请参阅我们的 贡献指南。

隐私声明

此扩展会收集遥测数据，以帮助改善产品体验。收集的数据包括：

• 扩展激活和使用事件
• 所选模型信息
• 处理的文件数量和提示长度
• LLM 响应时间
• 错误事件

遥测数据中绝不会包含源代码、文件内容或个人信息。

我们使用 @vscode/extension-telemetry 模块来收集这些数据。数据将发送到 Azure Application Insights，仅用于改进 Swark 的功能和用户体验。

您可以通过在 VS Code 设置中将 "telemetry.telemetryLevel": "off" 设置为关闭来禁用遥测数据收集。

许可证

Swark 根据 GNU Affero 通用公共许可证 v3.0 进行许可。

Swark 快速上手指南

Swark 是一款免费的 VS Code 开源扩展，能够利用大语言模型（LLM）自动从代码生成架构流程图。它直接集成 GitHub Copilot，无需额外配置 API Key，支持所有编程语言。

环境准备

在开始使用前，请确保满足以下条件：

1. 编辑器：已安装 Visual Studio Code。
2. 核心依赖：必须安装 GitHub Copilot 扩展。
   • Swark 通过 VS Code 的 Language Model API 调用 Copilot，因此需要登录 GitHub 账号并激活 Copilot 服务（目前 Copilot 提供免费层级）。
   • 安装地址：Visual Studio Marketplace - GitHub Copilot
3. 可选依赖（推荐）：为了在 VS Code 内直接预览生成的图表，建议安装 Markdown Preview Mermaid Support 扩展。
   • 若不安装此扩展，生成的文件可通过链接在 Mermaid Live Editor 网页版中查看。
   • 安装地址：Visual Studio Marketplace - Markdown Preview Mermaid Support

安装步骤

通过 VS Code 扩展市场直接安装：

1. 打开 VS Code，点击左侧活动栏的 扩展 (Extensions) 图标（或按下 Ctrl+Shift+X / Cmd+Shift+X）。
2. 在搜索框中输入 Swark。
3. 找到由 swark 发布的扩展，点击 安装 (Install) 按钮。
4. 或者，直接访问 Swark 扩展页面 点击安装。

基本使用

安装完成后，只需几步即可生成架构图：

1. 打开项目：在 VS Code 中打开包含源代码的文件夹。
2. 启动命令：
   • 打开命令面板：按下 Ctrl+Shift+P (Windows/Linux) 或 Cmd+Shift+P (Mac)。
   • 输入并选择：Swark: Create Architecture Diagram。
   • 快捷键方式：直接使用默认快捷键 Ctrl+Shift+R (Windows/Linux) 或 Cmd+Shift+R (Mac)。
3. 选择范围：在弹出的文件选择器中，确认或选择要分析的代码文件夹。
4. 查看结果：
   • 等待几秒钟，VS Code 将自动打开一个新标签页，显示生成的 Mermaid 架构流程图。
   • 如果安装了 Mermaid 预览扩展，你将直接看到渲染后的图形；否则将看到 Mermaid 代码及查看链接。

输出说明： 生成的文件会自动保存在工作区根目录下的 swark-output 文件夹中，包含：

• <日期>__<时间>__diagram.md：包含架构图代码的文件。
• <日期>__<时间>__log.md：包含运行日志、配置及所用文件列表，便于调试。

隐私提示：您的源代码仅通过官方渠道发送给 GitHub Copilot 进行处理，Swark 不会将代码发送至其他任何第三方 API 或服务提供商。