利用 CrewAI Agents 和大型语言模型从 C# 仓库自动生成代码文档

随着项目日积月累地发展，代码库不可避免地会变得越来越庞大，模块之间的复杂性和相互依赖性也会日益增加。如果没有适当的代码文档，新开发人员的入职将会面临巨大的挑战。当领域知识只掌握在少数人手中时，情况尤其如此。代码文档常常变成事后才考虑的事情，尤其是在项目交接期间。本文将探讨如何利用 CrewAI Agents 和 大型语言模型 (LLM) 自动化生成 C# 代码文档，从而解决这一难题。

代码文档的重要性

在软件开发生命周期中，代码文档的重要性不容忽视。它不仅可以帮助新成员快速了解项目结构、功能和设计思路，降低学习成本，还可以方便团队成员之间的协作，提高开发效率。一份高质量的代码文档能够显著减少维护成本，提升软件质量，并降低项目交接的风险。然而，在实际开发过程中，代码文档往往是最容易被忽视的环节。

我亲身经历过这样一个挑战，在一个实际的项目交接过程中，由于缺乏完善的代码文档，新的开发人员很难理解代码库，也难以有效地维护它，这凸显了维护方面存在的重大风险。如何系统且高效地生成 C# 代码文档，成为了亟待解决的问题。

CrewAI 框架与自动化文档生成

受到这个案例的启发，我开始思考是否可以使用人工智能代理来自动生成代码文档。最终的方案是利用 Python、CrewAI 框架和 Azure OpenAI 作为底层 大型语言模型 (LLM) 来构建一个自动化文档生成系统。

CrewAI 框架提供了一种组织和管理 AI 代理的强大方式。通过定义不同的 Agent (例如：代码分析专家、文档编写专家)，并分配特定的任务，可以有效地将复杂的文档生成过程分解为更小的、可管理的模块。这种模块化的设计方法提高了系统的灵活性和可维护性。

系统工作流程

该系统的工作流程主要包括以下几个阶段：

连接到 Azure DevOps C# 仓库: 首先，使用个人访问令牌 (PAT) 连接到 Azure DevOps 中的 C# 仓库。这允许系统访问代码库并提取所需的信息。
代码库解析: 系统逐个文件地解析代码库，提取其结构和关系。这包括识别类、方法、属性以及它们之间的继承和调用关系。
知识图谱构建: 使用 networkx 构建一个知识图谱，将类、方法、继承和用法表示为节点，并将它们之间的关系表示为边。这个知识图谱是 大型语言模型 (LLM) 理解代码库的关键。
AI Agent 文档生成: 将构建好的知识图谱输入到 AI Agent 中，该 Agent 利用 大型语言模型 (LLM) 生成易于理解的 Markdown 格式的代码文档。大型语言模型 (LLM) 的强大自然语言生成能力保证了文档的可读性和准确性。
文档推送: 最后，使用 Azure DevOps Git REST API 将生成的 Markdown 代码文档推送回仓库。

技术实现细节

在实际实现过程中，我最初尝试使用 Azure DevOps Git Python SDK (v7.0)，但遇到了多个问题，例如缺少关键类（如 GitChange 和 GitItemChange）。这导致使用 git_client.create_push() 失败，原因是数据结构不完整。经过大量的故障排除和研究，我转向直接使用 REST API，这提供了更大的控制和灵活性，可以可靠地处理提交操作。

以下是一些关键的代码片段，展示了如何使用 REST API 将生成的代码文档推送回 Azure DevOps 仓库：

import requests
import json

def push_documentation_to_azure_devops(organization, project, repository_id, pat, commit_message, file_path, file_content):
    """
    Pushes the generated documentation to an Azure DevOps repository using the REST API.

    Args:
        organization (str): The name of the Azure DevOps organization.
        project (str): The name of the project.
        repository_id (str): The ID of the repository.
        pat (str): Personal Access Token (PAT) for authentication.
        commit_message (str): The commit message for the changes.
        file_path (str): The path to the file where the documentation will be stored.
        file_content (str): The content of the documentation file.
    """

    # Construct the API endpoint URL
    url = f"https://dev.azure.com/{organization}/{project}/_apis/git/repositories/{repository_id}/pushes?api-version=7.1"

    # Set the headers for authentication and content type
    headers = {
        "Authorization": f"Basic {(':{}'.encode('utf-8').format(pat)).decode('utf-8')}",
        "Content-Type": "application/json"
    }

    # Construct the request payload
    payload = {
        "refUpdates": [
            {
                "name": "refs/heads/main", # You might need to change this to your main branch
                "oldObjectId": "0000000000000000000000000000000000000000"  # Represents a new branch or empty repository
            }
        ],
        "commits": [
            {
                "comment": commit_message,
                "changes": [
                    {
                        "changeType": "add",
                        "item": {
                            "path": file_path
                        },
                        "newContent": {
                            "content": file_content,
                            "contentType": "rawtext"
                        }
                    }
                ]
            }
        ]
    }

    # Convert the payload to JSON
    json_payload = json.dumps(payload)

    # Make the API request
    response = requests.post(url, headers=headers, data=json_payload)

    # Check the response status
    if response.status_code == 201:
        print("Documentation pushed successfully!")
    else:
        print(f"Failed to push documentation. Status code: {response.status_code}, Response: {response.text}")


