# aliyun_1M_summarize_code

**Repository Path**: chdwjzd/aliyun_1-m_summarize_code

## Basic Information

- **Project Name**: aliyun_1M_summarize_code
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-01-31
- **Last Updated**: 2025-02-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 项目简介

## 项目名称

`summarize_code`

## 项目描述

`summarize_code` 是一个用于自动化生成项目 README 的工具。它通过读取指定目录下的代码文件，利用通义千问 API 对代码进行分析，并生成包含项目功能、作用、使用方法、构建流程、项目架构等内容的 README 文档。此外，它还支持根据 `.gitignore` 文件过滤不需要处理的文件。

## 主要功能

1. **代码文件收集**：遍历指定目录，收集所有符合条件的代码文件。
2. **代码文件解析**：读取文件内容，并根据 `.gitignore` 文件过滤不需要处理的文件。
3. **代码片段拆分**：对于超过一定长度的文件，将其拆分成多个较小的片段，以便于通义千问 API 处理。
4. **通义千问 API 调用**：将代码片段发送给通义千问 API，获取关于项目功能、作用、使用方法、构建流程、项目架构等方面的分析结果。
5. **生成 README**：根据通义千问 API 的分析结果，生成包含上述信息的 README 文档。

## 如何使用

### 安装依赖

确保你已经安装了 Python 3.x，并且可以通过以下命令安装项目所需的依赖：

```bash
pip install -r requirements.txt
```

### 运行脚本

运行 `summarize_code.py` 脚本，指定目标代码目录，并选择是否生成 README 模式：

```bash
python summarize_code.py <目标代码目录> [-R]
```

- `<目标代码目录>`：指定要分析的代码目录。
- `-R`：可选参数，表示生成项目 README 风格的总结，而不是完整的概述。

### 示例

```bash
python summarize_code.py /path/to/your/code -R
```

## 构建方法

### 项目结构

```bash
/home/feiji/openai_api/
├── summarize_code.py          # 主程序，负责收集代码文件、调用通义千问 API 并生成 README
├── test.py                    # 测试脚本，用于测试通义千问 API 的调用
├── requirements.txt           # 项目依赖项
└── .vscode/settings.json      # VSCode 配置文件
```

### 环境依赖

- Python 3.x
- `dashscope`
- `pathspec`

## 作者与贡献者

- **作者**：Feiji
- **贡献者**：欢迎贡献！

## 版本说明

- **v1.0.0**：初始版本，支持基本功能。
- **v1.1.0**：增加 README 模式支持。

## 项目综合分析

### 整体项目的作用

该项目的主要目的是通过调用通义千问 API（OpenAI 兼容模式）对指定目录下的代码文件进行综合分析，并生成详细的项目总结。具体来说，它会：

1. **收集代码文件**：遍历指定目录，收集所有符合条件的代码文件（支持多种常见编程语言的文件类型）。
2. **处理大文件**：如果单个文件的内容超过预设的 Token 限制（默认 800,000），则将其行级拆分为多个子段。
3. **调用 API**：将收集到的代码文件内容发送给通义千问 API，请求对代码进行分析。
4. **生成总结**：根据 API 返回的结果，生成项目的阶段性总结和最终全局总结，并保存为 JSON 和 Markdown 格式。

### 功能

1. **代码文件收集**：通过 `collect_code_files` 函数，遍历指定目录，收集所有符合条件的代码文件，并跳过被 `.gitignore` 排除的文件。
2. **文件内容读取**：通过 `read_file_content` 函数读取文件内容，并处理编码不兼容的情况。
3. **Token 估算**：通过 `approximate_token_count` 函数估算文件内容所需的 Token 数量。
4. **文件拆分**：如果文件内容超过 Token 限制，则通过 `split_large_file_text` 函数将其行级拆分为多个子段。
5. **API 调用**：通过 `call_qwen_api` 函数调用通义千问 API，发送请求并接收响应。
6. **响应处理**：通过 `extract_content_from_response` 函数从 API 响应中提取有用的信息。
7. **请求脚本生成**：通过 `generate_request_py` 函数生成 Python 脚本，用于手动调用 API。
8. **结果保存**：通过 `save_result` 函数将分析结果保存为 JSON 和 Markdown 格式。

### 使用环境准备

在开始使用本项目之前，请确保您的环境满足以下要求：

