wsl-docs

使用 Agentic AI 完善开源仓库的端到端指南

发布日期：2026-02-20来源：https://towardsdatascience.com/an-end-to-end-guide-to-beautifying-your-open-source-repo-with-agentic-ai/22分钟阅读

摘要

1) 一句话总结

Open Source Advisor (OSA) 是一款基于大语言模型（LLM）多智能体系统的开源 Python 工具，旨在通过自动生成 README、代码文档和 CI/CD 配置，端到端地提升开源（尤其是科研）代码仓库的质量与可复现性。

2) 核心要点

  • 多平台与多模型支持：支持 GitHub 和 GitLab 平台，兼容 OpenAI、OpenRouter、本地模型（如 Ollama）以及自托管 LLM。
  • 灵活的运行方式：提供命令行界面（CLI）、Docker 本地部署以及 Web GUI 三种交互方式。
  • 四种工作模式：包含基础模式（预设改进）、自动模式（默认，由 LLM 分析并提供建议）、高级模式（全手动控制）以及实验性的对话模式（自然语言指令）。
  • 智能 README 生成：可根据代码逻辑、目录结构和提供的论文链接，自动生成“标准版”或“科研文章版” README 文件。
  • 上下文感知文档生成：利用 TreeSitter 解析代码依赖，分阶段生成函数、类和模块的 Docstring，并自动配置 MkDocs 和 GitHub Pages 进行文档部署。
  • 自动化 CI/CD 与目录重组：自动生成工作流脚本（支持 Black、PEP8、自动化测试等），并将测试和示例文件标准化移动至 tests 和 examples 文件夹。
  • 非侵入式交付：所有建议和修改最终会打包生成一个 Pull Request (PR)，由用户审查后合并，不会直接覆盖原有代码。
  • 量化成效：在 GAN-MFS 仓库的案例中，OSA 通过添加许可证和 CI/CD 脚本，将该仓库的 Scorecard 安全评分从 2.2/10 提升至 3.7/10。

3) 风险与不足

  • 语言限制：目前 OSA 主要针对 Python 仓库设计，对其他编程语言的支持仍处于未来计划阶段。
  • 功能处于实验阶段：允许用户通过自然语言指定改进的“对话模式”目前仍是实验性功能，正在开发中。
  • 缺乏最佳实践对比基准：目前尚未集成 RAG 系统，无法将目标仓库与开源最佳实践参考示例进行自动对比（已列入未来计划）。
  • 安全评分提升有限：在实际案例中，尽管工具补充了基础设施，但受限于科研小工具本身的低安全要求性质，仓库的最终 Scorecard 绝对评分（3.7/10）依然偏低。

正文

大家好！我是 Nikolay Nikitin 博士，ITMO 大学人工智能研究所的研究负责人，也是一名开源爱好者。我经常看到许多同事无法抽出时间和精力为他们的研究论文创建开源仓库，也难以确保这些仓库具备应有的质量。在本文中，我将探讨如何使用我们团队开发的 AI 工具 OSA（Open Source Advisor）来解决这个问题，帮助你的代码仓库变得更加完善。

如果你正在维护或参与开源项目，这篇文章将为你节省大量时间和精力：你将了解到 OSA 如何通过自动添加规范的 README、生成文档、设置 CI/CD 脚本，甚至总结项目的主要优缺点，来自动提升你的代码仓库质量。

市面上有许多不同的文档改进工具，但它们通常只关注仓库文档的某个单一组件。例如，Readme-AI 工具可以生成 README 文件，但它不考虑额外的上下文（这对于科研论文仓库来说非常重要）。另一个工具 RepoAgent 可以为仓库代码生成完整的文档，但无法生成 README 或 CI/CD 脚本。相比之下，OSA 从整体上审视代码仓库，旨在使其更易于理解且随时可运行。

该工具最初是为我们的科研同事（包括生物学家和化学家）设计的，他们通常缺乏软件工程和现代开发实践的经验。我们的主要目标是帮助他们只需点击几下，就能让代码仓库更具可读性和可复现性。当然，OSA 不仅适用于科研项目，也可用于任何代码仓库。

为什么需要这个工具？

科学开源在研究成果的复用方面面临着挑战。即使代码与科学论文一起共享，它们也往往不可用或不完整。这些代码通常难以阅读，缺乏文档，有时甚至连基本的 README 都没有——开发者可能打算在最后一刻编写，但最终没有时间。库和框架通常缺乏基本的 CI/CD 设置，如代码检查工具（linters）、自动化测试和其他质量检查。因此，复现论文中描述的算法变得几乎不可能。这是一个很大的问题，因为研究人员发表研究成果的初衷就是为了与社区共享。

这个问题不仅限于科学领域。专业开发者也经常长期拖延编写 README 和文档。如果一个项目包含数十个仓库，维护和使用它们将变得非常复杂。

理想情况下，每个仓库都应该易于运行且对用户友好。但发布的开发成果往往缺乏基本要素，例如清晰的 README 文件或规范的 Docstring（文档字符串），而这些本可以通过 mkdocs 等标准工具编译成完整的文档。基于我们的经验和对问题的分析，我们提出了解决方案，并将其实现为 Open Source Advisor（OSA）工具。

