使用说明

GitHub Pull请求摘要工具

此工具从指定的GitHub存储库获取并汇总拉取请求。它以Markdown表格格式输出数据，可以轻松复制到文档或报告中。

关于本项目的创建

这个存储库，包括所有代码、测试和文档，是在GitHub Copilot和Cursor的帮助下创建的。所有的实现、设计和文档任务都涉及人工智能驱动的代码生成和这些工具的建议，但每一项更改都会经过仔细审查，并在必要时进行手动更新。建议从不按原样接受；所有代码和文档都经过编辑和改进，以确保正确性和质量。

特性

从公共或私有存储库获取拉取请求。
根据草稿状态筛选拉取请求(only-drafts, no-drafts或没有过滤器）。
输出拉取请求详细信息，包括：
- 将拉取请求标记为可供审查的日期。
- 拉取请求的标题和编号。
- 作者详细信息。
- 审查和批准的数量。
--file-include / --file-exclude：正则表达式模式，用于按更改的文件路径过滤PR。
--url-from-pr-content：正则表达式模式，用于从PR diff中添加的行中提取URL。如果设置，则向输出表中添加一列匹配的URL。

需求

Python 3.6或更高版本。
看 requirements.txt.

测试

该项目包括单元测试和集成测试：

单元测试

快速：使用模拟依赖关系在没有网络连接的情况下运行
96%的代码覆盖率：全面测试所有核心功能
默认：跑步 make test

集成测试

真正的API测试：针对实际GitHub存储库进行测试
了解费率限制：自动处理GitHub API速率限制
两层方法：基本和完整的测试套件

# Run basic integration tests (recommended for development)
make test-integration

# Run full integration tests (requires higher rate limits or GitHub token)
make test-integration-full

# Run with convenience script
python run_integration_tests.py

# Run all tests (unit + integration)
make test-all

备注：集成测试在没有身份验证的情况下工作，但速率限制为每小时60个请求。为了更快地进行测试，请设置 GITHUB_TOKEN 环境变量。

有关详细信息，请参阅 docs/INTEGRATION_TESTS.md.

安装

先决条件

需要Python 3.6或更高版本。
确保你有 make 安装在您的系统上（可选，用于自动设置）。

步骤

克隆存储库：

git clone https://github.com/your-username/gh-pulls-summary.git
cd gh-pulls-summary

创建并激活虚拟环境：

python -m venv venv

# On Linux/macOS:
source venv/bin/activate

# On Windows:
venv\Scripts\activate

安装软件包及其依赖项：
```
# Option 1: Using make (if available)
make install

# Option 2: Using pip directly
pip install -r requirements.txt
pip install -e .
```
这将：
- 安装中列出的所需依赖项 requirements.txt.
- 安装 gh-pulls-summary 在您的虚拟环境中执行命令。
验证安装：
```
gh-pulls-summary --help
```
您应该看到该工具的帮助消息。

备注：记得激活虚拟环境(source venv/bin/activate 在Linux/macOS或 venv\Scripts\activate 在Windows上）每次您想在新的终端会话中使用该工具时。

用法

备注：在运行该工具之前，请确保您的虚拟环境已激活：

# On Linux/macOS:
source venv/bin/activate

# On Windows:
venv\Scripts\activate

然后使用以下任一方式运行该工具：

# Option 1: Using the installed command
gh-pulls-summary [OPTIONS]

# Option 2: Running the script directly
python gh_pulls_summary.py [OPTIONS]

选项

--owner：存储库的所有者（例如“microsoft”）。如果未指定，则默认为当前目录Git配置中的所有者。
--repo：存储库的名称（例如“vscode”）。如果未指定，则默认为当前目录Git配置中的仓库名称。
--pr-number：指定要查询的单个拉取请求号。
--draft-filter：根据草稿状态过滤拉取请求。使用“仅草稿”仅包含草稿，或使用“无草稿”排除草稿。
--file-include：正则表达式模式，包括基于更改的文件路径的拉取请求。可以多次指定。
--file-exclude：正则表达式模式，用于排除基于更改的文件路径的拉取请求。可以多次指定。
--url-from-pr-content：正则表达式模式，用于从PR diff中添加的行中提取所有唯一的URL。如果设置，则向输出表中添加一列匹配的URL。
--output-markdown：将生成的Markdown输出（带时间戳）写入文件的路径。如果未设置，则输出仅打印到stdout。
--debug：启用调试日志记录并显示错误回溯。
--column-title：覆盖任何输出列的标题。格式： COLUMN=TITLE有效的COLUMN值： date, title, author, changes, approvals, urls。可以指定多次。
--sort-column：指定要按哪个输出列排序。有效值： date, title, author, changes, approvals, urls默认值为 date.

示例

从PR差异中提取所有唯一的URL，将摘要写入文件，覆盖列标题，并按批准进行排序：

# Ensure virtual environment is activated first
source venv/bin/activate  # Linux/macOS
# or: venv\Scripts\activate  # Windows

gh-pulls-summary --owner myorg --repo myrepo \
  --url-from-pr-content 'https://example.com/[^\s]+' \
  --output-markdown /tmp/summary.md \
  --column-title date="Ready Date" --column-title approvals="Total Approvals" \
  --sort-column approvals

如果您没有指定 --output-markdown，Markdown摘要（带时间戳）将打印到终端。

在公共存储库上运行（无身份验证）

您可以在没有身份验证的情况下对公共存储库运行该工具。但是，请注意，GitHub API规定的速率限制为 每小时60个请求 用于未经身份验证的请求。

# Activate virtual environment first
source venv/bin/activate  # Linux/macOS
# or: venv\Scripts\activate  # Windows

gh-pulls-summary --owner jewzaam --repo gh-pulls-summary

在私有存储库上运行（需要身份验证）

访问专用存储库或将API速率限制提高到 每小时5000个请求，您需要使用GitHub个人访问令牌进行身份验证。

设置一个经典的GitHub Token:
- 代币（经典）
- 选择“生成新令牌”，然后“生成新的令牌（经典）”
- 检查范围 repo
- 有关更多信息，请参阅关于创建个人访问令牌的GitHub文档.
将令牌设置为环境变量: 将令牌导出为环境变量：
```
export GITHUB_TOKEN=<your_personal_access_token>
```

运行工具: 激活您的虚拟环境，并使用与公共存储库相同的命令：

# Activate virtual environment first
source venv/bin/activate  # Linux/macOS
# or: venv\Scripts\activate  # Windows

gh-pulls-summary --owner <owner> --repo <repo>

例子：

# Activate virtual environment and set token
source venv/bin/activate  # Linux/macOS
# or: venv\Scripts\activate  # Windows

export GITHUB_TOKEN=ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXX
gh-pulls-summary --owner my-org --repo private-repo

备注：The 经典 ……的范围 repo 此操作需要。任何其他权限尚未正常工作。如果有其他方法，欢迎PR在文档中修复此问题。

安全管理GitHub代币

管理GitHub令牌时，安全性至关重要。令牌授予对存储库的访问权限，应小心处理，以防止未经授权的访问。以下是为不同操作系统量身定制的安全管理令牌的说明。

1.使用环境变量

Linux/macOS

将令牌存储在环境变量中，以避免在脚本或文件中对其进行硬编码。例如：

export GITHUB_TOKEN=<your_personal_access_token>

然后，您可以在运行该工具时使用该令牌：

# Activate virtual environment first
source venv/bin/activate  # Linux/macOS
# or: venv\Scripts\activate  # Windows

gh-pulls-summary --owner <owner> --repo <repo>

Windows（命令提示符）

使用 set 设置环境变量的命令：

set GITHUB_TOKEN=<your_personal_access_token>

运行该工具：

REM Activate virtual environment first
venv\Scripts\activate

gh-pulls-summary --owner <owner> --repo <repo>

Windows（PowerShell）

使用 $env: 设置环境变量的语法：

$env:GITHUB_TOKEN="<your_personal_access_token>"

运行该工具：

# Activate virtual environment first
venv\Scripts\activate

gh-pulls-summary --owner <owner> --repo <repo>

2.使用 `.env` 文件

您可以使用 .env 用于在本地管理环境变量的文件。创建一个 .env 文件：

GITHUB_TOKEN=<your_personal_access_token>

加载 .env 在运行该工具之前，请先在shell中创建文件：

Linux/macOS

source .env

Windows（PowerShell）

Get-Content .env | ForEach-Object { $name, $value = $_ -split '='; $env:$name = $value }

备注：The .env 文件被排除在存储库的 .gitignore 文件。

3.使用系统钥匙圈

Linux

在Linux上，您可以使用 secret-tool 为了安全地存储和检索令牌：

存储令牌

secret-tool store --label="GitHub Token" service gh-pulls-summary

检索和使用令牌

# Activate virtual environment first
source venv/bin/activate

GITHUB_TOKEN=$(secret-tool lookup service gh-pulls-summary) gh-pulls-summary --owner <owner> --repo <repo>

更新令牌

如果需要更新令牌，请重新运行 secret-tool store 命令：

secret-tool store --label="GitHub Token" service gh-pulls-summary

macOS

在macOS上，您可以使用Keychain安全地存储和检索令牌：

存储令牌

security add-generic-password -a "gh-pulls-summary" -s "GitHub Token" -w <your_personal_access_token>

检索和使用令牌

# Activate virtual environment first
source venv/bin/activate

GITHUB_TOKEN=$(security find-generic-password -a "gh-pulls-summary" -s "GitHub Token" -w) gh-pulls-summary --owner <owner> --repo <repo>

更新令牌

如果需要更新令牌，请重新运行 security add-generic-password 命令。

视窗

在Windows上，您可以使用PowerShell中的SecretManagement模块安全地存储和检索令牌：

存储令牌

安装SecretManagement模块：

Install-Module -Name Microsoft.PowerShell.SecretManagement -Force

注册保管库（例如SecretStore）：

Register-SecretVault -Name MySecretVault -ModuleName Microsoft.PowerShell.SecretStore -DefaultVault

存储令牌：

Set-Secret -Name GitHubToken -Secret "<your_personal_access_token>"

检索和使用令牌

检索令牌并将其设置为环境变量：

# Activate virtual environment first
venv\Scripts\activate

$env:GITHUB_TOKEN = Get-Secret -Name GitHubToken
gh-pulls-summary --owner <owner> --repo <repo>

更新令牌

要更新令牌，请重新运行 Set-Secret 命令：

Set-Secret -Name GitHubToken -Secret "<new_personal_access_token>"

可选参数

--draft-filter：根据草稿状态过滤拉取请求。
- only-drafts：仅包括草稿拉取请求。
- no-drafts：排除草稿拉取请求。
- 如果未指定，则包括所有拉取请求，而不管草稿状态如何。

例子：

# Activate virtual environment first
source venv/bin/activate  # Linux/macOS
# or: venv\Scripts\activate  # Windows

gh-pulls-summary --owner jewzaam --repo gh-pulls-summary --draft-filter no-drafts

--debug：启用调试日志记录以输出有关脚本执行的详细信息。

例子：

# Activate virtual environment first
source venv/bin/activate  # Linux/macOS
# or: venv\Scripts\activate  # Windows

gh-pulls-summary --owner jewzaam --repo gh-pulls-summary --debug

输出

该工具输出一个包含以下列的Markdown表：

日期：拉取请求标记为可供审查的日期。
标题：拉取请求的标题，带有拉取请求链接。
作者：作者的姓名，并附有指向其GitHub个人资料的链接。
请求更改：请求更改的评论数量。
审批：总审查中的批准数量（例如“2/5”）。

输出示例：

| Date 🔽    | Title                                   | Author          | Change Requested | Approvals |
| ---------- | --------------------------------------- | --------------- | ---------------- | --------- |
| 2025-05-01 | Add feature X #[123](https://github.com/...) | [John Doe](https://github.com/johndoe) | 1            | 2 of 3    |
| 2025-05-02 | Fix bug Y #[124](https://github.com/...) | [Jane Smith](https://github.com/janesmith) | 0            | 1 of 1    |

贡献

对于本地开发，您可以使用以下命令运行测试：

make test

这些测试包括针对真实GitHub存储库的模拟和集成测试的全面单元测试。

拉取请求流程

所有拉取请求都必须通过自动PR检查，其中包括：

单元测试：具有模拟依赖关系的快速测试（96%的代码覆盖率）
简单集成测试：针对GitHub存储库的真实API测试
覆盖范围报告：自动覆盖报告和徽章更新

要设置分支保护（需要存储库管理员）：

首选 Settings > Branches 在您的GitHub存储库中
添加规则 main 具有以下要求的分支：
- ✅ 合并前需要通过状态检查
- ✅ 要求分支机构在合并前保持最新状态
- ✅ 从PR检查工作流中选择“测试”状态检查

自动覆盖徽章

每次推送时，覆盖徽章都会自动更新 main:

工作流从测试运行中提取覆盖率百分比
更新 .github/badges/coverage.json 以当前百分比
README徽章通过shields.io显示实时报道
无需外部服务或令牌

使用说明

GitHub Pull请求摘要工具

关于本项目的创建

特性

需求

测试

单元测试

集成测试

目录

安装

先决条件

步骤

用法

选项

示例

在公共存储库上运行（无身份验证）

在私有存储库上运行（需要身份验证）

安全管理GitHub代币

1.使用环境变量

Linux/macOS

Windows（命令提示符）

Windows（PowerShell）

2.使用 .env 文件

Linux/macOS

Windows（PowerShell）

3.使用系统钥匙圈

Linux

存储令牌

检索和使用令牌

更新令牌

macOS

存储令牌

检索和使用令牌

更新令牌

视窗

存储令牌

检索和使用令牌

更新令牌

可选参数

输出

贡献

拉取请求流程

自动覆盖徽章

相关 MCP

网页内容抓取服务器

知识图谱记忆服务器

顺序思维服务器

Figma MCP服务器

GitHub API服务器

Excel表格处理MCP服务

2.使用 `.env` 文件