1. **Python 环境**：请安装 Python 3.8 或更高版本。您可以从 [Python 官方网站](https://www.python.org/) 下载并安装适合您操作系统的版本。
2. **依赖库安装**：请使用以下命令安装项目所需的 Python 库：

```bash
pip install -r requirements.txt
```

这将安装以下库：

- `dashscope`：用于与通义千问 API 进行交互。
- `pathspec`：用于解析 `.gitignore` 文件，忽略不需要处理的文件。

### 通义千问 API 准备教程

要使用通义千问 API，请按照以下步骤进行配置：

1. **注册阿里云账号**：前往 [阿里云官网](https://www.aliyun.com/) 注册并登录您的阿里云账号。
2. **开通通义千问服务**：具体步骤可参考 [官方文档](https://bailian.console.aliyun.com/?spm=5176.28326591.0.0.77f655e3SkcQxX&accounttraceid=31c38fd8f7684444ba4f5a8010605371ftjy#/model-market/detail/qwen2.5-14b-instruct-1m)。
3. **创建 API Key**：在 DashScope 服务的 API Key 管理页面，创建一个新的 API Key。创建后，请妥善保存您的 API Key。详细步骤请参考 [官方指南](https://bailian.console.aliyun.com/?apiKey=1)。
4. **设置环境变量**：将获取的 API Key 设置为环境变量 `DASHSCOPE_API_KEY`。您可以在命令行中使用以下命令设置：

```bash
export DASHSCOPE_API_KEY=your_api_key_here
```

请将 `your_api_key_here` 替换为您实际的 API Key。

### 使用的模型简介

本项目使用了通义千问的 `qwen2.5-14b-instruct-1m` 模型。该模型是阿里云自主研发的大型语言模型，支持处理长达 100 万 Token 的上下文长度，适用于长文本的理解和分析任务。更多关于该模型的信息，请参考 [官方介绍](https://bailian.console.aliyun.com/?spm=5176.28326591.0.0.77f655e3SkcQxX&accounttraceid=31c38fd8f7684444ba4f5a8010605371ftjy#/model-market/detail/qwen2.5-14b-instruct-1m)。

### 架构（模块划分）

1. **基础工具函数**

   - `load_gitignore_patterns`：加载并解析 `.gitignore` 文件。
   - `is_code_file`：判断文件是否为代码文件。
   - `collect_code_files`：收集符合条件的代码文件。
   - `read_file_content`：读取文件内容。
   - `approximate_token_count`：估算文件内容所需的 Token 数量。
   - `split_large_file_text`：将大文件拆分为多个子段。
   - `get_last_two_levels`：获取路径的倒数两级目录名称。
2. **请求与响应处理**

   - `call_qwen_api`：调用通义千问 API。
   - `extract_content_from_response`：从 API 响应中提取有用的信息。
3. **生成请求脚本**

   - `generate_request_py`：生成 Python 脚本，用于手动调用 API。
4. **核心逻辑**

   - `main`：主函数，负责整个流程的控制，包括参数解析、文件收集、文件拆分、API 调用、结果保存等。
5. **保存结果**

   - `save_result`：将分析结果保存为 JSON 和 Markdown 格式。

### 进程/线程关系

该项目主要是一个单线程的命令行工具，没有显式的多线程或多进程设计。所有的操作都是顺序执行的，包括文件收集、文件拆分、API 调用等。因此，进程/线程关系较为简单，无需复杂的同步机制。

### 全局变量

- `PathSpec`：用于解析 `.gitignore` 文件的库对象，如果未安装 `pathspec` 库，则设置为 `None`。
- `sys.argv`：用于解析命令行参数，指定要分析的代码目录。
- `DASHSCOPE_API_KEY`：用于访问通义千问 API 的 API 密钥，通过环境变量获取。

### 测试文件

- `/home/feiji/openai_api/test.py`：一个简单的测试文件，用于测试 API 调用是否正常工作。它创建了一个 OpenAI 客户端实例，并发送了一个简单的请求，询问“你是谁？”。

### 总结

该项目通过调用通义千问 API，实现了对指定目录下代码文件的自动化分析和总结。它不仅能够处理大文件，还能生成详细的阶段性总结和最终全局总结，非常适合用于代码审查、技术文档生成等场景。