什么是 OSA？

OSA 是一个开源的 Python 库，它利用大语言模型（LLM）代理来改进开源仓库，使其更易于复用。该工具是一个可以通过命令行界面（CLI）运行的包，也可以使用 Docker 在本地部署。通过为你首选的 LLM 指定 API 密钥，你可以通过控制台与该工具进行交互。你也可以通过公共的 Web GUI 体验 OSA。

OSA 是如何工作的？

OSA 是一个多智能体（Multi-agent）工具，能够以自动化的方式帮助改善科学仓库的结构和可用性。它通过处理生成文档（README 文件、代码 Docstring）、创建必要文件（许可证和依赖要求）以及提出实用的仓库改进建议等任务，解决研究项目中的常见问题。用户只需提供仓库链接，就可以选择接收一个包含所有推荐更改的自动生成的 Pull Request (PR)，或者在应用更改之前在本地审查这些建议。

OSA 可以通过两种方式使用：克隆仓库并通过命令行界面（CLI）运行，或者通过 Web 界面运行。它提供三种工作模式：基础模式（basic）、自动模式（automatic）和高级模式（advanced），用户可以在运行时根据不同需求进行选择：

  • 基础模式：OSA 在无需额外输入的情况下应用一小部分标准改进：生成报告、README、社区文档和 About 部分，并在缺少时添加“tests”和“examples”等常见文件夹。
  • 高级模式：赋予用户对每个步骤的完全手动控制权。
  • 自动模式：OSA 使用 LLM 分析仓库结构和现有的 README，然后提出一系列改进建议供用户批准或拒绝。
  • 对话模式（实验性）：目前正在积极开发中，允许用户通过 CLI 使用自由形式的自然语言指定所需的改进。OSA 会解析此请求并应用相应的更改。

OSA 的另一个核心优势是其对语言模型的灵活性。它支持 OpenRouter 和 OpenAI 等流行提供商，以及 Ollama 等本地模型和通过 FastAPI 运行的自托管 LLM。

OSA 还支持多个仓库平台，包括 GitHub 和 GitLab（包括 GitLab.com 和自托管实例）。它可以调整 CI/CD 配置文件，设置文档部署工作流，并正确配置社区文档的路径。

OSA 采用了一个实验性的多智能体系统（MAS），该系统是其自动和对话模式的基础。该系统将仓库改进任务分解为一系列推理和执行阶段，每个阶段由专门的代理处理。代理之间通过共享状态进行通信，并通过有向状态图进行协调，从而实现条件转换和迭代工作流。

核心功能

1. README 生成

OSA 包含一个 README 生成工具，可自动创建两种格式的清晰实用的 README 文件：标准 README 和文章风格的 README。工具会自行决定使用哪种格式（例如，如果用户通过 CLI 提供了科学论文的路径或 URL，OSA 会切换到文章格式）。首先，它会扫描仓库以找到最重要的文件，重点关注核心逻辑和项目描述，并考虑文件夹结构和任何现有的 README。

  • 标准 README：OSA 分析关键项目文件、仓库结构、元数据以及现有 README 的主要部分。然后，它生成一个“核心功能”部分作为文档的基础。基于这些信息，OSA 编写清晰的项目概述，并在有示例脚本或演示文件时添加“快速入门”部分，帮助用户快速了解如何使用该项目。
  • 文章模式：工具会创建相关科学论文的摘要，并从主要代码文件中提取相关信息。这些内容被组合成解释项目目标的“概述”、描述主要组件及其协同工作方式的“内容”部分，以及解释实现方法如何融入研究的“算法”部分。这种方法在保持文档科学准确性的同时，使其更易于阅读和理解。

2. 文档生成

文档生成工具为函数、方法、类和代码模块生成简洁且具有上下文感知能力的文档。生成过程如下：

  1. 引用解析：首先，由 TreeSitter 驱动的解析器获取导入的模块，并为每个特定的源代码文件解析其路径，形成一个导入映射（Import map）。这有助于理清项目中不同部分之间的互连，并区分内部别名。解析器还会保留处理文件、出现的类和独立函数列表等一般信息。
  2. 初始 Docstring 生成：为缺乏文档的函数、方法和类生成初始 Docstring。此时的上下文主要是方法的源代码，重点是形成功能的一般描述。提示词包含参数和装饰器信息，并附带调用的外部方法的源代码以提供额外上下文。类的 Docstring 会在其所有方法的 Docstring 生成完毕后才生成。
  3. 生成项目主旨：使用上一阶段得出的组件描述来生成项目的“核心思想”。
  4. 更新 Docstring：在获取项目主旨后，开始第二阶段的 Docstring 生成。此时的重点是为模型提供初始生成的 Docstring 和项目主旨，以详细说明“为什么”项目中需要这个组件。扩展的项目叙述可能会促使模型纠正原始 Docstring 中的某些观点。
  5. 生成层级模块描述：从底层到顶层生成层级模块描述。
  6. 自动化文档推送与流式传输：使用 Mkdocs 和 GitHub Pages。这是 Docstring 管道的最后阶段，涉及对项目模块和子模块的递归遍历。模型以 Markdown 格式返回摘要，以确保与 mkdocs 文档生成管道无缝集成。

