摘要
1) 一句话总结
OSA（Open Source Advisor）是一个基于大语言模型多智能体系统的开源 Python 工具，能够通过自动生成 README、代码文档、CI/CD 脚本并优化目录结构，端到端地提升开源代码仓库的质量与可复现性。
2) 关键要点
- 工作流与输出：用户只需提供仓库链接，OSA 即可自动生成包含所有推荐更改（文档、脚本、结构调整等）的 Pull Request (PR) 供用户审查和合并。
- 运行模式：提供基础（Basic）、自动（Automatic）和高级（Advanced）三种核心模式，并正在开发基于自然语言的实验性多智能体对话模式。
- 模型与平台兼容性：支持 OpenAI、OpenRouter、Ollama 及自托管 LLM；兼容 GitHub 和 GitLab（含自托管实例）平台。
- README 生成：能够根据项目特征自动选择生成“标准格式”或“文章格式”（提取科研论文摘要和算法逻辑）的 README 文件。
- 上下文感知文档：利用 TreeSitter 解析代码依赖和导入映射，分阶段生成函数与类的文档字符串，并支持通过 MkDocs 和 GitHub Pages 自动部署文档网站。
- CI/CD 与目录重组：自动生成代码格式化（Black）、测试和规范检查（PEP8）的工作流脚本，并将测试和示例文件标准化归置到
tests和examples目录中。 - 实际成效：在
GAN-MFS仓库的测试案例中，OSA 自动补充了文档、许可证和 CI/CD 脚本，使该仓库的 Scorecard 安全评分从 2.2/10 提升至 3.7/10。
3) 风险与不足（基于原文明确提及）
- 语言支持受限：当前工具主要针对 Python 仓库设计，尚未支持其他编程语言。
- 缺乏基准对比机制：目前尚未集成 RAG 系统来对比开源最佳实践（例如无法自动识别并跳过已存在的高质量 README），该功能仍在计划中。
- 部分功能处于实验阶段：基于自然语言指令的多智能体对话模式目前仍是实验性功能。
正文
大家好！我是 ITMO 大学人工智能研究所的研究主管 Nikolay Nikitin 博士，也是一名开源爱好者。我经常看到许多同事没有时间和精力为他们的研究论文创建开源仓库，也无法保证这些代码库的质量。在本文中，我将探讨如何使用我们团队开发的 AI 工具 OSA（Open Source Advisor）来解决这个问题，帮助你的代码仓库脱胎换骨。
如果你正在维护或参与开源项目，这篇文章将为你节省大量时间和精力：你将了解到 OSA 如何通过添加规范的 README、生成文档、设置 CI/CD 脚本，甚至总结项目的优缺点，来自动优化你的代码仓库。
现有很多文档优化工具，但它们通常只关注代码仓库的单一组件。例如，Readme-AI 工具只生成 README 文件，但它不考虑额外的上下文（这对于科研论文仓库来说非常重要）；另一个工具 RepoAgent 会为仓库代码生成完整的文档，但不生成 README 或 CI/CD 脚本。相比之下，OSA 从整体上考量代码仓库，旨在使其更易于理解且随时可运行。
该工具最初是为我们在科研领域的同事（包括生物学家和化学家）设计的，他们通常缺乏软件工程经验和现代开发实践。我们的主要目的是帮助他们只需点击几下，就能提高仓库的可读性和可复现性。当然，OSA 适用于任何代码仓库，不仅限于科研领域。
为什么需要这个工具？
科研领域的开源项目在研究成果复用方面面临着挑战。即使代码随科研论文一起发布，也往往难以获取或不够完整。这些代码通常难以阅读，缺乏文档，有时甚至连基本的 README 都没有——开发者本打算在最后时刻编写，却没腾出时间。库和框架经常缺乏基本的 CI/CD 设置，如代码检查工具（linters）、自动化测试和其他质量检查。因此，复现论文中描述的算法变得几乎不可能。这是一个大问题，因为发表研究的初衷就是与社区分享。
这个问题不仅限于科学界。专业开发者也经常长期拖延编写 README 和文档。如果一个项目有几十个仓库，维护和使用它们将变得非常复杂。
理想情况下，每个仓库都应该易于运行且对用户友好。但发布的成果往往缺乏清晰的 README 文件或规范的文档字符串（docstrings）等基本元素，而这些本可以通过 mkdocs 等标准工具编译成完整的文档。基于我们的经验和对问题的分析，我们尝试提出解决方案，并将其实现为 Open Source Advisor (OSA) 工具。
OSA 工具是什么？
OSA 是一个开源的 Python 库，它利用大语言模型（LLM）智能体来优化开源仓库，使其更易于复用。该工具可以通过命令行界面（CLI）运行，也可以使用 Docker 进行本地部署。只需为你首选的 LLM 指定 API 密钥，即可通过控制台与工具交互。你也可以通过公共的 Web GUI 体验 OSA。
OSA 是如何工作的？
OSA 是一个多智能体工具，能够以自动化的方式帮助优化科研仓库的结构和可用性。它通过处理生成文档（README 文件、代码文档字符串）、创建必要文件（许可证和依赖清单）以及提出实用改进建议等任务，解决研究项目中的常见问题。用户只需提供仓库链接，即可接收包含所有推荐更改的自动生成的 Pull Request (PR)，或者在应用更改前在本地审查这些建议。
OSA 有两种使用方式：克隆仓库并通过命令行界面（CLI）运行，或通过 Web 界面使用。它提供三种工作模式，可在运行时根据不同需求进行选择：
- 基础模式 (Basic)：应用少量标准改进，无需额外输入。它会生成报告、README、社区文档和 About 部分，并在缺失时添加“tests”和“examples”等常见文件夹。
- 自动模式 (Automatic)：使用 LLM 分析仓库结构和现有的 README，然后提出改进列表供用户批准或拒绝。
- 高级模式 (Advanced)：让用户对每个步骤拥有完全的手动控制权。
此外，目前还在积极开发一种实验性的多智能体对话模式，允许用户通过 CLI 使用自由形式的自然语言指定所需的改进。OSA 会解析此请求并应用相应的更改。
OSA 的另一个核心优势是其对语言模型的灵活性。它支持 OpenRouter 和 OpenAI 等流行提供商，以及 Ollama 等本地模型和通过 FastAPI 运行的自托管 LLM。
OSA 还支持多个代码托管平台，包括 GitHub 和 GitLab（包括 GitLab.com 和自托管实例）。它可以调整 CI/CD 配置文件，设置文档部署工作流，并正确配置社区文档的路径。
OSA 采用实验性的多智能体系统 (MAS) 作为其自动和对话模式的基础。该系统将仓库优化分解为一系列推理和执行阶段，每个阶段由专门的智能体处理。智能体通过共享状态进行通信，并通过有向状态图进行协调，从而实现条件转换和迭代工作流。
README 生成
OSA 包含一个 README 生成工具，可自动创建两种格式的清晰实用文档：标准 README 和文章风格 README。工具会自动决定使用哪种格式（例如，如果用户通过 CLI 提供科研论文的路径或 URL，OSA 会切换到文章格式）。它首先扫描仓库以寻找最重要的文件，重点关注核心逻辑和项目描述，并考虑文件夹结构和现有的 README。
- 标准 README：OSA 分析关键项目文件、仓库结构、元数据以及现有 README 的主要部分。然后生成“核心功能”部分作为文档其余部分的基础。基于这些信息，OSA 编写清晰的项目概述，并在有示例脚本或演示文件时添加“快速开始”部分，帮助用户快速了解如何使用该项目。
- 文章模式：工具会生成相关科研论文的摘要，并从主要代码文件中提取相关信息。这些内容被组合成解释项目目标的“概述”、描述主要组件及其协同工作方式的“内容”部分，以及解释实现方法如何融入研究的“算法”部分。这种方法保持了文档的科学准确性，同时使其更易于阅读和理解。
文档生成
文档生成工具为函数、方法、类和代码模块生成简洁且具有上下文意识的文档。生成过程如下：
- 引用解析：首先，基于 TreeSitter 的解析器获取导入的模块，并为每个特定的源代码文件解析路径，形成导入映射。这使得理清项目各部分之间的互连并区分内部别名变得相对容易。解析器还会保存处理文件、出现的类和独立函数列表等一般信息。
- 初始文档字符串生成：为缺乏文档的函数、方法和类生成初始文档字符串。此阶段主要描述该方法“做什么”，上下文主要是方法的源代码。类的文档字符串会在其所有缺乏文档的方法生成完毕后才生成。
- 生成项目“核心思想”：使用上一阶段得出的组件描述来生成项目的核心理念。
- 使用“核心思想”更新文档字符串：结合所有类和函数的文档字符串、它们在导入映射中的重要性得分以及在项目层级中的位置，模型会以 Markdown 格式返回项目组件的摘要。获取核心思想后，开始第二阶段的文档字符串生成，重点是阐述“为什么”项目需要这个组件，并可能根据扩展的项目叙述修正初始文档。
- 层级模块描述生成：自下而上生成模块描述。
- 使用 MkDocs 和 GitHub Pages 自动推送和流式传输文档：递归遍历项目的模块和子模块，基于源代码路径的层级结构生成摘要，并以 Markdown 格式返回，以确保与 MkDocs 文档生成流水线无缝集成。
CI/CD 与结构组织
OSA 提供跨平台的自动化 CI/CD 设置。它生成可配置的工作流，简化测试、代码质量检查和部署。该工具支持常见的实用程序，如 Black（代码格式化）、unit_test（运行测试）、PEP8 和 autopep8（样式检查）、fix_pep8（自动样式修复）、pypi_publish（发布包）等。根据平台的不同，这些工作流会被放置在适当的位置（例如 GitHub 的 .github/workflows/ 或 GitLab 的 .gitlab-ci.yml）。
用户可以使用选项自定义生成的工作流，例如使用 --use-poetry 启用 Poetry 进行依赖管理，使用 --branches 定义触发工作流的分支，以及通过 --codecov-token 和 --include-codecov 设置代码覆盖率。
为了确保测试可靠，OSA 还会重组仓库结构。它识别测试和示例文件，并将它们移动到标准化的 tests 和 examples 目录中，使 CI 工作流无需额外配置即可一致地运行测试。
OSA 还使用 MkDocs 自动化文档部署。对于 GitHub 仓库，它在 .github/workflows 目录中生成 YAML 工作流；对于 GitLab，OSA 创建或更新 .gitlab-ci.yml 文件，包含使用 Docker 镜像、脚本和工件保留规则的构建和部署作业。当更改合并到主分支时，文档将自动发布。
如何使用 OSA
要开始使用 OSA，请选择一个代码不完整或文档不足的草稿仓库。你可以选择性地附上相关的科研论文或其他描述该库或算法的文档（作为单独文件上传，用于生成 README）。你还可以指定 LLM 提供商（如 OpenAI）和模型名称（如 GPT-4o）。
OSA 会生成以下改进建议：
- 基于代码分析生成的 README 文件（使用标准模板和示例）。
- 为当前缺失文档的类和方法生成文档字符串，以便使用 MkDocs 自动生成文档。
- 基本的 CI/CD 脚本，包括代码检查工具和自动化测试。
- 包含可操作建议的仓库改进报告。
- 贡献指南和文件（行为准则、Pull Request 和 Issue 模板等）。
设置好环境后，你需要选择一个 LLM 提供商。接下来，添加 GIT_TOKEN（具有标准仓库权限的 GitHub 令牌）和 OPENAI_API_KEY 作为环境变量，或者将它们存储在 .env 文件中。最后，你可以直接从命令行启动 OSA，提供仓库 URL 以及可选参数（如操作模式、API 端点和模型名称）。
启动后，OSA 会执行初步分析并显示关键信息：一般项目详细信息、当前环境配置以及包含计划和非活动操作的表格。然后，系统会提示用户接受建议的计划、取消操作或进入交互式编辑模式。
在交互模式下，可以修改计划：开启或关闭操作、调整参数，并配置其他选项。系统会引导用户了解每个操作的描述、可能的值和当前设置，直到用户确认最终计划。这种基于 CLI 的工作流确保了灵活性，既适合快速的初步评估，也适合详细的项目微调。
当 OSA 完成工作后，它会在仓库中创建一个 Pull Request (PR)。PR 包含所有提议的更改，如 README、文档字符串、文档页面、CI/CD 脚本、贡献指南、报告等。用户可以轻松审查 PR，在需要时进行修改，并将其合并到项目的主分支中。
应用案例：
以 GAN-MFS（一个提供 WGAN-GP 的 PyTorch 实现的仓库）为例。OSA 为该仓库做出了多项贡献：
- 生成了基于论文内容的 README 文件。
- 添加了许可证文件和基础的 CI/CD 脚本。
- 为所有缺失文档的类和方法添加了文档字符串，并生成了结构化的 Web 文档站点。
- 生成了包含仓库关键组件审计和针对性建议的报告。
OSA 机器人创建了仓库的分支并提交了包含所有更改的 PR。开发者只需审查建议并调整不正确的地方即可，这比从头编写 README 要容易得多。
为了评估仓库质量的整体提升，我们使用了 Scorecard 工具（从安全角度评估仓库）。原始仓库的综合得分为 2.2/10。经过 OSA 处理后，由于添加了许可证和 CI/CD 脚本，得分升至 3.7/10。对于一个基于科学文章生成合成数据的小型工具来说，其安全要求相对较低，这个提升已经非常可观。
OSA 的下一步计划
我们计划将 RAG 系统集成到 OSA 中，基于开源开发的最佳实践，将目标仓库与参考示例进行对比，以识别缺失的组件。例如，如果仓库已经有一个高质量的 README，它就不会被重新生成。最初，我们将 OSA 用于 Python 仓库，但我们计划在未来支持更多编程语言。
如果你有一个需要改进的开源仓库，不妨试试 OSA！如果你在工作中使用 OSA，可以通过以下方式引用： Nikitin N. et al. An LLM-Powered Tool for Enhancing Scientific Open-Source Repositories // Championing Open-source DEvelopment in ML Workshop@ ICML25.