# random_download_from_github

**Repository Path**: zxstty/random_download_from_github

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-20
- **Last Updated**: 2025-11-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GitHub文档检索与下载工具使用文档
## 一、Python环境搭建（Windows/macOS/Linux通用）

### 1. 安装Python（3.10+ 推荐）
#### 步骤1：下载Python安装包
- 官网下载地址：https://www.python.org/downloads/
- 选择 **Python 3.10.x 或更高版本**（推荐3.11，兼容性更好）
- 注意事项：
  - Windows：安装时勾选「Add Python to PATH」（自动添加环境变量）
  - macOS/Linux：默认已安装Python3，可通过 `python3 --version` 检查版本，低于3.10则需升级

#### 步骤2：验证Python安装
打开终端/命令提示符，输入以下命令，显示版本号则安装成功：
```bash
# Windows
python --version

# macOS/Linux
python3 --version
```
示例输出：`Python 3.11.6`（版本号≥3.10即可）

### 2. 配置虚拟环境（可选但推荐）
虚拟环境可避免依赖冲突，建议创建独立环境运行脚本：
```bash
# 1. 创建虚拟环境（名称可自定义，如 github-doc-env）
# Windows
python -m venv github-doc-env

# macOS/Linux
python3 -m venv github-doc-env

# 2. 激活虚拟环境
# Windows（命令提示符）
github-doc-env\Scripts\activate.bat

# Windows（PowerShell）
.\github-doc-env\Scripts\Activate.ps1

# macOS/Linux
source github-doc-env/bin/activate
```
激活成功后，终端前缀会显示 `(github-doc-env)`

### 3. 安装依赖包
脚本依赖 `requests`、`openai`、`pydantic`、`toml` 等库，创建 `requirements.txt` 文件（内容如下）：
```txt
requests==2.32.2
pydantic==2.11.7
toml==0.10.2
openai==1.93.0
```

在终端执行以下命令安装依赖：
```bash
# Windows
pip install -r requirements.txt

# macOS/Linux
pip3 install -r requirements.txt
```

### 4. 安装Git（必要依赖）
脚本需要 `git clone` 仓库，需安装Git客户端：
- 下载地址：https://git-scm.com/downloads
- 安装后验证：终端输入 `git --version`，显示版本号则成功

## 二、工具概述
本工具是一款高效的GitHub文档批量检索与下载工具，支持通过**领域关键词+文档关键词**组合检索GitHub仓库，并行克隆仓库并提取目标格式文档，同时集成敏感词检测功能过滤违规文件。核心特性包括：
- 组合检索：领域与文档关键词两两组合，提升检索精准度
- 并行处理：多线程并行克隆仓库，提高下载效率
- 敏感词过滤：基于大模型的智能敏感词检测，过滤违规文件
- 灵活配置：支持命令行参数与配置文件双重配置，适配不同需求
- 自动清理：自动清理临时克隆目录，避免磁盘占用

## 三、配置文件设置
工具运行需依赖根目录下的`config.toml`配置文件，需提前创建并完善以下内容：
```toml
[llm]
api_key = "你的大模型API密钥"       # 敏感词检测所需API密钥
api_base = "你的大模型API基础URL"   # 如https://api.example.com/v1
model_name = "qwen3-max"           # 模型名称（默认已配置）
max_tokens = 256000                # 最大Token数（默认已配置）
temperature = 0.1                  # 温度参数（默认已配置）
request_timeout = 60               # 超时时间（默认已配置）

[github]
github_token = "你的GitHub令牌（可选）"  # 无令牌则匿名访问，可能受限

[doc_keywords_and_domains]
doc_keywords = ["文档", "教程", "手册", "指南", "笔记", "资料", "报告", "论文"]  # 可扩展
domain_keywords = ["计算机", "人工智能", "数学", "金融", "医学", "教育", "法律"]  # 可扩展

[extensions]
extensions = ["pdf", "docx", "doc", "pptx", "ppt", "xlsx", "xls", "md", "txt"]  # 支持的文档格式
```