3. CI/CD 与结构组织

OSA 提供跨不同仓库托管平台的自动化 CI/CD 设置。它生成可配置的工作流，使运行测试、检查代码质量和部署项目变得更加容易。该工具支持 Black（代码格式化）、unit_test（运行测试）、PEP8 和 autopep8（样式检查）、fix_pep8（自动样式修复）、pypi_publish（发布包）等常见实用程序。

用户可以使用选项自定义生成的工作流，例如 --use-poetry 启用 Poetry 进行依赖管理，--branches 定义触发工作流的分支，以及通过 --codecov-token 和 --include-codecov 设置代码覆盖率。

为了确保测试的可靠性，OSA 还会重组仓库结构。它识别测试和示例文件，并将它们移动到标准化的 tests 和 examples 目录中，使 CI 工作流无需额外配置即可一致地运行测试。

OSA 还使用 MkDocs 自动化文档部署。对于 GitHub 仓库，它在 .github/workflows 目录中生成 YAML 工作流；对于 GitLab，它创建或更新 .gitlab-ci.yml 文件以包含构建和部署作业。当更改合并到主分支时，文档将自动发布。

如何使用 OSA

要开始使用 OSA，请选择一个代码不完整或文档不足的草稿仓库。你可以选择包含相关的科学论文或描述该仓库中实现的库/算法的其他文档（论文作为单独的文件上传，用于生成 README）。你还可以指定 LLM 提供商（例如 OpenAI）和模型名称（例如 GPT-4o）。

OSA 会生成改进仓库的建议，包括：

  • 基于代码分析生成的 README 文件。
  • 为当前缺失文档的类和方法生成的 Docstring，以便使用 MkDocs 自动生成文档。
  • 基本的 CI/CD 脚本，包括 linters 和自动化测试。
  • 包含改进仓库的可操作建议的报告。
  • 贡献指南和文件（行为准则、Pull Request 和 Issue 模板等）。

在设置好环境后，你需要选择一个 LLM 提供商。接下来，添加 GIT_TOKEN 和 OPENAI_API_KEY 作为环境变量（或存储在 .env 文件中）。最后，你可以直接从命令行启动 OSA。基本启动命令包括仓库地址和可选参数（如操作模式、API 端点和模型名称）。

OSA 支持三种操作模式：

  • auto（默认）：分析仓库并使用专门的 LLM 代理创建定制的改进计划。
  • basic：应用一组预定义的改进。
  • advanced：允许在执行前手动选择和配置操作。

启动后，OSA 会对仓库进行初步分析并显示关键信息。然后提示用户接受建议的计划、取消操作或进入交互式编辑模式。在交互模式下，可以修改计划（开启/关闭操作、调整参数）。系统会引导用户了解每个操作的描述、可能的值和当前设置，直到用户确认最终计划。

当 OSA 完成工作后，它会在仓库中创建一个 Pull Request (PR)。PR 包含所有提议的更改。用户可以轻松审查 PR，在需要时进行更改，并将其合并到项目的主分支中。

案例分析：GAN-MFS 仓库 GAN-MFS 是一个提供 Wasserstein GAN 带有梯度惩罚 (WGAN-GP) 的 PyTorch 实现的仓库。OSA 为该仓库做出了多项贡献：

  • 根据论文内容生成了 README 文件。
  • 在 PR 中添加了 License 文件以及一些基本的 CI/CD 脚本。
  • 为所有缺失文档的类和方法添加了 Docstring，并生成了结构化的基于 Web 的文档站点。
  • 生成了包含仓库关键组件审计的报告，并提供了针对性的改进建议。

最终，OSA 机器人创建了仓库的分支并打开了一个包含所有提议更改的 PR。开发者只需审查建议并调整不正确的地方。这比从头开始编写 README 要容易得多。

为了评估仓库质量的整体提升，我们使用了 Scorecard 工具从安全角度检查仓库。原始仓库的综合评分为 2.2/10。经过 OSA 处理后，由于添加了许可证和 CI/CD 脚本，评分提升至 3.7/10。虽然这个分数看起来仍然很低，但该仓库只是一个基于科学文章生成合成数据的小工具，其安全要求本身就较低。

OSA 的未来计划

我们计划将 RAG 系统集成到 OSA 中，基于开源开发的最佳实践，将目标仓库与参考示例进行比较，以识别缺失的组件。例如，如果仓库已经有一个高质量的 README，它就不会被重新生成。最初，我们将 OSA 用于 Python 仓库，但我们计划在未来支持其他编程语言。

如果你有一个需要改进的开源仓库，不妨试试 OSA！我们也欢迎你通过 Issues 和 PR 留下关于新功能的想法。

如果你希望在你的工作中使用 OSA，可以引用为： Nikitin N. et al. An LLM-Powered Tool for Enhancing Scientific Open-Source Repositories // Championing Open-source DEvelopment in ML Workshop@ ICML25.

关联主题

关系图谱

反向链接