# Example Usage (replace with your actual values)
organization = "your_organization"
project = "your_project"
repository_id = "your_repository_id"
pat = "your_personal_access_token"
commit_message = "Add automatically generated documentation"
file_path = "/docs/api_documentation.md"
file_content = "# API Documentation (Generated by CrewAI)" # This would be replaced with your actual generated documentation

# Call the function to push the documentation
# push_documentation_to_azure_devops(organization, project, repository_id, pat, commit_message, file_path, file_content)

这段代码展示了如何使用 Python 的 requests 库向 Azure DevOps 发送 POST 请求，将新的 代码文档 添加到指定的文件路径。需要注意的是，你必须替换示例代码中的占位符，例如 organization、project、repository_id 和 pat，使用你自己的 Azure DevOps 账户信息。

知识图谱的重要性

知识图谱在代码文档自动生成过程中扮演着至关重要的角色。它不仅能够提供代码库的结构化表示，还能帮助 大型语言模型 (LLM) 理解代码元素之间的复杂关系。一个精心设计的知识图谱能够显著提高文档生成的准确性和相关性。

例如，通过在知识图谱中明确表示类之间的继承关系，大型语言模型 (LLM) 可以生成更准确的关于继承和多态性的文档。同样，通过记录方法之间的调用关系，大型语言模型 (LLM) 可以生成关于代码执行流程和依赖关系的文档。

未来展望

这仅仅是一个开始，进一步完善知识图谱对于生成更准确、更相关的文档至关重要。未来的工作重点包括：

提高图提取的准确性: 当前的图提取算法可能会遗漏一些重要的代码关系。我们需要不断改进算法，以确保能够捕获所有关键信息。这包括处理复杂的代码结构、泛型类型、以及动态语言特性。
改进文档结构和清晰度: 生成的代码文档的结构和清晰度仍然有提升空间。我们需要探索不同的文档模板和组织方式，以提高文档的可读性和易用性。例如，可以根据不同的代码元素（如类、方法、属性）生成不同的文档章节，并提供清晰的目录和索引。
集成测试用例: 将测试用例集成到知识图谱中，可以帮助 大型语言模型 (LLM) 理解代码的预期行为，并生成更准确的示例代码和用例说明。
支持多种编程语言: 虽然目前的系统主要针对 C# 代码，但未来的目标是扩展其支持的编程语言范围，使其能够自动生成 Java、Python 等其他语言的代码文档。
用户反馈和持续改进: 通过收集用户反馈，我们可以不断改进文档生成系统的性能和准确性。例如，可以允许用户对生成的文档进行评分和评论，并使用这些反馈来调整 大型语言模型 (LLM) 的训练参数。
利用向量数据库存储代码语义信息: 将代码片段的语义信息嵌入到向量数据库中，可以加速检索和生成相关文档的过程。这可以通过使用 Sentence Transformers 等技术来实现。

结论

利用 CrewAI Agents 和 大型语言模型 (LLM) 自动生成 C# 代码文档是一个非常有前景的领域。通过不断改进知识图谱、优化文档结构、以及收集用户反馈，我们可以构建一个更加智能、高效、和可靠的文档生成系统。这将极大地提高软件开发效率，降低维护成本，并提升软件质量。

项目代码库已开源，欢迎贡献：https://github.com/manabendra-panda/CrewAIAgent

参考资料：Mastering AI Agents: The 10 Best Free Courses, Tutorials & Learning Tools | by Maximilian Vogel | Medium

欢迎大家提出宝贵意见和建议，共同推动该领域的发展！您的贡献将有助于提高图提取的准确性和改进文档的结构和清晰度。

利用 CrewAI Agents 和大型语言模型从 C# 仓库自动生成代码文档