#### 配置说明：
- `llm`部分：敏感词检测依赖大模型API，需填写有效密钥和API地址（支持通义千问、GPT等兼容OpenAI API的模型）
- `github`部分：GitHub令牌可选，匿名访问时API调用频率受限，建议创建[GitHub Personal Access Token](https://github.com/settings/tokens)（无需特殊权限）
- `doc_keywords_and_domains`部分：可根据需求扩展文档关键词和领域关键词，扩大检索范围
- `extensions`部分：默认支持常见文档格式，可通过配置或命令行参数扩展

## 四、快速开始
### 1. 基础使用（默认配置）
直接运行工具，使用默认参数下载50个文档到`./github_docs`目录：
```bash
# Windows
python github_doc_downloader.py

# macOS/Linux
python3 github_doc_downloader.py
```

### 2. 自定义参数示例
```bash
# 下载100个文档，保存到./my_docs目录，使用5个并行线程
# Windows
python github_doc_downloader.py --total-docs 100 --output ./my_docs --threads 5

# macOS/Linux
python3 github_doc_downloader.py --total-docs 100 --output ./my_docs --threads 5

# 增加额外支持的文件格式（zip、csv），抽取5个领域关键词
# Windows
python github_doc_downloader.py --extended-file-extensions zip csv --domains-sample 5

# macOS/Linux
python3 github_doc_downloader.py --extended-file-extensions zip csv --domains-sample 5

# 自定义临时克隆目录，限制最大处理200个仓库
# Windows
python github_doc_downloader.py --temp-clone-dir ./temp_clone --max-repos 200

# macOS/Linux
python3 github_doc_downloader.py --temp-clone-dir ./temp_clone --max-repos 200
```

## 五、命令行参数详解
| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `--total-docs` | int | 50 | 需要获取的总文档数量（必须为正整数） |
| `--output` | str | ./github_docs | 文档保存目录（不存在会自动创建） |
| `--temp-clone-dir` | str | ./temp_github_clone | 仓库克隆临时目录（任务完成后自动清理） |
| `--threads` | int | 3 | 并行克隆的线程数量（1-20之间，建议不超过10） |
| `--domains-sample` | int | 3 | 从领域关键词池随机抽取的领域数量 |
| `--doc-keyword-sample` | int | 3 | 从文档关键词池随机抽取的关键词数量 |
| `--max-repos` | int | 1000 | 最大处理的仓库数量（避免无限制处理） |
| `--extended-file-extensions` | list | [] | 额外支持的文件扩展名（如zip csv，无需加`.`） |

## 六、功能细节说明
### 1. 检索逻辑
工具会将选中的领域关键词与文档关键词两两组合（如"人工智能 教程"、"金融 报告"），通过GitHub API检索相关仓库，确保结果的精准性和多样性。

### 2. 文件筛选规则
下载的文件需满足以下条件：
- 格式在支持的扩展名列表中（默认+命令行扩展）
- 文件名包含中文且长度≥4个字符
- 排除隐藏文件（以`.`开头）
- 排除常见无用文件（README、LICENSE等开头的文件）
- 排除敏感文件（通过大模型检测政治敏感、色情、违法等内容）
- 按文件大小降序优先下载（优先获取较大文档）

### 3. 敏感词检测
- 检测失败时默认放行文件（可在`SensitiveWordDetector.is_sensitive`方法中修改为拒绝）
- 支持的敏感词类型：政治敏感、色情暴力、违法违规、歧视攻击、违反公序良俗等
- 若大模型API不可用，工具会自动降级为无敏感词过滤模式

### 4. 线程安全
- 使用线程锁保证计数变量（已下载数量、剩余数量）的线程安全
- 支持通过`stop_flag`快速终止所有线程（达到目标文档数时自动触发）

## 七、常见问题排查
### 1. 检索不到仓库
- 检查关键词配置是否过于冷门，建议扩展`doc_keywords`或`domain_keywords`
- 若无GitHub令牌，可能因API频率限制导致检索失败，建议配置令牌
- 网络问题：确保能正常访问GitHub API（可尝试更换网络或使用代理）

### 2. 克隆仓库失败
- 仓库地址无效或已被删除，工具会自动跳过并记录失败仓库
- 网络超时：可减少`--threads`数量，或检查网络连接
- 临时目录权限问题：确保当前用户有读写临时目录的权限
- Git未安装或未配置环境变量：重新安装Git并验证`git --version`可正常执行

### 3. 敏感词检测失败
- 检查大模型API密钥和API地址是否正确
- 确认模型名称是否支持（默认`qwen3-max`，需根据实际使用的模型修改）
- 超时错误：可在`config.toml`中增大`request_timeout`值
- 依赖包版本冲突：确保`openai`库版本与配置文件一致（1.93.0）

### 4. 文档数量未达目标
- 候选仓库中无足够匹配格式的文档，可扩展支持的文件格式
- 大量文件因敏感词被过滤，可查看日志中的"跳过敏感文件"记录
- 已达到最大处理仓库数，可增大`--max-repos`参数

### 5. 依赖安装失败
- 网络问题：更换pip源（如阿里云、清华源），示例：
  ```bash
  # Windows
  pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/

  # macOS/Linux
  pip3 install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/
  ```
- Python版本过低：升级到3.10+版本后重新安装

## 八、注意事项
1. 遵守GitHub使用规则，避免频繁大量调用API（配置令牌可提升频率限制）
2. 敏感词检测仅为辅助功能，需根据实际需求调整检测逻辑和放行策略
3. 并行线程数不宜过大，否则可能导致网络拥堵或被GitHub暂时限制访问
4. 工具会自动清理临时克隆目录，无需手动删除
5. 下载的文档版权归原仓库所有，仅用于合法学习和研究，请勿用于商业或违规用途
6. 确保Git已正确安装并添加到系统环境变量，否则会导致`git clone`命令执行失败

## 九、扩展与定制
### 1. 扩展关键词
修改`config.toml`中的`doc_keywords`和`domain_keywords`列表，可添加更多细分领域或文档类型（如"区块链 白皮书"、"心理学 论文"）。

### 2. 调整敏感词检测规则
修改`SensitiveWordDetector.is_sensitive`方法中的`system_prompt`，可自定义敏感词检测标准和输出格式。

### 3. 更换大模型
在`config.toml`中修改`llm.model_name`，并确保API地址（`api_base`）兼容OpenAI API格式。

### 4. 修改文件筛选规则
在`filter_and_copy_files`方法中调整文件过滤逻辑，如：
- 修改禁用文件名正则表达式
- 调整文件大小筛选阈值
- 取消中文文件名限制等